@estiva-app/ui 0.35.1 → 0.36.0

package/src/gates/status.ts

@@ -31,6 +31,7 @@ import { createRequire } from 'node:module'
 import { join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { ESLint as ESLintClass } from 'eslint'
+import { escapeLines, listEscapes } from './escapes'
 
 export type CheckResult = { result: 'pass' | 'fail' | 'part' | 'unknown'; detail: string }
 type Maybe<T> = T | Promise<T>
@@ -141,6 +142,16 @@ const said = (e: unknown) => {
   return { text: `${err.stdout ?? ''}${err.stderr ?? ''}`, message: String(err.message ?? e), code: err.code }
 }
 
+/** The scripts `estiva-gates ci` runs (R13): a job that runs it runs these. */
+const GATE_CI_SCRIPTS = new Set(['lint:rules', 'lint:tokens', 'lint', 'registry:check'])
+
+/** `estiva-gates ci`, as a workflow runs it, when it runs `script`; null otherwise. A comment line does not count. */
+function runsGateCi(text: string, script: string | RegExp): string | null {
+  if (typeof script !== 'string' || !GATE_CI_SCRIPTS.has(script)) return null
+  const m = /^(?!\s*#).*?((?:npx )?estiva-gates ci\b|npm run gates:ci\b|cli\.js"? ci\b)/m.exec(text)
+  return m ? m[1] : null
+}
+
 /** The helpers, bound to one repository. */
 export function helpers(ROOT: string): GateHelpers {
   const abs = (rel: string) => resolve(ROOT, rel)
@@ -263,6 +274,8 @@ export function helpers(ROOT: string): GateHelpers {
       for (const f of files) {
         const m = read(f).match(step)
         if (m) return PASS(`${f} runs npm run ${m[1]}`)
+        const all = runsGateCi(read(f), script)
+        if (all) return PASS(`${f} runs ${all}, which runs npm run ${script}`)
       }
       return FAIL(`no workflow runs npm run ${script}`)
     },
@@ -285,7 +298,9 @@ export function helpers(ROOT: string): GateHelpers {
         if (start === -1) continue
         const end = lines.findIndex((l, i) => i > start && /^ {0,2}\S/.test(l))
         const body = lines.slice(start + 1, end === -1 ? undefined : end).join('\n')
-        return step.test(body) ? PASS(`${f}: the job ${job} runs npm run ${script}`) : FAIL(`${f}: the job ${job} does not run npm run ${script}`)
+        if (step.test(body)) return PASS(`${f}: the job ${job} runs npm run ${script}`)
+        const all = runsGateCi(body, script)
+        return all ? PASS(`${f}: the job ${job} runs ${all}, which runs npm run ${script}`) : FAIL(`${f}: the job ${job} does not run npm run ${script}`)
       }
       return FAIL(`no workflow has a job ${job}`)
     },
@@ -560,10 +575,35 @@ export interface StatusOptions {
   app?: string
   json?: boolean
   detail?: boolean
+  /** List every escape, not only those due for review (B1). */
+  escapes?: boolean
+}
+
+/**
+ * What an app's catalogue leaves for Katerina: the parts nothing uses, by name
+ * (her UIG-13 ruling: an unused part is listed for her, never deleted by the
+ * catalogue; R20), and the parts with no link into Storybook (R22). A reusable
+ * part with none fails `estiva-ui check`; a one-off needs none (B10), so its
+ * number is shown and nothing more.
+ */
+async function catalogueLines(appDir: string): Promise<string[]> {
+  try {
+    const { buildAppRegistry } = await import('../registry/index')
+    const entries = buildAppRegistry({ root: appDir }).entries
+    const unused = entries.filter((e) => e.app?.class === 'unused')
+    const oneOffs = entries.filter((e) => e.app?.class === 'one-off')
+    const unlinked = oneOffs.filter((e) => !e.storyId && !e.docsId)
+    return [
+      `Unused parts: ${unused.length}${unused.length ? ` · Katerina rules on each: ${unused.map((e) => `${e.name} (${e.sourceFile})`).join(', ')}` : ''}`,
+      `Storybook links: every reusable part has one (estiva-ui check holds it) · one-offs with none: ${unlinked.length} of ${oneOffs.length}, which need none`,
+    ]
+  } catch (error) {
+    return [`Catalogue: could not be built here: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`]
+  }
 }
 
 /** Print where the project stands. Returns what was printed, or the JSON report. */
-export async function runStatus({ root = process.cwd(), app = '.', json = false, detail = false }: StatusOptions = {}): Promise<string> {
+export async function runStatus({ root = process.cwd(), app = '.', json = false, detail = false, escapes = false }: StatusOptions = {}): Promise<string> {
   const ROOT = resolve(root)
   const h = helpers(ROOT)
   const shown = (dir: string) => (relative(ROOT, dir) || dir).replace(/\\/g, '/')
@@ -574,8 +614,11 @@ export async function runStatus({ root = process.cwd(), app = '.', json = false,
   const out: string[] = []
   out.push('UI Guardrails · gates:status', 'Read from the code. Nothing here is a hand-ticked list.', '')
   out.push(`${pad(spec.repo, 10)} ${report.branch} @ ${report.commit}${behindMain(ROOT)}`)
+  // Every escape, listed and aged (Katerina's rulings B1, 25 September): the ones due for review always.
+  out.push('', ...escapeLines(listEscapes(join(ROOT, app)), { all: escapes }))
 
   if (!spec.all) {
+    out.push('', ...(await catalogueLines(join(ROOT, app))))
     // A sibling repo on its own: its own rows, then its parts of rows owned elsewhere.
     const own = report.rows.filter((r) => r.owner).map((r) => ({ ...r, ownerRepo: spec.repo, status: statusOf(r.checks) }))
     const parts = report.rows.filter((r) => !r.owner).map((r) => ({ ...r, ownerRepo: '', status: statusOf(r.checks) }))

package/src/gates/token-lint.ts

@@ -39,6 +39,7 @@ import type { ESLint, Linter } from 'eslint'
 import betterTailwindcss from 'eslint-plugin-better-tailwindcss'
 import { getDefaultSelectors } from 'eslint-plugin-better-tailwindcss/defaults'
 import { parser as typescriptParser, plugin as typescriptPlugin } from 'typescript-eslint'
+import { INLINE_STYLE_MESSAGE, INLINE_STYLE_TOKEN_KEYS, tokenStylePlugin } from './token-style'
 
 /** Who reads the messages. */
 export type TokenAudience = 'app' | 'package'
@@ -162,8 +163,7 @@ const HAND_WRITTEN = {
   width: `${V}(?:border(?:-[xytrblse])?|divide-[xy]|outline|ring|ring-offset)-\\[(?:length:)?-?[0-9.]+(?:px|rem|em)?\\]$`,
 }
 
-const INLINE_STYLE_TOKEN_PROPERTIES =
-  '/^(color|background|backgroundColor|backgroundImage|fill|stroke|fontSize|border|borderTop|borderRight|borderBottom|borderLeft|borderBlock|borderInline|borderStyle|boxShadow|textShadow)$|Color$/'
+const INLINE_STYLE_TOKEN_PROPERTIES = String(INLINE_STYLE_TOKEN_KEYS)
 
 interface Preset {
   theme: { extend: { fontSize: Record<string, string | [string, unknown]>; borderRadius: Record<string, string> } }
@@ -204,8 +204,10 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
   return {
     files: ['**/*.{ts,tsx}'],
     ignores: ['**/*.test.ts', '**/*.test.tsx'],
-    plugins: { 'token-values': betterTailwindcss, 'token-spacing': betterTailwindcss },
+    plugins: { 'token-values': betterTailwindcss, 'token-spacing': betterTailwindcss, 'token-style': tokenStylePlugin },
     rules: {
+      // A style kept in a const and passed by name (R9): the selector below cannot follow it.
+      'token-style/no-token-style': 'error',
       'token-values/no-restricted-classes': [
         'error',
         {
@@ -252,7 +254,12 @@ export function tokenValues({ audience = 'app' }: Pick<TokenLintOptions, 'audien
         'error',
         {
           selector: `JSXAttribute[name.name="style"] > JSXExpressionContainer > ObjectExpression > Property[key.name=${INLINE_STYLE_TOKEN_PROPERTIES}]`,
-          message: 'An inline style that sets a colour, a font size, a border or a shadow is outside the token contract: use a token class. If the value is computed (a palette, a size from a prop), say why in an eslint-disable comment. Width, height and transforms are fine.',
+          message: INLINE_STYLE_MESSAGE,
+        },
+        // The same key in quotes, `style={{ 'background': 'red' }}` (R9).
+        {
+          selector: `JSXAttribute[name.name="style"] > JSXExpressionContainer > ObjectExpression > Property[key.value=${INLINE_STYLE_TOKEN_PROPERTIES}]`,
+          message: INLINE_STYLE_MESSAGE,
         },
       ],
     },

package/src/gates/token-style.ts

@@ -0,0 +1,79 @@
+/// <reference types="node" />
+/**
+ * The token contract's inline-style check, where a selector cannot reach
+ * (the second review's R9, 25 September). `no-restricted-syntax` reads a
+ * `style={{ … }}` written in place; a style kept in a `const` and passed by name
+ * got through every lint in all three repos:
+ *
+ *   const look = { background: 'red' }
+ *   <div style={look} />
+ *
+ * This follows the name to its `const` in the same file and reads the keys
+ * there, quoted or not. It reports on the key, where the value is written, so
+ * an escape sits beside it. A style the code works out while it runs passes:
+ * nothing can read it.
+ */
+import type { ESLint, Rule, Scope } from 'eslint'
+
+/** The style keys outside the token contract: colours, a font size, borders and shadows. */
+export const INLINE_STYLE_TOKEN_KEYS = /^(color|background|backgroundColor|backgroundImage|fill|stroke|fontSize|border|borderTop|borderRight|borderBottom|borderLeft|borderBlock|borderInline|borderStyle|boxShadow|textShadow)$|Color$/
+
+export const INLINE_STYLE_MESSAGE =
+  'An inline style that sets a colour, a font size, a border or a shadow is outside the token contract: use a token class. If the value is computed (a palette, a size from a prop), say why in an eslint-disable comment. Width, height and transforms are fine.'
+
+interface Node {
+  type: string
+  [key: string]: unknown
+}
+
+const keyOf = (property: Node): string | undefined => {
+  if (property.computed) return undefined
+  const key = property.key as Node
+  return key.type === 'Identifier' ? (key.name as string) : key.type === 'Literal' && typeof key.value === 'string' ? key.value : undefined
+}
+
+/** The object a `const` of this name holds, in this scope or one around it. */
+function constObject(name: string, scope: Scope.Scope | null): Node | undefined {
+  for (let current = scope; current; current = current.upper) {
+    const variable = current.set.get(name)
+    if (!variable) continue
+    const definition = variable.defs[0] as unknown as { type: string; node: Node; parent?: Node } | undefined
+    if (variable.defs.length !== 1 || definition?.type !== 'Variable' || definition.parent?.kind !== 'const') return undefined
+    let init = definition.node.init as Node | undefined
+    while (init && (init.type === 'TSAsExpression' || init.type === 'TSSatisfiesExpression')) init = init.expression as Node
+    return init?.type === 'ObjectExpression' ? init : undefined
+  }
+  return undefined
+}
+
+const noTokenStyle: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: { description: 'No colour, font size, border or shadow in a style kept in a const' },
+    schema: [],
+    messages: { token: INLINE_STYLE_MESSAGE },
+  },
+  create(context) {
+    const reported = new Set<unknown>()
+    return {
+      JSXAttribute(ruleNode: Rule.Node) {
+        const attribute = ruleNode as unknown as Node
+        if ((attribute.name as Node).name !== 'style') return
+        const value = attribute.value as Node | null
+        const expression = value?.type === 'JSXExpressionContainer' ? (value.expression as Node) : undefined
+        if (expression?.type !== 'Identifier') return
+        const object = constObject(expression.name as string, context.sourceCode.getScope(ruleNode))
+        for (const property of (object?.properties as Node[] | undefined) ?? []) {
+          if (property.type !== 'Property' || reported.has(property)) continue
+          const key = keyOf(property)
+          if (!key || !INLINE_STYLE_TOKEN_KEYS.test(key)) continue
+          reported.add(property)
+          context.report({ node: property as unknown as Rule.Node, messageId: 'token' })
+        }
+      },
+    }
+  },
+}
+
+/** The plugin, as the token lint registers it: `token-style/no-token-style`. */
+export const tokenStylePlugin: ESLint.Plugin = { rules: { 'no-token-style': noTokenStyle } }

package/src/how.test.ts

@@ -0,0 +1,282 @@
+/// <reference types="node" />
+/**
+ * The code under every page's `## How` compiles against the package (UIG-14:
+ * "Every How compiles — checked, not assumed"; Katerina's ruling R18, 25
+ * September). It was compiled once, by hand, on 19 September, and never again.
+ *
+ * Each ```tsx block under `## How` becomes a module of its own:
+ *
+ * 1. Its own `import` lines, verbatim; `'@estiva-app/ui'` is this package's
+ *    `src/index.ts`, so a wrong name in an import fails.
+ * 2. Every part it did not import, imported (a page shows a part's companions
+ *    without their import line).
+ * 3. The rest as the body of a component: all JSX, or statements then JSX, or
+ *    statements alone, whichever parses.
+ * 4. What the page leaves to the reader is a placeholder: a lower-case name or
+ *    an ALL_CAPS one is `any`, a React hook comes from React, an `Icon…` from
+ *    Tabler. A capitalised name the package does not have is an error — that is
+ *    what a wrong part name looks like — except the reader's own stand-ins
+ *    below, which the pages name on purpose.
+ *
+ * Then it is type-checked with the package's own settings. A part name, a prop
+ * name and a prop's literal value are checked; a prop given a placeholder is not
+ * (a placeholder is `any`).
+ */
+import { readdirSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import ts from 'typescript'
+import { describe, expect, it } from 'vitest'
+
+const REPO = process.cwd()
+const norm = (p: string) => p.replace(/\\/g, '/').toLowerCase()
+
+/** The reader's own components a page draws around a part (Katerina's ruling R18: an allow-list). */
+const STAND_INS = ['App', 'Conversation', 'ItemDetail', 'ItemRow', 'ListRow', 'Row', 'YourList']
+/** Browser globals a page may mean for real; any other lower-case lib.dom name is a placeholder (`name`, `open`). */
+const REAL_GLOBALS = new Set(['window', 'document', 'console', 'fetch', 'setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'requestAnimationFrame', 'navigator', 'localStorage', 'sessionStorage', 'globalThis', 'queueMicrotask', 'structuredClone'])
+
+interface Block {
+  page: string
+  /** The .mdx line of the block's first line of code. */
+  start: number
+  lines: string[]
+}
+
+function howBlocks(page: string, text: string): Block[] {
+  const lines = text.split(/\r?\n/)
+  const blocks: Block[] = []
+  let inHow = false
+  let fence: string | null = null
+  let start = 0
+  let buf: string[] = []
+  lines.forEach((line, i) => {
+    if (fence !== null) {
+      if (/^\s*```\s*$/.test(line)) {
+        if (inHow && fence === 'tsx') blocks.push({ page, start, lines: buf })
+        fence = null
+        buf = []
+      } else buf.push(line)
+      return
+    }
+    const open = /^\s*```(\S*)/.exec(line)
+    if (open) {
+      fence = open[1] || '(none)'
+      start = i + 2
+      return
+    }
+    if (/^## /.test(line)) inHow = /^## How\b/.test(line)
+  })
+  return blocks
+}
+
+function indexValueExports(): string[] {
+  const sf = ts.createSourceFile('index.ts', readFileSync(join(REPO, 'src/index.ts'), 'utf8'), ts.ScriptTarget.Latest, true)
+  const names: string[] = []
+  for (const s of sf.statements) {
+    if (ts.isExportDeclaration(s) && !s.isTypeOnly && s.exportClause && ts.isNamedExports(s.exportClause)) for (const e of s.exportClause.elements) if (!e.isTypeOnly) names.push(e.name.text)
+  }
+  return names
+}
+
+const require = createRequire(join(REPO, 'package.json'))
+const REACT = new Set(Object.keys(require('react') as object))
+const TABLER = new Set(Object.keys(require('@tabler/icons-react') as object))
+const INDEX = indexValueExports()
+
+function splitImports(lines: string[]) {
+  const imports: { text: string; line: number }[] = []
+  const body = lines.slice()
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^import\b/.test(lines[i])) continue
+    let j = i
+    while (j < lines.length && !/from\s+['"][^'"]+['"]\s*;?\s*$/.test(lines[j]) && !/^import\s+['"]/.test(lines[j])) j++
+    imports.push({ text: lines.slice(i, j + 1).join('\n'), line: i })
+    for (let k = i; k <= j; k++) body[k] = ''
+    i = j
+  }
+  return { imports, body }
+}
+
+function importedNames(imports: { text: string }[]): Set<string> {
+  const names = new Set<string>()
+  const sf = ts.createSourceFile('i.ts', imports.map((x) => x.text).join('\n'), ts.ScriptTarget.Latest, true)
+  for (const s of sf.statements) {
+    const c = ts.isImportDeclaration(s) ? s.importClause : undefined
+    if (!c) continue
+    if (c.name) names.add(c.name.text)
+    if (c.namedBindings && ts.isNamedImports(c.namedBindings)) for (const e of c.namedBindings.elements) names.add(e.name.text)
+    if (c.namedBindings && ts.isNamespaceImport(c.namedBindings)) names.add(c.namedBindings.name.text)
+  }
+  return names
+}
+
+const jsxComments = (lines: string[]) => lines.map((l) => l.replace(/^\/\/(.*)$/, '{/*$1*/}'))
+const parses = (text: string) => (ts.transpileModule(text, { fileName: 'x.tsx', reportDiagnostics: true, compilerOptions: { jsx: ts.JsxEmit.ReactJSX } }).diagnostics ?? []).length === 0
+
+/** All JSX; statements then JSX; statements alone. The first that parses wins. */
+function wrappings(body: string[]) {
+  const out: { pre: string[]; jsx: string[] | null }[] = [{ pre: [], jsx: body }]
+  body.forEach((l, k) => {
+    if (k > 0 && /^[<{]/.test(l) && body.slice(0, k).some((x) => x.trim() && !/^\s*\/\//.test(x))) out.push({ pre: body.slice(0, k), jsx: body.slice(k) })
+  })
+  out.push({ pre: body, jsx: null })
+  return out
+}
+
+interface Extra {
+  react: Set<string>
+  tabler: Set<string>
+  declared: Set<string>
+}
+
+function build(block: Block, extra: Extra): { text: string; map: (number | null)[] } {
+  const { imports, body } = splitImports(block.lines)
+  const have = importedNames(imports)
+  const lines: string[] = []
+  const map: (number | null)[] = []
+  const push = (text: string, mdx: number | null) => {
+    for (const t of text.split('\n')) {
+      lines.push(t)
+      map.push(mdx)
+    }
+  }
+  for (const imp of imports) imp.text.split('\n').forEach((t, k) => push(t, block.start + imp.line + k))
+  const auto = INDEX.filter((n) => !have.has(n))
+  if (auto.length) push(`import { ${auto.join(', ')} } from '@estiva-app/ui'`, null)
+  const react = [...extra.react].filter((n) => !have.has(n))
+  if (react.length) push(`import { ${react.join(', ')} } from 'react'`, null)
+  const tabler = [...extra.tabler].filter((n) => !have.has(n))
+  if (tabler.length) push(`import { ${tabler.join(', ')} } from '@tabler/icons-react'`, null)
+  for (const d of extra.declared) push(`declare const ${d}: any`, null)
+  for (const s of STAND_INS) if (!have.has(s)) push(`declare const ${s}: (props: any) => React.JSX.Element`, null)
+
+  for (const w of wrappings(body)) {
+    const L = lines.slice()
+    const M = map.slice()
+    const add = (t: string, mdx: number | null) => {
+      L.push(t)
+      M.push(mdx)
+    }
+    add('export function __How() {', null)
+    w.pre.forEach((t, k) => add(t, block.start + k))
+    if (w.jsx) {
+      add('return (<>', null)
+      jsxComments(w.jsx).forEach((t, k) => add(t, block.start + w.pre.length + k))
+      add('</>)', null)
+    }
+    add('}', null)
+    const text = L.join('\n')
+    if (parses(text)) return { text, map: M }
+  }
+  return { text: `${lines.join('\n')}\nexport function __How() {\n${body.join('\n')}\n}`, map: [...map, null, ...body.map((_, k) => block.start + k), null] }
+}
+
+function compilerOptions(): ts.CompilerOptions {
+  const raw = ts.parseConfigFileTextToJson('tsconfig.json', readFileSync(join(REPO, 'tsconfig.json'), 'utf8')).config
+  const parsed = ts.convertCompilerOptionsFromJson(raw.compilerOptions, REPO)
+  // A placeholder is `any`: `people.map((p) => …)` would fail noImplicitAny on `p`,
+  // the placeholder's fault, not the page's. A callback prop's parameter keeps the part's type.
+  return { ...parsed.options, noEmit: true, noImplicitAny: false, baseUrl: REPO, paths: { '@estiva-app/ui': ['./src/index.ts'] }, types: [] }
+}
+
+function makeHost(options: ts.CompilerOptions, virtual: Map<string, string>): ts.CompilerHost {
+  const host = ts.createCompilerHost(options, true)
+  const read = host.readFile.bind(host)
+  const exists = host.fileExists.bind(host)
+  host.readFile = (f) => virtual.get(norm(f)) ?? read(f)
+  host.fileExists = (f) => virtual.has(norm(f)) || exists(f)
+  host.getSourceFile = (f, lang) => {
+    const t = host.readFile(f)
+    return t === undefined ? undefined : ts.createSourceFile(f, t, lang, true)
+  }
+  host.getCurrentDirectory = () => REPO
+  return host
+}
+
+interface Result {
+  page: string
+  start: number
+  errors: { line: number | null; code: number; text: string }[]
+}
+
+/** Compile every block, adding placeholders until nothing new is found. */
+function compileAll(blocks: Block[]): Result[] {
+  const options = compilerOptions()
+  const state: Extra[] = blocks.map(() => ({ react: new Set(), tabler: new Set(), declared: new Set() }))
+  const fileOf = blocks.map((b) => `${REPO}/src/__how__${b.page.replace(/\W+/g, '_')}_${b.start}.tsx`)
+  let program: ts.Program | undefined
+  let built: ReturnType<typeof build>[] = []
+  for (let round = 0; round < 8; round++) {
+    built = blocks.map((b, i) => build(b, state[i]))
+    const virtual = new Map(fileOf.map((f, i) => [norm(f), built[i].text]))
+    program = ts.createProgram(fileOf, options, makeHost(options, virtual), program)
+    const checker = program.getTypeChecker()
+    let added = 0
+    fileOf.forEach((f, i) => {
+      const s = state[i]
+      const sf = program!.getSourceFile(f)!
+      for (const d of ts.getPreEmitDiagnostics(program!, sf)) {
+        if (d.code !== 2304 && d.code !== 2552) continue
+        const x = /Cannot find name '([^']+)'/.exec(ts.flattenDiagnosticMessageText(d.messageText, ' '))?.[1]
+        if (!x || s.react.has(x) || s.tabler.has(x) || s.declared.has(x)) continue
+        if (REACT.has(x)) s.react.add(x)
+        else if (/^Icon[A-Z]/.test(x) && TABLER.has(x)) s.tabler.add(x)
+        else if (/^[a-z_$]/.test(x) || /^[A-Z][A-Z0-9_]+$/.test(x)) s.declared.add(x)
+        else continue
+        added++
+      }
+      // A placeholder that is also a browser global (`name`, `open`) never reports
+      // "Cannot find name": it silently takes the global's type. Shadow those too.
+      const walk = (node: ts.Node) => {
+        if (ts.isIdentifier(node) && built[i].map[sf.getLineAndCharacterOfPosition(node.getStart(sf)).line] != null) {
+          const p = node.parent
+          const member = (ts.isPropertyAccessExpression(p) && p.name === node) || (ts.isPropertyAssignment(p) && p.name === node) || ts.isJsxAttribute(p)
+          const x = node.text
+          if (!member && /^[a-z]/.test(x) && !REAL_GLOBALS.has(x) && !s.declared.has(x)) {
+            const sym = checker.getSymbolAtLocation(node)
+            const decls = sym?.declarations ?? []
+            if (sym && decls.length && decls.every((d) => program!.isSourceFileDefaultLibrary(d.getSourceFile())) && sym.flags & (ts.SymbolFlags.Variable | ts.SymbolFlags.Function)) {
+              s.declared.add(x)
+              added++
+            }
+          }
+        }
+        ts.forEachChild(node, walk)
+      }
+      walk(sf)
+    })
+    if (!added) break
+  }
+  return blocks.map((b, i) => {
+    const sf = program!.getSourceFile(fileOf[i])!
+    const errors = ts.getPreEmitDiagnostics(program!, sf).filter((d) => d.file === sf).map((d) => ({
+      line: built[i].map[sf.getLineAndCharacterOfPosition(d.start ?? 0).line] ?? null,
+      code: d.code,
+      text: ts.flattenDiagnosticMessageText(d.messageText, ' '),
+    }))
+    return { page: b.page, start: b.start, errors }
+  })
+}
+
+const pages = readdirSync(join(REPO, 'src')).filter((f) => f.endsWith('.mdx')).sort()
+const blocks = pages.flatMap((f) => howBlocks(`src/${f}`, readFileSync(join(REPO, 'src', f), 'utf8')))
+
+describe('the code under How', () => {
+  it('compiles on every page, and goes red on a wrong part, prop, value or import', { timeout: 120_000 }, () => {
+    expect(blocks.length).toBeGreaterThan(50)
+    const button = blocks.find((b) => b.page === 'src/Button.mdx')!
+    const broken = (name: string, change: (line: string) => string) => ({ ...button, page: `src/BROKEN-${name}.mdx`, lines: button.lines.map(change) })
+    const probes = [
+      broken('part', (l) => l.replace('<Button ', '<Buton ').replace('</Button>', '</Buton>')),
+      broken('prop', (l) => l.replace('variant="primary"', 'varient="primary"')),
+      broken('value', (l) => l.replace('variant="primary"', 'variant="big"')),
+      broken('import', (l) => l.replace('import { Button }', 'import { Buton }')),
+    ]
+    const results = compileAll([...blocks, ...probes])
+    const shown = (r: Result) => r.errors.map((e) => `${r.page}:${e.line ?? '?'} TS${e.code} ${e.text}`)
+    expect(results.slice(0, blocks.length).flatMap(shown)).toEqual([])
+    // Each broken copy must fail, or the check proves nothing.
+    for (const r of results.slice(blocks.length)) expect(r.errors.length, r.page).toBeGreaterThan(0)
+  })
+})

package/src/pages.test.ts

@@ -16,6 +16,7 @@
 import { readdirSync, readFileSync } from 'node:fs'
 import { describe, expect, it } from 'vitest'
 import { OWNED_BEHAVIOURS } from './eslint/no-rebuilt-behaviour'
+import { whenNotProblem } from './registry/contract'
 
 /** How a page words each behaviour. `base-ui` is how a part is built, not what it does for a caller. */
 const ROW: Record<string, RegExp> = {
@@ -119,6 +120,11 @@ describe('the page contract', () => {
         expect(names.filter((n) => !exported.has(n) && !pages.includes(n))).toEqual([])
       })
 
+      // B8 (25 September): When not names the part to use instead, or says there is none.
+      it('names another part under When not, or starts a line "No alternative:"', () => {
+        expect(whenNotProblem(t, partsOf(page), exported)).toBeNull()
+      })
+
       if (WAITING.includes(page)) return
 
       it('says what it owns, as the checker does', () => {
@@ -140,3 +146,14 @@ describe('the page contract', () => {
     })
   }
 })
+
+// The re-review after the audit before UIG-26 (R17): "Choosing a component" is written by
+// hand, and six parts with pages of their own had no row — ContainerHeader and ListColumn
+// among them, the parts behind the skill's first two Gotchas.
+describe('Choosing a component', () => {
+  it('names every part that has a page of its own', () => {
+    const choosing = readFileSync(new URL('../stories/Choosing.mdx', dir), 'utf8')
+    const named = new Set([...choosing.matchAll(/\*\*([A-Z][A-Za-z]+)\*\*/g)].map((m) => m[1]))
+    expect(pages.filter((page) => !named.has(page))).toEqual([])
+  })
+})

package/src/registry/app.test.ts

@@ -173,6 +173,22 @@ describe("an app's catalogue", () => {
     expect(registry.storybook.devUrl).toBe('http://localhost:6123')
   })
 
+  // C6: UIG-19's "adding an unclassified component fails the build — proved", proved.
+  it('fails a part with no class, and gives every part the builder finds one', () => {
+    const unclassified = structuredClone(registry)
+    const one = unclassified.entries.find((e) => e.app?.class === 'one-off')!
+    delete (one.app as Partial<NonNullable<RegistryEntry['app']>>).class
+    expect(validateRegistry(unclassified)).toContain(`entries[${unclassified.entries.indexOf(one)}] (${one.name}).app.class is undefined`)
+    const bare = structuredClone(registry)
+    bare.entries[0].app = null
+    expect(validateRegistry(bare).join('\n')).toContain('app is missing on an app entry')
+    // A part added to the app is classified the moment it exists.
+    const dir = app({ ...FIXTURE, 'src/components/Added.tsx': '/** A part nobody has sorted. */\nexport function Added() {\n  return <div />\n}\n' })
+    const added = buildAppRegistry({ root: dir, repo: 'fixture', packageRegistry })
+    expect(added.entries.find((e) => e.name === 'Added')?.app?.class).toBe('unused')
+    expect(added.entries.every((e) => ['re-export', 'reusable', 'one-off', 'promote-candidate', 'unused'].includes(e.app?.class ?? ''))).toBe(true)
+  })
+
   it('counts every .tsx outside stories and tests, and says why a file holds no part', () => {
     // main.tsx, App.tsx, 2 pass-ons, Frame, Card, Timeline, Sync, Ctx, Lonely, Shown, Wide, EmptyState, Lazy, HomePage, Other, hooks.tsx
     expect(registry.builtFrom.files).toBe(17)
@@ -230,6 +246,24 @@ describe("an app's catalogue", () => {
     expect(entry('Shown').app).toMatchObject({ class: 'unused', reason: 'No file of the app uses it; only its stories do.' })
   })
 
+  // B9: an app part owns what the part it is owns, followed through the app's own parts.
+  it('gives an app part what the part it returns owns, and a page nothing of its dialogs', () => {
+    const dir = app({
+      'src/ui/Floating.tsx': "/** Hands on the package's Popover. */\nexport { Popover } from '@estiva-app/ui'\n",
+      'src/DeleteDialog.tsx': "import { ConfirmDialog } from '@estiva-app/ui'\n/** Asks before deleting. */\nexport function DeleteDialog() {\n  return <ConfirmDialog open title=\"Delete?\" onConfirm={() => {}} onOpenChange={() => {}} />\n}\n",
+      'src/Ask.tsx': "import { DeleteDialog } from './DeleteDialog'\n/** The app's own wrapper of it. */\nexport function Ask() {\n  return open ? <DeleteDialog /> : null\n}\n",
+      'src/Page.tsx': "import { Ask } from './Ask'\n/** A page that opens it. */\nexport function Page() {\n  return (\n    <>\n      <main>Page</main>\n      <Ask />\n    </>\n  )\n}\n",
+      'src/main.tsx': "import { Page } from './Page'\nimport { Popover } from './ui/Floating'\nexport const all = [<Page key=\"p\" />, <Popover key=\"f\" />]\n",
+    })
+    const entries = buildAppRegistry({ root: dir, repo: 'x', packageRegistry }).entries
+    const ids = (name: string) => entries.find((e) => e.name === name)!.ownsBehaviours.map((owned) => owned.id)
+    expect(ids('DeleteDialog')).toEqual(expect.arrayContaining(['portal', 'focus', 'scroll-lock']))
+    expect(ids('DeleteDialog')).not.toContain('tab-stop')
+    expect(ids('Ask')).toEqual(ids('DeleteDialog'))
+    expect(ids('Page')).toEqual([])
+    expect(ids('Popover')).toEqual(packageRegistry.entries.find((e) => e.name === 'Popover')!.ownsBehaviours.map((owned) => owned.id))
+  })
+
   it('takes a kind written beside the part, with its reason', () => {
     expect(entry('Wide').app).toMatchObject({ class: 'reusable', written: true, reason: 'general; one screen uses it so far', usedIn: ['src/pages/HomePage.tsx'] })
     expect(entry('Wide').purpose).toBe('A general strip of things.')