@descent-vtt/spec-graph 0.3.0 → 0.5.0

package/dist/extract.js

@@ -15,7 +15,7 @@
  * broken reference to specification 256.
  */
 import { attr, attrList, directiveFor, parseDirectives } from './directives.js';
-import { identify, isDocumentTarget, isExternal, looksLikePath, normaliseRef, parsePrefixedRef, ID_KEYS, } from './identity.js';
+import { identify, isDocumentTarget, isExternal, looksLikePath, normaliseRef, parsePrefixedRef, withinOneEdit, ID_KEYS, } from './identity.js';
 import { isStatusHeading, phaseFromPath, phaseOf, STATUS_KEYS, supersessionTargetsIn } from './lifecycle.js';
 import { scanMarkdown, slugify } from './markdown.js';
 import { findSpecificationRegions, regionAt } from './sections.js';
@@ -95,43 +95,6 @@ export const RELATION_KEYS = {
     refs: { kind: 'references', inverted: false },
     'referenced-by': { kind: 'references', inverted: true },
 };
-/**
- * True when two folded keys are one edit apart.
- *
- * One edit, not two, and a transposition counts as one: `supercedesby` for
- * `supercededby` is a slip of the finger, `categories` for `dependencies` is a
- * different word. Written out rather than as a distance matrix because the
- * answer is a yes or a no and the bound is one - the general algorithm would be
- * more code, not less.
- */
-export function withinOneEdit(a, b) {
-    if (a === b)
-        return false;
-    if (a.length === b.length) {
-        let first = -1;
-        for (let i = 0; i < a.length; i += 1) {
-            if (a[i] === b[i])
-                continue;
-            if (first === -1) {
-                first = i;
-                continue;
-            }
-            // A second difference is allowed only if the two are a swapped pair, and
-            // only if there is no third.
-            return first === i - 1 && a[first] === b[i] && a[i] === b[first] && a.slice(i + 1) === b.slice(i + 1);
-        }
-        return true;
-    }
-    const [short, long] = a.length < b.length ? [a, b] : [b, a];
-    if (long.length - short.length !== 1)
-        return false;
-    for (let i = 0; i < short.length; i += 1) {
-        if (short[i] === long[i])
-            continue;
-        return short.slice(i) === long.slice(i + 1);
-    }
-    return true;
-}
 /**
  * True when a front-matter value is shaped like a citation.
  *
@@ -195,6 +158,35 @@ const RELATION_INDEX = new Map(Object.entries(RELATION_KEYS).map(([canonical, re
     foldRelationKey(canonical),
     { ...relation, canonical },
 ]));
+/**
+ * Keys a region must answer for itself, so the file's answer cannot shadow one.
+ *
+ * Identity and status and title are the three things a register exists to vary
+ * row by row. The rest of the file's front matter describes the file, and a
+ * decision inside the file is described by it too.
+ */
+const UNINHERITED = new Set([...ID_KEYS, ...STATUS_KEYS, 'title', 'alias', 'aliases']);
+/**
+ * The front matter a region inherits from the file that contains it.
+ *
+ * [ADR-0009](../docs/adr/0009-a-specification-is-a-region.md) left this open,
+ * and [ADR-0016](../docs/adr/0016-a-query-needs-a-sentence.md) made leaving it
+ * open a defect. A repository can now write `document[fm.owner!=platform]` as a
+ * rule of its own, and on a register every region answered nothing - which
+ * `!=` reads as a mismatch, because an absent value is not the value. A file
+ * whose front matter said `owner: platform` was reported twice for not being
+ * owned by platform, and the message rendered `{0.fm.owner}` as the literal
+ * placeholder. Confident, wrong, and unanswerable: the ADR-0006 failure.
+ *
+ * Two kinds of key stay behind. A relation key is a claim the file made -
+ * `supersedes:` at the top of a register supersedes on behalf of the register,
+ * not on behalf of each decision in it, and the edges were built from the
+ * file's entries before this ran. And a key the region answers itself must not
+ * be shadowed, which is {@link UNINHERITED}.
+ */
+export function inheritableFrontMatter(entries) {
+    return toRecord(entries.filter((entry) => !UNINHERITED.has(entry.key) && !RELATION_INDEX.has(foldRelationKey(entry.key))));
+}
 /**
  * Phrases that give a link its meaning, longest-matching-nearest wins.
  *
@@ -457,6 +449,8 @@ export function extractSpecifications(input) {
     return first === null ? [] : [first, ...first.subSpecifications];
 }
 /** Reads a file's own specification. Returns `null` when it opts out. */
