@sourcepress/knowledge 0.1.0

package/src/__tests__/knowledge-engine.test.ts

@@ -0,0 +1,177 @@
+import type { BudgetTracker, ResolvedProvider } from "@sourcepress/ai";
+import type { ContentFile } from "@sourcepress/core";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { KnowledgeEngine } from "../knowledge-engine.js";
+import { InMemoryKnowledgeStore } from "../knowledge-store.js";
+
+vi.mock("@sourcepress/ai", async () => {
+	const actual = await vi.importActual("@sourcepress/ai");
+	return { ...actual, classify: vi.fn(), extract: vi.fn() };
+});
+
+import { classify, extract } from "@sourcepress/ai";
+
+const mockProvider: ResolvedProvider = {
+	provider: "anthropic",
+	model: "claude-sonnet-4-5-20250514",
+};
+
+function makeMockBudget(): BudgetTracker {
+	return {
+		record: vi.fn(),
+		getStatus: vi.fn().mockReturnValue({
+			spent_today_usd: 0,
+			limit_usd: 5,
+			warn_at_usd: 3,
+			remaining_usd: 5,
+			is_over_limit: false,
+			is_warned: false,
+			reset_at: new Date().toISOString(),
+		}),
+		canSpend: vi.fn().mockReturnValue(true),
+		getHistory: vi.fn().mockReturnValue([]),
+		resetDaily: vi.fn(),
+	} as unknown as BudgetTracker;
+}
+
+const mockUsage = {
+	input_tokens: 500,
+	output_tokens: 100,
+	estimated_cost_usd: 0.01,
+	function_name: "test",
+	timestamp: new Date().toISOString(),
+};
+
+describe("KnowledgeEngine", () => {
+	let engine: KnowledgeEngine;
+	let store: InMemoryKnowledgeStore;
+	let budget: BudgetTracker;
+
+	beforeEach(() => {
+		store = new InMemoryKnowledgeStore();
+		budget = makeMockBudget();
+		engine = new KnowledgeEngine(store, mockProvider, budget);
+		vi.clearAllMocks();
+	});
+
+	describe("ingest", () => {
+		it("classifies, extracts, and stores a knowledge file", async () => {
+			vi.mocked(classify).mockResolvedValueOnce({
+				quality: "structured",
+				quality_score: 8,
+				type: "project-notes",
+				reasoning: "Well structured",
+				usage: mockUsage,
+			});
+			vi.mocked(extract).mockResolvedValueOnce({
+				entities: [{ type: "client", name: "Acme Corp", aliases: ["Acme"], confidence: 0.95 }],
+				relations: [
+					{
+						from_entity: "Acme Corp",
+						to_entity: "Next.js",
+						relation_type: "uses",
+						confidence: 0.9,
+						evidence: "Acme uses Next.js",
+					},
+				],
+				usage: mockUsage,
+			});
+
+			const result = await engine.ingest(
+				"knowledge/clients/acme.md",
+				"Meeting with Acme Corp about their Next.js migration.",
+				"manual",
+			);
+			expect(result.path).toBe("knowledge/clients/acme.md");
+			expect(result.quality).toBe("structured");
+			expect(result.quality_score).toBe(8);
+			expect(result.entities).toHaveLength(1);
+
+			const stored = await store.retrieve("knowledge/clients/acme.md");
+			expect(stored).not.toBeNull();
+			// biome-ignore lint/style/noNonNullAssertion: asserted not null on line above
+			expect(stored!.quality).toBe("structured");
+		});
+	});
+
+	describe("buildGraph", () => {
+		it("builds graph from all stored knowledge files", async () => {
+			await store.store({
+				path: "knowledge/a.md",
+				type: "notes",
+				quality: "structured",
+				quality_score: 8,
+				entities: [{ type: "client", name: "Acme Corp" }],
+				ingested_at: new Date().toISOString(),
+				source: "manual",
+				body: "Acme meeting notes",
+			});
+
+			vi.mocked(extract).mockResolvedValueOnce({
+				entities: [{ type: "client", name: "Acme Corp", aliases: ["Acme"], confidence: 0.95 }],
+				relations: [],
+				usage: mockUsage,
+			});
+
+			const graph = await engine.buildGraph();
+			expect(graph.entities.size).toBeGreaterThanOrEqual(1);
+			expect(graph.built_at).toBeTruthy();
+		});
+	});
+
+	describe("query", () => {
+		it("queries the graph for an entity", async () => {
+			await store.store({
+				path: "knowledge/a.md",
+				type: "notes",
+				quality: "structured",
+				quality_score: 8,
+				entities: [{ type: "client", name: "Acme Corp" }],
+				ingested_at: new Date().toISOString(),
+				source: "manual",
+				body: "Acme notes",
+			});
+
+			vi.mocked(extract).mockResolvedValueOnce({
+				entities: [{ type: "client", name: "Acme Corp", aliases: ["Acme"], confidence: 0.95 }],
+				relations: [],
+				usage: mockUsage,
+			});
+
+			await engine.buildGraph();
+			const result = engine.query("Acme Corp");
+			expect(result).not.toBeNull();
+			// biome-ignore lint/style/noNonNullAssertion: asserted not null on line above
+			expect(result!.entity.name).toBe("Acme Corp");
+		});
+
+		it("returns null before graph is built", () => {
+			expect(engine.query("Anything")).toBeNull();
+		});
+	});
+
+	describe("findGaps", () => {
+		it("delegates gap detection to graph ops", async () => {
+			await store.store({
+				path: "knowledge/a.md",
+				type: "notes",
+				quality: "structured",
+				quality_score: 8,
+				entities: [{ type: "client", name: "Acme Corp" }],
+				ingested_at: new Date().toISOString(),
+				source: "manual",
+				body: "Acme notes",
+			});
+
+			vi.mocked(extract).mockResolvedValueOnce({
+				entities: [{ type: "client", name: "Acme Corp", aliases: [], confidence: 0.95 }],
+				relations: [],
+				usage: mockUsage,
+			});
+
+			await engine.buildGraph();
+			const gaps = engine.findGaps([]);
+			expect(gaps.length).toBeGreaterThanOrEqual(1);
+		});
+	});
+});

