pi-jev-wiki 0.2.0

package/src/wiki/toc.ts

@@ -0,0 +1,198 @@
+/**
+ * The wiki table of contents (`index.md`) and the append-only log (`log.md`).
+ *
+ * Index format (Obsidian-friendly tables, machine-parseable):
+ *
+ *   ## architecture
+ *
+ *   | Page | Type | Tags | Summary | Updated |
+ *   |------|------|------|---------|---------|
+ *   | [Auth module](architecture/module-auth.md) | architecture/module | auth core | Owns token validation | 2026-09-19 |
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { todayISO, writeTextAtomic, type WikiLayout } from "./layout.ts";
+import { withWikiLock } from "./lock.ts";
+
+export interface TocEntry {
+	path: string;
+	title: string;
+	type: string;
+	tags: string[];
+	summary: string;
+	updated: string;
+}
+
+const ROW_RE = /^\|\s*\[(.*?)\]\((.*?)\)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*(.*?)\s*\|\s*$/;
+
+export function parseIndex(text: string): TocEntry[] {
+	const entries: TocEntry[] = [];
+	for (const line of text.split(/\r?\n/)) {
+		const match = line.match(ROW_RE);
+		if (!match) continue;
+		const [, title, path, type, tags, summary, updated] = match;
+		if (path.includes("](")) continue;
+		entries.push({
+			path: path.trim(),
+			title: title.trim(),
+			type: type.trim(),
+			tags: tags.trim() ? tags.trim().split(/\s+/) : [],
+			summary: summary.trim(),
+			updated: updated.trim(),
+		});
+	}
+	return entries;
+}
+
+function escapeCell(value: string): string {
+	return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ").trim();
+}
+
+export function topicOf(path: string): string {
+	const parts = path.split("/");
+	return parts.length > 1 ? parts[0] : "general";
+}
+
+/** Wiki-generated navigation files that are not knowledge pages. */
+export function isWikiMetaFile(relPath: string): boolean {
+	const rel = relPath.split("\\").join("/");
+	return rel === "index.md" || rel === "log.md" || rel === "toc.md" || rel.startsWith("toc/");
+}
+
+export function topicSlug(topic: string): string {
+	return topic.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "general";
+}
+
+function groupEntries(entries: TocEntry[]): Map<string, TocEntry[]> {
+	const groups = new Map<string, TocEntry[]>();
+	for (const entry of entries) {
+		if (entry.path === "index.md" || entry.path === "log.md") continue;
+		const topic = topicOf(entry.path);
+		const list = groups.get(topic) ?? [];
+		list.push(entry);
+		groups.set(topic, list);
+	}
+	return groups;
+}
+
+function renderTable(entries: TocEntry[]): string[] {
+	const lines = ["| Page | Type | Tags | Summary | Updated |", "|------|------|------|---------|---------|"];
+	for (const entry of entries) {
+		lines.push(
+			`| [${escapeCell(entry.title)}](${entry.path}) | ${escapeCell(entry.type)} | ${escapeCell(entry.tags.join(" "))} | ${escapeCell(entry.summary)} | ${escapeCell(entry.updated)} |`,
+		);
+	}
+	return lines;
+}
+
+export function renderIndex(entries: TocEntry[]): string {
+	const groups = groupEntries(entries);
+
+	const lines: string[] = [
+		"# Wiki Index",
+		"",
+		"> Complete machine-readable catalog, generated by jev-wiki; edit pages, not this file.",
+		"",
+	];
+	for (const topic of [...groups.keys()].sort()) {
+		const list = groups.get(topic)!.sort((a, b) => a.title.localeCompare(b.title));
+		lines.push(`## ${topic}`, "", ...renderTable(list), "");
+	}
+	return `${lines.join("\n").replace(/\s+$/, "")}\n`;
+}
+
+/** Compact agent-facing table of contents: topics, counts, and links to per-topic tables. */
+export function renderCompactToc(entries: TocEntry[]): string {
+	const groups = groupEntries(entries);
+	const lines: string[] = [
+		"# Wiki TOC",
+		"",
+		`> ${entries.length} pages across ${groups.size} topics. Per-topic tables: \`toc/<topic>.md\`. Full machine index: \`index.md\`.`,
+		"",
+		"| Topic | Pages | Table |",
+		"|-------|-------|-------|",
+	];
+	for (const topic of [...groups.keys()].sort()) {
+		lines.push(`| ${topic} | ${groups.get(topic)!.length} | [toc/${topicSlug(topic)}.md](toc/${topicSlug(topic)}.md) |`);
+	}
+	const recent = [...entries].filter((entry) => entry.path !== "index.md" && entry.path !== "log.md").sort((a, b) => b.updated.localeCompare(a.updated)).slice(0, 5);
+	if (recent.length > 0) {
+		lines.push("", "## Recently updated", ...recent.map((entry) => `- [${entry.title}](${entry.path}) — ${entry.summary} (${entry.updated})`));
+	}
+	return `${lines.join("\n").replace(/\s+$/, "")}\n`;
+}
+
+/** Full table for a single topic. */
+export function renderTopicToc(entries: TocEntry[], topic: string): string {
+	const list = entries.filter((entry) => topicOf(entry.path) === topic).sort((a, b) => a.title.localeCompare(b.title));
+	return [`# ${topic}`, "", ...renderTable(list)].join("\n") + "\n";
+}
+
+export function upsertEntries(existing: TocEntry[], updates: TocEntry[]): TocEntry[] {
+	const byPath = new Map(existing.map((entry) => [entry.path, entry]));
+	for (const update of updates) byPath.set(update.path, update);
+	return [...byPath.values()];
+}
+
+export async function readIndex(layout: WikiLayout): Promise<TocEntry[]> {
+	const path = join(layout.wikiDir, "index.md");
+	if (!existsSync(path)) return [];
+	return parseIndex(await readFile(path, "utf8"));
+}
+
+export async function writeIndex(layout: WikiLayout, entries: TocEntry[]): Promise<void> {
+	await writeTextAtomic(join(layout.wikiDir, "index.md"), renderIndex(entries));
+	await writeTextAtomic(join(layout.wikiDir, "toc.md"), renderCompactToc(entries));
+	for (const topic of groupEntries(entries).keys()) {
+		await writeTextAtomic(join(layout.wikiDir, "toc", `${topicSlug(topic)}.md`), renderTopicToc(entries, topic));
+	}
+}
+
+/** Atomic read-modify-write of the index under the wiki lock. */
+export async function updateIndex(
+	layout: WikiLayout,
+	mutator: (entries: TocEntry[]) => TocEntry[] | Promise<TocEntry[]>,
+): Promise<TocEntry[]> {
+	return withWikiLock(layout, async () => {
+		const entries = await readIndex(layout);
+		const next = await mutator(entries);
+		await writeIndex(layout, next);
+		return next;
+	});
+}
+
+export function entryFromPage(relPath: string, data: Record<string, unknown>): TocEntry {
+	return {
+		path: relPath.split("\\").join("/"),
+		title: String(data.title ?? relPath),
+		type: String(data.type ?? "concept"),
+		tags: Array.isArray(data.tags) ? data.tags.map(String) : [],
+		summary: String(data.summary ?? "(no summary)"),
+		updated: String(data.updated ?? todayISO()),
+	};
+}
+
+export async function appendLog(layout: WikiLayout, op: string, title: string, details: string[] = []): Promise<void> {
+	const path = join(layout.wikiDir, "log.md");
+	const header = `## [${todayISO()}] ${op} | ${title}`;
+	const block = [header, ...details.map((line) => `- ${line}`), ""].join("\n");
+	await withWikiLock(layout, async () => {
+		if (existsSync(path)) {
+			const existing = await readFile(path, "utf8");
+			await writeTextAtomic(path, `${existing.replace(/\s+$/, "")}\n\n${block}\n`);
+		} else {
+			await writeTextAtomic(path, `# Wiki Log\n\n${block}\n`);
+		}
+	});
+}
+
+export async function readRecentLog(layout: WikiLayout, limit = 5): Promise<string[]> {
+	const path = join(layout.wikiDir, "log.md");
+	if (!existsSync(path)) return [];
+	const text = await readFile(path, "utf8");
+	return text
+		.split(/\r?\n/)
+		.filter((line) => line.startsWith("## ["))
+		.slice(-limit);
+}