urtext 0.1.0

package/dist/extract/git.js

@@ -0,0 +1,247 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { WORKTREE } from "../types.js";
+const exec = promisify(execFile);
+/** Run git and return stdout. Throws with stderr attached on failure. */
+export async function git(args, cwd) {
+    const { stdout } = await exec("git", args, {
+        cwd,
+        maxBuffer: 64 * 1024 * 1024,
+        // Pin a stable, unlocalized locale for every invocation. isAbsenceError
+        // below matches known English substrings in git's stderr; under a
+        // non-English LANG/LC_ALL, git would emit translated fatal messages that
+        // match nothing, turning a genuine absence into a thrown error instead
+        // of null. LC_ALL=C is git's own recommendation for machine-parsed
+        // output; LANGUAGE=C additionally covers gettext's LANGUAGE override —
+        // moot on textbook GNU gettext, which ignores LANGUAGE when the locale
+        // is C, but cheap insurance against implementations that consult it
+        // anyway.
+        env: { ...process.env, LC_ALL: "C", LANGUAGE: "C" },
+    });
+    return stdout;
+}
+/**
+ * Absolute path to the top of the working tree containing `cwd`.
+ *
+ * Every path this module handles is repository-root-relative: `git diff`
+ * emits root-relative paths regardless of the directory it runs in, and
+ * `git show <rev>:<path>` resolves `<path>` from the root unless it starts
+ * with `./`. Only the worktree side of readAt touches the filesystem
+ * directly, so it must join against the root and not process.cwd() — from a
+ * subdirectory the latter reads nothing and makes every file look deleted.
+ *
+ * Memoized per cwd: a repository's root does not move during a run, and
+ * readAt is called several times per changed file, so without this the
+ * worktree branch would spawn a git subprocess per read.
+ */
+const ROOTS = new Map();
+export function repoRoot(cwd) {
+    let root = ROOTS.get(cwd);
+    if (!root) {
+        root = git(["rev-parse", "--show-toplevel"], cwd).then((out) => out.trim());
+        // Do not cache a rejection: a later call with a valid repo should retry.
+        root.catch(() => ROOTS.delete(cwd));
+        ROOTS.set(cwd, root);
+    }
+    return root;
+}
+async function exists(cwd, ref) {
+    try {
+        await git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The branch changes are measured against. Prefers the remote's declared
+ * HEAD, then common names, remote before local.
+ */
+export async function defaultBranch(cwd) {
+    // Establish that cwd is a usable git repository before probing for refs.
+    // If this throws (git missing from PATH, cwd not a repo, etc.), let it
+    // propagate — the "pick an explicit range" message below is only correct
+    // once we know we have a repo and simply can't find a default branch.
+    await git(["rev-parse", "--git-dir"], cwd);
+    try {
+        const out = await git(["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], cwd);
+        const ref = out.trim();
+        if (ref)
+            return ref.replace("refs/remotes/", "");
+    }
+    catch {
+        // No origin/HEAD; fall through to the candidate list.
+    }
+    for (const c of ["origin/main", "origin/master", "main", "master"]) {
+        if (await exists(cwd, c))
+            return c;
+    }
+    throw new Error("Could not determine the default branch. Pass an explicit range, e.g. `urtext review HEAD~1`.");
+}
+/**
+ * Resolves one named revision, or explains why it cannot be.
+ *
+ * `git()` rejects with the command it ran, and handing that to the CLI's
+ * error printer answers a request for a parent revision with
+ * "Command failed: git rev-parse ..." — the tool's internals in place of the
+ * reader's problem, and the first thing anyone meets on a shallow or
+ * single-commit clone. (The revision is spelled without its numeral here:
+ * this repository's comment contract reads a bare small integer in a comment
+ * as a restated constant.)
+ *
+ * The message names the cause it can establish rather than listing the
+ * causes it cannot tell apart: a shallow repository genuinely may have the
+ * revision upstream and simply not have fetched it, which is a different
+ * problem with a different fix from a revision that does not exist. See
+ * `test/extract/git.test.ts`, "names the missing revision instead of the git
+ * command that failed".
+ */
+async function resolveRev(cwd, rev) {
+    try {
+        return (await git(["rev-parse", `${rev}^{commit}`], cwd)).trim();
+    }
+    catch {
+        throw new Error(await unresolvedMessage(cwd, rev));
+    }
+}
+/**
+ * Why one revision did not resolve, saying only what can be established.
+ *
+ * Each clause is earned separately. A shallow clone genuinely may hold the
+ * revision upstream, which is a different problem with a different fix from
+ * a revision that does not exist. A history of one commit genuinely has no
+ * parent — but that answers `HEAD~n`, and answers nothing about a mistyped
+ * branch name, where it would be a true fact about the repository offered as
+ * a false explanation. So the parent clause is earned by the shape of the
+ * revision, not by the fact that something failed. See
+ * `test/extract/git.test.ts`, "explains a parent reference with the
+ * history's length only when that is why it failed".
+ */
+async function unresolvedMessage(cwd, rev) {
+    const named = `No revision \`${rev}\` in this repository.`;
+    const shallow = await git(["rev-parse", "--is-shallow-repository"], cwd)
+        .then((out) => out.trim() === "true")
+        .catch(() => false);
+    if (shallow) {
+        return `${named} This is a shallow clone, so it may exist upstream and simply not have been fetched — deepen it with \`git fetch --unshallow\`, or pass a range this clone has.`;
+    }
+    // `~` and `^` are the only spellings that ask for an ancestor, so they are
+    // the only ones a parentless history explains.
+    if (/[~^]/.test(rev)) {
+        const rootOnly = await git(["rev-list", "--count", "HEAD"], cwd)
+            .then((out) => out.trim() === "1")
+            .catch(() => false);
+        if (rootOnly) {
+            return `${named} This repository's history is a single commit, so it has no ancestor to compare against.`;
+        }
+    }
+    return named;
+}
+/**
+ * The merge base of two revisions that have already been resolved.
+ *
+ * Reached only once both names are known to exist, so a failure here is the
+ * one thing it can still be: histories with no commit in common. Saying that
+ * is only honest because the typo case was ruled out first.
+ */
+async function mergeBaseOf(cwd, a, b) {
+    try {
+        return (await git(["merge-base", a, b], cwd)).trim();
+    }
+    catch {
+        throw new Error(`\`${a}\` and \`${b}\` have no commit in common, so there is no merge base to review from. Use a two-dot range to compare them literally, e.g. \`${a}..${b}\`.`);
+    }
+}
+export async function resolveRange(cwd, spec) {
+    if (spec) {
+        const m = spec.match(/^(.*?)(\.{2,3})(.*)$/);
+        if (m) {
+            const a = m[1] || "HEAD";
+            const separator = m[2];
+            const b = m[3] || "HEAD";
+            // `A..B` is literally "from A to B". `A...B` is "from where the two
+            // diverged to B" — the change B introduced, ignoring whatever A gained
+            // meanwhile. Treating the second as the first reports every commit A
+            // made since the fork as a reversal in B, which is a false finding
+            // about files the branch never touched.
+            // Both sides are resolved before either is used, so a range naming a
+            // revision this repository does not have is answered about that
+            // revision. Without it, a three-dot range's typo reaches `merge-base`
+            // and comes back as a claim about the histories having no common
+            // ancestor — a confident wrong answer about the repository.
+            const left = await resolveRev(cwd, a);
+            const to = await resolveRev(cwd, b);
+            const from = separator === "..." ? await mergeBaseOf(cwd, a, b) : left;
+            return { from, to, label: spec };
+        }
+        // A bare revision means "from there to the working tree".
+        return {
+            from: await resolveRev(cwd, spec),
+            to: WORKTREE,
+            label: `vs ${spec}`,
+        };
+    }
+    const base = await defaultBranch(cwd);
+    await resolveRev(cwd, "HEAD");
+    await resolveRev(cwd, base);
+    const mergeBase = await mergeBaseOf(cwd, "HEAD", base);
+    return { from: mergeBase, to: WORKTREE, label: `vs ${base}` };
+}
+/** File contents at a revision, or null when the file is absent there. */
+export async function readAt(cwd, rev, path) {
+    if (rev === WORKTREE) {
+        try {
+            // `path` is repository-root-relative (see repoRoot), so resolve it
+            // against the root rather than the caller's working directory.
+            return await readFile(join(await repoRoot(cwd), path), "utf8");
+        }
+        catch (err) {
+            // ENOENT ("no such file") means the file is genuinely absent. Anything
+            // else (EACCES, EISDIR, ...) is a real failure and must propagate,
+            // not be reported as "not there at this revision".
+            if (isEnoent(err))
+                return null;
+            throw err;
+        }
+    }
+    try {
+        return await git(["show", `${rev}:${path}`], cwd);
+    }
+    catch (err) {
+        // git's stderr wording varies by case, but these phrasings all mean
+        // "the path/revision genuinely does not exist" rather than an
+        // environment or repo problem, so only these map to null:
+        //   - "does not exist in <rev>" — bad path, valid rev
+        //   - "exists on disk, but not in <rev>" — path is untracked/worktree-only
+        //   - "unknown revision or path not in the working tree" — bad rev
+        // Anything else (invalid object name, corrupt repo, git missing, ...)
+        // propagates so callers can't mistake a real failure for absence.
+        if (isAbsenceError(err))
+            return null;
+        throw err;
+    }
+}
+function isEnoent(err) {
+    return (err instanceof Error &&
+        "code" in err &&
+        err.code === "ENOENT");
+}
+const ABSENCE_SIGNALS = [
+    "does not exist in",
+    "exists on disk, but not in",
+    // Not reachable via readAt's `${rev}:${path}` show form today (a bad rev
+    // there yields "invalid object name" instead) — kept as defense-in-depth
+    // in case a future caller invokes git in a form where git emits it.
+    "unknown revision or path not in the working tree",
+];
+function isAbsenceError(err) {
+    const stderr = err instanceof Error && "stderr" in err
+        ? err.stderr
+        : undefined;
+    const text = (typeof stderr === "string" ? stderr : undefined) ??
+        (err instanceof Error ? err.message : String(err));
+    return ABSENCE_SIGNALS.some((signal) => text.includes(signal));
+}

package/dist/extract/index.d.ts

@@ -0,0 +1,4 @@
+import { type AnalysisContext, type Changeset, type RevRange } from "../types.js";
+export { resolveRange, readAt, repoRoot } from "./git.js";
+export declare function createContext(cwd: string, range: RevRange): AnalysisContext;
+export declare function extract(cwd: string, rangeSpec?: string): Promise<Changeset>;

package/dist/extract/index.js

@@ -0,0 +1,57 @@
+import { WORKTREE } from "../types.js";
+import { createProgramAt } from "../analyze/program.js";
+import { countUntracked, diffText, parseUnifiedDiff } from "./diff.js";
+import { readAt, repoRoot, resolveRange } from "./git.js";
+import { isTypeScriptFile, mapSymbols } from "./symbols.js";
+export { resolveRange, readAt, repoRoot } from "./git.js";
+export function createContext(cwd, range) {
+    // Memoized per revision, and only ever built on demand: constructing a
+    // program parses every TypeScript file in the repository, so an analyzer
+    // that never asks for one must not pay for it.
+    const programs = new Map();
+    return {
+        cwd,
+        range,
+        readAt: (rev, path) => readAt(cwd, rev, path),
+        programAt(rev) {
+            let program = programs.get(rev);
+            if (!program) {
+                program = createProgramAt(cwd, rev);
+                // Do not cache a rejection: a transient git failure should not
+                // poison every later request for this revision.
+                program.catch(() => programs.delete(rev));
+                programs.set(rev, program);
+            }
+            return program;
+        },
+    };
+}
+export async function extract(cwd, rangeSpec) {
+    // Everything downstream speaks repository-root-relative paths, so anchor
+    // the whole extraction at the root — `urtext review` has to mean the same
+    // thing from a subdirectory as it does from the top.
+    const root = await repoRoot(cwd);
+    const range = await resolveRange(root, rangeSpec);
+    const parsed = parseUnifiedDiff(await diffText(root, range));
+    const files = [];
+    for (const p of parsed) {
+        // mapSymbols discards non-TypeScript files anyway; reading them out of
+        // git first only pulls lockfiles and binaries into memory as utf8.
+        const wanted = isTypeScriptFile(p.path);
+        const beforePath = p.previousPath ?? p.path;
+        const before = !wanted || p.status === "added"
+            ? null
+            : await readAt(root, range.from, beforePath);
+        const after = !wanted || p.status === "deleted"
+            ? null
+            : await readAt(root, range.to, p.path);
+        files.push({
+            ...p,
+            symbols: mapSymbols(p.path, before, after, p.hunks),
+        });
+    }
+    // Untracked files only bear on a comparison that ends at the working tree;
+    // between two commits there is nothing to have been left out.
+    const untrackedCount = range.to === WORKTREE ? await countUntracked(root) : 0;
+    return { range, files, untrackedCount };
+}

package/dist/extract/intent.d.ts

@@ -0,0 +1,64 @@
+import { type RevRange } from "../types.js";
+/**
+ * Where a stated intent came from. One member today; a `--intent` override
+ * would add a second, and INTENT_SOURCE_LABEL in `../interpret/prompt.ts`
+ * makes adding one a compile error until the prompt block is told how to
+ * introduce it.
+ */
+export type IntentSource = "commits";
+export interface IntentCommit {
+    /** Abbreviated hash, shown so a reader of the prompt can find the commit. */
+    hash: string;
+    /** First line of the message. */
+    subject: string;
+    /** Remaining lines, trailers stripped, empty when there is no body. */
+    body: string;
+}
+export interface Intent {
+    source: IntentSource;
+    /** At least one. A zero-commit range yields `undefined`, never an empty Intent. */
+    commits: IntentCommit[];
+    /** Commits in the range that did not fit MAX_INTENT_COMMITS. Zero when all fit. */
+    omitted: number;
+    /** True when the range ends at the working tree, so part of the diff is described by no message. */
+    endsAtWorkingTree: boolean;
+}
+/**
+ * The most commit messages carried into one prompt's stated-intent block.
+ * Bounds prompt size on a long range, the same job MAX_FACTS does for facts;
+ * see `test/extract/intent.test.ts`, "caps a long range, keeps the newest,
+ * and reports the exact omitted count".
+ */
+export declare const MAX_INTENT_COMMITS = 30;
+/**
+ * The most code points one commit message contributes, subject and body
+ * together, after trailer stripping. A single squash-merge body can otherwise
+ * consume the whole block's budget and push every other message's intent out
+ * of the prompt.
+ */
+export declare const MAX_INTENT_MESSAGE_CHARS = 600;
+/** Appended to a message the cap cut, so no sentence merely appears to end. */
+export declare const INTENT_TRUNCATION_MARKER = "\u2026 [message truncated]";
+/** A trailer line — provenance metadata, not prose about the change. */
+export declare const TRAILER_LINE: RegExp;
+/** The one `git log --format` string; the parser reads its separators from here too. */
+export declare const INTENT_LOG_FORMAT = "%h%x1f%s%x1f%b%x1e";
+/**
+ * The stated intent for a range: the messages of the non-merge commits in it,
+ * bounded by MAX_INTENT_COMMITS with the remainder counted rather than
+ * hidden.
+ *
+ * Two invocations, both bounded. Counting by reading every message instead
+ * would be one call but unbounded on a long range; a capped log plus a count
+ * is bounded and exact, and both calls resolve the head the same way, so the
+ * count and the messages can never describe different ranges.
+ *
+ * A `git()` rejection from either call returns `undefined` rather than
+ * propagating — the same degradation rule the rest of the pipeline applies: a
+ * review missing its intent block is a review; a review that died collecting
+ * one is not. The absence then travels the ordinary disclosure path in
+ * `../interpret/index.ts`, so the user is told either way. See
+ * `test/extract/intent.test.ts`, "returns undefined rather than rejecting
+ * when git fails".
+ */
+export declare function collectIntent(cwd: string, range: RevRange): Promise<Intent | undefined>;

package/dist/extract/intent.js

@@ -0,0 +1,238 @@
+import { WORKTREE } from "../types.js";
+import { git } from "./git.js";
+/**
+ * The most commit messages carried into one prompt's stated-intent block.
+ * Bounds prompt size on a long range, the same job MAX_FACTS does for facts;
+ * see `test/extract/intent.test.ts`, "caps a long range, keeps the newest,
+ * and reports the exact omitted count".
+ */
+export const MAX_INTENT_COMMITS = 30;
+/**
+ * The most code points one commit message contributes, subject and body
+ * together, after trailer stripping. A single squash-merge body can otherwise
+ * consume the whole block's budget and push every other message's intent out
+ * of the prompt.
+ */
+export const MAX_INTENT_MESSAGE_CHARS = 600;
+/** Appended to a message the cap cut, so no sentence merely appears to end. */
+export const INTENT_TRUNCATION_MARKER = "… [message truncated]";
+/** A trailer line — provenance metadata, not prose about the change. */
+export const TRAILER_LINE = /^[A-Za-z][A-Za-z0-9-]*: /;
+/** The one `git log --format` string; the parser reads its separators from here too. */
+export const INTENT_LOG_FORMAT = "%h%x1f%s%x1f%b%x1e";
+/**
+ * The unit and record separator characters INTENT_LOG_FORMAT asks git for,
+ * read back out of that one constant rather than written a second time here.
+ * A commit body contains newlines by definition, so a newline-delimited parse
+ * is wrong on the first multi-line body it meets; a builder and a parser
+ * holding private copies of the separators is the other way this goes wrong,
+ * and deriving them closes it. The escapes are spelled only inside the format
+ * string above and never in a comment — the comment contract's guarded set
+ * includes a value the escapes are written with.
+ */
+const SEPARATORS = [...INTENT_LOG_FORMAT.matchAll(/%x([0-9A-Fa-f]{2})/g)].map((m) => String.fromCharCode(Number.parseInt(m[1], 16)));
+const FIELD_SEPARATOR = SEPARATORS[0];
+const RECORD_SEPARATOR = SEPARATORS[SEPARATORS.length - 1];
+/**
+ * Removes every separator character left inside a field. git escapes nothing
+ * in a commit message, so a body can hold the very characters
+ * INTENT_LOG_FORMAT delimits records and fields with; the split has already
+ * consumed each separator git itself wrote, so one still sitting inside a
+ * field is text an author typed — text that would otherwise fabricate
+ * structure the log never emitted. See `test/extract/intent.test.ts`, "keeps
+ * a planted field separator from fabricating a field".
+ */
+function withoutSeparators(text) {
+    return SEPARATORS.reduce((scrubbed, separator) => scrubbed.split(separator).join(""), text);
+}
+/**
+ * The line terminators a commit message can carry that git does not strip and
+ * `intentBlock` in `../interpret/prompt.ts` does not indent: NEL (U+0085),
+ * vertical tab (U+000B), form feed (U+000C), LINE SEPARATOR (U+2028), and
+ * PARAGRAPH SEPARATOR (U+2029). A consumer may honor any of them as a line
+ * break, so wherever the block renders field text on a line, one left in place
+ * begins a fresh line with the author's words at column 0. Carriage return and
+ * line feed are deliberately absent: those are the body's legitimate line
+ * structure, which `intentBlock` splits on and indents, and must survive.
+ * Named once here so the two collapses below cannot hold divergent copies of
+ * the set.
+ */
+const EXOTIC_LINE_BREAKS = "\u0085\u000B\u000C\u2028\u2029";
+/**
+ * Collapses line breaks to spaces. A field the prompt block renders as part
+ * of its own line structure — the hash and the subject, which share an
+ * entry's line — must carry no break of its own: a break there would begin a
+ * line with text an author wrote, outside the frame that marks the block as
+ * data rather than instruction. Collapsed rather than dropped, so the words
+ * stay readable on the entry they belong to. Every break a consumer may honor
+ * counts, not just carriage return and line feed but every EXOTIC_LINE_BREAKS
+ * member too. See `test/extract/intent.test.ts`, "never lets planted text
+ * reach the start of a line in the rendered intent block" and "collapses every
+ * line terminator a fabricated field may carry".
+ */
+function asOneLine(text) {
+    return text.replace(new RegExp(`[\\r\\n${EXOTIC_LINE_BREAKS}]+`, "g"), " ");
+}
+/**
+ * Canonicalizes a body's line breaks down to a single character. A carriage
+ * return — alone or as a CRLF pair — becomes a line feed: a carriage return
+ * is a real line break (UAX #14), so it earns its own indented continuation
+ * line rather than being dropped or left to ride mid-line. Every
+ * EXOTIC_LINE_BREAKS member becomes a space: those are not a body's prose
+ * structure — a body that legitimately spans lines does so on a line feed,
+ * never on NEL or a separator — so a space is the honest neutralization.
+ *
+ * Invariant, and the whole point of the seam: after tameBodyBreaks the only
+ * character in a body that any consumer treats as a line break is a line
+ * feed. `intentBlock` in `../interpret/prompt.ts` splits on that one
+ * character and indents each piece, so the block's idea of a break and a
+ * downstream consumer's cannot disagree — the mismatch that let a break the
+ * split did not recognize (a lone carriage return, an exotic terminator)
+ * ride to column 0. Applied at parse time, so the invariant holds for every
+ * consumer of a stored body, a future intent source included. See
+ * `test/extract/intent.test.ts`, "no line-break character in a body carries
+ * text to column 0".
+ */
+function tameBodyBreaks(text) {
+    return text
+        .replace(/\r\n?/g, "\n")
+        .replace(new RegExp(`[${EXOTIC_LINE_BREAKS}]`, "g"), " ");
+}
+/**
+ * Drops the run of trailer lines at the tail of a body, together with the
+ * blank lines separating it from the prose. Trailers are provenance metadata
+ * — co-authorship, sign-off, session links — and on agentic commits they are
+ * frequently the majority of the body's bytes. Only the tail run goes: a
+ * colon-prefixed line in the middle of a body is prose about the change and
+ * stays. See `test/extract/intent.test.ts`, "strips a trailer run at the tail
+ * while keeping a colon-prefixed line mid-body".
+ */
+function stripTrailers(body) {
+    const lines = body.split(/\r?\n/);
+    let end = lines.length;
+    while (end > 0) {
+        const line = lines[end - 1];
+        if (line.trim() === "" || TRAILER_LINE.test(line)) {
+            end--;
+            continue;
+        }
+        break;
+    }
+    return lines.slice(0, end).join("\n");
+}
+/**
+ * Subject and body together, capped in code points. `String#slice` counts
+ * UTF-16 units, so an astral character straddling the cut stores a lone
+ * surrogate that every downstream layer then faithfully preserves — the
+ * reason `truncateSignature` in `../analyze/surface.ts` counts the same way.
+ * A cut message ends with INTENT_TRUNCATION_MARKER, so the model is never
+ * shown a sentence that merely appears to end. A message that is empty after
+ * stripping keeps its subject: a commit whose body was nothing but trailers
+ * still stated an intent in its subject line. See
+ * `test/extract/intent.test.ts`, "cuts a long message on a code-point
+ * boundary and marks it".
+ */
+function capMessage(commit) {
+    const subject = [...commit.subject];
+    if (subject.length >= MAX_INTENT_MESSAGE_CHARS) {
+        return {
+            hash: commit.hash,
+            subject: subject.slice(0, MAX_INTENT_MESSAGE_CHARS).join("") + INTENT_TRUNCATION_MARKER,
+            body: "",
+        };
+    }
+    const budget = MAX_INTENT_MESSAGE_CHARS - subject.length;
+    const body = [...commit.body];
+    if (body.length <= budget)
+        return commit;
+    return {
+        hash: commit.hash,
+        subject: commit.subject,
+        body: body.slice(0, budget).join("") + INTENT_TRUNCATION_MARKER,
+    };
+}
+/**
+ * Oldest first: `git log` emits newest first, and the block reads in the
+ * order the change was built. See `test/extract/intent.test.ts`, "lists
+ * commits oldest first, the order the change was built in".
+ */
+function parseIntentLog(out) {
+    const commits = [];
+    for (const record of out.split(RECORD_SEPARATOR)) {
+        // git writes a newline after each formatted record; it belongs to the
+        // separator, not to the next commit's hash.
+        const text = record.replace(/^\r?\n/, "");
+        if (text === "")
+            continue;
+        const fields = text.split(FIELD_SEPARATOR);
+        // A record short of its fields is malformed output, not a commit with an
+        // empty body — dropping it is the honest reading.
+        if (fields.length < 3)
+            continue;
+        // Scrubbed here, at the seam where text becomes structure: this is the
+        // only place that can still tell a separator git wrote from one an
+        // author typed, and every field a commit is built from passes through
+        // it — the hash included.
+        const body = stripTrailers(tameBodyBreaks(withoutSeparators(fields.slice(2).join(FIELD_SEPARATOR))));
+        commits.push(capMessage({
+            hash: asOneLine(withoutSeparators(fields[0])),
+            subject: asOneLine(withoutSeparators(fields[1])),
+            body,
+        }));
+    }
+    return commits.reverse();
+}
+/**
+ * The stated intent for a range: the messages of the non-merge commits in it,
+ * bounded by MAX_INTENT_COMMITS with the remainder counted rather than
+ * hidden.
+ *
+ * Two invocations, both bounded. Counting by reading every message instead
+ * would be one call but unbounded on a long range; a capped log plus a count
+ * is bounded and exact, and both calls resolve the head the same way, so the
+ * count and the messages can never describe different ranges.
+ *
+ * A `git()` rejection from either call returns `undefined` rather than
+ * propagating — the same degradation rule the rest of the pipeline applies: a
+ * review missing its intent block is a review; a review that died collecting
+ * one is not. The absence then travels the ordinary disclosure path in
+ * `../interpret/index.ts`, so the user is told either way. See
+ * `test/extract/intent.test.ts`, "returns undefined rather than rejecting
+ * when git fails".
+ */
+export async function collectIntent(cwd, range) {
+    const endsAtWorkingTree = range.to === WORKTREE;
+    const head = endsAtWorkingTree ? "HEAD" : range.to;
+    const span = `${range.from}..${head}`;
+    let log;
+    let total;
+    try {
+        log = await git([
+            "log",
+            "--no-merges",
+            "-n",
+            String(MAX_INTENT_COMMITS),
+            `--format=${INTENT_LOG_FORMAT}`,
+            span,
+        ], cwd);
+        total = await git(["rev-list", "--count", "--no-merges", span], cwd);
+    }
+    catch {
+        return undefined;
+    }
+    const commits = parseIntentLog(log);
+    // A range of nothing but merge commits collects nothing and takes this
+    // path, which is the honest result: the merges' own messages state nothing
+    // about the code, and the commits they brought in are already in the range.
+    if (commits.length === 0)
+        return undefined;
+    const counted = Number.parseInt(total.trim(), 10);
+    return {
+        source: "commits",
+        commits,
+        // Truncation keeps the newest: later commits describe what the change
+        // became, and later work commonly amends earlier work.
+        omitted: Number.isFinite(counted) ? Math.max(counted - commits.length, 0) : 0,
+        endsAtWorkingTree,
+    };
+}