sdtk-wiki-kit 0.1.1 → 0.1.3

package/src/lib/wiki-compile.js

@@ -106,13 +106,150 @@ function mdList(values) {
   return items.length > 0 ? items.map((item) => `- ${item}`).join("\n") : "- None recorded.";
 }
 
+function mdLinkedList(values) {
+  const items = asArray(values).filter(Boolean);
+  if (items.length === 0) return "- None recorded.";
+  return items.map((item) => {
+    const text = String(item);
+    if (/^https?:\/\//i.test(text)) return `- [${text}](${text})`;
+    return `- ${text}`;
+  }).join("\n");
+}
+
+function quoteBlock(value) {
+  const text = String(value || "").replace(/\r?\n/g, " ").trim();
+  return text ? `> ${text}` : "> No extracted snippet recorded in the local source.";
+}
+
+function topicLabelList(entity) {
+  const topics = [...new Set(asArray(entity.topics).filter(Boolean).map(String))];
+  return topics.length > 0 ? topics.map((topic) => `- ${topic}`).join("\n") : "- No topic labels extracted from local sources.";
+}
+
+function relatedRepoList(entity) {
+  const repos = asArray(entity.related_repos);
+  if (repos.length === 0) return "- No related repositories inferred from local topic overlap.";
+  return repos.map((repo) => {
+    const label = repo.name || repo.entity_id || "related repo";
+    const suffix = asArray(repo.shared_topics).length > 0 ? ` (shared topics: ${asArray(repo.shared_topics).join(", ")})` : "";
+    return repo.github_url ? `- [${label}](${repo.github_url})${suffix}` : `- ${label}${suffix}`;
+  }).join("\n");
+}
+
+function relativePersonalBrainLink(targetPagePath) {
+  const text = toPosix(targetPagePath || "");
+  const marker = ".sdtk/wiki/personal-brain/";
+  const idx = text.indexOf(marker);
+  return idx >= 0 ? text.slice(idx + marker.length) : text;
+}
+
+function conceptAxisList(concept) {
+  const axes = asArray(concept.key_axes);
+  if (axes.length === 0) return "- No key axes were inferred from local evidence.";
+  return axes.map((axis) => `- ${axis.name}: ${axis.evidence_count || 1} local evidence reference(s).`).join("\n");
+}
+
+function conceptImplementationList(concept) {
+  const entities = asArray(concept.related_entity_details);
+  if (entities.length === 0) return "- No implementation examples were extracted from local sources.";
+  return entities.slice(0, 10).map((entity) => {
+    const label = entity.repo_owner && entity.repo_name ? `${entity.repo_owner}/${entity.repo_name}` : (entity.name || "tool candidate");
+    const link = entity.target_page_path ? relativePersonalBrainLink(entity.target_page_path) : "";
+    const target = link ? `[${label}](../${link})` : label;
+    const url = entity.github_url ? `; ${entity.github_url}` : "";
+    return `- ${target}: ${entity.summary || `Local candidate in ${entity.category || "uncategorized"}`}${url}`;
+  }).join("\n");
+}
+
+function conceptPatternList(concept) {
+  const patterns = asArray(concept.patterns);
+  if (patterns.length === 0) return "- No repeated pattern was inferred from local evidence.";
+  return patterns.map((pattern) => `- ${pattern.pattern}: ${pattern.evidence}`).join("\n");
+}
+
+function conceptRelatedPagesList(concept) {
+  const pages = asArray(concept.related_entity_details)
+    .map((entity) => entity.target_page_path)
+    .filter(Boolean)
+    .map((target) => `../${relativePersonalBrainLink(target)}`);
+  return mdList([...new Set(pages)].slice(0, 12));
+}
+
+function confidenceSummaryList(summary) {
+  if (!summary || typeof summary !== "object") return "- No source confidence summary recorded.";
+  const rows = Object.entries(summary).filter(([, count]) => Number(count) > 0);
+  return rows.length > 0 ? rows.map(([tier, count]) => `- ${tier}: ${count}`).join("\n") : "- No source confidence summary recorded.";
+}
+
+function comparisonMatrix(comparison) {
+  const rows = asArray(comparison.matrix_rows);
+  if (rows.length === 0) return "| Candidate | Category | Local evidence | Strengths | Caveats | Recommendation |\n|---|---|---:|---|---|---|\n| None recorded | - | 0 | - | - | - |";
+  const table = [
+    "| Candidate | Category | Local evidence | Strengths | Caveats | Recommendation |",
+    "|---|---|---:|---|---|---|",
+  ];
+  for (const row of rows) {
+    const candidate = row.github_url ? `[${row.name || row.entity_id}](${row.github_url})` : (row.name || row.entity_id || "candidate");
+    table.push(`| ${candidate} | ${row.category || "uncategorized"} | ${row.source_ref_count || 0} | ${asArray(row.strengths).slice(0, 3).join("<br>") || "-"} | ${asArray(row.caveats).slice(0, 3).join("<br>") || "-"} | ${row.local_recommendation || "review"} |`);
+  }
+  return table.join("\n");
+}
+
+function candidateToolList(records) {
+  const rows = asArray(records);
+  if (rows.length === 0) return "- No candidate tools recorded.";
+  return rows.slice(0, 12).map((row) => {
+    const label = row.github_url ? `[${row.name || row.entity_id}](${row.github_url})` : (row.name || row.entity_id || "candidate");
+    return `- ${label}: ${row.local_recommendation || "review"}; confidence ${row.source_confidence || row.confidence_tier || "unknown"}.`;
+  }).join("\n");
+}
+
+function yamlScalar(value) {
+  return `"${String(value ?? "").replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r?\n/g, " ").trim()}"`;
+}
+
+function yamlInlineList(values) {
+  const items = [...new Set(asArray(values).filter(Boolean).map(String))];
+  return `[${items.map(yamlScalar).join(", ")}]`;
+}
+
+function frontmatterBlock(fields) {
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fields)) {
+    if (Array.isArray(value)) {
+      lines.push(`${key}: ${yamlInlineList(value)}`);
+    } else {
+      lines.push(`${key}: ${yamlScalar(value)}`);
+    }
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+
+function withPersonalBrainFrontmatter(fields, body) {
+  return `${frontmatterBlock({
+    schema_version: "1",
+    product: "SDTK-WIKI",
+    managed_by: "sdtk-wiki",
+    status: "generated",
+    aliases: [],
+    tags: [],
+    related_pages: [],
+    source_refs: [],
+    confidence: "medium",
+    review_status: "needs_review",
+    ...fields,
+  })}${String(body || "").replace(/^\s+/, "")}`;
+}
+
 function recordTitle(record, fallback) {
   return String(record.title || record.name || record.topic || record.entity_id || record.concept_id || record.source_id || fallback || "Generated page");
 }
 
-function renderSourcePage(source) {
-  return [
-    `# ${recordTitle(source, "Source")}`,
+function renderSourcePage(source, generatedAt) {
+  const title = recordTitle(source, "Source");
+  const body = [
+    `# ${title}`,
     "",
     "## Summary",
     "",
@@ -136,93 +273,316 @@ function renderSourcePage(source) {
     mdList(provenanceRefsFor(source)),
     "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: source.source_id,
+    title,
+    type: "source",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: source.source_logical_path ? [source.source_logical_path] : [],
+    tags: ["source", source.source_type || "local"],
+    source_refs: sourceRefsFor(source),
+    confidence: source.source_quality && source.source_quality.low_confidence_extraction ? "low" : "medium",
+    review_status: source.source_quality && source.source_quality.low_confidence_extraction ? "needs_review" : "ready_for_review",
+  }, body);
 }
 
-function renderToolEntityPage(entity) {
-  return [
-    `# ${recordTitle(entity, "Tool entity")}`,
+function renderToolEntityPage(entity, generatedAt) {
+  const title = recordTitle(entity, "Tool entity");
+  const evidenceRecords = asArray(entity.evidence_records);
+  const firstSnippet = asArray(entity.evidence_snippets)[0] || (evidenceRecords[0] && evidenceRecords[0].snippet);
+  const discoverySources = [
+    ...asArray(entity.source_links),
+    ...asArray(entity.discovery_sources),
+    ...evidenceRecords.map((record) => record.source_link || record.source_logical_path).filter(Boolean),
+  ];
+  const sourceCount = sourceRefsFor(entity).length;
+  const whyItMatters = entity.summary
+    ? `Local evidence presents ${title} as relevant to ${entity.category || "the extracted tool landscape"}. ${entity.summary}`
+    : `Local evidence links ${title} to ${entity.category || "the extracted tool landscape"} with ${sourceCount} source reference(s).`;
+  const whenToUse = asArray(entity.topics).length > 0
+    ? `Review when exploring ${asArray(entity.topics).slice(0, 4).join(", ")} options from the local source set.`
+    : "Review when evaluating whether this repository should become a maintained tool note.";
+  const overlap = asArray(entity.related_repos).length > 0
+    ? "Related repositories were inferred from shared local topic labels or category evidence. Treat this as a review cue, not external verification."
+    : "No overlap was inferred from local topic labels in this slice.";
+  const body = [
+    `# ${title}`,
     "",
     "## Summary",
     "",
     entity.summary || `Generated tool entity page for ${entity.name || entity.entity_id}.`,
     "",
-    "## Repository",
+    "## Key Facts",
     "",
-    `- owner: ${entity.repo_owner || "(missing)"}`,
-    `- repo: ${entity.repo_name || "(missing)"}`,
-    `- url: ${entity.github_url || "(missing)"}`,
-    `- category: ${entity.category || "(unknown)"}`,
+    `- Canonical URL: ${entity.github_url || "(missing)"}`,
+    `- Owner: ${entity.repo_owner || "(missing)"}`,
+    `- Repo name: ${entity.repo_name || "(missing)"}`,
+    `- Category: ${entity.category || "(unknown)"}`,
+    `- Confidence: ${entity.confidence_tier || entity.confidence || "medium"}`,
+    `- Local source refs: ${sourceCount}`,
     "",
-    "## Evidence",
+    "## Discovery Source",
+    "",
+    mdLinkedList([...new Set(discoverySources.filter(Boolean).map(String))]),
+    "",
+    "## Extracted Snippet",
+    "",
+    quoteBlock(firstSnippet),
+    "",
+    "## Topic Labels",
+    "",
+    topicLabelList(entity),
+    "",
+    "## Why It Matters",
+    "",
+    whyItMatters,
+    "",
+    "## When To Use",
+    "",
+    whenToUse,
+    "",
+    "## Related Repos",
+    "",
+    relatedRepoList(entity),
+    "",
+    "## Overlaps / Differences",
+    "",
+    overlap,
+    "",
+    "## Open Questions",
+    "",
+    "- Verify license, maintenance status, and project maturity before relying on this tool.",
+    "- Confirm whether the local topic labels match the repository's actual current scope.",
+    "- Decide whether this should remain a tool entity or be reclassified after review.",
+    "",
+    "## Local Evidence Records",
     "",
-    mdList(sourceRefsFor(entity)),
+    evidenceRecords.length > 0
+      ? evidenceRecords.map((record) => [
+        `- source_id: ${record.source_id || "(missing)"}`,
+        `  - source: ${record.source_link || record.source_logical_path || "(missing)"}`,
+        `  - topics: ${asArray(record.topics).join(", ") || "(none)"}`,
+        `  - confidence: ${record.confidence_tier || record.confidence || "(unknown)"}`,
+      ].join("\n")).join("\n")
+      : "- No structured evidence records recorded.",
     "",
     "## Provenance",
     "",
     mdList(provenanceRefsFor(entity)),
     "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: entity.entity_id,
+    title,
+    type: "tool_entity",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [entity.repo_name, entity.github_url].filter(Boolean),
+    tags: ["tool", entity.category, ...asArray(entity.topics)].filter(Boolean),
+    source_refs: sourceRefsFor(entity),
+    confidence: entity.confidence_tier || entity.confidence || "medium",
+    review_status: "ready_for_review",
+  }, body);
 }
 
-function renderConceptPage(concept) {
-  return [
-    `# ${recordTitle(concept, "Concept")}`,
+function renderConceptPage(concept, generatedAt) {
+  const title = recordTitle(concept, "Concept");
+  const relatedCount = asArray(concept.related_entity_details).length || asArray(concept.related_entities).length;
+  const sourceCount = sourceRefsFor(concept).length;
+  const summary = concept.definition
+    || `Local sources contain ${relatedCount} tool candidate(s) and ${sourceCount} source reference(s) related to ${title}.`;
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    summary,
+    "",
+    "## Key Axes",
+    "",
+    conceptAxisList(concept),
+    "",
+    "## Implementations / Examples",
     "",
-    "## Definition",
+    conceptImplementationList(concept),
     "",
-    concept.definition || `Generated concept page for ${concept.name || concept.concept_id}.`,
+    "## Patterns",
+    "",
+    conceptPatternList(concept),
+    "",
+    "## Recommendations / Caveats",
+    "",
+    "- Treat this concept page as local-evidence synthesis, not external verification.",
+    "- Prioritize examples with multiple source references or stronger extraction confidence.",
+    "- Review source-quality warnings before making architecture or tool adoption decisions.",
+    "",
+    "## Open Questions",
+    "",
+    "- Which extracted implementation is mature enough for real project adoption?",
+    "- Are the local topic labels accurate after human review?",
+    "- Should this concept be split, merged, or promoted after comparison/synthesis enrichment?",
     "",
     "## Aliases",
     "",
     mdList(concept.aliases),
     "",
-    "## Related Entities",
+    "## Related Pages",
     "",
-    mdList(concept.related_entities),
+    conceptRelatedPagesList(concept),
     "",
-    "## Sources",
+    "## Source References",
     "",
     mdList(sourceRefsFor(concept)),
     "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(concept)),
+    "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: concept.concept_id,
+    title,
+    type: "concept",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: concept.aliases,
+    tags: ["concept"],
+    related_pages: asArray(concept.related_entity_details).map((entity) => entity.target_page_path ? `../${relativePersonalBrainLink(entity.target_page_path)}` : null).filter(Boolean).slice(0, 12),
+    source_refs: sourceRefsFor(concept),
+    confidence: concept.confidence_tier || concept.confidence || "medium",
+    review_status: "ready_for_review",
+  }, body);
 }
 
-function renderComparisonPage(comparison) {
-  return [
-    `# ${recordTitle(comparison, "Comparison")}`,
+function renderComparisonPage(comparison, generatedAt) {
+  const title = recordTitle(comparison, "Comparison");
+  const body = [
+    `# ${title}`,
+    "",
+    "## Summary",
+    "",
+    comparison.summary || `Local comparison for ${comparison.topic || comparison.comparison_id}.`,
+    "",
+    "## Decision Axes",
+    "",
+    conceptAxisList({ key_axes: comparison.decision_axes }),
+    "",
+    "## Comparison Matrix",
+    "",
+    comparisonMatrix(comparison),
+    "",
+    "## Candidate Tools / Repos",
+    "",
+    candidateToolList(comparison.matrix_rows),
+    "",
+    "## Recommendations",
     "",
-    "## Compared Entities",
+    mdList(comparison.recommendations),
     "",
-    mdList(comparison.compared_entities),
+    "## Caveats",
     "",
-    "## Criteria",
+    mdList(comparison.caveats),
     "",
-    mdList(comparison.criteria),
+    "## Source Confidence",
     "",
-    "## Sources",
+    confidenceSummaryList(comparison.source_confidence_summary),
+    "",
+    "## Open Questions",
+    "",
+    "- Which candidate should be verified first with external source checks?",
+    "- Which criteria matter most for the target SDTK use case?",
+    "- Are any candidates duplicates, abandoned, or misclassified in the local source set?",
+    "",
+    "## Source References",
     "",
     mdList(sourceRefsFor(comparison)),
     "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(comparison)),
+    "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: comparison.comparison_id,
+    title,
+    type: "comparison",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [comparison.topic].filter(Boolean),
+    tags: ["comparison"],
+    related_pages: asArray(comparison.compared_entity_details).map((entity) => entity.target_page_path ? `../${relativePersonalBrainLink(entity.target_page_path)}` : null).filter(Boolean).slice(0, 12),
+    source_refs: sourceRefsFor(comparison),
+    confidence: comparison.confidence_tier || comparison.confidence || "medium",
+    review_status: "needs_review",
+  }, body);
 }
 
-function renderSynthesisPage(synthesis) {
-  return [
-    `# ${recordTitle(synthesis, "Synthesis")}`,
+function renderSynthesisPage(synthesis, generatedAt) {
+  const title = recordTitle(synthesis, "Synthesis");
+  const body = [
+    `# ${title}`,
     "",
     "## Summary",
     "",
     synthesis.summary || `Generated synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
     "",
-    "## Recommendations",
+    "## Landscape Snapshot",
+    "",
+    candidateToolList(synthesis.candidate_tools),
+    "",
+    "## Key Patterns",
+    "",
+    conceptPatternList({ patterns: synthesis.patterns }),
+    "",
+    "## Decision Axes",
+    "",
+    conceptAxisList({ key_axes: synthesis.landscape_axes }),
+    "",
+    "## Recommended Review Path",
     "",
     mdList(synthesis.recommendations),
     "",
-    "## Sources",
+    "## Caveats",
+    "",
+    mdList(synthesis.caveats),
+    "",
+    "## Source Confidence",
+    "",
+    confidenceSummaryList(synthesis.source_confidence_summary),
+    "",
+    "## Related Comparisons",
+    "",
+    synthesis.related_comparison_path ? mdList([`../${relativePersonalBrainLink(synthesis.related_comparison_path)}`]) : "- None recorded.",
+    "",
+    "## Open Questions",
+    "",
+    "- Which comparison criteria should become product acceptance gates?",
+    "- Which local candidates need external verification before adoption?",
+    "- Does this cluster need a dedicated deeper synthesis pass?",
+    "",
+    "## Source References",
     "",
     mdList(sourceRefsFor(synthesis)),
     "",
+    "## Provenance",
+    "",
+    mdList(provenanceRefsFor(synthesis)),
+    "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: synthesis.synthesis_id,
+    title,
+    type: "synthesis",
+    created_at: generatedAt,
+    updated_at: generatedAt,
+    aliases: [synthesis.topic].filter(Boolean),
+    tags: ["synthesis"],
+    related_pages: synthesis.related_comparison_path ? [`../${relativePersonalBrainLink(synthesis.related_comparison_path)}`] : [],
+    source_refs: sourceRefsFor(synthesis),
+    confidence: synthesis.confidence_tier || synthesis.confidence || "medium",
+    review_status: "needs_review",
+  }, body);
 }
 
 function renderRootPage(name, payload) {
@@ -235,8 +595,9 @@ function renderRootPage(name, payload) {
     graph: "Personal Brain Graph",
     log: "Personal Brain Generation Log",
   };
-  return [
-    `# ${titles[name] || "Personal Brain"}`,
+  const title = titles[name] || "Personal Brain";
+  const body = [
+    `# ${title}`,
     "",
     "## Generation Context",
     "",
@@ -257,10 +618,22 @@ function renderRootPage(name, payload) {
     "- maintenance/",
     "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: `personal_brain_${name}`,
+    title,
+    type: "root",
+    created_at: payload.generated_at || "",
+    updated_at: payload.generated_at || "",
+    aliases: [name],
+    tags: ["personal-brain", name],
+    source_refs: asArray(payload.sources).map((source) => source.source_id).filter(Boolean).slice(0, 50),
+    confidence: "medium",
+    review_status: "needs_review",
+  }, body);
 }
 
 function renderMaintenancePage(payload) {
-  return [
+  const body = [
     "# Extraction Quality Review",
     "",
     "## Source Quality Findings",
@@ -272,6 +645,18 @@ function renderMaintenancePage(payload) {
     mdList(asArray(payload.unsupported_items).map((item) => `${item.item_id || "unsupported"}: ${item.reason || item.raw_observation_summary || "review required"}`)),
     "",
   ].join("\n");
+  return withPersonalBrainFrontmatter({
+    id: "maintenance_extraction_quality_review",
+    title: "Extraction Quality Review",
+    type: "maintenance",
+    created_at: payload.generated_at || "",
+    updated_at: payload.generated_at || "",
+    aliases: ["source quality", "extraction quality"],
+    tags: ["maintenance", "quality"],
+    source_refs: asArray(payload.sources).map((source) => source.source_id).filter(Boolean).slice(0, 50),
+    confidence: asArray(payload.unsupported_items).length > 0 ? "low" : "medium",
+    review_status: "needs_review",
+  }, body);
 }
 
 function pushCreatePageOperation(operations, raw) {
@@ -308,7 +693,7 @@ function operationsFromSemanticExtraction(payload) {
       source_id: source.source_id,
       source_hash: source.source_hash,
       target_page_path: source.target_page_path,
-      content: renderSourcePage(source),
+      content: renderSourcePage(source, payload.generated_at),
       proposed_content_summary: `Create personal-brain source page for ${source.source_logical_path || source.source_relative_path || source.source_id}.`,
       source_refs: sourceRefsFor(source),
       provenance_refs: provenanceRefsFor(source),
@@ -325,7 +710,7 @@ function operationsFromSemanticExtraction(payload) {
       source_id: sourceId,
       source_hash: sourceHashFor(sourceById, sourceId),
       target_page_path: entity.target_page_path,
-      content: renderToolEntityPage(entity),
+      content: renderToolEntityPage(entity, payload.generated_at),
       proposed_content_summary: `Create tool entity page for ${entity.name || entity.entity_id}.`,
       source_refs: sourceRefsFor(entity),
       provenance_refs: provenanceRefsFor(entity),
@@ -361,7 +746,7 @@ function operationsFromSemanticExtraction(payload) {
       source_id: sourceId,
       source_hash: sourceHashFor(sourceById, sourceId),
       target_page_path: concept.target_page_path,
-      content: renderConceptPage(concept),
+      content: renderConceptPage(concept, payload.generated_at),
       proposed_content_summary: `Create concept page for ${concept.name || concept.concept_id}.`,
       source_refs: sourceRefsFor(concept),
       provenance_refs: provenanceRefsFor(concept),
@@ -378,7 +763,7 @@ function operationsFromSemanticExtraction(payload) {
       source_id: sourceId,
       source_hash: sourceHashFor(sourceById, sourceId),
       target_page_path: comparison.target_page_path,
-      content: renderComparisonPage(comparison),
+      content: renderComparisonPage(comparison, payload.generated_at),
       proposed_content_summary: `Create comparison page for ${comparison.topic || comparison.comparison_id}.`,
       source_refs: sourceRefsFor(comparison),
       provenance_refs: provenanceRefsFor(comparison),
@@ -395,7 +780,7 @@ function operationsFromSemanticExtraction(payload) {
       source_id: sourceId,
       source_hash: sourceHashFor(sourceById, sourceId),
       target_page_path: synthesis.target_page_path,
-      content: renderSynthesisPage(synthesis),
+      content: renderSynthesisPage(synthesis, payload.generated_at),
       proposed_content_summary: `Create synthesis page for ${synthesis.topic || synthesis.synthesis_id}.`,
       source_refs: sourceRefsFor(synthesis),
       provenance_refs: provenanceRefsFor(synthesis),