@voxgig/sdkgen 4.5.3 → 4.7.0

package/src/cmp/ReadmeFeatures.ts

@@ -27,7 +27,7 @@ const ReadmeFeatures = cmp(function ReadmeFeatures(props: any) {
     return
   }
 
-  const features: FeatureDoc[] = featureDocs(model)
+  const features: FeatureDoc[] = featureDocs(model, target)
 
   if (0 === features.length) {
     return

package/src/cmp/ReadmeRefFeatures.ts

@@ -19,7 +19,7 @@ const ReadmeRefFeatures = cmp(function ReadmeRefFeatures(props: any) {
   const { target, ctx$ } = props
   const { model } = ctx$
 
-  const features: FeatureDoc[] = featureDocs(model)
+  const features: FeatureDoc[] = featureDocs(model, target)
 
   if (0 === features.length) {
     return

package/src/cmp/TestControl.ts

@@ -0,0 +1,64 @@
+import Path from 'node:path'
+
+import {
+  cmp,
+  File,
+  Fragment,
+} from 'jostraca'
+
+
+const TEST_CONTROL_FILE = 'sdk-test-control.json'
+
+
+// Keep the blanket per-target `Copy({ from: 'tm/<lang>' })` from restoring the
+// template default over a project's edited control file. One regex for every
+// target: the file sits under `test/`, `t/`, `tests/` or `sdktest/` depending
+// on the language, and the name is what identifies it either way.
+const TEST_CONTROL_EXCLUDE = new RegExp('(^|/)' + TEST_CONTROL_FILE + '$')
+
+
+// `sdk-test-control.json` is the ONE generated file a project is meant to edit
+// by hand: it names the tests to skip, the live pacing, and the extra client
+// options a live run needs (`test.client.options`).
+//
+// It shipped as part of each target's blanket `Copy({ from: 'tm/<lang>' })`,
+// and a Copy has no per-file "leave it alone if it already exists" — so every
+// `npm run generate` overwrote whatever the project had put there. The
+// documented workaround, editing the template master under `.sdk/tm/`, is
+// worse: `doctor` reports it as drift and the next `target add <lang>` reverts
+// it.
+//
+// So it is emitted HERE instead, write-once: `File({ exclude: true })` returns
+// early when the file already exists (FileOp), which is exactly the semantics
+// the file is documented to have. A project without one yet gets the
+// template's default; a project that has edited one keeps its edits across
+// both `generate` and `target add`.
+//
+// The content still comes from the target's own template, so there remains
+// exactly one copy of the default on disk.
+//
+// The template is addressed the SAME way the Copy this replaces addressed it:
+// `tm/<lang>/...` relative to the working directory, which is the project's
+// `.sdk`. Resolved to absolute here because Fragment resolves a RELATIVE
+// `from` against the OUTPUT folder instead — a different base, and the one
+// place these two could silently disagree.
+const TestControl = cmp(function TestControl(props: {
+  target: { name: string }
+  dir: string
+  ctx$?: any
+}) {
+  const { target, dir } = props
+
+  File({ name: TEST_CONTROL_FILE, exclude: true }, () => {
+    Fragment({
+      from: Path.resolve('tm', target.name, dir, TEST_CONTROL_FILE)
+    })
+  })
+})
+
+
+export {
+  TestControl,
+  TEST_CONTROL_FILE,
+  TEST_CONTROL_EXCLUDE,
+}

package/src/helpers/applicability.ts

@@ -0,0 +1,123 @@
+// Which features a target can actually take.
+//
+// THE ONE PLACE THIS RULE LIVES. `Feature` (what source is copied), the
+// per-language `Config_<lang>` and `Main_<lang>` components (what the
+// generated registry, imports and metadata contain) and `configDefinition`
+// (the embedded config) must all reach the same answer for one
+// (feature, target) pair. They previously each read the raw feature map,
+// which is how a feature with no source for a target still reached that
+// target's imports.
+//
+// The shape is `docs/design/feature-tags.md`: a feature declares what it
+// NEEDS, a target declares what it PROVIDES, and the feature applies when
+// `needs` is a subset of `provides`. Both default to empty, so a feature
+// that needs nothing applies everywhere — every feature that existed
+// before this gate keeps its behaviour with no model edit, which is what
+// makes the change additive.
+//
+// A named target list was the cheaper design and fails on time: it has to
+// be edited for targets the feature's author has never heard of, so a
+// published package starves every target added after its release. A tag is
+// a claim about the feature that stays true as the target set grows.
+
+import { KIT, getModelPath } from '@voxgig/apidef'
+
+
+// Tags are a MAP keyed by tag name, `{ sekreto: true }` — see the schema
+// note on `needs`. A map because aontu unifies maps by key, so a package
+// can add one tag without restating the others; and because a defaulted
+// list disjunction in this position hangs the unifier on a real project's
+// model. A tag counts only when its value is true, so a tag can be turned
+// off by overriding it rather than by deleting the key.
+//
+// A list is still accepted, for a hand-written model that used the shape
+// docs/design/feature-tags.md first proposed.
+function tags(val: any): string[] {
+  if (Array.isArray(val)) {
+    return val.filter((t: any) => 'string' === typeof t)
+  }
+
+  if (null == val || 'object' !== typeof val) {
+    return []
+  }
+
+  return Object.keys(val).filter((name: string) => true === val[name])
+}
+
+
+// Does this feature apply to this target?
+function featureApplies(feature: any, target: any): boolean {
+  const needs = tags(feature && feature.needs)
+
+  // The common case, and the reason this is additive: no needs, applies
+  // anywhere. Checked first so a target with no `provides` is unaffected.
+  if (0 === needs.length) {
+    return true
+  }
+
+  const provides = tags(target && target.provides)
+
+  return needs.every((need: string) => provides.includes(need))
+}
+
+
+// The features that apply to `target`, in the same map shape
+// `getModelPath(model, 'main.<kit>.feature')` returns — already
+// active-filtered by getModelPath, then gated by the tags.
+//
+// `target` may be the target object or its name; components hold the
+// object, `configDefinition` is only given the name.
+function targetFeatures(model: any, target: any): Record<string, any> {
+  const feature = getModelPath(model, `main.${KIT}.feature`, { required: false }) || {}
+
+  const t = 'string' === typeof target ?
+    (getModelPath(model, `main.${KIT}.target`, { required: false }) || {})[target] :
+    target
+
+  // A name that names no target gates nothing: a caller that cannot say
+  // which target it is generating for must not silently lose features.
+  if (null == t) {
+    return feature
+  }
+
+  // Keyed off the map, not off `f.name`: the key is what every consumer
+  // indexes by, and rebuilding from a field would drop an entry whose
+  // model never set one. Order is not preserved on purpose — consumers
+  // re-sort with `each`, which is what keeps output byte-stable.
+  const applies: Record<string, any> = {}
+  for (const [name, f] of Object.entries(feature as Record<string, any>)) {
+    if (featureApplies(f, t)) {
+      applies[name] = f
+    }
+  }
+
+  return applies
+}
+
+
+// THE CLOSED VOCABULARY. The schema comment says applicability tags are a
+// closed set; without this, `provides: &: boolean` accepts any key, so a
+// typo (`sekrreto`) compiles cleanly and silently makes the feature apply
+// NOWHERE — the worst failure shape, because the feature simply vanishes
+// with no diagnostic.
+//
+// Extended by adding a tag here AND documenting it in model/sdkgen.aon.
+const TAGS = [
+  // A vendored sekreto port lives in this target's feature container.
+  'sekreto',
+]
+
+
+// The tags named by `needs`/`provides` that are not in the vocabulary.
+function unknownTags(val: any): string[] {
+  return tags(val).filter((t: string) => !TAGS.includes(t))
+}
+
+
+export {
+  featureApplies,
+  targetFeatures,
+  tags as featureTags,
+  unknownTags,
+  TAGS,
+}

package/src/helpers/collectDeps.ts

@@ -11,6 +11,8 @@
 // need extra fields like `dep.replace` (go module replace directives) or
 // `dep.kind` (prod/dev/peer).
 
+import { targetFeatures } from './applicability'
+
 import { each } from 'jostraca'
 import { KIT, getModelPath } from '@voxgig/apidef'
 
@@ -30,7 +32,9 @@ function collectDeps(
   log?: any,
 ): DepEntry[] {
   const out: DepEntry[] = []
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated: a feature that does not apply to this target must not flow a
+  // dependency into its generated manifest.
+  const feature = targetFeatures(model, targetName)
 
   // Deduplicate by package name. Two features can require the same package
   // (or a feature and the target itself can), and every Package_<lang>.ts

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/serverVars.ts

@@ -88,6 +88,24 @@ function serverVariables(model: any): ServerVar[] {
 }
 
 
+// The environment variable a generated LIVE test reads one server variable
+// from: `<PROJ>_SERVER_<NAME>`, e.g. ELEMENTDEMO_SERVER_ACCOUNT_ID.
+//
+// A live client CANNOT BE CONSTRUCTED without every required server
+// variable — makeOptions raises rather than issue requests to a URL with a
+// literal `{account_id}` in it — so an SDK whose spec templates its server
+// URL had no runnable live suite at all until the generated tests could be
+// told the values. The apikey has had `<PROJ>_APIKEY` since the beginning;
+// this is the same idea for the other half of "where do I point".
+//
+// One variable per NAME rather than one JSON blob: the names come from the
+// spec, they are few, and a shell export per name is what a CI secret store
+// and a .env file both hold naturally.
+function serverVarEnv(projenvname: string, name: string): string {
+  return projenvname + '_SERVER_' + String(name).toUpperCase()
+}
+
+
 // Does the model's server URL contain any {name} placeholders at all?
 function hasServerVariables(model: any): boolean {
   const info = model?.main?.kit?.info || model?.main?.KIT?.info
@@ -100,6 +118,7 @@ function hasServerVariables(model: any): boolean {
 export {
   serverVariables,
   hasServerVariables,
+  serverVarEnv,
 }
 
 export type { ServerVar }

package/src/sdkgen.ts

@@ -22,6 +22,7 @@ import { SdkGenError, requirePath, isAuthActive, resolveAuthPrefix, isHttpBasicA
   configReprSetting, configDefinition, clean, rawStringLiteral } from './utility'
 
 import { Main } from './cmp/Main'
+import { featureApplies, targetFeatures, featureTags, unknownTags, TAGS } from './helpers/applicability'
 import { ExternalTarget } from './cmp/ExternalTarget'
 import { Docs, DocsItem } from './cmp/Docs'
 import { ExternalDocs } from './cmp/ExternalDocs'
@@ -39,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'
@@ -61,7 +63,7 @@ import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, canonToDtype, canonKey, canonScalarKey } from './helpers/canonType'
 import { OP_SUFFIX, opTypeName, opParams, ownPoint, opActions, entityActions, entityPath, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName, entityTypeCollisions, warnEntityTypeCollisions, deriveEntityNames, entityCollection } from './helpers/opShape'
 import { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, isPhpSdkClass, phpSafeTypeName, isTsReservedType, tsSafeTypeName, jsProp, jsOptProp, jsKey } from './helpers/naming'
-import { serverVariables, hasServerVariables } from './helpers/serverVars'
+import { serverVariables, hasServerVariables, serverVarEnv } from './helpers/serverVars'
 import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
 import type { ExampleLang } from './helpers/opExample'
 import { liveStrict } from './helpers/testPolicy'
@@ -72,6 +74,8 @@ import {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
 } from './helpers/featureSource'
 import type { FeatureSource } from './helpers/featureSource'
 import { stationLibrary } from './helpers/station'
@@ -1071,6 +1075,8 @@ export {
   Entity,
   Feature,
   Test,
+  TestControl,
+  TEST_CONTROL_EXCLUDE,
   Readme,
   ReadmeTop,
   AgentGuideTop,
@@ -1153,6 +1159,7 @@ export {
   tsSafeTypeName,
   serverVariables,
   hasServerVariables,
+  serverVarEnv,
   liveStrict,
   primaryOpCall,
   idLiteral,
@@ -1165,8 +1172,16 @@ export {
   featureExcludes,
   fullsetExcludes,
   srcFeatureExcludes,
+  pluginExcludes,
+  pluginExcludesFor,
   stationLibrary,
 
+  featureApplies,
+  targetFeatures,
+  featureTags,
+  unknownTags,
+  TAGS,
+
   definitionPath,
   definitionFolder,
   definitionNames,

package/src/utility.ts

@@ -5,6 +5,8 @@ import { JostracaResult, each } from 'jostraca'
 
 import { KIT, getModelPath } from '@voxgig/apidef'
 
+import { targetFeatures } from './helpers/applicability'
+
 import { serverVariables } from './helpers/serverVars'
 import { packageVersion } from './helpers/packageMeta'
 
@@ -80,6 +82,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
@@ -116,6 +146,7 @@ export {
   requirePath,
   isAuthActive,
   resolveAuthPrefix,
+  resolveAuthExchange,
   isHttpBasicAuth,
   SdkGenError,
   CONFIG_DATA_THRESHOLD,
@@ -299,6 +330,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,7 +352,14 @@ function rawStringLiteral(s: string): string {
 // across runs exactly like the literal it replaces.
 function configDefinition(model: any, targetname?: string): { def: any, json: string } {
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  // Gated by the target when one is named, so the embedded config cannot
+  // advertise a feature this target has no implementation for — the exact
+  // hybrid state the applicability gate exists to prevent. With no
+  // targetname (a caller that cannot say which target it is building) the
+  // helper returns every active feature, i.e. the old behaviour.
+  const feature = targetFeatures(model, targetname)
+
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
@@ -352,6 +399,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
   })