Dependency-graph selective remap (opt-in, conservative, multi-framework — React first)

[BenSheridanEdwards]

Part of #57. Revisits the rejected core of proposals #2/#3 (see spike #59) — but as a deliberate, opt-in, multi-framework capability, not a default that weakens the gate.

Goal

Speed up the pre-push capture by re-capturing only the surfaces a change can affect, and reusing the committed base maps for the rest — without ever silently missing a regression. Build a dependency graph that, given the changed files in a commit, returns the set of surfaces whose rendered output could have changed (or all). Support the major frameworks; start with React (the hardest).

The hard constraint (why this is subtle, not a quick win)

In the committed-map model, a wrong answer is silent and fatal: if the graph says a surface is unaffected and it actually changed, its stale committed map matches the base, the diff is empty, and the regression ships green. So the graph must over-approximate — when in doubt, re-capture. It is only sound if:

• Any non-page-local style change forces all — a CSS reset, a :root/theme token, a global stylesheet, a CSS-in-JS global, a Tailwind/theme config change, a design-system primitive. These cascade everywhere.
• The component→surface graph is complete for anything it claims is unaffected — including dynamic import(), React.lazy, context/providers, render props, children, and component registries/CMS-driven composition. A missed edge = a missed regression.
• Runtime theming / data-driven styling that isn't visible in the static graph is treated conservatively.

For most PRs (which touch shared CSS/tokens) the sound answer is often all, so the realistic win is on changes provably scoped to a single surface's own component + styles.

Proposed shape

• Opt-in, default off. The full-coverage gate stays the default and the source of truth.
• Pluggable framework adapters. A small interface affectedSurfaces(changedFiles, surfaces) → Set<key> | 'all'; ship a React/TS adapter first (lean on an existing module-graph tool — dependency-cruiser/madge — rather than reinventing it), then others.
• Conservative core, framework-agnostic. The "global change → all" classifier and the committed-map plumbing (capture subset, reuse committed base for the rest) live in core; only the import-graph resolution is per-framework.
• Trust-but-verify safety net. main (or a scheduled run) always captures all surfaces, so any graph hole is caught at the latest on merge, not hidden forever. Document that a PR-time miss can still slip to merge — the residual risk the adopter accepts.
• Loud about what it skipped. Log every surface it chose not to re-capture and why, so a reviewer can sanity-check.

Open questions to resolve in the spike

1. Can "is this style change global?" be classified soundly across CSS Modules / styled-components / Tailwind / vanilla / CSS-in-JS? If not reliably, the conservative default is all on any CSS/config change — does that leave enough win?
2. How complete can a static React graph be against dynamic composition, and how do we fail closed (→ all) when resolution is uncertain?
3. Does the trust-but-verify-on-main safety net make PR-time selection an acceptable risk, or is consumer-declared mapping (the maintainer asserts completeness) the only honest opt-in?
4. Per-framework adapter API + which existing graph tool to build on.

Acceptance

A design (and a React/TS proof-of-concept) that is opt-in, conservative (fails to all), framework-pluggable, and loud about skips, with the trust-but-verify net — or a documented decision that selective remap stays consumer-declared. The default gate must remain 100%-sound regardless.

Context: as of 3.0.0 the gate ships full coverage — every surface captured, changes determined by measuring the map (the map is the oracle), not by guessing. This issue is the path to making it faster on large apps without giving that up.

[BenSheridanEdwards]

Status after #98: keep this open as a design spike only, not an implementation ticket yet. The default gate must remain full-coverage and sound. Any PR from this issue needs to prove it fails closed to all, is opt-in, logs skipped surfaces loudly, and cannot certify an unmeasured surface green. Until that design/POC exists, the shipped guidance is the safe one from #98: whole-workflow path filters for non-rendered changes, never per-surface changed-file skipping by default.

[BenSheridanEdwards]

