@descent-vtt/spec-graph 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -11,6 +11,28 @@ 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
@@ -1410,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
 
@@ -630,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
@@ -1033,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
@@ -1041,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 |
@@ -1070,7 +1097,7 @@ steps:
     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@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
     with:
@@ -1093,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
@@ -1117,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:
@@ -1148,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
@@ -1163,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
@@ -1199,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:
@@ -1289,7 +1317,7 @@ 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,918 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.38% over 8,539 mutants, measured by CI's full sweep, and a build
 fails under 93 - because a vocabulary entry or a boundary

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descent-vtt/spec-graph",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Turn Markdown specs into a verifiable relational graph. Catches ghost handovers, stale premises and broken references in CI.",
   "keywords": [
     "adr",