@lepid-labs/weft-core 0.1.0

package/dist/content.test.js

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { countLines, hashBytes, hashContent, normalizeContent } from "./content.js";
+const BOM = "\uFEFF";
+describe("normalizeContent", () => {
+    it("converts CRLF to LF", () => {
+        expect(normalizeContent("a\r\nb\r\n")).toBe("a\nb\n");
+    });
+    it("strips a leading BOM", () => {
+        expect(normalizeContent(`${BOM}# Title`)).toBe("# Title");
+    });
+    it("leaves a BOM-like character that is not leading alone", () => {
+        expect(normalizeContent(`a${BOM}b`)).toBe(`a${BOM}b`);
+    });
+    it("leaves already-normalized content untouched", () => {
+        expect(normalizeContent("a\nb\n")).toBe("a\nb\n");
+    });
+});
+describe("hashContent", () => {
+    it("is stable for identical content", () => {
+        expect(hashContent("# Title\n")).toBe(hashContent("# Title\n"));
+    });
+    it("changes when the content changes", () => {
+        expect(hashContent("# Title\n")).not.toBe(hashContent("# Title!\n"));
+    });
+    // The point of normalizing: git does not preserve line endings across
+    // platforms, so a raw-byte hash would report every document as changed the
+    // moment CI checked it out with different ones.
+    it("is identical for CRLF and LF versions of the same document", () => {
+        expect(hashContent("# Title\n\nBody.\n")).toBe(hashContent("# Title\r\n\r\nBody.\r\n"));
+    });
+    it("is identical with and without a BOM", () => {
+        expect(hashContent("# Title\n")).toBe(hashContent(`${BOM}# Title\n`));
+    });
+    it("covers frontmatter, not just the body", () => {
+        const withTitle = "---\ntitle: A\n---\n\nBody.\n";
+        const withOther = "---\ntitle: B\n---\n\nBody.\n";
+        expect(hashContent(withTitle)).not.toBe(hashContent(withOther));
+    });
+    it("is a short lowercase hex digest", () => {
+        expect(hashContent("anything")).toMatch(/^[0-9a-f]{16}$/);
+    });
+    // Documented so an external build can declare a hash rather than have Weft
+    // recompute it: strip BOM, CRLF to LF, SHA-256, first 16 hex characters.
+    it("matches a SHA-256 of the normalized text computed independently", async () => {
+        const { createHash } = await import("node:crypto");
+        const content = "# Title\r\n";
+        const expected = createHash("sha256").update("# Title\n", "utf8").digest("hex").slice(0, 16);
+        expect(hashContent(content)).toBe(expected);
+    });
+});
+describe("hashBytes", () => {
+    const bytes = (...values) => Uint8Array.from(values);
+    it("is stable for identical bytes", () => {
+        expect(hashBytes(bytes(1, 2, 3))).toBe(hashBytes(bytes(1, 2, 3)));
+    });
+    it("changes when a single byte changes", () => {
+        expect(hashBytes(bytes(1, 2, 3))).not.toBe(hashBytes(bytes(1, 2, 4)));
+    });
+    // The opposite of hashContent on purpose: a PDF holds byte sequences that
+    // look like CRLF and are not line endings, so normalizing would hash
+    // something the file never was.
+    it("does not normalize line endings the way hashContent does", () => {
+        const crlf = bytes(0x61, 0x0d, 0x0a);
+        const lf = bytes(0x61, 0x0a);
+        expect(hashBytes(crlf)).not.toBe(hashBytes(lf));
+    });
+    it("hashes bytes that are not valid UTF-8 at all", () => {
+        expect(hashBytes(bytes(0xff, 0xfe, 0xfd))).toMatch(/^[0-9a-f]{16}$/);
+    });
+    it("is a short lowercase hex digest, like the text hash", () => {
+        expect(hashBytes(bytes(0))).toMatch(/^[0-9a-f]{16}$/);
+    });
+    it("matches a SHA-256 of the raw bytes computed independently", async () => {
+        const { createHash } = await import("node:crypto");
+        const input = bytes(0xde, 0xad, 0xbe, 0xef);
+        const expected = createHash("sha256").update(input).digest("hex").slice(0, 16);
+        expect(hashBytes(input)).toBe(expected);
+    });
+});
+describe("countLines", () => {
+    it("does not count a trailing newline as another line", () => {
+        expect(countLines("a\nb\nc\n")).toBe(3);
+    });
+    it("counts a final line with no trailing newline", () => {
+        expect(countLines("a\nb\nc")).toBe(3);
+    });
+    it("counts a single line", () => {
+        expect(countLines("just one line")).toBe(1);
+    });
+    it("counts blank lines between content", () => {
+        expect(countLines("a\n\nb\n")).toBe(3);
+    });
+    it("returns 0 for an empty document", () => {
+        expect(countLines("")).toBe(0);
+    });
+    it("counts CRLF content the same as LF", () => {
+        expect(countLines("a\r\nb\r\nc\r\n")).toBe(countLines("a\nb\nc\n"));
+    });
+});
+//# sourceMappingURL=content.test.js.map

