carto-md 2.0.8 → 2.1.0

package/src/predictive/cut-points.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Microservice cut-point finder.
+ *
+ * Identifies natural microservice boundaries by finding clusters with
+ * high internal cohesion and low external coupling.
+ *
+ * Method:
+ *   1. For each domain D in the store, count
+ *        - intra_edges    imports where both ends are in D
+ *        - external_edges imports from D to ¬D, plus imports from ¬D to D
+ *   2. cohesion = intra_edges / (intra_edges + external_edges)
+ *   3. A domain with cohesion >= 0.7 and size >= 10 is a candidate cut-point.
+ *
+ * Output: per-domain { domain, files, intra_edges, external_edges,
+ *                       cohesion_score, candidate: boolean }.
+ */
+
+function findCutPoints({ store, threshold = 0.7, minSize = 10 } = {}) {
+  if (!store || !store.db) return { cut_points: [], all_domains: [] };
+
+  const allDomains = store.getDomainsList();
+  const intraEdges = store.db.prepare(`
+    SELECT d.name as domain, COUNT(*) as c
+    FROM imports i
+    JOIN files f1 ON i.from_file_id = f1.id
+    JOIN files f2 ON i.to_file_id = f2.id
+    JOIN domains d ON f1.domain_id = d.id
+    WHERE f1.domain_id = f2.domain_id AND i.to_file_id IS NOT NULL
+    GROUP BY d.name
+  `).all();
+  const intraMap = new Map(intraEdges.map(r => [r.domain, r.c]));
+
+  const externalEdges = store.db.prepare(`
+    SELECT d.name as domain, COUNT(*) as c
+    FROM imports i
+    JOIN files f1 ON i.from_file_id = f1.id
+    JOIN files f2 ON i.to_file_id = f2.id
+    JOIN domains d ON f1.domain_id = d.id
+    WHERE f1.domain_id != f2.domain_id AND i.to_file_id IS NOT NULL
+    GROUP BY d.name
+  `).all();
+  const externalMap = new Map(externalEdges.map(r => [r.domain, r.c]));
+
+  // Inbound external edges: imports INTO domain D from other domains.
+  const inboundExt = store.db.prepare(`
+    SELECT d.name as domain, COUNT(*) as c
+    FROM imports i
+    JOIN files f1 ON i.from_file_id = f1.id
+    JOIN files f2 ON i.to_file_id = f2.id
+    JOIN domains d ON f2.domain_id = d.id
+    WHERE f1.domain_id != f2.domain_id AND i.to_file_id IS NOT NULL
+    GROUP BY d.name
+  `).all();
+  const inboundMap = new Map(inboundExt.map(r => [r.domain, r.c]));
+
+  const out = [];
+  for (const d of allDomains) {
+    const intra = intraMap.get(d.name) || 0;
+    const outbound = externalMap.get(d.name) || 0;
+    const inbound = inboundMap.get(d.name) || 0;
+    const external = outbound + inbound;
+    const total = intra + external;
+    const cohesion = total === 0 ? 0 : intra / total;
+    out.push({
+      domain: d.name,
+      files: d.fileCount,
+      intra_edges: intra,
+      outbound_edges: outbound,
+      inbound_edges: inbound,
+      cohesion: Math.round(cohesion * 1000) / 1000,
+      candidate: cohesion >= threshold && d.fileCount >= minSize,
+    });
+  }
+  out.sort((a, b) => b.cohesion - a.cohesion);
+  return {
+    cut_points: out.filter(x => x.candidate),
+    all_domains: out,
+  };
+}
+
+module.exports = { findCutPoints };

