@voxgig/sdkgen 4.4.1 → 4.5.0

package/src/cmp/FeatureDocs.ts

@@ -0,0 +1,100 @@
+import { each } from 'jostraca'
+
+import { KIT, getModelPath } from '../types'
+
+
+// Shared feature facts, derived from the model, for the three doc surfaces
+// that describe features: the root README summary, the per-target README
+// section, and REFERENCE.md.
+//
+// ONE SOURCE. The feature set, its defaults and its ordering constraints all
+// come from `main.kit.feature`, so a feature added to the model documents
+// itself everywhere rather than in whichever file someone remembered.
+
+type FeatureDoc = {
+  name: string
+  Name: string
+  title: string
+  transport: string
+  wraps: boolean
+  options: Array<{ name: string, value: string }>
+}
+
+
+// `transport` says how a feature attaches, and that is the whole of the
+// ordering story:
+//   wrap  wraps the transport chain — activation order IS nesting order
+//   base  installs the base transport others wrap (test)
+//   none  pipeline hooks only; order does not affect it
+function isWrapping(feat: any): boolean {
+  return 'wrap' === feat.transport
+}
+
+
+function renderValue(v: any): string {
+  if (null == v) { return '' }
+  if (Array.isArray(v)) { return '[' + v.map((x) => renderValue(x)).join(', ') + ']' }
+  if ('object' === typeof v) {
+    const keys = Object.keys(v)
+    return 0 === keys.length ? '{}' :
+      '{' + keys.map((k) => k + ': ' + renderValue(v[k])).join(', ') + '}'
+  }
+  if ('string' === typeof v) { return `'${v}'` }
+  return String(v)
+}
+
+
+// Every feature the model declares active, in a stable order, with its
+// options and their defaults.
+function featureDocs(model: any): FeatureDoc[] {
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  return each(feature)
+    .filter((f: any) => false !== f.active && 'base' !== f.name)
+    .map((f: any) => {
+      const opts = (f.config && f.config.options) || {}
+      const options = Object.keys(opts).sort().map((k) => ({
+        name: k,
+        value: renderValue(opts[k]),
+      }))
+      return {
+        name: f.name,
+        Name: f.Name || f.name,
+        title: f.title || '',
+        transport: f.transport || 'none',
+        wraps: isWrapping(f),
+        options,
+      }
+    })
+    .sort((a: FeatureDoc, b: FeatureDoc) => a.name.localeCompare(b.name))
+}
+
+
+
+
+// Targets that compose transport features in a FIXED catalog order rather
+// than the order the caller activates them in.
+//
+// Every other target derives `__derived__.featureorder` from the options and
+// adds features in that order, so an ordered activation list is what fixes
+// nesting. lean has no featureorder at all — SdkFeatures.featureNames is a
+// fixed array — and its resolveFeatureOpts accepts only a map, silently
+// replacing a list with an empty one. Telling a lean reader to activate
+// features as an ordered list would therefore disable every feature they
+// asked for.
+//
+// Verify with: grep -rl featureorder tm/<target>
+const FIXED_ORDER_TARGETS = ['lean']
+
+function honoursActivationOrder(target: any): boolean {
+  return !FIXED_ORDER_TARGETS.includes(target?.name)
+}
+
+
+export {
+  featureDocs,
+  renderValue,
+  honoursActivationOrder,
+}
+
+export type { FeatureDoc }

package/src/cmp/Readme.ts

@@ -13,6 +13,7 @@ import { ReadmeEntity } from './ReadmeEntity'
 import { ReadmeUnions } from './ReadmeUnions'
 import { ReadmeHowto } from './ReadmeHowto'
 import { ReadmeExplanation } from './ReadmeExplanation'
+import { ReadmeFeatures } from './ReadmeFeatures'
 import { ReadmeRef } from './ReadmeRef'
 
 
@@ -31,6 +32,7 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeModel({ target })
     ReadmeOptions({ target })
     ReadmeEntity({ target })
+    ReadmeFeatures({ target })
     ReadmeUnions({ target })
     ReadmeExplanation({ target })
 

package/src/cmp/ReadmeFeatures.ts

