Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/CODE_MAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -423,6 +423,7 @@ The tsx-data-flow analysis lives in `engine/`, a standalone Node package with it
| `/api/dataflow/*` endpoints | `server/app/routers/dataflow.py` |
| Engine `functionEffects` (M6, T14): a walk over the callable's body names each effect as a fact with a witness (families external, input, write, throw, timer, promise; activation direct, after-await, timer, latent), follows first-party callees the checker resolves (memoized, bounded, cycle-safe, aliases followed) and merges their facts behind a `via` chain, names what it cannot follow as frontiers (callback-parameter, dynamic-dispatch, unresolved-callee, recursion, budget), and says how each promise-yielding call is handled; identity from the checker, never a name; TypeScript lib intrinsics taken as pure unless named | `engine/src/analysis/effects/function-effects.ts`, `engine/src/srcly/ops/function-effects.ts`, contract `engine/src/srcly/contracts/function-effects.ts`; fixture `engine/examples/effects-basics/src/cases.ts` (21 cases) and `engine/test/srcly/function-effects.test.ts`; Python `models.py:FunctionEffectsResult` |
| Explain an edge (M4, T16): `routePath {route, source?, edge}` maps the field attachment's, frontier's or handoff bridge's `evidencePathElementIds` through the slice into ledger rows (input, transfer, transform, branch, terminal, boundary at a frontier), never inventing a step; the client selects a handoff or field edge by click and the inspector lists its steps, each opening its line | `engine/src/srcly/ops/route-path.ts`, contract `engine/src/srcly/contracts/route-path.ts`, `engine/test/srcly/route-path.test.ts`; client `DependencyCanvas.tsx` (`onSelectEdge`), `FlowView.tsx` (`selectedEdge`, `edgePath`), `FlowInspector.tsx` (`EdgeStepsView`) |
| Data-flow signals (M7): tier-2 `fileSignals` op builds the legacy render-path report once and returns per-file metrics (impossible defenses, relay hops, fan-out, shape changes, path depth), `impossible-defense` and `repeated-fork` finding spans (a defense is placed in the file on its sink's path whose text matches) and `dataflow.md` (the old CLI's work-packets, defensive-ledger, repeated-forks, prop-relay, context-relay and fan-out views, 8 items each); `srcly report --dataflow` and `srcly compare --dataflow` run it; the last result per root is saved, and the app lays the six `dataflow_*` metrics over the tree and marks the code viewer from it while the fingerprint (tree) or file mtime (marks) still match | `engine/src/srcly/ops/file-signals.ts`, `engine/src/srcly/contracts/file-signals.ts`; `server/app/services/dataflow/signals.py` (`collect`, `apply_to_tree`, `markers_for`, `latest_for_file`); `reporting.py` (`scan_tree(dataflow=)`, `render_dataflow_section`); `compare/snapshots.py` (`with_dataflow`); overlay in `scan_jobs.py:_overlay`, marks in `routers/files.py:_dataflow_markers`; catalog group `Data flow` in `metric_catalog.py` |
| Effects panel (M6, T15): Known facts by family and the places the analysis could not follow together, activation and via chain per fact, how each promise is handled, assumptions one click away, a witness row opens its line; in the code viewer's rail under the findings for the selected scope (else the function enclosing the opened line) and in the data-flow inspector for a selected box's function in anchor mode | `client/src/dataflow/EffectsPanel.tsx` (`createEffectsQuery`), pure wording in `client/src/dataflow/effectsModel.ts` (tested on the fake engine's shapes); hosts `CodeModal.tsx` → `MetricsSidebar.tsx` (`effects` slot) and `viz/deps/flow/FlowInspector.tsx` |
| Call identity (T13): the slice walk's invocation stack pairs a callee's return with the call the walk came in by (`pairInvocation`); a first-party callee is walked through its binding, never the bare `argument` link; the ops trust that pairing: a walk leaves a callee only through the call it entered by, and one that started inside it leaves through every call; an `argument` stays at its own call, and only the cross-calls the slice does not pair (callbacks, accessors) keep R7's one-call-site boundary (`facts.ts:needsOneCallSite`, `pairedInSlice`) | `engine/src/analysis/evidence-slice.ts`, `engine/src/srcly/facts.ts`, `engine/src/srcly/ops/{anchor-graph,value-flow}.ts`; fixtures `examples/value-flow-basics/src/{two-call-identity-helper,returns-other-argument}.tsx` |
| Field paths: the slice walk carries which field of a value it is after (`fields`, k-limited like the invocation stack). Backward a field read pushes its field and an object pack is entered only through that field (or a spread); forward a packed field pushes it and only a read of that field pops it. A reference, binding or return keeps the path; any other step widens it to the whole value, as does an element reached again with another path. An object literal's `fields` attribute names each property's field by its start, where its `pack-field` relation points; a store path setter's literal keys (`setStore("left", "title", v)`) pack its value field by field into the state, and past a computed key or a predicate the value is the whole field there | `engine/src/analysis/evidence-slice-fields.ts` (`stepFieldPath`), `evidence-slice.ts`, `program-evidence-collector-expression-support.ts` (`objectPackAttributes`); fixture `examples/value-flow-basics/src/field-paths.tsx` |
Expand Down
10 changes: 7 additions & 3 deletions docs/intent/tsx-dataflow-integration/initiative-map.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@
"slug": "tsx-dataflow-integration",
"scale": "program",
"current_phase": "execution",
"last_updated": "2026-11-12",
"last_updated": "2026-11-21",
"summary": "One engine (tsx-data-flow analysis moved into engine/, one lazy Node child) feeds three srcly surfaces: route -> terminal graph in the dependency viewer (headline), value-path ledger from graph destinations or code-viewer expressions (PR #102), and a function-effects panel (PR #103); findings/metrics/markers/reports follow. detailed-plan.md adds the file-level design, contracts, two-tier engine session, view-state registry and the corrections a code review of both repositories forced.",
"status": "active",
"next_action": "Only M7 remains: data-flow evidence in srcly pipelines (fileSignals, findings tool, catalog metrics, markers, work packets, skill). Nothing on main yet. Reconciled 2026-11-12 against origin/main 0bfb05ba."
"next_action": "M7 shipped in part (2026-11-21): fileSignals op, report --dataflow (dataflow.md, report.md section), six dataflow_* metrics with compare --dataflow, impossible-defense and repeated-fork findings with code-viewer marks, skill section. Left: context-relay and broad-prop-bundle finding rules, dataflow_defensive_ops, and an in-app way to start the tier-2 run (today only the CLI starts it). Retire the plan when those land or are dropped."
},
"artifacts": {
"intent_brief": {
Expand Down Expand Up @@ -647,7 +647,7 @@
"proof": "test_metric_catalog snapshots; markers count tests; report artifact test.",
"valid_intermediate_state": "Metrics N/A when engine absent.",
"rollback": "Remove dataflow tool + catalog entries.",
"status": "planned",
"status": "active",
"evidence": [],
"track": "D"
},
Expand Down Expand Up @@ -830,6 +830,10 @@
{
"date": "2026-11-12",
"change": "Set true milestone statuses from merged PRs: M1-M6 and M8 completed; M7 still planned."
},
{
"date": "2026-11-21",
"change": "M7 shipped in part: fileSignals, report/compare --dataflow, data-flow metrics, findings and marks, skill. Context-relay and broad-prop-bundle rules and an in-app trigger remain."
}
],
"closure": null
Expand Down
130 changes: 130 additions & 0 deletions site/src/data/catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@
"id": "Findings",
"description": "Lint and type-check results: the project's own tsc and eslint when it has them, otherwise srcly's bundled ruff and TS rules. No setup."
},
{
"id": "Data flow",
"description": "Render-path evidence from the TypeScript checker, after `srcly report --dataflow`: dead `??` guards, repeated forks and the worst value path in each TS/TSX file."
},
{
"id": "Detail",
"description": "Counts that describe code without saying it needs work: shown and colorable, never ranked."
Expand Down Expand Up @@ -531,6 +535,132 @@
],
"color_per_file": true
},
{
"id": "dataflow_impossible_defenses",
"label": "Impossible Defenses",
"short_label": "Dead?",
"unit": "guards",
"group": "Data flow",
"direction": "higher-worse",
"aggregation": "sum",
"languages": [
"ts",
"tsx"
],
"description": "`??` and `?.` whose guarded value the TypeScript types say is never null or undefined, so the fallback never runs. Only a type checker can prove this.",
"witness": false,
"color_domain": [
0,
1,
5
],
"color_per_file": true
},
{
"id": "dataflow_repeated_forks",
"label": "Repeated Forks",
"short_label": "Forks",
"unit": "forks",
"group": "Data flow",
"direction": "higher-worse",
"aggregation": "sum",
"languages": [
"ts",
"tsx"
],
"description": "Components that test the same discriminant at several sibling branch sites (ternaries, `&&`, Solid `<Show>` and `<Match>`): each wants one sub-component per branch.",
"witness": false,
"color_domain": [
0,
1,
3
],
"color_per_file": true
},
{
"id": "dataflow_relay_hops",
"label": "Prop Relay",
"short_label": "Relay",
"unit": "boundaries",
"group": "Data flow",
"direction": "higher-worse",
"aggregation": "max",
"languages": [
"ts",
"tsx"
],
"description": "The most component boundaries a value crosses on its way to one of the file's render sinks.",
"witness": false,
"color_domain": [
0,
3,
8
],
"color_per_file": false
},
{
"id": "dataflow_representation_changes",
"label": "Shape Changes",
"short_label": "Shape",
"unit": "steps",
"group": "Data flow",
"direction": "higher-worse",
"aggregation": "max",
"languages": [
"ts",
"tsx"
],
"description": "The most representation-only steps (alias, object pack, spread) on one of the file's render paths.",
"witness": false,
"color_domain": [
0,
3,
8
],
"color_per_file": false
},
{
"id": "dataflow_path_depth",
"label": "Path Depth",
"short_label": "Depth",
"unit": "steps",
"group": "Data flow",
"direction": "higher-worse",
"aggregation": "max",
"languages": [
"ts",
"tsx"
],
"description": "The most steps from a source (prop, signal, local) to one of the file's JSX sinks.",
"witness": false,
"color_domain": [
0,
6,
15
],
"color_per_file": false
},
{
"id": "dataflow_fan_out",
"label": "Value Fan-Out",
"short_label": "FanO",
"unit": "sinks",
"group": "Data flow",
"direction": "neutral",
"aggregation": "max",
"languages": [
"ts",
"tsx"
],
"description": "The most render sinks that one of the file's sink sources also feeds. Wide reach is a fact, not a fault.",
"witness": false,
"color_domain": [
0,
5,
20
],
"color_per_file": false
},
{
"id": "todo_count",
"label": "TODOs",
Expand Down
3 changes: 2 additions & 1 deletion site/src/docs/pages/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ uvx srcly scan . --out tree.json
uvx srcly report . --out .srcly --profile frontend
```

Use `--stdout` for a bundled JSON payload, `--refresh` to rescan and rerun checks, and `--verbose` to print per-file progress to stderr. To include the full raw tree, use `--include-tree`; to include TypeScript and TSX imports, use `--include-dependencies`. Select the output format with `--format markdown`, `--format json`, or `--format both`.
Use `--stdout` for a bundled JSON payload, `--refresh` to rescan and rerun checks, and `--verbose` to print per-file progress to stderr. To include the full raw tree, use `--include-tree`; to include TypeScript and TSX imports, use `--include-dependencies`. Select the output format with `--format markdown`, `--format json`, or `--format both`. Add `--dataflow` to run the TypeScript data-flow engine too: it writes `dataflow.md` and adds data-flow metrics and findings (see [Data-flow analysis](../data-flow/)).

The findings profile and the top-table metric are different settings. Use `--profile` for the weighted findings queue; use `--metric` for top files and functions. For example:

Expand Down Expand Up @@ -61,6 +61,7 @@ You can also pass a `path:line name` Start at location printed by the report. `e
uvx srcly compare
uvx srcly compare main HEAD --json
uvx srcly compare main pr:42 --json
uvx srcly compare --dataflow
```

Unavailable measurements stay null. If a file is measured on one side only, Srcly records a coverage change and does not count the missing value as a zero delta. A file absent from one dependency graph has unknown fan-in and fan-out.
Expand Down
15 changes: 11 additions & 4 deletions site/src/docs/pages/data-flow.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,21 @@ Data flow traces how values move through supported source code. Use it to invest

Depending on the anchor and language, Srcly can show a route, value-flow trace, or function effects. A route graph may show where a route's values move; an anchor graph starts from a selected symbol. The exact view depends on available code facts and supported language constructs.

For a repository summary or agent workflow, use a report and scoped explanation:
## Data-flow reports and findings

For a repository summary or an agent workflow, add `--dataflow` to a report:

```bash
uvx srcly report . --out .srcly
uvx srcly explain . --at src/app.tsx
uvx srcly report . --out .srcly --dataflow
```

These commands provide scan and scope context. The interactive Data flow view currently carries the graph exploration.
The engine traces every render path in the TypeScript and TSX program, from a prop, signal, or local to the JSX that renders it. This takes minutes on a large app, so it runs only when you ask. It adds:

- `dataflow.md`: ranked work packets with candidate edits, the risk queue and a stop recommendation, then the defensive ledger, repeated forks, prop relay, context relay, and fan-out.
- Two finding rules in the Data flow section of `report.md`. `impossible-defense` is a `??` or `?.` whose guarded value the types say is never null or undefined. `repeated-fork` is a component that tests the same discriminant at several sibling branch sites, including Solid `<Show>` and `<Match>`.
- Six metrics per TS/TSX file in the Data flow group: impossible defenses, repeated forks, prop relay, shape changes, path depth, and value fan-out. After the run, the app colors the treemap and marks the code viewer with them while the files stay unchanged.

`uvx srcly compare --dataflow` runs the engine on both sides and diffs these metrics.

## Requirements and language support

Expand Down
1 change: 1 addition & 0 deletions site/src/docs/pages/findings.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Srcly selects checks based on the files and tools it finds. Checks run independe
| Srcly TypeScript rules | TS files are outside project checker coverage | A selected built-in pattern matched, or that rule set did not cover the file. |
| Reachability and Solid rules | Supported TypeScript graph and patterns are available | Entry-point detection or language coverage may not match the project. Configure entries when needed. |
| ast-grep rules | `.srcly/rules/` files exist and ast-grep is available | The optional binary or rule run is unavailable. |
| Data-flow rules (`impossible-defense`, `repeated-fork`) | You pass `--dataflow` to `report` or `compare`, and Node 18+ is available | The engine is missing, the root is not TypeScript, or the run failed. The reason is in `report.md`. |

The exact checks vary by project. Srcly runs `tsc` per detected TypeScript project, expands solution configurations, runs ESLint when configured, and runs Ruff for Python. Its built-in TS checks include selected patterns such as explicit `any`, suppression directives without a reason, and non-null assertion chains when project tools do not cover those files. It also reports selected reachability, Solid, and await-in-loop signals. Optional ast-grep YAML rules can add project-specific checks. See [Configuration](../configuration/) for setup.

Expand Down
3 changes: 2 additions & 1 deletion site/src/docs/pages/reports.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,9 +34,10 @@ The default report writes these artifacts:
| `hotspots.json` | Which files or functions rank highest for the selected single metric? |
| `metrics.schema.json` | What do metrics mean, and how should an agent interpret them? |
| `agent-skill.md` | What guidance should an agent follow when it consumes the report? |
| `dataflow.md` | With `--dataflow`: which render paths in TypeScript and TSX are worth cleaning up, and where does cleanup stop paying off? |
| `size_budget.json` | Which code files exceed the token-size threshold, and what baseline does the ratchet use? |

The manifest identifies artifact paths and scan provenance. `report.md` is a practical first read; the JSON files support targeted tools and agent workflows. Use `--include-tree` to include the full raw tree or `--include-dependencies` to include the TypeScript and TSX import graph.
The manifest identifies artifact paths and scan provenance. `report.md` is a practical first read; the JSON files support targeted tools and agent workflows. Use `--include-tree` to include the full raw tree or `--include-dependencies` to include the TypeScript and TSX import graph. Use `--dataflow` to add `dataflow.md` and a Data flow section in `report.md`; it needs Node 18 or newer and takes minutes on a large app.

If you add `--quadrant <preset>`, Srcly also writes `quadrants.json` with the full member lists for the selected 2×2. The report's Markdown section gives a compact readable summary.

Expand Down
Loading
Loading