@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/decision-round-text.js

@@ -0,0 +1,146 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The card texts of a decision round (EPIC-060), read from a question or decision body: the
+ * prose before the fields, the options with their consequences, the option a recommendation
+ * names, the evidence lines, and the decision fields. The field parsing itself is
+ * `decision-question.ts`; this module adds what a card shows beside the fields.
+ */
+import { parseDecisionFields, parseQuestionFields, sectionText } from './decision-question.js';
+import { markdownSections, stripComments } from './epic-sections.js';
+/** The longest text a card carries for one field; the item itself holds the rest. */
+export const ROUND_TEXT_MAX = 2000;
+/** The evidence lines a question card shows at most. */
+export const ROUND_SOURCES_MAX = 8;
+const FIELD_LINE = /^(?:- )?([A-Za-z]+):\s*(.*)$/;
+const OPTION_LINE = /^(?:- )?[a-z]\)\s+/;
+const CONSEQUENCE = /\s*\bConsequences?:\s*/i;
+const SOURCE_HEADINGS = /^(evidence|sources?|references?)$/i;
+/** A decision's own lines end at its first H1 or H2 section. */
+const SECTION_HEADING = /^#{1,2}\s/;
+function clipped(text) {
+    return text ? clip(text) : undefined;
+}
+function clip(text) {
+    const trimmed = text.trim();
+    return trimmed.length <= ROUND_TEXT_MAX ? trimmed : `${trimmed.slice(0, ROUND_TEXT_MAX - 1)}…`;
+}
+/** The body without comments, the H1 title and fenced code, as lines. */
+function bodyLines(markdown) {
+    let fence = false;
+    return stripComments(markdown)
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fence = !fence;
+            return '';
+        }
+        return fence ? '' : line;
+    })
+        .filter((line, index) => !(index === 0 && /^#\s/.test(line)));
+}
+/** The paragraphs before the first field, option or heading, joined with blank lines. */
+function leadingProse(lines) {
+    const prose = [];
+    for (const line of lines) {
+        if (/^#{1,6}\s/.test(line) || OPTION_LINE.test(line) || FIELD_LINE.test(line))
+            break;
+        prose.push(line);
+    }
+    const text = prose
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    return text ? clip(text) : undefined;
+}
+/** The value of a `Key: value` line, with or without the leading dash. */
+function lineField(lines, key) {
+    for (const line of lines) {
+        const match = FIELD_LINE.exec(line);
+        if (match && match[1] === key && match[2].trim())
+            return clip(match[2]);
+    }
+    return undefined;
+}
+/** The question in prose: the body before its options and fields. */
+export function questionText(markdown) {
+    return leadingProse(bodyLines(markdown));
+}
+/** The options of a question, each with the consequence it names split off. */
+export function questionOptions(markdown) {
+    return parseQuestionFields(markdown).options.map(({ key, text }) => {
+        const [head, ...rest] = text.split(CONSEQUENCE);
+        const consequence = rest.join(' ').trim();
+        return consequence
+            ? { key, text: clip(head), consequence: clip(consequence) }
+            : { key, text: clip(text) };
+    });
+}
+/** The option key a recommendation names first (`b)`, `b.`, `b,` or `b ` …), if it is one. */
+export function recommendedOption(recommendation, options) {
+    const key = /^\s*([a-z])(?:\)|(?=[\s.,;:]|$))/.exec(recommendation ?? '')?.[1];
+    return key && options.some((option) => option.key === key) ? key : undefined;
+}
+/** The lines of a section's body: bullets without their marker, and plain lines. */
+function sectionItems(body) {
+    return body
+        .split('\n')
+        .map((line) => line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim())
+        .filter((line) => line.length > 0);
+}
+/** The evidence of a question: an Evidence or Sources section, and `Source:` lines. */
+export function questionSources(markdown) {
+    const lines = markdown.replace(/\r\n?/g, '\n').split('\n');
+    const answerAt = lines.findIndex((line) => /^##\s+Answer\s*$/i.test(line));
+    const body = stripComments(answerAt < 0 ? lines.join('\n') : lines.slice(0, answerAt).join('\n'));
+    const sources = [];
+    for (const section of markdownSections(body)) {
+        if (section.level >= 2 && SOURCE_HEADINGS.test(section.heading.trim())) {
+            sources.push(...sectionItems(section.body));
+        }
+    }
+    for (const line of bodyLines(body)) {
+        const match = /^(?:- )?Sources?:\s*(.+)$/.exec(line);
+        if (match)
+            sources.push(match[1].trim());
+    }
+    return [...new Set(sources)].slice(0, ROUND_SOURCES_MAX).map(clip);
+}
+/** Everything a question card shows from the body. */
+export function questionCardText(markdown) {
+    const options = questionOptions(markdown);
+    const raw = parseQuestionFields(markdown).Recommendation;
+    const recommendation = raw ? clip(raw) : undefined;
+    const recommended = recommendedOption(recommendation, options);
+    return {
+        ...(questionText(markdown) ? { text: questionText(markdown) } : {}),
+        options,
+        ...(recommendation ? { recommendation } : {}),
+        ...(recommended ? { recommended } : {}),
+        sources: questionSources(markdown),
+    };
+}
+/** Everything a decision card shows from the body: the decision, Deviates and the fields. */
+export function decisionCardText(markdown) {
+    const lines = bodyLines(markdown);
+    const sectionAt = lines.findIndex((line) => SECTION_HEADING.test(line));
+    const head = sectionAt < 0 ? lines : lines.slice(0, sectionAt);
+    const fields = parseDecisionFields(markdown);
+    const text = lineField(head, 'Decision') ??
+        leadingProse(head) ??
+        clipped(sectionText(markdown, /^decision(?: outcome)?$/i));
+    const deviates = lineField(head, 'Deviates');
+    const consequences = clipped(sectionText(markdown, /^consequences?$/i));
+    return {
+        ...(text ? { text } : {}),
+        ...(deviates ? { deviates } : {}),
+        ...(fields.Why ? { why: clip(fields.Why) } : {}),
+        ...(fields.Rejected ? { rejected: clip(fields.Rejected) } : {}),
+        ...(fields.Check ? { check: clip(fields.Check) } : {}),
+        sources: questionSources(markdown),
+        ...(consequences ? { consequences } : {}),
+    };
+}
+//# sourceMappingURL=decision-round-text.js.map

package/dist/core/decision-round-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-round-text.js","sourceRoot":"","sources":["../../src/core/decision-round-text.ts"],"names":[],"mappings":"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"}

package/dist/core/decision-round-types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Decision round view model (EPIC-060): the open questions and the decisions in review, grouped
+ * by the epic or story they belong to. Built in the shared core so that every surface renders the
+ * same round; a group is a filter over type, status and links, never a stored record.
+ */
+import type { EisenhowerQuadrant, ItemStatus, ItemType } from '../schemas/index.js';
+/** An item the round names. */
+export interface RoundRef {
+    id: string;
+    type: ItemType;
+    title: string;
+    status: ItemStatus;
+}
+/** One option `a) …` of a question, its consequence split off when the option names one. */
+export interface RoundOption {
+    key: string;
+    text: string;
+    consequence?: string;
+}
+interface RoundEntryBase {
+    id: string;
+    title: string;
+    status: ItemStatus;
+    priority: EisenhowerQuadrant;
+    /** The other epics and stories the item is linked to, beside its group's owner. */
+    alsoLinked: string[];
+}
+/** An open question (QST in draft). */
+export interface RoundQuestion extends RoundEntryBase {
+    kind: 'question';
+    /** The question in prose: the body before the options. */
+    text?: string;
+    options: RoundOption[];
+    recommendation?: string;
+    /** The option the recommendation names, when it names one of the options. */
+    recommended?: string;
+    /** Evidence and source lines of the body. */
+    sources: string[];
+    /** The decisions linked to the question. */
+    decisions: RoundRef[];
+    /** The item the question blocks, when it blocks one. */
+    blocks?: string;
+}
+/** A decision in review; a deviation carries the deviation tag. */
+export interface RoundDecision extends RoundEntryBase {
+    kind: 'decision';
+    deviation: boolean;
+    /** The decision in prose: its `Decision:` line, or the body's first paragraph. */
+    text?: string;
+    deviates?: string;
+    why?: string;
+    rejected?: string;
+    check?: string;
+    /** Evidence and source lines of the body. */
+    sources: string[];
+    /** The `## Consequences` section of the body. */
+    consequences?: string;
+    /** The questions linked to the decision. */
+    questions: RoundRef[];
+}
+export type RoundEntry = RoundQuestion | RoundDecision;
+export interface RoundCounts {
+    questions: number;
+    /** Every decision in review, deviations included. */
+    decisions: number;
+    deviations: number;
+}
+/** What applies to a group's items: the owner's chain source, its sections and its decisions. */
+export interface RoundCompass {
+    source: RoundRef;
+    /** The chain items between the owner and the source, nearest first. */
+    via: string[];
+    constraints: Array<{
+        text: string;
+        check?: string;
+    }>;
+    outOfScope: string[];
+    /** The accepted decisions linked to the chain. */
+    decisions: Array<RoundRef & {
+        deviation: boolean;
+    }>;
+    /** Lines the caps left out; `trace` of the source lists them. */
+    more: number;
+}
+export interface RoundGroup {
+    /** The owner's ID, or `none` for the items that belong to no epic or story. */
+    key: string;
+    owner?: RoundRef;
+    /** The owner's implements chain above it, nearest first. */
+    chain: RoundRef[];
+    counts: RoundCounts;
+    /** Deviations first, then questions, then the other decisions. */
+    entries: RoundEntry[];
+    compass?: RoundCompass;
+}
+export interface DecisionRound {
+    groups: RoundGroup[];
+    counts: RoundCounts;
+    /** The item the round is narrowed to, when it is. */
+    scope?: string;
+}
+/** The group key of the items that belong to no epic or story. */
+export declare const UNLINKED_GROUP = "none";
+export {};
+//# sourceMappingURL=decision-round-types.d.ts.map

package/dist/core/decision-round-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-round-types.d.ts","sourceRoot":"","sources":["../../src/core/decision-round-types.ts"],"names":[],"mappings":"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"}

package/dist/core/decision-round-types.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Decision round view model (EPIC-060): the open questions and the decisions in review, grouped
+ * by the epic or story they belong to. Built in the shared core so that every surface renders the
+ * same round; a group is a filter over type, status and links, never a stored record.
+ */
+/** The group key of the items that belong to no epic or story. */
+export const UNLINKED_GROUP = 'none';
+//# sourceMappingURL=decision-round-types.js.map

package/dist/core/decision-round-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-round-types.js","sourceRoot":"","sources":["../../src/core/decision-round-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAwGH,kEAAkE;AAClE,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC"}

package/dist/core/decision-round.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The decision round (EPIC-060): every open question (QST in draft) and every decision in review
+ * (DEC in review, deviations among them), grouped by the epic or story each belongs to, with the
+ * counts and the compass of each group. A group puts its deviations first, then its questions,
+ * blocking ones before the others, then its other decisions, each tier by priority and ID. The
+ * round is computed from the items on every call; nothing about it is stored.
+ */
+import { type DecisionRound, type RoundCounts, type RoundEntry } from './decision-round-types.js';
+export interface DecisionRoundOptions {
+    /** Narrow the round to the items of this owner, its descendants, or this item itself. */
+    scope?: string;
+}
+export declare function countsOf(entries: readonly RoundEntry[]): RoundCounts;
+/** The decision round of the project, or of one item's part of it when `scope` names one. */
+export declare function buildDecisionRound(devstepsDir: string, options?: DecisionRoundOptions): DecisionRound;
+//# sourceMappingURL=decision-round.d.ts.map

package/dist/core/decision-round.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-round.d.ts","sourceRoot":"","sources":["../../src/core/decision-round.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,UAAU,EAKhB,MAAM,2BAA2B,CAAC;AAGnC,MAAM,WAAW,oBAAoB;IACnC,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgHD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,WAAW,CAOpE;AAoDD,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAWf"}

package/dist/core/decision-round.js

@@ -0,0 +1,166 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The decision round (EPIC-060): every open question (QST in draft) and every decision in review
+ * (DEC in review, deviations among them), grouped by the epic or story each belongs to, with the
+ * counts and the compass of each group. A group puts its deviations first, then its questions,
+ * blocking ones before the others, then its other decisions, each tier by priority and ID. The
+ * round is computed from the items on every call; nothing about it is stored.
+ */
+import { EisenhowerQuadrant } from '../schemas/index.js';
+import { parseItemId } from '../utils/index.js';
+import { isDeviation } from './decision-question.js';
+import { groupCompass, metadataReader, ownerCandidates, ownerChain, roundRef, } from './decision-round-owner.js';
+import { decisionCardText, questionCardText } from './decision-round-text.js';
+import { UNLINKED_GROUP, } from './decision-round-types.js';
+import { readAllItemMetadata, readItem } from './item-store.js';
+function idNumber(id) {
+    return parseItemId(id)?.number ?? Number.MAX_SAFE_INTEGER;
+}
+function descriptionOf(devstepsDir, id) {
+    try {
+        return readItem(devstepsDir, id).description;
+    }
+    catch {
+        return '';
+    }
+}
+function linkedIds(item) {
+    return [...new Set(Object.values(item.linked_items).flatMap((ids) => ids ?? []))];
+}
+function linkedRefs(item, type, read) {
+    return linkedIds(item)
+        .filter((id) => parseItemId(id)?.type === type)
+        .flatMap((id) => {
+        const linked = read(id);
+        return linked ? [roundRef(linked)] : [];
+    })
+        .sort((a, b) => idNumber(a.id) - idNumber(b.id));
+}
+function questionEntry(devstepsDir, read, item, alsoLinked) {
+    const decisions = linkedRefs(item, 'decision', read);
+    const blocks = item.linked_items.blocks?.[0];
+    return {
+        kind: 'question',
+        id: item.id,
+        title: item.title,
+        status: item.status,
+        priority: item.eisenhower,
+        alsoLinked,
+        ...questionCardText(descriptionOf(devstepsDir, item.id)),
+        decisions,
+        ...(blocks ? { blocks } : {}),
+    };
+}
+function decisionEntry(devstepsDir, read, item, alsoLinked) {
+    return {
+        kind: 'decision',
+        id: item.id,
+        title: item.title,
+        status: item.status,
+        priority: item.eisenhower,
+        alsoLinked,
+        deviation: isDeviation(item),
+        ...decisionCardText(descriptionOf(devstepsDir, item.id)),
+        questions: linkedRefs(item, 'question', read),
+    };
+}
+function tierOf(entry) {
+    if (entry.kind === 'decision')
+        return entry.deviation ? 0 : 3;
+    return entry.blocks ? 1 : 2;
+}
+function place(devstepsDir, read, item) {
+    const [owner, ...others] = ownerCandidates(devstepsDir, read, item);
+    const alsoLinked = others.map((other) => other.id);
+    const entry = item.type === 'question'
+        ? questionEntry(devstepsDir, read, item, alsoLinked)
+        : decisionEntry(devstepsDir, read, item, alsoLinked);
+    const urgency = EisenhowerQuadrant.options.indexOf(item.eisenhower);
+    return {
+        entry,
+        chain: owner ? ownerChain(devstepsDir, owner) : [],
+        tier: tierOf(entry),
+        urgency: urgency < 0 ? EisenhowerQuadrant.options.length : urgency,
+        number: idNumber(item.id),
+    };
+}
+function comparePlaced(a, b) {
+    return a.tier - b.tier || a.urgency - b.urgency || a.number - b.number;
+}
+function inScope(placed, scope) {
+    return (placed.entry.id === scope ||
+        placed.chain.some((member) => member.id === scope) ||
+        placed.entry.alsoLinked.includes(scope));
+}
+export function countsOf(entries) {
+    const decisions = entries.filter((entry) => entry.kind === 'decision');
+    return {
+        questions: entries.length - decisions.length,
+        decisions: decisions.length,
+        deviations: decisions.filter((entry) => entry.kind === 'decision' && entry.deviation).length,
+    };
+}
+/** The sort key of a group: its chain's top item, then the owner's depth and ID; unlinked last. */
+function groupKey(chain) {
+    const top = chain[chain.length - 1];
+    const owner = chain[0];
+    if (!top || !owner)
+        return [1, 0, '', 0, 0];
+    return [0, idNumber(top.id), top.id, chain.length, idNumber(owner.id)];
+}
+function compareGroups(a, b) {
+    const [x, y] = [groupKey(a), groupKey(b)];
+    for (let index = 0; index < x.length; index += 1) {
+        if (x[index] === y[index])
+            continue;
+        return x[index] < y[index] ? -1 : 1;
+    }
+    return 0;
+}
+function groupsOf(devstepsDir, placed) {
+    const byOwner = new Map();
+    for (const entry of placed) {
+        const key = entry.chain[0]?.id ?? UNLINKED_GROUP;
+        byOwner.set(key, [...(byOwner.get(key) ?? []), entry]);
+    }
+    return [...byOwner.entries()]
+        .map(([key, members]) => ({ key, members, chain: members[0].chain }))
+        .sort((a, b) => compareGroups(a.chain, b.chain))
+        .map(({ key, members, chain }) => {
+        const entries = [...members].sort(comparePlaced).map((member) => member.entry);
+        const compass = chain.length > 0 ? groupCompass(devstepsDir, chain) : undefined;
+        return {
+            key,
+            ...(chain[0] ? { owner: roundRef(chain[0]) } : {}),
+            chain: chain.slice(1).map(roundRef),
+            counts: countsOf(entries),
+            entries,
+            ...(compass ? { compass } : {}),
+        };
+    });
+}
+/** The open questions and the decisions in review, from every item file on each call. */
+function openRecords(devstepsDir) {
+    const questions = readAllItemMetadata(devstepsDir, 'question').items;
+    const decisions = readAllItemMetadata(devstepsDir, 'decision').items;
+    return [
+        ...questions.filter((entry) => entry.metadata.status === 'draft'),
+        ...decisions.filter((entry) => entry.metadata.status === 'review'),
+    ].map((entry) => entry.metadata);
+}
+/** The decision round of the project, or of one item's part of it when `scope` names one. */
+export function buildDecisionRound(devstepsDir, options = {}) {
+    const read = metadataReader(devstepsDir);
+    const placed = openRecords(devstepsDir).map((item) => place(devstepsDir, read, item));
+    const { scope } = options;
+    const shown = scope ? placed.filter((entry) => inScope(entry, scope)) : placed;
+    const groups = groupsOf(devstepsDir, shown);
+    return {
+        groups,
+        counts: countsOf(groups.flatMap((group) => group.entries)),
+        ...(scope ? { scope } : {}),
+    };
+}
+//# sourceMappingURL=decision-round.js.map

package/dist/core/decision-round.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-round.js","sourceRoot":"","sources":["../../src/core/decision-round.ts"],"names":[],"mappings":"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"}

package/dist/core/description-patch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Exact, all-or-nothing description patches (STORY-528). Candidates stay in memory until
+ * every operation validates; text outside the selected spans is never normalized.
+ */
+export interface DescriptionReplacement {
+    old: string;
+    new: string;
+    expect_count?: number;
+}
+export interface DescriptionSectionReplacement {
+    heading: string;
+    text: string;
+}
+export interface DescriptionPatchInput {
+    replace?: DescriptionReplacement[];
+    replace_section?: DescriptionSectionReplacement;
+}
+/** One summary per requested operation; lines refer to its input, after prior operations. */
+export interface DescriptionChange {
+    start_line: number;
+    end_line: number;
+    matches: number;
+}
+export interface DescriptionPatchResult {
+    text: string;
+    changes: DescriptionChange[];
+}
+/** Description modes are mutually exclusive, including empty but explicitly supplied values. */
+export declare function assertDescriptionModes(args: DescriptionPatchInput & {
+    description?: string;
+    append_description?: string;
+    process_definition?: unknown;
+}): void;
+export declare function hasDescriptionPatch(args: DescriptionPatchInput): boolean;
+export declare function applyDescriptionPatch(text: string, input: DescriptionPatchInput): DescriptionPatchResult;
+//# sourceMappingURL=description-patch.d.ts.map

package/dist/core/description-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"description-patch.d.ts","sourceRoot":"","sources":["../../src/core/description-patch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACnC,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAED,6FAA6F;AAC7F,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,qBAAqB,GAAG;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GACA,IAAI,CASN;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAExE;AA2ED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,qBAAqB,GAC3B,sBAAsB,CAUxB"}

package/dist/core/description-patch.js

@@ -0,0 +1,107 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Exact, all-or-nothing description patches (STORY-528). Candidates stay in memory until
+ * every operation validates; text outside the selected spans is never normalized.
+ */
+import { z } from 'zod';
+import { markdownHeadingRanges } from './markdown-heading-ranges.js';
+const Replacement = z.strictObject({
+    old: z.string().min(1),
+    new: z.string(),
+    expect_count: z.number().int().positive().default(1),
+});
+const SectionReplacement = z.strictObject({ heading: z.string().trim().min(1), text: z.string() });
+/** Description modes are mutually exclusive, including empty but explicitly supplied values. */
+export function assertDescriptionModes(args) {
+    const modes = ['description', 'append_description', 'replace', 'replace_section'];
+    const present = modes.filter((mode) => args[mode] !== undefined);
+    if (present.length > 1) {
+        throw new Error(`Cannot combine description modes: ${present.join(', ')}`);
+    }
+    if (hasDescriptionPatch(args) && args.process_definition !== undefined) {
+        throw new Error('Cannot combine replace or replace_section with process_definition');
+    }
+}
+export function hasDescriptionPatch(args) {
+    return args.replace !== undefined || args.replace_section !== undefined;
+}
+function lineAt(text, offset) {
+    let prefix = text.slice(0, offset);
+    // A range ending on the LF of CRLF still belongs to the preceding line.
+    if (text[offset] === '\n' && prefix.endsWith('\r'))
+        prefix = prefix.slice(0, -1);
+    return (prefix.match(/\r\n|\r|\n/g)?.length ?? 0) + 1;
+}
+function replacePassages(text, input) {
+    const operations = z.array(Replacement).min(1).parse(input);
+    const changes = [];
+    for (const [index, operation] of operations.entries()) {
+        const offsets = [];
+        let offset = text.indexOf(operation.old);
+        while (offset !== -1) {
+            offsets.push(offset);
+            offset = text.indexOf(operation.old, offset + operation.old.length);
+        }
+        if (offsets.length !== operation.expect_count) {
+            throw new Error(`replace[${index}]: expected ${operation.expect_count} occurrence(s), found ${offsets.length}; item unchanged`);
+        }
+        if (operation.old !== operation.new) {
+            changes.push({
+                start_line: lineAt(text, offsets[0]),
+                end_line: lineAt(text, offsets[offsets.length - 1] + operation.old.length - 1),
+                matches: offsets.length,
+            });
+        }
+        text = text.split(operation.old).join(operation.new);
+    }
+    return { text, changes };
+}
+function replaceSection(text, input) {
+    const operation = SectionReplacement.parse(input);
+    const selector = operation.heading.replace(/^#{1,6}[ \t]+/, '');
+    const sections = markdownHeadingRanges(text);
+    const matches = sections.filter((heading) => heading.text === selector);
+    if (matches.length !== 1) {
+        throw new Error(`replace_section: expected one heading "${selector}", found ${matches.length}; item unchanged`);
+    }
+    const heading = matches[0];
+    const end = heading.end;
+    const newline = heading.ending || /\r\n|\r|\n/.exec(text)?.[0] || '\n';
+    let replacement = operation.text;
+    if (replacement && !heading.ending)
+        replacement = newline + replacement;
+    if (end < text.length && replacement && !/[\r\n]$/.test(replacement))
+        replacement += newline;
+    const candidate = text.slice(0, heading.bodyStart) + replacement + text.slice(end);
+    return {
+        text: candidate,
+        changes: candidate === text
+            ? []
+            : [
+                {
+                    start_line: lineAt(text, heading.bodyStart),
+                    end_line: lineAt(text, Math.max(heading.bodyStart, end - 1)),
+                    matches: 1,
+                },
+            ],
+    };
+}
+function assertProjectionUnchanged(before, after) {
+    const generated = /<!-- devsteps:guide-steps -->[\s\S]*?<!-- \/devsteps:guide-steps -->/g;
+    if (JSON.stringify(before.match(generated)) !== JSON.stringify(after.match(generated))) {
+        throw new Error('Cannot patch generated guide steps; update process_definition instead');
+    }
+}
+export function applyDescriptionPatch(text, input) {
+    assertDescriptionModes(input);
+    if (!hasDescriptionPatch(input))
+        throw new Error('A replace or replace_section patch is required');
+    const result = input.replace !== undefined
+        ? replacePassages(text, input.replace)
+        : replaceSection(text, input.replace_section);
+    assertProjectionUnchanged(text, result.text);
+    return result;
+}
+//# sourceMappingURL=description-patch.js.map