@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/git-diff.js

@@ -0,0 +1,338 @@
+/**
+ * `get_git_diff` — §18's "other useful Git tool": a live textual diff
+ * between two refs. P27's disclosed remainder — `ai-layer-plan.md` §3's
+ * re-derivation found `history.ts`'s own header already stating why it
+ * cannot be stretched into this shape: it is scoped to the stored
+ * `CHANGES_WITH` ledger, not a live `git diff`. `changedFiles`
+ * (`cross-pr.ts`) answers "which files changed" as a bare path list; this
+ * answers "what changed in them" — per-file status and line counts always,
+ * plus the unified-diff patch text when it is cheap enough to hand to a
+ * model (§4: the client's context window is not this tool's to spend).
+ */
+import { applyReplySizeBudget, changedFiles, gitDiff, gitWorkingTreeChange, TOTAL_PATCH_BUDGET_REASON_PREFIX, } from "@descryy/core";
+import { answer, optionalInteger, descryOwnState, optionalString, ToolInputError, optionalStringArray, } from "./kit.js";
+const DEFAULT_LIMIT = 200;
+/**
+ * The stable prefix of `patchOmittedReason` when the *reply's* size ceiling,
+ * rather than either patch budget, is what withheld a patch. A third reason a
+ * caller can tell apart from the other two — and it calls for the same action
+ * as the total patch budget (re-request narrowed), not for raising a limit,
+ * because this ceiling is not the caller's to raise.
+ */
+const REPLY_BUDGET_REASON_PREFIX = "the reply's overall size ceiling";
+/** Bytes this file costs in the encoded `files` array — its JSON plus a separator. */
+function fileBytes(file) {
+    return Buffer.byteLength(JSON.stringify(file), "utf8") + 1;
+}
+/**
+ * `fitToBudget` — the second half of the fix the aggregate patch budget was
+ * only the first half of.
+ *
+ * `maxTotalPatchBytes` bounds the patches and nothing else, so the same real
+ * 48-file diff that motivated it still failed after it shipped: 48 files of
+ * status/additions/deletions rows plus disclosures plus the capped patches
+ * summed past the host's ceiling and the reply was rejected whole. This bounds
+ * what the tool actually returns — patches withheld first, then files dropped
+ * from the list if the bare rows alone do not fit — and says which of the two
+ * happened, so the caller re-requests narrowed instead of reading a short list
+ * as the whole diff.
+ */
+function fitDiff(identity, shown, filesTotal, budgetBytes) {
+    const scaffold = Buffer.byteLength(JSON.stringify({ ...identity, files: [], filesTotal }), "utf8");
+    const fitted = applyReplySizeBudget(shown, {
+        maxTotalBytes: budgetBytes,
+        overheadBytes: scaffold,
+        sizeOf: fileBytes,
+        hasPayload: (f) => f.patch !== null,
+        // Deliberately terse, unlike the other two reasons. This one can land on
+        // every file in a 200-file reply, and a 200-character sentence repeated
+        // 200 times costs more than the patches it is apologising for — the same
+        // arithmetic that made the per-call disclosure boilerplate worth deduping.
+        // What to do about it is stated once, in the reply-level note below.
+        withhold: (f) => ({
+            ...f,
+            patch: null,
+            patchOmittedReason: `${REPLY_BUDGET_REASON_PREFIX} left no room for it`,
+        }),
+    });
+    const notes = [];
+    if (fitted.withheldCount > 0) {
+        notes.push(`${fitted.withheldCount} of the listed file(s) had their patch text withheld to keep this ` +
+            "reply inside its overall size ceiling, not by either patch budget — their stats above are " +
+            'complete. Re-request them with a narrowed "files" to read their patches.');
+    }
+    if (fitted.droppedCount > 0) {
+        notes.push(`${fitted.droppedCount} further changed file(s) are absent from this reply entirely — the ` +
+            "per-file rows for every changed file do not fit inside the reply's size ceiling on their " +
+            'own. This is a limit of one reply, not a finding about those files: re-request them with ' +
+            '"files" to see them.');
+    }
+    return {
+        data: { ...identity, files: fitted.items, filesTotal },
+        notes,
+        ...(fitted.droppedCount > 0
+            ? {
+                truncatedDetail: {
+                    shown: fitted.items.length,
+                    total: filesTotal,
+                    more: null,
+                },
+            }
+            : {}),
+    };
+}
+const SCHEMA = {
+    type: "object",
+    properties: {
+        base: {
+            type: "string",
+            description: "The ref to diff against. Required unless \"workingTree\" is given — there is no " +
+                "defensible default, and guessing one silently changes which diff the answer describes.",
+        },
+        workingTree: {
+            type: "string",
+            enum: ["unstaged", "staged", "all"],
+            description: "Diff uncommitted state instead of two refs. \"unstaged\" is the working tree against " +
+                "the index, \"staged\" the index against HEAD, \"all\" everything not yet committed. " +
+                "Mutually exclusive with \"base\", and never inferred: a working tree and a ref range " +
+                "answer different questions, so the caller declares which one they are asking.",
+        },
+        includeUntracked: {
+            type: "boolean",
+            description: "With \"workingTree\", also report files git has never seen, as new-file patches. On " +
+                "by default, because they are part of the change about to be committed. Pass false to " +
+                "restrict the answer to files git already tracks; the narrowing is stated in the reply.",
+        },
+        head: { type: "string", description: "The tip being diffed. Default HEAD." },
+        files: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict the diff to these repo-relative paths. Default: the whole diff.",
+        },
+        maxPatchBytes: {
+            type: "integer",
+            minimum: 1,
+            description: "A file's patch text is omitted (its status/additions/deletions are still reported) above " +
+                "this many bytes. Default 20,000 — narrow \"files\" to fetch a large file's patch on its own.",
+        },
+        maxTotalPatchBytes: {
+            type: "integer",
+            minimum: 1,
+            description: "The cap on the sum of every patch in the reply. Default 40,000. Files past it are still " +
+                "listed with their status and line counts; only their patch text is withheld, with the " +
+                "budget named as the reason. A per-file cap bounds no total. Note this bounds the patches " +
+                "alone: the reply as a whole is separately held under a fixed size ceiling, which can " +
+                "withhold further patches, and on a very wide diff drop trailing files from the list — " +
+                "both are disclosed and named distinctly from this budget when they happen.",
+        },
+        limit: { type: "integer", minimum: 1, description: "Cap on files in the reply. Default 200." },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const workingTree = optionalString(args, "workingTree");
+    // Defaults **on**, unlike the core primitive it calls. That one is a library
+    // function whose existing callers must not change behaviour by upgrading;
+    // this is the product surface, and a caller who asks for "the working tree"
+    // and is not shown the file they just created has been answered about
+    // something narrower than they asked for.
+    const includeUntracked = args["includeUntracked"] !== false;
+    const baseArg = optionalString(args, "base");
+    if (workingTree === undefined && baseArg === undefined) {
+        // The rule survives the new mode rather than being relaxed by it: one of
+        // the two questions has to be chosen, and neither has a defensible default.
+        throw new ToolInputError('Give either "base" (a ref range) or "workingTree" (uncommitted state). There is no ' +
+            "defensible default, and guessing one silently changes which diff the answer describes.");
+    }
+    if (workingTree !== undefined && baseArg !== undefined) {
+        throw new ToolInputError('"base" and "workingTree" are mutually exclusive — they are two different questions. ' +
+            "Ask one.");
+    }
+    if (workingTree !== undefined && !["unstaged", "staged", "all"].includes(workingTree)) {
+        throw new ToolInputError(`"workingTree" must be "unstaged", "staged" or "all" — got "${workingTree}".`);
+    }
+    const base = baseArg ?? null;
+    const head = base === null ? null : optionalString(args, "head") ?? "HEAD";
+    const files = optionalStringArray(args, "files");
+    const maxPatchBytes = optionalInteger(args, "maxPatchBytes", 1);
+    const maxTotalPatchBytes = optionalInteger(args, "maxTotalPatchBytes", 1);
+    const limit = optionalInteger(args, "limit", 1) ?? DEFAULT_LIMIT;
+    const { session } = ctx;
+    const stamp = session.provider().baseStamp();
+    const envelope = {
+        resolutionFloor: 0, // a live filesystem read, not a graph traversal claim — same convention as similar_incidents' R0 floor
+        commitSha: stamp.commitSha,
+        graphBuiltAt: stamp.graphBuiltAt,
+        irSchemaVersion: stamp.irSchemaVersion,
+        commitSpread: stamp.commitSpread,
+        repoCount: stamp.repoCount,
+        // "This file changed, N lines added/removed" is a name-level fact about
+        // the diff, not a claim about program shape.
+        nameLevel: true,
+    };
+    const scope = (workingTree ?? "all");
+    const subject = base === null ? `the working tree (${scope})` : `${base}...${head}`;
+    const mode = base === null ? "working-tree" : "range";
+    ctx.progress(`Diffing ${subject}`);
+    let all;
+    let untrackedTotal = 0;
+    let untrackedTruncated = false;
+    try {
+        if (base === null) {
+            const change = await gitWorkingTreeChange(session.repoPath, {
+                scope,
+                includeUntracked,
+                exclude: descryOwnState(session.config.graph),
+                ...(files === undefined ? {} : { files }),
+                ...(maxPatchBytes === undefined ? {} : { maxPatchBytes }),
+                ...(maxTotalPatchBytes === undefined ? {} : { maxTotalPatchBytes }),
+            });
+            all = change.files;
+            untrackedTotal = change.untrackedTotal;
+            untrackedTruncated = change.untrackedTruncated;
+        }
+        else {
+            all = await gitDiff(session.repoPath, base, head, {
+                ...(files === undefined ? {} : { files }),
+                ...(maxPatchBytes === undefined ? {} : { maxPatchBytes }),
+                ...(maxTotalPatchBytes === undefined ? {} : { maxTotalPatchBytes }),
+            });
+        }
+    }
+    catch (error) {
+        return answer({
+            ...envelope,
+            headline: `Could not diff ${subject}.`,
+            state: "refused",
+            data: {
+                mode,
+                base,
+                head,
+                files: [],
+                filesTotal: 0,
+                ...(base === null
+                    ? { workingTree: { scope, includeUntracked, untrackedTotal: 0, untrackedTruncated: false } }
+                    : {}),
+            },
+            notes: [
+                `git rejected it: ${error.message.trim()}.`,
+                "No diff was read, which is not a finding that nothing changed.",
+            ],
+        });
+    }
+    // UAT round 3, Suggestion 5, audited into get_git_diff too: `options.files`
+    // is passed straight to `git diff -- <pathspec>` (`sources/git/diff.ts`),
+    // so a filter naming a path with no change in this diff comes back with
+    // zero entries exactly the way a genuinely empty base...head does — the
+    // same `all.length === 0` either way. Reporting both as "has no changes"
+    // would be the contracts/validate collapse one level down: a false
+    // statement about the whole diff when it was really the named files that
+    // matched nothing. Checked against the unfiltered file list — cheap,
+    // name-only, no patch content — so a real empty diff is not confused with
+    // one that has changes the named files simply do not include.
+    // Range mode only: working-tree mode has no second ref to re-diff without
+    // "files", and `changedFiles` needs both.
+    let filesMatchedNothing = false;
+    let wholeDiffCount = 0;
+    if (base !== null && all.length === 0 && files !== undefined && files.length > 0) {
+        ctx.progress(`Checking whether ${base}...${head} has any changes at all`);
+        const wholeDiff = await changedFiles(session.repoPath, base, head).catch(() => null);
+        if (wholeDiff !== null && wholeDiff.length > 0) {
+            filesMatchedNothing = true;
+            wholeDiffCount = wholeDiff.length;
+        }
+    }
+    const shown = all.slice(0, limit);
+    const notes = [];
+    if (filesMatchedNothing) {
+        notes.push(`0 of the ${(files ?? []).length} named file(s) have any change in ${subject}, which ` +
+            `changes ${wholeDiffCount} file(s) in total when read without "files". This is not a ` +
+            "statement that the diff itself is empty.");
+    }
+    if (shown.length < all.length) {
+        notes.push(`${all.length - shown.length} further changed file(s) exist but are not listed — the reply ` +
+            `is capped at ${limit}.`);
+    }
+    const omittedPatches = shown.filter((f) => f.patchOmittedReason !== null).length;
+    if (omittedPatches > 0) {
+        notes.push(`${omittedPatches} of the listed file(s) had their patch text withheld — see each file's own ` +
+            '"patchOmittedReason".');
+    }
+    // Named separately from the per-file cap: this one is not a fact about any
+    // single file, and the action it calls for is different — re-request a
+    // narrowed "files", rather than raise a per-file limit.
+    const budgetWithheld = shown.filter((f) => f.patchOmittedReason?.startsWith(TOTAL_PATCH_BUDGET_REASON_PREFIX)).length;
+    if (budgetWithheld > 0) {
+        notes.push(`${budgetWithheld} of those were withheld by the reply's total patch budget, not by their ` +
+            'own size — their stats above are complete. Re-request them with a narrowed "files" to ' +
+            "read their patches.");
+    }
+    if (base === null && !includeUntracked) {
+        // The half not looked at, named. A working-tree answer that quietly omitted
+        // every never-added file would read as "nothing new here" on exactly the
+        // change that is most often entirely new files.
+        notes.push("Untracked files were not included — no form of git diff reports them, so a file written " +
+            'and not yet added is absent from this answer. Pass "includeUntracked" to see them.');
+    }
+    if (untrackedTruncated) {
+        notes.push(`${untrackedTotal} untracked file(s) exist and only some were diffed. The rest were counted, ` +
+            "not examined.");
+    }
+    return answer({
+        ...envelope,
+        headline: all.length === 0
+            ? filesMatchedNothing
+                ? `0 of the ${(files ?? []).length} named file(s) have any change in ${subject}. ` +
+                    "Not empty, not checked for those files."
+                : `${subject} has no changes.`
+            : `${subject} changes ${all.length} file(s)` +
+                (shown.length < all.length ? `, showing the first ${shown.length}.` : "."),
+        ...(all.length === 0 ? { state: "empty" } : {}),
+        data: {
+            mode,
+            base,
+            head,
+            files: shown,
+            filesTotal: all.length,
+            ...(base === null
+                ? { workingTree: { scope, includeUntracked, untrackedTotal, untrackedTruncated } }
+                : {}),
+        },
+        truncated: shown.length < all.length,
+        ...(shown.length < all.length
+            ? { truncatedDetail: { shown: shown.length, total: all.length, more: null } }
+            : {}),
+        notes,
+        fitToBudget: (budgetBytes) => fitDiff({
+            mode,
+            base,
+            head,
+            ...(base === null
+                ? { workingTree: { scope, includeUntracked, untrackedTotal, untrackedTruncated } }
+                : {}),
+        }, shown, all.length, budgetBytes),
+    });
+}
+export const gitDiffTool = {
+    name: "get_git_diff",
+    class: "read",
+    tier: "evidence",
+    // 2.0.0: the reply is now held under an overall size ceiling, which can
+    // withhold patches the two patch budgets would have allowed and, on a very
+    // wide diff, drop trailing files from the list. Both are disclosed, but a
+    // caller can receive strictly less than 1.0.0 returned for the same call —
+    // a behaviour change, so a version bump, not a patch release.
+    version: "2.0.0",
+    title: "Live textual diff between two refs",
+    description: "A live git diff between two refs — per-file status (added/modified/deleted/renamed), " +
+        "additions/deletions, and unified-diff patch text where it is small enough to include. Reads " +
+        "the working repository directly, not the stored graph — for the graph's stored co-change " +
+        "history use \"history\" instead. A file's patch is withheld above \"maxPatchBytes\", and any " +
+        "patch past the reply's \"maxTotalPatchBytes\" budget, each with a named reason; stats are " +
+        "still reported either way. The whole reply is additionally held under a fixed size ceiling: " +
+        "on a very wide diff that can withhold further patches and, in the extreme, leave trailing " +
+        "files out of the list entirely — always disclosed, never silently.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=git-diff.js.map

package/dist/tools/git-diff.js.map

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

package/dist/tools/git-history.d.ts

@@ -0,0 +1,16 @@
+/** `get_git_history`, §18. Live `git log --follow` for one file — no graph, no staleness. Distinct
+ *  from `history`'s stored `CHANGES_WITH` co-change ledger (built once at `analyze` time); this
+ *  reads the working repository directly. */
+import type { PathLogCommit } from "@descryy/core";
+import { type ToolDefinition } from "./kit.ts";
+export type GitHistoryCommit = PathLogCommit;
+export interface GitHistoryData {
+    readonly file: string;
+    /** Capped by `maxCommits`, newest-first. */
+    readonly commits: readonly GitHistoryCommit[];
+    /** Every commit touching this file, independent of `maxCommits` — a separate count, not
+     *  `commits.length`, so a caller can tell "20 most recent" from "all 3 there are". */
+    readonly totalTouching: number;
+}
+export declare const gitHistoryTool: ToolDefinition;
+//# sourceMappingURL=git-history.d.ts.map

package/dist/tools/git-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-history.d.ts","sourceRoot":"","sources":["../../src/tools/git-history.ts"],"names":[],"mappings":"AAAA;;6CAE6C;AAG7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAA6D,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAM1G,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C;0FACsF;IACtF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAqGD,eAAO,MAAM,cAAc,EAAE,cAa5B,CAAC"}

package/dist/tools/git-history.js

@@ -0,0 +1,106 @@
+/** `get_git_history`, §18. Live `git log --follow` for one file — no graph, no staleness. Distinct
+ *  from `history`'s stored `CHANGES_WITH` co-change ledger (built once at `analyze` time); this
+ *  reads the working repository directly. */
+import { logForPath } from "@descryy/core";
+import { answer, optionalInteger, requiredString } from "./kit.js";
+import { capBySize, sizeCapNote } from "../capped.js";
+const DEFAULT_MAX_COMMITS = 20;
+const SCHEMA = {
+    type: "object",
+    properties: {
+        file: { type: "string", description: "Repository-relative path to read live commit history for." },
+        maxCommits: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on commits returned, newest-first. Default 20.",
+        },
+    },
+    required: ["file"],
+    additionalProperties: false,
+};
+/**
+ * `commits` scales with `maxCommits` (caller-controlled, no upper bound) and
+ * with how long each commit's own subject/body is — a file with a handful of
+ * commits carrying long bodies can still overflow. Rows are self-contained,
+ * so shrinking means dropping trailing (older) commits.
+ */
+function fitGitHistory(rest, shownCommits, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ ...rest, commits: [] }), "utf8");
+    const fit = capBySize(shownCommits, budgetBytes, scaffoldBytes);
+    const notes = fit.droppedForSize === 0 ? [] : [sizeCapNote("commit", fit.shown.length, shownCommits.length, fit.droppedForSize)];
+    return {
+        data: { ...rest, commits: fit.shown },
+        notes,
+        ...(fit.droppedForSize === 0
+            ? {}
+            : { truncatedDetail: { shown: fit.shown.length, total: rest.totalTouching, more: null } }),
+    };
+}
+async function run(args, ctx) {
+    const file = requiredString(args, "file");
+    const maxCommits = optionalInteger(args, "maxCommits", 1) ?? DEFAULT_MAX_COMMITS;
+    const { session } = ctx;
+    const stamp = session.provider().baseStamp();
+    const envelope = {
+        resolutionFloor: 0, // a live git log read, not a graph traversal claim
+        commitSha: stamp.commitSha,
+        graphBuiltAt: stamp.graphBuiltAt,
+        irSchemaVersion: stamp.irSchemaVersion,
+        commitSpread: stamp.commitSpread,
+        repoCount: stamp.repoCount,
+        nameLevel: true,
+    };
+    ctx.progress(`Reading live commit history for ${file}`);
+    let result;
+    try {
+        result = await logForPath(session.repoPath, file, { maxCommits });
+    }
+    catch (error) {
+        return answer({
+            ...envelope,
+            headline: `Could not read history for "${file}".`,
+            state: "refused",
+            data: { file, commits: [], totalTouching: 0 },
+            notes: [
+                `git rejected the read: ${error.message.trim()}.`,
+                "No history was read, which is not a finding that this file has none.",
+            ],
+        });
+    }
+    const notes = [];
+    if (result.totalTouching > result.commits.length) {
+        notes.push(`${result.totalTouching - result.commits.length} further commit(s) touch this file but are ` +
+            `not listed — the reply is capped at ${maxCommits}, newest-first.`);
+    }
+    return answer({
+        ...envelope,
+        headline: result.totalTouching === 0
+            ? `No commit reachable from HEAD touches "${file}".`
+            : `${result.totalTouching} commit(s) touch "${file}"` +
+                (result.commits.length < result.totalTouching
+                    ? `; showing the ${result.commits.length} most recent.`
+                    : "."),
+        ...(result.totalTouching === 0 ? { state: "empty" } : {}),
+        data: { file, commits: result.commits, totalTouching: result.totalTouching },
+        truncated: result.commits.length < result.totalTouching,
+        ...(result.commits.length < result.totalTouching
+            ? { truncatedDetail: { shown: result.commits.length, total: result.totalTouching, more: null } }
+            : {}),
+        notes,
+        fitToBudget: (budgetBytes) => fitGitHistory({ file, totalTouching: result.totalTouching }, result.commits, budgetBytes),
+    });
+}
+export const gitHistoryTool = {
+    name: "get_git_history",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Live commit history for one file",
+    description: "Live git log for a repository-relative file path, following it across renames — sha, date, " +
+        "subject, body and this commit's status for the file, newest-first. Reads the working " +
+        "repository directly, not the stored graph — for the graph's stored file-to-file co-change " +
+        "ledger use \"history\" instead.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=git-history.js.map

package/dist/tools/git-history.js.map

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

package/dist/tools/history.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `history`: co-change (`CHANGES_WITH`) lookup over the stored graph, not a
+ * live `git log`/`diff` — §18's `get_git_history`. Resolves the path
+ * directly, keeping only `type === "FILE"` — `resolveOneNode` would add noise since `CHANGES_WITH` only ever connects FILE nodes.
+ */
+import { type BriefNode, type ToolDefinition } from "./kit.ts";
+/** A file this one moves with, and how strongly. */
+export interface CoChangedFile extends BriefNode {
+    /** Commits in which the two files were touched together. */
+    readonly support: number;
+    /** `support` over the more-frequently-changed file's own total. */
+    readonly confidence: number;
+}
+/** The resolved FILE node. */
+export interface HistoryFileResolved extends BriefNode {
+    readonly resolved: true;
+}
+/** No FILE node at the path, so nothing was read — only the path is known. */
+export interface HistoryFileUnresolved {
+    readonly resolved: false;
+    readonly path: string;
+}
+/** One key, one shape: `resolved` says whether `BriefNode` fields are meaningful — replaces a design where `file` was a bare string on one branch, `undefined` with no error on the other. */
+export type HistoryFile = HistoryFileResolved | HistoryFileUnresolved;
+export interface HistoryReport {
+    readonly file: HistoryFile;
+    /** Capped by `limit`; `coChangedTotal` is the uncapped count. Always
+     *  present, including when `file.resolved` is `false` (0, not omitted). */
+    readonly coChanged: readonly CoChangedFile[];
+    readonly coChangedTotal: number;
+}
+export type HistoryData = HistoryReport;
+export declare const historyTool: ToolDefinition;
+//# sourceMappingURL=history.d.ts.map

package/dist/tools/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/tools/history.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAKL,KAAK,SAAS,EAEd,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAGlB,oDAAoD;AACpD,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,8BAA8B;AAC9B,MAAM,WAAW,mBAAoB,SAAQ,SAAS;IACpD,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,8LAA8L;AAC9L,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,qBAAqB,CAAC;AAEtE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;+EAC2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC;AAiHxC,eAAO,MAAM,WAAW,EAAE,cAYzB,CAAC"}