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
5 changes: 5 additions & 0 deletions client/src/dataflow/effectsModel.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,11 @@ describe("the effects view", () => {
expect(closed.groups).toEqual([]);
});

it("does not imply closed coverage for a partial report without facts or listed frontiers", () => {
const partial = effectsView({ ...(effectsPartial as FunctionEffectsResult), facts: [], frontiers: [] });
expect(partial.headline).toBe("Partial analysis: no effects were confirmed");
});

it("words the via chain", () => {
expect(viaText([])).toBeNull();
expect(viaText([{ callable: "row", file: "a.tsx", line: 1 }, { callable: "stamp", file: "b.ts", line: 2 }])).toBe("via row › stamp");
Expand Down
5 changes: 4 additions & 1 deletion client/src/dataflow/effectsModel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ export const HANDLING_WORDS: Record<FunctionEffectsResult["resultHandling"][numb
export const FRONTIER_WORDS: Record<string, string> = {
"callback-parameter": "a callback the caller supplies",
"dynamic-dispatch": "a computed callee",
"receiver-ownership": "a receiver whose ownership is unknown",
"unresolved-callee": "a callee the checker cannot name",
recursion: "already on the call chain",
budget: "past the budget",
Expand Down Expand Up @@ -81,7 +82,9 @@ export function effectsView(result: FunctionEffectsResult): EffectsView {
result.coverage === "not-analyzed"
? "No function at this position"
: known === 0 && partial === 0
? "Closed: nothing it touches is visible from outside, under the assumptions below"
? result.coverage === "complete-for-supported-scope"
? "Closed: nothing it touches is visible from outside, under the assumptions below"
: "Partial analysis: no effects were confirmed"
: `${known} known effect${known === 1 ? "" : "s"}${partial ? ` · ${partial} place${partial === 1 ? "" : "s"} the analysis could not follow` : ""}`;
return {
callable: result.callable,
Expand Down
1 change: 1 addition & 0 deletions docs/dataflow-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ These came from the Python data-flow usability audit (`docs/research/python-data
## Engine structure

- Design rules, decisions, measurements and the batch evidence behind reports and the treemap (`fileSignals`): `docs/dataflow-engine.md`.
- Function effects follow bounded local `const` alias chains for modeled receiver mutations. A write through an unchanged parameter is reported; a fresh array literal or built-in array slice is not an outside write. When ownership cannot be determined (for example through a mutable alias or a field on a local object), the result names that gap instead of reporting the function as closed.
- `flowSignature` reduces each function of a file to line-free keys (origins, ends, origin→end pairs, parameter reads, effects, stops, status). `srcly compare --dataflow` diffs them as "Data-flow changes". Python has no parameter reads or effects (not measured), and a caller of a changed function is not re-traced.

- Every evidence kind is classified once in `engine/src/srcly/kinds.ts` (#200). Rules read traits, not lists of kind names.
Expand Down
31 changes: 31 additions & 0 deletions engine/examples/effects-basics/src/cases.ts
Original file line number Diff line number Diff line change
Expand Up @@ -140,3 +140,34 @@ export function fileRoundTrip(file: string) {
registry.push(file);
if (!text) throw new Error("empty");
}


// Effects ownership: const alias chains keep the caller's receiver.
export function constChainThenReverse(items: number[]) {
const same = items;
const sameAgain = (same);
sameAgain.reverse();
return sameAgain;
}

// Effects ownership: a mutable or reassigned binding is not a proof.
export function reassignedParameterThenSort(items: number[]) {
items = [];
const same = items;
same.sort();
return same;
}

export function mutableAliasThenSort(items: number[], replacement: number[], useReplacement: boolean) {
let same = items;
if (useReplacement) same = replacement;
same.sort();
return same;
}

// A fresh wrapper does not make an input stored inside it fresh.
export function wrappedInputThenSort(items: number[]) {
const box = { items };
box.items.sort();
return box;
}
82 changes: 77 additions & 5 deletions engine/src/analysis/effects/function-effects.ts
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ export const EFFECTS_BUDGET = { callables: 64, depth: 6 };

export const ASSUMPTIONS = [
"ECMAScript and DOM intrinsics (TypeScript's own lib) are taken as pure unless named here: console, fetch, timers, Promise, Date.now and Math.random are effects; Array.prototype.sort, push, splice, pop, shift, unshift, reverse and fill and Map and Set set, add, delete and clear write their receiver; a callback handed to map, filter, reduce, forEach, some, every or find runs at once.",
"An array literal or intrinsic Array/ReadonlyArray slice makes a fresh receiver under standard array behavior. Receiver ownership follows bounded local const aliases; other unresolved receiver origins stay partial.",
"A call that resolves to a declaration file outside the program is external: that it runs is a fact; what it does is not followed.",
"A function the callable returns or hands to another call runs later, if at all: its effects are latent.",
"Code after the first await runs once the function has yielded: its effects are after-await.",
Expand Down Expand Up @@ -237,11 +238,11 @@ export function analyzeFunctionEffects(ts: typeof TypeScript, program: TypeScrip
if (AMBIENT_INPUTS[name]) return fact("input", "ambient-read", name, `${name} reads ${AMBIENT_INPUTS[name]}.`);
const method = lastName(name);
if (ts.isPropertyAccessExpression(expression) && MODELLED_PURE.has(method) && place !== "none") return;
if (ts.isPropertyAccessExpression(expression) && MODELLED_RECEIVER_WRITES.has(method) && place !== "none") {
const receiver = receiverSymbol(expression.expression);
const target = receiver && parameters.has(receiver) ? "parameter" : receiver && isModuleLevel(receiver, moduleScope) ? "module" : "local";
if (target === "local") return;
push(out.facts, { id: nextId("fact"), family: "write", kind: `${target}-write`, label: clip(expression.getText(sourceFile)), detail: `${method} writes its receiver, ${target === "parameter" ? "a parameter the caller owns" : "module-level state"}.`, status: "proven", activation: act, via, witness, ...(target === "parameter" ? { param: parameterIndex(receiver!) } : {}) });
if (ts.isPropertyAccessExpression(expression) && MODELLED_RECEIVER_WRITES.has(method) && place === "intrinsic") {
const origin = receiverOrigin(expression.expression);
if (origin.kind === "fresh") return;
if (origin.kind === "unknown") return frontier("receiver-ownership", clip(expression.getText(sourceFile)), `${method} writes its receiver, but the analysis could not tell who owns it.`);
push(out.facts, { id: nextId("fact"), family: "write", kind: `${origin.kind}-write`, label: clip(expression.getText(sourceFile)), detail: `${method} writes its receiver, ${origin.kind === "parameter" ? "a parameter the caller owns" : "module-level state"}.`, status: "proven", activation: act, via, witness, ...(origin.kind === "parameter" ? { param: origin.index } : {}) });
return;
}
if (place === "none") return frontier("unresolved-callee", name, "The callee has no compiler-resolved symbol.");
Expand Down Expand Up @@ -269,6 +270,77 @@ export function analyzeFunctionEffects(ts: typeof TypeScript, program: TypeScrip
return node !== undefined && ts.isSourceFile(node);
};

// A binding can keep the same name while no longer denoting what the caller
// passed. Conservatively exclude any parameter rebound within this body.
let rebound: Set<TypeScript.Symbol> | undefined;
const reboundParameters = () => {
if (rebound) return rebound;
const writes = new Set<TypeScript.Symbol>();
const collectTarget = (target: TypeScript.Expression) => {
if (ts.isIdentifier(target)) {
const symbol = resolvedSymbol(target);
if (symbol && parameters.has(symbol)) writes.add(symbol);
} else if (ts.isParenthesizedExpression(target) || ts.isNonNullExpression(target) || ts.isAsExpression(target) || ts.isTypeAssertionExpression(target) || ts.isSpreadElement(target)) {
collectTarget(target.expression);
} else if (ts.isArrayLiteralExpression(target)) {
target.elements.forEach(collectTarget);
} else if (ts.isObjectLiteralExpression(target)) {
for (const property of target.properties) {
if (ts.isShorthandPropertyAssignment(property)) {
const symbol = checker.getShorthandAssignmentValueSymbol(property);
if (symbol && parameters.has(symbol)) writes.add(symbol);
} else if (ts.isPropertyAssignment(property)) collectTarget(property.initializer);
else if (ts.isSpreadAssignment(property)) collectTarget(property.expression);
}
} else if (ts.isBinaryExpression(target) && target.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
collectTarget(target.left);
}
};
const collect = (node: TypeScript.Node) => {
cancellation?.throwIfCancelled();
if (ts.isBinaryExpression(node) && isAssignment(ts, node.operatorToken.kind)) collectTarget(node.left);
if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
(node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken)) collectTarget(node.operand);
if ((ts.isForInStatement(node) || ts.isForOfStatement(node)) && !ts.isVariableDeclarationList(node.initializer)) collectTarget(node.initializer);
ts.forEachChild(node, collect);
};
const body = (fn as TypeScript.FunctionLikeDeclaration).body;
if (body) collect(body);
return rebound = writes;
};

const receiverOrigin = (expression: TypeScript.Expression): { kind: "parameter"; index: number } | { kind: "module" | "fresh" | "unknown" } => {
let current = unparen(ts, expression);
for (let depth = 0; depth <= 8; depth += 1) {
if (ts.isArrayLiteralExpression(current)) return { kind: "fresh" };
if (ts.isCallExpression(current) && ts.isPropertyAccessExpression(current.expression) && current.expression.name.text === "slice") {
const symbol = resolvedSymbol(current.expression.name);
if (placeOf(symbol) === "intrinsic" && (symbol?.declarations ?? []).every((d) => ts.isMethodSignature(d) && ts.isInterfaceDeclaration(d.parent) && ["Array", "ReadonlyArray"].includes(d.parent.name.text))) return { kind: "fresh" };
}
const symbol = receiverSymbol(current);
if (!symbol) break;
if (parameters.has(symbol)) {
const index = parameterIndex(symbol);
if (fn.parameters[index]?.dotDotDotToken || reboundParameters().has(symbol)) break;
return { kind: "parameter", index };
}
// Keep direct module receivers; captured prior values of mutable
// module bindings are not followed as local aliases.
if (isModuleLevel(symbol, moduleScope)) return { kind: depth === 0 ? "module" : "unknown" };
// Do not infer that a field of a fresh object is also fresh.
if (!ts.isIdentifier(current)) break;
const declaration = symbol.valueDeclaration;
if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer ||
!ts.isVariableDeclarationList(declaration.parent) || !(declaration.parent.flags & ts.NodeFlags.Const) ||
declaration.getSourceFile() !== sourceFile || declaration.getEnd() > current.getStart(sourceFile)) break;
let owner: TypeScript.Node = declaration.parent;
while (!ts.isFunctionLike(owner) && !ts.isSourceFile(owner)) owner = owner.parent;
if (owner !== fn) break;
current = unparen(ts, declaration.initializer);
}
return { kind: "unknown" };
};

const visit = (node: TypeScript.Node, activation: Activation) => {
cancellation?.throwIfCancelled();
if (ts.isFunctionLike(node) && node !== fn) {
Expand Down
29 changes: 26 additions & 3 deletions engine/test/srcly/function-effects.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import { freshSliceThenSort, inputAliasThenSort } from "../../examples/effects-basics/src/cases";
import type { FunctionEffectsResult } from "../../src/srcly/contracts/function-effects";
import { functionEffectsOp } from "../../src/srcly/ops/function-effects";
import { createEngineSession } from "../../src/srcly/session";
Expand All @@ -28,7 +29,7 @@ const summary = (r: FunctionEffectsResult) => ({
handling: r.resultHandling.map((h) => `${h.callee} ${h.handling}`),
});

describe("functionEffects on effects-basics (the 21 cases)", () => {
describe("functionEffects on effects-basics", () => {
const session = sessionFor(basics);
const effects = (marker: string) => functionEffectsOp(session, { file: "src/cases.ts", line: lineOf(basics, "src/cases.ts", marker) });

Expand All @@ -52,8 +53,30 @@ describe("functionEffects on effects-basics (the 21 cases)", () => {
});

it("5 and 6 sort writes a parameter, not a fresh slice", () => {
expect(summary(effects("export function freshSliceThenSort")).facts).toEqual([]);
expect(summary(effects("export function inputAliasThenSort")).facts).toEqual([]);
const original = [3, 1, 2];
expect(freshSliceThenSort(original)).not.toBe(original);
expect(original).toEqual([3, 1, 2]);
expect(inputAliasThenSort(original)).toBe(original);
expect(original).toEqual([1, 2, 3]);

const fresh = effects("export function freshSliceThenSort");
expect(fresh).toMatchObject({ outcome: "ok", facts: [], frontiers: [] });
const aliased = effects("export function inputAliasThenSort");
expect(aliased.frontiers).toEqual([]);
expect(aliased.facts).toHaveLength(1);
expect(aliased.facts[0]).toMatchObject({
kind: "parameter-write", status: "proven", activation: "direct", witness: { text: "same.sort()" },
});
});

it("preserves the parameter origin through const alias chains", () => {
const result = effects("export function constChainThenReverse");
expect(summary(result)).toEqual({ facts: ["parameter-write direct"], frontiers: [], handling: [] });
});

it.each(["reassignedParameterThenSort", "mutableAliasThenSort", "wrappedInputThenSort"])("reports unknown receiver ownership as partial for %s", (name) => {
const result = effects(`export function ${name}`);
expect(result).toMatchObject({ outcome: "partial", coverage: "partial", facts: [], frontiers: [{ reason: "receiver-ownership", witness: { text: expect.stringMatching(/\.sort\(\)$/) } }] });
});

it("7 and 8 a transitive parameter write is the caller's; a write to a fresh object is partial", () => {
Expand Down
Loading