@voxgig/sdkgen 4.5.3 → 4.6.0

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/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'
@@ -61,7 +62,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'
@@ -1153,6 +1154,7 @@ export {
   tsSafeTypeName,
   serverVariables,
   hasServerVariables,
+  serverVarEnv,
   liveStrict,
   primaryOpCall,
   idLiteral,
@@ -1167,6 +1169,12 @@ export {
   srcFeatureExcludes,
   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'
 
@@ -312,7 +314,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)

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

@@ -1,425 +0,0 @@
-// VERSION: @voxgig/struct 0.0.10
-// This test utility runs the JSON-specified tests in build/test/test.json.
-// (or .sdk/test/test.json if used in a @voxgig/sdkgen project)
-
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { deepStrictEqual, fail, AssertionError } from 'node:assert'
-
-const NULLMARK = '__NULL__' // Value is JSON null
-const UNDEFMARK = '__UNDEF__' // Value is not present (thus, undefined).
-const EXISTSMARK = '__EXISTS__' // Value exists (not undefined).
-
-
-type Subject = (...args: any[]) => any
-type RunSet = (testspec: any, testsubject: Function) => Promise<any>
-type RunSetFlags = (testspec: any, flags: Record<string, boolean>, testsubject: Function)
-  => Promise<any>
-
-
-type RunPack = {
-  spec: Record<string, any>
-  runset: RunSet
-  runsetflags: RunSetFlags
-  subject: Subject
-  client: any
-}
-
-
-type TestPack = {
-  name?: string
-  client: any
-  subject: Subject
-  utility: any
-}
-
-type Flags = Record<string, boolean>
-
-
-type Utility = {
-  struct: any
-  makeContext: (ctxmap: Record<string, any>, basectx?: any) => any
-}
-
-
-type Client = {
-  utility: () => Utility
-}
-
-
-async function makeRunner(testfile: string, client: Client) {
-
-  return async function runner(
-    name: string,
-    store?: any,
-  ): Promise<RunPack> {
-    store = store || {}
-
-    const utility = client.utility()
-    const structUtils = utility.struct
-
-    let spec = resolveSpec(name, testfile)
-    let clients = await resolveClients(client, spec, store, structUtils)
-    let subject = resolveSubject(name, utility)
-
-    let runsetflags: RunSetFlags = async (
-      testspec: any,
-      flags: Flags,
-      testsubject: Function
-    ) => {
-      subject = testsubject || subject
-      flags = resolveFlags(flags)
-      const testspecmap = fixJSON(testspec, flags)
-
-      const testset: any[] = testspecmap.set
-      for (let entry of testset) {
-        try {
-          entry = resolveEntry(entry, flags)
-
-          let testpack = resolveTestPack(name, entry, subject, client, clients)
-          let args = resolveArgs(entry, testpack, utility, structUtils)
-
-          let res = await testpack.subject(...args)
-          res = fixJSON(res, flags)
-          entry.res = res
-
-          checkResult(entry, args, res, structUtils)
-        }
-        catch (err: any) {
-          if (err instanceof AssertionError) {
-            throw err
-          }
-          handleError(entry, err, structUtils)
-        }
-      }
-    }
-
-    let runset: RunSet = async (
-      testspec: any,
-      testsubject: Function
-    ) => runsetflags(testspec, {}, testsubject)
-
-    const runpack: RunPack = {
-      spec,
-      runset,
-      runsetflags,
-      subject,
-      client,
-    }
-
-    return runpack
-  }
-}
-
-function resolveSpec(name: string, testfile: string): Record<string, any> {
-  const alltests =
-    JSON.parse(readFileSync(join(__dirname, testfile), 'utf8'))
-
-  let spec = alltests.primary?.[name] || alltests[name] || alltests
-  return spec
-}
-
-
-async function resolveClients(
-  client: any,
-  spec: Record<string, any>,
-  store: any,
-  structUtils: Record<string, any>
-):
-  Promise<Record<string, any>> {
-
-  const clients: Record<string, any> = {}
-  if (spec.DEF && spec.DEF.client) {
-    for (let cn in spec.DEF.client) {
-      const cdef = spec.DEF.client[cn]
-      const copts = cdef.test.options || {}
-      if ('object' === typeof store && structUtils?.inject) {
-        structUtils.inject(copts, store)
-      }
-
-      clients[cn] = await client.tester(copts)
-    }
-  }
-  return clients
-}
-
-
-function resolveSubject(name: string, container: any) {
-  const subject = container[name] || container.struct[name]
-  return subject
-}
-
-
-function resolveFlags(flags?: Flags): Flags {
-  if (null == flags) {
-    flags = {}
-  }
-  flags.null = null == flags.null ? true : !!flags.null
-  return flags
-}
-
-
-function resolveEntry(entry: any, flags: Flags): any {
-  entry.out = null == entry.out && flags.null ? NULLMARK : entry.out
-  return entry
-}
-
-
-function checkResult(entry: any, args: any[], res: any, structUtils: Record<string, any>) {
-  let matched = false
-
-  if (entry.err) {
-    return fail('Expected error did not occur: ' + entry.err +
-      '\n\nENTRY: ' + safeStringify(entry))
-  }
-
-  if (entry.match) {
-    const result = { in: entry.in, args, out: entry.res, ctx: entry.ctx }
-    match(
-      entry.match,
-      result,
-      structUtils
-    )
-
-    matched = true
-  }
-
-  const out = entry.out
-
-  if (out === res) {
-    return
-  }
-
-  // NOTE: allow match with no out.
-  if (matched && (NULLMARK === out || null == out)) {
-    return
-  }
-
-  deepStrictEqual(null != res ? JSON.parse(safeStringify(res)) : res, entry.out)
-}
-
-
-// Handle errors from test execution
-function handleError(entry: any, err: any, structUtils: Record<string, any>) {
-  entry.thrown = err
-
-  const entry_err = entry.err
-
-  if (null != entry_err) {
-    if (true === entry_err || matchval(entry_err, err.message, structUtils)) {
-      if (entry.match) {
-        match(
-          entry.match,
-          { in: entry.in, out: entry.res, ctx: entry.ctx, err: fixJSON(err, { null: true }) },
-          structUtils
-        )
-      }
-      return
-    }
-
-    fail('ERROR MATCH: [' + structUtils.stringify(entry_err) +
-      '] <=> [' + err.message + ']')
-  }
-
-  // Unexpected error (test didn't specify an error expectation)
-  else if (err instanceof AssertionError) {
-    fail(err.message + '\n\nENTRY: ' + safeStringify(entry))
-  }
-  else {
-    fail(err.stack + '\n\nENTRY: ' + safeStringify(entry))
-  }
-}
-
-
-function resolveArgs(
-  entry: any,
-  testpack: TestPack,
-  utility: Utility,
-  structUtils: Record<string, any>
-): any[] {
-  let args: any[] = []
-
-  if (entry.ctx) {
-    args = [entry.ctx]
-  }
-  else if (entry.args) {
-    args = entry.args
-  }
-  else {
-    args = [structUtils.clone(entry.in)]
-  }
-
-  if (entry.ctx || entry.args) {
-    let first = args[0]
-    if (structUtils.ismap(first)) {
-      first = structUtils.clone(first)
-      first = utility.makeContext(first)
-      args[0] = first
-      entry.ctx = first
-
-      first.client = testpack.client
-      first.utility = testpack.utility
-    }
-  }
-
-  return args
-}
-
-
-function resolveTestPack(
-  name: string,
-  entry: any,
-  subject: Subject,
-  client: any,
-  clients: Record<string, any>
-) {
-  const testpack: TestPack = {
-    name,
-    client,
-    subject,
-    utility: client.utility(),
-  }
-
-  if (entry.client) {
-    testpack.client = clients[entry.client]
-    testpack.utility = testpack.client.utility()
-    testpack.subject = resolveSubject(name, testpack.utility)
-  }
-
-  return testpack
-}
-
-
-function match(
-  check: any,
-  basex: any,
-  structUtils: Record<string, any>
-) {
-  const cbase = structUtils.clone(basex)
-
-  structUtils.walk(check, (_key: any, val: any, _parent: any, path: any) => {
-    if (!structUtils.isnode(val)) {
-      let baseval = structUtils.getpath(cbase, path)
-
-      if (baseval === val) {
-        return val
-      }
-
-      // Explicit undefined expected
-      if (UNDEFMARK === val && undefined === baseval) {
-        return val
-      }
-
-      // Explicit defined expected
-      if (EXISTSMARK === val && null != baseval) {
-        return val
-      }
-
-      if (!matchval(val, baseval, structUtils)) {
-        fail('MATCH: ' + path.join('.') +
-          ': [' + structUtils.stringify(val) +
-          '] <=> [' + structUtils.stringify(baseval) + ']')
-      }
-    }
-
-    return val
-  })
-}
-
-
-function matchval(
-  check: any,
-  base: any,
-  structUtils: Record<string, any>
-) {
-  let pass = check === base
-
-  if (!pass) {
-
-    if ('string' === typeof check) {
-      let basestr = structUtils.stringify(base)
-
-      let rem = check.match(/^\/(.+)\/$/)
-      if (rem) {
-        pass = new RegExp(rem[1]).test(basestr)
-      }
-      else {
-        pass = basestr.toLowerCase().includes(structUtils.stringify(check).toLowerCase())
-      }
-    }
-    else if ('function' === typeof check) {
-      pass = true
-    }
-  }
-
-  return pass
-}
-
-
-function safeStringify(val: any): string {
-  const seen = new WeakSet()
-  return JSON.stringify(val, (_k, v) => {
-    if ('object' === typeof v && null !== v) {
-      if (seen.has(v)) return '[Circular]'
-      seen.add(v)
-    }
-    if (v instanceof Error) {
-      return { name: v.name, message: v.message }
-    }
-    return v
-  }, 2)
-}
-
-
-function fixJSON(val: any, flags?: Flags): any {
-  if (null == val) {
-    return flags?.null ? NULLMARK : val
-  }
-
-  const seen = new WeakSet()
-  const replacer = (_k: string, v: any) => {
-    if (null == v && flags?.null) {
-      return NULLMARK
-    }
-
-    if (v instanceof Error) {
-      return {
-        ...v,
-        name: v.name,
-        message: v.message,
-      }
-    }
-
-    if ('object' === typeof v && null !== v) {
-      if (seen.has(v)) return '[Circular]'
-      seen.add(v)
-    }
-
-    return v
-  }
-
-  return JSON.parse(JSON.stringify(val, replacer))
-}
-
-
-function nullModifier(
-  val: any,
-  key: any,
-  parent: any
-) {
-  if ("__NULL__" === val) {
-    parent[key] = null
-  }
-  else if ('string' === typeof val) {
-    parent[key] = val.replaceAll('__NULL__', 'null')
-  }
-}
-
-
-export {
-  NULLMARK,
-  EXISTSMARK,
-  nullModifier,
-  makeRunner,
-}
-