@@ -0,0 +1,113 @@
+import { cmp, Content } from 'jostraca'
+
+import { requirePath } from '../utility'
+import { featureDocs, honoursActivationOrder } from './FeatureDocs'
+import type { FeatureDoc } from './FeatureDocs'
+
+
+// The `## Features` section of a target README: one subsection per feature
+// the SDK actually ships.
+//
+// WHY IT IS SHARED AND NOT PER-LANGUAGE. Every target activates features the
+// same way — a `feature` entry in the client options — and the options and
+// their defaults come from the model, so the substance is identical in all
+// twenty-five languages. Only the literal syntax of the options map differs,
+// and that is already shown once, in the Options section above. A per-target
+// `ReadmeFeatures_<lang>.ts` may override this to add idiomatic snippets;
+// none is required for the section to be correct.
+const ReadmeFeatures = cmp(function ReadmeFeatures(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const override =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeFeatures_${target.name}`, { ignore: true })
+
+  if (override) {
+    override['ReadmeFeatures']({ target })
+    return
+  }
+
+  const features: FeatureDoc[] = featureDocs(model)
+
+  if (0 === features.length) {
+    return
+  }
+
+  Content(`## Features
+
+This SDK ships ${features.length} optional features. Each is **inactive until you
+switch it on**, so an SDK you have not configured behaves exactly as if none of
+them existed — no retries, no cache, no logging, no measurable overhead.
+
+Activate a feature by name in the client options, alongside the options shown
+above:
+
+| Feature | What it does |
+|---|---|
+`)
+
+  for (const f of features) {
+    Content(`| [\`${f.name}\`](#${f.name}) | ${f.title} |
+`)
+  }
+
+  Content(`
+`)
+
+  const wrapping = features.filter((f) => f.wraps).map((f) => '`' + f.name + '`')
+  if (1 < wrapping.length) {
+    if (honoursActivationOrder(target)) {
+      Content(`> **Order matters for ${wrapping.join(', ')}.** These wrap the
+> transport, so each one wraps whatever is already installed: the order you
+> activate them in IS the nesting order. Activating them as an ordered list
+> rather than a map is what fixes that order.
+
+`)
+    }
+    else {
+      Content(`> **${wrapping.join(', ')} wrap the transport**, so each one wraps
+> whatever is already installed. This SDK composes them in a fixed catalog
+> order, not the order you activate them in, and takes \`feature\` as a map.
+
+`)
+    }
+  }
+
+  for (const f of features) {
+    Content(`### ${f.name}
+
+${f.title}.
+
+`)
+
+    if (0 < f.options.length) {
+      Content(`| Option | Default |
+|---|---|
+`)
+      for (const o of f.options) {
+        Content(`| \`${o.name}\` | \`${o.value}\` |
+`)
+      }
+      Content(`
+`)
+    }
+
+    Content(`Set \`feature.${f.name}.active\` to enable it${
+      0 < f.options.length ? ', then override any of the options above' : ''}.
+
+`)
+
+    if (f.wraps) {
+      Content(`\`${f.name}\` wraps the transport, so its position among the other
+transport features decides what it sees. A feature activated later wraps one
+activated earlier.
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeFeatures
+}

package/src/cmp/ReadmeRef.ts

@@ -15,6 +15,10 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
     requirePath(ctx$, `./cmp/${target.name}/ReadmeRef_${target.name}`, { ignore: true })
 
   if (ReadmeRef_sdk) {
+    // The per-language component owns the REFERENCE.md File, so anything
+    // appended out here lands outside it and silently vanishes. The shared
+    // feature reference is therefore called from INSIDE each
+    // ReadmeRef_<lang>.ts, at the end of its own features section.
     ReadmeRef_sdk['ReadmeRef']({ target })
   }
 })

package/src/cmp/ReadmeRefFeatures.ts

@@ -0,0 +1,149 @@
+import { cmp, Content } from 'jostraca'
+
+import { featureDocs, honoursActivationOrder } from './FeatureDocs'
+import type { FeatureDoc } from './FeatureDocs'
+
+
+// The feature reference, appended to every REFERENCE.md.
+//
+// REFERENCE.md is otherwise generated per-language, because the constructor
+// signature, op spelling and code fence differ. Feature CONFIGURATION does
+// not: the option names and defaults are model facts, identical in every
+// target. So this section is written once and appended to all of them, rather
+// than copied into twenty-five ReadmeRef_<lang>.ts files where it would drift.
+//
+// Covers what a reference has to cover and a README does not: every option
+// with its default, what the feature does at runtime, and the considerations
+// — ordering, interaction, and cost — that decide whether to switch it on.
+const ReadmeRefFeatures = cmp(function ReadmeRefFeatures(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const features: FeatureDoc[] = featureDocs(model)
+
+  if (0 === features.length) {
+    return
+  }
+
+  // Emitted INSIDE the per-language `## Features` section, after its summary
+  // table and activation snippet, so these are subsections of it rather than
+  // a competing heading.
+  Content(`
+### Configuring features
+
+Each feature is inactive until switched on, and an SDK with no feature
+configured does no feature work at all. Every option below keeps its default
+unless you name it.
+
+${honoursActivationOrder(target) ?
+  'The array form of \\`feature\\` is significant: several features wrap the\ntransport, and the order you list them in is the order they nest.' :
+  'This SDK takes \\`feature\\` as a map and composes the transport-wrapping\nfeatures in a fixed catalog order, so activation order does not change\nnesting here.'}
+
+`)
+
+  const wrapping = features.filter((f) => f.wraps)
+  const hooked = features.filter((f) => !f.wraps)
+
+  if (0 < wrapping.length) {
+    Content(`#### Ordering
+
+${wrapping.map((f) => '`' + f.name + '`').join(', ')} wrap the transport. Each
+wraps whatever is already installed${honoursActivationOrder(target) ?
+  ', so **activation order is nesting order**:\na feature activated later sits OUTSIDE one activated earlier, and sees the call\nfirst.' :
+  '. This SDK fixes that order in its own\ncatalog rather than taking it from the caller.'}
+
+${(features.some((f) => 'cost' === f.name) && features.some((f) => 'cache' === f.name)) ?
+`That decides behaviour, not just sequence. \\\`cost\\\` activated before \\\`cache\\\`
+sits inside it, so a response served from the cache never reaches \\\`cost\\\` and is
+correctly charged nothing; reverse them and every cache hit is billed for money
+that was never spent.
+` : `That decides behaviour, not just sequence: a feature that short-circuits the
+call, such as a cache serving a hit, stops every feature nested inside it from
+ever seeing that call.
+`}
+${hooked.map((f) => '`' + f.name + '`').join(', ')} attach to pipeline hooks
+rather than the transport, so their order does not affect what they observe.
+
+`)
+  }
+
+  for (const f of features) {
+    Content(`#### \`${f.name}\`
+
+${f.title}.
+
+`)
+
+    Content(`**Configuration**
+
+`)
+
+    // THE TABLE IS THE MODEL'S OPTIONS, AND THE MODEL IS INCOMPLETE. Several
+    // features accept runtime-only options the model never declares — cost
+    // reads `actor` and `sink`, audit reads `sink` — so a table derived from
+    // `config.options` cannot list them. Deriving from a second hand-written
+    // list would reintroduce exactly the drift this module exists to avoid,
+    // so the honest fix is upstream: declare them in the feature model. Until
+    // then, say so rather than imply the table is exhaustive.
+
+
+    if (0 < f.options.length) {
+      Content(`| Option | Default |
+|---|---|
+`)
+      for (const o of f.options) {
+        Content(`| \`${o.name}\` | \`${o.value}\` |
+`)
+      }
+      Content(`
+`)
+    }
+    else {
+      Content(`\`active\` only — this feature takes no further options.
+
+`)
+    }
+
+    Content(`Options above are those the model carries a default for. A feature may
+also accept callback options — a \`sink\` to receive each record, for
+instance — which have no default and are covered in the full feature
+reference.
+
+**Usage**
+
+Set \`feature.${f.name}.active\` to true in the client options${
+  0 < f.options.length ?
+    ', and override any option above in the same entry' : ''}. Every option keeps
+its default unless you name it.
+
+**Considerations**
+
+`)
+
+    if (f.wraps) {
+      Content(`- Wraps the transport: its place in the activation order decides what it
+  sees. See [Ordering](#ordering) above.
+`)
+    }
+    else {
+      Content(`- Attaches to pipeline hooks, not the transport, so activation order does
+  not change what it observes.
+`)
+    }
+
+    if ('base' === f.transport) {
+      Content(`- Installs the BASE transport that the wrapping features wrap, so it must be
+  activated before them.
+`)
+    }
+
+    Content(`- Inactive by default: leaving it out costs nothing at runtime.
+
+`)
+  }
+})
+
+
+export {
+  ReadmeRefFeatures
+}

