@voxgig/sdkgen 1.2.1 → 1.3.2

package/project/.sdk/src/cmp/ts/ReadmeEntity_ts.ts

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
@@ -41,6 +43,10 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+    const eVar = safeVarName(entity.name, target.name)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +59,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`const ${eVar} = client.${entity.Name}()\`
 
 `)
 
@@ -84,7 +90,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -93,10 +99,22 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape that generates <Name>LoadMatch, so the
+      // example always type-checks.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `${it.name}: ${exampleValue(entity, entity.op && entity.op.load, it.name,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
 \`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+const ${eVar} = await client.${entity.Name}().load(${loadArg})
 \`\`\`
 
 `)
@@ -106,23 +124,27 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
       Content(`#### Example: List
 
 \`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+const ${eVar}s = await client.${entity.Name}().list()
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape that generates <Name>CreateData:
+      // every required member must appear (the /* type */ placeholders also
+      // mark the block as an illustration for the doc gates); an
+      // all-optional create renders an empty — still assignable — literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
 \`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+const ${eVar} = await client.${entity.Name}().create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+      createItems.map((it: any) => {
+        Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
 `)
-        }
       })
       Content(`})
 \`\`\`

package/project/.sdk/src/cmp/ts/ReadmeExampleTest_ts.ts

@@ -0,0 +1,81 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Generates ts/test/ReadmeExample.test.ts — a test that reads the
+// repo's top-level README.md at runtime, extracts the first TS code
+// block under "## Quickstart", transforms `new <Name>SDK(...)`
+// to `<Name>SDK.test()` so it runs offline, evaluates the rest, and
+// asserts no error. Catches drift between the README quickstart and
+// the real SDK API.
+const ReadmeExampleTest = cmp(function ReadmeExampleTest(props: any) {
+  const { ctx$: { model } } = props
+  const Name = model.const.Name
+
+  File({ name: 'ReadmeExample.test.ts' }, () => {
+    Content(`// Verifies the README's lead-language quickstart still runs.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+
+import { ${Name}SDK } from '..'
+
+
+function findFirstTsBlock(md: string, sectionHeading: string): string | null {
+  const escapedHeading = sectionHeading.replace(/[.*+?^\${}()|[\\]\\\\]/g, '\\\\$&')
+  const re = new RegExp('##\\\\s+' + escapedHeading + '[\\\\s\\\\S]*?\`\`\`ts\\\\n([\\\\s\\\\S]*?)\`\`\`')
+  const m = md.match(re)
+  return m ? m[1] : null
+}
+
+
+function transformForTestMode(code: string, name: string): string {
+  // Strip import lines — symbols come from the test's outer scope.
+  let out = code.replace(/^\\s*import\\s+[^;\\n]+;?\\s*$/gm, '')
+  // Swap real client construction for test mode (no network, no auth).
+  out = out.replace(new RegExp('new\\\\s+' + name + 'SDK\\\\([^)]*\\\\)', 'g'), name + 'SDK.test()')
+  return out
+}
+
+
+describe('README example', () => {
+  it('lead-language quickstart runs in test mode', async () => {
+    const readmePath = Path.join(__dirname, '..', '..', 'README.md')
+    const md = Fs.readFileSync(readmePath, 'utf8')
+
+    const block = findFirstTsBlock(md, 'Quickstart')
+    assert(block, 'No TypeScript code block found under "## Quickstart" in README.md')
+
+    const code = transformForTestMode(block, '${Name}')
+
+    // Run the (transformed) example. Async, so wrap in AsyncFunction.
+    const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+    const silentConsole = { log: () => {}, error: () => {}, warn: () => {} }
+    const runner = new AsyncFunction('${Name}SDK', 'console', code)
+
+    // The example should at least parse and have a valid call shape
+    // (every method exists on the SDK and accepts the args shown). A
+    // "Not found" / 404 from test mode means the SDK accepted the call
+    // but there's no fixture for that match — that's a test-data gap,
+    // not a README bug, so it's OK. Everything else (TypeError,
+    // ReferenceError, SyntaxError) means the README example is out of
+    // sync with the real SDK API and the test should fail.
+    try {
+      await runner(${Name}SDK, silentConsole)
+    } catch (err: any) {
+      const msg = String(err?.message ?? err)
+      if (/\\b(404|Not found)\\b/i.test(msg)) return
+      throw err
+    }
+  })
+})
+`)
+  })
+})
+
+
+export {
+  ReadmeExampleTest
+}

package/project/.sdk/src/cmp/ts/ReadmeExamplesTest_ts.ts

@@ -0,0 +1,446 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Generates ts/test/readme_examples.test.ts — a COMPLETENESS GATE that
+// guarantees every fenced \`\`\`ts code example across all THREE docs (the
+// repo root README.md, this target's per-language README.md, and its
+// REFERENCE.md) is unit-tested. Every block from every doc is:
+//
+//  (1) TYPE-CHECKED against the real SDK types with the repo's local
+//      \`tsc --noEmit\`. To stay robust against tsc suppressing all semantic
+//      diagnostics program-wide whenever one file has a syntax error, blocks
+//      are compiled one-file-per-block in a fixpoint: compile the batch, drop
+//      the ones that error, recompile the rest, until a pass is clean — so a
+//      real type bug can never hide behind a neighbouring illustration's
+//      syntax error.
+//  (2) EXECUTED, if RUNNABLE (constructs \`new <Sdk>SDK\` / \`<Sdk>SDK.test\`
+//      or drives \`client.\`), by rewriting it to a seeded test-mode client
+//      and running it offline. A programming error (undefined method, wrong
+//      arity, bad symbol) fails; only a 404 / "Not found" domain error for an
+//      unseeded id is tolerated. This now runs for ALL THREE docs (previously
+//      only the root README executed).
+//  (3) PARTITIONED into exactly one of { executed, typechecked-only,
+//      illustration } with the counts asserted to sum to the total. A block
+//      that does NOT type-check is only allowed if it matches the NARROW
+//      illustration allowlist (bare method-signature \`?:\`, \`/* placeholder */\`
+//      value, or a type-SHAPE block). Any other non-type-checking block FAILS
+//      the test, quoting the block — it is NEVER silently skipped. A per-doc
+//      summary line makes the coverage visible in the test output.
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { ctx$: { model } } = props
+  const Name = model.const.Name
+
+  // Seed a fixture for every active entity so list()/load() resolve
+  // offline in test mode with no network. Keyed by the entity's model
+  // name (the same key the test-mode transport looks up).
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const seedEntities: Record<string, any> = {}
+  Object.values(entity).forEach((e: any) => {
+    if (e && false !== e.active && 'string' === typeof e.name) {
+      seedEntities[e.name] = { test01: { id: 'test01' } }
+    }
+  })
+  const seedLiteral = JSON.stringify({ entity: seedEntities })
+
+  File({ name: 'readme_examples.test.ts' }, () => {
+    Content(`// Completeness gate over every TypeScript example in this SDK's docs.
+//
+// Covers all THREE documentation files — the repo root README.md, this
+// target's README.md, and its REFERENCE.md. Every fenced \`\`\`ts block in
+// every one is put through the same pipeline:
+//
+//  (1) TYPE-CHECK — every block is compiled with the repo's local
+//      \`tsc --noEmit\` against the real SDK types. A block that misuses the
+//      SDK types (e.g. \`.data\` on a \`list()\` array, or a string id where a
+//      number is required) is a compile error.
+//  (2) EXECUTE — every RUNNABLE block (one that constructs the SDK or
+//      drives \`client.\`) is rewritten to seeded test mode, transpiled to
+//      JS, and run offline. A programming error (undefined method,
+//      wrong-arg-count, bad symbol) fails the test; only an expected domain
+//      error (a 404 / "Not found" for an unseeded id) is tolerated.
+//  (3) COMPLETENESS — every block is partitioned into exactly one of
+//      { executed, typechecked-only, illustration } and the counts must sum
+//      to the total. A block that does NOT type-check is allowed ONLY if it
+//      matches the NARROW illustration allowlist (a bare method signature
+//      \`?:\`, a \`/* placeholder */\` value, or a type-SHAPE block). Any other
+//      non-type-checking block FAILS the test, quoting the block — it is
+//      never silently skipped.
+//
+// Generated by @voxgig/sdkgen — do not edit by hand.
+
+import { describe, it } from 'node:test'
+import assert from 'node:assert'
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+import { createRequire } from 'node:module'
+import { spawnSync } from 'node:child_process'
+
+import { ${Name}SDK } from '..'
+
+
+const SDK_NAME = '${Name}SDK'
+
+// A fixture for every entity, so list()/load() resolve offline with no
+// network. Snippet client construction is rewritten to seed this.
+const TEST_SEED = ${seedLiteral}
+const SEED_ARG = JSON.stringify(TEST_SEED)
+const SEEDED_CTOR = SDK_NAME + '.test(' + SEED_ARG + ')'
+
+
+// The three docs this gate covers, resolved relative to dist-test/.
+const DOCS: Array<{ label: string; key: string; path: string }> = [
+  { label: 'root README.md', key: 'root_readme', path: Path.join(__dirname, '..', '..', 'README.md') },
+  { label: 'ts/README.md', key: 'lang_readme', path: Path.join(__dirname, '..', 'README.md') },
+  { label: 'ts/REFERENCE.md', key: 'reference', path: Path.join(__dirname, '..', 'REFERENCE.md') },
+]
+
+
+// Pull out the body of every \`\`\`ts fenced code block.
+function extractTsBlocks(md: string): string[] {
+  const blocks: string[] = []
+  const re = /\`\`\`ts\\n([\\s\\S]*?)\`\`\`/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(md)) !== null) {
+    blocks.push(m[1])
+  }
+  return blocks
+}
+
+
+// Snippet import lines reference the published package name, which is not
+// resolvable from inside the repo; the SDK symbol is supplied by the one
+// module-level import we emit / inject instead.
+function stripImports(code: string): string {
+  return code.replace(/^\\s*import\\s+[^\\n]*$/gm, '')
+}
+
+
+// A block is an ILLUSTRATION shape — documentation, not runnable code — if
+// it matches this NARROW allowlist. These are the ONLY shapes a
+// non-type-checking block is allowed to be; anything else that fails to
+// type-check is a real bug and fails the gate. Three shapes:
+//   1. a bare method / constructor signature with a typed-parameter
+//      signature ("?:", e.g. \`options?: { base?: string }\`);
+//   2. a placeholder-comment value ("/*", e.g. \`field: /* string */\`);
+//   3. a type-SHAPE block that lists fields as \`name: TypeKeyword\` with the
+//      type standing alone as the value — e.g. the DirectResult / FetchDef
+//      shape \`{ ok: boolean; status: number; ... }\`. Those bare keywords
+//      are undeclared VALUES (TS2693 "only refers to a type"). Matched
+//      only at the START of a line, so a genuine annotation inside runnable
+//      code (e.g. \`(ctx: any) => ...\`) is NOT matched.
+const SHAPE_ILLUSTRATION =
+  /^\\s*[A-Za-z_$][\\w$]*\\??\\s*:\\s*(?:boolean|number|string|object|any|unknown|never|void|symbol|bigint|Record<|Partial<|Array<|Map<|Set<)/m
+function isIllustrationShape(code: string): boolean {
+  if (code.includes('?:')) {
+    return true
+  }
+  if (code.includes('/*')) {
+    return true
+  }
+  if (SHAPE_ILLUSTRATION.test(code)) {
+    return true
+  }
+  return false
+}
+
+
+// A block is RUNNABLE if it constructs the SDK (\`new <Sdk>SDK\` /
+// \`<Sdk>SDK.test\`) or drives a \`client.\` — those are the blocks the execute
+// gate rewrites to seeded test mode and runs.
+function isRunnable(code: string): boolean {
+  return (
+    /new\\s+${Name}SDK\\b/.test(code) ||
+    /\\b${Name}SDK\\.test\\b/.test(code) ||
+    /\\bclient\\s*\\./.test(code)
+  )
+}
+
+
+// Wrap ONE block as a self-contained temp module: the block goes in its own
+// scope inside an async function with a shared seeded \`client\`.
+function buildSnippetModule(block: string): string {
+  const inner = stripImports(block).split('\\n').map((l) => '    ' + l).join('\\n')
+  return [
+    "import { " + SDK_NAME + " } from '..'",
+    '',
+    'async function __ex() {',
+    // Shared client for snippets that reference \`client\` without constructing
+    // one (e.g. the direct() example).
+    '  const client = ' + SDK_NAME + '.test()',
+    '  void client',
+    '  {',
+    inner,
+    '  }',
+    '}',
+    'void __ex',
+    '',
+  ].join('\\n')
+}
+
+
+// Compile a batch of blocks in ONE tsc pass — one temp file per block, so
+// each is an isolated program entry — and return which snippet indices
+// errored. NOTE: tsc suppresses ALL semantic diagnostics program-wide as
+// soon as any file has a SYNTAX error, so a single batch cannot be trusted;
+// \`typeCheckBlocks\` drives this in a fixpoint that removes erroring blocks
+// and recompiles the rest until a pass is clean.
+function compileBatch(indices: number[], blocks: string[], key: string): {
+  errored: Set<number>; raw: string; unattributed: boolean
+} {
+  const tsDir = Path.join(__dirname, '..')
+  const testDir = Path.join(tsDir, 'test')
+  // Leading dot: TypeScript wildcard includes skip dot-files, so these temp
+  // files are never swept into the normal build.
+  const files: string[] = []
+
+  try {
+    for (const i of indices) {
+      const f = Path.join(testDir, '.examples_' + key + '_snippet' + i + '.gen.ts')
+      Fs.writeFileSync(f, buildSnippetModule(blocks[i]), 'utf8')
+      files.push(f)
+    }
+
+    const requireFrom = createRequire(__filename)
+    const tsc = requireFrom.resolve('typescript/bin/tsc')
+
+    const res = spawnSync(process.execPath, [
+      tsc,
+      '--noEmit',
+      '--strict',
+      '--pretty', 'false',
+      '--target', 'ES2022',
+      '--module', 'nodenext',
+      '--moduleResolution', 'nodenext',
+      '--esModuleInterop',
+      '--resolveJsonModule',
+      '--skipLibCheck',
+      '--types', 'node',
+      ...files,
+    ], { cwd: tsDir, encoding: 'utf8' })
+
+    const raw = ((res.stdout || '') + (res.stderr || '')).trim()
+    const errored = new Set<number>()
+    let unattributed = false
+
+    if (0 !== res.status) {
+      for (const line of raw.split('\\n')) {
+        const m = /_snippet(\\d+)\\.gen\\.ts\\(\\d+,\\d+\\):\\s*error/.exec(line)
+        if (null == m) {
+          // A genuine error diagnostic not attributable to a snippet file
+          // (e.g. inside the SDK itself) is an anomaly.
+          if (/:\\s*error\\s+TS\\d+/.test(line)) {
+            unattributed = true
+          }
+          continue
+        }
+        errored.add(parseInt(m[1], 10))
+      }
+    }
+
+    return { errored, raw, unattributed }
+  } finally {
+    for (const f of files) {
+      Fs.rmSync(f, { force: true })
+    }
+  }
+}
+
+
+// Determine, robustly, which of a doc's blocks fail to type-check. Because
+// one syntax error suppresses semantic diagnostics for the whole batch, we
+// iterate: compile the still-unresolved blocks, record the ones that
+// errored, drop them, and recompile the rest — until a pass reports no
+// errors. Each erroring pass strictly shrinks the working set, so this
+// terminates. \`globalError\` flags an unattributable tsc error, surfaced
+// verbatim by the caller.
+function typeCheckBlocks(blocks: string[], key: string): {
+  failing: Set<number>; raw: string; globalError: boolean
+} {
+  const failing = new Set<number>()
+  const raws: string[] = []
+  let globalError = false
+  let remaining = blocks.map((_b, i) => i)
+
+  // Guard: at most one pass per block plus a final clean pass.
+  for (let pass = 0; pass <= blocks.length && 0 < remaining.length; pass++) {
+    const { errored, raw, unattributed } = compileBatch(remaining, blocks, key)
+    raws.push(raw)
+    if (unattributed) {
+      globalError = true
+    }
+    if (0 === errored.size) {
+      break
+    }
+    for (const i of errored) {
+      failing.add(i)
+    }
+    remaining = remaining.filter((i) => !errored.has(i))
+  }
+
+  return { failing, raw: raws.filter(Boolean).join('\\n'), globalError }
+}
+
+
+// Turn a documented snippet into an offline-runnable one: strip imports,
+// rewrite real client construction (\`new <Sdk>SDK(...)\` and any
+// \`<Sdk>SDK.test(...)\`) to a seeded test-mode client, and give snippets
+// that reference \`client\` without constructing one a shared seeded client.
+function rewriteForRun(code: string): string {
+  let out = stripImports(code)
+  out = out.replace(/new\\s+${Name}SDK\\s*\\([^)]*\\)/g, () => SEEDED_CTOR)
+  out = out.replace(/${Name}SDK\\.test\\s*\\([^)]*\\)/g, () => SEEDED_CTOR)
+  if (/\\bclient\\b/.test(out) && !/\\b(?:const|let|var)\\s+client\\b/.test(out)) {
+    out = 'const client = ' + SEEDED_CTOR + '\\n' + out
+  }
+  return out
+}
+
+
+// Run every runnable, non-illustration block from a doc offline in seeded
+// test mode. Returns a list of failure descriptions (empty === all passed).
+async function executeBlocks(blocks: string[]): Promise<string[]> {
+  const requireFrom = createRequire(__filename)
+  const ts = requireFrom('typescript')
+
+  const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+  const silentConsole = { log() {}, error() {}, warn() {}, info() {} }
+
+  const failures: string[] = []
+
+  for (let i = 0; i < blocks.length; i++) {
+    // Illustration shapes are documentation, not runnable code.
+    if (!isRunnable(blocks[i]) || isIllustrationShape(blocks[i])) {
+      continue
+    }
+
+    const src = rewriteForRun(blocks[i])
+    if ('' === src.trim()) {
+      continue
+    }
+
+    // Compile the snippet to JS (strips type annotations) so it runs under
+    // node exactly as a real caller would.
+    const js = ts.transpileModule(src, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ES2020,
+        module: ts.ModuleKind.ESNext,
+      },
+    }).outputText
+
+    let runner: any
+    try {
+      runner = new AsyncFunction(SDK_NAME, 'console', js)
+    } catch (err: any) {
+      failures.push('snippet ' + i + ' failed to compile as runnable JS: ' +
+        String((err && err.message) || err))
+      continue
+    }
+
+    try {
+      await runner(${Name}SDK, silentConsole)
+    } catch (err: any) {
+      const msg = String((err && err.message) || err)
+      // Tolerate the one expected domain error: no fixture seeded for the
+      // requested id (a 404 / "Not found" from test mode). A programming
+      // error (undefined method/symbol, wrong arg count) is a real doc bug
+      // and is NOT tolerated.
+      if (/\\b(?:404|not found)\\b/i.test(msg)) {
+        continue
+      }
+      failures.push('snippet ' + i + ' threw at runtime: ' + msg)
+    }
+  }
+
+  return failures
+}
+
+
+function indentBlock(code: string): string {
+  return code.replace(/^/gm, '    ').replace(/\\s+$/, '')
+}
+
+
+describe('README examples', () => {
+  for (const doc of DOCS) {
+    it(doc.label + ' — every example type-checks or is a known illustration', () => {
+      // A target without this doc has nothing to check.
+      if (!Fs.existsSync(doc.path)) {
+        return
+      }
+      const md = Fs.readFileSync(doc.path, 'utf8')
+      const blocks = extractTsBlocks(md)
+      assert(blocks.length > 0, 'No TypeScript code blocks found in ' + doc.label)
+
+      const { failing, raw, globalError } = typeCheckBlocks(blocks, doc.key)
+      assert(!globalError,
+        'tsc reported an error outside any snippet in ' + doc.label +
+        ' — the harness could not attribute it:\\n\\n' + raw + '\\n')
+
+      let executed = 0
+      let typecheckedOnly = 0
+      let illustration = 0
+      const unrecognized: string[] = []
+
+      blocks.forEach((b, i) => {
+        const typechecks = !failing.has(i)
+        const shape = isIllustrationShape(b)
+        const runnable = isRunnable(b) && !shape
+
+        if (!typechecks && shape) {
+          illustration++
+        } else if (!typechecks && !shape) {
+          unrecognized.push('  snippet ' + i + ':\\n' + indentBlock(b))
+        } else if (typechecks && runnable) {
+          executed++
+        } else {
+          typecheckedOnly++
+        }
+      })
+
+      // Emit the coverage summary FIRST so it is always visible, even when
+      // an assertion below fails.
+      console.log('README examples [' + doc.label + ']: total=' + blocks.length +
+        ' executed=' + executed + ' typechecked=' + typecheckedOnly +
+        ' illustration=' + illustration)
+
+      assert.strictEqual(unrecognized.length, 0,
+        'These ' + doc.label + ' \`\`\`ts blocks neither type-check nor match the ' +
+        'illustration allowlist. Fix the snippet (or the SDK), or — if it is ' +
+        'genuinely illustrative — reshape it to the allowlist:\\n\\n' +
+        unrecognized.join('\\n\\n') + '\\n\\ntsc output:\\n' + raw + '\\n')
+
+      assert.strictEqual(blocks.length, executed + typecheckedOnly + illustration,
+        'completeness partition mismatch for ' + doc.label + ': ' + blocks.length +
+        ' total != ' + executed + ' executed + ' + typecheckedOnly +
+        ' typechecked + ' + illustration + ' illustration')
+    })
+
+    it(doc.label + ' — every runnable example executes in test mode', async () => {
+      if (!Fs.existsSync(doc.path)) {
+        return
+      }
+      const md = Fs.readFileSync(doc.path, 'utf8')
+      const blocks = extractTsBlocks(md)
+      assert(blocks.length > 0, 'No TypeScript code blocks found in ' + doc.label)
+
+      const failures = await executeBlocks(blocks)
+      assert.strictEqual(failures.length, 0,
+        doc.label + ' runnable TypeScript snippets failed to run in test mode:\\n\\n' +
+        failures.join('\\n') + '\\n')
+    })
+  }
+})
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

package/project/.sdk/src/cmp/ts/ReadmeExplanation_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, packageName } from '@voxgig/sdkgen'
 
 
 const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
@@ -21,7 +21,7 @@ ${model.name}/
 Import the SDK from the package root:
 
 \`\`\`ts
-import { ${model.Name}SDK } from '${model.name}'
+import { ${model.Name}SDK } from '${packageName(model, target.name)}'
 \`\`\`
 
 `)