package/dist/content.test.js.map

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

package/dist/contributions.d.ts

@@ -0,0 +1,64 @@
+import type { WeftConfig, WeftEdge, WeftNode } from "./types.js";
+/** Contribution file schema version this build understands. */
+export declare const CONTRIBUTION_VERSION = 1;
+/**
+ * Node fields a contribution may set on a document Weft already indexed.
+ *
+ * `id`, `type`, `anchors` and `project` are excluded on purpose: the first
+ * three are facts about the file Weft read, and the last is graph topology. A
+ * build tool contributes what it knows that Weft cannot see, and overriding
+ * extraction output is not that.
+ */
+declare const PATCHABLE_FIELDS: readonly ["title", "description", "theme", "ogImage", "hiddenFromNav", "contentHash", "lineCount", "version", "modified"];
+/** Field patch applied to a node that already exists in the graph. */
+export type NodePatch = Partial<Pick<WeftNode, (typeof PATCHABLE_FIELDS)[number]>>;
+/**
+ * Facts an external build declares about the graph.
+ *
+ * Weft indexes source; a renderer knows things source cannot express — what a
+ * templated link resolved to, what it generated and from what. One format for
+ * all of them, so Weft never needs a per-tool adapter.
+ */
+export interface Contribution {
+    version: number;
+    /** Producing tool, echoed in messages so a bad contribution is traceable. */
+    tool?: string;
+    /** Nodes the build knows about that indexing source cannot discover. */
+    nodes?: WeftNode[];
+    /** Edges the build knows about. */
+    edges?: WeftEdge[];
+    /** Field patches for nodes that already exist, keyed by node id. */
+    metadata?: Record<string, NodePatch>;
+}
+/** A parsed contribution and the file it came from, for error messages. */
+export interface LoadedContribution {
+    contribution: Contribution;
+    /** Path relative to the project root. */
+    file: string;
+}
+/** Validate one parsed contribution file. */
+export declare function validateContribution(raw: unknown, file: string): Contribution;
+/**
+ * Read every configured contribution file.
+ *
+ * Paths are globs relative to the project root, resolved in sorted order so a
+ * merge is reproducible regardless of how the filesystem enumerates them.
+ */
+export declare function loadContributions(config: WeftConfig): Promise<LoadedContribution[]>;
+/**
+ * Merge contributions into a graph.
+ *
+ * Order is defined and part of the contract: Weft indexes source first, then
+ * contributions apply in the order their files sorted. Indexing rendered output
+ * instead would lose sidecars and source structure, so the build contributes
+ * resolved facts afterwards rather than replacing the scan.
+ */
+export declare function applyContributions(graph: {
+    nodes: WeftNode[];
+    edges: WeftEdge[];
+}, contributions: LoadedContribution[]): {
+    nodes: WeftNode[];
+    edges: WeftEdge[];
+};
+export {};
+//# sourceMappingURL=contributions.d.ts.map

package/dist/contributions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributions.d.ts","sourceRoot":"","sources":["../src/contributions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEjE,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAUtC;;;;;;;GAOG;AACH,QAAA,MAAM,gBAAgB,2HAYZ,CAAC;AAEX,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,mCAAmC;IACnC,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACrC;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IAClC,YAAY,EAAE,YAAY,CAAC;IAC3B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACb;AAmED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAgC7E;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAsBzF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,KAAK,EAAE;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,EAC/C,aAAa,EAAE,kBAAkB,EAAE,GACjC;IAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,CAsC1C"}

package/dist/contributions.js

