aontu 0.61.0 → 0.63.0

package/src/mod.ts

@@ -1,61 +1,24 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// MODULE IDENTITY AND LOCAL RESOLUTION (G6 phase 2,
-// docs/capability-review/g6-distribution.md).
-//
-// An import is still just `@"…"`; the string's SHAPE routes it, so the
-// grammar is untouched and every existing include keeps its exact
-// behaviour:
-//
-//   service: @"corp.example/schemas/service@1"
-//   frozen:  @"corp.example/schemas/service@1#aon1-4vJemVYtWFR2mQeN…"
-//   local:   @"./fragment.aon"        <- unchanged, not a module
-//
-// EVALUATION NEVER TOUCHES THE NETWORK. Resolution reads local stores
-// only: `aontu_meta/vendor/` beside the project's `mod.aon`, then a
-// content-addressed user cache keyed by canon-hash. Fetching is a
-// separate, explicit tool step, and a module that is in neither store
-// is an evaluation error that says so.
-//
-// TWO PINS, TWO ROLES. The lockfile's `oci` digest certifies that these
-// are the bytes the registry served; the `canon` hash certifies that
-// this is the MEANING that was reviewed. Only the second can be checked
-// locally without the registry, and it is the one this file checks: the
-// module is unified standalone and its canon-hash compared with the
-// pin. An inline `#aon1-…` fragment is the same check without a
-// lockfile — the degenerate mode for single-file and agent-sandbox use.
 
 import { join as pathJoin, dirname as pathDirname } from 'node:path'
 
 
-// A module import, as the string spells it.
 export type ModuleRef = {
   // The module path WITHOUT the major: `corp.example/schemas/service`.
   path: string
-  // The major version, from the `@N` suffix.
   major: number
   // The inline canon-hash pin, if the import froze one.
   hash?: string
 }
 
 
-// A file store the resolver can read. The engine passes its own `fs`
-// when the host injected one, so a sandboxed evaluation stays in the
-// filesystem the host gave it.
 export type ModuleFs = {
   existsSync: (p: string) => boolean
   readFileSync: (p: string, enc: string) => string
 }
 
 
