@estiva-app/ui 0.35.1 → 0.36.0

package/src/registry/app.ts

@@ -36,6 +36,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { basename, dirname, extname, join, relative, resolve, sep } from 'node:path'
 import ts from 'typescript'
+import { asBehaviours, baseUiBehaviours, drawnIn, handedOn, isBaseUi, rootsIn, splitTag } from './behaviours'
 import { firstSentence, pageOpening, readModule, sanitize, toId, PACKAGE_IMPORT, type Resolved } from './build'
 import { looksOf, parseForLooks } from '../eslint/looks-of'
 import { SCHEMA_VERSION, type AppFacts, type EntryClass, type FileWithoutPart, type Registry, type RegistryEntry } from './schema'
@@ -722,6 +723,50 @@ export function buildAppRegistry({ root = process.cwd(), repo, packageRegistry,
   }
   const port = /(?:-p|--port)[\s=]+(\d+)/.exec(manifest.scripts?.storybook ?? '')?.[1] ?? '6006'
 
+  // What each part owns, from what it draws (B9): a pass-on owns what its package
+  // part owns; any other part what the whole of each part it draws does, followed
+  // through the app's own parts, and what the Base UI parts it draws do.
+  const packageOwns = new Map((theRegistry?.entries ?? []).map((e) => [e.name, e.ownsBehaviours.map((b) => b.id)]))
+  const drawnByFile = new Map<string, { drawn: Map<string, Set<string>>; roots: Map<string, Set<string>> }>()
+  const owned = new Map<string, Set<string>>()
+  const ownsOf = (p: Found, seen: Set<string>): Set<string> => {
+    const at = key(p.file, p.name)
+    const held = owned.get(at)
+    if (held) return held
+    const out = new Set<string>()
+    if (p.from) {
+      if (p.from.specifier === PACKAGE_IMPORT) for (const id of packageOwns.get(p.from.name) ?? []) out.add(id)
+      return out
+    }
+    const f = facts.get(p.file)
+    if (!f || !p.local || seen.has(at)) return out
+    seen.add(at)
+    if (!drawnByFile.has(p.file)) drawnByFile.set(p.file, { drawn: drawnIn(f.sf), roots: rootsIn(f.sf) })
+    const { drawn, roots } = drawnByFile.get(p.file)!
+    const imported = new Map(f.links.filter((l) => l.kind === 'import').flatMap((l) => l.names.map((n) => [n.local, { link: l, imported: n.imported }] as const)))
+    // The Base UI parts it draws, anywhere in it (rare in an app: the gate refuses most).
+    for (const tag of drawn.get(p.local) ?? []) {
+      const [local, piece] = splitTag(tag)
+      const from = imported.get(local)
+      if (from && isBaseUi(from.link.specifier)) for (const id of baseUiBehaviours(from.imported, piece)) out.add(id)
+    }
+    // The parts it is: what it hands back at its root, the package's or the app's own.
+    for (const tag of roots.get(p.local) ?? []) {
+      const from = imported.get(splitTag(tag)[0])
+      if (!from) continue
+      let inner: Iterable<string> = []
+      if (from.link.specifier === PACKAGE_IMPORT) inner = handedOn(from.imported, packageOwns.get(from.imported) ?? [])
+      else if (from.link.target && from.link.target !== '?') {
+        const part = origin(from.link.target, from.imported)
+        if (part) inner = handedOn(part.from?.name ?? part.name, ownsOf(part, seen))
+      }
+      for (const id of inner) out.add(id)
+    }
+    if (seen.size === 1) owned.set(at, out)
+    seen.delete(at)
+    return out
+  }
+
   const entries: RegistryEntry[] = []
   for (const p of found) {
     const u = users.get(key(p.file, p.name))!
@@ -803,7 +848,12 @@ export function buildAppRegistry({ root = process.cwd(), repo, packageRegistry,
       packageNamesake: namesakes.has(p.name) && !(pass && pass.specifier === PACKAGE_IMPORT && pass.name === p.name) ? p.name : null,
       defaultExport: p.defaultExport,
     }
-    const { docsId, storyId } = pass ? { docsId: null, storyId: null } : storyOf(p)
+    const found = pass ? { docsId: null, storyId: null } : storyOf(p)
+    // A part with a page of its own and no story file links to its page, by the
+    // page's own title (Katerina's ruling B10, 25 September): Peek's EditedMarker.mdx
+    // shows the part in other parts' stories, and nothing linked it.
+    const titled = !found.docsId && pageText ? /<Meta\s+title=["'`]([^"'`]+)["'`]/.exec(readFileSync(join(app, page!), 'utf8'))?.[1] : undefined
+    const { docsId, storyId } = titled ? { docsId: `${sanitize(titled)}--docs`, storyId: found.storyId } : found
     entries.push({
       name: p.name,
       repo: repoName,
@@ -814,7 +864,7 @@ export function buildAppRegistry({ root = process.cwd(), repo, packageRegistry,
       purposeFrom,
       props: shape.props,
       variants: shape.variants,
-      ownsBehaviours: [],
+      ownsBehaviours: asBehaviours(ownsOf(p, new Set())),
       status: declared?.deprecated ? 'deprecated' : 'stable',
       migrationStage: null,
       docsId,

package/src/registry/behaviours.ts

@@ -0,0 +1,223 @@
+/**
+ * What a part owns, worked out from what it draws (Katerina's ruling B9,
+ * 25 September).
+ *
+ * The plan's Gate 0 asked for "the behaviours it owns — derived from which Base
+ * UI parts it imports". Until 0.36.0 only "is built on Base UI" was; the rest
+ * was UIG-8's hand list of owners, which is right for the part that does the
+ * work and silent for every part built from it: ConfirmDialog draws DialogShell,
+ * whose page says it keeps focus inside, and the catalogue listed no focus for
+ * ConfirmDialog. Every app entry listed nothing at all.
+ *
+ * Now a part owns:
+ *
+ * - what the Base UI parts it draws do, from UIG-8's enumeration (`baseUi` on
+ *   each behaviour, read from Base UI's source): all of it for a whole part
+ *   (`Menu.Root`), what it is for a piece (`Menu.Item`);
+ * - what the whole of the part it **is** does (floating, focus, keys, scroll):
+ *   the part it hands back at its root, followed through parts inside parts, in
+ *   the package and in an app. ConfirmDialog returns a DialogShell, so it keeps
+ *   focus inside; a page with a menu somewhere in it does not float, and a
+ *   tooltip's floating stays the tooltip's;
+ * - and, in the package, what UIG-8's list says (the floor: a part like `Link`
+ *   is reachable with Tab without any Base UI in it).
+ *
+ * Read from the code: a JSX tag inside the part's own declaration, or inside a
+ * function of the same file it draws. A root on one branch of a condition
+ * still counts, so the list says what a part can be, not what one screen shows.
+ */
+import ts from 'typescript'
+import { OWNED_BEHAVIOURS } from '../eslint/index'
+import type { EntryBehaviour } from './schema'
+
+/** `@base-ui/react`, its sub-paths, and the old `@base-ui-components/react` spelling. */
+export const isBaseUi = (specifier: string) => /^@base-ui(?:-components)?\/react(?:\/|$)/.test(specifier)
+
+/**
+ * What drawing a Base UI part gives, by behaviour id. The whole part (`Menu.Root`,
+ * or a part of one piece: `<Separator>`, `<Toggle>`) does all UIG-8 lists for it;
+ * a piece of one (`Menu.Item`, `Toolbar.Button`) only says what it is.
+ */
+export function baseUiBehaviours(part: string, piece?: string): string[] {
+  const whole = !piece || piece === 'Root' || piece === 'Provider'
+  return OWNED_BEHAVIOURS.filter((owned) => owned.id === 'base-ui' || (owned.baseUi.includes(part) && (whole || owned.id === 'role'))).map((owned) => owned.id)
+}
+
+/**
+ * What a part hands on to the parts drawn around it: what the whole thing does.
+ * Being built on Base UI, a role and a Tab stop stay the inner part's: a banner
+ * with a button in it is not itself reachable with Tab.
+ */
+export const HANDED_ON = new Set(['portal', 'press-outside', 'page-keys', 'focus', 'scroll-lock', 'follow', 'scroll'])
+
+/** A hint drawn beside a part: its floating is its own, never the part's. */
+export const HINTS = new Set(['Tooltip', 'WithTooltip', 'TooltipProvider', 'PreviewCard'])
+
+/** What a part drawn inside another hands on to it. */
+export const handedOn = (name: string, owned: Iterable<string>) => (HINTS.has(name) ? [] : [...owned].filter((id) => HANDED_ON.has(id)))
+
+/** Behaviour ids as the catalogue writes them: in UIG-8's order, each once. */
+export function asBehaviours(ids: Iterable<string>): EntryBehaviour[] {
+  const held = new Set(ids)
+  return OWNED_BEHAVIOURS.filter((owned) => held.has(owned.id)).map((owned) => ({ id: owned.id, behaviour: owned.behaviour }))
+}
+
+/** A tag as written: `Dialog.Popup`, `Button`. */
+function tagText(tag: ts.JsxTagNameExpression): string | null {
+  if (ts.isIdentifier(tag)) return tag.text
+  if (ts.isPropertyAccessExpression(tag)) {
+    const inner = tagText(tag.expression as ts.JsxTagNameExpression)
+    return inner && `${inner}.${tag.name.text}`
+  }
+  return null
+}
+
+/** A tag's name and its piece: `['Dialog', 'Popup']`, `['Button', undefined]`. */
+export const splitTag = (tag: string): [string, string | undefined] => {
+  const [root, piece] = tag.split('.')
+  return [root, piece]
+}
+
+/** Every tag drawn anywhere under `node`, as written. */
+function tagsUnder(node: ts.Node): Set<string> {
+  const found = new Set<string>()
+  const visit = (n: ts.Node) => {
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+      const tag = tagText(n.tagName)
+      if (tag && /^[A-Z]/.test(tag)) found.add(tag)
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(node)
+  return found
+}
+
+/**
+ * For each name a file declares at its top (a function, a `const`, a class):
+ * the tags drawn inside it, with the file's own functions it draws followed, so
+ * what is left are names the file imports or declares without a body.
+ */
+export function drawnIn(sf: ts.SourceFile): Map<string, Set<string>> {
+  const direct = new Map<string, Set<string>>()
+  for (const statement of sf.statements) {
+    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) direct.set(statement.name.text, tagsUnder(statement))
+    else if (ts.isVariableStatement(statement)) {
+      for (const d of statement.declarationList.declarations) if (ts.isIdentifier(d.name) && d.initializer) direct.set(d.name.text, tagsUnder(d.initializer))
+    }
+  }
+  const closed = new Map<string, Set<string>>()
+  for (const name of direct.keys()) {
+    const out = new Set<string>()
+    const seen = new Set([name])
+    const stack = [name]
+    while (stack.length) {
+      for (const tag of direct.get(stack.pop() as string) ?? []) {
+        out.add(tag)
+        if (direct.has(tag) && !seen.has(tag)) {
+          seen.add(tag)
+          stack.push(tag)
+        }
+      }
+    }
+    closed.set(name, out)
+  }
+  return closed
+}
+
+/** The tags an expression hands back at its top: both sides of a condition, never a fragment's children. */
+function rootsOfExpression(e: ts.Node | undefined, out: Set<string>): void {
+  if (!e) return
+  if (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e) || ts.isNonNullExpression(e)) return rootsOfExpression(e.expression, out)
+  if (ts.isConditionalExpression(e)) {
+    rootsOfExpression(e.whenTrue, out)
+    rootsOfExpression(e.whenFalse, out)
+    return
+  }
+  if (ts.isBinaryExpression(e)) {
+    if (e.operatorToken.kind !== ts.SyntaxKind.AmpersandAmpersandToken) rootsOfExpression(e.left, out)
+    rootsOfExpression(e.right, out)
+    return
+  }
+  // A fragment is several things side by side (a page and the dialog it opens):
+  // the part is none of them alone.
+  if (ts.isJsxFragment(e)) return
+  const tag = ts.isJsxElement(e) ? tagText(e.openingElement.tagName) : ts.isJsxSelfClosingElement(e) ? tagText(e.tagName) : null
+  if (tag && /^[A-Z]/.test(tag)) out.add(tag)
+}
+
+/** The tags a function hands back: every `return`, or an arrow's body, never a nested function's. */
+function rootsOfFunction(fn: ts.Node): Set<string> {
+  const out = new Set<string>()
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) rootsOfExpression(fn.body, out)
+  const visit = (n: ts.Node) => {
+    if (n !== fn && (ts.isFunctionLike(n) || ts.isClassLike(n))) return
+    if (ts.isReturnStatement(n)) rootsOfExpression(n.expression, out)
+    ts.forEachChild(n, visit)
+  }
+  visit(fn)
+  return out
+}
+
+/** The function a declaration's value is: itself, or the one inside `forwardRef(…)`, `memo(…)`. */
+function functionOf(node: ts.Node | undefined): ts.Node | undefined {
+  if (!node) return undefined
+  if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node)) return node
+  if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) return functionOf(node.expression)
+  if (ts.isCallExpression(node)) for (const argument of node.arguments) {
+    const fn = functionOf(argument)
+    if (fn) return fn
+  }
+  return undefined
+}
+
+/**
+ * For each function a file declares at its top: the parts it **is** — the tags it
+ * hands back at its root, following the file's own functions it hands back.
+ * `ConfirmDialog` returns a `DialogShell`, so it is one; a page with a menu
+ * somewhere in it is not a menu.
+ */
+export function rootsIn(sf: ts.SourceFile): Map<string, Set<string>> {
+  const direct = new Map<string, Set<string>>()
+  for (const statement of sf.statements) {
+    if (ts.isFunctionDeclaration(statement) && statement.name) direct.set(statement.name.text, rootsOfFunction(statement))
+    else if (ts.isVariableStatement(statement)) {
+      for (const d of statement.declarationList.declarations) {
+        const fn = functionOf(d.initializer)
+        if (ts.isIdentifier(d.name) && fn) direct.set(d.name.text, rootsOfFunction(fn))
+      }
+    }
+  }
+  const closed = new Map<string, Set<string>>()
+  for (const name of direct.keys()) {
+    const out = new Set<string>()
+    const seen = new Set([name])
+    const stack = [name]
+    while (stack.length) {
+      for (const tag of direct.get(stack.pop() as string) ?? []) {
+        if (direct.has(tag)) {
+          if (!seen.has(tag)) {
+            seen.add(tag)
+            stack.push(tag)
+          }
+        } else out.add(tag)
+      }
+    }
+    closed.set(name, out)
+  }
+  return closed
+}
+
+/** Each imported value name → where it came from. */
+export function importsOf(sf: ts.SourceFile): Map<string, { specifier: string; imported: string }> {
+  const out = new Map<string, { specifier: string; imported: string }>()
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue
+    const clause = statement.importClause
+    if (!clause || clause.isTypeOnly) continue
+    const specifier = statement.moduleSpecifier.text
+    if (clause.name) out.set(clause.name.text, { specifier, imported: 'default' })
+    const bindings = clause.namedBindings
+    if (bindings && ts.isNamedImports(bindings)) for (const e of bindings.elements) if (!e.isTypeOnly) out.set(e.name.text, { specifier, imported: (e.propertyName ?? e.name).text })
+  }
+  return out
+}

package/src/registry/build.ts

@@ -19,6 +19,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import ts from 'typescript'
 import { OWNED_BEHAVIOURS } from '../eslint/index'
+import { asBehaviours, baseUiBehaviours, drawnIn, handedOn, importsOf, isBaseUi, rootsIn, splitTag } from './behaviours'
 import { looksOf, parseForLooks } from '../eslint/looks-of'
 import { SCHEMA_VERSION, type EntryBehaviour, type EntryKind, type EntryProp, type EntryVariant, type Registry, type RegistryEntry } from './schema'
 
@@ -654,6 +655,41 @@ export function buildRegistry({ root = process.cwd(), repo = 'estiva-ui' }: Buil
 
   if (problems.length) throw new Error(`the registry cannot be built:\n  ${problems.join('\n  ')}`)
 
+  // What each part owns, from what it draws (B9): the Base UI parts in it, and
+  // every part of the package inside it, followed; UIG-8's list is the floor.
+  const moduleByName = new Map(values.map((v) => [v.name, v.module]))
+  const drawing = new Map<string, { drawn: Map<string, Set<string>>; roots: Map<string, Set<string>>; imports: ReturnType<typeof importsOf> }>()
+  const drawingOf = (moduleName: string) => {
+    if (!drawing.has(moduleName)) {
+      const file = moduleOf(moduleName).file
+      const sf = ts.createSourceFile(file, readFileSync(join(root, file), 'utf8'), ts.ScriptTarget.Latest, true, file.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS)
+      drawing.set(moduleName, { drawn: drawnIn(sf), roots: rootsIn(sf), imports: importsOf(sf) })
+    }
+    return drawing.get(moduleName)!
+  }
+  const owns = (name: string, seen: Set<string>): Set<string> => {
+    const out = new Set(behavioursOf(name).map((b) => b.id))
+    const moduleName = moduleByName.get(name)
+    if (!moduleName || seen.has(name)) return out
+    seen.add(name)
+    const { drawn, roots, imports } = drawingOf(moduleName)
+    // The Base UI parts it draws, anywhere in it.
+    for (const tag of drawn.get(name) ?? []) {
+      const [local, piece] = splitTag(tag)
+      const from = imports.get(local)
+      if (from && isBaseUi(from.specifier)) for (const id of baseUiBehaviours(from.imported, piece)) out.add(id)
+    }
+    // The parts it is: what it hands back at its root.
+    for (const tag of roots.get(name) ?? []) {
+      const [local] = splitTag(tag)
+      const from = imports.get(local)
+      const part = from?.specifier.startsWith('./') ? from.imported : !from && local !== name ? local : undefined
+      if (part && moduleByName.has(part)) for (const id of handedOn(part, owns(part, seen))) out.add(id)
+    }
+    return out
+  }
+  for (const entry of entries) if (entry.kind === 'component') entry.ownsBehaviours = asBehaviours(owns(entry.name, new Set()))
+
   entries.sort((a, b) => a.name.localeCompare(b.name))
 
   return {

package/src/registry/cli.ts

@@ -36,11 +36,11 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from
 import { tmpdir } from 'node:os'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { CONTRACT_KINDS, contractProblems, linkProblems } from './contract'
+import { CONTRACT_KINDS, contractProblems, linkProblems, nameProblems } from './contract'
 import { findInRegistries, formatFindings } from './find'
-import { findSiblings, workspaceOf } from './siblings'
+import { behindBy, findSiblings, workspaceOf } from './siblings'
 import { loaderPath, loaderProblem, loaderText, repositoryOf, settingsPath, settingsWithSearch } from './skill'
-import { storyMapProblems } from './storymap'
+import { indexHeadings, storyMapProblems } from './storymap'
 import { CLASSES, validateRegistry, type Registry } from './schema'
 
 /**
@@ -132,11 +132,11 @@ async function buildApp(folder: string, repo: string | undefined): Promise<Regis
  * Reports, and says whether it passed. A folder with no Storybook has nothing
  * to check.
  */
-function checkLinks(registry: Registry, folder: string): boolean {
+function checkLinks(registry: Registry, folder: string): { ok: boolean; headings?: Set<string>; titles?: Set<string> } {
   const bin = resolve(folder, 'node_modules', '.bin', process.platform === 'win32' ? 'storybook.cmd' : 'storybook')
   if (!existsSync(resolve(folder, '.storybook')) || !existsSync(bin)) {
     process.stdout.write('story links: no Storybook here, nothing to check\n')
-    return true
+    return { ok: true }
   }
   const out = join(mkdtempSync(join(tmpdir(), 'estiva-ui-index-')), 'index.json')
   // A `.cmd` needs a shell on Windows, and Node wants that as one quoted line
@@ -147,17 +147,20 @@ function checkLinks(registry: Registry, folder: string): boolean {
       : spawnSync(bin, ['index', '-o', out, '--quiet'], { cwd: folder, encoding: 'utf8' })
   if (run.status !== 0 || !existsSync(out)) {
     process.stderr.write(`story links: Storybook could not index its stories, so no link can be trusted:\n${(run.stderr || run.stdout || '').trim()}\n`)
-    return false
+    return { ok: false }
   }
-  const ids = new Set(Object.keys((JSON.parse(readFileSync(out, 'utf8')) as { entries: Record<string, unknown> }).entries))
+  const entries = (JSON.parse(readFileSync(out, 'utf8')) as { entries: Record<string, { title?: string }> }).entries
+  const ids = new Set(Object.keys(entries))
+  const headings = indexHeadings(entries)
+  const titles = new Set(Object.values(entries).flatMap((e) => (e.title ? [e.title] : [])))
   const dead = linkProblems(registry, ids)
   const count = registry.entries.reduce((n, entry) => n + (entry.storyId ? 1 : 0) + (entry.docsId ? 1 : 0), 0)
   if (dead.length) {
     process.stderr.write(`story links: ${dead.length} of ${count} lead nowhere:\n  ${dead.join('\n  ')}\n`)
-    return false
+    return { ok: false, headings, titles }
   }
   process.stdout.write(`story links: all ${count} open a story or docs page Storybook has\n`)
-  return true
+  return { ok: true, headings, titles }
 }
 
 /**
@@ -179,12 +182,12 @@ async function checkGated(registry: Registry, folder: string, kinds?: string[]):
 }
 
 /**
- * The app's hand-written map of its Storybook — the heading order and the
- * Introduction — against the Storybook and the catalogue (`./storymap`).
- * Reports, and says whether it passed.
+ * The repository's hand-written map of its Storybook — the heading order and the
+ * Introduction — against the Storybook (its own index, when there is one) and,
+ * in an app, the catalogue (`./storymap`). Reports, and says whether it passed.
  */
-function checkStoryMap(registry: Registry, folder: string): boolean {
-  const problems = storyMapProblems(registry, folder)
+function checkStoryMap(folder: string, registry?: Registry, headings?: Set<string>): boolean {
+  const problems = storyMapProblems(folder, { ...(registry ? { registry } : {}), ...(headings ? { real: headings } : {}) })
   if (problems.length) {
     process.stderr.write(`storybook map: ${problems.length === 1 ? 'one line no longer matches' : `${problems.length} lines no longer match`}:\n  ${problems.join('\n  ')}\n`)
     return false
@@ -212,6 +215,8 @@ async function main(): Promise<number> {
       const registries: Registry[] = [readPackageRegistry()]
       // An app that cannot be read is said out loud, and the rest still answer.
       const add = async (folder: string, repo: string | undefined) => {
+        const behind = behindBy(folder)
+        if (behind) process.stderr.write(`note: ${repo ?? basename(folder)} (${folder}) is ${behind} commit${behind === 1 ? '' : 's'} behind main as last fetched — its answers may name parts that are gone; pull it\n`)
         try {
           registries.push(await buildApp(folder, repo))
         } catch (error) {
@@ -273,7 +278,10 @@ async function main(): Promise<number> {
         const registry = await buildApp(root, value('repo'))
         process.stdout.write(`${summary(registry)}\n`)
         // The usage-page contract and the story links (UIG-19): the one copy, run by every app's `gate` job.
-        const broken = contractProblems(registry, root)
+        // A When not may name a part of the package or of this app (B8).
+        const pkg = readPackageRegistry()
+        const known = new Set([...pkg.entries, ...registry.entries].map((e) => e.name))
+        const broken = contractProblems(registry, root, known)
         if (broken.length) {
           process.stderr.write(`${broken.length === 1 ? 'a part breaks' : `${broken.length} parts break`} the usage-page contract:\n  ${broken.join('\n  ')}\n`)
         } else {
@@ -283,8 +291,17 @@ async function main(): Promise<number> {
         const linked = checkLinks(registry, root)
         const shown = await checkGated(registry, root)
         const loaded = checkLoader()
-        const mapped = checkStoryMap(registry, root)
-        return broken.length || !linked || !shown || !loaded || !mapped ? 1 : 0
+        const mapped = checkStoryMap(root, registry, linked.headings)
+        // What the pages name must still be there (R14): parts under When and When not,
+        // and the stories a Seen in line sends a reader to, here or in the package.
+        const stale = nameProblems(registry, root, {
+          known,
+          ...(linked.titles ? { titles: linked.titles } : {}),
+          packageIds: pkg.entries.flatMap((e) => [e.storyId, e.docsId].filter((id): id is string => Boolean(id))),
+        })
+        if (stale.length) process.stderr.write(`usage pages: ${stale.length === 1 ? 'one name leads' : `${stale.length} names lead`} nowhere:\n  ${stale.join('\n  ')}\n`)
+        else process.stdout.write('usage pages: every part and story they name is there\n')
+        return broken.length || stale.length || !linked.ok || !shown || !loaded || !mapped ? 1 : 0
       }
       const { buildRegistry, serializeRegistry } = await packageBuilder()
       const path = packageRegistryPath()
@@ -308,7 +325,9 @@ async function main(): Promise<number> {
       const linked = checkLinks(built, root)
       const shown = await checkGated(built, root, ['component'])
       const loaded = checkLoader()
-      return linked && shown && loaded ? 0 : 1
+      // The package keeps a heading order too (R16): it left out Layout, and nothing saw.
+      const mapped = checkStoryMap(root, undefined, linked.headings)
+      return linked.ok && shown && loaded && mapped ? 0 : 1
     }
 
     case 'skill': {

package/src/registry/contract.test.ts

@@ -18,7 +18,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
 import { buildAppRegistry } from './app'
-import { contractProblems, hasSeenIn, linkProblems, pageProblem } from './contract'
+import { contractProblems, hasSeenIn, linkProblems, nameProblems, pageProblem, whenNotProblem } from './contract'
 
 const made: string[] = []
 afterAll(() => {
@@ -53,6 +53,8 @@ const PAGE = [
   '',
   'A word.',
   '',
+  'No alternative: a count has only this badge.',
+  '',
   '## How',
   '',
   '```tsx',
@@ -78,7 +80,7 @@ describe('a usage page', () => {
   })
 
   it('fails with its sections out of order', () => {
-    const swapped = PAGE.replace('## When not\n\nA word.\n', '').replace('## What it owns', '## When not\n\nA word.\n\n## What it owns')
+    const swapped = PAGE.replace('## When not\n\nA word.\n\nNo alternative: a count has only this badge.\n', '').replace('## What it owns', '## When not\n\nA word.\n\n## What it owns')
     expect(pageProblem(swapped)).toMatch(/^sections out of order/)
   })
 
@@ -86,8 +88,23 @@ describe('a usage page', () => {
     expect(pageProblem(PAGE.replace('A small count beside a name.\n', ''))).toMatch(/^no opening line/)
   })
 
-  it('fails with no code under How', () => {
+  // R18: the code must be under How itself; one in a later section passed.
+  it('fails with no code under How, even with code further down', () => {
     expect(pageProblem(PAGE.replace('```tsx\n<Badge count={3} />\n```', 'Pass a count.'))).toBe('no code under "How"')
+    const later = PAGE.replace('```tsx\n<Badge count={3} />\n```', 'Pass a count.').replace('Nothing. It only draws.', '```tsx\n<Badge count={3} />\n```')
+    expect(pageProblem(later)).toBe('no code under "How"')
+  })
+
+  // B8: When not names the part to use instead, or says there is none.
+  it('asks When not to name another real part, or to say there is none', () => {
+    const known = new Set(['Badge', 'Once', 'Chip'])
+    const whenNot = (body: string) => PAGE.replace('A word.\n\nNo alternative: a count has only this badge.', body)
+    expect(whenNotProblem(PAGE, ['Badge'], known)).toBeNull()
+    expect(whenNotProblem(whenNot('A word. That is a **Chip**.'), ['Badge'], known)).toBeNull()
+    expect(whenNotProblem(whenNot('- A word.\n\nNo alternative: a count has only this.'), ['Badge'], known)).toBeNull()
+    expect(whenNotProblem(whenNot('A word.'), ['Badge'], known)).toMatch(/^"When not" names no other part/)
+    // Its own name, a name nothing has, and "No alternative:" mid-line do not count.
+    expect(whenNotProblem(whenNot('Not **Badge** twice, nor a `Widget`. See: No alternative: here.'), ['Badge'], known)).not.toBeNull()
   })
 
   it('reads a Windows checkout', () => {
@@ -133,6 +150,17 @@ describe('an app against the contract', () => {
     expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([])
   })
 
+  it("links a part with no story to its page by the page's title, and names one that links to nothing (B10)", () => {
+    const seen = PAGE.replace('A small count beside a name.\n', 'A small count beside a name.\n\n**Seen in** — *Parts/Card*, beside the title.\n')
+    const dir = app({ 'src/Badge.tsx': part('Badge'), 'src/Badge.mdx': seen })
+    const registry = buildAppRegistry({ root: dir, repo: 'fixture' })
+    expect(registry.entries.find((e) => e.name === 'Badge')).toMatchObject({ docsId: 'parts-badge--docs', storyId: null })
+    writeFileSync(join(dir, 'src/Badge.mdx'), seen.replace("<Meta title='Parts/Badge' />", '<Meta />'))
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([
+      'Badge (reusable, src/Badge.tsx) links to nothing in Storybook: give src/Badge.mdx a `<Meta title="…" />`, or give the part a story',
+    ])
+  })
+
   it("counts a story file named after the part that draws its view, from the part's own file", () => {
     const dir = app({
       'src/Panel.tsx': `${part('Panel')}\n/** The half that only draws. */\nexport function PanelView() {\n  return <div>view</div>\n}\n`,
@@ -156,3 +184,35 @@ describe('story links', () => {
     ])
   })
 })
+
+// R14, the re-review after the audit before UIG-26. Every case is Peek's or Ship's own:
+// StartTopicDialog sent readers to CreateTopicDialog and RepliesRow to HuddleCard, both
+// deleted by FOL-23; EmptyState's Seen in named a story on two lines; Ship's Attachment
+// named the package's story by a title it had lost.
+describe('nameProblems', () => {
+  const page = (whenNot: string, seenIn = '') =>
+    PAGE.replace('A word.', whenNot).replace('A small count beside a name.', `A small count beside a name.${seenIn ? `\n\n${seenIn}` : ''}`)
+  const registry = (dir: string) => ({ entries: [{ name: 'Badge', docPage: 'src/Badge.mdx' }] }) as unknown as Parameters<typeof nameProblems>[0]
+  const known = new Set(['Badge', 'Chip'])
+
+  it('names a part under When not that no catalogue has, and passes one that exists', () => {
+    const dir = app({ 'src/Badge.mdx': page('A topic someone is invited to: that is **CreateTopicDialog**; a label is `Chip`.') })
+    expect(nameProblems(registry(dir), dir, { known })).toEqual(['src/Badge.mdx: "When not" names CreateTopicDialog, which is no part of the package or this app'])
+  })
+
+  it('reads a Seen in line against the Storybook, a title wrapped across lines too, and the package ids', () => {
+    const seen = '**Seen in** — *Parts/Badge*, *To be removed/\nTopicActivity* and\n*Media/AttachmentCard*.'
+    const dir = app({ 'src/Badge.mdx': page('A word.', seen) })
+    const titles = new Set(['Parts/Badge'])
+    expect(nameProblems(registry(dir), dir, { known, titles, packageIds: ['components-attachmentcard--document'] })).toEqual([
+      'src/Badge.mdx: "Seen in" names To be removed/TopicActivity, which no Storybook has',
+      'src/Badge.mdx: "Seen in" names Media/AttachmentCard, which no Storybook has',
+    ])
+    expect(nameProblems(registry(dir), dir, { known, titles: new Set(['Parts/Badge', 'To be removed/TopicActivity']), packageIds: ['media-attachmentcard--default'] })).toEqual([])
+  })
+
+  it('leaves the Seen in line alone when there is no Storybook index to read', () => {
+    const dir = app({ 'src/Badge.mdx': page('A word.', '**Seen in** — *Gone/Story*.') })
+    expect(nameProblems(registry(dir), dir, { known })).toEqual([])
+  })
+})