@voxgig/sdkgen 4.21.0 → 4.23.0

package/src/helpers/dryrun.ts

@@ -1,11 +1,3 @@
-// Report what a dry run WOULD have done.
-//
-// `@voxgig/util`'s showChanges only lists merged and conflicted files, which
-// on a fresh `target add` is nothing at all — so `-y target add ts` printed
-// `** DRY RUN **`, listed no files, and (before the control fix) wrote them
-// anyway. A preview that shows nothing is indistinguishable from a preview of
-// nothing, which is exactly the wrong answer for the command whose whole job
-// is to overwrite a project's vendored scaffold.
 
 // Subset of jostraca's result: the per-outcome file lists.
 type FileLists = {

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,11 +1,7 @@
-// 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 []
-  return Object.entries(step.match).filter(([k]: any) => !k.endsWith('$'))
+  if (!step?.m) return []
+  return Object.entries(step.m).filter(([k]: any) => !k.endsWith('$'))
 }
 
 

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: {