@voxgig/sdkgen 3.4.6 → 3.5.0

package/src/helpers/modelcheck.ts

@@ -0,0 +1,262 @@
+// THE MODEL RULES A PACKAGE'S `.aontu` 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 { schemaFile } from './shipped'
+
+
+// The provenance anchor. The literal line a shipped definition carries so the
+// stamp has somewhere to hang (helpers/stdrep), and therefore the one thing
+// a package's definition must not lose.
+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
+
+
+// An aontu map key that is safe unquoted. Everything else — a hyphen
+// (`go-cli`), a dot (`go.v2`), a leading digit (`2go`) — has to be quoted or
+// the file does not parse, and the ITEM name grammar admits all three.
+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 }[] = []
+
+  String(text).split('\n').forEach((line: string, i: number) => {
+    if (/(^|\s)(\/\/|\/\*)/.test(code(line))) {
+      found.push({ line: i + 1, text: line.trim() })
+    }
+  })
+
+  return found
+}
+
+
+// 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(): any {
+  const aontu: any = new Aontu()
+  aontu.lang.jsonic.options({ comment: { def: { slash: null, multi: null } } })
+  return aontu
+}
+
+
+// An `@` include line for a path, quoted so a path containing a quote or a
+// backslash — a Windows path, or the pathological ones the provenance tests
+// exercise — cannot end the string early.
+function includeLine(file: string): string {
+  return "@'" + String(file).replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'"
+}
+
+
+type CompileResult = {
+  model?: any
+  errors: string[]
+}
+
+
+// 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'), '')
+    .split('\n')
+
+  const cut = lines.findIndex((l: string) => /^\s*-->/.test(l))
+
+  return (cut < 0 ? lines : lines.slice(0, cut))
+    .map((l: string) => l.trim())
+    .filter((l: string) => '' !== l)
+    .join(' ')
+}
+
+
+// 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 {
+    const aontu = false === opts?.strict ? new Aontu() : strictAontu()
+    const model = aontu.generate(text, { path, errs })
+
+    return {
+      model,
+      errors: errs.map((e: any) =>
+        tidy((null == e.why ? '' : '[' + e.why + '] ') + (e.msg ?? String(e)))),
+    }
+  }
+  catch (err: any) {
+    return { errors: [tidy(err.message ?? String(err))] }
+  }
+}
+
+
+// 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'],
+  ['publish: registry: state', "'active'", "'inactive'"],
+  ['publish: registry: active', 'true', 'false'],
+  ['publish: registry: package', "'@acme/pinned'", "'@acme/other'"],
+]
+
+
+// The probe: unify the target model with a project that sets each of them,
+// once per sentinel set. EITHER conflicting means the key is pinned.
+function publishOverrideProbe(
+  src: string, path: string, tname: string,
+): CompileResult {
+  const key = aontuKey(tname)
+
+  const run = (pick: (o: [string, string, string]) => string): CompileResult =>
+    compileModel(
+      [src, ...PUBLISH_OVERRIDES.map(
+        (o) => 'main: kit: target: ' + key + ': ' + o[0] + ': ' + pick(o))]
+        .join('\n'),
+      path)
+
+  const first = run((o) => o[1])
+  const second = run((o) => o[2])
+
+  return {
+    model: first.model ?? second.model,
+    errors: [...first.errors, ...second.errors],
+  }
+}
+
+
+export type {
+  CompileResult,
+}
+
+export {
+  ANCHOR,
+  ANCHOR_RE,
+  PUBLISH_OVERRIDES,
+  aontuKey,
+  compileModel,
+  includeLine,
+  publishOverrideProbe,
+  slashComments,
+  strictAontu,
+  unquoted,
+}

package/src/helpers/semver.ts

