pipework 0.8.1 → 0.8.4

package/dist/trace/cardinality/classify-edge.js

@@ -0,0 +1,27 @@
+// Structural cardinality verdict for one declared `@downstream` edge: locate
+// the edge's call sites in the flow-step body and decide whether the edge is a
+// plain `step`, a `branch` (a single call site reached through a loop, an
+// iteration method, a fan-out, or recursion), or `ambiguous` — reached through
+// indirection the analyzer cannot follow. See PLAN.tracing.md, Q1.
+import { findCallSites } from './branch-context.js';
+/** Classifies one `@downstream` edge of `site` against the flow-step body. */
+export function classifyEdge(file, site, edge) {
+    const from = site.subject.name;
+    const base = { file, from, edge };
+    const body = site.subject.body;
+    if (body === null) {
+        // An orphan annotation — no function body to walk. The `flow` check owns
+        // the diagnostic; here the edge is simply unresolvable.
+        return { ...base, structural: 'ambiguous', branchKind: null, line: null };
+    }
+    const sites = findCallSites(body, from, edge.symbol);
+    if (sites.length === 0) {
+        return { ...base, structural: 'ambiguous', branchKind: null, line: null };
+    }
+    const branching = sites.find(s => s.branchKind !== null);
+    if (branching !== undefined) {
+        return { ...base, structural: 'branch', branchKind: branching.branchKind, line: branching.line };
+    }
+    return { ...base, structural: 'step', branchKind: null, line: sites[0].line };
+}
+//# sourceMappingURL=classify-edge.js.map

package/dist/trace/cardinality/classify-edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classify-edge.js","sourceRoot":"","sources":["../../../src/trace/cardinality/classify-edge.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,+EAA+E;AAC/E,0EAA0E;AAC1E,+EAA+E;AAC/E,mEAAmE;AAInE,OAAO,EAAE,aAAa,EAAmB,MAAM,qBAAqB,CAAA;AA6BpE,8EAA8E;AAC9E,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,IAAkB,EAClB,IAAoB;IAEpB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC9B,MAAM,IAAI,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAEjC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC9B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,yEAAyE;QACzE,wDAAwD;QACxD,OAAO,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC3E,CAAC;IAED,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACpD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC3E,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,IAAI,CAAC,CAAA;IACxD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,CAAA;IAClG,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAA;AAChF,CAAC"}

package/dist/trace/cardinality/structural-max.d.ts

@@ -0,0 +1,14 @@
+/** One `step` edge of the flow graph, both endpoints as `path:symbol` node ids. */
+export interface StepEdge {
+    readonly from: string;
+    readonly to: string;
+}
+export interface StructuralMax {
+    /** Longest chain of `step` edges through the graph, counted in nodes. */
+    readonly value: number;
+    /** Every `step`-edge cycle found — each a ring of `path:symbol` node ids. */
+    readonly cycles: readonly (readonly string[])[];
+}
+/** Longest `step`-edge chain across the flow graph, plus any `step`-edge cycles. */
+export declare function computeStructuralMax(nodeIds: readonly string[], edges: readonly StepEdge[]): StructuralMax;
+//# sourceMappingURL=structural-max.d.ts.map

package/dist/trace/cardinality/structural-max.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-max.d.ts","sourceRoot":"","sources":["../../../src/trace/cardinality/structural-max.ts"],"names":[],"mappings":"AAWA,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAChD;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,SAAS,QAAQ,EAAE,GACzB,aAAa,CAqCf"}

package/dist/trace/cardinality/structural-max.js