package/src/__tests__/knowledge-store.test.ts

@@ -0,0 +1,111 @@
+import type { KnowledgeFile } from "@sourcepress/core";
+import { beforeEach, describe, expect, it } from "vitest";
+import { InMemoryKnowledgeStore } from "../knowledge-store.js";
+
+function makeKnowledgeFile(overrides: Partial<KnowledgeFile> = {}): KnowledgeFile {
+	return {
+		path: "knowledge/clients/acme.md",
+		type: "project-notes",
+		quality: "structured",
+		quality_score: 8,
+		entities: [
+			{ type: "client", name: "Acme Corp" },
+			{ type: "technology", name: "Next.js" },
+		],
+		ingested_at: "2026-04-04T10:00:00Z",
+		source: "manual",
+		body: "Meeting with Acme Corp about Next.js migration.",
+		...overrides,
+	};
+}
+
+describe("InMemoryKnowledgeStore", () => {
+	let store: InMemoryKnowledgeStore;
+
+	beforeEach(() => {
+		store = new InMemoryKnowledgeStore();
+	});
+
+	describe("store and retrieve", () => {
+		it("stores and retrieves a knowledge file", async () => {
+			const file = makeKnowledgeFile();
+			await store.store(file);
+			const retrieved = await store.retrieve(file.path);
+			expect(retrieved).toEqual(file);
+		});
+
+		it("returns null for non-existent file", async () => {
+			const retrieved = await store.retrieve("nonexistent.md");
+			expect(retrieved).toBeNull();
+		});
+
+		it("overwrites existing file at same path", async () => {
+			const file = makeKnowledgeFile();
+			await store.store(file);
+			const updated = makeKnowledgeFile({ quality_score: 9 });
+			await store.store(updated);
+			const retrieved = await store.retrieve(file.path);
+			expect(retrieved?.quality_score).toBe(9);
+		});
+	});
+
+	describe("list", () => {
+		it("lists all stored files", async () => {
+			await store.store(makeKnowledgeFile({ path: "knowledge/a.md" }));
+			await store.store(makeKnowledgeFile({ path: "knowledge/b.md" }));
+			const files = await store.list();
+			expect(files).toHaveLength(2);
+		});
+
+		it("filters by type", async () => {
+			await store.store(makeKnowledgeFile({ path: "a.md", type: "project-notes" }));
+			await store.store(makeKnowledgeFile({ path: "b.md", type: "transcript" }));
+			const files = await store.list({ type: "transcript" });
+			expect(files).toHaveLength(1);
+			expect(files[0].type).toBe("transcript");
+		});
+
+		it("filters by quality", async () => {
+			await store.store(makeKnowledgeFile({ path: "a.md", quality: "structured" }));
+			await store.store(makeKnowledgeFile({ path: "b.md", quality: "draft" }));
+			const files = await store.list({ quality: "draft" });
+			expect(files).toHaveLength(1);
+			expect(files[0].quality).toBe("draft");
+		});
+
+		it("filters by source", async () => {
+			await store.store(makeKnowledgeFile({ path: "a.md", source: "manual" }));
+			await store.store(makeKnowledgeFile({ path: "b.md", source: "url" }));
+			const files = await store.list({ source: "url" });
+			expect(files).toHaveLength(1);
+			expect(files[0].source).toBe("url");
+		});
+	});
+
+	describe("delete", () => {
+		it("deletes an existing file", async () => {
+			await store.store(makeKnowledgeFile());
+			const deleted = await store.delete("knowledge/clients/acme.md");
+			expect(deleted).toBe(true);
+			const retrieved = await store.retrieve("knowledge/clients/acme.md");
+			expect(retrieved).toBeNull();
+		});
+
+		it("returns false for non-existent file", async () => {
+			const deleted = await store.delete("nonexistent.md");
+			expect(deleted).toBe(false);
+		});
+	});
+
+	describe("count", () => {
+		it("returns 0 for empty store", async () => {
+			expect(await store.count()).toBe(0);
+		});
+
+		it("returns correct count", async () => {
+			await store.store(makeKnowledgeFile({ path: "a.md" }));
+			await store.store(makeKnowledgeFile({ path: "b.md" }));
+			expect(await store.count()).toBe(2);
+		});
+	});
+});

