@neat.is/core 0.2.9 → 0.3.0

package/dist/index.cjs

@@ -3869,7 +3869,244 @@ function startPersistLoop(graph, outPath, intervalMs = 6e4) {
 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();
@@ -4005,7 +4242,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() {
@@ -4084,10 +4321,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 {
@@ -4279,9 +4516,15 @@ function registerRoutes(scope, ctx) {
   scope.get("/health", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
+    const uptimeMs = Date.now() - startedAt;
     return {
-      uptime: Math.floor((Date.now() - startedAt) / 1e3),
+      ok: true,
       project: proj.name,
+      uptimeMs,
+      // Legacy fields kept additively. The web shell's StatusBar reads
+      // nodeCount / edgeCount; ADR-061's HealthResponseSchema validates
+      // the canonical triple and lets the extras pass through.
+      uptime: Math.floor(uptimeMs / 1e3),
       nodeCount: proj.graph.order,
       edgeCount: proj.graph.size,
       lastUpdated: (/* @__PURE__ */ new Date()).toISOString()
@@ -4301,7 +4544,7 @@ function registerRoutes(scope, ctx) {
       if (!proj.graph.hasNode(id)) {
         return reply.code(404).send({ error: "node not found", id });
       }
-      return proj.graph.getNodeAttributes(id);
+      return { node: proj.graph.getNodeAttributes(id) };
     }
   );
   scope.get(
@@ -4318,12 +4561,12 @@ function registerRoutes(scope, ctx) {
       return { inbound, outbound };
     }
   );
-  scope.get("/graph/node/:id/dependencies", async (req, reply) => {
+  scope.get("/graph/dependencies/:nodeId", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
-    const { id } = req.params;
-    if (!proj.graph.hasNode(id)) {
-      return reply.code(404).send({ error: "node not found", id });
+    const { nodeId } = req.params;
+    if (!proj.graph.hasNode(nodeId)) {
+      return reply.code(404).send({ error: "node not found", id: nodeId });
     }
     const depth = req.query.depth ? Number(req.query.depth) : TRANSITIVE_DEPENDENCIES_DEFAULT_DEPTH;
     if (!Number.isFinite(depth) || depth < 1 || depth > TRANSITIVE_DEPENDENCIES_MAX_DEPTH) {
@@ -4331,25 +4574,67 @@ function registerRoutes(scope, ctx) {
         error: `depth must be an integer in [1, ${TRANSITIVE_DEPENDENCIES_MAX_DEPTH}]`
       });
     }
-    return getTransitiveDependencies(proj.graph, id, depth);
+    return getTransitiveDependencies(proj.graph, nodeId, 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;
     const epath = errorsPathFor(proj);
-    if (!epath) return [];
-    return readErrorEvents(epath);
+    if (!epath) return { count: 0, total: 0, events: [] };
+    const events = await readErrorEvents(epath);
+    const total = events.length;
+    const limit = req.query.limit ? Number(req.query.limit) : 50;
+    const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.min(limit, 200) : 50;
+    const sliced = events.slice(0, safeLimit);
+    return { count: sliced.length, total, events: sliced };
   });
-  scope.get("/incidents/stale", async (req, reply) => {
+  scope.get("/stale-events", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
     const spath = staleEventsPathFor(proj);
-    if (!spath) return [];
+    if (!spath) return { count: 0, total: 0, events: [] };
     const events = await readStaleEvents(spath);
     const filtered = req.query.edgeType ? events.filter((e) => e.edgeType === req.query.edgeType) : events;
     const ordered = [...filtered].reverse();
+    const total = ordered.length;
     const limit = req.query.limit ? Number(req.query.limit) : 50;
-    return ordered.slice(0, Number.isFinite(limit) && limit > 0 ? limit : 50);
+    const sliced = ordered.slice(0, Number.isFinite(limit) && limit > 0 ? limit : 50);
+    return { count: sliced.length, total, events: sliced };
   });
   scope.get(
     "/incidents/:nodeId",
@@ -4361,14 +4646,15 @@ function registerRoutes(scope, ctx) {
         return reply.code(404).send({ error: "node not found", id: nodeId });
       }
       const epath = errorsPathFor(proj);
-      if (!epath) return [];
+      if (!epath) return { count: 0, total: 0, events: [] };
       const events = await readErrorEvents(epath);
-      return events.filter(
+      const filtered = events.filter(
         (e) => e.affectedNode === nodeId || e.service === nodeId.replace(/^service:/, "")
       );
+      return { count: filtered.length, total: filtered.length, events: filtered };
     }
   );
-  scope.get("/traverse/root-cause/:nodeId", async (req, reply) => {
+  scope.get("/graph/root-cause/:nodeId", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
     const { nodeId } = req.params;
@@ -4388,7 +4674,7 @@ function registerRoutes(scope, ctx) {
     if (!result) return reply.code(404).send({ error: "no root cause found", id: nodeId });
     return result;
   });
-  scope.get("/traverse/blast-radius/:nodeId", async (req, reply) => {
+  scope.get("/graph/blast-radius/:nodeId", async (req, reply) => {
     const proj = resolveProject(registry, req, reply);
     if (!proj) return;
     const { nodeId } = req.params;
@@ -4486,7 +4772,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",
@@ -4498,12 +4784,12 @@ function registerRoutes(scope, ctx) {
     if (req.query.policyId) {
       violations = violations.filter((v) => v.policyId === req.query.policyId);
     }
-    return violations;
+    return { violations };
   });
   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",
@@ -4577,6 +4863,20 @@ async function buildApi(opts) {
       });
     }
   });
+  app.get("/projects/:project", async (req, reply) => {
+    try {
+      const entry = await getProject(req.params.project);
+      if (!entry) {
+        return reply.code(404).send({ error: "project not found", project: req.params.project });
+      }
+      return { project: entry };
+    } catch (err) {
+      return reply.code(500).send({
+        error: "failed to read project registry",
+        details: err.message
+      });
+    }
+  });
   registerRoutes(app, routeCtx);
   await app.register(
     async (scope) => {