@imenam/mcp-documentor 1.0.86 → 1.0.88

package/dist/src/index.js

@@ -9,6 +9,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { APP_VERSION } from "./version.js";
 import { GuiLauncher, createLogger, setupLogging } from "@imenam/mcp-gui-interface";
 import { resolveLogDir } from "./core/log-dir.js";
+import { initGitHubLog, runTriggeredBy } from "./core/github-log.js";
 import { StorageEngine } from "./core/storage-engine.js";
 import { EmbeddingStore } from "./core/embedding-store.js";
 import { EmbeddingEngine } from "./core/embedding-engine.js";
@@ -35,6 +36,8 @@ import { gitDiffDoc } from "./tools/git-diff-doc.js";
 import { checkLinks } from "./tools/check-links.js";
 import { deleteDoc } from "./tools/delete-doc.js";
 import { moveDoc } from "./tools/move-doc.js";
+import { deleteProject } from "./tools/delete-project.js";
+import { createProject } from "./tools/create-project.js";
 import { getDocTree } from "./tools/get-doc-tree.js";
 import { migrateFolders } from "./core/migrate-folders.js";
 import { migrateEmbeddings } from "./core/migrate-embeddings.js";
@@ -79,6 +82,7 @@ function findProjectRoot(startDir) {
 const rootDir = findProjectRoot(__dirname);
 const packageEnvPath = path.join(rootDir, ".env");
 setupLogging({ processLabel: "mcp-documentor", logDir: resolveLogDir(rootDir) });
+initGitHubLog(resolveLogDir(rootDir));
 const logger = createLogger("mcp-documentor");
 function getConfig() {
     if (fs.existsSync(packageEnvPath)) {
@@ -126,9 +130,13 @@ function broadcastToGUI(message) {
         }
     }
 }
-/** Each GUI message is one operation: the branch head it reads is resolved once, and freshly. */
+/**
+ * Each GUI message is one operation: the branch head it reads is resolved once, and freshly.
+ * GitHub calls it makes are attributed to it in github.log.
+ */
 function handleIPCMessage(msg) {
-    return runInCodeOperation(() => dispatchIPCMessage(msg));
+    const trigger = `GUI · ${String(msg?.type ?? "unknown").toLowerCase().replace(/_/g, " ")}`;
+    return runInCodeOperation(() => runTriggeredBy(trigger, () => dispatchIPCMessage(msg)));
 }
 function dispatchIPCMessage(msg) {
     if (msg.type === "ALREADY_RUNNING") {
@@ -1129,15 +1137,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "move_doc",
-            description: "Move a documentation entry to a new path (changes its folder and/or name). All existing doc:// links and related_docs references pointing to the old path are automatically rewritten across the project. This is the only way to relocate a document — update_doc does not change the location.",
+            description: "Move a documentation entry to a new path (changes its folder and/or name) and/or to another project. All existing doc:// links and related_docs references pointing to the old location are automatically rewritten across all projects. When the entry changes project, its own links keep their target: bare ones are qualified with the source project, and those into the target project become bare. Links are always bare within their own project. Its tracked_files are then resolved against the target project's code source. This is the only way to relocate a document — update_doc does not change the location. Provide new_path, new_project, or both.",
             inputSchema: {
                 type: "object",
                 properties: {
                     path: { type: "string", description: "Current path of the documentation entry, e.g. 'backend/authentication'" },
-                    new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both." },
-                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " The doc stays in this project — move_doc never moves an entry across projects." },
+                    new_path: { type: "string", description: "New path for the documentation entry, e.g. 'backend/v2/authentication'. Can change folder, name, or both. Omitted: the entry keeps its current path (new_project is then required)." },
+                    project: { type: "string", description: PROJECT_PARAM_DESCRIPTION + " This is the project the entry is moved from." },
+                    new_project: { type: "string", description: "Project the entry is moved to. Must already exist (see list_projects; create it with create_project). Omitted: the entry stays in `project`." },
                 },
-                required: ["path", "new_path", "project"],
+                required: ["path", "project"],
             },
         },
         {
@@ -1172,6 +1181,38 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 properties: {},
             },
         },
