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
12 changes: 12 additions & 0 deletions docs/dataflow-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,18 @@ The work came from the data-flow experience audit (October 2026). The audit trac
- State: a zustand store (a `store` row) holds what its function returns and what its `set` receives; a selector reads the field it names, and calling a member read through the hook (`setCount` after `useStore((s) => s.setCount)`) runs the store's function, never the selector it is written beside. a setter's value reaches its getter's reads (#182); a function handed to a setter (`setCount((c) => c + step)`, a store path's `setState("todos", (list) => […])`) stands for what it returns, and its parameter is the current state; a Solid store path (`setStore("left", "title", v)`) writes `left.title` alone, so a sibling field never sees it, an updater there (inline or named) receives that field, not the whole store, and a predicate in the path (`(item) => item.id === id`) is a test, never stored; a store or signal's initial value seeds it field by field, so `createStore({ left, right })` keeps `left` and `right` apart; a state-pair row marked `lazy` (React's `useState`) calls a function initial value, and Solid's `createSignal` holds it; a `useReducer` dispatch binds the reducer's action, and the reducer's return is the state; state-pair factory and getter calls are framework-modelled (#188), modelled in the collector (#196).
- Ends: a binding every read of which decides a branch (`if (forgotten)` in nested branches, `ready && <X />`, `<Show when={isVisible()}>`, through `!` or an accessor's call) ends at its binding, decides a branch. A parameter or local binding the program never reads (`_level`, `const { isSuccess } = useQuery()`) ends there, named "never read": the checker proves the value goes nowhere, so the trace is `ok`, not a dead end; the value-flow ledger draws every in-place end (a branch test, a write, never read) as a terminal row, as the graph does. A service write or read is a method on a client's contract, or a function-valued field a declaration file declares (a generated client's); a callback prop the project declares (`props.save(x)`) is never one. A thrown value ends at the throw (#207). An exported value that nothing in the program reads ends at its export, the module's API, not at a dead end; a call through a callback an export nothing in the program calls was handed (`onSeen(id)`, `props.onPick(x)` in a component nothing renders) ends there too, at the module's API, never a library method on a parameter (`items.forEach`); one the program reads, by name or through `import * as`, walks on to that read. A function handed to a timer (`setTimeout`, `requestAnimationFrame`) ends there: the callback runs later. A function handed to a page element as a handler (`<button onClick={click}>`) is not an escape: the page drops what it returns. A trace whose anchor has nothing beyond it names a stop at the anchor. A context `Provider`'s `value` goes to its readers, never into the page. A request ends a forward trace where it is sent, and a backward trace lands at the request a response came from: neither stops at the response body. A promise chain the code drops (`load().then(show);`) ends there. A function library code hands to a callback (`resolve` in `new Promise((resolve) => …)`) hands its argument back to the call that supplied it: the value reaches that call's value, and the call through it ends there, handed back. A DOM call the code makes for its effect (`el.classList.add(x);`, `target.dispatchEvent(e);`, `() => input?.focus()`) is a page write: any member TypeScript's DOM lib declares, whose value the code drops. A DOM call whose value the code uses (`root.querySelector(sel)`) carries on. An arrow whose body is an optional void call returns nothing. `response.json()` on a `fetch` result reads the body; only a server's response is an HTTP response. An emitter's `emit("name", x)` binds each listener its receiver registered with `on("name", fn)`, and `yield* list` hands on `list`'s elements. A return that is a call (`yield items.slice(…)`, an arrow's `() => f(x)`) is judged by its own function's call sites, never the call's, so an exported generator no code iterates ends at its return. A class's annotated uses fold by file (#208). A `when` on Solid's `Show` or `Match` ends as "decides a branch", not a DOM attribute.

## Symbol view of an anchor trace

The symbol view is the default drawing of an anchor trace. `?model=steps` (the Steps toggle in `FlowTools.tsx`) keeps the old one-box-per-step view.

- One box per symbol. Boxes merge by scope and checker symbol id, which the anchor-graph contract carries as `symbol` and `field`, never by label. A node with no symbol keeps its own box. A merged edge keeps every original proof. On visual-notes' DocView this cut 557 boxes to 225.
- The anchor-graph contract is the one seam: `engine/src/srcly/contracts/anchor-graph.ts` feeds `client/src/viz/deps/flow/anchorAdapter.ts`. Each fact the view needs (symbol, operation, `symbolKind`, frame `role`, links) is an additive field on it.
- Value flow is the bold main line, with its operation named on the edge. Calls, reads and writes are thin links that can be toggled.
- `symbolKind` (state, transform, origin, end, plain) carries the strong color. Frames stay neutral and name their role: component, hook, helper, handler, fetcher, server or unknown. Roles live in `engine/src/srcly/scope-roles.ts`, never in `engine/src/analysis`. Unknown is never drawn as a component.
- The first screen is the main path from origins to ends. Side branches are stubs that grow with `+` and `−` or the depth control (1, 2, 3, all) in `depth.ts`. Depth is in the URL and the view-state registry.
- Plain TypeScript modules with no routes or components are an equal target.
- Tune the view on `engine/examples/symbol-graph/`. Use a large app such as visual-notes to check scale and find engine errors.

## Python type source

A Python root uses the same engine contracts as TypeScript. `engine/python/srcly_pyfacts.py` provides the evidence. The engine runs it once per generation.
Expand Down
16 changes: 16 additions & 0 deletions docs/initiative-history.json
Original file line number Diff line number Diff line change
Expand Up @@ -184,5 +184,21 @@
"Not built: a model passed to a serializer (model_validate, jsonable_encoder) as a use of its class. Nothing tracks it.",
"Not built for Python: following values across methods through instance state (self.x = ...). Partly tracked as pgm task-writers-of-a-model-field."
]
},
{
"title": "Show the logic, not only the components, in TS/TSX data flow",
"slug": "dataflow-logic-visibility",
"outcome": "completed",
"retired_at": "2026-11-12",
"summary": "Anchor traces in TS/TSX data flow now draw one box per symbol, name what happens along each edge, color symbols by kind, give frames a role, open on the main path and grow by depth, and link functions to what they call, read and write. Reconciled against origin/main 0bfb05ba.",
"reason": "All five milestones merged on 2026-10-29 (#268, #272, #274, #278, #279).",
"documentation": [
"docs/dataflow-coverage.md"
],
"revision": "0bfb05ba",
"follow_ups": [
"Run audit round 3 on visual-notes against the symbol view. Nothing tracks it.",
"Below the cut line and not built: a types overlay, the symbol view in the Components lens, Python frame roles. Hub summaries are tracked as pgm task-hub-summaries-for-size-limited-slices."
]
}
]
127 changes: 0 additions & 127 deletions docs/intent/dataflow-logic-visibility/implementation-plan.md

This file was deleted.

Loading
Loading