@voxgig/sdkgen 4.6.0 → 4.8.0

package/src/helpers/featureSource.ts

@@ -260,6 +260,134 @@ 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 }) || {}
+
+  const out: RegExp[] = []
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  for (const pname of Object.keys(plugins).sort()) {
+    const plugin = plugins[pname]
+    if (false !== plugin?.active) continue
+
+    const declared = plugin.path || []
+
+    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)
+        out.push(new RegExp('(^|/)' + pat.replace(/\\\/$/, '') +
+          (/\/$/.test(rel) ? '/' : '$')))
+      }
+      continue
+    }
+
+    out.push(new RegExp('(^|/)plugin/' + esc(pname) + '/'))
+  }
+
+  return out
+}
+
+
+function pluginExcludes(model: any): RegExp[] {
+  const active = getModelPath(model, `main.${KIT}.feature`,
+    { required: false }) || {}
+
+  const out: RegExp[] = []
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+  for (const fname of Object.keys(active)) {
+    const all = getModelPath(model,
+      `main.${KIT}.feature.${fname}.plugin`,
+      { required: false, only_active: false }) || {}
+    const on = getModelPath(model,
+      `main.${KIT}.feature.${fname}.plugin`,
+      { required: false }) || {}
+
+    for (const pname of Object.keys(all)) {
+      if (null != on[pname]) continue
+
+      // DECLARED paths first. A plugin's files are often not free to
+      // move — sekreto's provider modules are vendored, and both the
+      // vendoring guard and their own relative imports pin them at
+      // upstream's directory depth — so a plugin says which paths it
+      // owns rather than being assumed to own a directory.
+      const declared = all[pname].path || []
+
+      if (0 < declared.length) {
+        for (const one of declared) {
+          const pat = esc(String(one))
+          // A trailing slash means a folder and everything under it;
+          // anything else matches that path exactly, as featureExcludes
+          // does for a file source.
+          out.push(new RegExp('(^|/)' + pat.replace(/\\\/$/, '') +
+            (/\/$/.test(String(one)) ? '/' : '$')))
+        }
+        continue
+      }
+
+      out.push(new RegExp(
+        '(^|/)src/feature/' + esc(fname) + '/plugin/' + esc(pname) + '/'))
+    }
+  }
+
+  return out
+}
+
+
 export type {
   FeatureSource,
   FeatureEntry,
@@ -275,4 +403,6 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
 }

package/src/helpers/opShape.ts

@@ -29,6 +29,8 @@
 import { each, names } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
 
+import { pointSegments, pointTerminalParam, pointPathKey } from './pointPath'
+
 
 // THE entity collection for a model — resolved once, with a stable identity.
 //
