@holmes-lab/holmes-kit 0.3.10 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+<!-- @implements A-SPEC-209 -->
+## [0.4.0] - 2026-09-02
+
+The code property graph gets a real foundation, and "officially supported language" becomes a
+checkable fact instead of a sentence. Minor bump: new analysis layers ship, and the language
+capability table widens — no existing behaviour changes.
+
+### Added
+
+- **CPG foundation, layered** (REQ-510): a tree-sitter (wasm) substrate replaces ad-hoc parsing
+  for the analysis layers, and four layers land on top of it — **L1** lossless-span AST with a
+  basis-checked cache, **L2** control-flow graphs with Cooper–Harvey–Kennedy dominator and
+  post-dominator trees, **L3** reaching definitions (`REACHING_DEF`) and control dependence
+  (`CDG`, Ferrante–Ottenstein–Warren); PDG is their union. Vocabulary follows the Joern CPG
+  specification so external comparison stays apples-to-apples. **TypeScript/JavaScript and
+  Python** are lowered; every other language refuses honestly rather than returning a partial
+  graph, because a partial control-flow graph is a wrong one.
+  Dogfooded: 10,929 functions in this repository and 1,209 in an external Python corpus build
+  with **zero invariant violations** (34,946 REACHING_DEF and 15,090 CDG edges here).
+  Python's own semantics are pinned, not approximated: a loop's `else` runs only on exhaustion
+  (a `break` bypasses it), `match` has no fallthrough, and `try/else` runs only when nothing
+  was raised.
+- **Layer × language support matrix** (A-SPEC-510.6): `docs/language-support.md` is now
+  GENERATED from the modules that own each capability — a test pins it byte-identical, so the
+  table cannot drift from the code. It states plainly what was previously unwritten: `taint_scan`
+  analyses the TypeScript family only, and C++ has no test-runner adapter.
+- **Inheritance for five more languages** (REQ-511): Java (`extends` + `implements`), C#
+  (`base_list`), C++ (`base_class_clause`), Rust (`impl Trait for`) and Go (**struct embedding**)
+  now produce `inherits` edges that reach the RTM graph — so impact traversal finally sees a base
+  type's dependants in those languages. Go's interface satisfaction stays unrecovered by design:
+  it is implicit and structural, and guessing it would be worse than declaring the gap.
+
+### Fixed
+
+- **`test_run` false red on large suites**: every runner spawn used `execFileSync`'s default 1MB
+  buffer, so a full `jest --json` (>2MB here) died with ENOBUFS and a GREEN suite reported as
+  failed with no failing test named. All six runner adapters now share a 256MB ceiling.
+- **pre-push gate**: `core.hooksPath` is honored (installing into `.git/hooks` was a silent no-op
+  where that config is set), and tag refs are no longer judged — a tag names an existing commit
+  rather than advancing a baseline.
+
+<!-- @implements A-SPEC-209 -->
+## [0.3.11] - 2026-09-01
+
+### Fixed
+
+- **push gate: tag refs are names, not baselines** (dogfooded): pushing `--tags` sends
+  `refs/tags` lines whose shas are usually ancestors of the evidenced tip, and the exact-head
+  rule refused the release-tag push of the very version that shipped the gate. Only
+  `refs/heads` lines are judged now — a tag merely names an existing commit.
+
 <!-- @implements A-SPEC-209 -->
 ## [0.3.10] - 2026-09-01
 

package/dist/.build-id

@@ -1 +1 @@
-1085a02-mti0yut3
+3e5ef00-mtiwan92

package/dist/holmes/cpg/foundation/ast-store.d.ts

