@lepid-labs/weft-core 0.1.0

package/dist/repos.js

@@ -0,0 +1,46 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+/** `org/repo`: exactly two non-empty segments, no whitespace. */
+export const REPO_IDENTITY = /^[^/\s]+\/[^/\s]+$/;
+/**
+ * Resolve the configured `repos` map to absolute checkout paths.
+ *
+ * `~` expands to the home directory here rather than being left to the shell,
+ * because the value arrives from a YAML file no shell ever touches.
+ */
+export function resolveRepos(repos, rootDir) {
+    const map = new Map();
+    for (const [identity, path] of Object.entries(repos ?? {})) {
+        const expanded = path === "~" || path.startsWith("~/") ? resolve(homedir(), path.slice(2)) : path;
+        map.set(identity, isAbsolute(expanded) ? expanded : resolve(rootDir, expanded));
+    }
+    return map;
+}
+/**
+ * Parse a GitHub blob URL into repo identity, in-repo path and fragment.
+ *
+ * Any `blob/<ref>/` segment is accepted — weft serves the working tree, so
+ * which ref the URL claims is a validation question, not a resolution one. The
+ * ref is taken to be a single path segment; a branch name containing `/` is
+ * indistinguishable from the leading directories of the path in a blob URL, so
+ * such a URL resolves to a path that exists in no docs root and stays an
+ * ordinary external link.
+ */
+export function parseGitHubBlobUrl(url) {
+    const match = /^https?:\/\/(?:www\.)?github\.com\/([^/\s]+\/[^/\s]+)\/blob\/[^/\s]+\/([^#\s]+)(#.+)?$/.exec(url);
+    if (!match)
+        return undefined;
+    let path;
+    try {
+        path = decodeURIComponent(match[2]);
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        repo: match[1],
+        path,
+        ...(match[3] ? { anchor: match[3] } : {}),
+    };
+}
+//# sourceMappingURL=repos.js.map

package/dist/repos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repos.js","sourceRoot":"","sources":["../src/repos.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKhD,iEAAiE;AACjE,MAAM,CAAC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAyC,EAAE,OAAe;IACtF,MAAM,GAAG,GAAY,IAAI,GAAG,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,MAAM,QAAQ,GACb,IAAI,KAAK,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC;AAYD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC7C,MAAM,KAAK,GACV,wFAAwF,CAAC,IAAI,CAC5F,GAAG,CACH,CAAC;IACH,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAE7B,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,SAAS,CAAC;IAClB,CAAC;IAED,OAAO;QACN,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QACd,IAAI;QACJ,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzC,CAAC;AACH,CAAC"}

package/dist/repos.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=repos.test.d.ts.map

package/dist/repos.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repos.test.d.ts","sourceRoot":"","sources":["../src/repos.test.ts"],"names":[],"mappings":""}

package/dist/repos.test.js

@@ -0,0 +1,61 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { parseGitHubBlobUrl, resolveRepos } from "./repos.js";
+const ROOT = resolve("/project");
+describe("resolveRepos", () => {
+    it("returns an empty map for an absent config", () => {
+        expect(resolveRepos(undefined, ROOT).size).toBe(0);
+    });
+    it("resolves relative paths against the root dir", () => {
+        const repos = resolveRepos({ "acme/alpha": "../alpha" }, ROOT);
+        expect(repos.get("acme/alpha")).toBe(resolve(ROOT, "../alpha"));
+    });
+    it("keeps absolute paths as they are", () => {
+        const abs = resolve("/checkouts/beta");
+        const repos = resolveRepos({ "acme/beta": abs }, ROOT);
+        expect(repos.get("acme/beta")).toBe(abs);
+    });
+    it("expands ~ to the home directory", () => {
+        const repos = resolveRepos({ "acme/beta": "~/src/beta" }, ROOT);
+        expect(repos.get("acme/beta")).toBe(resolve(homedir(), "src/beta"));
+    });
+    it("does not expand ~ in the middle of a path", () => {
+        const repos = resolveRepos({ "acme/beta": "checkouts/~beta" }, ROOT);
+        expect(repos.get("acme/beta")).toBe(resolve(ROOT, "checkouts/~beta"));
+    });
+});
+describe("parseGitHubBlobUrl", () => {
+    it("parses repo identity, path and anchor", () => {
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha/blob/main/docs/api.md#endpoints")).toEqual({
+            repo: "acme/alpha",
+            path: "docs/api.md",
+            anchor: "#endpoints",
+        });
+    });
+    it("accepts any ref segment — weft serves the working tree", () => {
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha/blob/v2.1/docs/api.md")).toEqual({
+            repo: "acme/alpha",
+            path: "docs/api.md",
+        });
+    });
+    it("accepts http and a www prefix", () => {
+        expect(parseGitHubBlobUrl("http://www.github.com/acme/alpha/blob/main/README.md")).toEqual({
+            repo: "acme/alpha",
+            path: "README.md",
+        });
+    });
+    it("decodes percent-encoded paths", () => {
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha/blob/main/docs/release%20notes.md")?.path).toBe("docs/release notes.md");
+    });
+    it("returns undefined for tree URLs, other hosts, and non-blob paths", () => {
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha/tree/main/docs")).toBeUndefined();
+        expect(parseGitHubBlobUrl("https://gitlab.com/acme/alpha/blob/main/a.md")).toBeUndefined();
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha")).toBeUndefined();
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha/issues/12")).toBeUndefined();
+    });
+    it("returns undefined for a malformed percent encoding", () => {
+        expect(parseGitHubBlobUrl("https://github.com/acme/alpha/blob/main/%E0%A4%A.md")).toBeUndefined();
+    });
+});
+//# sourceMappingURL=repos.test.js.map

