@voxgig/sdkgen 4.15.0 → 4.17.0

package/project/.sdk/tm/ts/test/live-scenarios.ts

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict'
+import { LiveBlocked, runLiveSteps, assertLiveReport, createLiveTransport } from './live-runner'
+import { requestContract, synthesizeInput, validateContract } from './live-contract'
+import { liveClientOptions, liveDelayMs, isControlSkipped } from './utility'
+
+const at = (value: any, path?: string): any => (path || '').split('.').filter(Boolean).reduce((v, k) => v?.[k], value)
+export function resolveRecipe(recipe: any, values: Map<string, any>): any {
+  if (Array.isArray(recipe)) return recipe.map(v => resolveRecipe(v, values))
+  if (recipe && typeof recipe === 'object') {
+    if (recipe.from) {
+      if (!values.has(recipe.from)) throw new LiveBlocked('Missing recipe output: ' + recipe.from)
+      let value = values.get(recipe.from)
+      if (recipe.where) {
+        if (!Array.isArray(value)) throw new LiveBlocked('Discovery output is not a list')
+        value = value.find((item: any) => Object.entries(recipe.where).every(([k, v]) => at(item, k) === v) &&
+          (!recipe.related || (values.get(recipe.related.from) || []).some((other: any) =>
+            at(item, recipe.related.local) === at(other, recipe.related.foreign) &&
+            Object.entries(recipe.related.where || {}).every(([k, v]) => at(other, k) === v))))
+      }
+      value = at(value, recipe.path)
+      if (value === undefined || value === null) throw new LiveBlocked('Discovery found no compatible value')
+      return value
+    }
+    return Object.fromEntries(Object.entries(recipe).map(([k, v]) => [k, resolveRecipe(v, values)]))
+  }
+  return recipe
+}
+
+export function recipeNeeds(value: any): string[] {
+  if (!value || typeof value !== 'object') return []
+  return [...new Set([...(typeof value.from === 'string' ? [value.from] : []), ...Object.values(value).flatMap(recipeNeeds)])]
+}
+
+export async function runLiveScenarios(SDK: any, plan: any[], envPrefix: string, liveDefaults: any = {}) {
+  const transport = createLiveTransport()
+  const steps = plan.map(point => {
+    const hint = point.facts.live || {}
+    const control = isControlSkipped('entityOp', point.entity + '.' + point.op, 'live')
+    return { role: hint.auth || (point.facts.security?.length === 0 || point.facts.securitySource === 'unspecified' ? 'public' : 'account'), retention: hint.retention, id: hint.id || point.id, needs: [...new Set([...(hint.needs || []), ...recipeNeeds(hint.input), ...recipeNeeds(hint.credential), ...recipeNeeds(hint.assert)])] as string[],
+      cleanup: !!hint.cleanup,
+      excluded: control.skip ? control.reason || 'Excluded by test control' : hint.excluded,
+      run: async (ctx: any) => {
+        transport.enter(ctx)
+        if (point.contractVersion && point.contractVersion !== 1) throw new LiveBlocked('Unsupported operation contract version')
+        if (point.op === 'remove' || hint.cleanup) {
+          const owned = recipeNeeds(hint.input).some(id => plan.some(source =>
+            (source.facts.live?.id || source.id) === id && source.entity === point.entity && source.op === 'create'))
+          if (!owned) throw new LiveBlocked('Cleanup input is not bound to a resource created by this run')
+        }
+        if (!point.reachable) throw new LiveBlocked('Point selector is indistinguishable; add a guide action')
+        const request = requestContract(point.facts)
+        const explicit = hint.input === undefined ? request.example : resolveRecipe(hint.input, ctx.values)
+        let input = request.schema ? synthesizeInput(request.schema, explicit) : explicit ?? {}
+        for (const kind of ['params', 'query', 'header', 'cookie']) for (const arg of point.args?.[kind] || []) {
+          if (arg.reqd && input[arg.name] === undefined) {
+            if (arg.example === undefined) throw new LiveBlocked('Missing required argument: ' + arg.name)
+            input[arg.name] = arg.example
+          }
+        }
+        const role = hint.auth || (point.facts.security?.length === 0 || point.facts.securitySource === 'unspecified' ? 'public' : 'account')
+        let apikey = role === 'public' ? null : role === 'issued' ? resolveRecipe(hint.credential, ctx.values) : process.env[envPrefix + '_APIKEY']
+        if (role === 'issued' && (typeof apikey !== 'string' || !apikey)) throw new LiveBlocked('Issued credential unavailable')
+        let wire: any
+        let wireSchema: any
+        const options = liveClientOptions()
+        const client = new SDK({ ...options, ...liveDefaults, apikey,
+          feature: { ...options.feature, test: { active: false }, retry: { active: false },
+            secrets: { ...options.feature?.secrets, active: role === 'account' && (!apikey || options.feature?.secrets?.active === true) } },
+          system: { ...options.system, fetch: async (url: any, init: any) => {
+            const headers = new Headers(init?.headers)
+            if (role === 'public') assert(!headers.has('authorization'), 'Public request carries authentication')
+            else if (!headers.get('authorization')) throw new LiveBlocked('Credential unavailable for ' + role + ' request')
+            const response = await transport.fetch(url, { ...init, redirect: 'error' })
+            const expectedPath = point.path.replace(/\{([^}]+)\}/g, (_: string, name: string) => encodeURIComponent(input[point.rename?.param?.[name] || name] ?? input[name]))
+            if (point.kind === 'graphql') {
+              const payload = JSON.parse(init.body)
+              assert.equal(payload.query, point.graphql.doc, 'Entity selected wrong GraphQL operation')
+            } else assert.equal(new URL(String(url)).pathname, expectedPath, 'Entity selected wrong route')
+            assert.equal(init?.method || 'GET', point.method)
+            assert(response.status >= 200 && response.status < 300, 'Unsuccessful HTTP response')
+            if (point.kind === 'graphql') wire = await response.clone().json()
+            const def = point.facts.responses?.[response.status] || point.facts.responses?.[String(response.status)[0] + 'XX'] || point.facts.responses?.default
+            if (point.facts.responses && !def) throw new Error('Undeclared response status')
+            if (def) {
+              const schema = def.content?.['application/json']?.schema ?? def.schema
+              if (schema && response.status !== 204) { wireSchema = schema; wire = await response.clone().json() }
+            }
+            return response
+          } } })
+        if (point.action) input = { ...input, $action: point.action }
+        assert(JSON.stringify(input).length <= 1024 * 1024, 'Request exceeds test payload limit')
+        const result = await client[point.accessor]()[point.op](input)
+        const data = Array.isArray(result) ? result.map(item => { assert.equal(typeof item?.data, 'function'); return item.data() }) : (assert.equal(typeof result?.data, 'function'), result.data())
+        ctx.publish(data)
+        if (wireSchema) validateContract(wireSchema, wire, 'response')
+        if (Array.isArray(wire?.errors) && wire.errors.length) throw new Error('GraphQL operation reported errors')
+        if (wire?.success === false) throw new Error('API reported unsuccessful operation')
+        const checks = resolveRecipe(hint.assert || {}, ctx.values)
+        for (const [path, expected] of Object.entries(checks.equal || {})) assert.deepEqual(at(data, path), expected)
+        for (const path of checks.nonempty || []) assert(at(data, path)?.length > 0, 'Empty required output')
+        if (checks.vectors) {
+          const vectors = at(data, checks.vectors.path)
+          assert(Array.isArray(vectors) && vectors.length === checks.vectors.count)
+          for (const vector of vectors) assert(Array.isArray(vector) && vector.length === checks.vectors.dimension && vector.every((n: any) => typeof n === 'number' && Number.isFinite(n)), 'Invalid vector shape')
+        }
+      } }
+  })
+  const report = await runLiveSteps(steps, { delayMs: liveDelayMs(), report: result => console.log('LIVE STEP ' + JSON.stringify(result)) })
+  console.log('LIVE SUMMARY ' + JSON.stringify(report))
+  assertLiveReport(report)
+  return report
+}

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

