npm - carto-md - Versions diffs - 2.0.8 → 2.1.0 - Mend

carto-md 2.0.8 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (182) hide show

package/CONTRIBUTING.md +19 -15
package/README.md +203 -286
package/docs/anci/v0.1-DRAFT.md +420 -0
package/docs/api/README.md +99 -0
package/docs/api/did_we_discuss_this.md +34 -0
package/docs/api/dismiss_suggestion.md +34 -0
package/docs/api/explain_change_in_natural_language.md +33 -0
package/docs/api/find_consumers_of_api.md +34 -0
package/docs/api/get_action_patterns.md +32 -0
package/docs/api/get_active_drift.md +32 -0
package/docs/api/get_active_suggestions.md +25 -0
package/docs/api/get_ai_cost_attribution.md +32 -0
package/docs/api/get_arch_events.md +42 -0
package/docs/api/get_architectural_drift.md +37 -0
package/docs/api/get_architecture.md +25 -0
package/docs/api/get_blast_radius.md +34 -0
package/docs/api/get_canonical_pattern.md +39 -0
package/docs/api/get_change_plan.md +34 -0
package/docs/api/get_change_velocity.md +32 -0
package/docs/api/get_churn_vs_blast_radius.md +32 -0
package/docs/api/get_complexity_trend.md +39 -0
package/docs/api/get_context.md +34 -0
package/docs/api/get_conventions.md +32 -0
package/docs/api/get_cross_domain.md +25 -0
package/docs/api/get_cross_language_call_graph.md +25 -0
package/docs/api/get_cross_repo_blast_radius.md +34 -0
package/docs/api/get_cross_team_coupling.md +25 -0
package/docs/api/get_data_flow.md +33 -0
package/docs/api/get_dead_code_with_confidence.md +32 -0
package/docs/api/get_decision_log.md +32 -0
package/docs/api/get_dependency_surface.md +25 -0
package/docs/api/get_domain.md +34 -0
package/docs/api/get_domain_evolution.md +39 -0
package/docs/api/get_domain_health.md +32 -0
package/docs/api/get_domains_list.md +25 -0
package/docs/api/get_drift_digest.md +32 -0
package/docs/api/get_env_vars.md +32 -0
package/docs/api/get_evolution_delta.md +36 -0
package/docs/api/get_file_ownership.md +33 -0
package/docs/api/get_file_summary.md +34 -0
package/docs/api/get_high_impact_files.md +32 -0
package/docs/api/get_hot_in_prod_no_tests.md +34 -0
package/docs/api/get_hotspot_files.md +37 -0
package/docs/api/get_iac_resources.md +25 -0
package/docs/api/get_interface_contract.md +33 -0
package/docs/api/get_intervention_history.md +32 -0
package/docs/api/get_invariants.md +37 -0
package/docs/api/get_llm_enrichment.md +33 -0
package/docs/api/get_microservice_cut_points.md +32 -0
package/docs/api/get_microservices_migration_cut_points.md +25 -0
package/docs/api/get_minimal_context_for_intent.md +39 -0
package/docs/api/get_models.md +32 -0
package/docs/api/get_neighbors.md +39 -0
package/docs/api/get_org_architecture.md +25 -0
package/docs/api/get_org_domain_mapping.md +25 -0
package/docs/api/get_pending_decisions.md +32 -0
package/docs/api/get_predictive_risk.md +32 -0
package/docs/api/get_progressive_disclosure_tree.md +25 -0
package/docs/api/get_recent_decisions.md +37 -0
package/docs/api/get_risk_weighted_blast_radius.md +32 -0
package/docs/api/get_routes.md +25 -0
package/docs/api/get_safety_checklist.md +33 -0
package/docs/api/get_semantic_diff.md +34 -0
package/docs/api/get_service_boundary_violations.md +25 -0
package/docs/api/get_service_dependency_graph.md +25 -0
package/docs/api/get_session_context.md +32 -0
package/docs/api/get_similar_patterns.md +39 -0
package/docs/api/get_stale_docs.md +25 -0
package/docs/api/get_structure.md +25 -0
package/docs/api/get_temporal_context.md +34 -0
package/docs/api/get_test_coverage_map.md +25 -0
package/docs/api/get_token_budget_report.md +36 -0
package/docs/api/get_upgrade_risk.md +25 -0
package/docs/api/get_working_memory.md +25 -0
package/docs/api/ingest_otlp_traces.md +34 -0
package/docs/api/scaffold_for_intent.md +34 -0
package/docs/api/search_routes.md +34 -0
package/docs/api/simulate_change_impact.md +37 -0
package/docs/api/validate_change.md +39 -0
package/docs/api/validate_diff.md +39 -0
package/docs/concepts/anci.md +87 -0
package/docs/concepts/blast-radius.md +66 -0
package/docs/concepts/domains.md +91 -0
package/docs/concepts/import-graph.md +102 -0
package/docs/concepts/mcp-integration.md +148 -0
package/docs/guides/adding-feature-safely.md +101 -0
package/docs/guides/ci-integration.md +175 -0
package/docs/guides/monorepo-setup.md +121 -0
package/docs/guides/onboarding-new-engineer.md +121 -0
package/docs/guides/pre-merge-review.md +139 -0
package/docs/migration/v1-to-v2.md +110 -0
package/docs/quickstart.md +95 -0
package/docs/scale.md +129 -0
package/docs/troubleshooting.md +180 -0
package/package.json +12 -5
package/scripts/gen-api-docs.js +170 -0
package/scripts/postinstall.js +391 -24
package/src/acp/agent.js +83 -11
package/src/acp/config.js +64 -0
package/src/acp/persistence.js +146 -0
package/src/acp/providers/anthropic.js +179 -27
package/src/acp/providers/index.js +15 -2
package/src/acp/providers/openai.js +164 -38
package/src/acp/providers/sse.js +82 -0
package/src/acp/safety.js +128 -0
package/src/acp/session.js +73 -0
package/src/adjacent/call-graph.js +170 -0
package/src/adjacent/iac.js +167 -0
package/src/adjacent/llm-enrich.js +35 -0
package/src/adjacent/runtime.js +216 -0
package/src/adjacent/semantic-diff.js +143 -0
package/src/agents/leiden.js +4 -4
package/src/agents/scan-structure.js +2 -2
package/src/ai/context-builder.js +215 -0
package/src/ai/retrieval/lexical.js +122 -0
package/src/ai/retrieval/rrf.js +121 -0
package/src/ai/retrieval/semantic.js +35 -0
package/src/ai/retrieval/structural.js +82 -0
package/src/ai/tools.js +423 -0
package/src/anci/consumer.js +305 -0
package/src/anci/deserialize.js +160 -0
package/src/anci/emit.js +85 -0
package/src/anci/serialize.js +264 -0
package/src/anci/yaml.js +401 -0
package/src/bitmap/index.js +1 -1
package/src/bitmap/tools.js +2 -2
package/src/brain/conventions/index.js +185 -0
package/src/brain/index.js +31 -0
package/src/brain/invariants/index.js +252 -0
package/src/brain/procedural/index.js +181 -0
package/src/brain/suggestions/index.js +153 -0
package/src/brain/working/index.js +170 -0
package/src/cli/anci.js +237 -0
package/src/cli/check.js +47 -1
package/src/cli/diff.js +83 -0
package/src/cli/doctor.js +270 -0
package/src/cli/explain.js +61 -0
package/src/cli/index.js +115 -0
package/src/cli/init.js +144 -6
package/src/cli/inspect.js +1 -1
package/src/cli/org.js +172 -0
package/src/cli/pr-impact.js +554 -0
package/src/cli/serve.js +1 -1
package/src/cli/status.js +211 -0
package/src/cli/sync.js +2 -2
package/src/cli/temporal.js +188 -0
package/src/cli/validate.js +201 -0
package/src/cli/watch.js +4 -4
package/src/cli/why.js +101 -0
package/src/extractors/frameworks.js +236 -0
package/src/extractors/languages/dart.js +138 -0
package/src/extractors/languages/go.js +11 -1
package/src/extractors/languages/javascript.js +16 -6
package/src/extractors/languages/kotlin.js +169 -0
package/src/extractors/languages/php.js +195 -0
package/src/extractors/languages/python.js +12 -1
package/src/extractors/languages/swift.js +140 -0
package/src/extractors/languages/typescript.js +15 -2
package/src/extractors/plugin-api.js +102 -0
package/src/mcp/change-plan.js +8 -8
package/src/mcp/files-without-tests.js +285 -0
package/src/mcp/middleware/index.js +451 -0
package/src/mcp/server.js +2292 -0
package/src/mcp/validate.js +1 -1
package/src/org/detect.js +262 -0
package/src/org/queries.js +144 -0
package/src/org/store.js +173 -0
package/src/org/sync.js +106 -0
package/src/predictive/cut-points.js +83 -0
package/src/predictive/drift-digest.js +88 -0
package/src/predictive/ownership.js +145 -0
package/src/predictive/risk-score.js +121 -0
package/src/predictive/validate-change.js +55 -0
package/src/store/store-adapter.js +3 -3
package/src/store/{sync-v2.js → sync.js} +105 -16
package/src/temporal/backfill.js +211 -0
package/src/temporal/delta.js +85 -0
package/src/temporal/events.js +180 -0
package/src/temporal/queries.js +358 -0
package/src/temporal/snapshot.js +151 -0
package/src/temporal/store.js +400 -0
package/src/mcp/server-v2.js +0 -986

