@imenam/mcp-documentor 1.0.77 → 1.0.79

package/dist/src/core/section-tracker.js

@@ -1,21 +1,38 @@
 import crypto from "crypto";
-import fs from "fs";
 const ANCHOR_SIZE = 3;
 // Tolerance (in lines) around the expected bottom anchor position when lineCount is known.
 const BOTTOM_ANCHOR_TOLERANCE = 10;
+const sha256 = (text) => crypto.createHash("sha256").update(text).digest("hex");
+const stripCR = (line) => (line.endsWith("\r") ? line.slice(0, -1) : line);
+export function toFileContent(text) {
+    const raw = text.split("\n");
+    return { raw, lines: raw.map(stripCR) };
+}
+export function bytesToFileContent(bytes) {
+    return toFileContent(bytes.toString("utf-8"));
+}
+/** The whole-file hash written into a snapshot: taken over the normalised content. */
+export function hashFileContent(fc) {
+    return sha256(fc.lines.join("\n"));
+}
+/**
+ * Whether a stored whole-file hash still describes this content — true for the current
+ * (normalised) hash and for a legacy hash taken over the raw bytes.
+ */
+export function fileContentMatches(fc, storedHash) {
+    return hashFileContent(fc) === storedHash || sha256(fc.raw.join("\n")) === storedHash;
+}
 /**
- * Reads a file and snapshots a section defined by 1-indexed [start, end] line numbers.
+ * Reads a section defined by 1-indexed [start, end] line numbers and snapshots it.
  * Extracts top/bottom anchor lines and computes a hash of the section content.
- * The `lines` input is intentionally not persisted — only anchors, sectionHash, and lineCount are stored.
- * `lineCount` is used by findAndHashSection to constrain the bottom anchor search and prevent
+ * The section text is intentionally not persisted — only anchors, sectionHash, and lineCount.
+ * `lineCount` is used by locateSection to constrain the bottom anchor search and prevent
  * false matches when the file contains repeated lines.
  */