@@ -0,0 +1,49 @@
+/** The honest language envelope: exactly what the vendored grammars cover — nothing more. */
+export declare const AST_LANGUAGES: ReadonlyArray<{
+    ext: RegExp;
+    lang: 'typescript' | 'tsx' | 'python';
+    wasm: string;
+}>;
+export interface AstNodeRow {
+    /** tree-sitter node type (grammar vocabulary). */
+    type: string;
+    /** Byte-offset span into the source: 0 <= start <= end <= sourceLen. */
+    start: number;
+    end: number;
+    /** Index of the parent row in the flat array (-1 for the root). Pre-order layout. */
+    parent: number;
+    /** tree-sitter "named" node (true) vs anonymous token (false). */
+    named: boolean;
+}
+export interface PersistedAst {
+    lang: string;
+    grammarVersion: string;
+    runtimeVersion: string;
+    sourceHash: string;
+    sourceLen: number;
+    /** ERROR + missing nodes seen during the parse — partial parses are recorded, never hidden. */
+    errorCount: number;
+    nodes: AstNodeRow[];
+}
+/** Exposed for tests/tools that want to pay the load cost up front. */
+export declare function initSubstrate(): Promise<void>;
+export declare function languageFor(relPath: string): {
+    lang: string;
+    wasm: string;
+} | null;
+/** Parse one source into the flat lossless-span form. Throws only on substrate failure. */
+export declare function parseAst(source: string, relPath: string): Promise<PersistedAst | null>;
+export declare const AST_CACHE_DIR: string;
+/** Observable for tests: how many astOf calls were served without a parse. */
+export declare const cacheStats: {
+    hits: number;
+    misses: number;
+};
+/**
+ * Basis-checked persisted AST for a repo file. Hit only when sourceHash AND grammar AND runtime
+ * versions all match (GraphBasis doctrine: any moved field means reparse); a corrupt cache file
+ * degrades to a miss, never a crash. The cache directory is delete-safe — everything regenerates.
+ */
+export declare function astOf(root: string, relPath: string): Promise<PersistedAst | null>;
+/** The span invariants of REQ-510 L1 — violations by name, [] when the contract holds. */
+export declare function spanViolations(ast: PersistedAst): string[];

package/dist/holmes/cpg/foundation/ast-store.js