+/** The one character that makes a text file read as binary to other tools. */
+const NUL = '\u0000';
 export function extractDocument(input) {
     const scanned = scanMarkdown(input.text);
     const directives = parseDirectives(scanned.comments);
@@ -466,6 +460,22 @@ export function extractDocument(input) {
     const file = input.path;
     const problems = [];
     const at = (start, end) => refOf(file, index, start, end);
+    const nul = input.text.indexOf(NUL);
+    if (nul !== -1) {
+        // Not a finding. Nothing about the graph is wrong, and the text parsed - a
+        // NUL is whitespace to every rule here. It is a problem with the *input*,
+        // which is what a ParseProblem is for, and it is worth one line because
+        // spec-graph is likely the only tool that got this far: grep, diff and
+        // every review interface read the file as binary and show nothing at all.
+        //
+        // The cause is almost always an encoding, not a keystroke. UTF-16 read as
+        // UTF-8 puts a NUL between every character, and the document that produces
+        // looks plausible in some editors and is mojibake everywhere else.
+        problems.push({
+            message: `contains a NUL byte, so grep, diff and review tooling read this file as binary - check whether it was saved as UTF-16`,
+            at: at(nul, nul + 1),
+        });
+    }
     for (const directive of directives) {
         for (const unknown of directive.unknownAttributes) {
             problems.push({
@@ -478,6 +488,7 @@ export function extractDocument(input) {
     const byKey = new Map();
     for (const entry of entries)
         byKey.set(entry.key, entry);
+    const inherited = inheritableFrontMatter(entries);
     const h1 = scanned.headings.find((h) => h.level === 1) ?? null;
     const frontMatterId = firstValue(byKey, ID_KEYS) ?? null;
     const identityOf = (declaredId, directive) => identify({
@@ -544,6 +555,7 @@ export function extractDocument(input) {
         file,
         pathPhase,
         record,
+        inherited,
     }));
     const ownerAt = (offset) => {
         const region = regionAt(regions, offset);
@@ -612,12 +624,13 @@ function belongsTo(reference, documentId, items) {
  * It produces exactly the `DocumentNode` a whole file produces, which is the
  * reason every rule, query and reporter works on registers without knowing they
  * exist. The only deliberate differences: the node is anchored at its heading
- * rather than at line one, it carries no front matter of its own, and it does
- * not claim the file's path as an alias - the file already does, and two nodes
- * answering to one path would make every link to that file ambiguous.
+ * rather than at line one, it carries the file's front matter rather than front
+ * matter of its own, and it does not claim the file's path as an alias - the
+ * file already does, and two nodes answering to one path would make every link
+ * to that file ambiguous.
  */
 function buildRegion(context) {
-    const { region, input, scanned, index, file, pathPhase, record } = context;
+    const { region, input, scanned, index, file, pathPhase, record, inherited } = context;
     const at = (start, end) => refOf(file, index, start, end);
     const identity = identify({
         path: input.path,
@@ -648,7 +661,7 @@ function buildRegion(context) {
         phase: record ? 'record' : declaredPhase !== 'unknown' ? declaredPhase : pathPhase,
         rawStatus,
         statusAt,
-        frontMatter: {},
+        frontMatter: inherited,
     };
     const anchors = new Set(scanned.headings.filter((h) => h.start >= region.start && h.start < region.end).map((h) => h.slug));
     // Relations a table declares by column, typed by the header the author wrote.
@@ -670,7 +683,8 @@ function buildRegion(context) {
             items: [],
             references,
             problems: [],
-            // A region has no front matter of its own to misread.
+            // The file has already reported anything misread at the top of it, and
+            // there is one file however many regions it holds.
             misreadKeys: [],
             anchors,
             identity,