@estiva-app/ui 0.25.0 → 0.27.0

package/src/registry/contract.test.ts

@@ -0,0 +1,158 @@
+/// <reference types="node" />
+/**
+ * UIG-19: the usage-page contract every app's `gate` job runs, and the story
+ * links. Each case is one the three repos actually have, or one that got past
+ * the copies this replaces:
+ *
+ * - a page that lost its `When not` (the ticket's own example);
+ * - Peek's pages, which never checked the order or the code under `How`;
+ * - a reusable part drawn only inside another story, whose page says so on a
+ *   **Seen in** line (Katerina, 21 September);
+ * - a story file named after a part whose stories draw its `…View` half, in the
+ *   same file — FilesPanel and TopicDetailsDialog in Peek, which the catalogue
+ *   used to call drawn nowhere;
+ * - a Windows checkout, read with CRLF.
+ */
+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 { buildAppRegistry } from './app'
+import { contractProblems, hasSeenIn, linkProblems, pageProblem } from './contract'
+
+const made: string[] = []
+afterAll(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true })
+})
+
+function app(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), 'uig19-'))
+  made.push(dir)
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture-app', version: '1.0.0' }))
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true })
+    writeFileSync(join(dir, path), text)
+  }
+  return dir
+}
+
+const PAGE = [
+  "import { Meta } from '@storybook/addon-docs/blocks'",
+  '',
+  "<Meta title='Parts/Badge' />",
+  '',
+  '# Badge',
+  '',
+  'A small count beside a name.',
+  '',
+  '## When',
+  '',
+  'A count.',
+  '',
+  '## When not',
+  '',
+  'A word.',
+  '',
+  '## How',
+  '',
+  '```tsx',
+  '<Badge count={3} />',
+  '```',
+  '',
+  '## What it owns',
+  '',
+  'Nothing. It only draws.',
+  '',
+].join('\n')
+
+const part = (name: string, cls = 'reusable') =>
+  `/**\n * ${name}, for the fixture.\n * @registry ${cls}: the fixture says so\n */\nexport function ${name}() {\n  return <span>${name}</span>\n}\n`
+
+describe('a usage page', () => {
+  it('keeps the contract with an opening line and the four sections in order', () => {
+    expect(pageProblem(PAGE)).toBeNull()
+  })
+
+  it('fails without "When not"', () => {
+    expect(pageProblem(PAGE.replace('## When not', '## Not when'))).toBe('no "When not" section')
+  })
+
+  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')
+    expect(pageProblem(swapped)).toMatch(/^sections out of order/)
+  })
+
+  it('fails with no opening line', () => {
+    expect(pageProblem(PAGE.replace('A small count beside a name.\n', ''))).toMatch(/^no opening line/)
+  })
+
+  it('fails with no code under How', () => {
+    expect(pageProblem(PAGE.replace('```tsx\n<Badge count={3} />\n```', 'Pass a count.'))).toBe('no code under "How"')
+  })
+
+  it('reads a Windows checkout', () => {
+    expect(pageProblem(PAGE.replace(/\n/g, '\r\n'))).toBeNull()
+  })
+
+  it('knows a Seen in line, and only at the start of a line', () => {
+    expect(hasSeenIn('**Seen in** — *Messages/ConversationCard*.')).toBe(true)
+    expect(hasSeenIn('It is **Seen in** two places.')).toBe(false)
+  })
+})
+
+describe('an app against the contract', () => {
+  it('passes a reusable part with a page and a story, and asks nothing of a one-off', () => {
+    const dir = app({
+      'src/Badge.tsx': part('Badge'),
+      'src/Badge.mdx': PAGE,
+      'src/Badge.stories.tsx': "import { Badge } from './Badge'\nconst meta = { title: 'Parts/Badge', component: Badge }\nexport default meta\nexport const Default = {}\n",
+      'src/Once.tsx': part('Once', 'one-off'),
+    })
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([])
+  })
+
+  it('names a reusable part with no page, and the file to write', () => {
+    const dir = app({ 'src/Badge.tsx': part('Badge') })
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([
+      'Badge (reusable, src/Badge.tsx) has no usage page: write src/Badge.mdx, with an opening line, then When, When not, How, What it owns',
+    ])
+  })
+
+  it('names a page that lost a section', () => {
+    const dir = app({ 'src/Badge.tsx': part('Badge'), 'src/Badge.mdx': PAGE.replace('## When not', '## Not when') })
+    const problems = contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)
+    expect(problems).toContain('Badge (reusable, src/Badge.tsx): src/Badge.mdx has no "When not" section')
+  })
+
+  it('names a reusable part drawn nowhere, and passes it once its page says where it is seen', () => {
+    const dir = app({ 'src/Badge.tsx': part('Badge'), 'src/Badge.mdx': PAGE })
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([
+      'Badge (reusable, src/Badge.tsx) is drawn nowhere: give it a story, or write a "**Seen in**" line on src/Badge.mdx naming the stories that draw it, or why none can',
+    ])
+    writeFileSync(join(dir, 'src/Badge.mdx'), 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'))
+    expect(contractProblems(buildAppRegistry({ root: dir, repo: 'fixture' }), dir)).toEqual([])
+  })
+
+  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`,
+      'src/Panel.stories.tsx': "import { PanelView } from './Panel'\nconst meta = { title: 'Parts/Panel', component: PanelView }\nexport default meta\nexport const Open = {}\n",
+    })
+    const entry = buildAppRegistry({ root: dir, repo: 'fixture' }).entries.find((e) => e.name === 'Panel')
+    expect(entry?.storyId).toBe('parts-panel--open')
+  })
+})
+
+describe('story links', () => {
+  it('names a link its Storybook does not have, and passes the ones it has', () => {
+    const dir = app({
+      'src/Badge.tsx': part('Badge'),
+      'src/Badge.stories.tsx': "import { Badge } from './Badge'\nconst meta = { title: 'Parts/Badge', component: Badge }\nexport default meta\nexport const Default = {}\n",
+    })
+    const registry = buildAppRegistry({ root: dir, repo: 'fixture' })
+    expect(linkProblems(registry, new Set(['parts-badge--default', 'parts-badge--docs']))).toEqual([])
+    expect(linkProblems(registry, new Set(['parts-badge--docs']))).toEqual([
+      'Badge (src/Badge.tsx) links to a story its Storybook does not have: parts-badge--default',
+    ])
+  })
+})

package/src/registry/contract.ts

@@ -0,0 +1,108 @@
+/**
+ * The usage-page contract, checked against an app's catalogue (UIG-19).
+ *
+ * Every part an app classifies **reusable** (or **promote-candidate**) has a
+ * page beside it — `<PartName>.mdx` in the component's own folder — that opens
+ * with a line saying what the part is, then `When`, `When not`, `How` (with
+ * code) and `What it owns`, in that order. And it is drawn somewhere: a story
+ * of its own, or a **Seen in** line on its page naming the stories that draw
+ * it, or saying why none can (Katerina, 21 and 23 September 2026). A one-off
+ * needs only its class and a purpose line, which the catalogue already refuses
+ * to build without.
+ *
+ * This is the one copy. Peek and Ship each used to carry their own, pasted into
+ * their `scripts/gates-checks.mjs` and run only by `gates:status`, so a page
+ * could lose its `When not` and still merge. `estiva-ui check` runs this in
+ * every app's `gate` job (docs/GATES.md §23: one copy, in the package).
+ *
+ * The package's own pages keep the fuller contract in `src/pages.test.ts`,
+ * which also reads `What it owns` back against the lint rule.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Registry } from './schema'
+
+/** The four headings, in the order a page carries them. */
+export const PAGE_SECTIONS = ['When', 'When not', 'How', 'What it owns'] as const
+
+/** The classes that owe a page and a picture. */
+export const CONTRACT_KINDS = ['reusable', 'promote-candidate'] as const
+
+/** The line that stands in for a story of the part's own. */
+const SEEN_IN = /^\*\*Seen in\*\*/m
+
+/**
+ * Why a page breaks the contract, or null when it keeps it.
+ *
+ * Read on normalised text: the apps are checked out with CRLF on Windows.
+ */
+export function pageProblem(source: string): string | null {
+  const text = source.replace(/\r\n/g, '\n')
+  const heads = [...text.matchAll(/^##+\s+(.+?)\s*$/gm)].map((m) => m[1])
+  const at = PAGE_SECTIONS.map((s) => heads.indexOf(s))
+  const missing = PAGE_SECTIONS.filter((_, i) => at[i] < 0)
+  if (missing.length) return `no ${missing.map((s) => `"${s}"`).join(', ')} section`
+  if (at.some((i, n) => n > 0 && i < at[n - 1])) return `sections out of order: they go ${PAGE_SECTIONS.join(', ')}`
+  // The opening line: the first paragraph under the title that is not markup.
+  const opening = text
+    .split(/^# .*$/m)[1]
+    ?.split(/^##\s/m)[0]
+    ?.split(/\n\s*\n/)
+    .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"'
+  return null
+}
+
+/** Whether a page records where the part is drawn, in place of a story of its own. */
+export function hasSeenIn(source: string): boolean {
+  return SEEN_IN.test(source.replace(/\r\n/g, '\n'))
+}
+
+/**
+ * Every catalogue link that names a story or a docs page its Storybook does not
+ * have (UIG-19: a dead link is a build failure, not a dead end found six weeks
+ * later). `ids` is every entry id in the Storybook's own index — what
+ * `storybook index` writes — so this is Storybook's answer, not a guess at how
+ * it builds an id.
+ */
+export function linkProblems(registry: Registry, ids: ReadonlySet<string>): string[] {
+  const problems: string[] = []
+  for (const entry of registry.entries) {
+    for (const key of ['storyId', 'docsId'] as const) {
+      const id = entry[key]
+      if (id && !ids.has(id)) problems.push(`${entry.name} (${entry.sourceFile}) links to ${key === 'storyId' ? 'a story' : 'a docs page'} its Storybook does not have: ${id}`)
+    }
+  }
+  return problems
+}
+
+/**
+ * Every way an app's catalogue breaks the contract, one line each, naming the
+ * part, its file and what to do. Empty when it keeps it.
+ *
+ * `root` is the app's own folder: the one its catalogue's paths are relative to.
+ */
+export function contractProblems(registry: Registry, root: string): string[] {
+  const problems: string[] = []
+  for (const entry of registry.entries) {
+    const cls = entry.app?.class
+    if (!cls || !(CONTRACT_KINDS as readonly string[]).includes(cls)) continue
+    // Where the page must be: beside the component, named after the part —
+    // the same place the catalogue looks (src/registry/app.ts).
+    const page = join(entry.sourceFile.replace(/[^/\\]+$/, ''), `${entry.name}.mdx`).replace(/\\/g, '/')
+    const where = `${entry.name} (${cls}, ${entry.sourceFile})`
+    if (!existsSync(join(root, page))) {
+      problems.push(`${where} has no usage page: write ${page}, with an opening line, then ${PAGE_SECTIONS.join(', ')}`)
+      continue
+    }
+    const text = readFileSync(join(root, page), 'utf8')
+    const problem = pageProblem(text)
+    if (problem) problems.push(`${where}: ${page} has ${problem}`)
+    if (entry.storyId === null && !hasSeenIn(text)) {
+      problems.push(`${where} is drawn nowhere: give it a story, or write a "**Seen in**" line on ${page} naming the stories that draw it, or why none can`)
+    }
+  }
+  return problems
+}

package/src/registry/gated.test.ts

@@ -0,0 +1,98 @@
+/// <reference types="node" />
+/**
+ * UIG-19: what a part draws only behind a prop, and no story passes. Each case
+ * is one the scan met in Peek or the package:
+ *
+ * - a gate on the part itself (SectionHeader's chevron);
+ * - a prop handed to a smaller part that gates on it (ConversationCard's
+ *   `onReply`, which the strip draws — strict, by Katerina's ruling);
+ * - a prop handed to a dialog, shut in every story (skipped, her ruling);
+ * - a story that spreads another story's args (`...Topic.args`);
+ * - a spread it cannot open (a helper's `{...props}`), which keeps it quiet.
+ */
+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 { buildAppRegistry } from './app'
+import { gatedFindings } from './gated'
+
+const made: string[] = []
+afterAll(() => {
+  for (const dir of made) rmSync(dir, { recursive: true, force: true })
+})
+
+function app(files: Record<string, string>): string {
+  const dir = mkdtempSync(join(tmpdir(), 'uig19-gated-'))
+  made.push(dir)
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture-app', version: '1.0.0' }))
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(dir, path)), { recursive: true })
+    writeFileSync(join(dir, path), text)
+  }
+  return dir
+}
+
+const find = (dir: string) => gatedFindings(buildAppRegistry({ root: dir, repo: 'fixture' }), dir).map((f) => `${f.part}.${f.prop}`)
+
+const card = `/**
+ * A card.
+ * @registry reusable: the fixture says so
+ */
+export function Card({ title, onReply, onShare }: { title: string; onReply?: () => void; onShare?: () => void }) {
+  return (
+    <div>
+      {title}
+      {onReply && <button type="button">Reply</button>}
+      <Strip onShare={onShare} />
+      <ShareDialog onShare={onShare} />
+    </div>
+  )
+}
+
+/** The strip under a card. */
+export function Strip({ onShare }: { onShare?: () => void }) {
+  return <div>{onShare ? <button type="button">Share</button> : null}</div>
+}
+
+/** A dialog, shut until opened. */
+export function ShareDialog({ onShare }: { onShare?: () => void }) {
+  return <div>{onShare && <button type="button">Share now</button>}</div>
+}
+`
+
+const story = (body: string) => `import { Card } from './Card'\nconst meta = { title: 'Parts/Card', component: Card, args: { title: 'Hello' } }\nexport default meta\n${body}\n`
+
+describe('what a part draws behind a prop', () => {
+  it('names a gate on the part, and one it hands to a smaller part, when no story passes either', () => {
+    const dir = app({ 'src/Card.tsx': card, 'src/Card.stories.tsx': story('export const Default = {}') })
+    expect(find(dir).sort()).toEqual(['Card.onReply', 'Card.onShare'])
+  })
+
+  it('is satisfied by a story that passes them, in args or through another story’s args', () => {
+    const dir = app({
+      'src/Card.tsx': card,
+      'src/Card.stories.tsx': story("export const Default = { args: { onReply: () => {} } }\nexport const Shared = { args: { ...Default.args, onShare: () => {} } }"),
+    })
+    expect(find(dir)).toEqual([])
+  })
+
+  it('skips a prop that reaches only a dialog', () => {
+    const only = card.replace('      <Strip onShare={onShare} />\n', '')
+    const dir = app({ 'src/Card.tsx': only, 'src/Card.stories.tsx': story("export const Default = { args: { onReply: () => {} } }") })
+    expect(find(dir)).toEqual([])
+  })
+
+  it('stays quiet when a story passes props it cannot read', () => {
+    const dir = app({
+      'src/Card.tsx': card,
+      'src/Card.stories.tsx': `import { Card } from './Card'\nimport { props } from './fixtures'\nconst meta = { title: 'Parts/Card', component: Card }\nexport default meta\nexport const Default = { render: () => <Card title="x" {...props} /> }\n`,
+    })
+    expect(find(dir)).toEqual([])
+  })
+
+  it('asks nothing of a part no story draws: the contract says so instead', () => {
+    const dir = app({ 'src/Card.tsx': card })
+    expect(find(dir)).toEqual([])
+  })
+})

package/src/registry/gated.ts

@@ -0,0 +1,308 @@
+/**
+ * What a part draws only when a prop is passed, and no story passes it (UIG-19,
+ * Katerina's ruling 5).
+ *
+ * `{onReply && <IconButton … />}` works in the app, because the app passes
+ * `onReply`. In Storybook nothing does, so the button is simply not there. It
+ * reads as a broken behaviour rather than a missing fixture, and it hides the
+ * very state a reviewer came to see. UIG-17 found five in Peek by hand: Reply on
+ * ConversationCard, Edit and Delete on ReplyCard, Rename and Copy link on
+ * TopicMoreMenu, Open original on ThreadPanel.
+ *
+ * Read with TypeScript, part by part. The gate is looked for only inside the
+ * part's own function (and its `…View` half, when the stories draw that),
+ * because a file is not a component: UIG-17's first scan blamed ReplyCard for
+ * two props that belong to a menu declared beside it. A story passes a prop by
+ * naming it in an `args` object or as an attribute on the part's tag, anywhere
+ * in a story file that imports the part's file.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
+import ts from 'typescript'
+import type { Registry } from './schema'
+
+export interface GatedFinding {
+  part: string
+  file: string
+  prop: string
+  /** The part or view whose body holds the gate. */
+  in: string
+}
+
+const parse = (file: string, text: string) => ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)
+
+/** The function a name is declared as: `function X`, `const X = (…) =>`, `memo(…)`, `forwardRef(…)`. */
+function declared(sf: ts.SourceFile, name: string): ts.FunctionLikeDeclaration | null {
+  let found: ts.FunctionLikeDeclaration | null = null
+  const unwrap = (e: ts.Expression | undefined): ts.FunctionLikeDeclaration | null => {
+    if (!e) return null
+    if (ts.isArrowFunction(e) || ts.isFunctionExpression(e)) return e
+    if (ts.isCallExpression(e)) return unwrap(e.arguments[0])
+    if (ts.isParenthesizedExpression(e) || ts.isAsExpression(e) || ts.isSatisfiesExpression(e)) return unwrap(e.expression)
+    return null
+  }
+  for (const s of sf.statements) {
+    if (ts.isFunctionDeclaration(s) && s.name?.text === name) found = s
+    if (ts.isVariableStatement(s)) for (const d of s.declarationList.declarations) if (ts.isIdentifier(d.name) && d.name.text === name) found = unwrap(d.initializer)
+  }
+  return found
+}
+
+/** The props a function takes, by the name its body uses: `{ onReply, owner: who }` → onReply→onReply, who→owner. */
+function propsOf(fn: ts.FunctionLikeDeclaration): { locals: Map<string, string>; object: string | null } {
+  const locals = new Map<string, string>()
+  const first = fn.parameters[0]
+  if (!first) return { locals, object: null }
+  if (ts.isObjectBindingPattern(first.name)) {
+    for (const el of first.name.elements) {
+      if (el.dotDotDotToken || !ts.isIdentifier(el.name)) continue
+      const prop = el.propertyName && ts.isIdentifier(el.propertyName) ? el.propertyName.text : el.name.text
+      locals.set(el.name.text, prop)
+    }
+    return { locals, object: null }
+  }
+  return { locals, object: ts.isIdentifier(first.name) ? first.name.text : null }
+}
+
+const drawsJsx = (node: ts.Node): boolean => {
+  let yes = false
+  const walk = (n: ts.Node) => {
+    if (yes) return
+    if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n)) yes = true
+    else ts.forEachChild(n, walk)
+  }
+  walk(node)
+  return yes
+}
+
+/** Every prop that gates something drawn: `{p && <X/>}`, `{p ? <X/> : null}`, `{!!p && …}`, `{p != null && …}`. */
+function gates(fn: ts.FunctionLikeDeclaration): Set<string> {
+  const { locals, object } = propsOf(fn)
+  const out = new Set<string>()
+  const propIn = (e: ts.Expression): string | null => {
+    while (ts.isParenthesizedExpression(e) || ts.isNonNullExpression(e)) e = e.expression
+    if (ts.isPrefixUnaryExpression(e) && e.operator === ts.SyntaxKind.ExclamationToken && ts.isPrefixUnaryExpression(e.operand)) return propIn(e.operand.operand)
+    if (ts.isBinaryExpression(e) && [ts.SyntaxKind.ExclamationEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken].includes(e.operatorToken.kind)) return propIn(e.left)
+    if (ts.isIdentifier(e)) return locals.get(e.text) ?? null
+    if (object && ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && e.expression.text === object) return e.name.text
+    return null
+  }
+  const walk = (n: ts.Node) => {
+    // A function declared inside is its own component or handler: not this part's markup.
+    if (n !== fn && ts.isFunctionDeclaration(n)) return
+    if (ts.isJsxExpression(n) && n.expression) {
+      const e = n.expression
+      if (ts.isBinaryExpression(e) && e.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken && drawsJsx(e.right)) {
+        const p = propIn(e.left)
+        if (p) out.add(p)
+      }
+      if (ts.isConditionalExpression(e) && drawsJsx(e.whenTrue) && !drawsJsx(e.whenFalse)) {
+        const p = propIn(e.condition)
+        if (p) out.add(p)
+      }
+    }
+    ts.forEachChild(n, walk)
+  }
+  if (fn.body) walk(fn.body)
+  return out
+}
+
+/** Stands for "every prop": a spread the reader cannot open might pass any of them. */
+const ANY = '*'
+
+/**
+ * Every prop name a story file passes: keys of any `args` object, and
+ * attributes on the named tags. A spread of an object declared in the same
+ * file is opened (`args: { replyCount: 3, ...replyRow }`); one it cannot open
+ * — an import, a call — counts as passing everything, so the check stays quiet
+ * rather than wrong.
+ */
+function passed(sf: ts.SourceFile, tags: string[]): Set<string> {
+  const out = new Set<string>()
+  const consts = new Map<string, ts.ObjectLiteralExpression>()
+  for (const s of sf.statements) {
+    if (!ts.isVariableStatement(s)) continue
+    for (const d of s.declarationList.declarations) if (ts.isIdentifier(d.name) && d.initializer && ts.isObjectLiteralExpression(d.initializer)) consts.set(d.name.text, d.initializer)
+  }
+  const keysOf = (o: ts.ObjectLiteralExpression, seen: Set<string>) => {
+    for (const p of o.properties) {
+      if (ts.isSpreadAssignment(p)) {
+        // `...replyRow`, or another story's args: `...Topic.args`.
+        const e = p.expression
+        const name = ts.isIdentifier(e) ? e.text : ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && e.name.text === 'args' ? `${e.expression.text}.args` : null
+        let target: ts.ObjectLiteralExpression | undefined
+        if (name && !seen.has(name)) {
+          if (!name.endsWith('.args')) target = consts.get(name)
+          else {
+            const story = consts.get(name.slice(0, -'.args'.length))
+            const args = story?.properties.find((q) => ts.isPropertyAssignment(q) && ts.isIdentifier(q.name) && q.name.text === 'args')
+            if (args && ts.isPropertyAssignment(args) && ts.isObjectLiteralExpression(args.initializer)) target = args.initializer
+          }
+        }
+        if (target) keysOf(target, new Set([...seen, name!]))
+        else out.add(ANY)
+      } else if (p.name && (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name))) out.add(p.name.text)
+    }
+  }
+  const walk = (n: ts.Node) => {
+    if (ts.isPropertyAssignment(n) && ts.isIdentifier(n.name) && n.name.text === 'args') {
+      if (ts.isObjectLiteralExpression(n.initializer)) keysOf(n.initializer, new Set())
+      else out.add(ANY)
+    }
+    if ((ts.isJsxSelfClosingElement(n) || ts.isJsxOpeningElement(n)) && tags.includes(n.tagName.getText(sf))) {
+      for (const a of n.attributes.properties) {
+        if (ts.isJsxAttribute(a)) out.add(a.name.getText(sf))
+        else if (ts.isJsxSpreadAttribute(a)) {
+          const target = ts.isIdentifier(a.expression) ? consts.get(a.expression.text) : undefined
+          if (target) keysOf(target, new Set())
+          // `{...args}` hands on what `args` holds, and those are read where they are written.
+          else if (!(ts.isIdentifier(a.expression) && a.expression.text === 'args')) out.add(ANY)
+        }
+      }
+    }
+    ts.forEachChild(n, walk)
+  }
+  walk(sf)
+  return out
+}
+
+function storyFiles(root: string): string[] {
+  const out: string[] = []
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      if (name === 'node_modules' || name.startsWith('.')) continue
+      const path = join(dir, name)
+      if (statSync(path).isDirectory()) walk(path)
+      else if (/\.stories\.tsx?$/.test(name)) out.push(path)
+    }
+  }
+  if (existsSync(join(root, 'src'))) walk(join(root, 'src'))
+  return out
+}
+
+/** The props a part hands straight on to another tag: `<QuickActions onReply={onReply} />` → QuickActions, onReply, onReply. */
+function handsOn(fn: ts.FunctionLikeDeclaration, sf: ts.SourceFile): { tag: string; attr: string; prop: string }[] {
+  const { locals, object } = propsOf(fn)
+  const out: { tag: string; attr: string; prop: string }[] = []
+  const walk = (n: ts.Node) => {
+    if (n !== fn && ts.isFunctionDeclaration(n)) return
+    if (ts.isJsxSelfClosingElement(n) || ts.isJsxOpeningElement(n)) {
+      const tag = n.tagName.getText(sf)
+      if (/^[A-Z]/.test(tag)) {
+        for (const a of n.attributes.properties) {
+          if (!ts.isJsxAttribute(a) || !a.initializer || !ts.isJsxExpression(a.initializer) || !a.initializer.expression) continue
+          const e = a.initializer.expression
+          const prop = ts.isIdentifier(e) ? locals.get(e.text) : object && ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && e.expression.text === object ? e.name.text : undefined
+          if (prop) out.push({ tag, attr: a.name.getText(sf), prop })
+        }
+      }
+    }
+    ts.forEachChild(n, walk)
+  }
+  if (fn.body) walk(fn.body)
+  return out
+}
+
+/** Where a module specifier points, without its extension: `./X`, or Vite's `@/` for `src/`. */
+function target(from: string, spec: string, root: string): string | null {
+  if (spec.startsWith('.')) return join(dirname(from), spec).replace(/\.[jt]sx?$/, '')
+  if (spec.startsWith('@/')) return join(root, 'src', spec.slice(2)).replace(/\.[jt]sx?$/, '')
+  return null
+}
+
+/**
+ * Every prop that gates something a part draws, where some story draws the
+ * part and none of those stories passes the prop.
+ *
+ * "Draws the part" means a story file imports the part's own file — its own
+ * stories, or an umbrella sheet such as Peek's Overlays/Menus, which is how
+ * TopicMoreMenu lost Rename and Copy link. A gate a part only hands on counts
+ * as its own: ConversationCard hands `onReply` to the strip that draws Reply,
+ * so a ConversationCard story that never passes it shows no Reply. Followed
+ * three parts deep at most.
+ */
+export interface GatedOptions {
+  /** The classes checked. The contract's by default. */
+  kinds?: readonly string[]
+  /**
+   * `own`: a part's own stories show everything it can draw — ConversationCard's
+   * stories must show Reply. `anywhere`: a handed-on gate counts as shown when
+   * the part it is handed to has a story that shows it. Katerina rules which.
+   */
+  pictured?: 'own' | 'anywhere'
+}
+
+export function gatedFindings(registry: Registry, root: string, { kinds = ['reusable', 'promote-candidate'], pictured = 'own' }: GatedOptions = {}): GatedFinding[] {
+  const findings: GatedFinding[] = []
+  const stories = storyFiles(root).map((file) => ({ file, sf: parse(file, readFileSync(file, 'utf8')) }))
+  const sources = new Map<string, ts.SourceFile>()
+  const sourceOf = (rel: string): ts.SourceFile | null => {
+    const path = join(root, rel)
+    if (!sources.has(path)) {
+      if (!existsSync(path)) return null
+      sources.set(path, parse(path, readFileSync(path, 'utf8')))
+    }
+    return sources.get(path)!
+  }
+  const fileOf = new Map(registry.entries.filter((e) => e.kind === 'component').map((e) => [e.name, e.sourceFile]))
+
+  /** The story files that import a file, and every prop they pass to the part or its view. */
+  const givenTo = new Map<string, { drawn: boolean; given: Set<string> }>()
+  const storiesOf = (name: string, rel: string) => {
+    const key = `${rel}#${name}`
+    if (!givenTo.has(key)) {
+      const own = join(root, rel).replace(/\.[jt]sx?$/, '')
+      const drawing = stories.filter(({ file, sf: s }) =>
+        s.statements.some((st) => ts.isImportDeclaration(st) && ts.isStringLiteral(st.moduleSpecifier) && target(file, st.moduleSpecifier.text, root) === own),
+      )
+      givenTo.set(key, { drawn: drawing.length > 0, given: new Set(drawing.flatMap(({ sf: s }) => [...passed(s, [name, `${name}View`])])) })
+    }
+    return givenTo.get(key)!
+  }
+
+  const memo = new Map<string, Set<string>>()
+  /** The props a named part gates on, its own and those it hands to a part that gates. */
+  const gatesOf = (name: string, sf: ts.SourceFile, depth: number): Set<string> => {
+    const key = `${sf.fileName}#${name}`
+    if (memo.has(key)) return memo.get(key)!
+    memo.set(key, new Set())
+    const fn = declared(sf, name)
+    const out = fn ? gates(fn) : new Set<string>()
+    if (fn && depth < 3) {
+      for (const { tag, attr, prop } of handsOn(fn, sf)) {
+        // A dialog is shut in a story until someone opens it, so nothing it draws
+        // is missing from the picture (Katerina, 23 September).
+        if (out.has(prop) || /Dialog$/.test(tag)) continue
+        const here = declared(sf, tag) ? sf : fileOf.has(tag) ? sourceOf(fileOf.get(tag)!) : null
+        if (!here || !gatesOf(tag, here, depth + 1).has(attr)) continue
+        // Already pictured one level down: CollapsibleSection hands `trailing` to
+        // SectionHeader, and SectionHeader's own story shows the slot.
+        const theirs = fileOf.get(tag)
+        if (pictured === 'anywhere' && theirs && here !== sf) {
+          const { given } = storiesOf(tag, theirs)
+          if (given.has(attr) || given.has(ANY)) continue
+        }
+        out.add(prop)
+      }
+    }
+    memo.set(key, out)
+    return out
+  }
+
+  for (const entry of registry.entries) {
+    // The package's entries carry no app class: every one of its components is one.
+    const cls = entry.app?.class ?? 'component'
+    if (!kinds.includes(cls) || entry.kind !== 'component') continue
+    const sf = sourceOf(entry.sourceFile)
+    if (!sf) continue
+    const { drawn, given } = storiesOf(entry.name, entry.sourceFile)
+    // No story draws it at all: the contract's "drawn nowhere" says so, not this.
+    if (!drawn || given.has(ANY)) continue
+    for (const name of [entry.name, `${entry.name}View`]) {
+      for (const prop of gatesOf(name, sf, 0)) {
+        if (!given.has(prop)) findings.push({ part: entry.name, file: entry.sourceFile.split('\\').join('/'), prop, in: name })
+      }
+    }
+  }
+  return findings
+}