pipework-flow-parser

Pure syntactic parser for pipework @flow_step JSDoc blocks.

Text in, structured records out — no semantic analysis, no TypeScript AST, no file I/O. The contract is the FlowStepAnnotation output type (semver'd) plus the conformance corpus under tests/conformance-corpus.ts. Any reimplementation, in any language, must reproduce the corpus exactly.

The grammar is intentionally permissive (@downstream <kind> is optional); strictness (mandatoriness, call-graph alignment, cardinality verdicts) is layered on by the flow check in pipework, not by the grammar. See PLAN.tracing.md Q6 in the pipework repo for the rationale.

Usage

import { parseFlowStepAnnotation } from 'pipework-flow-parser'

const result = parseFlowStepAnnotation(`/**
 * @flow_step
 * @intent records the invoice
 * @downstream src/data/write/insert.ts:doInsert step
 * @touches Invoice:create
 */`)

if (result.kind === 'annotation') {
  // result.annotation.touches, .downstream, .upstream, .intent
}

Output type

parseFlowStepAnnotation(block) returns one of:

• { kind: 'not-a-flow-step' } — the block has no @flow_step tag; not an error.
• { kind: 'annotation', annotation: FlowStepAnnotation } — well-formed.
• { kind: 'invalid', errors: FlowStepParseError[] } — at least one syntactic malformation. Each error carries a closed-union code, a 1-based line within the block, and an actionable message.

Stability

The output type and the error-code union are semver'd. The conformance corpus in tests/ is the executable half of the contract; adding a case is non-breaking, changing one is breaking.