@descent-vtt/spec-graph 0.2.3 → 0.4.0

package/dist/extract.js

@@ -15,7 +15,7 @@
  * broken reference to specification 256.
  */
 import { attr, attrList, directiveFor, parseDirectives } from './directives.js';
-import { identify, isExternal, normaliseRef, 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';
@@ -25,34 +25,139 @@ import { parseFrontMatter, toRecord, valuesOf } from './yaml.js';
 /* -------------------------------------------------------------------------- */
 /* Vocabulary                                                                 */
 /* -------------------------------------------------------------------------- */
-/** Front-matter keys that declare a relation, and what they mean. */
-const RELATION_KEYS = {
+/**
+ * Front-matter keys that declare a relation, and what they mean.
+ *
+ * Every directional kind is spelled in **both** directions. A register that
+ * records `depends-on` but not `depended-on-by` is not a smaller vocabulary, it
+ * is a trap: the author writes the inverse, the key means nothing, and the edge
+ * they declared is missing from a graph that reports itself as consistent. Which
+ * half of a pair a repository writes is a filing convention, and a filing
+ * convention is not something a linter gets to have an opinion about.
+ *
+ * `relates-to` is the exception, and it is not one: the relation is symmetric,
+ * so it has no other direction to spell. `contains` is structural and never
+ * written by hand. `tests/parsing.test.ts` holds both facts to the fire.
+ */
+export const RELATION_KEYS = {
     supersedes: { kind: 'supersedes', inverted: false },
     supercedes: { kind: 'supersedes', inverted: false },
     replaces: { kind: 'supersedes', inverted: false },
     obsoletes: { kind: 'supersedes', inverted: false },
+    deprecates: { kind: 'supersedes', inverted: false },
     'superseded-by': { kind: 'supersedes', inverted: true },
     'superceded-by': { kind: 'supersedes', inverted: true },
     'replaced-by': { kind: 'supersedes', inverted: true },
     'obsoleted-by': { kind: 'supersedes', inverted: true },
+    'deprecated-by': { kind: 'supersedes', inverted: true },
+    'rolled-into': { kind: 'supersedes', inverted: true },
     amends: { kind: 'amends', inverted: false },
     extends: { kind: 'amends', inverted: false },
+    refines: { kind: 'amends', inverted: false },
+    clarifies: { kind: 'amends', inverted: false },
+    revises: { kind: 'amends', inverted: false },
     'amended-by': { kind: 'amends', inverted: true },
+    'extended-by': { kind: 'amends', inverted: true },
+    'refined-by': { kind: 'amends', inverted: true },
+    'clarified-by': { kind: 'amends', inverted: true },
+    'revised-by': { kind: 'amends', inverted: true },
     'depends-on': { kind: 'depends-on', inverted: false },
+    'dependent-on': { kind: 'depends-on', inverted: false },
     dependencies: { kind: 'depends-on', inverted: false },
     requires: { kind: 'depends-on', inverted: false },
+    'builds-on': { kind: 'depends-on', inverted: false },
+    'relies-on': { kind: 'depends-on', inverted: false },
+    'depended-on-by': { kind: 'depends-on', inverted: true },
+    'required-by': { kind: 'depends-on', inverted: true },
+    dependents: { kind: 'depends-on', inverted: true },
     assumes: { kind: 'assumes', inverted: false },
+    'assumed-by': { kind: 'assumes', inverted: true },
     'blocked-by': { kind: 'blocked-by', inverted: false },
+    'blocked-on': { kind: 'blocked-by', inverted: false },
+    'waiting-on': { kind: 'blocked-by', inverted: false },
+    'waiting-for': { kind: 'blocked-by', inverted: false },
+    'gated-on': { kind: 'blocked-by', inverted: false },
+    'gated-by': { kind: 'blocked-by', inverted: false },
     blocks: { kind: 'blocked-by', inverted: true },
     'delegates-to': { kind: 'delegates-to', inverted: false },
     'delegated-to': { kind: 'delegates-to', inverted: false },
+    'deferred-to': { kind: 'delegates-to', inverted: false },
     'tracked-in': { kind: 'delegates-to', inverted: false },
+    'tracked-by': { kind: 'delegates-to', inverted: false },
+    'continued-in': { kind: 'delegates-to', inverted: false },
+    'delegated-from': { kind: 'delegates-to', inverted: true },
     related: { kind: 'relates-to', inverted: false },
     'relates-to': { kind: 'relates-to', inverted: false },
+    'related-to': { kind: 'relates-to', inverted: false },
     'see-also': { kind: 'relates-to', inverted: false },
     references: { kind: 'references', inverted: false },
+    reference: { kind: 'references', inverted: false },
     refs: { kind: 'references', inverted: false },
+    'referenced-by': { kind: 'references', inverted: true },
 };
+/**
+ * True when a front-matter value is shaped like a citation.
+ *
+ * The second half of the gate on {@link misreadRelationKeys}, and the half that
+ * does the work. `sidebar_position: 4` and `ref: main` are a hair away from a
+ * relation key by spelling alone; neither carries anything that could name a
+ * document, and reporting them would make the rule an irritation rather than a
+ * catch (ADR-0006).
+ */
+function looksLikeCitation(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (parsePrefixedRef(trimmed) !== null)
+        return true;
+    return looksLikePath(trimmed) && isDocumentTarget(trimmed) && !isExternal(trimmed);
+}
+/**
+ * Front-matter keys that read as relations and declare none.
+ *
+ * Front matter is an open vocabulary and most of what lives there is nobody
+ * else's business, so the bar is deliberately high: the key has to be one edit
+ * from a relation key *and* carry something that could name a document. Both
+ * conditions together are what separates `dependson: ADR-0001`, which is an edge
+ * the author believes exists, from `description: ...`, which is a title.
+ */
+function misreadRelationKeys(byKey, from, at) {
+    const out = [];
+    for (const [key, entry] of byKey) {
+        const folded = foldRelationKey(key);
+        if (folded.length === 0 || RELATION_INDEX.has(folded))
+            continue;
+        if (!valuesOf(entry).some(looksLikeCitation))
+            continue;
+        const near = [...RELATION_INDEX.values()]
+            .filter((relation) => withinOneEdit(folded, foldRelationKey(relation.canonical)))
+            .map((relation) => relation.canonical);
+        if (near.length === 0)
+            continue;
+        out.push({ key, suggestion: near.join(', '), from, at: at(entry.start, entry.end) });
+    }
+    return out;
+}
+/**
+ * Folds a front-matter key to its lookup form.
+ *
+ * `depends-on`, `depends_on`, `dependsOn` and `Depends On` are one key written
+ * four ways, and which one a repository uses is decided by whatever wrote the
+ * front matter first. Dropping every separator collapses them - the YAML reader
+ * has already lower-cased the key, which is what makes camel case fold too.
+ *
+ * Which case this folds to is arbitrary and no test pins it: both sides of every
+ * comparison come through here, so upper would work exactly as well. Asserting
+ * on it would be asserting on the implementation.
+ */
+export function foldRelationKey(key) {
+    return key.replace(/[^a-z0-9]/gi, '').toLowerCase();
+}
+/** The vocabulary above, indexed by folded key. */
+const RELATION_INDEX = new Map(Object.entries(RELATION_KEYS).map(([canonical, relation]) => [
+    foldRelationKey(canonical),
+    { ...relation, canonical },
+]));
 /**
  * Phrases that give a link its meaning, longest-matching-nearest wins.
  *
@@ -315,6 +420,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);
@@ -324,6 +431,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({
@@ -432,6 +555,7 @@ export function extractDocument(input) {
     // Hand each region the items and references that fall inside it.
     const ownItems = allItems.filter((item) => item.document === identity.id);
     const ownReferences = allReferences.filter((reference) => belongsTo(reference, identity.id, allItems));
+    const misreadKeys = misreadRelationKeys(byKey, identity.id, at);
     const anchors = new Set(scanned.headings.map((h) => h.slug));
     const filled = subSpecifications.map((spec) => ({
         ...spec.extracted,
@@ -448,6 +572,7 @@ export function extractDocument(input) {
         items: ownItems,
         references: ownReferences,
         problems,
+        misreadKeys,
         anchors,
         identity,
         scanned,
@@ -526,6 +651,8 @@ function buildRegion(context) {
             items: [],
             references,
             problems: [],
+            // A region has no front matter of its own to misread.
+            misreadKeys: [],
             anchors,
             identity,
             scanned,
@@ -717,10 +844,12 @@ function extractReferences(context) {
     const { scanned, directives, document, documentAt, items, byKey, status, claimed, file, index } = context;
     const out = [];
     const at = (start, end) => refOf(file, index, start, end);
-    // Front matter.
-    for (const [key, relation] of Object.entries(RELATION_KEYS)) {
-        const entry = byKey.get(key) ?? byKey.get(key.replace(/-/g, '_'));
-        if (!entry)
+    // Front matter, walked in the order it was written rather than in the order
+    // the vocabulary happens to be listed: a key the table does not know still has
+    // to be looked at, and only the document knows which those are.
+    for (const [key, entry] of byKey) {
+        const relation = RELATION_INDEX.get(foldRelationKey(key));
+        if (!relation)
             continue;
         for (const value of valuesOf(entry)) {
             const target = cleanTarget(value);
@@ -1081,7 +1210,7 @@ function renderLink(link) {
             return `<${link.target}>`;
         case 'reference':
         case 'shortcut':
-            return `[${link.text}][${link.target}]`;
+            return `[${link.text}][${link.label ?? ''}]`;
         default:
             return `[${link.text}](${link.target})`;
     }