@estiva-app/ui 0.35.0 → 0.35.2

package/src/gates/create-app.test.ts

@@ -60,6 +60,14 @@ describe('create-estiva-app', () => {
     expect(files['.storybook/preview.tsx']).toContain('document.documentElement.dataset.theme = "dark"')
   })
 
+  // The re-review after the audit before UIG-26: the catalogue links every story file's part
+  // to its Docs page, and without autodocs there is none, so `registry:check` failed the
+  // made app's required job on its first commit ("pages-home--docs" leads nowhere). Proved
+  // with the real CLI on a made app: with the tag, "all 2 open"; without it, that failure.
+  it('gives every story file a Docs page, so the catalogue links it and the gate passes', () => {
+    expect(files['.storybook/preview.tsx']).toMatch(/tags: \['autodocs'\]/)
+  })
+
   it('starts the count at zero and keeps the CI job named gate', () => {
     const count = JSON.parse(files['.gates-count.json'])
     expect(Object.values(count.rules)).toEqual([{ errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }, { errors: 0, warnings: 0, escapes: 0 }])

package/src/gates/create-app.ts

@@ -929,6 +929,10 @@ import '../src/index.css'
 document.documentElement.dataset.theme = ${JSON.stringify(theme)}
 
 const preview: Preview = {
+  // Every story file gets a Docs page, as in Peek and Ship: the catalogue links each
+  // part to it, and \`npm run registry:check\` in CI's job \`gate\` fails a link that
+  // leads nowhere.
+  tags: ['autodocs'],
   parameters: { layout: 'centered' },
 }
 

package/src/gates/gate-config.ts

@@ -44,8 +44,10 @@ export interface GateConfigOptions {
 export function gateLint({ audience = 'app' }: Pick<GateConfigOptions, 'audience'> = {}): Linter.Config {
   return {
     ...(audience === 'package' ? estiva.configs.package : estiva.configs.recommended),
-    files: audience === 'package' ? ['src/**/*.tsx'] : ['src/**/*.{ts,tsx}'],
-    ignores: ['**/*.test.ts', '**/*.test.tsx'],
+    // An app's every script type: a raw <button> in a .jsx, or a key listener in a .mts,
+    // passed while only .ts and .tsx were read (the re-review after the audit before UIG-26).
+    files: audience === 'package' ? ['src/**/*.tsx'] : ['src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'],
+    ignores: ['**/*.test.*'],
     languageOptions: {
       parser: typescriptParser,
       parserOptions: { ecmaFeatures: { jsx: true } },

package/src/gates/gates.test.ts

@@ -182,6 +182,13 @@ describe('runHook', () => {
     expect((await runHook({ root: dir, input: fine })).code).toBe(0)
   })
 
+  // The re-review after the audit before UIG-26: only .ts and .tsx were read, so these passed.
+  it('reads every script type under src: a raw button in a .jsx, a page listener in a .mts', async () => {
+    expect((await runHook({ root: dir, input: write('src/Probe.jsx', component('<button type="button">x</button>')) })).code).toBe(2)
+    expect((await runHook({ root: dir, input: write('src/lib/probe.mts', "export function listen() {\n  document.addEventListener('keydown', () => {})\n}\n") })).code).toBe(2)
+    expect((await runHook({ root: dir, input: write('src/Probe.test.jsx', component('<button type="button">x</button>')) })).code).toBe(0)
+  })
+
   it('lets through a test, a declaration file, and anything outside src', async () => {
     for (const path of ['src/Probe.test.tsx', 'src/types.d.ts', 'scripts/probe.tsx']) {
       expect((await runHook({ root: dir, input: write(path, component('<button type="button">x</button>')) })).code).toBe(0)
@@ -242,14 +249,17 @@ describe('gates:status', () => {
   // the write goes through.
   it('runs the committed hook and passes only when it refuses the write', () => {
     const settings = (matcher: string, command: string) => ({ '.claude/settings.json': JSON.stringify({ hooks: { PreToolUse: [{ matcher, hooks: [{ type: 'command', command }] }] } }) })
-    const refuses = 'node -e "process.exit(2)" -- gates'
+    const refuses = 'node -e "console.error(String.fromCharCode(60) + \'button\' + String.fromCharCode(62)); process.exit(2)" -- gates'
     expect(helpers(app('hook-refuses', settings('Edit|Write', refuses))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'pass' })
     const broken = helpers(app('hook-broken', settings('Edit|Write', 'node "$CLAUDE_PROJECT_DIR/node_modules/@estiva-app/ui/dist/gates/cli.js" hook'))).hook('.claude/settings.json', 'gates')
     expect(broken).toMatchObject({ result: 'fail', detail: expect.stringContaining('let a raw <button> through (exit 1)') })
     expect(helpers(app('hook-waves', settings('Edit|Write', 'node -e "process.exit(0)" -- gates'))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'fail' })
     expect(helpers(app('hook-never', settings('Read', refuses))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'fail', detail: expect.stringContaining('never for a Write') })
     // The hook is handed the real project folder, as Claude Code hands it.
-    const seen = 'node -e "process.exit(String(process.env.CLAUDE_PROJECT_DIR).endsWith(process.argv[1]) ? 2 : 1)" hook-dir gates'
+    const seen = 'node -e "console.error(String.fromCharCode(60) + \'button\' + String.fromCharCode(62)); process.exit(String(process.env.CLAUDE_PROJECT_DIR).endsWith(process.argv[1]) ? 2 : 1)" hook-dir gates'
+    // Exit 2 for another reason is not a refusal of the button (in the package a new file with no page is refused too).
+    const other = 'node -e "console.error(String.fromCharCode(110) + \'o page\'); process.exit(2)" -- gates'
+    expect(helpers(app('hook-other', settings('Edit|Write', other))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'fail' })
     expect(helpers(app('hook-dir', settings('Edit|Write', seen))).hook('.claude/settings.json', 'gates')).toMatchObject({ result: 'pass' })
   })
 

package/src/gates/hook.ts

@@ -69,6 +69,8 @@ interface ToolCall {
 }
 
 const PASS: HookResult = { code: 0, message: '' }
+/** An app's source the gate reads: every script type, with or without JSX. */
+const APP_SOURCE = /^src\/.+\.[cm]?[jt]sx?$/
 
 export async function runHook({ root, app = '.', audience = 'app', input, seen }: HookOptions = {}): Promise<HookResult> {
   let call: ToolCall
@@ -84,8 +86,10 @@ export async function runHook({ root, app = '.', audience = 'app', input, seen }
   const appDir = resolve(top, app)
   const file = isAbsolute(args.file_path) ? args.file_path : resolve(call.cwd ?? top, args.file_path)
   const rel = relative(appDir, file).split(sep).join('/')
-  const source = audience === 'package' ? /^src\/.+\.tsx$/ : /^src\/.+\.tsx?$/
-  if (rel.startsWith('../') || isAbsolute(rel) || !source.test(rel) || /\.test\.tsx?$/.test(rel) || /\.d\.ts$/.test(rel)) return PASS
+  // Every script under an app's src/, as the gate reads it (a raw <button> in a .jsx passed
+  // before, the re-review after the audit before UIG-26); the package's own gate is .tsx only.
+  const source = audience === 'package' ? /^src\/.+\.tsx$/ : APP_SOURCE
+  if (rel.startsWith('../') || isAbsolute(rel) || !source.test(rel) || /\.test\.[cm]?[jt]sx?$/.test(rel) || /\.d\.[cm]?ts$/.test(rel)) return PASS
 
   const text = proposed(call.tool_name, args, file)
   if (text === null) return PASS

package/src/gates/status.ts

@@ -318,11 +318,13 @@ export function helpers(ROOT: string): GateHelpers {
         hook_event_name: 'PreToolUse',
         cwd: top,
         tool_name: 'Write',
-        tool_input: { file_path: `${resolve(ROOT, app, 'src', '__gates_hook_probe__.tsx').split('\\').join('/')}`, content: 'export function Probe() {\n  return <button type="button">x</button>\n}\n' },
+        tool_input: { file_path: `${resolve(ROOT, app, 'src', '__gates_hook_probe__.tsx').split('\\').join('/')}`, content: 'export function Probe() {\n  return <div><button type="button">x</button></div>\n}\n' },
       })
       const command = hit.command.replace(/\$\{?CLAUDE_PROJECT_DIR\}?/g, top)
       const run = spawnSync(command, { cwd: ROOT, input, shell: true, encoding: 'utf8', timeout: 120_000, env: { ...process.env, CLAUDE_PROJECT_DIR: top } })
-      if (run.status === 2) return PASS(`${settingsRel}: the hook ran and refused a raw <button> (exit 2)`)
+      // Refused for the button, not for something else about a new file (in the package a new
+      // file with no page is refused too): nested, so the package's inward rule reads it as well.
+      if (run.status === 2 && /<button>/.test(`${run.stderr ?? ''}${run.stdout ?? ''}`)) return PASS(`${settingsRel}: the hook ran and refused a raw <button> (exit 2)`)
       const why = `${run.stderr ?? ''}${run.stdout ?? ''}`.trim().split(/\r?\n/)[0] || (run.error ? String(run.error.message) : 'no output')
       return FAIL(`${settingsRel}: the hook ran and let a raw <button> through (exit ${run.status ?? 'none'}): ${why}`)
     },

package/src/pages.test.ts

@@ -140,3 +140,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/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) {
@@ -283,8 +288,18 @@ 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 pkg = readPackageRegistry()
+        const stale = nameProblems(registry, root, {
+          known: new Set([...pkg.entries, ...registry.entries].map((e) => e.name)),
+          ...(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 +323,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 } from './contract'
 
 const made: string[] = []
 afterAll(() => {
@@ -86,8 +86,11 @@ 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"')
   })
 
   it('reads a Windows checkout', () => {
@@ -156,3 +159,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([])
+  })
+})

package/src/registry/contract.ts

@@ -51,7 +51,10 @@ export function pageProblem(source: string): string | null {
     .map((s) => s.trim())
     .find((s) => s && !s.startsWith('<') && !s.startsWith('import '))
   if (!opening) return 'no opening line under the title saying what the part is'
-  if (!/^##\s+How\s*\n[\s\S]*?```tsx?\n/m.test(text)) return 'no code under "How"'
+  // Only the How section: the code block must sit under How, not in a later section
+  // (a page with none under How and one under What it owns passed, R18).
+  const how = text.split(/^##\s+How\s*$/m)[1]?.split(/^##\s/m)[0] ?? ''
+  if (!/```tsx?\n/.test(how)) return 'no code under "How"'
   return null
 }
 
@@ -106,3 +109,48 @@ export function contractProblems(registry: Registry, root: string): string[] {
   }
   return problems
 }
+
+/** Storybook's id for a title: lower case, every run of other characters one hyphen. */
+const toStoryId = (title: string) =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+/** The names a page's section writes as a part: bold or in backticks, starting with a capital. */
+function namedParts(section: string): string[] {
+  return [...section.matchAll(/\*\*([A-Z][A-Za-z0-9]+)\*\*|`([A-Z][A-Za-z0-9]+)`/g)].map((m) => m[1] ?? m[2])
+}
+
+/**
+ * What an app's usage pages name that is not there (the re-review after the audit
+ * before UIG-26, R14): a part named under When or When not that no catalogue has —
+ * Peek's StartTopicDialog sent readers to CreateTopicDialog, deleted by FOL-23 —
+ * and a story a **Seen in** line names that no Storybook has. `known` is every part
+ * of the package and the app; `titles` is the app's Storybook titles, when there
+ * is an index to read them from; `packageIds` the package's story and docs ids, so
+ * a page may send readers to the package's Storybook too.
+ */
+export function nameProblems(registry: Registry, root: string, { known, titles, packageIds = [] }: { known: Set<string>; titles?: Set<string>; packageIds?: string[] }): string[] {
+  const problems: string[] = []
+  for (const entry of registry.entries) {
+    if (!entry.docPage || !existsSync(join(root, entry.docPage))) continue
+    const text = readFileSync(join(root, entry.docPage), 'utf8').replace(/\r\n/g, '\n')
+    for (const heading of ['When', 'When not']) {
+      const section = text.split(new RegExp(`^##\\s+${heading}\\s*$`, 'm'))[1]?.split(/^##\s/m)[0] ?? ''
+      for (const name of new Set(namedParts(section).filter((n) => !known.has(n)))) {
+        problems.push(`${entry.docPage}: "${heading}" names ${name}, which is no part of the package or this app`)
+      }
+    }
+    if (!titles) continue
+    const seenIn = text.match(/^\*\*Seen in\*\*[^\n]*(?:\n(?!\n)[^\n]*)*/m)?.[0] ?? ''
+    for (const [, raw] of seenIn.matchAll(/\*([A-Z][^*/]*\/[^*]+)\*/g)) {
+      // A title may wrap across lines, and a line may break after its slash.
+      const title = raw.replace(/\s+/g, ' ').replace(/\s*\/\s*/g, '/').trim()
+      const id = toStoryId(title)
+      if (titles.has(title) || packageIds.some((p) => p.startsWith(`${id}--`))) continue
+      problems.push(`${entry.docPage}: "Seen in" names ${title}, which no Storybook has`)
+    }
+  }
+  return problems
+}

package/src/registry/siblings.test.ts

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, describe, expect, it } from 'vitest'
-import { appName, findSiblings, workspaceOf } from './siblings'
+import { appName, behindBy, findSiblings, workspaceOf } from './siblings'
 
 const workspace = mkdtempSync(join(tmpdir(), 'uig20-'))
 afterAll(() => rmSync(workspace, { recursive: true, force: true }))
@@ -83,3 +83,26 @@ describe.skipIf(!existsSync(cli))('estiva-ui find, with nothing else typed', ()
     expect(find(join(workspace, 'alpha'), 'workbench', '--here')).not.toContain('Workbench')
   })
 })
+
+// The re-review after the audit before UIG-26: a search from one repository read a
+// neighbour's checkout eleven commits behind, and answered with a part it had deleted.
+describe('behindBy', () => {
+  it('says how far a checkout is behind its main as last fetched, and null for a folder that is none', () => {
+    const base = mkdtempSync(join(tmpdir(), 'behind-'))
+    const git = (cwd: string, ...a: string[]) => execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t', ...a], { cwd, stdio: 'pipe' })
+    git(base, 'init', '-q', '--bare', '-b', 'main', 'origin.git')
+    git(base, 'clone', '-q', 'origin.git', 'writer')
+    git(join(base, 'writer'), 'commit', '-q', '--allow-empty', '-m', 'one')
+    git(join(base, 'writer'), 'push', '-q', 'origin', 'HEAD:main')
+    git(base, 'clone', '-q', 'origin.git', 'reader')
+    const reader = join(base, 'reader')
+    expect(behindBy(reader)).toBe(0)
+    git(join(base, 'writer'), 'commit', '-q', '--allow-empty', '-m', 'two')
+    git(join(base, 'writer'), 'push', '-q', 'origin', 'HEAD:main')
+    expect(behindBy(reader)).toBe(0)
+    git(reader, 'fetch', '-q')
+    expect(behindBy(reader)).toBe(1)
+    expect(behindBy(tmpdir())).toBeNull()
+    rmSync(base, { recursive: true, force: true })
+  })
+})

package/src/registry/siblings.ts

@@ -16,6 +16,7 @@
  * somebody's copy) carries the same package name; the app the search runs in
  * wins, then the one whose top folder has the shortest name.
  */
+import { execFileSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 
@@ -94,3 +95,25 @@ export function findSiblings(workspace: string, { skip = [] }: { skip?: string[]
   }
   return [...byPackage.values()].sort((a, b) => a.name.localeCompare(b.name))
 }
+
+/**
+ * How many commits the checkout that holds `folder` is behind its remote's main,
+ * as last fetched: nothing is fetched, so a search stays quick. Null when it is
+ * not a git checkout or has no remote main. A search that reads a stale copy
+ * answers with parts that are gone (the re-review after the audit before UIG-26:
+ * "files panel" found Peek's deleted FilesPanel in an old checkout), so `find`
+ * says so beside its answer.
+ */
+export function behindBy(folder: string): number | null {
+  const git = (...a: string[]) => {
+    try {
+      return execFileSync('git', ['-C', folder, ...a], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }).toString().trim()
+    } catch {
+      return null
+    }
+  }
+  const main = git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD') ?? (git('rev-parse', '--verify', '--quiet', 'origin/main') ? 'origin/main' : null)
+  if (!main) return null
+  const count = Number(git('rev-list', '--count', `HEAD..${main}`))
+  return Number.isFinite(count) ? count : null
+}

package/src/registry/storymap.test.ts

@@ -1,16 +1,18 @@
 /// <reference types="node" />
 /**
- * The app's hand-written map of its Storybook (audit A3). Every case is Peek's:
- * the Huddles heading its Introduction and `HEADINGS` kept after FOL-23 deleted
- * the stories, the "49 parts worth reusing" it kept when the catalogue built 41,
- * and a Storybook with no map at all, which has nothing to rot.
+ * The hand-written map of a Storybook (audit A3, widened by R16). Every case is a
+ * real one: Peek's Huddles heading, kept in its Introduction and `HEADINGS` after
+ * FOL-23 deleted the stories, and its "49 parts worth reusing" when the catalogue
+ * built 41; Ship's `storySort.order` naming a Feedback heading it does not have and
+ * leaving out Pages, and its Introduction's bullets; the package's order leaving
+ * out Layout; and a Storybook with no map at all, which has nothing to rot.
  */
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { afterAll, describe, expect, it } from 'vitest'
 import type { Registry } from './schema'
-import { introductionCount, introductionHeadings, orderedHeadings, sidebarHeadings, storyMapProblems } from './storymap'
+import { indexHeadings, introductionCount, introductionHeadings, orderedHeadings, sidebarHeadings, storyMapProblems } from './storymap'
 
 const made: string[] = []
 afterAll(() => {
@@ -31,66 +33,85 @@ function app(files: Record<string, string>): string {
 const catalogue = (...classes: string[]) => ({ entries: classes.map((cls) => ({ app: { class: cls } })) }) as unknown as Registry
 
 const STORY = (title: string) => `import type { Meta } from '@storybook/react-vite'\nconst meta = {\n  title: '${title}',\n} satisfies Meta\nexport default meta\n`
-const PREVIEW = (headings: string[]) =>
+const HEADINGS_PREVIEW = (headings: string[]) =>
   `export default {\n  parameters: {\n    options: {\n      storySort: (a, b) => {\n        const HEADINGS = [\n${headings.map((h) => `          '${h}', // someone's heading\n`).join('')}        ]\n        return 0\n      },\n    },\n  },\n}\n`
-const INTRO = (count: number, headings: string[]) =>
+const ORDER_PREVIEW = (headings: string[]) =>
+  `export default {\n  parameters: {\n    options: {\n      // Docs first; the rest follows\n      storySort: {\n        order: [${headings.map((h) => (h === 'Docs' ? "'Docs', ['Introduction']" : `'${h}'`)).join(', ')}],\n      },\n    },\n  },\n}\n`
+const TABLE_INTRO = (count: number, headings: string[]) =>
   `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title="Docs/Introduction" />\n\nOf everything the app owns, **${count} parts worth reusing** carry a written rule.\n\n| Heading | What |\n|---|---|\n${headings.map((h) => `| **${h}** | About ${h}. |`).join('\n')}\n`
+const BULLET_INTRO = (groups: string[][]) =>
+  `<Meta title="Docs/Introduction" />\n\n## How the sidebar is organised\n\n${groups.map((g) => `- **${g.join(' · ')}** — about them.`).join('\n')}\n\n## Conventions\n\n- **Stories first.** A component exists in Storybook first.\n`
 
 const PEEK_TODAY = {
-  'src/stories/Introduction.mdx': INTRO(2, ['Docs', 'Primitives', 'Huddles']),
+  'src/stories/Introduction.mdx': TABLE_INTRO(2, ['Docs', 'Primitives', 'Huddles']),
   'src/components/ui/Badge.stories.tsx': STORY('Primitives/Badge'),
   'src/components/ui/Chip.mdx': `import { Meta } from '@storybook/addon-docs/blocks'\n\n<Meta title='Primitives/Chip' />\n\n# Chip\n`,
-  '.storybook/preview.tsx': PREVIEW(['Docs', 'Primitives', 'Huddles']),
+  '.storybook/preview.tsx': HEADINGS_PREVIEW(['Docs', 'Primitives', 'Huddles']),
 }
 
 describe('reading the map', () => {
-  it('reads the sidebar from story titles and from page titles in either quote', () => {
-    expect([...sidebarHeadings(app(PEEK_TODAY))].sort()).toEqual(['Docs', 'Primitives'])
+  it('reads the sidebar from story titles and page titles in either quote, in src and stories', () => {
+    expect([...sidebarHeadings(app({ ...PEEK_TODAY, 'stories/Tokens.mdx': "<Meta title='Tokens/All' />\n" }))].sort()).toEqual(['Docs', 'Primitives', 'Tokens'])
   })
 
-  it('reads the order with its comments removed, and says when there is none', () => {
-    expect(orderedHeadings(PREVIEW(['Docs', 'Pages']))).toEqual(['Docs', 'Pages'])
+  it("reads Storybook's own index, whatever way a title was written", () => {
+    expect([...indexHeadings({ a: { title: 'Pages/Desk' }, b: { title: 'Docs/Introduction' }, c: {} })].sort()).toEqual(['Docs', 'Pages'])
+  })
+
+  it('reads a HEADINGS list and a storySort order, skipping comments and nested lists', () => {
+    expect(orderedHeadings(HEADINGS_PREVIEW(['Docs', 'Pages']))).toEqual(['Docs', 'Pages'])
+    expect(orderedHeadings(ORDER_PREVIEW(['Docs', 'Primitives', 'Feedback']))).toEqual(['Docs', 'Primitives', 'Feedback'])
     expect(orderedHeadings('export default {}')).toBeNull()
   })
 
-  it('reads the Introduction: its bold table rows and its stated count', () => {
-    const intro = INTRO(49, ['Docs', 'Huddles'])
-    expect([...introductionHeadings(intro)]).toEqual(['Docs', 'Huddles'])
-    expect(introductionCount(intro)).toBe(49)
+  it("reads the Introduction's table rows and its bullets, and its stated count", () => {
+    expect([...introductionHeadings(TABLE_INTRO(49, ['Docs', 'Huddles']))]).toEqual(['Docs', 'Huddles'])
+    // A bullet with no dash after its bold words is prose, not a heading.
+    expect([...introductionHeadings(BULLET_INTRO([['Docs'], ['Primitives', 'Feedback', 'Inputs']]))]).toEqual(['Docs', 'Primitives', 'Feedback', 'Inputs'])
+    expect(introductionCount(TABLE_INTRO(49, ['Docs']))).toBe(49)
     expect(introductionCount('# No number here')).toBeNull()
   })
 })
 
 describe('storyMapProblems', () => {
   it("finds Peek's three stale lines: a heading in both maps with no story, and the wrong count", () => {
-    const problems = storyMapProblems(catalogue('reusable', 'reusable', 'reusable', 'local'), app(PEEK_TODAY))
-    expect(problems).toEqual([
-      '.storybook/preview.tsx: named in HEADINGS but no story uses them: Huddles',
+    expect(storyMapProblems(app(PEEK_TODAY), { registry: catalogue('reusable', 'reusable', 'reusable', 'local') })).toEqual([
+      '.storybook/preview.tsx: in the heading order but no story uses them: Huddles',
       'src/stories/Introduction.mdx: the page names, the sidebar does not have: Huddles',
       'src/stories/Introduction.mdx: says 2 parts worth reusing; the catalogue builds 3',
     ])
   })
 
-  it('finds a heading the maps forget, which falls to the bottom of the sidebar', () => {
-    const dir = app({ ...PEEK_TODAY, 'src/pages/Desk.stories.tsx': STORY('Pages/Desk') })
-    expect(storyMapProblems(catalogue('reusable', 'promote-candidate'), dir)).toEqual([
-      '.storybook/preview.tsx: not named in HEADINGS, so they fall to the bottom of the sidebar: Pages',
-      '.storybook/preview.tsx: named in HEADINGS but no story uses them: Huddles',
+  it("finds Ship's: an order and bullets naming Feedback, which it has not got, and leaving out Pages", () => {
+    const dir = app({
+      '.storybook/preview.tsx': ORDER_PREVIEW(['Docs', 'Primitives', 'Feedback']),
+      'src/stories/Introduction.mdx': BULLET_INTRO([['Docs'], ['Primitives', 'Feedback']]),
+    })
+    expect(storyMapProblems(dir, { real: new Set(['Docs', 'Primitives', 'Pages']) })).toEqual([
+      '.storybook/preview.tsx: not in the heading order, so they fall to the bottom of the sidebar: Pages',
+      '.storybook/preview.tsx: in the heading order but no story uses them: Feedback',
       'src/stories/Introduction.mdx: the sidebar has, the page does not name: Pages',
-      'src/stories/Introduction.mdx: the page names, the sidebar does not have: Huddles',
+      'src/stories/Introduction.mdx: the page names, the sidebar does not have: Feedback',
+    ])
+  })
+
+  it("finds the package's order leaving out Layout, from a Storybook index", () => {
+    const dir = app({ '.storybook/preview.tsx': ORDER_PREVIEW(['Docs', 'Primitives']) })
+    expect(storyMapProblems(dir, { real: indexHeadings({ a: { title: 'Layout/ListColumn' }, b: { title: 'Primitives/Button' }, c: { title: 'Docs/Introduction' } }) })).toEqual([
+      '.storybook/preview.tsx: not in the heading order, so they fall to the bottom of the sidebar: Layout',
     ])
   })
 
   it('passes when both maps match the Storybook and the count matches the catalogue', () => {
     const dir = app({
       ...PEEK_TODAY,
-      'src/stories/Introduction.mdx': INTRO(2, ['Docs', 'Primitives']),
-      '.storybook/preview.tsx': PREVIEW(['Docs', 'Primitives']),
+      'src/stories/Introduction.mdx': TABLE_INTRO(2, ['Docs', 'Primitives']),
+      '.storybook/preview.tsx': HEADINGS_PREVIEW(['Docs', 'Primitives']),
     })
-    expect(storyMapProblems(catalogue('reusable', 'promote-candidate', 'local'), dir)).toEqual([])
+    expect(storyMapProblems(dir, { registry: catalogue('reusable', 'promote-candidate', 'local') })).toEqual([])
   })
 
-  it('has nothing to check in an app that keeps no map', () => {
-    expect(storyMapProblems(catalogue('reusable'), app({ 'src/Badge.stories.tsx': STORY('Parts/Badge') }))).toEqual([])
+  it('has nothing to check in a repository that keeps no map', () => {
+    expect(storyMapProblems(app({ 'src/Badge.stories.tsx': STORY('Parts/Badge') }), { registry: catalogue('reusable') })).toEqual([])
   })
 })