package/src/predictive/drift-digest.js

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * Weekly drift digest renderer.
+ *
+ * Produces a CLI-renderable weekly architectural digest as markdown.
+ * Slack delivery is left to whatever cron + webhook the user wires up;
+ * this module only renders the body.
+ *
+ * Content:
+ *   1. Domain growth/shrink over `time_range` (default 7d)
+ *   2. Top hotspots (commit_count × blast_radius)
+ *   3. New architectural events
+ *   4. New cross-domain edges introduced
+ *   5. Top files by predictive risk score
+ */
+
+function renderDriftDigest({ store, temporalStore, projectRoot, timeRange = '7d' }) {
+  if (!store) return '# Drift Digest\n\n_No store available._';
+
+  const lines = [`# Drift Digest (${timeRange})`];
+  lines.push(`\nGenerated ${new Date().toISOString()}\n`);
+
+  // ── Domain drift ────────────────────────────────────────────────
+  if (temporalStore) {
+    try {
+      const q = require('../temporal/queries');
+      const drift = q.getArchitecturalDrift(temporalStore, { timeRange });
+      lines.push('## Domain drift');
+      lines.push(`Trend: **${drift.trend}**.`);
+      if (drift.byDomain && drift.byDomain.length > 0) {
+        lines.push('| Domain | Before | After | Δ |');
+        lines.push('|--------|-------:|------:|---|');
+        for (const d of drift.byDomain.slice(0, 10)) {
+          lines.push(`| ${d.domain} | ${d.before} | ${d.after} | ${d.delta > 0 ? '+' + d.delta : d.delta} |`);
+        }
+      }
+    } catch {}
+
+    // ── Hotspots ────────────────────────────────────────────────
+    try {
+      const q = require('../temporal/queries');
+      const h = q.getHotspotFiles(temporalStore, { timeRange, limit: 10 });
+      if (h.hotspots && h.hotspots.length > 0) {
+        lines.push('\n## Top hotspots');
+        lines.push('| File | Commits | Blast | Score |');
+        lines.push('|------|--------:|------:|------:|');
+        for (const x of h.hotspots) {
+          lines.push(`| ${x.file_path} | ${x.commit_count} | ${x.blast_radius} | ${x.score} |`);
+        }
+      }
+    } catch {}
+
+    // ── Events ──────────────────────────────────────────────────
+    try {
+      const q = require('../temporal/queries');
+      const e = q.getArchEvents(temporalStore, { timeRange, limit: 20 });
+      if (e.events && e.events.length > 0) {
+        lines.push('\n## Architectural events');
+        lines.push('| When | Severity | Kind | Target |');
+        lines.push('|------|----------|------|--------|');
+        for (const ev of e.events) {
+          const when = new Date(ev.ts).toISOString();
+          const target = ev.domain || ev.file_path || '';
+          lines.push(`| ${when} | ${ev.severity} | ${ev.kind} | ${target} |`);
+        }
+      }
+    } catch {}
+  } else {
+    lines.push('## Temporal data unavailable\n\nRun `carto temporal init` to enable drift, hotspot, and events sections.');
+  }
+
+  // ── Predictive risk top 10 ────────────────────────────────
+  try {
+    const { scoreFiles } = require('./risk-score');
+    const ranked = scoreFiles({ store, temporalStore, projectRoot }).slice(0, 10);
+    if (ranked.length > 0) {
+      lines.push('\n## Predicted-risk top 10');
+      lines.push('| File | Score |');
+      lines.push('|------|------:|');
+      for (const f of ranked) lines.push(`| ${f.path} | ${f.score} |`);
+    }
+  } catch {}
+
+  return lines.join('\n');
+}
+
+module.exports = { renderDriftDigest };

package/src/predictive/ownership.js

