@imenam/mcp-documentor 1.0.76 → 1.0.78

package/dist/src/core/code-source.js

@@ -0,0 +1,248 @@
+import fs from "fs";
+import path from "path";
+import { createLogger } from "@imenam/mcp-gui-interface";
+import { bytesToFileContent, findAndHashSection } from "./section-tracker.js";
+import { getCodeRoot, toAbsolutePath, toStoredPath as toStoredPathLocal } from "./path-resolver.js";
+import { GitHubCodeApi, parseRepoSpec, formatRepoSpec } from "./github-code-api.js";
+const logger = createLogger("CodeSource");
+class LocalCodeSource {
+    project;
+    kind = "local";
+    constructor(project) {
+        this.project = project;
+    }
+    get label() {
+        const root = getCodeRoot(this.project);
+        return root ? `local working copy (${root})` : "local working copy";
+    }
+    async read(storedPath) {
+        const absolutePath = toAbsolutePath(storedPath, this.project);
+        if (!absolutePath || !fs.existsSync(absolutePath))
+            return undefined;
+        return {
+            content: bytesToFileContent(fs.readFileSync(absolutePath)),
+            lastModifiedAt: fs.statSync(absolutePath).mtime.toISOString(),
+        };
+    }
+    /** A working copy has no identity cheaper than reading the file, so there is no shortcut. */
+    async contentId() {
+        return undefined;
+    }
+    async toStoredPath(inputPath) {
+        // A relative input means "relative to the project's code root" — the same convention used
+        // when a stored path is read back. Never the server's cwd.
+        const absolute = toAbsolutePath(inputPath, this.project);
+        if (!absolute) {
+            throw new Error(`the path is relative but no code root is configured for project "${this.project}". ` +
+                `Provide an absolute path or set MCP_DOCUMENTOR_CODE_ROOT.`);
+        }
+        return toStoredPathLocal(absolute, this.project);
+    }
+}
+const toForwardSlashes = (p) => p.split("\\").join("/");
+class GitHubCodeSource {
+    api;
+    project;
+    kind = "github";
+    /** Agent-supplied path → repo-relative path, per source. Repo layouts barely move. */
+    repoPathCache = new Map();
+    constructor(api, project) {
+        this.api = api;
+        this.project = project;
+    }
+    get label() {
+        return `GitHub ${this.api.label}`;
+    }
+    async read(storedPath) {
+        const { commitSha, commitDate } = await this.api.resolveRef();
+        const repoPath = await this.toRepoPath(storedPath, commitSha);
+        if (!repoPath)
+            return undefined;
+        const blobSha = await this.api.getBlobSha(commitSha, repoPath);
+        if (!blobSha)
+            return undefined;
+        return {
+            content: bytesToFileContent(await this.api.getBlob(blobSha)),
+            lastModifiedAt: commitDate,
+            revision: commitSha,
+            blobId: blobSha,
+        };
+    }
+    /** The blob sha from the commit's tree — already fetched for the whole repository in one call. */
+    async contentId(storedPath) {
+        const { commitSha } = await this.api.resolveRef();
+        const repoPath = await this.toRepoPath(storedPath, commitSha);
+        return repoPath ? this.api.getBlobSha(commitSha, repoPath) : undefined;
+    }
+    async toStoredPath(inputPath) {
+        const { commitSha } = await this.api.resolveRef();
+        const repoPath = await this.toRepoPath(inputPath, commitSha);
+        if (!repoPath) {
+            throw new Error(`Cannot map "${inputPath}" to a path inside ${this.api.label}. ` +
+                `Provide the path relative to the repository root, or set a code root for project "${this.project}" ` +
+                `(MCP_DOCUMENTOR_CODE_ROOT / MCP_DOCUMENTOR_CODE_ROOTS) so absolute paths can be stripped down to it.`);
+        }
+        return repoPath;
+    }
+    /**
+     * Maps a path onto the repository layout.
+     *
+     * A relative path is already repo-relative. An absolute one — what an agent working on a local
+     * clone naturally sends — is reduced by the configured code root when there is one, and
+     * otherwise matched against the repository tree by its longest unambiguous path suffix, so the
+     * feature works without forcing every machine to declare a root.
+     */
+    async toRepoPath(inputPath, commitSha) {
+        if (this.repoPathCache.has(inputPath))
+            return this.repoPathCache.get(inputPath);
+        const resolved = await this.computeRepoPath(inputPath, commitSha);
+        this.repoPathCache.set(inputPath, resolved);
+        return resolved;
+    }
+    async computeRepoPath(inputPath, commitSha) {
+        const forward = toForwardSlashes(inputPath);
+        if (!path.isAbsolute(inputPath) && !/^[A-Za-z]:\//.test(forward)) {
+            return forward.replace(/^\.\//, "").replace(/^\/+/, "");
+        }
+        // A configured code root is the authoritative answer when the file sits under it.
+        const viaRoot = toForwardSlashes(toStoredPathLocal(inputPath, this.project));
+        if (!path.isAbsolute(viaRoot) && !/^[A-Za-z]:\//.test(viaRoot))
+            return viaRoot;
+        const tree = await this.api.getTree(commitSha);
+        const candidates = [...tree.keys()].filter((repoPath) => forward.endsWith(`/${repoPath}`));
+        if (candidates.length === 0)
+            return undefined;
+        const best = candidates.reduce((longest, current) => (current.length > longest.length ? current : longest));
+        if (!best.includes("/")) {
+            // A bare filename is only trustworthy when the repository holds exactly one file by that name.
+            const sameName = [...tree.keys()].filter((repoPath) => repoPath.split("/").pop() === best);
+            if (sameName.length > 1) {
+                logger.warn(`"${inputPath}" matches ${sameName.length} files named "${best}" in ${this.api.label}; not mapping it`);
+                return undefined;
+            }
+        }
+        return best;
+    }
+}
+let settings;
+const sourcesByProject = new Map();
+const apisByRepo = new Map();
+function loadSettings() {
+    if (settings)
+        return settings;
+    // One setting, two shapes. A repository is not a shared parent the way a code root is — it
+    // names exactly one codebase — so an instance serving several projects needs one spec per
+    // project, while a single-project or monorepo instance needs just the spec. A leading "{"
+    // tells the two apart unambiguously, since no repository spec starts with one.
+    const raw = process.env.MCP_DOCUMENTOR_CODE_REPO?.trim() || undefined;
+    const byProject = {};
+    let defaultSpec;
+    if (raw?.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                for (const [proj, spec] of Object.entries(parsed)) {
+                    if (typeof spec === "string" && spec.trim() !== "")
+                        byProject[proj] = spec.trim();
+                }
+            }
+            else {
+                logger.warn("MCP_DOCUMENTOR_CODE_REPO is not a JSON object, ignoring it");
+            }
+        }
+        catch {
+            logger.warn("MCP_DOCUMENTOR_CODE_REPO looks like a JSON map but could not be parsed, ignoring it");
+        }
+    }
+    else {
+        defaultSpec = raw;
+    }
+    settings = {
+        defaultSpec,
+        byProject,
+        defaultBranch: process.env.MCP_DOCUMENTOR_CODE_BRANCH?.trim() || undefined,
+        token: process.env.MCP_DOCUMENTOR_CODE_TOKEN?.trim() || process.env.MCP_DOCUMENTOR_SYNC_TOKEN?.trim() || undefined,
+    };
+    return settings;
+}
+/** Test-only / config-reload: drops the memoised environment snapshot and every cached source. */
+export function resetCodeSourceCache() {
+    settings = undefined;
+    sourcesByProject.clear();
+    apisByRepo.clear();
+}
+function buildSource(project) {
+    const config = loadSettings();
+    const raw = config.byProject[project] ?? config.defaultSpec;
+    if (!raw || raw.toLowerCase() === "local")
+        return new LocalCodeSource(project);
+    let spec;
+    try {
+        spec = parseRepoSpec(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.warn(`Code repository for project "${project}" is unusable, falling back to the local working copy: ${message}`);
+        return new LocalCodeSource(project);
+    }
+    if (!spec.ref && config.defaultBranch)
+        spec = { ...spec, ref: config.defaultBranch };
+    // One API client per (repo, ref): its tree and blob caches are then shared by every project
+    // pointing at the same branch.
+    const key = formatRepoSpec(spec);
+    let api = apisByRepo.get(key);
+    if (!api) {
+        api = new GitHubCodeApi(spec, config.token);
+        apisByRepo.set(key, api);
+        logger.info(`Project "${project}" reads its code from GitHub ${key}`);
+    }
+    return new GitHubCodeSource(api, project);
+}
+/** The code source a project reads from. Memoised — the configuration is environment-fixed. */
+export function getCodeSource(project) {
+    let source = sourcesByProject.get(project);
+    if (!source) {
+        source = buildSource(project);
+        sourcesByProject.set(project, source);
+    }
+    return source;
+}
+/**
+ * Where each tracked section of a file currently sits, as 1-indexed line ranges — `undefined`
+ * for a section whose anchors no longer match, and `undefined` for every section when the file
+ * itself cannot be read. Used to show positions without storing them.
+ */
+export async function locateTrackedSections(project, storedPath, sections) {
+    let file;
+    try {
+        file = await getCodeSource(project).read(storedPath);
+    }
+    catch {
+        // Reporting positions is never worth failing a read of the doc itself.
+        file = undefined;
+    }
+    if (!file)
+        return sections.map(() => undefined);
+    return sections.map((section) => {
+        const result = findAndHashSection(file.content, section);
+        return result.found ? result.lines : undefined;
+    });
+}
+/**
+ * Stored form of an agent-supplied path, for callers that only use it to match against paths a
+ * doc already tracks. A path the source cannot place is returned normalised rather than raising:
+ * it simply matches nothing, which is the right outcome for a filter.
+ */
+export async function toStoredPathForMatching(project, inputPath) {
+    try {
+        return await getCodeSource(project).toStoredPath(inputPath);
+    }
+    catch {
+        return toForwardSlashes(inputPath);
+    }
+}
+/** The GitHub client behind a project's source, or undefined when it reads the local working copy. */
+export function getGitHubApi(project) {
+    const source = getCodeSource(project);
+    return source instanceof GitHubCodeSource ? source.api : undefined;
+}

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

@@ -0,0 +1,72 @@
+/** A repository and the ref to read it at. `ref` undefined means the repo's default branch. */
+export interface RepoSpec {
+    owner: string;
+    repo: string;
+    ref?: string;
+}
+export declare function formatRepoSpec(spec: RepoSpec): string;
+/**
+ * Parses the repo half of a code-source setting.
+ *
+ * Accepted forms — with an optional `#branch` suffix on any of them:
+ *   owner/repo
+ *   https://github.com/owner/repo(.git)
+ *   git@github.com:owner/repo(.git)
+ */
+export declare function parseRepoSpec(raw: string): RepoSpec;
+/** A ref resolved to the commit it pointed at. */
+interface ResolvedRef {
+    commitSha: string;
+    /** Commit date of that commit — used as the snapshot timestamp for files read at this ref. */
+    commitDate: string;
+}
+export declare class GitHubApiError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Read-only access to a repository's file tree over the GitHub API.
+ *
+ * Reading a file takes three pieces of information, each cached at its own lifetime:
+ *   - the commit a ref points at — the only time-varying one, so it is resolved once per
+ *     operation and never carried across them (see `code-operation`);
+ *   - that commit's tree (path → blob sha) — immutable, cached per commit;
+ *   - a blob's bytes — immutable, cached per blob sha, so a file that survives a commit
+ *     untouched is never downloaded twice.
+ *
+ * One instance per (repo, ref) pair; instances are shared across projects by `code-source`.
+ */
+export declare class GitHubCodeApi {
+    private readonly spec;
+    private readonly token;
+    private readonly treeByCommit;
+    private readonly truncatedCommits;
+    private readonly blobCache;
+    constructor(spec: RepoSpec, token: string | undefined);
+    get label(): string;
+    private request;
+    /**
+     * The commit the configured ref points at right now.
+     *
+     * Resolved afresh for each operation — so a push is visible to the very next call — but only
+     * once within it, however many files that operation ends up reading.
+     */
+    resolveRef(): Promise<ResolvedRef>;
+    /** path → blob sha for every file in the commit's tree. */
+    getTree(commitSha: string): Promise<Map<string, string>>;
+    /** Whether the tree we hold for this commit is known to be incomplete. */
+    isTreeTruncated(commitSha: string): boolean;
+    /** Blob sha for one path at one commit, or undefined if the file does not exist there. */
+    getBlobSha(commitSha: string, repoPath: string): Promise<string | undefined>;
+    /** A blob's bytes. Blobs are immutable, so this is cached for the life of the process. */
+    getBlob(blobSha: string): Promise<Buffer>;
+    /**
+     * Unified diff of every file that changed between two commits, keyed by path.
+     *
+     * One call covers a whole doc, so `git_diff_doc` groups its tracked files by the commit they
+     * were snapshotted at rather than asking per file. GitHub caps the response at 300 files;
+     * paths beyond that are simply absent from the map.
+     */
+    comparePatches(baseSha: string, headSha: string): Promise<Map<string, string>>;
+}
+export {};

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

@@ -0,0 +1,182 @@
+import { createLogger } from "@imenam/mcp-gui-interface";
+import { oncePerOperation } from "./code-operation.js";
+const logger = createLogger("GitHubCodeApi");
+const API_BASE = "https://api.github.com";
+export function formatRepoSpec(spec) {
+    return `${spec.owner}/${spec.repo}@${spec.ref ?? "HEAD"}`;
+}
+/**
+ * Parses the repo half of a code-source setting.
+ *
+ * Accepted forms — with an optional `#branch` suffix on any of them:
+ *   owner/repo
+ *   https://github.com/owner/repo(.git)
+ *   git@github.com:owner/repo(.git)
+ */
+export function parseRepoSpec(raw) {
+    const trimmed = raw.trim();
+    const hashIdx = trimmed.indexOf("#");
+    const withoutRef = hashIdx >= 0 ? trimmed.slice(0, hashIdx) : trimmed;
+    const ref = hashIdx >= 0 ? trimmed.slice(hashIdx + 1).trim() || undefined : undefined;
+    // Strip any transport prefix and the trailing .git, leaving "owner/repo".
+    const slug = withoutRef
+        .replace(/^https?:\/\/[^/]+\//i, "")
+        .replace(/^git@[^:]+:/i, "")
+        .replace(/\.git$/i, "")
+        .replace(/^\/+|\/+$/g, "");
+    const parts = slug.split("/").filter(Boolean);
+    const NAME = /^[A-Za-z0-9._-]+$/;
+    if (parts.length !== 2 || !NAME.test(parts[0]) || !NAME.test(parts[1])) {
+        throw new Error(`Invalid repository "${raw}". Expected "owner/repo", a GitHub URL, optionally suffixed with "#branch".`);
+    }
+    return { owner: parts[0], repo: parts[1], ref };
+}
+export class GitHubApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "GitHubApiError";
+    }
+}
+/**
+ * Read-only access to a repository's file tree over the GitHub API.
+ *
+ * Reading a file takes three pieces of information, each cached at its own lifetime:
+ *   - the commit a ref points at — the only time-varying one, so it is resolved once per
+ *     operation and never carried across them (see `code-operation`);
+ *   - that commit's tree (path → blob sha) — immutable, cached per commit;
+ *   - a blob's bytes — immutable, cached per blob sha, so a file that survives a commit
+ *     untouched is never downloaded twice.
+ *
+ * One instance per (repo, ref) pair; instances are shared across projects by `code-source`.
+ */
+export class GitHubCodeApi {
+    spec;
+    token;
+    treeByCommit = new Map();
+    truncatedCommits = new Set();
+    blobCache = new Map();
+    constructor(spec, token) {
+        this.spec = spec;
+        this.token = token;
+    }
+    get label() {
+        return formatRepoSpec(this.spec);
+    }
+    async request(path) {
+        const headers = {
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "User-Agent": "mcp-documentor",
+        };
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        let response;
+        try {
+            response = await fetch(`${API_BASE}${path}`, { headers });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new GitHubApiError(`network error contacting GitHub (${message})`);
+        }
+        // 422 is what a valid repository returns for a ref that does not exist, so a mistyped
+        // branch lands here rather than on 404 — both mean "nothing to read at that address".
+        if (response.status === 404 || response.status === 422) {
+            throw new GitHubApiError(`not found: ${this.label} (repository, branch or path missing — or the token cannot see this repository)`, response.status);
+        }
+        if (response.status === 401 || response.status === 403) {
+            const rateLimited = response.headers.get("x-ratelimit-remaining") === "0";
+            throw new GitHubApiError(rateLimited
+                ? `GitHub API rate limit exhausted for ${this.label}`
+                : `access denied to ${this.label} — check MCP_DOCUMENTOR_CODE_TOKEN / MCP_DOCUMENTOR_SYNC_TOKEN`, response.status);
+        }
+        if (!response.ok) {
+            throw new GitHubApiError(`GitHub API returned ${response.status} for ${path}`, response.status);
+        }
+        return response.json();
+    }
+    /**
+     * The commit the configured ref points at right now.
+     *
+     * Resolved afresh for each operation — so a push is visible to the very next call — but only
+     * once within it, however many files that operation ends up reading.
+     */
+    resolveRef() {
+        return oncePerOperation(`ref:${this.label}`, async () => {
+            const ref = this.spec.ref ?? "HEAD";
+            const commit = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/commits/${encodeURIComponent(ref)}`);
+            logger.debug(`${this.label} is at ${String(commit.sha).slice(0, 7)}`);
+            return {
+                commitSha: commit.sha,
+                commitDate: commit.commit?.committer?.date ?? commit.commit?.author?.date ?? new Date().toISOString(),
+            };
+        });
+    }
+    /** path → blob sha for every file in the commit's tree. */
+    async getTree(commitSha) {
+        const cached = this.treeByCommit.get(commitSha);
+        if (cached)
+            return cached;
+        const tree = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/trees/${commitSha}?recursive=1`);
+        const map = new Map();
+        for (const entry of tree.tree ?? []) {
+            if (entry.type === "blob")
+                map.set(entry.path, entry.sha);
+        }
+        if (tree.truncated) {
+            // Past ~100k entries GitHub stops listing. Existence checks would then be wrong, so we
+            // remember it and fall back to a per-path lookup for anything absent from the partial tree.
+            this.truncatedCommits.add(commitSha);
+            logger.warn(`${this.label}: tree listing truncated at ${map.size} entries; falling back to per-path lookups`);
+        }
+        this.treeByCommit.set(commitSha, map);
+        return map;
+    }
+    /** Whether the tree we hold for this commit is known to be incomplete. */
+    isTreeTruncated(commitSha) {
+        return this.truncatedCommits.has(commitSha);
+    }
+    /** Blob sha for one path at one commit, or undefined if the file does not exist there. */
+    async getBlobSha(commitSha, repoPath) {
+        const tree = await this.getTree(commitSha);
+        const known = tree.get(repoPath);
+        if (known || !this.isTreeTruncated(commitSha))
+            return known;
+        try {
+            const contents = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/contents/${encodeURI(repoPath)}?ref=${commitSha}`);
+            return typeof contents?.sha === "string" ? contents.sha : undefined;
+        }
+        catch (err) {
+            if (err instanceof GitHubApiError && err.status === 404)
+                return undefined;
+            throw err;
+        }
+    }
+    /** A blob's bytes. Blobs are immutable, so this is cached for the life of the process. */
+    async getBlob(blobSha) {
+        const cached = this.blobCache.get(blobSha);
+        if (cached)
+            return cached;
+        const blob = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/git/blobs/${blobSha}`);
+        const bytes = Buffer.from(blob.content ?? "", blob.encoding === "base64" ? "base64" : "utf-8");
+        this.blobCache.set(blobSha, bytes);
+        return bytes;
+    }
+    /**
+     * Unified diff of every file that changed between two commits, keyed by path.
+     *
+     * One call covers a whole doc, so `git_diff_doc` groups its tracked files by the commit they
+     * were snapshotted at rather than asking per file. GitHub caps the response at 300 files;
+     * paths beyond that are simply absent from the map.
+     */
+    async comparePatches(baseSha, headSha) {
+        const comparison = await this.request(`/repos/${this.spec.owner}/${this.spec.repo}/compare/${baseSha}...${headSha}`);
+        const patches = new Map();
+        for (const file of comparison.files ?? []) {
+            if (typeof file.patch === "string")
+                patches.set(file.filename, file.patch);
+        }
+        return patches;
+    }
+}

package/dist/src/core/section-tracker.d.ts

@@ -1,32 +1,57 @@
 import type { TrackedSection } from "../../shared/schemas/doc.schema.js";
 /**
- * Reads a file and snapshots a section defined by 1-indexed [start, end] line numbers.
+ * A file's content, split both ways.
+ *
+ * Matching and hashing always use `lines` — every line with its trailing CR stripped — so a
+ * snapshot taken from a CRLF working copy and one taken from the LF blob stored in the repo
+ * produce the same hash. Without that, pointing a project at a GitHub code source would mark
+ * every file as modified on the first check.
+ *
+ * `raw` is kept only to recognise hashes stored before that normalisation existed, so an
+ * untouched file never reads as modified just because the tracker changed.
+ */
+export interface FileContent {
+    raw: string[];
+    lines: string[];
+}
+export declare function toFileContent(text: string): FileContent;
+export declare function bytesToFileContent(bytes: Buffer): FileContent;
+/** The whole-file hash written into a snapshot: taken over the normalised content. */
+export declare function hashFileContent(fc: FileContent): string;
+/**
+ * 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 declare function fileContentMatches(fc: FileContent, storedHash: string): boolean;
+/**
+ * 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 declare function snapshotSection(absolutePath: string, start: number, end: number): TrackedSection;
+export declare function snapshotSection(fc: FileContent, start: number, end: number): TrackedSection;
 type FindResult = {
     found: false;
 } | {
     found: true;
+    /** Hash of the located content, in the form a snapshot would store. */
     currentHash: string;
+    /** Whether the stored hash still describes the located content (legacy hashes included). */
+    matchesStored: boolean;
+    /** Current 1-indexed line range, so callers can display it without storing it. */
     lines: {
         start: number;
         end: number;
     };
 };
 /**
- * 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.
+ * Locates a tracked section in the current content and compares it with its stored hash.
  *
- * Returns { found: false } if the anchors cannot be located — which is treated as stale,
+ * 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 declare function findAndHashSection(absolutePath: string, section: TrackedSection): FindResult;
+export declare function findAndHashSection(fc: FileContent, section: TrackedSection): FindResult;
 type RelocateResult = {
     found: false;
 } | {
@@ -35,8 +60,8 @@ type RelocateResult = {
 };
 /**
  * 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 declare function relocateAndRefreshSection(absolutePath: string, section: TrackedSection): RelocateResult;
+export declare function relocateAndRefreshSection(fc: FileContent, section: TrackedSection): RelocateResult;
 export {};