@neat.is/core 0.2.9 → 0.2.10

package/dist/cli.cjs

@@ -3908,7 +3908,244 @@ var import_chokidar = __toESM(require("chokidar"), 1);
 init_cjs_shims();
 var import_fastify = __toESM(require("fastify"), 1);
 var import_cors = __toESM(require("@fastify/cors"), 1);
-var import_types19 = require("@neat.is/types");
+var import_types20 = require("@neat.is/types");
+
+// src/divergences.ts
+init_cjs_shims();
+var import_types18 = require("@neat.is/types");
+function bucketKey(source, target, type) {
+  return `${type}|${source}|${target}`;
+}
+function bucketEdges(graph) {
+  const buckets = /* @__PURE__ */ new Map();
+  graph.forEachEdge((id, attrs) => {
+    const e = attrs;
+    const parsed = (0, import_types18.parseEdgeId)(id);
+    const provenance = parsed?.provenance ?? e.provenance;
+    const key = bucketKey(e.source, e.target, e.type);
+    const cur = buckets.get(key) ?? { source: e.source, target: e.target, type: e.type };
+    switch (provenance) {
+      case import_types18.Provenance.EXTRACTED:
+        cur.extracted = e;
+        break;
+      case import_types18.Provenance.OBSERVED:
+        cur.observed = e;
+        break;
+      case import_types18.Provenance.INFERRED:
+        cur.inferred = e;
+        break;
+      case import_types18.Provenance.FRONTIER:
+        cur.frontier = e;
+        break;
+      default:
+        if (e.provenance === import_types18.Provenance.STALE) cur.stale = e;
+    }
+    buckets.set(key, cur);
+  });
+  return buckets;
+}
+function nodeIsFrontier(graph, nodeId) {
+  if (!graph.hasNode(nodeId)) return false;
+  const attrs = graph.getNodeAttributes(nodeId);
+  return attrs.type === import_types18.NodeType.FrontierNode;
+}
+function hasAnyObservedFromSource(graph, sourceId) {
+  if (!graph.hasNode(sourceId)) return false;
+  for (const edgeId of graph.outboundEdges(sourceId)) {
+    const e = graph.getEdgeAttributes(edgeId);
+    if (e.provenance === import_types18.Provenance.OBSERVED) return true;
+  }
+  return false;
+}
+function clampConfidence(n) {
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+function reasonForMissingObserved(source, target, type) {
+  return `Code declares ${source} \u2192 ${target} (${type}) but no production traffic has been observed for this edge.`;
+}
+function reasonForMissingExtracted(source, target, type) {
+  return `Production observed ${source} \u2192 ${target} (${type}) but static analysis did not surface this edge.`;
+}
+var RECOMMENDATION_MISSING_OBSERVED = "Verify the code path is exercised in production; check feature flags or conditional branches that might gate the call.";
+var RECOMMENDATION_MISSING_EXTRACTED = "Likely dynamic dispatch, reflection, or a coverage gap in tree-sitter extraction. Consider an `aliases` entry on the source service or file an extractor issue.";
+var RECOMMENDATION_HOST_MISMATCH = "Check environment-specific config overrides \u2014 the runtime host differs from what static configuration declares.";
+function detectMissingDivergences(graph, bucket) {
+  const out = [];
+  if (bucket.extracted && !bucket.observed) {
+    if (!nodeIsFrontier(graph, bucket.target)) {
+      const sourceHasTraffic = hasAnyObservedFromSource(graph, bucket.source);
+      out.push({
+        type: "missing-observed",
+        source: bucket.source,
+        target: bucket.target,
+        edgeType: bucket.type,
+        extracted: bucket.extracted,
+        confidence: sourceHasTraffic ? 1 : 0.5,
+        reason: reasonForMissingObserved(bucket.source, bucket.target, bucket.type),
+        recommendation: RECOMMENDATION_MISSING_OBSERVED
+      });
+    }
+  }
+  if (bucket.observed && !bucket.extracted) {
+    const cascaded = clampConfidence(confidenceForEdge(bucket.observed));
+    out.push({
+      type: "missing-extracted",
+      source: bucket.source,
+      target: bucket.target,
+      edgeType: bucket.type,
+      observed: bucket.observed,
+      confidence: cascaded,
+      reason: reasonForMissingExtracted(bucket.source, bucket.target, bucket.type),
+      recommendation: RECOMMENDATION_MISSING_EXTRACTED
+    });
+  }
+  return out;
+}
+function declaredHostFor(svc) {
+  const raw = svc.dbConnectionTarget?.trim();
+  if (!raw) return null;
+  const colon = raw.lastIndexOf(":");
+  if (colon === -1) return raw;
+  const port = raw.slice(colon + 1);
+  if (/^\d+$/.test(port)) return raw.slice(0, colon);
+  return raw;
+}
+function hasExtractedConfiguredBy(graph, svcId) {
+  for (const edgeId of graph.outboundEdges(svcId)) {
+    const e = graph.getEdgeAttributes(edgeId);
+    if (e.type === import_types18.EdgeType.CONFIGURED_BY && e.provenance === import_types18.Provenance.EXTRACTED) {
+      return true;
+    }
+  }
+  return false;
+}
+function detectHostMismatch(graph, svcId, svc) {
+  const declaredHost = declaredHostFor(svc);
+  if (!declaredHost) return [];
+  if (!hasExtractedConfiguredBy(graph, svcId)) return [];
+  const out = [];
+  for (const edgeId of graph.outboundEdges(svcId)) {
+    const edge = graph.getEdgeAttributes(edgeId);
+    if (edge.type !== import_types18.EdgeType.CONNECTS_TO) continue;
+    if (edge.provenance !== import_types18.Provenance.OBSERVED) continue;
+    const target = graph.getNodeAttributes(edge.target);
+    if (target.type !== import_types18.NodeType.DatabaseNode) continue;
+    const observedHost = target.host?.trim();
+    if (!observedHost) continue;
+    if (observedHost === declaredHost) continue;
+    out.push({
+      type: "host-mismatch",
+      source: svcId,
+      target: edge.target,
+      extractedHost: declaredHost,
+      observedHost,
+      confidence: clampConfidence(confidenceForEdge(edge)),
+      reason: `Config declares ${svcId} connects to ${declaredHost}; production connects to ${observedHost}.`,
+      recommendation: RECOMMENDATION_HOST_MISMATCH
+    });
+  }
+  return out;
+}
+function detectCompatDivergences(graph, svcId, svc) {
+  const out = [];
+  const deps = svc.dependencies ?? {};
+  for (const edgeId of graph.outboundEdges(svcId)) {
+    const edge = graph.getEdgeAttributes(edgeId);
+    if (edge.type !== import_types18.EdgeType.CONNECTS_TO) continue;
+    if (edge.provenance !== import_types18.Provenance.OBSERVED) continue;
+    const target = graph.getNodeAttributes(edge.target);
+    if (target.type !== import_types18.NodeType.DatabaseNode) continue;
+    for (const pair of compatPairs()) {
+      if (pair.engine !== target.engine) continue;
+      const declared = deps[pair.driver];
+      if (!declared) continue;
+      const result = checkCompatibility(
+        pair.driver,
+        declared,
+        target.engine,
+        target.engineVersion
+      );
+      if (!result.compatible && result.reason) {
+        out.push({
+          type: "version-mismatch",
+          source: svcId,
+          target: edge.target,
+          extractedVersion: declared,
+          observedVersion: target.engineVersion,
+          compatibility: "incompatible",
+          confidence: 1,
+          reason: result.reason,
+          recommendation: result.minDriverVersion ? `Upgrade ${pair.driver} to >= ${result.minDriverVersion}.` : `Update the ${pair.driver} driver to a version compatible with ${target.engine} ${target.engineVersion}.`
+        });
+      }
+    }
+    for (const rule of deprecatedApis()) {
+      const declared = deps[rule.package];
+      if (!declared) continue;
+      const result = checkDeprecatedApi(rule, declared);
+      if (!result.compatible && result.reason) {
+        const ruleRef = {
+          kind: rule.kind ?? "deprecated-api",
+          reason: result.reason,
+          package: rule.package
+        };
+        out.push({
+          type: "compat-violation",
+          source: svcId,
+          target: edge.target,
+          rule: ruleRef,
+          observed: edge,
+          confidence: 1,
+          reason: result.reason,
+          recommendation: `Replace deprecated ${rule.package}@${declared} with a supported version.`
+        });
+      }
+    }
+  }
+  return out;
+}
+function involvesNode(d, nodeId) {
+  return d.source === nodeId || d.target === nodeId;
+}
+function computeDivergences(graph, opts = {}) {
+  const all = [];
+  const buckets = bucketEdges(graph);
+  for (const bucket of buckets.values()) {
+    for (const d of detectMissingDivergences(graph, bucket)) all.push(d);
+  }
+  graph.forEachNode((nodeId, attrs) => {
+    const n = attrs;
+    if (n.type !== import_types18.NodeType.ServiceNode) return;
+    const svc = n;
+    for (const d of detectHostMismatch(graph, nodeId, svc)) all.push(d);
+    for (const d of detectCompatDivergences(graph, nodeId, svc)) all.push(d);
+  });
+  let filtered = all;
+  if (opts.type) {
+    const allowed = opts.type;
+    filtered = filtered.filter((d) => allowed.has(d.type));
+  }
+  if (opts.minConfidence !== void 0) {
+    const threshold = opts.minConfidence;
+    filtered = filtered.filter((d) => d.confidence >= threshold);
+  }
+  if (opts.node) {
+    const target = opts.node;
+    filtered = filtered.filter((d) => involvesNode(d, target));
+  }
+  filtered.sort((a, b) => {
+    if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+    if (a.type !== b.type) return a.type.localeCompare(b.type);
+    if (a.source !== b.source) return a.source.localeCompare(b.source);
+    return a.target.localeCompare(b.target);
+  });
+  return import_types18.DivergenceResultSchema.parse({
+    divergences: filtered,
+    totalAffected: filtered.length,
+    computedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
 
 // src/diff.ts
 init_cjs_shims();
@@ -4044,7 +4281,7 @@ init_cjs_shims();
 var import_node_fs18 = require("fs");
 var import_node_os2 = __toESM(require("os"), 1);
 var import_node_path30 = __toESM(require("path"), 1);
-var import_types18 = require("@neat.is/types");
+var import_types19 = require("@neat.is/types");
 var LOCK_TIMEOUT_MS = 5e3;
 var LOCK_RETRY_MS = 50;
 function neatHome() {
@@ -4123,10 +4360,10 @@ async function readRegistry() {
     throw err;
   }
   const parsed = JSON.parse(raw);
-  return import_types18.RegistryFileSchema.parse(parsed);
+  return import_types19.RegistryFileSchema.parse(parsed);
 }
 async function writeRegistry(reg) {
-  const validated = import_types18.RegistryFileSchema.parse(reg);
+  const validated = import_types19.RegistryFileSchema.parse(reg);
   await writeAtomically(registryPath(), JSON.stringify(validated, null, 2) + "\n");
 }
 var ProjectNameCollisionError = class extends Error {
@@ -4359,6 +4596,41 @@ function registerRoutes(scope, ctx) {
     }
     return getTransitiveDependencies(proj.graph, id, depth);
   });
+  scope.get("/graph/divergences", async (req, reply) => {
+    const proj = resolveProject(registry, req, reply);
+    if (!proj) return;
+    let typeFilter;
+    if (req.query.type) {
+      const candidates = req.query.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+      const parsed = [];
+      for (const c of candidates) {
+        const r = import_types20.DivergenceTypeSchema.safeParse(c);
+        if (!r.success) {
+          return reply.code(400).send({
+            error: `unknown divergence type "${c}"`,
+            allowed: import_types20.DivergenceTypeSchema.options
+          });
+        }
+        parsed.push(r.data);
+      }
+      typeFilter = new Set(parsed);
+    }
+    let minConfidence;
+    if (req.query.minConfidence !== void 0) {
+      const n = Number(req.query.minConfidence);
+      if (!Number.isFinite(n) || n < 0 || n > 1) {
+        return reply.code(400).send({
+          error: "minConfidence must be a number in [0, 1]"
+        });
+      }
+      minConfidence = n;
+    }
+    return computeDivergences(proj.graph, {
+      ...typeFilter ? { type: typeFilter } : {},
+      ...minConfidence !== void 0 ? { minConfidence } : {},
+      ...req.query.node ? { node: req.query.node } : {}
+    });
+  });
   scope.get("/incidents", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
@@ -4512,7 +4784,7 @@ function registerRoutes(scope, ctx) {
     const log = new PolicyViolationsLog(proj.paths.policyViolationsPath);
     let violations = await log.readAll();
     if (req.query.severity) {
-      const sev = import_types19.PolicySeveritySchema.safeParse(req.query.severity);
+      const sev = import_types20.PolicySeveritySchema.safeParse(req.query.severity);
       if (!sev.success) {
         return reply.code(400).send({
           error: "invalid severity",
@@ -4529,7 +4801,7 @@ function registerRoutes(scope, ctx) {
   scope.post("/policies/check", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
-    const parsed = import_types19.PoliciesCheckBodySchema.safeParse(req.body ?? {});
+    const parsed = import_types20.PoliciesCheckBodySchema.safeParse(req.body ?? {});
     if (!parsed.success) {
       return reply.code(400).send({
         error: "invalid /policies/check body",
@@ -4615,13 +4887,13 @@ async function buildApi(opts) {
 
 // src/extract/retire.ts
 init_cjs_shims();
-var import_types20 = require("@neat.is/types");
+var import_types21 = require("@neat.is/types");
 function retireEdgesByFile(graph, file) {
   const normalized = file.split("\\").join("/");
   const toDrop = [];
   graph.forEachEdge((id, attrs) => {
     const edge = attrs;
-    if (edge.provenance !== import_types20.Provenance.EXTRACTED) return;
+    if (edge.provenance !== import_types21.Provenance.EXTRACTED) return;
     if (!edge.evidence?.file) return;
     if (edge.evidence.file === normalized) toDrop.push(id);
   });
@@ -5613,9 +5885,12 @@ function renderPatch(sections) {
   return lines.join("\n");
 }
 
+// src/cli.ts
+var import_types23 = require("@neat.is/types");
+
 // src/cli-client.ts
 init_cjs_shims();
-var import_types21 = require("@neat.is/types");
+var import_types22 = require("@neat.is/types");
 var HttpError = class extends Error {
   constructor(status2, message, responseBody = "") {
     super(message);
@@ -5750,7 +6025,7 @@ async function runBlastRadius(client, input) {
   }
 }
 function formatBlastEntry(n) {
-  const tag = n.edgeProvenance === import_types21.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
+  const tag = n.edgeProvenance === import_types22.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
   return `  \u2022 ${n.nodeId} (distance ${n.distance}, ${n.edgeProvenance})${tag}`;
 }
 async function runDependencies(client, input) {
@@ -5796,9 +6071,9 @@ async function runObservedDependencies(client, input) {
     const edges = await client.get(
       projectPath(input.project, `/graph/edges/${encodeURIComponent(input.nodeId)}`)
     );
-    const observed = edges.outbound.filter((e) => e.provenance === import_types21.Provenance.OBSERVED);
+    const observed = edges.outbound.filter((e) => e.provenance === import_types22.Provenance.OBSERVED);
     if (observed.length === 0) {
-      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types21.Provenance.EXTRACTED);
+      const hasExtracted = edges.outbound.some((e) => e.provenance === import_types22.Provenance.EXTRACTED);
       const note = hasExtracted ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
       return { summary: `No OBSERVED dependencies for ${input.nodeId}.${note}` };
     }
@@ -5806,7 +6081,7 @@ async function runObservedDependencies(client, input) {
     return {
       summary: `${input.nodeId} has ${observed.length} runtime dependenc${observed.length === 1 ? "y" : "ies"} confirmed by OTel.`,
       block: blockLines.join("\n"),
-      provenance: import_types21.Provenance.OBSERVED
+      provenance: import_types22.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -5859,7 +6134,7 @@ async function runIncidents(client, input) {
     return {
       summary: `${target} has ${events.length} recorded incident${events.length === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
       block: blockLines.join("\n"),
-      provenance: import_types21.Provenance.OBSERVED
+      provenance: import_types22.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -5967,7 +6242,7 @@ async function runStaleEdges(client, input) {
   return {
     summary: `${events.length} stale-edge transition${events.length === 1 ? "" : "s"} recorded${input.edgeType ? ` for ${input.edgeType}` : ""}.`,
     block: blockLines.join("\n"),
-    provenance: import_types21.Provenance.STALE
+    provenance: import_types22.Provenance.STALE
   };
 }
 async function runPolicies(client, input) {
@@ -6030,6 +6305,54 @@ async function runPolicies(client, input) {
     provenance: severities.join(" ")
   };
 }
+function formatDivergenceLine(d) {
+  switch (d.type) {
+    case "missing-observed":
+    case "missing-extracted":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} (${d.edgeType}) \u2014 confidence ${d.confidence.toFixed(2)}`;
+    case "version-mismatch":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 declared ${d.extractedVersion}, observed engine ${d.observedVersion} (${d.compatibility})`;
+    case "host-mismatch":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 declared host ${d.extractedHost}, observed host ${d.observedHost}`;
+    case "compat-violation":
+      return `  \u2022 [${d.type}] ${d.source} \u2192 ${d.target} \u2014 ${d.rule.kind}${d.rule.package ? ` (${d.rule.package})` : ""}`;
+  }
+}
+async function runDivergences(client, input) {
+  const params = new URLSearchParams();
+  if (input.type && input.type.length > 0) params.set("type", input.type.join(","));
+  if (input.minConfidence !== void 0) {
+    params.set("minConfidence", String(input.minConfidence));
+  }
+  if (input.node) params.set("node", input.node);
+  const qs = params.size > 0 ? `?${params.toString()}` : "";
+  const result = await client.get(
+    projectPath(input.project, `/graph/divergences${qs}`)
+  );
+  if (result.totalAffected === 0) {
+    return {
+      summary: "No divergences found between the declared (EXTRACTED) and observed (OBSERVED) views of the graph."
+    };
+  }
+  const headline = result.divergences[0];
+  const summary = `Found ${result.totalAffected} divergence${result.totalAffected === 1 ? "" : "s"} between code and production. Highest-confidence: ${headline.type} on ${headline.source} \u2192 ${headline.target}. ${headline.reason}`;
+  const blockLines = [];
+  for (const d of result.divergences) {
+    blockLines.push(formatDivergenceLine(d));
+    blockLines.push(`    reason: ${d.reason}`);
+    blockLines.push(`    recommendation: ${d.recommendation}`);
+  }
+  const maxConfidence = result.divergences.reduce(
+    (m, d) => Math.max(m, d.confidence),
+    0
+  );
+  return {
+    summary,
+    block: blockLines.join("\n"),
+    confidence: maxConfidence,
+    provenance: "composite (EXTRACTED + OBSERVED)"
+  };
+}
 function formatFooter(confidence, provenance) {
   const c = confidence === void 0 ? "n/a" : confidence.toFixed(2);
   const p = provenance === void 0 ? "n/a" : Array.isArray(provenance) ? [...new Set(provenance)].join(", ") : provenance;
@@ -6108,6 +6431,9 @@ function usage() {
   console.log("  policies                         Current policy violations.");
   console.log("                                   Flags: --node <id>, --hypothetical-action <json>");
   console.log("                                   example: neat policies --node service:<name> --json");
+  console.log("  divergences                      Where code (EXTRACTED) and production (OBSERVED) disagree.");
+  console.log("                                   Flags: --type <list>, --min-confidence <0..1>, --node <id>");
+  console.log("                                   example: neat divergences --min-confidence 0.7");
   console.log("");
   console.log("flags:");
   console.log('  --project <name>   Name the project this command targets. Default: "default".');
@@ -6132,7 +6458,9 @@ var STRING_FLAGS = [
   ["--since", "since"],
   ["--against", "against"],
   ["--error-id", "errorId"],
-  ["--hypothetical-action", "hypotheticalAction"]
+  ["--hypothetical-action", "hypotheticalAction"],
+  ["--type", "type"],
+  ["--min-confidence", "minConfidence"]
 ];
 function parseArgs(rest) {
   const positional = [];
@@ -6151,6 +6479,8 @@ function parseArgs(rest) {
     against: null,
     errorId: null,
     hypotheticalAction: null,
+    type: null,
+    minConfidence: null,
     positional: []
   };
   for (let i = 0; i < rest.length; i++) {
@@ -6210,6 +6540,15 @@ function assignFlag(out, field, value) {
     out[field] = n;
     return;
   }
+  if (field === "minConfidence") {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < 0 || n > 1) {
+      console.error("neat: --min-confidence must be a number in [0, 1]");
+      process.exit(2);
+    }
+    out.minConfidence = n;
+    return;
+  }
   ;
   out[field] = value;
 }
@@ -6593,7 +6932,9 @@ var QUERY_VERBS = /* @__PURE__ */ new Set([
   "search",
   "diff",
   "stale-edges",
-  "policies"
+  "policies",
+  // Tenth verb (ADR-060) — amends ADR-050's locked allowlist of nine.
+  "divergences"
 ]);
 function resolveProjectFlag(parsed) {
   if (parsed.project) return parsed.project;
@@ -6715,6 +7056,31 @@ async function runQueryVerb(cmd, parsed) {
       });
       break;
     }
+    case "divergences": {
+      let typeFilter;
+      if (parsed.type) {
+        const parts = parsed.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+        const out = [];
+        for (const p of parts) {
+          const r = import_types23.DivergenceTypeSchema.safeParse(p);
+          if (!r.success) {
+            console.error(
+              `neat divergences: unknown --type "${p}". allowed: ${import_types23.DivergenceTypeSchema.options.join(", ")}`
+            );
+            return 2;
+          }
+          out.push(r.data);
+        }
+        typeFilter = out;
+      }
+      work = runDivergences(client, {
+        ...typeFilter ? { type: typeFilter } : {},
+        ...parsed.minConfidence !== null ? { minConfidence: parsed.minConfidence } : {},
+        ...parsed.node ? { node: parsed.node } : {},
+        ...project ? { project } : {}
+      });
+      break;
+    }
     default:
       console.error(`neat: unknown query verb "${cmd}"`);
       return 2;