Skip to content

feat: srcly report --dataflow, data-flow metrics and code-viewer marks - #399

Merged
byronwall merged 1 commit into
dataflow/engine-file-signalsfrom
dataflow/report-metrics
Nov 21, 2026
Merged

byronwall merged 1 commit into
dataflow/engine-file-signalsfrom
dataflow/report-metrics

Conversation

@byronwall

@byronwall byronwall commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

srcly report --dataflow now runs the TypeScript data-flow engine beside the scan. It writes dataflow.md with ranked work packets, adds a Data flow section with every finding to report.md, and adds six data-flow metrics per TS/TSX file. srcly compare --dataflow diffs those metrics, and the app colors the treemap and marks the code viewer from the last run.

What you'll see

  • srcly report --dataflow (needs Node 18+; minutes on a big app, so it is opt-in). New artifact dataflow.md (listed in the manifest, read order 4). report.md gets ## Data flow with each impossible-defense and repeated-fork finding by line, or "Not analyzed: ".
  • A new Data flow metric group: Impossible Defenses, Repeated Forks (sums), and Prop Relay, Shape Changes, Path Depth, Value Fan-Out (the worst path in the file, max over folders). A TS file outside the engine's program is N/A with the reason, never 0.
  • srcly compare --dataflow runs the engine on both sides (a commit side in a throwaway checkout) and diffs the metrics. This replaces tsx-data-flow's --baseline and --compare.
  • In the app, after a --dataflow run on the same files: color the treemap by Impossible Defenses, and the code viewer marks the line of each finding. The app never starts the tier-2 run itself.

Proof

The app on engine/examples/bad-ish-solid after srcly report --dataflow, colored by Impossible Defenses: DashboardShell.tsx is red with 12 (the explorer's "Dead?" column), the other files 0.

Treemap and explorer colored by Impossible Defenses

The code viewer's marks for that file (GET /api/files/markers) return 12 dataflow_impossible_defenses lines, one per finding.

SRCLY_ENGINE_DEV=1 srcly report --dataflow --profile frontend engine/examples/bad-ish-solid, the new report.md section (trimmed):

## Data flow

The TypeScript checker found 12 type-impossible `??`/`?.` guards and 1 repeated fork. Read `dataflow.md` for ranked work packets, candidate edits, the risk queue and the stop recommendation.

| Rule | Where | Finding |
| --- | --- | --- |
| repeated-fork | `src/Chart.tsx:37` | `Chart` tests `props.type` at 4 sibling branch sites (lines 37, 38, 45, 48). Split it into one sub-component per branch (`bar`, `line`). |
| impossible-defense | `src/DashboardShell.tsx:12` | `route.toolbar.theme ?? "light"` guards a value whose type `"light" \| "dark"` is never null or undefined, so the fallback never runs. Remove it after checking the contract. |
…

dataflow.md from the same run (start and end):

# Data flow
## Render-Path Data-Flow Work Packets
### Feature Clusters
| DashboardShell.tsx | 38    | 1     | 15        | 115           | normalize at the boundary | no provider/context signals |
| Chart.tsx          | 14    | 1     | 10        | 1             | local boundary cleanup    | no provider/context signals |
### Grouped Recommendations
**Extract bar rectangles** … | Toolbar   | bar rectangle  | 2     | h1, p  | BarRectangle[]  |
### WORK ITEM DF-001  ·  RPF-110-17
Simplify JSX row.label ?? "Untitled" in src/DashboardShell.tsx
…
### Stop Recommendation
Stop recommendation: no
Reason: 12 actionable defensive operation entries remain.

Its six sections match the archived tsx-data-flow CLI byte for byte (see #398).

srcly compare --dataflow on a copy of the example as a git repo, after removing two dead ?? from the working tree (trimmed):

| Metric | Before | After | Δ | Verdict | Files better / worse | Coverage lost / gained |
| dataflow_impossible_defenses | 12 | 10 | -2 | better | 1 / 0 | 0 / 0 |
| dataflow_relay_hops | 6 | 6 | +0 | same | 0 / 0 | 0 / 0 |
| dataflow_path_depth | 15 | 15 | +0 | same | 0 / 0 | 0 / 0 |
| dataflow_fan_out | 31 | 31 | +0 | same | 0 / 0 | 0 / 0 |

Tests: tests/test_dataflow_signals.py (overlay sums and maxes, N/A reasons, marks count equals the metric, report --dataflow writes dataflow.md and the plain report never starts the engine). scripts/check.sh passes.

Limits

  • The app shows data-flow metrics only from a CLI run on unchanged files; there is no button to start the tier-2 run from the app yet.
  • Marks are dropped for a file changed after the run (by mtime); the treemap needs the scan fingerprint to match.
  • context-relay and broad-prop-bundle are not finding rules yet; their evidence is in dataflow.md only.
  • A commit side in compare has no node_modules, so both sides use srcly's bundled TypeScript (like compare's checks).

Survey moves: server: traces +4, outcome partial +4, stops +55 (budget-exhausted +1, external-code +43, untraced +11). New Python exports in server/ (dataflow/signals.py) enter the survey's hash sample; no analysis code changed.

Stack: data-flow reporting, layer 2 of 3

This slice: report --dataflow, compare --dataflow, the six metrics, treemap and code-viewer marks.
Why it is its own layer: It is the user-visible change and touches the server, catalog and client defaults; the engine op below it stands alone.
Full story: #398

🤖 Generated with Claude Code

report --dataflow runs the engine's fileSignals op beside the scan, writes
dataflow.md (work packets) and a Data flow section in report.md, and lays
six data-flow metrics over the tree. compare --dataflow diffs them. The app
colors the treemap and marks the code viewer from the last saved result
while the files still match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@byronwall
byronwall added this pull request to stack #401 November 21, 2026 14:47
@byronwall
byronwall marked this pull request as ready for review November 21, 2026 14:52
@byronwall
byronwall merged commit f0d3384 into main Nov 21, 2026
7 checks passed
@byronwall
byronwall deleted the dataflow/report-metrics branch November 21, 2026 14:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant