@descent-vtt/spec-graph 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -11,6 +11,38 @@ the family's
 [versioning policy](https://github.com/DescentVTT/spec-core/blob/main/docs/adr/0009-versions-before-1-0.md)
 records.
 
+## 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

package/README.md

@@ -552,6 +552,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.
@@ -1061,16 +1063,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
     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
 ```
@@ -1287,9 +1289,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,918 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,
             });