@voxgig/sdkgen 4.9.0 → 4.10.0

package/src/helpers/modelNames.ts

@@ -0,0 +1,284 @@
+/* Copyright (c) 2024-2026 Voxgig Ltd, MIT License */
+
+// Normalise entity names in the model so every generated identifier is legal.
+//
+// An entity name is a MODEL KEY, and every target builds identifiers from it:
+// the PascalCase `Name` (class names, the SDK accessor, every generated type
+// name), the snake stem (python module names, test function names), the
+// object-literal key in the emitted config map. No target language permits an
+// identifier that starts with a digit, and ordinary resources produce one:
+// `/3ds-sessions` -> entity `3ds_session` -> `class 3dsSessionEntity`,
+// `import { 3dsSession }`, `3dsSession()`. That is not a degraded SDK, it is
+// no SDK — nothing compiles (issue #124).
+//
+// THE RENAME IS ON THE MODEL, NOT ON A DERIVED FORM, and that is the whole
+// design. Guarding `Name` where it is derived does not survive: a consumer's
+// scaffolded `Root.ts` — which lives in the consumer's repo, not here — runs
+// its own `names(entity, entity.name)` per entity per target, immediately
+// before emitting, and re-derives `Name` from the unguarded name. Only a
+// guarded `entity.name` makes that re-derivation come out right, and it fixes
+// the snake-stem and config-key positions at the same time.
+//
+// Applied before Root runs, so nothing has read a name yet.
+//
+// IT IS A NO-OP ON EVERY MODEL THAT EXISTS TODAY. apidef guards entity names
+// at the source, so a name reaching here with a leading digit means a
+// hand-authored `.sdk/model` or a pre-guard apidef. The rename is the same
+// rule, producing the same name, as apidef's own `prefixLeadingDigit` — so
+// the two layers agree rather than compete, and a model that went through
+// apidef is untouched.
+//
+// The WIRE is untouched. A request path comes from the point's `orig`, never
+// from the entity name, so renaming the entity cannot change what is called.
+
+import { each, names } from 'jostraca'
+import { KIT } from '@voxgig/apidef'
+
+import { prefixLeadingDigit } from './naming'
+
+
+// `from`/`to` are the entity NAME. `key` is where the entity sits in the
+// collection after the rename — the new name when the map was keyed by it (the
+// normal shape), the untouched original key when it was not.
+type Rename = { from: string, to: string, key: string }
+
+// The internal form, which also remembers where the entity sat BEFORE the
+// rename — the one thing the public record cannot carry and the apply pass
+// needs, since the key only moves when it was the name.
+type Plan = { from: string, to: string, origkey: string }
+
+
+// Rename every entity whose name would produce an illegal identifier, and
+// rewrite the model's own references to it. Returns the renames applied, so
+// the caller can report them; empty when the model is already clean.
+function guardModelNames(model: any, log?: any): Rename[] {
+  const entity = model?.main?.[KIT]?.entity
+  // An ARRAY is not a name-keyed collection: its keys are indices, and
+  // "renaming" one would rewrite the model into nonsense. Models are maps, but
+  // the check is cheap and the failure would be silent.
+  if (null == entity || 'object' !== typeof entity || Array.isArray(entity)) {
+    return []
+  }
+
+  const flow = flowMap(model)
+
+  // Sorted keys: the rename set, and any collision report, is byte-stable.
+  const keys = Object.keys(entity).sort()
+  const taken = new Set(keys)
+  keys.forEach((k) => {
+    const n = entity[k]?.name
+    if ('string' === typeof n) taken.add(n)
+  })
+
+  const plans: Plan[] = []
+  const blocked: string[] = []
+
+  for (const key of keys) {
+    const ent = entity[key]
+    if (null == ent || 'object' !== typeof ent) {
+      continue
+    }
+
+    // `name` is authoritative, not the key: it is the value every derived
+    // form comes from. The key moves with it only when the two agree, which
+    // is the normal shape.
+    const from = 'string' === typeof ent.name ? ent.name : key
+
+    const to = prefixLeadingDigit(from)
+    if (to === from) {
+      continue
+    }
+
+    // The guarded name is already another entity's. Renaming onto it would
+    // merge two unrelated entities — silently, since the model is a plain
+    // map — so leave this one alone and say so. The generated SDK still will
+    // not compile, but the reason is now in the log rather than in a syntax
+    // error 20 files later.
+    if (taken.has(to)) {
+      blocked.push(from)
+      continue
+    }
+
+    // The FLOW key would collide. `Basic<Name>Flow` is rebuilt from the
+    // guarded Name by every Test component, so if the guarded key is already
+    // occupied by a different flow, renaming would point all of them at that
+    // one and strand this entity's own flow under its old key — generated
+    // tests that exercise the wrong entity, silently. Refuse, exactly as for
+    // an entity-name collision: an SDK that does not compile is a better
+    // outcome than one whose tests lie.
+    if (null != flow && flowCollides(flow, from, to)) {
+      blocked.push(from)
+      continue
+    }
+
+    taken.add(to)
+    plans.push({ from, to, origkey: key })
+  }
+
+  if (0 < blocked.length && log?.warn) {
+    log.warn({
+      point: 'entity-name-guard-blocked', names: blocked.sort(),
+      note: `entity name(s) ${blocked.sort().join(', ')} start with a digit ` +
+        `and cannot be guarded: the guarded name, or the basic flow key it ` +
+        `implies, is already taken. Rename the entity (or that flow) in the ` +
+        `model — the generated SDK will not compile in any target while an ` +
+        `entity name is not an identifier`,
+    })
+  }
+
+  if (0 === plans.length) {
+    return []
+  }
+
+  const renames: Rename[] = []
+
+  for (const { from, to, origkey } of plans) {
+    const ent = entity[origkey]
+    ent.name = to
+    // jostraca's names() is memo-free but idempotent-by-absence: every derived
+    // form has to go, or a stale `Name` from an earlier pass survives the
+    // rename and the SDK is inconsistent with itself.
+    delete ent.Name
+    delete ent.NAME
+    delete ent.name_
+    delete ent['name-']
+    delete ent.name__orig
+
+    // The key moves only when it WAS the name. A key the model chose for some
+    // other reason is left where it is; every derived identifier comes from
+    // `name`, which is now guarded either way.
+    if (origkey === from) {
+      entity[to] = ent
+      delete entity[origkey]
+    }
+
+    renames.push({ from, to, key: origkey === from ? to : origkey })
+  }
+
+  renameReferences(model, renames)
+
+  // WARN, not info, because it names work only the project owner can do.
+  //
+  // The generated flow test reads its fixture from
+  // `.sdk/test/entity/<name>/<Name>TestData.json` and seeds the config under
+  // `<name>` — both derived from the guarded name. sdkgen READS that path and
+  // never writes it: the fixture is the project's own content under `.sdk/`,
+  // not generated output, so the rename cannot carry it. A project that
+  // already has one for a digit-named entity goes from an SDK that does not
+  // compile at all to one that compiles with a flow test failing on a missing
+  // fixture — better, but only if it says which file to move.
+  if (log?.warn) {
+    log.warn({
+      point: 'entity-name-guard', renames,
+      note: 'entity name(s) renamed so generated identifiers are legal: ' +
+        renames.map((r) => `${r.from} -> ${r.to}`).join(', ') +
+        '. If this project has a test fixture for one of them, move it: ' +
+        renames.map((r) =>
+          `.sdk/test/entity/${r.from}/${pascalName(r.from)}TestData.json -> ` +
+          `.sdk/test/entity/${r.to}/${pascalName(r.to)}TestData.json ` +
+          `(renaming its \`existing.${r.from}\` key to \`${r.to}\`)`)
+          .join('; '),
+    })
+  }
+
+  return renames
+}
+
+
+// The flow collection, when the model has one shaped like a map.
+function flowMap(model: any): Record<string, any> | null {
+  const flow = model?.main?.[KIT]?.flow
+  return (null != flow && 'object' === typeof flow && !Array.isArray(flow))
+    ? flow
+    : null
+}
+
+
+// Would renaming `from` to `to` put this entity's basic flow on a key another
+// flow already holds? The entity's own flow is the one sitting at the key its
+// CURRENT name implies; anything else at the guarded key belongs to something
+// else.
+function flowCollides(
+  flow: Record<string, any>, from: string, to: string,
+): boolean {
+  const held = flow[flowKey(to)]
+  return null != held && held !== flow[flowKey(from)]
+}
+
+
+// The model refers to an entity by name in two more places, and both have to
+// move with it or the reference dangles.
+function renameReferences(model: any, renames: Rename[]): void {
+  const map = new Map(renames.map((r) => [r.from, r.to]))
+
+  // 1. FLOWS. A flow names its entity, and the Test components look the flow
+  //    up by a key REBUILT from the entity's PascalCase Name
+  //    (`Basic${nom(entity, 'Name')}Flow`), so the key has to move too or the
+  //    entity silently generates no tests. Only a key that matches the
+  //    reconstructed old one is renamed; anything else the author chose is
+  //    left as it is, with just its `entity` field corrected.
+  const flow = flowMap(model)
+  if (null != flow) {
+    for (const key of Object.keys(flow).sort()) {
+      const f = flow[key]
+      if (null == f || 'object' !== typeof f) {
+        continue
+      }
+      const to = map.get(f.entity)
+      if (null == to) {
+        continue
+      }
+
+      const from = f.entity
+      f.entity = to
+
+      // The destination is free: `flowCollides` refused the rename outright
+      // when it was not, so this cannot clobber another flow.
+      const oldkey = flowKey(from)
+      if (key === oldkey) {
+        const newkey = flowKey(to)
+        f.name = newkey
+        flow[newkey] = f
+        delete flow[oldkey]
+      }
+    }
+  }
+
+  // 2. ANCESTORS. A nested entity records its parents by name.
+  const entity = model?.main?.[KIT]?.entity
+  each(entity).forEach((ent: any) => {
+    const ancestors = ent?.relations?.ancestors
+    if (!Array.isArray(ancestors)) {
+      return
+    }
+    ent.relations.ancestors = ancestors.map((a: any) =>
+      Array.isArray(a)
+        ? a.map((n: any) => map.get(n) ?? n)
+        : (map.get(a) ?? a))
+  })
+}
+
+
+// The basic flow's key for an entity name, as the Test components rebuild it
+// (`Basic${nom(entity, 'Name')}Flow`). Derived through jostraca's own names()
+// on a scratch object rather than by re-implementing PascalCase here — a
+// second spelling of that rule is exactly how the key and the lookup drift
+// apart, and the failure is silent (an entity that generates no tests).
+function flowKey(name: string): string {
+  return 'Basic' + pascalName(name) + 'Flow'
+}
+
+
+// The PascalCase `Name` for an entity name, through jostraca's own names() on
+// a scratch object — the same derivation every component gets, so a caller
+// here cannot drift from what is emitted.
+function pascalName(name: string): string {
+  const scratch: any = {}
+  names(scratch, name)
+  return scratch.Name
+}
+
+
+export {
+  guardModelNames,
+}

