@descent-vtt/spec-graph 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -11,6 +11,74 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 0.20.0
+
+A negation an aside sets apart from its phrase cancels it, and a
+pointer such as `see` governs the reference after it, so neither is
+read as the relation it denies or passes over. On Linux a `\` in an
+export path `diff` is given is a separator, and a run does not start in
+a directory whose name holds one. A relative `cwd` given to the library
+is read once.
+
+### Changed
+
+- **A negation an aside sets apart from the phrase cancels it.**
+  `Not, as it happens, blocked by [ADR-0002](0002.md)` and
+  `Never, ever, blocked by` were `blocked-by`, the relation each denies:
+  the comma after the negation ended its clause. An aside closed by a comma
+  of its own leaves the clause open now, and each is a citation, and no
+  phrase before such a negation governs the reference either, so
+  `Not, as decided in [ADR-0003](0003.md), blocked by [ADR-0002](0002.md)`
+  reads no premise from the second. The miss it trades is a negation that
+  ends a clause of its own before an aside, `If not, then, blocked by`,
+  which is a citation too
+  ([ADR-0006](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0006-false-positives-cost-more.md)).
+  A `ghost-handover`, `stale-premise` or `live-supersession` such a
+  sentence denies is no longer reported, and an open question it hands to
+  a live document is an `orphaned-obligation`, so a check can pass that
+  failed, and fail that passed. Upgrading: run `check`; where a hand-off
+  is written `Owner: nobody, for now, deferred to`, write it without the
+  aside.
+- **A pointer governs the reference after it.**
+  `Per tick, see [ADR-0002](0002.md)` read the cited document as a
+  premise, and `Blocked by the cache, see [ADR-0002](0002.md)` as what
+  blocks: `see` between a phrase
+  and the reference was passed over. It governs the reference as a
+  citation now, as it does with no phrase before it; `the must-see list`
+  and `seen in` point at nothing
+  ([ADR-0006](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0006-false-positives-cost-more.md)).
+  A finding read from such a phrase is no longer reported. Upgrading: run
+  `check`; where the phrase does name the reference, name it before the
+  pointer, `Blocked by [ADR-0002](0002.md), see its table`.
+- **A `\` in an export path is a separator.** `diff` read its two paths as
+  typed, so on Linux `diff 'sub\base.json' 'sub\head.json'` compared files
+  of those names, or found none, and `..\sub\base.json` typed one directory
+  down found none, where a baseline typed either way is `sub/base.json`.
+  Each path is read as a root and a baseline are now, from where it was
+  typed. Windows reads as before
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+  Upgrading: on Linux, rename an export whose file name holds a `\`; a
+  diff that read it reads the path the `\` spells now.
+- **A run does not start in a directory whose name holds a `\`.** Where the
+  host separates names with `/`, as Linux does, `check`, `query`, `graph`
+  and `rules` in `/work/a\b` read `/work/a/b`, the path the `\` spells: its
+  documents, its configuration and its rules, so a check could pass over
+  the tree it was typed in, and a `--record-baseline` was written there.
+  Each stops now with exit `2` and one line, before it reads or writes
+  anything; `diff`, `--help` and `--version` run there as before
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+  Upgrading: run from a path whose names hold no `\`, or give `--root` one,
+  such as a link to the directory.
+- **A relative `cwd` is read once.** The library's `main({ cwd: 'docs' })`
+  with no `--root` started the run in `docs/docs`, the directory joined to
+  itself: it checked `docs/docs/*.md` for `*.md` and recorded a baseline
+  there. It starts in `docs` now, and two values of a baseline are
+  compared from there. The `spec-graph` command gives an absolute
+  directory and is as it was
+  ([ADR-0010](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0010-configuration-belongs-to-the-repository.md)).
+  Upgrading: nothing to do; a caller that gave a relative `cwd` gets the
+  directory it named.
+
 ## 0.19.0
 
 A comma ends the clause a negation before a phrase is in, so

package/README.md

@@ -475,7 +475,15 @@ it, in the same statement: a sentence, a paragraph, a list item or a table cell.
   `Not in this release: deferred to` each state the relation, and are read as
   they state it. So do `if not, blocked by` and `both or neither, because`: a
   comma ends the clause the negation is in, and counts toward no phrase's 40
-  characters.
+  characters. An aside closed by a comma of its own leaves the clause open,
+  so `not, as it happens, blocked by` and `never, ever, blocked by` are
+  citations, and so is `if not, then, blocked by`, which is missed. No
+  phrase before such a negation governs the reference either:
+  `not, as decided in [ADR-0003](0003.md), blocked by [ADR-0002](0002.md)`
+  reads the first as a premise and the second as a citation.
+- A pointer between the two, `see`, governs the reference as a citation:
+  `per tick, see [ADR-0002](0002.md)` and `blocked by the cache, see` read no
+  relation, and `the must-see list` and `seen in` point at nothing.
 - A sentence written in Chinese ends at `。`, `？`, `！` or `；`, with a space
   after it or none, so `Deferred to later。另見 ADR-0002` hands nothing to
   ADR-0002. A stop only ends a statement sooner: it reads less, never more.
@@ -894,9 +902,17 @@ reports, byte for byte, because every path here is relative to the root.
 - A path typed on the command line stays relative to where you typed it, brace
   alternative by brace alternative: `{/docs,x}` typed in `sub` is `/docs` or
   `sub/x`.
-- A `\` in a root or a baseline is a separator on every host, as in a pattern,
-  so `--baseline sub\held.json` typed at the root and `..\sub\held.json`
-  typed in `docs` are one file, `sub/held.json`, on Linux as on Windows.
+- A `\` in a root, a baseline or an export `diff` reads is a separator on
+  every host, as in a pattern, so `--baseline sub\held.json` typed at the
+  root and `..\sub\held.json` typed in `docs` are one file, `sub/held.json`,
+  on Linux as on Windows.
+- So a run does not start in a directory whose name holds a `\`, where the
+  host separates names with `/`, as Linux does: read as a separator, the
+  `\` would name another directory, and the run would check it and record a
+  baseline into it. The run stops with
+  exit `2` and one line before it reads anything; run it from a path whose
+  names hold none, or give `--root` one, such as a link to the directory.
+  `diff`, `--help` and `--version` run there.
 
 See [ADR-0018](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0018-the-configuration-file-is-the-root.md).
 
@@ -1339,7 +1355,7 @@ steps:
   - run: npm ci
   - run: npx --no-install @descent-vtt/spec-graph --format sarif > spec-graph.sarif
     continue-on-error: true
-  - uses: github/codeql-action/upload-sarif@24c54180a607b1449ed407dd24f251e4e9147c8d # v4.38.3
+  - uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
     with:
       sarif_file: spec-graph.sarif
 ```
@@ -1483,6 +1499,9 @@ It names only what it can tell apart:
   resolved or reopened.
 - Findings are left to `--baseline`, which already reports what is new.
 
+Each export is read from where its path was typed, with a `\` a separator,
+as a baseline is.
+
 The exit code is `0` whether anything changed or not: a diff describes, and
 `check` gates. See
 [ADR-0020](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0020-a-diff-names-what-it-can-tell-apart.md).
@@ -1524,7 +1543,8 @@ The command line is `main`, which takes the line and the directory it was
 typed in: `await main({ argv: ['check', '--root', 'docs'], cwd })` reads
 `docs`, its configuration and any baseline beside it from `cwd`, and walks
 up from `cwd` for a configuration where no `--root` is given. Left out,
-`cwd` is the process's working directory, as for the `spec-graph` command.
+`cwd` is the process's working directory, as for the `spec-graph` command;
+a relative `cwd` is read from that directory.
 
 ## Design
 
@@ -1563,9 +1583,9 @@ 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.** 2,354 tests; 99.4% statement and 99.8% line
+**Verified, not just covered.** 2,381 tests; 99.4% statement and 99.8% line
 coverage. Coverage says a line ran, so the suite is also held to a mutation
-score - 96.58% over 9,126 mutants, measured by CI's full sweep, and a build
+score - 96.59% over 9,149 mutants, measured by CI's full sweep, and a build
 fails under 93 - because a vocabulary entry or a boundary
 condition can be weakened by an ordinary-looking refactor without a single test
 going red. [ADR-0007](https://github.com/DescentVTT/spec-graph/blob/main/docs/adr/0007-mutation-testing.md) is straight about what

package/dist/cli.js

@@ -10,7 +10,7 @@
  * itself could not run. A usage mistake never masquerades as a passing build,
  * and an error nothing here expected never as findings.
  */