package/dist/repos.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repos.test.js","sourceRoot":"","sources":["../src/repos.test.ts"],"names":[],"mappings":"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"}

package/dist/scalar-source.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A YAML scalar's text exactly as it was written.
+ *
+ * YAML types unquoted scalars, and for the identifiers Weft carries around that
+ * is a loss rather than a convenience: `2.10` becomes the number 2.1, and a
+ * content hash whose sixteen hex characters happen to all be digits becomes an
+ * integer with its leading zeros gone. Either way the value stops matching the
+ * text the author wrote, and the mismatch exists only in the parse.
+ *
+ * The parser keeps each scalar's source text for exactly this reason, so prefer
+ * it and leave quoting to the author's taste. Returns undefined for an absent or
+ * empty value, which callers treat as "not declared".
+ */
+export declare function scalarText(node: unknown): string | undefined;
+//# sourceMappingURL=scalar-source.d.ts.map

package/dist/scalar-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-source.d.ts","sourceRoot":"","sources":["../src/scalar-source.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK5D"}

package/dist/scalar-source.js

@@ -0,0 +1,21 @@
+import { isScalar } from "yaml";
+/**
+ * A YAML scalar's text exactly as it was written.
+ *
+ * YAML types unquoted scalars, and for the identifiers Weft carries around that
+ * is a loss rather than a convenience: `2.10` becomes the number 2.1, and a
+ * content hash whose sixteen hex characters happen to all be digits becomes an
+ * integer with its leading zeros gone. Either way the value stops matching the
+ * text the author wrote, and the mismatch exists only in the parse.
+ *
+ * The parser keeps each scalar's source text for exactly this reason, so prefer
+ * it and leave quoting to the author's taste. Returns undefined for an absent or
+ * empty value, which callers treat as "not declared".
+ */
+export function scalarText(node) {
+    if (!isScalar(node) || node.value === null || node.value === undefined)
+        return undefined;
+    const source = typeof node.source === "string" ? node.source.trim() : "";
+    return source || String(node.value);
+}
+//# sourceMappingURL=scalar-source.js.map

package/dist/scalar-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalar-source.js","sourceRoot":"","sources":["../src/scalar-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAEhC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACvC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEzF,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzE,OAAO,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC"}

package/dist/search.d.ts

