@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/helpers/manifest.ts

@@ -1,39 +1,3 @@
-// THE PACKAGE MANIFEST: `sdkgen-package.json`, beside the package's `.sdk`.
-//
-// See docs/design/sdkgen-packages.md §2.
-//
-//   <package-root>/
-//   ├── sdkgen-package.json      <- this
-//   └── .sdk/                    <- shaped exactly like ts/project/.sdk
-//
-// WHY JSON RATHER THAN AONTU
-//
-// Consumer models compile under `@voxgig/model`'s strictly-configured parser,
-// which accepts `#` comments only — a `//` line is a parse error, and seven
-// shipped targets once broke on exactly that (ts/test/model-compile.test.ts
-// exists because of it). The manifest is read by the CLI and never unified
-// into the model, so JSON keeps it outside that trap entirely.
-//
-// WHAT IT IS FOR
-//
-// A package's CLAIM about what it provides, so that:
-//
-//   - `package add <pkg>` knows what to install without guessing from
-//     directory listings;
-//   - a typo'd ref fails naming what the package actually provides, rather
-//     than resolving to a folder that exists and failing later on a missing
-//     file;
-//   - an item records WHICH PACKAGE supplied it (`package:` provenance), so a
-//     project can be resynced against a newer version of that package.
-//
-// A claim is worth nothing unless it is checked, so `validateManifest`
-// compares it against the trees actually on disk, in both directions: a
-// manifest that lies is an error, on-disk extras are a warning.
-//
-// THE MANIFEST IS OPTIONAL FOR A DIRECT REF. `target add ../pkg/iot-go`
-// against a bare `.sdk`-shaped folder keeps working exactly as it does today
-// — that is what every existing consumer fixture is — and simply records no
-// `package` provenance. Requiring one is `package add`'s business.
 
 import Path from 'node:path'
 
@@ -54,58 +18,26 @@ type Manifest = {
   name: string
   version?: string
 
-  // DECLARATIVE ONLY, so far. Nothing reads this range yet: the engine gate
-  // belongs with `package add` (design §9), which is the next phase, and
-  // there is no semver implementation here to compare with — this package has
-  // no runtime dependencies. Until then a package declaring an incompatible
-  // range installs anyway. Stated here rather than left to be discovered,
-  // because a field that looks enforced and is not is worse than an absent
-  // one.
   engines?: { sdkgen?: string }
 
-  // Keyed BY KIND, so a new kind (docs, …) needs no schema change.
   provides: Record<string, string[]>
 
   // Optional: which targets a feature ships source for, so a missing overlay
   // is reported as out-of-declared-coverage rather than broken.
   targetsSupported?: Record<string, string[]>
 
-  // Optional: the author's declared parity tier per target, in
-  // ts/test/parity.test.ts's vocabulary plus CONSUMER — see PARITY below.
   parity?: Record<string, string>
 }
 
 
-// THE CLOSED PARITY VOCABULARY.
-//
-// The first three are `ts/test/parity.test.ts`'s tiers, which grade a
-// language target against the shared `.aontu` corpus. `CONSUMER` is the
-// fourth and grades nothing: a consumer target wraps another target's SDK and
-// has no primary-utility surface to measure, so `parity.test.ts` keeps the
-// bundled ones in NON_SDK_TARGETS rather than in a tier. A package holding
-// one needs a way to say the same thing, and saying nothing is not it — an
-// absent field cannot be told apart from an author who did not know the field
-// existed, which is the silently-absent shape every other guard in this repo
-// exists to prevent.
-//
-// Closed, and checked, because a declaration nothing checks is the failure
-// `engines.sdkgen` documents about itself two fields up: a typo would
-// otherwise be indistinguishable from a considered choice.
 const PARITY = ['FULL', 'MIRRORED', 'UNCOVERED', 'CONSUMER']
 
 
