From a87bcf87d3d35ff9a4182221762cd7af9698f753 Mon Sep 17 00:00:00 2001
From: Dominic Buetow <fxOne@users.noreply.github.com>
Date: Mon, 3 Aug 2026 01:20:33 +0200
Subject: [PATCH] init

---
 packages/prop-flow/CHANGELOG.md               |  38 ++-
 packages/prop-flow/README.md                  |  81 +++++-
 .../prop-flow/fixtures/basic/constant.tsx     | 198 +++++++++++++
 packages/prop-flow/package.json               |   2 +-
 packages/prop-flow/src/analyzer.test.ts       |  92 +++++-
 packages/prop-flow/src/analyzer.ts            | 274 +++++++++++-------
 packages/prop-flow/src/args.test.ts           |  14 +-
 packages/prop-flow/src/args.ts                |   8 +-
 packages/prop-flow/src/ast.test.ts            |  24 +-
 packages/prop-flow/src/ast.ts                 |  22 +-
 packages/prop-flow/src/classify.ts            |  32 +-
 packages/prop-flow/src/cli.test.ts            |  43 +++
 packages/prop-flow/src/cli.ts                 |  20 +-
 packages/prop-flow/src/index.ts               |  13 +-
 packages/prop-flow/src/prop-flow.test.ts      |  33 ++-
 packages/prop-flow/src/prop-flow.ts           |  32 +-
 packages/prop-flow/src/report.test.ts         |  54 +++-
 packages/prop-flow/src/report.ts              |  49 +++-
 packages/prop-flow/src/types.ts               |  33 ++-
 packages/prop-flow/src/usage-index.test.ts    | 113 ++++++++
 packages/prop-flow/src/usage-index.ts         |  99 +++++++
 packages/prop-flow/src/values.ts              |  30 ++
 22 files changed, 1105 insertions(+), 199 deletions(-)
 create mode 100644 packages/prop-flow/fixtures/basic/constant.tsx
 create mode 100644 packages/prop-flow/src/usage-index.test.ts
 create mode 100644 packages/prop-flow/src/usage-index.ts
 create mode 100644 packages/prop-flow/src/values.ts

diff --git a/packages/prop-flow/CHANGELOG.md b/packages/prop-flow/CHANGELOG.md
index 6c628847..3d5f71fd 100644
--- a/packages/prop-flow/CHANGELOG.md
+++ b/packages/prop-flow/CHANGELOG.md
@@ -5,28 +5,52 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## To Be Released
 
+## 2.0.0
+
+- **BREAKING CHANGE**: `OptionalProp` is now `DeclaredProp`, with an added
+  `optional` field, and `Analyzer.listOptionalProps` is now
+  `listProps(component, { includeRequired })`
+- **BREAKING CHANGE**: `PropAnalysis` carries a required `constant` field, so
+  every `--json` row has one — `null` where there is no finding
+- **BREAKING CHANGE**: `SiteKind` no longer has a `spread` member — former
+  spread sites are now reported as `passthrough` / `real` / `omit` / `manual`
+  with a note
+- All three land in the library API and the `--json` shape; the CLI arguments
+  and the text output only gained things
+- Props that are passed the same value at every call site are reported as such.
+  Values are read off the type, so `size="sm"`, a `const`, an enum member and a
+  property of an `as const` object all resolve to one value; anything the
+  checker cannot pin to a literal, and any `manual` site, leaves the claim
+  unmade. `coverage: 'all'` says the omissions land on the value too, via the
+  component's own default — that is the case where the prop can go away
+- `--all-props` widens discovery to required props. They are reported only
+  where they carry a constant value, under a new `required` verdict; without
+  the flag the output is unchanged
 - JSX spreads are resolved instead of being blanket-reported as `manual`: a
   spread whose type provably lacks the prop is skipped, `{...props}` and
   `{...rest}` are followed one level up, and a spread of an object literal (or
   of a `const` bound to one) is read key by key. Only a spread whose type cannot
   answer the question, or an optional prop in a spread contesting an earlier
   value, still requires a human
+- Optional props declared only in a dependency are no longer reported. A
+  component spreading `React.ComponentProps<'button'>` inherits some 250
+  optional DOM and ARIA props; a verdict on those is true but not actionable,
+  and it buried the props the author actually owns
 - Fixed attribute precedence: `<C title="x" {...props} />` reported `"x"`, but
   JSX resolves last-wins, so the spread overrides the attribute
 - Fixed pass-throughs inside render callbacks: `items.map(() => <C x={props.x}/>)`
   was classified as a local value, which could turn into a wrong `justified` or
   `unnecessary-optional`
-- Optional props declared only in a dependency are no longer reported. A
-  component spreading `React.ComponentProps<'button'>` inherits some 250
-  optional DOM and ARIA props; a verdict on those is true but not actionable,
-  and it buried the props the author actually owns
+- Fixed a pass-through into a prop that binds its own default: the omissions at
+  that level were counted as omissions at the leaf, reporting a prop that is in
+  fact always set as `caller-dead`. `Relay({ size = 'lg' })` forwarding `size`
+  feeds `'lg'` down, and that is now what the counts and the value say. Each
+  absorbed omission is listed at the call site where the default fires, so the
+  pass count still lines up with the sites below it
 - A pass-through that climbs into a function which is called rather than
   rendered (a `renderX({ … })` test helper) now reports `manual` instead of
   counting its invisible callers as zero, which would report a live prop as
   `caller-dead`
-- `--json` output: `SiteKind` no longer has a `spread` member — former spread
-  sites are now reported as `passthrough` / `real` / `omit` / `manual` with a
-  note
 
 ## 1.0.0
 
diff --git a/packages/prop-flow/README.md b/packages/prop-flow/README.md
index 7d7ff251..49bc449e 100644
--- a/packages/prop-flow/README.md
+++ b/packages/prop-flow/README.md
@@ -28,15 +28,16 @@ directory, so it always analyses your code with the compiler your code uses.
 ## Usage
 
 ```bash
-$ pnpm prop-flow <file> [propName] [--tsconfig <path>] [--json]
+$ pnpm prop-flow <file> [propName] [--tsconfig <path>] [--all-props] [--json]
 ```
 
-| argument     | meaning                                                                                                             |
-| ------------ | ------------------------------------------------------------------------------------------------------------------- |
-| `<file>`     | a `.ts`/`.tsx` file containing the component(s) to inspect                                                          |
-| `[propName]` | one prop; omitted → every optional prop of every component exported from the file                                   |
-| `--tsconfig` | override the auto-discovered tsconfig — use the broadest "solution" config so call sites in other packages are seen |
-| `--json`     | machine-readable output                                                                                             |
+| argument       | meaning                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `<file>`       | a `.ts`/`.tsx` file containing the component(s) to inspect                                                          |
+| `[propName]`   | one prop; omitted → every optional prop of every component exported from the file                                   |
+| `--tsconfig`   | override the auto-discovered tsconfig — use the broadest "solution" config so call sites in other packages are seen |
+| `--all-props`  | inspect required props too — reported only where they carry a constant value                                        |
+| `--json`       | machine-readable output                                                                                             |
 
 ```
 $ pnpm prop-flow src/Button.tsx title
@@ -61,10 +62,50 @@ justified         Button.title
 | `caller-dead`          | no call site passes it → optional and always `undefined`                 |
 | `unused-component`     | the component itself has no call sites in the Program                    |
 | `manual`               | an unreadable spread or a contested override blocks a static conclusion  |
+| `required`             | the prop has no `?` to judge — listed only for its constant value        |
 
 Exit codes: `0` success, `1` nothing to do (usage printed), `2` a handled
 failure (message on stderr).
 
+## Constant values
+
+A prop that is passed the same value at every call site carries no information:
+the value can be inlined and the prop dropped. That question is **orthogonal**
+to the `?` — a prop can be `justified` (some call sites omit it) and still be
+constant everywhere it is passed, which is the most interesting combination of
+all. So it is reported as its own field rather than as a verdict:
+
+```
+justified         Chip.variant
+   passes=2  omits=1  ambiguous=0
+   constant="danger"  coverage=passes
+     real        src/App.tsx:4:7 (string literal)
+     real        src/App.tsx:5:7 (string literal)
+     omit        src/App.tsx:6:7
+   → genuinely sometimes-absent. The `?` is correct.
+   → every passing call site sends "danger"; the value could be inlined.
+```
+
+Values are read off the **type**, not off the syntax, so `size="sm"`,
+`size={'sm'}`, a `const SIZE = 'sm'`, an enum member and a property of an
+`as const` object all resolve to the same value — and anything the checker
+cannot pin to a single literal (a call, a parameter, a widened `let`) leaves
+the claim unmade. `<C dense />` counts as `true`.
+
+Two coverages: `passes` means every call site that passes the prop agrees; `all`
+means nothing anywhere sees another value — either there are no omissions, or
+the component's own binding default is that same value, so the omissions land
+on it too. `all` is the case where the prop can go away entirely.
+
+Nothing is reported below two passing sites — with one, "always the same value"
+is trivially true. And constant does not mean wrong: `variant="danger"` on the
+two delete buttons is constant and correct, which is why the hint stops at
+"could be inlined".
+
+`--all-props` widens *discovery* to required props, not the report: a required
+prop shows up only when it actually carries a constant value, under the
+`required` verdict. Without the flag the output is exactly as it was.
+
 ## API
 
 The same analysis is available programmatically:
@@ -76,15 +117,35 @@ const report = analyseProps({ file: 'src/Button.tsx', prop: 'title' });
 process.stdout.write(formatText(report));
 ```
 
-`analyseProps` accepts `{ cwd, file, prop, ts, tsconfig }` and returns a
-`Report`; passing `ts` injects a specific compiler instead of resolving one
+`analyseProps` accepts `{ allProps, cwd, file, prop, ts, tsconfig }` and returns
+a `Report`; passing `ts` injects a specific compiler instead of resolving one
 from `cwd`.
 
 ## Limitations
 
 Pass-throughs are followed through plain identifiers and `props.x` member
 access, including inside render callbacks — a `props.x` in `items.map(…)` is