@@ -0,0 +1,184 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { glob } from "glob";
+import { parse } from "yaml";
+/** Contribution file schema version this build understands. */
+export const CONTRIBUTION_VERSION = 1;
+/**
+ * Node types a contribution may declare.
+ *
+ * `artifact` matters most here: a build knows what it generated and from what,
+ * and a generated output is never discoverable by indexing source.
+ */
+const NODE_TYPES = ["markdown", "openapi", "artifact"];
+/**
+ * Node fields a contribution may set on a document Weft already indexed.
+ *
+ * `id`, `type`, `anchors` and `project` are excluded on purpose: the first
+ * three are facts about the file Weft read, and the last is graph topology. A
+ * build tool contributes what it knows that Weft cannot see, and overriding
+ * extraction output is not that.
+ */
+const PATCHABLE_FIELDS = [
+    "title",
+    "description",
+    "theme",
+    "ogImage",
+    "hiddenFromNav",
+    "contentHash",
+    "lineCount",
+    // A build tool often knows a version Weft cannot see — one kept in a release
+    // file or a tag rather than in the document's own frontmatter.
+    "version",
+    "modified",
+];
+function fail(file, message) {
+    return new Error(`weft contribution: ${message} (in ${file})`);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateNode(raw, file, index) {
+    if (!isPlainObject(raw))
+        throw fail(file, `nodes[${index}] must be a mapping`);
+    if (typeof raw.id !== "string" || !raw.id) {
+        throw fail(file, `nodes[${index}] is missing "id"`);
+    }
+    if (!NODE_TYPES.includes(raw.type)) {
+        throw fail(file, `nodes[${index}] ("${raw.id}") must have type ${NODE_TYPES.map((t) => `"${t}"`).join(", ")}`);
+    }
+    if (raw.anchors !== undefined && !Array.isArray(raw.anchors)) {
+        throw fail(file, `nodes[${index}] ("${raw.id}") has a non-array "anchors"`);
+    }
+    return {
+        ...raw,
+        title: typeof raw.title === "string" ? raw.title : raw.id,
+        anchors: raw.anchors ?? [],
+    };
+}
+function validateEdge(raw, file, index) {
+    if (!isPlainObject(raw))
+        throw fail(file, `edges[${index}] must be a mapping`);
+    const endpoint = (key) => {
+        const value = raw[key];
+        if (!isPlainObject(value) || typeof value.node !== "string" || !value.node) {
+            throw fail(file, `edges[${index}] needs a "${key}.node" string`);
+        }
+        return value;
+    };
+    const from = endpoint("from");
+    const to = endpoint("to");
+    if (raw.type !== undefined && typeof raw.type !== "string") {
+        throw fail(file, `edges[${index}] has a non-string "type"`);
+    }
+    return { ...raw, from, to, type: raw.type ?? "references" };
+}
+function validatePatch(raw, file, nodeId) {
+    if (!isPlainObject(raw))
+        throw fail(file, `metadata["${nodeId}"] must be a mapping`);
+    for (const key of Object.keys(raw)) {
+        if (!PATCHABLE_FIELDS.includes(key)) {
+            throw fail(file, `metadata["${nodeId}"] cannot set "${key}" — patchable fields are ${PATCHABLE_FIELDS.join(", ")}`);
+        }
+    }
+    return raw;
+}
+/** Validate one parsed contribution file. */
+export function validateContribution(raw, file) {
+    if (!isPlainObject(raw))
+        throw fail(file, "file must contain a top-level mapping");
+    if (raw.version !== CONTRIBUTION_VERSION) {
+        throw fail(file, `"version" must be ${CONTRIBUTION_VERSION}, got ${JSON.stringify(raw.version)}`);
+    }
+    if (raw.tool !== undefined && typeof raw.tool !== "string") {
+        throw fail(file, '"tool" must be a string');
+    }
+    const nodes = raw.nodes ?? [];
+    const edges = raw.edges ?? [];
+    if (!Array.isArray(nodes))
+        throw fail(file, '"nodes" must be an array');
+    if (!Array.isArray(edges))
+        throw fail(file, '"edges" must be an array');
+    if (raw.metadata !== undefined && !isPlainObject(raw.metadata)) {
+        throw fail(file, '"metadata" must be a mapping of node id to fields');
+    }
+    const metadata = {};
+    for (const [nodeId, patch] of Object.entries(raw.metadata ?? {})) {
+        metadata[nodeId] = validatePatch(patch, file, nodeId);
+    }
+    return {
+        version: CONTRIBUTION_VERSION,
+        ...(typeof raw.tool === "string" ? { tool: raw.tool } : {}),
+        nodes: nodes.map((node, i) => validateNode(node, file, i)),
+        edges: edges.map((edge, i) => validateEdge(edge, file, i)),
+        metadata,
+    };
+}
+/**
+ * Read every configured contribution file.
+ *
+ * Paths are globs relative to the project root, resolved in sorted order so a
+ * merge is reproducible regardless of how the filesystem enumerates them.
+ */
+export async function loadContributions(config) {
+    if (!config.contributions?.length)
+        return [];
+    const files = await glob(config.contributions, {
+        cwd: config.rootDir,
+        nodir: true,
+        posix: true,
+    });
+    const loaded = [];
+    for (const file of files.sort()) {
+        const source = await readFile(resolve(config.rootDir, file), "utf8");
+        let raw;
+        try {
+            raw = parse(source);
+        }
+        catch (err) {
+            throw fail(file, `failed to parse: ${err.message}`);
+        }
+        loaded.push({ contribution: validateContribution(raw ?? {}, file), file });
+    }
+    return loaded;
+}
+/**
+ * Merge contributions into a graph.
+ *
+ * Order is defined and part of the contract: Weft indexes source first, then
+ * contributions apply in the order their files sorted. Indexing rendered output
+ * instead would lose sidecars and source structure, so the build contributes
+ * resolved facts afterwards rather than replacing the scan.
+ */
+export function applyContributions(graph, contributions) {
+    if (!contributions.length)
+        return graph;
+    const nodes = [...graph.nodes];
+    const edges = [...graph.edges];
+    const indexOf = new Map(nodes.map((node, i) => [node.id, i]));
+    for (const { contribution, file } of contributions) {
+        for (const node of contribution.nodes ?? []) {
+            const existing = indexOf.get(node.id);
+            if (existing === undefined) {
+                indexOf.set(node.id, nodes.length);
+                nodes.push(node);
+                continue;
+            }
+            // Weft already indexed this path. Usually that means build output is
+            // landing under docsDir, which is worth saying out loud.
+            console.warn(`weft contribution: "${node.id}" is already indexed from source; merging over it (in ${file}). Is build output inside docsDir?`);
+            nodes[existing] = { ...nodes[existing], ...node };
+        }
+        for (const [nodeId, patch] of Object.entries(contribution.metadata ?? {})) {
+            const existing = indexOf.get(nodeId);
+            if (existing === undefined) {
+                console.warn(`weft contribution: metadata for unknown node "${nodeId}" ignored (in ${file})`);
+                continue;
+            }
+            nodes[existing] = { ...nodes[existing], ...patch };
+        }
+        edges.push(...(contribution.edges ?? []));
+    }
+    return { nodes, edges };
+}
+//# sourceMappingURL=contributions.js.map

package/dist/contributions.js.map

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

package/dist/contributions.test.d.ts

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

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

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

package/dist/contributions.test.js

@@ -0,0 +1,202 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { applyContributions, loadContributions, validateContribution, } from "./contributions.js";
+const dirs = [];
+function tempRoot(files = {}) {
+    const dir = mkdtempSync(join(tmpdir(), "weft-contrib-"));
+    dirs.push(dir);
+    for (const [name, content] of Object.entries(files)) {
+        writeFileSync(join(dir, name), content);
+    }
+    return dir;
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        rmSync(dir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+});
+function config(root, contributions) {
+    return {
+        rootDir: resolve(root),
+        docsDir: "docs",
+        entryPoint: "docs/README.md",
+        ignore: [],
+        ...(contributions ? { contributions } : {}),
+    };
+}
+function node(id, extra = {}) {
+    return { id, type: "markdown", title: id, anchors: [], ...extra };
+}
+function loaded(contribution, file = "build/weft.json") {
+    return { contribution: validateContribution({ version: 1, ...contribution }, file), file };
+}
+describe("validateContribution", () => {
+    it("accepts a minimal contribution", () => {
+        expect(validateContribution({ version: 1 }, "c.json")).toEqual({
+            version: 1,
+            nodes: [],
+            edges: [],
+            metadata: {},
+        });
+    });
+    it("keeps the producing tool for traceability", () => {
+        expect(validateContribution({ version: 1, tool: "quarto 1.4" }, "c.json").tool).toBe("quarto 1.4");
+    });
+    it("rejects a wrong schema version, naming the file", () => {
+        expect(() => validateContribution({ version: 99 }, "c.json")).toThrow(/"version" must be 1.*in c\.json/s);
+    });
+    it("rejects a non-mapping top level", () => {
+        expect(() => validateContribution([], "c.json")).toThrow(/top-level mapping/);
+    });
+    it("defaults a contributed node's title and anchors", () => {
+        const { nodes } = validateContribution({ version: 1, nodes: [{ id: "gen.md", type: "markdown" }] }, "c.json");
+        expect(nodes?.[0]).toEqual({ id: "gen.md", type: "markdown", title: "gen.md", anchors: [] });
+    });
+    it("rejects a node without an id or with an unknown type", () => {
+        expect(() => validateContribution({ version: 1, nodes: [{ type: "markdown" }] }, "c")).toThrow(/nodes\[0\] is missing "id"/);
+        expect(() => validateContribution({ version: 1, nodes: [{ id: "a.md", type: "prose" }] }, "c")).toThrow(/must have type "markdown", "openapi", "artifact"/);
+    });
+    it("accepts a contributed artifact", () => {
+        // The build is the only party that knows what it generated, and a
+        // generated output is never discoverable by indexing source.
+        const { nodes } = validateContribution({ version: 1, nodes: [{ id: "out/guide.pdf", type: "artifact", hiddenFromNav: true }] }, "c.json");
+        expect(nodes?.[0]).toMatchObject({ id: "out/guide.pdf", type: "artifact" });
+    });
+    it("accepts a contributed derives-from edge carrying a source hash", () => {
+        const { edges } = validateContribution({
+            version: 1,
+            edges: [
+                {
+                    from: { node: "out/guide.pdf" },
+                    to: { node: "guide.md" },
+                    type: "derives-from",
+                    sourceHash: "abc123abc123abc1",
+                },
+            ],
+        }, "c.json");
+        expect(edges?.[0].sourceHash).toBe("abc123abc123abc1");
+    });
+    it("defaults a contributed edge's type", () => {
+        const { edges } = validateContribution({ version: 1, edges: [{ from: { node: "a.md" }, to: { node: "b.md" } }] }, "c.json");
+        expect(edges?.[0].type).toBe("references");
+    });
+    it("rejects an edge missing an endpoint node", () => {
+        expect(() => validateContribution({ version: 1, edges: [{ from: { node: "a.md" }, to: {} }] }, "c")).toThrow(/edges\[0\] needs a "to\.node" string/);
+    });
+    it("rejects a metadata patch touching extraction output or identity", () => {
+        for (const field of ["id", "type", "anchors", "project"]) {
+            expect(() => validateContribution({ version: 1, metadata: { "a.md": { [field]: "x" } } }, "c")).toThrow(new RegExp(`cannot set "${field}"`));
+        }
+    });
+    it("accepts the patchable fields", () => {
+        const { metadata } = validateContribution({
+            version: 1,
+            metadata: { "a.md": { title: "Resolved", contentHash: "abc", lineCount: 12 } },
+        }, "c.json");
+        expect(metadata?.["a.md"]).toEqual({ title: "Resolved", contentHash: "abc", lineCount: 12 });
+    });
+});
+describe("loadContributions", () => {
+    it("returns nothing when none are configured", async () => {
+        expect(await loadContributions(config(tempRoot()))).toEqual([]);
+    });
+    it("reads a configured JSON contribution", async () => {
+        const root = tempRoot({
+            "weft-build.json": JSON.stringify({ version: 1, tool: "renderer", nodes: [] }),
+        });
+        const [first] = await loadContributions(config(root, ["weft-build.json"]));
+        expect(first.contribution.tool).toBe("renderer");
+        expect(first.file).toBe("weft-build.json");
+    });
+    it("reads YAML as well, since the parser is shared with config", async () => {
+        const root = tempRoot({ "c.yaml": "version: 1\ntool: sphinx\n" });
+        const [first] = await loadContributions(config(root, ["c.yaml"]));
+        expect(first.contribution.tool).toBe("sphinx");
+    });
+    it("resolves globs in sorted order, so a merge is reproducible", async () => {
+        const root = tempRoot({
+            "b.json": JSON.stringify({ version: 1, tool: "b" }),
+            "a.json": JSON.stringify({ version: 1, tool: "a" }),
+        });
+        const files = await loadContributions(config(root, ["*.json"]));
+        expect(files.map((f) => f.contribution.tool)).toEqual(["a", "b"]);
+    });
+    it("ignores a glob that matches nothing", async () => {
+        expect(await loadContributions(config(tempRoot(), ["nope/*.json"]))).toEqual([]);
+    });
+    it("reports a malformed file by name", async () => {
+        const root = tempRoot({ "c.json": "{ this is not valid" });
+        await expect(loadContributions(config(root, ["c.json"]))).rejects.toThrow(/c\.json/);
+    });
+});
+describe("applyContributions", () => {
+    const base = () => ({
+        nodes: [node("README.md"), node("api.md")],
+        edges: [],
+    });
+    it("returns the graph untouched when there is nothing to apply", () => {
+        const graph = base();
+        expect(applyContributions(graph, [])).toBe(graph);
+    });
+    it("adds a node the build knows about", () => {
+        const result = applyContributions(base(), [
+            loaded({ nodes: [{ id: "generated.md", type: "markdown", title: "Generated" }] }),
+        ]);
+        expect(result.nodes.map((n) => n.id)).toEqual(["README.md", "api.md", "generated.md"]);
+    });
+    it("adds edges the build knows about", () => {
+        const result = applyContributions(base(), [
+            loaded({
+                edges: [{ from: { node: "api.md" }, to: { node: "README.md" }, type: "derives-from" }],
+            }),
+        ]);
+        expect(result.edges).toHaveLength(1);
+        expect(result.edges[0].type).toBe("derives-from");
+    });
+    it("patches metadata onto an indexed node", () => {
+        // What a renderer resolved that source could not express.
+        const result = applyContributions(base(), [
+            loaded({ metadata: { "api.md": { title: "API v2.41" } } }),
+        ]);
+        expect(result.nodes.find((n) => n.id === "api.md")?.title).toBe("API v2.41");
+        expect(result.nodes.find((n) => n.id === "README.md")?.title).toBe("README.md");
+    });
+    it("leaves fields the patch does not mention alone", () => {
+        const graph = { nodes: [node("a.md", { description: "kept", lineCount: 5 })], edges: [] };
+        const result = applyContributions(graph, [loaded({ metadata: { "a.md": { lineCount: 9 } } })]);
+        expect(result.nodes[0]).toMatchObject({ description: "kept", lineCount: 9 });
+    });
+    it("warns rather than fails on metadata for an unknown node", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const result = applyContributions(base(), [
+            loaded({ metadata: { "ghost.md": { title: "X" } } }),
+        ]);
+        expect(result.nodes).toHaveLength(2);
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining('unknown node "ghost.md"'));
+    });
+    it("warns when a contributed node was already indexed from source", () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        // The signature of build output landing under docsDir.
+        const result = applyContributions(base(), [
+            loaded({ nodes: [{ id: "api.md", type: "markdown", title: "Rendered API" }] }),
+        ]);
+        expect(result.nodes).toHaveLength(2);
+        expect(result.nodes.find((n) => n.id === "api.md")?.title).toBe("Rendered API");
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("already indexed from source"));
+    });
+    it("applies contributions in order, so a later one wins", () => {
+        const result = applyContributions(base(), [
+            loaded({ metadata: { "api.md": { title: "first" } } }, "a.json"),
+            loaded({ metadata: { "api.md": { title: "second" } } }, "b.json"),
+        ]);
+        expect(result.nodes.find((n) => n.id === "api.md")?.title).toBe("second");
+    });
+    it("does not mutate the graph it was given", () => {
+        const graph = base();
+        applyContributions(graph, [loaded({ nodes: [{ id: "new.md", type: "markdown" }] })]);
+        expect(graph.nodes).toHaveLength(2);
+    });
+});
+//# sourceMappingURL=contributions.test.js.map

package/dist/contributions.test.js.map

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

package/dist/fetch/auth.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Resolve a GitHub token: `GH_TOKEN`, then `GITHUB_TOKEN`, then `gh auth token`
+ * when the GitHub CLI is on PATH. No credential store of our own — anyone with
+ * a private repo to fetch already has one of these.
+ */
+export declare function resolveToken(env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/**
+ * Environment that hands git an Authorization header for github.com.
+ *
+ * Passed as `GIT_CONFIG_*` variables rather than `-c` arguments or a rewritten
+ * remote URL, so the token never lands in a process listing or in the cached
+ * clone's `.git/config`.
+ */
+export declare function gitAuthEnv(token: string | undefined): NodeJS.ProcessEnv;
+//# sourceMappingURL=auth.d.ts.map

package/dist/fetch/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/fetch/auth.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,UAAU,CAQvE"}