package/src/cmp/ReadmeTop.ts

@@ -7,6 +7,7 @@ import {
 } from '../types'
 
 import { requirePath } from '../utility'
+import { featureDocs } from './FeatureDocs'
 
 import {
   entityPrimaryOp, entityIdField, opRequestShape, entityPath, entityActions,
@@ -206,6 +207,20 @@ Learn more about Voxgig SDKs at [voxgig.com/sdk](${VOXGIG_SDK}).
         : surfaces[0]
       Content(`> ${surfaceList} — all generated from one OpenAPI spec by [@voxgig/sdkgen](${SDKGEN_REPO}).
 
+`)
+    }
+
+    // FEATURES BELONG BESIDE THE TARGETS. What an SDK can do is as much a
+    // reason to choose it as which language it is in, and a reader who has to
+    // scroll past every language section to discover that retries, caching and
+    // tracing are built in has already decided it is a thin HTTP wrapper.
+    // Named here, in one line, with the detail left to each target's README.
+    const features = featureDocs(model)
+    if (0 < features.length) {
+      Content(`> **Features:** ${features.map((f: any) => '`' + f.name + '`').join(', ')} — opt-in,
+> inactive until switched on, and configured per client. See the Features
+> section of any SDK README below for what each one does.
+
 `)
     }
 
