fargo
68279d61a1
ci/woodpecker/pr/ci Pipeline was successful
- new canonical-only quality-rails stage (after build) invokes the evaluator CLI on the repo root — QC-19 monorepo subject — instead of duplicating presence logic; no ci.yml mirror (same shape as the build stage) - parity spec updated: stage-name list, evaluator-delegation assertions, and negative controls for inline duplication / dropped command - quality-rails README points at the probe inventory (input doc)
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
# @mosaicstack/quality-rails
|
|
|
|
Quality-rails scaffolding and — since RI-3-002 (RI-N4) — the **typed
|
|
quality-rails evaluator**: the single authoritative producer of check verdicts
|
|
for the checks it owns.
|
|
|
|
## Evaluator (RI-N4)
|
|
|
|
Every verdict is typed and fail-closed:
|
|
|
|
```
|
|
{ status: 'passed' | 'failed' | 'blocked' | 'error' | 'not-applicable',
|
|
checkId, checkVersion, subject, reason }
|
|
```
|
|
|
|
Missing implementations, missing inputs, unknown check ids, process errors,
|
|
timeouts, and malformed probe output can never become `passed` or an
|
|
unqualified skip — they surface as `blocked`/`error` with a reason (vocabulary
|
|
mirrors MACP's `GateStatus` discipline).
|
|
|
|
- Check definitions live as **data** with a version and a sha256 content
|
|
digest (`definitionDigest`); every recorded verdict names the definition
|
|
version that produced it.
|
|
- Check sets are selected **per subject kind** (`node`, `python`, `rust`,
|
|
`monorepo`, `unknown`) via the versioned, digested check-set policy — this
|
|
repository (a `monorepo` subject) does not share the node template's file
|
|
list.
|
|
- Shell probes stay **thin adapters**: the TS evaluator invokes them and owns
|
|
the verdict parsing (e.g. QC-20's planted-commit probe).
|
|
|
|
### Owned checks
|
|
|
|
| check id | canonical check | mechanism |
|
|
| --------------------------- | --------------- | ---------------------------------------------------------------------- |
|
|
| `qc-19-rails-files-present` | QC-19 | typed absorption of the former presence-only `check`/`doctor` loop |
|
|
| `qc-20-enforcement-verify` | QC-20 | thin shell adapter (framework `verify.sh`); verdict parsing owned here |
|
|
|
|
The canonical check ids QC-1..QC-21 and their dispositions are defined in
|
|
`docs/release-integrity/probe-inventory.md` (the RI-3-001 inventory — the
|
|
evaluator's input, not its output).
|
|
|
|
### Usage
|
|
|
|
```sh
|
|
# CLI (same typed report as the programmatic API)
|
|
node dist/cli.js quality-rails evaluate --project <path> [--probe-path <verify.sh>] [--json]
|
|
node dist/cli.js quality-rails check --project <path> [--json] # QC-19 only, fail-closed exit
|
|
```
|
|
|
|
```ts
|
|
import { evaluateSubject } from '@mosaicstack/quality-rails';
|
|
|
|
const report = await evaluateSubject({ subjectPath: '/path/to/project' });
|
|
// report.state: 'passed' | 'failed' | 'blocked' | 'error'
|
|
```
|
|
|
|
`pnpm verify:release` invokes this evaluator as its `quality-rails` stage
|
|
(canonical-only stage, QC-19 on the monorepo subject).
|
|
|
|
## Scaffolding (pre-existing)
|
|
|
|
`init` scaffolds rails files per detected kind/profile; `doctor` is advisory
|
|
and reports typed states.
|