@descent-vtt/spec-graph 0.8.0 → 0.9.1

package/README.md

@@ -123,12 +123,28 @@ onto four phases, chosen so one question can be answered from the phase alone:
 | `draft` | `proposed`, `provisional`, `wip`, `in-review`, `experimental`, … | yes |
 | `active` | `accepted`, `implementable`, `implemented`, `merged`, `adopted`, … | yes |
 | `frozen` | `final`, `ratified`, `locked`, `published`, … | **no** |
-| `retired` | `superseded`, `deprecated`, `rejected`, `withdrawn`, `archived`, … | **no** |
+| `retired` | `superseded`, `deprecated`, `rejected`, `withdrawn`, … | **no** |
 
 The status is found wherever your team writes it — front matter (`status:`,
 `state:`, `stage:`), a `## Status` section, `**Accepted** (2026-03-01) ✅`, or a
 `docs/adr/archive/` directory. `Accepted, later superseded by ADR-0009` is
-retired: retirement is terminal, so a retirement word anywhere wins.
+retired: retirement is terminal, so a retirement word anywhere wins. Front
+matter is read as YAML reads it, and a value YAML would not read -
+`status: Superseded by ADR-9: see notes`, where a plain value cannot hold `: ` -
+is left out rather than guessed at. Every run says how many statuses, ids and
+relations it left out that way, and `--verbose` says where and why: quote the
+value and it is read.
+
+`archived` is none of the four. It is what spec-brief writes on a round of work
+it has closed, and every spec-* tool reads it as a **record**: depending on it
+is normal, its unticked boxes are not anyone's work, its links are still
+checked, and new work handed to it is still a ghost handover. See
+[Journals, changelogs and minutes](#journals-changelogs-and-minutes). Unlike a
+journal, it still answers for what it claims: a supersession it declares, a
+cycle it closes and a link to itself are reported as they would be anywhere.
+To retire a decision, say `superseded` or `deprecated` -
+`archived, superseded by ADR-0009` is retired - and a document under an
+`archive/` directory that says nothing about itself is still retired.
 
 An unrecognised status becomes `unknown`, and rules treat it permissively. It
 never guesses.
@@ -242,7 +258,7 @@ Both forms need **two** signals, and that is deliberate: `## Q3 2026 Roadmap`
 parses as family `Q`, number 3, and `## v1.2.0` in a changelog parses as family
 `v`, number 1. Neither declares a status, so neither is a specification. A table
 of identifiers and prose is a citation list, not a register. See
-[ADR-0009](docs/adr/0009-a-specification-is-a-region.md).
+[ADR-0009](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0009-a-specification-is-a-region.md).
 
 ### When `[[...]]` tags a concept
 
@@ -272,7 +288,7 @@ The tool names that flag in the hint, so it costs one run to find:
 `--ignore-ref` suppresses *findings*, never edges. A reference that resolves is
 still a relation in the graph no matter what you exclude — not even
 `--ignore-ref "*"` can delete one. See
-[ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
+[ADR-0008](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0008-wiki-links-carry-no-path.md).
 
 #### A gap that is deliberate
 
@@ -399,16 +415,17 @@ against a fifty-four-character title takes `RegExp` 103 seconds and this 13
 microseconds. It reads the usual syntax minus backreferences and lookaround,
 which are not regular; both are refused when the selector is read, with the
 character pointed at. Globs - the patterns to check, `--ignore`, `--ignore-ref`,
-`--history` - are matched by the same automaton, because a glob with three stars
-in it is
-enough to keep `RegExp` busy for two minutes over a long reference target. See
-[ADR-0017](docs/adr/0017-a-predicate-must-finish.md).
+`--history` - are matched by an automaton too, because a glob with three stars
+in it is enough to keep `RegExp` busy for two minutes over a long reference
+target. See [ADR-0017](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0017-a-predicate-must-finish.md). Both automata
+are spec-core's, the library the spec-* tools share, copied into this package
+rather than installed.
 
 On a register, a region answers its file's front matter for every descriptive
 key — `fm.owner` on a decision inside a register is the register's owner — while
 the keys a region owns itself, its identifier and status and title, and any key
 that declares a relation, stay on the file. See
-[ADR-0009](docs/adr/0009-a-specification-is-a-region.md).
+[ADR-0009](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0009-a-specification-is-a-region.md).
 
 ## Your own rules
 
@@ -472,7 +489,7 @@ spec-graph: .spec-graph.json: rules.owner: "{1.phse}" asks for an attribute
   nothing has
 ```
 
-See [ADR-0016](docs/adr/0016-a-query-needs-a-sentence.md).
+See [ADR-0016](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0016-a-query-needs-a-sentence.md).
 
 ## Directives
 
@@ -508,7 +525,10 @@ had:
 { "historyPatterns": ["**/JOURNAL_*.md", "archive/**"] }
 ```
 
-or, for one file, `<!-- @spec-history -->` at the top of it.
+or, for one file, `<!-- @spec-history -->` at the top of it. A brief whose
+status is `archived` is a record already, with nothing declared, though not a
+log: the supersessions, cycles and self-references it declares are still
+checked.
 
 |  |  |
 | --- | --- |
@@ -520,7 +540,7 @@ or, for one file, `<!-- @spec-history -->` at the top of it.
 That last row is the point. Excluding the file with `--ignore` would have
 silenced the whole lot, including the links, and a journal full of 404s is
 exactly what this tool is for. See
-[ADR-0011](docs/adr/0011-a-record-is-not-a-specification.md).
+[ADR-0011](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0011-a-record-is-not-a-specification.md).
 
 ## Adopting this on a repository that predates it
 
@@ -576,7 +596,7 @@ nothing left to be stale about, so a typo in it looks exactly like a regression
 nobody introduced: it exits `2` instead. A `"baseline"` in the configuration is
 the other case and stays optional, because a repository declares the path before
 the first run records the file — `--verbose` says when it read nothing. Either
-may be absolute. See [ADR-0012](docs/adr/0012-a-baseline-is-a-ratchet.md).
+may be absolute. See [ADR-0012](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0012-a-baseline-is-a-ratchet.md).
 
 ## In CI
 
@@ -599,9 +619,34 @@ without drifting, because the `partialFingerprints` spec-graph writes are the
 same identity a baseline is keyed on — the rule, the specification, and the
 citation, with no line number in it (ADR-0012).
 
-`--format json` is the other machine-readable output, and the one to parse if
-you are building something of your own: it carries the baseline note, the
-summary and the per-file detail that SARIF has nowhere to put.
+On GitLab, `--format gitlab` writes the Code Quality report a merge request
+reads, and the merge request shows which findings it introduced and which it
+resolved:
+
+```yaml
+spec-graph:
+  script:
+    - npx spec-graph --format gitlab > gl-code-quality-report.json
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json
+```
+
+Each finding is an issue with its rule as `check_name`, its message and hint as
+`description`, and its file and line as `location`. Severities map as `error`
+to `critical` - or `major` when only `--strict` made it an error - `warn` to
+`minor` and `info` to `info`. The `fingerprint` is a SHA-256 of the rule, the
+specification and what within it - a citation's target, or the document at the
+other end - which is what a baseline counts by. There is no line in it, so a
+finding a paragraph moved is not reported as new, and no message, so ticking
+one of three open boxes does not make an `orphaned-obligation` new either; the
+second of two findings identical in all three is told apart by its order. `when: always` keeps the report when the job fails, which
+it does, with exit `1`, whenever there is an error to report.
+
+`--format json` is the machine-readable output to parse if you are building
+something of your own: it carries the baseline note, the summary and the
+per-file detail that SARIF and Code Quality have nowhere to put.
 
 **There is no `--watch`.** A full run on this repository takes 60 ms, so the
 loop that would justify a resident process is one line of shell, and it belongs
@@ -642,7 +687,7 @@ the root**. So a run from `packages/auth` reports what a run from the top
 reports, byte for byte, because every path here is relative to the root. The
 nearest file wins, `--root` names the root yourself and turns discovery off, and
 a path typed on the command line stays relative to where you typed it. See
-[ADR-0018](docs/adr/0018-the-configuration-file-is-the-root.md).
+[ADR-0018](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0018-the-configuration-file-is-the-root.md).
 
 A flag always wins over the file, and list flags **add** to it rather than
 replacing it — a `--ignore-ref` on the command line is one more exclusion, not a
@@ -661,6 +706,39 @@ all — a silently ignored `ignoreReference` is a configuration that looks appli
 and is not. `--no-config` checks on defaults instead, and the exit code then
 says which run it was.
 
+### Patterns
+
+The patterns to check, `--ignore`, `--history` and `historyPatterns` are the
+glob dialect every spec-* tool reads, so a scope means the same to spec-graph
+as to the tool that wrote it. They are matched against the whole
+repository-relative path, **case-sensitively on every host** — a baseline
+recorded on a Windows checkout holds in Linux CI:
+
+| pattern | matches |
+| --- | --- |
+| `docs/**/*.md` | Markdown anywhere under `docs`; `**` is whole directories, none or more |
+| `docs/**.md` | refused: `**` is whole directories or nothing, so write `docs/**/*.md` or `docs/*.md` |
+| `docs` | a file called `docs`, or everything under the directory |
+| `docs/` | everything under `docs`, and not `docs` itself |
+| `{docs,specs}` | two literals, so both directories and what they hold |
+| `adr/[0-9]*.md`, `adr/[!0-9]*.md` | a class, and a negated one; `[^0-9]` negates too |
+| `!docs/drafts/**` | takes back what an earlier pattern matched; the last to match wins |
+| `docs\adr\*.md` | the same as `docs/adr/*.md`: a `\` is a separator |
+
+A class never matches a `/`, and a pattern that cannot mean a path under the
+root — an unclosed `[` or `{`, `..`, a lone `.`, an empty one — stops the run
+with exit `2` and names the pattern, wherever it was written. So does an
+extended glob, `+(a|b)`: write `{a,b}`. A parenthesis with no `|` in its group
+is itself, so `C++(notes).md` names that file. A `..` typed below the root,
+`spec-graph "../*.md"` from `docs/deep`, is resolved against where you typed
+it. A bare `--ignore` name, `--ignore drafts`, still prunes that directory at
+any depth.
+
+`--ignore-ref` is matched against reference targets rather than paths: a bare
+pattern names one target exactly, case is ignored on every host, a `\` escapes
+the next character, and `.` and `..` are the text of the link. See
+[ADR-0022](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0022-globs-are-the-family-path-dialect.md).
+
 ### Family rules
 
 Every specification cites RFC 2119. In a repository that also keeps its own
@@ -677,7 +755,7 @@ has — and turns every other noun-number construct back into prose.
 Both are consulted only after resolution has already failed, so `RFC 0001` still
 resolves to your local RFC-0001 with `RFC` on the ignore list. No configuration
 can delete an edge. See
-[ADR-0010](docs/adr/0010-configuration-belongs-to-the-repository.md).
+[ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md).
 
 `--verbose` lists everything they silenced, so one over-broad glob cannot quietly
 turn the check off and look like a clean repository:
@@ -691,7 +769,7 @@ The JSON report carries the same rows under `suppressed`, without needing the
 flag. What is deliberately *not* listed is a bare identifier spec-graph read as
 prose on its own — `T-1000` was nobody's decision, and listing it would bury the
 entries that were. See
-[ADR-0008](docs/adr/0008-wiki-links-carry-no-path.md).
+[ADR-0008](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0008-wiki-links-carry-no-path.md).
 
 Prose like `Phase 1`, `R69`, `Q-120`, `Table 2` and `Step 4` has never needed
 this: an identifier found in prose is only read as a citation when its family
@@ -720,7 +798,8 @@ spec-graph diff <before> <after>     Compare two JSON graph exports.
 --record-baseline <f>   Write today's findings as accepted debt, exit 0
 --ratchet               Also fail when a baseline entry no longer occurs
 --no-config             Ignore .spec-graph.json and the package.json key
---format <fmt>          human | json | sarif (check) | markdown (check, diff)
+--format <fmt>          human | json | sarif (check) | gitlab (check)
+                        | markdown (check, diff)
 --graph-format <fmt>    dot | mermaid | json
 --documents-only        Hide items; their relations lift onto their documents
 --rule <id>=<severity>  error | warn | info | off (repeatable)
@@ -801,7 +880,7 @@ document, section and title when nothing else shares them. Anything unpaired
 is reported as having appeared or disappeared, never as resolved or reopened.
 Findings are left to `--baseline`, which already reports what is new. The exit
 code is `0` whether anything changed or not: a diff describes, and `check`
-gates. See [ADR-0020](docs/adr/0020-a-diff-names-what-it-can-tell-apart.md).
+gates. See [ADR-0020](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0020-a-diff-names-what-it-can-tell-apart.md).
 
 ## Visualising
 
@@ -838,41 +917,47 @@ exported. Reporters, editor extensions and custom rules are all first-class.
 
 ## Design
 
-Twenty ADRs, which `spec-graph` validates on every CI run:
-
-- [ADR-0001 — A hand-written Markdown scanner](docs/adr/0001-hand-written-markdown-scanner.md)
-- [ADR-0002 — A four-phase lifecycle lattice](docs/adr/0002-lifecycle-lattice.md)
-- [ADR-0003 — Item state is resolved from competing signals](docs/adr/0003-item-state-signals.md)
-- [ADR-0004 — Reference resolution is deliberately asymmetric](docs/adr/0004-reference-resolution.md)
-- [ADR-0005 — The rules and the query language share one engine](docs/adr/0005-rules-are-queries.md)
-- [ADR-0006 — False positives cost more than misses](docs/adr/0006-false-positives-cost-more.md)
-- [ADR-0007 — Mutation testing, and what the score actually means](docs/adr/0007-mutation-testing.md)
-- [ADR-0008 — A wiki link carries a name, not a path](docs/adr/0008-wiki-links-carry-no-path.md)
-- [ADR-0009 — A specification is a region of a file, not a file](docs/adr/0009-a-specification-is-a-region.md)
-- [ADR-0010 — Configuration belongs to the repository](docs/adr/0010-configuration-belongs-to-the-repository.md)
-- [ADR-0011 — A historical record is not a specification](docs/adr/0011-a-record-is-not-a-specification.md)
-- [ADR-0012 — A baseline is a ratchet, keyed on identity](docs/adr/0012-a-baseline-is-a-ratchet.md)
-- [ADR-0013 — When the scanner is unsure, it hands back prose](docs/adr/0013-the-scanner-hands-back-prose.md)
-- [ADR-0014 — A relation is spelled in both directions](docs/adr/0014-a-relation-is-spelled-both-ways.md)
-- [ADR-0015 — Feedback goes where the tools already look](docs/adr/0015-feedback-goes-where-the-tools-already-look.md)
-- [ADR-0016 — A query needs a sentence before it is a rule](docs/adr/0016-a-query-needs-a-sentence.md)
-- [ADR-0017 — A predicate must finish](docs/adr/0017-a-predicate-must-finish.md)
-- [ADR-0018 — The configuration file is the root](docs/adr/0018-the-configuration-file-is-the-root.md)
-- [ADR-0019 — The sweep runs in shards](docs/adr/0019-the-sweep-runs-in-shards.md)
-- [ADR-0020 — A diff names only what it can tell apart](docs/adr/0020-a-diff-names-what-it-can-tell-apart.md)
+Twenty-three ADRs, which `spec-graph` validates on every CI run:
+
+- [ADR-0001 — A hand-written Markdown scanner](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0001-hand-written-markdown-scanner.md)
+- [ADR-0002 — A four-phase lifecycle lattice](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0002-lifecycle-lattice.md)
+- [ADR-0003 — Item state is resolved from competing signals](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0003-item-state-signals.md)
+- [ADR-0004 — Reference resolution is deliberately asymmetric](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0004-reference-resolution.md)
+- [ADR-0005 — The rules and the query language share one engine](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0005-rules-are-queries.md)
+- [ADR-0006 — False positives cost more than misses](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0006-false-positives-cost-more.md)
+- [ADR-0007 — Mutation testing, and what the score actually means](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md)
+- [ADR-0008 — A wiki link carries a name, not a path](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0008-wiki-links-carry-no-path.md)
+- [ADR-0009 — A specification is a region of a file, not a file](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0009-a-specification-is-a-region.md)
+- [ADR-0010 — Configuration belongs to the repository](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)
+- [ADR-0011 — A historical record is not a specification](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0011-a-record-is-not-a-specification.md)
+- [ADR-0012 — A baseline is a ratchet, keyed on identity](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0012-a-baseline-is-a-ratchet.md)
+- [ADR-0013 — When the scanner is unsure, it hands back prose](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0013-the-scanner-hands-back-prose.md)
+- [ADR-0014 — A relation is spelled in both directions](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0014-a-relation-is-spelled-both-ways.md)
+- [ADR-0015 — Feedback goes where the tools already look](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0015-feedback-goes-where-the-tools-already-look.md)
+- [ADR-0016 — A query needs a sentence before it is a rule](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0016-a-query-needs-a-sentence.md)
+- [ADR-0017 — A predicate must finish](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0017-a-predicate-must-finish.md)
+- [ADR-0018 — The configuration file is the root](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0018-the-configuration-file-is-the-root.md)
+- [ADR-0019 — The sweep runs in shards](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0019-the-sweep-runs-in-shards.md)
+- [ADR-0020 — A diff names only what it can tell apart](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0020-a-diff-names-what-it-can-tell-apart.md)
+- [ADR-0021 — Releases are published by CI, with provenance](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0021-releases-are-published-by-ci.md)
+- [ADR-0022 — Globs are the family's path dialect](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0022-globs-are-the-family-path-dialect.md)
+- [ADR-0023 — The scanner is the family's](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0023-the-scanner-is-the-familys.md)
 
 **Zero runtime dependencies.** Node 22+, native ESM, TypeScript strict with
 `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes`. The Markdown
 scanner, the front-matter reader, the glob matcher, the query parser and the
-regular-expression matcher behind `~=` are all written here, so the whole
-package is auditable in an afternoon — and nothing in the pipeline can take
-longer than its input.
+regular-expression matcher behind `~=` are all written here or in
+[spec-core](https://github.com/DescentVTT/spec-core), the library the spec-*
+tools share, whose code is copied into `src/vendor/` and checked by hash rather
+than installed. So the whole package is auditable in an afternoon — and nothing
+in the pipeline can take longer than its input.
 
-**Verified, not just covered.** 411 tests; 94.2% statement and 96.9% line
+**Verified, not just covered.** 1,053 tests; 96.8% statement and 98.2% line
 coverage. Coverage says a line ran, so the suite is also held to a mutation
-score - 74.05% over 6,150 mutants - because a vocabulary entry or a boundary
+score - 76.73% over 8,400 mutants at 0.9.0, measured incrementally in CI -
+because a vocabulary entry or a boundary
 condition can be weakened by an ordinary-looking refactor without a single test
-going red. [ADR-0007](docs/adr/0007-mutation-testing.md) is straight about what
+going red. [ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) is straight about what
 that number is and is not.
 
 **Fast enough to run on save.** A synthetic corpus of 2,000 documents — 8.9 MB,

package/dist/cli.d.ts

@@ -54,7 +54,7 @@ export interface CliOptions {
     readonly ratchet: boolean;
     /** Skip the repository configuration file entirely. */
     readonly noConfig: boolean;
-    readonly format: 'human' | 'json' | 'sarif' | 'markdown';
+    readonly format: 'human' | 'json' | 'sarif' | 'markdown' | 'gitlab';
     readonly graphFormat: GraphFormat;
     readonly severities: Partial<Record<AnyRuleId, Severity>>;
     readonly color: boolean | null;
@@ -77,7 +77,7 @@ export interface CliIO {
     readonly env?: Readonly<Record<string, string | undefined>> | undefined;
     readonly isTTY?: boolean | undefined;
 }
-export declare const HELP = "spec-graph - turn Markdown specifications into a verifiable graph\n\nUSAGE\n  spec-graph [check] [patterns...] [options]\n  spec-graph query <selector|project:rule> [patterns...] [options]\n  spec-graph graph [patterns...] [--graph-format dot|mermaid|json]\n  spec-graph rules [rule-id] [--explain]\n  spec-graph diff <before.json> <after.json> [--format human|json|markdown]\n\nCOMMANDS\n  check     Validate the specification graph. The default.\n  query     Run a selector - or a registered project rule, by its id - and\n            print the matching paths.\n  graph     Export the graph for Graphviz, Mermaid, or another tool.\n  rules     List the diagnostics that will run, built in and project. Name one\n            to see only that one; --explain adds its selector and the ADR that\n            decided it.\n  diff      Compare two graph exports: documents added, removed, moved or\n            accepted; relations added or removed; and obligations resolved or\n            reopened where they can be told apart. Make both exports with the\n            same spec-graph. Exits 0 whether anything changed or not.\n\nOPTIONS\n  --root <dir>            Directory the patterns resolve against. Without it,\n                          .spec-graph.json is looked for in the working\n                          directory and then upward as far as the repository,\n                          and the directory holding it becomes the root - so a\n                          run from a subdirectory reports what a run from the\n                          top reports. Paths typed on the command line stay\n                          relative to where they were typed.\n  --ignore <glob>         Skip paths. Repeatable.\n  --ignore-ref <glob>     Do not report these reference targets when they fail\n                          to resolve, for repositories where [[...]] tags a\n                          concept rather than naming a file. Repeatable.\n                          Suppresses findings only, never edges.\n  --family <name>         Families a bare identifier in prose may name. When\n                          given, everything else stays prose. Repeatable.\n  --ignore-family <name>  Families that are never citations - RFC when the repo\n                          cites RFC 2119 and keeps its own RFCs. Repeatable.\n  --history <glob>        Files that log what was decided rather than deciding\n                          it - journals, changelogs, minutes. Their links are\n                          still checked; their obligations are not. Repeatable.\n  --baseline <file>       Accept the findings recorded in this file and report\n                          only what is new since. The file has to be there: a\n                          path that reads nothing accepts nothing and says so\n                          nowhere. A \"baseline\" in the configuration may name a\n                          file not recorded yet; a path typed here may not.\n  --record-baseline <f>   Write today's findings to this file as accepted debt,\n                          and exit 0 without judging them.\n  --ratchet               Also fail when a baseline entry no longer occurs, so\n                          a paid-off exemption cannot outlive the defect.\n  --no-config             Ignore .spec-graph.json and the package.json key.\n  --format <fmt>          human, json, sarif or markdown. sarif is the\n                          interchange format GitHub code scanning and editors\n                          already read, for check; markdown is a table for a\n                          pull-request comment or $GITHUB_STEP_SUMMARY, for check\n                          or diff (default: human)\n  --graph-format <fmt>    dot, mermaid or json (default: dot)\n  --documents-only        Leave items out of the exported graph\n  --rule <id>=<severity>  Override one rule: error, warn, info or off. A project\n                          rule is named in full: project:no-draft-dependency.\n                          Repeatable.\n  --max <n>               Show at most n findings (0 = no limit)\n  --max-warnings <n>      Fail when warnings exceed n (default: no limit)\n  --strict                Raise every warning to an error. An explicit --rule\n                          still wins, so --strict --rule x=warn exempts x.\n  --color / --no-color    Force colour on or off\n  --ascii                 Use ASCII glyphs only\n  --verbose               Include parse problems, per-file detail, and every\n                          reference --ignore-ref or --ignore-family silenced\n  -h, --help              Show this help\n  -v, --version           Show the version\n\nSELECTORS\n  A selector is a path through the graph.\n\n    item[openness=open] -delegates-to-> document[phase=retired]\n    document[phase=active] -assumes-> document[phase=retired]\n    document =supersedes=> document\n    *[path^=docs/adr] -contains-> item[state=accepted-debt]\n\n  Node types:  document, item, * (any)\n  Attributes:  id, kind, title, path, file, line, phase, status, receptivity,\n               alias, document, state (or disposition), openness, section,\n               text, body, evidence, conflicted, fm.<front-matter-key>\n  Operators:   = != ^= $= *= ~=   and [attr] for \"is present\"\n               ~= is a regular expression, matched by an automaton that cannot\n               backtrack: linear in the subject, whatever the pattern. It reads\n               the usual syntax minus backreferences and lookaround, which are\n               not regular - both are refused when the selector is read, with\n               the character pointed at\n  Relations:   -kind->  <-kind-   =kind=>  <=kind=   (= forms are transitive)\n\nEXIT CODES\n  0  clean\n  1  findings at error severity (or over --max-warnings)\n  2  the tool could not run\n\nCONFIGURATION\n  Anything repeated on every run belongs in the repository rather than in the\n  command. spec-graph reads the first of these that exists:\n\n    .spec-graph.json, spec-graph.config.json, or a \"spec-graph\" key in\n    package.json\n\n    { \"patterns\": [\"docs/**/*.md\"],\n      \"ignoreReferences\": [\"trap *\"],\n      \"ignoreFamilies\": [\"RFC\"],\n      \"historyPatterns\": [\"**/JOURNAL_*.md\", \"archive/**\"],\n      \"baseline\": \".spec-graph-baseline.json\",\n      \"severities\": { \"self-reference\": \"off\" },\n      \"strict\": true }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it.\n\n  A problem in that file stops the run with exit 2, named on stderr: invalid\n  JSON, an unknown key, a rule that does not compile. A configuration that did\n  not load checks a different repository than the one configured, and would\n  report that one as consistent. --no-config runs on defaults instead.\n\nPROJECT RULES\n  A convention spec-graph never anticipated is a selector plus a sentence, and\n  belongs in the same file. Every rule declared here runs beside the built-ins\n  and is reported, baselined, escalated by --strict and silenced by --rule in\n  exactly the same way.\n\n    { \"rules\": {\n        \"no-draft-dependency\": {\n          \"query\": \"document[phase=active] -depends-on-> document[phase=draft]\",\n          \"message\": \"{0} depends on {1}, which is still a draft\",\n          \"hint\": \"wait for {1} to be accepted, or drop it from {0.path}\",\n          \"severity\": \"error\" } } }\n\n  query     One selector, or a list of them read as a union.\n  message   The headline. {0} is the first node on the path, {1} the next;\n            {1.phase} and {0.fm.owner} read any selector attribute.\n  hint      The next action. Optional, and templated the same way.\n  severity  error, warn, info or off. Defaults to warn - a rule a team has\n            just written has not yet earned the right to fail their build.\n\n  The id is the name with project: in front, which is why it can never collide\n  with a built-in. A selector that does not parse, or a {2} the query can never\n  reach, is reported when the file is read rather than found missing later.\n\n  To see what one matches without copying its selector out of the file:\n\n    spec-graph query project:no-draft-dependency --verbose\n\nADOPTING THIS ON AN OLD REPOSITORY\n  Record what is already wrong, then report only what happens next:\n\n    spec-graph check --record-baseline .spec-graph-baseline.json\n    git add .spec-graph-baseline.json\n\n  The file is keyed by specification and citation, not by line number, so it\n  survives edits, moves and renames. Findings that stop occurring are reported\n  so the file can be tightened; nothing new gets in.\n\nEXAMPLES\n  spec-graph \"docs/**/*.md\"\n  spec-graph check --rule self-reference=off --format json\n  spec-graph query 'item[openness=open] -delegates-to-> document[phase=retired]'\n  spec-graph check --ignore-ref \"trap *\"    # [[trap 55]] tags a concept, not a file\n  spec-graph graph --documents-only --graph-format mermaid > graph.mmd\n  spec-graph check --history \"**/JOURNAL_*.md\"   # a log is not a specification\n  spec-graph check --baseline .spec-graph-baseline.json\n  spec-graph rules --explain                # including this repository's own\n  spec-graph rules ghost-handover --explain      # and why it exists\n  spec-graph check --rule project:no-draft-dependency=off\n  spec-graph query project:no-draft-dependency   # what does that rule match?\n  spec-graph check --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n  spec-graph diff base.json head.json --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n";
+export declare const HELP = "spec-graph - turn Markdown specifications into a verifiable graph\n\nUSAGE\n  spec-graph [check] [patterns...] [options]\n  spec-graph query <selector|project:rule> [patterns...] [options]\n  spec-graph graph [patterns...] [--graph-format dot|mermaid|json]\n  spec-graph rules [rule-id] [--explain]\n  spec-graph diff <before.json> <after.json> [--format human|json|markdown]\n\nCOMMANDS\n  check     Validate the specification graph. The default.\n  query     Run a selector - or a registered project rule, by its id - and\n            print the matching paths.\n  graph     Export the graph for Graphviz, Mermaid, or another tool.\n  rules     List the diagnostics that will run, built in and project. Name one\n            to see only that one; --explain adds its selector and the ADR that\n            decided it.\n  diff      Compare two graph exports: documents added, removed, moved or\n            accepted; relations added or removed; and obligations resolved or\n            reopened where they can be told apart. Make both exports with the\n            same spec-graph. Exits 0 whether anything changed or not.\n\nOPTIONS\n  --root <dir>            Directory the patterns resolve against. Without it,\n                          .spec-graph.json is looked for in the working\n                          directory and then upward as far as the repository,\n                          and the directory holding it becomes the root - so a\n                          run from a subdirectory reports what a run from the\n                          top reports. Paths typed on the command line stay\n                          relative to where they were typed.\n  --ignore <glob>         Skip paths. Repeatable.\n  --ignore-ref <glob>     Do not report these reference targets when they fail\n                          to resolve, for repositories where [[...]] tags a\n                          concept rather than naming a file. Repeatable.\n                          Suppresses findings only, never edges.\n  --family <name>         Families a bare identifier in prose may name. When\n                          given, everything else stays prose. Repeatable.\n  --ignore-family <name>  Families that are never citations - RFC when the repo\n                          cites RFC 2119 and keeps its own RFCs. Repeatable.\n  --history <glob>        Files that log what was decided rather than deciding\n                          it - journals, changelogs, minutes. Their links are\n                          still checked; their obligations are not. Repeatable.\n  --baseline <file>       Accept the findings recorded in this file and report\n                          only what is new since. The file has to be there: a\n                          path that reads nothing accepts nothing and says so\n                          nowhere. A \"baseline\" in the configuration may name a\n                          file not recorded yet; a path typed here may not.\n  --record-baseline <f>   Write today's findings to this file as accepted debt,\n                          and exit 0 without judging them.\n  --ratchet               Also fail when a baseline entry no longer occurs, so\n                          a paid-off exemption cannot outlive the defect.\n  --no-config             Ignore .spec-graph.json and the package.json key.\n  --format <fmt>          human, json, sarif, gitlab or markdown. sarif is the\n                          interchange format GitHub code scanning and editors\n                          already read, and gitlab the Code Quality report a\n                          GitLab merge request reads, both for check; markdown\n                          is a table for a pull-request comment or\n                          $GITHUB_STEP_SUMMARY, for check or diff\n                          (default: human)\n  --graph-format <fmt>    dot, mermaid or json (default: dot)\n  --documents-only        Leave items out of the exported graph\n  --rule <id>=<severity>  Override one rule: error, warn, info or off. A project\n                          rule is named in full: project:no-draft-dependency.\n                          Repeatable.\n  --max <n>               Show at most n findings (0 = no limit)\n  --max-warnings <n>      Fail when warnings exceed n (default: no limit)\n  --strict                Raise every warning to an error. An explicit --rule\n                          still wins, so --strict --rule x=warn exempts x.\n  --color / --no-color    Force colour on or off\n  --ascii                 Use ASCII glyphs only\n  --verbose               Include parse problems, per-file detail, and every\n                          reference --ignore-ref or --ignore-family silenced\n  -h, --help              Show this help\n  -v, --version           Show the version\n\nSELECTORS\n  A selector is a path through the graph.\n\n    item[openness=open] -delegates-to-> document[phase=retired]\n    document[phase=active] -assumes-> document[phase=retired]\n    document =supersedes=> document\n    *[path^=docs/adr] -contains-> item[state=accepted-debt]\n\n  Node types:  document, item, * (any)\n  Attributes:  id, kind, title, path, file, line, phase, status, receptivity,\n               alias, document, state (or disposition), openness, section,\n               text, body, evidence, conflicted, fm.<front-matter-key>\n  Operators:   = != ^= $= *= ~=   and [attr] for \"is present\"\n               ~= is a regular expression, matched by an automaton that cannot\n               backtrack: linear in the subject, whatever the pattern. It reads\n               the usual syntax minus backreferences and lookaround, which are\n               not regular - both are refused when the selector is read, with\n               the character pointed at\n  Relations:   -kind->  <-kind-   =kind=>  <=kind=   (= forms are transitive)\n\nEXIT CODES\n  0  clean\n  1  findings at error severity (or over --max-warnings)\n  2  the tool could not run\n\nCONFIGURATION\n  Anything repeated on every run belongs in the repository rather than in the\n  command. spec-graph reads the first of these that exists:\n\n    .spec-graph.json, spec-graph.config.json, or a \"spec-graph\" key in\n    package.json\n\n    { \"patterns\": [\"docs/**/*.md\"],\n      \"ignoreReferences\": [\"trap *\"],\n      \"ignoreFamilies\": [\"RFC\"],\n      \"historyPatterns\": [\"**/JOURNAL_*.md\", \"archive/**\"],\n      \"baseline\": \".spec-graph-baseline.json\",\n      \"severities\": { \"self-reference\": \"off\" },\n      \"strict\": true }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it.\n\n  A problem in that file stops the run with exit 2, named on stderr: invalid\n  JSON, an unknown key, a rule that does not compile. A configuration that did\n  not load checks a different repository than the one configured, and would\n  report that one as consistent. --no-config runs on defaults instead.\n\nPROJECT RULES\n  A convention spec-graph never anticipated is a selector plus a sentence, and\n  belongs in the same file. Every rule declared here runs beside the built-ins\n  and is reported, baselined, escalated by --strict and silenced by --rule in\n  exactly the same way.\n\n    { \"rules\": {\n        \"no-draft-dependency\": {\n          \"query\": \"document[phase=active] -depends-on-> document[phase=draft]\",\n          \"message\": \"{0} depends on {1}, which is still a draft\",\n          \"hint\": \"wait for {1} to be accepted, or drop it from {0.path}\",\n          \"severity\": \"error\" } } }\n\n  query     One selector, or a list of them read as a union.\n  message   The headline. {0} is the first node on the path, {1} the next;\n            {1.phase} and {0.fm.owner} read any selector attribute.\n  hint      The next action. Optional, and templated the same way.\n  severity  error, warn, info or off. Defaults to warn - a rule a team has\n            just written has not yet earned the right to fail their build.\n\n  The id is the name with project: in front, which is why it can never collide\n  with a built-in. A selector that does not parse, or a {2} the query can never\n  reach, is reported when the file is read rather than found missing later.\n\n  To see what one matches without copying its selector out of the file:\n\n    spec-graph query project:no-draft-dependency --verbose\n\nADOPTING THIS ON AN OLD REPOSITORY\n  Record what is already wrong, then report only what happens next:\n\n    spec-graph check --record-baseline .spec-graph-baseline.json\n    git add .spec-graph-baseline.json\n\n  The file is keyed by specification and citation, not by line number, so it\n  survives edits, moves and renames. Findings that stop occurring are reported\n  so the file can be tightened; nothing new gets in.\n\nEXAMPLES\n  spec-graph \"docs/**/*.md\"\n  spec-graph check --rule self-reference=off --format json\n  spec-graph query 'item[openness=open] -delegates-to-> document[phase=retired]'\n  spec-graph check --ignore-ref \"trap *\"    # [[trap 55]] tags a concept, not a file\n  spec-graph graph --documents-only --graph-format mermaid > graph.mmd\n  spec-graph check --history \"**/JOURNAL_*.md\"   # a log is not a specification\n  spec-graph check --baseline .spec-graph-baseline.json\n  spec-graph rules --explain                # including this repository's own\n  spec-graph rules ghost-handover --explain      # and why it exists\n  spec-graph check --rule project:no-draft-dependency=off\n  spec-graph query project:no-draft-dependency   # what does that rule match?\n  spec-graph check --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n  spec-graph check --format gitlab > gl-code-quality-report.json\n  spec-graph diff base.json head.json --format markdown >> \"$GITHUB_STEP_SUMMARY\"\n";
 /** Parses argv into options. Throws {@link UsageError} on anything malformed. */
 export declare function parseArgs(argv: readonly string[], cwd: string): CliOptions;
 /** Runs the CLI and returns the process exit code. Never throws. */

package/dist/cli.js

@@ -14,7 +14,7 @@ import { discoverConfig, loadConfig } from './config.js';
 import { DiffInputError, diffExports, formatDiffJson, formatDiffMarkdown, formatDiffText, parseGraphExport, } from './diff.js';
 import { isGlob, underRoot } from './glob.js';
 import { analyse, DEFAULT_PATTERNS, withDiagnostics } from './runner.js';
-import { formatGraph, formatJson, formatMarkdown, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
+import { formatGitlab, formatGraph, formatJson, formatMarkdown, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
 import { DEFAULT_SEVERITIES, resolveStrict, RULE_DECISIONS, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES, } from './rules.js';
 import { isAbsolutePath, toPosix } from './paths.js';
 import { formatRef } from './source.js';
@@ -81,11 +81,13 @@ OPTIONS
   --ratchet               Also fail when a baseline entry no longer occurs, so
                           a paid-off exemption cannot outlive the defect.
   --no-config             Ignore .spec-graph.json and the package.json key.
-  --format <fmt>          human, json, sarif or markdown. sarif is the
+  --format <fmt>          human, json, sarif, gitlab or markdown. sarif is the
                           interchange format GitHub code scanning and editors
-                          already read, for check; markdown is a table for a
-                          pull-request comment or $GITHUB_STEP_SUMMARY, for check
-                          or diff (default: human)
+                          already read, and gitlab the Code Quality report a
+                          GitLab merge request reads, both for check; markdown
+                          is a table for a pull-request comment or
+                          $GITHUB_STEP_SUMMARY, for check or diff
+                          (default: human)
   --graph-format <fmt>    dot, mermaid or json (default: dot)
   --documents-only        Leave items out of the exported graph
   --rule <id>=<severity>  Override one rule: error, warn, info or off. A project
@@ -201,6 +203,7 @@ EXAMPLES
   spec-graph check --rule project:no-draft-dependency=off
   spec-graph query project:no-draft-dependency   # what does that rule match?
   spec-graph check --format markdown >> "$GITHUB_STEP_SUMMARY"
+  spec-graph check --format gitlab > gl-code-quality-report.json
   spec-graph diff base.json head.json --format markdown >> "$GITHUB_STEP_SUMMARY"
 `;
 const SEVERITIES = ['error', 'warn', 'info', 'off'];
@@ -330,8 +333,8 @@ export function parseArgs(argv, cwd) {
                 break;
             case '--format': {
                 const value = next(arg, i);
-                if (value !== 'human' && value !== 'json' && value !== 'sarif' && value !== 'markdown') {
-                    throw new UsageError(`--format must be human, json, sarif or markdown, got "${value}"`);
+                if (value !== 'human' && value !== 'json' && value !== 'sarif' && value !== 'markdown' && value !== 'gitlab') {
+                    throw new UsageError(`--format must be human, json, sarif, markdown or gitlab, got "${value}"`);
                 }
                 format = value;
                 i += 1;
@@ -381,12 +384,13 @@ export function parseArgs(argv, cwd) {
                 throw new UsageError(`unknown option "${arg}"\n  run "spec-graph --help" to see the available options`);
         }
     }
-    // SARIF is a report about findings, and only `check` produces those. Falling
-    // back to JSON would hand a pipeline something its uploader rejects with a
-    // message about a schema rather than about the command that was run. Markdown
-    // is for a pull request, which reads a check or a diff.
-    if (format === 'sarif' && command !== 'check' && !help && !version) {
-        throw new UsageError(`--format sarif reports findings, so it belongs to check, not to ${command}`);
+    // SARIF and GitLab's Code Quality are reports about findings, and only
+    // `check` produces those. Falling back to JSON would hand a pipeline something
+    // its uploader rejects with a message about a schema rather than about the
+    // command that was run. Markdown is for a pull request, which reads a check
+    // or a diff.
+    if ((format === 'sarif' || format === 'gitlab') && command !== 'check' && !help && !version) {
+        throw new UsageError(`--format ${format} reports findings, so it belongs to check, not to ${command}`);
     }
     if (format === 'markdown' && command !== 'check' && command !== 'diff' && !help && !version) {
         throw new UsageError(`--format markdown is a report for a pull request, so it belongs to check or diff, not to ${command}`);
@@ -702,11 +706,13 @@ export async function main(io = {}) {
             const reporterOptions = { verbose: options.verbose, max: options.max, escalated, ...baselineNote };
             out(options.format === 'sarif'
                 ? formatSarif(reported, reported.graph, { version: await readVersion(), escalated, projectRules })
-                : options.format === 'json'
-                    ? formatJson(reported, { escalated, ...baselineNote })
-                    : options.format === 'markdown'
-                        ? formatMarkdown(reported, reporterOptions)
-                        : `${formatReport(reported, { color, ascii, ...reporterOptions })}\n`);
+                : options.format === 'gitlab'
+                    ? formatGitlab(reported, { escalated })
+                    : options.format === 'json'
+                        ? formatJson(reported, { escalated, ...baselineNote })
+                        : options.format === 'markdown'
+                            ? formatMarkdown(reported, reporterOptions)
+                            : `${formatReport(reported, { color, ascii, ...reporterOptions })}\n`);
             if (!reported.ok || looseBaseline)
                 return EXIT_FAILED;
             if (options.maxWarnings >= 0 && reported.summary.warnings > options.maxWarnings)
@@ -738,7 +744,20 @@ function below(root, from) {
 function anchor(prefix, value) {
     if (prefix === '' || isAbsolutePath(value))
         return value;
-    return value.startsWith('!') ? `!${prefix}/${value.slice(1)}` : `${prefix}/${value}`;
+    const negated = value.startsWith('!');
+    const directories = prefix.split('/');
+    let rest = toPosix(negated ? value.slice(1) : value);
+    // `../docs` typed one directory down is the root's `docs`. That is arithmetic
+    // on two relative paths, and this is the one place both are known; left in
+    // the pattern, it reads as a glob climbing out of the root, which is refused.
+    // A bare `..` typed in `docs/deep` leaves `docs/`: the directory's contents,
+    // which is what it named.
+    while (directories.length > 0 && (rest === '..' || rest.startsWith('../'))) {
+        directories.pop();
+        rest = rest.slice(3);
+    }
+    const joined = [...directories, rest].join('/');
+    return negated ? `!${joined}` : joined;
 }
 /** The same, for an ignore, where a bare name is a directory at any depth. */
 function anchorPath(prefix, pattern) {