@asrunjs/asrun 0.0.0-stage → 0.5.2

package/dist/lib/case-doc.js

@@ -0,0 +1,1117 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { NAME_PATTERN } from './case-id.js';
+export const STEP_TAGS = ['writes', 'input', 'email'];
+/** The fields every card must have; `pnpm case:check` fails without them. Kept here (pure) for the web panel. */
+export const TARGET_REQUIRED_FIELDS = ['what', 'where', 'identified by'];
+/* ------------------------------------------------------------------ parsing */
+/**
+ * The body of `## <name>`: exactly the regex every reader used before this module existed
+ * (`lib/values.ts`, `lib/targets.ts`, `scripts/check-cases.ts`), so behaviour does not change.
+ */
+export function caseSectionText(text, name) {
+    return caseSectionMatch(text, name)?.body ?? '';
+}
+/** The body of `## <name>` plus the offset it starts at, for parsers that report file line numbers. */
+function caseSectionMatch(text, name) {
+    const match = new RegExp(`^## ${name}\\s*$([\\s\\S]*?)(?=^## |(?![\\s\\S]))`, 'm').exec(text);
+    if (!match)
+        return null;
+    return { body: match[1], bodyStart: match.index + match[0].length - match[1].length };
+}
+/** The 1-based line number of one offset of the document. */
+function lineNumberAt(text, offset) {
+    let line = 1;
+    for (let at = text.indexOf('\n'); at >= 0 && at < offset; at = text.indexOf('\n', at + 1))
+        line++;
+    return line;
+}
+export function splitLines(text) {
+    const lines = [];
+    const breaks = /\r?\n/g;
+    let start = 0;
+    let number = 1;
+    let match;
+    while ((match = breaks.exec(text)) !== null) {
+        lines.push({ number: number++, start, end: match.index, text: text.slice(start, match.index) });
+        start = match.index + match[0].length;
+    }
+    lines.push({ number, start, end: text.length, text: text.slice(start) });
+    return lines;
+}
+/** Offset just after the line break that starts at `end` (or `end` itself at the end of the file). */
+export function endWithBreak(text, end) {
+    if (text.startsWith('\r\n', end))
+        return end + 2;
+    if (text.startsWith('\n', end))
+        return end + 1;
+    return end;
+}
+/** Offset just after the line break of `line` (also when the line is the last one, without a break). */
+export const afterLine = (text, line) => endWithBreak(text, line.end);
+const isBlank = (text) => text.trim() === '';
+const indentOf = (text) => /^[ \t]*/.exec(text)?.[0].length ?? 0;
+/** Does the line open or close a fenced code block? */
+const isFence = (text) => /^[ \t]*```/.test(text);
+function sectionsOf(text, lines) {
+    const headings = lines
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => /^##[ \t]+\S/.test(line.text));
+    return headings.map(({ line }, index) => ({
+        name: line.text.replace(/^##[ \t]+/, '').trim(),
+        headingStart: line.start,
+        body: {
+            start: afterLine(text, line),
+            end: headings[index + 1]?.line.start ?? text.length,
+        },
+    }));
+}
+const sectionAt = (sections, offset) => sections.find((section) => offset >= section.body.start && offset < section.body.end)?.name ?? '';
+/** The lines of one section, and whether they are inside a fenced code block. */
+function sectionLines(text, section) {
+    const result = [];
+    let fenced = false;
+    for (const line of splitLines(text)) {
+        if (line.start < section.body.start)
+            continue;
+        if (line.start >= section.body.end)
+            break;
+        result.push({ line, fenced });
+        if (isFence(line.text))
+            fenced = !fenced;
+    }
+    return result;
+}
+/** The front matter block: its parsed data plus the range of every key, so the panel can edit one key at a time. */
+export function parseCaseFrontMatter(text) {
+    const lines = splitLines(text);
+    if (lines.length === 0 || lines[0].text.trim() !== '---')
+        return null;
+    const closeIndex = lines.findIndex((line, index) => index > 0 && line.text.trim() === '---');
+    if (closeIndex < 0)
+        return null;
+    const raw = text.slice(afterLine(text, lines[0]), lines[closeIndex].start);
+    let data = {};
+    let problem = null;
+    try {
+        const parsed = parseYaml(raw);
+        if (parsed === null || parsed === undefined) {
+            data = {};
+        }
+        else if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+            // The old reader treated a non-map front matter as "no front matter"; keep that reading.
+            return null;
+        }
+        else {
+            data = parsed;
+        }
+    }
+    catch (error) {
+        problem = `the front matter is not valid yaml: ${error.message}`;
+    }
+    const entries = [];
+    let index = 1;
+    while (index < closeIndex) {
+        const line = lines[index];
+        const match = /^([A-Za-z][A-Za-z0-9_-]*)[ \t]*:(.*)$/.exec(line.text);
+        if (!match) {
+            index++;
+            continue;
+        }
+        let last = index;
+        for (let next = index + 1; next < closeIndex; next++) {
+            const candidate = lines[next];
+            if (candidate.text.trim() !== '' && indentOf(candidate.text) === 0)
+                break;
+            if (candidate.text.trim() !== '')
+                last = next;
+        }
+        const block = last > index;
+        const colon = line.text.indexOf(':');
+        let valueStart = colon + 1;
+        while (line.text[valueStart] === ' ' || line.text[valueStart] === '\t')
+            valueStart++;
+        let valueRange;
+        if (block) {
+            valueRange = { start: afterLine(text, line), end: lines[last].end };
+        }
+        else {
+            valueRange = { start: line.start + valueStart, end: scalarEnd(line, valueStart) };
+        }
+        entries.push({
+            key: match[1],
+            value: data[match[1]],
+            range: { start: line.start, end: lines[last].end },
+            valueRange,
+            line: line.number,
+            block,
+        });
+        index = last + 1;
+    }
+    return {
+        data,
+        entries,
+        range: { start: lines[0].start, end: lines[closeIndex].end },
+        insertAt: afterLine(text, lines[0]),
+        problem,
+    };
+}
+/** End of a scalar or flow value on its line: before a ` #` comment, or after the closing quote/bracket. */
+function scalarEnd(line, from) {
+    const text = line.text;
+    const quote = text[from];
+    if (quote === '"' || quote === "'") {
+        for (let index = from + 1; index < text.length; index++) {
+            if (text[index] === '\\' && quote === '"')
+                index++;
+            else if (text[index] === quote)
+                return line.start + index + 1;
+        }
+        return line.end;
+    }
+    if (quote === '[' || quote === '{') {
+        const close = quote === '[' ? ']' : '}';
+        let depth = 0;
+        let inner = '';
+        for (let index = from; index < text.length; index++) {
+            const character = text[index];
+            if (inner === '' && (character === '"' || character === "'"))
+                inner = character;
+            else if (inner !== '' && character === inner)
+                inner = '';
+            else if (inner === '' && character === quote)
+                depth++;
+            else if (inner === '' && character === close) {
+                depth--;
+                if (depth === 0)
+                    return line.start + index + 1;
+            }
+        }
+        return line.end;
+    }
+    const comment = text.indexOf(' #', from);
+    let end = comment >= 0 ? comment : text.length;
+    while (end > from && (text[end - 1] === ' ' || text[end - 1] === '\t'))
+        end--;
+    return line.start + end;
+}
+const STEP_RE = /^(\d+)\.([ \t]+)(.*)$/;
+const STEP_TAIL_RE = /(?:[ \t]*\[(writes|input|email)\])+[ \t]*$/;
+/** A recipe line under a step: `- Recipe:` or `- Recipe (start): ...` (case-insensitive on the word). */
+const RECIPE_RE = /^([ \t]*)[-*+][ \t]+recipe(?:[ \t]*\(([^)]*)\))?[ \t]*:(.*)$/i;
+/** A readiness line under a step: `- Ready when: ...` (case-insensitive on the words). */
+const READY_RE = /^([ \t]*)[-*+][ \t]+ready\s+when[ \t]*:(.*)$/i;
+function parseSteps(text, section) {
+    if (!section)
+        return [];
+    const lines = sectionLines(text, section);
+    const steps = [];
+    for (let index = 0; index < lines.length; index++) {
+        const { line, fenced } = lines[index];
+        if (fenced)
+            continue;
+        const match = STEP_RE.exec(line.text);
+        if (!match)
+            continue;
+        // A wrapped step continues on the indented lines under it, up to its first nested bullet (a recipe or TODO block).
+        let last = index;
+        for (let next = index + 1; next < lines.length; next++) {
+            const nextLine = lines[next].line;
+            if (isBlank(nextLine.text) || indentOf(nextLine.text) <= indentOf(line.text))
+                break;
+            if (isListItem(nextLine.text))
+                break;
+            last = next;
+        }
+        // The nested block (recipes and TODO blocks) runs through the indented lines that follow, up to a blank line or a
+        // line at the step's own indent.
+        let blockLast = last;
+        for (let next = last + 1; next < lines.length; next++) {
+            const nextLine = lines[next].line;
+            if (isBlank(nextLine.text) || indentOf(nextLine.text) <= indentOf(line.text))
+                break;
+            blockLast = next;
+        }
+        const bodyStart = match[1].length + 1 + match[2].length;
+        const raw = [line.text.slice(bodyStart), ...lines.slice(index + 1, last + 1).map(({ line: next }) => next.text.trim())]
+            .filter((part) => part !== '')
+            .join(' ');
+        const tags = [];
+        let textEnd = raw.length;
+        const tail = STEP_TAIL_RE.exec(raw);
+        if (tail) {
+            for (const tag of tail[0].matchAll(/\[(writes|input|email)\]/g))
+                tags.push(tag[1]);
+            textEnd = tail.index;
+        }
+        const lastLine = lines[last].line;
+        const insertAt = lastLine.start + lastLine.text.replace(/[ \t]+$/, '').length;
+        const tailLength = tail ? tail[0].length : 0;
+        const nested = parseStepBullets(lines, last + 1, blockLast);
+        steps.push({
+            number: Number(match[1]),
+            text: raw.slice(0, textEnd).replace(/[ \t]+$/, ''),
+            tags,
+            range: { start: line.start, end: lastLine.end },
+            textRange: { start: line.start + bodyStart, end: Math.max(line.start + bodyStart, insertAt - tailLength) },
+            insertAt,
+            line: line.number,
+            recipes: nested.recipes,
+            readiness: nested.readiness,
+        });
+        index = blockLast;
+    }
+    return steps;
+}
+/** One nested bullet under a step: its line, its last continuation line and the text after the colon. */
+function readNestedBullet(lines, at, to) {
+    const line = lines[at].line;
+    const indent = indentOf(line.text);
+    let last = at;
+    for (let next = at + 1; next <= to; next++) {
+        const nextLine = lines[next].line;
+        if (isBlank(nextLine.text) || isListItem(nextLine.text))
+            break;
+        if (indentOf(nextLine.text) <= indent)
+            break;
+        last = next;
+    }
+    const continuation = lines
+        .slice(at + 1, last + 1)
+        .map(({ line: nextLine }) => nextLine.text.trim())
+        .filter((part) => part !== '');
+    return {
+        line,
+        last,
+        /** Offset of the first character of `raw` (the text after the colon) in the document. */
+        textStart: (raw) => line.start + line.text.length - raw.length + (raw.length - raw.trimStart().length),
+        /** `raw` with its wrapped lines joined. */
+        text: (raw) => [raw.trim(), ...continuation].filter((part) => part !== '').join(' '),
+        end: lines[last].line.end,
+    };
+}
+/** The `- Recipe (...): ...` and `- Ready when: ...` bullets of one step, from the first nested line to the last one. */
+function parseStepBullets(lines, from, to) {
+    const recipes = [];
+    const readiness = [];
+    for (let at = from; at <= to; at++) {
+        if (lines[at].fenced)
+            continue;
+        const recipe = RECIPE_RE.exec(lines[at].line.text);
+        const ready = recipe ? null : READY_RE.exec(lines[at].line.text);
+        if (!recipe && !ready)
+            continue;
+        const bullet = readNestedBullet(lines, at, to);
+        if (recipe) {
+            const label = (recipe[2] ?? '').trim();
+            recipes.push({
+                what: label === '' ? null : label,
+                text: bullet.text(recipe[3]),
+                line: bullet.line.number,
+                range: { start: bullet.line.start, end: bullet.end },
+                textRange: { start: bullet.textStart(recipe[3]), end: bullet.end },
+            });
+        }
+        else if (ready) {
+            readiness.push({
+                text: bullet.text(ready[2]),
+                line: bullet.line.number,
+                range: { start: bullet.line.start, end: bullet.end },
+                textRange: { start: bullet.textStart(ready[2]), end: bullet.end },
+            });
+        }
+        at = bullet.last;
+    }
+    return { recipes, readiness };
+}
+/* A question block: `- ❓ TODO [non-blocking]: <question> (evidence)` with `- ✍️ Answer:` one level deeper. The emoji is
+ * part of the marker; a block without a tag is the old form and counts as blocking (see the open-questions reference).
+ * A question may wrap over several lines; its block ends at the first blank line or at a line that is not indented
+ * deeper than the question. */
+const QUESTION_RE = /^([ \t]*)[-*+][ \t]+(?:(\u{1F6AB}|\u{2753})\uFE0F?[ \t]*)?to[-_]?dos?\b[ \t]*(?:\[(blocking|non-blocking)\])?[ \t]*:?[ \t]*(.*)$/iu;
+const ANSWER_RE = /^([ \t]*)[-*+][ \t]+(?:\u270D\uFE0F?[ \t]*)?answer[ \t]*:(.*)$/iu;
+const EVIDENCE_RE = /^(.*?)[ \t]*\(([^()]*)\)[ \t]*$/;
+const HEADING_RE = /^##[ \t]+\S/;
+const LIST_ITEM_RE = /^[ \t]*(?:[-*+]|\d+\.)[ \t]+/;
+const isListItem = (text) => LIST_ITEM_RE.test(text);
+/** A bullet's text without its marker (`- `, `* `, `+ `); a numbered item keeps its number, and other lines come back unchanged. */
+const withoutMarker = (text) => text.replace(/^[ \t]*[-*+][ \t]+/, '');
+/**
+ * The text a question hangs under: one list item or one paragraph above it, wrapped lines joined. The nearest line with
+ * the same or a smaller indent is the anchor; a heading, a code fence or a blank line above the question means there is
+ * none (an accept would then delete a claim nobody sees, so the panel refuses it).
+ */
+function parentOf(lines, index, indent) {
+    // The nearest line above that can start the text: a heading, a fence or a blank line means there is none.
+    let candidate = -1;
+    for (let i = index - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (isBlank(line.text) || HEADING_RE.test(line.text) || isFence(line.text))
+            return null;
+        if (indentOf(line.text) > indent)
+            continue; // a wrapped line or a nested block above: look higher
+        if (QUESTION_RE.test(line.text) || ANSWER_RE.test(line.text))
+            continue; // another question at this level
+        candidate = i;
+        break;
+    }
+    if (candidate < 0)
+        return null;
+    // Extend to the outermost list item that holds it, or to the start of the paragraph.
+    let start = candidate;
+    if (isListItem(lines[start].text)) {
+        while (start > 0) {
+            const previous = lines[start - 1];
+            if (isBlank(previous.text) || HEADING_RE.test(previous.text) || isFence(previous.text))
+                break;
+            if (!isListItem(previous.text))
+                break; // a paragraph above a list is another block
+            if (indentOf(previous.text) >= indentOf(lines[start].text))
+                break; // a sibling item
+            start--;
+        }
+    }
+    else {
+        while (start > 0) {
+            const previous = lines[start - 1];
+            if (isBlank(previous.text) || HEADING_RE.test(previous.text) || isFence(previous.text))
+                break;
+            if (QUESTION_RE.test(previous.text) || ANSWER_RE.test(previous.text))
+                break;
+            if (isListItem(previous.text)) {
+                if (indentOf(previous.text) < indentOf(lines[start].text))
+                    start--;
+                break;
+            }
+            start--;
+        }
+    }
+    // Wrapped lines between the start and the question belong to the same item/paragraph; a nested bullet does not.
+    const parts = [withoutMarker(lines[start].text).trim()];
+    for (let i = start + 1; i < index; i++) {
+        if (isListItem(lines[i].text))
+            continue;
+        if (QUESTION_RE.test(lines[i].text) || ANSWER_RE.test(lines[i].text))
+            continue;
+        parts.push(lines[i].text.trim());
+    }
+    const text = parts.filter((part) => part !== '').join(' ').trim();
+    return text === '' ? null : { text, line: lines[start].number, from: lines[start].start };
+}
+function parseQuestions(text, sections) {
+    const lines = splitLines(text);
+    const questions = [];
+    let fenced = false;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (isFence(line.text)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        const match = QUESTION_RE.exec(line.text);
+        if (!match)
+            continue;
+        const indent = indentOf(line.text);
+        const kind = match[3] === 'non-blocking' || (match[3] === undefined && match[2] === '\u2753') ? 'non-blocking' : 'blocking';
+        // The block runs through the following lines that are indented deeper: the answer line and any wrapped lines.
+        let last = index;
+        for (let next = index + 1; next < lines.length; next++) {
+            if (isBlank(lines[next].text) || indentOf(lines[next].text) <= indent)
+                break;
+            last = next;
+        }
+        // The question is the marker line plus its plain continuation lines, up to the answer line or a nested bullet.
+        const parts = [match[4].trim()];
+        let answer = null;
+        let answerRange = null;
+        let answerLine = null;
+        for (let next = index + 1; next <= last; next++) {
+            const nextLine = lines[next];
+            const answerMatch = ANSWER_RE.exec(nextLine.text);
+            if (answerMatch) {
+                answer = answerMatch[2].trim();
+                answerRange = { start: nextLine.start + nextLine.text.length - answerMatch[2].length, end: nextLine.end };
+                answerLine = nextLine.number;
+                break;
+            }
+            if (isListItem(nextLine.text))
+                break;
+            parts.push(nextLine.text.trim());
+        }
+        const raw = parts.filter((part) => part !== '').join(' ').trim();
+        const evidenceMatch = EVIDENCE_RE.exec(raw);
+        const question = (evidenceMatch ? evidenceMatch[1] : raw).trim();
+        const evidence = evidenceMatch ? evidenceMatch[2].trim() : null;
+        const parent = parentOf(lines, index, indent);
+        questions.push({
+            kind,
+            question,
+            evidence,
+            parent,
+            section: sectionAt(sections, line.start),
+            line: line.number,
+            indent,
+            answer: answer ?? '',
+            answerRange: answerRange ?? { start: lines[last].end, end: lines[last].end },
+            hasAnswerLine: answerLine !== null,
+            answerLine,
+            lastLine: lines[last].number,
+            blockRange: { start: line.start, end: lines[last].end },
+            region: { start: parent?.from ?? line.start, end: lines[last].end },
+        });
+    }
+    return questions;
+}
+/* Kept in step with `ui/web/src/lib/highlight-keywords.ts` (same words, same emoji prefixes). */
+const MARKER_RE = /(?:\u{1F50D}\uFE0F?[ \t]*)?(?:\bto be confirmed(?:\s+by\s+QA)?\b|\bTBC\b|\bTBD\b|\bneeds?\s+confirmation\b)|(?:\u{1F441}\uFE0F?[ \t]*)?\bnot observed\b/giu;
+function parseMarkers(text, sections) {
+    const markers = [];
+    let fenced = false;
+    for (const line of splitLines(text)) {
+        if (isFence(line.text)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        for (const match of line.text.matchAll(MARKER_RE)) {
+            if (match[0] === '')
+                continue;
+            markers.push({
+                kind: /not observed/i.test(match[0]) ? 'unseen' : 'confirm',
+                text: match[0],
+                range: { start: line.start + (match.index ?? 0), end: line.start + (match.index ?? 0) + match[0].length },
+                sentence: line.text.trim(),
+                section: sectionAt(sections, line.start),
+                line: line.number,
+            });
+        }
+    }
+    return markers;
+}
+const VALUES_OPEN_RE = /^[ \t]*```ya?ml[ \t]*$/i;
+const VALUES_CLOSE_RE = /^[ \t]*```[ \t]*$/;
+const isPlaceholderValue = (value) => value === null || value === undefined || value === '' || (typeof value === 'string' && /^\s*TODO\b/i.test(value));
+function placeholdersOf(values) {
+    const found = [];
+    for (const [profile, entries] of Object.entries(values)) {
+        for (const [key, value] of Object.entries(entries)) {
+            if (isPlaceholderValue(value))
+                found.push(`${profile}.${key}`);
+        }
+    }
+    return found;
+}
+function parseValues(text, section) {
+    if (!section)
+        return null;
+    const noBlock = (problem) => ({
+        hasBlock: false,
+        range: { start: section.body.start, end: section.body.start },
+        values: {},
+        problem,
+        placeholders: [],
+    });
+    const lines = sectionLines(text, section);
+    const open = lines.findIndex(({ line }) => VALUES_OPEN_RE.test(line.text));
+    if (open < 0)
+        return noBlock('"## Values" must hold one fenced yaml block (```yaml ... ```)');
+    const close = lines.findIndex(({ line }, index) => index > open && VALUES_CLOSE_RE.test(line.text));
+    if (close < 0)
+        return noBlock('the yaml block of "## Values" is not closed with ```');
+    const range = { start: afterLine(text, lines[open].line), end: lines[close].line.start };
+    const raw = text.slice(range.start, range.end);
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (error) {
+        return { ...noBlock(`the yaml in "## Values" is not valid: ${error.message}`), range };
+    }
+    if (parsed === null || parsed === undefined) {
+        return { hasBlock: true, range, values: {}, problem: null, placeholders: [] };
+    }
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { ...noBlock('"## Values" must be a map of profile id (or "default") to a map of values'), range };
+    }
+    const values = {};
+    for (const [profile, entries] of Object.entries(parsed)) {
+        if (entries === null || typeof entries !== 'object' || Array.isArray(entries)) {
+            return { ...noBlock(`"## Values" entry "${profile}" must be a map of keys to values`), range };
+        }
+        values[profile] = entries;
+    }
+    return { hasBlock: true, range, values, problem: null, placeholders: placeholdersOf(values) };
+}
+const INPUT_RE = /^[-*+][ \t]+step[ \t]+(\d+)\b([^:]*):(.*)$/i;
+/**
+ * The lines of the old `## Inputs` section (kept for cases written before the recipes moved under their steps): one
+ * top-level bullet per recipe (`- Step 3 (start): ...`, several per step allowed) or per free note, with wrapped lines
+ * joined. Nested bullets are the TODO blocks that hang under a recipe and are not read here.
+ */
+function parseInputs(text, section) {
+    if (!section)
+        return [];
+    const lines = sectionLines(text, section);
+    const inputs = [];
+    let fenced = false;
+    for (let index = 0; index < lines.length; index++) {
+        const { line } = lines[index];
+        if (isFence(line.text)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced)
+            continue;
+        if (indentOf(line.text) > 0 || !isListItem(line.text))
+            continue;
+        if (QUESTION_RE.test(line.text) || ANSWER_RE.test(line.text))
+            continue;
+        let last = index;
+        for (let next = index + 1; next < lines.length; next++) {
+            const nextLine = lines[next].line;
+            if (isBlank(nextLine.text) || indentOf(nextLine.text) === 0)
+                break;
+            if (isListItem(nextLine.text) || QUESTION_RE.test(nextLine.text) || ANSWER_RE.test(nextLine.text))
+                break;
+            last = next;
+        }
+        const continuation = lines
+            .slice(index + 1, last + 1)
+            .map(({ line: nextLine }) => nextLine.text.trim())
+            .filter((part) => part !== '');
+        const match = INPUT_RE.exec(line.text);
+        if (match) {
+            const raw = match[3];
+            const label = match[2].trim().replace(/^\((.*)\)$/, '$1').trim();
+            inputs.push({
+                step: Number(match[1]),
+                what: label === '' ? null : label,
+                recipe: [raw.trim(), ...continuation].filter((part) => part !== '').join(' '),
+                line: line.number,
+                range: { start: line.start, end: lines[last].line.end },
+                recipeRange: {
+                    start: line.start + line.text.length - raw.length + (raw.length - raw.trimStart().length),
+                    end: lines[last].line.end,
+                },
+            });
+        }
+        else {
+            const withoutListMarker = withoutMarker(line.text);
+            inputs.push({
+                step: null,
+                what: null,
+                recipe: [withoutListMarker.trim(), ...continuation].filter((part) => part !== '').join(' '),
+                line: line.number,
+                range: { start: line.start, end: lines[last].line.end },
+                recipeRange: { start: line.start + (line.text.length - withoutListMarker.length), end: lines[last].line.end },
+            });
+        }
+        index = last;
+    }
+    return inputs;
+}
+/** A prose section (`## Goal`, `## Notes`): the panel renders it read-only and reveals a line on click. */
+export function parseProse(text, name) {
+    const section = sectionsOf(text, splitLines(text)).find((candidate) => candidate.name === name);
+    if (!section)
+        return null;
+    const body = text.slice(section.body.start, section.body.end);
+    const before = text.slice(0, section.body.start);
+    return {
+        name,
+        body,
+        range: section.body,
+        line: (before.match(/\n/g)?.length ?? 0) + 1,
+    };
+}
+/** The top-level bullets of a list section, with the blocks (a wrapped text, a TODO block) that belong to each. */
+export function parseBullets(text, name) {
+    const section = sectionsOf(text, splitLines(text)).find((candidate) => candidate.name === name);
+    if (!section)
+        return [];
+    const lines = sectionLines(text, section);
+    const bullets = [];
+    for (let index = 0; index < lines.length; index++) {
+        const { line, fenced } = lines[index];
+        if (fenced)
+            continue;
+        if (indentOf(line.text) > 0 || !isListItem(line.text))
+            continue;
+        if (QUESTION_RE.test(line.text) || ANSWER_RE.test(line.text))
+            continue;
+        // The block runs to the next top-level line; trailing blank lines are not part of it.
+        let last = index;
+        for (let next = index + 1; next < lines.length; next++) {
+            const nextLine = lines[next].line;
+            if (!isBlank(nextLine.text) && indentOf(nextLine.text) === 0)
+                break;
+            last = next;
+        }
+        while (last > index && isBlank(lines[last].line.text))
+            last--;
+        // The bullet's own text stops at its first nested bullet (a TODO block) or blank line.
+        let textLast = index;
+        for (let next = index + 1; next <= last; next++) {
+            const nextLine = lines[next].line;
+            if (isBlank(nextLine.text) || isListItem(nextLine.text))
+                break;
+            if (QUESTION_RE.test(nextLine.text) || ANSWER_RE.test(nextLine.text))
+                break;
+            textLast = next;
+        }
+        const marker = line.text.length - withoutMarker(line.text).length;
+        const parts = [withoutMarker(line.text).trim()];
+        for (let next = index + 1; next <= textLast; next++)
+            parts.push(lines[next].line.text.trim());
+        bullets.push({
+            text: parts.filter((part) => part !== '').join(' '),
+            range: { start: line.start, end: lines[last].line.end },
+            textRange: { start: line.start + marker, end: lines[textLast].line.end },
+            line: line.number,
+            questionLines: lines
+                .slice(index, last + 1)
+                .filter(({ line: candidate }) => QUESTION_RE.test(candidate.text))
+                .map(({ line: candidate }) => candidate.number),
+        });
+        index = last;
+    }
+    return bullets;
+}
+/** The `### T<n>` cards of `## Targets`. Pure, so the web panel can show a card name next to a visual check. */
+export function parseTargetCards(text) {
+    const section = caseSectionMatch(text, 'Targets');
+    if (!section)
+        return [];
+    const lines = splitLines(section.body);
+    const cards = [];
+    for (let index = 0; index < lines.length; index++) {
+        const heading = /^###\s+(T\d+)\b[\s:.-]*(.*)$/.exec(lines[index].text);
+        if (!heading)
+            continue;
+        let last = index;
+        for (let next = index + 1; next < lines.length; next++) {
+            if (/^###\s/.test(lines[next].text))
+                break;
+            last = next;
+        }
+        const card = {
+            id: heading[1],
+            name: heading[2].trim(),
+            fields: {},
+            references: {},
+            blocking: false,
+            line: lineNumberAt(text, section.bodyStart + lines[index].start),
+            range: { start: section.bodyStart + lines[index].start, end: section.bodyStart + lines[last].end },
+        };
+        for (let next = index + 1; next <= last; next++) {
+            const line = lines[next].text;
+            if (/^\s*-\s*\u{1F6AB} TODO \[blocking\]/u.test(line))
+                card.blocking = true;
+            const reference = /^-\s+Reference\s+([^:]+):\s*(.*)$/.exec(line);
+            if (reference) {
+                card.references[reference[1].trim()] = reference[2].trim();
+                continue;
+            }
+            const field = /^-\s+([A-Za-z][A-Za-z ]*?):\s*(.*)$/.exec(line);
+            if (field)
+                card.fields[field[1].trim().toLowerCase()] = field[2].trim();
+        }
+        cards.push(card);
+    }
+    return cards;
+}
+/* ------------------------------------------------------------- front matter */
+const META_ORDER = ['id', 'title', 'login', 'suites', 'writes', 'writes-note', 'envs'];
+function nameList(value, key, label) {
+    if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || !NAME_PATTERN.test(item))) {
+        throw new Error(`${label}: "${key}" must be a list of lowercase words (letters, digits, dashes), e.g. "${key}: [smoke, regression]"`);
+    }
+    const duplicate = value.find((item, i) => value.indexOf(item) !== i);
+    if (duplicate)
+        throw new Error(`${label}: "${key}" lists "${duplicate}" twice`);
+    return value;
+}
+function parseWrites(value, label, knownEnvs) {
+    if (value === undefined || value === null || value === 'none')
+        return [];
+    if (value === 'test-data') {
+        throw new Error(`${label}: "writes: test-data" is the old form. List the environments instead, e.g. "writes: [staging]"`);
+    }
+    if (Array.isArray(value) && value.length === 0)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new Error(`${label}: "writes" must be a list of environments, e.g. "writes: [staging]" (or omit it for read-only)`);
+    }
+    const writes = nameList(value, 'writes', label);
+    const unknown = writes.filter((env) => !knownEnvs.includes(env));
+    if (unknown.length > 0) {
+        throw new Error(`${label}: unknown environment(s) in "writes": ${unknown.join(', ')}. Known: ${knownEnvs.join(', ')}`);
+    }
+    return writes;
+}
+/** Parses and validates the front matter. Throws an Error that starts with `label` and says what to fix. */
+export function validateCaseMeta(id, data, knownEnvs, label = 'case document') {
+    if (data.suites !== undefined && data.priority !== undefined) {
+        throw new Error(`${label}: use "suites: [...]" only; "priority" is the old name of the same setting`);
+    }
+    const suites = data.suites !== undefined
+        ? nameList(data.suites, 'suites', label)
+        : data.priority !== undefined
+            ? nameList([data.priority], 'priority', label)
+            : (() => {
+                throw new Error(`${label}: front matter needs "suites: [<suite>, ...]", e.g. "suites: [smoke, regression]"`);
+            })();
+    const note = data['writes-note'];
+    const writes = parseWrites(data.writes, label, knownEnvs);
+    if (writes.length > 0 && (typeof note !== 'string' || note.trim() === '')) {
+        throw new Error(`${label}: "writes: [${writes.join(', ')}]" needs a "writes-note" that says what the case creates or changes`);
+    }
+    let envs = null;
+    if (data.envs !== undefined) {
+        envs = nameList(data.envs, 'envs', label);
+        const unknown = envs.filter((env) => !knownEnvs.includes(env));
+        if (unknown.length > 0) {
+            throw new Error(`${label}: unknown environment(s) in "envs": ${unknown.join(', ')}. Known: ${knownEnvs.join(', ')}`);
+        }
+    }
+    const unreachable = writes.filter((env) => envs !== null && !envs.includes(env));
+    if (unreachable.length > 0) {
+        throw new Error(`${label}: "writes" lists ${unreachable.join(', ')}, but "envs" does not run the case there`);
+    }
+    return {
+        id,
+        suites,
+        writes,
+        writesNote: typeof note === 'string' && note.trim() !== '' ? note.trim() : null,
+        envs,
+    };
+}
+/** The front matter problems a form can show without throwing; empty when it is valid. */
+export function caseMetaProblems(id, data, knownEnvs, label = 'case document') {
+    try {
+        validateCaseMeta(id, data, knownEnvs, label);
+        return [];
+    }
+    catch (error) {
+        return [error.message];
+    }
+}
+export function parseCaseDocument(text) {
+    const lines = splitLines(text);
+    const sections = sectionsOf(text, lines);
+    return {
+        text,
+        frontMatter: parseCaseFrontMatter(text),
+        sections,
+        steps: parseSteps(text, sections.find((section) => section.name === 'Steps')),
+        questions: parseQuestions(text, sections),
+        markers: parseMarkers(text, sections),
+        values: parseValues(text, sections.find((section) => section.name === 'Values')),
+        targets: parseTargetCards(text),
+        inputs: parseInputs(text, sections.find((section) => section.name === 'Inputs')),
+    };
+}
+/* -------------------------------------------------------------------- edits */
+/** Applies replacements that do not overlap. Positions refer to `text`, the text they were parsed from. */
+export function patchText(text, edits) {
+    const ordered = [...edits].sort((a, b) => b.start - a.start);
+    let result = text;
+    let limit = text.length;
+    for (const edit of ordered) {
+        if (edit.start < 0 || edit.end < edit.start || edit.end > limit) {
+            throw new Error('The case changed since it was read: reload it and try again.');
+        }
+        result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+        limit = edit.start;
+    }
+    return result;
+}
+/** Adds or removes one `[writes]` / `[input]` / `[email]` tag at the end of a step. */
+export function setStepTag(text, stepNumber, tag, on) {
+    const step = parseCaseDocument(text).steps.find((candidate) => candidate.number === stepNumber);
+    if (!step)
+        throw new Error(`The case has no step ${stepNumber}.`);
+    if (step.tags.includes(tag) === on)
+        return text;
+    if (on) {
+        const before = step.insertAt > step.range.start ? ' ' : '';
+        return patchText(text, [{ start: step.insertAt, end: step.insertAt, text: `${before}[${tag}]` }]);
+    }
+    const lineText = text.slice(step.range.start, step.range.end);
+    const at = lineText.lastIndexOf(`[${tag}]`);
+    if (at < 0)
+        return text;
+    const tagStart = step.range.start + at;
+    const separator = text[tagStart - 1] === ' ' || text[tagStart - 1] === '\t' ? 1 : 0;
+    return patchText(text, [{ start: tagStart - separator, end: tagStart + tag.length + 2, text: '' }]);
+}
+const singleLine = (value) => value.replace(/[\r\n]+/g, ' ').trim();
+/** The line break the document already uses, so an inserted line never mixes LF into a CRLF file. */
+const newlineOf = (text) => (text.includes('\r\n') ? '\r\n' : '\n');
+/** Writes an answer after `Answer:`; an empty answer clears the slot and keeps the line. */
+export function setQuestionAnswer(text, question, answer) {
+    const value = singleLine(answer);
+    if (question.hasAnswerLine) {
+        if (question.answer === value)
+            return text;
+        return patchText(text, [
+            { start: question.answerRange.start, end: question.answerRange.end, text: value === '' ? '' : ` ${value}` },
+        ]);
+    }
+    if (value === '')
+        return text;
+    const indent = ' '.repeat(question.indent + 2);
+    const newline = newlineOf(text);
+    return patchText(text, [
+        {
+            start: question.blockRange.end,
+            end: question.blockRange.end,
+            text: `${newline}${indent}- \u270D\uFE0F Answer: ${value}`,
+        },
+    ]);
+}
+/** Accepts the suggestion: deletes the whole question block, the answer line included. */
+export function acceptQuestion(text, question) {
+    return patchText(text, [{ start: question.blockRange.start, end: endWithBreak(text, question.blockRange.end), text: '' }]);
+}
+/**
+ * Removes a `🔍 to be confirmed by QA` / `👁️ not observed` marker. When the marker is the only content of its
+ * parentheses, the parentheses go too (`(👁️ not observed)`); otherwise the marker and one separator leave
+ * `(observed, 🔍 to be confirmed by QA)` as `(observed)`.
+ */
+export function removeMarker(text, marker) {
+    const open = text.lastIndexOf('(', marker.range.start);
+    const close = text.indexOf(')', marker.range.end);
+    if (open >= 0 && close >= 0 && !/[\r\n]/.test(text.slice(open, close))) {
+        const rest = text.slice(open + 1, marker.range.start) + text.slice(marker.range.end, close);
+        if (/^[\s,;:—-]*$/.test(rest)) {
+            const before = text[open - 1] === ' ' && /[.,;:!?]/.test(text[close + 1] ?? '') ? open - 1 : open;
+            return patchText(text, [{ start: before, end: close + 1, text: '' }]);
+        }
+    }
+    const lead = /(?:[ \t]*[,;][ \t]*|[ \t]+)$/.exec(text.slice(0, marker.range.start));
+    if (lead) {
+        return patchText(text, [{ start: marker.range.start - lead[0].length, end: marker.range.end, text: '' }]);
+    }
+    const trail = /^[ \t]+/.exec(text.slice(marker.range.end));
+    const end = trail ? marker.range.end + trail[0].length : marker.range.end;
+    return patchText(text, [{ start: marker.range.start, end, text: '' }]);
+}
+function replaceValues(text, block, values) {
+    const yaml = stringifyYaml(values, { lineWidth: 0 }).replace(/\r?\n/g, newlineOf(text));
+    const suffix = yaml.endsWith('\n') ? '' : newlineOf(text);
+    return patchText(text, [{ start: block.range.start, end: block.range.end, text: `${yaml}${suffix}` }]);
+}
+const editValues = (text, change) => {
+    const block = parseCaseDocument(text).values;
+    if (!block?.hasBlock)
+        throw new Error('The case has no "## Values" yaml block to edit.');
+    if (block.problem)
+        throw new Error(block.problem);
+    const values = Object.fromEntries(Object.entries(block.values).map(([profile, entries]) => [profile, { ...entries }]));
+    change(values);
+    return replaceValues(text, block, values);
+};
+/** Sets one value of one profile; `null` removes it (an empty cell in the panel means "not set here"). */
+export function setCaseValue(text, profile, key, value) {
+    const block = parseCaseDocument(text).values;
+    const current = block?.values[profile]?.[key];
+    const unchanged = value === null ? current === undefined : current === value;
+    if (unchanged)
+        return text;
+    return editValues(text, (values) => {
+        if (value === null) {
+            const entries = values[profile];
+            if (!entries)
+                return;
+            delete entries[key];
+            if (Object.keys(entries).length === 0)
+                delete values[profile];
+            return;
+        }
+        (values[profile] ??= {})[key] = value;
+    });
+}
+/** Adds a key to the `default` values of the case. */
+export function addCaseValueKey(text, key, value) {
+    return editValues(text, (values) => {
+        (values.default ??= {})[key] = value;
+    });
+}
+/** Writes the text of one `## Inputs` line (a recipe or a note); an empty text deletes the line. */
+export function setInputText(text, input, value) {
+    const clean = singleLine(value);
+    if (clean === input.recipe)
+        return text;
+    if (clean === '')
+        return removeInputLine(text, input);
+    return patchText(text, [{ start: input.recipeRange.start, end: input.recipeRange.end, text: clean }]);
+}
+/** Deletes one `## Inputs` bullet (a recipe line or a note), its wrapped lines included. */
+export function removeInputLine(text, input) {
+    return patchText(text, [{ start: input.range.start, end: endWithBreak(text, input.range.end), text: '' }]);
+}
+/** Writes the text of one recipe line under a step; an empty text deletes the line. */
+export function setRecipeText(text, recipe, value) {
+    const clean = singleLine(value);
+    if (clean === recipe.text)
+        return text;
+    if (clean === '')
+        return removeRecipe(text, recipe);
+    return patchText(text, [{ start: recipe.textRange.start, end: recipe.textRange.end, text: clean }]);
+}
+/** Deletes one recipe line under a step, its wrapped lines included. */
+export function removeRecipe(text, recipe) {
+    return patchText(text, [{ start: recipe.range.start, end: endWithBreak(text, recipe.range.end), text: '' }]);
+}
+const cleanLabel = (value) => (value ?? '')
+    .replace(/[\r\n()]+/g, ' ')
+    .trim();
+/** Writes the text of one `- Ready when:` line under a step; an empty text deletes the line. */
+export function setStepReady(text, signal, value) {
+    const clean = singleLine(value);
+    if (clean === signal.text)
+        return text;
+    if (clean === '')
+        return removeStepReady(text, signal);
+    return patchText(text, [{ start: signal.textRange.start, end: signal.textRange.end, text: clean }]);
+}
+/** Deletes one `- Ready when:` line under a step, its wrapped lines included. */
+export function removeStepReady(text, signal) {
+    return patchText(text, [{ start: signal.range.start, end: endWithBreak(text, signal.range.end), text: '' }]);
+}
+/**
+ * Adds a `- Ready when: ...` line under a step, right under the step sentence and above its recipes: readiness is read
+ * first, then what a person did. A second line goes under the first.
+ */
+export function addStepReady(text, stepNumber, value) {
+    const signal = singleLine(value);
+    if (signal === '')
+        return text;
+    const step = parseCaseDocument(text).steps.find((candidate) => candidate.number === stepNumber);
+    if (!step)
+        throw new Error(`The case has no step ${stepNumber}.`);
+    const bullet = `    - Ready when: ${signal}`;
+    const newline = newlineOf(text);
+    const anchor = step.readiness.at(-1);
+    const at = endWithBreak(text, anchor ? anchor.range.end : step.range.end);
+    const prefix = at > 0 && text[at - 1] !== '\n' ? newline : '';
+    return patchText(text, [{ start: at, end: at, text: `${prefix}${bullet}${newline}` }]);
+}
+/**
+ * Adds a `- Recipe (phase): ...` line under a step. It goes after the step's last recipe, or after its last readiness
+ * line, or directly under the step sentence, so a step keeps its readiness and recipes together and no separate input
+ * section is needed.
+ */
+export function addStepRecipe(text, stepNumber, what, value) {
+    const recipe = singleLine(value);
+    if (recipe === '')
+        return text;
+    const step = parseCaseDocument(text).steps.find((candidate) => candidate.number === stepNumber);
+    if (!step)
+        throw new Error(`The case has no step ${stepNumber}.`);
+    const label = cleanLabel(what);
+    const bullet = `    - Recipe${label === '' ? '' : ` (${label})`}: ${recipe}`;
+    const newline = newlineOf(text);
+    const anchor = step.recipes.at(-1) ?? step.readiness.at(-1);
+    const at = endWithBreak(text, anchor ? anchor.range.end : step.range.end);
+    const prefix = at > 0 && text[at - 1] !== '\n' ? newline : '';
+    return patchText(text, [{ start: at, end: at, text: `${prefix}${bullet}${newline}` }]);
+}
+/* ------------------------------------------------ front matter, steps, bullets */
+const scalarFor = (value) => stringifyYaml(value, { lineWidth: 0 }).replace(/\r?\n$/, '');
+const flowList = (values) => `[${values.map((value) => scalarFor(value)).join(", ")}]`;
+/** Sets one front matter key (a scalar or a list); `null` or an empty list removes it. */
+export function setFrontMatterValue(text, key, value) {
+    const front = parseCaseFrontMatter(text);
+    if (!front)
+        throw new Error("The case has no front matter block.");
+    if (front.problem)
+        throw new Error(front.problem);
+    if (value === null || (Array.isArray(value) && value.length === 0))
+        return removeFrontMatterKey(text, key);
+    const raw = Array.isArray(value) ? flowList(value) : scalarFor(value);
+    const entry = front.entries.find((candidate) => candidate.key === key);
+    if (entry) {
+        if (entry.block)
+            return patchText(text, [{ start: entry.range.start, end: entry.range.end, text: `${key}: ${raw}` }]);
+        return patchText(text, [{ start: entry.valueRange.start, end: entry.valueRange.end, text: raw }]);
+    }
+    const position = META_ORDER.indexOf(key);
+    const before = front.entries
+        .filter((candidate) => META_ORDER.includes(candidate.key) && META_ORDER.indexOf(candidate.key) < position)
+        .at(-1);
+    const at = before ? endWithBreak(text, before.range.end) : front.insertAt;
+    const prefix = at > 0 && text[at - 1] !== "\n" ? newlineOf(text) : "";
+    return patchText(text, [{ start: at, end: at, text: `${prefix}${key}: ${raw}${newlineOf(text)}` }]);
+}
+/** Removes one front matter key and its lines. */
+export function removeFrontMatterKey(text, key) {
+    const front = parseCaseFrontMatter(text);
+    const entry = front?.entries.find((candidate) => candidate.key === key);
+    if (!entry)
+        return text;
+    return patchText(text, [{ start: entry.range.start, end: endWithBreak(text, entry.range.end), text: "" }]);
+}
+/** Sets the sentence of a step (a multi-line value keeps its wrapping, indented under the number). */
+export function setStepText(text, step, value) {
+    const indent = " ".repeat(String(step.number).length + 2);
+    const clean = value
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line, index) => (index === 0 ? line.replace(/[ \t]+$/, "") : `${indent}${line.trim()}`))
+        .join("\n");
+    if (clean === text.slice(step.textRange.start, step.textRange.end))
+        return text;
+    return patchText(text, [{ start: step.textRange.start, end: step.textRange.end, text: clean }]);
+}
+/** Sets the text of one bullet (`## Expected`, `## Visual checks`); a nested TODO block is not touched. */
+export function setBulletText(text, bullet, value) {
+    const clean = value
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line, index) => (index === 0 ? line.replace(/[ \t]+$/, "") : `  ${line.trim()}`))
+        .join("\n");
+    if (clean === text.slice(bullet.textRange.start, bullet.textRange.end))
+        return text;
+    return patchText(text, [{ start: bullet.textRange.start, end: bullet.textRange.end, text: clean }]);
+}
+/** Appends a bullet to a list section. Returns the text unchanged when the section does not exist. */
+export function addBullet(text, name, value) {
+    const content = value
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line, index) => (index === 0 ? line.trim() : `  ${line.trim()}`))
+        .join("\n");
+    if (content === "")
+        return text;
+    const section = sectionsOf(text, splitLines(text)).find((candidate) => candidate.name === name);
+    if (!section)
+        return text;
+    const lines = sectionLines(text, section).map(({ line }) => line);
+    const last = [...lines].reverse().find((line) => !isBlank(line.text));
+    const at = last ? afterLine(text, last) : section.body.start;
+    const prefix = at > 0 && text[at - 1] !== "\n" ? newlineOf(text) : "";
+    return patchText(text, [{ start: at, end: at, text: `${prefix}- ${content}${newlineOf(text)}` }]);
+}
+/** Deletes one bullet and everything under it (a nested question block included). */
+export function removeBullet(text, bullet) {
+    return patchText(text, [{ start: bullet.range.start, end: endWithBreak(text, bullet.range.end), text: "" }]);
+}
+/** Moves one bullet block (and everything under it) to another position, with `arrayMove` semantics. */
+export function moveBullet(text, name, from, to) {
+    const bullets = parseBullets(text, name);
+    if (from === to || from < 0 || to < 0 || from >= bullets.length || to >= bullets.length)
+        return text;
+    const source = bullets[from];
+    const target = bullets[to];
+    const end = endWithBreak(text, source.range.end);
+    const block = text.slice(source.range.start, end);
+    const insertAt = from < to ? endWithBreak(text, target.range.end) : target.range.start;
+    return patchText(text, [
+        { start: source.range.start, end, text: "" },
+        { start: insertAt, end: insertAt, text: block },
+    ]);
+}