-// A module path is DOMAIN-SHAPED — the first segment carries a dot,
-// which is what tells it apart from `./local.aon`, `pkg-name` and every
-// other spelling already in use — and carries the major version in the
-// path, CUE/Go-style, so two majors are two modules.
-//
-// The pattern is deliberately narrow: anything it does not match falls
-// through to the existing resolver chain unchanged, so no document that
-// worked before this phase can be routed somewhere new by it.
 const MODULE_RE =
   /^([a-z0-9][a-z0-9-]*(?:\.[a-z0-9][a-z0-9-]*)+(?:\/[A-Za-z0-9._-]+)*)@(\d+)(?:#(aon1-[A-Za-z0-9_-]+))?$/
 
@@ -73,33 +36,10 @@ export function parseModuleRef(spec: string): ModuleRef | undefined {
 }
 
 
-// SHAPE IS NOT VALIDITY, and the gap between them was a hole. MODULE_RE
-// answers "does this string route to the module resolver" -- a
-// ROUTING predicate, and it must stay one, because anything it rejects
-// falls through to the file leg and a stricter pattern would silently
-// re-route documents that work today. But its element class
-// `[A-Za-z0-9._-]` admits `..`, and `moduleDir` joins elements with
-// pathJoin, which CLEANS `..` rather than refusing it:
-//
-//   moduleDir('/store/aontu_meta/vendor', 'corp.example/../../etc/passwd@1')
-//     -> /store/etc/passwd@1
-//
-// `mod vendor` then copied a tree THERE, outside the project entirely,
-// and reported `verdict: ok`. So validity is a separate question asked
-// separately, after the shape matched, and asked at every site that
-// turns a module path into a directory.
-//
-// The rules are Go's (golang.org/x/mod/module.CheckPath), for the
-// reason Go has them: a module path becomes a real directory on every
-// platform the toolchain runs on, so it must be a legal one everywhere.
 export const MODULE_MAX_PATH = 512
 export const MODULE_MAX_ELEMS = 32
 
 
-// Windows refuses these as file names whatever the extension, so a
-// module path containing one cannot be materialised there at all. The
-// check is on the element up to its first dot, which is where Windows
-// stops looking too.
 const RESERVED_ELEMS = new Set([
   'con', 'prn', 'aux', 'nul',
   'com1', 'com2', 'com3', 'com4', 'com5', 'com6', 'com7', 'com8', 'com9',
@@ -107,9 +47,6 @@ const RESERVED_ELEMS = new Set([
 ])
 
 
-// Why a module path may not be used as a directory, or undefined when
-// it may. The reason is user-facing: it goes in the refusal, because a
-// path refused without saying which rule it broke is a puzzle.
 export function validateModulePath(path: string): string | undefined {
   if (MODULE_MAX_PATH < path.length) {
     return 'longer than ' + MODULE_MAX_PATH + ' characters'
@@ -124,10 +61,6 @@ export function validateModulePath(path: string): string | undefined {
     if ('' === elem) {
       return 'an element is empty'
     }
-    // This one rule kills `.` and `..` -- the traversal -- along with
-    // `.hidden` and `trailing.`, exactly as Go's does. Stating it as
-    // the rule rather than as "no `..`" is deliberate: a check that
-    // named the two dangerous spellings would miss the next one.
     if (elem.startsWith('.') || elem.endsWith('.')) {
       return 'an element begins or ends with "."'
     }
@@ -140,46 +73,16 @@ export function validateModulePath(path: string): string | undefined {
 }
 
 
-// An element as it is spelled ON DISK. Uppercase is escaped to
-// `!`+lowercase, Go's rule (go.dev/ref/mod, module proxy protocol) and
-// for Go's reason: `github.com/Alice/Widgets` and
-// `github.com/alice/widgets` are two module identities and, on macOS
-// and Windows, ONE directory -- so without this the second module
-// fetched silently clobbers the first, and an unpinned import resolves
-// to whichever won.
-//
-// The WRITTEN path stays the identity; only the directory is escaped.
 function escapeElem(elem: string): string {
   return elem.replace(/[A-Z]/g, (c) => '!' + c.toLowerCase())
 }
 
 
-// The directory a module's files live in, under a store root.
-//
-// Callers must have validated the path (validateModulePath); this
-// function cannot refuse, because it answers a location rather than a
-// question, and every caller has a refusal shape of its own.
 export function moduleDir(store: string, ref: ModuleRef): string {
   return pathJoin(store, ...ref.path.split('/').map(escapeElem)) + '@' + ref.major
 }
 
 
-// EVERY project root at or above `from`, innermost first — a project
-// root being a directory holding a `mod.aon`. This used to answer with
-// the NEAREST one alone, and the plural is the fix, because a
-// VENDORED MODULE IS A PROJECT INSIDE A PROJECT. A module in
-// `aontu_meta/vendor/` carries its own `mod.aon`, which stopped the upward
-// walk there, so a nested import resolved against the vendored
-// module's own directory: a tree with no `aontu_meta/vendor/` of its own, and
-// therefore a `module not fetched` for a dependency sitting flat
-// beside it in the CONSUMER's vendor tree — the only layout `mod
-// vendor` produces (use-cases/BUGS.md §31).
-//
-// The consumer's stores are searched after the module's own, so a
-// module that vendors its dependencies nested still wins for its own
-// tree, and one that does not falls through to the consumer that
-// vendored it. The last element is `from` itself when nothing above it
-// declares a module, which is the single-file inline-pin mode.
 export function projectRoots(from: string, fs: ModuleFs): string[] {
   const roots: string[] = []
   let dir = from
@@ -196,18 +99,6 @@ export function projectRoots(from: string, fs: ModuleFs): string[] {
 }
 
 
-// The lockfile's pin for one import, or undefined.
-//
-// `mod-lock.aon` is machine-written CANONICAL Aontu, and canonical
-// Aontu whose leaves are scalars IS JSON — which is why reading it here
-// needs no evaluator, and why a hand-edited lockfile that is no longer
-// canonical simply does not parse. It is generated; the file says so.
-// The lockfile's JSON: its canonical line, with the generated-file
-// header stripped. The file is AONTU, so it may carry `#` comments —
-// and the header `aontu mod tidy` writes says not to edit it, which is
-// worth more than the two lines it costs to skip. Everything below the
-// comments is the canonical map, and canonical Aontu whose leaves are
-// scalars is JSON.
 export function lockJson(text: string): string {
   return text
     .split('\n')
@@ -216,38 +107,11 @@ export function lockJson(text: string): string {
 }
 
 
-// The user cache: `$XDG_CACHE_HOME/aontu/mod` unless the host names
-// another, else the platform's own cache location. A host with nowhere
-// to put one has no cache, which is a miss rather than a failure. One
-// rule, in one place: the resolver reads this cache during evaluation
-// and `aontu mod` writes into it, and two spellings of "where the cache
-// is" is one bug.
 export function modCacheDir(): string | undefined {
   return modCacheDirFor(process.platform, process.env)
 }
 
 
-// That rule with the platform and the environment PASSED IN, so the
-// Windows arm can be exercised off Windows — the only way a rule about
-// a platform nobody here runs gets tested at all. The Go port splits
-// the same way (modCacheDirFor, go/aontu.go).
-//
-// THE ORDER IS EXPLICIT BEFORE IMPLICIT, and LOCALAPPDATA is LAST.
-// XDG_CACHE_HOME is the override and wins everywhere, Windows included:
-// a caller who names a cache directory means it. HOME comes next and is
-// also honoured on Windows, where it is not standard but IS set by Git
-// Bash and by most development shells — a user who has one expects
-// their tools to agree about where home is.
-//
-// LOCALAPPDATA is the PLATFORM DEFAULT beneath both, which is the whole
-// addition: Windows sets neither XDG_CACHE_HOME nor HOME by default —
-// it supplies USERPROFILE and LOCALAPPDATA, and LOCALAPPDATA is what a
-// cache directory means there — so a rule that knew only the first two
-// left every Windows user with NO cache. Putting it ABOVE HOME was the
-// first attempt and was wrong: it made an explicitly set HOME
-// unreachable on Windows, which broke the existing fallback test the
-// moment CI ran it. A platform default that overrides what the
-// environment was told is not a default.
 export function modCacheDirFor(
   platform: string,
   env: Record<string, string | undefined>,
@@ -290,24 +154,10 @@ export function lockHash(root: string, ref: ModuleRef, fs: ModuleFs):
 }
 
 
-// What a module resolution needs from the engine: evaluate a source
-// standalone and answer both what it MEANS (the generated value, for
-// reading a module file's own metadata) and what its meaning HASHES to
-// (for the integrity check). Injected rather than imported, because
-// this is EVALUATION — the very thing this file is called from the
-// middle of — and a module resolver that imported the evaluator would
-// close a cycle around the whole language.
 export type ModuleEval =
   (src: string, path: string) => { gen: any, hash: string }
 
 
-// How deep module verification may nest before it is refused. A module
-// is verified by EVALUATING it, and that evaluation resolves the
-// module's own imports -- so a vendor tree that leads back to itself
-// (a symlink is enough) would recurse until the host's stack gave out,
-// and a verdict that depends on the host's stack size is exactly what
-// the determinism clause forbids (docs/trust.md, and the same argument
-// unify_cycle rests on). Sixteen is far above any real vendor nesting.
 export const MODULE_MAX_DEPTH = 16
 
 
@@ -316,10 +166,6 @@ export type ModuleOptions = {
   // only when the expected hash is known, which is what "content
   // addressed" means: without a pin there is no address.
   cache?: string
-  // The standalone evaluator, for reading module files and for the
-  // integrity check. Always present: Aontu injects it (ts/src/aontu.ts)
-  // because only the class that evaluates can answer what a module
-  // MEANS, and the resolver runs inside a parse that class started.
   eval: ModuleEval
   // How many module verifications deep this evaluation already is.
   depth?: number
@@ -333,23 +179,11 @@ export type ModuleFound = {
 }
 
 
-// EVERY code `resolveModule` can refuse with. The list lives HERE,
-// beside the refusals themselves, because the parse layer has to
-// recognise them to turn the throw into a parse-stage nil
-// (ts/src/lang.ts) -- and when that list was written out longhand
-// there, adding a fourth code left it unhandled and the refusal
-// surfaced as `unexpected error` instead of the message it carries.
-// The Go port has no such list (recordModErr takes any code), which is
-// why only this side could drift.
 export const MODULE_REFUSAL_CODES: ReadonlySet<string> = new Set([
   'module_path', 'module_missing', 'module_integrity', 'module_depth',
 ])
 
 
-// A refusal that carries its code to the parse layer, exactly as a
-// denied include does (makeModelResolver's `deny`): the resolver
-// THROWS, so a bare-member module import cannot vanish in the merge and
-// leave a plausible, silently-partial document.
 function refuse(code: string, message: string): never {
   const err: any = new Error(message)
   err.code = code
@@ -364,11 +198,6 @@ export function resolveModule(
   fs: ModuleFs,
   options: ModuleOptions,
 ): ModuleFound {
-  // THE PATH IS CHECKED BEFORE ANYTHING IS BUILT FROM IT. This is
-  // first because it is a question about the REQUEST, not about the
-  // state of the machine: a path that cannot legally be a directory is
-  // refused identically whether or not the module is present, and
-  // whether or not the depth bound is near.
   const badpath = validateModulePath(ref.path)
   if (undefined !== badpath) {
     refuse('module_path',
@@ -401,9 +230,6 @@ export function resolveModule(
 
   const dir = stores.find((d) => fs.existsSync(pathJoin(d, 'mod.aon')))
   if (undefined === dir) {
-    // The wording is the contract (docs/capability-review/
-    // g6-distribution.md): it names the module AND the step that fixes
-    // it, because an agent reading this error is the audience.
     refuse('module_missing',
       'module not fetched: ' + ref.path + '@' + ref.major +
       ' (run: aontu mod get)')
@@ -439,10 +265,6 @@ export function resolveModule(
 }
 
 
-// The `mod.main` a module file declares, or the default entry name.
-// The module file is ORDINARY AONTU, read by the language itself — the
-// toolchain dogfooding its own evaluator rather than pattern-matching
-// its own syntax with a regexp.
 function moduleMain(file: string, fs: ModuleFs, options: ModuleOptions): string {
   const gen: any = options.eval(fs.readFileSync(file, 'utf8'), file).gen
   const main = gen?.mod?.main