@@ -561,6 +576,39 @@ forking the SDK.
     Content(`
 Pass custom features via the \`extend\` option at construction time.
 
+`)
+
+    // 11c. Customization — the generator's whole story for "the output is
+    // not quite right": model-driven declarations, in-repo templates and
+    // components, merge-aware regeneration, and packages for custom targets
+    // and features. Every SDK repo carries its own generator, so this
+    // belongs in every README.
+    Content(`## Customizing this SDK
+
+This repository contains its own generator (\`.sdk/\`), so the SDK is
+customizable without forking any upstream tool:
+
+- **The model** (\`.sdk/model/\`) declares everything this project owns:
+  package names, versions, active features, per-target settings. It is
+  written in [aontu](https://github.com/aontu-lang/aontu), a JSON-based
+  specification language designed for building ontologies: easy to edit
+  by hand, and files unify rather than override, so small declarations
+  compose into one model. Regeneration re-reads it every time.
+- **Templates** (\`.sdk/tm/\`) and **components** (\`.sdk/src/cmp/\`) are
+  the two layers of generation, copied into this repo: templates are the
+  literal per-language source, components generate the API-shaped parts.
+- **Regeneration merges.** By default, newly generated content is
+  three-way merged into existing files, so generator updates and local
+  edits usually converge without manual conflict handling. A project can
+  opt for plain overwrite instead.
+- **Custom features and entire custom targets** arrive through sdkgen
+  packages (\`voxgig-sdkgen package add\`), on the same rails as the
+  bundled languages, and \`voxgig-sdkgen doctor\` reports any drift from
+  what a resync would write.
+
+How-to: [customize and propagate templates](https://github.com/voxgig/sdkgen/blob/main/docs/how-to/customize-and-propagate-templates.md).
+The full story: [voxgig.com/sdk/custom](https://voxgig.com/sdk/custom).
+
 `)
 
     // 12. Per-language docs links

package/src/helpers/opShape.ts