@@ -0,0 +1,83 @@
+// The Q7 step-cap derivation. Once batching is forced to branch, a single
+// trace's step count is bounded by the static flow graph: a `branch` edge
+// opens a *child* trace, so only `step` edges extend the current one.
+// `structuralMax` is the longest chain of `step` edges, counted in nodes.
+//
+// A cycle of `step` edges is unbounded — and a bug. A direct self-call is
+// caught as recursion by branch-context, but *mutual* recursion (A step-calls
+// B, B step-calls A) is invisible to single-function analysis; it surfaces
+// here as a `step`-edge cycle. One of the edges that close the loop should
+// have been a branch. See PLAN.tracing.md, Q7.
+/** Longest `step`-edge chain across the flow graph, plus any `step`-edge cycles. */
+export function computeStructuralMax(nodeIds, edges) {
+    const adjacency = buildAdjacency(nodeIds, edges);
+    const longest = new Map();
+    const visiting = new Set();
+    const cycles = [];
+    function dfs(node, stack) {
+        const cached = longest.get(node);
+        if (cached !== undefined)
+            return cached;
+        if (visiting.has(node)) {
+            // Back-edge: record the ring and treat this edge as contributing nothing,
+            // so the walk terminates. The node's own length is left uncached.
+            cycles.push([...stack.slice(stack.indexOf(node)), node]);
+            return 0;
+        }
+        visiting.add(node);
+        stack.push(node);
+        let best = 0;
+        // `node` is always an adjacency key — it came from `keys()` or from a
+        // neighbour set, and `buildAdjacency` ensures every endpoint is a key.
+        for (const target of adjacency.get(node)) {
+            best = Math.max(best, dfs(target, stack));
+        }
+        stack.pop();
+        visiting.delete(node);
+        const result = 1 + best;
+        longest.set(node, result);
+        return result;
+    }
+    let value = 0;
+    for (const node of adjacency.keys()) {
+        value = Math.max(value, dfs(node, []));
+    }
+    return { value, cycles: dedupeCycles(cycles) };
+}
+/**
+ * The `step`-edge adjacency of the flow graph. Every analyzed flow step is a
+ * node; a `step` edge to a target that is not itself an analyzed flow step
+ * still adds that target as a terminal node, so the cap stays an upper bound.
+ */
+function buildAdjacency(nodeIds, edges) {
+    const adjacency = new Map();
+    const ensure = (id) => {
+        let targets = adjacency.get(id);
+        if (targets === undefined) {
+            targets = new Set();
+            adjacency.set(id, targets);
+        }
+        return targets;
+    };
+    for (const id of nodeIds)
+        ensure(id);
+    for (const { from, to } of edges) {
+        ensure(to);
+        ensure(from).add(to);
+    }
+    return adjacency;
+}
+/** Collapses rotations and re-discoveries of the same ring to one entry each. */
+function dedupeCycles(cycles) {
+    const seen = new Map();
+    for (const cycle of cycles) {
+        // Drop the repeated closing node, then rotate so the smallest id leads —
+        // a canonical form shared by every rotation and rediscovery of the ring.
+        const ring = cycle.slice(0, -1);
+        const pivot = ring.indexOf([...ring].sort()[0]);
+        const canonical = [...ring.slice(pivot), ...ring.slice(0, pivot)];
+        seen.set(canonical.join(' '), canonical);
+    }
+    return [...seen.values()];
+}
+//# sourceMappingURL=structural-max.js.map

package/dist/trace/cardinality/structural-max.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-max.js","sourceRoot":"","sources":["../../../src/trace/cardinality/structural-max.ts"],"names":[],"mappings":"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"}

package/dist/trace/check/coverage-check.d.ts

@@ -0,0 +1,20 @@
+import { type IoKind } from './io-pattern.js';
+export interface CoverageViolation {
+    readonly rule: string;
+    readonly file: string;
+    readonly line: number;
+    readonly message: string;
+}
+export interface CoverageCheckResult {
+    readonly violations: readonly CoverageViolation[];
+    readonly scanned: number;
+}
+/**
+ * Tier-2 coverage check across `sourceFiles` (paths relative to `cwd`).
+ *
+ * `extras` extends the stock pipework I/O registry with consumer-declared
+ * patterns from `config.trace.io`. Defaults to empty — the stock registry
+ * (`pipe.*` writes, `pipe(...)`-chain reads) is always live.
+ */
+export declare function checkCoverage(cwd: string, sourceFiles: readonly string[], extras?: Readonly<Record<string, IoKind>>): CoverageCheckResult;
+//# sourceMappingURL=coverage-check.d.ts.map

package/dist/trace/check/coverage-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-check.d.ts","sourceRoot":"","sources":["../../../src/trace/check/coverage-check.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAEzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAA;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAUD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAC5C,mBAAmB,CAiErB"}

package/dist/trace/check/coverage-check.js

