dna-sdk 0.1.0

package/dist/viz/ascii.js

@@ -0,0 +1,60 @@
+/**
+ * ASCII tree rendering — standalone function operating on ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused.
+ */
+// ---------------------------------------------------------------------------
+// ASCII Tree
+// ---------------------------------------------------------------------------
+export function asciiTree(mi) {
+    const tree = mi.dependencyTree();
+    if (Object.keys(tree).length === 0) {
+        return "(no dependencies)";
+    }
+    const lines = [`\u{1F4E6} ${mi.scope}`];
+    const agentNames = Object.keys(tree).sort();
+    for (let i = 0; i < agentNames.length; i++) {
+        const agentName = agentNames[i];
+        const info = tree[agentName];
+        const isLastAgent = i === agentNames.length - 1;
+        const prefix = isLastAgent ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+        const childPrefix = isLastAgent ? "    " : "\u2502   ";
+        lines.push(`${prefix}\u{1F916} ${agentName}`);
+        const dependsOn = (info.depends_on ?? {});
+        const depGroups = Object.entries(dependsOn);
+        for (let j = 0; j < depGroups.length; j++) {
+            const [depType, deps] = depGroups[j];
+            const isLastGroup = j === depGroups.length - 1;
+            const groupPrefix = isLastGroup ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+            const itemPrefix = isLastGroup ? "    " : "\u2502   ";
+            lines.push(`${childPrefix}${groupPrefix}${depType}/`);
+            const depItems = Object.entries(deps);
+            for (let k = 0; k < depItems.length; k++) {
+                const [depName, depInfo] = depItems[k];
+                const isLastDep = k === depItems.length - 1;
+                const depPrefix = isLastDep ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+                const kind = depInfo.kind ?? "";
+                const found = depInfo.found ?? true;
+                // Use KindPort.asciiIcon + graphMeta for kind-specific labels
+                const depKp = mi.kindFor(kind);
+                const depIcon = depKp?.asciiIcon ?? "";
+                const depDoc = mi._one(kind, depName);
+                const depMeta = depDoc ? (depKp?.graphMeta?.(depDoc) ?? {}) : {};
+                let label;
+                if (depMeta.severity) {
+                    const m = depMeta;
+                    const severityIcon = m.severity === "error" ? "\u{1F534}" : "\u{1F7E1}";
+                    label = `${severityIcon} ${depName} (${m.rules ?? 0} rules, ${m.severity})`;
+                }
+                else {
+                    label = depIcon ? `${depIcon} ${depName}` : depName;
+                }
+                if (!found) {
+                    label += " \u274C MISSING";
+                }
+                lines.push(`${childPrefix}${itemPrefix}${depPrefix}${label}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/viz/health.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Health report and impact analysis — standalone functions operating on ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused.
+ */
+import type { ManifestInstance } from "../kernel/instance.js";
+export declare function healthReport(mi: ManifestInstance): Record<string, unknown>;
+export declare function impact(mi: ManifestInstance, kind: string, name: string): Record<string, unknown>;

package/dist/viz/health.js

@@ -0,0 +1,161 @@
+/**
+ * Health report and impact analysis — standalone functions operating on ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused.
+ */
+// ---------------------------------------------------------------------------
+// Helpers (private access via cast)
+// ---------------------------------------------------------------------------
+function _kinds(mi) {
+    return mi._kinds;
+}
+function _profiles(mi) {
+    return mi._profiles;
+}
+// ---------------------------------------------------------------------------
+// Health Report
+// ---------------------------------------------------------------------------
+export function healthReport(mi) {
+    const kinds = _kinds(mi);
+    const profiles = _profiles(mi);
+    const tree = mi.dependencyTree();
+    const comp = mi.compositionResult;
+    // All orchestrators (agents) — found via composition profiles
+    const allAgents = mi.allWhere(kp => kp.isPromptTarget && !kp.isRoot && !kp.flattenInContext);
+    const agentNames = new Set(allAgents.map((a) => a.name));
+    // --- Generic slot-based health checks via CompositionProfile ---
+    const slotIssues = {};
+    const slotCoverage = {};
+    const slotTotals = {};
+    let hasIssues = false;
+    for (const agent of allAgents) {
+        const profile = mi.profileFor(agent);
+        if (!profile)
+            continue;
+        for (const slot of profile.slots) {
+            if (!slot.healthCheck)
+                continue;
+            const deps = mi.iterDocDeps(agent);
+            const slotDeps = deps.find(d => d.label === slot.name);
+            const names = slotDeps?.names ?? [];
+            if (slot.healthCheck.rule === "at-least-one" && names.length === 0) {
+                const key = slot.healthCheck.issueKey;
+                (slotIssues[key] ??= []).push(agent.name);
+                hasIssues = true;
+            }
+        }
+    }
+    // Coverage stats per slot
+    for (const profile of profiles) {
+        for (const slot of profile.slots) {
+            if (!slot.healthCheck)
+                continue;
+            const issueList = slotIssues[slot.healthCheck.issueKey] ?? [];
+            const covered = allAgents.length - issueList.length;
+            slotCoverage[slot.name] = `${covered}/${allAgents.length} agents`;
+            // Count total docs of this slot's target kind
+            const targetKp = mi.kindForAlias(slot.targetAlias);
+            if (targetKp) {
+                const allOfKind = mi._all(targetKp.kind);
+                slotTotals[`${slot.name}_total`] = allOfKind.length;
+                // For kinds with graphMeta returning severity, count rules
+                let rulesCount = 0;
+                for (const d of allOfKind) {
+                    const meta = targetKp.graphMeta?.(d) ?? targetKp.summary(d) ?? {};
+                    const m = meta;
+                    if (typeof m.rules === "number")
+                        rulesCount += m.rules;
+                }
+                if (rulesCount > 0)
+                    slotTotals[`${slot.name}_rules_total`] = rulesCount;
+                // has-error-severity: find agents missing error-severity docs
+                if (slot.healthCheck.rule === "at-least-one") {
+                    const errorDocs = allOfKind.filter(d => {
+                        const m = (targetKp.graphMeta?.(d) ?? targetKp.summary(d) ?? {});
+                        return m.severity === "error";
+                    });
+                    if (errorDocs.length > 0) {
+                        const agentsWithError = new Set();
+                        for (const agent of allAgents) {
+                            const deps = mi.iterDocDeps(agent);
+                            const slotDeps = deps.find(dd => dd.label === slot.name);
+                            for (const depName of slotDeps?.names ?? []) {
+                                if (errorDocs.some(ed => ed.name === depName)) {
+                                    agentsWithError.add(agent.name);
+                                }
+                            }
+                        }
+                        const missing = [...agentNames].filter(n => !agentsWithError.has(n)).sort();
+                        if (missing.length > 0) {
+                            slotIssues[`agents_missing_error_${slot.name}`] = missing;
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Referenced deps (from tree)
+    const referenced = new Set();
+    for (const info of Object.values(tree)) {
+        const treeInfo = info;
+        const dependsOn = treeInfo.depends_on;
+        if (!dependsOn)
+            continue;
+        for (const deps of Object.values(dependsOn)) {
+            for (const depName of Object.keys(deps)) {
+                referenced.add(depName);
+            }
+        }
+    }
+    // Find orphan documents (not referenced, not root, not prompt-target)
+    const orphans = [];
+    for (const doc of mi.documents) {
+        const _kp = kinds.get(`${doc.apiVersion}\0${doc.kind}`);
+        if (_kp?.isRoot || _kp?.isPromptTarget)
+            continue;
+        if (!referenced.has(doc.name)) {
+            orphans.push({ kind: doc.kind, name: doc.name });
+        }
+    }
+    const isHealthy = comp.missing.length === 0 && !hasIssues;
+    return {
+        status: isHealthy ? "healthy" : "warnings",
+        composition_valid: comp.missing.length === 0,
+        missing_refs: comp.missing,
+        agents_total: allAgents.length,
+        // Slot issues — each key comes from slot.healthCheck.issueKey
+        ...slotIssues,
+        // Slot totals (e.g. guardrails_total, guardrails_rules_total)
+        ...slotTotals,
+        orphan_documents: orphans,
+        coverage: slotCoverage,
+    };
+}
+// ---------------------------------------------------------------------------
+// Impact Analysis
+// ---------------------------------------------------------------------------
+export function impact(mi, kind, name) {
+    const tree = mi.dependencyTree();
+    const affected = [];
+    for (const [agentName, info] of Object.entries(tree)) {
+        const treeInfo = info;
+        const dependsOn = treeInfo.depends_on;
+        if (!dependsOn)
+            continue;
+        for (const [depType, deps] of Object.entries(dependsOn)) {
+            if (name in deps) {
+                affected.push({ agent: agentName, relationship: depType });
+            }
+        }
+    }
+    const doc = mi._one(kind, name);
+    return {
+        kind,
+        name,
+        description: doc ? (doc.metadata.description ?? "") : "",
+        found: doc !== null,
+        affected_agents: affected,
+        affected_count: affected.length,
+        safe_to_remove: affected.length === 0,
+    };
+}

package/dist/viz/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Visualization module — barrel re-export.
+ *
+ * Standalone functions that operate on ManifestInstance, extracted from
+ * the class to keep the kernel focused on query/prompt/composition.
+ */
+export { dependencyTreeMermaid, compositionFlowchartMermaid, c4ComponentMermaid, erDiagramMermaid, erModel, mindmapMermaid, pieChartMermaid, quadrantMermaid, timelineMermaid, sankeyMermaid, kindCatalogMermaid, exportDiagramsMd, } from "./mermaid.js";
+export { healthReport, impact } from "./health.js";
+export { matrix, matrixMarkdown } from "./matrix.js";
+export { asciiTree } from "./ascii.js";

package/dist/viz/index.js

@@ -0,0 +1,10 @@
+/**
+ * Visualization module — barrel re-export.
+ *
+ * Standalone functions that operate on ManifestInstance, extracted from
+ * the class to keep the kernel focused on query/prompt/composition.
+ */
+export { dependencyTreeMermaid, compositionFlowchartMermaid, c4ComponentMermaid, erDiagramMermaid, erModel, mindmapMermaid, pieChartMermaid, quadrantMermaid, timelineMermaid, sankeyMermaid, kindCatalogMermaid, exportDiagramsMd, } from "./mermaid.js";
+export { healthReport, impact } from "./health.js";
+export { matrix, matrixMarkdown } from "./matrix.js";
+export { asciiTree } from "./ascii.js";

package/dist/viz/matrix.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Matrix views — standalone functions operating on ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused.
+ */
+import type { ManifestInstance } from "../kernel/instance.js";
+export declare function matrix(mi: ManifestInstance): Record<string, unknown>;
+export declare function matrixMarkdown(mi: ManifestInstance): string;

package/dist/viz/matrix.js

@@ -0,0 +1,84 @@
+/**
+ * Matrix views — standalone functions operating on ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused.
+ */
+// ---------------------------------------------------------------------------
+// Matrix (structured)
+// ---------------------------------------------------------------------------
+export function matrix(mi) {
+    const tree = mi.dependencyTree();
+    if (Object.keys(tree).length === 0) {
+        return { agents: [], dependencies: {}, matrix: {} };
+    }
+    const agents = Object.keys(tree).sort();
+    // Collect all deps grouped by kind
+    const depsByKind = new Map();
+    for (const info of Object.values(tree)) {
+        const treeInfo = info;
+        const dependsOn = treeInfo.depends_on;
+        if (!dependsOn)
+            continue;
+        for (const deps of Object.values(dependsOn)) {
+            for (const [depName, depInfo] of Object.entries(deps)) {
+                const kind = depInfo.kind ?? "Unknown";
+                if (!depsByKind.has(kind))
+                    depsByKind.set(kind, new Set());
+                depsByKind.get(kind).add(depName);
+            }
+        }
+    }
+    // Build matrix
+    const matrixData = {};
+    for (const [agentName, info] of Object.entries(tree)) {
+        const treeInfo = info;
+        const dependsOn = treeInfo.depends_on;
+        const row = {};
+        if (dependsOn) {
+            for (const deps of Object.values(dependsOn)) {
+                for (const depName of Object.keys(deps)) {
+                    row[depName] = true;
+                }
+            }
+        }
+        matrixData[agentName] = row;
+    }
+    // Build sorted dependencies object
+    const dependencies = {};
+    const sortedKinds = [...depsByKind.keys()].sort();
+    for (const kind of sortedKinds) {
+        dependencies[kind] = [...depsByKind.get(kind)].sort();
+    }
+    return { agents, dependencies, matrix: matrixData };
+}
+// ---------------------------------------------------------------------------
+// Matrix Markdown
+// ---------------------------------------------------------------------------
+export function matrixMarkdown(mi) {
+    const data = matrix(mi);
+    const agents = data.agents;
+    if (agents.length === 0) {
+        return "No agents with dependencies found.";
+    }
+    const dependencies = data.dependencies;
+    const matrixData = data.matrix;
+    // Flatten all dep names in kind order
+    const allDeps = []; // [kind, name]
+    for (const [kind, names] of Object.entries(dependencies)) {
+        for (const name of names) {
+            allDeps.push([kind, name]);
+        }
+    }
+    // Header
+    const depHeaders = allDeps.map(([, n]) => n);
+    const header = `| Agent | ${depHeaders.join(" | ")} |`;
+    const sep = `|-------|${allDeps.map(() => ":---:").join("|")}|`;
+    const rows = [];
+    for (const agent of agents) {
+        const cells = allDeps.map(([, depName]) => matrixData[agent]?.[depName] ? "\u25CF" : " ");
+        rows.push(`| **${agent}** | ${cells.join(" | ")} |`);
+    }
+    // Kind legend row
+    const kindRow = `| *Kind* | ${allDeps.map(([k]) => `*${k[0].toUpperCase()}*`).join(" | ")} |`;
+    return [header, sep, kindRow, ...rows].join("\n");
+}

package/dist/viz/mermaid.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Mermaid diagram generators — standalone functions that operate on a ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused on
+ * query/prompt/composition. The original methods on ManifestInstance are
+ * preserved for backwards compat; these functions are the canonical
+ * implementation going forward.
+ */
+import type { ManifestInstance } from "../kernel/instance.js";
+export declare function dependencyTreeMermaid(mi: ManifestInstance): string;
+export declare function compositionFlowchartMermaid(mi: ManifestInstance): string;
+export declare function c4ComponentMermaid(mi: ManifestInstance): string;
+export declare function erModel(mi: ManifestInstance): {
+    entities: {
+        id: string;
+        kind: string;
+        name: string;
+        attrs: {
+            key: string;
+            type: string;
+            value: string;
+        }[];
+    }[];
+    relationships: {
+        sourceId: string;
+        targetId: string;
+        label: string;
+        isMany: boolean;
+    }[];
+};
+export declare function erDiagramMermaid(mi: ManifestInstance): string;
+export declare function mindmapMermaid(mi: ManifestInstance): string;
+export declare function pieChartMermaid(mi: ManifestInstance): string;
+export declare function quadrantMermaid(mi: ManifestInstance): string;
+export declare function timelineMermaid(mi: ManifestInstance): string;
+export declare function sankeyMermaid(mi: ManifestInstance): string;
+export declare function kindCatalogMermaid(mi: ManifestInstance): string;
+export declare function exportDiagramsMd(mi: ManifestInstance, path?: string): Record<string, string>;