package/src/helpers/naming.ts

@@ -150,9 +150,14 @@ const RB_SDK_CONSTANTS = new Set<string>([
   'STRUCT_TEST_JSON_FILE',
   // vendored omni runner and its smoke test (vendor-tag rollout)
   'VoxgigOmni', 'OmniSmokeTest',
+  // vendored sekreto and its plugin host — the `secrets` feature's library,
+  // shipped only when that feature is selected, but declared at the top
+  // level when it is
+  'VoxgigSekreto', 'VoxgigPlugin',
   // the generated/templated test classes
   'ExistsTest', 'FeatureCorpusTest', 'FeatureTest', 'NetsimTest',
   'PipelineTest', 'PrimaryUtilityTest', 'ReadmeExamplesTest',
+  'SecretsFeatureTest',
   'TestHookFeature', 'TestInitFeature',
 ])
 
@@ -226,7 +231,8 @@ const SWIFT_SDK_TYPES = new Set<string>([
   'CostTotal', 'DebugFeature', 'IdempotencyFeature', 'LogFeature',
   'MetricsBucket', 'MetricsFeature', 'NetsimFeature', 'PagingFeature',
   'ProxyFeature', 'RatelimitFeature', 'RbacFeature', 'RetryFeature',
-  'StreamingFeature', 'TelemetryFeature', 'TestFeature', 'TimeoutFeature',
+  'SecretsFeature', 'StreamingFeature', 'TelemetryFeature', 'TestFeature',
+  'TimeoutFeature',
 ])
 
 
