@kirill.konshin/lint 0.5.2 → 0.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/lintPrepare.d.ts +9 -8
- package/dist/lintPrepare.d.ts.map +1 -1
- package/dist/lintPrepare.js +20 -14
- package/package.json +5 -3
- package/rules/github.md +0 -76
- package/rules/gitlab.md +0 -72
- package/rules/nextjs.md +2 -55
- package/rules/openspec.md +12 -0
- package/rules/storybook.md +2 -0
- package/rules/tailwind.md +1 -1
- package/rules/testing.md +1 -0
- package/rules/webstorm.md +6 -214
- package/skills/lint-github/SKILL.md +78 -0
- package/skills/lint-gitlab/SKILL.md +76 -0
- package/skills/lint-nextjs/SKILL.md +59 -0
- package/skills/{lint-repo.md → lint-repo/SKILL.md} +1 -1
- package/skills/lint-webstorm/SKILL.md +201 -0
- package/skills/lint-worktree/SKILL.md +28 -0
- package/skills/spec-steward/SKILL.md +76 -0
- package/skills/spec-steward/references/apply.md +18 -0
- package/skills/spec-steward/references/audit.md +57 -0
- package/skills/spec-steward/references/contract.md +186 -0
- package/skills/spec-steward/references/criteria.md +59 -0
- package/skills/spec-steward/references/model.md +71 -0
- package/skills/spec-steward/references/review-format.md +61 -0
- package/skills/spec-steward/references/wiring.md +19 -0
- package/skills/spec-steward/scripts/lib/align.mjs +126 -0
- package/skills/spec-steward/scripts/lib/checks.mjs +584 -0
- package/skills/spec-steward/scripts/lib/citations.mjs +156 -0
- package/skills/spec-steward/scripts/lib/corpus.mjs +259 -0
- package/skills/spec-steward/scripts/lib/coverage.mjs +124 -0
- package/skills/spec-steward/scripts/lib/evidence.mjs +335 -0
- package/skills/spec-steward/scripts/lib/git.mjs +138 -0
- package/skills/spec-steward/scripts/lib/review.mjs +347 -0
- package/skills/spec-steward/scripts/lib/scan.mjs +364 -0
- package/skills/spec-steward/scripts/lib/util.mjs +161 -0
- package/skills/spec-steward/scripts/lib/wire.mjs +331 -0
- package/skills/spec-steward/scripts/steward.mjs +350 -0
- package/skills/spec-steward/workflows/audit.js +539 -0
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# The spec-steward contract
|
|
2
|
+
|
|
3
|
+
What `spec-steward` checks and reports in every repository that runs it. It ships with `@kirill.konshin/lint`, so a repository is held to the version it pins. A repository's constitution states only its own choices — the `--binds` globs it passes, the jobs that run the gate, the audits it runs and where it publishes — and points here for the rest. How a specification is written is [model.md](model.md); this file is what the tool does with it. `steward.test.mjs` proves the cases below.
|
|
4
|
+
|
|
5
|
+
Terms used throughout:
|
|
6
|
+
|
|
7
|
+
- **The corpus** is every `spec.md` under the specs directory (`--specs`, default `openspec/specs`).
|
|
8
|
+
- **A requirement's statement** is the text between its `### Requirement:` heading and its first `#### Scenario:`. **Its block** runs from the heading to the next requirement heading.
|
|
9
|
+
- **A base** is the git ref the working tree is compared with ([Base resolution](#base-resolution)). A kind marked _base only_ runs only when a base is set.
|
|
10
|
+
|
|
11
|
+
## Citation and scanning
|
|
12
|
+
|
|
13
|
+
A citation is an optional pointer to a capability specification: a mention of `openspec/specs/<capability>/spec.md`, with or without `#<anchor>`, in a `{@link}` tag, a code comment, or a document outside `openspec/changes/`. Every citation present SHALL resolve — its file exists, and its anchor, when given, is a heading that file renders; one that does not fails the build. A code citation is neither evidence that code complies nor required, and its placement and applicability are not checked.
|
|
14
|
+
|
|
15
|
+
- **Files scanned.** Every tracked file, and every untracked file git does not ignore, that is text; a file holding a NUL byte is binary and skipped. Dockerfiles, Helm templates, `.env*` and `.dockerignore` are scanned like any other text file.
|
|
16
|
+
- **Files skipped.** Dependency and build output directories, every `spec.md`, and all of `openspec/changes/**`, open changes included. Change folders quote other repositories and paths being removed, so they are history and plans, not pointers.
|
|
17
|
+
- **Where a mention counts.** Anywhere in a Markdown or MDX document. Elsewhere, only inside a `{@link …}` or `@see` tag, or inside a comment: `//`, `/* */`, a JSDoc line, `<!-- -->`, and `#` in every file that is not JavaScript, TypeScript or Markdown. A path inside a string literal is data, not a citation.
|
|
18
|
+
- **Resolution.** A path that starts with `openspec/` resolves from the repository root. Any other path resolves from the citing file's directory.
|
|
19
|
+
- **Anchors.** An anchor resolves when the cited file renders a heading with that slug. Slugs follow github-slugger: lowercase, punctuation and symbols dropped, each space a hyphen with runs kept, and a repeated heading suffixed `-1`, `-2`. `### Requirement: <name>` renders `#requirement-<slug>`; `#### Scenario: <name>` renders `#scenario-<slug>`.
|
|
20
|
+
- **Renames.** Under a base, a citation of an anchor that the diff renamed is reported as `renamed-anchor`, not as `dangling-citation`. `--fix` rewrites every such citation.
|
|
21
|
+
|
|
22
|
+
Cases:
|
|
23
|
+
|
|
24
|
+
- **WHEN** a cited capability, requirement, or scenario is renamed or removed **THEN** the citation stops resolving and the build fails, rather than rotting silently
|
|
25
|
+
- **WHEN** a file under `openspec/changes/` names a path that does not exist **THEN** nothing is reported
|
|
26
|
+
- **WHEN** a `#` comment in a Dockerfile cites a scenario **THEN** that citation is resolved like any other
|
|
27
|
+
- **WHEN** a test fixture holds a specification path inside a string **THEN** it is not a citation
|
|
28
|
+
|
|
29
|
+
## Binding
|
|
30
|
+
|
|
31
|
+
A citation of a scenario's anchor binds the scenario only where it sits in one of the places below. A bound scenario has evidence for the [scenario ratchet](#scenario-ratchet) and the [coverage report](#coverage-report).
|
|
32
|
+
|
|
33
|
+
| Where the citation sits | Binds |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| In a test file (a JavaScript or TypeScript `*.test.*`, `*.spec.*` or `*.test-d.*` file, a file under `__tests__/` or `e2e/`, or a Python or Go test file), inside a `describe`, `it`, `test`, `suite` or `bench` call, with any `.only`, `.skip`, `.concurrent`, `.sequential`, `.todo`, `.each(…)`, `.for(…)`, `.runIf(…)`, `.skipIf(…)` or `.fails` chain, and Playwright's `test.describe`, `test.step`, `.serial`, `.parallel`, `.fixme` and `.fail`; in a Python test file, inside a `test_…` function or a `Test…` class; in a Go test file, inside a `Test…` function | yes |
|
|
36
|
+
| In a test file, in the comment run directly above such a call or function (in Python, its decorators too), with no blank line between | yes |
|
|
37
|
+
| In a test file, on a type assertion — an `Expect<…>` type alias, or an `expectTypeOf(…)` or `assertType(…)` call — at the top level or inside a block | yes |
|
|
38
|
+
| In a lint configuration — `eslint.config.{js,mjs,cjs,ts,mts,cts}` or `yarn.config.cjs` — anywhere | yes |
|
|
39
|
+
| In a file matching a `--binds <glob>` the repository passes (a check script, a Dockerfile, a CI configuration), anywhere | yes |
|
|
40
|
+
| Anywhere else in a test file: its header, a fixture, a helper | no — it binds nothing and fails nothing |
|
|
41
|
+
| Code, configuration, YAML, a Dockerfile or a document that no `--binds` glob matches | no — it is a pointer |
|
|
42
|
+
|
|
43
|
+
A requirement's anchor binds its scenario only when the requirement has exactly one. A call's or a Go function's extent is found by balanced brackets, skipping strings, template literals and comments; a Python function's or class's, by indentation.
|
|
44
|
+
|
|
45
|
+
Cases:
|
|
46
|
+
|
|
47
|
+
- **WHEN** a citation sits in a test file's header comment **THEN** it binds no scenario, and no finding is reported for it
|
|
48
|
+
- **WHEN** a citation sits in the comment directly above an `it(…)` call **THEN** it binds that scenario
|
|
49
|
+
- **WHEN** a requirement constrains a shape, an interface or a structure **THEN** a citation on the type assertion, lint entry or `--binds` check that proves it binds its scenario, as a test's would
|
|
50
|
+
- **WHEN** a test cites the requirement anchor of a requirement with two scenarios **THEN** neither scenario is bound
|
|
51
|
+
|
|
52
|
+
## Markers
|
|
53
|
+
|
|
54
|
+
There are exactly two markers. Each stands on a line of its own: the Advisory line in the requirement's statement, directly under its heading, and a Known gap line in the statement or inside the block of the scenario it qualifies.
|
|
55
|
+
|
|
56
|
+
| Marker | Meaning |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `**⚠️ Advisory:** <why review is its evidence>` | The requirement is ADVISORY. It keeps its RFC 2119 keywords and is exempt from the scenario ratchet and from `absolute-unproven`. Coverage reports it as `advisory`, and the evidence JSON classes it `advisory`. Marking an existing requirement Advisory is reported as `weakened` ("newly marked advisory"). It qualifies the whole requirement, so a requirement that mixes a contract with guidance is split. |
|
|
59
|
+
| `**⚠️ Known gap (<tracker>):** <what is missing>` | Behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. `<tracker>` is required text: a ticket key (`EVAA-34696`), a tickets-page id, or an open `openspec/changes/<name>` folder. Steward checks only that it is present: any non-empty text inside the parentheses counts and is not validated, so a placeholder counts until it is replaced. In the statement, the line records the gap and exempts nothing, unless it names scenarios of its requirement by title after `exempts`, each in quotes (`exempts scenario 'A'`, `exempts scenarios 'A' and 'B'`; double quotes, curly quotes, `_…_` and `*…*` are read too). Exactly the named scenarios are then exempt from the scenario ratchet. Inside a scenario's block, the line exempts that scenario. Coverage lists every gap with its tracker. |
|
|
60
|
+
|
|
61
|
+
Retired spellings are `**⚠️ Unenforced:**` and `**⚠️ Known gap:**` without a tracker. Each is reported as `marker-hygiene` and grants no exemption. So is a marker inside a line rather than on a line of its own, and an Advisory line inside a scenario. A misspelt marker (wrong case, missing emoji or bold) is reported as `marker-hygiene`, and `--fix` normalises it.
|
|
62
|
+
|
|
63
|
+
Cases:
|
|
64
|
+
|
|
65
|
+
- **WHEN** a Known gap line under the requirement names no scenario **THEN** coverage lists the gap, and no scenario is exempt
|
|
66
|
+
- **WHEN** a requirement carries `**⚠️ Unenforced:**` **THEN** `marker-hygiene` warns, and the requirement is REQUIRED with no exemption
|
|
67
|
+
- **WHEN** an existing requirement gains the Advisory marker **THEN** `weakened` reports it for the owner
|
|
68
|
+
|
|
69
|
+
## Kinds and severities
|
|
70
|
+
|
|
71
|
+
An `error` finding fails the run. A `warn` finding fails it only under `--strict`. An `info` finding is a prompt for judgement and never fails. Under a base, info findings are limited to the requirements and scenarios the diff added or edited and to citations in changed files; errors and warnings stay corpus-wide.
|
|
72
|
+
|
|
73
|
+
| Kind | Severity | Rule |
|
|
74
|
+
| --- | --- | --- |
|
|
75
|
+
| `dangling-citation` | error | A citation's file or anchor does not exist ([Citation and scanning](#citation-and-scanning)) |
|
|
76
|
+
| `renamed-anchor` | error, base only | A citation names an anchor the diff renamed; `--fix` rewrites it |
|
|
77
|
+
| `duplicate-anchor` | error | Two headings in one spec render the same slug |
|
|
78
|
+
| `duplicate-requirement` | error | The same requirement name in two capabilities, or two requirements whose bodies are equal up to whitespace |
|
|
79
|
+
| `size` | error / info | Over the failing line, or over the warning line ([Size gate](#size-gate-with-obligation-counting)) |
|
|
80
|
+
| `scenario-unproven` | error, base only | A changed scenario of a REQUIRED requirement is neither bound nor exempt ([Scenario ratchet](#scenario-ratchet)) |
|
|
81
|
+
| `weakened` | warn, base only | A rule was removed or lowered (MUST → SHOULD), lost an absolute, gained an exception, or was newly marked Advisory |
|
|
82
|
+
| `textual-test` | warn | A test asserts on the text of a source, a spec or a document |
|
|
83
|
+
| `marker-hygiene` | warn | A misspelt marker, a retired marker, or a Known gap without a tracker ([Markers](#markers)) |
|
|
84
|
+
| `new-requirement` | info, base only | A requirement the diff added: name the failure it prevents and the cheapest evidence that catches it |
|
|
85
|
+
| `absolute-unproven` | info | A REQUIRED requirement with an absolute in an obligation sentence, no exception word and no binding; Advisory requirements are skipped |
|
|
86
|
+
| `impl-detail`, `vague-obligation`, `restating-scenario`, `duplicate-scenario`, `unbound-test` | info | Judgement prompts; `unbound-test` judges block-level bindings |
|
|
87
|
+
| `non-ears`, `non-bdd` | info, base only | Added or edited text only. `non-ears`: the statement's first obligation sentence matches none of the forms _When …_, _While …_, _If … then …_, _Where …_ or _`<subject>` SHALL …_. `non-bdd`: a scenario lacks WHEN or THEN. |
|
|
88
|
+
|
|
89
|
+
The edit hook (`steward hook`) checks only the file an edit touched. On a spec, it compares the file with its committed version and reports `weakened` and `new-requirement`, `duplicate-anchor`, and, for the requirements the edit changed, `size`, `marker-hygiene` and the judgement prompts. On any other file it reports `dangling-citation`, and in a test file also `textual-test` and `unbound-test`. It runs no ratchet, and it does not repeat a finding it already reported in the session.
|
|
90
|
+
|
|
91
|
+
## Size gate with obligation counting
|
|
92
|
+
|
|
93
|
+
A requirement's block over 300 words, or a statement — the text before its first scenario — issuing more than five obligations, SHALL be reported as an `info` prompt; a block over 500 words, or a statement issuing more than eight obligations, SHALL fail the build. An obligation is an RFC 2119 keyword in the statement written outside backticks — `MUST`, `SHALL`, `SHOULD`, `MAY`, `REQUIRED`, `RECOMMENDED` or `OPTIONAL`, a `NOT` form counted once; a keyword inside backticks is mentioned as a term and is not counted.
|
|
94
|
+
|
|
95
|
+
Marker lines are not part of the statement for counting. `--max-words 300,500` and `--max-obligations 5,8` set the warning and failing lines as a pair.
|
|
96
|
+
|
|
97
|
+
Cases:
|
|
98
|
+
|
|
99
|
+
- **WHEN** a requirement's block exceeds 300 words or its statement issues more than five obligations **THEN** `size` reports it at `file:line` as a prompt, and the build proceeds
|
|
100
|
+
- **WHEN** a requirement's block exceeds 500 words or its statement issues more than eight obligations **THEN** the build fails until the requirement is brought under the line
|
|
101
|
+
- **WHEN** a statement names a keyword inside backticks **THEN** the obligation count does not include it
|
|
102
|
+
- **WHEN** a statement reads "The gate MUST run. It SHALL NOT skip `MUST`; it MAY warn, is NEVER silent and ALWAYS logs; logging is RECOMMENDED." **THEN** it issues four obligations
|
|
103
|
+
|
|
104
|
+
## Scenario ratchet
|
|
105
|
+
|
|
106
|
+
A scenario a merge request adds or modifies in a REQUIRED requirement SHALL be bound before the request merges, or SHALL be exempted by a `**⚠️ Known gap (<tracker>):**` line ([Markers](#markers)). An ⚠️ ADVISORY requirement is exempt. The scenarios the request's base already carries unbound are listed in the coverage report and fail nothing.
|
|
107
|
+
|
|
108
|
+
`scenario-unproven` enforces this under a base. A scenario counts as changed when its block, with whitespace normalised, appears nowhere in the base corpus, so a scenario moved verbatim is unchanged. A changed scenario fails when no [binding](#binding) cites `#scenario-<slug>` and no Known gap line exempts it. Its requirement's anchor counts only when the requirement has exactly one scenario. Without a base, the ratchet does not run.
|
|
109
|
+
|
|
110
|
+
Cases:
|
|
111
|
+
|
|
112
|
+
- **WHEN** a merge request changes a scenario of a REQUIRED requirement that nothing binds and no Known gap line exempts **THEN** `scenario-unproven` fails the run, naming the scenario at `file:line`
|
|
113
|
+
- **WHEN** a requirement's Known gap line names one scenario **THEN** that scenario is exempt, and the requirement's other changed scenarios still need binding
|
|
114
|
+
- **WHEN** a scenario of an ⚠️ ADVISORY requirement changes **THEN** the gate asks nothing of it
|
|
115
|
+
- **WHEN** a scenario moves to another requirement or capability unchanged **THEN** the gate asks nothing of it
|
|
116
|
+
- **WHEN** the base already carries a scenario unbound and the request does not change it **THEN** coverage lists it, and the run does not fail
|
|
117
|
+
|
|
118
|
+
## Base resolution
|
|
119
|
+
|
|
120
|
+
`--base auto` picks the base from where the run happens:
|
|
121
|
+
|
|
122
|
+
| Run | Base | Effect |
|
|
123
|
+
| --- | --- | --- |
|
|
124
|
+
| Merge-request pipeline (`CI_MERGE_REQUEST_DIFF_BASE_SHA` set) | That SHA, which is already the merge base. The run exits 2 if the object is missing. | Every kind runs |
|
|
125
|
+
| Any other CI pipeline (`CI` set: a default-branch push, a schedule, a manual run) | None | The base-only kinds are skipped: `weakened`, `new-requirement`, `renamed-anchor`, `scenario-unproven`, `non-ears`, `non-bdd`. The skip is stated on stderr, and info findings are not printed. |
|
|
126
|
+
| Local | The merge base of `origin/HEAD` and `HEAD`, else of `origin/main` and `HEAD`. With neither, the run exits 2 and asks for `git fetch origin`. | Every kind runs. The head is the working tree, tracked plus untracked files. |
|
|
127
|
+
|
|
128
|
+
An explicit `--base <ref>` compares with the merge base of `<ref>` and `HEAD`. With no `--base`, no base is set.
|
|
129
|
+
|
|
130
|
+
## Exit codes and output
|
|
131
|
+
|
|
132
|
+
| Command | Purpose | Output |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| `spec-steward check [--base auto\|<ref>] [--binds <glob>]… [--file <f>] [--fix] [--strict] [--json]` | The corpus gate, run locally, in CI and by the hook | Findings ([below](#findings)) |
|
|
135
|
+
| `spec-steward coverage [--out <file>] [--binds <glob>]…` | The [coverage report](#coverage-report) | Markdown, to the file or to stdout |
|
|
136
|
+
| `spec-steward evidence --json [--binds <glob>]…` | The audit's [evidence model](#evidence-json) | JSON on stdout |
|
|
137
|
+
| `spec-steward evidence --out <dir>`, `partition`, `index`, `review`, `align`, `wire`, `hook` | Audit bundles and partitions, the corpus index, review files, cross-repository drift, wiring, the edit hook | As each command documents |
|
|
138
|
+
|
|
139
|
+
`spec-steward` is the package's `bin`. A repository calls it from its root scripts and never imports steward's modules: the package's `exports` map does not expose them, so the CLI and its JSON are the interface.
|
|
140
|
+
|
|
141
|
+
### Findings
|
|
142
|
+
|
|
143
|
+
- **stdout.** One finding per line: `<file>:<line> <severity> <kind> <message>`, prefixed with `<root> ` when several `--root` are given. With `--json`, stdout is instead an array of `{ root, file, line, severity, kind, id?, message }`.
|
|
144
|
+
- **stderr.** First `base: …`, then `N finding(s): <kind> <n>, …`, then `PASS|FAIL — e error(s), w warning(s), i prompt(s)`.
|
|
145
|
+
|
|
146
|
+
### Exit codes
|
|
147
|
+
|
|
148
|
+
| Code | When |
|
|
149
|
+
| --- | --- |
|
|
150
|
+
| 0 | No error finding |
|
|
151
|
+
| 1 | An error finding, or a warning under `--strict` |
|
|
152
|
+
| 2 | A usage or environment error: an unknown flag, a base ref that does not exist, a git file listing that failed or came back empty, a missing specs directory |
|
|
153
|
+
|
|
154
|
+
Exit 2 on an empty listing keeps a broken checkout from passing a scan that read nothing.
|
|
155
|
+
|
|
156
|
+
## Coverage report
|
|
157
|
+
|
|
158
|
+
`spec-steward coverage` writes a Markdown report that is MDX-safe: `<`, `>`, `{`, `}` and `|` are escaped. It gates nothing: it exits 0, or 2 on an environment error. Statuses come from [bindings](#binding) and [markers](#markers) only. A pointer never changes a status.
|
|
159
|
+
|
|
160
|
+
- **Headline.** Requirements and capabilities; Advisory requirements; Known gaps; REQUIRED requirements no test binds; REQUIRED scenarios no test binds; retired markers.
|
|
161
|
+
- **Per capability.** One table: `| Requirement / Scenario | Spec | Bound by | Pointers | Status |`.
|
|
162
|
+
- **Requirement status.** `advisory`, `tested`, `known gap (<tracker>)` or `no test`.
|
|
163
|
+
- **Scenario status.** `bound`, `known gap (<tracker>)` or `no test`, and a dash under an Advisory requirement.
|
|
164
|
+
- **Pointers.** The code and document citations of the requirement and its scenarios.
|
|
165
|
+
- **Closing sections.** "Known gaps" (tracker, requirement, text) and "Retired markers".
|
|
166
|
+
|
|
167
|
+
## Evidence JSON
|
|
168
|
+
|
|
169
|
+
`spec-steward evidence --json` writes the evidence an audit reads, one entry per requirement:
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
{ version: 1, root, requirements: [{ id, capability, file, line, end, block, class: 'required'|'advisory',
|
|
173
|
+
gaps: [{ tracker, text, line, scenario: null|'<slug>', exempts: ['<slug>'] }],
|
|
174
|
+
scenarios: [{ slug, line, end, block, bound }],
|
|
175
|
+
bindings: [{ file, line, anchor, kind: 'test'|'file', title, window: [a, b] }],
|
|
176
|
+
pointers: [{ file, line, anchor, kind: 'code'|'doc' }],
|
|
177
|
+
terms: [{ term, hits: [{ file, line }] }],
|
|
178
|
+
related: [{ id, shared: [term] }] }] }
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
- `class` is `advisory` when the requirement carries the Advisory marker, else `required`.
|
|
182
|
+
- `gaps` lists each Known gap line that carries a tracker. `scenario` is the slug of the scenario whose block holds the line, or `null` for a line under the requirement; `exempts` lists the slugs of the scenarios it exempts, empty when it exempts none.
|
|
183
|
+
- `bindings` are the citations that [bind](#binding) a scenario or the requirement. `kind` is `test` for a test-file binding, and `file` for a lint configuration or a `--binds` file. `title` is the bound test's title, or `null`; `window` is the line range of the bound block.
|
|
184
|
+
- `pointers` are every other citation of the requirement or its scenarios.
|
|
185
|
+
- `terms` are the requirement's own distinctive terms, with every hit in non-test sources after comments are stripped. Line numbers are kept.
|
|
186
|
+
- `related` lists the requirements that share terms with it, across capabilities.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# Audit criteria
|
|
2
|
+
|
|
3
|
+
An audit judges whether the corpus holds the **right** rules with the **right** evidence — specification quality first, implementation compliance only where code reveals a problem with the rule. Read [model.md](model.md) first.
|
|
4
|
+
|
|
5
|
+
## What deserves an item
|
|
6
|
+
|
|
7
|
+
Every rule, requirement or scenario that matches one of these, numbered so findings can name them:
|
|
8
|
+
|
|
9
|
+
1. A REQUIRED rule that should be ⚠️ ADVISORY.
|
|
10
|
+
2. A rule that belongs in `AGENTS.md`, a scoped rule, a skill, a command, the OPSX config or a README rather than the specification (place it per `rules/agent.md`).
|
|
11
|
+
3. A rule better enforced by deterministic tooling than by an AI audit.
|
|
12
|
+
4. A rule that produces low-value or artificial tests.
|
|
13
|
+
5. A rule whose tests satisfy the wording while failing to protect the intent.
|
|
14
|
+
6. A rule that cannot reasonably be verified.
|
|
15
|
+
7. A rule whose wording allows materially different interpretations. An undefined evaluative term in a REQUIRED statement (_thin_, _safe_, _lean_, _at parity_, _needed_) is a finding: replace it with the criterion it stands for, drop the sentence where a precise rule already carries the obligation, or, when nothing checkable remains, make it ⚠️ ADVISORY.
|
|
16
|
+
8. A rule that describes implementation detail instead of an externally meaningful invariant.
|
|
17
|
+
9. A rule redundant with, or substantially overlapping, another.
|
|
18
|
+
10. Contradictory rules.
|
|
19
|
+
11. A rule that no longer matches the implementation or architecture.
|
|
20
|
+
12. Implementation suggesting the specification itself is wrong or outdated.
|
|
21
|
+
13. A missing high-value invariant the architecture clearly relies on.
|
|
22
|
+
14. A rule whose scope is unclear.
|
|
23
|
+
15. A rule that forces repository-wide reasoning where a subsystem scope would do.
|
|
24
|
+
16. A rule that encourages agents to modify specifications merely to make an implementation pass.
|
|
25
|
+
17. A rule whose verification relies on comments or superficial textual matching.
|
|
26
|
+
18. A tiny rule whose maintenance and enforcement cost is disproportionate to the failure it prevents.
|
|
27
|
+
19. Requirements or scenarios that repeat each other.
|
|
28
|
+
20. Scenario/When/Then structure that adds verbosity without precision.
|
|
29
|
+
|
|
30
|
+
Organisational criteria, for the mechanisms around the corpus:
|
|
31
|
+
|
|
32
|
+
21. The same concern held by two or more mechanisms (spec, design, `AGENTS.md`, scoped rule, skill, command, OPSX config, tooling, test, audit) — name the authoritative one and the copies to remove.
|
|
33
|
+
22. A rule shared by several repositories but worded differently.
|
|
34
|
+
23. A CI or audit configuration whose cost buys no signal, or whose classification of a run is wrong.
|
|
35
|
+
24. Citation machinery whose upkeep exceeds its value.
|
|
36
|
+
|
|
37
|
+
## How to judge
|
|
38
|
+
|
|
39
|
+
- **Ask what failure the verification would catch.** If the answer is trivial, artificial, coupled to implementation, or proves only textual or structural conformity, do not propose that verification.
|
|
40
|
+
- **Do not create compliance theatre.** Never propose a test merely because a rule lacks one.
|
|
41
|
+
- **Comments are never evidence and never a violation.** Judge executable behaviour and structure.
|
|
42
|
+
- **Two markers, nothing else.** A requirement is REQUIRED, or carries `**⚠️ Advisory:**`; absent behaviour or missing evidence is a `**⚠️ Known gap (<tracker>):**` line ([model.md](model.md#advisory-known-gap-or-neither), spellings in [contract.md](contract.md#markers)). A retired `**⚠️ Unenforced:**`, an untracked Known gap and an unmarked silence are findings, and a proposal never introduces one.
|
|
43
|
+
- **Ordinary bugs are out of scope** unless they show the rule is unrealistic, unclear, outdated, ambiguous, or contradicted by the tests' actual contract.
|
|
44
|
+
- **Do not decide intent silently.** Where the intent is ambiguous, say so and propose options; flag `needsHumanIntent`.
|
|
45
|
+
- **Do not flag style preference.** Every finding has a concrete reason.
|
|
46
|
+
- **Internal contracts are specification.** Do not move a rule out of the corpus because it is not user-facing.
|
|
47
|
+
- **Past owner decisions are stated.** A proposal that reverses one names it.
|
|
48
|
+
|
|
49
|
+
## Proposals name their target
|
|
50
|
+
|
|
51
|
+
Start every proposal with one of:
|
|
52
|
+
|
|
53
|
+
- `Keep → OpenSpec REQUIRED invariant` (optionally with a rewrite, or with a `**⚠️ Known gap (<tracker>):**` line when its behaviour or its evidence is missing)
|
|
54
|
+
- `Reclassify → OpenSpec ⚠️ ADVISORY` (the requirement gains an `**⚠️ Advisory:**` line; one that mixes a contract with guidance is split, the contract staying REQUIRED)
|
|
55
|
+
- `Move → <target>` — the design narrative (the repository's design documents or a package README), `<dir>/AGENTS.md`, `scoped rule (<glob>)`, `skill <name>` (referenced from `AGENTS.md` when it holds material moved out of it), `command <name>`, `openspec/config.yaml#<key>`, `README.md`
|
|
56
|
+
- `Replace → <tool>` — ESLint rule, dependency rule, type assertion, schema, script
|
|
57
|
+
- `Merge → <other rule>`
|
|
58
|
+
- `Rewrite → "<new text>"`
|
|
59
|
+
- `Delete → <reason>`
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# The specification model
|
|
2
|
+
|
|
3
|
+
Where a piece of guidance lives is decided by `rules/agent.md`, shipped by `@kirill.konshin/lint`; in a repository it is `.agents/rules/agent.md`. Read it there; this file covers only what is specific to the specifications themselves. What the gate checks mechanically — citations, binding, markers, size lines, the scenario ratchet — is [contract.md](contract.md).
|
|
4
|
+
|
|
5
|
+
## A rule in `openspec/specs` is a contract
|
|
6
|
+
|
|
7
|
+
A requirement states durable, observable behaviour of the system or of a component: inputs and validation, outputs, error semantics, lifecycle, state transitions, ordering, compatibility, persistence, concurrency, interactions between components. Internal package and API contracts qualify as much as user-facing behaviour — the line is **contract versus implementation or process**, never product versus engineering.
|
|
8
|
+
|
|
9
|
+
Normative force is carried by the RFC 2119 keywords — MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL — written in capitals and read as RFC 2119 defines them; emphasis or capitalisation of any other word carries no force, and a keyword inside backticks is mentioned, not issued.
|
|
10
|
+
|
|
11
|
+
A specification describes only real, existing behaviour. What is knowingly absent or incomplete is recorded as a [Known gap](#advisory-known-gap-or-neither), never written as though implemented and never left as unmarked silence.
|
|
12
|
+
|
|
13
|
+
Apply the two litmus questions from `rules/agent.md`; then the decision test:
|
|
14
|
+
|
|
15
|
+
> **Name the observable failure this rule prevents, and the cheapest evidence that would catch it.**
|
|
16
|
+
|
|
17
|
+
If you cannot name a failure, the rule is not a REQUIRED contract.
|
|
18
|
+
|
|
19
|
+
## Two kinds of requirement
|
|
20
|
+
|
|
21
|
+
| Kind | Meaning | Evidence |
|
|
22
|
+
| --- | --- | --- |
|
|
23
|
+
| **REQUIRED** | An invariant whose violation is a real defect — behavioural, API, compatibility, security, data. | The cheapest rung that catches the failure (ladder below). The requirement names that failure and that rung; a test is one rung, not the only one. |
|
|
24
|
+
| **⚠️ ADVISORY** | Design guidance that matters but cannot reasonably be proven mechanically. | Review judgement. Never a gate, never a reason to write a test. |
|
|
25
|
+
|
|
26
|
+
A REQUIRED requirement stating an absolute names its exceptions, or has none; one with neither is listed for the owner's review.
|
|
27
|
+
|
|
28
|
+
## Advisory, Known gap, or neither
|
|
29
|
+
|
|
30
|
+
A requirement is REQUIRED unless a marker says otherwise. The exact spellings, and what each exempts, are in [contract.md](contract.md#markers).
|
|
31
|
+
|
|
32
|
+
- **⚠️ Advisory** — permanent guidance whose only evidence is review, such as a design direction. Its line says why review is its evidence, and its RFC 2119 keywords stay. The marker qualifies the whole requirement, so a requirement that mixes a contract with guidance is split, and the contract half stays REQUIRED. Marking an existing requirement Advisory weakens it, so the owner confirms it.
|
|
33
|
+
- **⚠️ Known gap (<tracker>)** — behaviour the requirement describes is knowingly absent or incomplete, or a REQUIRED rule lacks the evidence that would catch its failure. The line says what is missing (for missing evidence, the missing rung) and names what tracks it: a ticket, a tickets-page entry or an open change. Under the requirement, it names by title the scenarios it exempts; inside a scenario's block, it exempts that scenario. A gap is never restated as a scenario, and a scenario that a gap conditions states that condition.
|
|
34
|
+
- **Neither** — a test (an end-to-end test included), a type assertion, a lint entry or a deterministic check that CI runs proves the rule. It stays REQUIRED and unmarked.
|
|
35
|
+
|
|
36
|
+
## The evidence ladder — cheapest first
|
|
37
|
+
|
|
38
|
+
1. The type system or compiler
|
|
39
|
+
2. Deterministic static analysis — lint, dependency rules, schema validation, a simple script
|
|
40
|
+
3. A behavioural test of the contract
|
|
41
|
+
4. A focused integration or end-to-end test
|
|
42
|
+
5. Implementation evidence a reader can point at
|
|
43
|
+
6. Review judgement, for a genuinely semantic concern
|
|
44
|
+
|
|
45
|
+
Prefer the cheapest rung that catches the failure. Never spend an LLM audit on what rungs 1–2 can prove. A requirement that constrains a shape, an interface or a structure rather than runtime behaviour is proven at rung 1 or 2 — a compile-time type assertion, a schema assertion, a lint entry or a deterministic script — as fully as a runtime test would prove it. Rungs 1–4 bind a scenario through a citation ([contract.md](contract.md#binding)); rungs 5 and 6 cannot. A REQUIRED rule that only they evidence therefore takes a Known gap naming the missing rung once one of its scenarios is added or changed.
|
|
46
|
+
|
|
47
|
+
## What is not evidence
|
|
48
|
+
|
|
49
|
+
- **Comments, descriptions, prompt or documentation text, and citations.** They are not evidence that code complies, and their absence or wording is never a violation. A citation in code is an optional pointer for a reader; the only rule on it is that it resolves.
|
|
50
|
+
- **A test that reads source, spec or documentation text** and asserts on it proves the text is present, not that the system behaves. If the structure itself is the contract (a dependency boundary, a manifest field), a deterministic tool usually proves it better than a test.
|
|
51
|
+
- **Coverage.** A test written so that spec prose counts as "covered" is compliance theatre. A test exists because it catches a meaningful regression.
|
|
52
|
+
|
|
53
|
+
## Citations
|
|
54
|
+
|
|
55
|
+
A code citation is written only where a reader needs the pointer: on the declaration whose behaviour it explains, never on a file's header, whose scope is everything and therefore nothing. Write it `{@link openspec/specs/<capability>/spec.md#<anchor>}`, addressed from the repository root, inside the declaration's `/** */` block, or as a `//` comment where JSDoc cannot attach. The gate checks only that it resolves.
|
|
56
|
+
|
|
57
|
+
## Tests and scenarios
|
|
58
|
+
|
|
59
|
+
A spec-driven test names the scenario it proves (`{@link openspec/specs/<capability>/spec.md#scenario-<slug>}`), so the binding between contract and evidence is explicit. The citation goes in the comment directly above the `describe`/`it`/`test` call, or inside it. A citation in a test file's header binds nothing ([contract.md](contract.md#binding)). A requirement with a single scenario may be cited by its requirement anchor.
|
|
60
|
+
|
|
61
|
+
A requirement describes one coherent area of behaviour a reader can hold in their head; related cases group under it as scenarios, one case each. Several rules that govern the same area form one requirement, and its scenarios carry the individual cases. A scenario exercises one specific case, not a family of them. A requirement past a size line ([contract.md](contract.md#size-gate-with-obligation-counting)) is split into coherent areas, never into one requirement per sentence.
|
|
62
|
+
|
|
63
|
+
A scenario adds precision — one concrete case, preferably Given/When/Then — or it is not written; a scenario that restates its requirement is noise. A requirement may carry a single scenario. That is not a smell, and no case is padded in to avoid it; OpenSpec's strict validation needs at least one.
|
|
64
|
+
|
|
65
|
+
New and edited text uses EARS for requirement statements — When <trigger>, the <system> SHALL <response>; While <state>, the <system> SHALL …; If <condition>, then the <system> SHALL …; or The <system> SHALL … — and Given/When/Then for scenarios, with Given only where a precondition matters. The RFC 2119 keyword stays in capitals: OpenSpec's strict validation fails a requirement whose body has no SHALL or MUST. Untouched text is not rewritten for syntax alone.
|
|
66
|
+
|
|
67
|
+
## Changing a rule
|
|
68
|
+
|
|
69
|
+
- Never weaken, narrow, delete or reclassify a rule to make code pass. A demonstrated divergence is decided by the owner: the code is wrong, or the rule is — and a wrong rule is changed openly, through the repository's change process.
|
|
70
|
+
- A rule shared by several repositories is worded identically in each.
|
|
71
|
+
- A rule restated in two places is one rule too many: keep it in the owning place and reference it elsewhere.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Review file format
|
|
2
|
+
|
|
3
|
+
An audit's findings go to the owner as one Markdown review file. The owner answers each item, and the file stays as the audit trail across rounds. `steward review render` writes items in this format; `steward review lint` checks it; `steward review verify --root NAME=path` checks that every quote is found where its location says; `steward review status` counts the answers.
|
|
4
|
+
|
|
5
|
+
## Items
|
|
6
|
+
|
|
7
|
+
Each item has a scan line and five bullets. The bullet labels are fixed — the parser reads them.
|
|
8
|
+
|
|
9
|
+
```md
|
|
10
|
+
### R-007 · SPEC-ADVISORY · CXAD apps/mastra · 1, 6
|
|
11
|
+
|
|
12
|
+
- Rule: “The A2A endpoint and Agent Card are the ONLY surface a consumer may target”
|
|
13
|
+
- Location: `CXAD openspec/specs/apps/mastra/spec.md:20`
|
|
14
|
+
- What’s wrong: <the concrete problem>. Evidence: `apps/mastra/src/main.ts:59`.
|
|
15
|
+
- Proposed: Reclassify → OpenSpec ⚠️ ADVISORY — <exactly what to do>
|
|
16
|
+
- My response: ⬜
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- **Scan line**: `### R-NNN · <owning layer> · <area> · <criteria numbers>`, plus `· ❓ intent` when the intent is ambiguous and the item proposes options.
|
|
20
|
+
- **Rule**: the original text, quoted verbatim, so the owner recognises the rule without opening the file. Use `…` to elide.
|
|
21
|
+
- **Location**: `` `NAME path:line` ``, where NAME is the repository and path is repository-relative.
|
|
22
|
+
- **Proposed**: starts with the target notation of [criteria.md](criteria.md#proposals-name-their-target).
|
|
23
|
+
|
|
24
|
+
## Theme items
|
|
25
|
+
|
|
26
|
+
When several rules share one problem and one solution, they become a single theme item. Its Rule bullet lists the members, each with its own quote and location.
|
|
27
|
+
|
|
28
|
+
```md
|
|
29
|
+
### R-012 · DELETE · Theme: Scenarios that restate their requirement · 19, 20
|
|
30
|
+
|
|
31
|
+
- Rule: “Scenarios that restate their requirement” — 3 rules:
|
|
32
|
+
- “WHEN the module is evaluated THEN no instance exists until the factory runs” — `CXAD openspec/specs/apps/mastra/spec.md:31`
|
|
33
|
+
- “…” — `APC openspec/specs/client/spec.md:88` — member-specific note
|
|
34
|
+
- Location: each member above
|
|
35
|
+
- What’s wrong: …
|
|
36
|
+
- Proposed: …
|
|
37
|
+
- My response: ⬜
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The owner gives one verdict for the whole theme, or comments under individual members by adding indented lines below a member. A rule appears in exactly one item. A second, distinct problem with the same rule becomes its own item, cross-referencing the first.
|
|
41
|
+
|
|
42
|
+
## Responses
|
|
43
|
+
|
|
44
|
+
| The owner writes | Meaning |
|
|
45
|
+
| ---------------- | ------------------------------------------------------------------------- |
|
|
46
|
+
| `⬜` | open — not yet answered |
|
|
47
|
+
| `✅` | accept the proposal |
|
|
48
|
+
| `✅ <comment>` | accept, with the clarification or instruction in the comment |
|
|
49
|
+
| `<comment>` | neither accepted nor rejected: interpret the comment and revisit the item |
|
|
50
|
+
| `❌` | reject: keep the rule as it is |
|
|
51
|
+
| `❌ <comment>` | reject, and follow the comment instead |
|
|
52
|
+
|
|
53
|
+
Silence is never approval. An item left at ⬜ is open.
|
|
54
|
+
|
|
55
|
+
## After a round
|
|
56
|
+
|
|
57
|
+
Processing a round ([apply.md](apply.md)) adds to the file and never deletes from it:
|
|
58
|
+
|
|
59
|
+
- **An applied item** gets ` * Applied: R<round> — <what changed, with paths>` after its response.
|
|
60
|
+
- **A comment-only item** is revisited. The previous answer moves into ` * Previous response (R<n>): …`, the proposal is revised in place, and the response resets to `⬜`.
|
|
61
|
+
- **New findings** go under `## Round <n> — new`, numbered after the last item, so resolved items stay recognisable as the trail.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Wiring the guard into a repository
|
|
2
|
+
|
|
3
|
+
A skill is discovered at the agent's discretion, so it cannot be the only thing that prevents a bad spec edit. The guard steers through points that reach the agent anyway. `steward wire --check` verifies each point, and every `steward` command warns in one line when one is missing.
|
|
4
|
+
|
|
5
|
+
| Point | What it does | Placed by |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| Scoped rule `.agents/rules/openspec.md` (+ `.claude/rules`, `.codex/rules`) | Hard constraints, loaded when the agent touches `openspec/**`. | `lint-prepare` (`@kirill.konshin/lint`) |
|
|
8
|
+
| Skill `.agents/skills/spec-steward` (+ `.claude/skills`, `.codex/skills`) | The procedures, the model, the contract and the scripts. | `lint-prepare` |
|
|
9
|
+
| Edit hook in `.claude/settings.json` | Runs `steward hook` after every Edit/Write/MultiEdit and feeds findings back to the agent at once — only for what the edit changed, with no ratchet. | `steward wire --fix` |
|
|
10
|
+
| Routing line in `AGENTS.md` | Tells every agent, Codex included, where the guard lives, and that corpus-quality audits use this skill while code conformance is the repository's own audit. | You, beside the specification-driven convention; `wire --fix` prints the line. |
|
|
11
|
+
| OPSX operation guidance in `openspec/config.yaml` | One narrow line each for `apply` and `archive`: run the repository's spec gate (AGENTS.md → Checks); a `weakened` finding stops the flow. | `steward wire --fix`, when the file has OpenSpec's standard shape |
|
|
12
|
+
|
|
13
|
+
These five points keep to the placement rules:
|
|
14
|
+
|
|
15
|
+
- Nothing restates `rules/agent.md` or the repository's own rules.
|
|
16
|
+
- The OPSX `context` stays untouched: it already carries `AGENTS.md`.
|
|
17
|
+
- The hook is a no-op where the skill is not installed, so teammates without it are not blocked.
|
|
18
|
+
|
|
19
|
+
**The gate.** A repository's spec gate (`spec:gates` and its CI job, listed in `AGENTS.md` → Checks) runs `steward check --base auto`, passing the repository's `--binds` globs, and then whatever change gates the repository keeps. Error findings fail it; warnings and prompts never do ([contract](contract.md#kinds-and-severities)). Steward is the one spec engine, so it never runs as a second job beside an existing gate, and the repository keeps no copy of a check steward implements. Whether a repository puts the gate in CI is its owner's decision.
|
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* Rules shared by several repositories, compared: capabilities pair by path or by leaf name, requirements by anchor or
|
|
4
|
+
* by text. Reports identical, drifted and one-sided rules; choosing the wording stays with the owner.
|
|
5
|
+
*/
|
|
6
|
+
import { loadCorpus } from './corpus.mjs';
|
|
7
|
+
import { jaccard, normalize, words } from './util.mjs';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* @typedef {import('./corpus.mjs').Corpus} Corpus
|
|
11
|
+
* @typedef {import('./corpus.mjs').Requirement} Requirement
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/** Body without heading, normalized. @param {Requirement} r */
|
|
15
|
+
const body = (r) => normalize(r.block.split('\n').slice(1).join('\n'));
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Word-level difference of two texts: the words only one side has, in order.
|
|
19
|
+
* @param {string} a
|
|
20
|
+
* @param {string} b
|
|
21
|
+
*/
|
|
22
|
+
export function wordDiff(a, b) {
|
|
23
|
+
const wa = normalize(a).split(' ');
|
|
24
|
+
const wb = normalize(b).split(' ');
|
|
25
|
+
const sa = new Set(wa);
|
|
26
|
+
const sb = new Set(wb);
|
|
27
|
+
return { onlyA: wa.filter((w) => !sb.has(w)).join(' '), onlyB: wb.filter((w) => !sa.has(w)).join(' ') };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* @param {Corpus} a
|
|
32
|
+
* @param {Corpus} b
|
|
33
|
+
*/
|
|
34
|
+
export function align(a, b) {
|
|
35
|
+
const pairs = [];
|
|
36
|
+
const leaf = (/** @type {string} */ c) => c.split('/').pop();
|
|
37
|
+
for (const ca of a.capabilities) {
|
|
38
|
+
const cb =
|
|
39
|
+
b.capabilities.find((x) => x.capability === ca.capability) ??
|
|
40
|
+
b.capabilities.find((x) => leaf(x.capability) === leaf(ca.capability));
|
|
41
|
+
if (!cb) continue;
|
|
42
|
+
const used = new Set();
|
|
43
|
+
const reqs = [];
|
|
44
|
+
for (const ra of ca.requirements) {
|
|
45
|
+
let rb = cb.requirements.find((x) => x.slug === ra.slug && !used.has(x.slug));
|
|
46
|
+
if (!rb) {
|
|
47
|
+
const best = cb.requirements
|
|
48
|
+
.filter((x) => !used.has(x.slug))
|
|
49
|
+
.map((x) => ({ x, s: jaccard(words(ra.block), words(x.block)) }))
|
|
50
|
+
.sort((p, q) => q.s - p.s)[0];
|
|
51
|
+
if (best && best.s >= 0.5) rb = best.x;
|
|
52
|
+
}
|
|
53
|
+
if (!rb) {
|
|
54
|
+
reqs.push({ kind: 'only-a', a: ra });
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
used.add(rb.slug);
|
|
58
|
+
const same = body(ra) === body(rb) && ra.name === rb.name;
|
|
59
|
+
reqs.push({
|
|
60
|
+
kind: same ? 'identical' : 'drift',
|
|
61
|
+
a: ra,
|
|
62
|
+
b: rb,
|
|
63
|
+
...(same ? {} : wordDiff(ra.block, rb.block)),
|
|
64
|
+
});
|
|
65
|
+
}
|
|
66
|
+
for (const rb of cb.requirements) if (!used.has(rb.slug)) reqs.push({ kind: 'only-b', b: rb });
|
|
67
|
+
pairs.push({ a: ca.capability, b: cb.capability, requirements: reqs });
|
|
68
|
+
}
|
|
69
|
+
return pairs;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* @param {Record<string, any>} opts
|
|
74
|
+
* @param {{ name: string, path: string, specsDir: string }[]} roots
|
|
75
|
+
*/
|
|
76
|
+
export function alignCli(opts, roots) {
|
|
77
|
+
if (roots.length < 2) {
|
|
78
|
+
process.stderr.write('align needs two --root NAME=path\n');
|
|
79
|
+
return 2;
|
|
80
|
+
}
|
|
81
|
+
const [ra, rb] = roots;
|
|
82
|
+
const pairs = align(loadCorpus(ra.path, ra), loadCorpus(rb.path, rb));
|
|
83
|
+
if (opts.json) {
|
|
84
|
+
process.stdout.write(
|
|
85
|
+
JSON.stringify(
|
|
86
|
+
pairs.map((p) => ({
|
|
87
|
+
...p,
|
|
88
|
+
requirements: p.requirements.map((r) => ({
|
|
89
|
+
kind: r.kind,
|
|
90
|
+
a: r.a && `${r.a.file}:${r.a.line} ${r.a.name}`,
|
|
91
|
+
b: r.b && `${r.b.file}:${r.b.line} ${r.b.name}`,
|
|
92
|
+
onlyA: r.onlyA,
|
|
93
|
+
onlyB: r.onlyB,
|
|
94
|
+
})),
|
|
95
|
+
})),
|
|
96
|
+
null,
|
|
97
|
+
2,
|
|
98
|
+
) + '\n',
|
|
99
|
+
);
|
|
100
|
+
return 0;
|
|
101
|
+
}
|
|
102
|
+
let drift = 0;
|
|
103
|
+
for (const p of pairs) {
|
|
104
|
+
const count = (/** @type {string} */ k) => p.requirements.filter((r) => r.kind === k).length;
|
|
105
|
+
process.stdout.write(
|
|
106
|
+
`\n${ra.name}:${p.a} ↔ ${rb.name}:${p.b} — identical ${count('identical')}, drift ${count('drift')}, only ${ra.name} ${count('only-a')}, only ${rb.name} ${count('only-b')}\n`,
|
|
107
|
+
);
|
|
108
|
+
for (const r of p.requirements) {
|
|
109
|
+
if (r.kind === 'identical') continue;
|
|
110
|
+
if (r.kind === 'drift') {
|
|
111
|
+
drift++;
|
|
112
|
+
process.stdout.write(
|
|
113
|
+
` drift ${ra.name} ${r.a?.file}:${r.a?.line} ↔ ${rb.name} ${r.b?.file}:${r.b?.line} "${r.a?.name}"\n`,
|
|
114
|
+
);
|
|
115
|
+
if (r.onlyA) process.stdout.write(` only ${ra.name}: ${r.onlyA.slice(0, 300)}\n`);
|
|
116
|
+
if (r.onlyB) process.stdout.write(` only ${rb.name}: ${r.onlyB.slice(0, 300)}\n`);
|
|
117
|
+
} else {
|
|
118
|
+
const x = r.a ?? r.b;
|
|
119
|
+
process.stdout.write(
|
|
120
|
+
` ${r.kind === 'only-a' ? `only ${ra.name}` : `only ${rb.name}`} ${x?.file}:${x?.line} "${x?.name}"\n`,
|
|
121
|
+
);
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
return drift ? 1 : 0;
|
|
126
|
+
}
|