@clear-capabilities/agentic-security-scanner 0.184.0 → 0.185.0

package/src/graph/registry.js

@@ -0,0 +1,129 @@
+//
+// registry.js: the set of graph views a query may span (DAG-06 R06.6).
+//
+// What registration rejects, each with a typed GraphViewError:
+//   INCOMPATIBLE_VERSION  an adapter whose major version this build cannot read
+//   ID_COLLISION          the same (graph kind, repository, digest) registered
+//                         twice with different content: a digest names ONE
+//                         immutable graph
+//   BAD_REF               a malformed view
+//
+// What lookups reject:
+//   DANGLING_REF          the graph is not registered, or the entity is not in it
+//   VERSION_INCOMPATIBLE  a reference written by a newer reference format
+//   AMBIGUOUS_LOCAL_ID   a bare local id that exists in more than one graph; a
+//                         local id is only meaningful inside its graph, so the
+//                         registry will not pick one
+//
+// A reference never resolves across repositories: the repository is part of the
+// reference, so `pnode:abc` in repository A and `pnode:abc` in repository B are
+// two different entities.
+
+import { GraphViewError, graphIdentityKey, validateRef, REF_VERSION } from './refs.js';
+import { PROVENANCE_ADAPTER_VERSION } from './adapters/provenance.js';
+import { DATAFLOW_ADAPTER_VERSION } from './adapters/dataflow.js';
+import { SEMANTIC_ADAPTER_VERSION } from './adapters/semantic.js';
+import { ARTIFACT_ADAPTER_VERSION } from './adapters/artifact.js';
+import { CROSSREPO_ADAPTER_VERSION, FINDINGS_ADAPTER_VERSION } from './adapters/crossrepo.js';
+
+const major = (v) => Number(String(v).split('.')[0]);
+
+/** Adapter majors this build understands, per graph kind. */
+export const SUPPORTED_ADAPTER_MAJORS = Object.freeze({
+  provenance: [major(PROVENANCE_ADAPTER_VERSION)],
+  dataflow: [major(DATAFLOW_ADAPTER_VERSION)],
+  semantic: [major(SEMANTIC_ADAPTER_VERSION)],
+  artifact: [major(ARTIFACT_ADAPTER_VERSION)],
+  'cross-repo-links': [major(CROSSREPO_ADAPTER_VERSION)],
+  findings: [major(FINDINGS_ADAPTER_VERSION)],
+});
+
+export function createGraphRegistry() {
+  const views = new Map(); // identity key -> view
+
+  function viewFor(ref) {
+    const bad = validateRef(ref);
+    if (bad) {
+      throw new GraphViewError(ref && ref.v !== undefined && ref.v !== REF_VERSION ? 'VERSION_INCOMPATIBLE' : 'BAD_REF', bad, { ref });
+    }
+    const v = views.get(graphIdentityKey(ref));
+    if (!v) throw new GraphViewError('DANGLING_REF', `no registered ${ref.graphKind} graph for repository ${ref.repository} with digest ${ref.graphDigest.slice(0, 12)}`, { ref });
+    return v;
+  }
+
+  const foreignViews = () => [...views.values()].filter((v) => v._allowForeign);
+
+  return {
+    register(view) {
+      const kinds = SUPPORTED_ADAPTER_MAJORS[view?.graphKind];
+      if (!kinds) throw new GraphViewError('BAD_REF', `unknown graph kind ${view?.graphKind}`);
+      if (!kinds.includes(major(view.adapterVersion))) {
+        throw new GraphViewError('INCOMPATIBLE_VERSION', `${view.graphKind} adapter ${view.adapterVersion} is not readable by this build (supported majors: ${kinds.join(',')})`);
+      }
+      const key = graphIdentityKey(view);
+      const prev = views.get(key);
+      if (prev) {
+        if (prev.fingerprint !== view.fingerprint) {
+          throw new GraphViewError('ID_COLLISION', `${view.graphKind}/${view.repository} digest ${view.graphDigest.slice(0, 12)} is already registered with different content`, { key });
+        }
+        return prev;
+      }
+      views.set(key, view);
+      return view;
+    },
+
+    views() { return [...views.values()]; },
+    viewFor,
+
+    has(ref) {
+      const v = views.get(graphIdentityKey(ref));
+      return !!v && v.has(ref);
+    },
+
+    node(ref) { return viewFor(ref).node(ref); },
+
+    outgoing(ref, filter) {
+      const out = viewFor(ref).outgoing(ref, filter);
+      for (const fv of foreignViews()) if (fv.graphKind !== ref.graphKind || fv.repository !== ref.repository || fv.graphDigest !== ref.graphDigest) out.push(...fv.outgoing(ref, filter));
+      return out;
+    },
+
+    incoming(ref, filter) {
+      const inn = viewFor(ref).incoming(ref, filter);
+      for (const fv of foreignViews()) if (fv.graphKind !== ref.graphKind || fv.repository !== ref.repository || fv.graphDigest !== ref.graphDigest) inn.push(...fv.incoming(ref, filter));
+      return inn;
+    },
+
+    /** A bare local id is ambiguous when more than one registered graph has it. */
+    resolveLocal(entityKind, localId, { graphKind } = {}) {
+      const hits = [];
+      for (const v of views.values()) {
+        if (graphKind && v.graphKind !== graphKind) continue;
+        try { hits.push(v.ref(entityKind, localId)); } catch { /* not in this graph */ }
+      }
+      if (hits.length === 0) throw new GraphViewError('DANGLING_REF', `no ${entityKind} ${localId} in any registered graph`);
+      if (hits.length > 1) throw new GraphViewError('AMBIGUOUS_LOCAL_ID', `${entityKind} ${localId} exists in ${hits.length} registered graphs; use a full reference`, { candidates: hits });
+      return hits[0];
+    },
+
+    /**
+     * Classify a foreign endpoint (for example, a cross-repository link end):
+     *   resolved             registered, and the entity exists
+     *   unresolved           no registered graph with that identity (not an error:
+     *                        the remote graph simply is not loaded)
+     *   dangling             the graph is registered but the entity is not in it
+     *   repository-mismatch  a graph with that digest is registered, but under a
+     *                        different repository than the reference claims
+     */
+    classify(ref) {
+      const bad = validateRef(ref);
+      if (bad) throw new GraphViewError('BAD_REF', bad, { ref });
+      const v = views.get(graphIdentityKey(ref));
+      if (v) return v.has(ref) ? 'resolved' : 'dangling';
+      for (const o of views.values()) {
+        if (o.graphKind === ref.graphKind && o.graphDigest === ref.graphDigest && o.repository !== ref.repository) return 'repository-mismatch';
+      }
+      return 'unresolved';
+    },
+  };
+}