+        {
+            name: "create_project",
+            description: "Create an empty documentation project, optionally with its code source (as set_code_source would set it). A GitHub repository and branch are checked first: if they cannot be found, nothing is created.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Name of the project to create. Must not exist yet, nor contain '/', '\' or ':'." },
+                    code_source: {
+                        type: "object",
+                        description: "Where the project's code is read from (defaults to the local working copy).",
+                        properties: {
+                            kind: { type: "string", enum: ["local", "github"], description: "'local' reads the working copy, 'github' reads a repository branch" },
+                            repo: { type: "string", description: "Repository when kind is 'github': 'owner/repo' or a GitHub URL" },
+                            branch: { type: "string", description: "Branch when kind is 'github' (defaults to the repository's default branch)" },
+                        },
+                        required: ["kind"],
+                    },
+                },
+                required: ["project"],
+            },
+        },
+        {
+            name: "delete_project",
+            description: "Delete an empty documentation project. Refuses — and lists what remains — while the project holds any doc, image or other file besides its settings: move_doc (with new_project) or delete_doc its entries first. Also forgets this machine's code root for the project.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: { type: "string", description: "Project to delete. Must exist and be empty." },
+                },
+                required: ["project"],
+            },
+        },
         {
             name: "refresh_file_snapshot",
             description: "Mark tracked files as up-to-date by updating their snapshot timestamps. Use when file changes don't affect the documentation. Accepts one or more doc paths.",
@@ -1207,7 +1248,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "patch_doc",
-            description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. Always use this instead of update_doc when making partial changes.",
+            description: "PREFERRED method for modifying documentation. Replaces a specific portion of a documentation entry's content using an exact search-and-replace, without touching the rest of the doc. The search text must occur exactly once, unless replace_all is set; the answer gives the number of occurrences replaced. The replacement is inserted verbatim. Always use this instead of update_doc when making partial changes.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1216,6 +1257,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                     ...textSourceProperties("search", "the search text"),
                     replacement: { type: "string", description: "Text to replace it with. Supports [copy-from-codebase|/absolute/path/to/file.ts|startLine|endLine] — the tag is replaced at save time by a fenced code block, and the file+range is automatically added to tracked_files. IMPORTANT: always read the source file first to identify the exact line numbers before writing the tag." },
                     ...textSourceProperties("replacement", "the replacement"),
+                    replace_all: { type: "boolean", description: "Replace every occurrence of the search text. Without it, a search text that occurs more than once is refused." },
                     project: { type: "string", description: PROJECT_PARAM_DESCRIPTION },
                 },
                 required: ["path", "project"],
@@ -1223,7 +1265,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
             name: "git_diff_doc",
-            description: "Show the git diff for each tracked file of one or more docs, between their current state and the last commit before the stored snapshot date.",
+            description: "Show, for each changed tracked file of one or more docs, the diff between the content recorded at its last snapshot and its current content at the project's code source. The snapshot content is read from the recorded blob, else from the recorded commit, else from the newest commit at or before the snapshot date; it is checked against the stored hash, and the diff is reported impossible when it does not match.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1520,8 +1562,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     };
 });
 // Each tool call is one operation: the branch head every tracked file is compared against is
-// resolved once for the whole call, and never carried over to the next one.
-server.setRequestHandler(CallToolRequestSchema, (request) => runInCodeOperation(() => handleToolCall(request)));
+// resolved once for the whole call, and never carried over to the next one. GitHub calls it makes
+// are attributed to the tool in github.log.
+server.setRequestHandler(CallToolRequestSchema, (request) => runInCodeOperation(() => runTriggeredBy(request.params.name, () => handleToolCall(request))));
 async function handleToolCall(request) {
     const { name, arguments: args } = request.params;
     if (isReadOnly() && WRITE_TOOLS.has(name)) {
@@ -1554,12 +1597,35 @@ async function handleToolCall(request) {
                             type: "text",
                             text: "set_project no longer exists: there is no active project. " +
                                 "Pass the project explicitly to every tool call (use list_projects to see them). " +
-                                "A project is created on demand by create_doc.",
+                                "Create a project with create_project, or on demand with create_doc.",
                         },
                     ],
                 };
             case "list_projects":
                 return await listProjects(storageEngine);
