@descent-vtt/spec-brief 0.1.0

package/dist/report.js

@@ -0,0 +1,244 @@
+/**
+ * Rendering: findings, lists, the collision matrix and plans, for a person at
+ * a terminal or for the machine reading the job.
+ *
+ * `json` is a document with a version, for orchestrators. `sarif` is SARIF
+ * 2.1.0, for code-scanning upload. `github` is workflow commands, which put a
+ * finding on the line of the pull request with no upload and no permission.
+ */
+import { summarise } from './lint.js';
+import { COLLISION_RULES, RULES } from './rules.js';
+export const FORMATS = ['pretty', 'json', 'sarif', 'github'];
+/** The version of the JSON documents this tool prints. Bumped when a field changes meaning. */
+export const JSON_SCHEMA_VERSION = 1;
+const CODES = {
+    red: [31, 39],
+    yellow: [33, 39],
+    cyan: [36, 39],
+    green: [32, 39],
+    dim: [2, 22],
+    bold: [1, 22],
+};
+export function paint(style, color, text) {
+    const code = CODES[color];
+    return style.color && code !== undefined ? `\u001b[${code[0]}m${text}\u001b[${code[1]}m` : text;
+}
+const SEVERITY_COLOR = { error: 'red', warning: 'yellow', note: 'cyan' };
+function plural(count, word) {
+    return `${count} ${word}${count === 1 ? '' : 's'}`;
+}
+export function summaryLine(findings) {
+    const s = summarise(findings);
+    return `${plural(s.errors, 'error')}, ${plural(s.warnings, 'warning')}, ${plural(s.notes, 'note')}`;
+}
+export function prettyFindings(findings, style) {
+    const out = [];
+    let file;
+    const width = Math.max(1, ...findings.map((f) => String(f.line).length));
+    for (const f of findings) {
+        if (f.file !== file) {
+            if (file !== undefined)
+                out.push('');
+            out.push(paint(style, 'bold', f.file));
+            file = f.file;
+        }
+        const severity = paint(style, SEVERITY_COLOR[f.severity], f.severity.padEnd(7));
+        out.push(`  ${String(f.line).padStart(width)}  ${severity}  ${f.message}  ${paint(style, 'dim', f.rule)}`);
+        if (f.hint !== undefined)
+            out.push(`  ${' '.repeat(width)}           ${paint(style, 'dim', f.hint)}`);
+    }
+    return out.join('\n');
+}
+export function jsonDocument(command, version, body) {
+    return `${JSON.stringify({ tool: 'spec-brief', version, schemaVersion: JSON_SCHEMA_VERSION, command, ...body }, null, 2)}\n`;
+}
+export function findingJson(f) {
+    const out = { rule: f.rule, severity: f.severity, file: f.file, line: f.line, message: f.message };
+    if (f.brief !== undefined)
+        out['brief'] = f.brief;
+    if (f.hint !== undefined)
+        out['hint'] = f.hint;
+    return out;
+}
+const SARIF_LEVEL = { error: 'error', warning: 'warning', note: 'note' };
+export function sarif(findings, version) {
+    const described = new Map([...RULES, ...COLLISION_RULES].map((r) => [r.id, r]));
+    const ids = [...new Set(findings.map((f) => f.rule))].sort();
+    const document = {
+        $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'spec-brief',
+                        version,
+                        informationUri: 'https://github.com/DescentVTT/spec-brief',
+                        rules: ids.map((id) => {
+                            const rule = described.get(id);
+                            return {
+                                id,
+                                shortDescription: { text: rule?.description ?? id },
+                                ...(rule !== undefined && rule.severity !== 'off'
+                                    ? { defaultConfiguration: { level: SARIF_LEVEL[rule.severity] } }
+                                    : {}),
+                            };
+                        }),
+                    },
+                },
+                results: findings.map((f) => ({
+                    ruleId: f.rule,
+                    level: SARIF_LEVEL[f.severity],
+                    message: { text: f.hint === undefined ? f.message : `${f.message}. ${f.hint}` },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: f.file, uriBaseId: '%SRCROOT%' },
+                                region: { startLine: f.line },
+                            },
+                        },
+                    ],
+                })),
+            },
+        ],
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+function escapeData(text) {
+    return text.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+function escapeProperty(text) {
+    return escapeData(text).replace(/:/g, '%3A').replace(/,/g, '%2C');
+}
+const GITHUB_COMMAND = { error: 'error', warning: 'warning', note: 'notice' };
+export function githubCommands(findings) {
+    return findings
+        .map((f) => {
+        const message = f.hint === undefined ? f.message : `${f.message}. ${f.hint}`;
+        const properties = `file=${escapeProperty(f.file)},line=${f.line},title=${escapeProperty(`spec-brief ${f.rule}`)}`;
+        return `::${GITHUB_COMMAND[f.severity]} ${properties}::${escapeData(message)}\n`;
+    })
+        .join('');
+}
+export function briefJson(brief, extra = {}) {
+    return {
+        id: brief.id,
+        file: brief.file,
+        title: brief.title,
+        phase: brief.phase,
+        status: brief.status,
+        type: brief.type,
+        wave: brief.wave,
+        dependsOn: brief.dependsOn,
+        affectedFiles: brief.affectedFiles,
+        protectedFiles: brief.protectedFiles,
+        tasks: { total: brief.tasks.length, checked: brief.tasks.filter((t) => t.checked).length },
+        ...extra,
+    };
+}
+/** Columns padded to their widest cell; every row has the header's length. */
+function table(header, rows) {
+    const all = [header, ...rows];
+    const widths = header.map((_, c) => Math.max(...all.map((r) => r[c].length)));
+    return all.map((r) => r
+        .map((cell, c) => (c === r.length - 1 ? cell : cell.padEnd(widths[c])))
+        .join('  ')
+        .trimEnd());
+}
+export function prettyList(rows, style) {
+    if (rows.length === 0)
+        return 'no briefs';
+    const lines = table(['ID', 'STATUS', 'WAVE', 'TASKS', 'READY', 'TITLE'], rows.map(({ brief, ready, waitingOn }) => [
+        brief.id ?? '?',
+        brief.status ?? brief.statusWord ?? '?',
+        brief.wave === null ? '-' : String(brief.wave),
+        `${brief.tasks.filter((t) => t.checked).length}/${brief.tasks.length}`,
+        brief.phase === 'archived' ? '-' : ready ? 'yes' : waitingOn.length > 0 ? `after ${waitingOn.join(', ')}` : 'no',
+        brief.title ?? brief.name,
+    ]));
+    return [paint(style, 'dim', lines[0]), ...lines.slice(1)].join('\n');
+}
+export function prettyMatrix(report, style) {
+    const out = [];
+    const label = (b) => b.id ?? b.name;
+    for (const wave of report.waves) {
+        const title = wave.wave === null ? 'all live briefs' : `wave ${wave.wave}`;
+        out.push(paint(style, 'bold', `${title} \u00b7 ${plural(wave.briefs.length, 'brief')}`));
+        const names = wave.briefs.map(label);
+        const width = Math.max(3, ...names.map((n) => n.length));
+        const hits = new Set(wave.collisions.flatMap((c) => [`${label(c.a)}\u0000${label(c.b)}`, `${label(c.b)}\u0000${label(c.a)}`]));
+        const near = new Set(wave.shared.flatMap((s) => [`${label(s.a)}\u0000${label(s.b)}`, `${label(s.b)}\u0000${label(s.a)}`]));
+        out.push(`  ${''.padEnd(width)}  ${names.map((n) => n.padStart(width)).join('  ')}`);
+        for (const row of names) {
+            const cells = names.map((col) => {
+                const key = `${row}\u0000${col}`;
+                const mark = row === col ? '\u00b7' : hits.has(key) ? paint(style, 'red', 'X') : near.has(key) ? paint(style, 'yellow', '~') : '\u00b7';
+                return `${' '.repeat(width - 1)}${mark}`;
+            });
+            out.push(`  ${row.padEnd(width)}  ${cells.join('  ')}`);
+        }
+        for (const c of wave.collisions) {
+            out.push(`  ${paint(style, 'red', 'X')} ${label(c.a)} "${c.patterns[0]}" and ${label(c.b)} "${c.patterns[1]}" both cover ${c.witness}`);
+        }
+        for (const s of wave.shared) {
+            out.push(`  ${paint(style, 'yellow', '~')} ${label(s.a)} and ${label(s.b)} both write into ${s.directory}/`);
+        }
+        for (const b of wave.unscoped) {
+            out.push(`  ${paint(style, 'cyan', '?')} ${label(b)} declares no affectedFiles and cannot be checked`);
+        }
+        out.push('');
+    }
+    if (report.unscheduled.length > 0) {
+        out.push(paint(style, 'dim', `no wave: ${report.unscheduled.map(label).join(', ')}`));
+    }
+    if (report.waves.length === 0 && report.unscheduled.length === 0)
+        out.push('no live briefs');
+    return out.join('\n').trimEnd();
+}
+export function prettyPlan(plan, dryRun, style) {
+    const out = [];
+    const verb = plan.action === 'archive' ? 'archive' : 'unarchive';
+    if (plan.done)
+        return `${plan.brief.file} is already ${plan.action === 'archive' ? 'archived' : 'live'}; nothing to do`;
+    if (plan.blocking.length > 0) {
+        out.push(paint(style, 'red', `cannot ${verb} ${plan.brief.file}:`), prettyFindings(plan.blocking, style));
+        if (plan.warnings.length > 0)
+            out.push('', prettyFindings(plan.warnings, style));
+        return out.join('\n');
+    }
+    out.push(`${dryRun ? 'would move' : 'moved'} ${plan.from} -> ${plan.to}`);
+    if (plan.linksRewritten > 0)
+        out.push(`  ${plural(plan.linksRewritten, 'relative link')} rewritten`);
+    for (const file of plan.inboundRewritten)
+        out.push(`  ${file}: links to it rewritten`);
+    for (const f of plan.inboundFrozen)
+        out.push(`  ${f.file}:${f.line}: links to the old path, and is frozen, so it was left as it is`);
+    if (plan.changes.length > 0)
+        out.push(`  the round changed ${plural(plan.changes.length, 'file')}`);
+    if (plan.warnings.length > 0)
+        out.push('', prettyFindings(plan.warnings, style));
+    if (dryRun && plan.banner.length > 0)
+        out.push('', paint(style, 'dim', 'banner:'), ...plan.banner.map((l) => `  ${l}`));
+    if (!dryRun)
+        out.push('', paint(style, 'dim', 'nothing was committed; review the change and commit it with the round'));
+    return out.join('\n');
+}
+export function planJson(plan) {
+    return {
+        action: plan.action,
+        brief: plan.brief.id,
+        from: plan.from,
+        to: plan.to,
+        done: plan.done,
+        refused: plan.blocking.length > 0,
+        blocking: plan.blocking.map(findingJson),
+        warnings: plan.warnings.map(findingJson),
+        linksRewritten: plan.linksRewritten,
+        inboundRewritten: plan.inboundRewritten,
+        inboundFrozen: plan.inboundFrozen,
+        operations: plan.ops.map((op) => ({ kind: op.kind, path: op.path })),
+        banner: plan.banner,
+        changes: plan.changes,
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Rendering: findings, lists, the collision matrix and plans, for a person at\n * a terminal or for the machine reading the job.\n *\n * `json` is a document with a version, for orchestrators. `sarif` is SARIF\n * 2.1.0, for code-scanning upload. `github` is workflow commands, which put a\n * finding on the line of the pull request with no upload and no permission.\n */\n\nimport type { Plan } from './archive.js';\nimport type { Brief } from './brief.js';\nimport type { CollisionReport } from './collisions.js';\nimport { summarise } from './lint.js';\nimport { COLLISION_RULES, RULES } from './rules.js';\nimport type { Finding, Severity } from './types.js';\n\nexport type Format = 'pretty' | 'json' | 'sarif' | 'github';\n\nexport const FORMATS: readonly Format[] = ['pretty', 'json', 'sarif', 'github'];\n\n/** The version of the JSON documents this tool prints. Bumped when a field changes meaning. */\nexport const JSON_SCHEMA_VERSION = 1;\n\nexport interface Style {\n  readonly color: boolean;\n}\n\nconst CODES: Readonly<Record<string, readonly [number, number]>> = {\n  red: [31, 39],\n  yellow: [33, 39],\n  cyan: [36, 39],\n  green: [32, 39],\n  dim: [2, 22],\n  bold: [1, 22],\n};\n\nexport function paint(style: Style, color: keyof typeof CODES, text: string): string {\n  const code = CODES[color];\n  return style.color && code !== undefined ? `\\u001b[${code[0]}m${text}\\u001b[${code[1]}m` : text;\n}\n\nconst SEVERITY_COLOR: Readonly<Record<Severity, keyof typeof CODES>> = { error: 'red', warning: 'yellow', note: 'cyan' };\n\nfunction plural(count: number, word: string): string {\n  return `${count} ${word}${count === 1 ? '' : 's'}`;\n}\n\nexport function summaryLine(findings: readonly Finding[]): string {\n  const s = summarise(findings);\n  return `${plural(s.errors, 'error')}, ${plural(s.warnings, 'warning')}, ${plural(s.notes, 'note')}`;\n}\n\nexport function prettyFindings(findings: readonly Finding[], style: Style): string {\n  const out: string[] = [];\n  let file: string | undefined;\n  const width = Math.max(1, ...findings.map((f) => String(f.line).length));\n  for (const f of findings) {\n    if (f.file !== file) {\n      if (file !== undefined) out.push('');\n      out.push(paint(style, 'bold', f.file));\n      file = f.file;\n    }\n    const severity = paint(style, SEVERITY_COLOR[f.severity], f.severity.padEnd(7));\n    out.push(`  ${String(f.line).padStart(width)}  ${severity}  ${f.message}  ${paint(style, 'dim', f.rule)}`);\n    if (f.hint !== undefined) out.push(`  ${' '.repeat(width)}           ${paint(style, 'dim', f.hint)}`);\n  }\n  return out.join('\\n');\n}\n\nexport function jsonDocument(command: string, version: string, body: Record<string, unknown>): string {\n  return `${JSON.stringify({ tool: 'spec-brief', version, schemaVersion: JSON_SCHEMA_VERSION, command, ...body }, null, 2)}\\n`;\n}\n\nexport function findingJson(f: Finding): Record<string, unknown> {\n  const out: Record<string, unknown> = { rule: f.rule, severity: f.severity, file: f.file, line: f.line, message: f.message };\n  if (f.brief !== undefined) out['brief'] = f.brief;\n  if (f.hint !== undefined) out['hint'] = f.hint;\n  return out;\n}\n\nconst SARIF_LEVEL: Readonly<Record<Severity, string>> = { error: 'error', warning: 'warning', note: 'note' };\n\nexport function sarif(findings: readonly Finding[], version: string): string {\n  const described = new Map([...RULES, ...COLLISION_RULES].map((r) => [r.id, r]));\n  const ids = [...new Set(findings.map((f) => f.rule))].sort();\n  const document = {\n    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',\n    version: '2.1.0',\n    runs: [\n      {\n        tool: {\n          driver: {\n            name: 'spec-brief',\n            version,\n            informationUri: 'https://github.com/DescentVTT/spec-brief',\n            rules: ids.map((id) => {\n              const rule = described.get(id);\n              return {\n                id,\n                shortDescription: { text: rule?.description ?? id },\n                ...(rule !== undefined && rule.severity !== 'off'\n                  ? { defaultConfiguration: { level: SARIF_LEVEL[rule.severity] } }\n                  : {}),\n              };\n            }),\n          },\n        },\n        results: findings.map((f) => ({\n          ruleId: f.rule,\n          level: SARIF_LEVEL[f.severity],\n          message: { text: f.hint === undefined ? f.message : `${f.message}. ${f.hint}` },\n          locations: [\n            {\n              physicalLocation: {\n                artifactLocation: { uri: f.file, uriBaseId: '%SRCROOT%' },\n                region: { startLine: f.line },\n              },\n            },\n          ],\n        })),\n      },\n    ],\n  };\n  return `${JSON.stringify(document, null, 2)}\\n`;\n}\n\nfunction escapeData(text: string): string {\n  return text.replace(/%/g, '%25').replace(/\\r/g, '%0D').replace(/\\n/g, '%0A');\n}\n\nfunction escapeProperty(text: string): string {\n  return escapeData(text).replace(/:/g, '%3A').replace(/,/g, '%2C');\n}\n\nconst GITHUB_COMMAND: Readonly<Record<Severity, string>> = { error: 'error', warning: 'warning', note: 'notice' };\n\nexport function githubCommands(findings: readonly Finding[]): string {\n  return findings\n    .map((f) => {\n      const message = f.hint === undefined ? f.message : `${f.message}. ${f.hint}`;\n      const properties = `file=${escapeProperty(f.file)},line=${f.line},title=${escapeProperty(`spec-brief ${f.rule}`)}`;\n      return `::${GITHUB_COMMAND[f.severity]} ${properties}::${escapeData(message)}\\n`;\n    })\n    .join('');\n}\n\nexport function briefJson(brief: Brief, extra: Record<string, unknown> = {}): Record<string, unknown> {\n  return {\n    id: brief.id,\n    file: brief.file,\n    title: brief.title,\n    phase: brief.phase,\n    status: brief.status,\n    type: brief.type,\n    wave: brief.wave,\n    dependsOn: brief.dependsOn,\n    affectedFiles: brief.affectedFiles,\n    protectedFiles: brief.protectedFiles,\n    tasks: { total: brief.tasks.length, checked: brief.tasks.filter((t) => t.checked).length },\n    ...extra,\n  };\n}\n\n/** Columns padded to their widest cell; every row has the header's length. */\nfunction table(header: readonly string[], rows: readonly (readonly string[])[]): string[] {\n  const all = [header, ...rows];\n  const widths = header.map((_, c) => Math.max(...all.map((r) => (r[c] as string).length)));\n  return all.map((r) =>\n    r\n      .map((cell, c) => (c === r.length - 1 ? cell : cell.padEnd(widths[c] as number)))\n      .join('  ')\n      .trimEnd(),\n  );\n}\n\nexport interface ListRow {\n  readonly brief: Brief;\n  readonly ready: boolean;\n  readonly waitingOn: readonly string[];\n}\n\nexport function prettyList(rows: readonly ListRow[], style: Style): string {\n  if (rows.length === 0) return 'no briefs';\n  const lines = table(\n    ['ID', 'STATUS', 'WAVE', 'TASKS', 'READY', 'TITLE'],\n    rows.map(({ brief, ready, waitingOn }) => [\n      brief.id ?? '?',\n      brief.status ?? brief.statusWord ?? '?',\n      brief.wave === null ? '-' : String(brief.wave),\n      `${brief.tasks.filter((t) => t.checked).length}/${brief.tasks.length}`,\n      brief.phase === 'archived' ? '-' : ready ? 'yes' : waitingOn.length > 0 ? `after ${waitingOn.join(', ')}` : 'no',\n      brief.title ?? brief.name,\n    ]),\n  );\n  return [paint(style, 'dim', lines[0] as string), ...lines.slice(1)].join('\\n');\n}\n\nexport function prettyMatrix(report: CollisionReport, style: Style): string {\n  const out: string[] = [];\n  const label = (b: Brief): string => b.id ?? b.name;\n  for (const wave of report.waves) {\n    const title = wave.wave === null ? 'all live briefs' : `wave ${wave.wave}`;\n    out.push(paint(style, 'bold', `${title} \\u00b7 ${plural(wave.briefs.length, 'brief')}`));\n    const names = wave.briefs.map(label);\n    const width = Math.max(3, ...names.map((n) => n.length));\n    const hits = new Set(wave.collisions.flatMap((c) => [`${label(c.a)}\\u0000${label(c.b)}`, `${label(c.b)}\\u0000${label(c.a)}`]));\n    const near = new Set(wave.shared.flatMap((s) => [`${label(s.a)}\\u0000${label(s.b)}`, `${label(s.b)}\\u0000${label(s.a)}`]));\n    out.push(`  ${''.padEnd(width)}  ${names.map((n) => n.padStart(width)).join('  ')}`);\n    for (const row of names) {\n      const cells = names.map((col) => {\n        const key = `${row}\\u0000${col}`;\n        const mark = row === col ? '\\u00b7' : hits.has(key) ? paint(style, 'red', 'X') : near.has(key) ? paint(style, 'yellow', '~') : '\\u00b7';\n        return `${' '.repeat(width - 1)}${mark}`;\n      });\n      out.push(`  ${row.padEnd(width)}  ${cells.join('  ')}`);\n    }\n    for (const c of wave.collisions) {\n      out.push(`  ${paint(style, 'red', 'X')} ${label(c.a)} \"${c.patterns[0]}\" and ${label(c.b)} \"${c.patterns[1]}\" both cover ${c.witness}`);\n    }\n    for (const s of wave.shared) {\n      out.push(`  ${paint(style, 'yellow', '~')} ${label(s.a)} and ${label(s.b)} both write into ${s.directory}/`);\n    }\n    for (const b of wave.unscoped) {\n      out.push(`  ${paint(style, 'cyan', '?')} ${label(b)} declares no affectedFiles and cannot be checked`);\n    }\n    out.push('');\n  }\n  if (report.unscheduled.length > 0) {\n    out.push(paint(style, 'dim', `no wave: ${report.unscheduled.map(label).join(', ')}`));\n  }\n  if (report.waves.length === 0 && report.unscheduled.length === 0) out.push('no live briefs');\n  return out.join('\\n').trimEnd();\n}\n\nexport function prettyPlan(plan: Plan, dryRun: boolean, style: Style): string {\n  const out: string[] = [];\n  const verb = plan.action === 'archive' ? 'archive' : 'unarchive';\n  if (plan.done) return `${plan.brief.file} is already ${plan.action === 'archive' ? 'archived' : 'live'}; nothing to do`;\n  if (plan.blocking.length > 0) {\n    out.push(paint(style, 'red', `cannot ${verb} ${plan.brief.file}:`), prettyFindings(plan.blocking, style));\n    if (plan.warnings.length > 0) out.push('', prettyFindings(plan.warnings, style));\n    return out.join('\\n');\n  }\n  out.push(`${dryRun ? 'would move' : 'moved'} ${plan.from} -> ${plan.to}`);\n  if (plan.linksRewritten > 0) out.push(`  ${plural(plan.linksRewritten, 'relative link')} rewritten`);\n  for (const file of plan.inboundRewritten) out.push(`  ${file}: links to it rewritten`);\n  for (const f of plan.inboundFrozen) out.push(`  ${f.file}:${f.line}: links to the old path, and is frozen, so it was left as it is`);\n  if (plan.changes.length > 0) out.push(`  the round changed ${plural(plan.changes.length, 'file')}`);\n  if (plan.warnings.length > 0) out.push('', prettyFindings(plan.warnings, style));\n  if (dryRun && plan.banner.length > 0) out.push('', paint(style, 'dim', 'banner:'), ...plan.banner.map((l) => `  ${l}`));\n  if (!dryRun) out.push('', paint(style, 'dim', 'nothing was committed; review the change and commit it with the round'));\n  return out.join('\\n');\n}\n\nexport function planJson(plan: Plan): Record<string, unknown> {\n  return {\n    action: plan.action,\n    brief: plan.brief.id,\n    from: plan.from,\n    to: plan.to,\n    done: plan.done,\n    refused: plan.blocking.length > 0,\n    blocking: plan.blocking.map(findingJson),\n    warnings: plan.warnings.map(findingJson),\n    linksRewritten: plan.linksRewritten,\n    inboundRewritten: plan.inboundRewritten,\n    inboundFrozen: plan.inboundFrozen,\n    operations: plan.ops.map((op) => ({ kind: op.kind, path: op.path })),\n    banner: plan.banner,\n    changes: plan.changes,\n  };\n}\n"]}

package/dist/rules.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The built-in rules. Each is a pure function of one brief and the corpus
+ * around it, and returns what it found with 1-based lines.
+ *
+ * Structure is checked on live briefs only. An archived brief is a frozen
+ * record of the tree before a round, and holding it to today's schema would
+ * ask somebody to edit what must not be edited; the rules that do reach the
+ * archive are about identity and the freeze itself.
+ */
+import { type Brief } from './brief.js';
+import type { Config, SectionRule } from './config.js';
+import { type Corpus } from './corpus.js';
+import { type Section } from './markdown.js';
+import type { Severity, SeveritySetting } from './types.js';
+export interface RuleResult {
+    /** 1-based. */
+    readonly line: number;
+    readonly message: string;
+    readonly hint?: string | undefined;
+    /** Lower than the rule's severity for this one finding, as a draft's unwritten sections are. */
+    readonly severity?: Severity | undefined;
+}
+export interface RuleContext {
+    readonly brief: Brief;
+    readonly corpus: Corpus;
+    readonly config: Config;
+    /** The files git sees, or every file without git; `null` when unknown. A rule that needs them stays quiet without them. */
+    readonly repoFiles: readonly string[] | null;
+    /** Analyses computed once per run and shared by every brief. */
+    readonly shared: SharedAnalysis;
+    /** A plugin's options from the configuration. */
+    readonly options?: unknown;
+}
+/** What a rule is called, how loud it is by default, and what it checks. */
+export interface RuleInfo {
+    readonly id: string;
+    readonly severity: SeveritySetting;
+    readonly description: string;
+}
+export interface Rule extends RuleInfo {
+    check(context: RuleContext): readonly RuleResult[] | Promise<readonly RuleResult[]>;
+}
+export interface SharedAnalysis {
+    readonly cycles: readonly (readonly Brief[])[];
+    readonly duplicates: ReadonlyMap<string, readonly Brief[]>;
+}
+export declare function analyse(corpus: Corpus): SharedAnalysis;
+/** The sections a brief must carry: the configured ones, then its type's. */
+export declare function sectionRules(brief: Brief, config: Config): SectionRule[];
+/** The headings that fill a section rule. */
+export declare function sectionsFilling(brief: Brief, rule: SectionRule): Section[];
+export declare const RULES: readonly Rule[];
+/**
+ * The rules the collision analysis reports under. They are not run per brief,
+ * so they carry no check: they exist so configuration can set their severity
+ * and reports can describe them.
+ */
+export declare const COLLISION_RULES: readonly RuleInfo[];