package/src/graph/relations.js

@@ -0,0 +1,81 @@
+//
+// relations.js: relation kinds and the traversal filter (DAG-06 R06.3, R06.4).
+//
+// Two independent axes, never collapsed into one:
+//   - RELATION: what the edge means (data flow, calls, ...).
+//   - ORIGIN: how the edge came to exist (derived from code, declared by an
+//     operator, observed at runtime, ...).
+//
+// A query chooses the relations it may traverse AND the origins it trusts.
+// The default filter traverses code-derived and derived edges only, so an
+// operator declaration or a runtime observation is never silently walked as
+// if it were a code-derived data flow (R06.4).
+
+import { GraphViewError } from './refs.js';
+
+export const RELATION_KINDS = Object.freeze([
+  'data_flow',            // a value moves from one place to another
+  'control_dependence',   // execution of B depends on a decision at A
+  'calls',                // a call site invokes a callee
+  'returns',              // a callee result comes back to a caller
+  'dependency',           // A needs B (package, module, component)
+  'declaration',          // A declares/contains B (symbol -> call site, origin)
+  'observation',          // a runtime observation attached to an entity
+  'artifact_derivation',  // A was built into / produced B
+]);
+
+export const EDGE_ORIGINS = Object.freeze([
+  'code',      // read directly from analyzed source
+  'derived',   // computed from code-derived facts by a projection or index
+  'declared',  // asserted by an operator (cross-repo links, deployments)
+  'observed',  // seen at runtime (telemetry)
+  'schema',    // taken from a schema or manifest
+]);
+
+/** Origins a default query trusts as "the program's own structure". */
+export const DEFAULT_TRUSTED_ORIGINS = Object.freeze(['code', 'derived', 'schema']);
+
+/**
+ * Normalize a relation filter. Accepted forms:
+ *   undefined / null          -> every relation, trusted origins only
+ *   'calls' | ['calls', ...]  -> those relations, trusted origins only
+ *   { relations, origins }    -> explicit on both axes
+ * Unknown relation or origin names throw, so a typo never silently widens
+ * or empties a query.
+ */
+export function normalizeFilter(filter) {
+  let relations = null;
+  let origins = DEFAULT_TRUSTED_ORIGINS;
+  if (filter === undefined || filter === null) {
+    // defaults
+  } else if (typeof filter === 'string') {
+    relations = [filter];
+  } else if (Array.isArray(filter)) {
+    relations = filter;
+  } else if (typeof filter === 'object') {
+    if (filter.relations !== undefined && filter.relations !== null) {
+      relations = typeof filter.relations === 'string' ? [filter.relations] : filter.relations;
+    }
+    if (filter.origins !== undefined && filter.origins !== null) {
+      origins = typeof filter.origins === 'string' ? [filter.origins] : filter.origins;
+    }
+  } else {
+    throw new GraphViewError('BAD_FILTER', 'a relation filter is a name, a list of names or { relations, origins }');
+  }
+  if (relations !== null) {
+    if (!Array.isArray(relations)) throw new GraphViewError('BAD_FILTER', 'relations must be a list');
+    for (const r of relations) {
+      if (!RELATION_KINDS.includes(r)) throw new GraphViewError('BAD_FILTER', `unknown relation kind ${JSON.stringify(r)}`);
+    }
+  }
+  if (!Array.isArray(origins)) throw new GraphViewError('BAD_FILTER', 'origins must be a list');
+  for (const o of origins) {
+    if (!EDGE_ORIGINS.includes(o)) throw new GraphViewError('BAD_FILTER', `unknown edge origin ${JSON.stringify(o)}`);
+  }
+  return { relations: relations ? new Set(relations) : null, origins: new Set(origins) };
+}
+
+export function edgeMatches(edge, nf) {
+  if (nf.relations && !nf.relations.has(edge.relation)) return false;
+  return nf.origins.has(edge.origin);
+}

