@monoes/monograph 1.1.0 → 1.2.0

package/src/export/codeclimate.ts

@@ -0,0 +1,201 @@
+import { relative } from 'path';
+import type { MonographDb } from '../storage/db.js';
+
+export interface CodeClimateIssue {
+  type: 'issue';
+  check_name: string;
+  description: string;
+  categories: string[];
+  fingerprint: string;
+  severity: 'blocker' | 'critical' | 'major' | 'minor' | 'info';
+  location: {
+    path: string;
+    lines: { begin: number; end?: number };
+  };
+}
+
+/** FNV-1a 32-bit hash → 8 lowercase hex chars. */
+function fnv1a32(str: string): string {
+  let h = 2166136261;
+  for (const b of Buffer.from(str)) {
+    h ^= b;
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}
+
+/** Normalize Next.js dynamic route segments. */
+function normalizePath(p: string): string {
+  return p.replace(/\[([^\]]+)\]/g, '%5B$1%5D');
+}
+
+function relativePath(filePath: string, repoRoot?: string): string {
+  if (!repoRoot) return filePath;
+  return relative(repoRoot, filePath);
+}
+
+function makeIssue(
+  checkName: string,
+  description: string,
+  categories: string[],
+  severity: CodeClimateIssue['severity'],
+  filePath: string,
+  line: number,
+  repoRoot?: string,
+): CodeClimateIssue {
+  const relPath = normalizePath(relativePath(filePath, repoRoot));
+  const fingerprint = fnv1a32(`${checkName}:${relPath}:${line}`);
+  return {
+    type: 'issue',
+    check_name: checkName,
+    description,
+    categories,
+    fingerprint,
+    severity,
+    location: {
+      path: relPath,
+      lines: { begin: line },
+    },
+  };
+}
+
+/**
+ * Export CodeClimate-compatible issue list from the monograph DB.
+ * Returns a JSON-serialisable array of issues.
+ */
+export function exportCodeClimate(db: MonographDb, repoRoot?: string): CodeClimateIssue[] {
+  const issues: CodeClimateIssue[] = [];
+
+  // ── God nodes (top 10% by fan-in) ─────────────────────────────────────────
+  const totalNodes = (db.prepare(`SELECT COUNT(*) as c FROM nodes WHERE label = 'File'`).get() as { c: number }).c;
+  const top10pct = Math.max(1, Math.floor(totalNodes * 0.1));
+  const godNodes = db.prepare(`
+    SELECT n.id, n.name, n.file_path, COALESCE(n.start_line, 1) AS line,
+           COUNT(e.id) AS in_degree
+    FROM nodes n
+    LEFT JOIN edges e ON e.target_id = n.id AND e.relation IN ('IMPORTS', 'RE_EXPORTS')
+    WHERE n.file_path IS NOT NULL AND n.label = 'File'
+    GROUP BY n.id
+    ORDER BY in_degree DESC
+    LIMIT ?
+  `).all(top10pct) as { id: string; name: string; file_path: string; line: number; in_degree: number }[];
+
+  for (const row of godNodes) {
+    if (row.in_degree === 0) continue;
+    issues.push(makeIssue(
+      'monograph/god-node',
+      `God node: "${row.name}" has ${row.in_degree} incoming dependencies.`,
+      ['Complexity'],
+      'major',
+      row.file_path,
+      row.line ?? 1,
+      repoRoot,
+    ));
+  }
+
+  // ── Unreachable files ──────────────────────────────────────────────────────
+  const unreachable = db.prepare(`
+    SELECT id, name, file_path FROM nodes
+    WHERE label = 'File'
+    AND (
+      json_extract(properties, '$.reachabilityRole') = 'unreachable'
+      OR properties LIKE '%"unreachable"%'
+    )
+    AND file_path IS NOT NULL
+  `).all() as { id: string; name: string; file_path: string }[];
+
+  for (const row of unreachable) {
+    issues.push(makeIssue(
+      'monograph/unreachable-file',
+      `Unreachable file: "${row.name}" is not reachable from any entry point.`,
+      ['Duplication'],
+      'minor',
+      row.file_path,
+      1,
+      repoRoot,
+    ));
+  }
+
+  // ── Structural duplicates (STRUCTURALLY_SIMILAR edges) ───────────────────
+  const dupes = db.prepare(`
+    SELECT e.id, n1.name AS src_name, n1.file_path AS src_path,
+           COALESCE(n1.start_line, 1) AS src_line
+    FROM edges e
+    JOIN nodes n1 ON n1.id = e.source_id
+    JOIN nodes n2 ON n2.id = e.target_id
+    WHERE e.relation = 'STRUCTURALLY_SIMILAR'
+    AND n1.file_path IS NOT NULL
+  `).all() as { id: string; src_name: string; src_path: string; src_line: number }[];
+
+  for (const row of dupes) {
+    issues.push(makeIssue(
+      'monograph/duplicate',
+      `Duplicate: "${row.src_name}" is structurally similar to another file.`,
+      ['Duplication'],
+      'minor',
+      row.src_path,
+      row.src_line ?? 1,
+      repoRoot,
+    ));
+  }
+
+  return issues;
+}
+
+// ── Round 10: health + duplication CodeClimate exports ────────────────────────
+
+export interface CodeClimateHealthIssue extends CodeClimateIssue {
+  categories: ['Complexity'];
+}
+
+export interface CodeClimateDuplicationIssue extends CodeClimateIssue {
+  categories: ['Duplication'];
+}
+
+export interface HealthFindingInput {
+  filePath: string;
+  functionName: string;
+  startLine: number;
+  endLine: number;
+  severity: 'major' | 'minor' | 'critical' | 'info';
+  crapScore: number;
+  cyclomatic: number;
+}
+
+export interface DuplicationFindingInput {
+  filePath: string;
+  startLine: number;
+  endLine: number;
+  groupId: number;
+  duplicatedLines: number;
+}
+
+function fingerprint(s: string): string {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (Math.imul(31, h) + s.charCodeAt(i)) >>> 0;
+  return h.toString(16).padStart(8, '0');
+}
+
+export function exportHealthCodeClimate(findings: HealthFindingInput[]): CodeClimateIssue[] {
+  return findings.map(f => ({
+    type: 'issue',
+    check_name: 'complexity',
+    description: `${f.functionName}: cyclomatic=${f.cyclomatic}, CRAP=${f.crapScore.toFixed(1)}`,
+    categories: ['Complexity'],
+    severity: f.severity,
+    fingerprint: fingerprint(`${f.filePath}:${f.functionName}:${f.startLine}`),
+    location: { path: f.filePath, lines: { begin: f.startLine, end: f.endLine } },
+  }));
+}
+
+export function exportDuplicationCodeClimate(findings: DuplicationFindingInput[]): CodeClimateIssue[] {
+  return findings.map(f => ({
+    type: 'issue',
+    check_name: 'duplication',
+    description: `Code duplication: ${f.duplicatedLines} lines (group ${f.groupId})`,
+    categories: ['Duplication'],
+    severity: 'minor' as const,
+    fingerprint: fingerprint(`${f.filePath}:${f.groupId}:${f.startLine}`),
+    location: { path: f.filePath, lines: { begin: f.startLine, end: f.endLine } },
+  }));
+}