@@ -0,0 +1,146 @@
+// Tier-2 coverage check (Q9): every I/O call site is inside a `@flow_step`,
+// and a flow_step performs at most one I/O — at most one write, in particular.
+// Without this, the trace is gap-prone by construction: an unannotated read or
+// write goes silently untraced and the build doesn't notice.
+//
+// Ships as warning (Phase 6f): violations are surfaced but do not fail
+// `pipework check`. Once the consumer corpus has been migrated, Phase 7a
+// flips it to an error.
+//
+// Two rules:
+//   - flow/io-outside-flow-step — an I/O call appears outside any annotated
+//     flow_step function. The runtime can't open a `trace_step` for it.
+//   - flow/multi-io-per-flow-step — a flow_step body contains more than one
+//     I/O call. Split it so each I/O is its own step. The stricter variant,
+//     more than one *write* in the same step, is reported as
+//     flow/multi-write-per-flow-step — surfaces the Q8 one-write-per-step
+//     rule with its own diagnostic.
+//
+// Lexical: I/O inside a nested closure inside a flow_step body still counts
+// as "inside the flow_step" — otherwise writes hide inside callbacks. The
+// cardinality analyzer's "don't follow nested closures" convention is the
+// opposite default, by design (Q1 vs Q9).
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from '@typescript-eslint/parser';
+import { collectFlowStepSites, isNode } from './flow-step-site.js';
+import { classifyIo } from './io-pattern.js';
+/**
+ * Tier-2 coverage check across `sourceFiles` (paths relative to `cwd`).
+ *
+ * `extras` extends the stock pipework I/O registry with consumer-declared
+ * patterns from `config.trace.io`. Defaults to empty — the stock registry
+ * (`pipe.*` writes, `pipe(...)`-chain reads) is always live.
+ */
+export function checkCoverage(cwd, sourceFiles, extras = {}) {
+    const violations = [];
+    let scanned = 0;
+    for (const file of sourceFiles) {
+        const abs = join(cwd, file);
+        if (!existsSync(abs))
+            continue;
+        let program = null;
+        let sites = [];
+        try {
+            program = parseProgram(readFileSync(abs, 'utf-8'));
+            sites = collectFlowStepSites(readFileSync(abs, 'utf-8'));
+        }
+        catch {
+            // Unparseable — leave syntax errors to the type checker.
+            continue;
+        }
+        scanned++;
+        const ioSites = collectIoSites(program, extras);
+        const flowStepRanges = collectFlowStepRanges(sites);
+        for (const io of ioSites) {
+            const enclosing = flowStepRanges.find(r => io.start >= r.bodyStart && io.start < r.bodyEnd);
+            if (enclosing === undefined) {
+                violations.push({
+                    rule: 'flow/io-outside-flow-step',
+                    file,
+                    line: io.line,
+                    message: `I/O ${io.kind} is outside any @flow_step. Wrap it in a standalone function and ` +
+                        `annotate that function with @flow_step so the runtime can open a trace_step for it.`,
+                });
+            }
+        }
+        for (const range of flowStepRanges) {
+            const inside = ioSites.filter(s => s.start >= range.bodyStart && s.start < range.bodyEnd);
+            if (inside.length <= 1)
+                continue;
+            const writes = inside.filter(s => s.kind === 'write');
+            if (writes.length > 1) {
+                violations.push({
+                    rule: 'flow/multi-write-per-flow-step',
+                    file,
+                    line: range.line,
+                    message: `@flow_step "${range.name}" performs ${String(writes.length)} writes. A flow_step ` +
+                        `may perform at most one write (Q8). Split each write into its own flow_step.`,
+                });
+                continue;
+            }
+            violations.push({
+                rule: 'flow/multi-io-per-flow-step',
+                file,
+                line: range.line,
+                message: `@flow_step "${range.name}" performs ${String(inside.length)} I/O calls. A flow_step ` +
+                    `may perform at most one I/O call. Split each call into its own flow_step.`,
+            });
+        }
+    }
+    return { violations, scanned };
+}
+function collectFlowStepRanges(sites) {
+    const ranges = [];
+    for (const site of sites) {
+        const body = site.subject.body;
+        if (body === null)
+            continue;
+        ranges.push({
+            name: site.subject.name,
+            line: site.subject.line,
+            bodyStart: body.range[0],
+            bodyEnd: body.range[1],
+        });
+    }
+    return ranges;
+}
+function collectIoSites(program, extras) {
+    const out = [];
+    walk(program, node => {
+        if (node.type !== 'CallExpression')
+            return;
+        const kind = classifyIo(node, extras);
+        if (kind === null)
+            return;
+        out.push({ kind, line: node.loc.start.line, start: node.range[0] });
+    });
+    return out;
+}
+const SKIP_KEYS = new Set(['loc', 'range', 'parent']);
+function walk(node, visit) {
+    visit(node);
+    for (const key of Object.keys(node)) {
+        if (SKIP_KEYS.has(key))
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (isNode(item))
+                    walk(item, visit);
+            }
+        }
+        else if (isNode(value)) {
+            walk(value, visit);
+        }
+    }
+}
+function parseProgram(code) {
+    return parse(code, {
+        range: true,
+        loc: true,
+        comment: true,
+        sourceType: 'module',
+    });
+}
+//# sourceMappingURL=coverage-check.js.map