-export function snapshotSection(absolutePath, start, end) {
-    const fileContent = fs.readFileSync(absolutePath, "utf-8");
-    const allLines = fileContent.split("\n");
+export function snapshotSection(fc, start, end) {
     const startIdx = Math.max(0, start - 1);
-    const endIdx = Math.min(allLines.length - 1, end - 1);
-    const sectionLines = allLines.slice(startIdx, endIdx + 1);
+    const endIdx = Math.min(fc.lines.length - 1, end - 1);
+    const sectionLines = fc.lines.slice(startIdx, endIdx + 1);
     let top;
     let bottom;
     if (sectionLines.length < ANCHOR_SIZE * 2) {
@@ -27,32 +44,26 @@ export function snapshotSection(absolutePath, start, end) {
         top = sectionLines.slice(0, ANCHOR_SIZE);
         bottom = sectionLines.slice(sectionLines.length - ANCHOR_SIZE);
     }
-    const sectionHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
-    return { anchors: { top, bottom }, sectionHash, lineCount: sectionLines.length };
+    return { anchors: { top, bottom }, sectionHash: sha256(sectionLines.join("\n")), lineCount: sectionLines.length };
 }
 /**
- * Locates a tracked section in the current file content using its stored anchors,
- * then hashes the found content for comparison with the stored sectionHash.
- * Also returns the current 1-indexed line range where the section was found,
- * so callers can display it without storing it.
+ * Finds a tracked section in the current content using its stored anchors.
  *
- * Returns { found: false } if the anchors cannot be located — which is treated as stale,
- * since the surrounding context has changed enough to invalidate the documentation.
+ * Anchors stored before line-ending normalisation may still carry a trailing CR, so they are
+ * stripped here too — the comparison is always normalised on both sides.
  */
-export function findAndHashSection(absolutePath, section) {
-    const fileContent = fs.readFileSync(absolutePath, "utf-8");
-    const fileLines = fileContent.split("\n");
-    const { top, bottom } = section.anchors;
+function locateSection(fc, section) {
+    const top = section.anchors.top.map(stripCR);
+    const bottom = section.anchors.bottom.map(stripCR);
+    const fileLines = fc.lines;
     if (bottom.length === 0) {
         // Short-section path: the top anchor IS the full section content
         for (let i = 0; i <= fileLines.length - top.length; i++) {
             if (top.every((line, j) => fileLines[i + j] === line)) {
-                const sectionLines = fileLines.slice(i, i + top.length);
-                const currentHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
-                return { found: true, currentHash, lines: { start: i + 1, end: i + top.length } };
+                return { start: i, endExclusive: i + top.length };
             }
         }
-        return { found: false };
+        return undefined;
     }
     // Normal path: locate top anchor, then search for bottom anchor below it.
     // If lineCount is stored, constrain the search window to prevent false matches on repeated lines.
@@ -60,64 +71,56 @@ export function findAndHashSection(absolutePath, section) {
         if (!top.every((line, j) => fileLines[i + j] === line))
             continue;
         const searchStart = i + top.length;
-        // Constrain bottom anchor search when lineCount is known
-        const expectedBottomStart = section.lineCount !== undefined
-            ? i + section.lineCount - bottom.length
-            : undefined;
-        const kMin = expectedBottomStart !== undefined
-            ? Math.max(searchStart, expectedBottomStart - BOTTOM_ANCHOR_TOLERANCE)
-            : searchStart;
+        const expectedBottomStart = section.lineCount !== undefined ? i + section.lineCount - bottom.length : undefined;
+        const kMin = expectedBottomStart !== undefined ? Math.max(searchStart, expectedBottomStart - BOTTOM_ANCHOR_TOLERANCE) : searchStart;
         const kMax = expectedBottomStart !== undefined
             ? Math.min(fileLines.length - bottom.length, expectedBottomStart + BOTTOM_ANCHOR_TOLERANCE)
             : fileLines.length - bottom.length;
         for (let k = kMin; k <= kMax; k++) {
             if (!bottom.every((line, j) => fileLines[k + j] === line))
                 continue;
-            const sectionLines = fileLines.slice(i, k + bottom.length);
-            const currentHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
-            return { found: true, currentHash, lines: { start: i + 1, end: k + bottom.length } };
+            return { start: i, endExclusive: k + bottom.length };
         }
     }
-    return { found: false };
+    return undefined;
+}
+/**
+ * Locates a tracked section in the current content and compares it with its stored hash.
+ *
+ * Returns { found: false } if the anchors cannot be located — treated as stale by callers,
+ * since the surrounding context has changed enough to invalidate the documentation.
+ */
+export function findAndHashSection(fc, section) {
+    const located = locateSection(fc, section);
+    if (!located)
+        return { found: false };
+    const { start, endExclusive } = located;
+    const currentHash = sha256(fc.lines.slice(start, endExclusive).join("\n"));
+    const legacyHash = sha256(fc.raw.slice(start, endExclusive).join("\n"));
+    return {
+        found: true,
+        currentHash,
+        matchesStored: currentHash === section.sectionHash || legacyHash === section.sectionHash,
+        lines: { start: start + 1, end: endExclusive },
+    };
 }
 /**
  * Locates a section by its current anchors, then refreshes its sectionHash to match
- * the current file content. Used by refresh_file_snapshot to acknowledge changes.
- * Anchors are kept as-is (they were found successfully); only sectionHash is updated.
+ * the current content. Used by refresh_file_snapshot to acknowledge changes.
+ * The anchors are re-stored normalised — they were found, so only their encoding changes.
  */
-export function relocateAndRefreshSection(absolutePath, section) {
-    const fileContent = fs.readFileSync(absolutePath, "utf-8");
-    const fileLines = fileContent.split("\n");
-    const { top, bottom } = section.anchors;
-    if (bottom.length === 0) {
-        for (let i = 0; i <= fileLines.length - top.length; i++) {
-            if (top.every((line, j) => fileLines[i + j] === line)) {
-                const sectionHash = crypto.createHash("sha256").update(fileLines.slice(i, i + top.length).join("\n")).digest("hex");
-                return { found: true, refreshed: { anchors: section.anchors, sectionHash } };
-            }
-        }
+export function relocateAndRefreshSection(fc, section) {
+    const located = locateSection(fc, section);
+    if (!located)
         return { found: false };
-    }
-    for (let i = 0; i <= fileLines.length - top.length; i++) {
-        if (!top.every((line, j) => fileLines[i + j] === line))
-            continue;
-        const searchStart = i + top.length;
-        const expectedBottomStart = section.lineCount !== undefined
-            ? i + section.lineCount - bottom.length
-            : undefined;
-        const kMin = expectedBottomStart !== undefined
-            ? Math.max(searchStart, expectedBottomStart - BOTTOM_ANCHOR_TOLERANCE)
-            : searchStart;
-        const kMax = expectedBottomStart !== undefined
-            ? Math.min(fileLines.length - bottom.length, expectedBottomStart + BOTTOM_ANCHOR_TOLERANCE)
-            : fileLines.length - bottom.length;
-        for (let k = kMin; k <= kMax; k++) {
-            if (!bottom.every((line, j) => fileLines[k + j] === line))
-                continue;
-            const sectionLines = fileLines.slice(i, k + bottom.length);
-            const sectionHash = crypto.createHash("sha256").update(sectionLines.join("\n")).digest("hex");
-            return { found: true, refreshed: { anchors: section.anchors, sectionHash, lineCount: sectionLines.length } };
-        }
-    }
-    return { found: false };
+    const { start, endExclusive } = located;
+    const sectionLines = fc.lines.slice(start, endExclusive);
+    return {
+        found: true,
+        refreshed: {
+            anchors: { top: section.anchors.top.map(stripCR), bottom: section.anchors.bottom.map(stripCR) },
+            sectionHash: sha256(sectionLines.join("\n")),
+            lineCount: sectionLines.length,
+        },
+    };
 }

package/dist/src/index.js

@@ -17,9 +17,11 @@ import { getDoc } from "./tools/get-doc.js";
 import { listDocs } from "./tools/list-docs.js";
 import { updateDoc } from "./tools/update-doc.js";
 import { searchDocs } from "./tools/search-docs.js";
-import { checkFreshness, computeFreshness } from "./tools/check-freshness.js";
+import { checkFreshness, computeFreshness, DOC_CONCURRENCY } from "./tools/check-freshness.js";
+import { mapWithConcurrency } from "./core/concurrency.js";
 import { findAndHashSection } from "./core/section-tracker.js";
-import { toAbsolutePath } from "./core/path-resolver.js";
+import { getCodeSource } from "./core/code-source.js";
+import { runInCodeOperation } from "./core/code-operation.js";
 import { listProjects } from "./tools/list-projects.js";
 import { refreshFileSnapshot } from "./tools/refresh-file-snapshot.js";
 import { getDocMetadata } from "./tools/get-doc-metadata.js";
@@ -112,7 +114,11 @@ function broadcastToGUI(message) {
         }
     }
 }
+/** Each GUI message is one operation: the branch head it reads is resolved once, and freshly. */
 function handleIPCMessage(msg) {
+    return runInCodeOperation(() => dispatchIPCMessage(msg));
+}
+function dispatchIPCMessage(msg) {
     if (msg.type === "ALREADY_RUNNING") {
         guiStatus = "already_running";
         guiUrl = msg.data?.url ?? guiUrl;
@@ -199,14 +205,14 @@ function requireProjectFromIPC(msg) {
 /** Loads one project's summaries and flags each entry as stale/broken. */
 async function listDocsWithFreshness(project) {
     const docs = await storageEngine.listDocs(project);
-    for (const doc of docs) {
+    await mapWithConcurrency(docs, DOC_CONCURRENCY, async (doc) => {
         const full = await storageEngine.getDoc(doc.id, project);
-        if (full && full.tracked_files.length > 0) {
-            const report = computeFreshness(full.tracked_files, project);
-            doc.isStale = report.status === "stale" || report.status === "broken";
-            doc.isBroken = report.status === "broken";
-        }
-    }
+        if (!full || full.tracked_files.length === 0)
+            return;
+        const report = await computeFreshness(full.tracked_files, project);
+        doc.isStale = report.status === "stale" || report.status === "broken";
+        doc.isBroken = report.status === "broken";
+    });
     return docs;
 }
 /**
@@ -512,19 +518,19 @@ async function handleGetFileSection(msg) {
         const trackedFile = doc.tracked_files.find((f) => f.path === filePath);
         if (!trackedFile || !trackedFile.sections?.length)
             throw new Error("No sections for this file");
-        const absolutePath = toAbsolutePath(trackedFile.path, project);
-        if (!absolutePath)
-            throw new Error("Cannot resolve file on this machine (no code root configured)");
-        const fileLines = fs.readFileSync(absolutePath, "utf-8").split("\n");
+        const source = getCodeSource(project);
+        const file = await source.read(trackedFile.path);
+        if (!file)
+            throw new Error(`Cannot read "${trackedFile.path}" from ${source.label}`);
         const sections = trackedFile.sections.map((section) => {
-            const result = findAndHashSection(absolutePath, section);
+            const result = findAndHashSection(file.content, section);
             if (!result.found)
                 return null;
             const { start, end } = result.lines;
             return {
                 start,
                 end,
-                code: fileLines.slice(start - 1, end).join("\n"),
+                code: file.content.lines.slice(start - 1, end).join("\n"),
             };
         }).filter(Boolean);
         broadcastToGUI({
@@ -556,7 +562,7 @@ async function handleCheckFreshness(msg) {
             });
             return;
         }
-        const report = computeFreshness(doc.tracked_files, project);
+        const report = await computeFreshness(doc.tracked_files, project);
         broadcastToGUI({
             type: "CHECK_FRESHNESS_RESPONSE",
             correlationId: msg.correlationId,
@@ -1368,7 +1374,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: isReadOnly() ? tools.filter((t) => !WRITE_TOOLS.has(t.name)) : tools,
     };
 });
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+// 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)));
+async function handleToolCall(request) {
     const { name, arguments: args } = request.params;
     if (isReadOnly() && WRITE_TOOLS.has(name)) {
         return {
@@ -1484,7 +1493,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             isError: true,
         };
     }
-});
+}
 async function syncPullOnStartup() {
     if (!syncEngine.isConfigured())
         return;

package/dist/src/tools/check-freshness.d.ts

@@ -1,7 +1,12 @@
 import type { TrackedFile, FreshnessReport } from "../../shared/schemas/doc.schema.js";
 import type { StorageEngine } from "../core/storage-engine.js";
-export declare function computeFileHash(absolutePath: string): string;
-export declare function computeFreshness(trackedFiles: TrackedFile[], project: string): FreshnessReport;
+/**
+ * Docs checked at once during a whole-project scan. With FILE_CONCURRENCY this caps in-flight
+ * source reads at 32 — enough to hide network latency on a 160-doc project, far below anything
+ * GitHub objects to.
+ */
+export declare const DOC_CONCURRENCY = 8;
+export declare function computeFreshness(trackedFiles: TrackedFile[], project: string): Promise<FreshnessReport>;
 export declare function formatFreshnessReport(title: string, report: FreshnessReport): string;
 export declare function checkFreshness(storageEngine: StorageEngine, args: unknown): Promise<{
     content: {

package/dist/src/tools/check-freshness.js

@@ -1,82 +1,91 @@
-import crypto from "crypto";
-import fs from "fs";
 import { CheckFreshnessArgsSchema } from "../../shared/schemas/doc.schema.js";
-import { findAndHashSection } from "../core/section-tracker.js";
-import { toAbsolutePath } from "../core/path-resolver.js";
+import { findAndHashSection, fileContentMatches } from "../core/section-tracker.js";
+import { getCodeSource } from "../core/code-source.js";
+import { mapWithConcurrency } from "../core/concurrency.js";
 import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
-export function computeFileHash(absolutePath) {
-    return crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
+/** Files of one doc checked at once. Kept modest: docs are also scanned several at a time. */
+const FILE_CONCURRENCY = 4;
+/**
+ * Docs checked at once during a whole-project scan. With FILE_CONCURRENCY this caps in-flight
+ * source reads at 32 — enough to hide network latency on a 160-doc project, far below anything
+ * GitHub objects to.
+ */
+export const DOC_CONCURRENCY = 8;
+/** Compares one tracked file with the source, never throwing — the failure is part of the verdict. */
+async function checkTrackedFile(tracked, source) {
+    try {
+        // When the source can identify the content without transferring it and that identity is
+        // unchanged, the file is provably untouched — sections included — so nothing is read.
+        if (tracked.sourceBlobId && (await source.contentId(tracked.path)) === tracked.sourceBlobId) {
+            return { kind: "unchanged" };
+        }
+        const file = await source.read(tracked.path);
+        // A path that does not resolve at the source counts as absent, so a doc whose files are all
+        // gone ends up "unverifiable" rather than crying wolf with "stale".
+        if (!file)
+            return { kind: "missing" };
+        if (tracked.sections && tracked.sections.length > 0) {
+            for (const section of tracked.sections) {
+                const result = findAndHashSection(file.content, section);
+                if (!result.found)
+                    return { kind: "anchors_lost" };
+                if (!result.matchesStored)
+                    return { kind: "modified" };
+            }
+            return { kind: "unchanged" };
+        }
+        if (tracked.contentHash) {
+            return fileContentMatches(file.content, tracked.contentHash) ? { kind: "unchanged" } : { kind: "modified" };
+        }
+        // Hash comparison is the only freshness system. An entry with neither sections nor
+        // contentHash predates it and cannot be checked — it is reported as broken (never checked by
+        // any other means) so readers can still expose the doc and its tracked list for re-tracking.
+        return { kind: "broken" };
+    }
+    catch (err) {
+        // The source itself is unreachable (network, auth, rate limit). Nothing can be compared, and
+        // reporting what we did not manage to read as "modified" would be crying wolf.
+        return { kind: "source_error", message: err instanceof Error ? err.message : String(err) };
+    }
 }
-export function computeFreshness(trackedFiles, project) {
+export async function computeFreshness(trackedFiles, project) {
+    const source = getCodeSource(project);
+    const empty = { modified: [], missing: [], unchanged: [], anchors_lost: [], broken: [], source: source.label };
     if (!trackedFiles || trackedFiles.length === 0) {
-        return { status: "no_tracking", modified: [], missing: [], unchanged: [], anchors_lost: [], broken: [], total: 0 };
+        return { status: "no_tracking", ...empty, total: 0 };
+    }
+    const verdicts = await mapWithConcurrency(trackedFiles, FILE_CONCURRENCY, (tracked) => checkTrackedFile(tracked, source));
+    const failed = verdicts.find((verdict) => verdict.kind === "source_error");
+    if (failed) {
+        return { status: "unverifiable", ...empty, total: trackedFiles.length, sourceError: failed.message };
     }
     const modified = [];
     const missing = [];
     const unchanged = [];
     const anchors_lost = [];
     const broken = [];
-    for (const tracked of trackedFiles) {
-        // A relative path with no code root configured on this machine is not
-        // resolvable here — count it as absent so we end up "unverifiable" rather
-        // than crying wolf with "stale".
-        const absolutePath = toAbsolutePath(tracked.path, project);
-        if (!absolutePath || !fs.existsSync(absolutePath)) {
-            missing.push(tracked.path);
-            continue;
-        }
-        if (tracked.sections && tracked.sections.length > 0) {
-            let sectionStale = false;
-            let anchorLost = false;
-            for (const section of tracked.sections) {
-                const result = findAndHashSection(absolutePath, section);
-                if (!result.found) {
-                    sectionStale = true;
-                    anchorLost = true;
-                    break;
-                }
-                else if (result.currentHash !== section.sectionHash) {
-                    sectionStale = true;
-                    break;
-                }
-            }
-            if (sectionStale) {
-                if (anchorLost) {
-                    anchors_lost.push(tracked.path);
-                }
-                else {
-                    modified.push(tracked.path);
-                }
-            }
-            else {
-                unchanged.push(tracked.path);
-            }
-        }
-        else if (tracked.contentHash) {
-            const currentHash = computeFileHash(absolutePath);
-            if (currentHash !== tracked.contentHash) {
-                modified.push(tracked.path);
-            }
-            else {
-                unchanged.push(tracked.path);
-            }
-        }
-        else {
-            // Hash comparison is the only freshness system. An entry with neither
-            // sections nor contentHash predates it and cannot be checked — it is
-            // reported as broken (never checked by any other means) so readers can
-            // still expose the doc and its tracked list to the agent for re-tracking.
-            broken.push(tracked.path);
-        }
-    }
-    // When every tracked file is absent, the source code simply isn't present on
-    // this machine (e.g. docs cloned without the codebase) — we can't verify
-    // freshness, so report "unverifiable" rather than crying wolf with "stale".
-    // A partial absence (some files missing, others present) is treated as a real
-    // change signal (likely deletions) and still counts as stale.
+    const buckets = { modified, missing, unchanged, anchors_lost, broken };
+    verdicts.forEach((verdict, i) => {
+        if (verdict.kind !== "source_error")
+            buckets[verdict.kind].push(trackedFiles[i].path);
+    });
+    // When every tracked file is absent, the source code simply isn't present at the source
+    // (e.g. docs cloned without the codebase, or a branch where those files don't exist) — we
+    // can't verify freshness, so report "unverifiable" rather than crying wolf with "stale".
+    // A partial absence (some files missing, others present) is treated as a real change signal
+    // (likely deletions) and still counts as stale.
     const allMissing = missing.length === trackedFiles.length;
     if (allMissing) {
-        return { status: "unverifiable", modified, missing, unchanged, anchors_lost, broken, total: trackedFiles.length };
+        return {
+            status: "unverifiable",
+            modified,
+            missing,
+            unchanged,
+            anchors_lost,
+            broken,
+            total: trackedFiles.length,
+            source: source.label,
+        };
     }
     const isStale = modified.length > 0 || missing.length > 0 || anchors_lost.length > 0;
     // Broken tracking outranks everything: no freshness verdict is trustworthy
@@ -89,24 +98,30 @@ export function computeFreshness(trackedFiles, project) {
         anchors_lost,
         broken,
         total: trackedFiles.length,
+        source: source.label,
     };
 }
 export function formatFreshnessReport(title, report) {
+    const sourceLine = report.source ? `\nCode source: ${report.source}.` : "";
     if (report.status === "no_tracking") {
         return `No tracked files for "${title}". Use tracked_files when creating or updating the doc to enable staleness detection.`;
     }
     if (report.status === "unverifiable") {
-        return `UNVERIFIABLE: "${title}" — none of the ${report.total} tracked file(s) are present on this machine, so freshness cannot be checked here. This is expected when the documentation is cloned without its source codebase.`;
+        const reason = report.sourceError
+            ? `the code source could not be consulted — ${report.sourceError}`
+            : `none of the ${report.total} tracked file(s) exist there`;
+        return (`UNVERIFIABLE: "${title}" — ${reason}, so freshness cannot be checked.${sourceLine}\n` +
+            `This is expected when the documentation is read without access to its source codebase.`);
     }
     let text;
     if (report.status === "broken") {
-        text = `BROKEN TRACKING: "${title}" — some tracked entries have no content snapshot and cannot be checked.\n`;
+        text = `BROKEN TRACKING: "${title}" — some tracked entries have no content snapshot and cannot be checked.${sourceLine}\n`;
     }
     else if (report.status === "stale") {
-        text = `STALE: "${title}" — tracked files have changed since the documentation was last updated.\n`;
+        text = `STALE: "${title}" — tracked files have changed since the documentation was last updated.${sourceLine}\n`;
     }
     else {
-        text = `UP TO DATE: "${title}" — no tracked files have been modified.\n`;
+        text = `UP TO DATE: "${title}" — no tracked files have been modified.${sourceLine}\n`;
     }
     const anchorLostCount = report.anchors_lost?.length ?? 0;
     const brokenCount = report.broken?.length ?? 0;
@@ -139,12 +154,25 @@ function renderUntrackedList(titles, heading) {
 }
 async function scanProjectFreshness(storageEngine, project) {
     const summaries = await storageEngine.listDocs(project);
-    const scan = { docCount: summaries.length, stale: [], noTracking: [], broken: [], upToDate: 0, unverifiable: 0 };
-    for (const summary of summaries) {
+    const scan = {
+        docCount: summaries.length,
+        stale: [],
+        noTracking: [],
+        broken: [],
+        upToDate: 0,
+        unverifiable: 0,
+        source: getCodeSource(project).label,
+    };
+    const checked = await mapWithConcurrency(summaries, DOC_CONCURRENCY, async (summary) => {
         const doc = await storageEngine.getDoc(summary.id, project);
-        if (!doc)
+        return doc ? { doc, report: await computeFreshness(doc.tracked_files, project) } : undefined;
+    });
+    for (const entry of checked) {
+        if (!entry)
             continue;
-        const report = computeFreshness(doc.tracked_files, project);
+        const { doc, report } = entry;
+        if (report.sourceError)
+            scan.sourceError = report.sourceError;
         if (report.status === "broken") {
             const files = report.broken.map((f) => `    • no snapshot: ${f}`).join("\n");
             scan.broken.push(`  - **${doc.title}** [${doc.id}]\n${files}`);
@@ -170,7 +198,10 @@ async function scanProjectFreshness(storageEngine, project) {
     return scan;
 }
 function renderScanSummary(scan) {
-    let text = `${scan.docCount} doc(s) scanned: **${scan.stale.length} stale**, ${scan.upToDate} up to date, ${scan.unverifiable} unverifiable (source absent), ${scan.noTracking.length} not tracking any file`;
+    let text = `Code source: ${scan.source}.\n\n`;
+    if (scan.sourceError)
+        text += `⚠ The code source could not be consulted: ${scan.sourceError}\n\n`;
+    text += `${scan.docCount} doc(s) scanned: **${scan.stale.length} stale**, ${scan.upToDate} up to date, ${scan.unverifiable} unverifiable (source absent), ${scan.noTracking.length} not tracking any file`;
     if (scan.broken.length > 0)
         text += `, **${scan.broken.length} with broken tracking**`;
     return text + ".";
@@ -198,7 +229,7 @@ export async function checkFreshness(storageEngine, args) {
             const resolved = await resolveDocInProject(storageEngine, validated.path, project, "freshness check");
             if (isScopeError(resolved))
                 return scopeErrorResult(resolved);
-            const report = computeFreshness(resolved.doc.tracked_files, project);
+            const report = await computeFreshness(resolved.doc.tracked_files, project);
             return { content: [{ type: "text", text: formatFreshnessReport(resolved.doc.title, report) }] };
         }
         if (validated.project) {

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

@@ -17,7 +17,7 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
         const rawContent = validated.content_file
             ? fs.readFileSync(validated.content_file, "utf-8")
             : validated.content;
-        const { content, additionalTrackedFiles } = resolveCodeRefs(rawContent);
+        const { content, additionalTrackedFiles } = await resolveCodeRefs(rawContent, project);
         const slug = slugify(validated.title);
         const id = validated.folder ? `${validated.folder}/${slug}` : slug;
         const now = new Date().toISOString();
@@ -34,7 +34,7 @@ export async function createDoc(storageEngine, embeddingEngine, args) {
             ...(validated.tracked_files ?? []),
             ...additionalTrackedFiles,
         ];
-        const trackedFiles = allTrackedInputs.length > 0 ? snapshotTrackedFiles(allTrackedInputs, resolvedProject) : [];
+        const trackedFiles = allTrackedInputs.length > 0 ? await snapshotTrackedFiles(allTrackedInputs, resolvedProject) : [];
         const folder = validated.folder;
         const doc = {
             id,

package/dist/src/tools/get-doc-metadata.js

@@ -1,8 +1,6 @@
-import fs from "fs";
 import { GetDocMetadataArgsSchema } from "../../shared/schemas/doc.schema.js";
 import { computeFreshness } from "./check-freshness.js";
-import { findAndHashSection } from "../core/section-tracker.js";
-import { toAbsolutePath } from "../core/path-resolver.js";
+import { locateTrackedSections } from "../core/code-source.js";
 import { resolveDocInProject, isScopeError, scopeErrorResult } from "../core/project-scope.js";
 export async function getDocMetadata(storageEngine, args) {
     try {
@@ -12,7 +10,7 @@ export async function getDocMetadata(storageEngine, args) {
             return scopeErrorResult(resolved);
         const { doc } = resolved;
         const project = validated.project;
-        const report = computeFreshness(doc.tracked_files, project);
+        const report = await computeFreshness(doc.tracked_files, project);
         const fileStatusIcon = (filePath) => {
             if (report.broken.includes(filePath))
                 return "⚠ broken tracking (no snapshot — re-declare via update_doc or run refresh_file_snapshot)";
@@ -28,24 +26,27 @@ export async function getDocMetadata(storageEngine, args) {
         text += `**Created:** ${doc.createdAt}\n`;
         text += `**Updated:** ${doc.updatedAt}\n`;
         text += `**Freshness:** ${report.status}\n`;
+        text += `**Code source:** ${report.source ?? "unknown"}\n`;
+        if (report.sourceError)
+            text += `**Source error:** ${report.sourceError}\n`;
         if (doc.tracked_files.length > 0) {
             text += `\nTracked files (${doc.tracked_files.length} total):\n`;
-            text += doc.tracked_files.map((f) => {
-                let entry = `  ${fileStatusIcon(f.path)} — ${f.path}\n  File mtime: ${f.lastModifiedAt}`;
+            const entries = await Promise.all(doc.tracked_files.map(async (f) => {
+                const revision = f.sourceRevision ? `\n  Snapshot commit: ${f.sourceRevision.slice(0, 7)}` : "";
+                let entry = `  ${fileStatusIcon(f.path)} — ${f.path}\n  File mtime: ${f.lastModifiedAt}${revision}`;
                 if (f.sections && f.sections.length > 0) {
-                    const abs = toAbsolutePath(f.path, project);
-                    const readable = abs && fs.existsSync(abs);
-                    const sectionLines = f.sections.map((section, idx) => {
-                        const result = readable ? findAndHashSection(abs, section) : { found: false };
-                        const location = result.found
-                            ? `lines ${result.lines.start}–${result.lines.end}`
+                    const positions = await locateTrackedSections(project, f.path, f.sections);
+                    const sectionLines = positions.map((position, idx) => {
+                        const location = position
+                            ? `lines ${position.start}–${position.end}`
                             : "section introuvable (ancres modifiées)";
                         return `    - Section ${idx + 1}: ${location}`;
                     });
                     entry += `\n  Sections (position actuelle):\n${sectionLines.join("\n")}`;
                 }
                 return entry;
-            }).join("\n");
+            }));
+            text += entries.join("\n");
         }
         else {
             text += "\nNo tracked files.";