-// What `readManifest` found. THREE outcomes, deliberately distinct: a
-// manifest, no manifest, or a manifest that could not be read. Collapsing the
-// last two into "no manifest" is what would let a typo in a package's own
-// JSON silently downgrade `package add` into a no-op.
 type ManifestRead = {
-  // Where it was looked for, always — the value an error message needs.
   file: string
 
-  // Present only when one was found AND parsed.
   manifest?: Manifest
 
-  // Present only when one was found and could NOT be parsed.
   err?: string
 }
 
@@ -226,12 +158,6 @@ function checkShape(manifest: Manifest, file: string): Finding[] {
         continue
       }
 
-      // A NAME, not a path. `missingPaths` joins these onto the package root,
-      // so `../../outside` would send every existence check out of the
-      // package entirely and let a manifest validate clean against unrelated
-      // files. `~` is excluded for a different reason: it is the alias
-      // separator, so a name containing one could never be resolved back to
-      // this item.
       for (const name of names as string[]) {
         if (!ITEM_NAME_RE.test(name)) {
           found.push({
@@ -263,31 +189,9 @@ function checkShape(manifest: Manifest, file: string): Finding[] {
 }
 
 
-// What may name a target, feature, or any other item.
-//
-// Deliberately narrow: these become directory names, aontu model keys,
-// generated config keys (`options.feature.<name>`) and component filename
-// suffixes, so the intersection of what all of those accept is the real
-// constraint. The shipped names — `go-cli`, `py-data`, `seneca-provider`,
-// `clienttrack` — all fit.
 const ITEM_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
 
 
-// Does the package's disk match its claim?
-//
-// BOTH DIRECTIONS, because they fail differently and neither implies the
-// other:
-//
-//   claim without disk  -> ERROR. `package add` would try to install it and
-//                          break partway through, having already written the
-//                          items listed before it.
-//   disk without claim  -> WARN. Everything works; the author has shipped
-//                          something nobody can discover, which is nearly
-//                          always a forgotten manifest edit.
-//
-// `kindRequires` is supplied by the caller rather than imported, because the
-// kind registry lives in `action/` and this is a helper — the dependency has
-// to point that way, not this way.
 function validateManifest(
   fs: any,
   sdkfolder: string,
@@ -319,16 +223,6 @@ function validateManifest(
       continue
     }
 
-    // ONE ORACLE FOR BOTH DIRECTIONS. The unclaimed-extras loop below reads
-    // the directory listing; if this loop asked the filesystem instead
-    // (`existsSync`/`statSync`), the two would disagree on a case-insensitive
-    // filesystem — APFS and NTFS by default, which is most package authors'
-    // machines. A manifest claiming `IoTGo` beside a `model/target/iotgo.aon`
-    // then validated CLEAN for the author and failed for every Linux consumer,
-    // which is precisely the "validated package that cannot install" this
-    // function exists to prevent. It also makes the duplicate check above
-    // meaningful: `['retry','Retry']` are two names to a Set and one file to
-    // the filesystem.
     const defined = new Set(definitionNames(fs, sdkfolder, kind))
 
     for (const name of names) {
@@ -351,30 +245,6 @@ function validateManifest(
   const targets = new Set(provides.target ?? [])
   const graded = new Set(Object.keys(manifest.parity ?? {}))
 
-  // A PROVIDED TARGET THE MANIFEST GRADES NOTHING FOR, when it grades OTHERS.
-  //
-  // Checking only the values leaves the weaker half undone: a typo'd tier is
-  // caught while an absent one passes, and absent is the failure mode the
-  // closed sets in this repo exist for — indistinguishable from an author who
-  // did not know the field was there.
-  //
-  // SCOPED TO A PARTIAL DECLARATION, and the scope is a real constraint
-  // rather than timidity. An ENTIRELY absent `parity` is the BUNDLED
-  // manifest's deliberate state: design §18.4a refused to duplicate
-  // parity.test.ts's tier map into ts/project/sdkgen-package.json, because
-  // the intended direction is the reverse — the manifest becomes the source
-  // and the suite reads it. Warning on a wholly absent field would fire on
-  // the shipped scaffold's 25 targets and demand that duplication now, which
-  // is the decision §18.4a made, not one to reverse from inside a validator.
-  //
-  // What IS unambiguous is inconsistency: a manifest that grades some of its
-  // targets and not others has no second reading. Nobody decides to grade two
-  // of three.
-  //
-  // WARNING, not error, and the level is the argument. The package works — a
-  // missing coverage declaration installs and generates correctly — so
-  // refusing it would be a worse outcome than saying so, the same call
-  // `manifest-item-unclaimed` makes for a tree nothing claims.
   for (const name of (0 === graded.size ? [] : [...targets].sort())) {
     if (!graded.has(name as string)) {
       found.push({
@@ -404,10 +274,6 @@ function validateManifest(
     }
   }
 
-  // The other direction. Only for kinds the manifest MENTIONS plus the ones
-  // this generator knows — a directory named after a kind nobody registered
-  // is already reported above if claimed, and is not this check's business if
-  // not.
   for (const kind of Object.keys(kinds)) {
     const claimed = new Set(provides[kind] ?? [])
 
@@ -427,22 +293,6 @@ function validateManifest(
 }
 
 
-// Every path an item of this kind needs, that is not there AS THE RIGHT KIND
-// OF THING.
-//
-// The definition file is implied for every kind; the kind's REQUIRED trees
-// add whatever else it needs (a target's component and template trees, a docs
-// item's components). An optional tree — a docs item's templates — is not
-// checked here, because a package that legitimately ships none must validate.
-//
-// FILE vs DIRECTORY is checked, not merely existence. A regular file at
-// `src/cmp/<t>` satisfies `existsSync` and satisfies nothing else: `target
-// add` walks both of those paths as trees, so a package validated on
-// existence alone could still be incapable of installing a usable target —
-// which is the one thing validation is supposed to rule out.
-//
-// Returned as package-relative strings, because that is what an error message
-// should say: the absolute path is this machine's business, not the author's.
 function missingPaths(
   fs: any,
   sdkfolder: string,
@@ -453,8 +303,6 @@ function missingPaths(
 ): string[] {
   const missing: string[] = []
 
-  // The definition, by EXACT NAME from the directory listing — see the note
-  // at the call site about the two directions needing one oracle.
   if (!defined.has(name)) {
     missing.push('model/' + kind + '/' + name + '.aon')
   }
@@ -473,9 +321,6 @@ function missingPaths(
 }
 
 
-// What is at a path: a file, a directory, or nothing. `statSync` FOLLOWS
-// symlinks, deliberately — a package may legitimately symlink a shared tree,
-// and what matters is what `target add` will find when it walks it.
 function entryKind(fs: any, path: string): 'file' | 'dir' | 'none' {
   try {
     const stat = fs.statSync(path)
@@ -487,20 +332,6 @@ function entryKind(fs: any, path: string): 'file' | 'dir' | 'none' {
 }
 
 
-// WHERE A PACKAGE ROOT IS, given a ref.
-//
-// The same probe chain `resolveSource` uses for an ITEM, one level up: an
-// installed npm package first, then a path relative to the project, then an
-// absolute path. A package root is the folder HOLDING `.sdk`, which is what
-// makes `<root>/<item>` the item ref — so the two resolvers agree by
-// construction about what a package is.
-//
-// It reports rather than throws, and it does not require a manifest, because
-// its two callers want different things from the same probe: `package add`
-// refuses a folder with no manifest (that is the verb's whole subject), while
-// `package check` reports the absence as its first finding and carries on
-// checking the `.sdk` — an author who has not written the manifest yet is
-// exactly who needs the rest of the battery.
 type PackageProbe = {
   ref: string
   root: string

package/src/helpers/modelNames.ts

@@ -1,45 +1,14 @@
 /* Copyright (c) 2024-2026 Voxgig Ltd, MIT License */
 
-// Normalise entity names in the model so every generated identifier is legal.
-//
-// An entity name is a MODEL KEY, and every target builds identifiers from it:
-// the PascalCase `Name` (class names, the SDK accessor, every generated type
-// name), the snake stem (python module names, test function names), the
-// object-literal key in the emitted config map. No target language permits an
-// identifier that starts with a digit, and ordinary resources produce one:
-// `/3ds-sessions` -> entity `3ds_session` -> `class 3dsSessionEntity`,
-// `import { 3dsSession }`, `3dsSession()`. That is not a degraded SDK, it is
-// no SDK — nothing compiles (issue #124).
-//
-// THE RENAME IS ON THE MODEL, NOT ON A DERIVED FORM, and that is the whole
-// design. Guarding `Name` where it is derived does not survive: a consumer's
-// scaffolded `Root.ts` — which lives in the consumer's repo, not here — runs
-// its own `names(entity, entity.name)` per entity per target, immediately
-// before emitting, and re-derives `Name` from the unguarded name. Only a
-// guarded `entity.name` makes that re-derivation come out right, and it fixes
-// the snake-stem and config-key positions at the same time.
-//
-// Applied before Root runs, so nothing has read a name yet.
-//
-// IT IS A NO-OP ON EVERY MODEL THAT EXISTS TODAY. apidef guards entity names
-// at the source, so a name reaching here with a leading digit means a
-// hand-authored `.sdk/model` or a pre-guard apidef. The rename is the same
-// rule, producing the same name, as apidef's own `prefixLeadingDigit` — so
-// the two layers agree rather than compete, and a model that went through
-// apidef is untouched.
-//
-// The WIRE is untouched. A request path comes from the point's `orig`, never
-// from the entity name, so renaming the entity cannot change what is called.
 
 import { each, names } from 'jostraca'
 import { KIT } from '@voxgig/apidef'
 
+import { entityRelationName } from './buildIdNames'
+
 import { prefixLeadingDigit } from './naming'
 
 
-// `from`/`to` are the entity NAME. `key` is where the entity sits in the
-// collection after the rename — the new name when the map was keyed by it (the
-// normal shape), the untouched original key when it was not.
 type Rename = { from: string, to: string, key: string }
 
 // The internal form, which also remembers where the entity sat BEFORE the
@@ -48,21 +17,14 @@ type Rename = { from: string, to: string, key: string }
 type Plan = { from: string, to: string, origkey: string }
 
 
-// Rename every entity whose name would produce an illegal identifier, and
-// rewrite the model's own references to it. Returns the renames applied, so
-// the caller can report them; empty when the model is already clean.
 function guardModelNames(model: any, log?: any): Rename[] {
   const entity = model?.main?.[KIT]?.entity
-  // An ARRAY is not a name-keyed collection: its keys are indices, and
-  // "renaming" one would rewrite the model into nonsense. Models are maps, but
-  // the check is cheap and the failure would be silent.
   if (null == entity || 'object' !== typeof entity || Array.isArray(entity)) {
     return []
   }
 
   const flow = flowMap(model)
 
-  // Sorted keys: the rename set, and any collision report, is byte-stable.
   const keys = Object.keys(entity).sort()
   const taken = new Set(keys)
   keys.forEach((k) => {
@@ -79,9 +41,6 @@ function guardModelNames(model: any, log?: any): Rename[] {
       continue
     }
 
-    // `name` is authoritative, not the key: it is the value every derived
-    // form comes from. The key moves with it only when the two agree, which
-    // is the normal shape.
     const from = 'string' === typeof ent.name ? ent.name : key
 
     const to = prefixLeadingDigit(from)
@@ -89,23 +48,11 @@ function guardModelNames(model: any, log?: any): Rename[] {
       continue
     }
 
-    // The guarded name is already another entity's. Renaming onto it would
-    // merge two unrelated entities — silently, since the model is a plain
-    // map — so leave this one alone and say so. The generated SDK still will
-    // not compile, but the reason is now in the log rather than in a syntax
-    // error 20 files later.
     if (taken.has(to)) {
       blocked.push(from)
       continue
     }
 
-    // The FLOW key would collide. `Basic<Name>Flow` is rebuilt from the
-    // guarded Name by every Test component, so if the guarded key is already
-    // occupied by a different flow, renaming would point all of them at that
-    // one and strand this entity's own flow under its old key — generated
-    // tests that exercise the wrong entity, silently. Refuse, exactly as for
-    // an entity-name collision: an SDK that does not compile is a better
-    // outcome than one whose tests lie.
     if (null != flow && flowCollides(flow, from, to)) {
       blocked.push(from)
       continue
@@ -135,18 +82,12 @@ function guardModelNames(model: any, log?: any): Rename[] {
   for (const { from, to, origkey } of plans) {
     const ent = entity[origkey]
     ent.name = to
-    // jostraca's names() is memo-free but idempotent-by-absence: every derived
-    // form has to go, or a stale `Name` from an earlier pass survives the
-    // rename and the SDK is inconsistent with itself.
     delete ent.Name
     delete ent.NAME
     delete ent.name_
     delete ent['name-']
     delete ent.name__orig
 
-    // The key moves only when it WAS the name. A key the model chose for some
-    // other reason is left where it is; every derived identifier comes from
-    // `name`, which is now guarded either way.
     if (origkey === from) {
       entity[to] = ent
       delete entity[origkey]
@@ -157,16 +98,6 @@ function guardModelNames(model: any, log?: any): Rename[] {
 
   renameReferences(model, renames)
 
-  // WARN, not info, because it names work only the project owner can do.
-  //
-  // The generated flow test reads its fixture from
-  // `.sdk/test/entity/<name>/<Name>TestData.json` and seeds the config under
-  // `<name>` — both derived from the guarded name. sdkgen READS that path and
-  // never writes it: the fixture is the project's own content under `.sdk/`,
-  // not generated output, so the rename cannot carry it. A project that
-  // already has one for a digit-named entity goes from an SDK that does not
-  // compile at all to one that compiles with a flow test failing on a missing
-  // fixture — better, but only if it says which file to move.
   if (log?.warn) {
     log.warn({
       point: 'entity-name-guard', renames,
@@ -185,7 +116,6 @@ function guardModelNames(model: any, log?: any): Rename[] {
 }
 
 
-// The flow collection, when the model has one shaped like a map.
 function flowMap(model: any): Record<string, any> | null {
   const flow = model?.main?.[KIT]?.flow
   return (null != flow && 'object' === typeof flow && !Array.isArray(flow))
@@ -206,17 +136,9 @@ function flowCollides(
 }
 
 
-// The model refers to an entity by name in two more places, and both have to
-// move with it or the reference dangles.
 function renameReferences(model: any, renames: Rename[]): void {
   const map = new Map(renames.map((r) => [r.from, r.to]))
 
-  // 1. FLOWS. A flow names its entity, and the Test components look the flow
-  //    up by a key REBUILT from the entity's PascalCase Name
-  //    (`Basic${nom(entity, 'Name')}Flow`), so the key has to move too or the
-  //    entity silently generates no tests. Only a key that matches the
-  //    reconstructed old one is renamed; anything else the author chose is
-  //    left as it is, with just its `entity` field corrected.
   const flow = flowMap(model)
   if (null != flow) {
     for (const key of Object.keys(flow).sort()) {
@@ -244,7 +166,6 @@ function renameReferences(model: any, renames: Rename[]): void {
     }
   }
 
-  // 2. ANCESTORS. A nested entity records its parents by name.
   const entity = model?.main?.[KIT]?.entity
   each(entity).forEach((ent: any) => {
     const ancestors = ent?.relations?.ancestors
@@ -253,7 +174,10 @@ function renameReferences(model: any, renames: Rename[]): void {
     }
     ent.relations.ancestors = ancestors.map((a: any) =>
       Array.isArray(a)
-        ? a.map((n: any) => map.get(n) ?? n)
+        ? a.map((n: string) => {
+          const renamed = map.get(entityRelationName(n))
+          return renamed == null ? n : n.startsWith('$.') ? '$.main.kit.entity.' + renamed : renamed
+        })
         : (map.get(a) ?? a))
   })
 }

package/src/helpers/modelcheck.ts

@@ -1,36 +1,3 @@
-// THE MODEL RULES A PACKAGE'S `.aon` FILES MUST SATISFY.
-//
-// See docs/design/sdkgen-packages.md §10 (the rules) and §14 (the battery).
-//
-// WHY THIS IS A MODULE AND NOT A TEST
-//
-// Every rule below was already enforced — on the BUNDLED scaffold only, and
-// from inside `ts/test/model-compile.test.ts`, where nothing else can call
-// it. `package check` has to apply the same rules to a package this
-// generator has never seen, and a rule written twice diverges: this
-// workstream has produced that exact defect five times (path refs, replace
-// maps, provenance reconstruction, the tilde parse, the installed-registry
-// call). So the rules move here and BOTH callers read them — the guard suite
-// over `ts/project`, which is itself an sdkgen package, and the verb.
-//
-// WHAT MAKES A MODEL FILE WRONG
-//
-// Three failure modes, and they surface at three different times, which is
-// why all three are checked:
-//
-//   1. It does not PARSE under the parser a consumer actually uses. Aontu
-//      takes `#` comments; the npm engine's jsonic enables `//` and `/* */`
-//      by default and `@voxgig/model` switches them back off, so a `//` line
-//      compiles here and fails in the consumer's build. Seven shipped
-//      targets went out broken that way.
-//   2. It parses but does not UNIFY with the base schema — a missing
-//      non-defaulted key (`ext`, `comment.line`, `module.name`, a feature's
-//      `title`). The file alone is fine, so nothing at add time notices; the
-//      consumer's whole model compile is what fails.
-//   3. It unifies but PINS a key the project owns (`publish.version`,
-//      `publish.registry.package`). Concrete-vs-concrete is a conflict in
-//      aontu, so the project cannot override it — and the failure names the
-//      project's own file, not the package's.
 
 import { Aontu } from 'aontu'
 import { createRequire } from 'node:module'
@@ -45,15 +12,6 @@ import { schemaFile } from './shipped'
 const ANCHOR = "base: 'BASE'"
 
 
-// Matched as a WHOLE LINE, never as a substring — the same rule doctor
-// learned the hard way (see AGENTS.md, "Provenance is matched by EXACT LINE").
-//
-// `database: 'BASE'` contains the anchor text, and so does a comment
-// mentioning it. Either would satisfy a substring test while leaving the
-// definition with no anchor of its own: the stamp then rewrites that
-// unrelated occurrence, the item records no usable `base`, and `doctor` and
-// `package update` can never locate its source — with `package check` having
-// reported the file as fine.
 const ANCHOR_RE = /^[ \t]*base: 'BASE'[ \t]*$/m
 
 
@@ -63,35 +21,21 @@ const ANCHOR_RE = /^[ \t]*base: 'BASE'[ \t]*$/m
 const BARE_KEY_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
 
-// The key as it must be WRITTEN in a model file.
 function aontuKey(name: string): string {
   return BARE_KEY_RE.test(name) ? name : "'" + name + "'"
 }
 
 
-// Blank out quoted spans before looking for comment markers, so a `//` inside
-// a string — a url, or the `comment: line: '//'` every C-family target model
-// legitimately declares — is not mistaken for a comment.
 function unquoted(line: string): string {
   return line.replace(/'[^']*'|"[^"]*"|`[^`]*`/g, '')
 }
 
 
-// What the PARSER sees on this line: quoted spans blanked, then everything
-// from the first `#` dropped.
-//
-// Both steps, in that order. Without the second, a perfectly valid comment
-// that happens to mention the token — `# some languages use // comments` —
-// is reported as a parse error and the CLI exits non-zero on a correct
-// package. Without the first, a `#` inside a string would truncate the line
-// early and hide a real `//` after it.
 function code(line: string): string {
   return unquoted(line).split('#')[0]
 }
 
 
-// Every line carrying a slash comment, 1-based, as a consumer's parser would
-// see it.
 function slashComments(text: string): { line: number, text: string }[] {
   const found: { line: number, text: string }[] = []
 
@@ -105,15 +49,6 @@ function slashComments(text: string): { line: number, text: string }[] {
 }
 
 
-// An Aontu configured the way `@voxgig/model` configures it — which is what
-// actually compiles a consumer's models. A plain `new Aontu()` accepts `//`
-// and `/* */`; the Go engine has no such extension, so the npm build switches
-// them off to match, and this must too or the check is checking a parser
-// nobody runs.
-//
-// A FRESH INSTANCE each time: the option call mutates the instance's jsonic,
-// so a cached one would leak its configuration into the bare compile that is
-// deliberately paired with it.
 function strictAontu(options?: any): any {
   const aontu: any = new Aontu(options)
   aontu.lang.jsonic.options({ comment: { def: { slash: null, multi: null } } })
@@ -135,12 +70,6 @@ type CompileResult = {
 }
 
 
-// aontu reports a resolution problem through the `errs` collector and THROWS
-// a parse problem, so both routes have to be handled or the interesting
-// failure escapes as an opaque AontuError. Its message carries a source
-// excerpt with ANSI colouring and line numbers that refer to the text
-// COMPILED, which is not the file on disk once a schema include is prepended
-// — so the excerpt is cut and only the diagnosis is kept.
 function tidy(msg: string): string {
   const lines = String(msg)
     .replace(new RegExp(String.fromCharCode(27) + "\\[[0-9;]*m", 'g'), '')
@@ -155,43 +84,18 @@ function tidy(msg: string): string {
 }
 
 
-// Compile one model file's TEXT.
-//
-//   strict: under the parser @voxgig/model configures (the consumer's
-//           reality) rather than a bare Aontu().
-//   schema: unified with the base schema, which is what makes a missing
-//           non-defaulted key a failure instead of an absent key nobody
-//           notices until the consumer compiles.
-//
-// `path` must be the file's real path even when the text is synthesised:
-// aontu resolves includes relative to it, and stats it.
 function compileModel(
   src: string,
   path: string,
   opts?: { strict?: boolean, schema?: boolean },
 ): CompileResult {
-  // `errs`, NOT `err`. They are different options with opposite behaviour:
-  //
-  //   errs — aontu THROWS on the first problem it cannot resolve.
-  //   err  — aontu COLLECTS problems and returns no model, which sounds
-  //          better and is not: a PARSE problem is then swallowed entirely.
-  //          `// nope` under the strict parser yields a model and an EMPTY
-  //          collector, and a slash comment is the single most common thing
-  //          this check exists to catch.
-  //
-  // So the throw is the signal, and it is caught below. The collector is
-  // still passed and still read: it costs nothing, and an aontu that one day
-  // collects instead of throwing must not report "no errors" here.
   const errs: any[] = []
 
   const text = true === opts?.schema ?
     includeLine(schemaFile()) + '\n' + src : src
 
   try {
-    // Resolve package includes from the model being checked, including native
-    // package self-references. The SDK toolchain's dependencies are unrelated.
     const localRequire = Object.assign(createRequire(Path.resolve(path)), { main: require.main })
-    // Aontu forwards this runtime resolver option to Lang; its public type omits it.
     const options: any = { require: localRequire }
     const aontu = false === opts?.strict ? new Aontu(options) : strictAontu(options)
     const model = aontu.generate(text, { path, errs })
@@ -208,16 +112,6 @@ function compileModel(
 }
 
 
-// Every key the schema DEFAULTS and a project therefore expects to set, with
-// TWO values to try setting it to. A target model that declares any of them
-// makes the project's own declaration a concrete-vs-concrete conflict — which
-// fails the consumer's entire model compile, naming the consumer's file.
-//
-// Two values because aontu unifies two EQUAL concrete scalars happily: a
-// target pinning `publish: tag: active: false` — which is one of only two
-// values that key can take — passed a single-sentinel probe while still
-// making `true` impossible for the consumer. One alternative value per key is
-// enough: a pin can equal one sentinel or the other, never both.
 const PUBLISH_OVERRIDES: [string, string, string][] = [
   ['publish: version', "'9.9.9'", "'8.8.8'"],
   ['publish: tag: active', 'false', 'true'],