pipework 0.252.0 → 0.253.0

package/src/trace/cardinality/analyze.ts

@@ -0,0 +1,173 @@
+// The cardinality analyzer. Given the `@flow_step` sites of a source set, it
+// classifies every `@downstream` edge structurally (classify-edge.ts), reports
+// the edges whose declared cardinality disagrees with the structure or whose
+// cardinality could not be resolved, and derives the Q7 `structuralMax` step
+// cap from the resulting graph. Pure over its inputs — file I/O lives in
+// check.ts. See PLAN.tracing.md, component 3.
+
+import type { FlowStepSite } from '../check/flow-step-site.js'
+import { classifyEdge, type EdgeClassification } from './classify-edge.js'
+import { computeStructuralMax, type StepEdge } from './structural-max.js'
+import type { BranchKind } from './branch-context.js'
+
+/** A `@flow_step` site paired with the source path it was found in. */
+export interface AnalyzerEntry {
+  /** Source path relative to `cwd` — the node-id prefix and the diagnostic file. */
+  readonly file: string
+  readonly site: FlowStepSite
+}
+
+export interface CardinalityViolation {
+  readonly rule: string
+  readonly file: string
+  readonly line: number
+  readonly message: string
+}
+
+export interface CardinalityResult {
+  /** Structural verdict for every `@downstream` edge across the input. */
+  readonly classifications: readonly EdgeClassification[]
+  readonly violations: readonly CardinalityViolation[]
+  /** The Q7 step cap: longest chain of `step` edges through the flow graph. */
+  readonly structuralMax: number
+  /** Count of flow-step sites the analyzer classified. */
+  readonly analyzed: number
+}
+
+/** The `path:symbol` flow-graph node id — the single place ids are composed. */
+function nodeId(path: string, symbol: string): string {
+  return `${path}:${symbol}`
+}
+
+/** Classifies every `@downstream` edge across `entries` and derives the step cap. */
+export function analyzeCardinality(entries: readonly AnalyzerEntry[]): CardinalityResult {
+  const classifications: EdgeClassification[] = []
+  const violations: CardinalityViolation[] = []
+  const nodeIds: string[] = []
+  const stepEdges: StepEdge[] = []
+  // Keyed `${from}\n${target}` so a `step`-cycle violation can recover the
+  // exact classification of the edge that closes the ring.
+  const stepEdgeIndex = new Map<string, EdgeClassification>()
+
+  for (const { file, site } of entries) {
+    // An orphan annotation documents no function, and an invalid one never
+    // parsed into edges — both are the `flow` check's diagnostics, not this
+    // one's. Nothing here to classify.
+    if (site.subject.node === null) continue
+    if (site.annotation.kind !== 'annotation') continue
+
+    const from = nodeId(file, site.subject.name)
+    nodeIds.push(from)
+
+    for (const edge of site.annotation.annotation.downstream) {
+      const classification = classifyEdge(file, site, edge)
+      classifications.push(classification)
+      const violation = violationFor(classification, site)
+      if (violation !== null) violations.push(violation)
+
+      if (classification.structural === 'step') {
+        const to = nodeId(edge.path, edge.symbol)
+        stepEdges.push({ from, to })
+        stepEdgeIndex.set(`${from}\n${to}`, classification)
+      }
+    }
+  }
+
+  const { value, cycles } = computeStructuralMax(nodeIds, stepEdges)
+  for (const cycle of cycles) {
+    violations.push(cycleViolation(cycle, stepEdgeIndex))
+  }
+
+  return {
+    classifications,
+    violations,
+    structuralMax: value,
+    analyzed: nodeIds.length,
+  }
+}
+
+/** The violation a single classified edge raises, or `null` when it is sound. */
+function violationFor(
+  classification: EdgeClassification,
+  site: FlowStepSite,
+): CardinalityViolation | null {
+  const { edge, structural, branchKind } = classification
+  const target = nodeId(edge.path, edge.symbol)
+  const file = classification.file
+  const line = classification.line ?? site.commentLine
+
+  if (edge.cardinality === null) {
+    // A missing cardinality the analyzer *can* resolve is the `flow` check's
+    // `missing-cardinality` warning, and the classification is what the codemod
+    // consumes to fill it in. Only an unresolved one is this check's to raise.
+    if (structural !== 'ambiguous') return null
+    return {
+      rule: 'cardinality/unannotated-ambiguity',
+      file,
+      line,
+      message:
+        `@downstream ${target} has no cardinality and the analyzer cannot locate the call — `
+        + `${edge.symbol} is reached through indirection (a bare callback, dynamic dispatch). `
+        + `Declare it explicitly: "@downstream ${target} step" or "@downstream ${target} branch".`,
+    }
+  }
+
+  // The author declared a cardinality the analyzer could not verify — the
+  // annotation is the source of truth for indirection it cannot follow.
+  if (structural === 'ambiguous') return null
+  if (structural === edge.cardinality) return null
+
+  if (structural === 'branch') {
+    const phrase = branchPhrase(branchKind!)
+    return {
+      rule: 'cardinality/mismatch',
+      file,
+      line,
+      message:
+        `@downstream ${target} is declared "step" but ${edge.symbol} is called inside `
+        + `${phrase} — that call site is traversed more than once, which is a `
+        + `branch. Change the cardinality to "branch", or hoist the call out of ${phrase}.`,
+    }
+  }
+  return {
+    rule: 'cardinality/mismatch',
+    file,
+    line,
+    message:
+      `@downstream ${target} is declared "branch" but every located call to ${edge.symbol} is `
+      + `linear — it is traversed at most once, which is a step. Change the cardinality to "step".`,
+  }
+}
+
+/** The violation for one `step`-edge cycle, attributed to the edge that opens it. */
+function cycleViolation(
+  cycle: readonly string[],
+  stepEdgeIndex: ReadonlyMap<string, EdgeClassification>,
+): CardinalityViolation {
+  // A `step`-edge cycle has at least two nodes — a self `step` edge is
+  // impossible, since a self-call is always classified `recursion` (a branch).
+  const source = cycle[0]!
+  const target = cycle[1]!
+  // Every node in a `step`-edge cycle is the `from` of a `step` edge in the
+  // ring, so the closing edge is always indexed.
+  const edge = stepEdgeIndex.get(`${source}\n${target}`)!
+  const ring = [...cycle, source].join(' → ')
+  return {
+    rule: 'cardinality/step-cycle',
+    file: edge.file,
+    line: edge.line!,
+    message:
+      `@downstream forms a cycle of "step" edges: ${ring}. A step edge that loops back makes the `
+      + `per-trace step count unbounded — one edge in this ring is a branch (mutual recursion is a `
+      + `branch). Re-classify the edge that closes the loop.`,
+  }
+}
+
+function branchPhrase(kind: BranchKind): string {
+  switch (kind) {
+    case 'loop': return 'a loop'
+    case 'iteration-method': return 'an iteration callback (.map, .forEach, …)'
+    case 'fan-out': return 'a Promise combinator (Promise.all, …)'
+    case 'recursion': return 'a recursive call'
+  }
+}