-import { resolve } from 'node:path';
+import { resolve, sep } from 'node:path';
 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';
@@ -19,7 +19,7 @@ import { isFamilyName } from './identity.js';
 import { analyse, DEFAULT_PATTERNS, withDiagnostics } from './runner.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 { foldDriveLetter, isAbsolutePath, joinPosix, toPosix } from './paths.js';
+import { foldDriveLetter, holdsBackslashInName, isAbsolutePath, joinPosix, toPosix } from './paths.js';
 import { formatRef } from './source.js';
 import { execute, parseQuery, QueryError, renderMatch } from './select.js';
 import { isProjectRule } from './types.js';
@@ -500,6 +500,11 @@ export function parseArgs(argv, cwd) {
     const once = (flag, typed, read, key = flag, takes = 'takes one value') => {
         valued.push({ flag, key, typed, read, takes });
     };
+    // A baseline typed here is read from the root where `--root` names one,
+    // and from where it was typed otherwise, which is the root's default. That
+    // directory is read once: joined to itself, a relative `cwd` such as
+    // `docs` read `docs/docs` (ADR-0010, 2026-10-24).
+    const fromRoot = (value) => foldDriveLetter(resolve(cwd, rootExplicit ? toPosix(root) : '', toPosix(value)));
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (arg === '--') {
@@ -582,18 +587,16 @@ export function parseArgs(argv, cwd) {
                 historyPatterns.push(next(arg, i));
                 i += 1;
                 break;
-            // A baseline typed here is read from the root where `--root` names one,
-            // and from where it was typed otherwise, which is the root's default.
             case '--baseline': {
                 const value = filled(arg, i, 'a file');
-                once(arg, value, () => foldDriveLetter(resolve(cwd, toPosix(root), toPosix(value))));
+                once(arg, value, () => fromRoot(value));
                 baseline = value;
                 i += 1;
                 break;
             }
             case '--record-baseline': {
                 const value = filled(arg, i, 'a file');
-                once(arg, value, () => foldDriveLetter(resolve(cwd, toPosix(root), toPosix(value))));
+                once(arg, value, () => fromRoot(value));
                 recordBaseline = value;
                 i += 1;
                 break;
@@ -906,8 +909,24 @@ async function run(io, err) {
     // the library names with `io.cwd`, and where two values of `--root` were
     // compared: left relative, the disk read it from Node's own directory, so
     // `--root docs` checked, and recorded a baseline into, another tree than
-    // the caller's. A `\` is a separator, as the walk has always read it.
-    const start = resolve(cwd, toPosix(options.root));
+    // the caller's. A `\` typed in the root is a separator, as the walk has
+    // always read it. The directory the line was typed in is not typed, and is
+    // read once, as the host gives it: joined to itself, a relative `cwd` such
+    // as `docs` started the run in `docs/docs`.
+    const start = options.rootExplicit ? resolve(cwd, toPosix(options.root)) : resolve(cwd);
+    // On a host whose separator is `/`, a `\` in where the run starts is a
+    // character of a name, from the directory the line was typed in, and the
+    // walk, the configuration and a baseline read every `\` as a separator: in
+    // `/t/a\b` they read `/t/a/b`, another directory, and recorded a baseline
+    // into it. No path handed on tells the one `\` from the other, so the run
+    // stops before it reads or writes anything. A diff reads its two files
+    // where they are, from that directory as the host gives it, and is not
+    // stopped (ADR-0010, 2026-10-24).
+    if (holdsBackslashInName(start, sep)) {
+        const named = options.rootExplicit ? `--root "${options.root}" is ${start}, which has` : `${start} has`;
+        err(`spec-graph: ${named} a "\\" in a name, and spec-graph reads each "\\" as a separator, so it would read ${toPosix(start)} instead: run it from a path with none, or give --root one\n`);
+        return EXIT_ERROR;
+    }
     // A root that was named is a directory, for every command that reads one.
     // `rules --root` with a path that is not there listed the built-in rules and
     // exited 0, as if the repository declared none, and the others said only
@@ -1456,9 +1475,15 @@ async function runDiff(paths, cwd, format, out, err) {
     for (const path of paths) {
         let raw;
         try {
+            // A `\` is a separator, as it is in a root and a baseline: kept as a
+            // character, `sub\a.json` typed at the top read a file of that name on
+            // Linux, where the same baseline is `sub/a.json`, and `..\sub\a.json`
+            // typed below it read nothing. The directory it was typed in is read
+            // as the host gives it, so a diff reads its files there, `\` or none.
+            //
             // Without the encoding this is a Buffer, which JSON.parse decodes as
             // UTF-8 all the same - so emptying the literal parses the same export.
-            raw = await readFile(resolve(cwd, path), 'utf8');
+            raw = await readFile(resolve(cwd, toPosix(path)), 'utf8');
         }
         catch (error) {
             err(`spec-graph: cannot read ${path}: ${error.message}\n`);