package/src/export/compact-health.ts

@@ -0,0 +1,119 @@
+import { relative } from 'node:path';
+
+export interface CompactHealthFinding {
+  path: string;
+  line: number;
+  name: string;
+  cyclomatic: number;
+  cognitive: number;
+  severity: string;
+  crap?: number;
+  coveragePct?: number;
+}
+
+export interface CompactHotspot {
+  path: string;
+  score: number;
+  commits: number;
+  linesAdded: number;
+  linesDeleted: number;
+  complexityDensity: number;
+  fanIn: number;
+  trend: string;
+}
+
+export interface CompactHealthScore {
+  score: number;
+  grade: string;
+}
+
+export interface CompactVitalSigns {
+  totalLoc?: number;
+  avgCyclomatic: number;
+  p90Cyclomatic: number;
+  deadFilePct?: number;
+  deadExportPct?: number;
+  maintainabilityAvg?: number;
+  hotspotCount?: number;
+  circularDepCount?: number;
+  unusedDepCount?: number;
+}
+
+export interface CompactHealthTrend {
+  overallDirection: string;
+  metrics: Array<{ name: string; previous: number; current: number; delta: number; direction: string }>;
+}
+
+export interface CompactHealthReport {
+  root: string;
+  healthScore?: CompactHealthScore;
+  vitalSigns?: CompactVitalSigns;
+  findings?: CompactHealthFinding[];
+  hotspots?: CompactHotspot[];
+  healthTrend?: CompactHealthTrend;
+}
+
+export interface CompactCloneGroup {
+  instances: Array<{ file: string; startLine: number; endLine: number; tokenCount?: number }>;
+}
+
+export interface CompactDuplicationReport {
+  root: string;
+  cloneGroups: CompactCloneGroup[];
+}
+
+function rel(p: string, root: string): string { return relative(root, p); }
+
+export function buildHealthCompactLines(report: CompactHealthReport): string[] {
+  const lines: string[] = [];
+  const { root } = report;
+  if (report.healthScore)
+    lines.push(`health-score:${report.healthScore.score.toFixed(1)}:${report.healthScore.grade}`);
+
+  if (report.vitalSigns) {
+    const vs = report.vitalSigns;
+    const parts: string[] = [];
+    if (vs.totalLoc) parts.push(`total_loc=${vs.totalLoc}`);
+    parts.push(`avg_cyclomatic=${vs.avgCyclomatic.toFixed(1)}`);
+    parts.push(`p90_cyclomatic=${vs.p90Cyclomatic}`);
+    if (vs.deadFilePct !== undefined) parts.push(`dead_file_pct=${vs.deadFilePct.toFixed(1)}`);
+    if (vs.deadExportPct !== undefined) parts.push(`dead_export_pct=${vs.deadExportPct.toFixed(1)}`);
+    if (vs.maintainabilityAvg !== undefined) parts.push(`maintainability_avg=${vs.maintainabilityAvg.toFixed(1)}`);
+    if (vs.hotspotCount !== undefined) parts.push(`hotspot_count=${vs.hotspotCount}`);
+    if (vs.circularDepCount !== undefined) parts.push(`circular_dep_count=${vs.circularDepCount}`);
+    if (vs.unusedDepCount !== undefined) parts.push(`unused_dep_count=${vs.unusedDepCount}`);
+    lines.push(`vital-signs:${parts.join(',')}`);
+  }
+
+  for (const f of report.findings ?? []) {
+    const crapSuffix = f.crap !== undefined
+      ? `,crap=${f.crap.toFixed(1)}${f.coveragePct !== undefined ? `,coverage_pct=${f.coveragePct.toFixed(1)}` : ''}` : '';
+    lines.push(`high-complexity:${rel(f.path, root)}:${f.line}:${f.name}:cyclomatic=${f.cyclomatic},cognitive=${f.cognitive},severity=${f.severity}${crapSuffix}`);
+  }
+
+  for (const h of report.hotspots ?? []) {
+    lines.push(`hotspot:${rel(h.path, root)}:score=${h.score.toFixed(1)},commits=${h.commits},churn=${h.linesAdded + h.linesDeleted},density=${h.complexityDensity.toFixed(2)},fan_in=${h.fanIn},trend=${h.trend}`);
+  }
+
+  if (report.healthTrend) {
+    lines.push(`trend:overall:direction=${report.healthTrend.overallDirection}`);
+    for (const m of report.healthTrend.metrics) {
+      const sign = m.delta >= 0 ? '+' : '';
+      lines.push(`trend:${m.name}:previous=${m.previous.toFixed(1)},current=${m.current.toFixed(1)},delta=${sign}${m.delta.toFixed(1)},direction=${m.direction}`);
+    }
+  }
+  return lines;
+}
+
+export function buildDuplicationCompactLines(report: CompactDuplicationReport): string[] {
+  const lines: string[] = [];
+  const { root } = report;
+  for (let i = 0; i < report.cloneGroups.length; i++) {
+    const group = report.cloneGroups[i];
+    for (const inst of group.instances) {
+      const tokens = inst.tokenCount !== undefined ? `${inst.tokenCount}tokens` : '';
+      lines.push(`clone-group-${i + 1}:${rel(inst.file, root)}:${inst.startLine}-${inst.endLine}${tokens ? ':' + tokens : ''}`);
+    }
+  }
+  return lines;
+}

