@voxgig/sdkgen 4.21.0 → 4.23.0

package/project/.sdk/tm/ts/test/utility.ts

@@ -1,15 +1,8 @@
-/**
- * Shared utility functions for unit tests
- *
- * This module provides common helper functions used across unit tests
- * for creating test data, transformations, validations, and environment overrides.
- */
 
 import * as Fs from 'node:fs'
 import * as Path from 'node:path'
 
 
-// Creates a new step data structure within the data model
 function makeStepData(dm: Record<string, any>, stepname: string): Record<string, any> {
   dm.s[stepname] = {
     entity: undefined,
@@ -41,7 +34,6 @@ function makeReqdata(
 }
 
 
-// Validates data against validation rules and returns the result
 function makeValid(
   dm: Record<string, any>,
   validate: Function,
@@ -53,13 +45,10 @@ function makeValid(
 }
 
 
-// Creates a control object for test explanations when enabled
 function makeCtrl(explain: boolean) {
   return explain ? { explain: {} } : undefined
 }
-// CLAUDE: add a full stop to each function comment
 
-// Overrides configuration values with environment variables if available
 function envOverride(m: Record<string, any>) {
   if (
     'TRUE' === process.env.PROJECTENV_TEST_LIVE ||
@@ -167,35 +156,6 @@ function skipIfMissingIds(t: any, setup: any, requiredKeys: string[]): boolean {
 }
 
 
-// Extra SDK options every LIVE client is constructed with, from
-// sdk-test-control.json `test.client.options`.
-//
-// The generated live client knows two things: the base URL (from the spec)
-// and the credential (from the environment). Everything else about how a
-// particular API wants to be talked to — which features to switch on, and
-// with what settings — is a property of THAT API, known to the project and
-// to nothing in the toolchain.
-//
-// The concrete case: an API that issues short-lived access tokens needs the
-// `secrets` feature's exchange turned on and pointed at its token endpoint,
-// or the live suite gets a handful of calls in and then fails 401 with
-// nothing explaining why. There was no seam for that, so the suite could
-// not be run at all.
-//
-// A committed FILE rather than an environment variable, because it is
-// configuration, not a secret: it belongs in the repo next to the API it
-// describes, where it can be read and reviewed. Secrets still come from the
-// environment (the providers this block names read them).
-//
-// Merged UNDER the generated fields, so the suite's own base/apikey/server
-// values win — this adds to the live client, it does not redirect it.
-//
-// That contract is enforced HERE rather than left to each merge site: the
-// generated object only names a field when the model calls for one, so a
-// `base` in this block would face no competing value and would silently
-// redirect the whole suite — credential included — to another host. The
-// reserved fields are stripped once, where the block is read, so every
-// caller gets the same guarantee whether or not it happens to emit them.
 const LIVE_RESERVED = ['base', 'prefix', 'suffix', 'server', 'apikey', 'secret']
 
 function liveClientOptions(): Record<string, any> {
@@ -237,20 +197,6 @@ function liveDelay(liveEnvVar: string): () => Promise<void> {
 }
 
 
-// Load a .env.local file into process.env, replacing the `dotenv`
-// devDependency — the SDK's last non-tooling package.
-//
-// Same semantics dotenv gave these tests: a missing file is fine, and a key
-// already present in the environment is never overridden, so an explicit
-// export still beats the file.
-//
-// WHY NOT sekreto's parsedotenv, which does the same job and is already
-// vendored: sekreto lives INSIDE the secrets feature container, so `target
-// add` removes it whenever a project does not select that feature — while
-// these entity tests need the loader either way. Importing it here would
-// couple every generated test suite to an optional feature. The parser is
-// small enough that a second, independent copy is cheaper than that
-// coupling; it deliberately handles only what a .env.local holds.
 function loadEnvLocal(file: string): void {
   let text: string
   try {
@@ -266,7 +212,6 @@ function loadEnvLocal(file: string): void {
   for (const raw of text.split(/\r?\n/)) {
     const line = raw.trim()
 
-    // Blank and comment lines. A '#' INSIDE a value is not a comment.
     if ('' === line || line.startsWith('#')) {
       continue
     }

package/project/.sdk/tm/zig/feature/test.zig

@@ -109,15 +109,22 @@ fn envelope(ctx: *Context, data: Value) Value {
     const restf = h.getpath(&.{ "transform", "res" }, ctx.point);
     if (restf != .string) return data;
     const spec = restf.string;
-    // Exactly `body.<key>`; a deeper path is not an envelope this mock can
-    // synthesise, so it is left alone rather than guessed at.
+    // Rebuild whatever nesting the transform unwraps. Multi-segment on purpose:
+    // GraphQL ops unwrap `body.data.<field>`, not just one envelope property.
     if (spec.len < 8) return data;
     if (!std.mem.startsWith(u8, spec, "`body.")) return data;
     if (!std.mem.endsWith(u8, spec, "`")) return data;
     const inner = spec[6 .. spec.len - 1];
     if (inner.len == 0) return data;
-    if (std.mem.indexOfScalar(u8, inner, '.') != null) return data;
-    return h.jo(&.{.{ inner, data }});
+    var out = data;
+    var end: usize = inner.len;
+    while (true) {
+        const cut = std.mem.lastIndexOfScalar(u8, inner[0..end], '.');
+        const start = if (cut) |c| c + 1 else 0;
+        out = h.jo(&.{.{ inner[start..end], out }});
+        if (cut) |c| end = c else break;
+    }
+    return out;
 }
 
 fn respond(ctx: *Context, status: i64, data: Value, extra: []const h.Pair) Value {

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.21.0",
+  "version": "4.23.0",
   "provides": {
     "target": [
       "c",

package/src/action/action.ts

@@ -12,38 +12,9 @@ import type {
 } from '../types'
 
 
-// `./` — aontu 0.65 reads a bare single-segment include as a PACKAGE name
-// (ADR-039), so `@"go.aon"` resolves against the package stores and is
-// refused: "local files need a ./ prefix". A sibling file has to say so.
 const indexEntry = (name: string) => `@"./${name}.aon"`
 
 
-// An index line that is an ACTIVE include, and the name it includes — or
-// undefined for a blank line, a comment, or anything else.
-//
-// Parsed rather than compared as a string, because both spellings around an
-// include are legal aontu and mean opposite things:
-//
-//   @"./go.aon"               -> active, name 'go'
-//   @"go.aon"                 -> active, name 'go'  (pre-0.65 spelling)
-//   @"./go.aon"  # pinned     -> active, name 'go'  (trailing comment)
-//     @"./go.aon"             -> active, name 'go'  (indented)
-//   # @"./go.aon"             -> NOT active
-//
-// A substring test (what this used to be) reads the commented-out form as
-// present, so `target add go` on a project that had switched the target off
-// by hand appended nothing and reported success while the target stayed
-// absent from the model. A whole-line equality test fixes that but then
-// misses the trailing-comment form, and appends a SECOND active include.
-//
-// BOTH SPELLINGS, and the `./` is not part of the name. Every index in every
-// already-generated SDK carries the bare form, and those files are the
-// project's own -- they change when the project regenerates, not when sdkgen
-// releases. Reading only the new spelling would make `target add go` on any
-// existing repo believe `go` was absent and append a second include; reading
-// only the old one would do the same the other way round once the index is
-// rewritten. Capturing the name WITHOUT the prefix is what lets the two
-// spellings compare equal, which is the whole point.
 const INDEX_ENTRY_RE = /^\s*@"(?:\.\/)?([^"]+)\.aon"\s*(?:#.*)?$/
 
 function indexEntryName(line: string): string | undefined {
@@ -75,12 +46,6 @@ function appendIndexEntries(content: string, names: string[]): string {
 }
 
 
-// Drop the `@"<name>.aon"` line for each name — the inverse of
-// appendIndexEntries, matching line-exact for the same reasons.
-//
-// Nothing calls this yet: a `remove` action is the fast-follow this exists
-// for (see docs/design/sdkgen-packages.md), and it is written here beside its
-// inverse so the two cannot drift on how an entry is recognised.
 function removeIndexEntries(content: string, names: string[]): string {
   const drop = new Set(names)
 
@@ -99,10 +64,6 @@ const UpdateIndex = cmp(function UpdateIndex(props: any) {
 })
 
 
-// Names given to an `add` action: every positional after the subcommand is
-// a name, each possibly comma-separated — `target add ts,py,go` and
-// `target add ts py go` are equivalent (space-separated extras used to be
-// silently dropped).
 function parseAddNames(args: any[]): string[] {
   return args.slice(2)
     .flatMap((a: any) => 'string' === typeof a ? a.split(',') : a)
@@ -110,17 +71,6 @@ function parseAddNames(args: any[]): string[] {
 }
 
 
-// The current index file for each kind, which `UpdateIndex` appends to.
-//
-// `seed` IS THE UPGRADE PATH. A project scaffolded before a kind existed has
-// no `model/<kind>/<kind>-index.aon` — every project alive today is in
-// exactly that position for `docs` — and reading it unguarded made the FIRST
-// `edition add` in any existing project fail on ENOENT before it wrote anything.
-//
-// Seeded per call rather than defaulted for every kind: a missing
-// `target-index.aon` in a scaffolded project is a broken project, and
-// quietly recreating it would hide that. A kind the project has never used is
-// a different thing, and only its own action knows which case it is in.
 function loadContent(
   actx: ActionContext, which: string | string[], seed?: Record<string, string>,
 ) {
@@ -143,21 +93,6 @@ function loadContent(
 
 
 
-// ENSURE THE PROJECT'S OWN MODEL INCLUDES A KIND'S INDEX.
-//
-// `model/sdk.aontu` is written once, by create-sdkgen, and includes the
-// indexes of the kinds that existed then. So a project scaffolded before a
-// kind existed — which is every project alive today, for `docs` — never
-// includes its index, and the item's model file is an orphan: it is on disk,
-// `<kind>-index.aon` includes it, and NOTHING includes that. `main.kit.doc.edition`
-// is then absent from the compiled model, so `package list`, `package update`
-// and `doctor` cannot see the item at all.
-//
-// Appending one include line is additive and idempotent, and it is the only
-// way an existing project can adopt a new kind without hand-editing. The
-// entry is parsed, not substring-matched, for the reason `hasIndexEntry`
-// documents: a commented-out include means the project switched it OFF, and
-// re-adding it would override that.
 function ensureModelInclude(actx: ActionContext, kind: string): boolean {
   const fs = actx.fs()
   const url = actx.url

package/src/action/check.ts

@@ -1,37 +1,4 @@
 import { kindCollection } from '../helpers/kindCollection'
-// `package check` — the AUTHOR-side battery. Design §14.
-//
-// WHAT IT IS FOR
-//
-// Every other verb here acts on a project. This one acts on a PACKAGE, before
-// anyone installs it, and its whole value is moving a failure from the
-// consumer's build back to the author's terminal. The failures worth moving
-// are the ones a package cannot detect by using itself:
-//
-//   - a model file that compiles for the author and not for a consumer (the
-//     `//` comment asymmetry — seven shipped targets went out that way);
-//   - a key the base schema requires and the file omits, which nothing
-//     notices until a consumer unifies the whole model;
-//   - a key the PROJECT owns that the package pinned, which fails in the
-//     consumer's own file and reads as the consumer's mistake;
-//   - a manifest that disagrees with the disk, in either direction;
-//   - feature source the trim step will never recognise, so it ships to every
-//     project whatever the model selected.
-//
-// WHY IT REUSES EVERYTHING
-//
-// The battery asserts nothing of its own. Manifest agreement is
-// `validateManifest`, the trees a kind needs are the kind registry's
-// `requires`, the feature catalogue is `availableFeatures`, the source walk is
-// `findFeatureEntries`, the model rules are `helpers/modelcheck`. A check that
-// restated any of those would be a second copy of a rule the installer
-// already has — and this workstream's most repeated defect is exactly that,
-// two copies of one rule drifting apart. Where the check and the installer
-// disagree, the check is wrong by construction.
-//
-// NO MANIFEST IS NOT A REFUSAL. `package add` requires one; here its absence
-// is the first finding and the rest of the battery still runs, because an
-// author who has not written it yet is precisely who needs the rest.
 
 import { unknownTags, TAGS } from '../helpers/applicability'
 import Path from 'node:path'
@@ -75,23 +42,9 @@ import { scaffoldFolder } from '../helpers/shipped'
 import { KINDS } from './kind'
 
 
-// How many lines of one file's worth of the same problem to name before
-// saying "and N more". A file with a hundred `//` lines is one mistake, and
-// printing a hundred findings buries the other nine checks.
 const SAME_FILE_LIMIT = 5
 
 
-// A LIST OF NAMES from a manifest map, or nothing.
-//
-// The manifest is the one input here that is neither this generator's nor
-// validated before it is read: `provides: { target: 42 }` is a manifest a
-// person can write, `checkShape` already reports it, and spreading it then
-// threw `TypeError: claimed is not iterable` — turning an actionable finding
-// into a stack trace, from the verb whose entire job is actionable findings.
-//
-// Malformed reads as EMPTY rather than as its own finding: the shape checks
-// have already said what is wrong with it, and saying so twice in different
-// words helps nobody.
 function claims(map: any, key: string): string[] {
   const value = map?.[key]
 
@@ -118,8 +71,6 @@ async function cmd_package_check(
     (a: any) => 'string' === typeof a ? a.split(',') : a)
     .filter((r: any) => null != r && '' !== r)
 
-  // No ref means "the package I am standing in", which is where an author
-  // runs it.
   const reports = (0 === refs.length ? ['.'] : refs)
     .map((ref: string) => checkPackage(ref, actx))
 
@@ -146,8 +97,6 @@ function checkPackage(ref: string, actx: ActionContext): CheckReport {
 
   const { found, search } = probePackage(fs, actx.folder ?? '.', ref)
 
-  // Nothing to check is not a finding — it is a wrong invocation, and the
-  // caller needs to know which paths were tried.
   if (null == found) {
     throw new SdkGenError(
       'Package not found: ' + ref + '\n  looked for a `.sdk` folder in:\n    ' +
@@ -188,7 +137,6 @@ function checkPackage(ref: string, actx: ActionContext): CheckReport {
 }
 
 
-// The manifest, and its agreement with the disk in both directions.
 function checkManifest(fs: any, sdk: string, read: any): Finding[] {
   if (null != read.err) {
     return [{
@@ -212,13 +160,6 @@ function checkManifest(fs: any, sdk: string, read: any): Finding[] {
 }
 
 
-// Every item's definition file: the anchor, the comment dialect, the parse,
-// the schema, and the kind-specific probes.
-//
-// The items are the manifest's claims UNION what is on disk, so a definition
-// nobody claims is still checked (its being unclaimed is `validateManifest`'s
-// finding, not a reason to skip it) and a claim with no file is skipped here
-// (its absence is also already reported, and there is nothing to compile).
 function checkItems(fs: any, sdk: string, manifest?: Manifest): Finding[] {
   const found: Finding[] = []
 
@@ -261,8 +202,6 @@ function checkDefinition(
       '`package update` and `doctor` could never locate its source'))
   }
 
-  // 2. The comment dialect. Reported before the parse so the finding names
-  //    the LINE rather than aontu's view of where the parse gave up.
   const slashes = slashComments(src)
 
   for (const s of slashes.slice(0, SAME_FILE_LIMIT)) {
@@ -277,15 +216,10 @@ function checkDefinition(
       'and ' + (slashes.length - SAME_FILE_LIMIT) + ' more slash-comment line(s)'))
   }
 
-  // A slash comment IS the parse failure below, and saying it twice — once
-  // with the line, once as aontu's `unexpected character(s): //` — reads as
-  // two problems. Everything after it would be reporting on a file the author
-  // is about to change anyway.
   if (0 < slashes.length) {
     return found
   }
 
-  // 3. The parse, as a CONSUMER's parser sees it.
   const strict = compileModel(src, file)
 
   if (0 < strict.errors.length) {
@@ -300,15 +234,9 @@ function checkDefinition(
         '  (it DOES compile under a bare Aontu() — the difference is the ' +
         'comment dialect a consumer configures)' : '')))
 
-    // Nothing below can run on a file that does not compile.
     return found
   }
 
-  // 4. Does it declare the key its FILENAME promises? `model/target/iot-go.aon`
-  //    is copied to that name and included by it, so a file still declaring
-  //    `main: kit: target: go:` installs an item the consumer's model never
-  //    sees — the exact mistake a package author makes copying a bundled
-  //    target as a starting point.
   const declared = kindCollection(strict.model, kind)?.[name]
 
   if (null == declared || 'object' !== typeof declared) {
@@ -328,12 +256,6 @@ function checkDefinition(
       err + '  (unified with the base schema — this is what a consumer compiles)'))
   }
 
-  // 5b. APPLICABILITY TAGS come from a CLOSED vocabulary (see
-  //     helpers/applicability). `provides: &: boolean` accepts any key, so
-  //     without this a typo — `sekrreto` for `sekreto` — compiles cleanly
-  //     and silently makes the feature apply to NO target at all. That is
-  //     the worst shape a mistake can take here: the feature simply
-  //     vanishes from every generated SDK with no diagnostic anywhere.
   const tagkey = 'feature' === kind ? 'needs' : 'provides'
   const unknown = null == declared ? [] : unknownTags((declared as any)[tagkey])
 
@@ -404,8 +326,6 @@ function checkFeatureModel(model: any, name: string, at: At): Finding[] {
       continue
     }
 
-    // The SLOT itself is legal and empty; only concrete entries are the
-    // mistake. An entry is concrete when it declares anything of its own.
     const named = Object.keys(deps).filter((d: string) =>
       null != deps[d] && 'object' === typeof deps[d] &&
       0 < Object.keys(deps[d]).length)
@@ -462,14 +382,6 @@ function checkFeatureSource(
     }
   }
 
-  // Strays: feature-shaped entries in a provided TARGET's tree whose name is
-  // in no catalogue. They are copied into every project regardless of what
-  // its model selects, because trim only drops what it can recognise.
-  //
-  // NOT REPORTED AT ALL if this generator's own feature definitions cannot be
-  // read: every bundled feature's source would then look like a stray, and a
-  // check that fires on a correct package because of a problem at ITS end is
-  // worse than one that stays quiet.
   if (0 === bundled.length) {
     return found
   }

package/src/action/dispatch.ts

@@ -1,20 +1,3 @@
-// WHAT `voxgig-sdkgen <action> …` CAN BE.
-//
-// Built FROM THE KIND REGISTRY rather than hand-listed, so registering a kind
-// is the only edit a new kind needs — `edition add …` costs no dispatch code
-// (docs/design/sdkgen-packages.md §9). The `package` and `doctor` verbs are
-// not kinds and are added beside it.
-//
-// It lives in its own module because `package.ts` needs the per-kind add
-// functions and `target.ts` imports `feature.ts` which imports `kind.ts`;
-// wiring them together anywhere in that chain is a require cycle. Here,
-// nothing imports back.
-//
-// NULL-PROTOTYPE, and this is not decoration. A plain object literal inherits
-// Object.prototype, so `voxgig-sdkgen toString` (or `constructor`, `valueOf`,
-// …) resolved to an inherited function, passed the `null == actionFunc`
-// guard, and got CALLED with the action arguments instead of reporting an
-// unknown action.
 
 import type {
   ActionContext,
@@ -78,16 +61,6 @@ function actionNames(): string[] {
 }
 
 
-// Does this invocation need the PROJECT's model?
-//
-// Every verb but one operates on a project, and compiling `model/sdk.aontu`
-// before dispatch is what makes them fail early and clearly when run from the
-// wrong directory. `package check` is the exception on purpose: it operates
-// on a PACKAGE, and an author runs it in their package root, where there is
-// no project model to compile and nothing is wrong with that.
-//
-// Stated here, with the verb table, rather than in the CLI or in `sdkgen.ts`:
-// it is a fact about the verb.
 function needsModel(args: string[]): boolean {
   return !('package' === args[0] && 'check' === args[1])
 }