circle-ir-ai 2.16.0 → 2.18.0

package/CHANGELOG.md

@@ -5,6 +5,139 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.18.0] - 2026-06-22
+
+### Added — findings-emission instrumentation env wiring (cognium-dev#145 PR C)
+
+`circle-ir-ai` now honors the `CIRCLE_IR_INSTRUMENT_FINDINGS=1`
+environment variable at analyzer-init time, flipping
+`setFindingsInstrumentation(true)` on `circle-ir`'s opt-in
+findings-emission hook. With the env var set, every call into
+`circle-ir`'s `analyze()` — from both the scanner static path and the
+mastra `runPatternMatch` LLM path — emits one `[finding]` JSON line on
+stderr per `SastFinding` plus one `[findings-summary]` line per file.
+
+Each `[finding]` payload carries the fields required to re-derive
+coalesce candidates for cognium-dev#143 after the fact:
+
+```jsonc
+{
+  "file": "VulnServlet.java",
+  "line": 9,
+  "rule_id": "sql-injection-jdbc",
+  "pass": "TaintMatcherPass",
+  "category": "security",
+  "severity": "high",
+  "cwe": "CWE-89",
+  "sink_type": "sql-query",
+  "source_type": "http-param",
+  "confidence": 0.95,
+  "dedup_group_id": "VulnServlet.java:9:sql-injection-jdbc"
+}
+```
+
+Per-file summary payload:
+
+```jsonc
+{
+  "file": "VulnServlet.java",
+  "total": 3,
+  "unique_groups": 2,
+  "max_findings_per_group": 2,
+  "sources_count": 1,
+  "sinks_count": 1,
+  "by_rule": { "sql-injection-jdbc": 3 },
+  "by_severity": { "high": 3 }
+}
+```
+
+The wiring lives in `src/utils/analyzer-init.ts` so any call into
+`ensureAnalyzerInitialized()` — which both `scanner.ts` and mastra's
+`runPatternMatch()` already use — applies the env var idempotently. No
+public API change; `setFindingsInstrumentation()` remains the
+programmatic entry point for non-CLI consumers.
+
+Output is `console.error` (per the upstream hook contract — see
+`circle-ir/dist/analysis/findings-instrumentation.js:13-15`). Redirect
+stderr to capture: `CIRCLE_IR_INSTRUMENT_FINDINGS=1 cognium-ai scan ./src
+2> findings.jsonl`. The flag is fully no-op when unset; no perf or
+allocation overhead on the default path.
+
+### Why this matters
+
+The empirical data collected here informs the **cognium-dev#143
+"coalesce candidates"** decision. The `dedup_group_id` field plus per-
+file `max_findings_per_group` count let us measure how often
+`(file, line, rule_id)` clusters actually receive multiple
+near-duplicate emissions in the wild. That measurement is the gating
+input for whether circle-ir's findings pipeline should add a
+post-emit coalesce pass or leave the existing dedup logic alone.
+
+### Verification
+
+- `npm run build` — clean.
+- `npm run typecheck` — clean.
+- `npm test` — **900 / 900 pass + 3 skipped** (+2 new tests
+  `findings-instrumentation.test.ts` covering both env states).
+- Manual: `CIRCLE_IR_INSTRUMENT_FINDINGS=1 ...` emits `[finding]` and
+  `[findings-summary]` lines on stderr; unsetting suppresses both.
+
+### Why minor (`2.17.0 → 2.18.0`)
+
+Additive: new env-var honored at init time, no removed or renamed
+exports, no change to the default observable output. Downstream
+packages (`cognium-ai`, `@cognium-ai/mcp-server`, `circle-pack`) need a
+dep range bump but no source-side change to benefit — setting the env
+var is enough.
+
+## [2.17.0] - 2026-06-22
+
+### Dependencies
+
+- Bump `circle-ir` `3.89.1` → `3.90.0`.
+
+### What 3.90.0 brings (inherited, no source-side changes here)
+
+`circle-ir@3.90.0` adds the **findings-emission instrumentation hook**
+that closes out cognium-dev#145 (PR B). Per-file `SastFinding[]`
+finalization now emits to an opt-in JSONL sink controlled by the
+engine's instrumentation surface (`emitFindingsInstrumentation`
+callback / env-var hook — see circle-ir 3.90.0 release notes for the
+exact wiring). This is the data source #143 will consume to evaluate
+coalesce hypotheses against real CLI workloads.
+
+Per-finding payload includes at minimum: `ruleId`, `file`, `line`,
+`sinkType`, `sourceType`, `severity`, `confidence`, `dedup_group_id`.
+**Payload schema is stable-additive** — the engine reserves the right
+to add new fields driven by #143's analysis without a major bump.
+Consumers should ignore unknown keys. Function signature is the
+freeze point.
+
+### What `circle-ir-ai` does with the hook (today: nothing)
+
+Engine-side surface is opt-in; no `circle-ir-ai` source exercises
+the hook yet. The intended consumer is PR C in `circle-ir-ai`
+itself (separate cycle), which will wire the hook through the
+mastra `runPatternMatch → analyze()` path so cognium-ai scans
+surface the instrumentation without users having to import
+`circle-ir` directly. Until PR C ships, the hook fires only for
+direct `circle-ir` consumers that opt in.
+
+### Verification
+
+- `npm install --prefer-online` — clean; `npm ls circle-ir` shows
+  `3.90.0`.
+- `npm run build` — clean.
+- `npm run typecheck` — clean.
+- `npm test` — **898 / 898 pass** (3 skipped).
+
+### Why minor (`2.16.0 → 2.17.0`)
+
+New engine surface is reachable via direct `circle-ir` import even
+though no `circle-ir-ai` code-path exercises it yet. Minor bump
+signals the underlying capability uplift to downstream consumers
+(mcp-server, circle-pack) that may wire the hook independently.
+
 ## [2.16.0] - 2026-06-22
 
 ### Added

