prop-flow: resolve JSX spreads instead of reporting them as manual

[fxOne]

findAttr reports any {...spread} on a JSX element as unresolvable, which turns
the whole prop into an ambiguous site and the verdict into manual.

The cost is per occurrence, not per count: a spread anywhere in a pass-through
chain suppresses the verdict for that call site and for every leaf below it,
because the climb stops there. A single unresolved spread can be the difference
between a usable verdict and manual for a prop with a dozen call sites.

For calibration, an AST count over the ui project (JSX spread attributes only):

	files	onto Component tag	onto intrinsic tag
first-party	14	7	7
shadcn (components/ui/)	25	77	22

Spreads onto intrinsic tags (<div {...props} />) carry no symbol, never enter
the usage index, and are irrelevant here. The shadcn block is vendored-but-
first-party source and mostly affects analysis of the library's internal
composition rather than application call sites. So the volume in everyday use is
modest — this change is justified by the blast radius per spread, not by how
many there are.

Most spreads are provably irrelevant for the prop under analysis, and the two
most common forms are fully resolvable with machinery that already exists.

Approach

Step 1 — exclude by type. Ask the checker whether the spread can carry the
prop at all:

const type = checker.getTypeAtLocation(spread.expression);
const sym = type.getProperty(propName);

undefined (and no index signature / any / unknown) means the spread cannot
supply this prop. Ignore the spread and fall through to the normal
present/omitted classification. Since we analyse one prop at a time and a spread
typically carries twenty others, this should resolve the majority of sites.

Step 2 — resolve what is left, in three tiers:

1. {...props} — the enclosing props parameter. asEnclosingProp already
   recognises the identifier; the result is a passthrough to
   Enclosing.<propName> (same name, no rename) and feeds the existing
   recursion including the cycle guard.
2. {...rest} — a rest element in the props destructure. TS types the rest
   binding as "props minus the destructured keys", so step 1 already does the
   right thing: a prop listed explicitly in the destructure is not in rest
   (spread irrelevant), anything else is a passthrough to
   Enclosing.<propName>. This also removes the current
   'rest element in props destructure' manual path in asEnclosingProp.
3. Object literals and as const constants — look the key up and classify the
   value expression through classifyAttrValue.

An optional property in the spread type is not a blocker for tiers 1 and 2:
whether it is ever actually fed is precisely what the climb answers.

Stays manual

• Opaque expressions ({...getProps()}): manual, whether the property is
  required or optional. The value is unknown either way, and a positive verdict
  must never be derived from an expression the analysis cannot see into — a
  real here would feed a wrong justified / unnecessary-optional.
• any / unknown / index signatures (Record<string, unknown>) — must be
  detected explicitly, otherwise getProperty returning undefined produces a
  false negative.
• Union types where only some constituents carry the prop.
• Uninstantiated generics (spread inside a generic wrapper, type stays T).

Attribute precedence bug (fold in here)

findAttr returns on the first name match and only consults sawSpread on the
not-found path. <C {...props} title="x" /> is handled correctly (last
attribute wins), but <C title="x" {...props} /> is wrong — the spread
overrides the explicit attribute and the tool still reports "x".

The fix comes with the refactor: AttrLookup changes from the 'spread'
sentinel union to something like
{ attr: JsxAttribute | null; spreadsAfter: JsxSpreadAttribute[] }, which makes
ordering explicit. Multiple spreads: the last candidate that can supply the prop
wins; if an earlier one could also supply it and any candidate is
optional-or-opaque, fall back to manual.

Acceptance criteria

• A spread whose type cannot carry the prop no longer produces an
  ambiguous site
• <C {...props} /> resolves to a passthrough and climbs
• <C {...rest} /> resolves, both for props inside and outside the
  destructure
• any / index-signature spreads stay manual
• <C title="x" {...props} /> is classified by the spread, not by the
  attribute
• README limitations section updated

[fxOne]

Technical Sketch

As of: 2026-08-02, master@d85a837
Originally created: 2026-08-02, master@d85a837

Current Plan

Affected areas:

• packages/prop-flow/src/ast.ts — findAttr / AttrLookup become ordering-aware; the module stays checker-free.
• packages/prop-flow/src/analyzer.ts — split along the classification/discovery seam; keeps the usage index, findComponents, listOptionalProps, the analyse recursion and verdictOf.
• packages/prop-flow/src/classify.ts (new) — Classification, classifyExpression, asEnclosingProp, the spread type probe and the three resolution tiers.
• packages/prop-flow/src/component.ts (new) — Component, componentFrom, componentOfFn, resolveAlias; imported by both of the above.
• packages/prop-flow/src/types.ts — SiteKind loses 'spread'.
• packages/prop-flow/fixtures/basic/ — new fixtures for the three tiers, for a multi-spread precedence case and for an opaque spread; badge.tsx and sink.tsx change verdict.
• packages/prop-flow/src/analyzer.test.ts, src/ast.test.ts — verdict table, spread expectations, direct findAttr ordering tests.
• packages/prop-flow/README.md — Limitations paragraph and the manual row of the verdict table.
• packages/prop-flow/CHANGELOG.md — entry under ## To Be Released; no version bump, the release rides with prop-flow: detect props that are always passed the same value #934.

