@merittdev/horus 0.4.0 → 0.4.1

package/dist/index.cjs

@@ -57239,7 +57239,7 @@ init_cjs_shims();
 
 // ../../packages/core/src/version.ts
 init_cjs_shims();
-var HORUS_VERSION = true ? "0.4.0" : "dev";
+var HORUS_VERSION = true ? "0.4.1" : "dev";
 var PINNED_SOURCE_VERSION = "1.1.1";
 
 // ../../packages/core/src/evidence.ts
@@ -77009,6 +77009,17 @@ function clamp015(n) {
   if (n > 1) return 1;
   return n;
 }
+function confidenceCeilingForCause(score) {
+  const s = clamp015(score);
+  if (s < 0.2) return 0.6;
+  if (s < 0.5) {
+    return 0.6 + (s - 0.2) / (0.5 - 0.2) * (0.78 - 0.6);
+  }
+  if (s < 0.85) {
+    return 0.78 + (s - 0.5) / (0.85 - 0.5) * (1 - 0.78);
+  }
+  return 1;
+}
 function relevanceForKind(kind) {
   switch (kind) {
     case "symbol":
@@ -77156,6 +77167,40 @@ function looksDiffable(since) {
   if (/^\d+[smhd]$/i.test(s)) return false;
   return /^[A-Za-z0-9._/~^-]+$/.test(s);
 }
+function looksExplanatory(hint) {
+  const h = hint.trim();
+  if (h.length === 0) return false;
+  if (/\b(how|what|why|when|where)\b.*\b(work|works|working|do|does|done|happen|happens|flow|flows|behave|called|invoked|triggered|used)\b/i.test(h)) {
+    return true;
+  }
+  if (/^\s*(how|what|why|when|where|explain|describe|walk\s+me\s+through|tell\s+me\s+(?:about|how))\b/i.test(h)) {
+    return true;
+  }
+  return false;
+}
+function formatRegressionCitation(recentChanges, changes) {
+  const commits = (recentChanges?.commits ?? []).slice(0, 2);
+  const commitParts = commits.map((c) => {
+    const sha = c.shortSha || c.sha.slice(0, 7);
+    const subject = (c.subject ?? "").replace(/\s+/g, " ").trim();
+    return subject ? `${sha} "${subject.slice(0, 50)}"` : sha;
+  });
+  const commitClause = commitParts.length > 0 ? ` (${commitParts.join(", ")})` : "";
+  const modified = changes?.modified ?? [];
+  const symbolNames = [];
+  for (const m of modified) {
+    const name = m.after?.name ?? m.before?.name;
+    if (name && !symbolNames.includes(name)) symbolNames.push(name);
+    if (symbolNames.length >= 3) break;
+  }
+  let symbolClause = "";
+  if (symbolNames.length > 0) {
+    const shown = symbolNames.join(", ");
+    const more = modified.length > symbolNames.length ? ", \u2026" : "";
+    symbolClause = ` touched ${shown}${more}`;
+  }
+  return { commitClause, symbolClause };
+}
 async function investigate(input, deps) {
   const { code, db } = deps;
   const hint = input.hint.trim();
@@ -77940,9 +77985,10 @@ async function investigate(input, deps) {
     const gitChangedFiles = recentChanges?.changedFiles ?? [];
     const seedFile = top?.filePath;
     const seedInChanges = seedFile !== void 0 && gitChangedFiles.length > 0 && gitChangedFiles.some((f) => f === seedFile || seedFile.endsWith(f) || f.endsWith(seedFile));
+    const citation = formatRegressionCitation(recentChanges, changes);
     causeInputs.push({
       id: "cause:deployment-regression",
-      title: top ? `Recent change to ${top.name} in ${input.since}..HEAD may have introduced the regression` : `Recent changes in ${input.since}..HEAD may have introduced the regression`,
+      title: top ? `Recent change${citation.commitClause} to ${top.name}${citation.symbolClause} in ${input.since}..HEAD may have introduced the regression` : `Recent change${citation.commitClause}${citation.symbolClause} in ${input.since}..HEAD may have introduced the regression`,
       category: "deployment-regression",
       sourceEvidenceIds: [changeEvId, ...seedEv ? [seedEv.id] : []],
       baseScore: clamp015((seedInChanges ? 0.45 : 0.25) + (queueHits.length > 0 ? 0.05 : 0)),
@@ -78065,8 +78111,20 @@ async function investigate(input, deps) {
   const banner2 = degradedNoSource ? "Runtime-only (source intelligence unavailable). " : "";
   const scope = top ? `resolved to ${label} (${area})` : `over runtime evidence (${area})`;
   const seedDisclaimer = seedIsLowConfidence && top ? `\u26A0 No symbol closely matched "${hint}" \u2014 "${top.name}" is a low-confidence closest match (semantic). Refine with an exact symbol or error code to target precisely. ` : "";
-  const summary = headlineCause ? `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. Top suspected cause: ${headlineCause.title}.` : `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. No dominant suspected cause emerged from the available ${degradedNoSource ? "runtime" : "structural"} evidence.`;
+  let summary = headlineCause ? `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. Top suspected cause: ${headlineCause.title}.` : `${seedDisclaimer}${banner2}Investigation of "${hint}" ${scope}. No dominant suspected cause emerged from the available ${degradedNoSource ? "runtime" : "structural"} evidence.`;
+  const hasIncidentSignal = directLogEvIds.length > 0 || latencyMetricEvIds.length > 0 || queueMetricEvIds.length > 0 || dataAnomalyEvIds.length > 0 || queueFailureSignals.length > 0 || findings2.some((f) => f.kind === "anomaly") || headlineCause !== void 0;
+  const explanatoryHint = looksExplanatory(hint) && !hasIncidentSignal;
+  if (explanatoryHint) {
+    const explainTarget = top?.name ?? input.service ?? hint;
+    summary = `${seedDisclaimer}${banner2}"${hint}" reads as a "how does it work" question and no incident signal was found (no error signatures, anomalies, or failing queues). For a focused answer, run \`horus explain ${explainTarget}\`. ${top ? `Investigated ${label} (${area}); the` : "The"} incident sections below are empty by design \u2014 this is not a fault hunt.`;
+  }
   const nextActions = buildNextActions(top, ctx, impact, queueHits, changes, input);
+  if (explanatoryHint) {
+    const explainTarget = top?.name ?? input.service ?? hint;
+    nextActions.unshift(
+      `This looks like a behavioral question \u2014 run \`horus explain ${explainTarget}\` for a focused walkthrough of how it works.`
+    );
+  }
   if (degradedNoSource) {
     nextActions.unshift(
       "Source intelligence was unavailable \u2014 run `horus index` to enable code-aware analysis, then re-run for a full investigation."
@@ -78124,7 +78182,7 @@ async function investigate(input, deps) {
   report.confidence = Math.min(report.confidence, gapAnalysis.confidenceCeiling);
   if (seedIsLowConfidence) report.confidence = Math.min(report.confidence, 0.45);
   const topCauseScore = report.suspectedCauses[0]?.finalScore ?? 0;
-  if (topCauseScore < 0.2) report.confidence = Math.min(report.confidence, 0.6);
+  report.confidence = Math.min(report.confidence, confidenceCeilingForCause(topCauseScore));
   report.nextActions.push(...gapNextActions(gapAnalysis.gaps));
   report.sourceStatus = buildRuntimeSourceStatus(evidence2, connectorFlags);
   const persistedId = await persist(db, input, report);
@@ -81201,24 +81259,98 @@ var PROCESSOR_RE = /@Processor\(\s*['"]([^'"]+)['"][^)]*\)\s*(?:@\w+[^\n]*\s*)*e
 var CONST_DECL_RE = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*['"]([^'"]+)['"]/g;
 var NEW_BULL_RE = /(?:(\w+)\s*[:=]\s*)?new\s+(Queue|Worker)\s*(?:<[^>]*>)?\s*\(\s*(['"][^'"]+['"]|[A-Za-z_$][\w$.]*)/g;
 var QUEUE_NAME_CONST_RE = /(?:export\s+)?const\s+([A-Za-z_$][\w$]*(?:QUEUE|Queue)[\w$]*)\s*=\s*['"]([^'"]+)['"]/g;
+var ENUM_DECL_RE = /(?:export\s+)?(?:const\s+)?enum\s+([A-Za-z_$][\w$]*)\s*\{([^}]*)\}/g;
+var ENUM_MEMBER_RE = /([A-Za-z_$][\w$]*)\s*(?:=\s*(['"])([^'"]*)\2)?/g;
+var OBJECT_VALUES_LOOP_RE = /for\s*\(\s*(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s+of\s+Object\.values\(\s*([A-Za-z_$][\w$]*)\s*\)/g;
+var DISPATCH_ENTRY_RE = /\[\s*([A-Za-z_$][\w$]*)\.([A-Za-z_$][\w$]*)\s*\]\s*:\s*([^,}]+)/g;
 function baseName(filePath) {
   const parts = filePath.split("/");
   const last = parts[parts.length - 1] ?? filePath;
   return last.replace(/\.[jt]sx?$/, "");
 }
-function resolveArg(raw, constMap) {
+function buildEnumMap(contents) {
+  const enums = /* @__PURE__ */ new Map();
+  for (const content of contents) {
+    for (const decl of content.matchAll(ENUM_DECL_RE)) {
+      const enumName = decl[1];
+      const body = decl[2] ?? "";
+      if (!enumName || enums.has(enumName)) continue;
+      const members = [];
+      for (const m of body.matchAll(ENUM_MEMBER_RE)) {
+        const member = m[1];
+        if (!member) continue;
+        const value = m[3] !== void 0 ? m[3] : member;
+        members.push({ member, value });
+      }
+      if (members.length) enums.set(enumName, members);
+    }
+  }
+  return enums;
+}
+function resolveEnumMember(ref, enums) {
+  const dot = ref.indexOf(".");
+  if (dot < 0) return null;
+  const enumName = ref.slice(0, dot);
+  const member = ref.slice(dot + 1);
+  const members = enums.get(enumName);
+  if (!members) return null;
+  return members.find((e) => e.member === member)?.value ?? null;
+}
+function resolveArg(raw, constMap, enums, loopVarEnums) {
   const arg = raw.trim();
   if (arg.startsWith('"') || arg.startsWith("'")) {
-    return arg.slice(1, -1);
+    return [arg.slice(1, -1)];
+  }
+  if (arg.includes(".")) {
+    const value = resolveEnumMember(arg, enums);
+    return value !== null ? [value] : [];
+  }
+  const loopEnum = loopVarEnums.get(arg);
+  if (loopEnum) {
+    const members = enums.get(loopEnum);
+    if (members) return members.map((e) => e.value);
+  }
+  const constValue = constMap.get(arg);
+  return constValue !== void 0 ? [constValue] : [];
+}
+function loopVarEnumsFor(content) {
+  const map2 = /* @__PURE__ */ new Map();
+  for (const m of content.matchAll(OBJECT_VALUES_LOOP_RE)) {
+    const loopVar = m[1];
+    const enumName = m[2];
+    if (loopVar && enumName) map2.set(loopVar, enumName);
+  }
+  return map2;
+}
+function extractDispatchHandlers(content, enums) {
+  const out = [];
+  for (const m of content.matchAll(DISPATCH_ENTRY_RE)) {
+    const enumName = m[1];
+    const member = m[2];
+    const rhs = (m[3] ?? "").trim();
+    if (!enumName || !member) continue;
+    const value = resolveEnumMember(`${enumName}.${member}`, enums);
+    if (value === null) continue;
+    const handler = handlerSymbolFromExpr(rhs);
+    if (handler) out.push({ value, handler });
   }
-  return constMap.get(arg) ?? null;
+  return out;
+}
+function handlerSymbolFromExpr(expr) {
+  const call = expr.match(/([A-Za-z_$][\w$]*)\s*\(/);
+  if (call?.[1]) return call[1];
+  const member = expr.match(/(?:[A-Za-z_$][\w$]*\.)+([A-Za-z_$][\w$]*)/);
+  if (member?.[1]) return member[1];
+  const ident = expr.match(/^([A-Za-z_$][\w$]*)$/);
+  if (ident?.[1]) return ident[1];
+  return null;
 }
 function extractQueueGraph(input) {
-  const constMap = /* @__PURE__ */ new Map();
   const allContent = [
     ...input.producerClasses.map((p) => p.content),
     ...input.workerFiles.map((w) => w.content)
   ];
+  const constMap = /* @__PURE__ */ new Map();
   for (const content of allContent) {
     for (const m of content.matchAll(CONST_DECL_RE)) {
       const ident = m[1];
@@ -81226,17 +81358,30 @@ function extractQueueGraph(input) {
       if (ident && value && !constMap.has(ident)) constMap.set(ident, value);
     }
   }
+  const enums = buildEnumMap(allContent);
+  const dispatchHandlers = [];
+  for (const unit of [...input.producerClasses, ...input.workerFiles]) {
+    const file = "filePath" in unit ? unit.filePath : "";
+    for (const h of extractDispatchHandlers(unit.content, enums)) {
+      dispatchHandlers.push({ value: h.value, handler: h.handler, file });
+    }
+  }
   const producers = [];
   for (const pc47 of input.producerClasses) {
+    const loopVarEnums = loopVarEnumsFor(pc47.content);
     for (const m of pc47.content.matchAll(INJECT_QUEUE_RE)) {
       const queue = m[1] ?? "";
       if (queue) producers.push({ queue, symbol: pc47.name, file: pc47.filePath });
     }
     for (const m of pc47.content.matchAll(NEW_BULL_RE)) {
       if (m[2] !== "Queue") continue;
-      const queue = resolveArg(m[3] ?? "", constMap);
-      if (queue) {
-        producers.push({ queue, symbol: (m[1] ?? pc47.name) || baseName(pc47.filePath), file: pc47.filePath });
+      const queues2 = resolveArg(m[3] ?? "", constMap, enums, loopVarEnums);
+      for (const queue of queues2) {
+        producers.push({
+          queue,
+          symbol: (m[1] ?? pc47.name) || baseName(pc47.filePath),
+          file: pc47.filePath
+        });
       }
     }
     for (const m of pc47.content.matchAll(QUEUE_NAME_CONST_RE)) {
@@ -81247,6 +81392,7 @@ function extractQueueGraph(input) {
   }
   const workers = [];
   for (const wf of input.workerFiles) {
+    const loopVarEnums = loopVarEnumsFor(wf.content);
     for (const m of wf.content.matchAll(PROCESSOR_RE)) {
       const queue = m[1] ?? "";
       const className = m[2] ?? "";
@@ -81254,17 +81400,24 @@ function extractQueueGraph(input) {
     }
     for (const m of wf.content.matchAll(NEW_BULL_RE)) {
       if (m[2] !== "Worker") continue;
-      const queue = resolveArg(m[3] ?? "", constMap);
-      if (queue) {
-        workers.push({ queue, symbol: m[1] ?? baseName(wf.filePath), file: wf.filePath });
+      const queues2 = resolveArg(m[3] ?? "", constMap, enums, loopVarEnums);
+      for (const queue of queues2) {
+        workers.push({
+          queue,
+          symbol: m[1] ?? baseName(wf.filePath),
+          file: wf.filePath
+        });
       }
     }
   }
+  for (const h of dispatchHandlers) {
+    workers.push({ queue: h.value, symbol: h.handler, file: h.file });
+  }
   const queues = [...new Set([...producers, ...workers].map((r) => r.queue))].sort();
   const edges = [];
   for (const q of queues) {
-    const P = dedupeByFile(producers.filter((p) => p.queue === q));
-    const W = dedupeByFile(workers.filter((w) => w.queue === q));
+    const P = dedupeBySymbolFile(producers.filter((p) => p.queue === q));
+    const W = dedupeBySymbolFile(workers.filter((w) => w.queue === q));
     if (P.length && W.length) {
       for (const p of P) {
         for (const w of W) {
@@ -81301,12 +81454,13 @@ function extractQueueGraph(input) {
   }
   return { queues, producers, workers, edges };
 }
-function dedupeByFile(rows) {
+function dedupeBySymbolFile(rows) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const r of rows) {
-    if (seen.has(r.file)) continue;
-    seen.add(r.file);
+    const key = `${r.symbol}\0${r.file}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
     out.push(r);
   }
   return out;
@@ -81317,7 +81471,7 @@ init_cjs_shims();
 async function stitch(client, db, opts = {}) {
   const producerRows = (await client.cypher(
     // "new Queue" (no paren) so generic-typed `new Queue<T>(...)` also matches.
-    'MATCH (n) WHERE n.content CONTAINS "@InjectQueue(" OR n.content CONTAINS "new Queue" OR n.content CONTAINS "QUEUE_NAME" OR n.content CONTAINS "QueueName" RETURN n.name, n.file_path, n.content'
+    'MATCH (n) WHERE n.content CONTAINS "@InjectQueue(" OR n.content CONTAINS "new Queue" OR n.content CONTAINS "QUEUE_NAME" OR n.content CONTAINS "QueueName" OR n.content CONTAINS "enum " OR n.content CONTAINS "Object.values(" OR n.content CONTAINS "]: (" RETURN n.name, n.file_path, n.content'
   )).rows;
   const producerClasses = producerRows.map((r) => ({
     name: String(r[0] ?? ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merittdev/horus",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Local-first, source-aware production-incident investigation engine",
   "type": "module",
   "bin": {