project-librarian 0.2.1 → 0.4.0

package/dist/wiki-files.js

@@ -37,6 +37,8 @@ exports.ignoredDirs = exports.standardWikiFiles = void 0;
 exports.walkMarkdownFiles = walkMarkdownFiles;
 exports.firstHeading = firstHeading;
 exports.compactSummary = compactSummary;
+exports.markdownBlockSnippet = markdownBlockSnippet;
+exports.extractMarkdownBlocks = extractMarkdownBlocks;
 exports.splitMarkdownRow = splitMarkdownRow;
 exports.parseMarkdownTableRows = parseMarkdownTableRows;
 exports.wikiMarkdownFiles = wikiMarkdownFiles;
@@ -46,10 +48,9 @@ exports.extractWikiLinks = extractWikiLinks;
 exports.wikiTitleForFile = wikiTitleForFile;
 exports.metadataSummary = metadataSummary;
 exports.stripMarkedSection = stripMarkedSection;
-exports.extractMarkedSection = extractMarkedSection;
-exports.withPreservedMarkedSections = withPreservedMarkedSections;
 exports.hasGlossaryNeedSignal = hasGlossaryNeedSignal;
 exports.hasGlossaryTable = hasGlossaryTable;
+exports.firstTldrBullet = firstTldrBullet;
 exports.canonicalBodyForLint = canonicalBodyForLint;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -75,24 +76,22 @@ exports.standardWikiFiles = new Set([
     "wiki/index.md",
     "wiki/inbox/project-candidates.md",
     "wiki/migration/inventory.md",
+    "wiki/migration/unit-map.md",
+    "wiki/migration/split-plan.md",
     "wiki/migration/coverage.md",
     "wiki/migration/plan.md",
     "wiki/migration/review.md",
     "wiki/migration/verification.md",
-    "wiki/canonical/project-brief.md",
+    "wiki/migration/bulk-review.md",
     "wiki/canonical/glossary.md",
-    "wiki/canonical/open-questions.md",
-    "wiki/canonical/assumptions.md",
-    "wiki/canonical/risks.md",
     "wiki/canonical/migration-inbox.md",
     "wiki/decisions/README.md",
     "wiki/decisions/log.md",
     "wiki/decisions/recent.md",
-    "wiki/decisions/decision-pack-template.md",
-    "wiki/decisions/full-adr-template.md",
     "wiki/decisions/migration-inbox.md",
     "wiki/meta/operating-model.md",
     "wiki/meta/decision-policy.md",
+    "wiki/meta/document-taxonomy.md",
     "wiki/meta/wiki-ops-v1-decisions.md",
     "wiki/sources/karpathy-llm-wiki.md",
     "wiki/sources/migration-inbox.md",
@@ -137,6 +136,109 @@ function compactSummary(text) {
         .trim()
         .slice(0, 180);
 }
+function slugForBlockId(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "block";
+}
+function isMarkdownHeading(line) {
+    return line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+}
+function isMarkdownTableSeparator(cells) {
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell.replace(/\s/g, "")));
+}
+function normalizeBlockText(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+function blockId(kind, line, text) {
+    return `${kind}:${line}:${slugForBlockId(text)}`;
+}
+function markdownBlockSnippet(block, maxLength = 180) {
+    const prefix = block.headingPath.length > 0 && block.kind !== "heading" ? `${block.headingPath.join(" > ")}: ` : "";
+    return `${prefix}${normalizeBlockText(block.text)}`.slice(0, maxLength);
+}
+function extractMarkdownBlocks(text) {
+    const body = (0, workspace_1.stripMetadataHeader)(text);
+    const lines = body.split(/\r?\n/);
+    const blocks = [];
+    const headingPath = [];
+    let paragraph = null;
+    let fence = null;
+    function addBlock(kind, line, blockText) {
+        const normalized = normalizeBlockText(blockText);
+        if (!normalized)
+            return;
+        blocks.push({
+            headingPath: [...headingPath],
+            id: blockId(kind, line, normalized),
+            kind,
+            line,
+            text: normalized,
+        });
+    }
+    function flushParagraph() {
+        if (!paragraph)
+            return;
+        addBlock("paragraph", paragraph.line, paragraph.lines.join(" "));
+        paragraph = null;
+    }
+    lines.forEach((line, index) => {
+        const lineNumber = index + 1;
+        const trimmed = line.trim();
+        const fenceMatch = trimmed.match(/^(```+|~~~+)\s*(.*)$/);
+        if (fence) {
+            const closingFence = fenceMatch?.[1] ?? "";
+            if (closingFence.startsWith(fence.fence.slice(0, 3)) && closingFence.length >= fence.fence.length) {
+                const sample = fence.lines.map((item) => item.trim()).filter(Boolean).slice(0, 3).join(" ");
+                addBlock("code_fence", fence.line, `code fence${fence.lang ? ` ${fence.lang}` : ""}: ${sample}`);
+                fence = null;
+            }
+            else {
+                fence.lines.push(line);
+            }
+            return;
+        }
+        if (fenceMatch) {
+            flushParagraph();
+            fence = { fence: fenceMatch[1] ?? "```", lang: (fenceMatch[2] ?? "").trim(), line: lineNumber, lines: [] };
+            return;
+        }
+        if (!trimmed) {
+            flushParagraph();
+            return;
+        }
+        const heading = isMarkdownHeading(line);
+        if (heading?.[1] && heading[2]) {
+            flushParagraph();
+            const level = heading[1].length;
+            const title = heading[2].trim();
+            headingPath.splice(level - 1);
+            headingPath[level - 1] = title;
+            addBlock("heading", lineNumber, title);
+            return;
+        }
+        if (/^\s{0,3}([-*+]|\d+\.)\s+\S/.test(line)) {
+            flushParagraph();
+            addBlock("list_item", lineNumber, trimmed);
+            return;
+        }
+        if (/^\|.+\|$/.test(trimmed)) {
+            flushParagraph();
+            const cells = splitMarkdownRow(line);
+            if (!isMarkdownTableSeparator(cells))
+                addBlock("table_row", lineNumber, cells.join(" | "));
+            return;
+        }
+        if (!paragraph)
+            paragraph = { line: lineNumber, lines: [] };
+        paragraph.lines.push(trimmed);
+    });
+    const unclosedFence = fence;
+    if (unclosedFence) {
+        const sample = unclosedFence.lines.map((item) => item.trim()).filter(Boolean).slice(0, 3).join(" ");
+        addBlock("code_fence", unclosedFence.line, `code fence${unclosedFence.lang ? ` ${unclosedFence.lang}` : ""}: ${sample}`);
+    }
+    flushParagraph();
+    return blocks;
+}
 function splitMarkdownRow(line) {
     const trimmed = line.trim();
     const row = trimmed.replace(/^\|/, "").replace(/\|$/, "");
@@ -264,25 +366,6 @@ function stripMarkedSection(text, startMarker, endMarker) {
         return text;
     return `${text.slice(0, start).trimEnd()}\n\n${text.slice(end + endMarker.length).trimStart()}`.trim() + "\n";
 }
-function extractMarkedSection(text, startMarker, endMarker) {
-    const start = text.indexOf(startMarker);
-    const end = text.indexOf(endMarker);
-    if (start < 0 || end <= start)
-        return "";
-    return text.slice(start, end + endMarker.length).trim();
-}
-function withPreservedMarkedSections(relativePath, base, markerPairs) {
-    if (!(0, workspace_1.exists)(relativePath))
-        return base;
-    const current = (0, workspace_1.read)(relativePath);
-    const preserved = markerPairs
-        .map(([startMarker, endMarker]) => extractMarkedSection(current, startMarker, endMarker))
-        .filter(Boolean)
-        .filter((section) => !base.includes(section));
-    if (preserved.length === 0)
-        return base;
-    return `${base.trimEnd()}\n\n${preserved.join("\n\n")}\n`;
-}
 function hasGlossaryNeedSignal(text) {
     return /(^|\n)##\s+(Glossary|Terms|Roles|Entities|Data Model|State Model|Permissions|Events|용어|역할|엔티티|상태 모델|권한|이벤트)(\s|$)|`[^`]+`\s*(term|role|state|permission|event|entity|API|DB|UI|용어|역할|상태|권한|이벤트|엔티티)/i.test(text);
 }
@@ -290,6 +373,16 @@ function hasGlossaryTable(text) {
     const body = (0, workspace_1.stripMetadataHeader)(text);
     return /\|\s*Term\s*\|\s*Definition\s*\|\s*Avoid\s*\|\s*Related Canonical Doc\s*\|\s*Status\s*\|/.test(body);
 }
+// First "## TL;DR" bullet for answer-shaped query envelopes: gives an agent the
+// page's one-line summary without opening the page. Pages without a TL;DR section
+// return "" and the envelope simply omits the line — quality-check separately
+// flags the missing TL;DR, so this is optional enrichment, not a fallback path.
+function firstTldrBullet(text) {
+    const body = (0, workspace_1.stripMetadataHeader)(text);
+    const match = body.match(/^##\s+TL;DR[^\n]*\n([\s\S]*?)(?=\n##\s|(?![\s\S]))/m);
+    const bullet = match?.[1]?.split(/\r?\n/).find((line) => /^\s*-\s+\S/.test(line));
+    return bullet ? bullet.replace(/^\s*-\s*/, "").trim().slice(0, 160) : "";
+}
 function canonicalBodyForLint() {
     return (0, workspace_1.walkFilesUnder)("wiki/canonical", (file) => /\.(md|mdx)$/i.test(file) && file !== "wiki/canonical/glossary.md")
         .map((file) => (0, workspace_1.stripMetadataHeader)((0, workspace_1.read)(file)))

package/dist/wiki-graph.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wikiAnswerTruncationNotice = exports.wikiAnswerCharCap = exports.wikiRouterExemptPages = exports.wikiRouterDepthBudget = exports.wikiRouterRoot = void 0;
+exports.finalizeWikiAnswer = finalizeWikiAnswer;
+exports.buildWikiGraph = buildWikiGraph;
+exports.wikiRouterDepths = wikiRouterDepths;
+exports.wikiQueryGraphEvidence = wikiQueryGraphEvidence;
+exports.wikiImpactAnswer = wikiImpactAnswer;
+const wiki_files_1 = require("./wiki-files");
+const workspace_1 = require("./workspace");
+// Router reachability budget. The benchmark fixture A1 assert guarantees
+// startup -> index -> answer page within two hops; real wikis add one hop for
+// generated scoped routers (startup -> index -> wiki/indexes/auto-*.md -> page),
+// so the real-wiki budget is three hops from wiki/startup.md.
+exports.wikiRouterRoot = "wiki/startup.md";
+exports.wikiRouterDepthBudget = 3;
+// startup is the BFS root; README is a human entry document that is deliberately
+// unrouted (the same exemption the orphan-page rule uses).
+exports.wikiRouterExemptPages = new Set([exports.wikiRouterRoot, "wiki/README.md"]);
+// Answer-shape discipline for wiki-side query/impact output: answer-first text,
+// hard char cap, explicit truncation notice (never silent). Mirrors the MCP
+// server constants (src/mcp-server.ts MAX_RESPONSE_CHARS / TRUNCATION_NOTICE);
+// kept separate so the MCP server module and its node:sqlite loading path stay
+// out of the bootstrap/diagnostics path.
+exports.wikiAnswerCharCap = 4000;
+exports.wikiAnswerTruncationNotice = "[truncated — refine the query]";
+function finalizeWikiAnswer(body) {
+    if (body.length <= exports.wikiAnswerCharCap)
+        return body;
+    const budget = exports.wikiAnswerCharCap - exports.wikiAnswerTruncationNotice.length - 1;
+    return `${body.slice(0, budget > 0 ? budget : 0).trimEnd()}\n${exports.wikiAnswerTruncationNotice}`;
+}
+// decision_ref is frontmatter, not a wiki link, so the link extractor never sees
+// it; normalize it here into a page edge. "none"/"-" are the documented empty
+// markers in generated metadata headers.
+function normalizedDecisionRef(file, value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === "none" || trimmed === "-")
+        return "";
+    return (0, wiki_files_1.normalizeWikiLinkTarget)(file, trimmed.replace(/^\[\[|\]\]$/g, ""));
+}
+function buildWikiGraph(pages) {
+    const files = new Set(pages.map((page) => page.file));
+    const links = [];
+    const incomingLinks = new Map();
+    const outgoingLinks = new Map();
+    const incomingDecisionRefs = new Map();
+    const outgoingDecisionRef = new Map();
+    for (const page of pages) {
+        for (const link of (0, wiki_files_1.extractWikiLinks)(page.file, page.text)) {
+            links.push(link);
+            outgoingLinks.set(page.file, [...(outgoingLinks.get(page.file) ?? []), link]);
+            incomingLinks.set(link.normalizedTarget, [...(incomingLinks.get(link.normalizedTarget) ?? []), link]);
+        }
+        const ref = normalizedDecisionRef(page.file, (0, workspace_1.metadataValue)(page.text, "decision_ref"));
+        if (ref && files.has(ref)) {
+            outgoingDecisionRef.set(page.file, ref);
+            incomingDecisionRefs.set(ref, [...(incomingDecisionRefs.get(ref) ?? []), page.file]);
+        }
+    }
+    return { files, links, incomingLinks, outgoingLinks, incomingDecisionRefs, outgoingDecisionRef };
+}
+// BFS depths over existing pages from wiki/startup.md (depth 0). Pages absent
+// from the result are unreachable through the router chain. Only links whose
+// target exists are traversed; broken links are the broken-link rule's job.
+function wikiRouterDepths(graph) {
+    const depths = new Map();
+    if (!graph.files.has(exports.wikiRouterRoot))
+        return depths;
+    depths.set(exports.wikiRouterRoot, 0);
+    const queue = [exports.wikiRouterRoot];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        const depth = depths.get(current) ?? 0;
+        for (const link of graph.outgoingLinks.get(current) ?? []) {
+            const target = link.normalizedTarget;
+            if (!graph.files.has(target) || depths.has(target))
+                continue;
+            depths.set(target, depth + 1);
+            queue.push(target);
+        }
+    }
+    return depths;
+}
+// Wiki impact: the --code-impact envelope shape applied to wiki maintenance.
+// Given a page or term, report which pages link to it (review candidates when it
+// changes), which pages cite it as decision_ref, what it depends on, and how the
+// router reaches it. Bounded by sampling plus the shared answer cap.
+const impactMatchCap = 5;
+const impactListCap = 12;
+function sampled(items, cap) {
+    if (items.length === 0)
+        return "none";
+    const shown = items.slice(0, cap).join(", ");
+    return items.length > cap ? `${shown}, …+${items.length - cap} more` : shown;
+}
+function uniqueSorted(values) {
+    return Array.from(new Set(values)).sort();
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function wikiQueryGraphEvidence(graph, file, depths = wikiRouterDepths(graph), listCap = 3) {
+    const outgoing = uniqueSorted((graph.outgoingLinks.get(file) ?? [])
+        .map((link) => link.normalizedTarget)
+        .filter((target) => target !== file && graph.files.has(target)));
+    const incoming = uniqueSorted((graph.incomingLinks.get(file) ?? [])
+        .map((link) => link.file)
+        .filter((source) => source !== file && graph.files.has(source)));
+    const incomingRefs = uniqueSorted((graph.incomingDecisionRefs.get(file) ?? [])
+        .filter((source) => source !== file && graph.files.has(source)));
+    const outgoingRef = graph.outgoingDecisionRef.get(file);
+    const depth = depths.get(file);
+    const parts = [
+        depth === undefined ? `router unreachable from ${exports.wikiRouterRoot}` : `router depth ${depth}`,
+    ];
+    if (outgoing.length > 0)
+        parts.push(`links-out ${outgoing.length}: ${sampled(outgoing, listCap)}`);
+    if (outgoingRef && outgoingRef !== file && graph.files.has(outgoingRef))
+        parts.push(`decision_ref-> ${outgoingRef}`);
+    if (incoming.length > 0)
+        parts.push(`linked-by ${incoming.length}: ${sampled(incoming, listCap)}`);
+    if (incomingRefs.length > 0)
+        parts.push(`decision_ref-by ${incomingRefs.length}: ${sampled(incomingRefs, listCap)}`);
+    return parts.join("; ");
+}
+function wikiImpactAnswer(pages, term) {
+    const graph = buildWikiGraph(pages);
+    const depths = wikiRouterDepths(graph);
+    const textByFile = new Map(pages.map((page) => [page.file, page.text]));
+    const lowered = term.toLowerCase();
+    const exactTarget = (0, wiki_files_1.normalizeWikiLinkTarget)("wiki/index.md", term.replace(/^\[\[|\]\]$/g, ""));
+    const matches = pages
+        .map((page) => ({ file: page.file, title: (0, wiki_files_1.wikiTitleForFile)(page.file, page.text) }))
+        .filter((page) => page.file === exactTarget || page.file.toLowerCase().includes(lowered) || page.title.toLowerCase().includes(lowered))
+        .sort((a, b) => Number(b.file === exactTarget) - Number(a.file === exactTarget) || a.file.localeCompare(b.file));
+    if (matches.length === 0)
+        return `Wiki impact "${term}": no matching wiki pages.`;
+    const shown = matches.slice(0, impactMatchCap);
+    // Headline counts are unions across the shown matches, not sums: a page that
+    // links two matched targets is one review candidate, not two.
+    const incomingUnion = new Set(shown.flatMap((match) => (graph.incomingLinks.get(match.file) ?? []).map((link) => link.file)));
+    const refUnion = new Set(shown.flatMap((match) => graph.incomingDecisionRefs.get(match.file) ?? []));
+    const lines = [
+        `Wiki impact "${term}": ${plural(matches.length, "matching page")}${matches.length > impactMatchCap ? ` (top ${impactMatchCap} shown)` : ""}; review the ${plural(incomingUnion.size, "linking page")} and ${plural(refUnion.size, "decision_ref citation")} below when ${matches.length === 1 ? "this page changes" : "these pages change"}.`,
+    ];
+    for (const match of shown) {
+        const text = textByFile.get(match.file) ?? "";
+        const incoming = uniqueSorted((graph.incomingLinks.get(match.file) ?? []).map((link) => link.file));
+        const refs = uniqueSorted(graph.incomingDecisionRefs.get(match.file) ?? []);
+        const outgoing = uniqueSorted((graph.outgoingLinks.get(match.file) ?? []).map((link) => link.normalizedTarget));
+        const depth = depths.get(match.file);
+        const trigger = (0, workspace_1.metadataValue)(text, "review_trigger");
+        lines.push("");
+        lines.push(`${match.file} — ${match.title}`);
+        if (trigger)
+            lines.push(`  review_trigger: ${trigger}`);
+        lines.push(`  incoming links (${incoming.length}): ${sampled(incoming, impactListCap)}`);
+        lines.push(`  decision_ref from (${refs.length}): ${sampled(refs, impactListCap)}`);
+        lines.push(`  outgoing links (${outgoing.length}): ${sampled(outgoing, impactListCap)}`);
+        lines.push(depth === undefined
+            ? `  router: unreachable from ${exports.wikiRouterRoot}`
+            : `  router: reachable at depth ${depth} (budget ${exports.wikiRouterDepthBudget})`);
+    }
+    return finalizeWikiAnswer(lines.join("\n"));
+}