agent-gov-core 0.4.2 → 0.4.3

package/README.md

@@ -66,7 +66,7 @@ The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json
 - `isSeverity(v)`, `isToolKind(v)`, `isNamespacedKind(v)` — type guards
 - `kind(tool, name)` — build a namespaced kind without hand-assembling the dotted string
 - `createFinding({tool, name, severity, message, ...})` — convenience constructor that calls `kind()` and `fingerprintFinding()` for you
-- `fingerprintFinding(finding)` — 16-character hex hash of `(kind, file, line, column)`. Stable across runs and message rewordings, so a meta-reviewer can dedupe
+- `fingerprintFinding(finding)` — 16-character hex hash of `(kind, file, line, column, salientKey?)`. Stable across runs and message rewordings, so a meta-reviewer can dedupe. Pass `salientKey` (since v0.4.3) when multiple distinct findings can fire at the same site
 - `validateFinding(value)` — runtime check against `schemas/finding.schema.json`, returns `{ ok, errors[] }`
 
 ### Config readers

package/dist/finding.d.ts

@@ -26,6 +26,16 @@ export interface Finding {
     location?: FindingLocation;
     /** Stable identifier for dedupe across runs. Recommended: hash of (kind, location, salient fields). */
     fingerprint?: string;
+    /**
+     * Optional discriminator that participates in the fingerprint hash. Set this
+     * when a single (kind, file, line) site can legitimately host multiple distinct
+     * findings — e.g. two suspicious imports on the same line, two MCP servers in
+     * the same JSON object, two npm dependencies declared in one package.json line.
+     * Without it, the meta-reviewer would dedupe them into one. Use a stable value
+     * that doesn't drift across reruns (package name, server name, rule id) — not
+     * a timestamp or counter.
+     */
+    salientKey?: string;
     /** Optional structured metadata; downstream meta-reviewers may inspect it. */
     data?: Record<string, unknown>;
 }
@@ -57,6 +67,12 @@ export interface CreateFindingSpec {
     detail?: string;
     location?: FindingLocation;
     data?: Record<string, unknown>;
+    /**
+     * See {@link Finding.salientKey}. Pass when the same (kind, file, line) site
+     * can produce multiple distinct findings that must not collapse to one
+     * fingerprint.
+     */
+    salientKey?: string;
     /** Optional explicit fingerprint. If omitted, {@link fingerprintFinding} is computed. */
     fingerprint?: string;
 }

package/dist/finding.js

@@ -62,6 +62,8 @@ export function createFinding(spec) {
         finding.detail = spec.detail;
     if (spec.location !== undefined)
         finding.location = spec.location;
+    if (spec.salientKey !== undefined)
+        finding.salientKey = spec.salientKey;
     if (spec.data !== undefined)
         finding.data = spec.data;
     finding.fingerprint = spec.fingerprint ?? fingerprintFinding(finding);
@@ -98,6 +100,10 @@ export function fingerprintFinding(finding) {
         fileNormalized,
         finding.location?.line ?? '',
         finding.location?.column ?? '',
+        // salientKey lets multiple distinct findings at the same (kind, file, line)
+        // site keep separate fingerprints. Empty string when absent so the hash
+        // shape is stable across findings that don't need a discriminator.
+        finding.salientKey ?? '',
     ];
     return createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 16);
 }
@@ -109,6 +115,7 @@ const FINDING_ALLOWED_KEYS = new Set([
     'detail',
     'location',
     'fingerprint',
+    'salientKey',
     'data',
 ]);
 const LOCATION_ALLOWED_KEYS = new Set(['file', 'line', 'column', 'endLine', 'endColumn']);
@@ -145,6 +152,9 @@ export function validateFinding(value) {
     if (v.fingerprint !== undefined && typeof v.fingerprint !== 'string') {
         errors.push('fingerprint must be a string when present');
     }
+    if (v.salientKey !== undefined && typeof v.salientKey !== 'string') {
+        errors.push('salientKey must be a string when present');
+    }
     if (v.data !== undefined && (v.data === null || typeof v.data !== 'object' || Array.isArray(v.data))) {
         errors.push('data must be an object when present');
     }

package/dist/locators.js

@@ -64,9 +64,19 @@ export function lineOfTomlKey(text, dottedKey, scope) {
     let inTargetTable = prefix.length === 0;
     let currentTable = [];
     const targetHeader = prefix.join('.');
+    // Track multi-line basic (`"""`) and literal (`'''`) string state. A leaf-key
+    // pattern can otherwise match against decoy text inside a multi-line string
+    // value — see lineOfTomlKey regression tests.
+    let inMultilineString = null;
     for (let i = 0; i < lines.length; i++) {
         const lineNumber = i + 1;
         const raw = lines[i];
+        const stateAtLineStart = inMultilineString;
+        inMultilineString = updateMultilineStringState(raw, inMultilineString);
+        // If we entered this line inside a multi-line string, never match. The key
+        // pattern there is part of a string literal, not a real assignment.
+        if (stateAtLineStart !== null)
+            continue;
         const trimmed = raw.trim();
         const headerMatch = /^\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(trimmed);
         if (headerMatch) {
@@ -93,6 +103,43 @@ export function lineOfTomlKey(text, dottedKey, scope) {
     }
     return 0;
 }
+/**
+ * Walk a line and update multi-line string state. Each unescaped occurrence of
+ * `"""` toggles basic-multiline; each `'''` toggles literal-multiline; the
+ * other delimiter is inert while we're inside the first. Returns the state at
+ * end-of-line so the next iteration knows whether it's inside a string.
+ */
+function updateMultilineStringState(line, current) {
+    let state = current;
+    let pos = 0;
+    while (pos <= line.length - 3) {
+        const window = line.substr(pos, 3);
+        if (state === null) {
+            if (window === '"""') {
+                state = '"""';
+                pos += 3;
+                continue;
+            }
+            if (window === "'''") {
+                state = "'''";
+                pos += 3;
+                continue;
+            }
+        }
+        else if (state === '"""' && window === '"""') {
+            state = null;
+            pos += 3;
+            continue;
+        }
+        else if (state === "'''" && window === "'''") {
+            state = null;
+            pos += 3;
+            continue;
+        }
+        pos++;
+    }
+    return state;
+}
 function scopeLineFilter(text, scope) {
     if (!scope)
         return () => true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-gov-core",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Shared primitives for the AI-agent governance suite: Finding schema, JSONC/TOML readers, line locators, MCP command normalization, shell tokenization, and GitHub Action helpers.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/finding.schema.json

@@ -41,6 +41,10 @@
       }
     },
     "fingerprint": { "type": "string" },
+    "salientKey": {
+      "type": "string",
+      "description": "Optional discriminator that participates in the fingerprint hash. Set when a single (kind, file, line) site can produce multiple distinct findings (e.g. two suspicious imports on one line). Use a stable value — package name, server name, rule id — not a timestamp."
+    },
     "data": { "type": "object" }
   }
 }