@@ -269,7 +269,11 @@ function opParams(op: any): any[] {
   const out: any[] = []
 
   points.forEach((pt: any, pointIndex: number) => {
-    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    // Path AND query: a path-param-only read misses e.g. GET /result?trace_id=,
+    // which has no path param at all but still addresses one record.
+    const pathParams = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    const queryParams = pt && pt.args && pt.args.query ? each(pt.args.query) : []
+    const params = [...pathParams, ...queryParams]
     const requiredHere: Record<string, boolean> = {}
     params.forEach((p: any) => {
       if (p && null != p.name) {

package/src/sdkgen.ts

@@ -17,7 +17,7 @@ import type {
   ActionResult,
 } from './types'
 
-import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix,
+import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix, isHttpBasicAuth,
   CONFIG_DATA_THRESHOLD, CONFIG_REPR_VALUES, isConfigData, configRepr,
   configReprSetting, configDefinition, clean, rawStringLiteral } from './utility'
 
@@ -49,6 +49,7 @@ import { ReadmeEntity } from './cmp/ReadmeEntity'
 import { ReadmeHowto } from './cmp/ReadmeHowto'
 import { ReadmeExplanation } from './cmp/ReadmeExplanation'
 import { ReadmeRef } from './cmp/ReadmeRef'
+import { ReadmeRefFeatures } from './cmp/ReadmeRefFeatures'
 import { FeatureHook } from './cmp/FeatureHook'
 import { registerComponent } from './cmp/Registered'
 import type { RegisterOptions } from './cmp/Registered'
@@ -392,10 +393,20 @@ function SdkGen(opts: SdkGenOptions) {
       // A skipped external target is still removed from the in-tree model
       // above: neither `active: false` nor a missing `output.create: false`
       // destination may relocate it into `<sdk-repo>/<target>/`.
-      if (null != ext.skip) {
+      // The snapshot is deliberately not re-taken to ADMIT an item: a
+      // destination that appeared since would be written without ever having
+      // been ownership-validated. Re-taking it to SKIP one is the opposite
+      // direction and cannot open that hole. Without this, an optional
+      // destination deleted or moved between the snapshot and this pass is
+      // recreated by jostraca's ensureDir — exactly what `output.create:
+      // false` promises not to do.
+      const gone = false === ext.target.output?.create && !fs.existsSync(ext.folder)
+
+      if (null != ext.skip || gone) {
         log.info({
           point: 'generate-external-skip', target: ext.name, folder: ext.folder,
-          note: ext.skip
+          note: ext.skip ?? (ext.name + ' output folder disappeared after ' +
+            'preflight and output.create=false, not generated')
         })
         continue
       }
@@ -794,10 +805,18 @@ function checkExternalFolders(external: ExternalPlan[], root: string, fs: any) {
   const claimed: Record<string, string> = {}
 
   for (const ext of external) {
-    // A skipped item writes nothing, so its destination is not a hazard. The
-    // snapshotted decision gates the actual pass too; keeping it identical is
-    // what makes the pre-write check complete.
-    if (null != ext.skip) continue
+    // An INACTIVE item writes nothing and claims nothing: it is out of the
+    // model for this run.
+    //
+    // An item skipped only because its optional destination is absent is a
+    // different case. Path containment and the duplicate claim are model
+    // invariants — they do not depend on folder contents — so skipping them
+    // here let two items claim one absent path: the ordinary one generated
+    // there, and the NEXT identical run then saw the folder, detected the
+    // duplicate, and refused everything. The failure appeared one run after
+    // the mistake. Validate the path; the `existsSync` guard below still
+    // skips every check that reads the folder.
+    if (!ext.active) continue
 
     const label = ext.kind.charAt(0).toUpperCase() + ext.kind.slice(1)
 
@@ -1067,6 +1086,7 @@ export {
   ReadmeHowto,
   ReadmeExplanation,
   ReadmeRef,
+  ReadmeRefFeatures,
   FeatureHook,
   registerComponent,
 
@@ -1076,6 +1096,7 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  isHttpBasicAuth,
   CONFIG_DATA_THRESHOLD,
   CONFIG_REPR_VALUES,
   isConfigData,

package/src/utility.ts

@@ -62,6 +62,24 @@ function resolveAuthPrefix(model: any): string {
 }
 
 
+// True when the spec's security scheme is genuine HTTP Basic Auth (two
+// credentials, base64-joined) rather than a single bearer-style token with
+// a prefix. Priority order mirrors resolveAuthPrefix:
+//   1. main.kit.config.auth.basic     (per-SDK user override)
+//   2. main.kit.info.security, spec-derived: type 'http' + a 'basic' prefix
+//      (apidef sets prefix from the OpenAPI `scheme: basic` value, title-cased)
+function isHttpBasicAuth(model: any): boolean {
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+    { only_active: false, required: false })
+  if (null != auth && null != auth.basic) return Boolean(auth.basic)
+
+  const security = getModelPath(model, `main.${KIT}.info.security`,
+    { only_active: false, required: false })
+  return null != security && 'http' === security.type &&
+    'basic' === String(security.prefix || '').toLowerCase()
+}
+
+
 function requirePath(ctx$: any, path: string, flags?: { ignore?: boolean }): any {
   const fullpath = resolvePath(ctx$, path)
   const ignore = null == flags?.ignore ? false : flags.ignore
@@ -98,6 +116,7 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  isHttpBasicAuth,
   SdkGenError,
   CONFIG_DATA_THRESHOLD,
   CONFIG_REPR_VALUES,
@@ -298,6 +317,7 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
 
   const authActive = isAuthActive(model)
   const authPrefix = resolveAuthPrefix(model)
+  const authBasic = isHttpBasicAuth(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
@@ -340,7 +360,7 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
     options.server = svars.reduce((a: any, v: any) => (a[v.name] = v.dflt, a), {})
   }
   if (authActive) {
-    options.auth = { prefix: authPrefix }
+    options.auth = authBasic ? { prefix: authPrefix, basic: true } : { prefix: authPrefix }
   }
   options.headers = headers
   options.entity = entityStubs