@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/action/edition.ts

@@ -1,40 +1,4 @@
 import { kindCollection } from '../helpers/kindCollection'
-// `edition add <ref>` — the third kind. See edition/design/sdkgen-packages.md §20.
-//
-// WHAT A DOCS ITEM IS
-//
-// A generation target whose destination is a DOCUMENTATION SYSTEM rather than
-// a language: a static site, a developer-portal catalogue, a hosted service's
-// config. sdkgen ships the kind and no items; the items live in packages
-// (`@voxgig/docgen` first), which is what makes the destinations someone
-// else's business rather than a list this repo has to guess at.
-//
-// WHY IT IS NOT A TARGET
-//
-// Three reasons, argued in §20.2 and worth restating where the code is:
-//
-//   - a edition item's INPUT is the target collection — a page per SDK, the
-//     package table, per-language tabs — so a edition item inside
-//     `main.kit.target` would enumerate itself;
-//   - `action/feature.ts` fans out with `each(target, …)` and warns
-//     `feature-source-missing` per target with no source, so a edition item in
-//     that collection would collect one warning per feature, forever
-//     (`srcfeature: false` does not help — that flag is read at generate time
-//     and never by the add-time fan-out);
-//   - `ext`, `comment: line` and `module: name` are required, non-defaulted
-//     strings in the target spread, and a site emitting `.md`, `.yml`, `.css`
-//     and `.svg` at once has no honest value for `comment.line`.
-//
-// WHAT THIS ACTION DOES, AND WHAT IT DELIBERATELY DOES NOT
-//
-// It installs the definition — through the shared spine, so provenance,
-// aliasing and the index come along unchanged — and the kind's trees, whose
-// paths come from the registry rather than being spelled here.
-//
-// It does NOT fan out over targets, trim, or prune. A edition item reads the
-// target collection at GENERATE time, not at add time: the opposite direction
-// and the opposite moment from a feature's fan-out, so sharing that machinery
-// would have been a false economy.
 
 import { cmp, each, Copy, Folder, Project } from 'jostraca'
 
@@ -101,7 +65,6 @@ async function cmd_edition_add(
 }
 
 
-// Code API.
 async function edition_add(
   edition: string[], actx: ActionContext,
 ): Promise<ActionResult> {
@@ -115,20 +78,12 @@ async function edition_add(
     log: actx.log.child({ cmp: 'jostraca' }),
     meta: {
       url: actx.url,
-      // Seeded: no project scaffolded before the edition kind existed has a
-      // edition index, and every project alive today is in that position.
       content: loadContent(actx, 'edition', { edition: '# Docs\n' }),
     },
     model: actx.model,
-    // Per-call, never left to the Jostraca instance: `generate` runs its own
-    // options through OptionsShape first, which fills `control.dryrun: false`
-    // and would override the instance flag. The same trap target_add
-    // documents.
     control: {
       dryrun: !!actx.opts.dryrun
     },
-    // Per-call for the same reason, and covering the same accident: see
-    // helpers/junk.
     cmp: copyOpts(),
   }
 
@@ -137,26 +92,11 @@ async function edition_add(
     note: (actx.opts.dryrun ? '** DRY RUN **' : '')
   })
 
-  // PREFLIGHT, before a single file is written.
-  //
-  // The write pass emits the definition and its index entry before it copies
-  // the trees, so a ref whose definition exists but whose required components
-  // do not left the command failed AND the project carrying a edition item with
-  // no implementation — which the next model compile then reads as real.
-  // `package add` already validates a whole package up front for exactly this
-  // reason; a direct `edition add` needs the same guarantee.
   preflight(edition, actx)
 
-  // The project's own model must INCLUDE the edition index, or everything below
-  // is invisible: no project scaffolded before this kind existed includes it,
-  // and `main.kit.edition` would simply be absent from the next compile.
   ensureModelInclude(actx, 'edition')
 