@@ -0,0 +1,145 @@
+'use strict';
+
+/**
+ * Team intelligence — implicit ownership detection + cross-team coupling.
+ *
+ * Detects "who touches this file most" from `git blame` and `git log`
+ * stats. Returns per-file and per-domain owners. From there we can
+ * surface cross-team coupling — Domain A is mostly touched by Alice but
+ * imports from Domain B, which Alice never touches → coordination cost.
+ *
+ * All git-shell-outs are wrapped: 10 s timeout, bounded output, errors
+ * fail soft to empty.
+ */
+
+const { execFileSync } = require('child_process');
+
+function gitLog(projectRoot, args, timeoutMs = 10_000) {
+  try {
+    return execFileSync('git', ['-C', projectRoot, ...args], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: timeoutMs,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * ownersForFile({ projectRoot, file }) → { file, top_author, authors: [{ name, lines }] }
+ *
+ * Uses `git blame --line-porcelain` to count lines per author. Fails soft
+ * to { file, authors: [] } when git is unavailable / file not tracked.
+ */
+function ownersForFile({ projectRoot, file }) {
+  const out = gitLog(projectRoot, ['blame', '--line-porcelain', '--', file]);
+  if (!out) return { file, authors: [], top_author: null };
+  const counts = new Map();
+  for (const line of out.split('\n')) {
+    if (line.startsWith('author ')) {
+      const name = line.slice('author '.length);
+      counts.set(name, (counts.get(name) || 0) + 1);
+    }
+  }
+  const authors = Array.from(counts.entries())
+    .map(([name, lines]) => ({ name, lines }))
+    .sort((a, b) => b.lines - a.lines);
+  return { file, authors, top_author: authors[0] ? authors[0].name : null };
+}
+
+/**
+ * ownersForDomain({ store, projectRoot, domain }) — aggregates per-file
+ * blame counts across the files in `domain`. Returns top authors.
+ */
+function ownersForDomain({ store, projectRoot, domain, maxFiles = 100 }) {
+  if (!store || !store.db) return { domain, authors: [], top_author: null };
+  const files = store.db.prepare(`
+    SELECT f.path FROM files f
+    JOIN domains d ON f.domain_id = d.id
+    WHERE d.name = ?
+    ORDER BY f.centrality DESC LIMIT ?
+  `).all(domain, maxFiles).map(r => r.path);
+  const counts = new Map();
+  for (const f of files) {
+    const r = ownersForFile({ projectRoot, file: f });
+    for (const a of r.authors) {
+      counts.set(a.name, (counts.get(a.name) || 0) + a.lines);
+    }
+  }
+  const authors = Array.from(counts.entries())
+    .map(([name, lines]) => ({ name, lines }))
+    .sort((a, b) => b.lines - a.lines);
+  return { domain, authors, top_author: authors[0] ? authors[0].name : null };
+}
+
+/**
+ * crossTeamCoupling({ store, projectRoot }) → warnings
+ *
+ * For each cross-domain edge in the graph, look up the owner of the
+ * source file and the owner of the target file. If they differ AND the
+ * source-side owner has never touched the target file, surface a
+ * coordination warning.
+ */
+function crossTeamCoupling({ store, projectRoot, maxEdges = 50 }) {
+  if (!store) return { warnings: [] };
+  const edges = (store.getCrossDomainDeps() || []).slice(0, maxEdges);
+  const ownerCache = new Map();
+  const warnings = [];
+
+  for (const e of edges) {
+    if (!ownerCache.has(e.from)) ownerCache.set(e.from, ownersForFile({ projectRoot, file: e.from }).top_author);
+    if (!ownerCache.has(e.to)) ownerCache.set(e.to, ownersForFile({ projectRoot, file: e.to }).top_author);
+    const fromOwner = ownerCache.get(e.from);
+    const toOwner = ownerCache.get(e.to);
+    if (fromOwner && toOwner && fromOwner !== toOwner) {
+      warnings.push({
+        from_file: e.from,
+        to_file: e.to,
+        from_domain: e.fromDomain || null,
+        to_domain: e.toDomain || null,
+        from_owner: fromOwner,
+        to_owner: toOwner,
+      });
+    }
+  }
+  return { warnings };
+}
+
+/**
+ * aiCostAttribution({ store, hours }) → per-client metrics
+ *
+ * Cheap proxy for "which AI client is creating the most cross-domain
+ * coupling?". Reads `ai_sessions.client_name` + joins to `decisions` and
+ * counts violations per client.
+ */
+function aiCostAttribution({ store, hours = 168 } = {}) {
+  if (!store || !store.db) return { clients: [] };
+  const since = Date.now() - hours * 60 * 60 * 1000;
+  const rows = store.db.prepare(`
+    SELECT s.client_name as client, COUNT(d.id) as decisions
+    FROM ai_sessions s
+    LEFT JOIN decisions d ON d.session_id = s.id
+    WHERE s.started_at >= ? OR d.ts >= ?
+    GROUP BY s.client_name
+  `).all(since, since);
+  const violations = store.db.prepare(`
+    SELECT s.client_name as client, COUNT(i.id) as violations
+    FROM ai_sessions s
+    LEFT JOIN interventions i ON i.session_id = s.id
+    WHERE s.started_at >= ? OR i.ts >= ?
+    GROUP BY s.client_name
+  `).all(since, since);
+  const vMap = new Map(violations.map(r => [r.client, r.violations]));
+  return {
+    hours,
+    clients: rows.map(r => ({
+      client: r.client || '(unknown)',
+      decisions: r.decisions || 0,
+      violations: vMap.get(r.client) || 0,
+    })).sort((a, b) => b.decisions - a.decisions),
+  };
+}
+
+module.exports = { ownersForFile, ownersForDomain, crossTeamCoupling, aiCostAttribution };

package/src/predictive/risk-score.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * Predictive risk scoring.
+ *
+ * Combines temporal + structural + intervention history into a single
+ * 0–1 score per file: P(this file causes the next incident).
+ *
+ * Inputs:
+ *   - blast_radius          how many transitive dependents (centrality column)
+ *   - commit_count          temporal churn
+ *   - cross_domain          is the file in cross-domain edges
+ *   - intervention_count    past HIGH-severity interventions
+ *   - test_present          has a detected test file
+ *
+ * Formula (additive, normalized to 0–1):
+ *   risk =   0.30 * normalized_blast
+ *         +  0.25 * normalized_churn
+ *         +  0.20 * cross_domain ? 1 : 0
+ *         +  0.15 * normalized_interventions
+ *         +  0.10 * test_present ? 0 : 1
+ *
+ * Each term capped at 1 before weighting. Final score is the weighted sum;
+ * naturally in [0, 1] because weights sum to 1.
+ */
+
+const path = require('path');
+
+const WEIGHTS = {
+  blast: 0.30,
+  churn: 0.25,
+  cross: 0.20,
+  intervention: 0.15,
+  noTest: 0.10,
+};
+
+function clampUnit(x) {
+  if (!Number.isFinite(x)) return 0;
+  return Math.max(0, Math.min(1, x));
+}
+
+/**
+ * scoreFiles({ store, temporalStore, projectRoot, files? }) → ranked Array
+ *
+ * If `files` is provided, scores only those; otherwise scores all files.
+ * Returns [{ path, score, components }] sorted by score DESC.
+ */
+function scoreFiles({ store, temporalStore = null, projectRoot, files = null }) {
+  if (!store || !store.db) return [];
+
+  // Normalization bases.
+  const maxBlast = (store.db.prepare('SELECT MAX(centrality) as m FROM files').get() || {}).m || 1;
+  const maxChurn = temporalStore && temporalStore.db
+    ? (temporalStore.db.prepare('SELECT MAX(commit_count) as m FROM file_churn').get() || {}).m || 1
+    : 1;
+
+  // Cross-domain edges set.
+  const crossSet = new Set();
+  try {
+    const rows = store.getCrossDomainDeps() || [];
+    for (const r of rows) crossSet.add(r.from);
+  } catch {}
+
+  // Intervention counts per file.
+  const ivCounts = new Map();
+  try {
+    const rows = store.db.prepare(`
+      SELECT file, COUNT(*) as c FROM interventions
+      WHERE file IS NOT NULL AND severity IN ('HIGH', 'critical')
+      GROUP BY file
+    `).all();
+    for (const r of rows) ivCounts.set(r.file, r.c);
+  } catch {}
+  const maxIv = Math.max(1, ...ivCounts.values());
+
+  // Tests-present set, via the files-without-tests detector.
+  const { filesWithoutTests } = require('../mcp/files-without-tests');
+  let withoutTests = new Set();
+  try {
+    const allFiles = files || store.db.prepare('SELECT path FROM files LIMIT 2000').all().map(r => r.path);
+    const r = filesWithoutTests(projectRoot, allFiles);
+    withoutTests = new Set(r.files || []);
+  } catch {}
+
+  // Score each file.
+  const rows = files
+    ? store.db.prepare(
+        `SELECT path, centrality FROM files WHERE path IN (${files.map(() => '?').join(',')})`
+      ).all(...files)
+    : store.db.prepare('SELECT path, centrality FROM files').all();
+
+  const out = [];
+  for (const r of rows) {
+    const blast = clampUnit((r.centrality || 0) / Math.max(1, maxBlast));
+    let churn = 0;
+    if (temporalStore && temporalStore.db) {
+      const ch = temporalStore.getFileChurn(r.path);
+      if (ch) churn = clampUnit((ch.commit_count || 0) / Math.max(1, maxChurn));
+    }
+    const cross = crossSet.has(r.path) ? 1 : 0;
+    const iv = clampUnit((ivCounts.get(r.path) || 0) / Math.max(1, maxIv));
+    const noTest = withoutTests.has(r.path) ? 1 : 0;
+
+    const score =
+      WEIGHTS.blast * blast +
+      WEIGHTS.churn * churn +
+      WEIGHTS.cross * cross +
+      WEIGHTS.intervention * iv +
+      WEIGHTS.noTest * noTest;
+
+    out.push({
+      path: r.path,
+      score: Math.round(score * 1000) / 1000,
+      components: { blast, churn, cross, intervention: iv, no_test: noTest },
+    });
+  }
+  out.sort((a, b) => b.score - a.score);
+  return out;
+}
+
+module.exports = { scoreFiles, WEIGHTS };

package/src/predictive/validate-change.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * validate_change — pre-write governance.
+ *
+ * `validateDiff` validates a unified diff after the edit. `validateChange`
+ * is the pre-write counterpart: given a file path plus the full proposed
+ * content, synthesize a minimal diff against current on-disk content and
+ * run the same validation pipeline. This is the API an IDE extension
+ * calls in `onWillSaveTextDocument`.
+ *
+ * Output: same shape as `validateDiff`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { validateDiff } = require('../mcp/validate');
+
+function validateChange({ store, projectRoot, file, content }) {
+  if (!store || !file || typeof content !== 'string') {
+    return { risk: 'SAFE', files_changed: [], violations: [], suggestions: [], reason: 'invalid_args' };
+  }
+
+  const full = path.resolve(projectRoot, file);
+  let prior = '';
+  try { prior = fs.readFileSync(full, 'utf-8'); } catch {}
+  // If file already at this content: SAFE no-op.
+  if (prior === content) {
+    return { risk: 'SAFE', files_changed: [], violations: [], suggestions: [], reason: 'no_change' };
+  }
+
+  // Synthesize a unified diff. The diff parser only needs added imports
+  // + line counts to compute risk; we don't need a fully-correct hunk header.
+  const diff = synthesizeDiff(file, prior, content);
+  return validateDiff({ store, diff });
+}
+
+/**
+ * synthesizeDiff(relPath, before, after) — produces a unified diff that
+ * `parseDiff` accepts. Hunk headers approximate the line counts.
+ */
+function synthesizeDiff(relPath, before, after) {
+  const beforeLines = (before || '').split('\n');
+  const afterLines = (after || '').split('\n');
+  const lines = [];
+  lines.push(`diff --git a/${relPath} b/${relPath}`);
+  lines.push(`--- a/${relPath}`);
+  lines.push(`+++ b/${relPath}`);
+  lines.push(`@@ -1,${beforeLines.length} +1,${afterLines.length} @@`);
+  for (const l of beforeLines) lines.push(`-${l}`);
+  for (const l of afterLines) lines.push(`+${l}`);
+  return lines.join('\n');
+}
+
+module.exports = { validateChange, synthesizeDiff };

package/src/store/store-adapter.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { SQLiteStore } = require('./sqlite-store');
-const { runSyncV2 } = require('./sync-v2');
+const { runSync } = require('./sync');
 
 /**
  * StoreAdapter — V1-compatible API wrapping SQLiteStore.
@@ -18,7 +18,7 @@ class StoreAdapter {
 
   /**
    * index(projectRoot, opts?)
-   * Opens the SQLite DB; runs runSyncV2 if DB is missing.
+   * Opens the SQLite DB; runs runSync if DB is missing.
    * opts.force — re-extract all files
    * opts.writeOutputs — if false, skip AGENTS.md + context file generation (default: false)
    */
@@ -28,7 +28,7 @@ class StoreAdapter {
     const dbExists = fs.existsSync(dbPath);
 
     if (!dbExists || opts.force) {
-      await runSyncV2({
+      await runSync({
         projectRoot,
         output: opts.writeOutputs ? path.resolve(projectRoot, 'AGENTS.md') : null,
       });