@voxgig/sdkgen 4.21.0 → 4.22.0

package/src/helpers/featureSource.ts

@@ -1,37 +1,3 @@
-// Locate the per-feature source inside a target's template tree.
-//
-// WHY THIS EXISTS
-//
-// `target add` is supposed to copy source for the features the model
-// declares, and nothing else. It used to do that with a single hardcoded
-// path assumption:
-//
-//   Copy({ from: 'tm/<lang>', exclude: [/src\/feature/] })
-//   Folder({ name: 'src/feature' }, () => /* copy each model feature */)
-//
-// That assumption holds for exactly two targets. `ts` and `js` keep feature
-// source at `src/feature/<name>/`; everyone else does something else —
-// `tm/go/feature/retry_feature.go`, `tm/rust/feature/retry.rs`,
-// `tm/py/pkg/feature/retry_feature.py`, `tm/dart/lib/feature/retry/...`,
-// `tm/swift/Sources/ProjectNameSDK/feature/RetryFeature.swift`, and so on.
-// None of those match `src/feature`, so the exclude never saw them and every
-// shipped feature was copied into every project regardless of the model: 272
-// stray source files across 17 targets for a project declaring no features
-// at all. (For those targets `src/feature/<name>/` holds only a `.gitkeep`
-// placeholder — the old gate was gating empty directories.)
-//
-// So instead of encoding one layout, DISCOVER it: walk the template tree,
-// treat any directory named `feature` as a feature container, and map each
-// entry inside it back to a feature name. That covers every layout above,
-// and a target added later gets gated without anyone editing this file.
-//
-// The mapping is deliberately conservative. An entry only counts as feature
-// source when its derived name is one the generator can actually supply
-// (`availableFeatures`, read from `model/feature/*.aon`). Everything else
-// inside a feature directory — `feature_options.go`, `FeatureOptions.cs`,
-// `mod.rs`, `support.rs`, `options.hpp`, `__init__.py`, `README.md`, and the
-// `harness.ts` under `test/feature/` — derives a name no feature has, so it
-// is left alone.
 
 import Path from 'node:path'
 
@@ -42,30 +8,20 @@ import { definitionNames } from './definition'
 import { isJunk } from './junk'
 
 
-// One feature's source within a target template tree.
 type FeatureSource = {
-  // Feature name, lowercased ('retry').
   name: string
 
-  // Path relative to the target template root ('feature/retry_feature.go',
-  // 'lib/feature/retry'), always with forward slashes.
   path: string
 
-  // True when `path` is a directory holding the whole feature.
   folder: boolean
 }
 
 
-// One entry inside a feature container, before the catalogue has had its say.
 type FeatureEntry = FeatureSource & {
-  // Does it follow a per-feature NAMING convention? See `featureShaped`.
   shaped: boolean
 }
 
 
-// Directory name that marks a feature container. Kept exact (not a substring
-// match) so `utility/feature_add.go` and `test/feature_test.go` — which are
-// shared machinery, not per-feature source — are never treated as features.
 const FEATURE_DIR = 'feature'
 
 
@@ -75,17 +31,6 @@ const FEATURE_DIR = 'feature'
 const BASE_FEATURE = 'base'
 
 
