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/dataflow-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ The work came from the data-flow experience audit (October 2026). The audit trac
- Receivers and keys: `bag["x"] = v` packs `v` under `x`, as `bag.x = v` does, and a read of `bag["y"]` takes only field `y`. A computed key (`bag[key] = v`) packs into some field, a `partial` step every read of `bag` may see. Assigning a setter the project declares (`cell.current = v`) runs it: `v` binds its parameter and `cell` its `this`. A member's state is still the class's, not one instance's.
- Call adapters: `f.call(t, a, b)`, `f.apply(t, [a, b])` (a list written out) and a call of what `f.bind(t, a)` returned run `f`, with `t` as its `this` and the arguments shifted into place, so an argument `f` drops reaches nothing. A value bound ahead (`this` or a leading argument of `bind`) enters `f`, but its return is not paired back to the later call: it stops at `unproven-handoff`.
- Contexts (`keyed` rows on `createContext` and `useContext`, `store: "providers"`): `useContext(Ctx)` gets the value of the nearest `Ctx` provider above the reader, or the `createContext` default where no provider is above it (`engine/src/analysis/program-evidence-context-ancestry.ts`). The walk goes out from the reader to its component or hook, and out from each place that one is rendered or called. A provider whose subtree has no reader supplies nothing. React 19's `<Ctx value>` is a provider too, never a DOM attribute or a component. The context object is not the value read. Where a mount is not known (an exported component nothing renders, a component handed on as a value, a render prop, a component that renders its own provider around children), every provider outside the components walked through, and the default, are candidates. A hook's one `useContext` call serves every caller, so each caller gets every value any caller may get. A context method resolves through a hook of the program's whose one return is the `useContext` call (`const cart = useCart()`, then `cart.add(x)`), and a context's value keeps its field path to the reader, so `cart.items` never sees what `add` takes. A state pair provided whole (`value={pair}` after `const pair = createSignal()`) gives a reader's element 1 as its setter and element 0 as its getter. Forward through a framework's state (a setter's write, then a getter's read) the walk is in no one call, as through a member's state, so it can leave the hook that read the context. Backward keeps the call stack, as before.
- Local callback props: a forward trace through a component’s prop call loads checker-matched JSX occurrences with that named prop on demand. It reuses the same occurrence-bound proof as the eager collector. An unresolved supplied callback does not gain any state or render edges.
- Reducers: a dispatch reached through a prop or a context runs the reducer as a direct one does. It used to write its argument straight into the state, so a reducer that ignores its action still showed the action in the render. A function given to a dispatch is an action: nothing calls it.
- DOM reads: a dropped `querySelector`, `closest` or `getAttribute` call is a read, not a page write. `engine/models/web.json` names the finite list. A DOM method it does not name keeps the old rule, and a project's own `querySelector` was never the page.
- Result cache: the engine fingerprint covers the library model rows, so a changed row misses the cache in a checkout and in a bundle.
Expand Down
10 changes: 7 additions & 3 deletions engine/src/analysis/program-evidence-collector-jsx-support.ts
Original file line number Diff line number Diff line change
Expand Up @@ -738,10 +738,14 @@ export class ProgramEvidenceCollectorJsxSupport extends ProgramEvidenceCollector
* is what that caller's own occurrences hand in, a few levels up.
*/
private handedProps(props: ReadonlyMap<string, readonly PendingComponentPropBinding[]>, ownerId: string, name: string, depth: number): { value: TypeScript.Node; paired: boolean; at?: TypeScript.Node }[] {
// The children a component's elements hand in are written where it is rendered: load those places.
const owner = name === "children" ? this.functionsById.get(ownerId) : undefined;
// A child partition can be collected before the caller that supplies its
// prop. Request those JSX sites; connectCalls retries with the new bindings.
const owner = this.functionsById.get(ownerId);
const named = owner ? functionNameNode(this.ts, owner.declaration as TypeScript.FunctionLikeDeclaration) : null;
if (named) this.requireReferences(named);
if (named) {
if (name === "children") this.requireReferences(named);
else this.requireComponentPropSites(named, name);
}
const children = name === "children" ? this.childFunctions.filter((item) => item.target === ownerId).map((item) => ({ value: item.value as TypeScript.Node, paired: true, at: item.at as TypeScript.Node })) : [];
return [...children, ...(props.get(ownerId) ?? []).flatMap((pending) => {
const value = pending.attribute.initializer && this.ts.isJsxExpression(pending.attribute.initializer) ? pending.attribute.initializer.expression : undefined;
Expand Down
1 change: 1 addition & 0 deletions engine/src/analysis/program-evidence-collector-support.ts
Original file line number Diff line number Diff line change
Expand Up @@ -312,6 +312,7 @@ export class ProgramEvidenceCollectorSupport {
protected bodyRoots(): readonly TypeScript.Node[] { return this.files; }
protected bodyCollected(_node: TypeScript.Node): boolean { return true; }
protected requireReferences(_node: TypeScript.Node): void {}
protected requireComponentPropSites(_name: TypeScript.Node, _prop: string): void {}
protected prepareComponentReceiver(_node: TypeScript.PropertyAccessExpression): void {}
protected shouldConnectCall(_call: CollectorCallInfo): boolean { return true; }
protected addReference(reference: CollectorReferenceInfo): void {
Expand Down
13 changes: 13 additions & 0 deletions engine/src/analysis/program-evidence-demand-collector.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,19 @@ export class ProgramEvidenceDemandCollector extends ProgramEvidenceCollector {
}
}

protected override requireComponentPropSites(name: TypeScript.Node, prop: string): void {
for (const reference of this.referenceCandidates(name, true)) {
this.checkCancellation();
let tag = reference;
while (this.ts.isPropertyAccessExpression(tag.parent) && tag.parent.name === tag) tag = tag.parent;
const opening = tag.parent;
if (!(this.ts.isJsxOpeningElement(opening) || this.ts.isJsxSelfClosingElement(opening)) || opening.tagName !== tag) continue;
if (!opening.attributes.properties.some((attribute) => this.ts.isJsxAttribute(attribute) && attribute.name.getText() === prop)) continue;
const root = this.partition(opening);
if (!this.roots.has(root)) this.requestedRoots.add(root);
}
}

protected override addFunction(node: TypeScript.FunctionLikeDeclaration, ownerId: string | null) {
const info = super.addFunction(node, ownerId);
this.returnsByFunction.defer(info.id, () => {
Expand Down
66 changes: 66 additions & 0 deletions engine/test/srcly/on-demand-evidence.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it, vi } from "vitest";
import { CompactRelationIndex } from "../../src/analysis/program-evidence-connector-index";
import { ProgramEvidenceCollector } from "../../src/analysis/program-evidence-collector";
Expand Down Expand Up @@ -205,6 +206,71 @@ describe("on-demand evidence parity", () => {
}
}, 30_000);

describe("React search callback", () => {
// Use the catalog's actual source; the shim supplies only the checker
// inputs exercised here, so the engine's test needs no React installation.
const catalog = fileURLToPath(new URL("../../examples/pattern-catalog/react/src/state.tsx", import.meta.url));
const state = fs.readFileSync(catalog, "utf8");
const react = `declare module "react" {
export function useState<T>(initial: T): [T, (next: T | ((previous: T) => T)) => void];
}`;
const searchValue = "e.target.value";
const queryFor = (root: string) => {
// The file has other input handlers with the same expression.
const trace = `props.onQuery(${searchValue})`;
const query = expressionQuery(root, "state.tsx", trace, "forward");
const column = query.span.startColumn + trace.indexOf(searchValue);
return { ...query, span: { ...query.span, startColumn: column, endColumn: column + searchValue.length } };
};

it("matches eager forward proof in a cold and shuffled session", () => {
const root = fixture({
"state.tsx": state,
"react.d.ts": react,
"other.ts": `export function unrelated(input: string) { return input.trim(); }`,
});
try {
const query = queryFor(root);
const cold = sessionFor(root);
const demand = anchorGraphOp(cold, query);
const eager = anchorGraphOp(eagerSessionFor(root), query);
expect(eager.outcome).toBe("ok");
expect(eager.nodes.some((node) => node.elementKind === "render-terminal" && node.label === "query")).toBe(true);
expect(eager.edges.flatMap((edge) => edge.proof)).toContainEqual(expect.objectContaining({
kind: "bound-handler",
detail: expect.stringContaining("setter handed in at setQuery"),
}));
expect(demand).toEqual(eager);
const stats = requireTypescript(cold.tier1(), "callback demand test").provider().getInstrumentation();
expect(stats.totalExpansionSourceFilesVisited).toBe(1);
expect(stats.totalExpansionPartitionsVisited).toBeLessThan(6);
const shuffled = sessionFor(root);
anchorGraphOp(shuffled, expressionQuery(root, "other.ts", "input.trim()", "forward"));
expect(anchorGraphOp(shuffled, query)).toEqual(eager);
} finally {
fs.rmSync(root, { recursive: true, force: true });
}
}, 30_000);

it("keeps a frontier for a genuinely unresolved supplied callback", () => {
const root = fixture({
"state.tsx": state.replace("onQuery={setQuery}", "onQuery={externalHandler()}") + `\ndeclare function externalHandler(): (q: string) => void;\n`,
"react.d.ts": react,
"other.tsx": `function Search(props: { onQuery: (q: string) => void }) { return <p>not the same component</p>; }
export function Other() { return <Search onQuery={(value) => console.log(value)} />; }`,
});
try {
const { demand, eager } = compareWithEager(root, queryFor(root));
expect(demand).toEqual(eager);
expect(demand.outcome).toBe("partial");
expect(demand.nodes.some((node) => node.kind === "frontier")).toBe(true);
expect(demand.nodes.some((node) => node.elementKind === "render-terminal" || node.file === "other.tsx")).toBe(false);
} finally {
fs.rmSync(root, { recursive: true, force: true });
}
}, 30_000);
});

it("matches eager traces from a provider to a separate context consumer", () => {
const root = fixture({
"solid-js.d.ts": `declare module "solid-js" { export function createContext<T>(value: T): { Provider: (props: { value: T; children?: unknown }) => unknown }; export function useContext<T>(context: { Provider: unknown }): T; }\n`,
Expand Down
Loading