@descent-vtt/spec-brief 0.1.0

package/dist/collisions.js

@@ -0,0 +1,127 @@
+/**
+ * The collision matrix: which briefs scheduled to run side by side declare
+ * scopes that can name the same file.
+ *
+ * Scopes are compared as globs, not as strings. `src/auth/**` and
+ * `src/**\/session.ts` share no prefix a string comparison would see and both
+ * cover `src/auth/session.ts`; the intersection finds that, and names the file.
+ * A brief that declares no scope cannot be proven apart from anything, so it
+ * is reported as unscoped rather than silently counted as safe.
+ */
+import { lineOfField } from './brief.js';
+import { globBase, intersectGlobs, parseGlob } from './glob.js';
+import { severityOf } from './lint.js';
+import { COLLISION_RULES } from './rules.js';
+function scopes(brief, isFile) {
+    return brief.affectedFiles.flatMap((pattern) => {
+        const parsed = parseGlob(pattern, { isFile });
+        return parsed.ok ? [{ pattern, glob: parsed.glob }] : [];
+    });
+}
+function matrix(wave, briefs, isFile) {
+    const collisions = [];
+    const shared = [];
+    const scoped = briefs.map((brief) => ({ brief, scopes: scopes(brief, isFile) }));
+    for (let i = 0; i < scoped.length; i += 1) {
+        for (let j = i + 1; j < scoped.length; j += 1) {
+            const left = scoped[i];
+            const right = scoped[j];
+            const found = [];
+            for (const x of left.scopes) {
+                for (const y of right.scopes) {
+                    const witness = intersectGlobs(x.glob, y.glob);
+                    if (witness !== null)
+                        found.push({ a: left.brief, b: right.brief, patterns: [x.pattern, y.pattern], witness });
+                }
+            }
+            collisions.push(...found);
+            if (found.length > 0)
+                continue;
+            const leftDirs = new Set(left.scopes.map((s) => globBase(s.glob)).filter((d) => d !== ''));
+            const common = [...new Set(right.scopes.map((s) => globBase(s.glob)))].filter((d) => leftDirs.has(d)).sort();
+            for (const directory of common)
+                shared.push({ a: left.brief, b: right.brief, directory });
+        }
+    }
+    const unscoped = briefs.length > 1 ? scoped.filter((s) => s.scopes.length === 0).map((s) => s.brief) : [];
+    return { wave, briefs, collisions, shared, unscoped };
+}
+export function collisions(corpus, options = {}) {
+    const files = options.repoFiles === undefined || options.repoFiles === null ? null : new Set(options.repoFiles);
+    const isFile = files === null ? undefined : (path) => files.has(path);
+    if (options.all === true)
+        return { waves: [matrix(null, corpus.live, isFile)], unscheduled: [] };
+    const byWave = new Map();
+    const unscheduled = [];
+    for (const brief of corpus.live) {
+        if (brief.wave === null)
+            unscheduled.push(brief);
+        else
+            byWave.set(brief.wave, [...(byWave.get(brief.wave) ?? []), brief]);
+    }
+    const waves = [...byWave.keys()].sort((a, b) => a - b).map((wave) => matrix(wave, byWave.get(wave), isFile));
+    return { waves, unscheduled };
+}
+function label(brief) {
+    return brief.id ?? brief.name;
+}
+function where(wave) {
+    return wave === null ? 'among the live briefs' : `in wave ${wave}`;
+}
+/**
+ * The report as findings. One collision is one finding, placed on the later
+ * brief of the pair, which is usually the one still being written.
+ */
+export function collisionFindings(corpus, report) {
+    const severity = (id) => {
+        const rule = COLLISION_RULES.find((r) => r.id === id);
+        const setting = severityOf(corpus, id, rule.severity);
+        return setting === 'off' ? null : setting;
+    };
+    const findings = [];
+    const collision = severity('collision');
+    const unscoped = severity('unscoped');
+    const sharedDirectory = severity('shared-directory');
+    for (const wave of report.waves) {
+        if (collision !== null) {
+            for (const c of wave.collisions) {
+                findings.push({
+                    rule: 'collision',
+                    severity: collision,
+                    message: `"${c.patterns[1]}" overlaps ${label(c.a)}'s "${c.patterns[0]}" ${where(wave.wave)}; both cover ${c.witness}`,
+                    file: c.b.file,
+                    line: lineOfField(c.b, 'affectedFiles') + 1,
+                    brief: c.b.id ?? undefined,
+                    hint: `run them in different waves, make one depend on the other, or narrow a scope`,
+                });
+            }
+        }
+        if (sharedDirectory !== null) {
+            for (const s of wave.shared) {
+                findings.push({
+                    rule: 'shared-directory',
+                    severity: sharedDirectory,
+                    message: `writes into ${s.directory}/, as ${label(s.a)} does ${where(wave.wave)}`,
+                    file: s.b.file,
+                    line: lineOfField(s.b, 'affectedFiles') + 1,
+                    brief: s.b.id ?? undefined,
+                });
+            }
+        }
+        if (unscoped !== null) {
+            for (const brief of wave.unscoped) {
+                findings.push({
+                    rule: 'unscoped',
+                    severity: unscoped,
+                    message: `declares no affectedFiles, so it cannot be checked against the ${wave.briefs.length - 1} other brief(s) ${where(wave.wave)}`,
+                    file: brief.file,
+                    line: 1,
+                    brief: brief.id ?? undefined,
+                    hint: 'list the files or globs this round writes under "affectedFiles"',
+                });
+            }
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=collisions.js.map

package/dist/collisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collisions.js","sourceRoot":"","sources":["../src/collisions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The collision matrix: which briefs scheduled to run side by side declare\n * scopes that can name the same file.\n *\n * Scopes are compared as globs, not as strings. `src/auth/**` and\n * `src/**\\/session.ts` share no prefix a string comparison would see and both\n * cover `src/auth/session.ts`; the intersection finds that, and names the file.\n * A brief that declares no scope cannot be proven apart from anything, so it\n * is reported as unscoped rather than silently counted as safe.\n */\n\nimport type { Brief } from './brief.js';\nimport { lineOfField } from './brief.js';\nimport type { Corpus } from './corpus.js';\nimport { type Glob, globBase, intersectGlobs, parseGlob } from './glob.js';\nimport { severityOf } from './lint.js';\nimport { COLLISION_RULES, type RuleInfo } from './rules.js';\nimport type { Finding, Severity } from './types.js';\n\nexport interface Collision {\n  readonly a: Brief;\n  readonly b: Brief;\n  readonly patterns: readonly [string, string];\n  /** A path both scopes cover. */\n  readonly witness: string;\n}\n\nexport interface SharedDirectory {\n  readonly a: Brief;\n  readonly b: Brief;\n  readonly directory: string;\n}\n\nexport interface WaveMatrix {\n  /** `null` when every live brief is compared regardless of wave. */\n  readonly wave: number | null;\n  readonly briefs: readonly Brief[];\n  readonly collisions: readonly Collision[];\n  readonly shared: readonly SharedDirectory[];\n  readonly unscoped: readonly Brief[];\n}\n\nexport interface CollisionReport {\n  readonly waves: readonly WaveMatrix[];\n  /** Live briefs with no wave, which the matrix does not place. */\n  readonly unscheduled: readonly Brief[];\n}\n\nexport interface CollisionOptions {\n  /** Compare every live brief with every other, whatever its wave. */\n  readonly all?: boolean;\n  /** Tracked files, which tell a literal file path from a directory. */\n  readonly repoFiles?: readonly string[] | null;\n}\n\nfunction scopes(brief: Brief, isFile: ((path: string) => boolean) | undefined): { pattern: string; glob: Glob }[] {\n  return brief.affectedFiles.flatMap((pattern) => {\n    const parsed = parseGlob(pattern, { isFile });\n    return parsed.ok ? [{ pattern, glob: parsed.glob }] : [];\n  });\n}\n\nfunction matrix(wave: number | null, briefs: readonly Brief[], isFile: ((path: string) => boolean) | undefined): WaveMatrix {\n  const collisions: Collision[] = [];\n  const shared: SharedDirectory[] = [];\n  const scoped = briefs.map((brief) => ({ brief, scopes: scopes(brief, isFile) }));\n  for (let i = 0; i < scoped.length; i += 1) {\n    for (let j = i + 1; j < scoped.length; j += 1) {\n      const left = scoped[i] as (typeof scoped)[number];\n      const right = scoped[j] as (typeof scoped)[number];\n      const found: Collision[] = [];\n      for (const x of left.scopes) {\n        for (const y of right.scopes) {\n          const witness = intersectGlobs(x.glob, y.glob);\n          if (witness !== null) found.push({ a: left.brief, b: right.brief, patterns: [x.pattern, y.pattern], witness });\n        }\n      }\n      collisions.push(...found);\n      if (found.length > 0) continue;\n      const leftDirs = new Set(left.scopes.map((s) => globBase(s.glob)).filter((d) => d !== ''));\n      const common = [...new Set(right.scopes.map((s) => globBase(s.glob)))].filter((d) => leftDirs.has(d)).sort();\n      for (const directory of common) shared.push({ a: left.brief, b: right.brief, directory });\n    }\n  }\n  const unscoped = briefs.length > 1 ? scoped.filter((s) => s.scopes.length === 0).map((s) => s.brief) : [];\n  return { wave, briefs, collisions, shared, unscoped };\n}\n\nexport function collisions(corpus: Corpus, options: CollisionOptions = {}): CollisionReport {\n  const files = options.repoFiles === undefined || options.repoFiles === null ? null : new Set(options.repoFiles);\n  const isFile = files === null ? undefined : (path: string): boolean => files.has(path);\n  if (options.all === true) return { waves: [matrix(null, corpus.live, isFile)], unscheduled: [] };\n  const byWave = new Map<number, Brief[]>();\n  const unscheduled: Brief[] = [];\n  for (const brief of corpus.live) {\n    if (brief.wave === null) unscheduled.push(brief);\n    else byWave.set(brief.wave, [...(byWave.get(brief.wave) ?? []), brief]);\n  }\n  const waves = [...byWave.keys()].sort((a, b) => a - b).map((wave) => matrix(wave, byWave.get(wave) as Brief[], isFile));\n  return { waves, unscheduled };\n}\n\nfunction label(brief: Brief): string {\n  return brief.id ?? brief.name;\n}\n\nfunction where(wave: number | null): string {\n  return wave === null ? 'among the live briefs' : `in wave ${wave}`;\n}\n\n/**\n * The report as findings. One collision is one finding, placed on the later\n * brief of the pair, which is usually the one still being written.\n */\nexport function collisionFindings(corpus: Corpus, report: CollisionReport): Finding[] {\n  const severity = (id: string): Severity | null => {\n    const rule = COLLISION_RULES.find((r) => r.id === id) as RuleInfo;\n    const setting = severityOf(corpus, id, rule.severity);\n    return setting === 'off' ? null : setting;\n  };\n  const findings: Finding[] = [];\n  const collision = severity('collision');\n  const unscoped = severity('unscoped');\n  const sharedDirectory = severity('shared-directory');\n  for (const wave of report.waves) {\n    if (collision !== null) {\n      for (const c of wave.collisions) {\n        findings.push({\n          rule: 'collision',\n          severity: collision,\n          message: `\"${c.patterns[1]}\" overlaps ${label(c.a)}'s \"${c.patterns[0]}\" ${where(wave.wave)}; both cover ${c.witness}`,\n          file: c.b.file,\n          line: lineOfField(c.b, 'affectedFiles') + 1,\n          brief: c.b.id ?? undefined,\n          hint: `run them in different waves, make one depend on the other, or narrow a scope`,\n        });\n      }\n    }\n    if (sharedDirectory !== null) {\n      for (const s of wave.shared) {\n        findings.push({\n          rule: 'shared-directory',\n          severity: sharedDirectory,\n          message: `writes into ${s.directory}/, as ${label(s.a)} does ${where(wave.wave)}`,\n          file: s.b.file,\n          line: lineOfField(s.b, 'affectedFiles') + 1,\n          brief: s.b.id ?? undefined,\n        });\n      }\n    }\n    if (unscoped !== null) {\n      for (const brief of wave.unscoped) {\n        findings.push({\n          rule: 'unscoped',\n          severity: unscoped,\n          message: `declares no affectedFiles, so it cannot be checked against the ${wave.briefs.length - 1} other brief(s) ${where(wave.wave)}`,\n          file: brief.file,\n          line: 1,\n          brief: brief.id ?? undefined,\n          hint: 'list the files or globs this round writes under \"affectedFiles\"',\n        });\n      }\n    }\n  }\n  return findings;\n}\n"]}

package/dist/config.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Configuration: what it may say, what it says when it says nothing, and how a
+ * file becomes a `Config`.
+ *
+ * Every repository that already keeps briefs keeps them its own way - where
+ * they live, what the sections are called, which word means "done" - so the
+ * conventions are data here rather than code. The defaults describe a brief
+ * with the four parts every round needs: an intent, a negative scope, what the
+ * round is not empowered to touch, and the invariants that prove it is done.
+ *
+ * A configuration that does not load stops the run. A typo that silently
+ * falls back to defaults produces a clean-looking report about the wrong
+ * rules, which is worse than no report.
+ */
+import { type Schema } from './schema.js';
+import type { SeveritySetting } from './types.js';
+export interface SectionRule {
+    readonly name: string;
+    readonly aliases: readonly string[];
+    /** Literal text the section must contain, compared exactly. */
+    readonly mustContain: readonly string[];
+    /** The section must hold at least one task item. */
+    readonly checklist: boolean;
+    readonly optional: boolean;
+}
+export interface PluginReference {
+    readonly module: string;
+    readonly options: unknown;
+}
+export interface Config {
+    /** Directory of live briefs, relative to the root. */
+    readonly briefs: string;
+    /** Directory of archived briefs, relative to the root. */
+    readonly archive: string;
+    /** Glob a file name must match to be a brief. */
+    readonly files: string;
+    /** File-name globs that are never briefs, such as an index. */
+    readonly exclude: readonly string[];
+    /** A template for `new`, relative to the root; `null` builds one from `sections`. */
+    readonly template: string | null;
+    readonly id: {
+        readonly source: 'filename' | 'frontmatter';
+        readonly separator: string;
+        readonly digits: number;
+    };
+    readonly status: {
+        readonly field: string | null;
+        readonly draft: string | null;
+        readonly active: string;
+        readonly archived: string;
+    };
+    readonly sections: readonly SectionRule[];
+    readonly sectionOrder: boolean;
+    readonly types: Readonly<Record<string, readonly SectionRule[]>>;
+    readonly placeholders: readonly string[];
+    readonly fields: readonly string[];
+    readonly archiving: {
+        readonly tasks: 'all' | readonly string[];
+        readonly dispositions: readonly string[];
+        readonly banner: readonly string[];
+        readonly rewriteLinks: boolean;
+        readonly freeze: boolean;
+        readonly base: string | null;
+    };
+    readonly rules: Readonly<Record<string, SeveritySetting>>;
+    readonly plugins: readonly PluginReference[];
+}
+export declare const CONFIG_FILES: readonly string[];
+/** The holes a banner line may use. */
+export declare const BANNER_PLACEHOLDERS: readonly string[];
+export declare const SCHEMA_URL = "https://raw.githubusercontent.com/DescentVTT/spec-brief/main/schema.json";
+export declare const CONFIG_SCHEMA: Schema;
+export declare const DEFAULT_CONFIG: Config;
+export declare class ConfigError extends Error {
+    readonly problems: readonly string[];
+    constructor(file: string, problems: readonly string[]);
+}
+/**
+ * Builds a configuration from parsed JSON. Objects merge one level deep over
+ * the defaults; lists and `types` replace them, because a repository that
+ * names its own sections means those sections and not the defaults as well.
+ */
+export declare function resolveConfig(raw: unknown, file?: string): Config;
+/** Parses the text of a configuration file. */
+export declare function parseConfig(text: string, file: string): Config;
+/**
+ * The configuration file for a directory: the nearest one at or above it.
+ * `exists` is injected so discovery needs no filesystem of its own.
+ */
+export declare function locateConfig(start: string, exists: (path: string) => Promise<boolean>): Promise<string | undefined>;
+/** The JSON Schema published as `schema.json`. */
+export declare function configJsonSchema(): Record<string, unknown>;
+/** The configuration `init` writes: every default spelled out, so it can be edited rather than looked up. */
+export declare function initialConfig(briefs: string, archive: string): Record<string, unknown>;

package/dist/config.js

@@ -0,0 +1,353 @@
+/**
+ * Configuration: what it may say, what it says when it says nothing, and how a
+ * file becomes a `Config`.
+ *
+ * Every repository that already keeps briefs keeps them its own way - where
+ * they live, what the sections are called, which word means "done" - so the
+ * conventions are data here rather than code. The defaults describe a brief
+ * with the four parts every round needs: an intent, a negative scope, what the
+ * round is not empowered to touch, and the invariants that prove it is done.
+ *
+ * A configuration that does not load stops the run. A typo that silently
+ * falls back to defaults produces a clean-looking report about the wrong
+ * rules, which is worse than no report.
+ */
+import { dirname, join } from 'node:path';
+import { parseGlob } from './glob.js';
+import { normalisePath } from './links.js';
+import { toJsonSchema, validate } from './schema.js';
+import { templateHoles } from './text.js';
+export const CONFIG_FILES = ['.spec-brief.json', 'spec-brief.json'];
+/** The holes a banner line may use. */
+export const BANNER_PLACEHOLDERS = [
+    'date',
+    'summary',
+    'pr',
+    'commit',
+    'diffstat',
+    'links',
+    'id',
+    'title',
+    'author',
+];
+export const SCHEMA_URL = 'https://raw.githubusercontent.com/DescentVTT/spec-brief/main/schema.json';
+const SEVERITY = { type: 'string', enum: ['off', 'note', 'warning', 'error'] };
+const STRINGS = { type: 'array', items: { type: 'string', minLength: 1 } };
+const SECTION = {
+    type: 'anyOf',
+    description: 'A section name, or a section with aliases and content rules.',
+    options: [
+        { type: 'string', minLength: 1 },
+        {
+            type: 'object',
+            required: ['name'],
+            properties: {
+                name: { type: 'string', minLength: 1, description: 'The heading text, compared without case or punctuation.' },
+                aliases: { ...STRINGS, description: 'Other headings that fill this section.' },
+                mustContain: { ...STRINGS, description: 'Literal text the section must contain.' },
+                checklist: { type: 'boolean', description: 'The section must hold at least one "- [ ]" task item.' },
+                optional: { type: 'boolean', description: 'Checked when present, not required.' },
+            },
+        },
+    ],
+};
+export const CONFIG_SCHEMA = {
+    type: 'object',
+    properties: {
+        $schema: { type: 'string' },
+        briefs: { type: 'string', minLength: 1, description: 'Directory of live briefs, relative to this file.' },
+        archive: { type: 'string', minLength: 1, description: 'Directory of archived briefs, relative to this file.' },
+        files: { type: 'string', minLength: 1, description: 'Glob a file name must match to be a brief.' },
+        exclude: { ...STRINGS, description: 'File-name globs that are never briefs.' },
+        template: { type: 'string', nullable: true, description: 'Template file for "new"; null builds one from the sections.' },
+        id: {
+            type: 'object',
+            properties: {
+                source: { type: 'string', enum: ['filename', 'frontmatter'], description: 'Where a brief id comes from.' },
+                separator: { type: 'string', minLength: 1, description: 'Separates the id from the slug in a file name.' },
+                digits: { type: 'integer', minimum: 1, maximum: 12, description: 'Width of an allocated numeric id.' },
+            },
+        },
+        status: {
+            type: 'object',
+            properties: {
+                field: { type: 'string', nullable: true, description: 'Front-matter key holding the status; null uses location only.' },
+                draft: { type: 'string', nullable: true, description: 'The word for a brief still being written, or null.' },
+                active: { type: 'string', minLength: 1, description: 'The word for a live brief.' },
+                archived: { type: 'string', minLength: 1, description: 'The word for an archived brief.' },
+            },
+        },
+        sections: { type: 'array', items: SECTION, description: 'Sections every live brief carries.' },
+        sectionOrder: { type: 'boolean', description: 'Sections must appear in the order listed.' },
+        types: {
+            type: 'map',
+            description: 'Brief types, each with the sections it adds.',
+            values: { type: 'object', properties: { sections: { type: 'array', items: SECTION } } },
+        },
+        placeholders: { ...STRINGS, description: 'Words that mark a section as unwritten.' },
+        fields: { ...STRINGS, description: 'Front-matter keys this repository uses beyond the built-in ones.' },
+        archiving: {
+            type: 'object',
+            properties: {
+                tasks: {
+                    type: 'anyOf',
+                    description: '"all", or the sections whose task items must be closed before archiving.',
+                    options: [{ type: 'string', enum: ['all'] }, STRINGS],
+                },
+                dispositions: { ...STRINGS, description: 'Text under an open box that closes it without a tick.' },
+                banner: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Lines of the frozen banner; a line with an empty {placeholder} is left out, and an empty line separates paragraphs.',
+                },
+                rewriteLinks: { type: 'boolean', description: 'Rewrite relative links so they resolve from the new directory.' },
+                freeze: { type: 'boolean', description: 'Record a content hash so later edits are caught.' },
+                base: { type: 'string', nullable: true, description: 'Branch the diff is measured from, such as "main".' },
+            },
+        },
+        rules: { type: 'map', values: SEVERITY, description: 'Severity per rule id.' },
+        plugins: {
+            type: 'array',
+            description: 'Modules that contribute rules.',
+            items: {
+                type: 'anyOf',
+                options: [
+                    { type: 'string', minLength: 1 },
+                    {
+                        type: 'object',
+                        required: ['module'],
+                        properties: { module: { type: 'string', minLength: 1 }, options: { type: 'any' } },
+                    },
+                ],
+            },
+        },
+    },
+};
+function section(name, extra = {}) {
+    return { name, aliases: [], mustContain: [], checklist: false, optional: false, ...extra };
+}
+export const DEFAULT_CONFIG = {
+    briefs: 'briefs',
+    archive: 'briefs/archive',
+    files: '[0-9]*.md',
+    exclude: [],
+    template: null,
+    id: { source: 'filename', separator: '_', digits: 3 },
+    status: { field: 'status', draft: 'draft', active: 'active', archived: 'archived' },
+    sections: [
+        section('Intent', { aliases: ["Commander's Intent", 'Mission', 'Objective'] }),
+        section('Negative Scope', {
+            aliases: ['Out of Scope', 'Non-Goals', 'Not in Scope', 'What this round is NOT', 'What this brief does NOT do'],
+        }),
+        section('Not Empowered', { aliases: ['Non-Empowerment', 'Non-Empowerment List'], optional: true }),
+        section('Invariants', { aliases: ['Invariant Checklist', 'Definition of Done'], checklist: true }),
+    ],
+    sectionOrder: false,
+    types: {
+        feature: [section('Acceptance Criteria', { checklist: true })],
+        defect: [section('The Defect, Measured', { aliases: ['Reproduction'] })],
+        refactor: [],
+        chore: [],
+    },
+    placeholders: ['TBD', 'TBA', 'TODO', 'FIXME', 'XXX', '???', '...', '\u2026'],
+    fields: [],
+    archiving: {
+        tasks: 'all',
+        dispositions: ['**Delegated', '**Accepted debt', '**Rejected'],
+        banner: [
+            '**Archived {date}.**',
+            '{summary}',
+            'Merged in pull request {pr}.',
+            'Recorded at commit `{commit}`: {diffstat}.',
+            '{links}',
+            'The body below describes the tree before execution and is not maintained.',
+        ],
+        rewriteLinks: true,
+        freeze: true,
+        base: null,
+    },
+    rules: {},
+    plugins: [],
+};
+function sectionFrom(raw) {
+    if (typeof raw === 'string')
+        return section(raw);
+    const r = raw;
+    return section(r['name'], {
+        aliases: r['aliases'] ?? [],
+        mustContain: r['mustContain'] ?? [],
+        checklist: r['checklist'] ?? false,
+        optional: r['optional'] ?? false,
+    });
+}
+function pluginFrom(raw) {
+    if (typeof raw === 'string')
+        return { module: raw, options: undefined };
+    const r = raw;
+    return { module: r['module'], options: r['options'] };
+}
+export class ConfigError extends Error {
+    problems;
+    constructor(file, problems) {
+        super(`${file}: ${problems.join('; ')}`);
+        this.name = 'ConfigError';
+        this.problems = problems;
+    }
+}
+/**
+ * Builds a configuration from parsed JSON. Objects merge one level deep over
+ * the defaults; lists and `types` replace them, because a repository that
+ * names its own sections means those sections and not the defaults as well.
+ */
+export function resolveConfig(raw, file = 'configuration') {
+    const problems = validate(CONFIG_SCHEMA, raw);
+    if (problems.length > 0)
+        throw new ConfigError(file, problems);
+    const r = raw;
+    const d = DEFAULT_CONFIG;
+    const merged = (key, base) => ({ ...base, ...(r[key] ?? {}) });
+    const archiving = merged('archiving', d.archiving);
+    const config = {
+        briefs: r['briefs'] ?? d.briefs,
+        archive: r['archive'] ?? (r['briefs'] === undefined ? d.archive : `${r['briefs']}/archive`),
+        files: r['files'] ?? d.files,
+        exclude: r['exclude'] ?? d.exclude,
+        template: r['template'] === undefined ? d.template : r['template'],
+        id: merged('id', d.id),
+        status: merged('status', d.status),
+        sections: r['sections'] === undefined ? d.sections : r['sections'].map(sectionFrom),
+        sectionOrder: r['sectionOrder'] ?? d.sectionOrder,
+        types: r['types'] === undefined
+            ? d.types
+            : Object.fromEntries(Object.entries(r['types']).map(([name, type]) => [
+                name,
+                (type['sections'] ?? []).map(sectionFrom),
+            ])),
+        placeholders: r['placeholders'] ?? d.placeholders,
+        fields: r['fields'] ?? d.fields,
+        archiving,
+        rules: { ...d.rules, ...(r['rules'] ?? {}) },
+        plugins: (r['plugins'] ?? []).map(pluginFrom),
+    };
+    const semantic = checkConfig(config);
+    if (semantic.length > 0)
+        throw new ConfigError(file, semantic);
+    return config;
+}
+/** What the schema cannot say: relationships between values. */
+function checkConfig(config) {
+    const problems = [];
+    const inside = (key, path) => {
+        try {
+            return normalisePath(path);
+        }
+        catch {
+            problems.push(`"${key}" must be a directory inside the repository, not "${path}"`);
+            return null;
+        }
+    };
+    const briefs = inside('briefs', config.briefs);
+    const archive = inside('archive', config.archive);
+    if (briefs !== null && briefs === archive)
+        problems.push('"briefs" and "archive" must be different directories');
+    const words = [config.status.draft, config.status.active, config.status.archived].filter((w) => w !== null);
+    if (new Set(words.map((w) => w.toLowerCase())).size !== words.length) {
+        problems.push('the status words for draft, active and archived must differ');
+    }
+    // A pattern that does not parse would match nothing, and a run over no briefs reads as clean.
+    for (const [key, pattern] of [['files', config.files], ...config.exclude.map((e) => ['exclude', e])]) {
+        const parsed = parseGlob(pattern);
+        if (!parsed.ok)
+            problems.push(`"${key}" pattern "${pattern}": ${parsed.error}`);
+    }
+    // An unknown hole is never filled, and a line with an unfilled hole is left
+    // out: a misspelt placeholder would silently drop its whole line.
+    for (const line of config.archiving.banner) {
+        for (const hole of templateHoles(line)) {
+            if (!BANNER_PLACEHOLDERS.includes(hole)) {
+                problems.push(`"archiving.banner" uses {${hole}}; the placeholders are ${BANNER_PLACEHOLDERS.map((p) => `{${p}}`).join(', ')}`);
+            }
+        }
+    }
+    return problems;
+}
+/** Parses the text of a configuration file. */
+export function parseConfig(text, file) {
+    let raw;
+    try {
+        raw = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+    }
+    catch (error) {
+        throw new ConfigError(file, [`is not valid JSON (${error.message})`]);
+    }
+    return resolveConfig(raw, file);
+}
+/**
+ * The configuration file for a directory: the nearest one at or above it.
+ * `exists` is injected so discovery needs no filesystem of its own.
+ */
+export async function locateConfig(start, exists) {
+    let directory = start;
+    // Bounded by the depth of the path: each pass moves one directory up.
+    for (let depth = 0; depth < 256; depth += 1) {
+        const found = [];
+        for (const name of CONFIG_FILES) {
+            const candidate = join(directory, name);
+            if (await exists(candidate))
+                found.push(candidate);
+        }
+        if (found.length > 1) {
+            throw new ConfigError(directory, [`holds both ${CONFIG_FILES.join(' and ')}; keep one`]);
+        }
+        if (found[0] !== undefined)
+            return found[0];
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+    /* v8 ignore next -- no path is 256 directories deep; the bound exists so the loop ends by construction. */
+    return undefined;
+}
+/** The JSON Schema published as `schema.json`. */
+export function configJsonSchema() {
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        $id: SCHEMA_URL,
+        title: 'spec-brief configuration',
+        ...toJsonSchema(CONFIG_SCHEMA),
+    };
+}
+/** The configuration `init` writes: every default spelled out, so it can be edited rather than looked up. */
+export function initialConfig(briefs, archive) {
+    const d = DEFAULT_CONFIG;
+    const sectionJson = (s) => {
+        const out = { name: s.name };
+        if (s.aliases.length > 0)
+            out['aliases'] = s.aliases;
+        if (s.mustContain.length > 0)
+            out['mustContain'] = s.mustContain;
+        if (s.checklist)
+            out['checklist'] = true;
+        if (s.optional)
+            out['optional'] = true;
+        return Object.keys(out).length === 1 ? s.name : out;
+    };
+    return {
+        $schema: SCHEMA_URL,
+        briefs,
+        archive,
+        files: d.files,
+        id: d.id,
+        status: d.status,
+        sections: d.sections.map(sectionJson),
+        types: Object.fromEntries(Object.entries(d.types).map(([k, v]) => [k, { sections: v.map(sectionJson) }])),
+        archiving: {
+            tasks: d.archiving.tasks,
+            dispositions: d.archiving.dispositions,
+            banner: d.archiving.banner,
+            base: d.archiving.base,
+        },
+    };
+}
+//# sourceMappingURL=config.js.map