agent-gov-core 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project will be documented here. The format follows [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). Under v1.0, minor versions may include breaking changes — see [CONTRIBUTING.md](./CONTRIBUTING.md#backwards-compatibility) for the rules.
 
+## [0.4.3] — 2026-05-22
+
+Third Gemini-inspection round caught one confirmed bug, one disguised-as-suggestion bug, and three feature opportunities. Both bugs fixed here; the feature work is queued for v0.5.0.
+
+### Added
+- `Finding.salientKey?: string` — optional discriminator that participates in the fingerprint hash. Set this when a single (kind, file, line) site can produce multiple distinct findings (e.g. two suspicious imports on the same line, two MCP servers in the same JSON object). Without it, the meta-reviewer would dedupe them into one. Stable values only — package name, server name, rule id; not timestamps or counters.
+- `CreateFindingSpec.salientKey` — pass-through to the new field.
+- Schema gained `salientKey` under properties (still optional, schema's `additionalProperties: false` updated to permit it).
+
+### Fixed
+- `fingerprintFinding` now includes `salientKey` in the hash. Two distinct findings of the same kind on the same line with different `salientKey` values now produce different fingerprints. Backwards-compatible: findings without `salientKey` still produce stable, identical fingerprints to v0.4.2 for the (kind, file, line, column) tuple.
+- `lineOfTomlKey` now tracks multi-line basic (`"""`) and literal (`'''`) string state and skips key matching on lines that fall inside one. Previously a decoy key inside a multi-line string value could be matched as if it were a real assignment — confirmed bug with sharper reproduction than Gemini's first-round example.
+
+### Tests
+- 7 new regression cases. 102 total (up from 95). Covers salientKey discrimination, backwards-compat for fingerprints without salientKey, validateFinding type check, decoy-in-`"""`, decoy-in-`'''`, single-line `"""..."""` (must NOT enter multiline state), and a plain-TOML sanity check that the fix doesn't over-correct.
+
+## [0.4.2] — 2026-05-22
+
+External code review (Gemini, second pass) caught four correctness bugs and one source-cleanliness issue. All five fixed here.
+
+### Fixed
+- `lineOfJsonKey` and `lineOfJsonStringValue` now JSON-encode the search input before building the regex. A caller passing the *decoded* value (e.g. `C:\Temp` from a Windows-path field) now correctly locates the JSON source bytes (`"C:\\Temp"`) instead of returning 0. Affects CapabilityEcho's `package-scripts` detector for scripts containing quotes/backslashes.
+- `lineOfJsonKey` and `lineOfJsonStringValue` now scan over `stripJsonComments(text)` instead of raw text. A commented-out `"command": "fake"` no longer shadows the real key on a later line. The strip is position-preserving so returned line numbers still reference the original source.
+- `getCommandHead` now strips wrapper flags (`sudo -E`, `env -i`) after recognizing a wrapper, so `sudo -E curl ...` returns `curl` instead of `-E`. SessionTrail/CapabilityEcho shell detectors no longer miss wrapped curl/wget invocations. Known limitation: short flags taking a value (`sudo -u user curl`) still misclassify as the value — documented and pinned by test.
+- TOML parser now rejects a standard table header (`[items]`) that follows an array-of-tables header (`[[items]]`) with a `Cannot redefine array-of-tables` error. Previously the standard table silently descended into the array's last entry, letting writes leak into `items[0]`. Spec compliance fix.
+- TOML inline-table parser now rejects duplicate keys with `Duplicate key in inline table: ...`. Previously `server = { host = "a", host = "b" }` parsed as `{ host: "b" }` — the standard-table guard wasn't mirrored on inline tables. Spec compliance fix.
+
+### Changed
+- Source cleanup: the two `keys.join` calls in `src/toml.ts` now use a named `PATH_KEY_SEPARATOR = ''` constant instead of literal NUL bytes embedded in the source. Same runtime behavior (NUL as the delimiter, which is illegal in TOML keys so collision-proof), but `rg`/`grep` no longer treat the file as binary and `file(1)` reports it as proper text.
+- README: `rankSeverity` doc corrected — was `none=0…critical=4`, actually `low=1, medium=2, high=3, critical=4`. The schema has no `none` severity.
+- README: `normalizeMcpCommand` signature and behavior description corrected — was listing a non-existent `serverUrl` field and claiming "resolves npx/uvx invocations" which doesn't happen. Now accurately lists: drops neutral confirm flags, strips Windows executable suffixes, sorts non-neutral flags alphabetically, preserves positional argument order, includes env + cwd in identity.
+
+### Added
+- 7 new regression tests: encoded-value lookup, commented-out shadow, wrapper-flag unwrap (+ edge-case pin), AOT-vs-table mixing, inline-table duplicate keys.
+
 ## [0.4.1] — 2026-05-22
 
 ### Fixed

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
@@ -81,14 +81,14 @@ The JSON schema at [`schemas/finding.schema.json`](./schemas/finding.schema.json
 - `lineOfTomlKey(text, dottedKey, scope?)` — 1-based line of a TOML key, optionally scoped to a byte range. Use scope to disambiguate `[[array]]`-of-tables entries that share the same leaf key.
 
 ### MCP command normalization
-- `normalizeMcpCommand({ command, args, url, serverUrl, env, cwd })` — canonical identity string for an MCP server entry. Drops neutral flags (`-y`, `--yes`), resolves npx/uvx invocations, includes env+cwd in the identity. Used to dedupe `mcp_command_mismatch` false positives when servers are equivalent but syntactically different (`npx -y foo@1.2.3` vs `npx foo@1.2.3`).
+- `normalizeMcpCommand({ command, args, url, env, cwd })` — canonical identity string for an MCP server entry. Drops neutral confirm flags (`-y`, `--yes`), strips Windows executable suffixes (`.cmd`, `.exe`, `.bat`, `.ps1`), sorts non-neutral flags alphabetically, preserves positional argument order, and includes env + cwd in the identity. Used to dedupe `mcp_command_mismatch` false positives when servers are equivalent but syntactically different (`npx -y foo@1.2.3` vs `npx foo@1.2.3`). Does not interpret what npx/uvx invocations resolve to at runtime — that's outside the substrate's scope.
 
 ### Shell tokenization
 - `tokenizeShell(command)` — quote-aware split on `;`, `|`, `&&`, `||` plus trivial obfuscation neutralization (`c""url` → `curl`, `c\\url` → `curl`)
 - `getCommandHead(subcommand)` — extract the leading verb after tokenization
 
 ### GitHub Action helpers
-- `rankSeverity(s)` — numeric rank `none=0 … critical=4`
+- `rankSeverity(s)` — numeric rank `low=1, medium=2, high=3, critical=4` (matches the schema's closed severity enum; there is no `none`)
 - `passesSeverityThreshold(s, threshold)`, `anyAtOrAbove(findings, threshold)` — fail-on plumbing
 - `emitFindingAnnotation(f)` — render a Finding as a `::warning file=…,line=…,title=…::…` GitHub workflow annotation
 

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.d.ts

@@ -11,12 +11,24 @@ export interface ByteRange {
     /** Exclusive end offset. */
     end: number;
 }
-/** 1-based line number for the first occurrence of `"key"` followed by `:`. */
+/**
+ * 1-based line number for the first occurrence of `"key"` followed by `:`.
+ *
+ * The key is JSON-encoded before matching so keys containing backslashes or
+ * quotes (rare but legal) are located in the source bytes. The scan ignores
+ * lines inside JSONC `//` and `/* *\/` comments so a commented-out `"key":`
+ * does not shadow the real one.
+ */
 export declare function lineOfJsonKey(text: string, key: string, scope?: ByteRange): number;
 /**
  * 1-based line number for the first JSON string value equal to `value`.
  * If `scope` is supplied (a byte range), only matches inside that range count —
  * this is the fix for the multi-server-ambiguity bug.
+ *
+ * The value is JSON-encoded before matching so values containing backslashes
+ * (e.g. Windows paths like `C:\Temp` written as `"C:\\Temp"` in JSON) are
+ * located correctly. The scan ignores JSONC comments so a commented-out
+ * matching value does not shadow the real one.
  */
 export declare function lineOfJsonStringValue(text: string, value: string, scope?: ByteRange): number;
 /**

package/dist/locators.js

@@ -5,19 +5,41 @@
  * All returned line numbers are 1-based. `0` is reserved for "not found"; callers
  * generally treat that as "fall back to file-level annotation".
  */
-/** 1-based line number for the first occurrence of `"key"` followed by `:`. */
+import { stripJsonComments } from './jsonc.js';
+/**
+ * 1-based line number for the first occurrence of `"key"` followed by `:`.
+ *
+ * The key is JSON-encoded before matching so keys containing backslashes or
+ * quotes (rare but legal) are located in the source bytes. The scan ignores
+ * lines inside JSONC `//` and `/* *\/` comments so a commented-out `"key":`
+ * does not shadow the real one.
+ */
 export function lineOfJsonKey(text, key, scope) {
-    const needle = `"${escapeForRegex(key)}"\\s*:`;
-    return findLineByRegex(text, new RegExp(needle), scope);
+    const encoded = jsonEncodeForRegex(key);
+    return findLineByRegex(text, new RegExp(`"${encoded}"\\s*:`), scope);
 }
 /**
  * 1-based line number for the first JSON string value equal to `value`.
  * If `scope` is supplied (a byte range), only matches inside that range count —
  * this is the fix for the multi-server-ambiguity bug.
+ *
+ * The value is JSON-encoded before matching so values containing backslashes
+ * (e.g. Windows paths like `C:\Temp` written as `"C:\\Temp"` in JSON) are
+ * located correctly. The scan ignores JSONC comments so a commented-out
+ * matching value does not shadow the real one.
  */
 export function lineOfJsonStringValue(text, value, scope) {
-    const needle = `"${escapeForRegex(value)}"`;
-    return findLineByRegex(text, new RegExp(needle), scope);
+    const encoded = jsonEncodeForRegex(value);
+    return findLineByRegex(text, new RegExp(`"${encoded}"`), scope);
+}
+/**
+ * Convert a string to the form it would appear in JSON source bytes, then
+ * regex-escape. `JSON.stringify('C:\\Temp')` yields `'"C:\\\\Temp"'` — slice
+ * off the surrounding quotes to get the inner byte sequence.
+ */
+function jsonEncodeForRegex(input) {
+    const jsonBody = JSON.stringify(input).slice(1, -1);
+    return escapeForRegex(jsonBody);
 }
 /**
  * 1-based line number for a TOML key. Supports dotted keys (`a.b.c`) — the
@@ -42,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) {
@@ -71,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;
@@ -79,7 +148,12 @@ function scopeLineFilter(text, scope) {
     return (line) => line >= startLine && line <= endLine;
 }
 function findLineByRegex(text, regex, scope) {
-    const haystack = scope ? text.slice(scope.start, scope.end) : text;
+    // stripJsonComments is position-preserving: it replaces comment bytes with
+    // spaces while leaving newlines intact. Offsets in the stripped text map
+    // 1:1 to offsets in the original text, so line numbers stay correct, but
+    // commented-out keys/values no longer match.
+    const searchable = stripJsonComments(text);
+    const haystack = scope ? searchable.slice(scope.start, scope.end) : searchable;
     const m = regex.exec(haystack);
     if (!m)
         return 0;

package/dist/shell.js

@@ -127,15 +127,43 @@ export function getCommandHead(subcommand) {
             break;
         s = s.slice(m[0].length);
     }
-    // Strip leading sudo / env wrappers
-    const wrapperMatch = /^(sudo|nohup|env|exec|command|builtin)\s+(.*)$/.exec(s);
+    // Strip leading sudo / env wrappers, then also strip any wrapper flags
+    // (`sudo -E`, `env -i`) and embedded env vars (`env FOO=1 BAZ=qux curl`)
+    // before recursing. Without this, `sudo -E curl` would return `-E`.
+    const wrapperMatch = /^(sudo|nohup|env|exec|command|builtin|stdbuf|nice|ionice|setsid)\s+(.*)$/.exec(s);
     if (wrapperMatch) {
-        return getCommandHead(wrapperMatch[2]);
+        return getCommandHead(stripWrapperPrefixes(wrapperMatch[2]));
     }
     // Now extract first token, honoring quoting and obfuscation neutralization.
     const head = readFirstToken(s);
     return deobfuscate(head);
 }
+/**
+ * Consume any leading flags (`-x`, `--xxx`, `--xxx=value`) and env var
+ * assignments (`FOO=bar`) so the next recursion finds the real command. We
+ * intentionally do NOT consume a non-flag token after a short flag (so
+ * `sudo -u user curl` still misclassifies as `user` — a known edge case
+ * that we accept rather than maintain a per-wrapper flag database).
+ */
+function stripWrapperPrefixes(input) {
+    let s = input.trimStart();
+    while (s.length > 0) {
+        if (s.startsWith('-')) {
+            const flagMatch = /^\S+\s*/.exec(s);
+            if (!flagMatch)
+                break;
+            s = s.slice(flagMatch[0].length);
+            continue;
+        }
+        const envMatch = /^([A-Za-z_][A-Za-z0-9_]*)=([^\s'"]*|"[^"]*"|'[^']*')\s+/.exec(s);
+        if (envMatch) {
+            s = s.slice(envMatch[0].length);
+            continue;
+        }
+        break;
+    }
+    return s;
+}
 function readFirstToken(s) {
     let out = '';
     let i = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-gov-core",
-  "version": "0.4.1",
+  "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" }
   }
 }