package/src/trace/cardinality/branch-context.ts

@@ -0,0 +1,214 @@
+// Locates every call to a target symbol inside a flow-step function body and
+// classifies each call's traversal context. A call reached through a loop, an
+// iteration method, a Promise-combinator fan-out, or a self-recursive edge is
+// "branching" — the single call site is traversed more than once per execution
+// of the parent. Anything else is linear. This is the structural half of the
+// cardinality analyzer: it reads AST shape only, never runtime behaviour, and
+// never resolves imports or types. See PLAN.tracing.md, Q1.
+
+import { isNode, type AstNode } from '../check/flow-step-site.js'
+
+/** The construct that makes a call site traversed more than once. */
+export type BranchKind = 'loop' | 'iteration-method' | 'fan-out' | 'recursion'
+
+/** One located call to the target symbol, with its traversal context. */
+export interface CallSite {
+  /** 1-based file line of the call. */
+  readonly line: number
+  /** The branching construct enclosing the call, or `null` when the call is linear. */
+  readonly branchKind: BranchKind | null
+}
+
+// Array methods whose callback argument is invoked once per element — a
+// downstream call inside the callback is traversed more than once. Lexical:
+// `.map` on a non-array still reads as iteration, by design (Q1).
+const ITERATION_METHODS = new Set([
+  'map', 'forEach', 'flatMap', 'filter',
+  'reduce', 'reduceRight',
+  'some', 'every',
+  'find', 'findIndex', 'findLast', 'findLastIndex',
+])
+
+// Promise combinators that run their arguments as concurrent siblings.
+const PROMISE_COMBINATORS = new Set(['all', 'allSettled', 'race', 'any'])
+
+const FUNCTION_TYPES = new Set([
+  'FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression',
+])
+
+const SKIP_KEYS = new Set(['loc', 'range', 'parent'])
+
+interface Context {
+  /** Name of the enclosing flow step — a call to it is recursion. */
+  readonly ownName: string
+  /** Symbol the `@downstream` edge points at. */
+  readonly target: string
+  /** The branching construct currently in scope, or `null` at linear depth. */
+  readonly branchKind: BranchKind | null
+  readonly out: CallSite[]
+}
+
+/** Every call to `target` inside `body`, each tagged with its traversal context. */
+export function findCallSites(body: AstNode, ownName: string, target: string): CallSite[] {
+  const out: CallSite[] = []
+  visit(body, { ownName, target, branchKind: null, out })
+  return out
+}
+
+function visit(node: AstNode, ctx: Context): void {
+  // A nested closure reached by ordinary descent is indirection the analyzer
+  // does not follow. Iteration-method callbacks are the one exception, and
+  // those are entered explicitly from `visitCall`.
+  if (FUNCTION_TYPES.has(node.type)) return
+
+  switch (node.type) {
+    case 'CallExpression':
+      visitCall(node, ctx)
+      return
+    case 'ForStatement':
+      visitForStatement(node, ctx)
+      return
+    case 'ForOfStatement':
+    case 'ForInStatement':
+      visitForInOf(node, ctx)
+      return
+    case 'WhileStatement':
+    case 'DoWhileStatement':
+      visitWhile(node, ctx)
+      return
+    default:
+      for (const child of childNodes(node)) visit(child, ctx)
+  }
+}
+
+function visitCall(node: AstNode, ctx: Context): void {
+  const callee = node['callee']
+  const name = calleeName(callee)
+  if (name === ctx.target) {
+    ctx.out.push({
+      line: node.loc.start.line,
+      branchKind: name === ctx.ownName ? 'recursion' : ctx.branchKind,
+    })
+  }
+
+  const args = nodeArray(node['arguments'])
+
+  if (isPromiseCombinator(callee)) {
+    // Each argument runs as a concurrent sibling — a fan-out.
+    for (const arg of args) visit(arg, branched(ctx, 'fan-out'))
+    return
+  }
+
+  if (isIterationMethod(callee)) {
+    // The receiver is evaluated once; the callback runs once per element.
+    if (isNode(callee)) visitChild(callee['object'], ctx)
+    for (const arg of args) visitIterationArg(arg, ctx)
+    return
+  }
+
+  // An ordinary call: callee and arguments stay at the current depth.
+  visitChild(callee, ctx)
+  for (const arg of args) visit(arg, ctx)
+}
+
+function visitIterationArg(arg: AstNode, ctx: Context): void {
+  if (arg.type === 'Identifier' && arg['name'] === ctx.target) {
+    // `items.map(downstream)` — the symbol is itself the per-element callback.
+    ctx.out.push({
+      line: arg.loc.start.line,
+      branchKind: arg['name'] === ctx.ownName ? 'recursion' : 'iteration-method',
+    })
+    return
+  }
+  if (FUNCTION_TYPES.has(arg.type)) {
+    visitChild(arg['body'], branched(ctx, 'iteration-method'))
+    return
+  }
+  // A non-callback argument (e.g. `reduce`'s seed) runs at the current depth.
+  visit(arg, ctx)
+}
+
+function visitForStatement(node: AstNode, ctx: Context): void {
+  // `init` runs once; `test`, `update`, and `body` run every iteration.
+  visitChild(node['init'], ctx)
+  const looped = branched(ctx, 'loop')
+  visitChild(node['test'], looped)
+  visitChild(node['update'], looped)
+  visitChild(node['body'], looped)
+}
+
+function visitForInOf(node: AstNode, ctx: Context): void {
+  // `right` (the iterable) is evaluated once; `body` runs once per element.
+  visitChild(node['right'], ctx)
+  visitChild(node['body'], branched(ctx, 'loop'))
+}
+
+function visitWhile(node: AstNode, ctx: Context): void {
+  // Both `test` and `body` run every iteration.
+  const looped = branched(ctx, 'loop')
+  visitChild(node['test'], looped)
+  visitChild(node['body'], looped)
+}
+
+/** Enters `branchKind` scope, keeping the outermost construct already in scope. */
+function branched(ctx: Context, kind: BranchKind): Context {
+  return { ...ctx, branchKind: ctx.branchKind ?? kind }
+}
+
+function visitChild(value: unknown, ctx: Context): void {
+  if (isNode(value)) visit(value, ctx)
+}
+
+function calleeName(callee: unknown): string | null {
+  if (!isNode(callee)) return null
+  if (callee.type === 'Identifier') {
+    const name = callee['name']
+    return typeof name === 'string' ? name : null
+  }
+  if (callee.type === 'MemberExpression' && callee['computed'] === false) {
+    const prop = callee['property']
+    if (isNode(prop) && prop.type === 'Identifier' && typeof prop['name'] === 'string') {
+      return prop['name']
+    }
+  }
+  return null
+}
+
+function isPromiseCombinator(callee: unknown): boolean {
+  if (!isNode(callee) || callee.type !== 'MemberExpression' || callee['computed'] !== false) {
+    return false
+  }
+  const obj = callee['object']
+  const prop = callee['property']
+  return isNode(obj) && obj.type === 'Identifier' && obj['name'] === 'Promise'
+    && isNode(prop) && prop.type === 'Identifier'
+    && typeof prop['name'] === 'string' && PROMISE_COMBINATORS.has(prop['name'])
+}
+
+function isIterationMethod(callee: unknown): boolean {
+  if (!isNode(callee) || callee.type !== 'MemberExpression' || callee['computed'] !== false) {
+    return false
+  }
+  const prop = callee['property']
+  return isNode(prop) && prop.type === 'Identifier'
+    && typeof prop['name'] === 'string' && ITERATION_METHODS.has(prop['name'])
+}
+
+function nodeArray(value: unknown): AstNode[] {
+  if (!Array.isArray(value)) return []
+  return value.filter(isNode)
+}
+
+function* childNodes(node: AstNode): Generator<AstNode> {
+  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)) yield item
+      }
+    } else if (isNode(value)) {
+      yield value
+    }
+  }
+}

package/src/trace/cardinality/check.ts

@@ -0,0 +1,33 @@
+// File-scanning wrapper around the cardinality analyzer: reads each source
+// file, collects its `@flow_step` sites, and runs `analyzeCardinality` over
+// the lot. Mirrors flow-check.ts — the analyzer itself is pure (analyze.ts);
+// this is the only part of the cardinality check that touches the filesystem.
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { collectFlowStepSites } from '../check/flow-step-site.js'
+import { analyzeCardinality, type AnalyzerEntry, type CardinalityResult } from './analyze.js'
+
+/** Analyzes `@downstream` cardinality across `sourceFiles` (paths relative to `cwd`). */
+export function checkCardinality(cwd: string, sourceFiles: readonly string[]): CardinalityResult {
+  const entries: AnalyzerEntry[] = []
+
+  for (const file of sourceFiles) {
+    const abs = join(cwd, file)
+
+    let sites
+    try {
+      sites = collectFlowStepSites(readFileSync(abs, 'utf-8'), file)
+    } catch {
+      // Missing or unparseable file — nothing to analyze; a syntax error is
+      // the type checker's diagnostic, not this check's.
+      continue
+    }
+
+    for (const site of sites) {
+      entries.push({ file, site })
+    }
+  }
+
+  return analyzeCardinality(entries)
+}