@@ -497,6 +503,43 @@ function exampleVarName(name: string, lang: string): string {
 }
 
 
+// LEADING DIGITS — the one hazard on this page that is not about a word being
+// taken. Every other guard here asks "is this name already claimed?"; this one
+// asks whether the name is an identifier at all. No target language permits
+// one that starts with a digit, and ordinary resources produce one:
+//
+//   /3ds-sessions  -> entity `3ds_session` -> Name `3dsSession`
+//   /2fa-tokens    -> entity `2fa_token`   -> Name `2faToken`
+//
+// `Name` feeds the class name, the SDK accessor and every generated type
+// name, so the SDK does not compile at all — it is not a degraded SDK, it is
+// no SDK (issue #124).
+//
+// The prefix takes the case of the name it guards — lower for `3ds_session`,
+// upper for `3DSecure` — so the result stays in whatever casing convention
+// the caller works in. Applied to the STEM before PascalCasing, which is why
+// `Name` comes out `N3dsSession` and not `n3dsSession`.
+//
+// This is deliberately the SAME rule, spelled the same way, as apidef's
+// `prefixLeadingDigit`. A model that came through apidef is already guarded,
+// so this is a no-op on it; a hand-authored `.sdk/model` entity gets the
+// identical name apidef would have given it. Idempotent by construction.
+//
+// The rule is applied ONCE, to the model's own entity name, by
+// `guardModelNames` — never to a derived form. Guarding `Name` alone does not
+// survive: a consumer's scaffolded `Root.ts` runs its own
+// `names(entity, entity.name)` per target, which re-derives `Name` from the
+// unguarded name and silently undoes the correction.
+function prefixLeadingDigit(s: string): string {
+  if (null == s || '' === s) return s
+  const first = s.charCodeAt(0)
+  if (first < 48 || first > 57) return s
+  const letter = s.match(/[a-zA-Z]/)
+  const upper = null != letter && letter[0] >= 'A' && letter[0] <= 'Z'
+  return (upper ? 'N' : 'n') + s
+}
+
+
 // A valid ECMAScript identifier — the only shape `obj.name` can express.
 const JS_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