package/src/graph/scc.js

@@ -0,0 +1,241 @@
+// Strongly connected components and condensation for typed directed graphs.
+//
+// Pure and iterative: no recursion anywhere (a 100,000-node chain must not
+// overflow the JavaScript stack), no I/O, no dependence on any analysis
+// engine. The raw graph is never modified; the condensation is a derived
+// view. It is a DAG, the raw graph is a provenance graph that may be cyclic.
+//
+// Input: `{ nodes: string[], edges: Array<[from, to] | {from, to}> }`.
+// Node ids are strings. Duplicate nodes and duplicate edges are collapsed.
+// An edge whose endpoint is not in `nodes` throws a TypeError rather than
+// being silently dropped (the caller decides how to filter).
+//
+// Output is independent of the order of `nodes` and `edges`:
+//   components    Array<{ id, members, internalEdges, recursive }>
+//                 ids are 0..n-1 assigned by ascending smallest member, so
+//                 they are stable. `members` is sorted. `internalEdges` is the
+//                 sorted, de-duplicated list of [from, to] inside the
+//                 component (self-loops included). `recursive` is true when
+//                 the component has more than one member or a self-loop.
+//   componentOf   Map<node, componentId>
+//   condensationEdges  sorted unique [fromId, toId] across components
+//   order         component ids in a deterministic topological order: for
+//                 every cross-component edge u -> v, comp(u) appears before
+//                 comp(v). Ties are broken by smallest component id.
+//
+// To schedule callees before callers, pass edges as callee -> caller (or
+// reverse `order`). SCC membership says nodes can reach each other; it is
+// not evidence that every pair has a feasible data path in any context.
+
+function cmp(a, b) { return a < b ? -1 : a > b ? 1 : 0; }
+
+function edgeEnds(e) {
+  if (Array.isArray(e)) return [e[0], e[1]];
+  return [e.from, e.to];
+}
+
+// Minimal binary min-heap of non-negative integers.
+class IntHeap {
+  constructor() { this.a = []; }
+  get size() { return this.a.length; }
+  push(v) {
+    const a = this.a;
+    let i = a.length;
+    a.push(v);
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (a[p] <= v) break;
+      a[i] = a[p];
+      i = p;
+    }
+    a[i] = v;
+  }
+  pop() {
+    const a = this.a;
+    const top = a[0];
+    const last = a.pop();
+    if (a.length > 0) {
+      let i = 0;
+      const n = a.length;
+      for (;;) {
+        let c = 2 * i + 1;
+        if (c >= n) break;
+        if (c + 1 < n && a[c + 1] < a[c]) c++;
+        if (a[c] >= last) break;
+        a[i] = a[c];
+        i = c;
+      }
+      a[i] = last;
+    }
+    return top;
+  }
+}
+
+export function computeScc(graph) {
+  const rawNodes = (graph && graph.nodes) || [];
+  const rawEdges = (graph && graph.edges) || [];
+  const names = [...new Set(rawNodes)].sort(cmp);
+  const n = names.length;
+  const index = new Map();
+  for (let i = 0; i < n; i++) index.set(names[i], i);
+
+  // Adjacency over integer indexes, de-duplicated and sorted.
+  const adjSets = new Array(n).fill(null);
+  for (const e of rawEdges) {
+    const [f, t] = edgeEnds(e);
+    const fi = index.get(f);
+    const ti = index.get(t);
+    if (fi === undefined || ti === undefined) {
+      throw new TypeError(`scc: edge endpoint not in nodes: ${String(f)} -> ${String(t)}`);
+    }
+    (adjSets[fi] ||= new Set()).add(ti);
+  }
+  const adj = adjSets.map(s => (s ? [...s].sort((a, b) => a - b) : []));
+
+  // Iterative Tarjan with explicit call stack.
+  const idx = new Int32Array(n).fill(-1);
+  const low = new Int32Array(n);
+  const onStack = new Uint8Array(n);
+  const comp = new Int32Array(n).fill(-1);
+  const sccStack = [];
+  const callNode = [];
+  const callPos = [];
+  let counter = 0;
+  const rawComps = [];
+  for (let root = 0; root < n; root++) {
+    if (idx[root] !== -1) continue;
+    callNode.push(root); callPos.push(0);
+    idx[root] = low[root] = counter++;
+    sccStack.push(root); onStack[root] = 1;
+    while (callNode.length > 0) {
+      const top = callNode.length - 1;
+      const v = callNode[top];
+      const pos = callPos[top];
+      const out = adj[v];
+      if (pos < out.length) {
+        callPos[top] = pos + 1;
+        const w = out[pos];
+        if (idx[w] === -1) {
+          idx[w] = low[w] = counter++;
+          sccStack.push(w); onStack[w] = 1;
+          callNode.push(w); callPos.push(0);
+        } else if (onStack[w] && idx[w] < low[v]) {
+          low[v] = idx[w];
+        }
+      } else {
+        if (low[v] === idx[v]) {
+          const members = [];
+          let w;
+          do {
+            w = sccStack.pop();
+            onStack[w] = 0;
+            members.push(w);
+          } while (w !== v);
+          rawComps.push(members);
+        }
+        callNode.pop(); callPos.pop();
+        if (callNode.length > 0) {
+          const parent = callNode[callNode.length - 1];
+          if (low[v] < low[parent]) low[parent] = low[v];
+        }
+      }
+    }
+  }
+
+  // Canonical component ids: ascending smallest member index (indexes follow
+  // the sorted names, so this is order-independent).
+  for (const m of rawComps) m.sort((a, b) => a - b);
+  rawComps.sort((a, b) => a[0] - b[0]);
+  for (let c = 0; c < rawComps.length; c++) for (const v of rawComps[c]) comp[v] = c;
+
+  const k = rawComps.length;
+  const internal = Array.from({ length: k }, () => []);
+  const condSets = new Array(k).fill(null);
+  for (let v = 0; v < n; v++) {
+    const cv = comp[v];
+    for (const w of adj[v]) {
+      const cw = comp[w];
+      if (cv === cw) internal[cv].push([v, w]);
+      else (condSets[cv] ||= new Set()).add(cw);
+    }
+  }
+  const condAdj = condSets.map(s => (s ? [...s].sort((a, b) => a - b) : []));
+
+  // Kahn's algorithm with a min-heap on component id.
+  const indeg = new Int32Array(k);
+  for (let c = 0; c < k; c++) for (const d of condAdj[c]) indeg[d]++;
+  const heap = new IntHeap();
+  for (let c = 0; c < k; c++) if (indeg[c] === 0) heap.push(c);
+  const order = [];
+  while (heap.size > 0) {
+    const c = heap.pop();
+    order.push(c);
+    for (const d of condAdj[c]) if (--indeg[d] === 0) heap.push(d);
+  }
+
+  const components = new Array(k);
+  for (let c = 0; c < k; c++) {
+    const members = rawComps[c].map(i => names[i]);
+    const internalEdges = internal[c].map(([a, b]) => [names[a], names[b]]);
+    internalEdges.sort((x, y) => cmp(x[0], y[0]) || cmp(x[1], y[1]));
+    components[c] = {
+      id: c,
+      members,
+      internalEdges,
+      recursive: members.length > 1 || internalEdges.length > 0,
+    };
+  }
+  const componentOf = new Map();
+  for (let v = 0; v < n; v++) componentOf.set(names[v], comp[v]);
+  const condensationEdges = [];
+  for (let c = 0; c < k; c++) for (const d of condAdj[c]) condensationEdges.push([c, d]);
+
+  return { components, componentOf, condensationEdges, order };
+}
+
+// Checks a result against its input graph. Returns `{ ok, problems }`; every
+// problem is a human-readable string. Verifies: each node is in exactly one
+// component, members are sorted, every edge is either internal to a
+// component or goes forward in `order`, internal edges match, and the
+// condensation edges are exactly the cross-component edges.
+export function verifyScc(graph, result) {
+  const problems = [];
+  const nodes = [...new Set((graph && graph.nodes) || [])];
+  const pos = new Map();
+  result.order.forEach((c, i) => pos.set(c, i));
+  if (result.order.length !== result.components.length || pos.size !== result.components.length) {
+    problems.push('order is not a permutation of the components');
+  }
+  const seen = new Set();
+  for (const c of result.components) {
+    for (let i = 0; i < c.members.length; i++) {
+      if (i > 0 && !(c.members[i - 1] < c.members[i])) problems.push(`component ${c.id} members not strictly sorted`);
+      if (seen.has(c.members[i])) problems.push(`node ${c.members[i]} in more than one component`);
+      seen.add(c.members[i]);
+      if (result.componentOf.get(c.members[i]) !== c.id) problems.push(`componentOf disagrees for ${c.members[i]}`);
+    }
+  }
+  for (const nd of nodes) if (!seen.has(nd)) problems.push(`node ${nd} missing from components`);
+  const cross = new Set();
+  const internalCount = new Map();
+  const edgeSeen = new Set();
+  for (const e of (graph && graph.edges) || []) {
+    const [f, t] = edgeEnds(e);
+    const key = `${f}\u0000${t}`;
+    if (edgeSeen.has(key)) continue;
+    edgeSeen.add(key);
+    const cf = result.componentOf.get(f);
+    const ct = result.componentOf.get(t);
+    if (cf === undefined || ct === undefined) { problems.push(`edge ${f} -> ${t} has an unknown endpoint`); continue; }
+    if (cf === ct) { internalCount.set(cf, (internalCount.get(cf) || 0) + 1); continue; }
+    cross.add(`${cf}\u0000${ct}`);
+    if (!(pos.get(cf) < pos.get(ct))) problems.push(`cross edge ${f} -> ${t} violates topological order`);
+  }
+  for (const c of result.components) {
+    if (c.internalEdges.length !== (internalCount.get(c.id) || 0)) problems.push(`component ${c.id} internal edge count mismatch`);
+    if (c.recursive !== (c.members.length > 1 || c.internalEdges.length > 0)) problems.push(`component ${c.id} recursive flag wrong`);
+  }
+  const condKeys = new Set(result.condensationEdges.map(([a, b]) => `${a}\u0000${b}`));
+  if (condKeys.size !== cross.size || [...cross].some(x => !condKeys.has(x))) problems.push('condensation edges differ from the cross-component edges');
+  return { ok: problems.length === 0, problems };
+}