@descent-vtt/spec-brief 0.1.0 → 0.2.1

package/dist/text.d.ts

@@ -3,6 +3,15 @@
  */
 /** Splits text into lines without their terminators. A final newline adds no line. */
 export declare function splitLines(text: string): string[];
+/**
+ * A brief's lines as one text, for spec-core's readers.
+ *
+ * A brief's lines end at LF or CRLF, and a sealed brief's hash is taken over
+ * them. spec-core ends a line at a lone CR as well, as CommonMark does, so a
+ * lone CR is handed to it as a space: every line and column it reports is
+ * then one of the brief's own.
+ */
+export declare function textOfLines(lines: readonly string[]): string;
 /**
  * The line ending a file already uses, so a rewrite does not flip it. Decided by
  * the first terminator; a file with none is written with LF.
@@ -10,6 +19,8 @@ export declare function splitLines(text: string): string[];
 export declare function lineEnding(text: string): '\n' | '\r\n';
 /** Joins lines with the given ending and a final newline. */
 export declare function joinLines(lines: readonly string[], eol: '\n' | '\r\n'): string;
+/** Lines written back with the source's byte-order mark, line ending and final newline, or lack of one. */
+export declare function encodeLike(source: string, lines: readonly string[]): string;
 export declare function stripBom(text: string): string;
 /** CRLF and a byte-order mark are storage details, not content. */
 export declare function canonicalText(text: string): string;
@@ -34,6 +45,8 @@ export declare function labelMatches(heading: string, name: string): boolean;
  * Letters with diacritics lose them; anything else becomes a separator.
  */
 export declare function slugify(title: string, maxLength?: number): string;
+/** `a`, `a and b`, `a, b and c`. */
+export declare function inWords(items: readonly string[]): string;
 /** Fills `{name}` holes. An unknown name is left as written. */
 export declare function fillTemplate(template: string, values: Readonly<Record<string, string>>): string;
 /** The `{name}` holes a template line refers to. */

package/dist/text.js

@@ -8,6 +8,17 @@ export function splitLines(text) {
         lines.pop();
     return lines;
 }