@@ -0,0 +1,211 @@
+// A DELIBERATELY SMALL semver range check, for `engines.sdkgen`.
+//
+// WHY NOT node-semver
+//
+// This package has no runtime dependencies (`dependencies: {}`), and adding
+// one to read a single optional manifest field is a poor trade. What the field
+// actually carries is a floor — `">=3.5"` — so the subset below covers the
+// spellings that occur, and REFUSES TO GUESS at anything else.
+//
+// THE FAILURE DIRECTION MATTERS MORE THAN THE COVERAGE
+//
+// Getting this wrong in the strict direction refuses a package that would
+// have worked, which is worse than the incompatibility it is trying to
+// prevent. So `satisfies` has three outcomes, not two: yes, no, and
+// `undefined` for "this range is outside the subset I understand". A caller
+// that gets `undefined` must let the install proceed and say so, never treat
+// it as a failure.
+//
+// SUPPORTED
+//   *  x  X  ''            any version
+//   >=1.2.3  >1.2  <=2  <2  =1.2.3  1.2.3
+//   ^1.2.3  ~1.2.3
+//   space-separated conjunction:  ">=3.5 <4"
+//   ||-separated alternatives:    "^3 || ^4"
+//
+// NOT SUPPORTED (returns undefined)
+//   hyphen ranges (`1.2.3 - 2.3.4`), prerelease/build metadata comparison,
+//   and anything else. Prereleases are compared by their numeric core only,
+//   which is why a range mentioning one is rejected rather than mishandled.
+
+
+type Parts = [number, number, number]
+
+
+const COMPARATOR_RE = /^(>=|<=|>|<|=|\^|~)?v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/
+
+const ANY_RE = /^(\*|x|X)$/
+
+
+// A version as three numbers, or undefined if it is not a plain `X.Y.Z`.
+// A prerelease or build suffix returns undefined deliberately: comparing them
+// properly is most of what makes semver hard, and this subset does not.
+function parseVersion(v: string): Parts | undefined {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(v).trim())
+
+  return null == m ? undefined :
+    [Number(m[1]), Number(m[2]), Number(m[3])]
+}
+
+
+function compare(a: Parts, b: Parts): number {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) {
+      return a[i] < b[i] ? -1 : 1
+    }
+  }
+  return 0
+}
+
+
+// The upper bound `^` and `~` imply, exclusive.
+//
+//   ^1.2.3 -> <2.0.0      ^0.2.3 -> <0.3.0      ^0.0.3 -> <0.0.4
+//   ~1.2.3 -> <1.3.0      ~1.2   -> <1.3.0      ~1     -> <2.0.0
+//
+// `^0.x` is the case worth stating: npm treats a leading zero as unstable, so
+// the caret narrows to the first NON-ZERO component. Getting that wrong would
+// admit `0.3.0` for `^0.2.3`, which is a breaking change by that convention.
+function caretBound(p: Parts): Parts {
+  if (0 !== p[0]) return [p[0] + 1, 0, 0]
+  if (0 !== p[1]) return [0, p[1] + 1, 0]
+  return [0, 0, p[2] + 1]
+}
+
+
+function tildeBound(p: Parts, given: number): Parts {
+  return nextBound(p, given)
+}
+
+
+// The version just past everything a PARTIAL version covers: `3.4` covers all
+// of 3.4.x, so the next bound is 3.5.0; `3` covers all of 3.x, so 4.0.0.
+// Shared by `~` and by the two strict comparators that need it, so they
+// cannot disagree about where a partial version ends.
+function nextBound(p: Parts, given: number): Parts {
+  return 1 === given ? [p[0] + 1, 0, 0] : [p[0], p[1] + 1, 0]
+}
+
+
+// One comparator against one version. `undefined` if the comparator is
+// outside the subset.
+function satisfiesOne(version: Parts, comparator: string): boolean | undefined {
+  const c = comparator.trim()
+
+  if ('' === c || ANY_RE.test(c)) {
+    return true
+  }
+
+  const m = COMPARATOR_RE.exec(c)
+
+  if (null == m) {
+    return undefined
+  }
+
+  const op = m[1] ?? '='
+
+  // How many components were actually written — `~1.2` and `~1` bound
+  // differently, and a partial version means "any" in its missing places.
+  const given = null != m[4] ? 3 : null != m[3] ? 2 : 1
+  const p: Parts = [Number(m[2]), Number(m[3] ?? 0), Number(m[4] ?? 0)]
+
+  const cmp = compare(version, p)
+
+  // A PARTIAL version is a RANGE, not a version with zeroes in it, and two of
+  // the four strict comparators have to move their bound to say so:
+  //
+  //   >3.4   means ">= all of 3.4.x"  ->  >=3.5.0    (not >3.4.0)
+  //   <=3.4  means "<= all of 3.4.x"  ->  <3.5.0     (not <=3.4.0)
+  //   >=3.4  ->  >=3.4.0     <3.4  ->  <3.4.0        (already right)
+  //
+  // Read as literal zeroes, `>3.4` admitted 3.4.8 (an incompatible package
+  // let through) and `<=3.4` rejected it (a compatible one refused) — the two
+  // failures this module's whole shape is meant to avoid, in one comparator.
+  const bound = 3 === given ? p : nextBound(p, given)
+
+  if ('>=' === op) return 0 <= cmp
+  if ('<' === op) return 0 > cmp
+  if ('>' === op) return 3 === given ? 0 < cmp : 0 <= compare(version, bound)
+  if ('<=' === op) return 3 === given ? 0 >= cmp : 0 > compare(version, bound)
+
+  if ('^' === op) {
+    return 0 <= cmp && 0 > compare(version, caretBound(p))
+  }
+
+  if ('~' === op) {
+    return 0 <= cmp && 0 > compare(version, tildeBound(p, given))
+  }
+
+  // `=` / bare. A partial version is a PREFIX match: `1.2` admits any 1.2.x,
+  // which is what every other tool means by it.
+  if (3 === given) return 0 === cmp
+  if (2 === given) return version[0] === p[0] && version[1] === p[1]
+  return version[0] === p[0]
+}
+
+
+// Does `version` satisfy `range`?
+//
+// `true` / `false` / `undefined` — see the note at the top: undefined means
+// "not understood", and the caller must not treat it as a failure.
+function satisfies(version: string, range: string): boolean | undefined {
+  const v = parseVersion(version)
+
+  if (null == v) {
+    return undefined
+  }
+
+  const text = String(range ?? '').trim()
+
+  if ('' === text || ANY_RE.test(text)) {
+    return true
+  }
+
+  // A hyphen range is not supported, and its parts would otherwise be read as
+  // a conjunction of two bare versions — which is never satisfiable, i.e. a
+  // false REFUSAL. Rejected explicitly rather than by accident.
+  if (/\s-\s/.test(text)) {
+    return undefined
+  }
+
+  // An alternative that MATCHES wins immediately, whatever the others say.
+  // But a `false` is only reportable if every comparator was understood:
+  // otherwise the honest answer is "do not know", and refusing on it would be
+  // the strict-direction failure this module is shaped to avoid.
+  let unknown = false
+
+  for (const alt of text.split('||')) {
+    const comparators = alt.trim().split(/\s+/).filter((s) => '' !== s)
+
+    if (0 === comparators.length) {
+      unknown = true
+      continue
+    }
+
+    let all = true
+
+    for (const c of comparators) {
+      const one = satisfiesOne(v, c)
+
+      if (null == one) {
+        unknown = true
+        all = false
+      }
+      else if (!one) {
+        all = false
+      }
+    }
+
+    if (all) {
+      return true
+    }
+  }
+
+  return unknown ? undefined : false
+}
+
+
+export {
+  satisfies,
+  parseVersion,
+}