+            case "create_project": {
+                const result = await createProject(storageEngine, localState, args);
+                if (!result.isError) {
+                    broadcastToGUI({
+                        type: "PROJECTS_CHANGED",
+                        data: { projects: storageEngine.getConfig().projects },
+                        timestamp: new Date().toISOString(),
+                    });
+                    broadcastCodeSourcesChanged(args?.project);
+                }
+                return result;
+            }
+            case "delete_project": {
+                const result = await deleteProject(storageEngine, localState, args);
+                if (!result.isError) {
+                    broadcastToGUI({
+                        type: "PROJECTS_CHANGED",
+                        data: { projects: storageEngine.getConfig().projects },
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                return result;
+            }
             case "refresh_file_snapshot":
                 return await refreshFileSnapshot(storageEngine, historyStore, args);
             case "get_doc_metadata":
@@ -1684,7 +1750,7 @@ async function syncPullOnStartup() {
 async function main() {
     await migrateFolders(storageEngine);
     await migrateEmbeddings(embeddingStore, storageEngine);
-    await syncPullOnStartup();
+    await runTriggeredBy("startup sync", syncPullOnStartup);
     migrateCodeSources(storageEngine, localState);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/src/tools/code-sources.d.ts

@@ -88,6 +88,15 @@ export declare function getCodeSourceTool(storageEngine: StorageEngine, localSta
         text: string;
     }[];
 }>;
+/** A code source as an agent describes it. */
+export interface CodeSourceInput {
+    kind?: string;
+    repo?: string;
+    branch?: string;
+}
+/** Turns an agent's description into a configuration, checking a GitHub repository and branch exist. */
+export declare function resolveCodeSourceInput({ kind, repo, branch }: CodeSourceInput): Promise<CodeSourceConfig>;
+export declare function describeCodeSourceConfig(config: CodeSourceConfig): string;
 export declare function setCodeSourceTool(storageEngine: StorageEngine, localState: LocalState, args: unknown): Promise<{
     content: {
         type: string;

package/dist/src/tools/code-sources.js

@@ -221,29 +221,31 @@ export async function getCodeSourceTool(storageEngine, localState, args) {
         `The code source is shared by every machine (synced with the docs); code roots belong to this machine.`;
     return { content: [{ type: "text", text }] };
 }
-export async function setCodeSourceTool(storageEngine, localState, args) {
-    const { project, kind, repo, branch } = (args ?? {});
-    if (!project)
-        throw new Error("project is required");
-    assertKnownProject(storageEngine, project);
-    let config;
-    if (kind === "local") {
-        config = { kind: "local" };
-    }
-    else if (kind === "github") {
+/** Turns an agent's description into a configuration, checking a GitHub repository and branch exist. */
+export async function resolveCodeSourceInput({ kind, repo, branch }) {
+    if (kind === "local")
+        return { kind: "local" };
+    if (kind === "github") {
         if (!repo)
             throw new Error('repo is required when kind is "github"');
         const inspection = await inspectRepository({ repo, branch });
         if (!inspection.ok)
             throw new Error(inspection.error);
-        config = { kind: "github", repo: inspection.repo.fullName, ...(branch && { branch: inspection.branch }) };
-    }
-    else {
-        throw new Error('kind must be "local" or "github"');
+        return { kind: "github", repo: inspection.repo.fullName, ...(branch && { branch: inspection.branch }) };
     }
+    throw new Error('kind must be "local" or "github"');
+}
+export function describeCodeSourceConfig(config) {
+    return config.kind === "github" ? `GitHub ${config.repo} · ${config.branch ?? "default branch"}` : "its local working copy";
+}
+export async function setCodeSourceTool(storageEngine, localState, args) {
+    const { project, ...input } = (args ?? {});
+    if (!project)
+        throw new Error("project is required");
+    assertKnownProject(storageEngine, project);
+    const config = await resolveCodeSourceInput(input);
     saveCodeSource(storageEngine, localState, project, config);
-    const where = config.kind === "github" ? `GitHub ${config.repo} · ${config.branch ?? "default branch"}` : "its local working copy";
-    return { content: [{ type: "text", text: `Project "${project}" now reads its code from ${where}.` }] };
+    return { content: [{ type: "text", text: `Project "${project}" now reads its code from ${describeCodeSourceConfig(config)}.` }] };
 }
 export function setCodeRootTool(storageEngine, localState, args) {
     const { path: root, project } = (args ?? {});

package/dist/src/tools/create-project.d.ts

@@ -0,0 +1,19 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { LocalState } from "../core/local-state.js";
+/**
+ * Creates an empty project, with its code source when one is given. The source is checked before
+ * anything is written, so an unknown repository or branch creates nothing.
+ */
+export declare function createProject(storageEngine: StorageEngine, localState: LocalState, args: unknown): Promise<{
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+} | {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+}>;

package/dist/src/tools/create-project.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { describeCodeSourceConfig, resolveCodeSourceInput, saveCodeSource } from "./code-sources.js";
+const CreateProjectArgsSchema = z.object({
+    project: z
+        .string()
+        .trim()
+        .min(1)
+        .refine((name) => name !== "." && name !== ".." && !/[\\/:]/.test(name), {
+        message: 'Project names cannot be "." or "..", nor contain "/", "\\" or ":".',
+    })
+        .describe("Name of the project to create."),
+    code_source: z
+        .object({
+        kind: z.enum(["local", "github"]),
+        repo: z.string().optional(),
+        branch: z.string().optional(),
+    })
+        .optional()
+        .describe("Where the project's code is read from, as with set_code_source. Omitted: the local working copy."),
+});
+/**
+ * Creates an empty project, with its code source when one is given. The source is checked before
+ * anything is written, so an unknown repository or branch creates nothing.
+ */
+export async function createProject(storageEngine, localState, args) {
+    try {
+        const { project, code_source } = CreateProjectArgsSchema.parse(args);
+        if (storageEngine.getConfig().projects.includes(project)) {
+            return { isError: true, content: [{ type: "text", text: `Project "${project}" already exists.` }] };
+        }
+        const config = code_source ? await resolveCodeSourceInput(code_source) : undefined;
+        storageEngine.ensureProject(project);
+        if (config)
+            saveCodeSource(storageEngine, localState, project, config);
+        const source = config ? ` It reads its code from ${describeCodeSourceConfig(config)}.` : "";
+        return { content: [{ type: "text", text: `Project "${project}" created.${source}` }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error creating project: ${message}` }] };
+    }
+}

package/dist/src/tools/delete-project.d.ts

@@ -0,0 +1,16 @@
+import type { StorageEngine } from "../core/storage-engine.js";
+import type { LocalState } from "../core/local-state.js";
+/** Deletes an empty project, along with this machine's code root for it. */
+export declare function deleteProject(storageEngine: StorageEngine, localState: LocalState, args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/src/tools/delete-project.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { invalidateCodeSources } from "../core/code-source.js";
+import { assertProject, scopeErrorResult } from "../core/project-scope.js";
+const DeleteProjectArgsSchema = z.object({
+    project: z.string().min(1).describe("Project to delete. It must be empty: no doc, no image, no other file."),
+});
+/** Deletes an empty project, along with this machine's code root for it. */
+export async function deleteProject(storageEngine, localState, args) {
+    try {
+        const { project } = DeleteProjectArgsSchema.parse(args);
+        const projectError = assertProject(storageEngine, project);
+        if (projectError)
+            return scopeErrorResult(projectError);
+        storageEngine.deleteProject(project);
+        localState.setProjectCodeRoot(project, undefined);
+        invalidateCodeSources(project);
+        return {
+            content: [{ type: "text", text: `Project "${project}" deleted.` }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Error deleting project: ${message}` }] };
+    }
+}

package/dist/src/tools/git-diff-doc.js

@@ -1,117 +1,144 @@
-import { execSync } from "child_process";
+import { execFileSync } from "child_process";
 import path from "path";
+import { createTwoFilesPatch } from "diff";
 import { GitDiffDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
 import { toAbsolutePath } from "../core/path-resolver.js";
-import { getCodeSource, getGitHubApi, toStoredPathForMatching } from "../core/code-source.js";
+import { getCodeSource, getGitHubSource, toStoredPathForMatching } from "../core/code-source.js";
+import { bytesToFileContent, fileContentMatches, findAndHashSection } from "../core/section-tracker.js";
+import { mapWithConcurrency } from "../core/concurrency.js";
 import { assertProject, scopeErrorResult } from "../core/project-scope.js";
-/** Diff of one tracked file against the local working copy, via the git CLI. */
-function getLocalGitDiff(tracked, project) {
-    const filePath = toAbsolutePath(tracked.path, project);
-    if (!filePath) {
-        return `  [INFO] Cannot resolve "${tracked.path}" on this machine (no code root configured) — source absent.`;
+/** Tracked files of one doc diffed at once. */
+const FILE_CONCURRENCY = 4;
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+const short = (sha) => sha.slice(0, 7);
+/**
+ * Snapshot content on GitHub, by decreasing reliability: the recorded blob (independent of any
+ * commit, so it survives a rebase), the file at the recorded commit, or the file at the newest
+ * commit on the branch at or before the snapshot date.
+ */
+async function githubSnapshotBase(source, tracked) {
+    const repo = source.api.label;
+    if (tracked.sourceBlobId) {
+        try {
+            return { content: await source.readBlob(tracked.sourceBlobId, tracked.path), origin: `snapshot blob ${short(tracked.sourceBlobId)}`, inferred: false };
+        }
+        catch (err) {
+            return { error: `The snapshot content (blob ${short(tracked.sourceBlobId)}) cannot be read on ${repo}: ${errorMessage(err)}` };
+        }
     }
-    const fileDir = path.dirname(filePath);
-    let repoRoot;
+    let commit = tracked.sourceRevision;
+    const inferred = !commit;
+    if (!commit) {
+        try {
+            commit = await source.api.resolveCommitAtDate(tracked.lastModifiedAt);
+        }
+        catch (err) {
+            return { error: `No source commit recorded, and the commit at the snapshot date (${tracked.lastModifiedAt}) could not be resolved on ${repo}: ${errorMessage(err)}` };
+        }
+        if (!commit) {
+            return { error: `No source commit recorded, and ${repo} has no commit at or before the snapshot date (${tracked.lastModifiedAt}).` };
+        }
+    }
+    const origin = inferred ? `commit ${short(commit)} inferred from the snapshot date` : `snapshot commit ${short(commit)}`;
     try {
-        repoRoot = execSync(`git -C "${fileDir}" rev-parse --show-toplevel`, { encoding: "utf-8" }).trim();
+        const content = await source.readAt(tracked.path, commit);
+        if (!content)
+            return { error: `The file does not exist at ${origin} on ${repo}.` };
+        return { content, origin, inferred };
     }
-    catch {
-        return `  [ERROR] Not a git repository: ${filePath}`;
+    catch (err) {
+        return { error: `The ${origin} cannot be read on ${repo}: ${errorMessage(err)}` };
     }
-    const relativeFilePath = path.relative(repoRoot, filePath).replace(/\\/g, "/");
-    let commitHash;
+}
+function git(repoRoot, args) {
+    return execFileSync("git", ["-C", repoRoot, ...args], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+}
+/** Snapshot content in the local clone, with the same order of preference as on GitHub. */
+function localSnapshotBase(tracked, project) {
+    const filePath = toAbsolutePath(tracked.path, project);
+    if (!filePath)
+        return { error: `Cannot resolve "${tracked.path}" on this machine (no code root configured).` };
+    let repoRoot;
     try {
-        commitHash = execSync(`git -C "${repoRoot}" log --before="${tracked.lastModifiedAt}" -1 --format=%H -- "${relativeFilePath}"`, { encoding: "utf-8" }).trim();
+        repoRoot = git(path.dirname(filePath), ["rev-parse", "--show-toplevel"]).toString("utf-8").trim();
     }
     catch {
-        return `  [ERROR] Could not retrieve git log for: ${filePath}`;
+        return { error: `Not a git repository: ${filePath}` };
     }
-    if (!commitHash) {
-        return `  [INFO] No commit found before snapshot date (${tracked.lastModifiedAt}) for: ${filePath}`;
+    const relativeFilePath = path.relative(repoRoot, filePath).replace(/\\/g, "/");
+    if (tracked.sourceBlobId) {
+        try {
+            return { content: bytesToFileContent(git(repoRoot, ["cat-file", "blob", tracked.sourceBlobId])), origin: `snapshot blob ${short(tracked.sourceBlobId)}`, inferred: false };
+        }
+        catch {
+            return { error: `The snapshot content (blob ${short(tracked.sourceBlobId)}) is not in the local repository ${repoRoot}.` };
+        }
     }
-    let diff;
+    let commit = tracked.sourceRevision;
+    const inferred = !commit;
+    if (!commit) {
+        try {
+            commit = git(repoRoot, ["log", `--before=${tracked.lastModifiedAt}`, "-1", "--format=%H", "--", relativeFilePath]).toString("utf-8").trim();
+        }
+        catch {
+            return { error: `Could not read the git log of ${filePath}.` };
+        }
+        if (!commit)
+            return { error: `No commit touches ${relativeFilePath} at or before the snapshot date (${tracked.lastModifiedAt}).` };
+    }
+    const origin = inferred ? `commit ${short(commit)} inferred from the snapshot date` : `snapshot commit ${short(commit)}`;
     try {
-        diff = execSync(`git -C "${repoRoot}" diff ${commitHash} -- "${relativeFilePath}"`, { encoding: "utf-8" }).trim();
+        return { content: bytesToFileContent(git(repoRoot, ["show", `${commit}:${relativeFilePath}`])), origin, inferred };
     }
     catch {
-        return `  [ERROR] Could not compute diff for: ${filePath}`;
-    }
-    if (!diff) {
-        return `  [INFO] No changes since snapshot (commit ${commitHash.slice(0, 7)}) for: ${filePath}`;
+        return { error: `The file does not exist at ${origin} in ${repoRoot}, or that commit is not in the local repository.` };
     }
-    return diff;
 }
 /**
- * Diffs tracked files against the branch they are tracked on, using the commit each snapshot
- * was taken at as the base.
- *
- * A snapshot with no recorded commit — taken before branch tracking, or from a local working copy —
- * is anchored on the newest commit at or before its date instead, so it diffs like any other rather
- * than demanding a refresh first.
- *
- * Files are grouped by that base commit so one comparison covers every file snapshotted at the
- * same revision — which, for a doc refreshed in one go, means a single API call.
+ * Whether a content is the one the snapshot recorded, judged by its stored hashes. Undefined when
+ * the entry holds no hash to judge by.
  */
-async function getGitHubDiffs(api, trackedFiles) {
-    const diffs = new Map();
-    const byBase = new Map();
-    const inferredBases = new Set();
-    for (const tracked of trackedFiles) {
-        let base = tracked.sourceRevision;
-        if (!base) {
-            try {
-                base = await api.resolveCommitAtDate(tracked.lastModifiedAt);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                diffs.set(tracked.path, `  [ERROR] No source commit recorded, and the commit at the snapshot date (${tracked.lastModifiedAt}) could not be resolved on ${api.label}: ${message}`);
-                continue;
-            }
-            if (!base) {
-                diffs.set(tracked.path, `  [INFO] No source commit recorded, and ${api.label} has no commit at or before the snapshot date (${tracked.lastModifiedAt}) — nothing to diff against.\n` +
-                    `  → Call refresh_file_snapshot to re-anchor this file on ${api.label}.`);
-                continue;
-            }
-            inferredBases.add(base);
-        }
-        const group = byBase.get(base);
-        if (group)
-            group.push(tracked);
-        else
-            byBase.set(base, [tracked]);
-    }
-    if (byBase.size === 0)
-        return diffs;
-    const { commitSha: head } = await api.resolveRef();
-    for (const [base, files] of byBase) {
-        // An inferred base is the branch state at the snapshot date, not a commit the snapshot was
-        // provably read from — worth saying, since the diff can then include changes already documented.
-        const note = inferredBases.has(base)
-            ? `  [INFO] Base commit ${base.slice(0, 7)} inferred from the snapshot date (no source commit recorded).\n\n`
-            : "";
-        if (base === head) {
-            for (const file of files) {
-                diffs.set(file.path, `${note}  [INFO] ${api.label} is still at the snapshot commit ${base.slice(0, 7)} — no changes.`);
-            }
-            continue;
-        }
-        let patches;
-        try {
-            patches = await api.comparePatches(base, head);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            for (const file of files)
-                diffs.set(file.path, `${note}  [ERROR] Could not compare ${base.slice(0, 7)}...${head.slice(0, 7)}: ${message}`);
-            continue;
-        }
-        for (const file of files) {
-            const patch = patches.get(file.path);
-            diffs.set(file.path, note + (patch ?? `  [INFO] No changes to this file between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`));
-        }
+function matchesSnapshot(content, tracked) {
+    if (tracked.sections && tracked.sections.length > 0) {
+        return tracked.sections.every((section) => {
+            const result = findAndHashSection(content, section);
+            return result.found && result.matchesStored;
+        });
+    }
+    if (tracked.contentHash)
+        return fileContentMatches(content, tracked.contentHash);
+    return undefined;
+}
+/** The diff section of one tracked file: snapshot content against the current one at the source. */
+async function diffTrackedFile(tracked, project, source) {
+    const github = getGitHubSource(project);
+    const base = github ? await githubSnapshotBase(github, tracked) : localSnapshotBase(tracked, project);
+    const impossible = (reason) => `  [ERROR] Diff impossible: ${reason}\n` +
+        `  → Re-read the file to check the doc against the current code, then call refresh_file_snapshot.`;
+    if ("error" in base)
+        return impossible(base.error);
+    const verdict = matchesSnapshot(base.content, tracked);
+    if (verdict === false) {
+        return impossible(`the content at ${base.origin} does not match the hash recorded at the snapshot.`);
+    }
+    const unverifiedNote = verdict === undefined ? `  [INFO] No hash recorded for this entry: ${base.origin} could not be checked against the snapshot.\n\n` : "";
+    const inferredNote = base.inferred && verdict ? `  [INFO] Base: ${base.origin} (no source commit recorded), checked against the snapshot hash.\n\n` : "";
+    let current;
+    try {
+        current = await source.read(tracked.path);
+    }
+    catch (err) {
+        return `${unverifiedNote}${inferredNote}  [ERROR] The current content cannot be read from ${source.label}: ${errorMessage(err)}`;
     }
-    return diffs;
+    if (!current)
+        return `${unverifiedNote}${inferredNote}  [INFO] The file no longer exists at ${source.label}.`;
+    const before = base.content.lines.join("\n");
+    const after = current.content.lines.join("\n");
+    if (before === after)
+        return `${unverifiedNote}${inferredNote}  [INFO] No changes since the snapshot.`;
+    const patch = createTwoFilesPatch(`a/${tracked.path}`, `b/${tracked.path}`, before, after, base.origin, "current", { context: 3 });
+    return unverifiedNote + inferredNote + patch.replace(/^=+\n/, "").trimEnd();
 }
 export async function gitDiffDoc(storageEngine, args) {
     try {
@@ -121,7 +148,6 @@ export async function gitDiffDoc(storageEngine, args) {
         if (projectError)
             return scopeErrorResult(projectError);
         const source = getCodeSource(project);
-        const githubApi = getGitHubApi(project);
         const wanted = validated.file_paths
             ? new Set(await Promise.all(validated.file_paths.map((p) => toStoredPathForMatching(project, p))))
             : undefined;
@@ -165,11 +191,10 @@ export async function gitDiffDoc(storageEngine, args) {
                 docSections.push(`## ${doc.title} [${docPath}]\n\n[INFO] All tracked files already shown in a previous documentation section.`);
                 continue;
             }
-            const diffs = githubApi ? await getGitHubDiffs(githubApi, fresh) : undefined;
-            const fileSections = fresh.map((tf) => {
-                const diff = diffs ? diffs.get(tf.path) : getLocalGitDiff(tf, project);
-                const base = tf.sourceRevision ? `\nSnapshot commit: ${tf.sourceRevision.slice(0, 7)}` : "";
-                return `### ${tf.path}\nSnapshot date: ${tf.lastModifiedAt}${base}\n\n${diff}`;
+            const diffs = await mapWithConcurrency(fresh, FILE_CONCURRENCY, (tf) => diffTrackedFile(tf, project, source));
+            const fileSections = fresh.map((tf, i) => {
+                const base = tf.sourceRevision ? `\nSnapshot commit: ${short(tf.sourceRevision)}` : "";
+                return `### ${tf.path}\nSnapshot date: ${tf.lastModifiedAt}${base}\n\n${diffs[i]}`;
             });
             docSections.push(`## ${doc.title} [${docPath}]\n\nCode source: ${source.label}\n\n${fileSections.join("\n\n---\n\n")}`);
         }