@@ -0,0 +1,14 @@
+import type { Manifest, SearchResult } from "./types.js";
+export declare class SearchIndex {
+    private index;
+    constructor();
+    /**
+     * Build the search index from a manifest. `resolvePath` maps a node id to an
+     * absolute file path — a function rather than a directory, since node ids may
+     * span several docs roots.
+     */
+    build(manifest: Manifest, resolvePath: (nodeId: string) => string | undefined): void;
+    /** Search the index. */
+    search(query: string): SearchResult[];
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AASzD,qBAAa,WAAW;IACvB,OAAO,CAAC,KAAK,CAAwB;;IAcrC;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG,IAAI;IA8BpF,wBAAwB;IACxB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE;CASrC"}

package/dist/search.js

@@ -0,0 +1,59 @@
+import { readFileSync } from "node:fs";
+import MiniSearch from "minisearch";
+export class SearchIndex {
+    index;
+    constructor() {
+        this.index = new MiniSearch({
+            fields: ["title", "content", "anchors"],
+            storeFields: ["title"],
+            searchOptions: {
+                boost: { title: 3, anchors: 2, content: 1 },
+                fuzzy: 0.2,
+                prefix: true,
+            },
+        });
+    }
+    /**
+     * Build the search index from a manifest. `resolvePath` maps a node id to an
+     * absolute file path — a function rather than a directory, since node ids may
+     * span several docs roots.
+     */
+    build(manifest, resolvePath) {
+        this.index.removeAll();
+        // Artifacts are excluded outright. Reading a PDF as UTF-8 does not throw —
+        // it yields a lossy decode — so the catch below would never fire and the
+        // index would fill with binary noise that matches queries by accident.
+        const searchable = manifest.nodes.filter((node) => node.type !== "artifact");
+        const docs = searchable.map((node) => {
+            let content = "";
+            const path = resolvePath(node.id);
+            try {
+                if (path)
+                    content = readFileSync(path, "utf-8");
+            }
+            catch {
+                // File may not exist or be unreadable
+            }
+            return {
+                id: node.id,
+                title: node.title,
+                content,
+                // Index the heading text alongside the slug: a reader searches for
+                // "Data Flow", not "data-flow".
+                anchors: node.anchors.map((a) => `${a.slug} ${a.text}`).join(" "),
+            };
+        });
+        this.index.addAll(docs);
+    }
+    /** Search the index. */
+    search(query) {
+        const results = this.index.search(query);
+        return results.map((r) => ({
+            id: r.id,
+            title: r.title,
+            score: r.score,
+            match: r.match,
+        }));
+    }
+}
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,UAAU,MAAM,YAAY,CAAC;AAUpC,MAAM,OAAO,WAAW;IACf,KAAK,CAAwB;IAErC;QACC,IAAI,CAAC,KAAK,GAAG,IAAI,UAAU,CAAY;YACtC,MAAM,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC;YACvC,WAAW,EAAE,CAAC,OAAO,CAAC;YACtB,aAAa,EAAE;gBACd,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;gBAC3C,KAAK,EAAE,GAAG;gBACV,MAAM,EAAE,IAAI;aACZ;SACD,CAAC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAkB,EAAE,WAAmD;QAC5E,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;QAEvB,2EAA2E;QAC3E,yEAAyE;QACzE,uEAAuE;QACvE,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;QAE7E,MAAM,IAAI,GAAgB,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACjD,IAAI,OAAO,GAAG,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC;gBACJ,IAAI,IAAI;oBAAE,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YACjD,CAAC;YAAC,MAAM,CAAC;gBACR,sCAAsC;YACvC,CAAC;YAED,OAAO;gBACN,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,OAAO;gBACP,mEAAmE;gBACnE,gCAAgC;gBAChC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;aACjE,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,wBAAwB;IACxB,MAAM,CAAC,KAAa;QACnB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1B,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAG,CAAkC,CAAC,KAAK;YAChD,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,KAAK,EAAE,CAAC,CAAC,KAAK;SACd,CAAC,CAAC,CAAC;IACL,CAAC;CACD"}

package/dist/service-concurrency.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-concurrency.test.d.ts.map

package/dist/service-concurrency.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-concurrency.test.d.ts","sourceRoot":"","sources":["../src/service-concurrency.test.ts"],"names":[],"mappings":""}

package/dist/service-concurrency.test.js

@@ -0,0 +1,89 @@
+import { cpSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { WeftService } from "./service.js";
+const __dirname = resolve(fileURLToPath(import.meta.url), "..");
+const FIXTURES_DIR = resolve(__dirname, "__fixtures__");
+/**
+ * Hooks into the mocked `checkFreshness` below: `hold` keeps a check open
+ * after it has its answer in hand, so a test can complete a `rebuild()` in
+ * exactly the window between computing a freshness result and caching it —
+ * the interleaving an MCP server handling concurrent tool calls produces
+ * naturally, and one no amount of sequencing through the public API can pin
+ * down deterministically.
+ */
+const gate = {
+    hold: null,
+    reached: null,
+    calls: 0,
+};
+vi.mock("./freshness.js", async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        checkFreshness: async (...args) => {
+            gate.calls++;
+            const result = await actual.checkFreshness(...args);
+            gate.reached?.();
+            if (gate.hold)
+                await gate.hold;
+            return result;
+        },
+    };
+});
+const tempDirs = [];
+function createWritableService() {
+    const dir = mkdtempSync(resolve(tmpdir(), "weft-concurrency-"));
+    tempDirs.push(dir);
+    cpSync(resolve(FIXTURES_DIR, "docs"), resolve(dir, "docs"), { recursive: true });
+    const service = new WeftService({
+        rootDir: dir,
+        docsDir: "docs",
+        entryPoint: "docs/README.md",
+        ignore: [],
+    });
+    return { dir, service };
+}
+afterEach(() => {
+    gate.hold = null;
+    gate.reached = null;
+    gate.calls = 0;
+    for (const dir of tempDirs.splice(0))
+        rmSync(dir, { recursive: true, force: true });
+});
+describe("WeftService freshness under concurrency", () => {
+    it("never caches a check that a rebuild overtook", async () => {
+        const { dir, service } = createWritableService();
+        await service.getManifest();
+        writeFileSync(resolve(dir, "docs", "architecture.md"), "# Changed\n");
+        let release;
+        gate.hold = new Promise((r) => {
+            release = r;
+        });
+        const reached = new Promise((r) => {
+            gate.reached = r;
+        });
+        const inFlight = service.freshness();
+        // The check has computed `stale` but not yet written it to the cache.
+        await reached;
+        await service.rebuild();
+        release();
+        // The overlapped caller still gets the honest answer for when it asked…
+        expect((await inFlight).status).toBe("stale");
+        // …but that answer was not cached over the rebuild's state: within the
+        // cache window, the next call re-checks and sees the rebuilt manifest.
+        expect((await service.freshness()).status).toBe("fresh");
+    });
+    it("coalesces concurrent cache misses onto one tree re-read", async () => {
+        const { service } = createWritableService();
+        await service.getManifest();
+        gate.calls = 0;
+        const [first, second] = await Promise.all([service.freshness(), service.freshness()]);
+        expect(first.status).toBe("fresh");
+        expect(second.status).toBe("fresh");
+        expect(gate.calls).toBe(1);
+    });
+});
+//# sourceMappingURL=service-concurrency.test.js.map

