@dxos/plugin-github 0.7.4 → 0.13.0

package/dist/lib/chunk-generate.mjs

@@ -0,0 +1,719 @@
+import { Walkthrough } from "#types";
+import * as Effect from "effect/Effect";
+import { Database, Filter, Obj, Ref } from "@dxos/echo";
+import * as Progress from "@dxos/app-toolkit/Progress";
+//#region src/walkthrough/patch.ts
+var FILE_HEADER = /^diff --git a\/(.+?) b\/(.+)$/;
+var HUNK_HEADER = /^@@+\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/;
+/**
+* Splits a multi-file unified diff — what `GET /repos/…/pulls/N` returns under the `diff` media type
+* — into files and hunks. Hunk bodies are carried verbatim rather than re-derived, so a chunk filled
+* from one is byte-identical to what git produced.
+*/
+var parsePatch = (patch) => {
+	const files = [];
+	let file;
+	let hunk;
+	for (const raw of patch.split("\n")) {
+		const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+		const header = FILE_HEADER.exec(line);
+		if (header) {
+			file = {
+				path: header[2],
+				preamble: [line],
+				hunks: [],
+				added: 0,
+				removed: 0
+			};
+			files.push(file);
+			hunk = void 0;
+			continue;
+		}
+		if (!file) continue;
+		const hunkHeader = HUNK_HEADER.exec(line);
+		if (hunkHeader) {
+			const beforeStart = Number(hunkHeader[1]);
+			const beforeCount = hunkHeader[2] === void 0 ? 1 : Number(hunkHeader[2]);
+			const afterStart = Number(hunkHeader[3]);
+			hunk = {
+				header: line,
+				lines: [],
+				afterStart,
+				afterEnd: afterStart + (hunkHeader[4] === void 0 ? 1 : Number(hunkHeader[4])) - 1,
+				beforeStart,
+				beforeEnd: beforeStart + beforeCount - 1,
+				added: 0,
+				removed: 0
+			};
+			file.hunks.push(hunk);
+			continue;
+		}
+		if (!hunk) {
+			file.preamble.push(line);
+			continue;
+		}
+		if (line.startsWith("\\")) {
+			hunk.lines.push(line);
+			continue;
+		}
+		if (line.startsWith("+")) {
+			hunk.added++;
+			file.added++;
+		} else if (line.startsWith("-")) {
+			hunk.removed++;
+			file.removed++;
+		}
+		hunk.lines.push(line);
+	}
+	const trailing = files.at(-1)?.hunks.at(-1);
+	if (trailing?.lines.at(-1) === "") trailing.lines.pop();
+	const merged = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const existing = merged.get(file.path);
+		if (existing) {
+			existing.hunks.push(...file.hunks);
+			existing.added += file.added;
+			existing.removed += file.removed;
+		} else merged.set(file.path, file);
+	}
+	return [...merged.values()];
+};
+/** The hunk text a diff fence holds: the `@@` header and its body, as git wrote them. */
+var renderHunks = (hunks) => hunks.map((hunk) => [hunk.header, ...hunk.lines].join("\n")).join("\n");
+/**
+* Whether a hunk shows any of `[start, end]` of the post-change file.
+*
+* A pure removal spans nothing after the change (`afterEnd === afterStart - 1`), so it is treated as
+* occupying the single position the lines were removed from — otherwise no range could ever select
+* it, including the one this module's own {@link hunkRange} reports for it.
+*/
+var hunkOverlaps = (hunk, start, end) => hunk.afterStart <= end && Math.max(hunk.afterEnd, hunk.afterStart) >= start;
+/**
+* The span a set of hunks covers, for a fence's `lines=` attribute.
+*
+* Measured after the change, except where nothing survives it: a deleted file's post-image is empty
+* and would otherwise read as `Lines 0`, so its range is quoted from the pre-image instead.
+*/
+var hunkRange = (hunks) => {
+	if (hunks.length === 0) return;
+	const survives = hunks.some((hunk) => hunk.afterEnd >= hunk.afterStart);
+	const start = Math.min(...hunks.map((hunk) => survives ? hunk.afterStart : hunk.beforeStart));
+	const end = Math.max(...hunks.map((hunk) => survives ? Math.max(hunk.afterEnd, hunk.afterStart) : hunk.beforeEnd));
+	return start >= end ? `${start}` : `${start}-${end}`;
+};
+//#endregion
+//#region src/walkthrough/headings.ts
+var FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+/** A closing fence carries nothing after its marker: a line with an info string only opens one. */
+var CLOSING_FENCE = /^\s{0,3}(`{3,}|~{3,})[ \t]*$/;
+var HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+/**
+* Puts a blank line before every heading outside a code fence.
+*
+* A heading may legally interrupt a paragraph, so the model and the chapter join both emit one on
+* the very next line — which the walkthrough's source-level editor shows flush against the prose.
+*/
+var spaceHeadings = (markdown) => {
+	const lines = markdown.split("\n");
+	const result = [];
+	let fence;
+	for (const line of lines) {
+		const crlf = line.endsWith("\r");
+		const text = crlf ? line.slice(0, -1) : line;
+		const marker = text.match(FENCE)?.[1];
+		if (fence) {
+			const closer = text.match(CLOSING_FENCE)?.[1];
+			if (closer && closer[0] === fence[0] && closer.length >= fence.length) fence = void 0;
+		} else if (marker) fence = marker;
+		else if (HEADING.test(text) && result.length > 0 && result[result.length - 1].trim() !== "") result.push(crlf ? "\r" : "");
+		result.push(line);
+	}
+	return result.join("\n");
+};
+//#endregion
+//#region src/walkthrough/generated.ts
+/**
+* Files a reviewer does not read, and a walkthrough should not spend prose or a fence on: machine
+* output, vendored blobs, and anything whose diff is a consequence of another file in the same
+* change.
+*
+* Detection is by path and by patch shape rather than by a `.gitattributes` lookup, because the
+* walkthrough only ever has the patch.
+*/
+/** Lockfiles: the largest hunk in most pull requests and the one nobody reads. */
+var LOCKFILES = [
+	"pnpm-lock.yaml",
+	"package-lock.json",
+	"yarn.lock",
+	"bun.lockb",
+	"npm-shrinkwrap.json",
+	"Cargo.lock",
+	"poetry.lock",
+	"composer.lock",
+	"Gemfile.lock",
+	"go.sum",
+	"flake.lock",
+	"uv.lock"
+];
+/** Directories whose contents are built, vendored or cached rather than written. */
+var GENERATED_DIRECTORIES = /(^|\/)(dist|build|out|coverage|node_modules|vendor|__snapshots__|\.turbo)\//;
+/** Suffixes that are compiled, minified, generated from a schema, or not text at all. */
+var GENERATED_SUFFIX = /(\.min\.(js|css)|\.map|\.snap|\.d\.ts|[._-]pb\.(ts|js)|\.pb\.go|_pb2\.py|\.gen\.(ts|js|go)|\.generated\.[a-z]+)$/i;
+/** Binary by extension. A patch shows these as "Binary files … differ", with nothing to read. */
+var BINARY_SUFFIX = /\.(png|jpe?g|gif|webp|avif|ico|icns|bmp|tiff?|svgz|pdf|woff2?|ttf|otf|eot|zip|gz|tgz|bz2|xz|7z|rar|wasm|so|dylib|dll|exe|bin|dat|db|sqlite3?|mp[34]|mov|mp4|webm|wav|ogg|jar|class|pyc|node)$/i;
+/**
+* Whether a path is machine-written or unreadable.
+*
+* `.changeset/` entries count: the changeset is a consequence of the change the walkthrough already
+* describes, and a section about it tells the reader nothing the rest of the document did not.
+*/
+var isGeneratedPath = (path) => {
+	const name = path.split("/").pop() ?? path;
+	return LOCKFILES.includes(name) || GENERATED_DIRECTORIES.test(path) || GENERATED_SUFFIX.test(path) || BINARY_SUFFIX.test(path) || path.startsWith(".changeset/") || path.includes("/.changeset/");
+};
+/** A file git could not diff as text, whatever its extension says. */
+var isBinaryPatch = (preamble) => preamble.some((line) => line.startsWith("Binary files ") || line.startsWith("GIT binary patch"));
+/**
+* Whether this file is one the walkthrough should leave alone.
+*
+* A hunk count of zero is NOT generated on its own: a rename or a mode change is still a change a
+* reviewer has to know about, and {@link fillWalkthrough} reports it separately.
+*/
+var isGeneratedFile = (file) => isGeneratedPath(file.path) || isBinaryPatch(file.preamble);
+//#endregion
+//#region src/walkthrough/fill.ts
+/**
+* Opening fence plus its info line; the body is whatever follows up to the matching close. Built per
+* call rather than shared: a `/g` regex carries `lastIndex` between uses.
+*
+* At most three spaces of indent, because four makes it an indented code block in CommonMark rather
+* than a fence.
+*/
+var fencePattern = () => /^( {0,3})(`{3,}|~{3,})[ \t]*diff\b([^\n]*)$/gm;
+var parseAttributes = (info) => {
+	const attributes = {};
+	for (const token of info.trim().match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []) {
+		const separator = token.indexOf("=");
+		if (separator > 0) attributes[token.slice(0, separator)] = token.slice(separator + 1).replace(/^["']|["']$/g, "");
+		else if (!attributes.file) attributes.file = token.replace(/^["']|["']$/g, "");
+	}
+	return attributes;
+};
+var findPlaceholders = (body) => {
+	const placeholders = [];
+	const pattern = fencePattern();
+	let match;
+	while (match = pattern.exec(body)) {
+		const [opening, indent, fence, info] = match;
+		const bodyStart = match.index + opening.length + 1;
+		const close = new RegExp(`^[ \\t]*${fence[0]}{${fence.length},}[ \\t]*$`, "m");
+		close.lastIndex = 0;
+		const rest = body.slice(bodyStart);
+		const closeMatch = close.exec(rest);
+		const contents = closeMatch ? rest.slice(0, closeMatch.index) : rest;
+		const to = closeMatch ? bodyStart + closeMatch.index + closeMatch[0].length : body.length;
+		placeholders.push({
+			from: match.index,
+			to,
+			fence,
+			indent,
+			attributes: parseAttributes(info),
+			empty: contents.trim().length === 0
+		});
+		pattern.lastIndex = to;
+	}
+	return placeholders;
+};
+/** The hunks a fence asks for: those overlapping its `lines=`, or the whole file without one. */
+var selectHunks = (file, lines) => {
+	const range = lines?.match(/^(\d+)(?:\s*[-–]\s*(\d+))?$/);
+	if (!range) return file.hunks;
+	const start = Number(range[1]);
+	const end = range[2] === void 0 ? start : Number(range[2]);
+	const selected = file.hunks.filter((hunk) => hunkOverlaps(hunk, start, end));
+	return selected.length > 0 ? selected : file.hunks;
+};
+var buildFence = (fence, attributes, contents, indent = "") => {
+	const info = Object.entries(attributes).filter(([, value]) => value.length > 0).map(([key, value]) => `${key}=${/\s/.test(value) ? `"${value}"` : value}`).join(" ");
+	return [
+		`${fence}diff${info ? ` ${info}` : ""}`,
+		...contents.split("\n"),
+		fence
+	].map((line) => line.length > 0 ? indent + line : line).join("\n");
+};
+/**
+* Fills the walkthrough's empty diff fences from the pull request's own patch, then reports what the
+* prose never mentioned.
+*
+* The model is asked for placeholders — a path and a line range — rather than diff content, because
+* a model that transcribes a diff gets lines subtly wrong and the result is a review artefact that
+* lies about the change. Here the bytes come from git and only the selection is the model's.
+*/
+var fillWalkthrough = (body, patch) => {
+	const files = parsePatch(patch);
+	const byPath = new Map(files.map((file) => [file.path, file]));
+	const generated = files.filter((file) => isGeneratedFile(file)).map((file) => file.path);
+	const generatedPaths = new Set(generated);
+	const used = /* @__PURE__ */ new Set();
+	const unresolved = [];
+	let filled = "";
+	let cursor = 0;
+	for (const placeholder of findPlaceholders(body)) {
+		const { file: path, ...rest } = placeholder.attributes;
+		const file = path ? byPath.get(path) : void 0;
+		const verbatim = body.slice(placeholder.from, placeholder.to);
+		filled += body.slice(cursor, placeholder.from);
+		cursor = placeholder.to;
+		if (!placeholder.empty) {
+			filled += verbatim;
+			continue;
+		}
+		if (!path) {
+			unresolved.push("(a fence with no file)");
+			filled += verbatim;
+			continue;
+		}
+		if (!file) {
+			unresolved.push(path);
+			filled += verbatim;
+			continue;
+		}
+		if (generatedPaths.has(path)) continue;
+		const hunks = selectHunks(file, rest.lines);
+		if (hunks.length === 0) {
+			filled += verbatim;
+			continue;
+		}
+		for (const hunk of hunks) used.add(hunk);
+		filled += buildFence(placeholder.fence, {
+			file: path,
+			...rest,
+			lines: hunkRange(hunks) ?? rest.lines ?? ""
+		}, renderHunks(hunks), placeholder.indent);
+	}
+	filled += body.slice(cursor);
+	const missed = files.map((file) => ({
+		path: file.path,
+		hunks: file.hunks.filter((hunk) => !used.has(hunk))
+	})).filter((file) => file.hunks.length > 0 && !generatedPaths.has(file.path));
+	const textless = files.filter((file) => file.hunks.length === 0 && !generatedPaths.has(file.path)).map((file) => file.path);
+	const total = files.filter((file) => !generatedPaths.has(file.path)).reduce((count, file) => count + file.hunks.length, 0);
+	const appendix = renderMissed(missed, textless, generated);
+	return {
+		body: appendix ? filled.trimEnd() + "\n" + appendix : filled,
+		missed,
+		textless,
+		generated,
+		unresolved,
+		covered: used.size,
+		total
+	};
+};
+/** The trailing section: everything the walkthrough did not account for, so the diff stays whole. */
+var renderMissed = (missed, textless, generated) => {
+	if (missed.length === 0 && textless.length === 0 && generated.length === 0) return "";
+	const hunks = missed.reduce((count, file) => count + file.hunks.length, 0);
+	const lines = [
+		"",
+		"## Also changed",
+		""
+	];
+	if (missed.length > 0) lines.push(`${hunks} ${hunks === 1 ? "hunk" : "hunks"} across ${missed.length} ${missed.length === 1 ? "file" : "files"} the walkthrough above does not describe.`, "");
+	for (const file of missed) lines.push(buildFence("```", {
+		file: file.path,
+		lines: hunkRange(file.hunks) ?? ""
+	}, renderHunks(file.hunks)), "");
+	if (textless.length > 0) lines.push(`Changed with no lines to show (renamed or mode-only): ${textless.join(", ")}.`, "");
+	if (generated.length > 0) lines.push(`Generated or binary, not shown: ${generated.join(", ")}.`, "");
+	return lines.join("\n");
+};
+//#endregion
+//#region src/walkthrough/plan.ts
+/**
+* Diffs longer than this get the two-stage treatment.
+*
+* Twice the one-shot budget: below that, trimming drops a file or two and the single prompt still
+* sees the shape of the change, and a second model call would buy nothing.
+*/
+var DEFAULT_CHAPTER_THRESHOLD_CHARS = 32e3;
+var PLANNER_SYSTEM_PROMPT = [
+	"You plan the chapters of a walkthrough: the document that takes a reviewer through a pull",
+	"request in the order it is best understood.",
+	"",
+	"You see the files and their sizes, never their contents. Decide the ORDER a reviewer should meet",
+	"this change in, and which files belong together.",
+	"",
+	"Rules:",
+	"- The core of the change comes first. Mechanical consequences (call sites, tests, docs) come",
+	"  after the thing that forced them.",
+	"- A chapter is a reason, not a directory. Files that change for the same reason belong together",
+	"  however far apart they sit in the tree.",
+	"- Every file in the list belongs to exactly one chapter. Do not invent files.",
+	"- Between three and seven chapters. Fewer on a change with one idea, more on a change that",
+	"  genuinely does several things.",
+	"",
+	"Answer with JSON and nothing else:",
+	"{\"title\": \"…\", \"overview\": \"…\", \"chapters\": [{\"title\": \"…\", \"summary\": \"…\", \"files\": [\"…\"]}]}",
+	"",
+	"`title` is the H1 for the document: what the change does, in one line. `overview` is two or",
+	"three sentences on what it does and why, for the reader who has not seen the diff. Each",
+	"chapter's `summary` is one sentence telling that chapter's writer what to explain."
+].join("\n");
+/** The file list the planner sees: path, size of change, and nothing else. */
+var buildPlannerPrompt = (facts, diff) => {
+	const files = parsePatch(diff).filter((file) => !isGeneratedFile(file));
+	const lines = [
+		`Repository: ${facts.owner}/${facts.repo}`,
+		`Pull request: #${facts.number}`,
+		`Title: ${facts.title}`
+	];
+	if (facts.description?.trim()) lines.push("", "Description as written by the author:", facts.description.trim());
+	lines.push("", `Files changed (${files.length}):`, "");
+	for (const file of files) lines.push(`${file.path} (+${file.added}/-${file.removed}, ${file.hunks.length} hunks)`);
+	return lines.join("\n");
+};
+/**
+* Reads the planner's answer.
+*
+* Tolerant of a fenced block or surrounding prose, because a refusal to parse costs the whole run
+* and the recovery — falling back to one-shot — is worse than reading a fence.
+*/
+var parsePlan = (response, paths) => {
+	const text = (response.match(/^[ \t]*(`{3,})[^\n]*\n([\s\S]*?)^[ \t]*\1`*[ \t]*$/m)?.[2] ?? response).trim();
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start < 0 || end <= start) return;
+	let parsed;
+	try {
+		parsed = JSON.parse(text.slice(start, end + 1));
+	} catch {
+		return;
+	}
+	const decoded = decodePlan(parsed);
+	if (!decoded) return;
+	const known = new Set(paths);
+	const claimed = /* @__PURE__ */ new Set();
+	const chapters = [];
+	for (const chapter of decoded.chapters) {
+		const files = chapter.files.filter((path) => known.has(path) && !claimed.has(path));
+		for (const path of files) claimed.add(path);
+		if (files.length > 0) chapters.push({
+			title: chapter.title,
+			files,
+			summary: chapter.summary
+		});
+	}
+	if (chapters.length === 0) return;
+	const unclaimed = paths.filter((path) => !claimed.has(path));
+	if (unclaimed.length > 0) chapters.push({
+		title: "The rest of the change",
+		files: [...unclaimed]
+	});
+	return {
+		title: decoded.title,
+		overview: decoded.overview,
+		chapters
+	};
+};
+/** Fields of the shape the planner was asked for; anything else is dropped rather than carried. */
+var isString = (value) => typeof value === "string";
+/**
+* Reads the model's JSON into the typed shape, field by field.
+*
+* Every value is checked, `summary` included: a non-string there would reach `buildChapterPrompt`
+* and be interpolated into the next prompt as `[object Object]`.
+*/
+var decodePlan = (value) => {
+	if (typeof value !== "object" || value === null) return;
+	const record = value;
+	if (!isString(record.title) || !Array.isArray(record.chapters)) return;
+	const chapters = record.chapters.flatMap((entry) => {
+		if (typeof entry !== "object" || entry === null) return [];
+		const chapter = entry;
+		if (!isString(chapter.title) || !Array.isArray(chapter.files)) return [];
+		return [{
+			title: chapter.title,
+			files: chapter.files.filter(isString),
+			...isString(chapter.summary) ? { summary: chapter.summary } : {}
+		}];
+	});
+	return {
+		title: record.title,
+		overview: isString(record.overview) ? record.overview : "",
+		chapters
+	};
+};
+/** The diff of one chapter's files, in patch order. */
+var chapterDiff = (files, chapter) => {
+	const wanted = new Set(chapter.files);
+	return files.filter((file) => wanted.has(file.path)).map((file) => [...file.preamble, ...file.hunks.flatMap((hunk) => [hunk.header, ...hunk.lines])].join("\n")).join("\n");
+};
+var CHAPTER_SYSTEM_PROMPT = [
+	"You write ONE chapter of a walkthrough of a pull request: the section a reviewer reads to",
+	"understand this part of the change.",
+	"",
+	"You are given the chapter you are writing, the document it belongs to, and the diff of this",
+	"chapter's files only. Other chapters cover the rest; do not describe them.",
+	"",
+	"Output:",
+	"- Open with the H2 heading you are given, exactly as given. No H1, no other H2.",
+	"- Under it, a short paragraph saying what this part does and what constraint it satisfies, then",
+	"  the code it refers to.",
+	"- Reference a change with an EMPTY fenced block, exactly like this, and nothing inside it:",
+	"",
+	"  ```diff file=path/to/file.ts lines=66-99",
+	"  ```",
+	"",
+	"- `file` is the path exactly as the diff gives it. `lines` is the range in the file AFTER the",
+	"  change, from the `@@` header. NEVER put diff content inside the fence: it is filled in for you",
+	"  from the real patch, and anything you write there is discarded.",
+	"- A mechanical change repeated across files is one point: fence the instance that shows the",
+	"  shape and say how many others take it.",
+	"- EVERY file listed in your chapter appears in at least one fence. A file whose hunks do not",
+	"  each earn a paragraph still gets one fence, grouped with the others that change for its reason.",
+	"",
+	"Write for a reviewer reading once. The sentence rule is the one that matters most:",
+	"- ONE IDEA PER SENTENCE, under thirty words. No semicolons joining two clauses, no dashes",
+	"  carrying a second thought, no sentence that needs a comma-separated list of parentheticals.",
+	"  Where you would write a long sentence, write two short ones.",
+	"- Name the mechanism, not the feeling. Prose explains WHY the change is the way it is: the",
+	"  constraint, the failure it avoids, the alternative rejected. Do not narrate what the diff shows.",
+	"- Active voice with the actor named. Plain words. Sentence case headings. No emoji.",
+	"- Output the markdown for this chapter and nothing else. No preamble, no closing summary."
+].join("\n");
+var buildChapterPrompt = (plan, chapter, diff) => [
+	`Document: ${plan.title}`,
+	plan.overview ? `Overview: ${plan.overview}` : "",
+	"",
+	`Your chapter: ## ${chapter.title}`,
+	chapter.summary ? `What it must explain: ${chapter.summary}` : "",
+	"",
+	`Other chapters, for context only: ${plan.chapters.filter((other) => other.title !== chapter.title).map((other) => other.title).join("; ")}`,
+	"",
+	"Diff:",
+	"",
+	diff
+].filter((line) => line !== "").join("\n");
+/** Stitches the planner's opening and the chapter bodies into one document. */
+var assembleWalkthrough = (plan, chapters) => spaceHeadings([
+	`# ${plan.title}`,
+	"",
+	plan.overview,
+	"",
+	...chapters.map((chapter) => chapter.trim())
+].filter((part, index) => part !== "" || index < 3).join("\n").replace(/\n{3,}/g, "\n\n")).trimEnd() + "\n";
+//#endregion
+//#region src/walkthrough/prompt.ts
+/**
+* Measured against Sonnet, whose 16k output budget covers reasoning AND the answer. A whole
+* 75k-character diff is ~33k input tokens, and the model then spends the entire output budget
+* reasoning: the response comes back `finishReason: 'length'` carrying a reasoning block and NO
+* text at all. At ~19k characters the same request answers in full with room to spare.
+*
+* Trimming costs nothing a reader sees, because every hunk the prose does not claim is appended
+* verbatim by {@link fillWalkthrough}.
+*/
+var DEFAULT_MAX_DIFF_CHARS = 16e3;
+/**
+* What the model is for: the ORDER and the REASONS, never the diff content.
+*
+* Every chunk is emitted as an empty fence carrying a path and a line range, which a postprocess
+* fills from the patch itself. A model asked to transcribe a diff gets lines subtly wrong, and a
+* review artefact that misquotes the change is worse than no artefact.
+*/
+var SYSTEM_PROMPT = [
+	"You write walkthroughs of pull requests: one markdown document that takes a reviewer through a",
+	"change in the order it is best understood, rather than in the order the files happen to sort.",
+	"",
+	"Structure:",
+	"- Open with an H1 naming the change, then two or three sentences on what it does and why.",
+	"- Group the change into sections with H2 headings, ordered so each one builds on the last.",
+	"  Put the core of the change first and the mechanical consequences after it.",
+	"- Under a heading, write a short paragraph saying what this part does and what constraint it",
+	"  satisfies, then show the code it refers to.",
+	"",
+	"Showing code — this is the part to get right:",
+	"- Reference a change with an EMPTY fenced block, exactly like this, and nothing inside it:",
+	"",
+	"  ```diff file=path/to/file.ts lines=66-99",
+	"  ```",
+	"",
+	"- `file` is the path exactly as the diff gives it, after the change. `lines` is the range in the",
+	"  file AFTER the change, taken from the `@@` header. Omit `lines` to show the whole file.",
+	"- NEVER put diff content, code, `@@` headers or `+`/`-` lines inside the fence. It is filled in",
+	"  for you from the real patch. Anything you write there is discarded.",
+	"- One fence per point being made. Several fences under one heading is normal.",
+	"",
+	"Style:",
+	"- Prose explains WHY the change is the way it is: the constraint, the failure it avoids, the",
+	"  alternative that was rejected. Do not narrate what the diff already shows.",
+	"- Do not describe every file. Cover what a reviewer must understand; the rest is appended for",
+	"  you under a separate heading.",
+	"- No preamble, no \"this PR\", no closing summary. Output the markdown document and nothing else.",
+	"",
+	"Write for a reviewer reading once:",
+	"- One idea per sentence. Past thirty words, split it. The reader must never backtrack to parse.",
+	"- Name the mechanism, not the feeling: \"the second attempt runs on a warmed socket\", never",
+	"  \"this makes the call more robust\". A sentence that would fit another project unchanged says",
+	"  nothing about this one. Cut it.",
+	"- Active voice with the actor named: \"the compiler validates queries\", not \"queries are validated\".",
+	"- Plain words. Never: additionally, crucial, delve, enhance, leverage, pivotal, robust, seamless,",
+	"  showcase, testament, underscore, utilize. Say \"is\" rather than \"serves as\" or \"stands as\".",
+	"- Sentence case headings. No emoji. No bold label that restates the line it introduces.",
+	"- End a sentence or use a comma rather than an em dash."
+].join("\n");
+/** Trims the patch to the budget, keeping as many files as fit and naming what was left out. */
+var budgetDiff = (diff, maxChars) => {
+	const parsed = parsePatch(diff);
+	const generated = parsed.filter((file) => isGeneratedFile(file)).map((file) => file.path);
+	const files = parsed.filter((file) => !isGeneratedFile(file)).map((file) => ({
+		path: file.path,
+		text: [...file.preamble, ...file.hunks.flatMap((hunk) => [hunk.header, ...hunk.lines])].join("\n")
+	}));
+	const withoutGenerated = files.map((file) => file.text).join("\n");
+	if (withoutGenerated.length <= maxChars) return {
+		diff: generated.length > 0 ? withoutGenerated : diff,
+		omitted: generated
+	};
+	const order = [...files].sort((left, right) => left.text.length - right.text.length);
+	const kept = /* @__PURE__ */ new Set();
+	let used = 0;
+	for (const file of order) {
+		if (used + file.text.length > maxChars) continue;
+		used += file.text.length + 1;
+		kept.add(file.path);
+	}
+	return {
+		diff: files.filter((file) => kept.has(file.path)).map((file) => file.text).join("\n"),
+		omitted: [...generated, ...files.filter((file) => !kept.has(file.path)).map((file) => file.path)]
+	};
+};
+/** The user-side content: what the change is, followed by the diff the fences will be filled from. */
+var buildPrompt = (input, options = {}) => {
+	const { diff, omitted } = budgetDiff(input.diff, options.maxDiffChars ?? DEFAULT_MAX_DIFF_CHARS);
+	const lines = [
+		`Repository: ${input.owner}/${input.repo}`,
+		`Pull request: #${input.number}`,
+		`Title: ${input.title}`
+	];
+	if (input.headBranch && input.baseBranch) lines.push(`Branch: ${input.headBranch} into ${input.baseBranch}`);
+	if (input.description?.trim()) lines.push("", "Description as written by the author:", input.description.trim());
+	if (omitted.length > 0) lines.push("", `Omitted from the diff below for length, and not yours to describe: ${omitted.join(", ")}.`);
+	lines.push("", "Diff:", "", diff);
+	return lines.join("\n");
+};
+/**
+* Decides whether to regenerate, runs the model, fills the chunks, and stores the result.
+*
+* Split from the operation handler so the part with the decisions in it can be tested against a real
+* database without a network or a model: what the handler adds is two HTTP calls.
+*/
+var generateWalkthrough = ({ pullRequest, remote, diff, force, model, narrate, report = () => {}, chapterThresholdChars = DEFAULT_CHAPTER_THRESHOLD_CHARS }) => Effect.gen(function* () {
+	const existing = yield* findWalkthrough(pullRequest);
+	if (existing && !force && remote.commit && !Walkthrough.isStale(existing, remote.commit)) {
+		report(Progress.STATUS_COMPLETE, 5);
+		return {
+			walkthrough: existing,
+			generated: false,
+			covered: existing.covered ?? 0,
+			total: existing.total ?? 0
+		};
+	}
+	report("Writing the walkthrough", 3);
+	const facts = {
+		owner: pullRequest.owner,
+		repo: pullRequest.repo,
+		number: pullRequest.number,
+		title: remote.title ?? pullRequest.title,
+		description: remote.description ?? pullRequest.description,
+		baseBranch: remote.baseBranch ?? pullRequest.baseBranch,
+		headBranch: remote.headBranch ?? pullRequest.headBranch
+	};
+	const chaptered = diff.length > chapterThresholdChars ? yield* narrateChapters(facts, diff, narrate, report) : void 0;
+	const narration = chaptered ?? (yield* narrate(`${SYSTEM_PROMPT}\n\n---\n\n${buildPrompt({
+		...facts,
+		diff
+	})}`));
+	report("Filling the chunks", 4);
+	const filled = fillWalkthrough(narration, diff);
+	const walkthrough = yield* upsert(existing, {
+		pullRequest: Ref.make(pullRequest),
+		title: Walkthrough.makeTitle(pullRequest, remote.title ?? pullRequest.title),
+		body: spaceHeadings(filled.body),
+		commit: remote.commit ?? "",
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		model,
+		covered: filled.covered,
+		total: filled.total
+	});
+	report(Progress.STATUS_COMPLETE, 5);
+	return {
+		walkthrough,
+		strategy: chaptered ? "chaptered" : "one-shot",
+		generated: true,
+		covered: filled.covered,
+		total: filled.total
+	};
+});
+/**
+* Plans the chapters, then narrates each one against its own files.
+*
+* Returns undefined when the plan cannot be read, so the caller falls back to one prompt rather
+* than failing: a walkthrough of part of the change beats no walkthrough.
+*/
+var narrateChapters = (facts, diff, narrate, report) => Effect.gen(function* () {
+	const files = parsePatch(diff).filter((file) => !isGeneratedFile(file));
+	const plan = parsePlan(yield* narrate(`${PLANNER_SYSTEM_PROMPT}\n\n---\n\n${buildPlannerPrompt(facts, diff)}`), files.map((file) => file.path));
+	if (!plan) return;
+	const chapters = [];
+	for (const chapter of plan.chapters) {
+		report(`Writing "${chapter.title}"`, 3);
+		const body = yield* narrate(`${CHAPTER_SYSTEM_PROMPT}\n\n---\n\n${buildChapterPrompt(plan, chapter, chapterDiff(files, chapter))}`);
+		chapters.push(body);
+	}
+	return assembleWalkthrough(plan, chapters);
+});
+/** The walkthrough already written for this pull request, if any. */
+var findWalkthrough = (pullRequest) => Database.query(Filter.type(Walkthrough.Walkthrough, { pullRequest: Ref.make(pullRequest) })).run.pipe(Effect.map(newestWalkthrough), Effect.orDie);
+/**
+* The newest of however many were written, ties broken by id.
+*
+* Two generations racing on one pull request both see none and both add: the check and the write
+* are separate steps, and ECHO has neither a uniqueness constraint nor an atomic upsert to close
+* that. Picking deterministically makes the duplicate inert instead — every reader lands on the
+* same object, and the next regeneration updates that one in place rather than forking again. The
+* loser stays in the space; removing it from a read path would delete another client's object.
+*/
+var newestWalkthrough = (walkthroughs) => walkthroughs.reduce((newest, walkthrough) => {
+	if (!newest) return walkthrough;
+	const left = generatedTime(walkthrough);
+	const right = generatedTime(newest);
+	if (left !== right) return left > right ? walkthrough : newest;
+	return walkthrough.id > newest.id ? walkthrough : newest;
+}, void 0);
+/**
+* Parsed rather than compared as a string: `generatedAt` is an unvalidated date-time, so a value
+* written by anything but this code can carry an offset (`+02:00`) that sorts against a `Z` value
+* the wrong way round. An unparseable or absent one sorts oldest.
+*/
+var generatedTime = (walkthrough) => {
+	const parsed = Date.parse(walkthrough.generatedAt ?? "");
+	return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+};
+/** Replaces the body in place where one exists, so links to the walkthrough survive regeneration. */
+var upsert = (existing, props) => Effect.gen(function* () {
+	if (!existing) return yield* Database.add(Walkthrough.make(props));
+	return Obj.update(existing, (existing) => {
+		existing.title = props.title;
+		existing.body = props.body;
+		existing.commit = props.commit;
+		existing.generatedAt = props.generatedAt;
+		existing.model = props.model;
+		existing.covered = props.covered;
+		existing.total = props.total;
+	});
+});
+//#endregion
+export { renderHunks as a, parsePatch as i, newestWalkthrough as n, spaceHeadings as r, generateWalkthrough as t };
+
+//# sourceMappingURL=chunk-generate.mjs.map