# @govlab/pipeline ## Purpose `runStages(label, stages, context)` in `core/coordinators/stage.coordinator.ts` runs an ordered stage list. A stage is `{ label, slug, bypass, steps }`, and a step is either one shell command or a `parallel` group of them. In the default live mode each step streams to the terminal and the first failure aborts, printing the command, the elapsed seconds and the count of steps that did not run. Under `--report` every step runs captured, each result is parsed for a trailing violation count, and the run ends with a per-stage table. The workspace gate is the plan `stagesFor` builds in `core/factories/plan.factory.ts` from the `STAGES` builders, and `runtime/entrypoints/validation.entrypoint.ts` hands it to the runner for `npm run verify`. ## When to use - Composing a multi-stage gate whose ordering carries meaning, such as a generator that runs before the readers of what it generates. - Running independent checks concurrently while keeping one aggregated pass or fail for the whole run. - Wanting a gate that reports how many of its steps did not run. ## When NOT to use - A single command. Invoke it directly. - Work needing branching between steps. A stage list is declarative and ordered, with no conditionals and no data flowing from one step to the next. - A watch loop or any long-lived process, because every step is expected to exit. ## Architecture charts The structure, logical-flow and dependency diagrams derived from the source AST live in [_code.info.generated/mermaid-charts.generated.md](./_code.info.generated/mermaid-charts.generated.md). ## Install A private workspace package resolved through the root `package.json` workspaces glob `govlab.root/govlab.*`. It declares `@govlab/argv`, `@govlab/canonical-write`, `@govlab/quality` and `@ssot/paths`, and holds no third-party dependency of its own. There is no build step, and the root `verify` scripts run `govlab.root/govlab.pipeline/runtime/entrypoints/validation.entrypoint.ts`. ## Quick start ```ts EXAMPLE: Declare and run a staged gate import { argvOf } from "@govlab/argv"; import { GATE_ARGV } from "@govlab/pipeline/configuration/configs/invocation.config.ts"; import { runStages } from "@govlab/pipeline/core/coordinators/stage.coordinator.ts"; import { shellFor } from "@govlab/pipeline/core/resolvers/shell.resolver.ts"; import { stageArgsOf } from "@govlab/pipeline/core/converters/invocation.converter.ts"; await runStages( "verify-codebase", [ { bypass: false, label: "Prepare", slug: "prepare", steps: [{ label: "Typecheck", run: "npx tsc --noEmit -p tsconfig.json" }], }, ], { args: stageArgsOf(argvOf(GATE_ARGV, ["--report"])), options: {}, shell: shellFor(process.platform, process.env.ComSpec), }, ); ``` ```sh EXAMPLE: Select or skip stages at invocation, and switch to report mode npm run verify -- --bypass linting # everything except one stage npm run verify:code # everything except the steps tagged docs npm run verify -- --only "Lint surfaces" # one step by label npm run verify # every step, in report mode ``` ```sh EXAMPLE: Gate one workspace member instead of the whole tree npm run verify -- --member app # one member npm run verify -- --member quality,pipeline # several members in one run npm run verify # every gated member, plus the repo-wide steps ``` ## API The package exposes no public API. ## Configuration The stage plan is the configuration. `configuration/configs/invocation.config.ts` declares the command line as `GATE_ARGV`: `--bypass `, `--run `, `--member `, `--only `, `--tag `, `--skip-tag ` and `--report`, each repeatable. `--help` prints the contract, and an undeclared flag or a bare argument is refused. `configuration/configs/package.config.ts` declares `MEMBERS`, the registry `--member` resolves against. `runStages` takes a context of the parsed arguments, the report options `{ reportPath, violationsPath, writeReport }` and the shell, and writes both artifacts on every exit path. Every step runs through a shell from the repo root, so a relative path in a command resolves against the workspace root. ## Dependencies - `@govlab/argv` - `@govlab/canonical-write` - `@govlab/quality` - `@ssot/paths` ## AI context - Stage order is enforced only by position in `STAGES`. Auto-fix precedes linting, which reads the closure graph auto-fix writes, and nothing asserts that dependency. - A step's `run` is a shell command string executed from the repo root, so relative paths resolve against the workspace root. - **The gate never invokes an npm script.** Every step is a direct binary or `node