+/**
+ * A brief's lines as one text, for spec-core's readers.
+ *
+ * A brief's lines end at LF or CRLF, and a sealed brief's hash is taken over
+ * them. spec-core ends a line at a lone CR as well, as CommonMark does, so a
+ * lone CR is handed to it as a space: every line and column it reports is
+ * then one of the brief's own.
+ */
+export function textOfLines(lines) {
+    return lines.join('\n').replace(/\r/g, ' ');
+}
 /**
  * The line ending a file already uses, so a rewrite does not flip it. Decided by
  * the first terminator; a file with none is written with LF.
@@ -19,6 +30,14 @@ export function lineEnding(text) {
 export function joinLines(lines, eol) {
     return lines.length === 0 ? '' : `${lines.join(eol)}${eol}`;
 }
+/** Lines written back with the source's byte-order mark, line ending and final newline, or lack of one. */
+export function encodeLike(source, lines) {
+    const bom = source.charCodeAt(0) === 0xfeff ? '\uFEFF' : '';
+    const eol = lineEnding(source);
+    const text = joinLines(lines, eol);
+    const finalNewline = source === '' || source.endsWith('\n');
+    return `${bom}${finalNewline ? text : text.slice(0, text.length - eol.length)}`;
+}
 export function stripBom(text) {
     return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
@@ -84,6 +103,10 @@ export function slugify(title, maxLength = 80) {
     const lastBreak = cut.lastIndexOf('-');
     return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;
 }
+/** `a`, `a and b`, `a, b and c`. */
+export function inWords(items) {
+    return items.length < 2 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1]}`;
+}
 /** Fills `{name}` holes. An unknown name is left as written. */
 export function fillTemplate(template, values) {
     return template.replace(/\{([A-Za-z]+)\}/g, (hole, name) => values[name] ?? hole);

package/dist/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Line handling and the normalisations every other module agrees on.\n */\n\n/** Splits text into lines without their terminators. A final newline adds no line. */\nexport function splitLines(text: string): string[] {\n  const lines = text.split(/\\r?\\n/);\n  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();\n  return lines;\n}\n\n/**\n * The line ending a file already uses, so a rewrite does not flip it. Decided by\n * the first terminator; a file with none is written with LF.\n */\nexport function lineEnding(text: string): '\\n' | '\\r\\n' {\n  return text.charAt(text.indexOf('\\n') - 1) === '\\r' ? '\\r\\n' : '\\n';\n}\n\n/** Joins lines with the given ending and a final newline. */\nexport function joinLines(lines: readonly string[], eol: '\\n' | '\\r\\n'): string {\n  return lines.length === 0 ? '' : `${lines.join(eol)}${eol}`;\n}\n\nexport function stripBom(text: string): string {\n  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n}\n\n/** CRLF and a byte-order mark are storage details, not content. */\nexport function canonicalText(text: string): string {\n  return stripBom(text).replace(/\\r\\n/g, '\\n');\n}\n\n/**\n * The form in which two section names are compared.\n *\n * Headings are typed by people and pasted from documents, so the comparison\n * forgives what does not change meaning: typographic apostrophes and quotes,\n * emphasis and code markers, a leading number, a trailing colon, case and runs\n * of whitespace. `## 2. Commander’s Intent:` and `Commander's Intent` compare\n * equal. Nothing else is folded: a different word is a different section.\n */\nexport function normaliseLabel(label: string): string {\n  return label\n    .normalize('NFKC')\n    .replace(/[\\u2018\\u2019\\u201b\\u2032\\u00b4]/g, \"'\")\n    .replace(/[\\u201c\\u201d\\u201f\\u2033]/g, '\"')\n    .replace(/[*_`]/g, '')\n    .replace(/^\\s*\\d+(?:\\.\\d+)*[.)]?\\s+/, '')\n    .replace(/\\s*:\\s*$/, '')\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .toLowerCase();\n}\n\n/**\n * Whether a heading names a section: equal after normalisation, or the section\n * name followed by a separator and a qualifier, as in `Invariants (must hold)`\n * or `Deliverables — round two`.\n */\nexport function labelMatches(heading: string, name: string): boolean {\n  const h = normaliseLabel(heading);\n  const n = normaliseLabel(name);\n  if (n.length === 0) return false;\n  if (h === n) return true;\n  if (!h.startsWith(n)) return false;\n  const rest = h.slice(n.length);\n  return /^(?:\\s*[:(\\u2014\\u2013]|\\s+-\\s)/.test(rest);\n}\n\n/**\n * A file-name slug: lower case, ASCII letters and digits, single hyphens.\n * Letters with diacritics lose them; anything else becomes a separator.\n */\nexport function slugify(title: string, maxLength = 80): string {\n  const slug = title\n    .normalize('NFKD')\n    .replace(/[\\u0300-\\u036f]/g, '')\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '');\n  if (slug.length <= maxLength) return slug;\n  const cut = slug.slice(0, maxLength);\n  // A cut that lands on a break keeps its last word whole.\n  if (slug.charAt(maxLength) === '-') return cut;\n  const lastBreak = cut.lastIndexOf('-');\n  return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;\n}\n\n/** Fills `{name}` holes. An unknown name is left as written. */\nexport function fillTemplate(template: string, values: Readonly<Record<string, string>>): string {\n  return template.replace(/\\{([A-Za-z]+)\\}/g, (hole, name: string) => values[name] ?? hole);\n}\n\n/** The `{name}` holes a template line refers to. */\nexport function templateHoles(template: string): string[] {\n  return [...template.matchAll(/\\{([A-Za-z]+)\\}/g)].map((match) => match[1] as string);\n}\n"]}
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Line handling and the normalisations every other module agrees on.\n */\n\n/** Splits text into lines without their terminators. A final newline adds no line. */\nexport function splitLines(text: string): string[] {\n  const lines = text.split(/\\r?\\n/);\n  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();\n  return lines;\n}\n\n/**\n * A brief's lines as one text, for spec-core's readers.\n *\n * A brief's lines end at LF or CRLF, and a sealed brief's hash is taken over\n * them. spec-core ends a line at a lone CR as well, as CommonMark does, so a\n * lone CR is handed to it as a space: every line and column it reports is\n * then one of the brief's own.\n */\nexport function textOfLines(lines: readonly string[]): string {\n  return lines.join('\\n').replace(/\\r/g, ' ');\n}\n\n/**\n * The line ending a file already uses, so a rewrite does not flip it. Decided by\n * the first terminator; a file with none is written with LF.\n */\nexport function lineEnding(text: string): '\\n' | '\\r\\n' {\n  return text.charAt(text.indexOf('\\n') - 1) === '\\r' ? '\\r\\n' : '\\n';\n}\n\n/** Joins lines with the given ending and a final newline. */\nexport function joinLines(lines: readonly string[], eol: '\\n' | '\\r\\n'): string {\n  return lines.length === 0 ? '' : `${lines.join(eol)}${eol}`;\n}\n\n/** Lines written back with the source's byte-order mark, line ending and final newline, or lack of one. */\nexport function encodeLike(source: string, lines: readonly string[]): string {\n  const bom = source.charCodeAt(0) === 0xfeff ? '\\uFEFF' : '';\n  const eol = lineEnding(source);\n  const text = joinLines(lines, eol);\n  const finalNewline = source === '' || source.endsWith('\\n');\n  return `${bom}${finalNewline ? text : text.slice(0, text.length - eol.length)}`;\n}\n\nexport function stripBom(text: string): string {\n  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;\n}\n\n/** CRLF and a byte-order mark are storage details, not content. */\nexport function canonicalText(text: string): string {\n  return stripBom(text).replace(/\\r\\n/g, '\\n');\n}\n\n/**\n * The form in which two section names are compared.\n *\n * Headings are typed by people and pasted from documents, so the comparison\n * forgives what does not change meaning: typographic apostrophes and quotes,\n * emphasis and code markers, a leading number, a trailing colon, case and runs\n * of whitespace. `## 2. Commander’s Intent:` and `Commander's Intent` compare\n * equal. Nothing else is folded: a different word is a different section.\n */\nexport function normaliseLabel(label: string): string {\n  return label\n    .normalize('NFKC')\n    .replace(/[\\u2018\\u2019\\u201b\\u2032\\u00b4]/g, \"'\")\n    .replace(/[\\u201c\\u201d\\u201f\\u2033]/g, '\"')\n    .replace(/[*_`]/g, '')\n    .replace(/^\\s*\\d+(?:\\.\\d+)*[.)]?\\s+/, '')\n    .replace(/\\s*:\\s*$/, '')\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .toLowerCase();\n}\n\n/**\n * Whether a heading names a section: equal after normalisation, or the section\n * name followed by a separator and a qualifier, as in `Invariants (must hold)`\n * or `Deliverables — round two`.\n */\nexport function labelMatches(heading: string, name: string): boolean {\n  const h = normaliseLabel(heading);\n  const n = normaliseLabel(name);\n  if (n.length === 0) return false;\n  if (h === n) return true;\n  if (!h.startsWith(n)) return false;\n  const rest = h.slice(n.length);\n  return /^(?:\\s*[:(\\u2014\\u2013]|\\s+-\\s)/.test(rest);\n}\n\n/**\n * A file-name slug: lower case, ASCII letters and digits, single hyphens.\n * Letters with diacritics lose them; anything else becomes a separator.\n */\nexport function slugify(title: string, maxLength = 80): string {\n  const slug = title\n    .normalize('NFKD')\n    .replace(/[\\u0300-\\u036f]/g, '')\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '');\n  if (slug.length <= maxLength) return slug;\n  const cut = slug.slice(0, maxLength);\n  // A cut that lands on a break keeps its last word whole.\n  if (slug.charAt(maxLength) === '-') return cut;\n  const lastBreak = cut.lastIndexOf('-');\n  return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;\n}\n\n/** `a`, `a and b`, `a, b and c`. */\nexport function inWords(items: readonly string[]): string {\n  return items.length < 2 ? (items[0] ?? '') : `${items.slice(0, -1).join(', ')} and ${items[items.length - 1] as string}`;\n}\n\n/** Fills `{name}` holes. An unknown name is left as written. */\nexport function fillTemplate(template: string, values: Readonly<Record<string, string>>): string {\n  return template.replace(/\\{([A-Za-z]+)\\}/g, (hole, name: string) => values[name] ?? hole);\n}\n\n/** The `{name}` holes a template line refers to. */\nexport function templateHoles(template: string): string[] {\n  return [...template.matchAll(/\\{([A-Za-z]+)\\}/g)].map((match) => match[1] as string);\n}\n"]}

