agent-gov-core 0.4.3 → 0.7.0

package/dist/jsonc.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { toConfigParseError } from './parse-error.js';
 /**
  * Strip `//` line comments, `/* ... *\/` block comments, and trailing commas from JSONC,
  * preserving byte offsets (replacement is space-filled, newlines preserved) so downstream
@@ -113,7 +114,7 @@ export function readJsonObjectWithSource(path) {
         return { value: parsed, json: parsed, text };
     }
     catch (err) {
-        return { value: undefined, json: undefined, text, parseError: err };
+        return { value: undefined, json: undefined, text, parseError: toConfigParseError(text, err) };
     }
 }
 //# sourceMappingURL=jsonc.js.map

package/dist/locators.d.ts

@@ -28,7 +28,9 @@ export declare function lineOfJsonKey(text: string, key: string, scope?: ByteRan
  * 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.
+ * matching value does not shadow the real one. The negative lookahead skips
+ * occurrences in key position (`"command":`) so a value matching a key name
+ * elsewhere in the document doesn't return the key's line.
  */
 export declare function lineOfJsonStringValue(text: string, value: string, scope?: ByteRange): number;
 /**

package/dist/locators.js

@@ -26,11 +26,13 @@ export function lineOfJsonKey(text, key, scope) {
  * 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.
+ * matching value does not shadow the real one. The negative lookahead skips
+ * occurrences in key position (`"command":`) so a value matching a key name
+ * elsewhere in the document doesn't return the key's line.
  */
 export function lineOfJsonStringValue(text, value, scope) {
     const encoded = jsonEncodeForRegex(value);
-    return findLineByRegex(text, new RegExp(`"${encoded}"`), scope);
+    return findLineByRegex(text, new RegExp(`"${encoded}"(?!\\s*:)`), scope);
 }
 /**
  * Convert a string to the form it would appear in JSON source bytes, then
@@ -56,14 +58,9 @@ export function lineOfTomlKey(text, dottedKey, scope) {
     const parts = splitTomlDottedKey(dottedKey);
     if (parts.length === 0)
         return 0;
-    const leaf = parts[parts.length - 1];
-    const prefix = parts.slice(0, -1);
     const lines = text.split(/\r?\n/);
     const inScope = scopeLineFilter(text, scope);
-    // Find header range we're inside of.
-    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.
@@ -81,40 +78,85 @@ export function lineOfTomlKey(text, dottedKey, scope) {
         const headerMatch = /^\[\[?\s*([^\]]+?)\s*\]\]?\s*(#.*)?$/.exec(trimmed);
         if (headerMatch) {
             currentTable = splitTomlDottedKey(headerMatch[1]);
-            inTargetTable = currentTable.join('.') === targetHeader;
             continue;
         }
-        if (!inTargetTable)
-            continue;
         if (trimmed === '' || trimmed.startsWith('#'))
             continue;
         if (!inScope(lineNumber))
             continue;
-        // Match leaf key at start of line: bare, "quoted", or 'literal'
-        const leafPattern = new RegExp(`^\\s*(?:${escapeForRegex(leaf)}|"${escapeForRegex(leaf)}"|'${escapeForRegex(leaf)}')\\s*(?:\\.|=)`);
-        if (leafPattern.test(raw))
+        // Generalized dotted-key matching: if the current table is a strict
+        // prefix of (or equal to) the target dotted key, try matching the
+        // REMAINING dotted segments on this line. Covers all three cases:
+        //  - Top-level (`a.b.c = 1` at root):     currentTable=[]      → match `a.b.c`
+        //  - Inside a parent (`[a]\nb.c = 1`):    currentTable=['a']   → match `b.c`
+        //  - Inside the exact table (`[a.b]\nc = 1`): currentTable=['a','b'] → match `c`
+        const tableIsPrefix = currentTable.length <= parts.length &&
+            currentTable.every((seg, idx) => seg === parts[idx]);
+        if (!tableIsPrefix)
+            continue;
+        const remaining = parts.slice(currentTable.length);
+        if (remaining.length === 0)
+            continue;
+        // Remaining-as-dotted-key match (covers any depth ≥ 1). Build the
+        // regex from individual segments joined by `\s*\.\s*` so spaced dotted
+        // keys (`a . b . c = 1` — valid TOML) match as well as compact ones.
+        const segmentsPattern = remaining.map(escapeForRegex).join('\\s*\\.\\s*');
+        const dottedPattern = new RegExp(`^\\s*${segmentsPattern}\\s*=`);
+        if (dottedPattern.test(raw))
             return lineNumber;
-        // Also: dotted key like `prefix.leaf = ...` defined at top-level
-        if (prefix.length > 0 && currentTable.length === 0) {
-            const dottedPattern = new RegExp(`^\\s*${escapeForRegex(dottedKey)}\\s*=`);
-            if (dottedPattern.test(raw))
+        // If remaining is exactly the leaf, also try the quoted-leaf forms
+        if (remaining.length === 1) {
+            const leafKey = remaining[0];
+            const leafPattern = new RegExp(`^\\s*(?:${escapeForRegex(leafKey)}|"${escapeForRegex(leafKey)}"|'${escapeForRegex(leafKey)}')\\s*(?:\\.|=)`);
+            if (leafPattern.test(raw))
                 return lineNumber;
         }
     }
     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.
+ * Walk a line and update multi-line string state.
+ *
+ * Inside a basic multi-line string (`"""…"""`), a backslash escapes the next
+ * character — so `\"""` is a literal `"""` inside the value, NOT the string's
+ * closing delimiter. The walker must skip the next character after each `\`
+ * or it'll terminate the string state early and start matching key patterns
+ * against text that's still inside the value.
+ *
+ * Literal multi-line strings (`'''…'''`) do not process escapes per TOML spec,
+ * so backslash is inert there.
  */
 function updateMultilineStringState(line, current) {
     let state = current;
     let pos = 0;
-    while (pos <= line.length - 3) {
-        const window = line.substr(pos, 3);
-        if (state === null) {
+    while (pos < line.length) {
+        if (state === '"""') {
+            // Inside a basic multi-line string — honor backslash escapes
+            if (line[pos] === '\\') {
+                pos += 2; // skip the backslash AND the next character
+                continue;
+            }
+            if (pos <= line.length - 3 && line.substr(pos, 3) === '"""') {
+                state = null;
+                pos += 3;
+                continue;
+            }
+            pos++;
+            continue;
+        }
+        if (state === "'''") {
+            // Literal multi-line — no escapes per spec
+            if (pos <= line.length - 3 && line.substr(pos, 3) === "'''") {
+                state = null;
+                pos += 3;
+                continue;
+            }
+            pos++;
+            continue;
+        }
+        // state === null
+        if (pos <= line.length - 3) {
+            const window = line.substr(pos, 3);
             if (window === '"""') {
                 state = '"""';
                 pos += 3;
@@ -126,16 +168,6 @@ function updateMultilineStringState(line, current) {
                 continue;
             }
         }
-        else if (state === '"""' && window === '"""') {
-            state = null;
-            pos += 3;
-            continue;
-        }
-        else if (state === "'''" && window === "'''") {
-            state = null;
-            pos += 3;
-            continue;
-        }
         pos++;
     }
     return state;

package/dist/mcp.js

@@ -41,13 +41,47 @@ export function normalizeMcpCommand(spec) {
     }
     return parts.join('\n');
 }
-/** Strip `.cmd`/`.exe`/`.bat`/`.ps1` suffix and lowercase on Windows-style paths. */
+/**
+ * Strip `.cmd`/`.exe`/`.bat`/`.ps1` suffix on Windows-style paths and
+ * lowercase those — Windows filesystem lookup is case-insensitive, so
+ * `NPX.CMD`, `npx.cmd`, and `npx` all refer to the same executable and
+ * should produce identical identity strings. POSIX paths (no backslash
+ * separator, no Windows suffix) keep their case because `./curl` and
+ * `./CURL` are genuinely different files there.
+ */
 function normalizeExecutable(cmd) {
     const trimmed = cmd.trim();
     const base = trimmed.replace(/\\/g, '/');
+    const hadWindowsSuffix = /\.(cmd|exe|bat|ps1)$/i.test(base);
     const withoutSuffix = base.replace(/\.(cmd|exe|bat|ps1)$/i, '');
-    return withoutSuffix;
+    // Windows-shaped if the original used `\` separators or had a Windows
+    // executable suffix. In either case, case-fold for cross-machine identity.
+    const isWindowsShaped = hadWindowsSuffix || trimmed.includes('\\');
+    const cased = isWindowsShaped ? withoutSuffix.toLowerCase() : withoutSuffix;
+    // De-noise PATH-resolved runtimes: `/usr/bin/node` and `node` both run node.
+    // Only fold when the basename matches a known runtime so custom scripts at
+    // absolute paths (e.g. `/opt/internal/orchestrator.sh`) keep their identity.
+    const basename = cased.split('/').pop() ?? cased;
+    if (KNOWN_RUNTIMES.has(basename.toLowerCase())) {
+        return isWindowsShaped ? basename.toLowerCase() : basename;
+    }
+    return cased;
 }
+/**
+ * Common runtime executables whose absolute-path location varies across
+ * machines (PATH lookup resolves them) but whose identity for MCP-config
+ * purposes is the runtime name itself. Conservative — only entries where
+ * basename collapse is provably safe across the platforms an MCP config
+ * might be authored on.
+ */
+const KNOWN_RUNTIMES = new Set([
+    'node', 'npx', 'npm', 'pnpm', 'yarn',
+    'python', 'python3', 'pip', 'pip3', 'pipx', 'uvx', 'uv',
+    'ruby', 'gem', 'bundle',
+    'perl', 'cpan',
+    'bash', 'sh', 'zsh', 'fish', 'powershell', 'pwsh',
+    'deno', 'bun', 'tsx', 'ts-node',
+]);
 function normalizePath(p) {
     return p.trim().replace(/\\/g, '/').replace(/\/+$/, '');
 }
@@ -59,6 +93,22 @@ function normalizePath(p) {
  * (npx, uvx, pipx, node).
  */
 const NEUTRAL_BOOLEAN_FLAGS = new Set(['-y', '--yes']);
+/**
+ * Flags universally treated as boolean (no value follows) by the runners we
+ * care about. Listed so `canonicalizeArgs` doesn't greedily pair them with the
+ * next positional argument, which would conflate `--verbose pkg` with
+ * `--verbose=pkg`. Unlike NEUTRAL_BOOLEAN_FLAGS these stay in the canonical
+ * form — they're load-bearing (different identity vs. their absence) but
+ * standalone.
+ *
+ * Conservative — only flags where "takes a value" is essentially never their
+ * meaning in any CLI we'd see in an MCP config.
+ */
+const KNOWN_BOOLEAN_FLAGS = new Set([
+    '-v', '-V', '-q', '-h', '-d',
+    '--verbose', '--quiet', '--silent', '--debug', '--help', '--version',
+    '--force', '--dry-run', '--no-cache', '--no-color', '--no-progress', '--json',
+]);
 /**
  * Sort *neutral* flag/value pairs so reordering doesn't change identity, but
  * preserve the order of positional arguments (which are usually load-bearing —
@@ -87,6 +137,15 @@ function canonicalizeArgs(args) {
                 flagPairs.push([a.slice(0, eq), a.slice(eq + 1)]);
                 continue;
             }
+            // Known-boolean flags never consume the next argument, so `--verbose pkg`
+            // leaves `pkg` as a positional rather than collapsing into a fake pair.
+            // Without this guard, reordering ['--host', 'localhost', '--verbose', 'pkg']
+            // vs ['--verbose', '--host', 'localhost', 'pkg'] produced different
+            // canonical strings because `--verbose` greedily ate the next non-flag.
+            if (KNOWN_BOOLEAN_FLAGS.has(a)) {
+                flagPairs.push([a, null]);
+                continue;
+            }
             const next = filtered[i + 1];
             if (next !== undefined && !next.startsWith('-')) {
                 flagPairs.push([a, next]);

package/dist/merge.d.ts

@@ -0,0 +1,91 @@
+import { type Finding, type Severity, type ToolKind } from './finding.js';
+export interface MergeOptions {
+    /**
+     * Lower bound for findings included in the merged output. Anything below
+     * this severity is dropped from `findings` (but still counted in
+     * `droppedBelowThreshold`). Defaults to `'low'` (include everything).
+     */
+    threshold?: Severity;
+    /**
+     * When two reports contribute findings with the same fingerprint, the
+     * default keeps the one with the higher severity. Set this to `'first'`
+     * to keep the first report's finding instead. Default: `'highest_severity'`.
+     */
+    duplicatePolicy?: 'highest_severity' | 'first';
+}
+export interface MergeSource {
+    tool: ToolKind;
+    toolVersion?: string;
+    /** Conversation ID declared by this source, if any. */
+    conversationId?: string;
+    /** Number of findings in this source report (BEFORE dedup or threshold filtering). */
+    findingCount: number;
+    /** Aggregate rating reported by the source. */
+    rating: 'none' | Severity;
+}
+export interface InvalidReport {
+    /** Index into the input `reports` array. */
+    index: number;
+    /** Tool name from the malformed report, if recoverable. */
+    tool?: ToolKind;
+    errors: string[];
+}
+export interface InvalidFinding {
+    /** Originating tool's report index. */
+    reportIndex: number;
+    /** Index of the finding within that report's `findings` array. */
+    findingIndex: number;
+    /** Tool name from the report. */
+    tool: ToolKind;
+    errors: string[];
+}
+export interface MergedReport {
+    schemaVersion: '1.0';
+    /** Per-tool provenance for the reports that fed into this merge. */
+    sources: MergeSource[];
+    /** Aggregate rating across all surviving findings. */
+    rating: 'none' | Severity;
+    /**
+     * Conversation ID shared by all valid source reports — set iff every source
+     * declared the same `conversationId`. When sources disagree (or some lack the
+     * field), this is omitted so a meta-reviewer can detect cross-conversation
+     * mixing.
+     */
+    conversationId?: string;
+    /** Deduped findings, sorted by severity (highest first). */
+    findings: Finding[];
+    /** Count of findings dropped because their severity was below `threshold`. */
+    droppedBelowThreshold: number;
+    /** Count of finding pairs collapsed via fingerprint dedup. */
+    duplicateCollapsed: number;
+    /** Reports rejected by envelope validation. */
+    invalidReports: InvalidReport[];
+    /** Individual findings rejected by finding validation. */
+    invalidFindings: InvalidFinding[];
+    /** Severity counts across the surviving findings. */
+    severityCounts: Record<Severity, number>;
+}
+/**
+ * Merge N reports from different tools into one normalized report. Validates
+ * each input report and each finding, deduplicates by fingerprint, applies an
+ * optional severity threshold, and rolls up the aggregate rating.
+ *
+ * Invalid reports / findings are NOT silently dropped — they're collected in
+ * `invalidReports` and `invalidFindings` so a meta-reviewer can surface them
+ * to the user instead of letting bad data disappear.
+ *
+ * @example
+ * import { readFileSync } from 'node:fs';
+ * import { mergeFindings } from 'agent-gov-core';
+ *
+ * const reports = [
+ *   JSON.parse(readFileSync('scopetrail-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('policymesh-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('capabilityecho-report.json', 'utf8')),
+ * ];
+ * const merged = mergeFindings(reports, { threshold: 'medium' });
+ * console.log(`Merged rating: ${merged.rating}`);
+ * console.log(`${merged.findings.length} unique findings across ${merged.sources.length} tools`);
+ */
+export declare function mergeFindings(reports: readonly unknown[], opts?: MergeOptions): MergedReport;
+//# sourceMappingURL=merge.d.ts.map

package/dist/merge.js

@@ -0,0 +1,154 @@
+import { SEVERITIES, TOOL_KINDS, isToolKind, validateFinding } from './finding.js';
+import { REPORT_SCHEMA_VERSION, maxSeverity } from './report.js';
+import { rankSeverity } from './action.js';
+/**
+ * Merge N reports from different tools into one normalized report. Validates
+ * each input report and each finding, deduplicates by fingerprint, applies an
+ * optional severity threshold, and rolls up the aggregate rating.
+ *
+ * Invalid reports / findings are NOT silently dropped — they're collected in
+ * `invalidReports` and `invalidFindings` so a meta-reviewer can surface them
+ * to the user instead of letting bad data disappear.
+ *
+ * @example
+ * import { readFileSync } from 'node:fs';
+ * import { mergeFindings } from 'agent-gov-core';
+ *
+ * const reports = [
+ *   JSON.parse(readFileSync('scopetrail-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('policymesh-report.json', 'utf8')),
+ *   JSON.parse(readFileSync('capabilityecho-report.json', 'utf8')),
+ * ];
+ * const merged = mergeFindings(reports, { threshold: 'medium' });
+ * console.log(`Merged rating: ${merged.rating}`);
+ * console.log(`${merged.findings.length} unique findings across ${merged.sources.length} tools`);
+ */
+export function mergeFindings(reports, opts = {}) {
+    const threshold = opts.threshold ?? 'low';
+    const duplicatePolicy = opts.duplicatePolicy ?? 'highest_severity';
+    const thresholdRank = rankSeverity(threshold);
+    const sources = [];
+    const invalidReports = [];
+    const invalidFindings = [];
+    // fingerprint → Finding chosen so far
+    const dedupe = new Map();
+    let droppedBelowThreshold = 0;
+    let duplicateCollapsed = 0;
+    for (let i = 0; i < reports.length; i++) {
+        const candidate = reports[i];
+        // Structural envelope check — does NOT recurse into individual findings.
+        // A report with some malformed findings is still partially mergeable; we
+        // collect the bad ones into `invalidFindings` and pass through the good
+        // ones. Only a structurally broken envelope (wrong tool, missing array,
+        // etc.) gets rejected wholesale.
+        const envelope = validateReportEnvelope(candidate);
+        if (!envelope.ok) {
+            const tool = candidateTool(candidate);
+            invalidReports.push({ index: i, tool, errors: envelope.errors });
+            continue;
+        }
+        const report = candidate;
+        const source = {
+            tool: report.tool,
+            findingCount: report.findings.length,
+            rating: report.rating,
+        };
+        if (report.toolVersion !== undefined)
+            source.toolVersion = report.toolVersion;
+        if (report.conversationId !== undefined)
+            source.conversationId = report.conversationId;
+        sources.push(source);
+        for (let j = 0; j < report.findings.length; j++) {
+            const finding = report.findings[j];
+            const findingCheck = validateFinding(finding);
+            if (!findingCheck.ok) {
+                invalidFindings.push({
+                    reportIndex: i,
+                    findingIndex: j,
+                    tool: report.tool,
+                    errors: findingCheck.errors,
+                });
+                continue;
+            }
+            if (rankSeverity(finding.severity) < thresholdRank) {
+                droppedBelowThreshold++;
+                continue;
+            }
+            // Dedupe by fingerprint. Fall back to the finding's structural identity
+            // when fingerprint is missing — though by v0.5.0 it should always be
+            // populated by `createFinding`.
+            const key = finding.fingerprint ?? `${finding.kind}|${finding.location?.file ?? ''}|${finding.location?.line ?? ''}|${finding.salientKey ?? ''}`;
+            const existing = dedupe.get(key);
+            if (existing === undefined) {
+                dedupe.set(key, finding);
+                continue;
+            }
+            duplicateCollapsed++;
+            if (duplicatePolicy === 'highest_severity') {
+                if (rankSeverity(finding.severity) > rankSeverity(existing.severity)) {
+                    dedupe.set(key, finding);
+                }
+            }
+            // 'first' policy: keep existing — do nothing
+        }
+    }
+    const findings = Array.from(dedupe.values()).sort((a, b) => rankSeverity(b.severity) - rankSeverity(a.severity));
+    const severityCounts = { low: 0, medium: 0, high: 0, critical: 0 };
+    for (const f of findings)
+        severityCounts[f.severity]++;
+    // Propagate conversationId iff every source agrees. When sources disagree
+    // or some lack the field, leave it undefined — silent unification of cross-
+    // conversation reports would hide a meta-reviewer misuse.
+    const conversationIds = sources.map((s) => s.conversationId);
+    const allSame = conversationIds.length > 0
+        && conversationIds.every((id) => id !== undefined && id === conversationIds[0]);
+    const merged = {
+        schemaVersion: '1.0',
+        sources,
+        rating: maxSeverity(findings),
+        findings,
+        droppedBelowThreshold,
+        duplicateCollapsed,
+        invalidReports,
+        invalidFindings,
+        severityCounts,
+    };
+    if (allSame)
+        merged.conversationId = conversationIds[0];
+    return merged;
+}
+function candidateTool(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const t = value.tool;
+    return typeof t === 'string' && /^(scope_trail|policy_mesh|capability_echo|task_bound|session_trail)$/.test(t)
+        ? t
+        : undefined;
+}
+/**
+ * Envelope-only structural check. Unlike `validateReport`, this does NOT
+ * recurse into individual findings — that's done separately by mergeFindings
+ * so a single bad finding doesn't poison the rest of the report.
+ */
+function validateReportEnvelope(value) {
+    const errors = [];
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return { ok: false, errors: ['report must be a plain object'] };
+    }
+    const v = value;
+    if (v.schemaVersion !== REPORT_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be '${REPORT_SCHEMA_VERSION}'`);
+    }
+    if (!isToolKind(v.tool)) {
+        errors.push(`tool must be one of: ${TOOL_KINDS.join(', ')}`);
+    }
+    const ratingValues = new Set(['none', ...SEVERITIES]);
+    if (typeof v.rating !== 'string' || !ratingValues.has(v.rating)) {
+        errors.push(`rating must be one of: none, ${SEVERITIES.join(', ')}`);
+    }
+    if (!Array.isArray(v.findings)) {
+        errors.push('findings must be an array');
+    }
+    return { ok: errors.length === 0, errors };
+}
+//# sourceMappingURL=merge.js.map

package/dist/parse-error.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured config-file parse error. Carries the 1-based line and column of
+ * the failure so consumers can emit a `*.config_syntax_error` Finding pointing
+ * at the exact spot without recomputing line numbers from the raw offset.
+ *
+ * Thrown nowhere directly — instead, {@link readJsonObjectWithSource} and
+ * {@link readTomlObject} populate the `parseError` field of their result with
+ * this type whenever they can resolve a byte offset from the underlying parser.
+ * When the underlying error lacks position info, the original `Error` is
+ * preserved unchanged.
+ *
+ * @example
+ * import { readTomlObject, ConfigParseError } from 'agent-gov-core';
+ * const { parseError } = readTomlObject('.codex/config.toml');
+ * if (parseError instanceof ConfigParseError) {
+ *   emitFinding({
+ *     kind: 'policy_mesh.config_syntax_error',
+ *     location: { file: '.codex/config.toml', line: parseError.line, column: parseError.column },
+ *     message: parseError.message,
+ *   });
+ * }
+ */
+export declare class ConfigParseError extends Error {
+    readonly line: number;
+    readonly column: number;
+    readonly rawOffset: number;
+    constructor(message: string, opts: {
+        line: number;
+        column: number;
+        rawOffset: number;
+        cause?: Error;
+    });
+}
+/** Convert a 0-based byte offset to 1-based line and column. */
+export declare function lineColumnOfOffset(text: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Extract a byte offset from a parser error message. Both this library's TOML
+ * parser ("at offset N") and Node's `JSON.parse` ("at position N", or a
+ * `position` property on newer runtimes) use compatible-enough formats that
+ * one helper handles both.
+ *
+ * Returns `null` when no offset can be recovered — most semantic errors
+ * (duplicate-key, table redefinition) don't include one.
+ */
+export declare function extractParseOffset(err: Error): number | null;
+/**
+ * Wrap an arbitrary parser error into a {@link ConfigParseError} when offset
+ * recovery is possible; otherwise return the original error unchanged.
+ */
+export declare function toConfigParseError(text: string, err: Error): Error;
+//# sourceMappingURL=parse-error.d.ts.map

package/dist/parse-error.js

@@ -0,0 +1,85 @@
+/**
+ * Structured config-file parse error. Carries the 1-based line and column of
+ * the failure so consumers can emit a `*.config_syntax_error` Finding pointing
+ * at the exact spot without recomputing line numbers from the raw offset.
+ *
+ * Thrown nowhere directly — instead, {@link readJsonObjectWithSource} and
+ * {@link readTomlObject} populate the `parseError` field of their result with
+ * this type whenever they can resolve a byte offset from the underlying parser.
+ * When the underlying error lacks position info, the original `Error` is
+ * preserved unchanged.
+ *
+ * @example
+ * import { readTomlObject, ConfigParseError } from 'agent-gov-core';
+ * const { parseError } = readTomlObject('.codex/config.toml');
+ * if (parseError instanceof ConfigParseError) {
+ *   emitFinding({
+ *     kind: 'policy_mesh.config_syntax_error',
+ *     location: { file: '.codex/config.toml', line: parseError.line, column: parseError.column },
+ *     message: parseError.message,
+ *   });
+ * }
+ */
+export class ConfigParseError extends Error {
+    line;
+    column;
+    rawOffset;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'ConfigParseError';
+        this.line = opts.line;
+        this.column = opts.column;
+        this.rawOffset = opts.rawOffset;
+        if (opts.cause) {
+            // Node 16.9+ supports the `cause` option on Error; some runtimes don't.
+            this.cause = opts.cause;
+        }
+    }
+}
+/** Convert a 0-based byte offset to 1-based line and column. */
+export function lineColumnOfOffset(text, offset) {
+    const safe = Math.max(0, Math.min(offset, text.length));
+    let line = 1;
+    let column = 1;
+    for (let i = 0; i < safe; i++) {
+        if (text[i] === '\n') {
+            line++;
+            column = 1;
+        }
+        else {
+            column++;
+        }
+    }
+    return { line, column };
+}
+/**
+ * Extract a byte offset from a parser error message. Both this library's TOML
+ * parser ("at offset N") and Node's `JSON.parse` ("at position N", or a
+ * `position` property on newer runtimes) use compatible-enough formats that
+ * one helper handles both.
+ *
+ * Returns `null` when no offset can be recovered — most semantic errors
+ * (duplicate-key, table redefinition) don't include one.
+ */
+export function extractParseOffset(err) {
+    const m = /at (?:offset|position)\s+(\d+)/i.exec(err.message);
+    if (m)
+        return Number.parseInt(m[1], 10);
+    // Newer Node (≥21) attaches `position` to SyntaxError from JSON.parse.
+    const maybePos = err.position;
+    if (typeof maybePos === 'number')
+        return maybePos;
+    return null;
+}
+/**
+ * Wrap an arbitrary parser error into a {@link ConfigParseError} when offset
+ * recovery is possible; otherwise return the original error unchanged.
+ */
+export function toConfigParseError(text, err) {
+    const offset = extractParseOffset(err);
+    if (offset === null)
+        return err;
+    const { line, column } = lineColumnOfOffset(text, offset);
+    return new ConfigParseError(err.message, { line, column, rawOffset: offset, cause: err });
+}
+//# sourceMappingURL=parse-error.js.map