package/dist/trace/check/coverage-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-check.js","sourceRoot":"","sources":["../../../src/trace/check/coverage-check.ts"],"names":[],"mappings":"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"}

package/dist/trace/check/flow-check.d.ts

@@ -0,0 +1,13 @@
+export interface FlowViolation {
+    readonly rule: string;
+    readonly file: string;
+    readonly line: number;
+    readonly message: string;
+}
+export interface FlowCheckResult {
+    readonly violations: readonly FlowViolation[];
+    readonly scanned: number;
+}
+/** Validates every `@flow_step` annotation in `sourceFiles` (paths relative to `cwd`). */
+export declare function checkFlowAnnotations(cwd: string, sourceFiles: readonly string[]): FlowCheckResult;
+//# sourceMappingURL=flow-check.d.ts.map

package/dist/trace/check/flow-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-check.d.ts","sourceRoot":"","sources":["../../../src/trace/check/flow-check.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,eAAe,CAuBjG"}

package/dist/trace/check/flow-check.js

@@ -0,0 +1,82 @@
+// The `flow` check: validates `@flow_step` annotations across a set of source
+// files. This is the syntactic tier — it rejects what is locally wrong about an
+// annotation without consulting the call graph. Three rules:
+//
+//   - a `@flow_step` block must document a standalone function, not a method;
+//   - every `@downstream` must declare its cardinality (`step` | `branch`);
+//   - the annotation must parse.
+//
+// Cardinality is *correct* only relative to the call graph — that is the
+// cardinality analyzer's job, not this one. See PLAN.tracing.md, component 2.
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { collectFlowStepSites } from './flow-step-site.js';
+/** Validates every `@flow_step` annotation in `sourceFiles` (paths relative to `cwd`). */
+export function checkFlowAnnotations(cwd, sourceFiles) {
+    const violations = [];
+    let scanned = 0;
+    for (const file of sourceFiles) {
+        const abs = join(cwd, file);
+        if (!existsSync(abs))
+            continue;
+        let sites;
+        try {
+            sites = collectFlowStepSites(readFileSync(abs, 'utf-8'));
+        }
+        catch {
+            // Unparseable file — leave syntax errors to the type checker.
+            continue;
+        }
+        scanned++;
+        for (const site of sites) {
+            collectSiteViolations(file, site, violations);
+        }
+    }
+    return { violations, scanned };
+}
+function collectSiteViolations(file, site, out) {
+    const { subject, annotation, commentLine } = site;
+    if (subject.shape === 'orphan') {
+        out.push({
+            rule: 'flow/orphan-annotation',
+            file,
+            line: commentLine,
+            message: '@flow_step JSDoc is not attached to a function. A flow step must document a '
+                + 'standalone function declaration so it has a stable path:symbol identity.',
+        });
+    }
+    else if (subject.shape === 'method') {
+        out.push({
+            rule: 'flow/no-method-flow-step',
+            file,
+            line: subject.line,
+            message: `@flow_step on method "${subject.name}" — a method cannot be a flow step. It carries `
+                + `hidden "this" state, so the trace boundary is untrustworthy. Extract "${subject.name}" `
+                + 'into a standalone function.',
+        });
+    }
+    if (annotation.kind === 'invalid') {
+        for (const err of annotation.errors) {
+            out.push({
+                rule: 'flow/invalid-annotation',
+                file,
+                line: commentLine + err.line - 1,
+                message: err.message,
+            });
+        }
+        return;
+    }
+    for (const edge of annotation.annotation.downstream) {
+        if (edge.cardinality === null) {
+            out.push({
+                rule: 'flow/missing-cardinality',
+                file,
+                line: commentLine,
+                message: `@downstream ${edge.path}:${edge.symbol} is missing a cardinality. Add "step" or `
+                    + `"branch": @downstream ${edge.path}:${edge.symbol} branch. A branch is an edge `
+                    + 'traversed more than once (loop, batch, recursion, fan-out).',
+            });
+        }
+    }
+}
+//# sourceMappingURL=flow-check.js.map