package/src/__tests__/scraper.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import { Scraper } from "../ingestion/scraper.js";
+
+const SAMPLE_HTML = `
+<!DOCTYPE html>
+<html>
+<head><title>Test Article</title></head>
+<body>
+  <header><nav>Skip me</nav></header>
+  <article>
+    <h1>Test Article Title</h1>
+    <p>This is the first paragraph with <strong>bold text</strong> and a
+    <a href="https://example.com">link</a>.</p>
+    <h2>Section Two</h2>
+    <p>Another paragraph with <em>italic</em> content. It has enough text to
+    be considered readable content by the Readability algorithm, which typically
+    requires a minimum amount of textual content to determine that an element
+    contains the main article body rather than boilerplate navigation.</p>
+    <ul>
+      <li>Item one</li>
+      <li>Item two</li>
+    </ul>
+    <p>Final paragraph to ensure sufficient content length for the readability
+    parser to properly identify the main content area of this test page.</p>
+  </article>
+  <footer>Footer stuff</footer>
+</body>
+</html>`;
+
+function mockFetcher(html: string, status = 200): typeof globalThis.fetch {
+	return vi.fn().mockResolvedValue({
+		ok: status >= 200 && status < 300,
+		status,
+		statusText: status === 200 ? "OK" : "Not Found",
+		text: () => Promise.resolve(html),
+	}) as unknown as typeof globalThis.fetch;
+}
+
+describe("Scraper", () => {
+	it("scrapes a URL and returns readable content", async () => {
+		const fetcher = mockFetcher(SAMPLE_HTML);
+		const scraper = new Scraper(fetcher);
+		const result = await scraper.scrape("https://example.com/article");
+
+		expect(fetcher).toHaveBeenCalledWith("https://example.com/article", undefined);
+		expect(result.url).toBe("https://example.com/article");
+		expect(result.title).toContain("Test Article");
+		expect(result.content).toContain("first paragraph");
+		expect(result.markdown).toContain("**bold text**");
+		expect(result.length).toBeGreaterThan(0);
+		expect(result.scraped_at).toBeTruthy();
+	});
+
+	it("throws on HTTP error", async () => {
+		const fetcher = mockFetcher("", 404);
+		const scraper = new Scraper(fetcher);
+		await expect(scraper.scrape("https://example.com/missing")).rejects.toThrow("404");
+	});
+
+	it("throws when no readable content found", async () => {
+		const fetcher = mockFetcher("<html><body><nav>Just navigation</nav></body></html>");
+		const scraper = new Scraper(fetcher);
+		await expect(scraper.scrape("https://example.com/empty")).rejects.toThrow(
+			"No readable content",
+		);
+	});
+
+	it("extracts markdown from HTML directly", () => {
+		const scraper = new Scraper(mockFetcher(""));
+		const result = scraper.extractFromHtml("https://example.com", SAMPLE_HTML);
+		expect(result.markdown).toContain("[link](https://example.com)");
+		expect(result.markdown).toContain("- Item one");
+	});
+});

