@voxgig/sdkgen 4.21.0 → 4.22.0

package/src/action/action.ts

@@ -12,38 +12,9 @@ import type {
 } from '../types'
 
 
-// `./` — aontu 0.65 reads a bare single-segment include as a PACKAGE name
-// (ADR-039), so `@"go.aon"` resolves against the package stores and is
-// refused: "local files need a ./ prefix". A sibling file has to say so.
 const indexEntry = (name: string) => `@"./${name}.aon"`
 
 
-// An index line that is an ACTIVE include, and the name it includes — or
-// undefined for a blank line, a comment, or anything else.
-//
-// Parsed rather than compared as a string, because both spellings around an
-// include are legal aontu and mean opposite things:
-//
-//   @"./go.aon"               -> active, name 'go'
-//   @"go.aon"                 -> active, name 'go'  (pre-0.65 spelling)
-//   @"./go.aon"  # pinned     -> active, name 'go'  (trailing comment)
-//     @"./go.aon"             -> active, name 'go'  (indented)
-//   # @"./go.aon"             -> NOT active
-//
-// A substring test (what this used to be) reads the commented-out form as
-// present, so `target add go` on a project that had switched the target off
-// by hand appended nothing and reported success while the target stayed
-// absent from the model. A whole-line equality test fixes that but then
-// misses the trailing-comment form, and appends a SECOND active include.
-//
-// BOTH SPELLINGS, and the `./` is not part of the name. Every index in every
-// already-generated SDK carries the bare form, and those files are the
-// project's own -- they change when the project regenerates, not when sdkgen
-// releases. Reading only the new spelling would make `target add go` on any
-// existing repo believe `go` was absent and append a second include; reading
-// only the old one would do the same the other way round once the index is
-// rewritten. Capturing the name WITHOUT the prefix is what lets the two
-// spellings compare equal, which is the whole point.
 const INDEX_ENTRY_RE = /^\s*@"(?:\.\/)?([^"]+)\.aon"\s*(?:#.*)?$/
 
 function indexEntryName(line: string): string | undefined {
@@ -75,12 +46,6 @@ function appendIndexEntries(content: string, names: string[]): string {
 }
 
 
-// Drop the `@"<name>.aon"` line for each name — the inverse of
-// appendIndexEntries, matching line-exact for the same reasons.
-//
-// Nothing calls this yet: a `remove` action is the fast-follow this exists
-// for (see docs/design/sdkgen-packages.md), and it is written here beside its
-// inverse so the two cannot drift on how an entry is recognised.
 function removeIndexEntries(content: string, names: string[]): string {
   const drop = new Set(names)
 
@@ -99,10 +64,6 @@ const UpdateIndex = cmp(function UpdateIndex(props: any) {
 })
 
 
-// Names given to an `add` action: every positional after the subcommand is
-// a name, each possibly comma-separated — `target add ts,py,go` and
-// `target add ts py go` are equivalent (space-separated extras used to be
-// silently dropped).
 function parseAddNames(args: any[]): string[] {
   return args.slice(2)
     .flatMap((a: any) => 'string' === typeof a ? a.split(',') : a)
@@ -110,17 +71,6 @@ function parseAddNames(args: any[]): string[] {
 }
 
 
-// The current index file for each kind, which `UpdateIndex` appends to.
-//
-// `seed` IS THE UPGRADE PATH. A project scaffolded before a kind existed has
-// no `model/<kind>/<kind>-index.aon` — every project alive today is in
-// exactly that position for `docs` — and reading it unguarded made the FIRST
-// `edition add` in any existing project fail on ENOENT before it wrote anything.
-//
-// Seeded per call rather than defaulted for every kind: a missing
-// `target-index.aon` in a scaffolded project is a broken project, and
-// quietly recreating it would hide that. A kind the project has never used is
-// a different thing, and only its own action knows which case it is in.
 function loadContent(
   actx: ActionContext, which: string | string[], seed?: Record<string, string>,
 ) {
@@ -143,21 +93,6 @@ function loadContent(
 
 
 
-// ENSURE THE PROJECT'S OWN MODEL INCLUDES A KIND'S INDEX.
-//
-// `model/sdk.aontu` is written once, by create-sdkgen, and includes the
-// indexes of the kinds that existed then. So a project scaffolded before a
-// kind existed — which is every project alive today, for `docs` — never
-// includes its index, and the item's model file is an orphan: it is on disk,
-// `<kind>-index.aon` includes it, and NOTHING includes that. `main.kit.doc.edition`
-// is then absent from the compiled model, so `package list`, `package update`
-// and `doctor` cannot see the item at all.
-//
-// Appending one include line is additive and idempotent, and it is the only
-// way an existing project can adopt a new kind without hand-editing. The
-// entry is parsed, not substring-matched, for the reason `hasIndexEntry`
-// documents: a commented-out include means the project switched it OFF, and
-// re-adding it would override that.
 function ensureModelInclude(actx: ActionContext, kind: string): boolean {
   const fs = actx.fs()
   const url = actx.url

package/src/action/check.ts

@@ -1,37 +1,4 @@
 import { kindCollection } from '../helpers/kindCollection'
-// `package check` — the AUTHOR-side battery. Design §14.
-//
-// WHAT IT IS FOR
-//
-// Every other verb here acts on a project. This one acts on a PACKAGE, before
-// anyone installs it, and its whole value is moving a failure from the
-// consumer's build back to the author's terminal. The failures worth moving
-// are the ones a package cannot detect by using itself:
-//
-//   - a model file that compiles for the author and not for a consumer (the
-//     `//` comment asymmetry — seven shipped targets went out that way);
-//   - a key the base schema requires and the file omits, which nothing
-//     notices until a consumer unifies the whole model;
-//   - a key the PROJECT owns that the package pinned, which fails in the
-//     consumer's own file and reads as the consumer's mistake;
-//   - a manifest that disagrees with the disk, in either direction;
-//   - feature source the trim step will never recognise, so it ships to every
-//     project whatever the model selected.
-//
-// WHY IT REUSES EVERYTHING
-//
-// The battery asserts nothing of its own. Manifest agreement is
-// `validateManifest`, the trees a kind needs are the kind registry's
-// `requires`, the feature catalogue is `availableFeatures`, the source walk is
-// `findFeatureEntries`, the model rules are `helpers/modelcheck`. A check that
-// restated any of those would be a second copy of a rule the installer
-// already has — and this workstream's most repeated defect is exactly that,
-// two copies of one rule drifting apart. Where the check and the installer
-// disagree, the check is wrong by construction.
-//
-// NO MANIFEST IS NOT A REFUSAL. `package add` requires one; here its absence
-// is the first finding and the rest of the battery still runs, because an
-// author who has not written it yet is precisely who needs the rest.
 
 import { unknownTags, TAGS } from '../helpers/applicability'
 import Path from 'node:path'
@@ -75,23 +42,9 @@ import { scaffoldFolder } from '../helpers/shipped'
 import { KINDS } from './kind'
 
 
-// How many lines of one file's worth of the same problem to name before
-// saying "and N more". A file with a hundred `//` lines is one mistake, and
-// printing a hundred findings buries the other nine checks.
 const SAME_FILE_LIMIT = 5
 
 
-// A LIST OF NAMES from a manifest map, or nothing.
-//
-// The manifest is the one input here that is neither this generator's nor
-// validated before it is read: `provides: { target: 42 }` is a manifest a
-// person can write, `checkShape` already reports it, and spreading it then
-// threw `TypeError: claimed is not iterable` — turning an actionable finding
-// into a stack trace, from the verb whose entire job is actionable findings.
-//
-// Malformed reads as EMPTY rather than as its own finding: the shape checks
-// have already said what is wrong with it, and saying so twice in different
-// words helps nobody.
 function claims(map: any, key: string): string[] {
   const value = map?.[key]
 
@@ -118,8 +71,6 @@ async function cmd_package_check(
     (a: any) => 'string' === typeof a ? a.split(',') : a)
     .filter((r: any) => null != r && '' !== r)
 
-  // No ref means "the package I am standing in", which is where an author
-  // runs it.
   const reports = (0 === refs.length ? ['.'] : refs)
     .map((ref: string) => checkPackage(ref, actx))
 
@@ -146,8 +97,6 @@ function checkPackage(ref: string, actx: ActionContext): CheckReport {
 
   const { found, search } = probePackage(fs, actx.folder ?? '.', ref)
 
-  // Nothing to check is not a finding — it is a wrong invocation, and the
-  // caller needs to know which paths were tried.
   if (null == found) {
     throw new SdkGenError(
       'Package not found: ' + ref + '\n  looked for a `.sdk` folder in:\n    ' +
@@ -188,7 +137,6 @@ function checkPackage(ref: string, actx: ActionContext): CheckReport {
 }
 
 
-// The manifest, and its agreement with the disk in both directions.
 function checkManifest(fs: any, sdk: string, read: any): Finding[] {
   if (null != read.err) {
     return [{
@@ -212,13 +160,6 @@ function checkManifest(fs: any, sdk: string, read: any): Finding[] {
 }
 
 
-// Every item's definition file: the anchor, the comment dialect, the parse,
-// the schema, and the kind-specific probes.
-//
-// The items are the manifest's claims UNION what is on disk, so a definition
-// nobody claims is still checked (its being unclaimed is `validateManifest`'s
-// finding, not a reason to skip it) and a claim with no file is skipped here
-// (its absence is also already reported, and there is nothing to compile).
 function checkItems(fs: any, sdk: string, manifest?: Manifest): Finding[] {
   const found: Finding[] = []
 
@@ -261,8 +202,6 @@ function checkDefinition(
       '`package update` and `doctor` could never locate its source'))
   }
 
-  // 2. The comment dialect. Reported before the parse so the finding names
-  //    the LINE rather than aontu's view of where the parse gave up.
   const slashes = slashComments(src)
 
   for (const s of slashes.slice(0, SAME_FILE_LIMIT)) {
@@ -277,15 +216,10 @@ function checkDefinition(
       'and ' + (slashes.length - SAME_FILE_LIMIT) + ' more slash-comment line(s)'))
   }
 
-  // A slash comment IS the parse failure below, and saying it twice — once
-  // with the line, once as aontu's `unexpected character(s): //` — reads as
-  // two problems. Everything after it would be reporting on a file the author
-  // is about to change anyway.
   if (0 < slashes.length) {
     return found
   }
 
-  // 3. The parse, as a CONSUMER's parser sees it.
   const strict = compileModel(src, file)
 
   if (0 < strict.errors.length) {
@@ -300,15 +234,9 @@ function checkDefinition(
         '  (it DOES compile under a bare Aontu() — the difference is the ' +
         'comment dialect a consumer configures)' : '')))
 
-    // Nothing below can run on a file that does not compile.
     return found
   }
 
-  // 4. Does it declare the key its FILENAME promises? `model/target/iot-go.aon`
-  //    is copied to that name and included by it, so a file still declaring
-  //    `main: kit: target: go:` installs an item the consumer's model never
-  //    sees — the exact mistake a package author makes copying a bundled
-  //    target as a starting point.
   const declared = kindCollection(strict.model, kind)?.[name]
 
   if (null == declared || 'object' !== typeof declared) {
@@ -328,12 +256,6 @@ function checkDefinition(
       err + '  (unified with the base schema — this is what a consumer compiles)'))
   }
 
-  // 5b. APPLICABILITY TAGS come from a CLOSED vocabulary (see
-  //     helpers/applicability). `provides: &: boolean` accepts any key, so
-  //     without this a typo — `sekrreto` for `sekreto` — compiles cleanly
-  //     and silently makes the feature apply to NO target at all. That is
-  //     the worst shape a mistake can take here: the feature simply
-  //     vanishes from every generated SDK with no diagnostic anywhere.
   const tagkey = 'feature' === kind ? 'needs' : 'provides'
   const unknown = null == declared ? [] : unknownTags((declared as any)[tagkey])
 
@@ -404,8 +326,6 @@ function checkFeatureModel(model: any, name: string, at: At): Finding[] {
       continue
     }
 
-    // The SLOT itself is legal and empty; only concrete entries are the
-    // mistake. An entry is concrete when it declares anything of its own.
     const named = Object.keys(deps).filter((d: string) =>
       null != deps[d] && 'object' === typeof deps[d] &&
       0 < Object.keys(deps[d]).length)
@@ -462,14 +382,6 @@ function checkFeatureSource(
     }
   }
 
-  // Strays: feature-shaped entries in a provided TARGET's tree whose name is
-  // in no catalogue. They are copied into every project regardless of what
-  // its model selects, because trim only drops what it can recognise.
-  //
-  // NOT REPORTED AT ALL if this generator's own feature definitions cannot be
-  // read: every bundled feature's source would then look like a stray, and a
-  // check that fires on a correct package because of a problem at ITS end is
-  // worse than one that stays quiet.
   if (0 === bundled.length) {
     return found
   }

package/src/action/dispatch.ts

@@ -1,20 +1,3 @@
-// WHAT `voxgig-sdkgen <action> …` CAN BE.
-//
-// Built FROM THE KIND REGISTRY rather than hand-listed, so registering a kind
-// is the only edit a new kind needs — `edition add …` costs no dispatch code
-// (docs/design/sdkgen-packages.md §9). The `package` and `doctor` verbs are
-// not kinds and are added beside it.
-//
-// It lives in its own module because `package.ts` needs the per-kind add
-// functions and `target.ts` imports `feature.ts` which imports `kind.ts`;
-// wiring them together anywhere in that chain is a require cycle. Here,
-// nothing imports back.
-//
-// NULL-PROTOTYPE, and this is not decoration. A plain object literal inherits
-// Object.prototype, so `voxgig-sdkgen toString` (or `constructor`, `valueOf`,
-// …) resolved to an inherited function, passed the `null == actionFunc`
-// guard, and got CALLED with the action arguments instead of reporting an
-// unknown action.
 
 import type {
   ActionContext,
@@ -78,16 +61,6 @@ function actionNames(): string[] {
 }
 
 
-// Does this invocation need the PROJECT's model?
-//
-// Every verb but one operates on a project, and compiling `model/sdk.aontu`
-// before dispatch is what makes them fail early and clearly when run from the
-// wrong directory. `package check` is the exception on purpose: it operates
-// on a PACKAGE, and an author runs it in their package root, where there is
-// no project model to compile and nothing is wrong with that.
-//
-// Stated here, with the verb table, rather than in the CLI or in `sdkgen.ts`:
-// it is a fact about the verb.
 function needsModel(args: string[]): boolean {
   return !('package' === args[0] && 'check' === args[1])
 }