package/src/helpers/shipped.ts

@@ -0,0 +1,41 @@
+// WHERE THIS GENERATOR'S OWN FILES ARE, resolved from the compiled code.
+//
+// Every other path in `action/` is relative to the PROJECT being operated on
+// — `node_modules/@voxgig/sdkgen/project/.sdk` is how a consumer reaches the
+// bundled scaffold, and that is correct there. `package check` has no project:
+// it is run by an AUTHOR against a package that may sit anywhere, and it
+// still needs this generator's base schema (to unify against) and its feature
+// catalogue (to know which names denote features). Those come from the
+// installation doing the checking, which is this one.
+//
+// `__dirname` is `dist/helpers` in the shipped package, so the package root is
+// two levels up. npm can only ship files under that root, which is why the
+// canonical `model/` is mirrored into `ts/model/` (the model-mirror guard
+// fails on drift).
+
+import Path from 'node:path'
+
+
+function packageRoot(): string {
+  return Path.resolve(__dirname, '..', '..')
+}
+
+
+// The base model schema — `@voxgig/sdkgen/model/sdkgen.aontu`.
+function schemaFile(): string {
+  return Path.join(packageRoot(), 'model', 'sdkgen.aontu')
+}
+
+
+// The bundled scaffold — the `.sdk` of `ts/project`, which is itself an
+// sdkgen package.
+function scaffoldFolder(): string {
+  return Path.join(packageRoot(), 'project', '.sdk')
+}
+
+
+export {
+  packageRoot,
+  schemaFile,
+  scaffoldFolder,
+}