package/dist/service-concurrency.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-concurrency.test.js","sourceRoot":"","sources":["../src/service-concurrency.test.ts"],"names":[],"mappings":"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"}

package/dist/service-history.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-history.test.d.ts.map

package/dist/service-history.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-history.test.d.ts","sourceRoot":"","sources":["../src/service-history.test.ts"],"names":[],"mappings":""}

package/dist/service-history.test.js

@@ -0,0 +1,76 @@
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { WeftService } from "./service.js";
+import { ValidatorRegistry } from "./validate/index.js";
+// The point of these tests is counting subprocess spawns, so the walk itself
+// is stubbed: every call lands in `walks` and yields an empty history, which
+// both the indexer and validation accept as "git had nothing to say".
+const walks = [];
+vi.mock("./git.js", async (importOriginal) => {
+    const original = await importOriginal();
+    const fileHistory = async (dir, depth = "full") => {
+        walks.push({ dir, depth });
+        return { dates: new Map(), blobs: new Map(), renames: new Map() };
+    };
+    return {
+        ...original,
+        fileHistory,
+        lastCommitDates: async (dir) => (await fileHistory(dir, "dates")).dates,
+    };
+});
+const __dirname = resolve(fileURLToPath(import.meta.url), "..");
+const FIXTURES_DIR = resolve(__dirname, "__fixtures__");
+function createService() {
+    const config = {
+        rootDir: FIXTURES_DIR,
+        docsDir: "docs",
+        entryPoint: "docs/README.md",
+        ignore: [],
+    };
+    return new WeftService(config);
+}
+/** A registry whose one rule reads no history. */
+function historylessRegistry() {
+    return new ValidatorRegistry().register({
+        rules: [{ id: "no-history", description: "Reads no history", defaultSeverity: "info" }],
+        run: () => [],
+    });
+}
+beforeEach(() => {
+    walks.length = 0;
+});
+describe("WeftService history walks", () => {
+    it("walks git once per root, at full depth, when check builds and validates", async () => {
+        // The regression in #54: indexing walked for dates and validation walked
+        // again identically, so a one-root `weft check` ran `git log` twice.
+        const service = createService();
+        await service.validate();
+        expect(walks).toEqual([{ dir: resolve(FIXTURES_DIR, "docs"), depth: "full" }]);
+    });
+    it("walks once at dates depth for a plain rebuild", async () => {
+        const service = createService();
+        await service.rebuild();
+        expect(walks).toEqual([{ dir: resolve(FIXTURES_DIR, "docs"), depth: "dates" }]);
+    });
+    it("walks once at dates depth when no enabled rule reads history", async () => {
+        const service = createService();
+        await service.validate(historylessRegistry());
+        expect(walks.map((walk) => walk.depth)).toEqual(["dates"]);
+    });
+    it("upgrades a dates walk to full once, then serves validation from cache", async () => {
+        const service = createService();
+        await service.rebuild();
+        await service.validate();
+        await service.validate();
+        expect(walks.map((walk) => walk.depth)).toEqual(["dates", "full"]);
+    });
+    it("walks afresh after a rebuild invalidates the cached history", async () => {
+        const service = createService();
+        await service.validate();
+        await service.rebuild();
+        await service.validate();
+        expect(walks.map((walk) => walk.depth)).toEqual(["full", "dates", "full"]);
+    });
+});
+//# sourceMappingURL=service-history.test.js.map

