@descent-vtt/spec-graph 0.9.10 → 0.11.0

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' | 'gitlab';
+    readonly format: 'human' | 'json' | 'sarif' | 'markdown' | 'gitlab' | 'github';
     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, 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      \"maxRelated\": 3 }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it. maxRelated has no flag: it caps how many related locations one\n  finding lists, 8 unless set, and 0 lists none.\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";
+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, github, gitlab or markdown. sarif\n                          is the interchange format GitHub code scanning and\n                          editors already read, github the workflow commands a\n                          GitHub Actions log turns into annotations, and gitlab\n                          the Code Quality report a GitLab merge request reads,\n                          all three for check; markdown is a table for a\n                          pull-request comment or $GITHUB_STEP_SUMMARY, for\n                          check 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      \"maxRelated\": 3 }\n\n  A flag always wins over the file, and list flags add to it rather than\n  replacing it. maxRelated has no flag: it caps how many related locations one\n  finding lists, 8 unless set, and 0 lists none.\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 github             # annotations from an Actions log\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

@@ -12,14 +12,15 @@
 import { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline, } from './baseline.js';
 import { discoverConfig, loadConfig } from './config.js';
 import { DiffInputError, diffExports, formatDiffJson, formatDiffMarkdown, formatDiffText, parseGraphExport, } from './diff.js';
-import { isGlob, underRoot } from './glob.js';
+import { isGlob, rebasePattern, underRoot } from './glob.js';
 import { analyse, DEFAULT_PATTERNS, withDiagnostics } from './runner.js';
-import { formatGitlab, formatGraph, formatJson, formatMarkdown, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
+import { formatGithub, formatGitlab, formatGraph, formatJson, formatMarkdown, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
 import { DEFAULT_SEVERITIES, resolveStrict, RULE_DECISIONS, decisionUrl, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES, } from './rules.js';
-import { isAbsolutePath, toPosix } from './paths.js';
+import { isAbsolutePath, joinPosix, toPosix } from './paths.js';
 import { formatRef } from './source.js';
 import { execute, parseQuery, QueryError, renderMatch } from './select.js';
 import { isProjectRule } from './types.js';
+import { displayWidth } from './vendor/spec-core/text/index.js';
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_ERROR = 2;
@@ -81,13 +82,14 @@ 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, gitlab or markdown. sarif is the
-                          interchange format GitHub code scanning and editors
-                          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)
+  --format <fmt>          human, json, sarif, github, gitlab or markdown. sarif
+                          is the interchange format GitHub code scanning and
+                          editors already read, github the workflow commands a
+                          GitHub Actions log turns into annotations, and gitlab
+                          the Code Quality report a GitLab merge request reads,
+                          all three 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
@@ -205,6 +207,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 github             # annotations from an Actions log
   spec-graph check --format gitlab > gl-code-quality-report.json
   spec-graph diff base.json head.json --format markdown >> "$GITHUB_STEP_SUMMARY"
 `;
@@ -333,8 +336,13 @@ export function parseArgs(argv, cwd) {
                 break;
             case '--format': {
                 const value = next(arg, i);
-                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}"`);
+                if (value !== 'human' &&
+                    value !== 'json' &&
+                    value !== 'sarif' &&
+                    value !== 'markdown' &&
+                    value !== 'gitlab' &&
+                    value !== 'github') {
+                    throw new UsageError(`--format must be human, json, sarif, markdown, gitlab or github, got "${value}"`);
                 }
                 format = value;
                 i += 1;
@@ -384,12 +392,12 @@ export function parseArgs(argv, cwd) {
                 throw new UsageError(`unknown option "${arg}"\n  run "spec-graph --help" to see the available options`);
         }
     }
-    // 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) {
+    // SARIF, GitHub's workflow commands 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' || format === 'github') && 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) {
@@ -554,41 +562,53 @@ export async function main(io = {}) {
         out(renderRules(options.verbose, await readVersion(), projectRules, wanted ?? null, loaded.source));
         return EXIT_OK;
     }