package/src/__tests__/sitemap-parser.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from "vitest";
+import { SitemapParser } from "../ingestion/sitemap-parser.js";
+
+const SAMPLE_SITEMAP = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url><loc>https://example.com/</loc></url>
+  <url><loc>https://example.com/blog/post-1</loc></url>
+  <url><loc>https://example.com/blog/post-2</loc></url>
+  <url><loc>https://example.com/services/web</loc></url>
+  <url><loc>https://example.com/services/mobile</loc></url>
+  <url><loc>https://example.com/services/cloud</loc></url>
+  <url><loc>https://example.com/cases/acme</loc></url>
+  <url><loc>https://example.com/about</loc></url>
+</urlset>`;
+
+function mockFetcher(xml: string, status = 200) {
+	return vi.fn().mockResolvedValue({
+		ok: status >= 200 && status < 300,
+		status,
+		statusText: "OK",
+		text: () => Promise.resolve(xml),
+	}) as unknown as typeof globalThis.fetch;
+}
+
+describe("SitemapParser", () => {
+	it("parses a sitemap and groups URLs by section", async () => {
+		const parser = new SitemapParser(mockFetcher(SAMPLE_SITEMAP));
+		const result = await parser.parse("https://example.com/sitemap.xml");
+
+		expect(result.total_urls).toBe(8);
+		expect(result.sections.length).toBeGreaterThanOrEqual(3);
+
+		const services = result.sections.find((s) => s.pattern === "/services/*");
+		expect(services).toBeDefined();
+		expect(services?.count).toBe(3);
+
+		const blog = result.sections.find((s) => s.pattern === "/blog/*");
+		expect(blog).toBeDefined();
+		expect(blog?.count).toBe(2);
+	});
+
+	it("throws on HTTP error", async () => {
+		const parser = new SitemapParser(mockFetcher("", 404));
+		await expect(parser.parse("https://example.com/sitemap.xml")).rejects.toThrow("404");
+	});
+
+	it("throws when no URLs found", async () => {
+		const parser = new SitemapParser(mockFetcher("<urlset></urlset>"));
+		await expect(parser.parse("https://example.com/sitemap.xml")).rejects.toThrow("No URLs found");
+	});
+
+	it("filters URLs by include patterns", async () => {
+		const parser = new SitemapParser(mockFetcher(SAMPLE_SITEMAP));
+		const result = await parser.parse("https://example.com/sitemap.xml");
+		const filtered = parser.filterUrls(result, {
+			sitemap_url: "https://example.com/sitemap.xml",
+			include: ["/services/*"],
+		});
+		expect(filtered).toHaveLength(3);
+		expect(filtered.every((u) => u.includes("/services/"))).toBe(true);
+	});
+
+	it("filters URLs by exclude patterns", async () => {
+		const parser = new SitemapParser(mockFetcher(SAMPLE_SITEMAP));
+		const result = await parser.parse("https://example.com/sitemap.xml");
+		const filtered = parser.filterUrls(result, {
+			sitemap_url: "https://example.com/sitemap.xml",
+			exclude: ["/blog/*"],
+		});
+		expect(filtered.some((u) => u.includes("/blog/"))).toBe(false);
+		expect(filtered.length).toBe(6); // 8 total - 2 blog
+	});
+
+	it("combines include and exclude", async () => {
+		const parser = new SitemapParser(mockFetcher(SAMPLE_SITEMAP));
+		const result = await parser.parse("https://example.com/sitemap.xml");
+		const filtered = parser.filterUrls(result, {
+			sitemap_url: "https://example.com/sitemap.xml",
+			include: ["/services/*", "/blog/*"],
+			exclude: ["/blog/*"],
+		});
+		expect(filtered).toHaveLength(3);
+		expect(filtered.every((u) => u.includes("/services/"))).toBe(true);
+	});
+});

package/src/graph-builder.ts

@@ -0,0 +1,109 @@
+import type { EntityCluster, ExtractedEntity, ExtractedRelation, KnowledgeGraph } from "./types.js";
+
+export interface GraphBuilderOptions {
+	minConfidence?: number;
+}
+
+export class GraphBuilder {
+	private entities: Map<string, ExtractedEntity> = new Map();
+	private relations: ExtractedRelation[] = [];
+	private sourceFiles: Set<string> = new Set();
+	private minConfidence: number;
+
+	constructor(options: GraphBuilderOptions = {}) {
+		this.minConfidence = options.minConfidence ?? 0;
+	}
+
+	addEntities(entities: ExtractedEntity[]): void {
+		for (const entity of entities) {
+			this.sourceFiles.add(entity.source_file);
+			const existing = this.entities.get(entity.name);
+			if (existing) {
+				const mergedAliases = Array.from(
+					new Set([...(existing.aliases || []), ...(entity.aliases || [])]),
+				);
+				if (entity.confidence > existing.confidence) {
+					this.entities.set(entity.name, { ...entity, aliases: mergedAliases });
+				} else {
+					existing.aliases = mergedAliases;
+				}
+			} else {
+				this.entities.set(entity.name, { ...entity });
+			}
+		}
+	}
+
+	getEntities(): Map<string, ExtractedEntity> {
+		return this.entities;
+	}
+
+	addRelations(relations: ExtractedRelation[]): void {
+		for (const relation of relations) {
+			this.sourceFiles.add(relation.source_file);
+			this.relations.push({ ...relation });
+		}
+	}
+
+	build(): KnowledgeGraph {
+		const filteredRelations = this.relations.filter((r) => r.confidence >= this.minConfidence);
+		const clusters = this.buildClusters(filteredRelations);
+		return {
+			entities: new Map(this.entities),
+			relations: filteredRelations,
+			clusters,
+			built_at: new Date().toISOString(),
+			file_count: this.sourceFiles.size,
+		};
+	}
+
+	private buildClusters(relations: ExtractedRelation[]): EntityCluster[] {
+		const parent: Map<string, string> = new Map();
+		const find = (x: string): string => {
+			if (!parent.has(x)) parent.set(x, x);
+			// biome-ignore lint/style/noNonNullAssertion: key presence guaranteed by parent.has() check above
+			if (parent.get(x) !== x) parent.set(x, find(parent.get(x)!));
+			// biome-ignore lint/style/noNonNullAssertion: key presence guaranteed by parent.has() check above
+			return parent.get(x)!;
+		};
+		const union = (a: string, b: string): void => {
+			const rootA = find(a);
+			const rootB = find(b);
+			if (rootA !== rootB) parent.set(rootB, rootA);
+		};
+
+		for (const name of this.entities.keys()) find(name);
+		for (const relation of relations) {
+			if (this.entities.has(relation.from_entity) && this.entities.has(relation.to_entity)) {
+				union(relation.from_entity, relation.to_entity);
+			}
+		}
+
+		const groups: Map<string, string[]> = new Map();
+		for (const name of this.entities.keys()) {
+			const root = find(name);
+			if (!groups.has(root)) groups.set(root, []);
+			// biome-ignore lint/style/noNonNullAssertion: key presence guaranteed by groups.has() check above
+			groups.get(root)!.push(name);
+		}
+
+		const clusters: EntityCluster[] = [];
+		let clusterId = 0;
+		for (const [, members] of groups) {
+			if (members.length < 2) continue;
+			const clusterRelations = relations.filter(
+				(r) => members.includes(r.from_entity) && members.includes(r.to_entity),
+			);
+			const coherence =
+				clusterRelations.length > 0
+					? clusterRelations.reduce((sum, r) => sum + r.confidence, 0) / clusterRelations.length
+					: 0;
+			clusters.push({
+				id: `cluster-${clusterId++}`,
+				name: members[0],
+				entities: members,
+				coherence_score: Math.round(coherence * 100) / 100,
+			});
+		}
+		return clusters;
+	}
+}

package/src/graph-ops.ts

@@ -0,0 +1,129 @@
+import type { ContentFile } from "@sourcepress/core";
+import type {
+	ExtractedEntity,
+	GraphQueryResult,
+	KnowledgeGap,
+	KnowledgeGraph,
+	StaleContent,
+} from "./types.js";
+
+export interface GraphStats {
+	entity_count: number;
+	relation_count: number;
+	cluster_count: number;
+	file_count: number;
+	built_at: string;
+}
+
+export class GraphOps {
+	private graph: KnowledgeGraph;
+	private aliasIndex: Map<string, string>;
+
+	constructor(graph: KnowledgeGraph) {
+		this.graph = graph;
+		this.aliasIndex = this.buildAliasIndex();
+	}
+
+	private buildAliasIndex(): Map<string, string> {
+		const index = new Map<string, string>();
+		for (const [name, entity] of this.graph.entities) {
+			index.set(name.toLowerCase(), name);
+			for (const alias of entity.aliases || []) {
+				index.set(alias.toLowerCase(), name);
+			}
+		}
+		return index;
+	}
+
+	private resolveEntityName(nameOrAlias: string): string | null {
+		if (this.graph.entities.has(nameOrAlias)) return nameOrAlias;
+		return this.aliasIndex.get(nameOrAlias.toLowerCase()) ?? null;
+	}
+
+	query(nameOrAlias: string): GraphQueryResult | null {
+		const resolvedName = this.resolveEntityName(nameOrAlias);
+		if (!resolvedName) return null;
+		const entity = this.graph.entities.get(resolvedName);
+		if (!entity) return null;
+
+		const relations = this.graph.relations.filter(
+			(r) => r.from_entity === resolvedName || r.to_entity === resolvedName,
+		);
+		const relatedNames = new Set<string>();
+		for (const r of relations) {
+			if (r.from_entity === resolvedName) relatedNames.add(r.to_entity);
+			if (r.to_entity === resolvedName) relatedNames.add(r.from_entity);
+		}
+		const related_entities: ExtractedEntity[] = [];
+		for (const name of relatedNames) {
+			const e = this.graph.entities.get(name);
+			if (e) related_entities.push(e);
+		}
+		const files = new Set<string>();
+		files.add(entity.source_file);
+		for (const r of relations) files.add(r.source_file);
+
+		return { entity, relations, related_entities, files: Array.from(files) };
+	}
+
+	findGaps(contentFiles: ContentFile[]): KnowledgeGap[] {
+		const gaps: KnowledgeGap[] = [];
+		for (const [name, entity] of this.graph.entities) {
+			const contentCount = contentFiles.filter((c) => {
+				const bodyLower = c.body.toLowerCase();
+				const titleLower = String(c.frontmatter.title ?? "").toLowerCase();
+				return bodyLower.includes(name.toLowerCase()) || titleLower.includes(name.toLowerCase());
+			}).length;
+			if (contentCount === 0) {
+				gaps.push({
+					entity_name: name,
+					entity_type: entity.type,
+					knowledge_file_count: 1,
+					content_file_count: 0,
+					reason: `Entity "${name}" (${entity.type}) exists in knowledge but has no corresponding content`,
+				});
+			}
+		}
+		return gaps;
+	}
+
+	findStale(
+		contentFiles: ContentFile[],
+		knowledgeTimestamps: Record<string, string>,
+	): StaleContent[] {
+		const stale: StaleContent[] = [];
+		for (const content of contentFiles) {
+			if (!content.provenance?.generated_at || !content.provenance?.source_files) continue;
+			const generatedAt = content.provenance.generated_at;
+			const staleSources: string[] = [];
+			let newestSourceChange = "";
+			for (const sourcePath of content.provenance.source_files) {
+				const sourceTimestamp = knowledgeTimestamps[sourcePath];
+				if (sourceTimestamp && sourceTimestamp > generatedAt) {
+					staleSources.push(sourcePath);
+					if (sourceTimestamp > newestSourceChange) newestSourceChange = sourceTimestamp;
+				}
+			}
+			if (staleSources.length > 0) {
+				stale.push({
+					content_path: content.path,
+					generated_at: generatedAt,
+					newest_source_change: newestSourceChange,
+					stale_sources: staleSources,
+					reason: `Content generated at ${generatedAt} but source(s) updated at ${newestSourceChange}`,
+				});
+			}
+		}
+		return stale;
+	}
+
+	getStats(): GraphStats {
+		return {
+			entity_count: this.graph.entities.size,
+			relation_count: this.graph.relations.length,
+			cluster_count: this.graph.clusters.length,
+			file_count: this.graph.file_count,
+			built_at: this.graph.built_at,
+		};
+	}
+}