@voxgig/sdkgen 4.20.0 → 4.22.0

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])
 }