@imenam/mcp-documentor 1.0.80 → 1.0.81

package/dist/src/core/github-code-api.d.ts

@@ -40,6 +40,7 @@ export declare class GitHubCodeApi {
     private readonly spec;
     private readonly token;
     private readonly treeByCommit;
+    private readonly commitByDate;
     private readonly truncatedCommits;
     private readonly blobCache;
     constructor(spec: RepoSpec, token: string | undefined);
@@ -52,6 +53,15 @@ export declare class GitHubCodeApi {
      * once within it, however many files that operation ends up reading.
      */
     resolveRef(): Promise<ResolvedRef>;
+    /**
+     * The newest commit on the configured ref at or before `isoDate`, or undefined if the branch
+     * has no commit that old.
+     *
+     * This is how a snapshot taken before commits were recorded still gets a diff base: the date it
+     * was taken at stands in for the revision it was taken from. History is immutable below the ref's
+     * head, so the answer is cached for the life of the process.
+     */
+    resolveCommitAtDate(isoDate: string): Promise<string | undefined>;
     /** path → blob sha for every file in the commit's tree. A commit's tree never changes. */
     getTree(commitSha: string): Promise<Map<string, string>>;
     /**

package/dist/src/core/github-code-api.js

@@ -58,6 +58,7 @@ export class GitHubCodeApi {
     // at once, and they all need the same tree — and often the same blobs. Caching the promise makes
     // concurrent callers await one request instead of each firing its own.
     treeByCommit = new Map();
+    commitByDate = new Map();
     truncatedCommits = new Set();
     blobCache = new Map();
     constructor(spec, token) {
@@ -116,6 +117,24 @@ export class GitHubCodeApi {
             };
         });
     }
+    /**
+     * The newest commit on the configured ref at or before `isoDate`, or undefined if the branch
+     * has no commit that old.
+     *
+     * This is how a snapshot taken before commits were recorded still gets a diff base: the date it
+     * was taken at stands in for the revision it was taken from. History is immutable below the ref's
+     * head, so the answer is cached for the life of the process.
+     */
+    resolveCommitAtDate(isoDate) {
+        return this.cached(this.commitByDate, isoDate, async () => {
+            const ref = this.spec.ref ?? "HEAD";
+            const commits = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/commits` +
+                `?sha=${encodeURIComponent(ref)}&until=${encodeURIComponent(isoDate)}&per_page=1`);
+            const sha = Array.isArray(commits) && typeof commits[0]?.sha === "string" ? commits[0].sha : undefined;
+            logger.debug(`${this.label}: commit at or before ${isoDate} is ${sha ? sha.slice(0, 7) : "none"}`);
+            return sha;
+        });
+    }
     /** path → blob sha for every file in the commit's tree. A commit's tree never changes. */
     getTree(commitSha) {
         return this.cached(this.treeByCommit, commitSha, async () => {

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

@@ -46,31 +46,53 @@ function getLocalGitDiff(tracked, project) {
  * 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.
  */
 async function getGitHubDiffs(api, trackedFiles) {
     const diffs = new Map();
     const byBase = new Map();
+    const inferredBases = new Set();
     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;
+        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(tracked.sourceRevision);
+        const group = byBase.get(base);
         if (group)
             group.push(tracked);
         else
-            byBase.set(tracked.sourceRevision, [tracked]);
+            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, `  [INFO] ${api.label} is still at the snapshot commit ${base.slice(0, 7)} — no changes.`);
+                diffs.set(file.path, `${note}  [INFO] ${api.label} is still at the snapshot commit ${base.slice(0, 7)} — no changes.`);
             }
             continue;
         }
@@ -81,12 +103,12 @@ async function getGitHubDiffs(api, trackedFiles) {
         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}`);
+                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, patch ?? `  [INFO] No changes to this file between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`);
+            diffs.set(file.path, note + (patch ?? `  [INFO] No changes to this file between ${base.slice(0, 7)} and ${head.slice(0, 7)}.`));
         }
     }
     return diffs;

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.80";
+export declare const APP_VERSION = "1.0.81";

package/dist/src/version.js

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

package/package.json

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