package/dist/service-history.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-history.test.js","sourceRoot":"","sources":["../src/service-history.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,6EAA6E;AAC7E,6EAA6E;AAC7E,sEAAsE;AACtE,MAAM,KAAK,GAA2C,EAAE,CAAC;AAEzD,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE;IAC5C,MAAM,QAAQ,GAAG,MAAM,cAAc,EAA6B,CAAC;IACnE,MAAM,WAAW,GAAG,KAAK,EAAE,GAAW,EAAE,QAAsB,MAAM,EAAE,EAAE;QACvE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3B,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IACnE,CAAC,CAAC;IACF,OAAO;QACN,GAAG,QAAQ;QACX,WAAW;QACX,eAAe,EAAE,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,CAAC,MAAM,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK;KAC/E,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;AAChE,MAAM,YAAY,GAAG,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAExD,SAAS,aAAa;IACrB,MAAM,MAAM,GAAe;QAC1B,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,MAAM;QACf,UAAU,EAAE,gBAAgB;QAC5B,MAAM,EAAE,EAAE;KACV,CAAC;IACF,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,kDAAkD;AAClD,SAAS,mBAAmB;IAC3B,OAAO,IAAI,iBAAiB,EAAE,CAAC,QAAQ,CAAC;QACvC,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;QACvF,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE;KACb,CAAC,CAAC;AACJ,CAAC;AAED,UAAU,CAAC,GAAG,EAAE;IACf,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IAC1C,EAAE,CAAC,yEAAyE,EAAE,KAAK,IAAI,EAAE;QACxF,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAEzB,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;QAC9D,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QAExB,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC7E,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,MAAM,OAAO,CAAC,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAC;QAE9C,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uEAAuE,EAAE,KAAK,IAAI,EAAE;QACtF,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzB,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAEzB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;QAEhC,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAEzB,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/service.d.ts