@@ -161,8 +161,7 @@ function skipIfMissingIds(t: any, setup: any, requiredKeys: string[]): boolean {
   if (!setup.live) return false
   const missing = requiredKeys.filter(k => null == setup.idmap?.[k])
   if (missing.length > 0) {
-    t.skip(`live test needs ${missing.join(', ')} via *_ENTID env var (synthetic IDs only)`)
-    return true
+    throw new Error(`Live test blocked: needs ${missing.join(', ')} via *_ENTID env var`)
   }
   return false
 }

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "provides": {
     "target": [
       "c",

package/src/action/action.ts

@@ -102,7 +102,7 @@ function parseAddNames(args: any[]): string[] {
 // `seed` IS THE UPGRADE PATH. A project scaffolded before a kind existed has
 // no `model/<kind>/<kind>-index.aon` — every project alive today is in
 // exactly that position for `docs` — and reading it unguarded made the FIRST
-// `docs add` in any existing project fail on ENOENT before it wrote anything.
+// `edition add` in any existing project fail on ENOENT before it wrote anything.
 //
 // Seeded per call rather than defaulted for every kind: a missing
 // `target-index.aon` in a scaffolded project is a broken project, and
@@ -136,7 +136,7 @@ function loadContent(
 // indexes of the kinds that existed then. So a project scaffolded before a
 // kind existed — which is every project alive today, for `docs` — never
 // includes its index, and the item's model file is an orphan: it is on disk,
-// `<kind>-index.aon` includes it, and NOTHING includes that. `main.kit.docs`
+// `<kind>-index.aon` includes it, and NOTHING includes that. `main.kit.doc.edition`
 // is then absent from the compiled model, so `package list`, `package update`
 // and `doctor` cannot see the item at all.
 //

package/src/action/check.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // `package check` — the AUTHOR-side battery. Design §14.
 //
 // WHAT IT IS FOR
@@ -308,11 +309,11 @@ function checkDefinition(
   //    `main: kit: target: go:` installs an item the consumer's model never
   //    sees — the exact mistake a package author makes copying a bundled
   //    target as a starting point.
-  const declared = strict.model?.main?.[KIT]?.[kind]?.[name]
+  const declared = kindCollection(strict.model, kind)?.[name]
 
   if (null == declared || 'object' !== typeof declared) {
     found.push(at('error', 'model-key-missing',
-      'declares no `main: kit: ' + kind + ': ' + name + ':` block — the file ' +
+      'declares no `main: kit: ' + (kind === 'edition' ? 'doc: edition' : kind) + ': ' + name + ':` block — the file ' +
       'is installed and included under its own name, so nothing it declares ' +
       'under another name is reachable'))
   }

package/src/action/dispatch.ts

@@ -1,7 +1,7 @@
 // WHAT `voxgig-sdkgen <action> …` CAN BE.
 //
 // Built FROM THE KIND REGISTRY rather than hand-listed, so registering a kind
-// is the only edit a new kind needs — `docs add …` costs no dispatch code
+// is the only edit a new kind needs — `edition add …` costs no dispatch code
 // (docs/design/sdkgen-packages.md §9). The `package` and `doctor` verbs are
 // not kinds and are added beside it.
 //
@@ -25,7 +25,7 @@ import { KINDS } from './kind'
 
 import { action_target, target_add } from './target'
 import { action_feature, feature_add } from './feature'
-import { action_docs, docs_add } from './docs'
+import { action_edition, edition_add } from './edition'
 import { action_doctor } from './doctor'
 import { action_package, registerAdder } from './package'
 
@@ -41,7 +41,7 @@ const KIND_ACTIONS: Record<string, ActionFunc> = Object.assign(
   Object.create(null), {
   target: action_target,
   feature: action_feature,
-  docs: action_docs,
+  edition: action_edition,
 })
 
 
@@ -49,7 +49,7 @@ const KIND_ACTIONS: Record<string, ActionFunc> = Object.assign(
 // over. Registered rather than imported by `package.ts`, for the cycle above.
 registerAdder('target', target_add)
 registerAdder('feature', feature_add)
-registerAdder('docs', docs_add)
+registerAdder('edition', edition_add)
 
 
 function actionMap(): Record<string, ActionFunc> {

package/src/action/doctor.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // `voxgig-sdkgen doctor` — does this project's `.sdk/` still match the
 // scaffold?
 //
@@ -276,7 +277,7 @@ async function doctor(
 
   const counts: Record<string, number> = {}
   for (const kind of kinds) {
-    counts[kind] = Object.keys((model as any)?.main?.[KIT]?.[kind] ?? {}).length
+    counts[kind] = Object.keys(kindCollection(model, kind) ?? {}).length
   }
 
   log.info({ point: 'doctor-start', targets: counts.target ?? 0, ...counts })
@@ -303,7 +304,7 @@ async function doctor(
   }
 
   for (const kind of kinds) {
-    const items = Object.keys((model as any)?.main?.[KIT]?.[kind] ?? {}).sort()
+    const items = Object.keys(kindCollection(model, kind) ?? {}).sort()
 
     for (const name of items) {
       if (null != scope && !scope(kind, name)) {
@@ -321,8 +322,8 @@ async function doctor(
         checkTarget(actx, source, report)
       }
 
-      if ('docs' === kind) {
-        checkDocs(actx, source, report)
+      if ('edition' === kind) {
+        checkEdition(actx, source, report)
       }
 
       // Only an ACTIVE feature has source copied out; what an inactive one
@@ -433,7 +434,7 @@ function checkWiring(actx: ActionContext, report: DoctorReport) {
 function resolveDeclared(
   kind: string, name: string, actx: ActionContext,
 ): Source | undefined {
-  const declared: any = (actx.model as any)?.main?.[KIT]?.[kind]?.[name]
+  const declared: any = kindCollection(actx.model, kind)?.[name]
   const ref = recordedRef(declared, name) || name
 
   try {
@@ -659,8 +660,8 @@ function compareTrees(
 // rather than being spelled a second time.
 //
 // The optional template tree is skipped when the SOURCE does not ship one:
-// `docs add` did not copy it, so the project is right not to have it.
-function checkDocs(
+// `edition add` did not copy it, so the project is right not to have it.
+function checkEdition(
   actx: ActionContext, resolved: Source, report: DoctorReport,
 ) {
   const fs = actx.fs()
@@ -669,8 +670,8 @@ function checkDocs(
   const origname = resolved.origname
   const aliased = name !== origname
 
-  const dest = kindTrees('docs', name)
-  const from = kindTrees('docs', origname)
+  const dest = kindTrees('edition', name)
+  const from = kindTrees('edition', origname)
 
   const trees: TreeCompare[] = dest.flatMap((tree: TreeDef, i: number) => {
     const scaffold = Path.join(resolved.folder, ...from[i].path.split('/'))

package/src/action/{docs.ts → edition.ts}

@@ -1,4 +1,5 @@
-// `docs add <ref>` — the third kind. See docs/design/sdkgen-packages.md §20.
+import { kindCollection } from '../helpers/kindCollection'
+// `edition add <ref>` — the third kind. See edition/design/sdkgen-packages.md §20.
 //
 // WHAT A DOCS ITEM IS
 //
@@ -12,11 +13,11 @@
 //
 // Three reasons, argued in §20.2 and worth restating where the code is:
 //
-//   - a docs item's INPUT is the target collection — a page per SDK, the
-//     package table, per-language tabs — so a docs item inside
+//   - a edition item's INPUT is the target collection — a page per SDK, the
+//     package table, per-language tabs — so a edition item inside
 //     `main.kit.target` would enumerate itself;
 //   - `action/feature.ts` fans out with `each(target, …)` and warns
-//     `feature-source-missing` per target with no source, so a docs item in
+//     `feature-source-missing` per target with no source, so a edition item in
 //     that collection would collect one warning per feature, forever
 //     (`srcfeature: false` does not help — that flag is read at generate time
 //     and never by the add-time fan-out);
@@ -30,7 +31,7 @@
 // aliasing and the index come along unchanged — and the kind's trees, whose
 // paths come from the registry rather than being spelled here.
 //
-// It does NOT fan out over targets, trim, or prune. A docs item reads the
+// It does NOT fan out over targets, trim, or prune. A edition item reads the
 // target collection at GENERATE time, not at add time: the opposite direction
 // and the opposite moment from a feature's fan-out, so sharing that machinery
 // would have been a false economy.
@@ -58,26 +59,26 @@ import { aliasCmpTree, pruneStaleTemplates } from './target'
 import { parseAddNames, loadContent, ensureModelInclude } from './action'
 
 
-// The PREFIX of a docs item's component tree (`src/cmp/docs/`), for the
+// The PREFIX of a edition item's component tree (`src/cmp/edition/`), for the
 // alias rewrite. Derived from the registry's declaration rather than written
-// out a second time, so the two cannot disagree about where docs components
+// out a second time, so the two cannot disagree about where edition components
 // live.
 const NAME_MARK = '\u0001name\u0001'
 
 function cmpBase(): string {
-  const cmp = kindTrees('docs', NAME_MARK)
+  const cmp = kindTrees('edition', NAME_MARK)
     .find((t: TreeDef) => 'none' === t.replace)
 
-  return null == cmp ? 'src/cmp/docs/' : cmp.path.split(NAME_MARK)[0]
+  return null == cmp ? 'src/cmp/edition/' : cmp.path.split(NAME_MARK)[0]
 }
 
 
 const CMD_MAP: any = Object.assign(Object.create(null), {
-  add: cmd_docs_add,
+  add: cmd_edition_add,
 })
 
 
-async function action_docs(
+async function action_edition(
   args: string[], actx: ActionContext,
 ): Promise<ActionResult> {
   const cmdname = args[1]
@@ -85,7 +86,7 @@ async function action_docs(
 
   if (null == cmd) {
     throw new SdkGenError(
-      'Unknown docs cmd: ' + cmdname + ' (expected: ' +
+      'Unknown edition cmd: ' + cmdname + ' (expected: ' +
       Object.keys(CMD_MAP).sort().join(', ') + ')')
   }
 
@@ -93,17 +94,19 @@ async function action_docs(
 }
 
 
-async function cmd_docs_add(
+async function cmd_edition_add(
   args: string[], actx: ActionContext,
 ): Promise<ActionResult> {
-  return docs_add(parseAddNames(args), actx)
+  return edition_add(parseAddNames(args), actx)
 }
 
 
 // Code API.
-async function docs_add(
-  docs: string[], actx: ActionContext,
+async function edition_add(
+  edition: string[], actx: ActionContext,
 ): Promise<ActionResult> {
+  edition = edition.map(ref => !ref.includes('/') && !ref.includes('\\') &&
+    !kindCollection(actx.model, 'edition')[ref.split('~')[0]] ? '@voxgig/docgen/project/' + ref : ref)
   const jostraca = actx.jostraca
 
   const opts = {
@@ -112,9 +115,9 @@ async function docs_add(
     log: actx.log.child({ cmp: 'jostraca' }),
     meta: {
       url: actx.url,
-      // Seeded: no project scaffolded before the docs kind existed has a
-      // docs index, and every project alive today is in that position.
-      content: loadContent(actx, 'docs', { docs: '# Docs\n' }),
+      // Seeded: no project scaffolded before the edition kind existed has a
+      // edition index, and every project alive today is in that position.
+      content: loadContent(actx, 'edition', { edition: '# Docs\n' }),
     },
     model: actx.model,
     // Per-call, never left to the Jostraca instance: `generate` runs its own
@@ -130,7 +133,7 @@ async function docs_add(
   }
 
   opts.log.info({
-    point: 'docs-start',
+    point: 'edition-start',
     note: (actx.opts.dryrun ? '** DRY RUN **' : '')
   })
 
@@ -138,26 +141,26 @@ async function docs_add(
   //
   // The write pass emits the definition and its index entry before it copies
   // the trees, so a ref whose definition exists but whose required components
-  // do not left the command failed AND the project carrying a docs item with
+  // do not left the command failed AND the project carrying a edition item with
   // no implementation — which the next model compile then reads as real.
   // `package add` already validates a whole package up front for exactly this
-  // reason; a direct `docs add` needs the same guarantee.
-  preflight(docs, actx)
+  // reason; a direct `edition add` needs the same guarantee.
+  preflight(edition, actx)
 
-  // The project's own model must INCLUDE the docs index, or everything below
+  // The project's own model must INCLUDE the edition index, or everything below
   // is invisible: no project scaffolded before this kind existed includes it,
-  // and `main.kit.docs` would simply be absent from the next compile.
-  ensureModelInclude(actx, 'docs')
+  // and `main.kit.edition` would simply be absent from the next compile.
+  ensureModelInclude(actx, 'edition')
 
   // Into the IN-MEMORY model before anything reads it. Nothing recompiles
-  // `model/sdk.aontu` mid-process, so without this a second docs item in the
+  // `model/sdk.aontu` mid-process, so without this a second edition item in the
   // same command — and anything else later in it — behaves as if the first
   // was never installed. One definition of what gets recorded, shared with
   // `target add` and `package add`.
-  registerInstalled('docs', docs, actx)
+  registerInstalled('edition', edition, actx)
 
   const jres = await jostraca.generate(opts, () =>
-    DocsRoot({ docs, actx }))
+    EditionRoot({ edition, actx }))
 
   return { jres }
 }
@@ -166,13 +169,13 @@ async function docs_add(
 // Resolve every ref and check every REQUIRED tree, throwing before anything
 // is written. Resolution itself is the other half: a ref that names no
 // definition fails here rather than partway through the pass.
-function preflight(docs: string[], actx: ActionContext) {
+function preflight(edition: string[], actx: ActionContext) {
   const fs = actx.fs()
 
-  for (const ref of docs) {
-    const source = resolveKind(ref, 'docs', actx as any)
+  for (const ref of edition) {
+    const source = resolveKind(ref, 'edition', actx as any)
 
-    for (const tree of kindTrees('docs', source.origname)) {
+    for (const tree of kindTrees('edition', source.origname)) {
       if (!tree.required) {
         continue
       }
@@ -182,7 +185,7 @@ function preflight(docs: string[], actx: ActionContext) {
       if (!fs.existsSync(from)) {
         throw new SdkGenError(
           'Docs ' + source.name + ': required tree not found: ' + from +
-          '\n  a docs item needs its components (' + tree.path +
+          '\n  a edition item needs its components (' + tree.path +
           '); nothing has been written')
       }
     }
@@ -190,8 +193,8 @@ function preflight(docs: string[], actx: ActionContext) {
 }
 
 
-const DocsRoot = cmp(function DocsRoot(props: any) {
-  const { ctx$, docs } = props
+const EditionRoot = cmp(function EditionRoot(props: any) {
+  const { ctx$, edition } = props
   const { log } = ctx$
 
   Project({}, () => {
@@ -200,29 +203,29 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
     // carry all of them.
     const dnames: string[] = []
 
-    each(docs, (n: any) => {
+    each(edition, (n: any) => {
       const dref = n.val$
 
-      log.info({ point: 'docs-build', docs: dref, note: dref })
+      log.info({ point: 'edition-build', edition: dref, note: dref })
 
       // The shared spine: a BARE name resolves against what the model
-      // RECORDS, so a docs item installed from a package resolves back to
+      // RECORDS, so a edition item installed from a package resolves back to
       // that package on its next add rather than to the bundled scaffold.
-      const source = resolveKind(dref, 'docs', ctx$)
+      const source = resolveKind(dref, 'edition', ctx$)
 
       dnames.push(source.name)
 
       log.info({
-        point: 'docs-name', docs: source.name, folder: source.folder, ref: dref,
+        point: 'edition-name', edition: source.name, folder: source.folder, ref: dref,
         note: source.name +
           (source.name !== source.origname ?
             ' (from ' + source.origname + ')' : '') +
           ' from:' + source.folder
       })
 
-      Folder({ name: 'model/docs' }, () => kindModel({
-        ctx$, kind: 'docs', source, names: dnames,
-        content: ctx$.meta.content.docs_index,
+      Folder({ name: 'model/edition' }, () => kindModel({
+        ctx$, kind: 'edition', source, names: dnames,
+        content: ctx$.meta.content.edition_index,
       }))
 
       // Both ends of every tree come from the registry's ONE declaration,
@@ -230,8 +233,8 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
       // the installed one. Deriving the source path by substituting inside
       // the destination path would corrupt any item whose name also appears
       // in the fixed part of the path.
-      const dest = kindTrees('docs', source.name)
-      const from = kindTrees('docs', source.origname)
+      const dest = kindTrees('edition', source.name)
+      const from = kindTrees('edition', source.origname)
 
       dest.forEach((tree: TreeDef, i: number) => {
         // Copy only ADDS and overwrites. A newer version of the package that
@@ -252,7 +255,7 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
         copyTree(ctx$, source, tree, from[i].path)
       })
 
-      log.info({ point: 'docs-done', docs: source.name, note: source.name })
+      log.info({ point: 'edition-done', edition: source.name, note: source.name })
     })
   })
 })
@@ -261,7 +264,7 @@ const DocsRoot = cmp(function DocsRoot(props: any) {
 // One tree, copied from the origin path to the installed one.
 //
 // An optional tree the source does not ship is simply not copied — that is
-// what `required: false` means, and a docs item whose every byte is generated
+// what `required: false` means, and a edition item whose every byte is generated
 // legitimately has no template tree.
 function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
   const fs = ctx$.fs()
@@ -274,7 +277,7 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
     }
 
     ctx$.log.info({
-      point: 'docs-tree-absent', docs: source.name, tree: tree.path, from,
+      point: 'edition-tree-absent', edition: source.name, tree: tree.path, from,
       note: source.name + ': the source ships no ' + frompath +
         ', nothing to copy'
     })
@@ -282,8 +285,8 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
   }
 
   // An ALIASED component tree cannot be copied verbatim: components are
-  // dispatched by the convention `cmp/docs/<n>/Main_<n>`, so files keeping
-  // the origin suffix resolve nothing — `Main_apidocs.ts` is invisible to a
+  // dispatched by the convention `cmp/edition/<n>/Main_<n>`, so files keeping
+  // the origin suffix resolve nothing — `Main_summary.ts` is invisible to a
   // lookup for `Main_portal`. Same rule as a target's, so the same function
   // does it; jostraca's tree Copy has no per-entry rename hook, which is why
   // an aliased tree is emitted file by file.
@@ -305,6 +308,6 @@ function copyTree(ctx$: any, source: any, tree: TreeDef, frompath: string) {
 
 
 export {
-  action_docs,
-  docs_add,
+  action_edition,
+  edition_add,
 }

package/src/action/kind.ts

@@ -1,3 +1,4 @@
+import { kindCollection } from '../helpers/kindCollection'
 // KINDS: the things an `add` can install.
 //
 // `target` and `feature` are two of them, `docs` and others are meant to
@@ -20,6 +21,7 @@
 // are genuinely different work, not the same work with different strings, and
 // pretending otherwise would buy generality nobody can use.
 
+
 import Path from 'node:path'
 
 import { File, Copy, Content, template } from 'jostraca'
@@ -30,7 +32,7 @@ import { SdkGenError } from '../utility'
 
 import { provenanceReplace } from '../helpers/stdrep'
 
-import { resolveSource } from './resolve'
+import { resolveSource, recordedRef, isBare } from './resolve'
 import type { Source } from './resolve'
 
 import { UpdateIndex } from './action'
@@ -92,7 +94,7 @@ type TreeDef = {
 
 // Rewrite the ITEM KEY in a copied model file, for an aliased install.
 //
-// Parameterised by kind because `main: kit: docs: <n>:` is the same rewrite
+// Parameterised by kind because `main: kit: doc: edition: <n>:` is the same rewrite
 // with a different word, and a second copy of this regex is exactly the
 // same-rule-written-twice defect the registry exists to prevent.
 //
@@ -156,21 +158,21 @@ const KINDS: Record<string, KindDef> = Object.assign(Object.create(null), {
 
   // DOCS — the third kind. See docs/design/sdkgen-packages.md §20.
   //
-  // Its trees are NESTED under the kind name (`src/cmp/docs/<n>`, not
+  // Its trees are NESTED under the kind name (`src/cmp/edition/<n>`, not
   // `src/cmp/<n>`) so a docs item and a target may share a name without
   // sharing a directory. Everything that composes those paths takes them
   // from here.
   //
-  // `tm/docs/{name}` is NOT required: a docs item whose every emitted byte
+  // `tm/edition/{name}` is NOT required: a docs item whose every emitted byte
   // depends on the API — a catalogue entry, a config file — legitimately
   // ships no template tree, while a static site needs one. So it is
   // copy-if-present, and `package check` does not demand it.
-  docs: {
-    name: 'docs', alias: true, ownedWhenAliased: true,
-    rename: aliasModelKey('docs'),
+  edition: {
+    name: 'edition', alias: true, ownedWhenAliased: true,
+    rename: aliasModelKey('edition'),
     trees: [
-      { path: 'src/cmp/docs/{name}', replace: 'none', required: true },
-      { path: 'tm/docs/{name}', replace: 'template', required: false },
+      { path: 'src/cmp/edition/{name}', replace: 'none', required: true },
+      { path: 'tm/edition/{name}', replace: 'template', required: false },
     ],
   },
 })
@@ -208,12 +210,7 @@ function kindDef(kind: string): KindDef {
 // source.
 function resolveKind(ref: string, kind: string, ctx$: any): Source {
   const def = kindDef(kind)
-  const model = ctx$.model
-
-  const declared: any = model?.main?.[KIT]?.[kind]?.[ref]
-  const recorded = (isBare(ref) && recordedRef(declared, ref)) || ref
-
-  const source = resolveSource(recorded, kind, ctx$)
+  const source = resolveSource(ref, kind, ctx$)
 
   // Asked of the RESOLVER rather than by re-reading the ref. `~` separates an
   // alias only in the last segment, and a check that looked for one anywhere
@@ -334,24 +331,6 @@ function kindModel(props: {
 // ONE definition, used by the add actions and by doctor. This reconstruction
 // was written twice and the two copies had already diverged on exactly this
 // point, which is the drift the kind spine exists to end.
-function recordedRef(declared: any, name: string): string | undefined {
-  if (null == declared?.base || '' === declared.base) {
-    return undefined
-  }
-
-  const origname = declared.origname || name
-
-  return Path.join(declared.base, '..', origname) +
-    (origname === name ? '' : '~' + name)
-}
-
-
-// A bare NAME, as opposed to a ref that locates a source.
-function isBare(ref: string): boolean {
-  return !ref.includes('/') && !ref.includes(Path.sep)
-}
-
-
 function capitalise(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1)
 }