@voxgig/sdkgen 4.20.0 → 4.22.0

package/dist/action/kind.js

@@ -11,27 +11,6 @@ exports.kindDef = kindDef;
 exports.resolveKind = resolveKind;
 exports.kindModel = kindModel;
 exports.kindIndex = kindIndex;
-// KINDS: the things an `add` can install.
-//
-// `target` and `feature` are two of them, `docs` and others are meant to
-// follow (docs/design/sdkgen-packages.md §8). They were two hand-written
-// pipelines that had already drifted apart — only one took path refs, only
-// one applied a replace map, only one recorded provenance — and a third kind
-// would have been a third copy of the same drift.
-//
-// What every kind shares is declared here and executed once:
-//
-//   - the ref grammar and resolution, including the fallback to what the
-//     model already records for a bare name;
-//   - whether the kind may be installed under a different name (`~alias`);
-//   - the definition file: `model/<kind>/<name>.aon`, stamped with
-//     provenance and landing under the INSTALLED name;
-//   - the include list: `model/<kind>/<kind>-index.aon`.
-//
-// What a kind adds on top — a target's component and template trees, a
-// feature's per-target source fan-out — stays in that kind's own action. Those
-// are genuinely different work, not the same work with different strings, and
-// pretending otherwise would buy generality nobody can use.
 const node_path_1 = __importDefault(require("node:path"));
 const jostraca_1 = require("jostraca");
 const utility_1 = require("../utility");
@@ -40,32 +19,6 @@ const resolve_1 = require("./resolve");
 Object.defineProperty(exports, "recordedRef", { enumerable: true, get: function () { return resolve_1.recordedRef; } });
 Object.defineProperty(exports, "isBare", { enumerable: true, get: function () { return resolve_1.isBare; } });
 const action_1 = require("./action");