-  // Into the IN-MEMORY model before anything reads it. Nothing recompiles
-  // `model/sdk.aontu` mid-process, so without this a second edition item in the
-  // same command — and anything else later in it — behaves as if the first
-  // was never installed. One definition of what gets recorded, shared with
-  // `target add` and `package add`.
+  // Later items in the command read this in-memory registration.
   registerInstalled('edition', edition, actx)
 
   const jres = await jostraca.generate(opts, () =>
@@ -166,9 +106,6 @@ async function edition_add(
 }
 
 
-// Resolve every ref and check every REQUIRED tree, throwing before anything
-// is written. Resolution itself is the other half: a ref that names no
-// definition fails here rather than partway through the pass.
 function preflight(edition: string[], actx: ActionContext) {
   const fs = actx.fs()
 
@@ -198,9 +135,6 @@ const EditionRoot = cmp(function EditionRoot(props: any) {
   const { log } = ctx$
 
   Project({}, () => {
-    // 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.
     const dnames: string[] = []
 
     each(edition, (n: any) => {
@@ -208,9 +142,6 @@ const EditionRoot = cmp(function EditionRoot(props: any) {
 
       log.info({ point: 'edition-build', edition: dref, note: dref })
 
-      // The shared spine: a BARE name resolves against what the model
-      // RECORDS, so a edition item installed from a package resolves back to
-      // that package on its next add rather than to the bundled scaffold.
       const source = resolveKind(dref, 'edition', ctx$)
 
       dnames.push(source.name)
@@ -237,15 +168,6 @@ const EditionRoot = cmp(function EditionRoot(props: any) {
       const from = kindTrees('edition', source.origname)
 
       dest.forEach((tree: TreeDef, i: number) => {
-        // Copy only ADDS and overwrites. A newer version of the package that
-        // RETIRED a template would leave the old one behind, generating from
-        // it forever — the failure `pruneStaleTemplates` exists for, and the
-        // reason 30 repos once carried a superseded harness file.
-        //
-        // Templates only, exactly as `target add` prunes only `tm`: extra
-        // files under a component tree are the project's own (doctor calls
-        // them `additive`, and adding a component is the supported way to
-        // extend an item), so pruning there would delete supported work.
         if ('template' === tree.replace) {
           pruneStaleTemplates(
             ctx$, source.folder + '/' + from[i].path, tree.path, [],
@@ -258,7 +180,6 @@ const EditionRoot = cmp(function EditionRoot(props: any) {
       log.info({ point: 'edition-done', edition: source.name, note: source.name })
     })
 
-    // ONCE, after the loop. See kindIndex.
     if (0 < dnames.length) {
       Folder({ name: 'model/edition' }, () => kindIndex({
         kind: 'edition', names: dnames,
@@ -292,12 +213,6 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
     return
   }
 
-  // An ALIASED component tree cannot be copied verbatim: components are
-  // dispatched by the convention `cmp/edition/<n>/Main_<n>`, so files keeping
-  // the origin suffix resolve nothing — `Main_summary.ts` is invisible to a
-  // lookup for `Main_portal`. Same rule as a target's, so the same function
-  // does it; jostraca's tree Copy has no per-entry rename hook, which is why
-  // an aliased tree is emitted file by file.
   if (source.name !== source.origname && 'none' === tree.replace) {
     aliasCmpTree(ctx$, from, tree.path, source.origname, source.name,
       cmpBase())
@@ -307,7 +222,6 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
   Folder({ name: tree.path }, () => {
     Copy({
       from,
-      // Shared with doctor, which re-applies them before comparing.
       ...('template' === tree.replace ?
         { replace: templateReplacements(ctx$.model, source.name) } : {}),
     })

package/src/action/feature.ts

@@ -92,13 +92,6 @@ async function feature_add(features: string[], actx: ActionContext): Promise<Act
       content: loadContent(actx, 'feature')
     },
     model: actx.model,
-    // Dry run must be passed per-call, not left to the Jostraca instance.
-    // jostraca's `generate` runs its own options through OptionsShape FIRST,
-    // which fills in `control.dryrun: false`, and only then merges
-    // `deep({}, gOpts.control, opts.control)` — so the shape default silently
-    // OVERRIDES the instance-level flag. `-y target add ts` printed
-    // ** DRY RUN ** and wrote every file. (Same trap as the `existing` FIX
-    // note in jostraca.js.)
     control: {
       dryrun: !!actx.opts.dryrun
     },
@@ -147,16 +140,7 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
 
     each(features, (n) => {
       const fref = n.val$
-      // TODO: validate feature is a-z0-9-_. only
-
-      // Resolution, the alias policy, and the bare-name fallback to what the
-      // model records are the same for every kind — see action/kind.
-      //
-      // A name that no longer resolves must not abort the RUN: `target add`
-      // re-runs this action for every active feature, so one feature whose
-      // source has moved (package uninstalled, checkout relocated) would
-      // otherwise stop every other feature — including `test`, which every
-      // generated target needs — from being copied at all.
+
       let source: any
       try {
         source = resolveKind(fref, 'feature', ctx$)
@@ -190,13 +174,6 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
         content: ctx$.meta.content.feature_index,
       }))
 
-      // Bring in the feature's source for every target already in the model.
-      // Where that source lives is language-specific — `src/feature/<name>/`
-      // for ts and js, `feature/<name>_feature.go` for go,
-      // `lib/feature/<name>/` for dart, and so on — so discover it in the
-      // target's template tree instead of assuming one layout. Assuming
-      // `src/feature/<name>` meant `feature add` silently added nothing for
-      // every target that keeps feature source elsewhere.
       each(target, (t) => {
         // The target's OWN tree, under the name it has in ITS source — an
         // aliased target's templates live at `tm/<origname>`, so searching
@@ -205,14 +182,6 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
         const torigname = t.origname || t.name
         const owntm = Path.join(sdkfolder, 'tm', torigname)
 
-        // Two places a feature's per-target source can live, in order:
-        // the FEATURE package's own overlay for this target, then the
-        // target's own tree. A feature shipped by one package for a target
-        // shipped by another has nowhere else to put it.
-        //
-        // First hit wins at DISCOVERY rather than by copy order: jostraca
-        // writes last-write-wins, so copying both would silently invert the
-        // precedence.
         const featuretm = Path.join(source.folder, 'tm', torigname)
         const overlay = featuretm === owntm ? [] :
           findFeatureSources(fs, featuretm, [fname])
@@ -220,13 +189,6 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
         const own = 0 < overlay.length ?
           findFeatureSources(fs, owntm, [fname]) : []
 
-        // Both trees carrying source for one feature means two packages claim
-        // the same name. The overlay wins, but the target's own files were
-        // already copied by `target add` and Copy never removes, so the
-        // project is left holding BOTH — duplicate symbols, or stale feature
-        // code that still runs. Detecting the name collision at add time is
-        // what actually fixes this (it belongs with manifest validation); say
-        // so loudly until then, rather than leaving a silent hybrid.
         if (0 < own.length) {
           log.warn({
             point: 'feature-source-shadowed', feature: fname, target: t.name,
@@ -261,13 +223,6 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
           Folder({ name: 'tm/' + t.name + '/' + dest }, () => {
             Copy({
               from: Path.join(tmfolder, source.path),
-              // The SAME map `target add` writes `tm/<t>` with. Without it
-              // this copy laid RAW template text over files the target add
-              // had already substituted, so `ProjectName` / `PROJECTVERSION`
-              // survived into the project depending only on which action
-              // wrote the file last — the writer/writer disagreement
-              // helpers/stdrep.ts exists to prevent, in the one place that
-              // did not share the map.
               replace: templateReplacements(model, t.name),
             })
           })
@@ -280,9 +235,6 @@ const FeatureRoot = cmp(function FeatureRoot(props: any) {
       })
     })
 
-    // ONCE, after the loop, with every name this run installed. Emitted inside
-    // kindModel it was one File component per feature on the same path, which
-    // jostraca 0.38 refuses.
     if (0 < fnames.length) {
       Folder({ name: 'model/feature' }, () => kindIndex({
         kind: 'feature', names: fnames,

package/src/action/kind.ts

@@ -1,25 +1,4 @@
 import { kindCollection } from '../helpers/kindCollection'
-// 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.
 
 
 import Path from 'node:path'
@@ -39,15 +18,8 @@ import { UpdateIndex } from './action'
 
 
 type KindDef = {
-  // The kind's name, which is also its model subdirectory and the prefix of
-  // its index file.
   name: string
 
-  // May it be installed under a different name? Targets yes — that is how a
-  // project gets two Go modules from one target. Features no: a feature's
-  // name is part of the generated `options.feature.<name>` config key and of
-  // the hook wiring in every target, so renaming one at install time is real
-  // work with no customer.
   alias: boolean
 
   // Rewrite the definition's own text when it is installed under a different
@@ -60,16 +32,6 @@ type KindDef = {
   // overwritten; everything else is toolchain-owned and resyncs.
   ownedWhenAliased?: boolean
 
-  // Everything BESIDES the definition file that an item of this kind must
-  // have in its package, `{name}`-templated and relative to the `.sdk`
-  // folder. `validateManifest` checks these, which is how a manifest claiming
-  // a target it does not ship fails at `package add` rather than partway
-  // through installing it.
-  //
-  // A feature has none: its definition is the whole of it. Its per-target
-  // SOURCE is deliberately not required — a feature package ships overlays
-  // only for the targets it supports, and `targetsSupported` is where that
-  // coverage is declared (design §7).
   trees?: TreeDef[]
 }
 
@@ -92,32 +54,6 @@ type TreeDef = {
 }
 
 
-// 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: string) {
@@ -156,17 +92,6 @@ const KINDS: Record<string, KindDef> = 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'),
@@ -178,10 +103,6 @@ const KINDS: Record<string, KindDef> = Object.assign(Object.create(null), {
 })
 
 
-// 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: string, name: string): TreeDef[] {
   return (kindDef(kind).trees ?? []).map((t: TreeDef) => ({
     ...t,
@@ -199,24 +120,10 @@ function kindDef(kind: string): KindDef {
 }
 
 
-// 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: string, kind: string, ctx$: any): Source {
   const def = kindDef(kind)
   const source = 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 SdkGenError(
       capitalise(kind) + ' aliasing is not supported: ' + ref +
@@ -225,21 +132,6 @@ function resolveKind(ref: string, kind: string, ctx$: any): Source {
       '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)
@@ -249,12 +141,6 @@ function resolveKind(ref: string, kind: string, ctx$: any): 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: {
   ctx$: any,
   kind: string,
@@ -277,15 +163,6 @@ function kindModel(props: {
   })
 
   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) {
@@ -315,20 +192,6 @@ function kindModel(props: {
 }
 
 
-// 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: {
   kind: string,
   names: string[],
@@ -342,18 +205,6 @@ function kindIndex(props: {
 }
 
 
-// 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: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1)
 }