@voxgig/sdkgen 4.20.0 → 4.22.0

package/project/.sdk/src/cmp/rb/ReadmeTopQuick_rb.ts

@@ -47,8 +47,6 @@ client = ${ctor}
     // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
     const eVar = exampleVarName(eName.toLowerCase(), 'rb')
     const opnames = Object.keys(exampleEntity.op || {})
-    // Model-driven id key: null when the entity has no id-like field, in which
-    // case the load example takes no match argument.
     const idF = entityIdField(exampleEntity)
 
     let hasCall = false
@@ -62,9 +60,6 @@ puts ${eVar}s
     }
 
     if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params like
-      // page_id) — the same shape the runtime resolves path params from, so
-      // the example always works.
       const loadItems = opRequestShape(exampleEntity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>

package/project/.sdk/src/cmp/rb/ReadmeTopTest_rb.ts

@@ -8,7 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-// A type-correct Ruby literal for a field's canonical type.
 function rbLit(type: any): string {
   const k = canonScalarKey(type)
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
@@ -24,8 +23,6 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
-  // Pick an entity with a real op (prefer a read op) — never fabricate a
-  // `load` on an op-less entity like Cloudsmith's `Abort`.
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
   if (exampleEntity && primaryOp) {

package/project/.sdk/src/cmp/rb/Schema_rb.ts

@@ -0,0 +1,55 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+  rawStringLiteral,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`# ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+#
+# Generated from the model: \`main.kit.optspec\` and each feature's
+# \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+require 'json'
+
+module ${model.const.Name}Schema
+
+  OPTSPEC_DATA = ${rawStringLiteral(JSON.stringify(optspec))}.freeze
+
+  ENTITYSPEC_DATA = ${rawStringLiteral(JSON.stringify(entityspec))}.freeze
+
+  # Parsed ONCE, at load. The spec is read on every client construction and
+  # never mutated, so a per-call parse would be pure waste — and sharing the
+  # hash is safe for the same reason: make_options validates AGAINST it and
+  # writes into the options, never into the spec.
+  OPTSPEC = JSON.parse(OPTSPEC_DATA).freeze
+
+  ENTITYSPEC = JSON.parse(ENTITYSPEC_DATA).freeze
+
+end
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/rb/TestDirect_rb.ts

@@ -250,8 +250,6 @@ ${listSkipBlock}    client = setup[:client]
     }
 
     if (hasLoad && loadPoint) {
-      // Skip live direct-load only when we can't fill path params:
-      // no spec examples and no list-bootstrap. Spec examples win first.
       const loadSkipBlock = (loadParams.length > 0 && !loadAllHaveExamples)
         ? `    if setup[:live]
       skip "live direct-load needs real ID — set *_ENTID env var with real IDs to run"

package/project/.sdk/src/cmp/rb/utility_rb.ts

@@ -68,28 +68,6 @@ function formatRubyValue(val: any, indent: number = 0): string {
 }
 
 
-// Emission-time normalisation of a model subtree (L0).
-//
-// Always drops jostraca's iteration metadata (`$`-suffixed keys: index$,
-// key$, val$). With `dropDefaults`, also drops keys whose value IS the
-// default the runtime already assumes when the key is absent, which is pure
-// payload — see CONFIG_DEFAULT.
-//
-// Rebuilds the tree rather than mutating during a walk. The previous
-// implementation walked a clone calling `delete p[k]`, but walk() assigns its
-// callback's result back over the child (`setprop(out, ckey, walk(...))`), so
-// the delete was undone on the way out and the helper silently did nothing.
-// Returning `undefined` from the callback does not fix it either: setprop
-// stores undefined rather than removing the key, which then emits as a null.
-//
-// `dropDefaults` is opt-in and must be passed ONLY for the entity subtree.
-// `active` means something different in feature config, where absent reads as
-// INACTIVE (see feature_init) — dropping `active: true` there would silently
-// disable the feature.
-// jostraca's iteration metadata, injected by each()/names() while it walks the
-// model. Listed explicitly rather than matched by trailing-dollar suffix: a
-// trailing dollar is not exclusive to jostraca -- Seneca uses entity$ as real
-// data -- so a blanket suffix match can silently drop a legitimate API field.
 const MODEL_META = ['index$', 'key$', 'val$']
 
 // Keys whose value IS the default the runtime already assumes when the key is

package/project/.sdk/src/cmp/rust/Config_rust.ts

@@ -52,34 +52,8 @@ const Config = cmp(async function Config(props: any) {
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
-  // The canonical config OBJECT and its JSON, from the shared helper. Both
-  // representations render from the same `def`, so they cannot describe
-  // different configs - and this target picks up `options.server` (the
-  // OpenAPI server-variable defaults), which the hand-rolled build here
-  // omitted entirely. Passing target.name opts into the main
-  // slug/version/target identity fields (station descriptor input, mirrors
-  // Config_ts) - both reps below render from this same def, so the data
-  // and literal branches pick the fields up together.
   const { def: config, json: baseJson } = configDefinition(model, target.name)
 
-  // `in` and `name` TRAVEL WITH THE PREFIX NOW.
-  //
-  // apidef resolved both from the spec's securityScheme all along and this
-  // generator dropped them, so an apiKey-in-query API got an `authorization`
-  // header it does not read (see PrepareAuth_rust). The generated
-  // prepare_auth is built from the same two values, and the config carries
-  // them so the placement is a visible, overridable runtime option beside
-  // auth.prefix - which is also what keeps the SDK from rejecting its own
-  // config: the auth optspec in tm/rust/utility/make_options.rs is a CLOSED
-  // map, and an undeclared key there fails validate with "Unexpected keys at
-  // field auth".
-  //
-  // Emitted ONLY when they differ from header/Authorization, so a
-  // header-based SDK's config.rs is byte-identical to what it generated
-  // before. Both representations are patched through the one object, so the
-  // literal (formatRustValue) and the data rep (rustRawString) cannot
-  // disagree - the json is re-derived from the def, exactly as
-  // configDefinition derives it.
   const authIn = resolveAuthIn(model)
   const authName = resolveAuthName(model)
   let configJson = baseJson
@@ -103,15 +77,6 @@ const Config = cmp(async function Config(props: any) {
 
   File({ name: 'config.' + target.ext }, () => {
 
-    // ABOVE THE THRESHOLD: emit the model as DATA.
-    //
-    // The literal is one deeply nested expression. rustc type-checks and
-    // monomorphises it as a single item, so compile time and memory grow with
-    // the whole model at once; a string constant is one token, and json_parse
-    // builds the same Value tree at runtime.
-    //
-    // No number-type question here, unlike Go: `Value::Num` is f64 in both
-    // representations, so there is nothing for the two paths to disagree about.
     if (asData) {
       Content(`// Generated API configuration (mirrors go core/config.go).
 

package/project/.sdk/src/cmp/rust/EntityTypes_rust.ts

@@ -1,28 +1,5 @@
 
 
-// Typed-model generator (Rust target). Port of EntityTypes_go.ts.
-//
-// Reads main.<KIT>.entity.<e>.fields[] and per-op params
-// (op.<name>.points[].args.params[]) and emits one file, entity/types.rs, with
-// a rust `struct <Name> { ... }` per entity plus a request/match struct per
-// active op. Field/param sentinels ($STRING, $INTEGER, ...) map to rust types
-// via the SHARED canonToType 'rust' column (the single source of truth per
-// language — do not keep a local table here). Note OBJECT renders as
-// std::collections::HashMap<String, Value> (fully qualified, no import
-// needed).
-//
-// DESIGN NOTE (rust specifics vs the go reference):
-//   * The rust runtime is fully DYNAMIC: every op takes and returns the
-//     vendored `Value` enum (Result<Value, ...Error>), and the op fragments
-//     emit no typed wrappers. Go additionally emits `LoadTyped`/`ListTyped`
-//     wrappers plus json round-trip helpers; rust has no serde/json-derive
-//     dependency (only `ureq`), so these typed models are DOCUMENTARY: they
-//     mirror the entity/op shapes for reference and IDE support, but are not
-//     wired into the runtime. They compile as part of the crate (declared in
-//     entity/mod.rs) so they stay in sync with the model.
-//   * Optional (req:false) member -> `Option<T>`.
-//   * The module carries broad `#![allow(...)]` since nothing consumes the
-//     types yet (parity intent, not dead-code churn).
 
 import {
   cmp, each,
@@ -52,8 +29,6 @@ function fieldLine(name: string, sentinel: any, optional: boolean): string {
 }
 
 
-// Emit a struct named `typeName` from {name, type, optional} items, dropping
-// duplicate rust identifiers (two model names can collapse to one ident).
 function emitStruct(comment: string, typeName: string, items: any[]): void {
   Content(`${comment}
 #[derive(Debug, Clone)]
@@ -82,14 +57,8 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   // collection, so inactive entities still get generated entity code that
   // references these typed names. The typed model must cover them too.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  // Emit for every entity that gets an entity file (filter on `name`, always
-  // present; derive `Name` here so the struct set is deterministic — parity
-  // with the go emitter's fix).
   const entityList = deriveEntityNames(entity)
 
-  // Surface duplicate generated type names (two entities with the same
-  // PascalCase Name) — they would redeclare a type in statically-typed
-  // targets. Detection only; renaming is a model-level decision.
   warnEntityTypeCollisions(entity, log, LANG)
 
   Folder({ name: 'entity' }, () => {
@@ -116,15 +85,12 @@ use crate::utility::voxgigstruct::Value;
         const fields = (ent.fields ? each(ent.fields) : [])
           .filter((f: any) => f.active !== false)
 
-        // Entity data model: one field per model field. req:false -> Option.
         emitStruct(
           `/// ${Name} is the typed data model for the ${ent.name} entity.`,
           Name,
           fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req }))
         )
 
-        // Per active op: a request/match struct. Members and their optionality
-        // come from the shared partiality policy (opRequestShape).
         const ops = ent.op || {}
         ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
           if (null == ops[opname]) {

package/project/.sdk/src/cmp/rust/Entity_rust.ts

@@ -32,19 +32,12 @@ const Entity = cmp(function Entity(props: any) {
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/rust/fragment/')
 
-  // Entity files go to entity/ as one module per entity.
   Folder({ name: 'entity' }, () => {
 
     File({ name: rustVarName(entity.name) + '.' + target.ext }, () => {
 
       const opnames = Object.keys(entity.op || {})
 
-      // For each CRUD op: if the spec defines it, splice in the real
-      // implementation. Otherwise emit a stub that satisfies the static
-      // ProjectNameEntity trait (so the crate compiles) but errors at
-      // runtime if the caller invokes an unsupported op.
-      // Tag-form keys (`#LoadOp`) match the marker line `// #LoadOp` and
-      // capture its indent, so the spliced method nests inside the impl.
       const opfrags =
         (['load', 'list', 'create', 'update', 'remove']
           .reduce((a: any, opname: string) =>
@@ -74,8 +67,6 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
-          // Class/constructor tokens are decoupled from the EntityName
-          // data-type token so the class can be renamed independently.
           EntyClass: cls,
 
           // Matches every `// #<Stage>-Hook` marker in the fragment (all of

package/project/.sdk/src/cmp/rust/Main_rust.ts

@@ -24,6 +24,7 @@ import {
 
 import { Package } from './Package_rust'
 import { Config } from './Config_rust'
+import { Schema } from './Schema_rust'
 import { PrepareAuth } from './PrepareAuth_rust'
 import { Gitignore } from './Gitignore_rust'
 import { MainEntity } from './MainEntity_rust'
@@ -44,8 +45,6 @@ const Main = cmp(async function Main(props: any) {
   // helpers/applicability.
   const feature = targetFeatures(model, target)
 
-  // The rust crate identifier (RUSTCRATE placeholder), e.g. solar_sdk —
-  // used in every `use <crate>::...` path in the test templates.
   const rustcrate = crateIdent(model)
 
   Package({ target })
@@ -68,23 +67,8 @@ const Main = cmp(async function Main(props: any) {
     }
   })
 
-  // utility/prepare_auth.rs is GENERATED, not templated: where the
-  // credential goes (header / query / cookie, and under what name) is a
-  // fact about the API, and tm/ can only hold one answer. See
-  // PrepareAuth_rust.
-  //
-  // AT ROOT LEVEL, and outside the `core` Folder below. The rust crate root
-  // IS the target root - lib.rs, core/, feature/ and utility/ all sit there
-  // - the component opens `utility` itself, and that is the same path
-  // `Copy({from:'tm/rust'})` used for the template it replaces. Calling it
-  // beside Config, inside `Folder({name:'core'})`, would emit
-  // core/utility/prepare_auth.rs instead: a file no module declares, so
-  // rustc never compiles it, while utility/mod.rs's `pub mod prepare_auth;`
-  // keeps binding whatever utility/ actually holds.
   PrepareAuth({ target })
 
-  // Generated core files: the client (sdk.rs), the API config and the
-  // branded error type.
   Folder({ name: 'core' }, () => {
 
     File({ name: 'sdk.' + target.ext }, () => {
@@ -97,7 +81,6 @@ const Main = cmp(async function Main(props: any) {
           }
         },
 
-        // Entity accessors - injected at SLOT
         () => {
           each(entity, (entity: ModelEntity) => {
             const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
@@ -109,15 +92,11 @@ const Main = cmp(async function Main(props: any) {
 
     Config({ target })
 
+    Schema({ target })
+
     SdkError({ target })
   })
 
-  // feature/mod.rs — the feature module index.
-  //
-  // GENERATED, not templated: rust needs every module declared, and
-  // `target add` only copies source for the features the model selects. A
-  // static index listing all eighteen shipped features stops the crate from
-  // compiling the moment the set is trimmed.
   Folder({ name: 'feature' }, () => {
     File({ name: 'mod.' + target.ext }, () => {
       Content(`// ${model.const.Name} SDK feature modules (mirrors tm/go/feature).
@@ -131,29 +110,7 @@ pub mod base;
       each(feature, (feat: any) => Content(`pub mod ${feat.name};\n`))
     })
 
-    // feature/<name>/plugins.rs - a feature's PLUGIN module index.
-    //
-    // GENERATED, and it has no go/py analogue: rust compiles only the
-    // modules a parent DECLARES, and the declared set varies with the
-    // plugin trim, so a static index would either name a file the trim
-    // just deleted or leave an active kind out of the build.
-    //
-    // It sits one level ABOVE the vendored `plugins/` directory on
-    // purpose: the vendoring guard fails any non-vendored file inside a
-    // vendor dir. Nothing is lost by that - an .rs file no module
-    // declares is not compiled at all, so an inactive group's vendored
-    // file left on disk is inert whether or not the trim reached it.
-    //
-    // This is rust's replacement for go's core-emitted FeaturePlugins map
-    // (Config_go), and it is better placed: core/config.rs never has to
-    // name a feature's types.
     each(feature, (feat: any) => {
-      // `only_active: false`, the same subtlety pluginExcludesFor
-      // documents: the feature object a component is handed has already
-      // been filtered, so a feature whose plugins are ALL inactive would
-      // arrive with nothing here and the index would not be emitted at
-      // all - leaving `pub mod plugins;` in the feature source pointing
-      // at a file that does not exist.
       const declared = getModelPath(model,
         `main.${KIT}.feature.${feat.name}.plugin`,
         { required: false, only_active: false }) || {}
@@ -172,18 +129,11 @@ pub mod base;
         if (true !== plugin.active) return
 
         for (const [sym, one] of Object.entries(plugin.def?.rust || {})) {
-          // 'feature/secrets/plugins/aws.rs' -> the module `aws`.
           mods.add(String(one).replace(/^.*\//, '').replace(/\.rs$/, ''))
           syms.add(sym)
         }
       })
 
-      // The shared HTTP client the vendored vault kinds import
-      // (`use super::httpjson::...`) belongs to NO plugin group - trimming
-      // it with any one group would delete a file the others compile
-      // against - so it ships with the feature core and is DECLARED here
-      // only when something reaches for it. That is what keeps rustls out
-      // of a chain that is [dotenv, env] or [secretspec].
       const NOHTTP = ['secretspec']
       const http = Array.from(mods).some((m: string) => !NOHTTP.includes(m))
 
@@ -225,15 +175,10 @@ pub fn definitions() -> Vec<Definition> {
     })
   })
 
-  // entity/mod.rs — the entity module index.
   EntityBase({ target })
 
-  // entity/types.rs — the documentary typed models (one struct per entity +
-  // per op). Declared as a module by EntityBase so it compiles with the crate.
   EntityTypes({ target })
 
-  // lib.rs — the crate root: module declarations plus the public API
-  // re-exports (twin of the go root package file).
   File({ name: 'lib.' + target.ext }, () => {
     Content(`// ${model.const.Name} SDK for Rust (generated by @voxgig/sdkgen).
 //

package/project/.sdk/src/cmp/rust/Package_rust.ts

@@ -17,12 +17,6 @@ import type {
 import { crateIdent, crateName } from './utility_rust'
 
 
-// Cargo.toml (the rust manifest). Dependencies come from the target model
-// (`deps` block, kind prod|dev) plus any feature-declared rust deps, via
-// the shared collectDeps helper. The vendored voxgig struct port needs no
-// external crate. The lib path is the crate root `lib.rs` (the generated
-// SDK mirrors the go layout: core/, feature/, utility/, entity/ at the
-// repo root rather than under src/).
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
   const target = props.target
@@ -74,21 +68,6 @@ path = "lib.rs"
       }
     }
 
-    // [[test]] stanzas for the feature suites.
-    //
-    // cargo auto-discovers `tests/*.rs` and `tests/<dir>/main.rs`, but NOT
-    // `tests/<dir>/<dir>/main.rs` - and the two-level path is not
-    // negotiable: a feature's tests must live inside a `feature/`
-    // container so `target add` trims them WITH the feature
-    // (helpers/featureSource), exactly as go's tm/go/test/feature/secrets/
-    // and py's tm/py/test/feature/secrets/ do. A one-level
-    // tests/secrets/main.rs would auto-discover and then be left behind in
-    // a project that does not select the feature, carrying a suite that
-    // cannot compile.
-    //
-    // So the suite is DECLARED, and only for a feature that both applies
-    // to this target and is active in the model - which is also exactly
-    // when `target add` kept its directory.
     const suites = Object.keys(targetFeatures(model, target))
       .filter((name: string) => null != FEATURE_TESTS[name])
       .sort()
@@ -113,15 +92,6 @@ const FEATURE_TESTS: Record<string, string> = {
 }
 
 
-// One Cargo dependency's value: the bare version string, or the TABLE form
-// when the model asks for anything more.
-//
-// `default: false` and `features: [...]` are not decoration. The secrets
-// feature's vendored HTTP helper speaks rustls, and `rustls = "0.23"` with
-// DEFAULT features pulls aws-lc-rs/aws-lc-sys and a cmake C build, while
-// the ring feature set is what the target's existing `ureq` dep already
-// compiles. Without the table form, turning on one feature would add a
-// native toolchain requirement to every SDK that selected it.
 function depValue(version: string, raw: any): string {
   const features: string[] = Array.isArray(raw?.features) ? raw.features : []
   const nodefault = false === raw?.default

package/project/.sdk/src/cmp/rust/PrepareAuth_rust.ts

@@ -12,26 +12,6 @@ import {
 } from '@voxgig/sdkgen'
 
 
-// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
-// rather than templated. This is the rust peer of PrepareAuth_ts; read that
-// one first, it carries the full account of the defect.
-//
-// This was a static file at `tm/rust/utility/prepare_auth.rs` that hardcoded
-//
-//   const HEADER_AUTH: &str = "authorization";
-//
-// apidef has always resolved the scheme's `in` and `name` into
-// `main.kit.info.security` — joplin's says `in: "query", name: "token"` —
-// and generation dropped both, so the SDK sent a header the API does not
-// read and never sent the query parameter it does.
-//
-// A template cannot fix this, because the three placements need three
-// different bodies and a template has to pick one. A component emits the
-// branch this API actually uses and nothing else — no dead query code in a
-// bearer-token SDK, and no runtime `if` on a value that is fixed at
-// generation time. Rust makes that worth doing carefully: an import the
-// emitted body never reaches is a warning on every build of the crate, so
-// the `use` lines are chosen per placement too.
 const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   const { target } = props
   const { model } = props.ctx$
@@ -42,41 +22,12 @@ const PrepareAuth = cmp(async function PrepareAuth(props: any) {
   // the way Main_rust spells it in lib.rs's re-exports.
   const errtype = model.const.Name + 'Error'
 
-  // `!isAuthSuppressed`, NOT `isAuthActive`. The latter is also false when
-  // the SPEC merely declares no security scheme (`main.kit.info.auth:
-  // false`), and those SDKs still carry a credential: optspec always
-  // declares `apikey` and makeOptions fills `options.auth` from its
-  // defaults, so the runtime guard never fired and they have always sent
-  // it. Only an explicit `main.kit.config.auth.active: false` means "no
-  // credential, ever", which is what isAuthSuppressed reads.
   const active = !isAuthSuppressed(model)
   const where = resolveAuthIn(model)
   const name = resolveAuthName(model)
-  // Resolved, and deliberately NOT baked into the source: the prefix is a
-  // runtime option (`options.auth.prefix`), and the template this replaces
-  // read it from the options map so a caller could override it per client.
-  // Only the PLACEMENT is fixed at generation time.
   const prefix = resolveAuthPrefix(model)
   const basic = isHttpBasicAuth(model)
 
-  // FOLDER NESTING. Main_rust opens NO folder around this call: the rust
-  // crate root IS the target root (lib.rs, core/, feature/, utility/ all sit
-  // there — see the `[lib] path` in tm/rust/Cargo.toml), the template this
-  // replaces lived at `tm/rust/utility/prepare_auth.rs`, and
-  // `Copy({from:'tm/rust'})` lands it at `<root>/utility/`. So the `utility`
-  // folder is opened HERE, exactly as EntityBase_rust opens `entity`.
-  //
-  // The call site matters as much. Config_rust runs inside
-  // `Folder({name:'core'})`, and putting PrepareAuth beside it would write
-  // `core/utility/prepare_auth.rs` — a path no module declares, so rustc
-  // never compiles it, while `utility/mod.rs`'s `pub mod prepare_auth;`
-  // keeps binding whatever `utility/` actually holds. Main_rust calls this
-  // at ROOT level.
-  //
-  // The file NAME is not free either: `utility/mod.rs` declares the module
-  // `prepare_auth`, and `make_spec` calls
-  // `crate::utility::prepare_auth::prepare_auth_util`. The generated file
-  // has to answer to that name.
   Folder({ name: 'utility' }, () => {
     File({ name: 'prepare_auth.' + target.ext }, () => {
       Content(render({ errtype, active, where, name, prefix, basic }))
@@ -97,10 +48,6 @@ type AuthSpec = {
 
 function render(spec: AuthSpec): string {
 
-  // NO AUTH AT ALL. A public API's SDK gets a prepare_auth that is honest
-  // about it rather than one that deletes a header nobody set. `vs`, `Value`
-  // and the helpers are left out of the imports deliberately — rustc warns
-  // on an unused import, on every build, forever.
   if (!spec.active) {
     return `// prepare_auth utility.
 //
@@ -134,9 +81,6 @@ pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.
   // where it can mean something.
   const withBasic = spec.basic && 'header' === spec.where
 
-  // `getpath` reads `options.auth.prefix`, and only a header placement has a
-  // prefix to read: a query parameter drops it, and a cookie pair has no
-  // room for one.
   const withGetpath = 'header' === spec.where
 
   const bag = bagName(spec.where)
@@ -248,8 +192,6 @@ ${place(spec.where)}
 }
 `
 
-  // The encoder goes AFTER prepare_auth_util, so the function a reader opens
-  // this file for is the first one they meet.
   const encoder = !withBasic ? '' : `
 /// Standard base64, for the \`Authorization: Basic base64(user:pass)\` value.
 ///
@@ -294,19 +236,6 @@ fn base64_encode(input: &[u8]) -> String {
 }
 
 
-// The credential's key, as it goes into the bag.
-//
-// A HEADER name is lowercased. HTTP header names are case-insensitive
-// (RFC 9110 5.1) and the fetcher writes them out as given, so nothing
-// changes on the wire — but this SDK's own header map is keyed in lowercase
-// throughout (`content-type`, and the `authorization` that tm/rust/tests/
-// pipeline_test.rs asserts on), and the shipped `prepare_auth.rs` said
-// `"authorization"`. Emitting the resolver's title-cased default here would
-// have left every header SDK's own test suite failing on a purely cosmetic
-// difference.
-//
-// A QUERY parameter and a COOKIE name are case-SENSITIVE, so those go in
-// verbatim: `?token=` is not `?Token=`.
 function credLiteral(where: string, name: string): string {
   return 'header' === where ? String(name).toLowerCase() : String(name)
 }
@@ -323,29 +252,18 @@ function credComment(where: string): string {
 }
 
 
-// The bag the credential lands in, per placement — and, in rust, the `Spec`
-// field it is read from, which is spelled the same. Cookies ride the header
-// bag because a cookie IS a header.
 function bagName(where: string): string {
   return 'query' === where ? 'query' : 'headers'
 }
 
 
 function clear(where: string): string {
-  // COOKIE clears the header named for the credential, NOT the cookie
-  // header: the cookie header may carry pairs this SDK never set, and
-  // deleting it to remove one pair would drop them all. Removing a header
-  // that placement never writes is a no-op, which is the honest outcome
-  // when there is no credential to place.
   return `vs::del_prop(${bagName(where)}, &Value::str(CRED_NAME))`
 }
 
 
 function place(where: string): string {
   if ('query' === where) {
-    // NO PREFIX IN A QUERY STRING. `?token=Bearer%20abc` is not a thing any
-    // API reads; the prefix is a header convention and is dropped here
-    // deliberately rather than silently concatenated.
     return `        let apikey_val = match &apikey {
             Value::Str(s) => s.clone(),
             _ => String::new(),
@@ -355,8 +273,6 @@ function place(where: string): string {
   }
 
   if ('cookie' === where) {
-    // Append, never replace: the cookie header may already carry pairs this
-    // SDK did not set, and clobbering it would drop them.
     return `        let apikey_val = match &apikey {
             Value::Str(s) => s.clone(),
             _ => String::new(),

package/project/.sdk/src/cmp/rust/ReadmeExamplesTest_rust.ts

@@ -1,22 +1,6 @@
 import { cmp, Content, File } from '@voxgig/sdkgen'
 
 
-// Emits rust/tests/readme_examples_test.rs — a structural gate over every
-// ```rust fenced block in the three docs that ship rust examples:
-//   - the root README.md (top-level, multi-language quick start)
-//   - the per-language rust/README.md
-//   - the per-language rust/REFERENCE.md
-//
-// DESIGN NOTE vs the go gate (ReadmeExamplesTest_go.ts): the go version shells
-// out to `go build`/`go run` to COMPILE and RUN every block. A faithful rust
-// port would shell out to `cargo`/`rustc` against extracted snippets — a large,
-// environment-sensitive harness that cannot be authored safely without a build
-// to validate it. This rust gate instead validates that every documented rust
-// block is PRESENT and STRUCTURALLY well-formed (balanced delimiters,
-// non-empty). It is a real, always-passing test that keeps the docs honest
-// about block structure; upgrading it to a true compile gate (a temp crate that
-// `cargo build`s each block against the generated SDK) is left as a follow-up.
-// Missing docs are tolerated (a run may generate a subset of phases).
 const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
   const { ctx$: { model } } = props