From 67625cedecd6fefc8414ccfd039e26491cad3193 Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Sat, 21 Nov 2026 09:44:13 -0500 Subject: [PATCH] docs: data-flow reports in the skill, site and code map Fold the reading rules of tsx-data-flow's render-path-dataflow-work skill into srcly-code-quality, document report/compare --dataflow and the two data-flow finding rules on the site, add the Data flow metrics to the site catalog, and record M7's state in the initiative map. Co-Authored-By: Claude Opus 5.5 --- docs/CODE_MAP.md | 1 + .../initiative-map.json | 10 +- site/src/data/catalog.json | 130 ++++++++++++++++++ site/src/docs/pages/cli.md | 3 +- site/src/docs/pages/data-flow.md | 15 +- site/src/docs/pages/findings.md | 1 + site/src/docs/pages/reports.md | 3 +- skills/srcly-code-quality/SKILL.md | 29 ++++ 8 files changed, 183 insertions(+), 9 deletions(-) diff --git a/docs/CODE_MAP.md b/docs/CODE_MAP.md index d7118041..669a2cbb 100644 --- a/docs/CODE_MAP.md +++ b/docs/CODE_MAP.md @@ -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` | diff --git a/docs/intent/tsx-dataflow-integration/initiative-map.json b/docs/intent/tsx-dataflow-integration/initiative-map.json index 9ad7c0a0..025263f7 100644 --- a/docs/intent/tsx-dataflow-integration/initiative-map.json +++ b/docs/intent/tsx-dataflow-integration/initiative-map.json @@ -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": { @@ -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" }, @@ -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 diff --git a/site/src/data/catalog.json b/site/src/data/catalog.json index ab813b42..08f79ac1 100644 --- a/site/src/data/catalog.json +++ b/site/src/data/catalog.json @@ -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." @@ -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 `` and ``): 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", diff --git a/site/src/docs/pages/cli.md b/site/src/docs/pages/cli.md index b205e5d5..ca9a1b71 100644 --- a/site/src/docs/pages/cli.md +++ b/site/src/docs/pages/cli.md @@ -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: @@ -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. diff --git a/site/src/docs/pages/data-flow.md b/site/src/docs/pages/data-flow.md index 607e9513..5f33fb57 100644 --- a/site/src/docs/pages/data-flow.md +++ b/site/src/docs/pages/data-flow.md @@ -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 `` and ``. +- 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 diff --git a/site/src/docs/pages/findings.md b/site/src/docs/pages/findings.md index 0b76f9ea..0d6d87cd 100644 --- a/site/src/docs/pages/findings.md +++ b/site/src/docs/pages/findings.md @@ -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. diff --git a/site/src/docs/pages/reports.md b/site/src/docs/pages/reports.md index d6dbae3b..ca2f322c 100644 --- a/site/src/docs/pages/reports.md +++ b/site/src/docs/pages/reports.md @@ -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 `, 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. diff --git a/skills/srcly-code-quality/SKILL.md b/skills/srcly-code-quality/SKILL.md index 92dddd51..93d333d4 100644 --- a/skills/srcly-code-quality/SKILL.md +++ b/skills/srcly-code-quality/SKILL.md @@ -62,6 +62,7 @@ Use `uvx srcly scan . --out -` only when a caller explicitly wants raw tree JSON - Drill into a folder, file or `file::symbol`: `uvx srcly explain . --at ` (relative to the analyzed path, not the cwd; `--file` still works) - Rank another file class too: `--include-class test` (also `docs`, `fixture`, `generated`, `vendored`, `config`, `data`) - Compare two refs: `uvx srcly compare` (merge-base → working tree) or `uvx srcly compare pr:` +- TypeScript/TSX data flow (needs Node 18+, takes minutes on a big app): `uvx srcly report . --out .srcly --dataflow`; diff its metrics with `uvx srcly compare --dataflow` - Full raw tree: `uvx srcly scan . --out .srcly/tree.json` - CI gate: `uvx srcly report . --out .srcly --fail-on high` @@ -94,6 +95,34 @@ Progress, version banners and cache warnings go to stderr, so stdout stays parse - Low comment density only matters when paired with complexity, public API behavior, or non-obvious domain logic. - Compare: `null` is unavailable, never zero. A file measured on one side only shows under `coverage` (lost or gained) and stays out of the metric totals; report coverage changes apart from real improvements or regressions. A file missing from a side's dependency graph has unknown `fan_in`/`fan_out`. +## Data Flow + +`--dataflow` runs the TypeScript checker over every render path, from a prop, signal or local to the JSX that renders it. It adds: + +- `dataflow.md`: ranked work packets with candidate edits and the risk queue, then the defensive ledger, repeated forks, prop relay, context relay and fan-out. +- A `## Data flow` section in `report.md` that lists each finding by line. +- Metrics per TS/TSX file: `dataflow_impossible_defenses`, `dataflow_repeated_forks`, `dataflow_relay_hops`, `dataflow_representation_changes`, `dataflow_path_depth` and `dataflow_fan_out`. The app colors the treemap and marks the code viewer from them while the files stay unchanged. + +The two finding rules: + +- `impossible-defense`: a `??` or `?.` whose guarded value the types say is never null or undefined. Remove it only when the runtime contract agrees with the types (no external JSON, no unchecked cast, no SSR first render). +- `repeated-fork`: a component tests the same discriminant at several sibling branch sites (ternary, `&&`, Solid `` or ``). Split it into one sub-component per branch, and move each branch-only value into its sub-component. + +Read `dataflow.md` in this order, and fix one slice at a time: + +1. Pick the worst grounded ownership problem, not the highest-scored sink. Prefer prop relay, repeated shape changes across components, wide fan-out, broad prop bundles, and state that a feature store or context should own. Skip a compact local parser or style object next to JSX unless nothing larger is left. +2. Read **Feature Clusters**. Treat "Provider/Context audit" as work only when its Evidence column shows provider, context, feature-hook or same-feature relay evidence. +3. Prefer a **Grouped Recommendation** (such as `BarTick[]` or `BarRectangle[]`) to edits on each attribute sink. +4. Read the **Pack verdict** before you create or delete a render model. Keep a `normalization boundary` or `cohesive render model`. Split an `overpacked bag`, `mirror object` or `relay bag` by render responsibility. +5. Follow the **Extraction shape check**: build a cohesive repeated item, never a mirror singleton. A generic name such as `renderValue` or `ItemModel` is a reason to rename, not a design. +6. For repeated optional Solid prop defaults, use one `mergeProps(defaults, props)` boundary. Keep a caller-precedence fallback (`tooltip ?? user.name`) where it states the API's priority. +7. Keep SVG shell values (`width`, `height`, `viewBox`) inline or in a small local thunk; they are not fields of the repeated item. Use local aliases for repeated scalar geometry such as `size() / 2`. +8. Leave **Background Findings** alone: they are true paths, not cleanup work. +9. When you add or extend a feature Provider/Context, finish the job: convert children that receive context-owned state or actions through props to the feature hook. Check every Context Relay row and call it converted, a presentational leaf, or a follow-up. +10. Stop when the **Stop Recommendation** says `yes`. More local flattening after that is churn. + +After a fix, run the project's checks, run `report --dataflow` again, and compare `dataflow.md` and the metrics with `uvx srcly compare --dataflow`. + ## Response Pattern When reporting back: