pipework 0.251.0 → 0.252.1

package/src/trace/transformer/apply.ts

@@ -0,0 +1,79 @@
+// Applies the flow-step transformer to one source file: the entry point both
+// the vitest plugin and the Node dev/serve loader call. Returns null without
+// parsing when the source carries no `@flow_step`, so unannotated files cost a
+// substring search. Types are kept in the output; the caller's own TypeScript
+// stripping still runs after this.
+
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+import ts from 'typescript'
+
+import { createFlowStepTransformer } from './transform-flow-steps.js'
+import type { FlowStepTransformError } from './transform-error.js'
+
+export interface AppliedFlowSteps {
+  readonly code: string
+  readonly errors: readonly FlowStepTransformError[]
+}
+
+const rootCache = new Map<string, string>()
+
+/**
+ * The directory `ref` paths are relative to: the nearest ancestor holding
+ * `pipework.config.ts` (the directory `pipework check` runs from), else the
+ * nearest holding `package.json`, else the file's own directory.
+ */
+export function flowStepProjectRoot(fileName: string): string {
+  const start = dirname(resolve(fileName))
+  const cached = rootCache.get(start)
+  if (cached !== undefined) return cached
+  const found = walkUp(start, 'pipework.config.ts') ?? walkUp(start, 'package.json') ?? start
+  rootCache.set(start, found)
+  return found
+}
+
+function walkUp(start: string, marker: string): string | null {
+  let dir = start
+  for (;;) {
+    if (existsSync(join(dir, marker))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Wraps every `@flow_step` declaration in `source`. Returns null when there is
+ * nothing to wrap. Throws one error naming every hard transform error: an
+ * annotated function left unwrapped records no trace and no audit.
+ */
+export function applyFlowStepTransform(
+  source: string,
+  fileName: string,
+  projectRoot: string = flowStepProjectRoot(fileName),
+): AppliedFlowSteps | null {
+  if (!source.includes('@flow_step')) return null
+  const errors: FlowStepTransformError[] = []
+  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.ESNext, true)
+  const transformer = createFlowStepTransformer({
+    projectRoot,
+    runtimeImport: 'pipework',
+    onError: e => errors.push(e),
+  })
+  const result = ts.transform(sourceFile, [transformer])
+  try {
+    if (errors.length > 0) {
+      const lines = errors.map(e => `  ${e.file}:${String(e.line)} ${e.code}: ${e.message}`)
+      throw new Error(
+        `[pipework] @flow_step could not be applied — the annotated function(s) would run unwrapped:\n${lines.join('\n')}`,
+      )
+    }
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })
+    const transformed = result.transformed[0]
+    if (transformed === undefined || transformed === sourceFile) return null
+    return { code: printer.printFile(transformed), errors }
+  } finally {
+    result.dispose()
+  }
+}

package/src/trace/transformer/build-meta-literal.ts

@@ -0,0 +1,30 @@
+// Builds the `FlowStepMeta` object literal the transformer bakes in at every
+// wrap site. The `ref` is the `path:symbol` node id — the same shape the
+// annotation grammar uses for `@upstream` / `@downstream` targets.
+
+import ts from 'typescript'
+
+export interface MetaTouchTarget {
+  readonly entity: string
+  readonly verb: string
+}
+
+// `touches` (the `@touches Entity:verb` targets) is baked in only when
+// non-empty, so an unaudited step keeps the plain `{ ref }` literal.
+export function buildMetaLiteral(
+  factory: ts.NodeFactory,
+  ref: string,
+  touches: readonly MetaTouchTarget[] = [],
+): ts.ObjectLiteralExpression {
+  const properties = [factory.createPropertyAssignment('ref', factory.createStringLiteral(ref))]
+  if (touches.length > 0) {
+    properties.push(factory.createPropertyAssignment(
+      'touches',
+      factory.createArrayLiteralExpression(touches.map(t => factory.createObjectLiteralExpression([
+        factory.createPropertyAssignment('entity', factory.createStringLiteral(t.entity)),
+        factory.createPropertyAssignment('verb', factory.createStringLiteral(t.verb)),
+      ]))),
+    ))
+  }
+  return factory.createObjectLiteralExpression(properties, false)
+}

package/src/trace/transformer/find-flow-step-sites.ts

@@ -0,0 +1,85 @@
+// Locates `@flow_step` annotation sites in a TS source file. A site pairs the
+// parsed annotation with the top-level statement it documents and what shape
+// that statement is — a named function declaration, a named single-declarator
+// variable bound to a function, or something the transformer can't wrap. The
+// flow-step transformer (component 5) reads this to decide what to rewrite.
+
+import ts from 'typescript'
+
+import { parseFlowStepAnnotation, type FlowStepParseResult } from 'pipework-flow-parser'
+
+export type FlowStepSiteShape =
+  | { readonly kind: 'function-declaration'; readonly name: string }
+  | { readonly kind: 'variable-declaration'; readonly name: string }
+  | { readonly kind: 'rejected'; readonly reason: string }
+
+export interface FlowStepSite {
+  readonly statement: ts.Statement
+  readonly shape: FlowStepSiteShape
+  readonly annotation: Exclude<FlowStepParseResult, { kind: 'not-a-flow-step' }>
+  /** 1-based line where the statement begins. */
+  readonly line: number
+}
+
+/** Returns every `@flow_step` site in `sourceFile`, in source order. */
+export function findFlowStepSites(sourceFile: ts.SourceFile): readonly FlowStepSite[] {
+  const sites: FlowStepSite[] = []
+  const text = sourceFile.getFullText()
+  for (const statement of sourceFile.statements) {
+    const annotation = leadingFlowStepAnnotation(statement, text)
+    if (annotation === null) continue
+    const line = sourceFile.getLineAndCharacterOfPosition(statement.getStart(sourceFile)).line + 1
+    sites.push({ statement, shape: classifyShape(statement), annotation, line })
+  }
+  return sites
+}
+
+function leadingFlowStepAnnotation(
+  statement: ts.Statement,
+  text: string,
+): Exclude<FlowStepParseResult, { kind: 'not-a-flow-step' }> | null {
+  const ranges = ts.getLeadingCommentRanges(text, statement.getFullStart())
+  if (ranges === undefined) return null
+  for (const range of ranges) {
+    if (range.kind !== ts.SyntaxKind.MultiLineCommentTrivia) continue
+    const block = text.slice(range.pos, range.end)
+    if (!block.startsWith('/**')) continue
+    const parsed = parseFlowStepAnnotation(block)
+    if (parsed.kind !== 'not-a-flow-step') return parsed
+  }
+  return null
+}
+
+function classifyShape(statement: ts.Statement): FlowStepSiteShape {
+  if (ts.isFunctionDeclaration(statement)) {
+    if (statement.name === undefined) {
+      return { kind: 'rejected', reason: 'function declaration has no name — anonymous default exports cannot be wrapped' }
+    }
+    if (hasDefaultModifier(statement)) {
+      return { kind: 'rejected', reason: 'default-exported function declarations cannot be wrapped; export the wrapper from a named binding instead' }
+    }
+    return { kind: 'function-declaration', name: statement.name.text }
+  }
+  if (ts.isVariableStatement(statement)) {
+    const declarations = statement.declarationList.declarations
+    if (declarations.length !== 1) {
+      return { kind: 'rejected', reason: 'multi-declarator variable statements cannot be wrapped — give the flow-step its own `const` binding' }
+    }
+    const decl = declarations[0]!
+    if (decl.initializer === undefined) {
+      return { kind: 'rejected', reason: 'flow-step variable has no initializer — bind it to an arrow or function expression' }
+    }
+    if (!ts.isArrowFunction(decl.initializer) && !ts.isFunctionExpression(decl.initializer)) {
+      return { kind: 'rejected', reason: 'flow-step variable initializer is not a function — bind it to an arrow or function expression' }
+    }
+    if (!ts.isIdentifier(decl.name)) {
+      return { kind: 'rejected', reason: 'flow-step variable name must be an identifier — destructuring patterns cannot be wrapped' }
+    }
+    return { kind: 'variable-declaration', name: decl.name.text }
+  }
+  return { kind: 'rejected', reason: 'flow-step annotation must document a function declaration or a single-declarator `const` bound to a function' }
+}
+
+function hasDefaultModifier(node: ts.HasModifiers): boolean {
+  return ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false
+}

package/src/trace/transformer/inject-flow-step-import.ts

@@ -0,0 +1,39 @@
+// Ensures the wrapped source file imports `__flowStep` from the runtime
+// package. Re-uses an existing named import from the same module specifier if
+// one is present; otherwise injects a fresh import above the file's existing
+// imports. A no-op when no flow step was wrapped.
+
+import ts from 'typescript'
+
+export function injectFlowStepImport(
+  sourceFile: ts.SourceFile,
+  runtimeImport: string,
+  factory: ts.NodeFactory,
+): ts.SourceFile {
+  for (const statement of sourceFile.statements) {
+    if (!ts.isImportDeclaration(statement)) continue
+    if (!ts.isStringLiteral(statement.moduleSpecifier)) continue
+    if (statement.moduleSpecifier.text !== runtimeImport) continue
+    const clause = statement.importClause
+    if (clause === undefined || clause.namedBindings === undefined) continue
+    if (!ts.isNamedImports(clause.namedBindings)) continue
+    if (clause.namedBindings.elements.some(e => e.name.text === '__flowStep')) {
+      return sourceFile
+    }
+  }
+
+  const newImport = factory.createImportDeclaration(
+    undefined,
+    factory.createImportClause(
+      false,
+      undefined,
+      factory.createNamedImports([
+        factory.createImportSpecifier(false, undefined, factory.createIdentifier('__flowStep')),
+      ]),
+    ),
+    factory.createStringLiteral(runtimeImport),
+    undefined,
+  )
+
+  return factory.updateSourceFile(sourceFile, [newImport, ...sourceFile.statements])
+}

package/src/trace/transformer/transform-error.ts

@@ -0,0 +1,14 @@
+// Hard build errors the flow-step transformer can raise. Every code names one
+// concrete malformation; every message tells the author what is wrong, what
+// they probably meant, and how to fix it. See PLAN.tracing.md, Q3.
+
+export type FlowStepTransformErrorCode =
+  | 'orphan-annotation'
+  | 'invalid-annotation'
+
+export interface FlowStepTransformError {
+  readonly code: FlowStepTransformErrorCode
+  readonly file: string
+  readonly line: number
+  readonly message: string
+}

package/src/trace/transformer/transform-flow-steps.ts

@@ -0,0 +1,123 @@
+// The flow-step build transformer (component 5). A `ts.TransformerFactory`
+// that finds every `@flow_step`-annotated top-level declaration in a source
+// file and rewrites it as a value-wrapping pair: a renamed implementation and
+// a `__flowStep(meta, impl)` binding that re-exposes the original name. The
+// implementation body is preserved verbatim — there is no body rewriting.
+//
+// Off-the-traced-path overhead is one `getContext()` lookup and a branch (see
+// `__flowStep`). `meta` is baked in as a literal at transform time: the
+// wrapper never computes the step's identity.
+//
+// Hard errors (orphan annotations, default exports, unsupported shapes) are
+// reported via `onError` and the offending statement is left untouched. The
+// caller decides whether to fail the build.
+
+import { posix, relative, sep } from 'node:path'
+
+import ts from 'typescript'
+
+import { findFlowStepSites, type FlowStepSite, type FlowStepSiteShape } from './find-flow-step-sites.js'
+import type { MetaTouchTarget } from './build-meta-literal.js'
+import { injectFlowStepImport } from './inject-flow-step-import.js'
+import { wrapFunctionDeclaration } from './wrap-function-declaration.js'
+import { wrapVariableDeclaration } from './wrap-variable-declaration.js'
+import type { FlowStepTransformError } from './transform-error.js'
+
+export interface FlowStepTransformOptions {
+  /** Project root — `ref` is derived as `<relative-path>:<symbol>`. */
+  readonly projectRoot: string
+  /** Module specifier the injected `__flowStep` import resolves to. */
+  readonly runtimeImport: string
+  /** Sink for hard build errors. The transformer never throws. */
+  readonly onError: (err: FlowStepTransformError) => void
+}
+
+export function createFlowStepTransformer(
+  options: FlowStepTransformOptions,
+): ts.TransformerFactory<ts.SourceFile> {
+  return context => sourceFile => transformSourceFile(sourceFile, options, context.factory)
+}
+
+function transformSourceFile(
+  sourceFile: ts.SourceFile,
+  options: FlowStepTransformOptions,
+  factory: ts.NodeFactory,
+): ts.SourceFile {
+  const sites = findFlowStepSites(sourceFile)
+  if (sites.length === 0) return sourceFile
+
+  const relPath = toPosixPath(relative(options.projectRoot, sourceFile.fileName))
+  let wrappedAny = false
+  const replacements = new Map<ts.Statement, readonly ts.Statement[]>()
+
+  for (const site of sites) {
+    const wrapped = wrapSite(site, sourceFile.fileName, relPath, factory, options.onError)
+    if (wrapped === null) continue
+    replacements.set(site.statement, wrapped)
+    wrappedAny = true
+  }
+
+  if (!wrappedAny) return sourceFile
+
+  const newStatements: ts.Statement[] = []
+  for (const statement of sourceFile.statements) {
+    const wrapped = replacements.get(statement)
+    if (wrapped === undefined) {
+      newStatements.push(statement)
+      continue
+    }
+    newStatements.push(...wrapped)
+  }
+  const rewritten = factory.updateSourceFile(sourceFile, newStatements)
+  return injectFlowStepImport(rewritten, options.runtimeImport, factory)
+}
+
+function wrapSite(
+  site: FlowStepSite,
+  fileName: string,
+  relPath: string,
+  factory: ts.NodeFactory,
+  onError: (err: FlowStepTransformError) => void,
+): readonly ts.Statement[] | null {
+  if (site.annotation.kind === 'invalid') {
+    for (const err of site.annotation.errors) {
+      onError({
+        code: 'invalid-annotation',
+        file: fileName,
+        line: site.line,
+        message: err.message,
+      })
+    }
+    return null
+  }
+  const shape = site.shape
+  if (shape.kind === 'rejected') {
+    onError({
+      code: 'orphan-annotation',
+      file: fileName,
+      line: site.line,
+      message: shape.reason,
+    })
+    return null
+  }
+  const ref = `${relPath}:${shape.name}`
+  const touches = site.annotation.annotation.touches
+  return dispatch(shape, site.statement, ref, factory, touches)
+}
+
+function dispatch(
+  shape: Exclude<FlowStepSiteShape, { kind: 'rejected' }>,
+  statement: ts.Statement,
+  ref: string,
+  factory: ts.NodeFactory,
+  touches: readonly MetaTouchTarget[],
+): readonly ts.Statement[] {
+  if (shape.kind === 'function-declaration') {
+    return wrapFunctionDeclaration(statement as ts.FunctionDeclaration, shape.name, ref, factory, touches)
+  }
+  return wrapVariableDeclaration(statement as ts.VariableStatement, shape.name, ref, factory, touches)
+}
+
+function toPosixPath(filePath: string): string {
+  return sep === posix.sep ? filePath : filePath.split(sep).join(posix.sep)
+}

package/src/trace/transformer/wrap-function-declaration.ts

