@descent-vtt/spec-brief 0.1.0 → 0.2.1

package/dist/collisions.js

@@ -4,63 +4,70 @@
  *
  * 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.
+ * cover `src/auth/session.ts`; the witness search finds that, and names the
+ * file. What a brief protects it will not write, so a file either brief of a
+ * pair protects is no collision. A brief that declares no scope cannot be
+ * proven apart from anything, so it is reported as unscoped rather than
+ * silently counted as safe, and a pair the search could not decide is reported
+ * as undecided rather than as either.
+ *
+ * Two briefs that collide are one defect however many of their patterns
+ * meet: they are fixed together, by a wave, a dependency or a narrower scope.
+ * So a pair is one collision, carrying every pair of patterns that meets.
  */
 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) {
+import { waitingOnDeferred } from './corpus.js';
+import { globBases, readingIn, WITNESS_BUDGET } from './glob.js';
+import { configuredSeverity } from './lint.js';
+import { meet, scopeOf } from './scope.js';
+import { inWords } from './text.js';
+function matrix(wave, briefs, scopes, budget) {
     const collisions = [];
+    const undecided = [];
     const shared = [];
-    const scoped = briefs.map((brief) => ({ brief, scopes: scopes(brief, isFile) }));
+    const scoped = briefs.map((brief) => scopes.get(brief));
     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 });
-                }
+            const meeting = meet(left, right, budget);
+            if (meeting.overlaps.length > 0) {
+                collisions.push({ a: left.brief, b: right.brief, overlaps: meeting.overlaps });
+                continue;
             }
-            collisions.push(...found);
-            if (found.length > 0)
+            if (meeting.undecided.length > 0) {
+                undecided.push({ a: left.brief, b: right.brief, patterns: meeting.undecided });
                 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 leftDirs = new Set(left.affected.flatMap((s) => globBases(s.glob)).filter((d) => d !== ''));
+            const directories = [...new Set(right.affected.flatMap((s) => globBases(s.glob)))].filter((d) => leftDirs.has(d)).sort();
+            if (directories.length > 0)
+                shared.push({ a: left.brief, b: right.brief, directories });
         }
     }
-    const unscoped = briefs.length > 1 ? scoped.filter((s) => s.scopes.length === 0).map((s) => s.brief) : [];
-    return { wave, briefs, collisions, shared, unscoped };
+    const unscoped = briefs.length > 1 ? scoped.filter((s) => s.affected.length === 0).map((s) => s.brief) : [];
+    return { wave, briefs, collisions, undecided, 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);
+    const reading = readingIn(options.repoFiles ?? null);
+    const budget = options.budget ?? WITNESS_BUDGET;
+    const deferred = corpus.live.filter((b) => b.status === 'deferred');
+    const waiting = waitingOnDeferred(corpus);
+    const held = new Set(waiting.map((w) => w.brief));
+    const live = corpus.live.filter((b) => b.status !== 'deferred' && !held.has(b));
+    const scopes = new Map(live.map((brief) => [brief, scopeOf(brief, reading)]));
     if (options.all === true)
-        return { waves: [matrix(null, corpus.live, isFile)], unscheduled: [] };
+        return { waves: [matrix(null, live, scopes, budget)], unscheduled: [], deferred, waiting };
     const byWave = new Map();
     const unscheduled = [];