package/dist/trace/check/flow-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-check.js","sourceRoot":"","sources":["../../../src/trace/check/flow-check.ts"],"names":[],"mappings":"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"}

package/dist/trace/check/flow-step-site.d.ts

@@ -0,0 +1,62 @@
+import { type FlowStepParseResult } from '@pipework/flow-step-parser';
+interface Position {
+    readonly line: number;
+    readonly column: number;
+}
+interface SourceLocation {
+    readonly start: Position;
+    readonly end: Position;
+}
+/** A structurally-typed ESTree node — enough to walk without a parser type dependency. */
+export interface AstNode {
+    readonly type: string;
+    readonly range: readonly [number, number];
+    readonly loc: SourceLocation;
+    readonly [key: string]: unknown;
+}
+/**
+ * How a `@flow_step`-annotated declaration is shaped.
+ *
+ * - `function` — a standalone function (declaration or a `const` bound to an
+ *   arrow / function expression). The only legal shape.
+ * - `method` — a class method, class field bound to a function, or object
+ *   literal method. Banned: a method carries hidden `this` state, so the trace
+ *   boundary is untrustworthy. See PLAN.tracing.md, Q3.
+ * - `orphan` — the JSDoc block documents no declaration the analyzer can see.
+ */
+export type FlowStepShape = 'function' | 'method' | 'orphan';
+export interface FlowStepSubject {
+    readonly shape: FlowStepShape;
+    /** Declared name, or `<anonymous>` / `<computed>` when none can be read. */
+    readonly name: string;
+    /** 1-based line of the declaration, or of the JSDoc block when orphaned. */
+    readonly line: number;
+    /** The declaration node, or `null` when orphaned. */
+    readonly node: AstNode | null;
+    /**
+     * The documented function's executable body — what the cardinality analyzer
+     * walks. `null` exactly when `node` is `null` (an orphan): every `function`
+     * and `method` subject resolves to a function with a body.
+     */
+    readonly body: AstNode | null;
+}
+export interface FlowStepSite {
+    /** Parsed content of the `@flow_step` JSDoc block — never `not-a-flow-step`. */
+    readonly annotation: Exclude<FlowStepParseResult, {
+        kind: 'not-a-flow-step';
+    }>;
+    /** The declaration the block documents, and how it is shaped. */
+    readonly subject: FlowStepSubject;
+    /** 1-based line where the `@flow_step` JSDoc block opens. */
+    readonly commentLine: number;
+}
+/**
+ * Parse `code` and return every `@flow_step` site it contains, in source order.
+ *
+ * Throws if `code` is not parseable — callers scanning many files should catch
+ * and skip, leaving syntax errors to the type checker.
+ */
+export declare function collectFlowStepSites(code: string): FlowStepSite[];
+export declare function isNode(value: unknown): value is AstNode;
+export {};
+//# sourceMappingURL=flow-step-site.d.ts.map

package/dist/trace/check/flow-step-site.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-step-site.d.ts","sourceRoot":"","sources":["../../../src/trace/check/flow-step-site.ts"],"names":[],"mappings":"AAOA,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAE9F,UAAU,QAAQ;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,UAAU,cAAc;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAA;IACxB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;CACvB;AAED,0FAA0F;AAC1F,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;IAC5B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAChC;AAaD;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE5D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,mBAAmB,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAA;IAC9E,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CA2BjE;AAgGD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAIvD"}

package/dist/trace/check/flow-step-site.js

