diff --git a/client/src/dataflow/effectsModel.test.ts b/client/src/dataflow/effectsModel.test.ts index 270998bc..abb860d2 100644 --- a/client/src/dataflow/effectsModel.test.ts +++ b/client/src/dataflow/effectsModel.test.ts @@ -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"); diff --git a/client/src/dataflow/effectsModel.ts b/client/src/dataflow/effectsModel.ts index dcfe102b..f97f2f9d 100644 --- a/client/src/dataflow/effectsModel.ts +++ b/client/src/dataflow/effectsModel.ts @@ -37,6 +37,7 @@ export const HANDLING_WORDS: Record = { "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", @@ -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, diff --git a/docs/dataflow-coverage.md b/docs/dataflow-coverage.md index bef935a7..1e7e040f 100644 --- a/docs/dataflow-coverage.md +++ b/docs/dataflow-coverage.md @@ -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. diff --git a/engine/examples/effects-basics/src/cases.ts b/engine/examples/effects-basics/src/cases.ts index 7c9d10b1..74fd4e5c 100644 --- a/engine/examples/effects-basics/src/cases.ts +++ b/engine/examples/effects-basics/src/cases.ts @@ -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; +} diff --git a/engine/src/analysis/effects/function-effects.ts b/engine/src/analysis/effects/function-effects.ts index c4819ccf..bd74c044 100644 --- a/engine/src/analysis/effects/function-effects.ts +++ b/engine/src/analysis/effects/function-effects.ts @@ -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.", @@ -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."); @@ -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 | undefined; + const reboundParameters = () => { + if (rebound) return rebound; + const writes = new Set(); + 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) { diff --git a/engine/test/srcly/function-effects.test.ts b/engine/test/srcly/function-effects.test.ts index 3aa90c93..51e15c92 100644 --- a/engine/test/srcly/function-effects.test.ts +++ b/engine/test/srcly/function-effects.test.ts @@ -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"; @@ -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) }); @@ -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", () => {