@voxgig/sdkgen 4.21.0 → 4.22.0

package/src/helpers/modelNames.ts

@@ -1,35 +1,5 @@
 /* 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'
@@ -37,9 +7,6 @@ import { KIT } from '@voxgig/apidef'
 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 +15,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 +39,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 +46,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 +80,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 +96,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 +114,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 +134,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 +164,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

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'],