package/src/trace/cardinality/classify-edge.ts

@@ -0,0 +1,64 @@
+// 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 type { DownstreamEdge } from 'pipework-flow-parser'
+import type { FlowStepSite } from '../check/flow-step-site.js'
+import { findCallSites, type BranchKind } from './branch-context.js'
+
+/**
+ * The analyzer's structural verdict for a `@downstream` edge.
+ *
+ * - `step` — every located call site is linear; traversed at most once.
+ * - `branch` — at least one call site is reached through a loop, an iteration
+ *   method, a Promise-combinator fan-out, or recursion.
+ * - `ambiguous` — no call site could be located. The edge is reached through
+ *   indirection the analyzer does not follow (a bare callback, dynamic
+ *   dispatch), so its cardinality must be declared by hand. See Q1.
+ */
+export type StructuralCardinality = 'step' | 'branch' | 'ambiguous'
+
+export interface EdgeClassification {
+  /** Source path of the flow step the edge is declared on, relative to `cwd`. */
+  readonly file: string
+  /** Name of the flow step the edge is declared on. */
+  readonly from: string
+  /** The declared edge, verbatim from the annotation. */
+  readonly edge: DownstreamEdge
+  /** The analyzer's structural verdict. */
+  readonly structural: StructuralCardinality
+  /** The branching construct, when `structural` is `branch`; otherwise `null`. */
+  readonly branchKind: BranchKind | null
+  /** 1-based file line of the call site driving the verdict; `null` when none was located. */
+  readonly line: number | null
+}
+
+/** Classifies one `@downstream` edge of `site` against the flow-step body. */
+export function classifyEdge(
+  file: string,
+  site: FlowStepSite,
+  edge: DownstreamEdge,
+): EdgeClassification {
+  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 }
+}

package/src/trace/cardinality/structural-max.ts

@@ -0,0 +1,107 @@
+// 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.
+
+/** 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 function computeStructuralMax(
+  nodeIds: readonly string[],
+  edges: readonly StepEdge[],
+): StructuralMax {
+  const adjacency = buildAdjacency(nodeIds, edges)
+  const longest = new Map<string, number>()
+  const visiting = new Set<string>()
+  const cycles: string[][] = []
+
+  function dfs(node: string, stack: string[]): number {
+    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: readonly string[],
+  edges: readonly StepEdge[],
+): Map<string, Set<string>> {
+  const adjacency = new Map<string, Set<string>>()
+  const ensure = (id: string): Set<string> => {
+    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: readonly string[][]): string[][] {
+  const seen = new Map<string, string[]>()
+  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()]
+}