@@ -546,4 +589,5 @@ export {
   jsProp,
   jsOptProp,
   jsKey,
+  prefixLeadingDigit,
 }

package/src/sdkgen.ts

@@ -59,10 +59,11 @@ import type { RegisterOptions } from './cmp/Registered'
 import { buildIdNames } from './helpers/buildIdNames'
 import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
+import { guardModelNames } from './helpers/modelNames'
 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 { isReservedName, safeVarName, exampleVarName, phpEntityAccessor, entityCacheField, isRbCoreConstant, isRbSdkConstant, rbSafeTypeName, isSwiftSdkType, swiftSafeTypeName, isPhpReservedType, isPhpSdkClass, phpSafeTypeName, isTsReservedType, tsSafeTypeName, jsProp, jsOptProp, jsKey, prefixLeadingDigit } from './helpers/naming'
 import { serverVariables, hasServerVariables, serverVarEnv } from './helpers/serverVars'
 import { primaryOpCall, idLiteral, matchArg, dataArg, litFor } from './helpers/opExample'
 import type { ExampleLang } from './helpers/opExample'
@@ -269,6 +270,13 @@ function SdkGen(opts: SdkGenOptions) {
     log.info({ point: 'generate-start', start, note: opts.dryrun ? '** DRY RUN **' : '' })
     log.debug({ point: 'generate-spec', spec })
 
+    // BEFORE ANYTHING READS A NAME. An entity whose name starts with a digit
+    // yields identifiers no target language accepts, and the consumer's own
+    // Root.ts re-derives those names per target — so the only correction that
+    // survives is one made to the model itself, before Root runs. No-op on
+    // every model apidef produces; see helpers/modelNames.
+    guardModelNames(model, log)
+
     let Root = spec.root
 
     if (null == Root && null != config?.root) {
@@ -1153,6 +1161,7 @@ export {
   warnEntityTypeCollisions,
   deriveEntityNames,
   entityCollection,
+  guardModelNames,
   isReservedName,
   safeVarName,
   exampleVarName,
@@ -1205,6 +1214,7 @@ export {
   jsProp,
   jsOptProp,
   jsKey,
+  prefixLeadingDigit,
 
   packageName,
   installCommand,

package/src/testkit.ts

@@ -26,6 +26,12 @@
 //   consumer.compile()                             // as a consumer's build does
 //   const { files, leaks } = await generateInto(consumer, { model })
 //
+// A target with `output: path` writes outside the consumer root, so declare
+// its destinations and read them back per destination:
+//
+//   const { outside } = await generateInto(
+//     consumer, { model, outside: ['../acme-provider'] })
+//
 // That runs the REAL add pipeline and the REAL generation, so provenance,
 // index handling, the feature fan-out and the trim catalogue are all exercised
 // against the package as published rather than as described.
@@ -615,6 +621,24 @@ type GenerateOptions = {
   // Placeholder mentions that are NOT leaks, exactly as `parity.test.ts`
   // keeps its list: a stated policy, not a mute button.
   allowPlaceholder?: (path: string, token: string) => boolean
+
+  // OUT-OF-TREE DESTINATIONS THE CALLER EXPECTS — the `output: path` of every
+  // external target in the model, exactly as the model spells it.
+  //
+  // Needed because a target with `output: path` writes OUTSIDE the consumer
+  // root, and the check below treats a path outside the root as a bug rather
+  // than a result. That check is worth keeping (see it for what it catches),
+  // so the way to express out-of-tree output is to DECLARE the destination
+  // rather than to loosen it: a path under neither the root nor a declared
+  // destination is still a bug and still throws.
+  //
+  // Without this a package shipping an out-of-tree target — which is what
+  // `seneca-provider` is, and the reason it was the first consumer target to
+  // migrate — could not test its defining mode at all.
+  //
+  // A relative destination resolves against the consumer ROOT, which is what
+  // `output: path` itself resolves against: the SDK project, not the CWD.
+  outside?: string[]
 }
 
 
@@ -622,7 +646,15 @@ type GenerateResult = {
   // Every generated path, relative to the consumer root, mapped to content.
   files: Record<string, string>
 
-  // `<path>: <token>` for each surviving placeholder.
+  // Files written OUTSIDE the consumer root, one map per destination declared
+  // in `outside`, keyed by the destination as the caller spelled it and then
+  // by the path relative to that destination. Empty unless `outside` was
+  // passed.
+  outside: Record<string, Record<string, string>>
+
+  // `<path>: <token>` for each surviving placeholder, across `files` AND
+  // every `outside` destination — an external target's output is generated
+  // by the same replace maps and leaks the same way.
   leaks: string[]
 }
 
@@ -698,50 +730,107 @@ async function generateInto(
   // On POSIX both transformations are identity, so this changes nothing there.
   const rootkey = volumeKey(consumer.root)
 
+  // The declared out-of-tree destinations, resolved the way `output: path` is
+  // — against the consumer root — and reduced to volume keys so they compare
+  // with generated paths on the same terms as the root does.
+  //
+  // LONGEST KEY FIRST. A destination nested inside another would otherwise be
+  // matched by whichever came first in the array, silently filing its files
+  // under the wrong one; sorting makes the most specific destination win, the
+  // same rule a router uses.
+  const declared = (opts.outside ?? [])
+    .map((dest) => ({ dest, key: volumeKey(Path.resolve(consumer.root, dest)) }))
+    .sort((a, b) => b.key.length - a.key.length)
+
   const files: Record<string, string> = {}
+  const outside: Record<string, Record<string, string>> = {}
+  for (const { dest } of declared) {
+    outside[dest] = {}
+  }
+
   for (const [path, content] of Object.entries(vol.toJSON() as Record<string, string>)) {
     const key = volumeKey(path)
 
-    // A KEY OUTSIDE THE ROOT IS A BUG HERE, NOT A RESULT.
+    const under = (base: string) => key === base || key.startsWith(base + '/')
+    const rel = (base: string) => key === base ? '' : key.slice(base.length + 1)
+
+    // The generator's own bookkeeping, wherever it landed. Skipped in both
+    // views for the same reason: the caller is asking what package was
+    // written, not what jostraca recorded about writing it.
+    const junk = (p: string) =>
+      p.startsWith('.jostraca/') || p.includes('/.jostraca/')
+
+    if (under(rootkey)) {
+      const p = rel(rootkey)
+      if (!junk(p)) files[p] = content
+      continue
+    }
+
+    const hit = declared.find((d) => under(d.key))
+    if (null != hit) {
+      const p = rel(hit.key)
+      if (!junk(p)) outside[hit.dest][p] = content
+      continue
+    }
+
+    // A KEY OUTSIDE THE ROOT AND EVERY DECLARED DESTINATION IS A BUG HERE,
+    // NOT A RESULT.
     //
     // It means the string generation wrote under and the string being stripped
     // off have diverged, and the caller would otherwise get a file map keyed
     // by absolute path — which reads as "my component never ran" rather than
     // as a path problem, and is exactly how this presented on Windows.
-    if (key !== rootkey && !key.startsWith(rootkey + '/')) {
-      throw new Error(
-        'testkit: generated path is not under the consumer root, so the ' +
-        'result cannot be keyed.\n  root: ' + consumer.root +
-        '\n  path: ' + path +
-        '\n  compared as: ' + rootkey + '  vs  ' + key +
-        '\nThese must agree once separators and any drive letter are ' +
-        'normalised — memfs stores volume keys, not OS paths.')
-    }
-
-    const rel = key === rootkey ? '' : key.slice(rootkey.length + 1)
-
-    if (rel.startsWith('.jostraca/') || rel.includes('/.jostraca/')) continue
-    files[rel] = content
+    //
+    // An out-of-tree target is the one legitimate way to be outside the root,
+    // and it is legitimate only because the caller SAID SO: pass its
+    // `output: path` in `outside`. A path under neither still throws, so a
+    // package cannot get here by accident.
+    throw new Error(
+      'testkit: generated path is not under the consumer root or any ' +
+      'declared out-of-tree destination, so the result cannot be keyed.' +
+      '\n  root: ' + consumer.root +
+      '\n  path: ' + path +
+      '\n  compared as: ' + rootkey + '  vs  ' + key +
+      (0 === declared.length
+        ? '\nIf this target declares `output: path`, pass that path in the ' +
+          '`outside` option.'
+        : '\n  declared: ' + declared.map((d) => d.key).join(', ')) +
+      '\nThese must agree once separators and any drive letter are ' +
+      'normalised — memfs stores volume keys, not OS paths.')
   }
 
   const allow = opts.allowPlaceholder ?? (() => false)
   const leaks: string[] = []
-  for (const [path, content] of Object.entries(files)) {
-    if ('string' !== typeof content) continue
 
-    for (const token of PLACEHOLDERS) {
-      if (content.includes(token) && !allow(path, token)) {
-        leaks.push(path + ': ' + token)
+  // SCANNED IN BOTH VIEWS. An out-of-tree target's output goes through the
+  // same replace maps and leaks a placeholder the same way, so a scan that
+  // covered only the in-tree files would report `leaks: []` for a package
+  // whose whole output is external.
+  const scan = (prefix: string, map: Record<string, string>) => {
+    for (const [path, content] of Object.entries(map)) {
+      if ('string' !== typeof content) continue
+
+      const label = prefix + path
+
+      for (const token of PLACEHOLDERS) {
+        if (content.includes(token) && !allow(label, token)) {
+          leaks.push(label + ': ' + token)
+        }
       }
-    }
 
-    const ref = content.match(PLACEHOLDER_REF)
-    if (null != ref && !allow(path, ref[0])) {
-      leaks.push(path + ': ' + ref[0])
+      const ref = content.match(PLACEHOLDER_REF)
+      if (null != ref && !allow(label, ref[0])) {
+        leaks.push(label + ': ' + ref[0])
+      }
     }
   }
 
-  return { files, leaks: leaks.sort() }
+  scan('', files)
+  for (const { dest } of declared) {
+    scan(dest + '/', outside[dest])
+  }
+
+  return { files, outside, leaks: leaks.sort() }
 }
 
 

package/src/utility.ts

@@ -29,17 +29,27 @@ function resolvePath(ctx$: any, path: string): any {
 
 // True unless the model declares auth off. Templates use this to gate
 // apikey-related code, docs, and examples for public APIs that need no
-// authentication. Two opt-outs, in priority order:
-//   1. main.kit.info.auth: false        (user-facing, set in api-info.aon)
-//   2. main.kit.config.auth.active: false
+// authentication.
+//
+// The project's own word comes first: `main.kit.config.auth.active` set
+// EXPLICITLY (true or false) decides. GitHub's official OpenAPI declares no
+// securitySchemes, so apidef faithfully writes `info.auth: false` and every
+// generated client sent no credential; the only override lived in a
+// generated file. A project that knows its API takes a bearer token says so
+// once in its own config and that wins over the spec's silence.
+//
+// Otherwise the spec-derived signal governs:
+//   1. main.kit.config.auth.active: true|false  (per-SDK, in config.aon)
+//   2. main.kit.info.auth: false                (apidef: the spec declares
+//                                               no authentication)
 function isAuthActive(model: any): boolean {
-  const info = getModelPath(model, `main.${KIT}.info`,
+  const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })
-  if (info && false === info.auth) return false
+  if (null != auth && 'boolean' === typeof auth.active) return auth.active
 
-  const auth = getModelPath(model, `main.${KIT}.config.auth`,
+  const info = getModelPath(model, `main.${KIT}.info`,
     { only_active: false, required: false })
-  return null == auth || false !== auth.active
+  return !(info && false === info.auth)
 }