onto-mcp 0.3.0

package/dist/core-runtime/learning/health-report.js

@@ -0,0 +1,165 @@
+/**
+ * Learning pool health dashboard — pure aggregator and renderer.
+ *
+ * Design authority: .onto/processes/learn/health.md (rule owner)
+ *
+ * Responsibility:
+ *   - Aggregate axis/purpose/type distribution, file size indicators,
+ *     marker counts, and referenced domain list from ParsedLearningItem[]
+ *   - Render a deterministic markdown dashboard
+ *
+ * Scope: pure. No I/O. No mutation.
+ *
+ * Consumers:
+ *   - future learn/govern surfaces
+ */
+// ---------------------------------------------------------------------------
+// Aggregation
+// ---------------------------------------------------------------------------
+export function buildHealthReport(items, target) {
+    const axis = { methodology_only: 0, domain_only: 0, dual: 0 };
+    const purpose = {
+        guardrail: 0,
+        foundation: 0,
+        convention: 0,
+        insight: 0,
+        unassigned: 0,
+    };
+    const type = { fact: 0, judgment: 0 };
+    const lineMax = new Map();
+    const domainCounts = new Map();
+    let event_markers = 0;
+    let tag_incomplete = 0;
+    let consolidated = 0;
+    let retention_confirmed = 0;
+    for (const item of items) {
+        const hasMethodology = item.applicability_tags.includes("methodology");
+        const hasDomain = item.applicability_tags.some((t) => t.startsWith("domain/"));
+        if (hasMethodology && hasDomain)
+            axis.dual += 1;
+        else if (hasMethodology)
+            axis.methodology_only += 1;
+        else if (hasDomain)
+            axis.domain_only += 1;
+        if (item.role === null)
+            purpose.unassigned += 1;
+        else
+            purpose[item.role] += 1;
+        type[item.type] += 1;
+        event_markers += item.event_markers.length;
+        if (item.retention_confirmed_at !== null)
+            retention_confirmed += 1;
+        if (item.raw_line.includes("tag-incomplete"))
+            tag_incomplete += 1;
+        if (item.raw_line.includes("consolidated into"))
+            consolidated += 1;
+        const prior = lineMax.get(item.source_path) ?? 0;
+        if (item.line_number > prior)
+            lineMax.set(item.source_path, item.line_number);
+        for (const tag of item.applicability_tags) {
+            if (tag.startsWith("domain/")) {
+                const d = tag.slice("domain/".length);
+                domainCounts.set(d, (domainCounts.get(d) ?? 0) + 1);
+            }
+        }
+    }
+    const file_count = lineMax.size;
+    let largest_file = null;
+    for (const [source_path, lines] of lineMax) {
+        if (largest_file === null || lines > largest_file.lines) {
+            largest_file = { agent: extractAgentFromPath(source_path), lines, source_path };
+        }
+    }
+    const domains = [...domainCounts.entries()]
+        .map(([domain, count]) => ({ domain, count }))
+        .sort((a, b) => b.count !== a.count ? b.count - a.count : a.domain.localeCompare(b.domain));
+    return {
+        target,
+        total_entries: items.length,
+        file_count,
+        largest_file,
+        axis_distribution: axis,
+        purpose_distribution: purpose,
+        type_distribution: type,
+        event_markers,
+        tag_incomplete,
+        consolidated,
+        retention_confirmed,
+        domains,
+    };
+}
+function extractAgentFromPath(sourcePath) {
+    const match = sourcePath.match(/learnings\/([^/]+)\.md$/);
+    return match && match[1] ? match[1] : sourcePath;
+}
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+function pct(part, total) {
+    if (total === 0)
+        return "0";
+    return String(Math.round((part / total) * 100));
+}
+export function renderHealthReport(report) {
+    const lines = [];
+    const label = report.target === "global" ? "Global" : "Project";
+    const total = report.total_entries;
+    lines.push(`## Learning Health Dashboard`);
+    lines.push("");
+    lines.push(`### ${label} Learnings`);
+    lines.push("");
+    lines.push("| Metric | Value |");
+    lines.push("|--------|-------|");
+    lines.push(`| Total entries | ${total} |`);
+    lines.push(`| Files | ${report.file_count} |`);
+    if (report.largest_file) {
+        lines.push(`| Largest file | ${report.largest_file.agent} (${report.largest_file.lines} lines) |`);
+    }
+    else {
+        lines.push(`| Largest file | — |`);
+    }
+    lines.push("");
+    lines.push("### Axis Distribution");
+    lines.push("| Tag | Count | % |");
+    lines.push("|-----|-------|---|");
+    lines.push(`| methodology-only | ${report.axis_distribution.methodology_only} | ${pct(report.axis_distribution.methodology_only, total)}% |`);
+    lines.push(`| domain-only | ${report.axis_distribution.domain_only} | ${pct(report.axis_distribution.domain_only, total)}% |`);
+    lines.push(`| dual-tag | ${report.axis_distribution.dual} | ${pct(report.axis_distribution.dual, total)}% |`);
+    lines.push("");
+    lines.push("### Purpose Distribution");
+    lines.push("| Tag | Count |");
+    lines.push("|-----|-------|");
+    lines.push(`| guardrail | ${report.purpose_distribution.guardrail} |`);
+    lines.push(`| foundation | ${report.purpose_distribution.foundation} |`);
+    lines.push(`| convention | ${report.purpose_distribution.convention} |`);
+    lines.push(`| insight | ${report.purpose_distribution.insight} |`);
+    if (report.purpose_distribution.unassigned > 0) {
+        lines.push(`| unassigned | ${report.purpose_distribution.unassigned} |`);
+    }
+    lines.push("");
+    lines.push("### Type Distribution");
+    lines.push("| Tag | Count | % |");
+    lines.push("|-----|-------|---|");
+    lines.push(`| fact | ${report.type_distribution.fact} | ${pct(report.type_distribution.fact, total)}% |`);
+    lines.push(`| judgment | ${report.type_distribution.judgment} | ${pct(report.type_distribution.judgment, total)}% |`);
+    lines.push("");
+    lines.push("### Health Indicators");
+    lines.push("| Indicator | Value | Note |");
+    lines.push("|-----------|-------|------|");
+    const largestLines = report.largest_file?.lines ?? 0;
+    const sizeStatus = largestLines >= 200 ? "WARNING" : largestLines >= 100 ? "NOTICE" : "OK";
+    lines.push(`| File size | ${sizeStatus} | 최대 ${largestLines}행 (100 NOTICE, 200 WARNING). 대응: learn promotion design에서 consolidation 검토 |`);
+    lines.push(`| Event markers | ${report.event_markers} | applied-then-found-invalid 누적. learn promotion design에서 후보로 표면화 |`);
+    lines.push(`| Tag-incomplete | ${report.tag_incomplete} | Creation gate 실패 수. 해당 학습 항목의 태그 수동 보완 필요 |`);
+    lines.push(`| Consolidated | ${report.consolidated} | Cross-agent dedup 수행 수. 조치 불필요 (정보만) |`);
+    lines.push(`| Retention-confirmed | ${report.retention_confirmed} | 명시적 유지 판정 수 |`);
+    lines.push("");
+    lines.push("### Domains Referenced");
+    if (report.domains.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        lines.push(report.domains.map((d) => `${d.domain} (${d.count})`).join(", "));
+    }
+    return lines.join("\n");
+}