Spinning out Q4 (which graph tool to build on) as a scoped spike: #155 — evaluates GitNexus (already indexing this repo) as the affected-surfaces engine, with the fail-closed/soundness bar as the gate. It resolves to one of: (a) sound + shippable → build the React adapter on it; (b) sound but dev-only → prove the model, ship on a lean graph (dependency-cruiser/madge); (c) no static graph is sound enough → selective remap stays consumer-declared. Default full-coverage gate stays the source of truth either way.

[BenSheridanEdwards]

PoC done on #155 — decision: (b). GitNexus is a good validation harness but not the shipped engine. Two hard findings from a real React fixture: (1) CSS is invisible to GitNexus (every stylesheet is an orphan File node with only a folder CONTAINS edge — no Header.tsx → Header.css import), so the CSS-ownership resolver and the "global → all" classifier are StyleProof-owned regardless; (2) the symbol-level call graph false-negatives on React.lazy (impact(Promo) → 0 impacted, silently drops the surface — fatal in the committed-map model), while the file-level import graph got it right (conf 1.0). So #75's adapter should be built on a lean file-level module graph (dependency-cruiser/madge), file-level not symbol-level, plus the CSS classifier + fail-closed-to-all. Full evidence table on #155.

[BenSheridanEdwards]

Follow-on spike #157 — built affectedSurfaces() on dependency-cruiser as real code (6/6 sound cases + fail-closed on unbounded dynamic imports). Highlights that decide the design:

• dependency-cruiser closes both GitNexus gaps: it captures the CSS import edge and resolves string-literal lazy(() => import()). CSS-ownership comes free.
• The ceiling is dynamic composition, not the tool. A single context import (import(`../dir/${x}`)) soundly forces every file in that dir to count as a dependency → precision collapses to directory granularity there, and to all for unbounded specifiers. The win survives only for statically-reachable code outside context-glob dirs. (This is your Q2.)
• Dangerous silence: dependency-cruiser reports computed imports as couldNotResolve: 0 with no warning — fail-closed must come from an independent source scan, not the tool.
• Decision: green-light an opt-in, default-off, file-level (not symbol-level) adapter — gated on the global-CSS classifier (your Q1), which is the unsolved weak link: it must be provably sound or itself fail to all. If it can't be, fallback is "any CSS/config change → all" and the win shrinks to JS/TS changes.

Full evidence + the ~90-line PoC rationale on #157.

[BenSheridanEdwards]

Classifier spike done on #157 (resolves the gate). Comparison sound classifier vs blunt "any CSS → all" fallback across all major styling systems: sound = 10/10 exact, 10/10 sound, 3 selective; blunt = 9/10 sound (UNSOUND on createGlobalStyle in a .tsx), 2 selective.

• The blunt fallback isn't safe: CSS-in-JS globals live in .tsx and slip through as "local". So the createGlobalStyle/injectGlobal scan is mandatory, not optional.
• The sound classifier strictly dominates — safer and keeps CSS-Module edits selective — at trivial cost. Ship it, not the fallback.
• Honest limiter: vanilla global CSS → all (unscoped). CSS-side win is structural — it lives in CSS-Modules / CSS-in-JS codebases.

All three Q's now have answers: Q1 (global classifier) = sound classifier per #157; Q2 (dynamic composition) = directory-bounded via context-glob / all; Q4 (graph tool) = dependency-cruiser, file-level, not GitNexus (#155). Remaining before a PR: enumerate CSS-in-JS global APIs (vanilla-extract/Linaria) + carry composes/@use edges, else those → all.

[BenSheridanEdwards]

Landed the sound reasoning core as a PR: #158 — affectedSurfaces + classifyStyleChange, opt-in, zero new deps, sound-by-construction (fails closed to all), never touches the default gate. 25 new tests, proved end-to-end on a real dependency-cruiser graph. Implements the #155/#157 decisions (Q1/Q2/Q4). Remaining for a full selective-remap pipeline is consumer-side wiring (produce the graph, diff the changed files, reuse committed base maps) — the library now supplies the hard, must-be-sound part.