@@ -0,0 +1,62 @@
+// Wraps a `@flow_step`-annotated function declaration:
+//
+//   /** @flow_step */
+//   export function foo(x: number): number { return x }
+//
+// becomes
+//
+//   function foo__impl(x: number): number { return x }
+//   export const foo = __flowStep({ ref: 'src/x.ts:foo' }, foo__impl)
+//
+// The original body is preserved verbatim by reusing the implementation node;
+// the wrapper is a fresh value binding. `export` is moved from the impl onto
+// the wrapper so the public name keeps its existing visibility.
+
+import ts from 'typescript'
+
+import { buildMetaLiteral, type MetaTouchTarget } from './build-meta-literal.js'
+
+export function wrapFunctionDeclaration(
+  original: ts.FunctionDeclaration,
+  name: string,
+  ref: string,
+  factory: ts.NodeFactory,
+  touches: readonly MetaTouchTarget[] = [],
+): readonly ts.Statement[] {
+  const implName = `${name}__impl`
+  const originalModifiers = ts.getModifiers(original) ?? []
+  const isExported = originalModifiers.some(m => m.kind === ts.SyntaxKind.ExportKeyword)
+  const implModifiers = originalModifiers.filter(m => m.kind !== ts.SyntaxKind.ExportKeyword)
+
+  const impl = factory.createFunctionDeclaration(
+    implModifiers,
+    original.asteriskToken,
+    factory.createIdentifier(implName),
+    original.typeParameters,
+    original.parameters,
+    original.type,
+    original.body,
+  )
+
+  const wrapperModifiers = isExported
+    ? [factory.createModifier(ts.SyntaxKind.ExportKeyword)]
+    : undefined
+  const wrapper = factory.createVariableStatement(
+    wrapperModifiers,
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration(
+        factory.createIdentifier(name),
+        undefined,
+        undefined,
+        factory.createCallExpression(
+          factory.createIdentifier('__flowStep'),
+          undefined,
+          [buildMetaLiteral(factory, ref, touches), factory.createIdentifier(implName)],
+        ),
+      )],
+      ts.NodeFlags.Const,
+    ),
+  )
+
+  return [impl, wrapper]
+}

package/src/trace/transformer/wrap-variable-declaration.ts

@@ -0,0 +1,67 @@
+// Wraps a `@flow_step`-annotated single-declarator `const`:
+//
+//   /** @flow_step */
+//   export const foo = async (x: number): Promise<number> => x + 1
+//
+// becomes
+//
+//   const foo__impl = async (x: number): Promise<number> => x + 1
+//   export const foo = __flowStep({ ref: 'src/x.ts:foo' }, foo__impl)
+//
+// The original initializer (arrow or function expression) is preserved by
+// reference. `export` is moved from the impl binding onto the wrapper binding.
+
+import ts from 'typescript'
+
+import { buildMetaLiteral, type MetaTouchTarget } from './build-meta-literal.js'
+
+export function wrapVariableDeclaration(
+  original: ts.VariableStatement,
+  name: string,
+  ref: string,
+  factory: ts.NodeFactory,
+  touches: readonly MetaTouchTarget[] = [],
+): readonly ts.Statement[] {
+  const originalModifiers = ts.getModifiers(original) ?? []
+  const isExported = originalModifiers.some(m => m.kind === ts.SyntaxKind.ExportKeyword)
+  const declarator = original.declarationList.declarations[0]
+  if (declarator === undefined) {
+    throw new Error('wrapVariableDeclaration called on an empty declaration list — site classifier should have rejected this')
+  }
+  const implName = `${name}__impl`
+
+  const impl = factory.createVariableStatement(
+    undefined,
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration(
+        factory.createIdentifier(implName),
+        undefined,
+        declarator.type,
+        declarator.initializer,
+      )],
+      ts.NodeFlags.Const,
+    ),
+  )
+
+  const wrapperModifiers = isExported
+    ? [factory.createModifier(ts.SyntaxKind.ExportKeyword)]
+    : undefined
+  const wrapper = factory.createVariableStatement(
+    wrapperModifiers,
+    factory.createVariableDeclarationList(
+      [factory.createVariableDeclaration(
+        factory.createIdentifier(name),
+        undefined,
+        undefined,
+        factory.createCallExpression(
+          factory.createIdentifier('__flowStep'),
+          undefined,
+          [buildMetaLiteral(factory, ref, touches), factory.createIdentifier(implName)],
+        ),
+      )],
+      ts.NodeFlags.Const,
+    ),
+  )
+
+  return [impl, wrapper]
+}

package/src/workspace/affected.ts