package/src/export/compact.ts

@@ -0,0 +1,83 @@
+import { relative } from 'path';
+import type { MonographDb } from '../storage/db.js';
+
+function relPath(filePath: string, repoRoot?: string): string {
+  if (!repoRoot) return filePath;
+  return relative(repoRoot, filePath);
+}
+
+/**
+ * Export a compact one-line-per-issue text format suitable for CLI output
+ * and machine consumption by shell pipelines.
+ *
+ * Line formats:
+ *   unreachable-file:{path}
+ *   god-node:{path}:{line}:{name}
+ *   duplicate:{path}:{name}
+ *   boundary-violation:{path}:{line}:{rule}
+ */
+export function exportCompact(db: MonographDb, repoRoot?: string): string {
+  const lines: string[] = [];
+
+  // ── Unreachable files ──────────────────────────────────────────────────────
+  const unreachable = db.prepare(`
+    SELECT file_path FROM nodes
+    WHERE label = 'File'
+    AND (
+      json_extract(properties, '$.reachabilityRole') = 'unreachable'
+      OR properties LIKE '%"unreachable"%'
+    )
+    AND file_path IS NOT NULL
+  `).all() as { file_path: string }[];
+
+  for (const row of unreachable) {
+    lines.push(`unreachable-file:${relPath(row.file_path, repoRoot)}`);
+  }
+
+  // ── God nodes (top 10% by fan-in) ─────────────────────────────────────────
+  const totalNodes = (db.prepare(`SELECT COUNT(*) as c FROM nodes WHERE label = 'File'`).get() as { c: number }).c;
+  const top10pct = Math.max(1, Math.floor(totalNodes * 0.1));
+  const godNodes = db.prepare(`
+    SELECT n.name, n.file_path, COALESCE(n.start_line, 1) AS line,
+           COUNT(e.id) AS in_degree
+    FROM nodes n
+    LEFT JOIN edges e ON e.target_id = n.id AND e.relation IN ('IMPORTS', 'RE_EXPORTS')
+    WHERE n.file_path IS NOT NULL AND n.label = 'File'
+    GROUP BY n.id
+    ORDER BY in_degree DESC
+    LIMIT ?
+  `).all(top10pct) as { name: string; file_path: string; line: number; in_degree: number }[];
+
+  for (const row of godNodes) {
+    if (row.in_degree === 0) continue;
+    lines.push(`god-node:${relPath(row.file_path, repoRoot)}:${row.line}:${row.name}`);
+  }
+
+  // ── Structural duplicates ─────────────────────────────────────────────────
+  const dupes = db.prepare(`
+    SELECT n1.name AS src_name, n1.file_path AS src_path
+    FROM edges e
+    JOIN nodes n1 ON n1.id = e.source_id
+    WHERE e.relation = 'STRUCTURALLY_SIMILAR'
+    AND n1.file_path IS NOT NULL
+  `).all() as { src_name: string; src_path: string }[];
+
+  for (const row of dupes) {
+    lines.push(`duplicate:${relPath(row.src_path, repoRoot)}:${row.src_name}`);
+  }
+
+  // ── Boundary violations (stored in node properties) ───────────────────────
+  const violations = db.prepare(`
+    SELECT file_path, COALESCE(start_line, 1) AS line,
+           json_extract(properties, '$.boundaryViolation') AS rule
+    FROM nodes
+    WHERE file_path IS NOT NULL
+    AND json_extract(properties, '$.boundaryViolation') IS NOT NULL
+  `).all() as { file_path: string; line: number; rule: string }[];
+
+  for (const row of violations) {
+    lines.push(`boundary-violation:${relPath(row.file_path, repoRoot)}:${row.line}:${row.rule}`);
+  }
+
+  return lines.join('\n');
+}

