From 71c7310e8fcb60935dab125422c8748eb8adb71d Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Sat, 21 Nov 2026 09:42:45 -0500 Subject: [PATCH] feat: srcly report --dataflow, data-flow metrics and code-viewer marks 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 --- client/src/utils/normalizeTree.ts | 7 + server/app/models.py | 22 +- server/app/routers/files.py | 8 + server/app/run.py | 16 ++ server/app/services/analysis_types.py | 14 +- server/app/services/compare/service.py | 10 +- server/app/services/compare/snapshots.py | 22 ++ server/app/services/dataflow/signals.py | 279 +++++++++++++++++++++ server/app/services/metric_catalog.py | 38 ++- server/app/services/reporting.py | 70 +++++- server/app/services/scan_jobs.py | 8 +- server/tests/snapshots/metric-catalog.json | 154 ++++++++++++ server/tests/test_dataflow_signals.py | 108 ++++++++ 13 files changed, 745 insertions(+), 11 deletions(-) create mode 100644 server/app/services/dataflow/signals.py create mode 100644 server/tests/test_dataflow_signals.py diff --git a/client/src/utils/normalizeTree.ts b/client/src/utils/normalizeTree.ts index 3cc10c24..b895ecf7 100644 --- a/client/src/utils/normalizeTree.ts +++ b/client/src/utils/normalizeTree.ts @@ -56,6 +56,12 @@ export const DEFAULT_METRICS = { churn_lines: null, finding_count: null, error_count: null, + dataflow_impossible_defenses: null, + dataflow_repeated_forks: null, + dataflow_relay_hops: null, + dataflow_fan_out: null, + dataflow_representation_changes: null, + dataflow_path_depth: null, na_reason: "", na_reasons: null, analysis_status: "ok", @@ -70,6 +76,7 @@ export const DEFAULT_NODE = { end_line: 0, activity: null, findings: null, + dataflow: null, } as const; type RawNode = { diff --git a/server/app/models.py b/server/app/models.py index ac75be6e..4a3b8e0e 100644 --- a/server/app/models.py +++ b/server/app/models.py @@ -1,4 +1,4 @@ -from typing import List +from typing import Any, List from pydantic import BaseModel, Field, PrivateAttr class Witness(BaseModel): @@ -92,6 +92,15 @@ class Metrics(BaseModel): finding_count: int | None = None error_count: int | None = None + # Data-flow signals (``services/dataflow/signals``), laid over the tree + # after ``srcly report --dataflow``: TS/TSX files and folders; scopes N/A. + dataflow_impossible_defenses: int | None = None + dataflow_repeated_forks: int | None = None + dataflow_relay_hops: int | None = None + dataflow_fan_out: int | None = None + dataflow_representation_changes: int | None = None + dataflow_path_depth: int | None = None + na_reason: str = "" # Per-metric reasons that override ``na_reason`` (activity has its own: # "Not a Git repository", "Shallow clone", ...). @@ -151,6 +160,13 @@ class FindingsInfo(BaseModel): finding_count: int = 0 +class DataflowInfo(BaseModel): + """Whether the data-flow signals ran for a tree (root node only, after ``--dataflow``).""" + + status: str # "ok" | "na" + reason: str = "" + + class AnalysisInfo(BaseModel): """Where a CLI command's tree came from (root node only; set by ``reporting.scan_tree``).""" @@ -177,8 +193,12 @@ class Node(BaseModel): activity: ActivityInfo | None = None # Root only: whether the checks finished, and which tools ran. findings: FindingsInfo | None = None + # Root only: whether the data-flow signals ran (``services/dataflow/signals``). + dataflow: DataflowInfo | None = None # Root only, CLI only (never on the wire): whether ``reporting.scan_tree`` reused the saved scan. _analysis: AnalysisInfo | None = PrivateAttr(default=None) + # Root only, CLI only: the data-flow signals ``scan_tree(dataflow=True)`` laid over the tree. + _dataflow: Any = PrivateAttr(default=None) model_config = { "populate_by_name": True diff --git a/server/app/routers/files.py b/server/app/routers/files.py index ae749a20..bbdabf47 100644 --- a/server/app/routers/files.py +++ b/server/app/routers/files.py @@ -94,6 +94,7 @@ def get_file_markers( else: markers = collect_markers(str(file_path)) markers.update(_findings_markers(file_path)) + markers.update(_dataflow_markers(file_path)) except HTTPException: raise except Exception as e: @@ -115,6 +116,13 @@ def _findings_markers(file_path: Path) -> dict: return findings.markers_for(str(file_path), _findings_job_result(file_path)) +def _dataflow_markers(file_path: Path) -> dict: + """Lines behind the data-flow counts, from the last ``--dataflow`` result, while the file is unchanged.""" + from app.services.dataflow import signals + + return signals.markers_for(str(file_path.resolve()), signals.latest_for_file(file_path)) + + @router.get("/findings") def get_file_findings(path: str = Query(..., description="Absolute path to the file")): """ diff --git a/server/app/run.py b/server/app/run.py index b5e05c2a..5c72368c 100644 --- a/server/app/run.py +++ b/server/app/run.py @@ -329,6 +329,14 @@ def _run_headless(argv: list[str]) -> None: default=[], help="Also rank this file class. May be repeated.", ) + report_parser.add_argument( + "--dataflow", + action="store_true", + help=( + "Also run the TypeScript data-flow engine (needs Node 18+): data-flow metrics and findings, " + "and dataflow.md with ranked work packets. Takes minutes on a big app." + ), + ) report_parser.add_argument("--tree-depth", type=_positive_int, default=3, help="Maximum depth in tree.summary.json.") report_parser.add_argument("--tree-top", type=_positive_int, default=6, help="Maximum children per tree level.") report_parser.add_argument("--include-tree", action="store_true", help="Also write/include the full raw tree.json artifact.") @@ -434,6 +442,11 @@ def _run_headless(argv: list[str]) -> None: help="Include both full trees and dependency graphs in the JSON.", ) compare_parser.add_argument("--refresh", action="store_true", help="Rescan both sides instead of using the cache.") + compare_parser.add_argument( + "--dataflow", + action="store_true", + help="Also diff the data-flow metrics (runs the TypeScript data-flow engine on both sides; minutes on a big app).", + ) compare_parser.add_argument("--limit", type=_positive_int, default=40, help="Maximum files in the markdown summary.") fix_parser = subparsers.add_parser( @@ -521,6 +534,7 @@ def _dispatch(args) -> None: quadrant=args.quadrant, quadrant_cohort=args.quadrant_cohort, include_classes=("code", *args.include_class), + dataflow=args.dataflow, ) # Static reference (metric schema, agent guide) and the findings_top prefix are artifacts, # not per-run evidence; `report --out` still writes them. @@ -548,6 +562,7 @@ def _dispatch(args) -> None: quadrant=args.quadrant, quadrant_cohort=args.quadrant_cohort, include_classes=("code", *args.include_class), + dataflow=args.dataflow, ) written = reporting.write_artifacts(payload, out_dir, output_format=output_format) if args.verbose: @@ -622,6 +637,7 @@ def _run_compare(args) -> None: head, include_sides=args.include_sides, force=args.refresh, + dataflow=args.dataflow, on_phase=lambda phase: print(f"srcly compare: {phase}", file=sys.stderr, flush=True), ) except GitError as exc: diff --git a/server/app/services/analysis_types.py b/server/app/services/analysis_types.py index 3d0a77d8..44227bb9 100644 --- a/server/app/services/analysis_types.py +++ b/server/app/services/analysis_types.py @@ -205,8 +205,20 @@ def iter_executable_scopes(funcs): # Lint and type-check findings: from external tools (``services/findings``), # laid over the tree when it is served, per file. FINDINGS_METRICS = frozenset({"finding_count", "error_count"}) +# Data-flow signals from the engine's tier-2 report (``services/dataflow/signals``): +# TypeScript and TSX only, laid over the tree when a ``--dataflow`` run left a result. +DATAFLOW_METRICS = frozenset( + { + "dataflow_impossible_defenses", + "dataflow_repeated_forks", + "dataflow_relay_hops", + "dataflow_fan_out", + "dataflow_representation_changes", + "dataflow_path_depth", + } +) # Filled after the scan, so never "not measured for ". -OVERLAY_METRICS = ACTIVITY_METRICS | FINDINGS_METRICS +OVERLAY_METRICS = ACTIVITY_METRICS | FINDINGS_METRICS | DATAFLOW_METRICS # Means over a file's functions; with no functions there is nothing to average. MEAN_OVER_FUNCTIONS = frozenset({"complexity_avg", "average_function_length"}) diff --git a/server/app/services/compare/service.py b/server/app/services/compare/service.py index 89ee9efe..68180573 100644 --- a/server/app/services/compare/service.py +++ b/server/app/services/compare/service.py @@ -18,7 +18,7 @@ resolve_auto_base, resolve_ref, ) -from app.services.compare.snapshots import Side, load_side +from app.services.compare.snapshots import Side, load_side, with_dataflow from app.services.scan_progress import NULL_OBSERVER, ScanObserver from app.services.scan_workers import CancelToken @@ -98,12 +98,14 @@ def build_compare( on_phase: Callable[[str], None] = lambda _phase: None, timer: Optional[StepTimer] = None, activity_window: Optional[str] = None, + dataflow: bool = False, ) -> dict[str, Any]: """ Compare ``base`` → ``head`` for the git repo containing ``path``. ``include_sides`` adds both full trees and graphs (what the UI draws); - the CLI omits them by default to keep the JSON small. + the CLI omits them by default to keep the JSON small. ``dataflow`` also + runs the data-flow engine on both sides, so its metrics are diffed. """ timer = timer or StepTimer() @@ -137,6 +139,10 @@ def phase(name: str) -> None: for side in (base_side, head_side): result = activity.collect(side.ref.root(repo), activity_window, rev=side.ref.sha) activity.apply_to_tree(side.tree, result, lambda path: path) + if dataflow: + phase("dataflow") + for side in (base_side, head_side): + with_dataflow(repo, side) phase("diffing") payload: dict[str, Any] = { diff --git a/server/app/services/compare/snapshots.py b/server/app/services/compare/snapshots.py index 8fb7268d..608ca4e7 100644 --- a/server/app/services/compare/snapshots.py +++ b/server/app/services/compare/snapshots.py @@ -233,6 +233,28 @@ def _with_checks(tree_json: dict[str, Any], root: Path, *, fingerprint: Optional return findings.apply_to_tree(tree_json, result) +def with_dataflow(repo: Path, side: Side) -> None: + """ + Lay data-flow metrics over a loaded side (``compare --dataflow``). A + commit side gets its own throwaway checkout, since the side cache keeps no + files; its engine is closed after. Like compare's checks, a checkout has + no ``node_modules``, so both sides use srcly's bundled TypeScript. + """ + from app.services.dataflow import signals + + def apply(root: Path, *, fingerprint: Optional[str], close: bool) -> None: + result = signals.collect(root, fingerprint=fingerprint, close_after=close) + root_str = str(root.resolve()) + signals.apply_to_tree(side.tree, result, lambda p: os.path.join(root_str, p) if p else root_str) + + if side.ref.is_worktree or side.ref.sha is None: + root = side.ref.root(repo) + apply(root, fingerprint=cache.fingerprint(root), close=False) + return + with snapshot_checkout(repo, side.ref.sha) as checkout: + apply(checkout, fingerprint=None, close=True) + + def load_side( repo: Path, ref: ResolvedRef, diff --git a/server/app/services/dataflow/signals.py b/server/app/services/dataflow/signals.py new file mode 100644 index 00000000..da70286e --- /dev/null +++ b/server/app/services/dataflow/signals.py @@ -0,0 +1,279 @@ +""" +Data-flow signals for srcly's pipelines (M7): per-file metrics, findings and +``dataflow.md``, from the engine's tier-2 ``fileSignals`` op. + +Tier 2 builds the legacy render-path report, which takes minutes on a big +app, so nothing runs it by default: ``srcly report --dataflow`` and +``srcly compare --dataflow`` ask for it. The last result per root is kept on +disk, so the app colors the treemap and marks the code viewer from it while +the files still match. +""" + +from __future__ import annotations + +import gzip +import hashlib +import json +import os +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Callable, Optional + +from app.services.analysis_types import DATAFLOW_METRICS +from app.services.dataflow.engine import EngineError +from app.services.dataflow.models import FileSignalsResult + +# The legacy report on a big app takes minutes; ``SRCLY_DATAFLOW_TIMEOUT`` still overrides it. +SIGNALS_TIMEOUT = 1800.0 +TS_SUFFIXES = (".ts", ".tsx", ".mts", ".cts") + +# Engine field → catalog metric id, and how a folder rolls it up. +FIELDS: dict[str, tuple[str, str]] = { + "dataflow_impossible_defenses": ("impossibleDefenses", "sum"), + "dataflow_relay_hops": ("relayHops", "max"), + "dataflow_fan_out": ("fanOut", "max"), + "dataflow_representation_changes": ("representationChanges", "max"), + "dataflow_path_depth": ("pathDepth", "max"), +} +REPEATED_FORKS = "dataflow_repeated_forks" +RULE_METRIC = {"impossible-defense": "dataflow_impossible_defenses", "repeated-fork": REPEATED_FORKS} + + +@dataclass +class Signals: + root: str + """The engine root, absolute; result paths are relative to it.""" + status: str + """``ok`` or ``na``.""" + reason: str = "" + result: Optional[FileSignalsResult] = None + fingerprint: Optional[str] = None + + def per_file(self) -> dict[str, dict[str, int]]: + """Absolute path → metric id → value, for every file the engine analyzed.""" + if self.result is None: + return {} + out: dict[str, dict[str, int]] = {} + for item in self.result.files: + m = item.metrics.model_dump() + values = {metric: m[field] for metric, (field, _) in FIELDS.items()} + values[REPEATED_FORKS] = 0 + out[os.path.join(self.root, item.file)] = values + for f in self.result.findings: + if f.rule == "repeated-fork": + values = out.get(os.path.join(self.root, f.file)) + if values is not None: + values[REPEATED_FORKS] += 1 + return out + + def findings_in(self, path: str) -> list[dict[str, Any]]: + if self.result is None: + return [] + return [f.model_dump() for f in self.result.findings if os.path.join(self.root, f.file) == path] + + def as_dict(self) -> dict[str, Any]: + return { + "root": self.root, + "status": self.status, + "reason": self.reason, + "fingerprint": self.fingerprint, + "result": self.result.model_dump() if self.result else None, + } + + @classmethod + def from_dict(cls, data: dict[str, Any]) -> "Signals": + result = data.get("result") + return cls( + root=data["root"], + status=data["status"], + reason=data.get("reason", ""), + fingerprint=data.get("fingerprint"), + result=FileSignalsResult.model_validate(result) if result else None, + ) + + +# -- running and caching ------------------------------------------------------ + + +def _cache_file(root: Path) -> Path: + from app.services.cache import cache_dir + + digest = hashlib.sha256(str(root).encode()).hexdigest()[:24] + return cache_dir().parent / "dataflow-signals" / f"{digest}.json.gz" + + +# Saved file → (its mtime, the parsed result): the app reads it on every tree request. +_memo: dict[Path, tuple[float, Signals]] = {} + + +def cached(root: Path) -> Optional[Signals]: + """The last finished result for ``root``, whatever its fingerprint.""" + path = _cache_file(root.resolve()) + try: + mtime = path.stat().st_mtime + hit = _memo.get(path) + if hit is not None and hit[0] == mtime: + return hit[1] + with gzip.open(path, "rt", encoding="utf-8") as fh: + signals = Signals.from_dict(json.load(fh)) + except Exception: # noqa: BLE001 - a missing or bad entry is a miss + return None + _memo[path] = (mtime, signals) + return signals + + +def _save(root: Path, signals: Signals) -> None: + target = _cache_file(root) + try: + target.parent.mkdir(parents=True, exist_ok=True) + tmp = target.with_suffix(f".{os.getpid()}.tmp") + with gzip.open(tmp, "wt", encoding="utf-8") as fh: + json.dump(signals.as_dict(), fh) + os.replace(tmp, target) + except OSError: + pass # the cache is best-effort + + +def collect( + root: Path, + *, + fingerprint: Optional[str] = None, + use_cache: bool = True, + close_after: bool = False, + registry: Any = None, +) -> Signals: + """ + Signals for ``root``. Never raises: no Node, no engine, a Python root, a + crash or a timeout comes back N/A with the reason. Reuses the saved result + when ``fingerprint`` matches it. ``close_after`` stops the engine when done + (compare's throwaway checkouts). + """ + from app.services.dataflow import engine as dataflow_engine + + root = root.resolve() + if use_cache and fingerprint: + hit = cached(root) + if hit is not None and hit.fingerprint == fingerprint and hit.status == "ok": + return hit + registry = registry or dataflow_engine.registry + try: + found = registry.probe(root) + if not found.available: + return Signals(str(root), "na", found.message or found.reason or "The data-flow engine is unavailable") + if found.language != "typescript": + return Signals(str(root), "na", "Data-flow signals cover TypeScript and TSX only") + timeout = dataflow_engine.timeout_override() or SIGNALS_TIMEOUT + raw = registry.query(root, "fileSignals", {}, timeout=timeout) + result = FileSignalsResult.model_validate(raw) + except EngineError as exc: + return Signals(str(root), "na", f"Data flow not analyzed: {exc.message}") + finally: + if close_after: + registry.close(root) + signals = Signals(str(root), "ok", result=result, fingerprint=fingerprint) + if fingerprint: + _save(root, signals) + return signals + + +# -- tree overlay --------------------------------------------------------------- + + +def _set_na(metrics: dict[str, Any], reason: str) -> None: + for name in DATAFLOW_METRICS: + metrics[name] = None + reasons = dict(metrics.get("na_reasons") or {}) + reasons.update({name: reason for name in DATAFLOW_METRICS}) + metrics["na_reasons"] = reasons + + +def _set_values(metrics: dict[str, Any], values: dict[str, int]) -> None: + metrics.update(values) + reasons = {k: v for k, v in (metrics.get("na_reasons") or {}).items() if k not in DATAFLOW_METRICS} + metrics["na_reasons"] = reasons or None + + +def apply_to_tree( + tree: dict[str, Any], + signals: Signals, + path_of: Callable[[str], Optional[str]] = lambda p: p, +) -> dict[str, Any]: + """ + Set the data-flow metrics on every TS/TSX file of a ``Node`` JSON tree and + roll them into folders (sums for counts, maxes for the worst path). A TS + file the engine did not analyze is N/A with the reason, never 0; other + languages stay unmeasured. The root gets ``dataflow`` (status and reason). + """ + per_file = signals.per_file() + rollup = {metric: agg for metric, (_, agg) in FIELDS.items()} | {REPEATED_FORKS: "sum"} + if signals.status != "ok": + missing = signals.reason + else: + missing = "Not in the data-flow program (outside its tsconfig)" + + def visit(node: dict[str, Any]) -> Optional[dict[str, int]]: + metrics = node.setdefault("metrics", {}) + kind = node.get("type") + if kind == "file": + path = path_of(node.get("path", "")) + if path is None or not path.endswith(TS_SUFFIXES) or path.endswith(".d.ts"): + return None + values = per_file.get(path) + if values is None: + _set_na(metrics, missing) + return None + _set_values(metrics, values) + return values + if kind != "folder": + return None + total: Optional[dict[str, int]] = None + for child in node.get("children") or []: + values = visit(child) + if values is None: + continue + if total is None: + total = dict(values) + continue + for metric, agg in rollup.items(): + total[metric] = total[metric] + values[metric] if agg == "sum" else max(total[metric], values[metric]) + if total is None: + for name in DATAFLOW_METRICS: + metrics[name] = None + else: + _set_values(metrics, total) + return total + + visit(tree) + tree["dataflow"] = {"status": signals.status, "reason": signals.reason} + return tree + + +def markers_for(path: str, signals: Optional[Signals]) -> dict[str, list[dict]]: + """Code viewer lines behind the impossible-defense and repeated-fork counts.""" + if signals is None or signals.status != "ok": + return {} + out: dict[str, list[dict]] = {} + for f in signals.findings_in(path): + marker = {"line": f["line"], "end_line": f["endLine"], "note": f"dataflow {f['rule']}: {f['message']}"} + out.setdefault(RULE_METRIC[f["rule"]], []).append(marker) + return out + + +def latest_for_file(path: Path) -> Optional[Signals]: + """ + The saved result for the nearest folder above ``path`` that has one, when + the file has not changed since it was computed (so the lines still match). + """ + path = path.resolve() + for folder in path.parents: + hit = cached(folder) + if hit is None: + continue + try: + saved = _cache_file(folder).stat().st_mtime + if path.stat().st_mtime > saved: + return None + except OSError: + return None + return hit + return None diff --git a/server/app/services/metric_catalog.py b/server/app/services/metric_catalog.py index 7b817312..9f17c9e3 100644 --- a/server/app/services/metric_catalog.py +++ b/server/app/services/metric_catalog.py @@ -16,7 +16,7 @@ from dataclasses import dataclass, field from typing import Any, Literal -from app.services.analysis_types import FINDINGS_METRICS, MEASURED_FILE_METRICS, MEASURED_SCOPE_METRICS, OVERLAY_METRICS +from app.services.analysis_types import DATAFLOW_METRICS, FINDINGS_METRICS, MEASURED_FILE_METRICS, MEASURED_SCOPE_METRICS, OVERLAY_METRICS Direction = Literal["higher-worse", "lower-worse", "neutral"] Aggregation = Literal["sum", "max", "mean"] @@ -30,6 +30,7 @@ ("Markdown", "Markdown documents."), ("Activity", "Git history per file in the selected window (90 days by default). On whenever the folder is a Git repo."), ("Findings", "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."), + ("Data flow", "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."), ("Detail", "Counts that describe code without saying it needs work: shown and colorable, never ranked."), ) @@ -71,6 +72,8 @@ def languages(self) -> list[str] | None: if self.id in FINDINGS_METRICS: # Checkers exist for these: tsc and eslint, eslint for plain JS, ruff. return ["ts", "tsx", "js", "jsx", "python"] + if self.id in DATAFLOW_METRICS: + return ["ts", "tsx"] langs = [lang for lang, measured in MEASURED_FILE_METRICS.items() if self.id in measured] return langs or None @@ -261,6 +264,39 @@ def _component(id: str, label: str, short: str, unit: tuple[str, str], descripti "Findings the checker calls errors: type errors, eslint errors, syntax errors and undefined names. Warnings aren't counted.", color_domain=(0, 1, 5), color_per_file=True, ), + # Data flow: from the engine's render-path report (services/dataflow/signals), per file. + MetricSpec( + "dataflow_impossible_defenses", "Impossible Defenses", "Dead?", "guards", "guard", "Data flow", "higher-worse", "sum", + "`??` 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.", + color_domain=(0, 1, 5), color_per_file=True, + weights={"frontend": 0.8, "typescript": 0.8}, + ), + MetricSpec( + "dataflow_repeated_forks", "Repeated Forks", "Forks", "forks", "fork", "Data flow", "higher-worse", "sum", + "Components that test the same discriminant at several sibling branch sites (ternaries, `&&`, Solid `` and ``): each wants one sub-component per branch.", + color_domain=(0, 1, 3), color_per_file=True, + weights={"frontend": 0.5}, + ), + MetricSpec( + "dataflow_relay_hops", "Prop Relay", "Relay", "boundaries", "boundary", "Data flow", "higher-worse", "max", + "The most component boundaries a value crosses on its way to one of the file's render sinks.", + color_domain=(0, 3, 8), + ), + MetricSpec( + "dataflow_representation_changes", "Shape Changes", "Shape", "steps", "step", "Data flow", "higher-worse", "max", + "The most representation-only steps (alias, object pack, spread) on one of the file's render paths.", + color_domain=(0, 3, 8), + ), + MetricSpec( + "dataflow_path_depth", "Path Depth", "Depth", "steps", "step", "Data flow", "higher-worse", "max", + "The most steps from a source (prop, signal, local) to one of the file's JSX sinks.", + color_domain=(0, 6, 15), + ), + MetricSpec( + "dataflow_fan_out", "Value Fan-Out", "FanO", "sinks", "sink", "Data flow", "neutral", "max", + "The most render sinks that one of the file's sink sources also feeds. Wide reach is a fact, not a fault.", + color_domain=(0, 5, 20), compare="neutral", + ), # Detail: describes code without saying it needs work. MetricSpec( "todo_count", "TODOs", "TODO", "TODOs", "TODO", "Detail", "neutral", "sum", diff --git a/server/app/services/reporting.py b/server/app/services/reporting.py index 3468b6d7..fd7eea7f 100644 --- a/server/app/services/reporting.py +++ b/server/app/services/reporting.py @@ -26,7 +26,12 @@ def scan_tree( - root_path: Path, *, verbose: bool = False, activity_window: str | None = None, refresh: bool = False + root_path: Path, + *, + verbose: bool = False, + activity_window: str | None = None, + refresh: bool = False, + dataflow: bool = False, ) -> Node: """ Scan ``root_path`` and lay Git activity for ``activity_window`` (default @@ -34,7 +39,9 @@ def scan_tree( The analysis tree is shared with the app's cache: while no file under the root has changed, a second command (or the app) reuses it instead of - rescanning. ``refresh`` rescans and reruns the checks. + rescanning. ``refresh`` rescans and reruns the checks. ``dataflow`` also + runs the data-flow engine's render-path report (minutes on a big app) + and lays its metrics over the tree; ``tree._dataflow`` keeps the result. """ from concurrent.futures import ThreadPoolExecutor @@ -42,10 +49,17 @@ def scan_tree( root = root_path.resolve() fingerprint = cache.fingerprint(root) - with ThreadPoolExecutor(max_workers=1) as pool: + from app.services.dataflow import signals as dataflow_signals + + with ThreadPoolExecutor(max_workers=2) as pool: checks = pool.submit( lambda: lint_findings.collect(root, fingerprint=fingerprint, use_cache=not refresh) ) + flow = ( + pool.submit(lambda: dataflow_signals.collect(root, fingerprint=fingerprint, use_cache=not refresh)) + if dataflow + else None + ) entry = None if refresh else cache.analysis_cache.load(root, fingerprint) if entry is not None: data = json.loads(entry.data) @@ -66,7 +80,11 @@ def scan_tree( ) data = activity.apply_to_scan(data, root, activity_window) lint_findings.apply_to_tree(data, checks.result()) + signals = flow.result() if flow else None + if signals is not None: + dataflow_signals.apply_to_tree(data, signals) tree = Node.model_validate(data) + tree._dataflow = signals tree._analysis = AnalysisInfo( reused=entry is not None, scanned_at=datetime.fromtimestamp(scanned_at, timezone.utc).isoformat(timespec="seconds"), @@ -113,12 +131,13 @@ def build_report_payload( quadrant: str | None = None, quadrant_cohort: str | None = None, include_classes: Iterable[str] = ("code",), + dataflow: bool = False, ) -> dict[str, Any]: if profile not in PROFILE_WEIGHTS: raise ValueError(f"Unknown profile: {profile}") metric = metric or metric_catalog.profile_lead(profile) - tree = scan_tree(root_path, verbose=verbose, activity_window=activity_window, refresh=refresh) + tree = scan_tree(root_path, verbose=verbose, activity_window=activity_window, refresh=refresh, dataflow=dataflow) rank_options = dict( profile=profile, root_path=root_path, @@ -151,6 +170,12 @@ def build_report_payload( manifest = build_manifest(root_path=root_path, profile=profile) manifest["activity"] = tree.activity.model_dump() if tree.activity else None manifest["checks"] = tree.findings.model_dump() if tree.findings else None + signals = tree._dataflow + manifest["dataflow"] = ( + {"status": signals.status, "reason": signals.reason, "findings": len(signals.result.findings) if signals.result else 0} + if signals + else None + ) manifest["analysis"] = scopes.provenance(tree, root_path.resolve()) manifest["cache_used"] = bool(tree._analysis and tree._analysis.reused) metrics_schema = build_metrics_schema() @@ -179,12 +204,15 @@ def build_report_payload( focus_paths=focus_paths, deprioritize_paths=deprioritize_paths, ) - + (f"\n{quadrants.render_markdown(quadrant_result)}" if quadrant_result else ""), + + (f"\n{quadrants.render_markdown(quadrant_result)}" if quadrant_result else "") + + (f"\n{render_dataflow_section(signals, root_path)}" if signals else ""), "action_plan_markdown": action_plan_markdown, "agent_skill_markdown": render_agent_skill(), } if quadrant_result: payload["quadrants"] = quadrant_result + if signals is not None and signals.result is not None: + payload["dataflow_markdown"] = signals.result.markdown if include_tree: payload["tree"] = _node_to_json(tree) if include_dependencies: @@ -219,6 +247,7 @@ def write_report( quadrant: str | None = None, quadrant_cohort: str | None = None, include_classes: Iterable[str] = ("code",), + dataflow: bool = False, ) -> dict[str, Path]: payload = build_report_payload( root_path, @@ -239,6 +268,7 @@ def write_report( quadrant=quadrant, quadrant_cohort=quadrant_cohort, include_classes=include_classes, + dataflow=dataflow, ) return write_artifacts(payload, out_dir, output_format=output_format) @@ -266,6 +296,8 @@ def write_artifacts(payload: dict[str, Any], out_dir: Path, *, output_format: Ou written["report"] = _write_text(out_dir / "report.md", payload["report_markdown"]) written["action_plan"] = _write_text(out_dir / "action-plan.md", payload["action_plan_markdown"]) written["agent_skill"] = _write_text(out_dir / "agent-skill.md", payload["agent_skill_markdown"]) + if "dataflow_markdown" in payload: + written["dataflow"] = _write_text(out_dir / "dataflow.md", payload["dataflow_markdown"]) # The ratchet's state, always: `srcly check --ratchet` compares against it. from app.services import size_budget @@ -629,6 +661,32 @@ def render_markdown_report( return "\n".join(lines) + "\n" +def render_dataflow_section(signals: Any, root_path: Path, limit: int = 15) -> str: + """``report.md``'s data-flow section: the findings by line, then where the work packets are.""" + lines = ["## Data flow", ""] + if signals.status != "ok" or signals.result is None: + return "\n".join([*lines, f"Not analyzed: {signals.reason}", ""]) + result = signals.result + counts = {rule: sum(1 for f in result.findings if f.rule == rule) for rule in ("impossible-defense", "repeated-fork")} + lines.append( + f"The TypeScript checker found {counts['impossible-defense']} type-impossible `??`/`?.` guards and " + f"{counts['repeated-fork']} repeated {'fork' if counts['repeated-fork'] == 1 else 'forks'}. Read `dataflow.md` for ranked work packets, candidate edits, " + "the risk queue and the stop recommendation." + ) + if result.unplacedDefenses: + lines.append(f"{result.unplacedDefenses} more impossible guards could not be placed in a file and are not listed.") + lines.extend(["", "| Rule | Where | Finding |", "| --- | --- | --- |"]) + prefix = _display_path(signals.root, root_path) + for f in result.findings[:limit]: + where = f.file if prefix in (".", "") else f"{prefix}/{f.file}" + lines.append(f"| {f.rule} | `{where}:{f.line}` | {f.message.replace('|', '\\|')} |") + if not result.findings: + lines.append("| – | | No data-flow findings |") + elif len(result.findings) > limit: + lines.append(f"| +{len(result.findings) - limit} more | | Each one is also a code-viewer mark. |") + return "\n".join([*lines, ""]) + + def _activity_line(info: dict[str, Any] | None) -> str: if not info: return "- Git activity: not collected" @@ -776,6 +834,8 @@ def enrich_manifest_with_artifacts( ("agent_skill", "agent-skill.md", payload["agent_skill_markdown"], 10, "reference"), ] ) + if "dataflow_markdown" in payload: + artifact_specs.append(("dataflow", "dataflow.md", payload["dataflow_markdown"], 4, "top_n")) manifest["artifacts"] = [ { "name": name, diff --git a/server/app/services/scan_jobs.py b/server/app/services/scan_jobs.py index 638773a0..60d3a3e0 100644 --- a/server/app/services/scan_jobs.py +++ b/server/app/services/scan_jobs.py @@ -28,6 +28,7 @@ from app.models import Metrics, Node from app.services import activity, analysis, cache, findings +from app.services.dataflow import signals as dataflow_signals from app.services.scan_progress import ScanObserver from app.services.scan_workers import CancelToken, ScanCancelled @@ -282,9 +283,12 @@ def _overlay(self, window: Optional[str]) -> tuple[tuple, bytes]: window = activity.normalize_window(window) result = activity.collect(self.root_path, window) checks = self.findings_result() + # Data-flow metrics only from a `--dataflow` run on these very files: the engine never starts here. + flow = dataflow_signals.cached(self.root_path) + flow = flow if flow is not None and flow.status == "ok" and flow.fingerprint == self.fingerprint else None signature = ( result.status, result.reason, result.note, result.head, result.repo_root, len(result.files), - checks.status, id(self.findings_job), + checks.status, id(self.findings_job), id(flow), ) with self._result_json_lock: hit = self._overlay_json.get(window) @@ -293,6 +297,8 @@ def _overlay(self, window: Optional[str]) -> tuple[tuple, bytes]: tree = json.loads(self.result_json()) activity.apply_to_tree(tree, result, activity.scan_path_mapper(self.root_path, result)) findings.apply_to_tree(tree, checks) + if flow is not None: + dataflow_signals.apply_to_tree(tree, flow) data = json.dumps(compact_tree(tree), separators=(",", ":")).encode() with self._result_json_lock: self._overlay_json[window] = (signature, data) diff --git a/server/tests/snapshots/metric-catalog.json b/server/tests/snapshots/metric-catalog.json index 469133c1..7805f22b 100644 --- a/server/tests/snapshots/metric-catalog.json +++ b/server/tests/snapshots/metric-catalog.json @@ -43,6 +43,10 @@ "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": "Findings" }, + { + "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": "Data flow" + }, { "description": "Counts that describe code without saying it needs work: shown and colorable, never ranked.", "id": "Detail" @@ -642,6 +646,156 @@ "viewer_label": null, "witness": false }, + { + "aggregation": "sum", + "color_domain": [ + 0, + 1, + 5 + ], + "color_per_file": true, + "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.", + "direction": "higher-worse", + "group": "Data flow", + "id": "dataflow_impossible_defenses", + "label": "Impossible Defenses", + "languages": [ + "ts", + "tsx" + ], + "picker": true, + "scope": "file", + "short_label": "Dead?", + "unit": "guards", + "unit_one": "guard", + "viewer_label": null, + "witness": false + }, + { + "aggregation": "sum", + "color_domain": [ + 0, + 1, + 3 + ], + "color_per_file": true, + "description": "Components that test the same discriminant at several sibling branch sites (ternaries, `&&`, Solid `` and ``): each wants one sub-component per branch.", + "direction": "higher-worse", + "group": "Data flow", + "id": "dataflow_repeated_forks", + "label": "Repeated Forks", + "languages": [ + "ts", + "tsx" + ], + "picker": true, + "scope": "file", + "short_label": "Forks", + "unit": "forks", + "unit_one": "fork", + "viewer_label": null, + "witness": false + }, + { + "aggregation": "max", + "color_domain": [ + 0, + 3, + 8 + ], + "color_per_file": false, + "description": "The most component boundaries a value crosses on its way to one of the file's render sinks.", + "direction": "higher-worse", + "group": "Data flow", + "id": "dataflow_relay_hops", + "label": "Prop Relay", + "languages": [ + "ts", + "tsx" + ], + "picker": true, + "scope": "file", + "short_label": "Relay", + "unit": "boundaries", + "unit_one": "boundary", + "viewer_label": null, + "witness": false + }, + { + "aggregation": "max", + "color_domain": [ + 0, + 3, + 8 + ], + "color_per_file": false, + "description": "The most representation-only steps (alias, object pack, spread) on one of the file's render paths.", + "direction": "higher-worse", + "group": "Data flow", + "id": "dataflow_representation_changes", + "label": "Shape Changes", + "languages": [ + "ts", + "tsx" + ], + "picker": true, + "scope": "file", + "short_label": "Shape", + "unit": "steps", + "unit_one": "step", + "viewer_label": null, + "witness": false + }, + { + "aggregation": "max", + "color_domain": [ + 0, + 6, + 15 + ], + "color_per_file": false, + "description": "The most steps from a source (prop, signal, local) to one of the file's JSX sinks.", + "direction": "higher-worse", + "group": "Data flow", + "id": "dataflow_path_depth", + "label": "Path Depth", + "languages": [ + "ts", + "tsx" + ], + "picker": true, + "scope": "file", + "short_label": "Depth", + "unit": "steps", + "unit_one": "step", + "viewer_label": null, + "witness": false + }, + { + "aggregation": "max", + "color_domain": [ + 0, + 5, + 20 + ], + "color_per_file": false, + "description": "The most render sinks that one of the file's sink sources also feeds. Wide reach is a fact, not a fault.", + "direction": "neutral", + "group": "Data flow", + "id": "dataflow_fan_out", + "label": "Value Fan-Out", + "languages": [ + "ts", + "tsx" + ], + "picker": true, + "scope": "file", + "short_label": "FanO", + "unit": "sinks", + "unit_one": "sink", + "viewer_label": null, + "witness": false + }, { "aggregation": "sum", "color_domain": [ diff --git a/server/tests/test_dataflow_signals.py b/server/tests/test_dataflow_signals.py new file mode 100644 index 00000000..8db97ef3 --- /dev/null +++ b/server/tests/test_dataflow_signals.py @@ -0,0 +1,108 @@ +"""Data-flow signals: the tree overlay, code viewer marks and the ``--dataflow`` report.""" + +from __future__ import annotations + +from pathlib import Path + +from app.services import reporting +from app.services.dataflow import signals +from app.services.dataflow.models import FileSignalsResult + +ROOT = "/repo" + + +def _metrics(**values: int) -> dict: + base = {"impossibleDefenses": 0, "relayHops": 0, "fanOut": 0, "representationChanges": 0, "pathDepth": 0} + return {**base, **values} + + +def _result() -> FileSignalsResult: + return FileSignalsResult.model_validate( + { + "outcome": "ok", + "generation": 1, + "programHash": "h", + "tsconfig": "tsconfig.json", + "typescript": "5.9.3", + "nullProof": True, + "reason": None, + "files": [ + {"file": "src/a.tsx", "metrics": _metrics(impossibleDefenses=2, pathDepth=9, relayHops=1)}, + {"file": "src/b.ts", "metrics": _metrics(impossibleDefenses=1, pathDepth=4, relayHops=3)}, + ], + "findings": [ + {"rule": "impossible-defense", "file": "src/a.tsx", "line": 3, "column": 5, "endLine": 3, "message": "`x ?? 1` is dead"}, + {"rule": "impossible-defense", "file": "src/a.tsx", "line": 8, "column": 5, "endLine": 8, "message": "`y ?? 2` is dead"}, + {"rule": "repeated-fork", "file": "src/a.tsx", "line": 10, "column": 3, "endLine": 14, "message": "forks on props.kind"}, + {"rule": "impossible-defense", "file": "src/b.ts", "line": 1, "column": 1, "endLine": 1, "message": "`z?.w` is dead"}, + ], + "unplacedDefenses": 0, + "markdown": "# Data flow\n", + } + ) + + +def _tree() -> dict: + file = lambda name: {"name": name, "type": "file", "path": f"{ROOT}/src/{name}", "metrics": {}} # noqa: E731 + return { + "name": "repo", + "type": "folder", + "path": ROOT, + "metrics": {}, + "children": [ + {"name": "src", "type": "folder", "path": f"{ROOT}/src", "metrics": {}, "children": [file("a.tsx"), file("b.ts"), file("c.tsx"), file("d.py")]} + ], + } + + +def test_overlay_counts_sum_paths_max_and_unanalyzed_ts_is_na(): + tree = signals.apply_to_tree(_tree(), signals.Signals(ROOT, "ok", result=_result())) + a, b, c, py = tree["children"][0]["children"] + assert a["metrics"]["dataflow_impossible_defenses"] == 2 + assert a["metrics"]["dataflow_repeated_forks"] == 1 + assert c["metrics"]["dataflow_impossible_defenses"] is None + assert "Not in the data-flow program" in c["metrics"]["na_reasons"]["dataflow_path_depth"] + assert "dataflow_path_depth" not in py["metrics"] + folder = tree["children"][0]["metrics"] + assert folder["dataflow_impossible_defenses"] == 3 + assert folder["dataflow_repeated_forks"] == 1 + assert (folder["dataflow_path_depth"], folder["dataflow_relay_hops"]) == (9, 3) + assert tree["dataflow"] == {"status": "ok", "reason": ""} + + +def test_overlay_names_why_the_engine_did_not_run(): + tree = signals.apply_to_tree(_tree(), signals.Signals(ROOT, "na", "Node.js was not found")) + a = tree["children"][0]["children"][0] + assert a["metrics"]["dataflow_impossible_defenses"] is None + assert a["metrics"]["na_reasons"]["dataflow_impossible_defenses"] == "Node.js was not found" + + +def test_marks_match_the_counts(): + found = signals.Signals(ROOT, "ok", result=_result()) + marks = signals.markers_for(f"{ROOT}/src/a.tsx", found) + values = found.per_file()[f"{ROOT}/src/a.tsx"] + assert len(marks["dataflow_impossible_defenses"]) == values["dataflow_impossible_defenses"] + assert len(marks["dataflow_repeated_forks"]) == values["dataflow_repeated_forks"] + assert marks["dataflow_repeated_forks"][0] == {"line": 10, "end_line": 14, "note": "dataflow repeated-fork: forks on props.kind"} + + +def test_report_dataflow_writes_dataflow_md(tmp_path: Path, monkeypatch): + root = tmp_path / "app" + (root / "src").mkdir(parents=True) + (root / "src" / "a.tsx").write_text("export const A = () =>
{1}
;\n") + asked = [] + + def fake_collect(path, **_kwargs): + asked.append(path) + return signals.Signals(str(path), "ok", result=_result()) + + monkeypatch.setattr(signals, "collect", fake_collect) + written = reporting.write_report(root, tmp_path / "out", verbose=False, dataflow=True) + assert written["dataflow"].read_text() == "# Data flow\n" + report = written["report"].read_text() + assert "## Data flow" in report and "| impossible-defense | `src/a.tsx:3` |" in report + assert asked == [root.resolve()] + + plain = reporting.write_report(root, tmp_path / "plain", verbose=False) + assert "dataflow" not in plain + assert len(asked) == 1