Approach:

• Ordering-aware attribute lookup (ast.ts, syntax only). AttrLookup becomes { attr: JsxAttribute | null; spreadsAfter: JsxSpreadAttribute[] } — spreads before a matching attribute are dropped at lookup time, since JSX's last-wins rule makes them irrelevant. This alone fixes the <C title="x" {...props} /> precedence bug. findAttr needs no checker and stays where it is.

• Type probe decides relevance (checker side); opaque spreads always stay manual. For each candidate, checker.getTypeAtLocation(spread.expression).getProperty(propName) yields no / definite (present & required) / maybe (present & optional) / opaque. opaque must be detected explicitly: any, unknown, a string index signature (Record<string, unknown>) and unions that carry the prop in only some constituents all make getProperty return undefined for the wrong reason — verified against TS 6.0.3, the partial union is a confirmed false negative. Bare type parameters need no special case: getProperty resolves them through their constraint, and with no climbable expression they land on manual anyway. definite vs maybe is used only for precedence, never to manufacture a verdict out of an expression the analysis cannot see into.

• Three resolution tiers, all reusing the existing climb. (a) An identifier that is the enclosing props parameter or its rest binding → passthrough to Enclosing.<propName> (same name, no rename), feeding the existing recursion including the cycle guard; this deletes the 'rest element in props destructure' manual path, because TS types the rest binding as "props minus the destructured keys" (verified), so a destructured prop is already excluded by the probe. (b) An object literal, or a constant whose initializer is one → look the key up and classify the value expression. (c) Anything else → manual. Tier (b) is why classifyAttrValue splits into an expression-level classifyExpression: a props.x inside the object literal must get the same climb it gets in an attribute.

• Only an uncontested or definite winner produces a verdict. The last candidate that is not no wins. If it is maybe and something earlier could also supply the prop (an explicit attribute or a further spread), the site has two possible runtime outcomes and stays manual with a note naming the conflict; a definite winner overrides everything before it, so no fallback is needed. With that, 'spread' leaves SiteKind — it described a provenance, not an outcome, and every spread site now lands on passthrough / real / omit / manual with the note carrying "via spread".

• analyzer.ts splits along the classification/discovery seam. component.ts and classify.ts are checker-bound factories mirroring createAnalyzer; the dependency direction is analyzer → classify → component and stays acyclic. The alternative — a spread.ts beside analyzer.ts — was rejected: the spread logic needs checker, componentOfFn and classifyExpression, so it belongs inside classification rather than parallel to it.

Known risks / gotchas:

• The error direction flips. Today an unresolved spread over-reports (manual); afterwards a mis-probe under-reports. A union wrongly read as "cannot carry the prop" produces a false caller-dead, whose hint tells the user to delete the prop and the code reading it. Every uncertain branch must land on manual, never on omit.
• Two fixture verdicts change on purpose. badge.tsx: Badge.tone goes manual → justified, because tier (b) resolves <Badge {...badgeProps} />. sink.tsx: Sink.data goes manual → unnecessary-optional, because data={rest} passes the rest object as a value and that object always exists → real. Both are correct; both need a fixture comment so they do not read as accidental.
• The climb fans out further and is unmeasured. The walk used to stop at a spread; now it continues. The cycle guard (symbolId#prop) still terminates it, but shadcn-style components spreading ComponentProps<'button'> multiply the pass-through graph, and there is no perf baseline in the repo.
• prop-flow: detect props that are always passed the same value #934 builds on tier (b). Its literal-value extraction sits on exactly the value expressions tier (b) classifies. Keep classifyExpression the single entry point for "what is this expression worth", so prop-flow: detect props that are always passed the same value #934 extends it instead of adding a parallel walker.
• --json output changes shape (SiteKind without 'spread', notes on former spread sites). Acceptable — no consumers — but it is a real output-contract change and belongs in the CHANGELOG entry.

Open technical questions:

• None. The decisions taken in discussion are folded into the Approach above: opaque spreads stay manual regardless of required/optional (the issue body was updated to match), tier (b) is in scope, the spread site kind is dropped, and analyzer.ts is split.

Validation command (run before implementation):

git log d85a837..HEAD -- packages/prop-flow

Change History

• 2026-08-02 (d85a837): Initial version