Plan 04: Multi-File Packages & Internal Shielding

Goal: Enable packages to span multiple files in a single directory without forward declarations, and enforce compile-time internal/ package encapsulation. Inspiration: Go's package compilation model (go/build, cmd/compile) and the Go internal/ boundary rule.

1. Problem Statement & Root Cause

Currently in Kyna:

1. Single-File Compilation Unit: Each compilation unit corresponds to a single .kyna source file. To split functionality across multiple files, developers must use explicit import statements between every file.
2. No Compiler-Enforced Internal Privacy: Any module can import any file from any directory. Libraries cannot have private internal utility packages without risking external consumers depending on unstable internals.

2. Target Architecture

2.1 Multi-File Package Loading

When compiling a package directory:

1. The compiler gathers all *.kyna files in that directory.
2. Each file is parsed into an individual AST (FileAST).
3. Declarations from all files are merged into a single package scope (PackageScope).
4. Type resolution and cycle detection occur across the entire package simultaneously without requiring forward declarations.

1namespace kyna::loading {
2 
3struct PackageSource {
4  std::string name;
5  std::filesystem::path directory;
6  std::vector<SourceFile> files;
7};
8 
9class PackageLoader {
10public:
11  std::optional<PackageSource> loadPackageDirectory(const std::filesystem::path& dir);
12};
13 
14} // namespace kyna::loading

2.2 Compiler-Enforced internal/ Boundary Rule

A package located at or beneath a directory named internal may only be imported by packages that share the parent of that internal directory as an ancestor:

1// compiler/kyna_typecheck/src/checkers/package_checker.cpp
2bool isInternalImportAllowed(const std::filesystem::path& importerPath,
3                             const std::filesystem::path& importedPath) {
4  auto internalPos = importedPath.string().find("/internal/");
5  if (internalPos == std::string::npos) return true; // not an internal package
6 
7  auto parentOfInternal = importedPath.string().substr(0, internalPos);
8  return importerPath.string().starts_with(parentOfInternal);
9}

3. Implementation Steps

• Step 1: Extend CLI Command Dispatcher
  • Update tools/kyna_cli/src/commands/run_command.cpp and check_command.cpp to accept a directory path (package mode) in addition to single .kyna files.
• Step 2: Implement PackageLoader
  • Create compiler/kyna_loading/src/loading/package_loader.cpp to discover all .kyna files in a package folder.
• Step 3: Multi-AST Merger in Semantic Analysis
  • Merge declarations from multiple FileAST instances into a unified package root scope before statement checking.
• Step 4: Implement internal/ Path Validator
  • In import statement checking, reject imports from internal/ paths when the importing module is outside the parent tree.

4. Verification Plan

1. Test Cases:
   • Create test packages with 3+ files sharing types and functions without imports.
   • Create tests asserting that external imports of internal/ packages fail with diagnostic KSEM1042: use of internal package not allowed.
2. Tooling Tests:
   • Run ctest --test-dir build-debug.