-    const patterns = options.patterns.length > 0 ? options.patterns.map((pattern) => anchor(here, pattern)) : (file.patterns ?? DEFAULT_PATTERNS);
+    // Named the way the reader would have to type it, because a discovered
+    // configuration is often not the one in front of them.
+    //
+    // On stderr, with everything else this run says about itself. stdout is the
+    // report, and in three of the four formats it is a document: a line above it
+    // made `--verbose --format json` unparseable and handed `--format sarif` to a
+    // code-scanning uploader that rejects it over a schema.
+    if (options.verbose && loaded.source !== null)
+        err(`configuration: ${fromHere(here, loaded.source)}\n`);
+    // A bare `--ignore` name prunes a directory of that name at any depth, the
+    // way a .gitignore line does, so it means the same thing wherever it was
+    // typed. Every other pattern is matched against the repository-relative
+    // path, a bare `--history` name included, and leaving one alone would make
+    // it silently match something else or nothing. A pattern that cannot be
+    // rebased onto the root stops the run as one the dialect refuses does,
+    // named as it was typed.
+    let typed;
+    try {
+        typed = {
+            patterns: options.patterns.map((pattern) => anchor(here, pattern)),
+            ignore: options.ignore.map((pattern) => anchorPath(here, pattern)),
+            history: options.historyPatterns.map((pattern) => anchor(here, pattern)),
+        };
+    }
+    catch (error) {
+        err(`spec-graph: ${error.message}\n`);
+        return EXIT_ERROR;
+    }
+    const patterns = typed.patterns.length > 0 ? typed.patterns : (file.patterns ?? DEFAULT_PATTERNS);
     const severityOverrides = { ...(file.severities ?? {}), ...options.severities };
     const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false), projectRules);
     const analyseOptions = {
         root,
         patterns,
-        // A bare name prunes a directory of that name at any depth, the way a
-        // .gitignore line does, so it means the same thing wherever it was typed.
-        // A path or a glob is matched against the repository-relative path, and
-        // leaving that one alone would make it silently match nothing.
-        //
         // A stray entry in one of the empty fallbacks below changes a run only if
         // it matches a path, a target or a family some corpus has, so the mutants
         // that plant one survive every corpus but one built for them - except in
         // `families`, where any entry is an allowlist.
-        ignore: [...(file.ignore ?? []), ...options.ignore.map((pattern) => anchorPath(here, pattern))],
+        ignore: [...(file.ignore ?? []), ...typed.ignore],
         ignoreReferences: [...(file.ignoreReferences ?? []), ...options.ignoreReferences],
         families: [...(file.families ?? []), ...options.families],
         ignoreFamilies: [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies],
-        historyPatterns: [...(file.historyPatterns ?? []), ...options.historyPatterns.map((pattern) => anchorPath(here, pattern))],
+        historyPatterns: [...(file.historyPatterns ?? []), ...typed.history],
         severities,
         projectRules,
         maxRelated: file.maxRelated,
     };