@@ -0,0 +1,142 @@
+// Locates `@flow_step` annotation sites in a TypeScript source file: each site
+// pairs a parsed annotation with the declaration it documents and how that
+// declaration is shaped — a standalone function, a method, or nothing at all.
+// The `flow` check and the cardinality analyzer both build on this; it is the
+// one place that answers "where are the flow steps in this file".
+import { parse } from '@typescript-eslint/parser';
+import { parseFlowStepAnnotation } from '@pipework/flow-step-parser';
+/**
+ * Parse `code` and return every `@flow_step` site it contains, in source order.
+ *
+ * Throws if `code` is not parseable — callers scanning many files should catch
+ * and skip, leaving syntax errors to the type checker.
+ */
+export function collectFlowStepSites(code) {
+    const program = parse(code, {
+        range: true,
+        loc: true,
+        comment: true,
+        sourceType: 'module',
+    });
+    const candidates = [];
+    walk(program, node => {
+        const candidate = classify(node);
+        if (candidate !== null)
+            candidates.push(candidate);
+    });
+    candidates.sort((a, b) => a.node.range[0] - b.node.range[0]);
+    const sites = [];
+    for (const comment of program.comments) {
+        if (comment.type !== 'Block')
+            continue;
+        const annotation = parseFlowStepAnnotation(`/*${comment.value}*/`);
+        if (annotation.kind === 'not-a-flow-step')
+            continue;
+        sites.push({
+            annotation,
+            subject: subjectFor(comment, candidates),
+            commentLine: comment.loc.start.line,
+        });
+    }
+    return sites;
+}
+/** The declaration a `@flow_step` block documents: the nearest one that follows it. */
+function subjectFor(comment, candidates) {
+    const documented = candidates.find(c => c.node.range[0] >= comment.range[1]);
+    if (documented === undefined) {
+        return { shape: 'orphan', name: '<unknown>', line: comment.loc.start.line, node: null, body: null };
+    }
+    return {
+        shape: documented.shape,
+        name: documented.name,
+        line: documented.node.loc.start.line,
+        node: documented.node,
+        body: documented.body,
+    };
+}
+/** Classifies a node as a flow-step-able declaration, or `null` if it is not one. */
+function classify(node) {
+    switch (node.type) {
+        case 'FunctionDeclaration':
+            return { node, shape: 'function', name: readName(node['id']), body: bodyOf(node) };
+        case 'VariableDeclaration': {
+            const bound = functionBoundDeclarator(node);
+            if (bound === null)
+                return null;
+            return { node, shape: 'function', name: readName(bound['id']), body: bodyOf(bound['init']) };
+        }
+        case 'MethodDefinition':
+        case 'TSAbstractMethodDefinition':
+            return { node, shape: 'method', name: readName(node['key']), body: bodyOf(node['value']) };
+        case 'PropertyDefinition':
+        case 'TSAbstractPropertyDefinition':
+        case 'Property':
+            return isFunctionExpression(node['value'])
+                ? { node, shape: 'method', name: readName(node['key']), body: bodyOf(node['value']) }
+                : null;
+        default:
+            return null;
+    }
+}
+/** The executable `body` of a function node — a `BlockStatement` or, for a
+ * concise arrow, the returned expression. `null` when `fn` is not a function. */
+function bodyOf(fn) {
+    if (!isNode(fn))
+        return null;
+    const body = fn['body'];
+    return isNode(body) ? body : null;
+}
+/** The first declarator in a `VariableDeclaration` bound to a function, or `null`. */
+function functionBoundDeclarator(node) {
+    const declarations = node['declarations'];
+    if (!Array.isArray(declarations))
+        return null;
+    for (const declarator of declarations) {
+        if (isNode(declarator) && isFunctionExpression(declarator['init']))
+            return declarator;
+    }
+    return null;
+}
+function isFunctionExpression(value) {
+    return isNode(value)
+        && (value.type === 'ArrowFunctionExpression' || value.type === 'FunctionExpression');
+}
+function readName(keyOrId) {
+    if (!isNode(keyOrId))
+        return '<anonymous>';
+    switch (keyOrId.type) {
+        case 'Identifier':
+            return String(keyOrId['name']);
+        case 'PrivateIdentifier':
+            return `#${String(keyOrId['name'])}`;
+        case 'Literal':
+            return String(keyOrId['value']);
+        default:
+            return '<computed>';
+    }
+}
+const SKIP_KEYS = new Set(['loc', 'range', 'parent']);
+/** Depth-first visit of every node reachable from `node`, parents before children. */
+function walk(node, visit) {
+    visit(node);
+    for (const key of Object.keys(node)) {
+        if (SKIP_KEYS.has(key))
+            continue;
+        const value = node[key];
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (isNode(item))
+                    walk(item, visit);
+            }
+        }
+        else if (isNode(value)) {
+            walk(value, visit);
+        }
+    }
+}
+export function isNode(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.type === 'string';
+}
+//# sourceMappingURL=flow-step-site.js.map

