@descent-vtt/spec-graph 0.7.0 → 0.9.0

package/dist/extract.js

@@ -17,11 +17,11 @@
 import { attr, attrList, bindItemDirectives, parseDirectives } from './directives.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 { anchorsOf, isMarkdownLine, isOnlyComment, referenceLinks, scanMarkdown, slugify, } from './markdown.js';
 import { findSpecificationRegions, regionAt } from './sections.js';
 import { resolveItemState } from './state.js';
 import { refOf } from './source.js';
-import { parseFrontMatter, toRecord, valuesOf } from './yaml.js';
+import { readEntries, toRecord, valuesOf } from './yaml.js';
 /* -------------------------------------------------------------------------- */
 /* Vocabulary                                                                 */
 /* -------------------------------------------------------------------------- */
@@ -158,6 +158,19 @@ const RELATION_INDEX = new Map(Object.entries(RELATION_KEYS).map(([canonical, re
     foldRelationKey(canonical),
     { ...relation, canonical },
 ]));
+/**
+ * Whether a front-matter key is one the graph is built from: a status, an id
+ * or an alias, or a relation. Left unread, each changes a verdict - a status
+ * is unknown, a node is named by its path, an edge is missing. A title or a
+ * description left unread changes a label.
+ */
+function buildsGraph(key) {
+    return (STATUS_KEYS.includes(key) ||
+        ID_KEYS.includes(key) ||
+        key === 'alias' ||
+        key === 'aliases' ||
+        RELATION_INDEX.has(foldRelationKey(key)));
+}
 /**
  * Keys a region must answer for itself, so the file's answer cannot shadow one.
  *
@@ -476,6 +489,17 @@ export function extractDocument(input) {
             at: at(nul, nul + 1),
         });
     }
+    // CommonMark reads a comment that opens a line and never closes as running
+    // to the end of the document, and so does the scan: nothing after it is a
+    // heading, an item or a link. A renderer hides it all, so the author may see
+    // it, but the graph would lose it without a word.
+    const unclosed = scanned.comments.find((comment) => !comment.closed);
+    if (unclosed !== undefined) {
+        problems.push({
+            message: 'a comment opened here is never closed, so nothing after it is read - close it with -->',
+            at: at(unclosed.start, unclosed.start + 4),
+        });
+    }
     for (const directive of directives) {
         for (const unknown of directive.unknownAttributes) {
             problems.push({
@@ -484,7 +508,13 @@ export function extractDocument(input) {
             });
         }
     }
-    const entries = scanned.frontMatter ? parseFrontMatter(scanned.frontMatter.raw, scanned.frontMatter.start) : [];
+    const { entries, problems: unread } = readEntries(scanned);
+    for (const problem of unread) {
+        // A line that names no key could have held any of them, and so could a
+        // block that was not read at all.
+        const lost = problem.unread && (problem.key === null || buildsGraph(problem.key));
+        problems.push({ message: problem.message, at: at(problem.start, problem.end), ...(lost ? { unread: true } : {}) });
+    }
     const byKey = new Map();
     for (const entry of entries)
         byKey.set(entry.key, entry);
@@ -534,6 +564,7 @@ export function extractDocument(input) {
         path: input.path,
         aliases: identity.aliases,
         phase,
+        history: record,
         rawStatus: status.raw,
         statusAt: status.at,
         frontMatter: toRecord(entries),
@@ -587,7 +618,7 @@ export function extractDocument(input) {
     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 anchors = anchorsOf(scanned.headings);
     const filled = subSpecifications.map((spec) => ({
         ...spec.extracted,
         items: allItems.filter((item) => item.document === spec.document.id),
@@ -659,11 +690,12 @@ function buildRegion(context) {
         // wrote for itself. Being a record is a statement about the file made from
         // outside it, and it does not stop at a heading.
         phase: record ? 'record' : declaredPhase !== 'unknown' ? declaredPhase : pathPhase,
+        history: record,
         rawStatus,
         statusAt,
         frontMatter: inherited,
     };
-    const anchors = new Set(scanned.headings.filter((h) => h.start >= region.start && h.start < region.end).map((h) => h.slug));
+    const anchors = anchorsOf(scanned.headings.filter((h) => h.start >= region.start && h.start < region.end));
     // Relations a table declares by column, typed by the header the author wrote.
     const references = region.relations.map((relation) => ({
         kind: relation.kind,
@@ -744,9 +776,9 @@ function statusSectionBody(scanned, headingLine) {
     for (const line of scanned.lines) {
         if (line.line <= headingLine)
             continue;
-        if (line.blank)
+        if (line.blank || isOnlyComment(scanned, line))
             continue;
-        if (line.code)
+        if (!isMarkdownLine(line))
             return null;
         const trimmed = line.content.trim();
         // A heading immediately after means the section is empty.
@@ -960,7 +992,8 @@ function extractReferences(context) {
     // so `| ADR-0002 | ... | [ADR-0001](0001.md) |` yields one typed edge rather
     // than a typed edge and a neutral citation beside it.
     const linked = new Set();
-    for (const link of scanned.links) {
+    const links = referenceLinks(scanned);
+    for (const link of links) {
         if (link.form === 'definition')
             continue;
         if (isClaimed(claimed, link.start))
@@ -972,14 +1005,14 @@ function extractReferences(context) {
             continue;
         const owner = ownerOf(items, link.start) ?? documentAt(link.start).id;
         const section = sectionPathAt(scanned, link.start);
-        const classified = classifyReference(scanned.masked, link.start, link.end, section);
+        const classified = classifyReference(scanned.masks.structure, link.start, link.end, section);
         linked.add(normaliseRef(stripAnchor(target)));
         out.push({
             kind: classified.kind,
             from: owner,
             target,
             origin: 'link',
-            declaredAt: at(link.targetStart, link.targetStart + link.target.length),
+            declaredAt: at(link.targetStart, link.targetEnd),
             raw: renderLink(link),
             inverted: classified.inverted,
             opportunistic: false,
@@ -987,7 +1020,7 @@ function extractReferences(context) {
     }
     // Bare identifiers in prose. Everything already covered by a link is skipped
     // so a citation written as `[ADR-7](0007.md)` is not counted twice.
-    for (const bare of findBareReferences(scanned)) {
+    for (const bare of findBareReferences(scanned, links)) {
         const key = normaliseRef(bare.text);
         if (linked.has(key))
             continue;
@@ -995,7 +1028,7 @@ function extractReferences(context) {
             continue;
         const owner = ownerOf(items, bare.start) ?? documentAt(bare.start).id;
         const section = sectionPathAt(scanned, bare.start);
-        const classified = classifyReference(scanned.masked, bare.start, bare.end, section);
+        const classified = classifyReference(scanned.masks.structure, bare.start, bare.end, section);
         out.push({
             kind: classified.kind,
             from: owner,
@@ -1167,15 +1200,16 @@ function sentenceAfter(text, end) {
  * Link constructs are blanked first. Without that, `[ADR-7](https://x/adr-7)`
  * would yield three references to the same thing - one real and two harvested
  * out of a URL - which is precisely the mis-match that makes hand-rolled regex
- * checks untrustworthy.
+ * checks untrustworthy. Images are not blanked, since they are not references:
+ * an identifier in one's text is prose, as it always was here.
  */
-function findBareReferences(scanned) {
+function findBareReferences(scanned, links) {
     // Slice-based for the same reason as the scanner's masking: this runs over
     // every document, and a per-character array is the wrong shape for the job.
-    const source = scanned.masked;
+    const source = scanned.masks.structure;
     let text = '';
     let cursor = 0;
-    for (const link of scanned.links) {
+    for (const link of links) {
         const start = Math.max(link.start, cursor);
         const end = Math.min(link.end, source.length);
         if (end <= start)