@descent-vtt/spec-graph 0.3.0 → 0.5.0

package/dist/cli.js

@@ -8,14 +8,16 @@
  * Exit codes are the contract with CI: `0` clean, `1` findings, `2` the tool
  * itself could not run. A usage mistake never masquerades as a passing build.
  */
-import { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline } from './baseline.js';
-import { loadConfig } from './config.js';
-import { underRoot } from './glob.js';
+import { applyBaseline, EMPTY_BASELINE, formatBaseline, parseBaseline, } from './baseline.js';
+import { discoverConfig, loadConfig } from './config.js';
+import { isGlob, underRoot } from './glob.js';
 import { analyse, DEFAULT_PATTERNS, withDiagnostics } from './runner.js';
-import { formatGraph, formatJson, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
-import { DEFAULT_SEVERITIES, resolveStrict, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES } from './rules.js';
+import { formatGraph, formatJson, formatMarkdown, formatReport, formatSarif, shouldUseAscii, shouldUseColor, } from './report.js';
+import { DEFAULT_SEVERITIES, resolveStrict, RULE_DECISIONS, RULE_DESCRIPTIONS, RULE_IDS, RULE_QUERIES, } from './rules.js';
+import { toPosix } from './paths.js';
 import { formatRef } from './source.js';
 import { execute, parseQuery, QueryError, renderMatch } from './select.js';
+import { isProjectRule } from './types.js';
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_ERROR = 2;
@@ -29,18 +31,27 @@ export const HELP = `spec-graph - turn Markdown specifications into a verifiable
 
 USAGE
   spec-graph [check] [patterns...] [options]
-  spec-graph query <selector> [patterns...] [options]
+  spec-graph query <selector|project:rule> [patterns...] [options]
   spec-graph graph [patterns...] [--graph-format dot|mermaid|json]
-  spec-graph rules [--explain]
+  spec-graph rules [rule-id] [--explain]
 
 COMMANDS
   check     Validate the specification graph. The default.
-  query     Run a selector and print the matching paths.
+  query     Run a selector - or a registered project rule, by its id - and
+            print the matching paths.
   graph     Export the graph for Graphviz, Mermaid, or another tool.
-  rules     List the built-in diagnostics.
+  rules     List the diagnostics that will run, built in and project. Name one
+            to see only that one; --explain adds its selector and the ADR that
+            decided it.
 
 OPTIONS
-  --root <dir>            Directory the patterns resolve against (default: cwd)
+  --root <dir>            Directory the patterns resolve against. Without it,
+                          .spec-graph.json is looked for in the working
+                          directory and then upward as far as the repository,
+                          and the directory holding it becomes the root - so a
+                          run from a subdirectory reports what a run from the
+                          top reports. Paths typed on the command line stay
+                          relative to where they were typed.
   --ignore <glob>         Skip paths. Repeatable.
   --ignore-ref <glob>     Do not report these reference targets when they fail
                           to resolve, for repositories where [[...]] tags a
@@ -60,19 +71,23 @@ OPTIONS
   --ratchet               Also fail when a baseline entry no longer occurs, so
                           a paid-off exemption cannot outlive the defect.
   --no-config             Ignore .spec-graph.json and the package.json key.
-  --format <fmt>          human, json, or sarif - the interchange format
-                          GitHub code scanning and editors already read
-                          (default: human)
+  --format <fmt>          human, json, sarif or markdown. sarif is the
+                          interchange format GitHub code scanning and editors
+                          already read; markdown is a table for a pull-request
+                          comment or $GITHUB_STEP_SUMMARY (default: human)
   --graph-format <fmt>    dot, mermaid or json (default: dot)
   --documents-only        Leave items out of the exported graph
-  --rule <id>=<severity>  Override one rule: error, warn, info or off. Repeatable.
+  --rule <id>=<severity>  Override one rule: error, warn, info or off. A project
+                          rule is named in full: project:no-draft-dependency.
+                          Repeatable.
   --max <n>               Show at most n findings (0 = no limit)
   --max-warnings <n>      Fail when warnings exceed n (default: no limit)
   --strict                Raise every warning to an error. An explicit --rule
                           still wins, so --strict --rule x=warn exempts x.
   --color / --no-color    Force colour on or off
   --ascii                 Use ASCII glyphs only
-  --verbose               Include parse problems and per-file detail
+  --verbose               Include parse problems, per-file detail, and every
+                          reference --ignore-ref or --ignore-family silenced
   -h, --help              Show this help
   -v, --version           Show the version
 
@@ -89,6 +104,11 @@ SELECTORS
                alias, document, state (or disposition), openness, section,
                text, body, evidence, conflicted, fm.<front-matter-key>
   Operators:   = != ^= $= *= ~=   and [attr] for "is present"
+               ~= is a regular expression, matched by an automaton that cannot
+               backtrack: linear in the subject, whatever the pattern. It reads
+               the usual syntax minus backreferences and lookaround, which are
+               not regular - both are refused when the selector is read, with
+               the character pointed at
   Relations:   -kind->  <-kind-   =kind=>  <=kind=   (= forms are transitive)
 
 EXIT CODES
@@ -114,6 +134,34 @@ CONFIGURATION
   A flag always wins over the file, and list flags add to it rather than
   replacing it.
 
+PROJECT RULES
+  A convention spec-graph never anticipated is a selector plus a sentence, and
+  belongs in the same file. Every rule declared here runs beside the built-ins
+  and is reported, baselined, escalated by --strict and silenced by --rule in
+  exactly the same way.
+
+    { "rules": {
+        "no-draft-dependency": {
+          "query": "document[phase=active] -depends-on-> document[phase=draft]",
+          "message": "{0} depends on {1}, which is still a draft",
+          "hint": "wait for {1} to be accepted, or drop it from {0.path}",
+          "severity": "error" } } }
+
+  query     One selector, or a list of them read as a union.
+  message   The headline. {0} is the first node on the path, {1} the next;
+            {1.phase} and {0.fm.owner} read any selector attribute.
+  hint      The next action. Optional, and templated the same way.
+  severity  error, warn, info or off. Defaults to warn - a rule a team has
+            just written has not yet earned the right to fail their build.
+
+  The id is the name with project: in front, which is why it can never collide
+  with a built-in. A selector that does not parse, or a {2} the query can never
+  reach, is reported when the file is read rather than found missing later.
+
+  To see what one matches without copying its selector out of the file:
+
+    spec-graph query project:no-draft-dependency --verbose
+
 ADOPTING THIS ON AN OLD REPOSITORY
   Record what is already wrong, then report only what happens next:
 
@@ -132,6 +180,11 @@ EXAMPLES
   spec-graph graph --documents-only --graph-format mermaid > graph.mmd
   spec-graph check --history "**/JOURNAL_*.md"   # a log is not a specification
   spec-graph check --baseline .spec-graph-baseline.json
+  spec-graph rules --explain                # including this repository's own
+  spec-graph rules ghost-handover --explain      # and why it exists
+  spec-graph check --rule project:no-draft-dependency=off
+  spec-graph query project:no-draft-dependency   # what does that rule match?
+  spec-graph check --format markdown >> "$GITHUB_STEP_SUMMARY"
 `;
 const SEVERITIES = ['error', 'warn', 'info', 'off'];
 /** Parses argv into options. Throws {@link UsageError} on anything malformed. */
@@ -154,6 +207,7 @@ export function parseArgs(argv, cwd) {
     let noConfig = false;
     const severities = {};
     let root = cwd;
+    let rootExplicit = false;
     let format = 'human';
     let graphFormat = 'dot';
     let color = null;
@@ -223,6 +277,7 @@ export function parseArgs(argv, cwd) {
                 break;
             case '--root':
                 root = next(arg, i);
+                rootExplicit = true;
                 i += 1;
                 break;
             case '--ignore':
@@ -258,8 +313,8 @@ export function parseArgs(argv, cwd) {
                 break;
             case '--format': {
                 const value = next(arg, i);
-                if (value !== 'human' && value !== 'json' && value !== 'sarif') {
-                    throw new UsageError(`--format must be human, json or sarif, got "${value}"`);
+                if (value !== 'human' && value !== 'json' && value !== 'sarif' && value !== 'markdown') {
+                    throw new UsageError(`--format must be human, json, sarif or markdown, got "${value}"`);
                 }
                 format = value;
                 i += 1;
@@ -281,7 +336,11 @@ export function parseArgs(argv, cwd) {
                     throw new UsageError(`--rule expects <id>=<severity>, got "${value}"`);
                 const id = value.slice(0, equals);
                 const level = value.slice(equals + 1);
-                if (!RULE_IDS.includes(id)) {
+                // A project rule is taken on its namespace here and checked for real
+                // once the configuration defining it has been read: arguments are
+                // parsed before any file is opened, and a flag has to be usable on that
+                // first pass whatever the repository turns out to declare.
+                if (!RULE_IDS.includes(id) && !isProjectRule(id)) {
                     throw new UsageError(`unknown rule "${id}"\n  known rules: ${RULE_IDS.join(', ')}`);
                 }
                 if (!SEVERITIES.includes(level)) {
@@ -308,8 +367,8 @@ export function parseArgs(argv, cwd) {
     // SARIF is a report about findings, and only `check` produces those. Falling
     // back to JSON would hand a pipeline something its uploader rejects with a
     // message about a schema rather than about the command that was run.
-    if (format === 'sarif' && command !== 'check' && !help && !version) {
-        throw new UsageError(`--format sarif reports findings, so it belongs to check, not to ${command}`);
+    if ((format === 'sarif' || format === 'markdown') && command !== 'check' && !help && !version) {
+        throw new UsageError(`--format ${format} reports findings, so it belongs to check, not to ${command}`);
     }
     if (command === 'query' && selector === null && !help && !version) {
         throw new UsageError('query needs a selector, for example:\n  spec-graph query \'item[openness=open]\'');
@@ -318,6 +377,7 @@ export function parseArgs(argv, cwd) {
         command,
         patterns,
         root,
+        rootExplicit,
         ignore,
         ignoreReferences,
         families,
@@ -401,34 +461,72 @@ export async function main(io = {}) {
     }
     const color = options.color ?? shouldUseColor({ isTTY: io.isTTY, env });
     const ascii = options.ascii ?? shouldUseAscii({ env });
-    if (options.command === 'rules') {
-        out(renderRules(options.verbose));
-        return EXIT_OK;
-    }
     // Configuration is what is true of the repository; a flag is somebody
     // overriding it for one run. So a flag always wins, and lists add rather than
     // replace - a `--ignore-ref` on the command line is one more exclusion, not a
     // decision to throw away the ones the repository already declared.
-    const loaded = options.noConfig ? { config: {}, source: null, problems: [] } : loadConfig(options.root);
+    //
+    // Read before `rules` prints anything, so that command lists the conventions
+    // this repository will actually check rather than the ones spec-graph ships.
+    const loaded = options.noConfig
+        ? { config: {}, source: null, problems: [], root: options.root }
+        : options.rootExplicit
+            ? { ...loadConfig(options.root), root: options.root }
+            : discoverConfig(options.root);
     for (const problem of loaded.problems)
         err(`spec-graph: ${problem}\n`);
     const file = loaded.config;
-    const patterns = options.patterns.length > 0 ? options.patterns : (file.patterns ?? DEFAULT_PATTERNS);
+    const projectRules = file.rules ?? [];
+    const root = loaded.root;
+    // How far the root moved up. Everything a repository declares about itself is
+    // relative to the root; everything typed on the command line is relative to
+    // where it was typed, and this is what keeps those two readings apart.
+    const here = below(root, options.root);
+    // A `--rule` naming a project rule that does not exist is a flag that
+    // silently does nothing, and nothing in the output would distinguish that
+    // from a rule that ran and found none.
+    for (const id of Object.keys(options.severities)) {
+        if (!isProjectRule(id) || projectRules.some((rule) => rule.id === id))
+            continue;
+        err(`spec-graph: unknown rule "${id}"\n  ${knownProjectRules(projectRules)}\n`);
+        return EXIT_ERROR;
+    }
+    if (options.command === 'rules') {
+        // The one positional argument `rules` can take is a rule id: this command
+        // reads no files, so a pattern here would be a word with nowhere to go.
+        const wanted = options.patterns[0];
+        if (wanted !== undefined && !RULE_IDS.includes(wanted) && !projectRules.some((rule) => rule.id === wanted)) {
+            err(`spec-graph: unknown rule "${wanted}"\n  known rules: ${RULE_IDS.join(', ')}\n  ${knownProjectRules(projectRules)}\n`);
+            return EXIT_ERROR;
+        }
+        out(renderRules(options.verbose, projectRules, wanted ?? null, loaded.source));
+        return EXIT_OK;
+    }
+    const patterns = options.patterns.length > 0 ? options.patterns.map((pattern) => anchor(here, pattern)) : (file.patterns ?? DEFAULT_PATTERNS);
     const severityOverrides = { ...(file.severities ?? {}), ...options.severities };
-    const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false));
+    const { severities, escalated } = resolveStrict(severityOverrides, options.strict || (file.strict ?? false), projectRules);
     const analyseOptions = {
-        root: options.root,
+        root,
         patterns,
-        ignore: [...(file.ignore ?? []), ...options.ignore],
+        // A bare name prunes a directory of that name at any depth, the way a
+        // .gitignore line does, so it means the same thing wherever it was typed.
+        // A path or a glob is matched against the repository-relative path, and
+        // leaving that one alone would make it silently match nothing.
+        ignore: [...(file.ignore ?? []), ...options.ignore.map((pattern) => anchorPath(here, pattern))],
         ignoreReferences: [...(file.ignoreReferences ?? []), ...options.ignoreReferences],
         families: [...(file.families ?? []), ...options.families],
         ignoreFamilies: [...(file.ignoreFamilies ?? []), ...options.ignoreFamilies],
-        historyPatterns: [...(file.historyPatterns ?? []), ...options.historyPatterns],
+        historyPatterns: [...(file.historyPatterns ?? []), ...options.historyPatterns.map((pattern) => anchorPath(here, pattern))],
         severities,
+        projectRules,
         ...(file.maxRelated !== undefined ? { maxRelated: file.maxRelated } : {}),
     };
-    if (options.verbose && loaded.source !== null)
-        out(`configuration: ${loaded.source}\n`);
+    // Named the way the reader would have to type it, because a discovered
+    // configuration is often not the one in front of them.
+    if (options.verbose && loaded.source !== null) {
+        const depth = here === '' ? 0 : here.split('/').length;
+        out(`configuration: ${'../'.repeat(depth)}${loaded.source}\n`);
+    }
     let result;
     try {
         result = await analyse(analyseOptions);
@@ -438,7 +536,7 @@ export async function main(io = {}) {
         return EXIT_ERROR;
     }
     if (result.files.length === 0) {
-        err(`spec-graph: no specifications matched ${options.patterns.length > 0 ? options.patterns.map((p) => `"${p}"`).join(', ') : 'the default patterns'}\n  looked under ${options.root}\n`);
+        err(`spec-graph: no specifications matched ${patterns.map((p) => `"${p}"`).join(', ')}\n  looked under ${root}\n`);
         return EXIT_ERROR;
     }
     switch (options.command) {
@@ -446,18 +544,38 @@ export async function main(io = {}) {
             out(formatGraph(result.graph, options.graphFormat, { documentsOnly: options.documentsOnly }));
             return EXIT_OK;
         case 'query': {
-            try {
-                const matches = execute(result.graph, parseQuery(options.selector));
-                out(renderMatches(matches, options.format === 'json' ? 'json' : 'human', result.graph.nodes.size));
-                return matches.length > 0 ? EXIT_OK : EXIT_FAILED;
-            }
-            catch (error) {
-                if (error instanceof QueryError) {
-                    err(renderQueryError(options.selector, error));
+            const selector = options.selector;
+            let queries;
+            // A registered rule is asked for by name, because by the time this runs
+            // it is already compiled and the alternative is copying its selector out
+            // of the configuration file by hand. The namespace cannot collide with
+            // the grammar: no selector begins with a word and a colon. See ADR-0016.
+            if (isProjectRule(selector)) {
+                const rule = projectRules.find((candidate) => candidate.id === selector);
+                if (rule === undefined) {
+                    err(`spec-graph: unknown rule "${selector}"\n  ${knownProjectRules(projectRules)}\n`);
                     return EXIT_ERROR;
                 }
-                throw error;
+                queries = rule.queries;
+                if (options.verbose)
+                    for (const source of rule.sources)
+                        out(`${rule.id}: ${source}\n`);
+            }
+            else {
+                try {
+                    queries = [parseQuery(selector)];
+                }
+                catch (error) {
+                    if (error instanceof QueryError) {
+                        err(renderQueryError(selector, error));
+                        return EXIT_ERROR;
+                    }
+                    throw error;
+                }
             }
+            const matches = union(result.graph, queries);
+            out(renderMatches(matches, options.format === 'json' ? 'json' : 'human', result.graph.nodes.size));
+            return matches.length > 0 ? EXIT_OK : EXIT_FAILED;
         }
         default: {
             // Recording is not checking. It writes down what is wrong today so that
@@ -467,7 +585,7 @@ export async function main(io = {}) {
                 const text = formatBaseline(result.graph, result.diagnostics);
                 try {
                     const { writeFile } = await import('node:fs/promises');
-                    await writeFile(underRoot(options.root, options.recordBaseline), text, 'utf8');
+                    await writeFile(underRoot(root, anchor(here, options.recordBaseline)), text, 'utf8');
                 }
                 catch (error) {
                     err(`spec-graph: cannot write ${options.recordBaseline}: ${error.message}\n`);
@@ -477,34 +595,46 @@ export async function main(io = {}) {
                 out(`recorded ${count(result.diagnostics.length, 'finding')} as ${count(entries, 'entry', 'entries')} in ${options.recordBaseline}\n`);
                 return EXIT_OK;
             }
-            const source = options.baseline ?? file.baseline ?? null;
+            const source = options.baseline === null ? (file.baseline ?? null) : anchor(here, options.baseline);
             const ratchet = options.ratchet || file.ratchet === true;
             let reported = result;
             let note;
             if (source !== null) {
-                const held = await readBaseline(underRoot(options.root, source), source);
+                const held = await readBaseline(underRoot(root, source), source);
                 for (const problem of held.problems)
                     err(`spec-graph: ${problem}\n`);
                 const outcome = applyBaseline(result.graph, result.diagnostics, held.baseline);
                 reported = withDiagnostics(result, outcome.kept);
-                note = { source, suppressed: outcome.suppressed, stale: outcome.stale.length, ratchet };
+                note = {
+                    source,
+                    suppressed: outcome.suppressed,
+                    stale: outcome.stale.length,
+                    ratchet,
+                    entries: outcome.stale,
+                };
                 // Listed rather than counted when the run turns on them: a number is
-                // enough to know the file has slack, and not enough to strike it. Never
-                // in JSON, where the entries are already in the report and a stray line
-                // on stdout is the difference between parsing and not.
+                // enough to know the file has slack, and not enough to strike it. On
+                // stdout only for a human - the structured formats carry the same rows
+                // inside the document, where a stray line is the difference between
+                // parsing and not.
                 if (options.format === 'human' && (options.verbose || (ratchet && outcome.stale.length > 0))) {
                     for (const entry of outcome.stale) {
-                        out(`  paid: ${entry.rule} ${entry.document}${entry.subject === '' ? '' : ` "${entry.subject}"`}\n`);
+                        const subject = entry.subject === '' ? '' : ` "${entry.subject}"`;
+                        const why = entry.reason === 'gone' ? ` - ${entry.document} is not in this corpus` : '';
+                        out(`  ${entry.reason}: ${entry.rule} ${entry.document}${subject}${why}\n`);
                     }
                 }
             }
             const looseBaseline = note !== undefined && note.ratchet && note.stale > 0;
             const baselineNote = note === undefined ? {} : { baseline: note };
+            const reporterOptions = { verbose: options.verbose, max: options.max, escalated, ...baselineNote };
             out(options.format === 'sarif'
-                ? formatSarif(reported, reported.graph, { version: await readVersion(), escalated })
+                ? formatSarif(reported, reported.graph, { version: await readVersion(), escalated, projectRules })
                 : options.format === 'json'
                     ? formatJson(reported, { escalated, ...baselineNote })
-                    : `${formatReport(reported, { color, ascii, verbose: options.verbose, max: options.max, escalated, ...baselineNote })}\n`);
+                    : options.format === 'markdown'
+                        ? formatMarkdown(reported, reporterOptions)
+                        : `${formatReport(reported, { color, ascii, ...reporterOptions })}\n`);
             if (!reported.ok || looseBaseline)
                 return EXIT_FAILED;
             if (options.maxWarnings >= 0 && reported.summary.warnings > options.maxWarnings)
@@ -516,14 +646,92 @@ export async function main(io = {}) {
 /* -------------------------------------------------------------------------- */
 /* Rendering                                                                  */
 /* -------------------------------------------------------------------------- */
-function renderRules(explain) {
-    const width = Math.max(...RULE_IDS.map((id) => id.length));
+/**
+ * Where the working directory sits below the root, or `''` when it is the root.
+ *
+ * Discovery only ever walks upward, so the root is always a prefix of the
+ * directory the command was typed in, and this is a slice rather than path
+ * arithmetic.
+ */
+function below(root, from) {
+    const start = toPosix(from).replace(/[/]+$/, '');
+    return start.startsWith(`${root}/`) ? start.slice(root.length + 1) : '';
+}
+/**
+ * Re-anchors a path typed in `prefix` so it reads from the root.
+ *
+ * An absolute path is left alone: it was not relative to anywhere, so moving
+ * the root cannot change what it means.
+ */
+function anchor(prefix, value) {
+    if (prefix === '' || ABSOLUTE.test(value))
+        return value;
+    return value.startsWith('!') ? `!${prefix}/${value.slice(1)}` : `${prefix}/${value}`;
+}
+const ABSOLUTE = /^(?:[/\\]|[A-Za-z]:)/;
+/** The same, for an ignore, where a bare name is a directory at any depth. */
+function anchorPath(prefix, pattern) {
+    return isGlob(pattern) || pattern.includes('/') ? anchor(prefix, pattern) : pattern;
+}
+function knownProjectRules(projectRules) {
+    const known = projectRules.map((rule) => rule.id);
+    return known.length > 0 ? `project rules here: ${known.join(', ')}` : 'this repository defines no project rules';
+}
+/**
+ * Runs a list of selectors as one result set.
+ *
+ * A project rule is a union of its selectors, and a path that two of them both
+ * find is one path - the same dedupe `projectFindings` does, so that asking
+ * this command what a rule matches answers with the set `check` reports on.
+ */
+function union(graph, queries) {
+    if (queries.length === 1)
+        return execute(graph, queries[0]);
+    const seen = new Set();
+    const matches = [];
+    for (const spec of queries) {
+        for (const match of execute(graph, spec)) {
+            const key = match.nodes.map((node) => node.id).join('>');
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            matches.push(match);
+        }
+    }
+    return matches;
+}
+function renderRules(explain, projectRules = [], only = null, configSource = null) {
+    // A project rule is described by the selector it is, because that is what it
+    // is - its message is a template, and a template is not a description.
+    const rows = [
+        ...RULE_IDS.map((id) => ({
+            id,
+            severity: DEFAULT_SEVERITIES[id],
+            description: RULE_DESCRIPTIONS[id],
+            query: RULE_QUERIES[id],
+            decided: RULE_DECISIONS[id],
+        })),
+        ...projectRules.map((rule) => ({
+            id: rule.id,
+            severity: rule.severity,
+            description: rule.sources[0],
+            query: rule.sources.slice(1).join(' | ') || undefined,
+            decided: configSource === null ? `rules.${rule.name}` : `${configSource}: rules.${rule.name}`,
+        })),
+    ];
+    const shown = only === null ? rows : rows.filter((row) => row.id === only);
+    const width = Math.max(...shown.map((row) => row.id.length));
     const lines = [];
-    for (const id of RULE_IDS) {
-        lines.push(`${id.padEnd(width)}  ${DEFAULT_SEVERITIES[id].padEnd(5)}  ${RULE_DESCRIPTIONS[id]}`);
-        const query = RULE_QUERIES[id];
-        if (explain && query)
-            lines.push(`${' '.repeat(width)}         ${query}`);
+    for (const row of shown) {
+        lines.push(`${row.id.padEnd(width)}  ${row.severity.padEnd(5)}  ${row.description}`);
+        if (!explain)
+            continue;
+        if (row.query)
+            lines.push(`${' '.repeat(width)}         ${row.query}`);
+        // Where the decision is written down, rather than a second copy of it. A
+        // reader who has just been told their document is inconsistent is entitled
+        // to know who decided that and why, and the ADR is the answer.
+        lines.push(`${' '.repeat(width)}         ${row.decided}`);
     }
     return `${lines.join('\n')}\n`;
 }