@descent-vtt/spec-graph 0.11.1 → 0.12.1

package/CHANGELOG.md

@@ -11,6 +11,60 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 0.12.1
+
+The README's commands gave `npx` the command's bare name, which on npm is
+not this project's package. spec-graph itself is unchanged.
+
+### Security
+
+- Every command in the README gives `npx` the package's full name behind
+  `--no-install`, as in `npx --no-install @descent-vtt/spec-graph ...`.
+  `spec-graph` without the scope belongs to nobody on npm (2026-10-07), so
+  anyone can register it.
+  `npx` given a name the project has not installed fetches the package of
+  that name and runs it, unasked when no terminal is attached: a fresh
+  clone, a worktree before `npm ci`, a CI job with no install step.
+  The CI examples install first, and [Names](README.md#names) says whose the
+  names are; what was measured is in the family's
+  [adopting guide](https://github.com/DescentVTT/spec-core/blob/main/docs/adopting.md#names).
+  Upgrading: where a CI job or a script gives `npx` the command's name
+  alone, write `npx --no-install @descent-vtt/spec-graph`. `--no-install`
+  before the bare name is not enough: npm still runs a copy of that name's
+  package an earlier fetch left in its cache.
+
+## 0.12.0
+
+Names every JavaScript object answers to - `constructor`, `__proto__` - are
+read as the unknown names they are in seven places, three of which could
+leave a run that passed refusing or finding something now.
+
+### Changed
+
+- A node type named `constructor` is refused as any unknown type is: a
+  query or a project rule written with it matched nothing in silence, and is
+  now a usage error, exit 2. Upgrading: write `document`, `item` or `*`.
+- A table column headed `Constructor` declares no relation, where it made
+  the table a register and each cell an edge of no kind. Upgrading: a table
+  that was a register only by that column needs a `Status` column or a
+  relation the README lists.
+- A `@spec-edge` whose `kind` names no relation is a `references` edge, and
+  `--verbose` lists it as a parse problem; any other word drew an edge of a
+  kind no rule knows, and one to its own document ended the check with exit
+  2 (ADR-0014). Upgrading: write one of the eight relations.
+
+### Fixed
+
+- A front-matter key, a `state=` word or a directory named `constructor` or
+  `__proto__` no longer ends a query or a check on a TypeError: the key is
+  found where it was written, the state is ignored, and a document under
+  such a directory keeps its own id.
+
+### Documentation
+
+- The README's SARIF example pins the actions the workflows run now, and a
+  test holds it to them.
+
 ## 0.11.1
 
 Documentation and robustness: the README's SARIF example is pinned as CI
@@ -1378,7 +1432,7 @@ reference.
 `$GITHUB_STEP_SUMMARY` or a pull-request comment:
 
 ```yaml
-- run: npx spec-graph --format markdown >> "$GITHUB_STEP_SUMMARY"
+- run: npx --no-install @descent-vtt/spec-graph --format markdown >> "$GITHUB_STEP_SUMMARY"
 ```
 
 SARIF puts a finding on the line that caused it, which is where somebody fixing

package/README.md

@@ -53,22 +53,44 @@ document and obvious when you can query all of them at once.
 
 ```bash
 npm install --save-dev @descent-vtt/spec-graph
-npx spec-graph
+npx --no-install @descent-vtt/spec-graph
 ```
 
 No configuration, no annotations, no migration. It reads what your repository
 already looks like:
 
 ```bash
-npx spec-graph "docs/**/*.md"
+npx --no-install @descent-vtt/spec-graph "docs/**/*.md"
 ```
 
-**The package is scoped; the command is not.** After a local install the binary
-is plain `spec-graph`. Without one, `npx` needs the full name:
+## Names
 
-```bash
-npx @descent-vtt/spec-graph "docs/**/*.md"
-```
+The package is `@descent-vtt/spec-graph`, and the command it installs is
+`spec-graph`. The name without the scope is not this project: on npm,
+`spec-graph` belonged to nobody on 2026-10-07, and whoever registers it decides
+what it runs.
+
+`npx` fetches and runs the package of whatever name it is given when the
+project has none installed - a fresh clone, a worktree before `npm ci`, a CI job
+without the install step - and without a terminal it does not ask first. So
+give `npx` the full name:
+
+- `npx --no-install @descent-vtt/spec-graph` in a project that installed it: it
+  runs that install, the version the lockfile pins, and where there is none it
+  stops with an error that names this package.
+- `npx @descent-vtt/spec-graph`, without `--no-install`, where nothing is
+  installed: it fetches this package and runs it.
+
+<!-- bare-name: the two forms in the next sentence are shown as what not to write -->
+Never `npx spec-graph`, and not `npx --no-install spec-graph` either:
+`--no-install` stops a download, and npm still runs a copy of the bare name's
+package that an earlier fetch left in its cache. The family's
+[adopting guide](https://github.com/DescentVTT/spec-core/blob/main/docs/adopting.md#names)
+has what was measured, under npm 10, 11 and 12.
+
+Where this page writes the command alone, as in `spec-graph query ...`, it is
+what a `package.json` script holds - npm fetches nothing for a script - and what
+follows `npx --no-install @descent-vtt/` at a prompt.
 
 ## What it checks
 
@@ -552,6 +574,8 @@ Each takes these attributes. Any other is a parse problem, listed by
 
 - `reason`, `note`, `owner` and a node's `kind` are for whoever reads the
   source; spec-graph reads nothing from them.
+- An edge's `kind` is one of the relations a selector steps along. Any other
+  word is a parse problem too, and the edge is read as `references`.
 - `aliases` splits at commas, semicolons and spaces.
 - A value is quoted with either quote mark, or bare when it holds no space or
   quote, and an attribute with no value is a flag.
@@ -628,7 +652,7 @@ gate without writing any code:
 ```yaml
 - name: No PRD may depend on a draft decision
   run: |
-    ! npx spec-graph query 'document[path^=docs/prd] -depends-on-> document[phase=draft]'
+    ! npx --no-install @descent-vtt/spec-graph query 'document[path^=docs/prd] -depends-on-> document[phase=draft]'
 ```
 
 That shell line is a rule wearing a disguise. Give it a name and a sentence and
@@ -1031,7 +1055,7 @@ loop that would justify a resident process is one line of shell, and it belongs
 to whatever the developer already uses rather than to this tool:
 
 ```bash
-npx spec-graph --format json | jq -r '.summary'
+npx --no-install @descent-vtt/spec-graph --format json | jq -r '.summary'
 ```
 
 ## In CI
@@ -1039,6 +1063,11 @@ npx spec-graph --format json | jq -r '.summary'
 The exit code is the contract: `0` clean, `1` findings, `2` the tool could not
 run. That is all most pipelines need.
 
+Every job below installs the project first, with `npm ci`, and gives `npx` the
+package's [full name](#names) behind `--no-install`: a job that lost its install
+step then stops, where the command's name alone would fetch whatever package
+has that name.
+
 Beyond that, a format puts the findings where somebody will look:
 
 | Format | Where the findings land |
@@ -1061,16 +1090,16 @@ permissions:
   contents: read
   security-events: write
 steps:
-  - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+  - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
     with:
       persist-credentials: false
-  - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+  - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
     with:
       node-version: '24'
   - run: npm ci
-  - run: npx spec-graph --format sarif > spec-graph.sarif
+  - run: npx --no-install @descent-vtt/spec-graph --format sarif > spec-graph.sarif
     continue-on-error: true
-  - uses: github/codeql-action/upload-sarif@1c5b675653bb5c22dbe9b12b556ec555138e09fd # v4.38.1
+  - uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
     with:
       sarif_file: spec-graph.sarif
 ```
@@ -1091,7 +1120,7 @@ command per finding, and the job's log turns each into an annotation on the
 diff, with no upload step:
 
 ```yaml
-- run: npx spec-graph --format github
+- run: npx --no-install @descent-vtt/spec-graph --format github
 ```
 
 ```text
@@ -1115,7 +1144,8 @@ resolved:
 ```yaml
 spec-graph:
   script:
-    - npx spec-graph --format gitlab > gl-code-quality-report.json
+    - npm ci
+    - npx --no-install @descent-vtt/spec-graph --format gitlab > gl-code-quality-report.json
   artifacts:
     when: always
     reports:
@@ -1146,7 +1176,7 @@ actually look:
 ```yaml
 - name: Summarise the specification graph
   if: always()
-  run: npx spec-graph --format markdown >> "$GITHUB_STEP_SUMMARY"
+  run: npx --no-install @descent-vtt/spec-graph --format markdown >> "$GITHUB_STEP_SUMMARY"
 ```
 
 It leads with the verdict, counts the corpus, gives every finding its hint, and
@@ -1161,7 +1191,7 @@ per-file detail that SARIF and Code Quality have nowhere to put.
 
 ```yaml
 - name: Check the specification graph
-  run: npx spec-graph "docs/**/*.md" --format json > spec-graph.json
+  run: npx --no-install @descent-vtt/spec-graph "docs/**/*.md" --format json > spec-graph.json
 ```
 
 The JSON report is versioned, flat, and carries start and end positions for
@@ -1197,9 +1227,9 @@ binary, so CI makes one from the base branch and one from the pull request:
 
 ```yaml
 - run: git fetch --depth 1 origin "$GITHUB_BASE_REF" && git worktree add ../base FETCH_HEAD
-- run: npx spec-graph graph --root ../base --graph-format json > base.json
-- run: npx spec-graph graph --graph-format json > head.json
-- run: npx spec-graph diff base.json head.json --format markdown >> "$GITHUB_STEP_SUMMARY"
+- run: npx --no-install @descent-vtt/spec-graph graph --root ../base --graph-format json > base.json
+- run: npx --no-install @descent-vtt/spec-graph graph --graph-format json > head.json
+- run: npx --no-install @descent-vtt/spec-graph diff base.json head.json --format markdown >> "$GITHUB_STEP_SUMMARY"
 ```
 
 It names only what it can tell apart:
@@ -1287,9 +1317,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.** 1,886 tests; 99.4% statement and 99.8% line
+**Verified, not just covered.** 1,995 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.31% over 8,385 mutants, measured by CI's full sweep, and a build
+score - 96.38% over 8,539 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/extract.d.ts

@@ -16,7 +16,7 @@
  */
 import { type DocumentIdentity } from './identity.js';
 import { type ScannedDocument } from './markdown.js';
-import type { DocumentNode, EdgeKind, EdgeOrigin, ItemNode, MisreadKey, ParseProblem, SourceRef } from './types.js';
+import { type DocumentNode, type EdgeKind, type EdgeOrigin, type ItemNode, type MisreadKey, type ParseProblem, type SourceRef } from './types.js';
 import { type YamlEntry } from './yaml.js';
 /**
  * A relation that has been read but not yet resolved to a target node.

package/dist/extract.js

@@ -21,6 +21,7 @@ import { anchorsOf, isMarkdownLine, isOnlyComment, referenceLinks, scanMarkdown,
 import { findSpecificationRegions, isRegisterTable, opensHeading, regionAt, } from './sections.js';
 import { resolveItemState } from './state.js';
 import { refOf } from './source.js';
+import { EDGE_KINDS, } from './types.js';
 import { readEntries, toRecord, valuesOf } from './yaml.js';
 /* -------------------------------------------------------------------------- */
 /* Vocabulary                                                                 */
@@ -513,6 +514,13 @@ export function extractDocument(input) {
                 at: at(directive.start, directive.end),
             });
         }
+        const kind = directive.name === 'spec-edge' ? attr(directive, 'kind') : null;
+        if (kind !== null && !isEdgeKind(kind.value)) {
+            problems.push({
+                message: `unknown relation "${kind.value}" on @spec-edge, read as references - expected one of: ${EDGE_KINDS.join(', ')}`,
+                at: at(kind.start, kind.end),
+            });
+        }
     }
     const { entries, problems: unread } = readEntries(scanned);
     for (const problem of unread) {
@@ -981,6 +989,17 @@ function summarise(text) {
 function isClaimed(claimed, offset) {
     return claimed.some((range) => offset >= range.start && offset < range.end);
 }
+/**
+ * Whether a word a `@spec-edge` gives as its kind is a relation.
+ *
+ * Asked of the list, as a selector's relation is: the word was once taken as
+ * it stood, so `kind="blocks"` made an edge of a kind no rule knows, a
+ * document with such an edge to itself ended the run, and `kind="constructor"`
+ * did not, since the table of kinds is an object and answers to that name.
+ */
+function isEdgeKind(word) {
+    return EDGE_KINDS.includes(word);
+}
 function extractReferences(context) {
     const { scanned, directives, document, documentAt, items, byKey, status, claimed, file, index } = context;
     // This list and the one `withoutOverlaps` builds from it are only ever read
@@ -1035,11 +1054,14 @@ function extractReferences(context) {
     for (const directive of directives) {
         if (directive.name !== 'spec-edge')
             continue;
-        const kind = attr(directive, 'kind')?.value;
+        const written = attr(directive, 'kind')?.value;
         const to = attr(directive, 'to');
         const from = attr(directive, 'from');
-        if (!kind)
+        if (!written)
             continue;
+        // A word that names no relation is still a link to somewhere, as a cell
+        // under a column that names none is: a citation, and no more than one.
+        const kind = isEdgeKind(written) ? written : 'references';
         const owner = ownerOf(items, directive.start) ?? documentAt(directive.start).id;
         if (to) {
             out.push({
@@ -1048,7 +1070,7 @@ function extractReferences(context) {
                 target: to.value,
                 origin: 'directive',
                 declaredAt: at(to.start, to.end),
-                raw: `@spec-edge kind="${kind}" to="${to.value}"`,
+                raw: `@spec-edge kind="${written}" to="${to.value}"`,
                 inverted: false,
                 opportunistic: false,
             });
@@ -1060,7 +1082,7 @@ function extractReferences(context) {
                 target: from.value,
                 origin: 'directive',
                 declaredAt: at(from.start, from.end),
-                raw: `@spec-edge kind="${kind}" from="${from.value}"`,
+                raw: `@spec-edge kind="${written}" from="${from.value}"`,
                 inverted: true,
                 opportunistic: false,
             });