package/src/export/csv.ts

@@ -0,0 +1,33 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+
+export interface CsvExport {
+  nodes: string;
+  edges: string;
+}
+
+function escape(v: string | number | boolean | undefined | null): string {
+  const s = String(v ?? '');
+  // Prefix formula-injection characters to prevent spreadsheet execution
+  const safe = /^[=+\-@]/.test(s) ? `'${s}` : s;
+  return safe.includes(',') || safe.includes('"') || safe.includes('\n')
+    ? `"${safe.replace(/"/g, '""')}"` : safe;
+}
+
+export function toCsv(nodes: MonographNode[], edges: MonographEdge[]): CsvExport {
+  const nodeHeader = 'id,label,name,filePath,isExported,startLine,endLine';
+  const nodeRows = nodes.map(n =>
+    [n.id, n.label, n.name, n.filePath ?? '', n.isExported, n.startLine ?? '', n.endLine ?? '']
+      .map(escape).join(',')
+  );
+
+  const edgeHeader = 'id,sourceId,targetId,relation,confidence,confidenceScore';
+  const edgeRows = edges.map(e =>
+    [e.id, e.sourceId, e.targetId, e.relation, e.confidence, e.confidenceScore]
+      .map(escape).join(',')
+  );
+
+  return {
+    nodes: [nodeHeader, ...nodeRows].join('\n'),
+    edges: [edgeHeader, ...edgeRows].join('\n'),
+  };
+}

package/src/export/dot.ts