@@ -0,0 +1,110 @@
+import type { ResolvedModule } from './discover.js'
+import type { DiffMode } from './changed-files.js'
+import { changedFiles, filesToModules, resolveBaseBranch } from './changed-files.js'
+import { buildModuleGraph } from './dependency-graph.js'
+
+export interface ScopeResult {
+  readonly modules: ReadonlySet<string>
+  readonly all: boolean
+  /**
+   * The affected set could not be computed (no git, no base branch, …) so the
+   * scope was widened to every module rather than silently scoped to nothing.
+   * The caller should log this loudly. Issue #325.
+   */
+  readonly failedOpen?: boolean
+  /**
+   * Human-readable statement of what this scope was computed FROM — the diff
+   * mode, base ref, and file count, or the flag that pinned it. Callers print
+   * it next to any result they report, so scope-of-invocation is always
+   * visible next to scope-of-claim and a green can never silently rest on an
+   * empty basis.
+   */
+  readonly basis: string
+}
+
+export type ScopeMode =
+  | { kind: 'all' }
+  | { kind: 'module'; path: string }
+  | { kind: 'diff'; mode: DiffMode }
+
+/**
+ * `configDir` anchors the diff: module paths are relative to the directory
+ * holding pipework.config.ts, so `changedFiles` must report paths in that same
+ * coordinate system. Passing the invocation cwd here reintroduces the
+ * path-prefix mismatch that made every scoped run widen to all modules
+ * whenever the config dir sat below the git toplevel.
+ */
+export function resolveAffected(
+  configDir: string,
+  resolvedModules: readonly ResolvedModule[],
+  projectName: string,
+  scope: ScopeMode,
+  baseBranches?: readonly string[],
+): ScopeResult {
+  const allPaths = new Set(resolvedModules.map(m => m.relativePath))
+
+  if (resolvedModules.length === 0) {
+    return { modules: allPaths, all: true, basis: 'every module (none declared)' }
+  }
+  if (scope.kind === 'all') {
+    return { modules: allPaths, all: true, basis: 'every module (--all/--full)' }
+  }
+
+  if (scope.kind === 'module') {
+    if (!allPaths.has(scope.path)) {
+      const known = [...allPaths].sort().join(', ')
+      throw new Error(
+        `Unknown module "${scope.path}".\n\n  Known modules: ${known}\n`,
+      )
+    }
+    return { modules: new Set([scope.path]), all: false, basis: `--module ${scope.path}` }
+  }
+
+  const modeLabel = diffLabel(configDir, scope.mode, baseBranches)
+
+  const files = changedFiles(configDir, scope.mode, baseBranches)
+  if (files === null) {
+    // The diff could not be computed — fail open to every module rather than
+    // silently check nothing. Issue #325.
+    return {
+      modules: allPaths,
+      all: true,
+      failedOpen: true,
+      basis: `${modeLabel} — could not be computed; failed open to every module`,
+    }
+  }
+  const fileCount = `${String(files.length)} changed file${files.length === 1 ? '' : 's'}`
+  if (files.length === 0) {
+    return { modules: new Set(), all: false, basis: `${modeLabel} — 0 changed files` }
+  }
+
+  const mapped = filesToModules(files, [...allPaths])
+  if (mapped.rootChanged) {
+    return {
+      modules: allPaths,
+      all: true,
+      basis: `${modeLabel} — ${fileCount}, including changes outside any module; widened to all modules`,
+    }
+  }
+
+  if (mapped.modules.size === 0) {
+    return { modules: new Set(), all: false, basis: `${modeLabel} — ${fileCount}, none inside a module` }
+  }
+
+  const graph = buildModuleGraph(resolvedModules, projectName)
+  return {
+    modules: graph.affected(mapped.modules),
+    all: false,
+    basis: `${modeLabel} — ${fileCount}`,
+  }
+}
+
+function diffLabel(configDir: string, mode: DiffMode, baseBranches?: readonly string[]): string {
+  if (mode === 'branch') {
+    const base = resolveBaseBranch(configDir, baseBranches)
+    return base === null
+      ? 'diff vs base branch (no base branch found)'
+      : `diff vs merge-base with '${base}'`
+  }
+  return mode === 'staged' ? 'staged changes' : 'uncommitted changes'
+}