package/dist/trace/check/flow-step-site.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-step-site.js","sourceRoot":"","sources":["../../../src/trace/check/flow-step-site.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,kEAAkE;AAElE,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAA;AACjD,OAAO,EAAE,uBAAuB,EAA4B,MAAM,4BAA4B,CAAA;AA2E9F;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,IAAI;QACX,GAAG,EAAE,IAAI;QACT,OAAO,EAAE,IAAI;QACb,UAAU,EAAE,QAAQ;KACrB,CAAuB,CAAA;IAExB,MAAM,UAAU,GAAgB,EAAE,CAAA;IAClC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;QACnB,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;QAChC,IAAI,SAAS,KAAK,IAAI;YAAE,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACpD,CAAC,CAAC,CAAA;IACF,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAE5D,MAAM,KAAK,GAAmB,EAAE,CAAA;IAChC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACvC,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO;YAAE,SAAQ;QACtC,MAAM,UAAU,GAAG,uBAAuB,CAAC,KAAK,OAAO,CAAC,KAAK,IAAI,CAAC,CAAA;QAClE,IAAI,UAAU,CAAC,IAAI,KAAK,iBAAiB;YAAE,SAAQ;QACnD,KAAK,CAAC,IAAI,CAAC;YACT,UAAU;YACV,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC;YACxC,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI;SACpC,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,uFAAuF;AACvF,SAAS,UAAU,CAAC,OAAoB,EAAE,UAAgC;IACxE,MAAM,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5E,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IACrG,CAAC;IACD,OAAO;QACL,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI;QACpC,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,IAAI,EAAE,UAAU,CAAC,IAAI;KACtB,CAAA;AACH,CAAC;AAED,qFAAqF;AACrF,SAAS,QAAQ,CAAC,IAAa;IAC7B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,qBAAqB;YACxB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAA;QACpF,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;YAC3C,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,IAAI,CAAA;YAC/B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;QAC9F,CAAC;QACD,KAAK,kBAAkB,CAAC;QACxB,KAAK,4BAA4B;YAC/B,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAA;QAC5F,KAAK,oBAAoB,CAAC;QAC1B,KAAK,8BAA8B,CAAC;QACpC,KAAK,UAAU;YACb,OAAO,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE;gBACrF,CAAC,CAAC,IAAI,CAAA;QACV;YACE,OAAO,IAAI,CAAA;IACf,CAAC;AACH,CAAC;AAED;iFACiF;AACjF,SAAS,MAAM,CAAC,EAAW;IACzB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5B,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,CAAC,CAAA;IACvB,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;AACnC,CAAC;AAED,sFAAsF;AACtF,SAAS,uBAAuB,CAAC,IAAa;IAC5C,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,CAAA;IACzC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC;QAAE,OAAO,IAAI,CAAA;IAC7C,KAAK,MAAM,UAAU,IAAI,YAAY,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,oBAAoB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,UAAU,CAAA;IACvF,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,MAAM,CAAC,KAAK,CAAC;WACf,CAAC,KAAK,CAAC,IAAI,KAAK,yBAAyB,IAAI,KAAK,CAAC,IAAI,KAAK,oBAAoB,CAAC,CAAA;AACxF,CAAC;AAED,SAAS,QAAQ,CAAC,OAAgB;IAChC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;QAAE,OAAO,aAAa,CAAA;IAC1C,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,YAAY;YACf,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;QAChC,KAAK,mBAAmB;YACtB,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAA;QACtC,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;QACjC;YACE,OAAO,YAAY,CAAA;IACvB,CAAC;AACH,CAAC;AAED,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;AAErD,sFAAsF;AACtF,SAAS,IAAI,CAAC,IAAa,EAAE,KAA2B;IACtD,KAAK,CAAC,IAAI,CAAC,CAAA;IACX,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAQ;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;QACvB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,MAAM,CAAC,IAAI,CAAC;oBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;aAAM,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC3B,KAAK,KAAK,IAAI;WACd,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CAAA;AAC7D,CAAC"}