package/dist/core-runtime/learning/health-report.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import { buildHealthReport, renderHealthReport, } from "./health-report.js";
+// ─── Helpers ───
+function makeItem(overrides = {}) {
+    return {
+        agent_id: "logic",
+        scope: "global",
+        source_path: "/home/user/.onto/learnings/logic.md",
+        raw_line: "- [methodology][guardrail][fact] sample content",
+        line_number: 10,
+        type: "fact",
+        applicability_tags: ["methodology"],
+        role: "guardrail",
+        content: "sample content",
+        source_project: null,
+        source_domain: null,
+        source_date: null,
+        impact: "normal",
+        learning_id: null,
+        event_markers: [],
+        retention_confirmed_at: null,
+        ...overrides,
+    };
+}
+describe("buildHealthReport", () => {
+    it("returns zero metrics for empty input", () => {
+        const report = buildHealthReport([], "global");
+        expect(report.total_entries).toBe(0);
+        expect(report.file_count).toBe(0);
+        expect(report.largest_file).toBeNull();
+        expect(report.axis_distribution.methodology_only).toBe(0);
+        expect(report.domains).toEqual([]);
+    });
+    it("classifies axis distribution (methodology-only / domain-only / dual)", () => {
+        const items = [
+            makeItem({ applicability_tags: ["methodology"] }),
+            makeItem({ applicability_tags: ["methodology"] }),
+            makeItem({ applicability_tags: ["domain/SE"] }),
+            makeItem({ applicability_tags: ["methodology", "domain/SE"] }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.axis_distribution.methodology_only).toBe(2);
+        expect(report.axis_distribution.domain_only).toBe(1);
+        expect(report.axis_distribution.dual).toBe(1);
+    });
+    it("counts purpose distribution including unassigned (role=null)", () => {
+        const items = [
+            makeItem({ role: "guardrail" }),
+            makeItem({ role: "foundation" }),
+            makeItem({ role: "convention" }),
+            makeItem({ role: "insight" }),
+            makeItem({ role: null }),
+            makeItem({ role: null }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.purpose_distribution.guardrail).toBe(1);
+        expect(report.purpose_distribution.foundation).toBe(1);
+        expect(report.purpose_distribution.convention).toBe(1);
+        expect(report.purpose_distribution.insight).toBe(1);
+        expect(report.purpose_distribution.unassigned).toBe(2);
+    });
+    it("tallies type distribution fact vs judgment", () => {
+        const items = [
+            makeItem({ type: "fact" }),
+            makeItem({ type: "judgment" }),
+            makeItem({ type: "judgment" }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.type_distribution.fact).toBe(1);
+        expect(report.type_distribution.judgment).toBe(2);
+    });
+    it("counts event markers (sum of item.event_markers.length)", () => {
+        const items = [
+            makeItem({ event_markers: ["applied-then-found-invalid"] }),
+            makeItem({ event_markers: ["applied-then-found-invalid", "applied-then-found-invalid"] }),
+            makeItem({ event_markers: [] }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.event_markers).toBe(3);
+    });
+    it("detects tag-incomplete and consolidated markers from raw_line", () => {
+        const items = [
+            makeItem({ raw_line: "- [methodology] content [tag-incomplete]" }),
+            makeItem({ raw_line: "- [methodology] content <!-- consolidated into learning_id -->" }),
+            makeItem({ raw_line: "- [methodology] content" }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.tag_incomplete).toBe(1);
+        expect(report.consolidated).toBe(1);
+    });
+    it("counts retention_confirmed (retention_confirmed_at non-null)", () => {
+        const items = [
+            makeItem({ retention_confirmed_at: "2026-04-10" }),
+            makeItem({ retention_confirmed_at: "2026-04-11" }),
+            makeItem({ retention_confirmed_at: null }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.retention_confirmed).toBe(2);
+    });
+    it("derives file_count and largest_file from source_path and line_number", () => {
+        const items = [
+            makeItem({ source_path: "/p/.onto/learnings/logic.md", line_number: 40 }),
+            makeItem({ source_path: "/p/.onto/learnings/logic.md", line_number: 80 }),
+            makeItem({ source_path: "/p/.onto/learnings/axiology.md", line_number: 50 }),
+        ];
+        const report = buildHealthReport(items, "project");
+        expect(report.file_count).toBe(2);
+        expect(report.largest_file?.agent).toBe("logic");
+        expect(report.largest_file?.lines).toBe(80);
+    });
+    it("aggregates referenced domains with counts sorted desc then name asc", () => {
+        const items = [
+            makeItem({ applicability_tags: ["domain/SE"] }),
+            makeItem({ applicability_tags: ["domain/SE"] }),
+            makeItem({ applicability_tags: ["domain/UI"] }),
+            makeItem({ applicability_tags: ["methodology", "domain/Business"] }),
+        ];
+        const report = buildHealthReport(items, "global");
+        expect(report.domains).toEqual([
+            { domain: "SE", count: 2 },
+            { domain: "Business", count: 1 },
+            { domain: "UI", count: 1 },
+        ]);
+    });
+});
+describe("renderHealthReport", () => {
+    function makeReport() {
+        return buildHealthReport([
+            makeItem({ applicability_tags: ["methodology"], role: "guardrail" }),
+            makeItem({ applicability_tags: ["domain/SE"], role: "insight", type: "judgment" }),
+        ], "global");
+    }
+    it("renders markdown dashboard with all required sections", () => {
+        const output = renderHealthReport(makeReport());
+        expect(output).toContain("## Learning Health Dashboard");
+        expect(output).toContain("### Global Learnings");
+        expect(output).toContain("### Axis Distribution");
+        expect(output).toContain("### Purpose Distribution");
+        expect(output).toContain("### Type Distribution");
+        expect(output).toContain("### Health Indicators");
+        expect(output).toContain("### Domains Referenced");
+    });
+    it("labels target as Project when target=project", () => {
+        const report = buildHealthReport([makeItem()], "project");
+        const output = renderHealthReport(report);
+        expect(output).toContain("### Project Learnings");
+        expect(output).not.toContain("### Global Learnings");
+    });
+    it("marks file size WARNING when largest file >= 200 lines", () => {
+        const report = buildHealthReport([makeItem({ line_number: 210 })], "global");
+        const output = renderHealthReport(report);
+        expect(output).toContain("| File size | WARNING |");
+    });
+    it("marks file size NOTICE when largest file >= 100 and < 200", () => {
+        const report = buildHealthReport([makeItem({ line_number: 150 })], "global");
+        const output = renderHealthReport(report);
+        expect(output).toContain("| File size | NOTICE |");
+    });
+    it("marks file size OK when largest file < 100", () => {
+        const report = buildHealthReport([makeItem({ line_number: 50 })], "global");
+        const output = renderHealthReport(report);
+        expect(output).toContain("| File size | OK |");
+    });
+    it("renders (none) when no domains referenced", () => {
+        const report = buildHealthReport([makeItem({ applicability_tags: ["methodology"] })], "global");
+        const output = renderHealthReport(report);
+        expect(output).toContain("(none)");
+    });
+});