-// Rewrite the ITEM KEY in a copied model file, for an aliased install.
-//
-// Parameterised by kind because `main: kit: doc: edition: <n>:` is the same rewrite
-// with a different word, and a second copy of this regex is exactly the
-// same-rule-written-twice defect the registry exists to prevent.
-//
-// Two forms are in use across the shipped models — bare (`target: go:`) and
-// quoted (`target: 'go-cli':`) — and two paths carry the key: the item
-// block itself (`main: kit: target: <t>:`) and the per-target feature-deps
-// slot every target model declares
-// (`main: kit: feature: &: target: <t>: deps: &:`). Both belong to the
-// installed item, so both move. Matching on `<kind>: ` rather than on the
-// bare name is what keeps the rewrite off the item's own values — `ext: go`
-// and `module: name: '$$name$$'` must not change.
-//
-// ONE regex, with the quote optional and captured, rather than two entries in
-// jostraca's `replace` map: that map canonicalises each key into a regex
-// group NAME, and the bare and quoted spellings of the same key reduce to the
-// same name — so one silently overwrote the other and `go-cli~cli2` came out
-// as the BARE `target: cli2:`, losing the quoting a hyphenated key needs.
-//
-// The alias may also NEED quoting when the origin did not: aontu rejects a
-// bare key containing a hyphen (`unexpected character(s): -`), so
-// `target add go~go-alt` emitting the origin's unquoted style produced a
-// model that could not compile at all. Quote when the origin was quoted OR
-// the alias is not a bare identifier.
 const BARE_KEY_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
 function aliasModelKey(kind) {
     return function aliasModelText(src, origname, name) {
@@ -92,17 +45,6 @@ const KINDS = Object.assign(Object.create(null), {
         ],
     },
     feature: { name: 'feature', alias: false },
-    // DOCS — the third kind. See docs/design/sdkgen-packages.md §20.
-    //
-    // Its trees are NESTED under the kind name (`src/cmp/edition/<n>`, not
-    // `src/cmp/<n>`) so a docs item and a target may share a name without
-    // sharing a directory. Everything that composes those paths takes them
-    // from here.
-    //
-    // `tm/edition/{name}` is NOT required: a docs item whose every emitted byte
-    // depends on the API — a catalogue entry, a config file — legitimately
-    // ships no template tree, while a static site needs one. So it is
-    // copy-if-present, and `package check` does not demand it.
     edition: {
         name: 'edition', alias: true, ownedWhenAliased: true,
         rename: aliasModelKey('edition'),
@@ -113,10 +55,6 @@ const KINDS = Object.assign(Object.create(null), {
     },
 });
 exports.KINDS = KINDS;
-// The trees a kind's add copies, with `{name}` resolved. ONE composition of
-// these paths, read by the add, by doctor's drift walk and (through
-// `requires`) by manifest validation — three readers that must agree about
-// where an item's content lives, and previously would each have spelled it.
 function kindTrees(kind, name) {
     return (kindDef(kind).trees ?? []).map((t) => ({
         ...t,
@@ -130,55 +68,20 @@ function kindDef(kind) {
     }
     return def;
 }
-// Resolve one ref for a kind, applying that kind's alias policy.
-//
-// A BARE name resolves against what the model already RECORDS. Without that,
-// provenance would be write-only: the add actions re-run with the model's own
-// keys (`circuitbreaker`, not the ref it was installed from), a bare name
-// falls back to the bundled scaffold — whose `.sdk` folder exists, so
-// resolution SUCCEEDS — and the copy then throws on a definition that is not
-// there. An explicit ref always wins: that is how something is moved to a new
-// source.
 function resolveKind(ref, kind, ctx$) {
     const def = kindDef(kind);
     const source = (0, resolve_1.resolveSource)(ref, kind, ctx$);
-    // Asked of the RESOLVER rather than by re-reading the ref. `~` separates an
-    // alias only in the last segment, and a check that looked for one anywhere
-    // rejected every ref whose PATH contains a tilde — a Windows 8.3 short name
-    // like `C:\Users\RUNNER~1\...` is one. Parsing the ref in two places is what
-    // let that defect come back after it was fixed.
     if (!def.alias && source.name !== source.origname) {
         throw new utility_1.SdkGenError(capitalise(kind) + ' aliasing is not supported: ' + ref +
             '\n  A ' + kind + ' name is part of the generated config ' +
             '(options.' + kind + '.<name>) and of the hook wiring in every target, ' +
             'so it cannot be renamed at install time.');
     }
-    // The DEFINITION has to be there, not just the folder that would hold it.
-    //
-    // Resolution stops at the `.sdk` folder, and a bare name resolves to the
-    // bundled scaffold — whose folder always exists — so a name with no
-    // definition anywhere resolved "successfully" and then failed much later
-    // inside jostraca's Copy, as a shape validation error naming a path the
-    // caller never wrote.
-    //
-    // Where that bites is the fan-out: `target add` re-runs `feature add` for
-    // every feature key in the model, and a key with no definition installed
-    // aborted the ENTIRE target add — no templates, no components, nothing —
-    // over one feature. A plain Error, not an SdkGenError, so the fan-out's
-    // per-item guard skips it with a warning; the add path for an explicit ref
-    // does not catch, so `feature add nosuch` still fails, now saying what is
-    // actually missing.
     if (!ctx$.fs().existsSync(source.model)) {
         throw new Error(capitalise(kind) + ' definition not found: ' + source.model);
     }
     return source;
 }
-// Emit the kind's definition file and its index entry.
-//
-// Called inside a `Folder({ name: 'model/<kind>' })`, so both land together.
-// `names` is every INSTALLED name seen so far in this run: the index File is
-// re-rendered per item and the last render wins, so each render has to carry
-// all of them.
 function kindModel(props) {
     const { ctx$, kind, source } = props;
     const def = kindDef(kind);
@@ -192,15 +95,6 @@ function kindModel(props) {
         package: source.package,
     });
     if (aliased) {
-        // The copy lands under the INSTALLED name AND declares it. Left alone it
-        // kept the origin basename (jostraca defaults a single-file Copy's
-        // destination to the source's), so the index named a file that does not
-        // exist — which fails the whole model compile, not just the alias.
-        //
-        // `exclude: true` — CREATE, never overwrite, for a kind whose aliased
-        // definition is project-owned: an alias exists to be differentiated,
-        // which is why doctor reports its diffs as informational and why
-        // add-a-target tells the project to edit it.
         const owned = true === def.ownedWhenAliased;
         if (owned) {
             const dest = node_path_1.default.join(ctx$.folder ?? '.', 'model', kind, source.name + '.aon');
@@ -221,20 +115,6 @@ function kindModel(props) {
         (0, jostraca_1.Copy)({ from: source.model, replace });
     }
 }
-// The kind's include list, emitted ONCE for the whole run.
-//
-// This used to live at the end of kindModel, which is called per item, and the
-// comment there said so plainly: "the index File is re-rendered per item and
-// the last render wins, so each render has to carry all of them". jostraca
-// 0.38 added a duplicate-output-path check and now refuses that outright:
-//
-//   two File components resolve to the same output path,
-//   path=/out/model/feature/feature-index.aon
-//
-// Last-write-wins was never the intent, only the mechanism. Installing three
-// features rendered the index three times to write it once. Emitting it after
-// the loop, with the complete name list, produces the same file from one File
-// component and says what it means.
 function kindIndex(props) {
     const { kind, names, content } = props;
     (0, jostraca_1.File)({ name: kindDef(kind).name + '-index.aon' }, () => (0, action_1.UpdateIndex)({
@@ -242,18 +122,6 @@ function kindIndex(props) {
         names,
     }));
 }
-// The ref that reinstalls what the model already records — `base` says which
-// `.sdk` folder, `origname` says what it is called there.
-//
-// The ALIAS has to be carried back through. Rebuilding only `<base>/../<orig>`
-// resolves to the ORIGIN name, so `target add go2` (after installing
-// `go~go2`) would refresh and index a new `go` target and leave `go2` stale —
-// losing the differentiated identity the alias exists for, and the
-// project-owned model file with it.
-//
-// ONE definition, used by the add actions and by doctor. This reconstruction
-// was written twice and the two copies had already diverged on exactly this
-// point, which is the drift the kind spine exists to end.
 function capitalise(s) {
     return s.charAt(0).toUpperCase() + s.slice(1);
 }

package/dist/action/kind.js.map

@@ -1 +1 @@
-{"version":3,"file":"kind.js","sourceRoot":"","sources":["../../src/action/kind.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kind.js","sourceRoot":"","sources":["../../src/action/kind.ts"],"names":[],"mappings":"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"}

package/dist/action/package.js

@@ -13,32 +13,6 @@ exports.selectItems = selectItems;
 exports.parseAliases = parseAliases;
 exports.registerAdder = registerAdder;
 const kindCollection_1 = require("../helpers/kindCollection");
-// `package add` / `package list` — the whole-package verbs.
-//
-// See docs/design/sdkgen-packages.md §9.
-//
-// WHAT `package add` IS
-//
-// Not a new copy pipeline. It resolves a package ROOT, validates its manifest,
-// and then runs the SAME per-kind add that `target add` / `feature add` run,
-// once per provided item. Index handling, provenance stamping, feature
-// fan-out, dry run and logging all come along unchanged, because they are not
-// reimplemented. The value it adds over typing the individual adds is:
-//
-//   - the manifest is REQUIRED and validated first, so a package that lies
-//     about what it provides fails before anything is written rather than
-//     halfway through;
-//   - the engine range is checked once, for the package, rather than never;
-//   - ordering: targets before features, because `feature add` fans a
-//     feature's source out across the targets already in the model, so a
-//     feature installed first would find none of the package's own targets.
-//
-// WHY VALIDATION COMES FIRST, ALL OF IT
-//
-// The items are installed in a loop. If the fourth one turns out not to be in
-// the package, the first three are already written and the project is left
-// half-installed with a partial index. Validating the whole claim up front is
-// what makes the loop safe to run at all.
 const node_path_1 = __importDefault(require("node:path"));
 const types_1 = require("../types");
 const utility_1 = require("../utility");
@@ -54,18 +28,6 @@ const CMD_MAP = Object.assign(Object.create(null), {
     list: cmd_package_list,
     update: cmd_package_update,
 });
-// The kinds `package add` installs, IN ORDER.
-//
-// Targets first. `feature add` copies a feature's per-target source into every
-// target already in the model, so a feature installed before the package's own
-// targets would silently ship no source for them — the `feature-source-missing`
-// warning, once per target, and a feature that does nothing.
-//
-// Docs LAST, for the mirror-image reason: a docs item is ABOUT the targets and
-// features a project has (a page per SDK, a page per feature), and while it
-// reads them at generate time rather than at add time, installing it last
-// keeps the add log in the order a reader would expect and leaves the model
-// complete before anything reads it.
 const ADD_ORDER = ['target', 'feature', 'edition'];
 async function action_package(args, actx) {
     const cmdname = args[1];
@@ -83,10 +45,6 @@ function resolvePackage(ref, actx) {
             search.join('\n    '));
     }
     const { root, sdk, read } = found;
-    // A `.sdk` folder with no manifest is a legal source for a DIRECT ref and
-    // is what every pre-manifest fixture is — but `package add` is the verb
-    // that acts on a manifest, so here its absence is the error, and it says
-    // which of the two commands the user wants.
     if (null == read.manifest) {
         throw new utility_1.SdkGenError('No package manifest: ' + read.file +
             (null == read.err ? '' : '\n  ' + read.err) +
@@ -115,12 +73,6 @@ function refuse(src, found, log) {
         node_path_1.default.join(src.root, manifest_1.MANIFEST) + ')\n  ' +
         errors.map((f) => f.note).join('\n  '));
 }
-// Is this generator new enough for the package?
-//
-// `undefined` from `satisfies` means the range is outside the subset it
-// understands — see helpers/semver. That is reported and ALLOWED: refusing on
-// a range nobody could parse would block a package that works, which is worse
-// than the incompatibility being guarded against.
 function checkEngine(src, actx) {
     const range = src.manifest.engines?.sdkgen;
     if (null == range || '' === range) {
@@ -154,21 +106,8 @@ const SDKGEN_VERSION = (() => {
     }
 })();
 exports.SDKGEN_VERSION = SDKGEN_VERSION;
-// The items to install, as `<kind>` -> names, after `--only` is applied.
-//
-// `--only target:iot-go,feature:circuitbreaker` — a subset of what the
-// manifest provides, named the same way the manifest keys them. A name that
-// the package does not provide is an ERROR listing what it does, rather than
-// a silent no-op: a typo'd `--only` that installed nothing and reported
-// success is the failure this whole verb exists to remove.
 function selectItems(src, only, log) {
     const provides = src.manifest.provides ?? {};
-    // ABSENT means "everything"; EXPLICITLY EMPTY does not.
-    //
-    // `--only=` and `{ only: '' }` are what a script gets when it builds the
-    // flag from an empty variable, and treating that as absent installs the
-    // whole package — the opposite of what the operator asked for, at the one
-    // moment nobody is watching.
     if (null == only) {
         return provides;
     }
@@ -208,10 +147,6 @@ function describeProvides(provides) {
     }
     return 0 === parts.length ? '(nothing)' : parts.join(', ');
 }
-// `--alias iot-go=acme-go,other=thing` — the install-time renames, by ORIGIN
-// name. Only kinds that permit aliasing may appear; a feature alias is
-// refused here with the same explanation `feature add` gives, so the two
-// entry points cannot disagree about what is allowed.
 function parseAliases(alias, wanted) {
     // NULL-PROTOTYPE. A manifest may legally provide an item called
     // `constructor` or `toString` — the name grammar admits them — and on a
@@ -230,13 +165,6 @@ function parseAliases(alias, wanted) {
         }
         const from = spec.slice(0, eq);
         const to = spec.slice(eq + 1);
-        // Checked HERE as well as in the resolver, because the two catch
-        // different things. The resolver sees whatever survives ref parsing, so
-        // it catches `iotgo=..`; but `iotgo=../../elsewhere` is concatenated into
-        // `<root>/iotgo~../../elsewhere`, whose last segment is `elsewhere` and
-        // which therefore stops looking like an alias at all — it resolves as a
-        // ref to a different item and fails confusingly instead. Same grammar in
-        // both places, so they cannot disagree about what a name is.
         if (!manifest_1.ITEM_NAME_RE.test(to)) {
             throw new utility_1.SdkGenError('Invalid alias in --alias ' + JSON.stringify(spec) + ': ' +
                 JSON.stringify(to) + ' is not a name (matching ' +
@@ -278,14 +206,6 @@ async function package_add(refs, actx) {
         throw new utility_1.SdkGenError('--only and --alias apply to a single package; ' + refs.length +
             ' were given: ' + refs.join(', '));
     }
-    // PREFLIGHT EVERY PACKAGE BEFORE INSTALLING ANY OF THEM.
-    //
-    // The same argument that makes this verb validate a manifest in full before
-    // writing anything applies across refs: `package add good,bad` that
-    // installed `good` and then failed would leave exactly the half-completed
-    // command the guarantee is about. Resolution, the engine gate, manifest
-    // validation, `--only` selection and the name-collision check all happen
-    // here, for all of them, before the first file is written.
     const plan = refs.map((ref) => plan_one(ref, flags, actx));
     checkCollisions(plan, actx);
     const results = [];
@@ -341,16 +261,6 @@ function plan_one(ref, flags, actx) {
     }
     return { src, wanted, items };
 }
-// Would any of this REPLACE something the project got from elsewhere?
-//
-// `add` is overwrite, deliberately — that is how a resync works. But
-// overwriting one package's `go` with a different package's `go` is not a
-// resync: it silently replaces a working target's model, components and
-// templates. The project asked for a package, not for that.
-//
-// Checked across the WHOLE plan, so two packages in one command claiming the
-// same name are caught too — the second would otherwise conflict with nothing,
-// because the first is not installed yet either.
 function checkCollisions(plan, actx) {
     const claimed = new Map();
     const clashes = [];
@@ -405,56 +315,12 @@ const ADDERS = Object.create(null);
 function registerAdder(kind, add) {
     ADDERS[kind] = add;
 }
-// The adder for a kind, LOADING THE REGISTRATIONS IF NOBODY HAS YET.
-//
-// `dispatch` is what calls `registerAdder`, and until this, whether it had
-// been loaded depended on the importer: `sdkgen.ts` pulls it in, so the CLI
-// worked, but anything importing this module directly got an empty table —
-// and `package add` / `package update` then skipped every item with a
-// `package-kind-unsupported` warning and reported success. It silently did
-// nothing.
-//
-// Found the hard way: a throwaway script written to reproduce a review
-// finding imported this module alone, and the "update" it performed was a
-// no-op that looked like a passing result. A capability that depends on some
-// other module having been imported first is not a capability.
-//
-// Required lazily rather than at the top, because `dispatch` imports THIS
-// module; by call time the cycle has resolved.
 function adderFor(kind) {
     if (0 === Object.keys(ADDERS).length) {
         require('./dispatch');
     }
     return ADDERS[kind];
 }
-// `package update <pkg>` — refresh everything a package supplied.
-//
-// See docs/design/sdkgen-packages.md §13.
-//
-// THE ORDER IS THE SAFETY PROPERTY, which is why this command owns the fetch
-// instead of telling the operator to run `npm update` first:
-//
-//   1. CHECK the project's copies against the source AS CURRENTLY INSTALLED
-//   2. FETCH the new version
-//   3. RE-ADD each item
-//
-// Measured at step 1, a copy that differs from its source means the project
-// changed it. Run the other way round — fetch first, then check — every item
-// legitimately differs from the new source, the gate fires on all of them,
-// and the operator learns to pass `--force` every time. That ordering bug
-// would make the gate worse than useless, because the same signal (copy
-// differs from source) carries both meanings and only sequence separates
-// them.
-//
-// WHAT THE GATE CANNOT DO, and says so
-//
-// It cannot prove which meaning applies. If the operator already ran
-// `npm update` in another shell, step 1 is measuring against the NEW source
-// and a difference means "stale", not "forked" — and nothing recorded in the
-// project distinguishes the two. So the refusal states both readings and
-// gives a runnable out for each, rather than asserting a fork it cannot
-// diagnose. (A per-file digest recorded at add time would make it exact;
-// deferred, design §17.9.)
 async function cmd_package_update(args, actx) {
     const names = args.slice(2).flatMap((a) => 'string' === typeof a ? a.split(',') : a)
         .filter((r) => null != r && '' !== r);
@@ -464,13 +330,6 @@ async function cmd_package_update(args, actx) {
     }
     return package_update(names, actx);
 }
-// Everything the model says came from `pkgname`.
-//
-// By RECORDED PROVENANCE, not by asking the package what it provides: what
-// this refreshes is what the project actually installed, which may be a
-// subset (`--only`) or carry aliases the package never mentions. Asking the
-// package would refresh things the project does not have and miss the ones it
-// renamed.
 function installedFrom(pkgname, actx) {
     const kit = actx.model?.main?.[types_1.KIT] ?? {};
     const found = [];
@@ -537,21 +396,6 @@ async function package_update(names, actx) {
     }
     return { jres: results[results.length - 1]?.jres };
 }
-// EVERYTHING THE RE-ADD WILL WRITE, not just the package's own items.
-//
-// The gate is only worth having if it covers what step 3 actually touches,
-// and step 3 touches more than it is asked to: `target_add` re-runs
-// `feature_add` for EVERY active feature in the model, whoever supplied it.
-// So updating a target package rewrites the model file of a feature that came
-// from somewhere else — and a scope of "this package's items" never looked at
-// it, so a local edit there was overwritten without `--force`, by the command
-// whose whole promise is that it asks first.
-//
-// The features are added to the scope, not the fan-out narrowed: what the
-// re-add does is `target add`'s long-standing behaviour, and changing it here
-// would make `package update` write something different from what a
-// hand-typed add writes — the equivalence every other part of this verb is
-// built on.
 function blastRadius(installed, actx) {
     const wanted = new Set(installed.map((i) => i.kind + ':' + i.name));
     if (!installed.some((i) => 'target' === i.kind)) {
@@ -575,10 +419,6 @@ async function preCheck(pkgname, installed, actx) {
     const wanted = blastRadius(installed, actx);
     const res = await (0, doctor_1.doctor)(actx, (kind, name) => wanted.has(kind + ':' + name));
     const report = res.report;
-    // `forked` and `edited` only. `missing` means the project is short of what
-    // add would write, which an update FIXES; `resyncPending` is provenance
-    // catching up, which an update also fixes; `aliasedDiff` is the project's
-    // own differentiation of an alias, which step 3 does not touch anyway.
     const changed = [...report.forked, ...report.edited];
     if (0 === changed.length) {
         return;
@@ -604,13 +444,6 @@ async function preCheck(pkgname, installed, actx) {
         '\n  If you did: reinstall the version you had, re-run this command, ' +
         'and it will check against the right source.');
 }
-// STEP 2: fetch. Injectable, so tests do not shell out and a caller with its
-// own dependency management can supply one.
-//
-// `--no-fetch` covers the operator who has already fetched deliberately and
-// accepts that step 1 measured against the new source. It is not the default
-// because then this command would only ever re-apply the source it already
-// has, which is `package add`.
 async function fetchPackage(pkgname, installed, actx) {
     const flags = actx.flags ?? {};
     if (true === flags.nofetch) {
@@ -620,13 +453,6 @@ async function fetchPackage(pkgname, installed, actx) {
         });
         return;
     }
-    // A DRY RUN MUST NOT FETCH. The adders honour `actx.opts.dryrun` and write
-    // nothing, but an unconditional `npm install --save-dev` rewrites
-    // package.json, the lockfile and node_modules — mutating dependency state
-    // in the one mode whose entire promise is that nothing changes. This
-    // workstream has already fixed one dry-run defect (pruneStaleTemplates
-    // deleting files during a dry run); the fetch is the same failure in a
-    // louder place, because it reaches outside the project.
     if (true === actx.opts?.dryrun) {
         actx.log.info({
             point: 'package-update-dryrun-fetch', package: pkgname,
@@ -636,12 +462,6 @@ async function fetchPackage(pkgname, installed, actx) {
         return;
     }
     const fetch = actx.fetchPackage ?? npmFetch;
-    // npm CAN ONLY UPDATE WHAT NPM INSTALLED. A package added by a local path
-    // or an absolute checkout records that base, and the re-add reads from it —
-    // so an `npm install` would write a fresh copy into `node_modules`, leave
-    // the recorded source untouched, and the command would then recopy the OLD
-    // content while reporting success and having changed the project's
-    // dependencies. Refused rather than half-done, naming the way to do it.
     if (null == actx.fetchPackage) {
         const local = installed.find((i) => '' !== i.base && !isNodeModules(i.base));
         if (null != local) {
@@ -662,12 +482,6 @@ function isNodeModules(base) {
     const norm = base.split(node_path_1.default.sep).join('/');
     return norm.startsWith('node_modules/') || norm.includes('/node_modules/');
 }
-// The default fetch: hand it to npm, in the project's own directory.
-//
-// SHELLING OUT IS DELIBERATE and is the one place this generator runs another
-// tool. The alternative — telling the operator to fetch first — is what makes
-// the pre-check unable to distinguish a fork from a stale copy, which is the
-// entire point of the ordering above.
 async function npmFetch(pkgname, actx) {
     const { execFile } = require('node:child_process');
     const { promisify } = require('node:util');
@@ -678,18 +492,6 @@ async function npmFetch(pkgname, actx) {
         note: pkgname + ': npm install ' + pkgname + '@latest'
     });
     try {
-        // `npm.cmd` ON WINDOWS. `execFile` does no PATHEXT resolution, so plain
-        // `npm` — which is a `.cmd` shim there — fails with ENOENT. Not caught by
-        // CI, because every test injects its own fetcher and this function never
-        // runs; found by reading it rather than by it breaking.
-        //
-        // Arguments as an ARRAY and no `shell: true`, so a package name is never
-        // interpreted by a shell.
-        //
-        // maxBuffer raised well past execFile's 1MB default: `npm install` output
-        // for a large tree exceeds it, and the resulting ENOBUFS would be caught
-        // below and reported as a failed fetch — after npm had in fact SUCCEEDED,
-        // leaving the project's dependencies updated and its `.sdk` not.
         const out = await run('win32' === process.platform ? 'npm.cmd' : 'npm', ['install', '--save-dev', pkgname + '@latest'], { cwd, maxBuffer: 64 * 1024 * 1024 });
         actx.log.debug({
             point: 'package-update-fetched', package: pkgname,
@@ -703,17 +505,6 @@ async function npmFetch(pkgname, actx) {
             (null == err.stderr ? '' : '\n\n' + err.stderr));
     }
 }
-// STEP 2b: the fetched package is a DIFFERENT package from the one checked.
-//
-// Resolved from a recorded base rather than by name, because that is where
-// the re-add will read from — validating some other copy of the package would
-// be validating the wrong thing.
-//
-// A source with no manifest is not an error here, unlike in `package add`:
-// the project demonstrably installed from it once, and refusing to refresh it
-// now would strand a project whose package predates the manifest. Nothing is
-// validated in that case, which is the same amount as before this command
-// existed.
 function validateFetched(pkgname, installed, actx) {
     const base = installed.find((i) => '' !== i.base)?.base;
     if (null == base) {
@@ -735,14 +526,6 @@ function validateFetched(pkgname, installed, actx) {
     checkEngine(src, actx);
     refuse(src, (0, manifest_1.validateManifest)(actx.fs(), src.sdk, src.manifest, kind_1.KINDS), actx.log);
 }
-// STEP 3: re-add each item from its recorded base.
-//
-// An ALIASED item's model file is left alone, and that is not special-cased
-// here: `kindModel` already creates it `exclude: true` for a kind whose
-// aliased definition is project-owned, so a re-add refreshes `src/cmp` and
-// `tm` from the new origin and leaves the file the project is MEANT to edit
-// untouched. Reported, so the author knows to port upstream model changes by
-// hand rather than discovering later that they were never applied.
 async function reAdd(pkgname, installed, actx) {
     const log = actx.log;
     const results = [];
@@ -782,14 +565,10 @@ async function reAdd(pkgname, installed, actx) {
     }
     return results;
 }
-// `package list` — what this project has installed, and where each item came
-// from. Read entirely from the MODEL's recorded provenance (§4), which is why
-// there is no lockfile to consult and nothing that can disagree with it.
 async function cmd_package_list(_args, actx) {
     const log = actx.log;
     const fs = actx.fs();
     const kit = actx.model?.main?.[types_1.KIT] ?? {};
-    // package name -> kind -> [{name, base, origname}]
     const groups = Object.create(null);
     for (const kind of Object.keys(kind_1.KINDS).sort()) {
         const items = (0, kindCollection_1.kindCollection)({ main: { [types_1.KIT]: kit } }, kind);