package/src/cli/pr-impact.js ADDED Viewed

@@ -0,0 +1,554 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * `carto pr-impact` — pull-request-shaped impact report.
+ *
+ * Computes the impact of a pull request's diff against the current
+ * project graph and renders either:
+ *   - Markdown wrapped in a `<!-- carto-impact-report -->` HTML marker
+ *     so the GitHub Action can detect-and-update sticky comments.
+ *   - JSON for programmatic consumers (CI dashboards, custom workflows).
+ *
+ * Composition:
+ *   1. `git diff --unified=3 <base>...<head>` → unified diff text.
+ *   2. `validateDiff(store, sidecar, diff)` → violations, blast radius,
+ *      risk roll-up. (Same engine the MCP `validate_diff` tool uses.)
+ *   3. Per-file `StoreAdapter.getBlastRadius(file)` → routes affected,
+ *      domains impacted (validateDiff returns counts; the comment
+ *      template wants the actual route list).
+ *   4. Render.
+ *
+ * Exit code:
+ *   - 0 by default (the comment surfaces the risk; failing the build
+ *     is opt-in).
+ *   - Non-zero when `--fail-on HIGH|MEDIUM` is supplied AND the rolled-up
+ *     risk meets or exceeds the threshold.
+ *
+ * The command is read-only: it does not write to the SQLite store and
+ * does not record episodic-memory rows — those persistence concerns
+ * belong to the MCP `validate_diff` tool, not the CI surface.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { SQLiteStore } = require('../store/sqlite-store');
+const { StoreAdapter } = require('../store/store-adapter');
+const { ensureBitmapFresh } = require('../bitmap/index');
+const { validateDiff } = require('../mcp/validate');
+const bitmapTools = require('../bitmap/tools');
+const { filesWithoutTests } = require('../mcp/files-without-tests');
+const MARKER = '<!-- carto-impact-report -->';
+function parseArgs(argv) {
+  const args = {
+    base: null,
+    head: 'HEAD',
+    format: 'markdown',
+    failOn: null,           // null | 'HIGH' | 'MEDIUM' | 'LOW'
+    diffFile: null,         // for tests: read diff from a file instead of git
+    projectRoot: process.cwd(),
+    help: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case '--base':       args.base = argv[++i]; break;
+      case '--head':       args.head = argv[++i]; break;
+      case '--format':     args.format = argv[++i]; break;
+      case '--fail-on':    args.failOn = (argv[++i] || '').toUpperCase(); break;
+      case '--diff-file':  args.diffFile = argv[++i]; break;
+      case '--project':    args.projectRoot = path.resolve(argv[++i]); break;
+      case '--help':
+      case '-h':           args.help = true; break;
+      default:
+        // Unknown flag — fail loudly so typos in CI are visible.
+        if (a.startsWith('--')) {
+          throw new Error(`unknown flag: ${a}`);
+        }
+    }
+  }
+  if (!['markdown', 'json'].includes(args.format)) {
+    throw new Error(`--format must be 'markdown' or 'json' (got '${args.format}')`);
+  }
+  if (args.failOn && !['HIGH', 'MEDIUM', 'LOW'].includes(args.failOn)) {
+    throw new Error(`--fail-on must be HIGH | MEDIUM | LOW (got '${args.failOn}')`);
+  }
+  return args;
+}
+function printUsage() {
+  process.stdout.write(`
+Usage: carto pr-impact [options]
+Computes the impact of a PR's diff against the current carto index and
+renders a markdown or JSON report. Designed for the carto GitHub Action
+but usable standalone.
+Options:
+  --base <ref>          Git ref the PR branched from (e.g. origin/main)
+  --head <ref>          Git ref of the PR head (default: HEAD)
+  --format <fmt>        markdown (default) | json
+  --fail-on <severity>  Exit non-zero if risk >= severity (HIGH | MEDIUM | LOW)
+  --diff-file <path>    Read diff text from a file instead of running git diff
+                        (primarily for testing)
+  --project <path>      Project root (default: cwd)
+  --help, -h            Show this help
+Exit codes:
+  0  Normal — comment rendered.
+  1  Misuse, missing index, or git failure.
+  2  --fail-on threshold tripped.
+`);
+}
+/**
+ * runGitDiff(projectRoot, base, head) → diffText
+ *
+ * Captures the unified diff between two refs. Three-dot syntax (`base...head`)
+ * matches what GitHub uses for PR diffs — only the changes introduced on
+ * the head branch since it diverged from base, not changes that landed on
+ * base in the meantime.
+ */
+function runGitDiff(projectRoot, base, head) {
+  if (!base) {
+    throw new Error('--base is required (or use --diff-file to supply a diff manually)');
+  }
+  let out;
+  try {
+    out = execFileSync('git', ['diff', '--unified=3', `${base}...${head}`], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024, // 64 MB — large PRs are rare but real
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (err) {
+    const stderr = (err.stderr || '').toString().trim();
+    throw new Error(
+      `git diff ${base}...${head} failed${stderr ? `: ${stderr}` : ''}`
+    );
+  }
+  return out;
+}
+const RISK_BADGE = {
+  HIGH:   '🔴 HIGH',
+  MEDIUM: '🟡 MEDIUM',
+  LOW:    '🟢 LOW',
+  SAFE:   '✅ SAFE',
+};
+const RISK_RANK = { SAFE: 0, LOW: 1, MEDIUM: 2, HIGH: 3 };
+/**
+ * collectImpact(projectRoot, diffText) → { result, perFile, domains, highImpact }
+ *
+ * - `result`     — full validateDiff(...) output (violations + blast
+ *                  radius + risk).
+ * - `perFile`    — Map<path, { blastRadius, routes, domains }> for files
+ *                  in the diff. Skipped for files not in the index
+ *                  (pure adds, renames where the new path didn't exist
+ *                  at sync time).
+ * - `domains`    — sorted Array<string> of all domains touched by the
+ *                  changed files (used for the headline sentence).
+ * - `highImpact` — { file, dependents } for the changed file with the
+ *                  most direct dependents, or null if all are 0.
+ */
+function collectImpact(projectRoot, diffText) {
+  const cartoDir = path.join(projectRoot, '.carto');
+  const dbPath = path.join(cartoDir, 'carto.db');
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(
+      `No carto index at ${dbPath}. Run \`carto init\` (or \`carto sync\` ` +
+      `if the index already exists) before \`carto pr-impact\`.`
+    );
+  }
+  const store = new SQLiteStore(projectRoot);
+  store.open({ readonly: true });
+  let sidecar = null;
+  try {
+    sidecar = ensureBitmapFresh(cartoDir, store);
+  } catch (err) {
+    process.stderr.write(
+      `[CARTO] bitmap unavailable, validation will use SQLite-only path: ` +
+      `${err.message || err}\n`
+    );
+  }
+  const result = validateDiff(store, sidecar, diffText);
+  // Per-file rich detail via StoreAdapter (matches what `carto impact <file>`
+  // returns — routes, domain). We open a second adapter pointed at the same
+  // DB rather than re-implementing the formatter here.
+  const adapter = new StoreAdapter();
+  // Skip the indexer — we know the DB exists. Open the store directly.
+  adapter._store = store;
+  adapter._projectRoot = projectRoot;
+  const perFile = new Map();
+  const domainSet = new Set();
+  let highImpact = null;
+  for (const f of result.diff) {
+    if (f.kind === 'delete') continue;
+    let br = null;
+    try {
+      br = adapter.getBlastRadius(f.path);
+    } catch {
+      // File not in index — most often a pure add. Leave perFile entry
+      // off the map; renderer skips files it doesn't have detail for.
+    }
+    if (!br) continue;
+    perFile.set(f.path, {
+      blastRadius: br.dependentFiles.length,
+      directlyAffected: br.directlyAffected.files,
+      routes: br.routesImpacted,
+      domains: br.domainsImpacted,
+    });
+    for (const d of br.domainsImpacted) domainSet.add(d);
+    if (
+      !highImpact ||
+      br.directlyAffected.files > highImpact.dependents
+    ) {
+      highImpact = {
+        file: f.path,
+        dependents: br.directlyAffected.files,
+      };
+    }
+  }
+  store.close();
+  // Files-without-tests metric.
+  //
+  // We compute it over the *union blast radius* (every changed file
+  // plus every transitive dependent) — that's the set of files at risk
+  // of regression. The detector is local-filesystem-walk only, so it
+  // works on PRs touching files that aren't in the index yet.
+  const seedPaths = result.diff
+    .filter((f) => f.kind !== 'delete')
+    .map((f) => f.path);
+  let unionFiles = seedPaths.slice();
+  if (sidecar && seedPaths.length > 0) {
+    try {
+      const sim = bitmapTools.simulateChangeImpact(sidecar, seedPaths);
+      // sim.files is [{ file, hop_distance }]. Combine with seeds; dedupe via Set.
+      const set = new Set(seedPaths);
+      for (const row of sim.files || []) set.add(row.file);
+      unionFiles = [...set];
+    } catch {
+      // Bitmap missing — fall through with seedPaths only.
+    }
+  }
+  const filesWithoutTestsReport = filesWithoutTests(projectRoot, unionFiles);
+  return {
+    result,
+    perFile,
+    domains: [...domainSet].sort(),
+    highImpact: highImpact && highImpact.dependents > 0 ? highImpact : null,
+    filesWithoutTests: filesWithoutTestsReport,
+  };
+}
+/**
+ * renderMarkdown(impact) → string
+ *
+ * Renders the PR comment body. Wraps the entire body in a
+ * `<!-- carto-impact-report -->` HTML comment marker so the GitHub
+ * Action can find-and-update its previous comment instead of posting
+ * a duplicate every commit.
+ *
+ * Sections:
+ *   - Headline sentence ("This PR touches X and Y domains.")
+ *   - Metric table (Risk · Blast radius · Files changed · Violations
+ *     introduced · High-impact file)
+ *   - Affected routes (collapsible) — only if any
+ *   - Cross-domain violations (collapsible) — only if any
+ *   - Suggestions (collapsible) — only if any
+ */
+function renderMarkdown(impact) {
+  const { result, perFile, domains, highImpact, filesWithoutTests: fwt } = impact;
+  const out = [];
+  out.push(MARKER);
+  out.push('## 🗺️ Carto Impact Report');
+  out.push('');
+  if (result.diff.length === 0) {
+    out.push('_No file changes detected in this diff._');
+    out.push('');
+    return out.join('\n');
+  }
+  // Headline sentence.
+  if (domains.length === 0) {
+    out.push(`This PR touches **${result.diff.length} file(s)** in unmapped domains.`);
+  } else if (domains.length === 1) {
+    out.push(`This PR touches the **${domains[0]}** domain.`);
+  } else if (domains.length === 2) {
+    out.push(`This PR touches **${domains[0]}** and **${domains[1]}** domains.`);
+  } else {
+    const head = domains.slice(0, -1).map((d) => `**${d}**`).join(', ');
+    const tail = `**${domains[domains.length - 1]}**`;
+    out.push(`This PR touches ${head}, and ${tail} domains.`);
+  }
+  out.push('');
+  // Metric table.
+  const crossDomainCount = result.violations.filter(
+    (v) => v.kind === 'cross_domain'
+  ).length;
+  out.push('| Metric | Value |');
+  out.push('|--------|-------|');
+  out.push(`| **Risk** | ${RISK_BADGE[result.risk] || result.risk} |`);
+  out.push(`| Blast radius (union) | ${result.blast_radius.union} files |`);
+  out.push(`| Files changed | ${result.diff.length} |`);
+  out.push(`| Cross-domain violations introduced | ${crossDomainCount} |`);
+  if (fwt && typeof fwt.count === 'number') {
+    // Only render the row when the detector actually considered files
+    // (skip when nothing testable was in the union — keeps the table
+    // honest for non-source PRs).
+    if (fwt.considered > 0) {
+      out.push(`| Files without tests in blast radius | ${fwt.count} of ${fwt.considered} |`);
+    }
+  }
+  if (highImpact) {
+    out.push(
+      `| High-impact file changed | \`${highImpact.file}\` (${highImpact.dependents} direct dependents) |`
+    );
+  }
+  out.push('');
+  // Routes section — flatten per-file routes, dedupe by method+path.
+  const routeRows = [];
+  const seenRoutes = new Set();
+  for (const detail of perFile.values()) {
+    for (const r of detail.routes || []) {
+      const key = `${r.method} ${r.path}`;
+      if (seenRoutes.has(key)) continue;
+      seenRoutes.add(key);
+      routeRows.push(r);
+    }
+  }
+  if (routeRows.length > 0) {
+    out.push(`<details>`);
+    out.push(`<summary>Affected routes (${routeRows.length})</summary>`);
+    out.push('');
+    for (const r of routeRows) {
+      out.push(`- \`${r.method} ${r.path}\` — risk: ${r.risk}`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // Cross-domain violations.
+  const crossViolations = result.violations.filter(
+    (v) => v.kind === 'cross_domain'
+  );
+  if (crossViolations.length > 0) {
+    out.push(`<details>`);
+    out.push(
+      `<summary>Cross-domain violations (${crossViolations.length})</summary>`
+    );
+    out.push('');
+    for (const v of crossViolations) {
+      out.push(
+        `- \`${v.file}\` now imports from \`${v.toFile}\` (${v.fromDomain}→${v.toDomain})`
+      );
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // High-blast violations as a separate section so reviewers see them
+  // even when no cross-domain edges exist.
+  const blastViolations = result.violations.filter(
+    (v) => v.kind === 'high_blast'
+  );
+  if (blastViolations.length > 0) {
+    out.push(`<details>`);
+    out.push(
+      `<summary>High-blast files modified (${blastViolations.length})</summary>`
+    );
+    out.push('');
+    for (const v of blastViolations) {
+      out.push(`- \`${v.file}\` — ${v.blast_radius} dependents (${v.severity})`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // Suggestions.
+  if (result.suggestions.length > 0) {
+    out.push(`<details>`);
+    out.push(`<summary>Suggestions (${result.suggestions.length})</summary>`);
+    out.push('');
+    for (const s of result.suggestions) {
+      out.push(`- ${s.message}`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  // Files without tests in blast radius — collapsible list.
+  // Show up to 10 names; the metric row already shows the total.
+  if (fwt && fwt.count > 0) {
+    out.push(`<details>`);
+    out.push(`<summary>Files without tests in blast radius (${fwt.count})</summary>`);
+    out.push('');
+    const shown = fwt.files.slice(0, 10);
+    for (const file of shown) {
+      out.push(`- \`${file}\``);
+    }
+    if (fwt.files.length > shown.length) {
+      out.push(`- _… and ${fwt.files.length - shown.length} more_`);
+    }
+    out.push('');
+    out.push(`</details>`);
+    out.push('');
+  }
+  out.push(`<sub>Generated by [carto-md](https://www.npmjs.com/package/carto-md).</sub>`);
+  return out.join('\n');
+}
+/**
+ * renderJson(impact) → object
+ *
+ * Stable contract for programmatic consumers. Locked-in shape (any
+ * additions go at the end of the object, no key removals before a
+ * major version bump):
+ *
+ *   {
+ *     marker:                 string,
+ *     risk:                   'SAFE' | 'LOW' | 'MEDIUM' | 'HIGH',
+ *     files_changed:          number,
+ *     blast_radius_union:     number,
+ *     domains_touched:        string[],
+ *     high_impact_file:       { file, dependents } | null,
+ *     violations:             [{ kind, severity, file, message, ... }],
+ *     suggestions:            [{ kind, file, message, ... }],
+ *     per_file: {
+ *       [path]: {
+ *         blast_radius:        number,
+ *         directly_affected:   number,
+ *         domains:             string[],
+ *         routes:              [{ method, path, risk }],
+ *       }
+ *     }
+ *   }
+ */
+function renderJson(impact) {
+  const { result, perFile, domains, highImpact, filesWithoutTests: fwt } = impact;
+  const per_file = {};
+  for (const [path_, detail] of perFile) {
+    per_file[path_] = {
+      blast_radius: detail.blastRadius,
+      directly_affected: detail.directlyAffected,
+      domains: detail.domains,
+      routes: detail.routes,
+    };
+  }
+  return {
+    marker: MARKER,
+    risk: result.risk,
+    files_changed: result.diff.length,
+    blast_radius_union: result.blast_radius.union,
+    domains_touched: domains,
+    high_impact_file: highImpact,
+    violations: result.violations,
+    suggestions: result.suggestions,
+    per_file,
+    // Files-without-tests metric. Always present so the JSON shape is
+    // stable; values are null/0 when not computable.
+    files_without_tests: fwt
+      ? { count: fwt.count, considered: fwt.considered, files: fwt.files }
+      : { count: 0, considered: 0, files: [] },
+  };
+}
+/**
+ * Decide exit code based on --fail-on threshold.
+ *   - failOn null → always 0
+ *   - failOn set  → 2 if risk >= threshold, else 0
+ */
+function decideExitCode(risk, failOn) {
+  if (!failOn) return 0;
+  return RISK_RANK[risk] >= RISK_RANK[failOn] ? 2 : 0;
+}
+/**
+ * run({ argv, stdout, stderr }) → exitCode
+ *
+ * Pure function — no side effects on `process`. Tests pass an in-memory
+ * argv + capture stdout via a writable stream.
+ */
+function run({ argv, stdout, stderr } = {}) {
+  argv = argv || process.argv.slice(3);
+  stdout = stdout || process.stdout;
+  stderr = stderr || process.stderr;
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  if (args.help) {
+    printUsage();
+    return 0;
+  }
+  let diffText;
+  try {
+    if (args.diffFile) {
+      diffText = fs.readFileSync(args.diffFile, 'utf8');
+    } else {
+      diffText = runGitDiff(args.projectRoot, args.base, args.head);
+    }
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  let impact;
+  try {
+    impact = collectImpact(args.projectRoot, diffText);
+  } catch (err) {
+    stderr.write(`[CARTO] ${err.message}\n`);
+    return 1;
+  }
+  if (args.format === 'json') {
+    stdout.write(JSON.stringify(renderJson(impact), null, 2) + '\n');
+  } else {
+    stdout.write(renderMarkdown(impact) + '\n');
+  }
+  return decideExitCode(impact.result.risk, args.failOn);
+}
+module.exports = {
+  run,
+  // Exported for tests:
+  parseArgs,
+  collectImpact,
+  renderMarkdown,
+  renderJson,
+  decideExitCode,
+  MARKER,
+};
+// CLI entry — when invoked directly (not required for tests):
+if (require.main === module) {
+  process.exit(run());
+}

package/src/cli/serve.js CHANGED Viewed

@@ -18,7 +18,7 @@ function run(projectRoot) {
   }
   console.error('[CARTO] MCP server starting...');
-  require('../mcp/server-v2');
+  require('../mcp/server');
 }
 module.exports = { run };