-// Derive the feature name an entry inside a feature directory belongs to.
-// Returns the lowercased name, which the caller then checks against the
-// available set.
-//
-//   retry_feature.go   -> retry     (go, py, rb, lua, perl)
-//   RetryFeature.cs    -> retry     (csharp, java, kotlin, scala, swift, php)
-//   retry.rs           -> retry     (rust, c, cpp, zig, elixir)
-//   retry/             -> retry     (ts, js, dart)
-//   feature_options.go -> feature_options   (not a feature; `_feature` is a
-//                                            prefix here, not a suffix)
-//   FeatureOptions.cs  -> featureoptions    (ditto)
 function featureOf(entry: string, folder: boolean): string {
   if (folder) {
     return entry.toLowerCase()
@@ -102,14 +47,6 @@ function featureOf(entry: string, folder: boolean): string {
 }
 
 
-// Feature names this generator can supply, read from the scaffold's
-// `model/feature/*.aon`. This is the authoritative catalogue: a name not in
-// it is not a feature, so nothing outside it is ever excluded.
-//
-// LOWERCASED, unlike `definitionNames`, because these are matched against
-// names DERIVED FROM FILENAMES (`RetryFeature.swift` -> `retry`), and the
-// languages disagree about case. The manifest compares definition names as
-// written, so the two callers cannot share the lowercasing.
 function availableFeatures(fs: any, sdkfolder: string): string[] {
   return definitionNames(fs, sdkfolder, 'feature')
     .map((n: string) => n.toLowerCase())
@@ -117,15 +54,6 @@ function availableFeatures(fs: any, sdkfolder: string): string[] {
 }
 
 
-// Does the entry LOOK like per-feature source, whatever it is called?
-//
-// The naming conventions carry the intent: `<name>_feature.<ext>`,
-// `<Name>Feature.<ext>`, and a directory named for the feature. A bare
-// `<name>.<ext>` does NOT — `retry.rs` and `support.rs` are written the same
-// way, so shape cannot separate rust's feature source from rust's shared
-// machinery, and only the catalogue can. That is the deliberate blind spot of
-// `package check`'s unrecognised-source finding: it reports what it can prove
-// looks like a feature, and stays quiet where it would have to guess.
 function featureShaped(entry: string, folder: boolean): boolean {
   if (folder) {
     return true
@@ -137,15 +65,6 @@ function featureShaped(entry: string, folder: boolean): boolean {
 }
 
 
-// Every entry inside a feature container of a target's template tree —
-// whether or not its derived name is a feature this generator knows.
-//
-// `known` decides DESCENT, not membership: a directory that names a known
-// feature is the whole feature, so the walk stops there, and one that does
-// not is walked through (`src/feature/base/` holds `BaseFeature.ts`, and the
-// container rule below then ignores it because its parent is not `feature`).
-// The unknown entries are what `package check` reports and what
-// `findFeatureSources` drops; both need the same walk, so there is one.
 function findFeatureEntries(
   fs: any, tmfolder: string, known: Set<string>,
 ): FeatureEntry[] {
@@ -155,7 +74,6 @@ function findFeatureEntries(
     return found
   }
 
-  // `rel` is relative to tmfolder, '' at the root.
   const walk = (rel: string) => {
     const abs = '' === rel ? tmfolder : Path.join(tmfolder, rel)
     const entries = fs.readdirSync(abs).sort()
@@ -199,8 +117,6 @@ function findFeatureEntries(
 }
 
 
-// Walk a target's template tree and return every per-feature source entry.
-// `tmfolder` is the target template root (`<sdk>/tm/<lang>`).
 function findFeatureSources(fs: any, tmfolder: string, available: string[]): FeatureSource[] {
   const known = new Set(available)
 
@@ -210,12 +126,6 @@ function findFeatureSources(fs: any, tmfolder: string, available: string[]): Fea
 }
 
 
-// Turn discovered sources into path patterns for a jostraca `Copy` exclude.
-//
-// jostraca tests each candidate against the path built up during its walk,
-// which carries the enclosing node path as a prefix — so anchor on a
-// segment boundary at both ends rather than on the whole string. A folder
-// source matches everything beneath it; a file source matches only itself.
 function featureExcludes(sources: FeatureSource[]): RegExp[] {
   return sources.map((s) => new RegExp(
     '(^|/)' + s.path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + (s.folder ? '/' : '$')
@@ -223,12 +133,6 @@ function featureExcludes(sources: FeatureSource[]): RegExp[] {
 }
 
 
-// Path patterns for templates that only compile with the COMPLETE feature
-// set — see `feature.fullset` in each target's model. These are the
-// cross-feature test suites: one file per target that constructs every
-// shipped feature type by name (`feature.NewRetryFeature`,
-// `RUSTCRATE::feature::retry::RetryFeature`, ...). Trimming the feature set
-// without dropping them leaves a project that will not compile.
 function fullsetExcludes(paths: string[]): RegExp[] {
   return (paths || []).map((p) => new RegExp(
     '(^|/)' + String(p).replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '$'
@@ -236,16 +140,6 @@ function fullsetExcludes(paths: string[]): RegExp[] {
 }
 
 
-// Generate-time guard for the `src/feature/<name>/` layout (ts, js).
-//
-// Root renders one Feature component per ACTIVE feature, but Main then
-// copies the whole `tm/<lang>` tree — which puts a deactivated feature's
-// source straight back, silently undoing the filter. `target add` keeps
-// deactivated features out of `tm` in the first place; this covers the case
-// where a feature is switched off AFTER it was added.
-//
-// Only declared-but-inactive features are excluded. `base` and anything else
-// the model never mentions is left alone.
 function srcFeatureExcludes(model: any): RegExp[] {
   const all = getModelPath(model, `main.${KIT}.feature`,
     { required: false, only_active: false }) || {}
@@ -260,45 +154,11 @@ function srcFeatureExcludes(model: any): RegExp[] {
 }
 
 
-// The same rule as srcFeatureExcludes, ONE LEVEL DEEPER: a feature's
-// declared-but-inactive PLUGINS.
-//
-// A plugin is a feature's optional part — the `secrets` feature over
-// sekreto has one per provider kind, and each carries its own platform
-// cost (node:crypto for AWS request signing, fetch for seven HTTP vault
-// clients). A project whose chain is `[dotenv, env]` should carry neither,
-// and before the plugin trim it carried both, because every kind was
-// reachable from a single import.
-//
-// Layout is `src/feature/<feature>/plugin/<plugin>/`, so a plugin's tree
-// is excluded exactly as a feature's is. Only declared-but-inactive
-// plugins are excluded: a directory the model never mentions is left
-// alone, matching srcFeatureExcludes' treatment of `base`.
-//
-// Note this trims a plugin belonging to an ACTIVE feature. An inactive
-// feature's whole tree — plugins included — is already gone via
-// srcFeatureExcludes, so walking its plugins here would be redundant, and
-// asking the model for them would fail on the `only_active` filter anyway.
-// One feature's inactive-plugin patterns.
-//
-// Separate from pluginExcludes(model) because the two COPIES that need it
-// see different things: Main copies the whole target tree and has the
-// model, while the Feature component copies one feature's tree and has
-// only that feature. Feature's copy is the one that actually matters —
-// it runs for every ACTIVE feature, so without this an active feature's
-// plugins were all copied regardless, and Main's exclude never saw them.
 function pluginExcludesFor(model: any, fname: string): RegExp[] {
   if (null == model || null == fname) {
     return []
   }
 
-  // `only_active: false`, and this is the whole subtlety. The feature
-  // object a component is handed has ALREADY been filtered, so its
-  // `plugin` map contains only the ACTIVE plugins — and a function looking
-  // there for something inactive finds nothing and excludes nothing. That
-  // is exactly the trap srcFeatureExcludes documents, hit again one level
-  // down: the first cut of this read the filtered feature and silently
-  // trimmed nothing while every test passed.
   const plugins = getModelPath(model,
     `main.${KIT}.feature.${fname}.plugin`,
     { required: false, only_active: false }) || {}
@@ -314,18 +174,6 @@ function pluginExcludesFor(model: any, fname: string): RegExp[] {
 
     if (0 < declared.length) {
       for (const one of declared) {
-        // FEATURE-RELATIVE, because jostraca tests a Copy's candidates
-        // against the path RELATIVE TO THAT COPY'S ROOT — `sekreto/
-        // provider/aws.ts`, not `src/feature/secrets/sekreto/provider/
-        // aws.ts`. The Feature component's Copy is rooted at
-        // `tm/<target>/src/feature/<feature>`, so a full declared path
-        // never matches and the trim silently does nothing.
-        //
-        // Worth stating because it is invisible: an exclude that matches
-        // nothing is indistinguishable from no exclude at all, and both
-        // the patterns and the model were correct while nothing was
-        // trimmed. Main's copy IS rooted at the target root, which is why
-        // pluginExcludes below keeps the full path.
         const rel = String(one).replace(
           new RegExp('^src/feature/' + esc(fname) + '/'), '')
         const pat = esc(rel)

package/src/helpers/getMatchEntries.ts

@@ -1,7 +1,3 @@
-// Return the user-facing entries of a flow step's `match` object. Keys ending
-// in `$` are jostraca/aontu metadata sentinels and are skipped.
-//
-// Identical helper was previously inlined in TestEntity_*.ts and TestDirect_*.ts.
 
 function getMatchEntries(step: any): [string, any][] {
   if (!step?.match) return []

package/src/helpers/junk.ts

@@ -1,59 +1,13 @@
-// WHAT NEVER COUNTS AS CONTENT.
-//
-// Every tree sdkgen reads — the scaffold's `tm/<lang>` and `src/cmp/<lang>`, an
-// external package's `.sdk`, a project's own copies of both — is a DIRECTORY ON
-// A DEVELOPER'S MACHINE, and a developer's machine drops things in directories:
-// `.DS_Store` from the Finder, `__pycache__` from running a python module,
-// `node_modules` from an `npm install` in the wrong shell, a `~` backup from an
-// editor. None of it is authored, none of it is tracked (it is all gitignored),
-// and all of it is invisible in `git status` — so the first thing that notices
-// is whatever compares two trees.
-//
-// It bit as: a stray `tm/py/utility/__pycache__/make_options.cpython-314.pyc`,
-// created in August by running that module in place, copied verbatim by
-// `target add py` into the add output, and reported by the golden-manifest test
-// as toolchain drift. The copy is the real problem — the test only saw it. Left
-// alone, that `.pyc` ships into every consumer's SDK repo, compiled against
-// whatever python the maintainer happened to have.
-//
-// The rule is one list, in one place, applied by everything that walks a tree:
-// the WRITER (jostraca's Copy, through `cmp.Copy.ignore`, plus the two walks
-// target-add does itself) and every READER that compares against what the
-// writer produced (doctor's drift walk, the feature-source scan, the definition
-// listing). A writer and a reader that disagree about what counts report the
-// whole tree as a fork — the same discipline `templateReplacements` and
-// `aliasCmpName` are held to, and for the same reason.
-//
-// MEMBERSHIP IS A PROMISE that no template will ever legitimately carry that
-// name, so this list holds only what a TOOL creates and a person does not: no
-// `build`, `dist`, `bin` or `out` (a template may well ship one), and
-// emphatically no `target` — sdkgen's own model directory is called that, and
-// it is also where cargo and maven put their output. `test/junk.test.ts` checks
-// the list against every name in the shipped scaffold, so an over-broad pattern
-// fails there rather than by silently dropping a file from someone's SDK.
-
-// All of these are matched against the BARE NAME of a directory entry, not its
-// path — the same way jostraca's `cmp.Copy.ignore` is applied, so that naming a
-// directory prunes its whole subtree without every caller having to spell out
-// what is inside it.
-
-
-// Droppings that are not output of anything: an editor, the Finder, or a
-// version control system left them, and they occupy no space in the meaning of
-// the tree. Kept separate from BUILD because "would we copy this" and "is this
-// directory empty" are different questions, and only this half answers both —
-// a destination holding `node_modules` is not empty by any reading.
+
+
+
 const NOISE: RegExp[] = [
-  // Editors and merges. `~` duplicates jostraca's built-in `IGNORED_RE`,
-  // deliberately: that one governs its Copy walk alone, and the walks sdkgen
-  // does itself (the prune, the feature scan) have to agree with it.
-  /~$/,                 // editor backup
-  /^\.#/,               // emacs lock link
-  /^#.*#$/,             // emacs autosave
-  /\.sw[a-p]$/,         // vim swap
-  /\.(bak|orig|rej)$/,  // backups, and what a conflicted merge leaves behind
-
-  // Operating systems.
+  /~$/,
+  /^\.#/,
+  /^#.*#$/,
+  /\.sw[a-p]$/,
+  /\.(bak|orig|rej)$/,
+
   /^\.DS_Store$/,
   /^__MACOSX$/,
   /^Thumbs\.db$/i,
@@ -64,13 +18,10 @@ const NOISE: RegExp[] = [
   /^\.git$/,
   /^\.svn$/,
   /^\.hg$/,
-  /^\.idea$/,           // not `.vscode` — an SDK may ship editor settings
+  /^\.idea$/,
 ]
 
 
-// Toolchain output, per language. Each of these appears exactly when someone
-// runs that language's tools inside a template tree, which is the normal way to
-// check that a template actually works — and none of them is ever the payload.
 const BUILD: RegExp[] = [
   /^node_modules$/,
   /^__pycache__$/,
@@ -83,11 +34,11 @@ const BUILD: RegExp[] = [
   /^\.dart_tool$/,
   /^\.?zig-cache$/,
   /^zig-out$/,
-  /^_build$/,           // mix, dune
+  /^_build$/,
   /^\.elixir_ls$/,
-  /^\.cpcache$/,        // clojure
+  /^\.cpcache$/,
   /^\.stack-work$/,
-  /^dist-newstyle$/,    // cabal
+  /^dist-newstyle$/,
   /^\.cargo$/,
 ]
 
@@ -95,14 +46,11 @@ const BUILD: RegExp[] = [
 const JUNK: RegExp[] = [...NOISE, ...BUILD]
 
 
-// Is this directory entry something no tree operation should see?
 function isJunk(name: string): boolean {
   return matches(name, JUNK)
 }
 
 
-// Weaker: does this entry leave a directory as good as empty? Toolchain output
-// does NOT — it is junk to copy and content to find.
 function isNoise(name: string): boolean {
   return matches(name, NOISE)
 }
@@ -125,30 +73,6 @@ function matches(name: string, patterns: RegExp[]): boolean {
 }
 
 
-// The jostraca `cmp` option block, which is how the WRITER side of the rule is
-// applied: jostraca tests `cmp.Copy.ignore` against the bare name of every
-// entry it walks, directories included, and prunes what matches.
-//
-// Passed PER CALL by each action, not left to the Jostraca instance — the same
-// discipline `control.dryrun` is held to, and for a related reason: the actions
-// take whatever instance their caller hands them (`actx.jostraca`), and a
-// consumer that builds its own would otherwise silently lose the filter. A
-// per-call value is merged last and wins.
-//
-// `/~$/` is first, and must stay first while any supported jostraca is at or
-// below 0.31.0. That merge takes this list over its own default of `[/~$/]`
-// with `deep()`, which recursed INTO index 0 — two RegExps are both objects, so
-// it iterated the incoming one's enumerable properties, of which a RegExp has
-// none, and kept the default. Whatever sat at index 0 was silently discarded.
-// Leading with the value already there makes that a no-op instead of a hole,
-// and jostraca's built-in `IGNORED_RE` covers `~` anyway.
-//
-// FIXED UPSTREAM (jostraca `deep` now replaces a custom-constructor value
-// rather than walking into it), so this is compatibility, not a live
-// workaround: harmless on a fixed jostraca, load-bearing on an older one.
-//
-// A FRESH object each call: `deep` mutates its base, and jostraca's merge order
-// leaves these values reachable from options it keeps.
 function copyOpts(): { Copy: { ignore: RegExp[] } } {
   return {
     Copy: {

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