package/dist/utils/analyzer-init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer-init.d.ts","sourceRoot":"","sources":["../../src/utils/analyzer-init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAuC,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAKtF;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBjG;AAGD,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"analyzer-init.d.ts","sourceRoot":"","sources":["../../src/utils/analyzer-init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,WAAW,CAAC;AAgCnB;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BjG;AAGD,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC"}

package/dist/utils/analyzer-init.js

@@ -5,14 +5,44 @@
  * This fixes issues when cognium-ai is installed globally or in various
  * node_modules configurations.
  */
-import { initAnalyzer, isAnalyzerInitialized } from 'circle-ir';
+import { initAnalyzer, isAnalyzerInitialized, setFindingsInstrumentation, } from 'circle-ir';
 import { getWasmAnalyzerOptions } from './wasm-path.js';
 let initializationPromise = null;
+let instrumentationApplied = false;
+/**
+ * cognium-dev#145 PR C — honor `CIRCLE_IR_INSTRUMENT_FINDINGS=1` at
+ * analyzer-init time so every path that hits circle-ir's `analyze()`
+ * (scanner static path + mastra `runPatternMatch` LLM path) emits the
+ * per-file `[finding]` / `[findings-summary]` JSON lines on stderr.
+ *
+ * `circle-ir`'s library does not read the env var itself — only its
+ * own CLI does. We translate the env var to `setFindingsInstrumentation(true)`
+ * here so cognium-ai runs honor the same opt-in toggle without each CLI
+ * needing to re-implement the wiring.
+ *
+ * Idempotent: only flips the toggle on once per process even though
+ * `ensureAnalyzerInitialized` may be called many times. Never disables
+ * the flag — external `setFindingsInstrumentation(false)` calls still
+ * take effect.
+ */
+function applyInstrumentationEnv() {
+    if (instrumentationApplied) {
+        return;
+    }
+    instrumentationApplied = true;
+    if (process.env.CIRCLE_IR_INSTRUMENT_FINDINGS === '1') {
+        setFindingsInstrumentation(true);
+    }
+}
 /**
  * Initialize the analyzer with proper WASM path resolution.
  * Safe to call multiple times - will only initialize once.
  */
 export async function ensureAnalyzerInitialized(options) {
+    // Apply instrumentation toggle on every call (cheap, idempotent) so the
+    // env-var check happens even when the analyzer was warmed by an unrelated
+    // import path.
+    applyInstrumentationEnv();
     if (isAnalyzerInitialized()) {
         return;
     }

package/dist/utils/analyzer-init.js.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer-init.js","sourceRoot":"","sources":["../../src/utils/analyzer-init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAwB,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,IAAI,qBAAqB,GAAyB,IAAI,CAAC;AAEvD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAAkC;IAChF,IAAI,qBAAqB,EAAE,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,IAAI,qBAAqB,EAAE,CAAC;QAC1B,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,qBAAqB,GAAG,CAAC,KAAK,IAAI,EAAE;QAClC,gDAAgD;QAChD,MAAM,WAAW,GAAG,sBAAsB,EAAE,CAAC;QAE7C,uCAAuC;QACvC,MAAM,aAAa,GAAoB;YACrC,GAAG,WAAW;YACd,GAAG,OAAO;SACX,CAAC;QAEF,MAAM,YAAY,CAAC,aAAa,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,CAAC;IAEL,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,4BAA4B;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"analyzer-init.js","sourceRoot":"","sources":["../../src/utils/analyzer-init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,0BAA0B,GAE3B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,IAAI,qBAAqB,GAAyB,IAAI,CAAC;AACvD,IAAI,sBAAsB,GAAG,KAAK,CAAC;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,SAAS,uBAAuB;IAC9B,IAAI,sBAAsB,EAAE,CAAC;QAC3B,OAAO;IACT,CAAC;IACD,sBAAsB,GAAG,IAAI,CAAC;IAC9B,IAAI,OAAO,CAAC,GAAG,CAAC,6BAA6B,KAAK,GAAG,EAAE,CAAC;QACtD,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAAkC;IAChF,wEAAwE;IACxE,0EAA0E;IAC1E,eAAe;IACf,uBAAuB,EAAE,CAAC;IAE1B,IAAI,qBAAqB,EAAE,EAAE,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,IAAI,qBAAqB,EAAE,CAAC;QAC1B,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IAED,qBAAqB,GAAG,CAAC,KAAK,IAAI,EAAE;QAClC,gDAAgD;QAChD,MAAM,WAAW,GAAG,sBAAsB,EAAE,CAAC;QAE7C,uCAAuC;QACvC,MAAM,aAAa,GAAoB;YACrC,GAAG,WAAW;YACd,GAAG,OAAO;SACX,CAAC;QAEF,MAAM,YAAY,CAAC,aAAa,CAAC,CAAC;IACpC,CAAC,CAAC,EAAE,CAAC;IAEL,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,4BAA4B;AAC5B,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circle-ir-ai",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "description": "LLM-enhanced SAST analysis built on circle-ir",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -95,7 +95,7 @@
   "dependencies": {
     "@ax-llm/ax": "^20.0.0",
     "@mastra/core": "^1.18.0",
-    "circle-ir": "3.89.1",
+    "circle-ir": "3.90.0",
     "minimatch": "^10.2.5",
     "p-queue": "^9.1.0"
   },