-    for (const brief of corpus.live) {
+    for (const brief of 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 };
+    const waves = [...byWave.keys()].sort((a, b) => a - b).map((wave) => matrix(wave, byWave.get(wave), scopes, budget));
+    return { waves, unscheduled, deferred, waiting };
 }
 function label(brief) {
     return brief.id ?? brief.name;
@@ -68,27 +75,44 @@ function label(brief) {
 function where(wave) {
     return wave === null ? 'among the live briefs' : `in wave ${wave}`;
 }
+function collisionMessage(c, wave) {
+    if (c.overlaps.length === 1) {
+        const only = c.overlaps[0];
+        return `"${only.patterns[1]}" overlaps ${label(c.a)}'s "${only.patterns[0]}" ${where(wave)}; both cover ${only.witness}`;
+    }
+    const each = c.overlaps.map((o) => `"${o.patterns[1]}" and ${label(c.a)}'s "${o.patterns[0]}" both cover ${o.witness}`);
+    return `overlaps ${label(c.a)} ${where(wave)} through ${c.overlaps.length} pairs of patterns: ${each.join('; ')}`;
+}
+/** A pair whose collision the search could not decide, as one finding on the later brief. */
+export function undecidedFinding(severity, a, b, patterns, wave) {
+    const pairs = patterns.map(([x, y]) => `"${y}" and ${label(a)}'s "${x}"`);
+    return {
+        rule: 'collision-undecided',
+        severity,
+        message: `whether it can write a file ${label(a)} writes ${where(wave)} is undecided: the search met its budget for ${inWords(pairs)}`,
+        file: b.file,
+        line: lineOfField(b, 'affectedFiles') + 1,
+        brief: b.id ?? undefined,
+        hint: 'narrow one of the patterns, or run the two in different waves',
+    };
+}
 /**
- * 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.
+ * The report as findings. One pair of briefs 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');
+    const collision = configuredSeverity(corpus, 'collision');
+    const undecided = configuredSeverity(corpus, 'collision-undecided');
+    const unscoped = configuredSeverity(corpus, 'unscoped');
+    const sharedDirectory = configuredSeverity(corpus, '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}`,
+                    message: collisionMessage(c, wave.wave),
                     file: c.b.file,
                     line: lineOfField(c.b, 'affectedFiles') + 1,
                     brief: c.b.id ?? undefined,
@@ -96,32 +120,40 @@ export function collisionFindings(corpus, report) {
                 });
             }
         }
+        if (undecided !== null) {
+            for (const u of wave.undecided)
+                findings.push(undecidedFinding(undecided, u.a, u.b, u.patterns, wave.wave));
+        }
         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)}`,
+                    message: `writes into ${inWords(s.directories.map((d) => `${d}/`))}, as ${label(s.a)} does ${where(wave.wave)}`,
                     file: s.b.file,
                     line: lineOfField(s.b, 'affectedFiles') + 1,
                     brief: s.b.id ?? undefined,
+                    hint: 'check that the two do not depend on one decision in that directory; if they do, order them',
                 });
             }
         }
         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"',
-                });
-            }
+            for (const brief of wave.unscoped)
+                findings.push(unscopedFinding(unscoped, brief, `the ${wave.briefs.length - 1} other brief(s) ${where(wave.wave)}`));
         }
     }
     return findings;
 }
+/** A brief with no scope, which nothing can be proved apart from. */
+export function unscopedFinding(severity, brief, others) {
+    return {
+        rule: 'unscoped',
+        severity,
+        message: `declares no affectedFiles, so it cannot be checked against ${others}`,
+        file: brief.file,
+        line: 1,
+        brief: brief.id ?? undefined,
+        hint: 'list the files or globs this round writes under "affectedFiles"',
+    };
+}
 //# sourceMappingURL=collisions.js.map

package/dist/collisions.js.map

@@ -1 +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"]}
+{"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 witness search finds that, and names the\n * file. What a brief protects it will not write, so a file either brief of a\n * pair protects is no collision. A brief that declares no scope cannot be\n * proven apart from anything, so it is reported as unscoped rather than\n * silently counted as safe, and a pair the search could not decide is reported\n * as undecided rather than as either.\n *\n * Two briefs that collide are one defect however many of their patterns\n * meet: they are fixed together, by a wave, a dependency or a narrower scope.\n * So a pair is one collision, carrying every pair of patterns that meets.\n */\n\nimport type { Brief } from './brief.js';\nimport { lineOfField } from './brief.js';\nimport { type Corpus, waitingOnDeferred, type Waiting } from './corpus.js';\nimport { globBases, readingIn, WITNESS_BUDGET } from './glob.js';\nimport { configuredSeverity } from './lint.js';\nimport { meet, type Overlap, type Scope, scopeOf } from './scope.js';\nimport { inWords } from './text.js';\nimport type { Finding, Severity } from './types.js';\n\nexport type { Overlap } from './scope.js';\n\nexport interface Collision {\n  readonly a: Brief;\n  readonly b: Brief;\n  /** Every pair of patterns that meets, `a`'s first; never empty. */\n  readonly overlaps: readonly Overlap[];\n}\n\n/** Two briefs no pair of whose patterns is known to meet, and some pair the search could not decide. */\nexport interface UndecidedPair {\n  readonly a: Brief;\n  readonly b: Brief;\n  /** The pairs of patterns, `a`'s first; never empty. */\n  readonly patterns: readonly (readonly [string, string])[];\n}\n\nexport interface SharedDirectory {\n  readonly a: Brief;\n  readonly b: Brief;\n  /** The directories both write into, sorted; never empty. */\n  readonly directories: readonly 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 undecided: readonly UndecidedPair[];\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  /** Deferred briefs, which wait for their trigger and run in no wave. */\n  readonly deferred: readonly Brief[];\n  /**\n   * Briefs that depend on a deferred brief, or on one that waits on one. They\n   * cannot start before the deferred work, so they run in no wave either, and\n   * are compared with nothing - as `schedule` places them nowhere. By id.\n   */\n  readonly waiting: readonly Waiting[];\n}\n\nexport interface CollisionOptions {\n  /** Compare every live brief with every other, whatever its wave. */\n  readonly all?: boolean;\n  /** The files the tree holds, which say whether a literal path is a file or a directory. */\n  readonly repoFiles?: readonly string[] | null;\n  /** How many states one witness search may visit before it answers `undecided`. */\n  readonly budget?: number;\n}\n\nfunction matrix(wave: number | null, briefs: readonly Brief[], scopes: ReadonlyMap<Brief, Scope>, budget: number): WaveMatrix {\n  const collisions: Collision[] = [];\n  const undecided: UndecidedPair[] = [];\n  const shared: SharedDirectory[] = [];\n  const scoped = briefs.map((brief) => scopes.get(brief) as Scope);\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 Scope;\n      const right = scoped[j] as Scope;\n      const meeting = meet(left, right, budget);\n      if (meeting.overlaps.length > 0) {\n        collisions.push({ a: left.brief, b: right.brief, overlaps: meeting.overlaps });\n        continue;\n      }\n      if (meeting.undecided.length > 0) {\n        undecided.push({ a: left.brief, b: right.brief, patterns: meeting.undecided });\n        continue;\n      }\n      const leftDirs = new Set(left.affected.flatMap((s) => globBases(s.glob)).filter((d) => d !== ''));\n      const directories = [...new Set(right.affected.flatMap((s) => globBases(s.glob)))].filter((d) => leftDirs.has(d)).sort();\n      if (directories.length > 0) shared.push({ a: left.brief, b: right.brief, directories });\n    }\n  }\n  const unscoped = briefs.length > 1 ? scoped.filter((s) => s.affected.length === 0).map((s) => s.brief) : [];\n  return { wave, briefs, collisions, undecided, shared, unscoped };\n}\n\nexport function collisions(corpus: Corpus, options: CollisionOptions = {}): CollisionReport {\n  const reading = readingIn(options.repoFiles ?? null);\n  const budget = options.budget ?? WITNESS_BUDGET;\n  const deferred = corpus.live.filter((b) => b.status === 'deferred');\n  const waiting = waitingOnDeferred(corpus);\n  const held = new Set(waiting.map((w) => w.brief));\n  const live = corpus.live.filter((b) => b.status !== 'deferred' && !held.has(b));\n  const scopes = new Map(live.map((brief) => [brief, scopeOf(brief, reading)]));\n  if (options.all === true) return { waves: [matrix(null, live, scopes, budget)], unscheduled: [], deferred, waiting };\n  const byWave = new Map<number, Brief[]>();\n  const unscheduled: Brief[] = [];\n  for (const brief of 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[], scopes, budget));\n  return { waves, unscheduled, deferred, waiting };\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\nfunction collisionMessage(c: Collision, wave: number | null): string {\n  if (c.overlaps.length === 1) {\n    const only = c.overlaps[0] as Overlap;\n    return `\"${only.patterns[1]}\" overlaps ${label(c.a)}'s \"${only.patterns[0]}\" ${where(wave)}; both cover ${only.witness}`;\n  }\n  const each = c.overlaps.map((o) => `\"${o.patterns[1]}\" and ${label(c.a)}'s \"${o.patterns[0]}\" both cover ${o.witness}`);\n  return `overlaps ${label(c.a)} ${where(wave)} through ${c.overlaps.length} pairs of patterns: ${each.join('; ')}`;\n}\n\n/** A pair whose collision the search could not decide, as one finding on the later brief. */\nexport function undecidedFinding(severity: Severity, a: Brief, b: Brief, patterns: readonly (readonly [string, string])[], wave: number | null): Finding {\n  const pairs = patterns.map(([x, y]) => `\"${y}\" and ${label(a)}'s \"${x}\"`);\n  return {\n    rule: 'collision-undecided',\n    severity,\n    message: `whether it can write a file ${label(a)} writes ${where(wave)} is undecided: the search met its budget for ${inWords(pairs)}`,\n    file: b.file,\n    line: lineOfField(b, 'affectedFiles') + 1,\n    brief: b.id ?? undefined,\n    hint: 'narrow one of the patterns, or run the two in different waves',\n  };\n}\n\n/**\n * The report as findings. One pair of briefs is one finding, placed on the\n * later brief of the pair, which is usually the one still being written.\n */\nexport function collisionFindings(corpus: Corpus, report: CollisionReport): Finding[] {\n  const findings: Finding[] = [];\n  const collision = configuredSeverity(corpus, 'collision');\n  const undecided = configuredSeverity(corpus, 'collision-undecided');\n  const unscoped = configuredSeverity(corpus, 'unscoped');\n  const sharedDirectory = configuredSeverity(corpus, '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: collisionMessage(c, wave.wave),\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 (undecided !== null) {\n      for (const u of wave.undecided) findings.push(undecidedFinding(undecided, u.a, u.b, u.patterns, wave.wave));\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 ${inWords(s.directories.map((d) => `${d}/`))}, 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          hint: 'check that the two do not depend on one decision in that directory; if they do, order them',\n        });\n      }\n    }\n    if (unscoped !== null) {\n      for (const brief of wave.unscoped) findings.push(unscopedFinding(unscoped, brief, `the ${wave.briefs.length - 1} other brief(s) ${where(wave.wave)}`));\n    }\n  }\n  return findings;\n}\n\n/** A brief with no scope, which nothing can be proved apart from. */\nexport function unscopedFinding(severity: Severity, brief: Brief, others: string): Finding {\n  return {\n    rule: 'unscoped',\n    severity,\n    message: `declares no affectedFiles, so it cannot be checked against ${others}`,\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"]}

package/dist/config.d.ts

@@ -22,6 +22,13 @@ export interface SectionRule {
     /** The section must hold at least one task item. */
     readonly checklist: boolean;
     readonly optional: boolean;
+    /**
+     * What the section must answer. A new brief carries it as a comment under
+     * the heading, a finding that the section is missing or unwritten carries it
+     * as its hint, and `list` and `lint` report it, so a tool that helps write a
+     * brief can ask for each section without knowing its name in advance.
+     */
+    readonly hint?: string | undefined;
 }
 export interface PluginReference {
     readonly module: string;
@@ -47,6 +54,8 @@ export interface Config {
         readonly field: string | null;
         readonly draft: string | null;
         readonly active: string;
+        /** The word for work put off until an event its `trigger` names; `null` when a repository has none. */
+        readonly deferred: string | null;
         readonly archived: string;
     };
     readonly sections: readonly SectionRule[];
@@ -69,6 +78,13 @@ 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";
+/**
+ * The `$schema` `init` writes, the path the README recommends: the schema of
+ * the version installed, which is the one that loads the file. `SCHEMA_URL`
+ * follows main, and would flag a key the installed version accepts, or pass
+ * one it refuses, as soon as the two differ.
+ */
+export declare const SCHEMA_PATH = "./node_modules/@descent-vtt/spec-brief/schema.json";
 export declare const CONFIG_SCHEMA: Schema;
 export declare const DEFAULT_CONFIG: Config;
 export declare class ConfigError extends Error {
@@ -81,6 +97,8 @@ export declare class ConfigError extends Error {
  * names its own sections means those sections and not the defaults as well.
  */
 export declare function resolveConfig(raw: unknown, file?: string): Config;
+/** The status words a repository uses, in lifecycle order. */
+export declare function statusWords(config: Config): string[];
 /** Parses the text of a configuration file. */
 export declare function parseConfig(text: string, file: string): Config;
 /**

package/dist/config.js

@@ -16,7 +16,7 @@ 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';
+import { inWords, 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 = [
@@ -31,6 +31,13 @@ export const BANNER_PLACEHOLDERS = [
     'author',
 ];
 export const SCHEMA_URL = 'https://raw.githubusercontent.com/DescentVTT/spec-brief/main/schema.json';
+/**
+ * The `$schema` `init` writes, the path the README recommends: the schema of
+ * the version installed, which is the one that loads the file. `SCHEMA_URL`
+ * follows main, and would flag a key the installed version accepts, or pass
+ * one it refuses, as soon as the two differ.
+ */
+export const SCHEMA_PATH = './node_modules/@descent-vtt/spec-brief/schema.json';
 const SEVERITY = { type: 'string', enum: ['off', 'note', 'warning', 'error'] };
 const STRINGS = { type: 'array', items: { type: 'string', minLength: 1 } };
 const SECTION = {
@@ -47,6 +54,11 @@ const 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.' },
+                hint: {
+                    type: 'string',
+                    minLength: 1,
+                    description: 'What the section must answer: a comment under the heading in a new brief, and the hint of a finding that it is missing or unwritten.',
+                },
             },
         },
     ],
@@ -74,6 +86,11 @@ export const CONFIG_SCHEMA = {
                 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.' },
+                deferred: {
+                    type: 'string',
+                    nullable: true,
+                    description: 'The word for a live brief put off until the event its "trigger" names, or null. A deferred brief is never ready and runs in no wave.',
+                },
                 archived: { type: 'string', minLength: 1, description: 'The word for an archived brief.' },
             },
         },
@@ -133,19 +150,36 @@ export const DEFAULT_CONFIG = {
     exclude: [],
     template: null,
     id: { source: 'filename', separator: '_', digits: 3 },
-    status: { field: 'status', draft: 'draft', active: 'active', archived: 'archived' },
+    status: { field: 'status', draft: 'draft', active: 'active', deferred: 'deferred', archived: 'archived' },
     sections: [
-        section('Intent', { aliases: ["Commander's Intent", 'Mission', 'Objective'] }),
+        section('Intent', {
+            aliases: ["Commander's Intent", 'Mission', 'Objective'],
+            hint: 'The state of the tree when this round is done, and why it matters. One paragraph.',
+        }),
         section('Negative Scope', {
             aliases: ['Out of Scope', 'Non-Goals', 'Not in Scope', 'What this round is NOT', 'What this brief does NOT do'],
+            hint: 'What this round must not do, even where it would look helpful.',
+        }),
+        section('Not Empowered', {
+            aliases: ['Non-Empowerment', 'Non-Empowerment List'],
+            optional: true,
+            hint: 'Files, interfaces and decisions this round may not change.',
+        }),
+        section('Invariants', {
+            aliases: ['Invariant Checklist', 'Definition of Done'],
+            checklist: true,
+            hint: 'Checks that must hold before the round is called done, each one a task item.',
         }),
-        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'] })],
+        feature: [section('Acceptance Criteria', { checklist: true, hint: 'What a reviewer checks to accept the result, each one a task item.' })],
+        defect: [
+            section('The Defect, Measured', {
+                aliases: ['Reproduction'],
+                hint: 'How to reproduce the defect, and the measurement that shows it.',
+            }),
+        ],
         refactor: [],
         chore: [],
     },
@@ -178,6 +212,7 @@ function sectionFrom(raw) {
         mustContain: r['mustContain'] ?? [],
         checklist: r['checklist'] ?? false,
         optional: r['optional'] ?? false,
+        hint: r['hint'],
     });
 }
 function pluginFrom(raw) {
@@ -234,6 +269,11 @@ export function resolveConfig(raw, file = 'configuration') {
         throw new ConfigError(file, semantic);
     return config;
 }
+/** The status words a repository uses, in lifecycle order. */
+export function statusWords(config) {
+    const { draft, active, deferred, archived } = config.status;
+    return [draft, active, deferred, archived].filter((w) => w !== null);
+}
 /** What the schema cannot say: relationships between values. */
 function checkConfig(config) {
     const problems = [];
@@ -250,9 +290,22 @@ function checkConfig(config) {
     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');
+    // Named by the statuses that share a word: a 0.1 configuration that spelt
+    // another status "deferred" meets the default for the new one here.
+    const sharing = new Map();
+    for (const key of ['draft', 'active', 'deferred', 'archived']) {
+        const word = config.status[key];
+        if (word === null)
+            continue;
+        const group = sharing.get(word.toLowerCase()) ?? { word, keys: [] };
+        group.keys.push(key);
+        sharing.set(word.toLowerCase(), group);
+    }
+    for (const { word, keys } of sharing.values()) {
+        if (keys.length < 2)
+            continue;
+        const orNull = keys.includes('deferred') ? ', or set "status.deferred" to null where no work is deferred' : '';
+        problems.push(`the status words must differ: "${word}" is the word for ${inWords(keys)}; give ${keys.length === 2 ? 'one of them' : 'all but one'} another word${orNull}`);
     }
     // 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])]) {
@@ -331,10 +384,12 @@ export function initialConfig(briefs, archive) {
             out['checklist'] = true;
         if (s.optional)
             out['optional'] = true;
+        if (s.hint !== undefined)
+            out['hint'] = s.hint;
         return Object.keys(out).length === 1 ? s.name : out;
     };
     return {
-        $schema: SCHEMA_URL,
+        $schema: SCHEMA_PATH,
         briefs,
         archive,
         files: d.files,