README.md
README.md is a file in GovLab Pipeline. 107 lines of code and 0 definitions.
<!-- Auto-generated 2026-09-29T00:22Z v7 -->
# @govlab/pipeline
<!-- concern:overview -->
## 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`.
<!-- /concern:overview -->
<!-- concern:use -->
## 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.
<!-- /concern:use -->
<!-- concern:charts -->
## 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).
<!-- /concern:charts -->
<!-- concern:install -->
## 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
```
<!-- /concern:install -->
<!-- concern:api -->
## API
The package exposes no public API.
<!-- /concern:api -->
<!-- concern:config -->
## Configuration
The stage plan is the configuration. `configuration/configs/invocation.config.ts` declares the command line as `GATE_ARGV`: `--bypass <slug>`, `--run <slug>`, `--member <id>`, `--only <label>`, `--tag <tag>`, `--skip-tag <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.
<!-- /concern:config -->
<!-- concern:deps -->
## Dependencies
- `@govlab/argv`
- `@govlab/canonical-write`
- `@govlab/quality`
- `@ssot/paths`
<!-- /concern:deps -->
<!-- concern:ai-context -->
## 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 <script>` call, and a step reading `npm run <name>` is a defect.
- A `parallel` group is a barrier. Every member runs, then the group aborts if any failed, printing each failure's captured output. Independent checks share a group, and dependent ones are separate steps.
- `bypass: true` on a stage makes it opt-in, so it runs only when `--run <slug>` names it. No stage in this workspace ships that way.
- Report mode runs every step and surveys a broken tree, and the live mode gates work. Both report artifacts are written in either mode and flushed before every abort, so a present artifact does not mean a passing run.
- `--member <id>` is an inner-loop convenience. A scoped run narrows every step that takes a path and drops the steps that scan the tree as a whole: lockfile integrity, prune, knip, catalog and document generation, and the validators. Those are named on stdout before the run starts. Work merges on a green unscoped `npm run verify`.
- Each stage builder keeps the repo-wide command for every step that has one and switches to per-member commands only under `--member`, so an unscoped `npm run verify` keeps its coverage.
- The entry point is the only file that reads `process.env` or `process.argv`. The runner receives the shell and the parsed flags in its context.
<!-- /concern:ai-context -->
<!-- concern:domains -->
## Domains
This package serves these software domains, which `_manifest.json` declares in `domains` from the two-tier software-domain vocabulary (`meta → sub`):
- **developer-tooling** — build-tooling, cli
<!-- /concern:domains -->
<!-- concern:quality-governance -->
## Quality governance
The canonical quality catalog resolves the quality concepts that govern this package. `_manifest.json` declares them in `governedBy`, and a lint package derives them from the concepts its own rules enforce. Each maps to the custom lint rules that enforce it:
- **separation-of-concerns** — _complexity_
- **type-safety** — _correctness_
<!-- /concern:quality-governance -->
<!-- concern:disposal -->
## Disposal
- Replace the root `verify` scripts with a direct invocation of each check, accepting the loss of ordering, aggregation and the not-run count.
- Repoint the consumers of `stagesFor` and `stageLabels` in the build, content and host members.
- Remove `govlab.root/govlab.pipeline/` and its workspace entry.
<!-- /concern:disposal -->
<!-- concern:metrics -->
---
stable · 0 exports · 4 deps · 0 principles · 2 concepts
<!-- /concern:metrics -->