@tracegraph/graph-engine 0.1.0

package/dist/index.mjs

@@ -0,0 +1,898 @@
+// src/graph.ts
+var NODE_COLORS = {
+  http_request: "#3b82f6",
+  // blue
+  http_response: "#3b82f6",
+  // blue
+  db_query: "#f97316",
+  // orange
+  authorization_check: "#ef4444",
+  // red
+  auth_check: "#ef4444",
+  // red
+  external_http_call: "#a855f7",
+  // purple
+  function_call: "#6b7280",
+  // grey
+  method_call: "#6b7280",
+  // grey
+  return: "#9ca3af",
+  // light grey
+  error: "#dc2626",
+  // crimson
+  queue_event: "#14b8a6",
+  // teal
+  trace_start: "#94a3b8",
+  // slate
+  trace_end: "#94a3b8",
+  // slate
+  log: "#a3a3a3",
+  // neutral
+  // Test runner nodes — green spectrum, dimmed for skips
+  test_file: "#4ade80",
+  // bright green
+  test_suite: "#86efac",
+  // medium green
+  test_run: "#bbf7d0",
+  // light green (pass colour; fail overridden in code)
+  vendor: "#cbd5e1"
+  // very light
+};
+var DEFAULT_COLOR = "#6b7280";
+function getNodeColor(type) {
+  return NODE_COLORS[type] ?? DEFAULT_COLOR;
+}
+function getTestAwareColor(event) {
+  if (event.type === "test_run") {
+    const status = event.metadata?.["testStatus"];
+    if (status === "fail") return "#ef4444";
+    if (status === "skip") return "#d1d5db";
+    return NODE_COLORS.test_run ?? DEFAULT_COLOR;
+  }
+  return getNodeColor(event.type);
+}
+var VENDOR_PATH_RE = /(?:node_modules|\/vendor\/)[\\/](@[^\\/]+[\\/][^\\/]+|[^\\/]+)/;
+function isVendorEvent(event) {
+  const f = event.file ?? "";
+  return VENDOR_PATH_RE.test(f);
+}
+function extractPackageName(file) {
+  const m = file.match(VENDOR_PATH_RE);
+  return m?.[1] ?? "vendor";
+}
+function vendorNodeId(pkg) {
+  return `vendor__${pkg.replace(/[^a-z0-9@]/gi, "_")}`;
+}
+function computeNodeSize(event) {
+  if (!event.durationMs) return 1;
+  return Math.max(1, Math.min(10, Math.ceil(Math.log10(event.durationMs + 1))));
+}
+function traceSessionToGraph(session) {
+  const nodes = [];
+  const edges = [];
+  const eventToNodeId = /* @__PURE__ */ new Map();
+  const vendorNodes = /* @__PURE__ */ new Map();
+  for (const event of session.events) {
+    if (event.name?.includes("tracegraph_xdebug_marker")) continue;
+    if (event.type === "trace_start" || event.type === "trace_end") {
+    }
+    if (isVendorEvent(event)) {
+      const pkg = extractPackageName(event.file);
+      const nodeId = vendorNodeId(pkg);
+      if (!vendorNodes.has(nodeId)) {
+        const vendorNode = {
+          id: nodeId,
+          label: pkg,
+          type: "vendor",
+          language: event.language,
+          color: NODE_COLORS.vendor,
+          size: 1,
+          data: event
+        };
+        vendorNodes.set(nodeId, vendorNode);
+        nodes.push(vendorNode);
+      }
+      eventToNodeId.set(event.eventId, nodeId);
+      continue;
+    }
+    const nodeType = event.type;
+    const node = {
+      id: event.eventId,
+      label: event.displayName ?? event.name,
+      displayName: event.displayName,
+      type: nodeType,
+      language: event.language,
+      framework: event.framework,
+      durationMs: event.durationMs,
+      file: event.file,
+      line: event.line,
+      color: getTestAwareColor(event),
+      size: computeNodeSize(event),
+      data: event
+    };
+    nodes.push(node);
+    eventToNodeId.set(event.eventId, event.eventId);
+  }
+  const asyncGroupSeen = /* @__PURE__ */ new Map();
+  for (const event of session.events) {
+    if (!event.parentEventId) continue;
+    const sourceNodeId = eventToNodeId.get(event.parentEventId);
+    const targetNodeId = eventToNodeId.get(event.eventId);
+    if (!sourceNodeId || !targetNodeId) continue;
+    if (sourceNodeId === targetNodeId) continue;
+    let edgeType = "parent";
+    if (event.asyncGroupId) {
+      const group = asyncGroupSeen.get(event.asyncGroupId) ?? [];
+      if (group.length > 0) edgeType = "parallel_branch";
+      group.push(targetNodeId);
+      asyncGroupSeen.set(event.asyncGroupId, group);
+    }
+    const edgeId = `${sourceNodeId}\u2192${targetNodeId}`;
+    if (!edges.some((e) => e.id === edgeId)) {
+      edges.push({ id: edgeId, source: sourceNodeId, target: targetNodeId, type: edgeType });
+    }
+  }
+  return { nodes, edges, captureLevel: session.captureLevel };
+}
+
+// src/signature.ts
+import { createHash } from "crypto";
+var VALIDATION_RE = /validate|verify|check|assert|ensure|guard|permission|authorize/i;
+var AUTH_EVENT_TYPES = /* @__PURE__ */ new Set(["auth_check", "authorization_check"]);
+function classifyRole(event) {
+  if (AUTH_EVENT_TYPES.has(event.type)) return "authorization";
+  if (event.type === "db_query") return "db";
+  if (event.type === "external_http_call") return "external_call";
+  const namesToCheck = [
+    event.functionName,
+    event.name,
+    event.displayName,
+    event.className
+  ].filter(Boolean).join(" ");
+  if (VALIDATION_RE.test(namesToCheck)) return "validation";
+  return "business_logic";
+}
+function eventToSignature(event) {
+  const role = classifyRole(event);
+  const routePathPattern = event.metadata?.["route"] ? normaliseRoutePath(String(event.metadata["route"])) : void 0;
+  const routeMethod = event.metadata?.["method"] ? String(event.metadata["method"]).toUpperCase() : void 0;
+  return {
+    eventType: event.type,
+    language: event.language,
+    framework: event.framework,
+    className: event.className,
+    methodName: event.functionName ?? void 0,
+    // functionName field on the event
+    functionName: event.name,
+    routeMethod,
+    routePathPattern,
+    resourceType: event.resource?.type,
+    resourceKey: event.resource?.key,
+    resourceOperation: event.resource?.operation,
+    role
+  };
+}
+function normaliseRoutePath(path) {
+  return path.replace(
+    /\/([^/]+)/g,
+    (_, segment) => {
+      if (segment.startsWith(":")) return `/${segment}`;
+      if (/^[0-9a-f-]{8,}$/i.test(segment) || /^\d+$/.test(segment)) return "/:param";
+      return `/${segment}`;
+    }
+  );
+}
+function signatureToIdentityHash(sig) {
+  const parts = [
+    sig.eventType ?? "",
+    sig.language ?? "",
+    sig.framework ?? "",
+    sig.className ?? "",
+    sig.methodName ?? "",
+    sig.functionName ?? "",
+    sig.routeMethod ?? "",
+    sig.routePathPattern ?? "",
+    sig.resourceType ?? "",
+    sig.resourceKey ?? "",
+    sig.resourceOperation ?? "",
+    sig.role ?? ""
+  ];
+  return createHash("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
+}
+
+// src/baseline.ts
+import { createHash as createHash2 } from "crypto";
+import { SCHEMA_VERSIONS } from "@tracegraph/shared-types";
+function sessionToBaseline(session, meta) {
+  const signatureMap = /* @__PURE__ */ new Map();
+  const resourceMap = /* @__PURE__ */ new Map();
+  let responseShape = { type: "unknown" };
+  for (const event of session.events) {
+    if (event.type === "trace_start" || event.type === "trace_end") continue;
+    if (event.type === "return") continue;
+    const sig = eventToSignature(event);
+    const hash = signatureToIdentityHash(sig);
+    const role = classifyRole(event);
+    const existing = signatureMap.get(hash);
+    if (existing) {
+      existing.count++;
+    } else {
+      signatureMap.set(hash, {
+        signature: sig,
+        role: String(role),
+        count: 1,
+        critical: isSecurityCritical(event)
+      });
+    }
+    if (event.type === "db_query" && event.resource) {
+      const rKey = `${event.resource.type}:${event.resource.key}:${event.resource.operation}`;
+      const r = resourceMap.get(rKey);
+      if (r) {
+        r.count++;
+      } else {
+        resourceMap.set(rKey, {
+          type: event.resource.type,
+          key: event.resource.key,
+          operation: event.resource.operation,
+          count: 1
+        });
+      }
+    }
+    if (event.type === "http_response" && event.output) {
+      responseShape = extractShape(event.output);
+    }
+  }
+  return {
+    schemaVersion: SCHEMA_VERSIONS.baseline,
+    baselineId: `baseline_${createBaselineId(session)}`,
+    testId: deriveTestId(session.entrypoint),
+    entrypoint: session.entrypoint,
+    approvedAt: Date.now(),
+    approvedBy: meta.approvedBy,
+    reason: meta.reason,
+    captureLevel: session.captureLevel.overall,
+    events: Array.from(signatureMap.values()),
+    resources: Array.from(resourceMap.values()),
+    responseShape
+  };
+}
+function deriveTestId(entrypoint) {
+  let key;
+  switch (entrypoint.type) {
+    case "http_request":
+      key = `${entrypoint.method}:${entrypoint.path}`;
+      break;
+    case "test_case":
+      key = entrypoint.testName;
+      break;
+    case "function":
+      key = `fn:${entrypoint.functionName}`;
+      break;
+    case "cli_command":
+      key = `cmd:${entrypoint.command}`;
+      break;
+    default:
+      key = JSON.stringify(entrypoint);
+  }
+  return createHash2("sha256").update(key).digest("hex").slice(0, 12);
+}
+function createBaselineId(session) {
+  return createHash2("sha256").update(session.traceId + session.sessionId).digest("hex").slice(0, 12);
+}
+var SECURITY_CRITICAL_TYPES = /* @__PURE__ */ new Set(["auth_check", "authorization_check"]);
+function isSecurityCritical(event) {
+  return SECURITY_CRITICAL_TYPES.has(event.type) || Boolean(event.security?.["critical"]);
+}
+function extractShape(value, depth = 0, maxDepth = 4) {
+  if (depth >= maxDepth) return { type: "unknown" };
+  if (value === null || value === void 0) return { type: "null" };
+  switch (typeof value) {
+    case "string":
+      return { type: "string" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+  }
+  if (Array.isArray(value)) {
+    const itemShape = value.length > 0 ? extractShape(value[0], depth + 1, maxDepth) : { type: "unknown" };
+    return { type: "array", items: itemShape };
+  }
+  if (typeof value === "object") {
+    const properties = {};
+    for (const [k, v] of Object.entries(value)) {
+      properties[k] = extractShape(v, depth + 1, maxDepth);
+    }
+    return { type: "object", properties };
+  }
+  return { type: "unknown" };
+}
+
+// src/diff.ts
+import { normaliseForDiff } from "@tracegraph/trace-sanitizer";
+function diffBaseline(baseline, candidate) {
+  const candidateHashes = /* @__PURE__ */ new Set();
+  const candidateSignatureChanges = [];
+  for (const event of candidate.events) {
+    if (event.type === "trace_start" || event.type === "trace_end") continue;
+    if (event.type === "return") continue;
+    const sig = eventToSignature(event);
+    const hash = signatureToIdentityHash(sig);
+    const role = classifyRole(event);
+    candidateHashes.add(hash);
+    candidateSignatureChanges.push({
+      signature: sig,
+      identityHash: hash,
+      role,
+      critical: isSecurityCritical2(event),
+      eventId: event.eventId,
+      eventName: event.name
+    });
+  }
+  const baselineHashes = new Set(
+    baseline.events.map((e) => signatureToIdentityHash(e.signature))
+  );
+  const removedSignatures = [];
+  for (const entry of baseline.events) {
+    const hash = signatureToIdentityHash(entry.signature);
+    if (!candidateHashes.has(hash)) {
+      removedSignatures.push({
+        signature: entry.signature,
+        identityHash: hash,
+        role: entry.role,
+        critical: entry.critical ?? false
+      });
+    }
+  }
+  const seenAdded = /* @__PURE__ */ new Set();
+  const addedSignatures = [];
+  for (const item of candidateSignatureChanges) {
+    if (!baselineHashes.has(item.identityHash) && !seenAdded.has(item.identityHash)) {
+      seenAdded.add(item.identityHash);
+      addedSignatures.push(item);
+    }
+  }
+  const candidateResources = buildResourceMap(candidate);
+  const changedResources = [];
+  const allResourceKeys = /* @__PURE__ */ new Set([
+    ...baseline.resources.map((r) => `${r.type}:${r.key}:${r.operation}`),
+    ...Object.keys(candidateResources)
+  ]);
+  for (const key of allResourceKeys) {
+    const [type, rKey, operation] = key.split(":");
+    const baselineCount = baseline.resources.find(
+      (r) => `${r.type}:${r.key}:${r.operation}` === key
+    )?.count ?? 0;
+    const candidateCount = candidateResources[key] ?? 0;
+    if (baselineCount !== candidateCount) {
+      changedResources.push({ type, key: rKey, operation, baselineCount, candidateCount });
+    }
+  }
+  const responseShapeChange = diffResponseShapes(baseline, candidate);
+  return {
+    traceId: candidate.traceId,
+    baselineId: baseline.baselineId,
+    addedSignatures,
+    removedSignatures,
+    changedResources,
+    ...responseShapeChange ? { responseShapeChange } : {}
+  };
+}
+function isSecurityCritical2(event) {
+  return event.type === "auth_check" || event.type === "authorization_check" || Boolean(event.security?.["critical"]);
+}
+function buildResourceMap(session) {
+  const map = {};
+  for (const event of session.events) {
+    if (event.type === "db_query" && event.resource) {
+      const key = `${event.resource.type}:${event.resource.key}:${event.resource.operation}`;
+      map[key] = (map[key] ?? 0) + 1;
+    }
+  }
+  return map;
+}
+function diffResponseShapes(baseline, candidate) {
+  let candidateShape = { type: "unknown" };
+  for (const event of candidate.events) {
+    if (event.type === "http_response" && event.output) {
+      const normalised = normaliseForDiff(event.output);
+      candidateShape = extractShape(normalised);
+      break;
+    }
+  }
+  const baselineShape = baseline.responseShape;
+  if (baselineShape.type !== "object" || candidateShape.type !== "object") {
+    return null;
+  }
+  const baselineFields = new Set(Object.keys(baselineShape.properties ?? {}));
+  const candidateFields = new Set(Object.keys(candidateShape.properties ?? {}));
+  const addedFields = [...candidateFields].filter((f) => !baselineFields.has(f));
+  const removedFields = [...baselineFields].filter((f) => !candidateFields.has(f));
+  const typeChanges = [];
+  for (const field of baselineFields) {
+    if (!candidateFields.has(field)) continue;
+    const bType = (baselineShape.properties ?? {})[field]?.type;
+    const cType = (candidateShape.properties ?? {})[field]?.type;
+    if (bType !== cType && bType && cType) {
+      typeChanges.push({ field, from: String(bType), to: String(cType) });
+    }
+  }
+  if (addedFields.length === 0 && removedFields.length === 0 && typeChanges.length === 0) {
+    return null;
+  }
+  return { addedFields, removedFields, typeChanges };
+}
+
+// src/findings.ts
+import { createHash as createHash3 } from "crypto";
+var RULES = {
+  AUTHORIZATION_REMOVED: "behavior.authorization.removed",
+  MIDDLEWARE_REMOVED: "security.authorization.middleware_removed",
+  VALIDATION_REMOVED: "behavior.validation.removed",
+  BUSINESS_LOGIC_REMOVED: "behavior.business_logic.removed",
+  AUTHORIZATION_ADDED: "behavior.authorization.added",
+  RESOURCE_COUNT_CHANGED: "behavior.resource_count.changed",
+  RESPONSE_FIELD_REMOVED: "behavior.response_shape.field_removed",
+  RESPONSE_FIELD_ADDED: "behavior.response_shape.field_added"
+};
+function diffToFindings(diff) {
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const removed of diff.removedSignatures) {
+    const { ruleId, severity, category, title, description, recommendation } = classifyRemovedSignature(removed);
+    const fingerprint = computeFingerprint({
+      ruleId,
+      removed
+    });
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    findings.push({
+      id: `find_${fingerprint}`,
+      fingerprint,
+      ruleId,
+      severity,
+      category,
+      title,
+      description,
+      evidence: [{ traceId: diff.traceId, eventIds: [] }],
+      recommendation
+    });
+  }
+  for (const added of diff.addedSignatures) {
+    if (added.role !== "authorization" && !added.critical) continue;
+    const ruleId = RULES.AUTHORIZATION_ADDED;
+    const fingerprint = computeFingerprint({ ruleId, removed: added });
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    findings.push({
+      id: `find_${fingerprint}`,
+      fingerprint,
+      ruleId,
+      severity: "high",
+      category: "behavior_change",
+      title: `Authorization check added: ${sigLabel(added)}`,
+      description: `A new authorization check was introduced: "${added.eventName ?? sigLabel(added)}". Verify this is intentional and does not break existing authorized flows.`,
+      evidence: [{ traceId: diff.traceId, eventIds: added.eventId ? [added.eventId] : [] }],
+      recommendation: "Review the new authorization check and ensure all legitimate callers are still permitted."
+    });
+  }
+  for (const rc of diff.changedResources) {
+    const ruleId = RULES.RESOURCE_COUNT_CHANGED;
+    const fingerprint = createHash3("sha256").update(`${ruleId}:${rc.type}:${rc.key}:${rc.operation}`).digest("hex").slice(0, 16);
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    findings.push({
+      id: `find_${fingerprint}`,
+      fingerprint,
+      ruleId,
+      severity: "medium",
+      category: "behavior_change",
+      title: `Resource operation count changed: ${rc.type}.${rc.operation}`,
+      description: `The number of ${rc.operation} operations on "${rc.type}:${rc.key}" changed from ${rc.baselineCount} (baseline) to ${rc.candidateCount} (candidate).`,
+      evidence: [{ traceId: diff.traceId, eventIds: [] }],
+      recommendation: "Verify the change in operation count is expected."
+    });
+  }
+  if (diff.responseShapeChange) {
+    const rsc = diff.responseShapeChange;
+    for (const field of rsc.removedFields) {
+      const fingerprint = createHash3("sha256").update(`${RULES.RESPONSE_FIELD_REMOVED}:${diff.baselineId}:${field}`).digest("hex").slice(0, 16);
+      if (!seen.has(fingerprint)) {
+        seen.add(fingerprint);
+        findings.push({
+          id: `find_${fingerprint}`,
+          fingerprint,
+          ruleId: RULES.RESPONSE_FIELD_REMOVED,
+          severity: "low",
+          category: "behavior_change",
+          title: `Response field removed: "${field}"`,
+          description: `The field "${field}" was present in the baseline response shape but is absent in the candidate.`,
+          evidence: [{ traceId: diff.traceId, eventIds: [] }],
+          recommendation: "Verify this is a planned API change and update dependent clients."
+        });
+      }
+    }
+    for (const field of rsc.addedFields) {
+      const fingerprint = createHash3("sha256").update(`${RULES.RESPONSE_FIELD_ADDED}:${diff.baselineId}:${field}`).digest("hex").slice(0, 16);
+      if (!seen.has(fingerprint)) {
+        seen.add(fingerprint);
+        findings.push({
+          id: `find_${fingerprint}`,
+          fingerprint,
+          ruleId: RULES.RESPONSE_FIELD_ADDED,
+          severity: "info",
+          category: "behavior_change",
+          title: `Response field added: "${field}"`,
+          description: `The field "${field}" is present in the candidate response but was absent in the baseline.`,
+          evidence: [{ traceId: diff.traceId, eventIds: [] }]
+        });
+      }
+    }
+  }
+  return findings;
+}
+function computeFingerprint(input) {
+  const { ruleId, removed: sig } = input;
+  const s = sig.signature;
+  const parts = [
+    ruleId,
+    s.role ?? "",
+    s.routePathPattern ?? "",
+    s.routeMethod ?? "",
+    s.className ?? "",
+    s.methodName ?? "",
+    s.functionName ?? "",
+    s.resourceOperation ?? "",
+    s.resourceType ?? "",
+    s.resourceKey ?? ""
+  ];
+  return createHash3("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
+}
+function classifyRemovedSignature(removed) {
+  const label = sigLabel(removed);
+  const eventLabel = removed.eventName ?? label;
+  if (removed.role === "authorization" && removed.signature.routePathPattern && !removed.critical) {
+    return {
+      ruleId: RULES.MIDDLEWARE_REMOVED,
+      severity: "critical",
+      category: "security_authorization",
+      title: `Authorization middleware removed: ${eventLabel}`,
+      description: `A route-level authorization middleware "${eventLabel}" that guarded "${removed.signature.routeMethod ?? ""} ${removed.signature.routePathPattern}" in the baseline is absent in the candidate trace. Removing route middleware exposes every request to that route to unauthenticated or unauthorized access.`,
+      recommendation: "Restore the middleware or confirm the route is now protected by an equivalent mechanism."
+    };
+  }
+  if (removed.critical || removed.role === "authorization") {
+    return {
+      ruleId: RULES.AUTHORIZATION_REMOVED,
+      severity: "critical",
+      category: "security_authorization",
+      title: `Authorization check removed: ${eventLabel}`,
+      description: `An authorization check "${eventLabel}" that was present in the baseline is no longer present in the candidate trace. This may indicate a security regression.`,
+      recommendation: "Restore the authorization check or confirm this removal is intentional and safe."
+    };
+  }
+  if (removed.role === "validation") {
+    return {
+      ruleId: RULES.VALIDATION_REMOVED,
+      severity: "high",
+      category: "behavior_change",
+      title: `Validation step removed: ${eventLabel}`,
+      description: `A validation step "${eventLabel}" present in the baseline is absent in the candidate trace. Input may no longer be validated before processing.`,
+      recommendation: "Verify validation is still performed (possibly in a different location) or restore the validation step."
+    };
+  }
+  return {
+    ruleId: RULES.BUSINESS_LOGIC_REMOVED,
+    severity: "medium",
+    category: "behavior_change",
+    title: `Behaviour change: ${eventLabel} removed`,
+    description: `The event "${eventLabel}" was present in the baseline but is absent in the candidate trace.`,
+    recommendation: "Verify this change is intentional."
+  };
+}
+function sigLabel(change) {
+  const s = change.signature;
+  if (s.className && s.methodName) return `${s.className}.${s.methodName}`;
+  if (s.functionName) return s.functionName;
+  if (s.routePathPattern) return `${s.routeMethod ?? ""} ${s.routePathPattern}`.trim();
+  return s.eventType;
+}
+
+// src/evaluator.ts
+function evaluateFindings(findings, session, suppressions, approvals) {
+  const now = Date.now();
+  return findings.map((finding) => evaluate(finding, session, suppressions, approvals, now));
+}
+function evaluate(finding, session, suppressions, approvals, now) {
+  for (const approval of approvals) {
+    if (approval.findingFingerprint !== finding.fingerprint) continue;
+    if (new Date(approval.expiresAt).getTime() < now) continue;
+    return {
+      ...finding,
+      status: "approved",
+      approvedBy: approval.approvedBy,
+      approvedReason: approval.reason
+    };
+  }
+  for (const suppression of suppressions) {
+    if (suppression.ruleId !== finding.ruleId) continue;
+    if (new Date(suppression.expiresAt).getTime() < now) continue;
+    if (!semanticTargetMatches(suppression.semanticTarget, finding)) continue;
+    if (suppression.requiresEvidence && suppression.requiresEvidence.length > 0) {
+      const allPresent = suppression.requiresEvidence.every(
+        (item) => session.events.some(
+          (e) => e.type === item.type && (item.name === "*" || e.name.includes(item.name))
+        )
+      );
+      if (!allPresent) {
+        continue;
+      }
+    }
+    return {
+      ...finding,
+      status: "suppressed",
+      suppressedBy: suppression.approvedBy
+    };
+  }
+  return { ...finding, status: "open" };
+}
+function semanticTargetMatches(target, finding) {
+  if (Object.keys(target).length === 0) return true;
+  const titleAndDesc = `${finding.title} ${finding.description}`.toLowerCase();
+  if (target.functionName && !titleAndDesc.includes(target.functionName.toLowerCase())) {
+    return false;
+  }
+  if (target.className && !titleAndDesc.includes(target.className.toLowerCase())) {
+    return false;
+  }
+  if (target.routePathPattern && !titleAndDesc.includes(target.routePathPattern.toLowerCase())) {
+    return false;
+  }
+  if (target.role && !titleAndDesc.includes(target.role)) {
+    return false;
+  }
+  return true;
+}
+
+// src/analyse.ts
+import { createHash as createHash4 } from "crypto";
+var ANALYSE_RULES = {
+  SENSITIVE_DATA_IN_RESPONSE: "security.sensitive_data.in_response",
+  N_PLUS_ONE_QUERY: "reliability.n_plus_one_query",
+  DUPLICATE_SIDE_EFFECTS: "reliability.duplicate_side_effects",
+  MISSING_TRANSACTION: "reliability.missing_transaction"
+};
+var SENSITIVE_FIELD_NAMES = /* @__PURE__ */ new Set([
+  // Credentials
+  "password",
+  "passwd",
+  "pass",
+  "secret",
+  "credentials",
+  // API keys / tokens
+  "token",
+  "apikey",
+  "apisecret",
+  "privatekey",
+  "signingkey",
+  "clientsecret",
+  "clienttoken",
+  // Auth tokens
+  "authtoken",
+  "accesstoken",
+  "refreshtoken",
+  "sessiontoken",
+  "idtoken",
+  "bearer",
+  // Payment / PII
+  "creditcard",
+  "cardnumber",
+  "cardcvv",
+  "cvv",
+  "cvc",
+  "cvc2",
+  "ssn",
+  "socialsecurity"
+]);
+var N_PLUS_ONE_THRESHOLD = 5;
+var WRITE_OPERATIONS = /* @__PURE__ */ new Set(["write", "insert", "update", "delete", "upsert", "create"]);
+function analyseTraceFindings(session) {
+  return [
+    ...detectSensitiveDataInResponse(session),
+    ...detectNPlusOneQuery(session),
+    ...detectDuplicateSideEffects(session),
+    ...detectMissingTransaction(session)
+  ];
+}
+function detectSensitiveDataInResponse(session) {
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const event of session.events) {
+    if (event.type !== "http_response") continue;
+    if (!event.output || typeof event.output !== "object" || Array.isArray(event.output)) continue;
+    const fields = collectKeys(event.output);
+    for (const field of fields) {
+      if (!isSensitiveFieldName(field)) continue;
+      const fingerprint = fp(ANALYSE_RULES.SENSITIVE_DATA_IN_RESPONSE, session.traceId, field);
+      if (seen.has(fingerprint)) continue;
+      seen.add(fingerprint);
+      findings.push({
+        id: `find_${fingerprint}`,
+        fingerprint,
+        ruleId: ANALYSE_RULES.SENSITIVE_DATA_IN_RESPONSE,
+        severity: "high",
+        category: "security_sensitive_data",
+        title: `Sensitive field in HTTP response: "${field}"`,
+        description: `The field "${field}" appears in the HTTP response payload and may expose sensitive data (password, token, secret, PII). Leaking such fields in API responses is a security risk and may violate data-protection requirements.`,
+        evidence: [{ traceId: session.traceId, eventIds: event.eventId ? [event.eventId] : [] }],
+        recommendation: `Remove "${field}" from the response or redact its value before sending. Use an API resource / serializer layer to explicitly whitelist the fields your API should expose (e.g. Laravel API Resources, a JSON:API transformer).`
+      });
+    }
+  }
+  return findings;
+}
+function detectNPlusOneQuery(session) {
+  const findings = [];
+  const groups = /* @__PURE__ */ new Map();
+  for (const event of session.events) {
+    if (event.type !== "db_query" || !event.resource) continue;
+    const { type: resourceType, operation } = event.resource;
+    const key = `${resourceType}\0${operation}`;
+    let entry = groups.get(key);
+    if (!entry) {
+      entry = { count: 0, eventIds: [], resourceType, operation };
+      groups.set(key, entry);
+    }
+    entry.count++;
+    if (event.eventId) entry.eventIds.push(event.eventId);
+  }
+  for (const entry of groups.values()) {
+    if (entry.count < N_PLUS_ONE_THRESHOLD) continue;
+    const fingerprint = fp(
+      ANALYSE_RULES.N_PLUS_ONE_QUERY,
+      session.traceId,
+      `${entry.resourceType}\0${entry.operation}`
+    );
+    findings.push({
+      id: `find_${fingerprint}`,
+      fingerprint,
+      ruleId: ANALYSE_RULES.N_PLUS_ONE_QUERY,
+      severity: "medium",
+      category: "performance",
+      title: `Possible N+1 query: ${entry.resourceType}.${entry.operation} \xD7 ${entry.count}`,
+      description: `The "${entry.operation}" operation on "${entry.resourceType}" was executed ${entry.count} times in a single request. This pattern commonly indicates an N+1 problem where child records are fetched individually in a loop rather than in a single batched query.`,
+      evidence: [{ traceId: session.traceId, eventIds: entry.eventIds.slice(0, 10) }],
+      recommendation: `Use eager loading to batch-fetch related records (e.g. Eloquent \`with()\`, TypeORM \`relations\`, Sequelize \`include\`). Add a query counter assertion to your test suite to prevent regressions.`
+    });
+  }
+  return findings;
+}
+function detectDuplicateSideEffects(session) {
+  const findings = [];
+  const queueGroups = /* @__PURE__ */ new Map();
+  const outboundGroups = /* @__PURE__ */ new Map();
+  for (const event of session.events) {
+    if (event.type === "queue_event" && event.name) {
+      addToGroup(queueGroups, event.name, event.eventId);
+    }
+    if (event.type === "external_http_call") {
+      const method = String(
+        event.metadata?.["method"] ?? ""
+      ).toUpperCase();
+      if (!["POST", "PUT", "PATCH", "DELETE"].includes(method)) continue;
+      const url = String(
+        event.metadata?.["url"] ?? event.name ?? ""
+      );
+      addToGroup(outboundGroups, `${method}:${url}`, event.eventId);
+    }
+  }
+  for (const [name, entry] of queueGroups) {
+    if (entry.count < 2) continue;
+    const fingerprint = fp(ANALYSE_RULES.DUPLICATE_SIDE_EFFECTS, session.traceId, `queue:${name}`);
+    findings.push({
+      id: `find_${fingerprint}`,
+      fingerprint,
+      ruleId: ANALYSE_RULES.DUPLICATE_SIDE_EFFECTS,
+      severity: "medium",
+      category: "data_integrity",
+      title: `Duplicate queue dispatch: "${name}" \xD7 ${entry.count}`,
+      description: `The job/event "${name}" was dispatched ${entry.count} times within a single request. Unless this is intentional, consumers may process the same work multiple times (e.g. duplicate emails, double charges, redundant notifications).`,
+      evidence: [{ traceId: session.traceId, eventIds: entry.eventIds }],
+      recommendation: `Verify the dispatch is not inside a loop or on multiple code paths. Consider idempotency keys or a deduplication layer in the queue consumer.`
+    });
+  }
+  for (const [key, entry] of outboundGroups) {
+    if (entry.count < 2) continue;
+    const colonIdx = key.indexOf(":");
+    const method = key.slice(0, colonIdx);
+    const url = key.slice(colonIdx + 1);
+    const fingerprint = fp(ANALYSE_RULES.DUPLICATE_SIDE_EFFECTS, session.traceId, key);
+    findings.push({
+      id: `find_${fingerprint}`,
+      fingerprint,
+      ruleId: ANALYSE_RULES.DUPLICATE_SIDE_EFFECTS,
+      severity: "medium",
+      category: "data_integrity",
+      title: `Duplicate outbound ${method}: "${url}" \xD7 ${entry.count}`,
+      description: `An outbound ${method} request to "${url}" was made ${entry.count} times in a single request. This may cause unintended duplicate writes or side effects on the remote service.`,
+      evidence: [{ traceId: session.traceId, eventIds: entry.eventIds }],
+      recommendation: `Check whether the call appears in a loop or on multiple branches. If idempotency is required, pass an idempotency key in the request headers.`
+    });
+  }
+  return findings;
+}
+function detectMissingTransaction(session) {
+  const hasTransaction = session.events.some(
+    (e) => e.type === "transaction_start" || e.type === "transaction_commit" || e.type === "transaction_rollback"
+  );
+  if (hasTransaction) return [];
+  const writeEvents = session.events.filter(
+    (e) => e.type === "db_query" && e.resource != null && WRITE_OPERATIONS.has(e.resource.operation)
+  );
+  const tables = new Set(writeEvents.map((e) => e.resource.type));
+  if (tables.size < 2) return [];
+  const sortedTables = [...tables].sort();
+  const fingerprint = fp(
+    ANALYSE_RULES.MISSING_TRANSACTION,
+    session.traceId,
+    sortedTables.join(",")
+  );
+  const tableList = sortedTables.join(", ");
+  return [{
+    id: `find_${fingerprint}`,
+    fingerprint,
+    ruleId: ANALYSE_RULES.MISSING_TRANSACTION,
+    severity: "medium",
+    category: "data_integrity",
+    title: `Multi-table write without transaction: ${tableList}`,
+    description: `Write operations were performed on multiple tables (${tableList}) within a single request but no transaction boundary was observed. If an error occurs part-way through, the database may be left in an inconsistent state.`,
+    evidence: [{
+      traceId: session.traceId,
+      eventIds: writeEvents.map((e) => e.eventId).filter((id) => id != null)
+    }],
+    recommendation: `Wrap the multi-table writes in a database transaction. Laravel: \`DB::transaction(fn() => ...)\`. Express/TypeORM: \`dataSource.transaction(async (em) => ...)\`.`
+  }];
+}
+function fp(...parts) {
+  return createHash4("sha256").update(parts.join("\0")).digest("hex").slice(0, 16);
+}
+function normaliseName(name) {
+  return name.toLowerCase().replace(/[-_]/g, "");
+}
+function isSensitiveFieldName(field) {
+  return SENSITIVE_FIELD_NAMES.has(normaliseName(field));
+}
+function collectKeys(obj, depth = 0) {
+  const keys = [];
+  for (const [key, value] of Object.entries(obj)) {
+    keys.push(key);
+    if (depth < 2 && value !== null && typeof value === "object" && !Array.isArray(value)) {
+      keys.push(...collectKeys(value, depth + 1));
+    }
+  }
+  return keys;
+}
+function addToGroup(map, key, eventId) {
+  let entry = map.get(key);
+  if (!entry) {
+    entry = { count: 0, eventIds: [] };
+    map.set(key, entry);
+  }
+  entry.count++;
+  if (eventId) entry.eventIds.push(eventId);
+}
+export {
+  ANALYSE_RULES,
+  analyseTraceFindings,
+  classifyRole,
+  computeFingerprint,
+  deriveTestId,
+  diffBaseline,
+  diffToFindings,
+  evaluateFindings,
+  eventToSignature,
+  extractShape,
+  sessionToBaseline,
+  signatureToIdentityHash,
+  traceSessionToGraph
+};