package/src/helpers/stdrep.ts

@@ -50,7 +50,77 @@ function templateReplacements(model: any, tname: string): Record<string, string>
 }
 
 
+// PROVENANCE — where a copied target or feature came from.
+//
+// Every shipped model file carries a `base: 'BASE'` line as an ANCHOR, and
+// the add actions rewrite that one line into the block the copy keeps:
+//
+//   base: 'BASE'   ->   base: 'node_modules/@acme/sdkgen-iot/.sdk'
+//                       origname: 'iot-go'
+//
+// The anchor is why every shipped model needs the line even though most
+// installs are unaliased from the bundled scaffold: a `replace` map can only
+// rewrite text that is already there, and there is nowhere else to hang the
+// keys that do not appear in the source.
+//
+// ONE definition, for the same reason templateReplacements is one: `target
+// add` and `feature add` WRITE with this map and `doctor` re-applies it to
+// the scaffold before comparing. A writer and a reader that disagree by a
+// single character make every project read as forked.
+//
+// `origname` and `package` are emitted only when they apply, so an ordinary
+// install still records exactly one line and its model file is unchanged
+// from what earlier versions wrote — apart from the base value itself.
+type Provenance = {
+  // The `.sdk` folder the copy came from, project-relative and
+  // '/'-normalised (see resolveTarget).
+  base: string
+
+  // The name in the SOURCE and the name it was INSTALLED as. Equal for an
+  // ordinary add; different for `target add go~go2`.
+  origname?: string
+  name?: string
+
+  // The sdkgen package that provided it, when the source declared one.
+  package?: string
+}
+
+// Two spaces, matching every shipped model file's indentation for these keys.
+const PROVENANCE_INDENT = '  '
+
+
+// A value as a single-quoted aontu string. These are PATHS and NAMES from the
+// filesystem, so they can legally contain a quote — `/home/o'connor/pkg` is a
+// valid directory — and concatenating one between quotes closes the string
+// early and leaves the copied model unparsable. Aontu accepts a backslash
+// escape, which keeps the quoting style every shipped model already uses.
+function aontuString(value: string): string {
+  return "'" + String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'") + "'"
+}
+
+
+function provenanceReplace(prov: Provenance): Record<string, string> {
+  const lines = ['base: ' + aontuString(prov.base)]
+
+  if (null != prov.origname && null != prov.name &&
+    prov.origname !== prov.name) {
+    lines.push('origname: ' + aontuString(prov.origname))
+  }
+
+  if (null != prov.package && '' !== prov.package) {
+    lines.push('package: ' + aontuString(prov.package))
+  }
+
+  return { "base: 'BASE'": lines.join('\n' + PROVENANCE_INDENT) }
+}
+
+
+export type {
+  Provenance,
+}
+
 export {
   ensureStdrep,
   templateReplacements,
+  provenanceReplace,
 }