@svp-labs/talos 0.0.0 → 0.1.0

package/dist/docs/comments/rules.js

@@ -0,0 +1,174 @@
+function blank(text) {
+    return ' '.repeat(text.length);
+}
+/** URLs and quoted code are what a comment shows, not what it says. */
+function prose(text) {
+    return text
+        .replaceAll(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, blank)
+        .replaceAll(/`[^`]*`/g, blank)
+        .replaceAll(/\b[\w.-]+\/[\w.-]+#\d+\b/g, blank);
+}
+const TODO = /\b(todo|fixme|xxx|hack)\b(\s*[:(])?/gi;
+/** A work marker: one written in capitals, or any spelling followed by `:` or `(`. */
+function todo(text) {
+    for (const match of text.matchAll(TODO)) {
+        const word = match[1] ?? '';
+        if (word === word.toUpperCase() || match[2] !== undefined)
+            return word.toUpperCase();
+    }
+    return undefined;
+}
+/** Ticket-shaped tokens that are standards and formats, not tickets. */
+const NOT_TICKETS = new Set([
+    'AES ANSI ARM ASN AVX BS COVID CP CRC CVE CWE DIN ECMA EN ES FIPS GPT GHSA HTTP IEC',
+    'IEEE ISO KOI MD NIST P PEP PSR RFC RSA SHA SP SSL TLS UCS UTF WCAG X',
+]
+    .join(' ')
+    .split(' '));
+const TICKET = /(?<![\p{L}\p{N}_/.-])([A-Z][A-Z0-9]{0,9})-(\d+)(?![\p{L}\p{N}_-]|\.\d)/gu;
+const ISSUE = /(?<![\p{L}\p{N}_&$#{/])#([1-9]\d*)\b/gu;
+function tickets(text) {
+    const found = [...text.matchAll(TICKET)]
+        .filter((match) => !NOT_TICKETS.has(match[1] ?? ''))
+        .map((match) => match[0]);
+    return [...found, ...[...text.matchAll(ISSUE)].map((match) => match[0])];
+}
+const ID = String.raw `[A-Z]{1,2}\d{1,3}[a-z]?`;
+const TOKEN = /(?<![\p{L}\p{N}_#$@/.\\-])([A-Z]{1,2}\d{1,3})[a-z]?(?![\p{L}\p{N}_-]|\.\d)/gu;
+const CITATION = new RegExp(String.raw `^(?:(?:her|his|its|their|see|per|cf\.?|also|[A-Z][\w'’]*)\s+)?${ID}` +
+    String.raw `(?:\s*(?:,|and|or|to|–|-|/|&)\s*${ID})*$`, 'u');
+/** Bare tokens that are names of things far more often than decisions. */
+const COMMON = new Set([
+    ...'H1 H2 H3 H4 H5 H6 V8 S3 R2 M1 M2 M3 M4 X11 L1 L2 L3'.split(' '),
+    ...Array.from({ length: 12 }, (_, index) => `F${String(index + 1)}`),
+]);
+/** A short ID cited in parentheses, or any ID this repository defines. */
+function cited(id, decisions) {
+    return decisions.has(id) || /^[A-Z]\d{1,2}$/.test(id);
+}
+/** The ID tokens of parenthesised citations, such as `(K4, K5)` or `(Talos C20)`. */
+function citationTokens(text) {
+    const tokens = [];
+    for (const group of text.matchAll(/\(([^()]*)\)/g)) {
+        let offset = group.index + 1;
+        for (const part of (group[1] ?? '').split(/([,;])/)) {
+            const tokensOfPart = CITATION.test(part.trim()) ? [...part.matchAll(TOKEN)] : [];
+            tokens.push(...tokensOfPart.map((token) => ({ id: token[1] ?? '', offset: offset + token.index })));
+            offset += part.length;
+        }
+    }
+    return tokens;
+}
+function decisionRefs(text, ctx) {
+    const citations = citationTokens(text);
+    const inCitations = new Set(citations.map((token) => token.offset));
+    const found = citations.filter((token) => cited(token.id, ctx.decisions)).map((t) => t.id);
+    for (const token of text.matchAll(TOKEN)) {
+        const id = token[1] ?? '';
+        if (!inCitations.has(token.index) && ctx.decisions.has(id) && !COMMON.has(id))
+            found.push(id);
+    }
+    return found;
+}
+const DATE = String.raw `(?:\d{4}-\d{2}(?:-\d{2})?\b|(?:jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\.?\s+\d)`;
+const CHANGED = String.raw `\b(?:added|changed|amended|modified|introduced|removed|updated|fixed|deprecated|re-?decided)`;
+const HISTORY = [
+    new RegExp(String.raw `${CHANGED}\s+(?:(?:on|in)\s+(?:v?\d+\.\d+\b|${DATE})|${DATE})`, 'i'),
+    /^(?:added|changed|modified|introduced|written)\s+by\b/i,
+    /\b(?:was|were)\s+previously\b|\bpreviously\s+(?:was|were|it|this|we|returned|called)\b/i,
+    /\bused\s+to\s+be\b|\bformerly\b|\brenamed\s+from\b|\bwas\s+(?:added|changed|renamed)\s+(?:in|on|by)\b/i,
+    /\b(?:originally|initially)\s+(?:was|were|this|it|we)\b/i,
+];
+const CODE = {
+    rust: [
+        /^(?:let|fn|use|pub|impl|mod|struct|enum|match|if|for|while|loop)\b.*[;{]$/,
+        /^[\w:.]+!?\(.*\)\s*;$/,
+        /^\w[\w.]* ?= ?[^\s=].*;$/,
+        /^[{}]$/,
+    ],
+    php: [
+        /^\$\w.*;$/,
+        /^(?:echo|return|use|namespace|require|include|throw|new)\b.*;$/,
+        /^(?:if|foreach|for|while|function|switch)\b.*\{$/,
+        /^[\w\\]+(?:->|::)\w+\(.*\)\s*;$/,
+        /^[{}]$/,
+    ],
+    lua: [
+        /^local [^=]+=[^=]/,
+        /^[\w.:]+\(.*\)$/,
+        /^(?:if|while|for)\b.*\b(?:then|do)$/,
+        /^[\w.[\]"']+\s*=\s*\S.*$/,
+    ],
+    shell: [
+        /^[A-Za-z_]\w*=\S*$/,
+        /^(?:export|local|readonly)\s+\w+=/,
+        /^(?:if|while)\s+\[.*\];?\s*(?:then|do)?$/,
+        /^(?:fi|done|esac)$/,
+        /^(?:echo|printf)\s+["'$]/,
+    ],
+    powershell: [
+        /^\$[\w:]+\s*=/,
+        /^[A-Z][a-z]+-[A-Z]\w*(?:\s|$)/,
+        /^(?:if|foreach|while)\s*\(.*\)\s*\{?$/,
+        /^[{}]$/,
+    ],
+};
+function lineProblems(comment, ctx) {
+    const text = prose(comment.text);
+    const problems = [];
+    const at = { line: comment.line };
+    const marker = todo(text);
+    if (marker !== undefined) {
+        problems.push({
+            rule: 'comments/todo',
+            ...at,
+            message: `This comment carries a ${marker} marker; file an issue for the work instead.`,
+        });
+    }
+    const references = [...tickets(text), ...decisionRefs(text, ctx)];
+    if (references.length > 0) {
+        problems.push({
+            rule: 'comments/reference',
+            ...at,
+            message: `This comment cites ${[...new Set(references)].join(', ')}; ` +
+                'say the reason itself, not where it was decided or tracked.',
+        });
+    }
+    if (HISTORY.some((pattern) => pattern.test(text.trim()))) {
+        problems.push({
+            rule: 'comments/history',
+            ...at,
+            message: "This comment tells the code's history; say what holds now, and leave history to the PR.",
+        });
+    }
+    return problems;
+}
+/** Runs of consecutive line comments that read as code, each one problem. */
+function commentedCode(lines, shape) {
+    const runs = [];
+    for (const comment of lines) {
+        if (comment.doc || comment.block)
+            continue;
+        if (!CODE[shape].some((pattern) => pattern.test(comment.text)))
+            continue;
+        const last = runs.at(-1);
+        if (last?.endLine === comment.line - 1)
+            last.endLine = comment.line;
+        else
+            runs.push({ line: comment.line, endLine: comment.line });
+    }
+    return runs.map((run) => ({
+        rule: 'comments/code',
+        line: run.line,
+        ...(run.endLine > run.line ? { endLine: run.endLine } : {}),
+        message: 'This comment holds code; delete it, since git keeps what was there.',
+    }));
+}
+/** What the comment rules find in one file's comments. */
+export function judgeComments(lines, ctx, shape) {
+    return [
+        ...lines.flatMap((comment) => lineProblems(comment, ctx)),
+        ...(shape === undefined ? [] : commentedCode(lines, shape)),
+    ];
+}
+//# sourceMappingURL=rules.js.map

package/dist/docs/comments/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../src/docs/comments/rules.ts"],"names":[],"mappings":"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"}

package/dist/docs/comments/scan.js

@@ -0,0 +1,138 @@
+function lineStarts(text) {
+    const starts = [0];
+    for (let index = text.indexOf('\n'); index !== -1; index = text.indexOf('\n', index + 1)) {
+        starts.push(index + 1);
+    }
+    return starts;
+}
+/** The 1-based line of an offset. */
+function lineOf(state, offset) {
+    let low = 0;
+    let high = state.lineStarts.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if ((state.lineStarts[middle] ?? 0) <= offset)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low + 1;
+}
+/** Runs the matchers over the text, first match wins; anything else is code, skipped. */
+export function scan(text, matchers, start = 0) {
+    const state = {
+        text,
+        at: start,
+        out: [],
+        lineStarts: lineStarts(text),
+        heredocDelimiters: [],
+    };
+    while (state.at < text.length) {
+        if (!matchers.some((matcher) => matcher(state)))
+            state.at += 1;
+    }
+    return state.out;
+}
+/** Records a comment's body, which starts at `from`, one entry per line. */
+export function emit(state, from, body, kind) {
+    const first = lineOf(state, from);
+    for (const [index, raw] of body.split('\n').entries()) {
+        const text = kind.block ? raw.replace(/^\s*\*(?!\/)/, '') : raw;
+        state.out.push({ line: first + index, text: text.trim(), ...kind });
+    }
+}
+/** The end of the line `from` is on (the offset of its newline, or the text's end). */
+export function endOfLine(text, from) {
+    const newline = text.indexOf('\n', from);
+    return newline === -1 ? text.length : newline;
+}
+/** A comment running to the end of the line, such as `//` or `#`. */
+export function lineComment(opener, options = {}) {
+    return (state) => {
+        if (!state.text.startsWith(opener, state.at))
+            return false;
+        if (options.when?.(state) === false)
+            return false;
+        const from = state.at + opener.length;
+        const end = options.end?.(state, from) ?? endOfLine(state.text, from);
+        const body = state.text.slice(from, end);
+        const doc = options.doc?.(body) ?? false;
+        emit(state, from, doc && options.marker ? body.replace(options.marker, '') : body, {
+            doc,
+            block: false,
+        });
+        state.at = end;
+        return true;
+    };
+}
+function nestedEnd(text, from, open, close) {
+    let depth = 1;
+    let index = from;
+    while (index < text.length && depth > 0) {
+        if (text.startsWith(open, index)) {
+            depth += 1;
+            index += open.length;
+        }
+        else if (text.startsWith(close, index)) {
+            depth -= 1;
+            index += close.length;
+        }
+        else
+            index += 1;
+    }
+    return depth === 0 ? index - close.length : text.length;
+}
+/** A comment between two markers, such as `/* … *\/`; Rust nests them. */
+export function blockComment(open, close, options = {}) {
+    return (state) => {
+        if (!state.text.startsWith(open, state.at))
+            return false;
+        const from = state.at + open.length;
+        const found = options.nested === true
+            ? nestedEnd(state.text, from, open, close)
+            : state.text.indexOf(close, from);
+        const end = found === -1 ? state.text.length : found;
+        const body = state.text.slice(from, end);
+        emit(state, from, body, { doc: options.doc?.(body) ?? false, block: true });
+        state.at = Math.min(state.text.length, end + close.length);
+        return true;
+    };
+}
+/** The offset after a string's closing quote, starting just after its opening one. */
+export function stringEnd(text, from, quote, options) {
+    let index = from;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === options.escape)
+            index += 2;
+        else if (text.startsWith(quote, index)) {
+            if (options.doubled === true && text.startsWith(quote, index + quote.length)) {
+                index += 2 * quote.length;
+            }
+            else
+                return index + quote.length;
+        }
+        else if (char === '\n' && options.multiline !== true)
+            return index;
+        else
+            index += 1;
+    }
+    return text.length;
+}
+/** A string literal, skipped so that comment markers inside it are not comments. */
+export function quoted(quote, options) {
+    return (state) => {
+        if (!state.text.startsWith(quote, state.at))
+            return false;
+        state.at = stringEnd(state.text, state.at + quote.length, quote, options);
+        return true;
+    };
+}
+/** The last character before `offset` that isn't white space, and where it is. */
+export function previousSignificant(text, offset) {
+    let index = offset - 1;
+    while (index >= 0 && /\s/.test(text[index] ?? ''))
+        index -= 1;
+    return index;
+}
+//# sourceMappingURL=scan.js.map

package/dist/docs/comments/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../../../src/docs/comments/scan.ts"],"names":[],"mappings":"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"}

package/dist/docs/comments/script.js

@@ -0,0 +1,135 @@
+import { blockComment, emit, endOfLine, lineComment, quoted, stringEnd, } from './scan.js';
+import { matchNaming } from '../../core/literal.js';
+/**
+ * A Python string. A triple-quoted one that starts a statement is a docstring, an API
+ * docblock, so its lines are reported as doc comments.
+ */
+const pythonString = (state) => {
+    const { text, at } = state;
+    const quote = text[at];
+    if (quote !== '"' && quote !== "'")
+        return false;
+    const triple = text.startsWith(quote.repeat(3), at);
+    if (!triple) {
+        state.at = stringEnd(text, at + 1, quote, { escape: '\\' });
+        return true;
+    }
+    const delimiter = quote.repeat(3);
+    const end = stringEnd(text, at + 3, delimiter, { escape: '\\', multiline: true });
+    const lineStart = text.lastIndexOf('\n', at - 1) + 1;
+    if (/^\s*[rRbBuUfF]{0,2}$/.test(text.slice(lineStart, at))) {
+        const body = text.slice(at + 3, Math.max(at + 3, end - 3));
+        emit(state, at + 3, body, { doc: true, block: true });
+    }
+    state.at = end;
+    return true;
+};
+/** Python: `#` comments and docstrings. */
+export const PYTHON = [lineComment('#'), pythonString];
+const LONG_OPEN = /^\[(=*)\[/;
+/** A Lua long bracket opening at `from`: where its body starts and ends, and where it closes. */
+function longBracket(text, from) {
+    const open = LONG_OPEN.exec(text.slice(from, from + 64));
+    if (open === null)
+        return undefined;
+    const close = `]${open[1] ?? ''}]`;
+    const body = from + open[0].length;
+    const found = text.indexOf(close, body);
+    if (found === -1)
+        return { body, bodyEnd: text.length, end: text.length };
+    return { body, bodyEnd: found, end: found + close.length };
+}
+const luaComment = (state) => {
+    if (!state.text.startsWith('--', state.at))
+        return false;
+    const long = longBracket(state.text, state.at + 2);
+    if (long === undefined) {
+        return lineComment('--', { doc: (rest) => rest.startsWith('-'), marker: /^-/ })(state);
+    }
+    emit(state, long.body, state.text.slice(long.body, long.bodyEnd), { doc: false, block: true });
+    state.at = long.end;
+    return true;
+};
+const luaLongString = (state) => {
+    if (state.text[state.at] !== '[')
+        return false;
+    const long = longBracket(state.text, state.at);
+    if (long === undefined)
+        return false;
+    state.at = long.end;
+    return true;
+};
+/** Lua: `--` comments, `--[[ ]]` blocks, and long strings that may hold `--`. */
+export const LUA = [
+    luaComment,
+    luaLongString,
+    quoted("'", { escape: '\\' }),
+    quoted('"', { escape: '\\' }),
+];
+const shebang = (state) => {
+    if (state.at !== 0 || !state.text.startsWith('#!'))
+        return false;
+    state.at = endOfLine(state.text, 0);
+    return true;
+};
+/** A `#` starts a shell comment only at a word's start; `$#` and `${#x}` are code. */
+function shellCommentStart(state) {
+    const before = state.text[state.at - 1];
+    return before === undefined || /[\s;&|(]/.test(before);
+}
+/** `<<EOF`, `<<-EOF` and `<<'EOF'`: the body starts on the next line. */
+const heredocOpen = (state) => {
+    if (!state.text.startsWith('<<', state.at) || state.text[state.at + 2] === '<')
+        return false;
+    const match = /^<<-?[ \t]*(["']?)([A-Za-z_]\w*)\1/.exec(state.text.slice(state.at, state.at + 80));
+    if (match === null)
+        return false;
+    state.heredocDelimiters.push(match[2] ?? '');
+    state.at += match[0].length;
+    return true;
+};
+/** A line that may close a here-document: its delimiter alone, after tabs. */
+const HEREDOC_CLOSE = /^\t*([A-Za-z_]\w*)[ \t]*$/gm;
+/** At a line's end with here-documents open, skips their bodies. */
+const heredocBodies = (state) => {
+    if (state.text[state.at] !== '\n' || state.heredocDelimiters.length === 0)
+        return false;
+    let at = state.at + 1;
+    for (const delimiter of state.heredocDelimiters.splice(0)) {
+        const found = matchNaming(HEREDOC_CLOSE, state.text, at, delimiter);
+        at = found === undefined ? state.text.length : found.index + found[0].length;
+    }
+    state.at = at;
+    return true;
+};
+/** Shell scripts. */
+export const SHELL = [
+    shebang,
+    heredocBodies,
+    lineComment('#', { when: shellCommentStart }),
+    heredocOpen,
+    quoted("'", { multiline: true }),
+    quoted('"', { escape: '\\', multiline: true }),
+];
+/** `@"` … `"@` and `@'` … `'@`, whose closing marker starts a line. */
+function hereString(quote) {
+    return (state) => {
+        if (!state.text.startsWith(`@${quote}`, state.at))
+            return false;
+        if (state.text.slice(state.at + 2, endOfLine(state.text, state.at)).trim() !== '')
+            return false;
+        const close = state.text.indexOf(`\n${quote}@`, state.at);
+        state.at = close === -1 ? state.text.length : close + 3;
+        return true;
+    };
+}
+/** PowerShell: `#` comments and `<# #>` blocks, which carry comment-based help. */
+export const POWERSHELL = [
+    blockComment('<#', '#>', { doc: (rest) => /^\s*\.[A-Z]/.test(rest) }),
+    lineComment('#'),
+    hereString('"'),
+    hereString("'"),
+    quoted("'", { doubled: true, multiline: true }),
+    quoted('"', { escape: '`', multiline: true }),
+];
+//# sourceMappingURL=script.js.map

package/dist/docs/comments/script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.js","sourceRoot":"","sources":["../../../src/docs/comments/script.ts"],"names":[],"mappings":"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"}

package/dist/docs/decisions.js

@@ -0,0 +1,168 @@
+import { maskCode, maskFences, maskHtmlComments } from './markdown.js';
+const HEADING = /^(#{2,3})[ \t]+([A-Z]{1,2}\d{1,4})[ \t]+[·—–:-][ \t]+\S/;
+const MARKER = /^(Reversed by|Reverses)[*_]*:(.*)$/;
+/** An ID-shaped token: not part of a word, a path, an anchor, a version or a ticket. */
+const TOKEN = /(?<![\p{L}\p{N}_#$@/.\\-])([A-Z]{1,2})(\d{1,4})[a-z]?(?![\p{L}\p{N}_-]|\.\d)/gu;
+/** What joins the IDs of one citation: `C3, C15 and C20`, `I1 to I7`. */
+const JOINER = /^(?:,(?: and| or)?|and|or|to|[;/–&-])$/;
+/** The IDs a marker line names. */
+function idsIn(text) {
+    return [...text.matchAll(TOKEN)].map((match) => `${match[1] ?? ''}${match[2] ?? ''}`);
+}
+function markersIn(lines, from, to) {
+    const reverses = [];
+    const reversedBy = [];
+    for (let index = from; index < to; index += 1) {
+        const match = MARKER.exec((lines[index] ?? '').replace(/^[>*_\s]+/, ''));
+        if (match === null)
+            continue;
+        const into = match[1] === 'Reverses' ? reverses : reversedBy;
+        into.push(...idsIn(match[2] ?? '').map((id) => ({ id, line: index + 1 })));
+    }
+    return [reverses, reversedBy];
+}
+/** The decisions a document defines, each with its reversal markers. */
+export function decisionsIn(doc) {
+    const lines = maskHtmlComments(maskFences(doc.text)).split('\n');
+    const starts = lines.flatMap((line, index) => {
+        const match = HEADING.exec(line);
+        return match?.[2] === undefined ? [] : [{ id: match[2], index }];
+    });
+    const headingLines = lines.flatMap((line, index) => (/^#{1,3}\s/.test(line) ? [index] : []));
+    return starts.map(({ id, index }) => {
+        const end = headingLines.find((line) => line > index) ?? lines.length;
+        const [reverses = [], reversedBy = []] = markersIn(lines, index + 1, end);
+        return { id, file: doc.file, line: index + 1, reverses, reversedBy };
+    });
+}
+function prefixOf(id) {
+    return /^[A-Z]+/.exec(id)?.[0] ?? '';
+}
+/** The systems whose decisions SVP-Labs documents cite by name: `Talos C20`, `Thea D8`. */
+const SYSTEMS = new Set(['Talos', 'Thea']);
+/**
+ * Whether the words before a citation name another repository's or person's decisions: a
+ * possessive or a pronoun (`Thea's D8`, `her G1`), a system's name, or a capitalised word in
+ * the middle of a sentence (`the LoreLock D3 rule`).
+ */
+function qualified(before) {
+    const trimmed = before.trimEnd();
+    if (trimmed === before)
+        return false;
+    const start = Math.max(trimmed.lastIndexOf(' '), trimmed.lastIndexOf('\t'), trimmed.lastIndexOf('(')) + 1;
+    const word = trimmed.slice(start).replaceAll(/[*_]/g, '');
+    if (/['’]s$/.test(word) || /^(?:her|his|its|their)$/i.test(word) || SYSTEMS.has(word)) {
+        return true;
+    }
+    if (!/^[A-Z]\p{L}+$/u.test(word))
+        return false;
+    const rest = trimmed.slice(0, start).replaceAll(/[*_]/g, '').trimEnd();
+    return rest !== '' && !/(?:[.:!?|>]|^\s*(?:[-+]|\d+[.)]))$/.test(rest);
+}
+/** Groups tokens into citations: tokens joined only by commas, `and`, `to` and the like. */
+function citations(line) {
+    const groups = [];
+    for (const match of line.matchAll(TOKEN)) {
+        const token = {
+            id: `${match[1] ?? ''}${match[2] ?? ''}`,
+            start: match.index,
+            end: match.index + match[0].length,
+        };
+        const last = groups.at(-1)?.at(-1);
+        const between = line
+            .slice(last?.end ?? 0, token.start)
+            .trim()
+            .replaceAll(/\s+/g, ' ');
+        if (last !== undefined && JOINER.test(between)) {
+            groups.at(-1)?.push(token);
+        }
+        else
+            groups.push([token]);
+    }
+    return groups;
+}
+/**
+ * The references a document makes to this repository's decisions: ID tokens in prose whose
+ * prefix is one the repository defines. A citation qualified by a name (`Talos C20`, `Thea's
+ * D8`, `her G1`) points at another repository's decisions and is left alone.
+ */
+export function referencesIn(doc, prefixes) {
+    const lines = maskCode(doc.text).split('\n');
+    return lines.flatMap((line, index) => citations(line)
+        .filter((group) => !qualified(line.slice(0, group[0]?.start ?? 0)))
+        .flat()
+        .filter((token) => prefixes.has(prefixOf(token.id)))
+        .map((token) => ({ id: token.id, file: doc.file, line: index + 1, column: token.start + 1 })));
+}
+function duplicates(decisions) {
+    const first = new Map();
+    return decisions.flatMap((decision) => {
+        const earlier = first.get(decision.id);
+        if (earlier === undefined) {
+            first.set(decision.id, decision);
+            return [];
+        }
+        return [
+            {
+                rule: 'decisions/duplicate-id',
+                file: decision.file,
+                line: decision.line,
+                message: `${decision.id} is already defined at ${earlier.file}:${String(earlier.line)}; ` +
+                    'give this decision an ID of its own.',
+            },
+        ];
+    });
+}
+function oneWay(byId, decision) {
+    const check = (marker, back) => {
+        const other = byId.get(marker.id);
+        if (other === undefined || other[back].some((m) => m.id === decision.id))
+            return [];
+        const [said, missing] = back === 'reversedBy' ? ['reverses', 'Reversed by'] : ['is reversed by', 'Reverses'];
+        return [
+            {
+                rule: 'decisions/one-way-reversal',
+                file: decision.file,
+                line: marker.line,
+                message: `${decision.id} ${said} ${marker.id}, but ${marker.id} has no ` +
+                    `"${missing}: ${decision.id}" line; link the two both ways.`,
+            },
+        ];
+    };
+    return [
+        ...decision.reverses.flatMap((marker) => check(marker, 'reversedBy')),
+        ...decision.reversedBy.flatMap((marker) => check(marker, 'reverses')),
+    ];
+}
+/**
+ * Judges the decision records: `definitions` are `DECISIONS.md` and the briefs, `documents`
+ * every Markdown file whose references must resolve (the definitions among them).
+ */
+export function judgeDecisions(definitions, documents) {
+    const decisions = definitions.flatMap((doc) => decisionsIn(doc));
+    const byId = new Map();
+    for (const decision of decisions)
+        if (!byId.has(decision.id))
+            byId.set(decision.id, decision);
+    const prefixes = new Set(decisions.map((decision) => prefixOf(decision.id)));
+    const unresolved = documents
+        .flatMap((doc) => referencesIn(doc, prefixes))
+        .filter((reference) => !byId.has(reference.id))
+        .map((reference) => ({
+        rule: 'decisions/unresolved-reference',
+        file: reference.file,
+        line: reference.line,
+        column: reference.column,
+        message: `${reference.id} names no decision in DECISIONS.md or the briefs.`,
+    }));
+    return [
+        ...duplicates(decisions),
+        ...unresolved,
+        ...decisions.flatMap((decision) => oneWay(byId, decision)),
+    ];
+}
+/** Every decision ID the documents define, for checks that look for citations elsewhere. */
+export function decisionIds(definitions) {
+    return new Set(definitions.flatMap((doc) => decisionsIn(doc).map((decision) => decision.id)));
+}
+//# sourceMappingURL=decisions.js.map