@imenam/mcp-documentor 1.0.77 → 1.0.78

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

@@ -2,9 +2,11 @@ import { execSync } from "child_process";
 import path from "path";
 import { GitDiffDocArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
-import { toAbsolutePath, toStoredPath } from "../core/path-resolver.js";
+import { toAbsolutePath } from "../core/path-resolver.js";
+import { getCodeSource, getGitHubApi, toStoredPathForMatching } from "../core/code-source.js";
 import { assertProject, scopeErrorResult } from "../core/project-scope.js";
-function getGitDiffForFile(tracked, project) {
+/** 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.`;
@@ -40,6 +42,55 @@ function getGitDiffForFile(tracked, project) {
     }
     return diff;
 }
+/**
+ * Diffs tracked files against the branch they are tracked on, using the commit each snapshot
+ * was taken at as the base.
+ *
+ * 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.
+ */
+async function getGitHubDiffs(api, trackedFiles) {
+    const diffs = new Map();
+    const byBase = new Map();
+    for (const tracked of trackedFiles) {
+        if (!tracked.sourceRevision) {
+            diffs.set(tracked.path, `  [INFO] No source commit recorded for "${tracked.path}" — this snapshot predates branch tracking, or was taken from a local working copy.\n` +
+                `  → Call refresh_file_snapshot to re-anchor it on ${api.label}, after which diffs become available.`);
+            continue;
+        }
+        const group = byBase.get(tracked.sourceRevision);
+        if (group)
+            group.push(tracked);
+        else
+            byBase.set(tracked.sourceRevision, [tracked]);
+    }
+    if (byBase.size === 0)
+        return diffs;
+    const { commitSha: head } = await api.resolveRef();
+    for (const [base, files] of byBase) {
+        if (base === head) {
+            for (const file of files) {
+                diffs.set(file.path, `  [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, `  [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, patch ?? `  [INFO] No changes to this file between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`);
+        }
+    }
+    return diffs;
+}
 export async function gitDiffDoc(storageEngine, args) {
     try {
         const validated = GitDiffDocArgsSchema.parse(args);
@@ -47,6 +98,11 @@ export async function gitDiffDoc(storageEngine, args) {
         const projectError = assertProject(storageEngine, project);
         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;
         const docSections = [];
         const seenFilePaths = new Set();
         for (const docPath of validated.paths) {
@@ -60,12 +116,11 @@ export async function gitDiffDoc(storageEngine, args) {
                 continue;
             }
             let filesToDiff;
-            if (validated.file_paths) {
-                const wanted = new Set(validated.file_paths.map((p) => toStoredPath(p, project)));
+            if (wanted) {
                 filesToDiff = doc.tracked_files.filter((tf) => wanted.has(tf.path));
             }
             else {
-                const freshness = computeFreshness(doc.tracked_files, project);
+                const freshness = await computeFreshness(doc.tracked_files, project);
                 // Broken entries (no snapshot) can't be hash-compared, but the git diff
                 // is still the best signal the agent has to re-assess them — include them.
                 const changedPaths = new Set([...freshness.modified, ...freshness.missing, ...freshness.broken]);
@@ -78,22 +133,23 @@ export async function gitDiffDoc(storageEngine, args) {
                 docSections.push(`## ${doc.title}\n\n${msg}`);
                 continue;
             }
-            const fileSections = filesToDiff
-                .filter((tf) => {
+            const fresh = filesToDiff.filter((tf) => {
                 if (seenFilePaths.has(tf.path))
                     return false;
                 seenFilePaths.add(tf.path);
                 return true;
-            })
-                .map((tf) => {
-                const diff = getGitDiffForFile(tf, project);
-                return `### ${tf.path}\nSnapshot date: ${tf.lastModifiedAt}\n\n${diff}`;
             });
-            if (fileSections.length === 0) {
+            if (fresh.length === 0) {
                 docSections.push(`## ${doc.title} [${docPath}]\n\n[INFO] All tracked files already shown in a previous documentation section.`);
                 continue;
             }
-            docSections.push(`## ${doc.title} [${docPath}]\n\n${fileSections.join("\n\n---\n\n")}`);
+            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}`;
+            });
+            docSections.push(`## ${doc.title} [${docPath}]\n\nCode source: ${source.label}\n\n${fileSections.join("\n\n---\n\n")}`);
         }
         return { content: [{ type: "text", text: docSections.join("\n\n═══════════════════════════════════\n\n") }] };
     }

package/dist/src/tools/list-docs.js

@@ -41,7 +41,7 @@ export async function listDocs(storageEngine, args) {
             for (const summary of summaries) {
                 const doc = await storageEngine.getDoc(summary.id, proj);
                 if (doc && doc.tracked_files.length > 0) {
-                    const report = computeFreshness(doc.tracked_files, proj);
+                    const report = await computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
                     summary.isBroken = report.status === "broken";
                 }
@@ -60,7 +60,7 @@ export async function listDocs(storageEngine, args) {
             for (const summary of summaries) {
                 const doc = await storageEngine.getDoc(summary.id, proj);
                 if (doc && doc.tracked_files.length > 0) {
-                    const report = computeFreshness(doc.tracked_files, proj);
+                    const report = await computeFreshness(doc.tracked_files, proj);
                     summary.isStale = report.status === "stale";
                     summary.isBroken = report.status === "broken";
                 }

package/dist/src/tools/patch-doc.js

@@ -17,7 +17,7 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
         const rawReplacement = validated.replacement_file
             ? fs.readFileSync(validated.replacement_file, "utf-8")
             : validated.replacement;
-        const { content: replacement, additionalTrackedFiles } = resolveCodeRefs(rawReplacement);
+        const { content: replacement, additionalTrackedFiles } = await resolveCodeRefs(rawReplacement, resolvedProject);
         if (!doc.content.includes(search)) {
             const preview = doc.content.slice(0, 300).replace(/\n/g, "↵");
             return {
@@ -29,7 +29,7 @@ export async function patchDoc(storageEngine, embeddingEngine, args) {
             };
         }
         doc.content = doc.content.replace(search, replacement);
-        doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
+        doc.tracked_files = await mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
         doc.updatedAt = new Date().toISOString();
         await storageEngine.saveDoc(doc, resolvedProject, "patch");
         if (embeddingEngine.isConfigured()) {

package/dist/src/tools/refresh-file-snapshot.js

@@ -1,8 +1,6 @@
-import fs from "fs";
 import { RefreshFileSnapshotArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { computeFileHash } from "./check-freshness.js";
-import { relocateAndRefreshSection } from "../core/section-tracker.js";
-import { toAbsolutePath, toStoredPath } from "../core/path-resolver.js";
+import { relocateAndRefreshSection, hashFileContent } from "../core/section-tracker.js";
+import { getCodeSource, toStoredPathForMatching } from "../core/code-source.js";
 import { assertProject, scopeErrorResult } from "../core/project-scope.js";
 export async function refreshFileSnapshot(storageEngine, historyStore, args) {
     try {
@@ -11,7 +9,15 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
         const projectError = assertProject(storageEngine, resolvedProject);
         if (projectError)
             return scopeErrorResult(projectError);
+        const source = getCodeSource(resolvedProject);
         const docSections = [];
+        // Normalize to forward slashes and lowercase for case-insensitive comparison
+        // on Windows. Agent-supplied file_paths are absolute; map them to the stored
+        // (portable) form so they match tracked.path regardless of representation.
+        const norm = (p) => p.replace(/\\/g, "/").toLowerCase();
+        const resolvedFilePaths = validated.file_paths
+            ? await Promise.all(validated.file_paths.map(async (p) => norm(await toStoredPathForMatching(resolvedProject, p))))
+            : undefined;
         for (const docPath of validated.paths) {
             const doc = await storageEngine.getDoc(docPath, resolvedProject);
             if (!doc) {
@@ -22,31 +28,27 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
             const missing = [];
             const skipped = [];
             const anchorsLost = [];
-            // Normalize to forward slashes and lowercase for case-insensitive comparison
-            // on Windows. Agent-supplied file_paths are absolute; map them to the stored
-            // (portable) form so they match tracked.path regardless of representation.
-            const norm = (p) => p.replace(/\\/g, "/").toLowerCase();
-            const resolvedFilePaths = validated.file_paths?.map((p) => norm(toStoredPath(p, resolvedProject)));
             for (const tracked of doc.tracked_files) {
                 if (resolvedFilePaths && !resolvedFilePaths.includes(norm(tracked.path))) {
                     skipped.push(tracked.path);
                     continue;
                 }
-                const absolutePath = toAbsolutePath(tracked.path, resolvedProject);
-                if (!absolutePath || !fs.existsSync(absolutePath)) {
+                const file = await source.read(tracked.path);
+                if (!file) {
                     missing.push(tracked.path);
                     continue;
                 }
-                tracked.lastModifiedAt = fs.statSync(absolutePath).mtime.toISOString();
+                tracked.lastModifiedAt = file.lastModifiedAt;
+                tracked.sourceRevision = file.revision;
+                tracked.sourceBlobId = file.blobId;
                 if (tracked.sections && tracked.sections.length > 0) {
                     let hasLostAnchors = false;
-                    const refreshedSections = tracked.sections.map((section) => {
-                        const result = relocateAndRefreshSection(absolutePath, section);
+                    tracked.sections = tracked.sections.map((section) => {
+                        const result = relocateAndRefreshSection(file.content, section);
                         if (!result.found)
                             hasLostAnchors = true;
                         return result.found ? result.refreshed : section;
                     });
-                    tracked.sections = refreshedSections;
                     if (hasLostAnchors) {
                         anchorsLost.push(tracked.path);
                     }
@@ -55,13 +57,13 @@ export async function refreshFileSnapshot(storageEngine, historyStore, args) {
                     }
                 }
                 else {
-                    tracked.contentHash = computeFileHash(absolutePath);
+                    tracked.contentHash = hashFileContent(file.content);
                     refreshed.push(tracked.path);
                 }
             }
             await storageEngine.saveDoc(doc, resolvedProject);
             historyStore.record(resolvedProject, doc, "snapshot");
-            let section = `**${doc.title}** [${docPath}]: refreshed ${refreshed.length}, anchors lost ${anchorsLost.length}, missing ${missing.length}, skipped ${skipped.length}`;
+            let section = `**${doc.title}** [${docPath}]: refreshed ${refreshed.length}, anchors lost ${anchorsLost.length}, missing ${missing.length}, skipped ${skipped.length} (source: ${source.label})`;
             if (refreshed.length > 0)
                 section += `\n${refreshed.map((f) => `  ✓ ${f}`).join("\n")}`;
             if (missing.length > 0)

package/dist/src/tools/update-doc.js

@@ -16,12 +16,12 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         }
         let additionalTrackedFiles = [];
         if (validated.content_file !== undefined) {
-            const { content, additionalTrackedFiles: refs } = resolveCodeRefs(fs.readFileSync(validated.content_file, "utf-8"));
+            const { content, additionalTrackedFiles: refs } = await resolveCodeRefs(fs.readFileSync(validated.content_file, "utf-8"), resolvedProject);
             doc.content = content;
             additionalTrackedFiles = refs;
         }
         else if (validated.content !== undefined) {
-            const { content, additionalTrackedFiles: refs } = resolveCodeRefs(validated.content);
+            const { content, additionalTrackedFiles: refs } = await resolveCodeRefs(validated.content, resolvedProject);
             doc.content = content;
             additionalTrackedFiles = refs;
         }
@@ -30,14 +30,14 @@ export async function updateDoc(storageEngine, embeddingEngine, args) {
         // the same scope are carried over as-is; only genuinely new entries get one.
         let trackedResult;
         if (validated.tracked_files !== undefined) {
-            trackedResult = resnapshotPreserving(doc.tracked_files, [
+            trackedResult = await resnapshotPreserving(doc.tracked_files, [
                 ...validated.tracked_files,
                 ...additionalTrackedFiles,
             ], resolvedProject);
             doc.tracked_files = trackedResult.tracked;
         }
         else {
-            doc.tracked_files = mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
+            doc.tracked_files = await mergeTrackedFiles(doc.tracked_files, additionalTrackedFiles, resolvedProject);
         }
         if (validated.tags !== undefined) {
             doc.tags = validated.tags;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.77";
+export declare const APP_VERSION = "1.0.78";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.77';
+export const APP_VERSION = '1.0.78';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.77",
+  "version": "1.0.78",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",