@@ -0,0 +1,52 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+
+export interface DotOptions {
+  graphName?: string;
+}
+
+function escapeDotString(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+
+function safeDotId(s: string): string {
+  return /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(s) ? s : `"${escapeDotString(s)}"`;
+}
+
+/**
+ * Export nodes and edges to Graphviz DOT format.
+ *
+ * @param nodes - Array of MonographNode objects
+ * @param edges - Array of MonographEdge objects
+ * @param options - Optional configuration (graphName)
+ * @returns A DOT format string suitable for Graphviz
+ */
+export function toDot(
+  nodes: MonographNode[],
+  edges: MonographEdge[],
+  options: DotOptions = {},
+): string {
+  const graphName = safeDotId(options.graphName ?? 'monograph');
+
+  const nodeLines = nodes.map(n => {
+    const label = escapeDotString(`${n.name}\n[${n.label}]`);
+    return `  "${escapeDotString(n.id)}" [label="${label}"];`;
+  });
+
+  const edgeLines = edges.map(e => {
+    const src = escapeDotString(e.sourceId);
+    const tgt = escapeDotString(e.targetId);
+    const rel = escapeDotString(e.relation);
+    return `  "${src}" -> "${tgt}" [label="${rel}"];`;
+  });
+
+  const lines = [
+    `digraph ${graphName} {`,  // graphName is already quoted/validated by safeDotId
+    '  rankdir=LR;',
+    '  node [shape=box, fontsize=10];',
+    ...nodeLines,
+    ...edgeLines,
+    '}',
+  ];
+
+  return lines.join('\n');
+}

package/src/export/gexf.ts

@@ -0,0 +1,59 @@
+import type { MonographNode, MonographEdge } from '../types.js';
+
+function esc(s: string): string {
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Export nodes and edges to GEXF (Graph Exchange XML Format) string.
+ *
+ * GEXF is the format used by Gephi and similar graph visualization tools.
+ *
+ * @param nodes - Array of MonographNode objects
+ * @param edges - Array of MonographEdge objects
+ * @returns A GEXF XML string
+ */
+export function toGexf(nodes: MonographNode[], edges: MonographEdge[]): string {
+  const nodeXml = nodes
+    .map(n =>
+      `    <node id="${esc(n.id)}" label="${esc(n.name)}">` +
+      `<attvalues>` +
+      `<attvalue for="0" value="${esc(n.label)}"/>` +
+      `<attvalue for="1" value="${n.isExported ? 'true' : 'false'}"/>` +
+      (n.filePath ? `<attvalue for="2" value="${esc(n.filePath)}"/>` : '') +
+      `</attvalues>` +
+      `</node>`
+    )
+    .join('\n');
+
+  const edgeXml = edges
+    .map(e =>
+      `    <edge id="${esc(e.id)}" source="${esc(e.sourceId)}" target="${esc(e.targetId)}" label="${esc(e.relation)}" weight="${e.confidenceScore}"/>`
+    )
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<gexf xmlns="http://gexf.net/1.3" version="1.3">
+  <meta>
+    <creator>@monomind/monograph</creator>
+    <description>Knowledge graph export</description>
+  </meta>
+  <graph defaultedgetype="directed">
+    <attributes class="node">
+      <attribute id="0" title="label" type="string"/>
+      <attribute id="1" title="isExported" type="boolean"/>
+      <attribute id="2" title="filePath" type="string"/>
+    </attributes>
+    <nodes>
+${nodeXml}
+    </nodes>
+    <edges>
+${edgeXml}
+    </edges>
+  </graph>
+</gexf>`;
+}

package/src/export/graphml.ts

@@ -9,6 +9,7 @@ export function toGraphml(nodes: MonographNode[], edges: MonographEdge[]): strin
         `<data key="name">${esc(n.name)}</data>` +
         `<data key="file">${esc(n.filePath ?? '')}</data>` +
         `<data key="exported">${n.isExported ? 'true' : 'false'}</data>` +
+        (n.communityId !== undefined ? `<data key="community">${n.communityId}</data>` : '') +
         `</node>`
     )
     .join('\n');
@@ -29,6 +30,7 @@ export function toGraphml(nodes: MonographNode[], edges: MonographEdge[]): strin
   <key id="name" for="node" attr.name="name" attr.type="string"/>
   <key id="file" for="node" attr.name="file" attr.type="string"/>
   <key id="exported" for="node" attr.name="exported" attr.type="boolean"/>
+  <key id="community" for="node" attr.name="community" attr.type="int"/>
   <key id="relation" for="edge" attr.name="relation" attr.type="string"/>
   <key id="confidence" for="edge" attr.name="confidence" attr.type="string"/>
   <graph id="G" edgedefault="directed">