@@ -217,25 +219,19 @@ function entityPath(entity: any): string {
 // no point's `select.exist` matches. It cannot be shared with them — a
 // template ships standalone, outside this package — so it is written twice on
 // purpose, and both sides must move together.
-function terminalParam(point: any): boolean {
-  const parts: any[] = (point && point.parts) || []
-  const last = 0 < parts.length ? parts[parts.length - 1] : ''
-  return 'string' === typeof last && last.startsWith('{')
-}
-
-
 function ownPoint(points: any[]): any {
   let best = points[0]
 
   for (const pt of points) {
-    if (null == pt || null == pt.parts || null == best || null == best.parts) {
+    if (null == pt || null == pt.segments || null == best || null == best.segments) {
       continue
     }
 
-    const ptterm = terminalParam(pt)
-    const bestterm = terminalParam(best)
+    const ptterm = pointTerminalParam(pt)
+    const bestterm = pointTerminalParam(best)
 
-    if (ptterm !== bestterm ? ptterm : pt.parts.length < best.parts.length) {
+    if (ptterm !== bestterm ?
+      ptterm : pointSegments(pt).length < pointSegments(best).length) {
       best = pt
     }
   }
@@ -248,10 +244,9 @@ function ownPoint(points: any[]): any {
 // selectors on one endpoint (the same path, chosen by different query
 // params), not cross-references to different resources.
 function samePath(points: any[]): boolean {
-  const first = ((points[0] && points[0].parts) || []).join('/')
+  const first = pointPathKey(points[0])
 
-  return points.every((pt: any) =>
-    first === ((pt && pt.parts) || []).join('/'))
+  return points.every((pt: any) => first === pointPathKey(pt))
 }
 
 

package/src/helpers/pointPath.ts

@@ -0,0 +1,88 @@
+/* Copyright (c) 2024-2025 Voxgig, MIT License */
+
+// A point's path, as apidef resolves it.
+//
+// apidef ADR-003: the model carries the path as a typed segment vector —
+// `[{ lit: 'element' }, { var: 'id' }]` — and no brace-templated string. A
+// `var` names one of the point's `args.params` directly, so a consumer walks
+// the vector instead of parsing anything.
+//
+// The generated SDK runtimes still speak the older braced-string form
+// (`['element', '{id}']`), which this file reconstructs in ONE place. Every
+// generation-time consumer and the embedded config go through here, so when
+// the runtimes move onto segments there is a single call site to retire —
+// rather than the twenty-odd hand-written brace parsers ADR-003 is about.
+
+
+type PathSegment = {
+  lit?: string
+  var?: string
+}
+
+
+// The segment vector, defensively. GraphQL points address the single endpoint
+// and carry no path, so an empty vector is normal, not a fault.
+function pointSegments(point: any): PathSegment[] {
+  const segments = point && point.segments
+  return Array.isArray(segments) ? segments : []
+}
+
+
+// The braced-string form the SDK runtimes still consume. A `lit` is emitted
+// verbatim — including one that contains braces, which apidef leaves literal
+// (a compound element like `{a}.{b}` names no single parameter). That is the
+// lossiness ADR-003 removed from the model, and it survives here only because
+// this is the OLD representation being reconstructed on the way out.
+function pointParts(point: any): string[] {
+  return pointSegments(point).map((seg: PathSegment) =>
+    null == seg.var ? String(seg.lit ?? '') : '{' + seg.var + '}')
+}
+
+
+// Does the path end in a parameter?
+//
+// DELIBERATELY asked of the reconstructed part, not of the vector, even
+// though the vector states it directly and more accurately.
+//
+// The same rule runs at RUNTIME, in all 21 languages' makePoint template
+// (`0 === last.indexOf('{')` over `parts`), to pick a fallback route when no
+// point's `select.exist` matches. Those templates ship standalone, outside
+// this package, so the rule is written twice on purpose and BOTH SIDES MUST
+// MOVE TOGETHER — see the note in opShape.ts and in each template.
+//
+// Reading the vector here would break that. A path ending in a LITERAL that
+// contains braces (`/reports/{id}.json`) is not a terminal parameter by the
+// vector, but every runtime still says it is, because from the reconstructed
+// string it cannot tell. Generation-time `ownPoint` would then pick a
+// different route than the SDK picks at request time — for the same model.
+//
+// So this stays bug-compatible with the runtimes until they move onto
+// segments, at which point this becomes `null != last.var` and all 21 change
+// with it.
+function pointTerminalParam(point: any): boolean {
+  const parts = pointParts(point)
+  const last = 0 < parts.length ? parts[parts.length - 1] : ''
+  return 0 === last.indexOf('{')
+}
+
+
+// Do two points describe the same route? Compares the vectors, so a literal
+// containing braces cannot be mistaken for a parameter of the same spelling.
+function pointPathKey(point: any): string {
+  return pointSegments(point)
+    .map((seg: PathSegment) =>
+      null == seg.var ? 'l:' + String(seg.lit ?? '') : 'v:' + seg.var)
+    .join('/')
+}
+
+
+export type {
+  PathSegment,
+}
+
+export {
+  pointSegments,
+  pointParts,
+  pointTerminalParam,
+  pointPathKey,
+}

package/src/sdkgen.ts

@@ -40,6 +40,7 @@ import { License } from './cmp/License'
 import { Security } from './cmp/Security'
 import { Changelog } from './cmp/Changelog'
 import { Test } from './cmp/Test'
+import { TestControl, TEST_CONTROL_EXCLUDE } from './cmp/TestControl'
 import { ReadmeInstall } from './cmp/ReadmeInstall'
 import { ReadmeQuick } from './cmp/ReadmeQuick'
 import { ReadmeErrors } from './cmp/ReadmeErrors'
@@ -66,6 +67,9 @@ import { serverVariables, hasServerVariables, serverVarEnv } from './helpers/ser
 import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
 import type { ExampleLang } from './helpers/opExample'
 import { liveStrict } from './helpers/testPolicy'
+import { pointSegments, pointParts, pointTerminalParam, pointPathKey }
+  from './helpers/pointPath'
+import type { PathSegment } from './helpers/pointPath'
 import {
   featureOf,
   availableFeatures,
@@ -73,6 +77,8 @@ import {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
 } from './helpers/featureSource'
 import type { FeatureSource } from './helpers/featureSource'
 import { stationLibrary } from './helpers/station'
@@ -1011,6 +1017,7 @@ export type {
   SdkGenOptions,
   ExampleLang,
   DepEntry,
+  PathSegment,
   FeatureSource,
   DoctorReport,
   RegisterOptions,
@@ -1072,6 +1079,8 @@ export {
   Entity,
   Feature,
   Test,
+  TestControl,
+  TEST_CONTROL_EXCLUDE,
   Readme,
   ReadmeTop,
   AgentGuideTop,
@@ -1114,6 +1123,13 @@ export {
   buildIdNames,
   getMatchEntries,
   collectDeps,
+
+  // apidef ADR-003: the model carries typed path segments, not braced
+  // strings. Scaffold components read the path through these.
+  pointSegments,
+  pointParts,
+  pointTerminalParam,
+  pointPathKey,
   canonToType,
   canonToDtype,
   canonKey,
@@ -1167,6 +1183,8 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
   stationLibrary,
 
   featureApplies,

package/src/utility.ts

@@ -8,6 +8,7 @@ import { KIT, getModelPath } from '@voxgig/apidef'
 import { targetFeatures } from './helpers/applicability'
 
 import { serverVariables } from './helpers/serverVars'
+import { pointParts } from './helpers/pointPath'
 import { packageVersion } from './helpers/packageMeta'
 
 
@@ -82,6 +83,34 @@ function isHttpBasicAuth(model: any): boolean {
 }
 
 
+// The API's ACCESS-TOKEN EXCHANGE, as apidef recorded it from the spec
+// (main.kit.info.security.exchange): where the token endpoint lives, and the
+// field names it sends and answers with. Null when the spec describes none,
+// which is the common case.
+//
+// These are FACTS ABOUT THE API, so they belong in the generated config
+// rather than in a project's hand-written model: an SDK whose spec says the
+// exchange is at `auth/token` should not need to be told so again. A feature
+// opts in to receiving them with `spec: { authexchange: '<options-key>' }`;
+// configDefinition does the overlay.
+//
+// Deliberately NOT included: `active`. Whether a client performs the
+// exchange is the project's decision (some resolve a static credential
+// through the same feature on an API that also has a token endpoint), so
+// apidef records only what the exchange IS, never that it should run.
+function resolveAuthExchange(model: any): Record<string, any> | null {
+  const security = getModelPath(model, `main.${KIT}.info.security`,
+    { only_active: false, required: false })
+
+  const exchange = security?.exchange
+  if (null == exchange || 'object' !== typeof exchange) {
+    return null
+  }
+
+  return exchange
+}
+
+
 function requirePath(ctx$: any, path: string, flags?: { ignore?: boolean }): any {
   const fullpath = resolvePath(ctx$, path)
   const ignore = null == flags?.ignore ? false : flags.ignore
@@ -118,6 +147,7 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  resolveAuthExchange,
   isHttpBasicAuth,
   SdkGenError,
   CONFIG_DATA_THRESHOLD,
@@ -301,6 +331,15 @@ function rawStringLiteral(s: string): string {
 }
 
 
+// The closed vocabulary of spec-derived facts a feature may ask for by
+// declaring `spec: { <fact>: <options-key> }`. Closed, and resolved through
+// one function each, so a feature cannot reach arbitrarily into the model
+// and a fact's shape is defined in exactly one place.
+const SPEC_FACTS: Record<string, (model: any) => any> = {
+  authexchange: resolveAuthExchange,
+}
+
+
 // THE CANONICAL CONFIG OBJECT, and the JSON the threshold is measured on.
 //
 // Every target builds its config from this one function, so the literal a
@@ -312,6 +351,35 @@ function rawStringLiteral(s: string): string {
 //
 // Key order is `each`'s order, which is sorted, so the JSON is byte-stable
 // across runs exactly like the literal it replaces.
+// The embedded config still speaks the braced-string path form
+// (`['element', '{id}']`) that every generated runtime reads. apidef now
+// emits the resolved vector instead (its ADR-003), so the old shape is
+// reconstructed HERE — the single point at which a point reaches generated
+// output — via the single reconstruction in helpers/pointPath.
+//
+// Both are written: `parts` for the runtimes as they stand, `segments`
+// alongside it so a runtime can be moved over one language at a time. That
+// duplication is deliberate and temporary, and it lives in GENERATED output,
+// not in the model — which is what ADR-003 forbids. It ends when the last
+// runtime reads segments and `parts` is dropped from this function.
+function withPointParts(op: any): any {
+  if (null == op) {
+    return op
+  }
+
+  const out: any = {}
+  each(op, (o: any, opname: string) => {
+    out[opname] = null == o || null == o.points ? o : {
+      ...o,
+      points: each(o.points).map((pt: any) =>
+        null == pt ? pt : { ...pt, parts: pointParts(pt) }),
+    }
+  })
+
+  return out
+}
+
+
 function configDefinition(model: any, targetname?: string): { def: any, json: string } {
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
@@ -339,7 +407,7 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
     entityDefs[e.name] = clean({
       fields: e.fields,
       name: e.name,
-      op: e.op,
+      op: withPointParts(e.op),
       relations: e.relations,
     }, true)
     entityStubs[e.name] = {}
@@ -361,6 +429,29 @@ function configDefinition(model: any, targetname?: string): { def: any, json: st
     if (null != f.transport && '' !== f.transport) {
       fdef.transport = String(f.transport)
     }
+
+    // SPEC-DERIVED OPTIONS. A feature declares `spec: { <fact>: <options
+    // key> }` to receive facts apidef recorded from the OpenAPI spec — the
+    // same declare-never-infer rule `needs` and `transport` follow, and for
+    // the same reason: the alternative is this function knowing feature
+    // names, which is exactly the coupling the generic feature loop exists
+    // to avoid.
+    //
+    // The fact overlays the feature's DECLARED DEFAULTS, and rightly: a
+    // default like `path: 'auth/token'` is a generic guess, while the spec
+    // states where this API's endpoint actually is. A project that needs
+    // something else still overrides at runtime through `options.feature`,
+    // which beats the embedded config either way.
+    for (const factname of Object.keys(f.spec || {}).sort()) {
+      const optkey = f.spec[factname]
+      const fact = SPEC_FACTS[factname]?.(model)
+      if (null == fact || null == optkey || '' === optkey) {
+        continue
+      }
+      fdef.options = { ...(fdef.options || {}) }
+      fdef.options[optkey] = { ...(fdef.options[optkey] || {}), ...fact }
+    }
+
     featureDefs[f.name] = fdef
   })