Nocter v0.10.0 Phase 1

Status: Complete.

Purpose

Phase 1 replaces file-defined modules with directory-defined modules. It separates package metadata, module identity, and physical source composition so large libraries can split private implementation across files without creating public namespaces or scattering their API surface.

Source Model

• nocter.nct is the package file. It contains package documentation and package directives only.
• A directory containing index.nct defines one module. The index.nct file is that module's module root source file.
• Other imported .nct files are source files of the nearest enclosing module. Their file names do not create namespaces or externally visible identities.
• A directory without index.nct is a source folder, not a module.
• use ./search resolves search.nct as a same-module source import when that file exists.
• use ./parser.Parser resolves parser/index.nct as a child-module import.
• A source file and a child module may not use the same logical path. The compiler reports the conflict instead of selecting one by precedence.
• Same-module source imports are idempotent and may form cycles because declarations are collected for the complete module before bodies are resolved.
• A source file not reachable from the module root source file is not part of the module.

Visibility and Identity

• Only a module root source file may contain pub declarations or pub use declarations.
• All declarations in other source files are module-private and are visible throughout their module.
• Duplicate declarations are diagnosed across the complete module, independent of source order.
• External imports address only directory modules and their root-defined public surface. A package consumer cannot import a source file directly.
• Compiler and editor identities use package plus normalized module-directory path. Physical source paths remain definition locations, dependency edges, and diagnostic origins only.

Package Targets

#executable and #test select a module with module; the former entry field is removed. An omitted executable module selects .. Module . is the package root index.nct, never nocter.nct.

#executable: {
    name: "app",
    module: ".",
}

Completion Gate

• package loading rejects ordinary Nocter declarations in nocter.nct
• build, check, run, test, graph, formatting, AST JSON, and package initialization use directory modules and module target fields
• source imports compose one module namespace without producing import aliases
• module imports expose only the root source file's public surface
• resolver, type checker, native lowering, trusted declaration lookup, and LSP queries preserve source-backed locations while sharing directory module identity
• the standard library, public examples, fixtures, and tests use the new layout
• documentation contains no active one-file-one-module, package-source, or target-entry contract
• development/compiler/scripts/verify.sh, documentation generation, and git diff --check pass

Phase 1 does not introduce wildcard source discovery, textual inclusion order, partial declarations, or an additional manifest file.

Completion Record

• Package parsing now keeps nocter.nct outside the ordinary AST and rejects source declarations there. Package targets resolve directory modules through module; the removed entry field is diagnosed rather than retained as a compatibility alias.
• One shared source-layout model defines module roots, source membership, normalized module identity, ambiguity detection, and missing-file canonicalization for open editor buffers.
• The resolver joins reachable physical sources into one declaration namespace while preserving per-source spans and analysis results. Source cycles are idempotent; module cycles remain errors.
• Visibility validation makes index.nct the sole public-surface authority. Package, dependency, standard-library, and re-export paths cannot address implementation sources.
• CLI commands, package initialization, the LSP, the standard library, compiler fixtures, and public examples use the directory-module layout. Cross-source LSP navigation is covered for unsaved implementation buffers.
• The complete 3,405-test compiler verification suite, generated documentation, public example checks, and whitespace validation passed for the migrated tree.