package/dist/trigger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether a deferral's trigger names an event or only a time.
+ *
+ * Deferred work comes back when something happens: "when the second tenant
+ * signs", "when p95 exceeds 200 ms". A date is not that. It passes whether or
+ * not the reason for the work has arrived, and a deferral that fires on a date
+ * is a reminder to look again, which the deferral itself already is. So a
+ * trigger made only of words that say when - a date, a quarter, a month or a
+ * weekday, a stretch of time and the small words that join them - is refused,
+ * and one word that says what is enough to pass.
+ *
+ * The lists are deliberately short. A trigger this reads as an event when it
+ * is a time is a miss, and a miss costs less here than refusing a real event
+ * for looking like a date.
+ */
+/** Whether a trigger has a word that says what must happen, rather than only when. */
+export declare function namesAnEvent(trigger: string): boolean;

package/dist/trigger.js

@@ -0,0 +1,49 @@
+/**
+ * Whether a deferral's trigger names an event or only a time.
+ *
+ * Deferred work comes back when something happens: "when the second tenant
+ * signs", "when p95 exceeds 200 ms". A date is not that. It passes whether or
+ * not the reason for the work has arrived, and a deferral that fires on a date
+ * is a reminder to look again, which the deferral itself already is. So a
+ * trigger made only of words that say when - a date, a quarter, a month or a
+ * weekday, a stretch of time and the small words that join them - is refused,
+ * and one word that says what is enough to pass.
+ *
+ * The lists are deliberately short. A trigger this reads as an event when it
+ * is a time is a miss, and a miss costs less here than refusing a real event
+ * for looking like a date.
+ */
+const MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];
+const WEEKDAYS = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'];
+/** Words that say when and nothing else. */
+const WHEN = new Set([
+    ...MONTHS,
+    ...MONTHS.map((m) => m.slice(0, 3)),
+    'sept',
+    ...WEEKDAYS,
+    ...WEEKDAYS.map((d) => d.slice(0, 3)),
+    // A stretch of time.
+    ...['day', 'week', 'weekend', 'month', 'quarter', 'year', 'sprint'].flatMap((unit) => [unit, `${unit}s`]),
+    'today',
+    'tomorrow',
+    'soon',
+    'later',
+    // How many of them.
+    ...['a', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve', 'few', 'couple'],
+    // The words that join them.
+    ...['in', 'on', 'by', 'at', 'after', 'before', 'until', 'from', 'of', 'the', 'next', 'this', 'end', 'start', 'early', 'mid', 'late'],
+]);
+/**
+ * A number or an ordinal - `2026`, `15`, `15th` - or a quarter, `Q3`. A date is
+ * its numbers: `2026-10-01` and `10/01/2026` are read a number at a time.
+ */
+const DATE = /^(?:q[1-4]|\d+(?:st|nd|rd|th)?)$/;
+/** The runs of letters and digits, in lower case: `mid-2027` is two words, and punctuation none. */
+function words(text) {
+    return text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+/** Whether a trigger has a word that says what must happen, rather than only when. */
+export function namesAnEvent(trigger) {
+    return words(trigger).some((word) => !WHEN.has(word) && !DATE.test(word));
+}
+//# sourceMappingURL=trigger.js.map

package/dist/trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger.js","sourceRoot":"","sources":["../src/trigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,GAAG,CAAC,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AAC1I,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;AAEhG,4CAA4C;AAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC;IACnB,GAAG,MAAM;IACT,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACnC,MAAM;IACN,GAAG,QAAQ;IACX,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrC,qBAAqB;IACrB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC;IACzG,OAAO;IACP,UAAU;IACV,MAAM;IACN,OAAO;IACP,oBAAoB;IACpB,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC;IAC5H,4BAA4B;IAC5B,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC;CACrI,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,IAAI,GAAG,kCAAkC,CAAC;AAEhD,oGAAoG;AACpG,SAAS,KAAK,CAAC,IAAY;IACzB,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;AAC3D,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5E,CAAC","sourcesContent":["/**\n * Whether a deferral's trigger names an event or only a time.\n *\n * Deferred work comes back when something happens: \"when the second tenant\n * signs\", \"when p95 exceeds 200 ms\". A date is not that. It passes whether or\n * not the reason for the work has arrived, and a deferral that fires on a date\n * is a reminder to look again, which the deferral itself already is. So a\n * trigger made only of words that say when - a date, a quarter, a month or a\n * weekday, a stretch of time and the small words that join them - is refused,\n * and one word that says what is enough to pass.\n *\n * The lists are deliberately short. A trigger this reads as an event when it\n * is a time is a miss, and a miss costs less here than refusing a real event\n * for looking like a date.\n */\n\nconst MONTHS = ['january', 'february', 'march', 'april', 'may', 'june', 'july', 'august', 'september', 'october', 'november', 'december'];\nconst WEEKDAYS = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'];\n\n/** Words that say when and nothing else. */\nconst WHEN = new Set([\n  ...MONTHS,\n  ...MONTHS.map((m) => m.slice(0, 3)),\n  'sept',\n  ...WEEKDAYS,\n  ...WEEKDAYS.map((d) => d.slice(0, 3)),\n  // A stretch of time.\n  ...['day', 'week', 'weekend', 'month', 'quarter', 'year', 'sprint'].flatMap((unit) => [unit, `${unit}s`]),\n  'today',\n  'tomorrow',\n  'soon',\n  'later',\n  // How many of them.\n  ...['a', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve', 'few', 'couple'],\n  // The words that join them.\n  ...['in', 'on', 'by', 'at', 'after', 'before', 'until', 'from', 'of', 'the', 'next', 'this', 'end', 'start', 'early', 'mid', 'late'],\n]);\n\n/**\n * A number or an ordinal - `2026`, `15`, `15th` - or a quarter, `Q3`. A date is\n * its numbers: `2026-10-01` and `10/01/2026` are read a number at a time.\n */\nconst DATE = /^(?:q[1-4]|\\d+(?:st|nd|rd|th)?)$/;\n\n/** The runs of letters and digits, in lower case: `mid-2027` is two words, and punctuation none. */\nfunction words(text: string): readonly string[] {\n  return text.toLowerCase().match(/[\\p{L}\\p{N}]+/gu) ?? [];\n}\n\n/** Whether a trigger has a word that says what must happen, rather than only when. */\nexport function namesAnEvent(trigger: string): boolean {\n  return words(trigger).some((word) => !WHEN.has(word) && !DATE.test(word));\n}\n"]}

package/dist/types.d.ts

@@ -7,12 +7,14 @@ export type SeveritySetting = Severity | 'off';
 /** Where a brief lives. Location is the authority on whether a brief is archived. */
 export type Phase = 'live' | 'archived';
 /**
- * The lifecycle a brief moves through. `draft` is optional: a repository that
- * never writes one maps no word to it. There is no persisted "archiving" state;
- * archival is a transaction, and a transaction that stops half-way is rolled
- * back rather than recorded.
+ * The lifecycle a brief moves through. `draft` and `deferred` are optional: a
+ * repository that never writes one maps no word to it. A deferred brief waits
+ * in the live directory for an event its `trigger` names, and runs in no wave
+ * until then. There is no persisted "archiving" state; archival is a
+ * transaction, and a transaction that stops half-way is rolled back rather
+ * than recorded.
  */
-export type Status = 'draft' | 'active' | 'archived';
+export type Status = 'draft' | 'active' | 'deferred' | 'archived';
 /**
  * One problem, located. Lines are 1-based; a finding about a file as a whole
  * points at line 1.
@@ -27,4 +29,11 @@ export interface Finding {
     readonly brief?: string | undefined;
     /** The concrete next action, where there is one. */
     readonly hint?: string | undefined;
+    /**
+     * The one repository path a finding is about, where it is about one: a
+     * protected file the round changed is one finding per file, and names it.
+     */
+    readonly path?: string | undefined;
+    /** The paths of a finding about several, such as the files a round changed outside its scope. */
+    readonly paths?: readonly string[] | undefined;
 }

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG","sourcesContent":["/**\n * Types shared across the pipeline. Type-only: this module compiles to nothing.\n */\n\nexport type Severity = 'error' | 'warning' | 'note';\n\n/** A severity as configuration spells it, where `off` silences a rule. */\nexport type SeveritySetting = Severity | 'off';\n\n/** Where a brief lives. Location is the authority on whether a brief is archived. */\nexport type Phase = 'live' | 'archived';\n\n/**\n * The lifecycle a brief moves through. `draft` is optional: a repository that\n * never writes one maps no word to it. There is no persisted \"archiving\" state;\n * archival is a transaction, and a transaction that stops half-way is rolled\n * back rather than recorded.\n */\nexport type Status = 'draft' | 'active' | 'archived';\n\n/**\n * One problem, located. Lines are 1-based; a finding about a file as a whole\n * points at line 1.\n */\nexport interface Finding {\n  readonly rule: string;\n  readonly severity: Severity;\n  readonly message: string;\n  /** Repository-relative POSIX path. */\n  readonly file: string;\n  readonly line: number;\n  readonly brief?: string | undefined;\n  /** The concrete next action, where there is one. */\n  readonly hint?: string | undefined;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG","sourcesContent":["/**\n * Types shared across the pipeline. Type-only: this module compiles to nothing.\n */\n\nexport type Severity = 'error' | 'warning' | 'note';\n\n/** A severity as configuration spells it, where `off` silences a rule. */\nexport type SeveritySetting = Severity | 'off';\n\n/** Where a brief lives. Location is the authority on whether a brief is archived. */\nexport type Phase = 'live' | 'archived';\n\n/**\n * The lifecycle a brief moves through. `draft` and `deferred` are optional: a\n * repository that never writes one maps no word to it. A deferred brief waits\n * in the live directory for an event its `trigger` names, and runs in no wave\n * until then. There is no persisted \"archiving\" state; archival is a\n * transaction, and a transaction that stops half-way is rolled back rather\n * than recorded.\n */\nexport type Status = 'draft' | 'active' | 'deferred' | 'archived';\n\n/**\n * One problem, located. Lines are 1-based; a finding about a file as a whole\n * points at line 1.\n */\nexport interface Finding {\n  readonly rule: string;\n  readonly severity: Severity;\n  readonly message: string;\n  /** Repository-relative POSIX path. */\n  readonly file: string;\n  readonly line: number;\n  readonly brief?: string | undefined;\n  /** The concrete next action, where there is one. */\n  readonly hint?: string | undefined;\n  /**\n   * The one repository path a finding is about, where it is about one: a\n   * protected file the round changed is one finding per file, and names it.\n   */\n  readonly path?: string | undefined;\n  /** The paths of a finding about several, such as the files a round changed outside its scope. */\n  readonly paths?: readonly string[] | undefined;\n}\n"]}

package/dist/vendor/spec-core/markdown/frontmatter.d.ts

@@ -0,0 +1,103 @@
+/**
+ * A reader and editor for the front matter the spec-* tools use: a flat bag
+ * of YAML scalars and lists, and optionally one level of nested mapping.
+ *
+ * Supported: `key: value` lines; plain, single-quoted and double-quoted
+ * scalars; inline `[a, b]` sequences; block `- item` sequences; `#` comments.
+ * Plain scalars follow the YAML 1.2 core schema, so `yes` is a word and `035`
+ * keeps its leading zero for whoever reads it as text. With `nested`, a key
+ * whose value is an indented block of keys is read as `parent.child` entries.
+ *
+ * Anything richer - deeper nesting, block scalars, anchors, tags, a value
+ * continued onto the next line - is recognised and reported as unsupported
+ * rather than guessed at. A YAML library would parse more, but it would not
+ * give back the line and the offset of every value, and a report has to point
+ * at the value it is about, and an edit has to leave every other line of the
+ * file as it was.
+ */
+import type { FrontMatterKind } from './types.js';
+export interface YamlScalar {
+    readonly text: string;
+    readonly quoted: boolean;
+}
+export type YamlValue = {
+    readonly kind: 'scalar';
+    readonly scalar: YamlScalar;
+} | {
+    readonly kind: 'list';
+    readonly items: readonly YamlScalar[];
+} | {
+    readonly kind: 'unsupported';
+    readonly reason: string;
+};
+export interface FrontMatterEntry {
+    /** The key as written; a nested key is its parent's and its own, joined by a dot. */
+    readonly key: string;
+    /** The key compared: {@link keyName} of `key`, so `depends-on` is `dependsOn`. */
+    readonly name: string;
+    /** The parent key as written, for a nested key; `null` at the top level. */
+    readonly parent: string | null;
+    /** 0-based line of the key. */
+    readonly line: number;
+    /** 0-based line after the entry's last line. */
+    readonly end: number;
+    /** Offset of the key in the text read. */
+    readonly keyStart: number;
+    /**
+     * Offsets of the value as written: a quoted scalar with its quotes, an
+     * inline list with its brackets, a block list from its first item's text to
+     * its last item's. An empty value is the empty range just past the colon.
+     */
+    readonly valueStart: number;
+    readonly valueEnd: number;
+    readonly value: YamlValue;
+}
+export interface FrontMatterProblem {
+    /** 0-based line. */
+    readonly line: number;
+    readonly message: string;
+}
+export interface FrontMatter {
+    readonly kind: FrontMatterKind;
+    /** 0-based line of the closing delimiter, or -1 when the block is never closed. */
+    readonly close: number;
+    readonly entries: readonly FrontMatterEntry[];
+    readonly problems: readonly FrontMatterProblem[];
+}
+export interface ReadOptions {
+    /**
+     * Read one level of nested mapping as `parent.child` entries, instead of
+     * reporting the parent's value as unsupported.
+     */
+    readonly nested?: boolean;
+}
+/** The kind of front matter a document's first line opens, or `null` when it opens none. */
+export declare function frontMatterKind(firstLine: string): FrontMatterKind | null;
+/** Whether a line closes front matter of a kind: `---` or `...` for YAML, `+++` for TOML. */
+export declare function frontMatterCloses(line: string, kind: FrontMatterKind): boolean;
+export declare function keyName(key: string): string;
+/**
+ * Reads the front matter at the top of a text, or `null` when there is none.
+ *
+ * A leading byte-order mark is not part of the text read: offsets count from
+ * the character after it, as a scan's do.
+ */
+export declare function readFrontMatter(source: string, options?: ReadOptions): FrontMatter | null;
+/** Parses a value written on the key's own line. `text` is trimmed and non-empty. */
+export declare function parseInline(text: string): YamlValue;
+/** Null in the YAML 1.2 core schema: empty, `~` or `null` in any of its three spellings. */
+export declare function isNull(scalar: YamlScalar): boolean;
+/** Renders a string as a scalar that reads back as the same string. */
+export declare function renderScalar(value: string): string;
+export declare function findEntry(frontMatter: FrontMatter | null, key: string): FrontMatterEntry | undefined;
+/**
+ * Sets one key, leaving every other line as it was.
+ *
+ * `lines` are the lines of the text the front matter was read from, as
+ * `splitLines` gives them. An existing entry keeps the spelling and the
+ * indentation of its key; a new one goes last, at the top level. A text with
+ * no front matter gains a block.
+ */
+export declare function setEntry(lines: readonly string[], frontMatter: FrontMatter | null, key: string, rendered: string): string[];
+/** Removes one key and its value lines; a key that is absent changes nothing. */
+export declare function removeEntry(lines: readonly string[], frontMatter: FrontMatter | null, key: string): string[];