@@ -0,0 +1,209 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheStats = exports.AST_CACHE_DIR = exports.AST_LANGUAGES = void 0;
+exports.initSubstrate = initSubstrate;
+exports.languageFor = languageFor;
+exports.parseAst = parseAst;
+exports.astOf = astOf;
+exports.spanViolations = spanViolations;
+// @implements A-SPEC-510.2
+/**
+ * L1 of the CPG foundation: lossless-span AST persistence on the tree-sitter(wasm) substrate
+ * (decided by the S-510.1 five-axis probe; grammar provenance sealed by scripts/sync-grammars.js).
+ *
+ * LOSSLESS is a span contract, not a text copy: every node carries byte offsets into the source,
+ * the root covers [0, sourceLen], children nest inside their parent, and a node's text is
+ * reconstructible as source.slice(start, end). The tree is stored as a flat parent-indexed array —
+ * compact, order-preserving (pre-order), and cheap for the CFG/PDG layers to walk.
+ *
+ * Vocabulary note (2026-09-01 survey): this layer corresponds to the `AST` edge partition of the
+ * Joern CPG specification (cpg.joern.io); CFG/CDG/REACHING_DEF/DOMINATE names are reserved for
+ * .3+ so the differential-comparison harness stays apples-to-apples.
+ *
+ * NEVER imported by hooks/gates (pinned by test): loading a wasm runtime inside the gate path
+ * would violate REQ-510's zero-cost constraint. Cache invalidation is basis-checked, file-hash
+ * driven (the batch-scan consumption pattern) — editor-style incremental edit() is deliberately
+ * not used here.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+/** The honest language envelope: exactly what the vendored grammars cover — nothing more. */
+exports.AST_LANGUAGES = [
+    { ext: /\.tsx$/, lang: 'tsx', wasm: 'tree-sitter-tsx.wasm' },
+    { ext: /\.(ts|mts|cts)$/, lang: 'typescript', wasm: 'tree-sitter-typescript.wasm' },
+    { ext: /\.(js|mjs|cjs|jsx)$/, lang: 'tsx', wasm: 'tree-sitter-tsx.wasm' }, // TS grammar family parses JS (decision 3: no separate JS grammar)
+    { ext: /\.py$/, lang: 'python', wasm: 'tree-sitter-python.wasm' },
+];
+const GRAMMARS_DIR = (() => {
+    // src/holmes/cpg/foundation → three up is the package root; identical depth from dist.
+    const root = path.resolve(__dirname, '..', '..', '..', '..');
+    return path.join(root, 'grammars');
+})();
+let manifestCache = null;
+function manifest() {
+    if (!manifestCache) {
+        manifestCache = JSON.parse(fs.readFileSync(path.join(GRAMMARS_DIR, 'manifest.json'), 'utf8'));
+    }
+    return manifestCache;
+}
+let parserP = null;
+function substrate() {
+    if (!parserP) {
+        parserP = (async () => {
+            const { Parser, Language } = require('web-tree-sitter');
+            // BYTES, not paths: handing the runtime its core wasm and each grammar as buffers keeps
+            // web-tree-sitter's internal fetch/dynamic-import loader entirely out of the picture —
+            // measured 2026-09-01: the path-based loader dynamic-imports, which jest's CJS VM refuses
+            // (--experimental-vm-modules), and an env flag would silently red every spawned jest
+            // (test_run evidence runs) that doesn't carry it.
+            const runtimeWasm = fs.readFileSync(path.join(path.dirname(require.resolve('web-tree-sitter', { paths: [GRAMMARS_DIR] })), 'web-tree-sitter.wasm'));
+            await Parser.init({ wasmBinary: runtimeWasm });
+            const languages = new Map();
+            for (const wasm of new Set(exports.AST_LANGUAGES.map((l) => l.wasm))) {
+                languages.set(wasm, await Language.load(fs.readFileSync(path.join(GRAMMARS_DIR, wasm))));
+            }
+            return { parser: new Parser(), languages };
+        })();
+    }
+    return parserP;
+}
+/** Exposed for tests/tools that want to pay the load cost up front. */
+async function initSubstrate() { await substrate(); }
+function languageFor(relPath) {
+    const base = path.basename(relPath);
+    for (const { ext, lang, wasm } of exports.AST_LANGUAGES)
+        if (ext.test(base))
+            return { lang, wasm };
+    return null;
+}
+/** Parse one source into the flat lossless-span form. Throws only on substrate failure. */
+async function parseAst(source, relPath) {
+    const langOf = languageFor(relPath);
+    if (!langOf)
+        return null; // honest envelope: ts/tsx/js/py only
+    const { parser, languages } = await substrate();
+    parser.setLanguage(languages.get(langOf.wasm));
+    const tree = parser.parse(source);
+    const nodes = [];
+    let errorCount = 0;
+    const walk = (node, parent) => {
+        const idx = nodes.length;
+        if (node.type === 'ERROR' || node.isMissing)
+            errorCount++;
+        nodes.push({ type: node.type, start: node.startIndex, end: node.endIndex, parent, named: node.isNamed });
+        for (let i = 0; i < node.childCount; i++) {
+            const c = node.child(i);
+            if (c)
+                walk(c, idx);
+        }
+    };
+    walk(tree.rootNode, -1);
+    tree.delete();
+    const gramEntry = manifest().grammars.find((g) => g.file === langOf.wasm);
+    return {
+        lang: langOf.lang,
+        grammarVersion: gramEntry?.packageVersion ?? 'unknown',
+        runtimeVersion: manifest().webTreeSitter,
+        sourceHash: (0, node_crypto_1.createHash)('sha256').update(source).digest('hex'),
+        sourceLen: source.length,
+        errorCount,
+        nodes,
+    };
+}
+exports.AST_CACHE_DIR = path.join('.ax', 'cpg_cache', 'ast');
+const cacheFileFor = (root, relPath) => path.join(root, exports.AST_CACHE_DIR, `${(0, node_crypto_1.createHash)('sha256').update(relPath).digest('hex').slice(0, 24)}.json`);
+/** Observable for tests: how many astOf calls were served without a parse. */
+exports.cacheStats = { hits: 0, misses: 0 };
+/**
+ * Basis-checked persisted AST for a repo file. Hit only when sourceHash AND grammar AND runtime
+ * versions all match (GraphBasis doctrine: any moved field means reparse); a corrupt cache file
+ * degrades to a miss, never a crash. The cache directory is delete-safe — everything regenerates.
+ */
+async function astOf(root, relPath) {
+    if (!languageFor(relPath))
+        return null;
+    let source;
+    try {
+        source = fs.readFileSync(path.join(root, relPath), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const sourceHash = (0, node_crypto_1.createHash)('sha256').update(source).digest('hex');
+    const cacheFile = cacheFileFor(root, relPath);
+    try {
+        const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+        const gramEntry = manifest().grammars.find((g) => g.file === languageFor(relPath).wasm);
+        if (cached.sourceHash === sourceHash
+            && cached.grammarVersion === (gramEntry?.packageVersion ?? 'unknown')
+            && cached.runtimeVersion === manifest().webTreeSitter
+            && Array.isArray(cached.nodes)) {
+            exports.cacheStats.hits++;
+            return cached;
+        }
+    }
+    catch { /* absent or corrupt: fall through to a fresh parse */ }
+    exports.cacheStats.misses++;
+    const ast = await parseAst(source, relPath);
+    if (!ast)
+        return null;
+    try {
+        fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+        fs.writeFileSync(cacheFile, JSON.stringify(ast));
+    }
+    catch { /* persistence failure degrades to compute-only — never a crash */ }
+    return ast;
+}
+/** The span invariants of REQ-510 L1 — violations by name, [] when the contract holds. */
+function spanViolations(ast) {
+    const out = [];
+    ast.nodes.forEach((n, i) => {
+        if (!(n.start >= 0 && n.start <= n.end && n.end <= ast.sourceLen))
+            out.push(`node ${i} (${n.type}): span out of bounds`);
+        if (i === 0 ? n.parent !== -1 : !(n.parent >= 0 && n.parent < i))
+            out.push(`node ${i} (${n.type}): bad parent index`);
+        if (n.parent >= 0) {
+            const p = ast.nodes[n.parent];
+            if (!(n.start >= p.start && n.end <= p.end))
+                out.push(`node ${i} (${n.type}): escapes parent span`);
+        }
+    });
+    if (ast.nodes.length > 0 && !(ast.nodes[0].start === 0 && ast.nodes[0].end === ast.sourceLen)) {
+        out.push('root does not cover [0, sourceLen]');
+    }
+    return out;
+}

package/dist/holmes/cpg/foundation/cdg.d.ts

@@ -0,0 +1,31 @@
+/**
+ * L3-CDG: control dependence per Ferrante–Ottenstein–Warren, computed in the edge-walk form that
+ * is equivalent to the post-dominance frontier — for every CFG edge (A→s) out of a BRANCH block A,
+ * every block on the post-dominator chain from s up to (exclusive) ipostdom(A) is control-dependent
+ * on A. Joern vocabulary: `CDG`. PDG = REACHING_DEF (.4) ∪ CDG (.5).
+ *
+ * ENVELOPE: dependence on ENTRY (top-level code that no branch guards) is NOT emitted — "it runs
+ * because the function was entered" is vacuous and would be pure noise. Blocks that do not reach
+ * EXIT (infinite-loop tails, ipostdom = -1) terminate the chain walk; they still register as
+ * dependent on the guarding branch, which is true — whether they run at all hangs on it.
+ */
+import type { PersistedAst } from './ast-store';
+import type { Cfg, FunctionRef } from './cfg';
+import { DdgEdge } from './ddg';
+export interface CdgEdge {
+    ctrl: number;
+    dep: number;
+}
+export interface Pdg {
+    reachingDefs: DdgEdge[];
+    controlDeps: CdgEdge[];
+}
+export declare function cdgOf(cfg: Cfg): CdgEdge[];
+/** PDG = the two dependence halves, composed verbatim — no recomputation, no reinterpretation. */
+export declare function pdgOf(ast: PersistedAst, cfg: Cfg | {
+    unsupported: string;
+}, fn: FunctionRef, source: string): Pdg | {
+    unsupported: string;
+};
+/** The CDG verifier — [] means the FOW definition holds on this instance. */
+export declare function cdgViolations(cfg: Cfg, edges: CdgEdge[]): string[];

package/dist/holmes/cpg/foundation/cdg.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cdgOf = cdgOf;
+exports.pdgOf = pdgOf;
+exports.cdgViolations = cdgViolations;
+const ddg_1 = require("./ddg");
+function cdgOf(cfg) {
+    const outdeg = new Map();
+    for (const e of cfg.edges)
+        outdeg.set(e.from, (outdeg.get(e.from) ?? 0) + 1);
+    const edges = [];
+    const seen = new Set();
+    for (const e of cfg.edges) {
+        const A = e.from;
+        if (A === cfg.entry)
+            continue; // vacuous ENTRY dependence (envelope)
+        if ((outdeg.get(A) ?? 0) < 2)
+            continue; // only a BRANCH can control anything
+        const stop = cfg.ipostdom[A]; // -1 when A never reaches EXIT
+        let B = e.to;
+        const guard = new Set();
+        while (B !== stop && B !== -1 && !guard.has(B)) {
+            guard.add(B);
+            const key = `${A}>${B}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                edges.push({ ctrl: A, dep: B });
+            }
+            B = cfg.ipostdom[B];
+        }
+    }
+    return edges;
+}
+// @implements A-SPEC-510.5
+/** PDG = the two dependence halves, composed verbatim — no recomputation, no reinterpretation. */
+function pdgOf(ast, cfg, fn, source) {
+    if ('unsupported' in cfg)
+        return cfg;
+    const ddg = (0, ddg_1.ddgOf)(ast, cfg, fn, source);
+    if ('unsupported' in ddg)
+        return ddg;
+    return { reachingDefs: ddg.edges, controlDeps: cdgOf(cfg) };
+}
+// @implements A-SPEC-510.5
+/** The CDG verifier — [] means the FOW definition holds on this instance. */
+function cdgViolations(cfg, edges) {
+    const out = [];
+    const n = cfg.blocks.length;
+    const outdeg = new Map();
+    const succ = cfg.blocks.map(() => []);
+    for (const e of cfg.edges) {
+        outdeg.set(e.from, (outdeg.get(e.from) ?? 0) + 1);
+        succ[e.from].push(e.to);
+    }
+    const inCycle = (a) => {
+        const seen = new Set();
+        const st = [...succ[a]];
+        while (st.length) {
+            const x = st.pop();
+            if (x === a)
+                return true;
+            if (!seen.has(x)) {
+                seen.add(x);
+                st.push(...succ[x]);
+            }
+        }
+        return false;
+    };
+    for (const e of edges) {
+        if (e.ctrl < 0 || e.ctrl >= n || e.dep < 0 || e.dep >= n) {
+            out.push(`edge escapes blocks: ${e.ctrl}->${e.dep}`);
+            continue;
+        }
+        if ((outdeg.get(e.ctrl) ?? 0) < 2)
+            out.push(`ctrl ${e.ctrl} is not a branch`);
+        if (e.dep === cfg.ipostdom[e.ctrl])
+            out.push(`dep ${e.dep} post-dominates its ctrl ${e.ctrl}`);
+        // Self-dependence is legitimate ONLY for a loop head (the branch sits on its own cycle).
+        if (e.ctrl === e.dep && !inCycle(e.ctrl))
+            out.push(`acyclic self-dependence at ${e.ctrl}`);
+    }
+    return out;
+}

package/dist/holmes/cpg/foundation/cfg.d.ts

@@ -0,0 +1,60 @@
+/**
+ * L2 of the CPG foundation: statement-granularity control-flow graphs over the L1 PersistedAst,
+ * with synthetic ENTRY/EXIT, labeled edges, and Cooper-Harvey-Kennedy (post-)dominator trees.
+ * Vocabulary aligns with the Joern CPG spec's CFG/DOMINATE/POST_DOMINATE partitions.
+ *
+ * GRANULARITY ENVELOPE (sealed in A-SPEC-510.3): statements are the atoms. Expression-internal
+ * control flow (ternary, &&/||, optional chaining short-circuits) is NOT modeled here; await and
+ * yield proceed linearly in statement order. Exception edges are a CONSERVATIVE over-approximation:
+ * every statement inside a try is assumed able to throw into its handler.
+ *
+ * FAIL-CLOSED: the statement types this builder understands are ENUMERATED. Anything outside the
+ * list — `with_statement` deliberately included — yields `{ unsupported }` for the WHOLE function:
+ * a partial control-flow graph is a wrong control-flow graph.
+ */
+import type { PersistedAst } from './ast-store';
+export type EdgeKind = 'seq' | 'true' | 'false' | 'case' | 'default' | 'loop-back' | 'break' | 'continue' | 'exception' | 'return' | 'throw';
+export interface CfgBlock {
+    id: number;
+    stmts: number[];
+}
+export interface CfgEdge {
+    from: number;
+    to: number;
+    kind: EdgeKind;
+}
+export interface Cfg {
+    blocks: CfgBlock[];
+    edges: CfgEdge[];
+    entry: number;
+    exit: number;
+    /** idom[b] = immediate dominator block id (-1 for entry / unreachable). */
+    idom: Int32Array;
+    /** ipostdom[b] = immediate post-dominator block id (-1 for exit / not reaching exit). */
+    ipostdom: Int32Array;
+    /** Blocks not reachable from ENTRY (dead code after return etc.) — lint material, not an error. */
+    unreachable: number[];
+}
+export interface FunctionRef {
+    nodeIndex: number;
+    bodyIndex: number;
+}
+export declare const FUNCTION_TYPES: Set<string>;
+/**
+ * The languages this lowering understands — DERIVED from the rule table, so the layer×language
+ * matrix and the guard below can never disagree with what is actually implemented.
+ */
+export declare const CFG_LANGUAGES: ReadonlySet<string>;
+export interface Children {
+    of(i: number): number[];
+}
+/** Shared child index over the flat pre-order AST — DDG (L3) walks with the same truth. */
+export declare function childrenIndex(ast: PersistedAst): Children;
+/** Every function-like node in the AST, with its body (statement_block or expression body). */
+export declare function functionsIn(ast: PersistedAst): FunctionRef[];
+/** Build the CFG of one function, or refuse the whole function honestly. */
+export declare function cfgOf(ast: PersistedAst, fn: FunctionRef, source?: string): Cfg | {
+    unsupported: string;
+};
+/** The invariant verifier — the ONE truth tests and later layers share. [] means the theory holds. */
+export declare function domViolations(cfg: Cfg): string[];