@descent-vtt/spec-brief 0.1.0

package/dist/frontmatter.js

@@ -0,0 +1,311 @@
+/**
+ * A front-matter reader and editor for the flat subset of YAML briefs use.
+ *
+ * Supported: `key: value` at the top level; 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.
+ *
+ * Anything richer - nested mappings, 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, and would be the
+ * largest dependency of a package that has none; it would also not give back
+ * the line of every value, and an edit that must leave every other line of a
+ * file untouched needs exactly that.
+ */
+const OPEN = /^---[ \t]*$/;
+const CLOSE = /^(?:---|\.\.\.)[ \t]*$/;
+const KEY = /^([A-Za-z_][\w.-]*)[ \t]*:(?:[ \t]+(.*))?$/;
+const SEQUENCE_ITEM = /^([ \t]*)-(?:[ \t]+(.*))?$/;
+const BLANK_OR_COMMENT = /^[ \t]*(?:#.*)?$/;
+export function keyName(key) {
+    return key.toLowerCase().replace(/[-_]/g, '');
+}
+/** Reads the front matter at the top of `lines`, or `null` when there is none. */
+export function readFrontMatter(lines) {
+    if (lines.length === 0 || !OPEN.test(lines[0]))
+        return null;
+    let close = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (CLOSE.test(lines[i])) {
+            close = i;
+            break;
+        }
+    }
+    if (close < 0) {
+        return {
+            close: -1,
+            entries: [],
+            problems: [{ line: 0, message: 'the front matter opened on line 1 is never closed' }],
+        };
+    }
+    const entries = [];
+    const problems = [];
+    const seen = new Map();
+    let i = 1;
+    while (i < close) {
+        const line = lines[i];
+        if (BLANK_OR_COMMENT.test(line)) {
+            i += 1;
+            continue;
+        }
+        const match = KEY.exec(line);
+        if (!match) {
+            problems.push({
+                line: i,
+                message: /^\s/.test(line) ? 'an indented line belongs to no key' : 'not a "key: value" line',
+            });
+            i += 1;
+            continue;
+        }
+        const key = match[1];
+        const inline = stripLeadingComment((match[2] ?? '').trim());
+        let end = i + 1;
+        while (end < close && belongsToBlock(lines[end]))
+            end += 1;
+        while (end > i + 1 && BLANK_OR_COMMENT.test(lines[end - 1]))
+            end -= 1;
+        const block = lines.slice(i + 1, end);
+        let value;
+        if (inline.length > 0) {
+            value = block.some((l) => !BLANK_OR_COMMENT.test(l))
+                ? unsupported('the value continues on the next line; keep it on one line, or quote it')
+                : parseInline(inline);
+        }
+        else {
+            value = parseBlock(block);
+        }
+        const name = keyName(key);
+        const previous = seen.get(name);
+        if (previous !== undefined) {
+            problems.push({ line: i, message: `"${key}" is declared twice (first on line ${previous + 1})` });
+        }
+        else {
+            seen.set(name, i);
+        }
+        entries.push({ key, name, line: i, end, value });
+        i = end;
+    }
+    return { close, entries, problems };
+}
+/** A line under a key is part of its value when it is indented or starts a sequence item. */
+function belongsToBlock(line) {
+    return /^[ \t]/.test(line) || /^-(?:[ \t]|$)/.test(line) || line.trim() === '';
+}
+function stripLeadingComment(text) {
+    return text.startsWith('#') ? '' : text;
+}
+function unsupported(reason) {
+    return { kind: 'unsupported', reason };
+}
+function parseBlock(block) {
+    const content = block.filter((l) => !BLANK_OR_COMMENT.test(l));
+    if (content.length === 0)
+        return { kind: 'scalar', scalar: { text: '', quoted: false } };
+    const first = SEQUENCE_ITEM.exec(content[0]);
+    if (!first) {
+        return KEY.test(content[0].trim())
+            ? unsupported('nested mappings are not supported; flatten the key')
+            : unsupported('the value continues on the next line; keep it on one line, or quote it');
+    }
+    const indent = first[1].length;
+    const items = [];
+    for (const line of content) {
+        const item = SEQUENCE_ITEM.exec(line);
+        if (!item || item[1].length !== indent) {
+            return unsupported('a list item is continued or nested; keep each item on one line');
+        }
+        const text = stripLeadingComment((item[2] ?? '').trim());
+        if (text.length === 0)
+            return unsupported('a list item is empty');
+        const parsed = parseInline(text);
+        if (parsed.kind !== 'scalar') {
+            return parsed.kind === 'list' ? unsupported('nested lists are not supported') : parsed;
+        }
+        items.push(parsed.scalar);
+    }
+    return { kind: 'list', items };
+}
+/** Parses a value written on the key's own line. `text` is trimmed and non-empty. */
+export function parseInline(text) {
+    const head = text.charAt(0);
+    if (head === '"' || head === "'") {
+        const quoted = head === '"' ? readDoubleQuoted(text) : readSingleQuoted(text);
+        if (typeof quoted === 'string')
+            return unsupported(quoted);
+        return trailingIsComment(text.slice(quoted.next))
+            ? { kind: 'scalar', scalar: { text: quoted.text, quoted: true } }
+            : unsupported('text follows a closing quote');
+    }
+    if (head === '[')
+        return parseFlowSequence(text);
+    if (head === '{')
+        return unsupported('inline mappings are not supported');
+    if (head === '|' || head === '>')
+        return unsupported('block scalars are not supported; keep the value on one line');
+    if (head === '&' || head === '*' || head === '!')
+        return unsupported('anchors, aliases and tags are not supported');
+    if (head === '@' || head === '`')
+        return unsupported(`a plain value cannot start with "${head}"; quote it`);
+    const plain = stripTrailingComment(text);
+    if (/:(?:\s|$)/.test(plain))
+        return unsupported('a plain value cannot contain ": "; quote it');
+    if (/^-(?:\s|$)/.test(plain))
+        return unsupported('a list must start on the line after its key');
+    return { kind: 'scalar', scalar: { text: plain, quoted: false } };
+}
+function stripTrailingComment(text) {
+    const hash = text.search(/\s#/);
+    return (hash < 0 ? text : text.slice(0, hash)).trim();
+}
+function trailingIsComment(rest) {
+    return /^\s*(?:#.*)?$/.test(rest) && (rest.trim() === '' || /^\s/.test(rest));
+}
+const ESCAPES = {
+    '"': '"',
+    '\\': '\\',
+    '/': '/',
+    '0': '\0',
+    b: '\b',
+    f: '\f',
+    n: '\n',
+    r: '\r',
+    t: '\t',
+};
+const HEX_ESCAPE_LENGTH = { x: 2, u: 4, U: 8 };
+/** Reads a double-quoted scalar starting at index 0, or returns why it cannot. */
+function readDoubleQuoted(text) {
+    let out = '';
+    for (let i = 1; i < text.length; i += 1) {
+        const ch = text.charAt(i);
+        if (ch === '"')
+            return { text: out, next: i + 1 };
+        if (ch !== '\\') {
+            out += ch;
+            continue;
+        }
+        const code = text.charAt(i + 1);
+        const simple = ESCAPES[code];
+        if (simple !== undefined) {
+            out += simple;
+            i += 1;
+            continue;
+        }
+        const width = HEX_ESCAPE_LENGTH[code];
+        const hex = width === undefined ? '' : text.slice(i + 2, i + 2 + width);
+        if (width === undefined || hex.length !== width || !/^[0-9A-Fa-f]+$/.test(hex)) {
+            return `"\\${code}" is not an escape this reader knows`;
+        }
+        const point = Number.parseInt(hex, 16);
+        if (point > 0x10ffff)
+            return `"\\${code}${hex}" is not a character`;
+        out += String.fromCodePoint(point);
+        i += 1 + width;
+    }
+    return 'a double-quoted value is never closed';
+}
+function readSingleQuoted(text) {
+    let out = '';
+    for (let i = 1; i < text.length; i += 1) {
+        const ch = text.charAt(i);
+        if (ch !== "'") {
+            out += ch;
+            continue;
+        }
+        if (text.charAt(i + 1) === "'") {
+            out += "'";
+            i += 1;
+            continue;
+        }
+        return { text: out, next: i + 1 };
+    }
+    return 'a single-quoted value is never closed';
+}
+function parseFlowSequence(text) {
+    const items = [];
+    let i = 1;
+    for (;;) {
+        while (i < text.length && /\s/.test(text.charAt(i)))
+            i += 1;
+        if (i >= text.length)
+            return unsupported('an inline list is never closed; keep it on one line');
+        const ch = text.charAt(i);
+        if (ch === ']') {
+            return trailingIsComment(text.slice(i + 1))
+                ? { kind: 'list', items }
+                : unsupported('text follows the end of an inline list');
+        }
+        if (ch === '[' || ch === '{')
+            return unsupported('nested lists and mappings are not supported');
+        if (ch === ',')
+            return unsupported('an inline list has an empty item');
+        let item;
+        if (ch === '"' || ch === "'") {
+            const rest = text.slice(i);
+            const quoted = ch === '"' ? readDoubleQuoted(rest) : readSingleQuoted(rest);
+            if (typeof quoted === 'string')
+                return unsupported(quoted);
+            item = { text: quoted.text, quoted: true };
+            i += quoted.next;
+        }
+        else {
+            let j = i;
+            while (j < text.length && !',]'.includes(text.charAt(j)))
+                j += 1;
+            const plain = text.slice(i, j).trim();
+            if (/[[{]/.test(plain) || /:(?:\s|$)/.test(plain) || plain.includes(' #')) {
+                return unsupported(`"${plain}" needs quoting inside an inline list`);
+            }
+            item = { text: plain, quoted: false };
+            i = j;
+        }
+        items.push(item);
+        while (i < text.length && /\s/.test(text.charAt(i)))
+            i += 1;
+        if (i >= text.length)
+            return unsupported('an inline list is never closed; keep it on one line');
+        // After a comma the next pass reads an item or, legally in YAML, the bracket.
+        if (text.charAt(i) === ',')
+            i += 1;
+        else if (text.charAt(i) !== ']')
+            return unsupported('inline list items must be separated by commas');
+    }
+}
+/** Null in the YAML 1.2 core schema: empty, `~` or `null` in any of its three spellings. */
+export function isNull(scalar) {
+    return !scalar.quoted && ['', '~', 'null', 'Null', 'NULL'].includes(scalar.text);
+}
+/** Renders a string as a scalar that reads back as the same string. */
+export function renderScalar(value) {
+    const reserved = /^(?:true|false|null|yes|no|on|off|~)$/i.test(value);
+    const plain = /^[A-Za-z][A-Za-z0-9 ._/+-]*$/.test(value) && !value.endsWith(' ');
+    return plain && !reserved ? value : JSON.stringify(value);
+}
+export function findEntry(frontMatter, key) {
+    const name = keyName(key);
+    return frontMatter?.entries.find((entry) => entry.name === name);
+}
+/**
+ * Sets one key, leaving every other line as it was. An existing entry keeps the
+ * spelling of its key; a new one goes last. A file with no front matter gains
+ * a block.
+ */
+export function setEntry(lines, frontMatter, key, rendered) {
+    if (frontMatter === null)
+        return ['---', `${key}: ${rendered}`, '---', ...lines];
+    if (frontMatter.close < 0)
+        throw new Error('cannot edit front matter that is never closed');
+    const entry = findEntry(frontMatter, key);
+    if (entry === undefined) {
+        return [...lines.slice(0, frontMatter.close), `${key}: ${rendered}`, ...lines.slice(frontMatter.close)];
+    }
+    return [...lines.slice(0, entry.line), `${entry.key}: ${rendered}`, ...lines.slice(entry.end)];
+}
+/** Removes one key and its value lines; a key that is absent changes nothing. */
+export function removeEntry(lines, frontMatter, key) {
+    const entry = findEntry(frontMatter, key);
+    if (entry === undefined)
+        return [...lines];
+    return [...lines.slice(0, entry.line), ...lines.slice(entry.end)];
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * A front-matter reader and editor for the flat subset of YAML briefs use.\n *\n * Supported: `key: value` at the top level; plain, single-quoted and\n * double-quoted scalars; inline `[a, b]` sequences; block `- item` sequences;\n * `#` comments. Plain scalars follow the YAML 1.2 core schema, so `yes` is a\n * word and `035` keeps its leading zero for whoever reads it as text.\n *\n * Anything richer - nested mappings, block scalars, anchors, tags, a value\n * continued onto the next line - is recognised and reported as unsupported\n * rather than guessed at. A YAML library would parse more, and would be the\n * largest dependency of a package that has none; it would also not give back\n * the line of every value, and an edit that must leave every other line of a\n * file untouched needs exactly that.\n */\n\nexport interface YamlScalar {\n  readonly text: string;\n  readonly quoted: boolean;\n}\n\nexport type YamlValue =\n  | { readonly kind: 'scalar'; readonly scalar: YamlScalar }\n  | { readonly kind: 'list'; readonly items: readonly YamlScalar[] }\n  | { readonly kind: 'unsupported'; readonly reason: string };\n\nexport interface FrontMatterEntry {\n  /** The key as written. */\n  readonly key: string;\n  /** The key compared: lower case, without `-` or `_`, so `depends-on` is `dependsOn`. */\n  readonly name: string;\n  /** 0-based line of the key. */\n  readonly line: number;\n  /** 0-based line after the entry's last line. */\n  readonly end: number;\n  readonly value: YamlValue;\n}\n\nexport interface FrontMatterProblem {\n  readonly line: number;\n  readonly message: string;\n}\n\nexport interface FrontMatter {\n  /** 0-based line of the closing delimiter, or -1 when the block is never closed. */\n  readonly close: number;\n  readonly entries: readonly FrontMatterEntry[];\n  readonly problems: readonly FrontMatterProblem[];\n}\n\nconst OPEN = /^---[ \\t]*$/;\nconst CLOSE = /^(?:---|\\.\\.\\.)[ \\t]*$/;\nconst KEY = /^([A-Za-z_][\\w.-]*)[ \\t]*:(?:[ \\t]+(.*))?$/;\nconst SEQUENCE_ITEM = /^([ \\t]*)-(?:[ \\t]+(.*))?$/;\nconst BLANK_OR_COMMENT = /^[ \\t]*(?:#.*)?$/;\n\nexport function keyName(key: string): string {\n  return key.toLowerCase().replace(/[-_]/g, '');\n}\n\n/** Reads the front matter at the top of `lines`, or `null` when there is none. */\nexport function readFrontMatter(lines: readonly string[]): FrontMatter | null {\n  if (lines.length === 0 || !OPEN.test(lines[0] as string)) return null;\n  let close = -1;\n  for (let i = 1; i < lines.length; i += 1) {\n    if (CLOSE.test(lines[i] as string)) {\n      close = i;\n      break;\n    }\n  }\n  if (close < 0) {\n    return {\n      close: -1,\n      entries: [],\n      problems: [{ line: 0, message: 'the front matter opened on line 1 is never closed' }],\n    };\n  }\n\n  const entries: FrontMatterEntry[] = [];\n  const problems: FrontMatterProblem[] = [];\n  const seen = new Map<string, number>();\n  let i = 1;\n  while (i < close) {\n    const line = lines[i] as string;\n    if (BLANK_OR_COMMENT.test(line)) {\n      i += 1;\n      continue;\n    }\n    const match = KEY.exec(line);\n    if (!match) {\n      problems.push({\n        line: i,\n        message: /^\\s/.test(line) ? 'an indented line belongs to no key' : 'not a \"key: value\" line',\n      });\n      i += 1;\n      continue;\n    }\n    const key = match[1] as string;\n    const inline = stripLeadingComment((match[2] ?? '').trim());\n    let end = i + 1;\n    while (end < close && belongsToBlock(lines[end] as string)) end += 1;\n    while (end > i + 1 && BLANK_OR_COMMENT.test(lines[end - 1] as string)) end -= 1;\n    const block = lines.slice(i + 1, end);\n\n    let value: YamlValue;\n    if (inline.length > 0) {\n      value = block.some((l) => !BLANK_OR_COMMENT.test(l))\n        ? unsupported('the value continues on the next line; keep it on one line, or quote it')\n        : parseInline(inline);\n    } else {\n      value = parseBlock(block);\n    }\n\n    const name = keyName(key);\n    const previous = seen.get(name);\n    if (previous !== undefined) {\n      problems.push({ line: i, message: `\"${key}\" is declared twice (first on line ${previous + 1})` });\n    } else {\n      seen.set(name, i);\n    }\n    entries.push({ key, name, line: i, end, value });\n    i = end;\n  }\n  return { close, entries, problems };\n}\n\n/** A line under a key is part of its value when it is indented or starts a sequence item. */\nfunction belongsToBlock(line: string): boolean {\n  return /^[ \\t]/.test(line) || /^-(?:[ \\t]|$)/.test(line) || line.trim() === '';\n}\n\nfunction stripLeadingComment(text: string): string {\n  return text.startsWith('#') ? '' : text;\n}\n\nfunction unsupported(reason: string): YamlValue {\n  return { kind: 'unsupported', reason };\n}\n\nfunction parseBlock(block: readonly string[]): YamlValue {\n  const content = block.filter((l) => !BLANK_OR_COMMENT.test(l));\n  if (content.length === 0) return { kind: 'scalar', scalar: { text: '', quoted: false } };\n  const first = SEQUENCE_ITEM.exec(content[0] as string);\n  if (!first) {\n    return KEY.test((content[0] as string).trim())\n      ? unsupported('nested mappings are not supported; flatten the key')\n      : unsupported('the value continues on the next line; keep it on one line, or quote it');\n  }\n  const indent = (first[1] as string).length;\n  const items: YamlScalar[] = [];\n  for (const line of content) {\n    const item = SEQUENCE_ITEM.exec(line);\n    if (!item || (item[1] as string).length !== indent) {\n      return unsupported('a list item is continued or nested; keep each item on one line');\n    }\n    const text = stripLeadingComment((item[2] ?? '').trim());\n    if (text.length === 0) return unsupported('a list item is empty');\n    const parsed = parseInline(text);\n    if (parsed.kind !== 'scalar') {\n      return parsed.kind === 'list' ? unsupported('nested lists are not supported') : parsed;\n    }\n    items.push(parsed.scalar);\n  }\n  return { kind: 'list', items };\n}\n\n/** Parses a value written on the key's own line. `text` is trimmed and non-empty. */\nexport function parseInline(text: string): YamlValue {\n  const head = text.charAt(0);\n  if (head === '\"' || head === \"'\") {\n    const quoted = head === '\"' ? readDoubleQuoted(text) : readSingleQuoted(text);\n    if (typeof quoted === 'string') return unsupported(quoted);\n    return trailingIsComment(text.slice(quoted.next))\n      ? { kind: 'scalar', scalar: { text: quoted.text, quoted: true } }\n      : unsupported('text follows a closing quote');\n  }\n  if (head === '[') return parseFlowSequence(text);\n  if (head === '{') return unsupported('inline mappings are not supported');\n  if (head === '|' || head === '>') return unsupported('block scalars are not supported; keep the value on one line');\n  if (head === '&' || head === '*' || head === '!') return unsupported('anchors, aliases and tags are not supported');\n  if (head === '@' || head === '`') return unsupported(`a plain value cannot start with \"${head}\"; quote it`);\n  const plain = stripTrailingComment(text);\n  if (/:(?:\\s|$)/.test(plain)) return unsupported('a plain value cannot contain \": \"; quote it');\n  if (/^-(?:\\s|$)/.test(plain)) return unsupported('a list must start on the line after its key');\n  return { kind: 'scalar', scalar: { text: plain, quoted: false } };\n}\n\nfunction stripTrailingComment(text: string): string {\n  const hash = text.search(/\\s#/);\n  return (hash < 0 ? text : text.slice(0, hash)).trim();\n}\n\nfunction trailingIsComment(rest: string): boolean {\n  return /^\\s*(?:#.*)?$/.test(rest) && (rest.trim() === '' || /^\\s/.test(rest));\n}\n\ninterface Quoted {\n  readonly text: string;\n  /** Index just past the closing quote. */\n  readonly next: number;\n}\n\nconst ESCAPES: Readonly<Record<string, string>> = {\n  '\"': '\"',\n  '\\\\': '\\\\',\n  '/': '/',\n  '0': '\\0',\n  b: '\\b',\n  f: '\\f',\n  n: '\\n',\n  r: '\\r',\n  t: '\\t',\n};\n\nconst HEX_ESCAPE_LENGTH: Readonly<Record<string, number>> = { x: 2, u: 4, U: 8 };\n\n/** Reads a double-quoted scalar starting at index 0, or returns why it cannot. */\nfunction readDoubleQuoted(text: string): Quoted | string {\n  let out = '';\n  for (let i = 1; i < text.length; i += 1) {\n    const ch = text.charAt(i);\n    if (ch === '\"') return { text: out, next: i + 1 };\n    if (ch !== '\\\\') {\n      out += ch;\n      continue;\n    }\n    const code = text.charAt(i + 1);\n    const simple = ESCAPES[code];\n    if (simple !== undefined) {\n      out += simple;\n      i += 1;\n      continue;\n    }\n    const width = HEX_ESCAPE_LENGTH[code];\n    const hex = width === undefined ? '' : text.slice(i + 2, i + 2 + width);\n    if (width === undefined || hex.length !== width || !/^[0-9A-Fa-f]+$/.test(hex)) {\n      return `\"\\\\${code}\" is not an escape this reader knows`;\n    }\n    const point = Number.parseInt(hex, 16);\n    if (point > 0x10ffff) return `\"\\\\${code}${hex}\" is not a character`;\n    out += String.fromCodePoint(point);\n    i += 1 + width;\n  }\n  return 'a double-quoted value is never closed';\n}\n\nfunction readSingleQuoted(text: string): Quoted | string {\n  let out = '';\n  for (let i = 1; i < text.length; i += 1) {\n    const ch = text.charAt(i);\n    if (ch !== \"'\") {\n      out += ch;\n      continue;\n    }\n    if (text.charAt(i + 1) === \"'\") {\n      out += \"'\";\n      i += 1;\n      continue;\n    }\n    return { text: out, next: i + 1 };\n  }\n  return 'a single-quoted value is never closed';\n}\n\nfunction parseFlowSequence(text: string): YamlValue {\n  const items: YamlScalar[] = [];\n  let i = 1;\n  for (;;) {\n    while (i < text.length && /\\s/.test(text.charAt(i))) i += 1;\n    if (i >= text.length) return unsupported('an inline list is never closed; keep it on one line');\n    const ch = text.charAt(i);\n    if (ch === ']') {\n      return trailingIsComment(text.slice(i + 1))\n        ? { kind: 'list', items }\n        : unsupported('text follows the end of an inline list');\n    }\n    if (ch === '[' || ch === '{') return unsupported('nested lists and mappings are not supported');\n    if (ch === ',') return unsupported('an inline list has an empty item');\n    let item: YamlScalar;\n    if (ch === '\"' || ch === \"'\") {\n      const rest = text.slice(i);\n      const quoted = ch === '\"' ? readDoubleQuoted(rest) : readSingleQuoted(rest);\n      if (typeof quoted === 'string') return unsupported(quoted);\n      item = { text: quoted.text, quoted: true };\n      i += quoted.next;\n    } else {\n      let j = i;\n      while (j < text.length && !',]'.includes(text.charAt(j))) j += 1;\n      const plain = text.slice(i, j).trim();\n      if (/[[{]/.test(plain) || /:(?:\\s|$)/.test(plain) || plain.includes(' #')) {\n        return unsupported(`\"${plain}\" needs quoting inside an inline list`);\n      }\n      item = { text: plain, quoted: false };\n      i = j;\n    }\n    items.push(item);\n    while (i < text.length && /\\s/.test(text.charAt(i))) i += 1;\n    if (i >= text.length) return unsupported('an inline list is never closed; keep it on one line');\n    // After a comma the next pass reads an item or, legally in YAML, the bracket.\n    if (text.charAt(i) === ',') i += 1;\n    else if (text.charAt(i) !== ']') return unsupported('inline list items must be separated by commas');\n  }\n}\n\n/** Null in the YAML 1.2 core schema: empty, `~` or `null` in any of its three spellings. */\nexport function isNull(scalar: YamlScalar): boolean {\n  return !scalar.quoted && ['', '~', 'null', 'Null', 'NULL'].includes(scalar.text);\n}\n\n/** Renders a string as a scalar that reads back as the same string. */\nexport function renderScalar(value: string): string {\n  const reserved = /^(?:true|false|null|yes|no|on|off|~)$/i.test(value);\n  const plain = /^[A-Za-z][A-Za-z0-9 ._/+-]*$/.test(value) && !value.endsWith(' ');\n  return plain && !reserved ? value : JSON.stringify(value);\n}\n\nexport function findEntry(frontMatter: FrontMatter | null, key: string): FrontMatterEntry | undefined {\n  const name = keyName(key);\n  return frontMatter?.entries.find((entry) => entry.name === name);\n}\n\n/**\n * Sets one key, leaving every other line as it was. An existing entry keeps the\n * spelling of its key; a new one goes last. A file with no front matter gains\n * a block.\n */\nexport function setEntry(\n  lines: readonly string[],\n  frontMatter: FrontMatter | null,\n  key: string,\n  rendered: string,\n): string[] {\n  if (frontMatter === null) return ['---', `${key}: ${rendered}`, '---', ...lines];\n  if (frontMatter.close < 0) throw new Error('cannot edit front matter that is never closed');\n  const entry = findEntry(frontMatter, key);\n  if (entry === undefined) {\n    return [...lines.slice(0, frontMatter.close), `${key}: ${rendered}`, ...lines.slice(frontMatter.close)];\n  }\n  return [...lines.slice(0, entry.line), `${entry.key}: ${rendered}`, ...lines.slice(entry.end)];\n}\n\n/** Removes one key and its value lines; a key that is absent changes nothing. */\nexport function removeEntry(lines: readonly string[], frontMatter: FrontMatter | null, key: string): string[] {\n  const entry = findEntry(frontMatter, key);\n  if (entry === undefined) return [...lines];\n  return [...lines.slice(0, entry.line), ...lines.slice(entry.end)];\n}\n"]}

package/dist/fs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The filesystem, behind an interface.
+ *
+ * Every path crossing this boundary is repository-relative and POSIX; the
+ * Node implementation is the only place a host path exists. The in-memory
+ * implementation is not a test double bolted on afterwards: it is how a
+ * harness asks "what would archiving this do" against files that were never
+ * written, and how the transaction's rollback is exercised with a failure on
+ * exactly the operation that matters.
+ */
+export interface FileSystem {
+    /** Contents, or `null` when there is no such file. */
+    read(path: string): Promise<string | null>;
+    /** Writes a file, creating its directory. Replaces an existing file atomically where the platform allows. */
+    write(path: string, content: string): Promise<void>;
+    /** Removes a file. Removing a file that is absent is an error. */
+    remove(path: string): Promise<void>;
+    /** Names of the files directly inside a directory, or `null` when it does not exist. */
+    list(directory: string): Promise<string[] | null>;
+    /** Every file beneath the root, as sorted repository-relative paths, skipping {@link IGNORED_DIRECTORIES}. */
+    walk(): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}
+/**
+ * The path as the filesystem names it: links and junctions followed, and on
+ * Windows short names such as `RUNNER~1` expanded. Git reports the top of a
+ * work tree this way, so a root compared with it has to be named the same.
+ * A path that does not exist is returned as given, for the caller to report.
+ */
+export declare function canonicalPath(path: string): Promise<string>;
+/** Directories a walk never enters: build output and other tools' state. */
+export declare const IGNORED_DIRECTORIES: ReadonlySet<string>;
+export declare class NodeFileSystem implements FileSystem {
+    readonly root: string;
+    constructor(root: string);
+    private host;
+    read(path: string): Promise<string | null>;
+    write(path: string, content: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    list(directory: string): Promise<string[] | null>;
+    walk(): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}
+export type FileOperation = 'write' | 'remove';
+/**
+ * Files in a `Map`. `fail` lets a test make one chosen operation throw, which
+ * is the only honest way to prove a rollback restores what it claims to.
+ */
+export declare class MemoryFileSystem implements FileSystem {
+    readonly files: Map<string, string>;
+    fail: ((operation: FileOperation, path: string) => boolean) | undefined;
+    constructor(files?: Readonly<Record<string, string>>);
+    read(path: string): Promise<string | null>;
+    write(path: string, content: string): Promise<void>;
+    remove(path: string): Promise<void>;
+    list(directory: string): Promise<string[] | null>;
+    walk(): Promise<string[]>;
+    exists(path: string): Promise<boolean>;
+}

package/dist/fs.js

@@ -0,0 +1,189 @@
+/**
+ * The filesystem, behind an interface.
+ *
+ * Every path crossing this boundary is repository-relative and POSIX; the
+ * Node implementation is the only place a host path exists. The in-memory
+ * implementation is not a test double bolted on afterwards: it is how a
+ * harness asks "what would archiving this do" against files that were never
+ * written, and how the transaction's rollback is exercised with a failure on
+ * exactly the operation that matters.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { normalisePath as repoPath } from './links.js';
+/**
+ * The path as the filesystem names it: links and junctions followed, and on
+ * Windows short names such as `RUNNER~1` expanded. Git reports the top of a
+ * work tree this way, so a root compared with it has to be named the same.
+ * A path that does not exist is returned as given, for the caller to report.
+ */
+export async function canonicalPath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return path;
+    }
+}
+/** Directories a walk never enters: build output and other tools' state. */
+export const IGNORED_DIRECTORIES = new Set([
+    '.git',
+    '.hg',
+    '.svn',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    'target',
+    '.venv',
+    '__pycache__',
+    '.stryker-tmp',
+]);
+/** Errors a rename on Windows raises while another process briefly holds the file. */
+const TRANSIENT = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const RENAME_ATTEMPTS = 6;
+async function pause(ms) {
+    await new Promise((done) => setTimeout(done, ms));
+}
+export class NodeFileSystem {
+    root;
+    constructor(root) {
+        this.root = resolve(root);
+    }
+    host(path) {
+        const normal = repoPath(path);
+        return normal === '' ? this.root : join(this.root, ...normal.split('/'));
+    }
+    async read(path) {
+        try {
+            return await readFile(this.host(path), 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    }
+    async write(path, content) {
+        const target = this.host(path);
+        await mkdir(dirname(target), { recursive: true });
+        // Written beside the target and renamed over it, so a reader never sees half a file.
+        const temporary = join(dirname(target), `.${randomBytes(6).toString('hex')}.spec-brief.tmp`);
+        await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });
+        try {
+            for (let attempt = 1;; attempt += 1) {
+                try {
+                    await rename(temporary, target);
+                    return;
+                }
+                catch (error) {
+                    const code = error.code ?? '';
+                    if (!TRANSIENT.has(code) || attempt >= RENAME_ATTEMPTS)
+                        throw error;
+                    await pause(15 * attempt);
+                }
+            }
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw error;
+        }
+    }
+    async remove(path) {
+        await rm(this.host(path));
+    }
+    async list(directory) {
+        try {
+            const entries = await readdir(this.host(directory), { withFileTypes: true });
+            return entries.filter((e) => e.isFile()).map((e) => e.name);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return null;
+            /* v8 ignore next -- a permission error, which a portable test cannot provoke; it must not read as "no briefs". */
+            throw error;
+        }
+    }
+    async walk() {
+        const found = [];
+        const visit = async (directory) => {
+            const entries = await readdir(directory, { withFileTypes: true });
+            for (const entry of entries) {
+                const full = join(directory, entry.name);
+                if (entry.isDirectory()) {
+                    if (!IGNORED_DIRECTORIES.has(entry.name))
+                        await visit(full);
+                }
+                else if (entry.isFile()) {
+                    found.push(relative(this.root, full).split(sep).join('/'));
+                }
+            }
+        };
+        await visit(this.root);
+        return found.sort();
+    }
+    async exists(path) {
+        try {
+            await stat(this.host(path));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+/**
+ * Files in a `Map`. `fail` lets a test make one chosen operation throw, which
+ * is the only honest way to prove a rollback restores what it claims to.
+ */
+export class MemoryFileSystem {
+    files;
+    fail;
+    constructor(files = {}) {
+        this.files = new Map(Object.entries(files).map(([path, content]) => [repoPath(path), content]));
+        this.fail = undefined;
+    }
+    read(path) {
+        return Promise.resolve(this.files.get(repoPath(path)) ?? null);
+    }
+    write(path, content) {
+        const normal = repoPath(path);
+        if (this.fail?.('write', normal) === true)
+            return Promise.reject(new Error(`injected failure writing ${normal}`));
+        this.files.set(normal, content);
+        return Promise.resolve();
+    }
+    remove(path) {
+        const normal = repoPath(path);
+        if (this.fail?.('remove', normal) === true)
+            return Promise.reject(new Error(`injected failure removing ${normal}`));
+        if (!this.files.delete(normal))
+            return Promise.reject(new Error(`${normal} does not exist`));
+        return Promise.resolve();
+    }
+    list(directory) {
+        const prefix = repoPath(directory);
+        const names = [];
+        let isDirectory = prefix === '';
+        for (const path of this.files.keys()) {
+            if (prefix !== '' && !path.startsWith(`${prefix}/`))
+                continue;
+            isDirectory = true;
+            const rest = prefix === '' ? path : path.slice(prefix.length + 1);
+            if (!rest.includes('/'))
+                names.push(rest);
+        }
+        return Promise.resolve(isDirectory ? names.sort() : null);
+    }
+    walk() {
+        const paths = [...this.files.keys()].filter((path) => !path.split('/').some((part) => IGNORED_DIRECTORIES.has(part)));
+        return Promise.resolve(paths.sort());
+    }
+    exists(path) {
+        const normal = repoPath(path);
+        return Promise.resolve(this.files.has(normal) || [...this.files.keys()].some((p) => normal === '' || p.startsWith(`${normal}/`)));
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The filesystem, behind an interface.\n *\n * Every path crossing this boundary is repository-relative and POSIX; the\n * Node implementation is the only place a host path exists. The in-memory\n * implementation is not a test double bolted on afterwards: it is how a\n * harness asks \"what would archiving this do\" against files that were never\n * written, and how the transaction's rollback is exercised with a failure on\n * exactly the operation that matters.\n */\n\nimport { randomBytes } from 'node:crypto';\nimport { mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';\nimport { dirname, join, relative, resolve, sep } from 'node:path';\n\nimport { normalisePath as repoPath } from './links.js';\n\nexport interface FileSystem {\n  /** Contents, or `null` when there is no such file. */\n  read(path: string): Promise<string | null>;\n  /** Writes a file, creating its directory. Replaces an existing file atomically where the platform allows. */\n  write(path: string, content: string): Promise<void>;\n  /** Removes a file. Removing a file that is absent is an error. */\n  remove(path: string): Promise<void>;\n  /** Names of the files directly inside a directory, or `null` when it does not exist. */\n  list(directory: string): Promise<string[] | null>;\n  /** Every file beneath the root, as sorted repository-relative paths, skipping {@link IGNORED_DIRECTORIES}. */\n  walk(): Promise<string[]>;\n  exists(path: string): Promise<boolean>;\n}\n\n/**\n * The path as the filesystem names it: links and junctions followed, and on\n * Windows short names such as `RUNNER~1` expanded. Git reports the top of a\n * work tree this way, so a root compared with it has to be named the same.\n * A path that does not exist is returned as given, for the caller to report.\n */\nexport async function canonicalPath(path: string): Promise<string> {\n  try {\n    return await realpath(path);\n  } catch {\n    return path;\n  }\n}\n\n/** Directories a walk never enters: build output and other tools' state. */\nexport const IGNORED_DIRECTORIES: ReadonlySet<string> = new Set([\n  '.git',\n  '.hg',\n  '.svn',\n  'node_modules',\n  'dist',\n  'build',\n  'coverage',\n  'target',\n  '.venv',\n  '__pycache__',\n  '.stryker-tmp',\n]);\n\n/** Errors a rename on Windows raises while another process briefly holds the file. */\nconst TRANSIENT = new Set(['EPERM', 'EACCES', 'EBUSY']);\nconst RENAME_ATTEMPTS = 6;\n\nasync function pause(ms: number): Promise<void> {\n  await new Promise((done) => setTimeout(done, ms));\n}\n\nexport class NodeFileSystem implements FileSystem {\n  readonly root: string;\n\n  constructor(root: string) {\n    this.root = resolve(root);\n  }\n\n  private host(path: string): string {\n    const normal = repoPath(path);\n    return normal === '' ? this.root : join(this.root, ...normal.split('/'));\n  }\n\n  async read(path: string): Promise<string | null> {\n    try {\n      return await readFile(this.host(path), 'utf8');\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;\n      throw error;\n    }\n  }\n\n  async write(path: string, content: string): Promise<void> {\n    const target = this.host(path);\n    await mkdir(dirname(target), { recursive: true });\n    // Written beside the target and renamed over it, so a reader never sees half a file.\n    const temporary = join(dirname(target), `.${randomBytes(6).toString('hex')}.spec-brief.tmp`);\n    await writeFile(temporary, content, { encoding: 'utf8', flag: 'wx' });\n    try {\n      for (let attempt = 1; ; attempt += 1) {\n        try {\n          await rename(temporary, target);\n          return;\n        } catch (error) {\n          const code = (error as NodeJS.ErrnoException).code ?? '';\n          if (!TRANSIENT.has(code) || attempt >= RENAME_ATTEMPTS) throw error;\n          await pause(15 * attempt);\n        }\n      }\n    } catch (error) {\n      await rm(temporary, { force: true });\n      throw error;\n    }\n  }\n\n  async remove(path: string): Promise<void> {\n    await rm(this.host(path));\n  }\n\n  async list(directory: string): Promise<string[] | null> {\n    try {\n      const entries = await readdir(this.host(directory), { withFileTypes: true });\n      return entries.filter((e) => e.isFile()).map((e) => e.name);\n    } catch (error) {\n      const code = (error as NodeJS.ErrnoException).code;\n      if (code === 'ENOENT' || code === 'ENOTDIR') return null;\n      /* v8 ignore next -- a permission error, which a portable test cannot provoke; it must not read as \"no briefs\". */\n      throw error;\n    }\n  }\n\n  async walk(): Promise<string[]> {\n    const found: string[] = [];\n    const visit = async (directory: string): Promise<void> => {\n      const entries = await readdir(directory, { withFileTypes: true });\n      for (const entry of entries) {\n        const full = join(directory, entry.name);\n        if (entry.isDirectory()) {\n          if (!IGNORED_DIRECTORIES.has(entry.name)) await visit(full);\n        } else if (entry.isFile()) {\n          found.push(relative(this.root, full).split(sep).join('/'));\n        }\n      }\n    };\n    await visit(this.root);\n    return found.sort();\n  }\n\n  async exists(path: string): Promise<boolean> {\n    try {\n      await stat(this.host(path));\n      return true;\n    } catch {\n      return false;\n    }\n  }\n}\n\nexport type FileOperation = 'write' | 'remove';\n\n/**\n * Files in a `Map`. `fail` lets a test make one chosen operation throw, which\n * is the only honest way to prove a rollback restores what it claims to.\n */\nexport class MemoryFileSystem implements FileSystem {\n  readonly files: Map<string, string>;\n  fail: ((operation: FileOperation, path: string) => boolean) | undefined;\n\n  constructor(files: Readonly<Record<string, string>> = {}) {\n    this.files = new Map(Object.entries(files).map(([path, content]) => [repoPath(path), content]));\n    this.fail = undefined;\n  }\n\n  read(path: string): Promise<string | null> {\n    return Promise.resolve(this.files.get(repoPath(path)) ?? null);\n  }\n\n  write(path: string, content: string): Promise<void> {\n    const normal = repoPath(path);\n    if (this.fail?.('write', normal) === true) return Promise.reject(new Error(`injected failure writing ${normal}`));\n    this.files.set(normal, content);\n    return Promise.resolve();\n  }\n\n  remove(path: string): Promise<void> {\n    const normal = repoPath(path);\n    if (this.fail?.('remove', normal) === true) return Promise.reject(new Error(`injected failure removing ${normal}`));\n    if (!this.files.delete(normal)) return Promise.reject(new Error(`${normal} does not exist`));\n    return Promise.resolve();\n  }\n\n  list(directory: string): Promise<string[] | null> {\n    const prefix = repoPath(directory);\n    const names: string[] = [];\n    let isDirectory = prefix === '';\n    for (const path of this.files.keys()) {\n      if (prefix !== '' && !path.startsWith(`${prefix}/`)) continue;\n      isDirectory = true;\n      const rest = prefix === '' ? path : path.slice(prefix.length + 1);\n      if (!rest.includes('/')) names.push(rest);\n    }\n    return Promise.resolve(isDirectory ? names.sort() : null);\n  }\n\n  walk(): Promise<string[]> {\n    const paths = [...this.files.keys()].filter((path) => !path.split('/').some((part) => IGNORED_DIRECTORIES.has(part)));\n    return Promise.resolve(paths.sort());\n  }\n\n  exists(path: string): Promise<boolean> {\n    const normal = repoPath(path);\n    return Promise.resolve(\n      this.files.has(normal) || [...this.files.keys()].some((p) => normal === '' || p.startsWith(`${normal}/`)),\n    );\n  }\n}\n"]}