-    // Named the way the reader would have to type it, because a discovered
-    // configuration is often not the one in front of them.
-    //
-    // On stderr, with everything else this run says about itself. stdout is the
-    // report, and in three of the four formats it is a document: a line above it
-    // made `--verbose --format json` unparseable and handed `--format sarif` to a
-    // code-scanning uploader that rejects it over a schema.
-    if (options.verbose && loaded.source !== null) {
-        const depth = here === '' ? 0 : here.split('/').length;
-        err(`configuration: ${'../'.repeat(depth)}${loaded.source}\n`);
-    }
     let result;
     try {
         result = await analyse(analyseOptions);
@@ -658,7 +678,7 @@ export async function main(io = {}) {
                     const { writeFile } = await import('node:fs/promises');
                     // Node writes a string as UTF-8 when the encoding is empty too, so
                     // emptying this literal writes the same bytes.
-                    await writeFile(underRoot(root, anchor(here, options.recordBaseline)), text, 'utf8');
+                    await writeFile(underRoot(root, anchorFile(here, options.recordBaseline)), text, 'utf8');
                 }
                 catch (error) {
                     err(`spec-graph: cannot write ${options.recordBaseline}: ${error.message}\n`);
@@ -668,10 +688,11 @@ export async function main(io = {}) {
                 out(`recorded ${count(result.diagnostics.length, 'finding')} as ${count(entries, 'entry', 'entries')} in ${options.recordBaseline}\n`);
                 return EXIT_OK;
             }
-            const source = options.baseline === null ? (file.baseline ?? null) : anchor(here, options.baseline);
+            const source = options.baseline === null ? (file.baseline ?? null) : anchorFile(here, options.baseline);
             const ratchet = options.ratchet || file.ratchet === true;
             let reported = result;
             let note;
+            let recordAs;
             if (source !== null) {
                 const held = await readBaseline(underRoot(root, source), source);
                 // A path typed on the command line says the file is there for this run.
@@ -701,6 +722,10 @@ export async function main(io = {}) {
                     ratchet,
                     entries: outcome.stale,
                 };
+                // The command that re-records it is typed where this run was: a path
+                // typed on this command line is relative to there already, and the
+                // configuration's is from the root.
+                recordAs = options.baseline ?? fromHere(here, source);
                 // Listed rather than counted when the run turns on them: a number is
                 // enough to know the file has slack, and not enough to strike it. On
                 // stdout only for a human - the structured formats carry the same rows
@@ -715,16 +740,18 @@ export async function main(io = {}) {
                 }
             }
             const looseBaseline = note !== undefined && note.ratchet && note.stale > 0;
-            const reporterOptions = { verbose: options.verbose, max: options.max, escalated, baseline: note };
+            const reporterOptions = { verbose: options.verbose, max: options.max, escalated, baseline: note, recordAs };
             out(options.format === 'sarif'
                 ? formatSarif(reported, reported.graph, { version: await readVersion(), escalated, projectRules })
                 : options.format === 'gitlab'
                     ? formatGitlab(reported, { escalated })
-                    : options.format === 'json'
-                        ? formatJson(reported, { escalated, baseline: note })
-                        : options.format === 'markdown'
-                            ? formatMarkdown(reported, reporterOptions)
-                            : `${formatReport(reported, { color, ascii, ...reporterOptions })}\n`);
+                    : options.format === 'github'
+                        ? formatGithub(reported, { escalated })
+                        : options.format === 'json'
+                            ? formatJson(reported, { escalated, baseline: note })
+                            : 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)
@@ -751,33 +778,46 @@ function below(root, from) {
     return start.startsWith(`${root}/`) ? start.slice(root.length + 1) : '';
 }
 /**
- * Re-anchors a path typed in `prefix` so it reads from the root.
+ * A path from the root, as it is typed in `here`: one `../` for each directory
+ * `here` is below the root. An absolute path reads the same from anywhere.
+ */
+function fromHere(here, path) {
+    return here === '' || isAbsolutePath(path) ? path : `${'../'.repeat(here.split('/').length)}${path}`;
+}
+/**
+ * Re-anchors a pattern typed in `prefix` so it reads from the root, brace
+ * alternative by brace alternative, or throws naming it as typed.
+ *
+ * `../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.
  *
  * An absolute path is left alone: it was not relative to anywhere, so moving
- * the root cannot change what it means.
+ * the root cannot change what it means. spec-core roots a leading `/` and
+ * knows no drive letter, so `C:/docs` is told apart here.
  */
-function anchor(prefix, value) {
-    if (prefix === '' || isAbsolutePath(value))
-        return 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;
+function anchor(prefix, pattern) {
+    return isAbsolutePath(pattern) ? pattern : rebasePattern(pattern, prefix);
 }
-/** The same, for an ignore, where a bare name is a directory at any depth. */
+/**
+ * The same, for an `--ignore`, where a bare name is a directory at any depth.
+ * Only the walk reads a name that way; a `--history` pattern is matched as a
+ * whole path, and goes to {@link anchor}.
+ */
 function anchorPath(prefix, pattern) {
     return isGlob(pattern) || pattern.includes('/') ? anchor(prefix, pattern) : pattern;
 }
+/**
+ * Re-anchors a file typed in `prefix`, a baseline, so it reads from the root.
+ *
+ * A file name is not a pattern: a brace or a `!` in it is a character, which
+ * {@link anchor} would read as syntax, and a baseline outside the repository
+ * is as good as one inside, so a `..` past the root is a path like any other.
+ * At the root the file is named as it was typed.
+ */
+function anchorFile(prefix, file) {
+    return prefix === '' || isAbsolutePath(file) ? file : joinPosix(prefix, toPosix(file));
+}
 function knownProjectRules(projectRules) {
     const known = projectRules.map((rule) => rule.id);
     return known.length > 0 ? `project rules here: ${known.join(', ')}` : 'this repository defines no project rules';
@@ -884,9 +924,14 @@ function nodeSummary(node) {
         ...(node.kind === 'document' ? { phase: node.phase } : { state: node.disposition, openness: node.openness }),
     };
 }
-/** Points at the exact character of a selector that failed to parse. */
+/**
+ * Points at the exact character of a selector that failed to parse, in the
+ * columns a terminal draws: a Han character before it takes two, so an offset
+ * counted in UTF-16 units put the caret short of it. The offset is a position
+ * the parser reached, never negative, so it needs no floor.
+ */
 function renderQueryError(selector, error) {
-    const caret = `${' '.repeat(Math.max(0, error.offset))}^`;
+    const caret = `${' '.repeat(displayWidth(selector.slice(0, error.offset)))}^`;
     return `spec-graph: ${error.message}\n  ${selector}\n  ${caret}\n`;
 }
 /**