@@ -0,0 +1,118 @@
+import { type DocsRoot } from "./config.js";
+import { type HistoryDepth } from "./git.js";
+import type { Freshness, Manifest, SearchResult, WeftConfig, WeftEdge } from "./types.js";
+import { type ValidationResult, type ValidatorRegistry } from "./validate/index.js";
+export declare class WeftService {
+    private config;
+    private roots;
+    private graphs;
+    /**
+     * The last history walk per root, tagged with how deep it went. A rebuild
+     * replaces its targets' entries, so an entry is always as fresh as the
+     * graph built beside it. `validate` upgrades a `"dates"` entry to `"full"`
+     * on demand; the reverse never happens implicitly — a full walk answers a
+     * dates question, not the other way round.
+     */
+    private histories;
+    private manifest;
+    private searchIndex;
+    private freshnessCache;
+    /**
+     * Bumped by every rebuild. A `freshness()` check spans an `await` over a
+     * full tree re-read, so a rebuild can complete underneath it — clearing
+     * the cache is not enough, because the in-flight check would then resume
+     * and write its pre-rebuild answer back. The check records the generation
+     * it started under and only caches if no rebuild happened in between.
+     */
+    private freshnessGeneration;
+    /** In-flight check, so concurrent cache misses share one tree re-read. */
+    private freshnessInFlight;
+    constructor(config: WeftConfig);
+    get weftConfig(): WeftConfig;
+    /** All configured docs roots — one per project, or a single implicit root. */
+    get docsRoots(): DocsRoot[];
+    /** True when node ids are namespaced by project slug. */
+    get namespaced(): boolean;
+    /** Get the docs directory absolute path. In multi-project mode, the first project's. */
+    get docsDir(): string;
+    /** Path of the merged manifest. Always under `rootDir` when the docs root is not. */
+    get manifestPath(): string;
+    /**
+     * Path of a single project's manifest.
+     *
+     * A root living in another checkout gets its manifest under this project's
+     * own `.weft/` — writing into a repo we do not own would dirty its git
+     * status on every index. `manifestInRepo` opts a co-owned repo back in.
+     */
+    projectManifestPath(slug: string): string;
+    /** Path of the index listing every project manifest. */
+    get projectsIndexPath(): string;
+    /** Resolve a node id to an absolute file path, or undefined if it escapes its root. */
+    resolveNodePath(nodeId: string): string | undefined;
+    /** Walk one root's git history at the given depth and remember the result. */
+    private walkHistory;
+    /**
+     * Build or rebuild the manifest from the filesystem. Pass a project slug to
+     * rescan only that project — the rest of the graph is reused.
+     *
+     * The history walk each root pays here is shared with `validate`: at the
+     * default `"dates"` depth it skips rename detection, since indexing only
+     * wants commit dates. `validate` builds at `"full"` depth instead when a
+     * history-reading rule is enabled, so `weft check` walks git exactly once
+     * per root rather than once for indexing and again for validation.
+     *
+     * The inputs hash always spans every root, even for a single-project
+     * rescan: it is the baseline for the whole merged manifest, not just the
+     * project that changed, so a partial rebuild that skipped roots outside
+     * `slug` would leave the hash wrong specifically in multi-project mode.
+     */
+    rebuild(slug?: string, historyDepth?: HistoryDepth): Promise<Manifest>;
+    /** Get the current manifest, building it if necessary. */
+    getManifest(): Promise<Manifest>;
+    /**
+     * Whether the manifest still reflects its docs tree.
+     *
+     * Answering honestly costs a full re-read of the docs tree, so the result
+     * is cached for {@link FRESHNESS_CACHE_MS} — see that constant for why.
+     * `rebuild` clears the cache immediately.
+     */
+    freshness(): Promise<Freshness>;
+    /**
+     * Write the manifest to disk. In multi-project mode this writes one manifest
+     * per project, an index of them, and the merged manifest at the project root.
+     * Returns every path written.
+     */
+    writeManifest(): Promise<string[]>;
+    /**
+     * Read a document's content.
+     *
+     * An artifact is refused rather than read. Reading a binary as UTF-8 does not
+     * throw — it returns a lossy decode — so without this the caller receives
+     * nonsense wearing every sign of success, a 200 and a body, instead of an
+     * error it can act on.
+     */
+    read(nodeId: string): string;
+    /**
+     * Run the validation stage over the current manifest, building it first if
+     * necessary. Pass a registry to run a different set of checks than the
+     * built-in ones.
+     *
+     * History is shared with the build rather than walked again: a graph built
+     * here is built at `"full"` depth when a history-reading rule is enabled,
+     * and a graph built earlier at `"dates"` depth has each root upgraded once
+     * and remembered until its next rebuild.
+     */
+    validate(registry?: ValidatorRegistry): Promise<ValidationResult>;
+    /** Search the index. */
+    search(query: string): Promise<SearchResult[]>;
+    /** Traverse the graph: find edges connected to a node. */
+    traverse(nodeId: string, direction?: "outgoing" | "incoming" | "both"): Promise<WeftEdge[]>;
+    /**
+     * Watch every docs root for changes, rebuilding the changed project on change.
+     *
+     * A root inside the fetch cache is a checkout pinned to a commit — nothing
+     * edits it, so it is not watched.
+     */
+    watch(callback?: (manifest: Manifest) => void): () => void;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,QAAQ,EAAiD,MAAM,aAAa,CAAC;AAI3F,OAAO,EAAoB,KAAK,YAAY,EAAe,MAAM,UAAU,CAAC;AAG5E,OAAO,KAAK,EACX,SAAS,EACT,QAAQ,EAGR,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,MAAM,YAAY,CAAC;AACpB,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAKtB,MAAM,qBAAqB,CAAC;AAa7B,qBAAa,WAAW;IACvB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAAgC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,SAAS,CAAoE;IACrF,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAyD;IAC/E;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB,CAAK;IAChC,0EAA0E;IAC1E,OAAO,CAAC,iBAAiB,CAAoE;gBAEjF,MAAM,EAAE,UAAU;IAM9B,IAAI,UAAU,IAAI,UAAU,CAE3B;IAED,8EAA8E;IAC9E,IAAI,SAAS,IAAI,QAAQ,EAAE,CAE1B;IAED,yDAAyD;IACzD,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,wFAAwF;IACxF,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,qFAAqF;IACrF,IAAI,YAAY,IAAI,MAAM,CAIzB;IAED;;;;;;OAMG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IASzC,wDAAwD;IACxD,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,uFAAuF;IACvF,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAUnD,8EAA8E;YAChE,WAAW;IAMzB;;;;;;;;;;;;;;OAcG;IACG,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,YAAY,GAAE,YAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAuCrF,0DAA0D;IACpD,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC;IAOtC;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC;IAqCrC;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAmCxC;;;;;;;OAOG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAa5B;;;;;;;;;OASG;IACG,QAAQ,CAAC,QAAQ,GAAE,iBAAqC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqB1F,wBAAwB;IAClB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAKpD,0DAA0D;IACpD,QAAQ,CACb,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,UAAU,GAAG,UAAU,GAAG,MAAe,GAClD,OAAO,CAAC,QAAQ,EAAE,CAAC;IAatB;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,MAAM,IAAI;CAsC1D"}