-still traced to the surrounding component.
+still traced to the surrounding component. When a level of the chain binds its
+own default, an omission at *its* call sites is counted as a pass of that
+default rather than as an omission at the leaf: `Relay({ size = 'lg' })`
+forwarding `size` feeds `'lg'` down, not `undefined`. Those absorbed omissions
+are listed individually, at the call site where the default fires:
+
+```
+NEEDLESS ?        Hop.size
+   passes=2  omits=0  ambiguous=0
+   constant="lg"  coverage=all
+     passthrough src/Relay.tsx:9:10 → Relay.size (omissions fall back to its default)
+     real        src/App.tsx:14:7 → Relay.size (the default fires here)
+     real        src/App.tsx:15:7 → Relay.size (the default fires here)
+```
+
+Otherwise the counts are of *leaves*, not of lines: one pass-through site can
+stand for a whole subtree of passes and omissions below it.
+
+A constancy claim needs every call site to be readable. One `manual` site sinks
+it — an unreadable spread could be carrying any value at all — as does a single
+value the checker cannot pin to a literal.
 
 A spread is only ambiguous when it can actually reach the prop. `{...x}` whose
 type provably lacks the prop is skipped; `{...props}` and `{...rest}` are
diff --git a/packages/prop-flow/fixtures/basic/constant.tsx b/packages/prop-flow/fixtures/basic/constant.tsx
new file mode 100644
index 00000000..c1bac53f
--- /dev/null
+++ b/packages/prop-flow/fixtures/basic/constant.tsx
@@ -0,0 +1,198 @@
+// What makes a prop constant across its call sites, and what breaks the claim.
+// Each component below is one case; `ConstantApp` at the bottom is the only
+// render root in this file, so nothing here moves the counts the other fixtures
+// assert.
+
+export interface ChipProps {
+  id: string;
+  /** justified AND constant: two passes of one value, plus an omission */
+  variant?: string;
+}
+
+export function Chip({ id, variant }: ChipProps) {
+  return <b data-id={id} data-variant={variant} />;
+}
+
+export interface TileProps {
+  id: string;
+  /** constant with coverage=all: the omission lands on the same value */
+  size?: string;
+}
+
+export function Tile({ id, size = 'md' }: TileProps) {
+  return <i data-id={id} data-size={size} />;
+}
+
+export interface FlagProps {
+  /** constant `true`: boolean shorthand carries a value without an expression */
+  dense?: boolean;
+  id: string;
+}
+
+export function Flag({ dense, id }: FlagProps) {
+  return <u data-dense={dense} data-id={id} />;
+}
+
+export enum Tone {
+  Danger = 'danger',
+  Muted = 'muted',
+}
+
+const dangerTone = Tone.Danger;
+const preset = { tone: Tone.Danger } as const;
+
+export interface TagProps {
+  id: string;
+  /** constant: the same enum member written three different ways */
+  tone?: Tone;
+}
+
+export function Tag({ id, tone }: TagProps) {
+  return <em data-id={id} data-tone={tone} />;
+}
+
+export interface BlurProps {
+  id: string;
+  /** not constant: one call site computes its value, which could be anything */
+  label?: string;
+}
+
+export function Blur({ id, label }: BlurProps) {
+  return <s data-id={id}>{label}</s>;
+}
+
+function compute(): string {
+  return 'computed';
+}
+
+export interface SoloProps {
+  /** not constant: a single passing call site agrees only with itself */
+  hint?: string;
+  id: string;
+}
+
+export function Solo({ hint, id }: SoloProps) {
+  return <q data-id={id}>{hint}</q>;
+}
+
+export interface HopProps {
+  id: string;
+  /** constant `'lg'`: what reaches it is Relay's default, not `undefined` */
+  size?: string;
+}
+
+export function Hop({ id, size }: HopProps) {
+  return <mark data-id={id} data-size={size} />;
+}
+
+export interface RelayProps {
+  id: string;
+  size?: string;
+}
+
+/** Carries a default, so an omission at ITS call sites forwards `'lg'` on. */
+export function Relay({ id, size = 'lg' }: RelayProps) {
+  return <Hop id={id} size={size} />;
+}
+
+export interface DimProps {
+  id: string;
+  /** not constant: the default the omissions fall back to is computed */
+  size?: string;
+}
+
+export function Dim({ id, size }: DimProps) {
+  return <small data-id={id} data-size={size} />;
+}
+
+/** The same absorption as Relay, but a computed default has no value to give. */
+export function Vague({ id, size = compute() }: DimProps) {
+  return <Dim id={id} size={size} />;
+}
+
+export interface KeepProps {
+  id: string;
+  /** constant, but only over the passes: the default is a different value */
+  weight?: string;
+}
+
+export function Keep({ id, weight = 'bold' }: KeepProps) {
+  return <strong data-id={id} data-weight={weight} />;
+}
+
+export interface DriftProps {
+  id: string;
+  /** the same split for the other reason: the default cannot be read at all */
+  label?: string;
+}
+
+export function Drift({ id, label = compute() }: DriftProps) {
+  return <cite data-id={id}>{label}</cite>;
+}
+
+export interface GaugeProps {
+  id: string;
+  /** constant `42`: a number is read off the type, exactly as a string is */
+  span?: number;
+}
+
+export function Gauge({ id, span }: GaugeProps) {
+  return <output data-id={id} data-span={span} />;
+}
+
+export interface ToggleProps {
+  id: string;
+  /** constant `true` written out: booleans are not `isLiteral()` literals */
+  on?: boolean;
+}
+
+export function Toggle({ id, on }: ToggleProps) {
+  return <label data-id={id} data-on={on} />;
+}
+
+export interface ReqProps {
+  id: string;
+  /** required, yet fed one and the same value everywhere — the --all-props case */
+  kind: string;
+}
+
+export function Req({ id, kind }: ReqProps) {
+  return <span data-id={id} data-kind={kind} />;
+}
+
+export function ConstantApp() {
+  return (
+    <div>
+      <Chip id="c1" variant="danger" />
+      <Chip id="c2" variant="danger" />
+      <Chip id="c3" />
+      <Tile id="t1" size="md" />
+      <Tile id="t2" size="md" />
+      <Tile id="t3" />
+      <Flag dense id="f1" />
+      <Flag dense id="f2" />
+      <Tag id="enum" tone={Tone.Danger} />
+      <Tag id="alias" tone={dangerTone} />
+      <Tag id="member" tone={preset.tone} />
+      <Blur id="b1" label="fixed" />
+      <Blur id="b2" label={compute()} />
+      <Solo hint="once" id="s1" />
+      <Relay id="r1" />
+      <Relay id="r2" />
+      <Vague id="v1" />
+      <Vague id="v2" />
+      <Keep id="k1" weight="light" />
+      <Keep id="k2" weight="light" />
+      <Keep id="k3" />
+      <Drift id="d1" label="fixed" />
+      <Drift id="d2" label="fixed" />
+      <Drift id="d3" />
+      <Gauge id="g1" span={42} />
+      <Gauge id="g2" span={42} />
+      <Toggle id="tg1" on={true} />
+      <Toggle id="tg2" on={true} />
+      <Req id="q1" kind="primary" />
+      <Req id="q2" kind="primary" />
+    </div>
+  );
+}
diff --git a/packages/prop-flow/package.json b/packages/prop-flow/package.json
index 7464a976..b43591a7 100644
--- a/packages/prop-flow/package.json
+++ b/packages/prop-flow/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@fxone/prop-flow",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "trace an optional prop across every JSX call site and tell whether its `?` is justified",
   "keywords": [
     "typescript",
diff --git a/packages/prop-flow/src/analyzer.test.ts b/packages/prop-flow/src/analyzer.test.ts
index 30aaa9ba..f61c5eb2 100644
--- a/packages/prop-flow/src/analyzer.test.ts
+++ b/packages/prop-flow/src/analyzer.test.ts
@@ -4,7 +4,7 @@ import { beforeAll, describe, expect, it } from 'vitest';
 import { createAnalyzer, verdictOf } from './analyzer.js';
 import type { Analyzer } from './analyzer.js';
 import { readTsConfig } from './tsconfig.js';
-import type { PropAnalysis, Site, Verdict } from './types.js';
+import type { ConstantValue, PropAnalysis, Site, Verdict } from './types.js';
 
 const FIXTURE_DIR = resolve(import.meta.dirname, '../fixtures/basic');
 
@@ -237,9 +237,9 @@ describe('createAnalyzer', () => {
     // out anywhere, and `id` becomes optional only through the mapping.
     const mapped = analyzer.findComponents(sourceFile('sources.tsx')).find(({ name }) => name === 'Mapped');
 
-    expect(mapped && analyzer.listOptionalProps(mapped)).toEqual([
-      { hasDefault: false, name: 'id' },
-      { hasDefault: false, name: 'note' },
+    expect(mapped && analyzer.listProps(mapped)).toEqual([
+      { hasDefault: false, name: 'id', optional: true },
+      { hasDefault: false, name: 'note', optional: true },
     ]);
   });
 
@@ -263,20 +263,92 @@ describe('createAnalyzer', () => {
     expect(analyzer.findComponents(sourceFile('app.tsx'))).toEqual([]);
 
     const [button] = analyzer.findComponents(sourceFile('button.tsx'));
-    expect(button && analyzer.listOptionalProps(button)).toEqual([
-      { hasDefault: false, name: 'disabled' },
-      { hasDefault: false, name: 'icon' },
-      { hasDefault: true, name: 'size' },
-      { hasDefault: false, name: 'title' },
+    expect(button && analyzer.listProps(button)).toEqual([
+      { hasDefault: false, name: 'disabled', optional: true },
+      { hasDefault: false, name: 'icon', optional: true },
+      { hasDefault: true, name: 'size', optional: true },
+      { hasDefault: false, name: 'title', optional: true },
     ]);
   });
 
+  it('adds the props declared without a `?` only when asked to', () => {
+    const [button] = analyzer.findComponents(sourceFile('button.tsx'));
+
+    expect(button && analyzer.listProps(button, { includeRequired: true })[0]).toEqual({
+      hasDefault: false,
+      name: 'label',
+      optional: false,
+    });
+  });
+
   it('skips optional props that are inherited from a dependency', () => {
     // VendoredProps extends an interface from node_modules: `hidden` and
     // `lang` are not the author's to drop, and they drown the ones that are.
     const [vendored] = analyzer.findComponents(sourceFile('vendored.tsx'));
 
-    expect(vendored && analyzer.listOptionalProps(vendored)).toEqual([{ hasDefault: false, name: 'caption' }]);
+    expect(vendored && analyzer.listProps(vendored)).toEqual([{ hasDefault: false, name: 'caption', optional: true }]);
+  });
+});
+
+describe('constant values', () => {
+  it.each<[string, string, ConstantValue | null]>([
+    // Two passes agree, one call site omits it: the `?` is justified and the
+    // value is still redundant.
+    ['Chip', 'variant', { coverage: 'passes', value: '"danger"' }],
+    // Same shape, but the binding default equals the value, so the omissions
+    // land on it too — nothing anywhere sees anything else.
+    ['Tile', 'size', { coverage: 'all', value: '"md"' }],
+    ['Flag', 'dense', { coverage: 'all', value: 'true' }],
+    // Written out, through a `const` alias and off an `as const` object: the
+    // checker normalises all three to the one enum member.
+    ['Tag', 'tone', { coverage: 'all', value: 'Tone.Danger' }],
+    ['Blur', 'label', null],
+    ['Solo', 'hint', null],
+    ['Hop', 'size', { coverage: 'all', value: '"lg"' }],
+    ['Dim', 'size', null],
+    // A default the omissions land on, but not on what the passes send — so
+    // the claim stops at the passes. `Drift` splits the same way for the other
+    // reason: its default is a call, which cannot be shown to agree with
+    // anything.
+    ['Keep', 'weight', { coverage: 'passes', value: '"light"' }],
+    ['Drift', 'label', { coverage: 'passes', value: '"fixed"' }],
+    // Read off the type rather than the syntax: a number, and a boolean, which
+    // is a union of two literal types and so not an `isLiteral()` literal.
+    ['Gauge', 'span', { coverage: 'all', value: '42' }],
+    ['Toggle', 'on', { coverage: 'all', value: 'true' }],
+  ])('constant.tsx: %s.%s → %j', (component, prop, constant) => {
+    expect(analyse('constant.tsx', component, prop).constant).toEqual(constant);
+  });
+
+  it('leaves a claim unmade where a single site cannot be read', () => {
+    // Every MANUAL site could be feeding any value at all, so one of them is
+    // enough to sink the claim even where every readable site agrees.
+    expect(analyse('spread.tsx', 'Murky', 'note').constant).toBeNull();
+  });
+
+  it('absorbs an intermediate default instead of counting it as an omission', () => {
+    // <Relay/> is rendered twice without `size`, but Relay defaults it to 'lg'
+    // and forwards that on — so what reaches Hop is 'lg', not `undefined`.
+    const result = analyse('constant.tsx', 'Hop', 'size');
+
+    expect(result).toMatchObject({ ambiguous: 0, omit: 0, real: 2, verdict: 'unnecessary-optional' });
+    // The two absorbed omissions get a line each, at the <Relay/> that omits
+    // them — `passes=2` under a single pass-through line would read as a
+    // miscount, and those locations are where the default actually fires.
+    expect(result.sites.map(({ kind, note }) => `${kind} ${note ?? ''}`.trim())).toEqual([
+      'passthrough omissions fall back to its default',
+      'real the default fires here',
+      'real the default fires here',
+    ]);
+    expect(result.sites.every(({ via }) => via === 'Relay.size')).toBe(true);
+  });
+
+  it('absorbs a default it cannot read without inventing a value for it', () => {
+    // Vague defaults `size` to a call. The omissions are still passes — the
+    // counts move — but what they pass is unknown, so no constant survives.
+    const result = analyse('constant.tsx', 'Dim', 'size');
+
+    expect(result).toMatchObject({ ambiguous: 0, constant: null, omit: 0, real: 2 });
   });
 });
 
diff --git a/packages/prop-flow/src/analyzer.ts b/packages/prop-flow/src/analyzer.ts
index 9ebbc246..766cc45f 100644
--- a/packages/prop-flow/src/analyzer.ts
+++ b/packages/prop-flow/src/analyzer.ts
@@ -1,11 +1,20 @@
 import type * as TS from 'typescript';
-import { defaultedBindingNames, isExported, unwrapToFn } from './ast.js';
+import { defaultedBindings, isExported, unwrapToFn } from './ast.js';
 import { createClassifier } from './classify.js';
 import { createComponentFactory } from './component.js';
 import type { Component } from './component.js';
 import { locOf } from './paths.js';
-import type { OptionalProp, PropAnalysis, Site, Verdict } from './types.js';
+import type { ConstantValue, DeclaredProp, PropAnalysis, Site, Verdict } from './types.js';
 import type { TypeScriptApi } from './typescript-api.js';
+import { createUsageIndex } from './usage-index.js';
+import { literalValueOf } from './values.js';
+
+/**
+ * Below this, "always the same value" is trivially true: one passing call site
+ * agrees with itself, and reporting that would fire on every single-use
+ * component.
+ */
+const MIN_CONSTANT_SITES = 2;
 
 export interface AnalyzerOptions {
   /** Paths in the output are printed relative to this directory. */
@@ -18,8 +27,31 @@ export interface AnalyzerOptions {
 interface Contribution {
   readonly ambiguous: number;
   readonly omit: number;
+  /** A value that could not be read as a literal — no constancy is claimable. */
+  readonly poisoned: boolean;
+  readonly real: number;
+  /** One line per call site, except where absorbing a default splits it up. */
+  readonly sites: readonly Site[];
+  readonly values: readonly string[];
+}
+
+/** The counters a single call site can move — it always moves exactly one. */
+type Counts = Partial<Pick<Contribution, 'ambiguous' | 'omit' | 'real'>>;
+
+/** The raw accumulation of a walk, before `constant` is derived from it. */
+interface Walk {
+  readonly ambiguous: number;
+  readonly omit: number;
+  readonly poisoned: boolean;
   readonly real: number;
-  readonly site: Site;
+  readonly sites: readonly Site[];
+  readonly values: ReadonlySet<string>;
+  readonly verdict: Verdict;
+}
+
+export interface ListPropsOptions {
+  /** Also list props declared without a `?` — the `--all-props` mode. */
+  readonly includeRequired?: boolean;
 }
 
 export interface Analyzer {
@@ -27,97 +59,140 @@ export interface Analyzer {
   analyse(component: Component, propName: string): PropAnalysis;
   /** Components exported from `sourceFile` that take a props parameter. */
   findComponents(sourceFile: TS.SourceFile): Component[];
-  listOptionalProps(component: Component): OptionalProp[];
+  listProps(component: Component, options?: ListPropsOptions): DeclaredProp[];
 }
 
 export function createAnalyzer({ cwd, program, ts }: AnalyzerOptions): Analyzer {
   const checker = program.getTypeChecker();
   const components = createComponentFactory({ checker, ts });
   const classifier = createClassifier({ checker, components, ts });
+  const index = createUsageIndex({ checker, components, program, ts });
 
-  // Symbol identity. Symbols are not primitives, so a Map keyed by symbol
-  // works — but the index is keyed by a plain id to keep it printable.
-  const symbolIds = new WeakMap<TS.Symbol, number>();
-  let nextSymbolId = 1;
+  // Binding defaults per component, read once: the walk asks for them at every
+  // pass-through, and again when it decides a constant's coverage.
+  const defaultsById = new Map<number, Map<string, TS.Expression>>();
 
-  // Every JSX usage in the Program, indexed once: component symbol → call
-  // sites, plus the symbols that are CALLED rather than rendered. Building
-  // this eagerly costs one walk and saves one per prop.
-  const { calledIds, usageIndex } = indexProgram();
-
-  return { analyse, findComponents, listOptionalProps };
+  return { analyse, findComponents, listProps };
 
   // ── core analysis ─────────────────────────────────────────────────────────
 
-  function analyse(component: Component, propName: string, visited = new Set<string>()): PropAnalysis {
-    const key = `${symbolId(component.symbol)}#${propName}`;
+  function analyse(component: Component, propName: string): PropAnalysis {
+    const result = walk(component, propName, new Set<string>());
+    return {
+      ambiguous: result.ambiguous,
+      constant: constantOf(component, propName, result),
+      omit: result.omit,
+      real: result.real,
+      sites: result.sites,
+      verdict: result.verdict,
+    };
+  }
+
+  /** Every call site of `component`, merged into counts, sites and values. */
+  function walk(component: Component, propName: string, visited: Set<string>): Walk {
+    const key = `${index.symbolId(component.symbol)}#${propName}`;
     if (visited.has(key)) {
       // A cycle in the pass-through graph. The first visit already counted
       // this subtree, so the repeat contributes nothing.
-      return { ambiguous: 0, omit: 0, real: 0, sites: [], verdict: 'cycle' };
+      return { ambiguous: 0, omit: 0, poisoned: false, real: 0, sites: [], values: new Set(), verdict: 'cycle' };
     }
     visited.add(key);
 
-    const usages = usageIndex.get(symbolId(component.symbol)) ?? [];
-    const sites: Site[] = [];
-    let real = 0;
-    let omit = 0;
-    let ambiguous = 0;
-
-    for (const el of usages) {
-      const contribution = contributionOf(el, propName, visited);
-      real += contribution.real;
-      omit += contribution.omit;
-      ambiguous += contribution.ambiguous;
-      sites.push(contribution.site);
-    }
+    const usages = index.usagesOf(component.symbol);
+    const merged = merge(usages.map((el) => contributionOf(el, propName, visited)));
 
-    return { ambiguous, omit, real, sites, verdict: verdictOf(usages.length, real, omit, ambiguous) };
+    return { ...merged, verdict: verdictOf(usages.length, merged.real, merged.omit, merged.ambiguous) };
   }
 
   /** Classify one call site, expanding a pass-through into what it bottoms out in. */
   function contributionOf(el: TS.JsxOpeningLikeElement, propName: string, visited: Set<string>): Contribution {
     const classified = classifier.classifyElement(el, propName);
+    const loc = locOf(el, cwd);
     if (classified.kind === 'real') {
-      return { ambiguous: 0, omit: 0, real: 1, site: { kind: 'real', loc: locOf(el, cwd), note: classified.note } };
+      return leaf({ real: 1 }, { kind: 'real', loc, note: classified.note }, classified.value);
     }
     if (classified.kind === 'omit') {
-      return { ambiguous: 0, omit: 1, real: 0, site: { kind: 'omit', loc: locOf(el, cwd), note: classified.note } };
+      return leaf({ omit: 1 }, { kind: 'omit', loc, note: classified.note });
     }
     if (classified.kind === 'manual') {
-      return { ambiguous: 1, omit: 0, real: 0, site: { kind: 'manual', loc: locOf(el, cwd), note: classified.note } };
+      return leaf({ ambiguous: 1 }, { kind: 'manual', loc, note: classified.note });
     }
 
     // The value is the enclosing component's own prop — climb.
-    const sub = analyse(classified.component, classified.prop, visited);
-    if (sub.verdict === 'unused-component' && calledIds.has(symbolId(classified.component.symbol))) {
+    const sub = walk(classified.component, classified.prop, visited);
+    if (sub.verdict === 'unused-component' && index.isCalled(classified.component.symbol)) {
       // The climb landed on a plain function taking an options object — a test
       // helper, say. It has callers, they just are not JSX, so the walk cannot
       // see them. Counting the empty subtree would turn an invisible pass into
       // a caller-dead: "delete the prop" on live code.
+      const note = `${classified.component.name}.${classified.prop}: called, never rendered as JSX`;
+      return leaf({ ambiguous: 1 }, { kind: 'manual', loc, note });
+    }
+    return absorbDefault(el, classified.component, classified.prop, sub);
+  }
+
+  /**
+   * An omission one level up does not reach this call site as `undefined` when
+   * the level above binds a default: `Relay({ size = 'lg' })` forwarding
+   * `size` passes `'lg'`. So those omissions are converted into passes of the
+   * default here — anything else reports a prop that is in fact always set as
+   * `caller-dead`, and hands constancy the wrong value.
+   */
+  function absorbDefault(el: TS.JsxOpeningLikeElement, via: Component, viaProp: string, sub: Walk): Contribution {
+    const loc = locOf(el, cwd);
+    const trace = `${via.name}.${viaProp}`;
+    const fallback = defaultsOf(via).get(viaProp);
+    if (sub.omit === 0 || fallback === undefined) {
+      // No omission for the default to catch, or no default to catch it.
       return {
-        ambiguous: 1,
-        omit: 0,
-        real: 0,
-        site: {
-          kind: 'manual',
-          loc: locOf(el, cwd),
-          note: `${classified.component.name}.${classified.prop}: called, never rendered as JSX`,
-        },
+        ambiguous: sub.ambiguous,
+        omit: sub.omit,
+        poisoned: sub.poisoned,
+        real: sub.real,
+        sites: [{ kind: 'passthrough', loc, via: trace }],
+        values: [...sub.values],
       };
     }
+
+    const value = literalValueOf(checker, ts, fallback);
+    // Point at the omissions that just turned into passes: a lone pass-through
+    // line above `passes=2` reads like a miscount. Only the omissions written
+    // at this level are visible — ones arriving through a deeper pass-through
+    // stay behind their own line, as every expanded count already does.
+    const absorbed = sub.sites
+      .filter((site) => site.kind === 'omit')
+      .map((site): Site => ({ kind: 'real', loc: site.loc, note: 'the default fires here', via: trace }));
     return {
       ambiguous: sub.ambiguous,
-      omit: sub.omit,
-      real: sub.real,
-      site: {
-        kind: 'passthrough',
-        loc: locOf(el, cwd),
-        via: `${classified.component.name}.${classified.prop}`,
-      },
+      omit: 0,
+      poisoned: sub.poisoned || value === null,
+      real: sub.real + sub.omit,
+      sites: [{ kind: 'passthrough', loc, note: 'omissions fall back to its default', via: trace }, ...absorbed],
+      values: value === null ? [...sub.values] : [...sub.values, value],
     };
   }
 
+  /** The one value every readable call site agreed on, if there is one. */
+  function constantOf(component: Component, propName: string, result: Walk): ConstantValue | null {
+    if (result.ambiguous > 0 || result.poisoned || result.real < MIN_CONSTANT_SITES) {
+      return null;
+    }
+    const [value] = result.values;
+    if (value === undefined || result.values.size > 1) {
+      return null;
+    }
+    return { coverage: coverageOf(component, propName, result.omit, value), value };
+  }
+
+  /** Whether the omissions land on the value too — via the binding default. */
+  function coverageOf(component: Component, propName: string, omit: number, value: string): ConstantValue['coverage'] {
+    if (omit === 0) {
+      return 'all';
+    }
+    const fallback = defaultsOf(component).get(propName);
+    return fallback && literalValueOf(checker, ts, fallback) === value ? 'all' : 'passes';
+  }
+
   // ── component + prop discovery ────────────────────────────────────────────
 
   function findComponents(sourceFile: TS.SourceFile): Component[] {
@@ -151,18 +226,30 @@ export function createAnalyzer({ cwd, program, ts }: AnalyzerOptions): Analyzer
     return fn ? components.fromNode(fn, decl.name) : null;
   }
 
-  function listOptionalProps(component: Component): OptionalProp[] {
+  function listProps(component: Component, { includeRequired = false }: ListPropsOptions = {}): DeclaredProp[] {
     const type = checker.getTypeAtLocation(component.paramNode);
-    const defaults = defaultedBindingNames(ts, component.paramNode);
-    const out: OptionalProp[] = [];
+    const defaults = defaultsOf(component);
+    const out: DeclaredProp[] = [];
     for (const sym of type.getProperties()) {
-      if ((sym.getFlags() & ts.SymbolFlags.Optional) !== 0 && !isVendored(sym)) {
-        out.push({ hasDefault: defaults.has(sym.getName()), name: sym.getName() });
+      const optional = (sym.getFlags() & ts.SymbolFlags.Optional) !== 0;
+      if ((optional || includeRequired) && !isVendored(sym)) {
+        out.push({ optional, hasDefault: defaults.has(sym.getName()), name: sym.getName() });
       }
     }
     return out;
   }
 
+  function defaultsOf(component: Component): Map<string, TS.Expression> {
+    const id = index.symbolId(component.symbol);
+    const known = defaultsById.get(id);
+    if (known) {
+      return known;
+    }
+    const defaults = defaultedBindings(ts, component.paramNode);
+    defaultsById.set(id, defaults);
+    return defaults;
+  }
+
   /**
    * Whether the prop is declared only in a dependency. A component spreading
    * `React.ComponentProps<'button'>` inherits some 250 optional DOM and ARIA
@@ -176,54 +263,39 @@ export function createAnalyzer({ cwd, program, ts }: AnalyzerOptions): Analyzer
       declarations.every((declaration) => program.isSourceFileFromExternalLibrary(declaration.getSourceFile()))
     );
   }
+}
 
-  // ── JSX usage index ───────────────────────────────────────────────────────
-
-  function indexProgram(): { calledIds: Set<number>; usageIndex: Map<number, TS.JsxOpeningLikeElement[]> } {
-    const calledIds = new Set<number>();
-    const usageIndex = new Map<number, TS.JsxOpeningLikeElement[]>();
-    const visit = (node: TS.Node): void => {
-      if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
-        const sym = jsxTagSymbol(node.tagName);
-        if (sym) {
-          const id = symbolId(sym);
-          const list = usageIndex.get(id) ?? [];
-          list.push(node);
-          usageIndex.set(id, list);
-        }
-      } else if (ts.isCallExpression(node)) {
-        const sym = checker.getSymbolAtLocation(node.expression);
-        if (sym) {
-          calledIds.add(symbolId(components.resolveAlias(sym)));
-        }
-      }
-      ts.forEachChild(node, visit);
-    };
-
-    for (const sourceFile of program.getSourceFiles()) {
-      // Declarations and dependencies hold no call site this analysis owns.
-      if (!sourceFile.isDeclarationFile && !sourceFile.fileName.includes('/node_modules/')) {
-        visit(sourceFile);
-      }
-    }
-    return { calledIds, usageIndex };
-  }
+/**
+ * A call site that bottoms out here: it moves one counter and contributes one
+ * report line. Only a `real` site carries a value, and only a `real` one can
+ * poison the constancy claim — a `manual` site already suppresses it through
+ * `ambiguous`, and an omission has no value to be unreadable in the first place.
+ */
+function leaf(counts: Counts, site: Site, value: string | null = null): Contribution {
+  return {
+    ambiguous: counts.ambiguous ?? 0,
+    omit: counts.omit ?? 0,
+    poisoned: site.kind === 'real' && value === null,
+    real: counts.real ?? 0,
+    sites: [site],
+    values: value === null ? [] : [value],
+  };
+}
 
-  function jsxTagSymbol(tagName: TS.JsxTagNameExpression): TS.Symbol | null {
-    // Intrinsics (<div/>) have no symbol; <Ns.Foo/> resolves on the property.
-    const sym = checker.getSymbolAtLocation(tagName);
-    return sym ? components.resolveAlias(sym) : null;
-  }
+/** Fold every call site's contribution into the walk's totals. */
+function merge(contributions: readonly Contribution[]): Omit<Walk, 'verdict'> {
+  return {
+    ambiguous: total(contributions, 'ambiguous'),
+    omit: total(contributions, 'omit'),
+    poisoned: contributions.some((contribution) => contribution.poisoned),
+    real: total(contributions, 'real'),
+    sites: contributions.flatMap((contribution) => contribution.sites),
+    values: new Set(contributions.flatMap((contribution) => contribution.values)),
+  };
+}
 
-  function symbolId(sym: TS.Symbol): number {
-    let id = symbolIds.get(sym);
-    if (id === undefined) {
-      id = nextSymbolId;
-      nextSymbolId += 1;
-      symbolIds.set(sym, id);
-    }
-    return id;
-  }
+function total(contributions: readonly Contribution[], counter: keyof Counts): number {
+  return contributions.reduce((sum, contribution) => sum + contribution[counter], 0);
 }
 
 export function verdictOf(usageCount: number, real: number, omit: number, ambiguous: number): Verdict {
diff --git a/packages/prop-flow/src/args.test.ts b/packages/prop-flow/src/args.test.ts
index e92eace2..4b03f61a 100644
--- a/packages/prop-flow/src/args.test.ts
+++ b/packages/prop-flow/src/args.test.ts
@@ -5,13 +5,17 @@ import { PropFlowError } from './errors.js';
 describe('parseArgs', () => {
   it('reads the file, the prop and the flags in any order', () => {
     expect(parseArgs(['src/Button.tsx'])).toEqual({
+      allProps: false,
       file: 'src/Button.tsx',
       help: false,
       json: false,
       prop: null,
       tsconfig: null,
     });
-    expect(parseArgs(['--json', 'src/Button.tsx', '--tsconfig', 'tsconfig.base.json', 'title'])).toEqual({
+    expect(
+      parseArgs(['--json', 'src/Button.tsx', '--all-props', '--tsconfig', 'tsconfig.base.json', 'title']),
+    ).toEqual({
+      allProps: true,
       file: 'src/Button.tsx',
       help: false,
       json: true,
@@ -28,6 +32,14 @@ describe('parseArgs', () => {
     expect(parseArgs([])).toMatchObject({ help: false, file: null });
   });
 
+  it('skips a hole in argv rather than reading it as a positional', () => {
+    // `parseArgs` is exported, so the argv is not always `process.argv.slice(2)`
+    // — a gap must be stepped over, not shifted into the [propName] slot.
+    const argv = ['src/Button.tsx', undefined, 'title'] as unknown as string[];
+
+    expect(parseArgs(argv)).toMatchObject({ file: 'src/Button.tsx', prop: 'title' });
+  });
+
   it.each([
     [['--tsconfig'], /--tsconfig needs a path/],
     [['--tsconfig', '--json'], /--tsconfig needs a path/],
diff --git a/packages/prop-flow/src/args.ts b/packages/prop-flow/src/args.ts
index 4e2b75d3..75fd3693 100644
--- a/packages/prop-flow/src/args.ts
+++ b/packages/prop-flow/src/args.ts
@@ -1,6 +1,7 @@
 import { PropFlowError } from './errors.js';
 
 export interface CliArgs {
+  readonly allProps: boolean;
   readonly help: boolean;
   readonly json: boolean;
   readonly tsconfig: string | null;
@@ -10,6 +11,7 @@ export interface CliArgs {
 
 export function parseArgs(argv: readonly string[]): CliArgs {
   const positional: string[] = [];
+  let allProps = false;
   let help = false;
   let json = false;
   let tsconfig: string | null = null;
@@ -19,7 +21,9 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     if (arg === undefined) {
       continue;
     }
-    if (arg === '--json') {
+    if (arg === '--all-props') {
+      allProps = true;
+    } else if (arg === '--json') {
       json = true;
     } else if (arg === '-h' || arg === '--help') {
       help = true;
@@ -41,5 +45,5 @@ export function parseArgs(argv: readonly string[]): CliArgs {
     throw new PropFlowError(`Unexpected argument: ${positional[2] ?? ''}`);
   }
 
-  return { help, json, tsconfig, file: positional[0] ?? null, prop: positional[1] ?? null };
+  return { allProps, help, json, tsconfig, file: positional[0] ?? null, prop: positional[1] ?? null };
 }
diff --git a/packages/prop-flow/src/ast.test.ts b/packages/prop-flow/src/ast.test.ts
index 071c3fc0..3f7b721c 100644
--- a/packages/prop-flow/src/ast.test.ts
+++ b/packages/prop-flow/src/ast.test.ts
@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import {
   bindingKey,
   bindingNameOfFn,
-  defaultedBindingNames,
+  defaultedBindings,
   findAttr,
   isComponentFn,
   isExported,
@@ -92,21 +92,29 @@ describe('unwrapToFn', () => {
   });
 });
 
-describe('defaultedBindingNames', () => {
+describe('defaultedBindings', () => {
+  /** The props keys collected, in declaration order. */
+  function keysOf(code: string): string[] {
+    return [...defaultedBindings(ts, firstParameter(code)).keys()];
+  }
+
   it('collects the props keys whose binding carries a default', () => {
-    expect([...defaultedBindingNames(ts, firstParameter('function C({ a = 1, b, c: d = 2, e: f }: P) {}'))]).toEqual([
-      'a',
-      'c',
-    ]);
+    expect(keysOf('function C({ a = 1, b, c: d = 2, e: f }: P) {}')).toEqual(['a', 'c']);
+  });
+
+  it('maps each key to the default expression, not just to the fact of one', () => {
+    const defaults = defaultedBindings(ts, firstParameter('function C({ size = "md" }: P) {}'));
+
+    expect(defaults.get('size')?.getText()).toBe('"md"');
   });
 
   it('has nothing to collect for a whole-object parameter', () => {
-    expect([...defaultedBindingNames(ts, firstParameter('function C(props: P) {}'))]).toEqual([]);
+    expect(keysOf('function C(props: P) {}')).toEqual([]);
   });
 
   it('skips a defaulted binding whose props key cannot be read', () => {
     // A computed key over a nested pattern: neither half names a props key.
-    expect([...defaultedBindingNames(ts, firstParameter('function C({ [k]: { x } = {} }: P) {}'))]).toEqual([]);
+    expect(keysOf('function C({ [k]: { x } = {} }: P) {}')).toEqual([]);
   });
 });
 
diff --git a/packages/prop-flow/src/ast.ts b/packages/prop-flow/src/ast.ts
index 21d9246d..8d0a9948 100644
--- a/packages/prop-flow/src/ast.ts
+++ b/packages/prop-flow/src/ast.ts
@@ -35,15 +35,23 @@ export function unwrapToFn(ts: TypeScriptApi, expr: TS.Expression): ComponentFn
   return null;
 }
 
-/** Names in `function C({ foo = 1 }: P)` that carry a default initializer. */
-export function defaultedBindingNames(ts: TypeScriptApi, paramNode: TS.ParameterDeclaration): Set<string> {
+/**
+ * Props keys in `function C({ foo = 1 }: P)` that carry a default, mapped to
+ * the default itself. The expression, not just the fact of it: a default is a
+ * value the component feeds itself whenever a caller omits the prop.
+ */
+export function defaultedBindings(ts: TypeScriptApi, paramNode: TS.ParameterDeclaration): Map<string, TS.Expression> {
+  const out = new Map<string, TS.Expression>();
   if (!ts.isObjectBindingPattern(paramNode.name)) {
-    return new Set();
+    return out;
+  }
+  for (const element of paramNode.name.elements) {
+    const key = bindingKey(ts, element);
+    if (element.initializer !== undefined && key !== null) {
+      out.set(key, element.initializer);
+    }
   }
-  const keys = paramNode.name.elements
-    .filter((element) => element.initializer !== undefined)
-    .map((element) => bindingKey(ts, element));
-  return new Set(keys.filter((key) => key !== null));
+  return out;
 }
 
 /** The props key a binding element reads: `{ label: text }` → `label`. */
diff --git a/packages/prop-flow/src/classify.ts b/packages/prop-flow/src/classify.ts
index 485e96df..3ebdb7e2 100644
--- a/packages/prop-flow/src/classify.ts
+++ b/packages/prop-flow/src/classify.ts
@@ -2,6 +2,7 @@ import type * as TS from 'typescript';
 import { bindingKey, findAttr, isComponentFn } from './ast.js';
 import type { Component, ComponentFactory } from './component.js';
 import type { TypeScriptApi } from './typescript-api.js';
+import { BOOLEAN_SHORTHAND_VALUE, literalValueOf } from './values.js';
 
 /** The value is the enclosing component's own prop — climb one level up. */
 interface Passthrough {
@@ -26,6 +27,8 @@ interface Omission {
 interface Real {
   readonly kind: 'real';
   readonly note: string;
+  /** What the value is, printably — null when it is not a single literal. */
+  readonly value: string | null;
 }
 
 /** Where the value a JSX element feeds to one prop comes from. */
@@ -206,10 +209,10 @@ export function createClassifier({ checker, components, ts }: ClassifierOptions)
     const init = attr.initializer;
     // Shorthand boolean: <C flag /> → always a concrete `true`.
     if (init === undefined) {
-      return { kind: 'real', note: 'boolean shorthand' };
+      return { kind: 'real', note: 'boolean shorthand', value: BOOLEAN_SHORTHAND_VALUE };
     }
     if (ts.isStringLiteral(init)) {
-      return { kind: 'real', note: 'string literal' };
+      return realValue(init, 'string literal');
     }
     if (!ts.isJsxExpression(init) || init.expression === undefined) {
       return { kind: 'manual', note: 'unrecognised attribute form' };
@@ -220,26 +223,31 @@ export function createClassifier({ checker, components, ts }: ClassifierOptions)
   /** Where the value an expression evaluates to originates. */
   function classifyExpression(expr: TS.Expression): Classification {
     if (ts.isStringLiteral(expr)) {
-      return { kind: 'real', note: 'string literal' };
+      return realValue(expr, 'string literal');
     }
-    // `prop={undefined}` is an omission dressed up as a pass.
-    if (ts.isIdentifier(expr) && expr.text === 'undefined') {
-      return { kind: 'omit', note: 'explicit undefined' };
-    }
-    // Identifier — a destructured prop of the enclosing component (climb) or a
-    // local value (a real source).
     if (ts.isIdentifier(expr)) {
-      return asDestructuredProp(expr) ?? { kind: 'real', note: 'local value' };
+      // `prop={undefined}` is an omission dressed up as a pass.
+      if (expr.text === 'undefined') {
+        return { kind: 'omit', note: 'explicit undefined' };
+      }
+      // Otherwise a destructured prop of the enclosing component (climb), or a
+      // local value (a real source).
+      return asDestructuredProp(expr) ?? realValue(expr, 'local value');
     }
     // `props.foo` — climb when `props` is the enclosing props parameter.
     if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression)) {
-      return asMemberProp(expr.expression, expr.name.text) ?? { kind: 'real', note: 'member value' };
+      return asMemberProp(expr.expression, expr.name.text) ?? realValue(expr, 'member value');
     }
     // Any other expression (call, object, conditional, JSX, template…) — the
     // value is produced right here. Treat as a real source; a conditional that
     // can yield undefined is the one false positive we accept (conservative:
     // counts as "present").
-    return { kind: 'real', note: ts.SyntaxKind[expr.kind] };
+    return realValue(expr, ts.SyntaxKind[expr.kind]);
+  }
+
+  /** A value written at this call site; `note` says which shape it took. */
+  function realValue(expr: TS.Expression, note: string): Real {
+    return { kind: 'real', note, value: literalValueOf(checker, ts, expr) };
   }
 
   /** `<C prop={text}/>` where `text` is destructured from the props parameter. */
diff --git a/packages/prop-flow/src/cli.test.ts b/packages/prop-flow/src/cli.test.ts
index 427df87f..83ba88d9 100644
--- a/packages/prop-flow/src/cli.test.ts
+++ b/packages/prop-flow/src/cli.test.ts
@@ -3,6 +3,8 @@ import ts from 'typescript';
 import { describe, expect, it } from 'vitest';
 import { runCli } from './cli.js';
 import type { CliContext, OutputStream } from './cli.js';
+import type { Report } from './types.js';
+import type { TypeScriptApi } from './typescript-api.js';
 
 const FIXTURE_DIR = resolve(import.meta.dirname, '../fixtures/basic');
 
@@ -45,6 +47,28 @@ describe('runCli', () => {
     });
   });
 
+  it('reaches required props with --all-props', () => {
+    const { code, stdout } = run(['--all-props', 'constant.tsx', 'kind']);
+
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/required\s+Req\.kind/);
+    expect(stdout).toContain('constant="primary"  coverage=all');
+  });
+
+  it('carries the constant value into --json, null where there is none', () => {
+    const { code, stdout } = run(['--json', 'constant.tsx', 'size']);
+    const report = JSON.parse(stdout) as Report;
+
+    expect(code).toBe(0);
+    expect(report.props.map((row) => [`${row.component}.${row.prop}`, row.constant])).toEqual([
+      ['Tile.size', { coverage: 'all', value: '"md"' }],
+      ['Hop.size', { coverage: 'all', value: '"lg"' }],
+      ['Relay.size', null],
+      ['Dim.size', null],
+      ['Vague.size', null],
+    ]);
+  });
+
   it('prints usage on --help and exits 0', () => {
     const { code, stdout } = run(['--help']);
 
@@ -69,4 +93,23 @@ describe('runCli', () => {
     expect(stdout).toBe('');
     expect(stderr).toContain(message);
   });
+
+  it('lets an unexpected failure through instead of dressing it as exit 2', () => {
+    // Only PropFlowError means "handled". Anything else is a bug in prop-flow
+    // or in the compiler, and swallowing it into a one-line message would hide
+    // the stack that says so.
+    const stdout = new Capture();
+    const stderr = new Capture();
+    const broken = {
+      ...ts,
+      createProgram: () => {
+        throw new TypeError('the compiler exploded');
+      },
+    } as unknown as TypeScriptApi;
+
+    expect(() => runCli(['button.tsx'], { cwd: FIXTURE_DIR, stderr, stdout, ts: broken })).toThrow(
+      'the compiler exploded',
+    );
+    expect(stderr.text).toBe('');
+  });
 });
diff --git a/packages/prop-flow/src/cli.ts b/packages/prop-flow/src/cli.ts
index 1bf1c13c..bdc7f84b 100644
--- a/packages/prop-flow/src/cli.ts
+++ b/packages/prop-flow/src/cli.ts
@@ -17,15 +17,18 @@ export interface CliContext {
 }
 
 export const USAGE =
-  'Usage: prop-flow <file> [propName] [--tsconfig <path>] [--json]\n\n' +
-  '  <file>      a .ts/.tsx file containing the component(s) to inspect\n' +
-  '  [propName]  one prop; omitted → every optional prop of every component\n' +
-  '              exported from the file\n' +
-  '  --tsconfig  override the auto-discovered tsconfig (use the broadest\n' +
-  '              "solution" config so call sites in other packages are seen)\n' +
-  '  --json      machine-readable output\n\n' +
+  'Usage: prop-flow <file> [propName] [--tsconfig <path>] [--all-props] [--json]\n\n' +
+  '  <file>       a .ts/.tsx file containing the component(s) to inspect\n' +
+  '  [propName]   one prop; omitted → every optional prop of every component\n' +
+  '               exported from the file\n' +
+  '  --tsconfig   override the auto-discovered tsconfig (use the broadest\n' +
+  '               "solution" config so call sites in other packages are seen)\n' +
+  '  --all-props  inspect required props too, reported only where they are\n' +
+  '               passed the same value at every call site\n' +
+  '  --json       machine-readable output\n\n' +
   'Trace an optional prop up every JSX call site and report whether its\n' +
-  '`?` is justified, needless, or the prop is never passed (caller-dead).\n';
+  '`?` is justified, needless, or the prop is never passed (caller-dead),\n' +
+  'plus whether every call site sends it one and the same value.\n';
 
 /** Exit codes: 0 ok, 1 nothing to do (usage printed), 2 a handled failure. */
 export function runCli(argv: readonly string[], context: CliContext): number {
@@ -36,6 +39,7 @@ export function runCli(argv: readonly string[], context: CliContext): number {
       return args.help ? 0 : 1;
     }
     const report = analyseProps({
+      allProps: args.allProps,
       cwd: context.cwd,
       file: args.file,
       prop: args.prop,
diff --git a/packages/prop-flow/src/index.ts b/packages/prop-flow/src/index.ts
index 714bf54a..57c19483 100644
--- a/packages/prop-flow/src/index.ts
+++ b/packages/prop-flow/src/index.ts
@@ -1,5 +1,5 @@
 export { createAnalyzer, verdictOf } from './analyzer.js';
-export type { Analyzer, AnalyzerOptions } from './analyzer.js';
+export type { Analyzer, AnalyzerOptions, ListPropsOptions } from './analyzer.js';
 export { parseArgs } from './args.js';
 export type { CliArgs } from './args.js';
 export { runCli, USAGE } from './cli.js';
@@ -10,6 +10,15 @@ export { analyseProps } from './prop-flow.js';
 export type { AnalyseOptions } from './prop-flow.js';
 export { formatJson, formatText } from './report.js';
 export { discoverTsconfig, readTsConfig } from './tsconfig.js';
-export type { OptionalProp, PropAnalysis, PropReport, Report, Site, SiteKind, Verdict } from './types.js';
+export type {
+  ConstantValue,
+  DeclaredProp,
+  PropAnalysis,
+  PropReport,
+  Report,
+  Site,
+  SiteKind,
+  Verdict,
+} from './types.js';
 export { loadTypeScript } from './typescript-api.js';
 export type { TypeScriptApi } from './typescript-api.js';
diff --git a/packages/prop-flow/src/prop-flow.test.ts b/packages/prop-flow/src/prop-flow.test.ts
index 0a6a0cee..e3590dcf 100644
--- a/packages/prop-flow/src/prop-flow.test.ts
+++ b/packages/prop-flow/src/prop-flow.test.ts
@@ -1,4 +1,4 @@
-import { resolve } from 'node:path';
+import { relative, resolve } from 'node:path';
 import ts from 'typescript';
 import { describe, expect, it } from 'vitest';
 import { PropFlowError } from './errors.js';
@@ -36,6 +36,37 @@ describe('analyseProps', () => {
     expect(report.props[0]).toMatchObject({ hasDefault: true, prop: 'size', verdict: 'unnecessary-optional' });
   });
 
+  it('reports required props only under allProps, and only where constant', () => {
+    const plain = analyse('constant.tsx');
+    const all = analyseProps({ allProps: true, cwd: FIXTURE_DIR, file: 'constant.tsx', ts });
+
+    expect(verdicts(plain)).not.toHaveProperty('Req.kind');
+    expect(verdicts(all)['Req.kind']).toBe('required');
+    // Every other required prop is an `id`, and no two call sites send the same
+    // one — so widening discovery adds exactly the one finding, not a listing.
+    expect(Object.keys(verdicts(all))).toEqual([...Object.keys(verdicts(plain)), 'Req.kind']);
+  });
+
+  it('widens the wording of the not-found error under allProps', () => {
+    // Without the flag the message can promise the prop is not an *optional*
+    // one; with it, required props were searched too and that promise is gone.
+    expect(() => analyseProps({ allProps: true, cwd: FIXTURE_DIR, file: 'button.tsx', prop: 'nope', ts })).toThrow(
+      /'nope' is not a prop of any component exported from button\.tsx/,
+    );
+  });
+
+  it('falls back to process.cwd() and to the project TypeScript when given neither', () => {
+    // What `bin.ts` actually does — it passes no `cwd` and no `ts` — so these
+    // two defaults are the production path, and every other test steps over
+    // them by injecting both.
+    const file = relative(process.cwd(), resolve(FIXTURE_DIR, 'card.tsx'));
+
+    const report = analyseProps({ file });
+
+    expect(report.file).toContain('fixtures/basic/card.tsx');
+    expect(verdicts(report)).toEqual({ 'Card.action': 'justified' });
+  });
+
   it('accepts an explicit tsconfig and an absolute file path', () => {
     const report = analyseProps({
       ts,
diff --git a/packages/prop-flow/src/prop-flow.ts b/packages/prop-flow/src/prop-flow.ts
index f504cac3..025195e4 100644
--- a/packages/prop-flow/src/prop-flow.ts
+++ b/packages/prop-flow/src/prop-flow.ts
@@ -10,6 +10,11 @@ import { loadTypeScript } from './typescript-api.js';
 import type { TypeScriptApi } from './typescript-api.js';
 
 export interface AnalyseOptions {
+  /**
+   * Also inspect required props. They are reported only when they carry a
+   * constant value — there is no `?` on them to pass a verdict on.
+   */
+  readonly allProps?: boolean;
   /** Root for path resolution and for shortening printed paths. */
   readonly cwd?: string;
   /** A .ts/.tsx file containing the component(s) to inspect. */
@@ -27,7 +32,8 @@ export interface AnalyseOptions {
 
 /**
  * Trace every optional prop of every component exported from `file` up the
- * JSX call sites across the whole Program.
+ * JSX call sites across the whole Program. With `allProps`, required props
+ * join in — but only where they turn out to carry a constant value.
  */
 export function analyseProps(options: AnalyseOptions): Report {
   const cwd = options.cwd ?? process.cwd();
@@ -58,25 +64,35 @@ export function analyseProps(options: AnalyseOptions): Report {
     throw new PropFlowError(`No exported component with a typed props object found in ${relativeTo(cwd, file)}.`);
   }
 
+  const allProps = options.allProps ?? false;
   const propName = options.prop ?? null;
   const props: PropReport[] = [];
+  let matched = 0;
   for (const component of components) {
-    const optional = analyzer.listOptionalProps(component);
-    const selected = propName === null ? optional : optional.filter((prop) => prop.name === propName);
+    const declared = analyzer.listProps(component, { includeRequired: allProps });
+    const selected = propName === null ? declared : declared.filter((prop) => prop.name === propName);
     for (const prop of selected) {
+      matched += 1;
+      const analysis = analyzer.analyse(component, prop.name);
+      // A prop with no `?` has nothing for the verdicts to say: `justified` and
+      // `caller-dead` are impossible on it and `unnecessary-optional` is a lie.
+      // Its constant value is the whole reason it is here — no value, no row.
+      if (!prop.optional && analysis.constant === null) {
+        continue;
+      }
       props.push({
-        ...analyzer.analyse(component, prop.name),
+        ...analysis,
         component: component.name,
         hasDefault: prop.hasDefault,
         prop: prop.name,
+        verdict: prop.optional ? analysis.verdict : 'required',
       });
     }
   }
 
-  if (propName !== null && props.length === 0) {
-    throw new PropFlowError(
-      `'${propName}' is not an optional prop of any component exported from ${relativeTo(cwd, file)}.`,
-    );
+  if (propName !== null && matched === 0) {
+    const scope = allProps ? 'a prop' : 'an optional prop';
+    throw new PropFlowError(`'${propName}' is not ${scope} of any component exported from ${relativeTo(cwd, file)}.`);
   }
 
   return {
diff --git a/packages/prop-flow/src/report.test.ts b/packages/prop-flow/src/report.test.ts
index 6f2998c7..95616d97 100644
--- a/packages/prop-flow/src/report.test.ts
+++ b/packages/prop-flow/src/report.test.ts
@@ -1,11 +1,12 @@
 import { describe, expect, it } from 'vitest';
-import { formatJson, formatText, hint } from './report.js';
+import { constantHint, formatJson, formatText, hint } from './report.js';
 import type { PropReport, Report, Verdict } from './types.js';
 
 function makeRow(overrides: Partial<PropReport> = {}): PropReport {
   return {
     ambiguous: 0,
     component: 'Button',
+    constant: null,
     hasDefault: false,
     omit: 1,
     prop: 'title',
@@ -69,8 +70,42 @@ describe('formatText', () => {
     `);
   });
 
-  it('says so when a component has no optional props at all', () => {
-    expect(formatText(makeReport({ props: [] }))).toContain('No optional props found.');
+  it('prints the constant value and names the absorbed pass-through', () => {
+    const report = makeReport({
+      props: [
+        makeRow({
+          constant: { coverage: 'all', value: '"lg"' },
+          omit: 0,
+          prop: 'size',
+          real: 2,
+          sites: [
+            {
+              kind: 'passthrough',
+              loc: 'src/relay.tsx:4:5',
+              note: 'omissions fall back to its default',
+              via: 'Relay.size',
+            },
+          ],
+          verdict: 'unnecessary-optional',
+        }),
+        makeRow({
+          component: 'Req',
+          constant: { coverage: 'passes', value: '"primary"' },
+          prop: 'kind',
+          verdict: 'required',
+        }),
+      ],
+    });
+
+    expect(formatText(report)).toContain('   constant="lg"  coverage=all\n');
+    expect(formatText(report)).toContain(' → Relay.size (omissions fall back to its default)\n');
+    expect(formatText(report)).toContain('every call site sees "lg"');
+    expect(formatText(report)).toMatch(/^required\s+Req\.kind$/m);
+    expect(formatText(report)).toContain('every passing call site sends "primary"');
+  });
+
+  it('says so when a component has nothing to report', () => {
+    expect(formatText(makeReport({ props: [] }))).toContain('No props to report.');
   });
 });
 
@@ -84,11 +119,24 @@ describe('hint', () => {
     ['manual', false, 'Check the MANUAL sites'],
     ['unused-component', false, 'no call sites in this Program'],
     ['cycle', false, ''],
+    // A required row's advice is the constancy hint; the verdict adds nothing.
+    ['required', false, ''],
   ])('%s (hasDefault=%s) advises %s', (verdict, hasDefault, expected) => {
     expect(hint(makeRow({ hasDefault, verdict }))).toContain(expected);
   });
 });
 
+describe('constantHint', () => {
+  it('stays at "could be inlined" — a constant value is not a defect', () => {
+    expect(constantHint(makeRow({ constant: { coverage: 'passes', value: '"sm"' } }))).toContain('could be inlined');
+    expect(constantHint(makeRow({ constant: { coverage: 'all', value: '"sm"' } }))).toContain('the prop dropped');
+  });
+
+  it('has nothing to say without a constant', () => {
+    expect(constantHint(makeRow())).toBe('');
+  });
+});
+
 describe('formatJson', () => {
   it('round-trips the report and ends with a newline', () => {
     const report = makeReport();
diff --git a/packages/prop-flow/src/report.ts b/packages/prop-flow/src/report.ts
index 8de0ff6f..940b2b01 100644
--- a/packages/prop-flow/src/report.ts
+++ b/packages/prop-flow/src/report.ts
@@ -1,4 +1,4 @@
-import type { PropReport, Report, Verdict } from './types.js';
+import type { PropReport, Report, Site, Verdict } from './types.js';
 
 // Keyed by the full Verdict union, so a new verdict is a compile error here
 // rather than a raw slug leaking into the output.
@@ -7,11 +7,14 @@ const LABELS: Record<Verdict, string> = {
   'cycle': 'CYCLE',
   'justified': 'justified',
   'manual': 'MANUAL',
+  'required': 'required',
   'unnecessary-optional': 'NEEDLESS ?',
   'unused-component': 'UNUSED COMPONENT',
 };
 
 const LABEL_WIDTH = 16;
+/** Widest `SiteKind`, so the locations of one row line up under each other. */
+const SITE_KIND_WIDTH = 11;
 
 export function formatJson(report: Report): string {
   return `${JSON.stringify(report, null, 2)}\n`;
@@ -21,29 +24,28 @@ export function formatText(report: Report): string {
   const head =
     `tsconfig: ${report.configPath}  (${report.fileCount} files in Program)\n` + `file:     ${report.file}\n\n`;
   if (report.props.length === 0) {
-    return `${head}No optional props found.\n`;
+    return `${head}No props to report.\n`;
   }
   return head + report.props.map(formatRow).join('');
 }
 
 function formatRow(row: PropReport): string {
   const suffix = row.hasDefault ? ' [has default]' : '';
-  const lines = [
+  return [
     `${LABELS[row.verdict].padEnd(LABEL_WIDTH)}  ${row.component}.${row.prop}${suffix}\n`,
     `   passes=${row.real}  omits=${row.omit}  ambiguous=${row.ambiguous}\n`,
-  ];
-  for (const site of row.sites) {
-    lines.push(`     ${site.kind.padEnd(11)} ${site.loc}${siteSuffix(site.note, site.via)}\n`);
-  }
-  lines.push(hint(row), '\n');
-  return lines.join('');
+    row.constant ? `   constant=${row.constant.value}  coverage=${row.constant.coverage}\n` : '',
+    ...row.sites.map(formatSite),
+    hint(row),
+    constantHint(row),
+    '\n',
+  ].join('');
 }
 
-function siteSuffix(note: string | undefined, via: string | undefined): string {
-  if (via) {
-    return ` → ${via}`;
-  }
-  return note ? ` (${note})` : '';
+function formatSite(site: Site): string {
+  const trace = site.via ? ` → ${site.via}` : '';
+  const evidence = site.note ? `${trace} (${site.note})` : trace;
+  return `     ${site.kind.padEnd(SITE_KIND_WIDTH)} ${site.loc}${evidence}\n`;
 }
 
 export function hint(row: PropReport): string {
@@ -64,7 +66,26 @@ export function hint(row: PropReport): string {
       return '   → an unreadable spread or a contested override blocks a static verdict. Check the MANUAL sites by hand.\n';
     case 'unused-component':
       return '   → the component has no call sites in this Program. Verify the tsconfig spans its callers.\n';
+    // `required` and `cycle` have no advice of their own: what puts a required
+    // row on screen at all is its constant value, and that hint is below.
     default:
       return '';
   }
 }
+
+/**
+ * Constant does not mean wrong — `variant="danger"` on the two delete buttons
+ * is constant and correct. So the wording stops at "could be inlined".
+ */
+export function constantHint(row: PropReport): string {
+  if (!row.constant) {
+    return '';
+  }
+  const { coverage, value } = row.constant;
+  // `sees` rather than `sends`: under `all` even a call site that omits the
+  // prop ends up on the value, because the component's own default is it.
+  if (coverage === 'all') {
+    return `   → every call site sees ${value}; the value could be inlined and the prop dropped.\n`;
+  }
+  return `   → every passing call site sends ${value}; the value could be inlined.\n`;
+}
diff --git a/packages/prop-flow/src/types.ts b/packages/prop-flow/src/types.ts
index 0fd8eb1d..ecc9eb2f 100644
--- a/packages/prop-flow/src/types.ts
+++ b/packages/prop-flow/src/types.ts
@@ -10,8 +10,11 @@
  *                        human to check
  *   cycle                the pass-through graph looped back on itself; the
  *                        repeat visit contributes no new information
+ *   required             the prop has no `?` to judge — listed only because it
+ *                        carries a constant value (`--all-props`)
  */
-export type Verdict = 'caller-dead' | 'cycle' | 'justified' | 'manual' | 'unnecessary-optional' | 'unused-component';
+export type Verdict =
+  'caller-dead' | 'cycle' | 'justified' | 'manual' | 'required' | 'unnecessary-optional' | 'unused-component';
 
 export type SiteKind = 'manual' | 'omit' | 'passthrough' | 'real';
 
@@ -19,15 +22,34 @@ export type SiteKind = 'manual' | 'omit' | 'passthrough' | 'real';
 export interface Site {
   readonly kind: SiteKind;
   readonly loc: string;
-  /** Why it was classified this way — `real`, `omit` and `manual` sites only. */
+  /** Why it was classified this way; a `passthrough` carries one only rarely. */
   readonly note?: string;
-  /** `Component.prop` the value was traced to — `passthrough` sites only. */
+  /**
+   * `Component.prop` the value was traced through. A `passthrough` always
+   * carries one; so does a `real` site whose value is a default that fired one
+   * level up, which is where the trace says *whose* default it was.
+   */
   readonly via?: string;
 }
 
+/**
+ * The same value at every call site the walk could read. Orthogonal to
+ * `Verdict`: a `justified` prop can be constant too, and that combination —
+ * the `?` is correct, yet the prop carries no information — is the most
+ * interesting finding of all.
+ */
+export interface ConstantValue {
+  /** `all` — omissions land on the value too; `passes` — passing sites only. */
+  readonly coverage: 'all' | 'passes';
+  /** Printed as the checker prints it: `"sm"`, `true`, `42`, `Tone.Danger`. */
+  readonly value: string;
+}
+
 /** Counts are of ULTIMATE leaves: pass-throughs are expanded, not counted. */
 export interface PropAnalysis {
   readonly ambiguous: number;
+  /** null unless at least two passing sites agree and none is unreadable. */
+  readonly constant: ConstantValue | null;
   readonly omit: number;
   readonly real: number;
   readonly sites: readonly Site[];
@@ -50,8 +72,11 @@ export interface Report {
   readonly props: readonly PropReport[];
 }
 
-export interface OptionalProp {
+/** One prop a component declares, as the analysis sees it before walking. */
+export interface DeclaredProp {
   /** The binding carries a default: `function C({ size = 'md' }: Props)`. */
   readonly hasDefault: boolean;
   readonly name: string;
+  /** Declared with a `?`. Required props are listed only under `--all-props`. */
+  readonly optional: boolean;
 }
diff --git a/packages/prop-flow/src/usage-index.test.ts b/packages/prop-flow/src/usage-index.test.ts
new file mode 100644
index 00000000..942eb2cb
--- /dev/null
+++ b/packages/prop-flow/src/usage-index.test.ts
@@ -0,0 +1,113 @@
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { createComponentFactory } from './component.js';
+import type { ComponentFactory } from './component.js';
+import { readTsConfig } from './tsconfig.js';
+import { createUsageIndex } from './usage-index.js';
+import type { UsageIndex } from './usage-index.js';
+
+const FIXTURE_DIR = resolve(import.meta.dirname, '../fixtures/basic');
+
+let program: ts.Program;
+let checker: ts.TypeChecker;
+let components: ComponentFactory;
+let index: UsageIndex;
+
+beforeAll(() => {
+  // One Program for the whole file — building it is by far the slowest part.
+  const parsed = readTsConfig(ts, resolve(FIXTURE_DIR, 'tsconfig.json'));
+  program = ts.createProgram({ options: parsed.options, rootNames: parsed.fileNames });
+  checker = program.getTypeChecker();
+  components = createComponentFactory({ checker, ts });
+  index = createUsageIndex({ checker, components, program, ts });
+});
+
+function sourceFile(file: string): ts.SourceFile {
+  const found = program.getSourceFile(resolve(FIXTURE_DIR, file));
+  if (!found) {
+    throw new Error(`fixture ${file} is not part of the Program`);
+  }
+  return found;
+}
+
+/** The identifiers one top-level statement binds a value to. */
+function declaredNames(stmt: ts.Statement): ts.Identifier[] {
+  if (ts.isFunctionDeclaration(stmt)) {
+    return stmt.name ? [stmt.name] : [];
+  }
+  if (ts.isVariableStatement(stmt)) {
+    return stmt.declarationList.declarations.map(({ name }) => name).filter(ts.isIdentifier);
+  }
+  return [];
+}
+
+/**
+ * The symbol behind a top-level declaration — exported or not, which is what
+ * the analyzer's own `findComponents` cannot reach and `renderMurky` needs.
+ */
+function symbolOf(file: string, name: string): ts.Symbol {
+  const id = sourceFile(file)
+    .statements.flatMap(declaredNames)
+    .find((node) => node.text === name);
+  const symbol = id && checker.getSymbolAtLocation(id);
+  if (!symbol) {
+    throw new Error(`no top-level ${name} declared in ${file}`);
+  }
+  return components.resolveAlias(symbol);
+}
+
+/** `tag@line`, the compact form of a call site this index hands back. */
+function describeUsage(el: ts.JsxOpeningLikeElement): string {
+  const { line } = el.getSourceFile().getLineAndCharacterOfPosition(el.getStart());
+  return `${el.tagName.getText()}@${line + 1}`;
+}
+
+describe('createUsageIndex', () => {
+  it('collects every JSX call site of a component and nothing else', () => {
+    // Nine <Leaf/> in spread.tsx: one per forwarding component, one inside each
+    // render callback, one dead one in Unrendered, and the spread in SpreadApp.
+    // Intrinsics carry no symbol, so the <ul>/<b>/<div> around them are absent.
+    expect(index.usagesOf(symbolOf('spread.tsx', 'Leaf')).map(describeUsage)).toEqual([
+      'Leaf@44',
+      'Leaf@49',
+      'Leaf@54',
+      'Leaf@59',
+      'Leaf@64',
+      'Leaf@70',
+      'Leaf@80',
+      'Leaf@85',
+      'Leaf@121',
+    ]);
+  });
+
+  it('files a usage under the declaration, not under the name it was rendered as', () => {
+    // `export { Aliased as Public }`, rendered as <Public/> in app.tsx. Without
+    // alias resolution this would be a second entry nothing ever asks about,
+    // and Aliased would look like it had no call sites at all.
+    expect(index.usagesOf(symbolOf('late.tsx', 'Aliased')).map(describeUsage)).toEqual(['Public@27']);
+  });
+
+  it('reports no usages for a component the Program never renders', () => {
+    expect(index.usagesOf(symbolOf('legacy.tsx', 'Legacy'))).toEqual([]);
+  });
+
+  it('separates being called from being rendered', () => {
+    // The distinction the walk needs: `renderMurky` has live callers no JSX
+    // site can show, so its empty usage list must not read as dead code —
+    // whereas Leaf, rendered nine times and called never, genuinely is not.
+    expect(index.isCalled(symbolOf('spread.tsx', 'renderMurky'))).toBe(true);
+    expect(index.usagesOf(symbolOf('spread.tsx', 'renderMurky'))).toEqual([]);
+    expect(index.isCalled(symbolOf('spread.tsx', 'Leaf'))).toBe(false);
+  });
+
+  it('hands out one stable id per symbol', () => {
+    const leaf = symbolOf('spread.tsx', 'Leaf');
+
+    expect(index.symbolId(leaf)).toBe(index.symbolId(leaf));
+    expect(index.symbolId(leaf)).not.toBe(index.symbolId(symbolOf('spread.tsx', 'Murky')));
+    // Never rendered and never called, so the walk meets it only through the
+    // caches keyed on this id — which still has to be an id.
+    expect(index.symbolId(symbolOf('legacy.tsx', 'Legacy'))).toEqual(expect.any(Number));
+  });
+});
diff --git a/packages/prop-flow/src/usage-index.ts b/packages/prop-flow/src/usage-index.ts
new file mode 100644
index 00000000..e6559606
--- /dev/null
+++ b/packages/prop-flow/src/usage-index.ts
@@ -0,0 +1,99 @@
+import type * as TS from 'typescript';
+import type { ComponentFactory } from './component.js';
+import type { TypeScriptApi } from './typescript-api.js';
+
+export interface UsageIndexOptions {
+  readonly checker: TS.TypeChecker;
+  readonly components: ComponentFactory;
+  readonly program: TS.Program;
+  readonly ts: TypeScriptApi;
+}
+
+export interface UsageIndex {
+  /**
+   * Whether `sym` is ever called as a plain function. Such a symbol has live
+   * callers this index cannot see, so an empty `usagesOf` does not mean dead.
+   */
+  isCalled(sym: TS.Symbol): boolean;
+  /**
+   * A stable number for `sym`. Symbols are objects, so a Map would key on them
+   * directly — the id exists because it is printable, which the caches and the
+   * cycle guard built on top of it both want.
+   */
+  symbolId(sym: TS.Symbol): number;
+  /** Every JSX element rendering `sym`, in Program order. */
+  usagesOf(sym: TS.Symbol): readonly TS.JsxOpeningLikeElement[];
+}
+
+/**
+ * Every JSX usage in the Program, indexed in one walk: component symbol → call
+ * sites, plus the symbols that are CALLED rather than rendered. Building this
+ * eagerly costs one traversal and saves one per prop analysed.
+ *
+ * Import aliases are resolved on the way in, so `<Public/>` and the `Aliased`
+ * it was exported as land on the same entry.
+ */
+export function createUsageIndex({ checker, components, program, ts }: UsageIndexOptions): UsageIndex {
+  // Symbols are not primitives, so a WeakMap keyed by symbol is the identity
+  // map; the id it hands out is what everything downstream keys on.
+  const symbolIds = new WeakMap<TS.Symbol, number>();
+  let nextSymbolId = 1;
+
+  const calledIds = new Set<number>();
+  const usagesById = new Map<number, TS.JsxOpeningLikeElement[]>();
+
+  for (const sourceFile of program.getSourceFiles()) {
+    // Declarations and dependencies hold no call site this analysis owns.
+    if (!sourceFile.isDeclarationFile && !sourceFile.fileName.includes('/node_modules/')) {
+      visit(sourceFile);
+    }
+  }
+
+  return { isCalled, symbolId, usagesOf };
+
+  function isCalled(sym: TS.Symbol): boolean {
+    return calledIds.has(symbolId(sym));
+  }
+
+  function usagesOf(sym: TS.Symbol): readonly TS.JsxOpeningLikeElement[] {
+    return usagesById.get(symbolId(sym)) ?? [];
+  }
+
+  function symbolId(sym: TS.Symbol): number {
+    let id = symbolIds.get(sym);
+    if (id === undefined) {
+      id = nextSymbolId;
+      nextSymbolId += 1;
+      symbolIds.set(sym, id);
+    }
+    return id;
+  }
+
+  function visit(node: TS.Node): void {
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      recordUsage(node);
+    } else if (ts.isCallExpression(node)) {
+      recordCall(node);
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  function recordUsage(node: TS.JsxOpeningLikeElement): void {
+    // Intrinsics (<div/>) have no symbol; <Ns.Foo/> resolves on the property.
+    const sym = checker.getSymbolAtLocation(node.tagName);
+    if (!sym) {
+      return;
+    }
+    const id = symbolId(components.resolveAlias(sym));
+    const list = usagesById.get(id) ?? [];
+    list.push(node);
+    usagesById.set(id, list);
+  }
+
+  function recordCall(node: TS.CallExpression): void {
+    const sym = checker.getSymbolAtLocation(node.expression);
+    if (sym) {
+      calledIds.add(symbolId(components.resolveAlias(sym)));
+    }
+  }
+}
diff --git a/packages/prop-flow/src/values.ts b/packages/prop-flow/src/values.ts
new file mode 100644
index 00000000..ed3a9f3a
--- /dev/null
+++ b/packages/prop-flow/src/values.ts
@@ -0,0 +1,30 @@
+import type * as TS from 'typescript';
+import type { TypeScriptApi } from './typescript-api.js';
+
+/** `<C flag />` carries no expression to read; the value is always `true`. */
+export const BOOLEAN_SHORTHAND_VALUE = 'true';
+
+/**
+ * The value `expr` resolves to, printed as the checker prints it (`"sm"`,
+ * `true`, `42`, `Tone.Danger`), or null when it is not a single literal.
+ *
+ * Going through the type rather than the syntax is what makes `const SIZE =
+ * 'sm'`, an enum member and a property of an `as const` object all normalise to
+ * the same string as a written-out `size="sm"` — and what keeps everything
+ * else (a call, a parameter, a widened `let`) honestly unknown.
+ */
+export function literalValueOf(checker: TS.TypeChecker, ts: TypeScriptApi, expr: TS.Expression): string | null {
+  // A written-out string literal is read from the node instead: as a JSX
+  // attribute initializer (`size="md"`) it sits outside an expression position,
+  // where the checker has no type to hand back.
+  if (ts.isStringLiteral(expr)) {
+    return JSON.stringify(expr.text);
+  }
+  const type = checker.getTypeAtLocation(expr);
+  // `isLiteral` covers string, number and enum literals; booleans are a union
+  // of two literal types of their own and need the flag.
+  if (type.isLiteral() || (type.flags & ts.TypeFlags.BooleanLiteral) !== 0) {
+    return checker.typeToString(type);
+  }
+  return null;
+}