@provartesting/provardx-cli 1.5.0 → 1.5.2-beta.2

package/lib/mcp/utils/fieldMask.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+/**
+ * Mask an object (or array of objects) to retain only the specified fields.
+ *
+ * - Top-level keys: `"name"` keeps only the `name` property
+ * - Dot notation:   `"steps.action"` keeps the `steps` array but only `action` within each element
+ * - Unknown field names are silently ignored — never an error
+ * - Arrays: masking is applied to every element
+ *
+ * @param obj    Source object or array (typed as unknown; cast internally, never through any)
+ * @param fields Parsed field list — each entry is a dot-path string
+ */
+export function maskFields(obj, fields) {
+    if (Array.isArray(obj)) {
+        return obj.map((item) => maskFields(item, fields));
+    }
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    const source = obj;
+    // Group fields: topLevelKeys contains every key to retain.
+    // dotFields[key] holds the sub-paths to drill into for that key.
+    const topLevelKeys = new Set();
+    const dotFields = {};
+    for (const field of fields) {
+        const dotIdx = field.indexOf('.');
+        if (dotIdx === -1) {
+            topLevelKeys.add(field);
+        }
+        else {
+            const top = field.slice(0, dotIdx);
+            const rest = field.slice(dotIdx + 1);
+            topLevelKeys.add(top);
+            if (!dotFields[top])
+                dotFields[top] = [];
+            dotFields[top].push(rest);
+        }
+    }
+    const result = {};
+    for (const key of topLevelKeys) {
+        if (!(key in source))
+            continue; // silently ignore unknown fields
+        const subPaths = dotFields[key];
+        if (subPaths) {
+            const val = source[key];
+            // Dot-path into a primitive can't be narrowed; omit rather than leak the whole value.
+            if (Array.isArray(val) || (val !== null && typeof val === 'object')) {
+                result[key] = maskFields(val, subPaths);
+            }
+        }
+        else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+/**
+ * Parse a comma-separated fields string into a trimmed, non-empty field list.
+ * Returns null when the string is absent or blank (caller should skip masking).
+ */
+export function parseFieldsParam(fields) {
+    if (!fields)
+        return null;
+    const parsed = fields
+        .split(',')
+        .map((f) => f.trim())
+        .filter(Boolean);
+    return parsed.length > 0 ? parsed : null;
+}
+//# sourceMappingURL=fieldMask.js.map

package/lib/mcp/utils/fieldMask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldMask.js","sourceRoot":"","sources":["../../../src/mcp/utils/fieldMask.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY,EAAE,MAAgB;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,MAAM,GAAG,GAA8B,CAAC;IAE9C,2DAA2D;IAC3D,iEAAiE;IACjE,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,MAAM,SAAS,GAA6B,EAAE,CAAC;IAE/C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACnC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACrC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC;gBAAE,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YACzC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC;YAAE,SAAS,CAAC,iCAAiC;QACjE,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,sFAAsF;YACtF,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACpE,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA0B;IACzD,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM;SAClB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC"}

package/lib/mcp/utils/testCasePlanMode.d.ts

@@ -0,0 +1,41 @@
+/**
+ * How the project's provardx-properties.json runs this test case.
+ *
+ * `direct` means the test case path appears in `testCase` or `testCases` and
+ * no `.testinstance` references it — data-driven `<dataTable>` rows will not
+ * iterate. `plan` means the test case is referenced by at least one
+ * `.testinstance` under `plans/`, so data-driven execution works. `unknown`
+ * means the properties file could not be resolved or parsed (no
+ * `~/.sf/config.json`, file outside allowed paths, missing project root, etc.)
+ * — callers should default to the safe behaviour (emit the structural
+ * warning) when the mode is unknown.
+ */
+export type TestCasePlanMode = 'direct' | 'plan' | 'unknown';
+export interface ResolvedTestCaseMode {
+    mode: TestCasePlanMode;
+    /** The properties-file path consulted (when resolved). */
+    propertiesFilePath?: string;
+    /** The project root resolved from the properties file (when present). */
+    projectPath?: string;
+}
+interface ResolveOptions {
+    /** Path to the test case file under validation. */
+    testCaseFilePath: string;
+    /** Allowed-paths policy from the MCP server config. */
+    allowedPaths: string[];
+    /** Override of ~/.sf/config.json location for testing. */
+    sfConfigPathOverride?: string;
+    /** Override of provardx-properties.json location for testing. */
+    propertiesFilePathOverride?: string;
+}
+/**
+ * Resolve whether a given test case file is referenced directly via
+ * `testCase`/`testCases` or via a `.testinstance` inside a plan.
+ *
+ * The resolution flow is intentionally best-effort and silent: any file
+ * read failure, JSON parse error, or path-policy violation collapses to
+ * `mode: 'unknown'` so the caller falls back to default behaviour rather
+ * than surfacing a confusing error from the validator.
+ */
+export declare function resolveTestCasePlanMode(opts: ResolveOptions): ResolvedTestCaseMode;
+export {};

package/lib/mcp/utils/testCasePlanMode.js

@@ -0,0 +1,208 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+/* eslint-disable camelcase */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { assertPathAllowed } from '../security/pathPolicy.js';
+/**
+ * Resolve whether a given test case file is referenced directly via
+ * `testCase`/`testCases` or via a `.testinstance` inside a plan.
+ *
+ * The resolution flow is intentionally best-effort and silent: any file
+ * read failure, JSON parse error, or path-policy violation collapses to
+ * `mode: 'unknown'` so the caller falls back to default behaviour rather
+ * than surfacing a confusing error from the validator.
+ */
+export function resolveTestCasePlanMode(opts) {
+    const propsPath = readPropertiesFilePath(opts);
+    if (!propsPath)
+        return { mode: 'unknown' };
+    let propsObj;
+    try {
+        propsObj = JSON.parse(fs.readFileSync(propsPath, 'utf-8'));
+    }
+    catch {
+        return { mode: 'unknown', propertiesFilePath: propsPath };
+    }
+    const projectPath = typeof propsObj['projectPath'] === 'string' ? propsObj['projectPath'] : null;
+    if (!projectPath) {
+        // Without a project root we cannot resolve relative `testCase` entries or
+        // walk `plans/`. The mode is unknown.
+        return { mode: 'unknown', propertiesFilePath: propsPath };
+    }
+    let resolvedProjectPath;
+    try {
+        resolvedProjectPath = path.resolve(projectPath);
+        assertPathAllowed(resolvedProjectPath, opts.allowedPaths);
+    }
+    catch {
+        return { mode: 'unknown', propertiesFilePath: propsPath };
+    }
+    const resolvedTestCasePath = path.resolve(opts.testCaseFilePath);
+    // A `.testinstance` reference inside any plan wins — plan mode supports
+    // data-driven iteration.
+    if (isReferencedFromPlanInstance(resolvedProjectPath, resolvedTestCasePath)) {
+        return { mode: 'plan', propertiesFilePath: propsPath, projectPath: resolvedProjectPath };
+    }
+    if (isReferencedDirectly(propsObj, resolvedProjectPath, resolvedTestCasePath)) {
+        return { mode: 'direct', propertiesFilePath: propsPath, projectPath: resolvedProjectPath };
+    }
+    return { mode: 'unknown', propertiesFilePath: propsPath, projectPath: resolvedProjectPath };
+}
+/**
+ * Resolve the active properties file path. Prefers an explicit override
+ * (used by tests), then `~/.sf/config.json`'s `PROVARDX_PROPERTIES_FILE_PATH`.
+ *
+ * Both the override and the value read from `~/.sf/config.json` are funnelled
+ * through `assertPathAllowed` so a caller cannot trick the resolver into
+ * reading a properties file outside the configured `allowedPaths`. Any policy
+ * violation collapses to `null` to preserve the helper's best-effort contract.
+ */
+function readPropertiesFilePath(opts) {
+    if (opts.propertiesFilePathOverride) {
+        return enforceAllowed(opts.propertiesFilePathOverride, opts.allowedPaths);
+    }
+    try {
+        const sfConfigPath = opts.sfConfigPathOverride ?? path.join(os.homedir(), '.sf', 'config.json');
+        if (!fs.existsSync(sfConfigPath))
+            return null;
+        const sfConfig = JSON.parse(fs.readFileSync(sfConfigPath, 'utf-8'));
+        const propsPath = sfConfig['PROVARDX_PROPERTIES_FILE_PATH'];
+        if (!propsPath)
+            return null;
+        return enforceAllowed(propsPath, opts.allowedPaths);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve a candidate properties-file path through `assertPathAllowed`, then
+ * canonicalize via `fs.realpathSync` when the file exists so a symlink
+ * inside an allowed directory cannot redirect the read outside it. Returns
+ * `null` on any policy violation, missing file, or unexpected error — the
+ * caller treats `null` as "mode unknown" and falls back to default behaviour.
+ */
+function enforceAllowed(candidate, allowedPaths) {
+    try {
+        const resolved = path.resolve(candidate);
+        assertPathAllowed(resolved, allowedPaths);
+        if (!fs.existsSync(resolved))
+            return null;
+        try {
+            return fs.realpathSync(resolved);
+        }
+        catch {
+            return resolved;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Does the properties file's top-level `testCase` or `testCases` array
+ * reference this test case file? Entries are interpreted relative to
+ * `<projectPath>/tests/` (per the Provar runtime convention).
+ */
+function isReferencedDirectly(props, projectPath, testCaseFilePath) {
+    const entries = [];
+    const tc = props['testCase'];
+    const tcs = props['testCases'];
+    for (const candidate of [tc, tcs]) {
+        if (typeof candidate === 'string') {
+            entries.push(candidate);
+        }
+        else if (Array.isArray(candidate)) {
+            for (const e of candidate) {
+                if (typeof e === 'string')
+                    entries.push(e);
+            }
+        }
+    }
+    if (entries.length === 0)
+        return false;
+    const testsDir = path.join(projectPath, 'tests');
+    const targetNorm = path.resolve(testCaseFilePath).toLowerCase();
+    for (const entry of entries) {
+        // Provar accepts both bare names ("MyTest") and relative paths
+        // ("Module/MyTest.testcase"). Allow either; match with and without the
+        // `.testcase` extension.
+        const variants = [];
+        const trimmed = entry.replace(/^[/\\]+/, '');
+        variants.push(path.resolve(testsDir, trimmed));
+        if (!/\.testcase$/i.test(trimmed)) {
+            variants.push(path.resolve(testsDir, `${trimmed}.testcase`));
+        }
+        for (const v of variants) {
+            if (v.toLowerCase() === targetNorm)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Walk `<projectPath>/plans/` for `.testinstance` files referencing this
+ * test case via `testCasePath="..."`. Best-effort — any read error skips
+ * the offending file.
+ */
+function isReferencedFromPlanInstance(projectPath, testCaseFilePath) {
+    const plansDir = path.join(projectPath, 'plans');
+    if (!fs.existsSync(plansDir))
+        return false;
+    const testsDir = path.join(projectPath, 'tests');
+    const targetNorm = path.resolve(testCaseFilePath).toLowerCase();
+    let found = false;
+    const walk = (dir) => {
+        if (found)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (found)
+                return;
+            if (entry.name.startsWith('.') && !entry.name.endsWith('.testinstance'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!entry.name.endsWith('.testinstance'))
+                continue;
+            let content;
+            try {
+                content = fs.readFileSync(full, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const matches = content.matchAll(/testCasePath=["']([^"']+)["']/g);
+            for (const m of matches) {
+                const rel = m[1].replace(/\\/g, '/');
+                // testCasePath in Provar testinstances is conventionally relative to
+                // `<projectPath>/tests/`. Also tolerate paths relative to project root.
+                const candidates = [path.resolve(testsDir, rel), path.resolve(projectPath, rel)];
+                for (const c of candidates) {
+                    if (c.toLowerCase() === targetNorm) {
+                        found = true;
+                        return;
+                    }
+                }
+            }
+        }
+    };
+    walk(plansDir);
+    return found;
+}
+//# sourceMappingURL=testCasePlanMode.js.map

package/lib/mcp/utils/testCasePlanMode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testCasePlanMode.js","sourceRoot":"","sources":["../../../src/mcp/utils/testCasePlanMode.ts"],"names":[],"mappings":"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"}

package/lib/mcp/utils/tokenMeta.d.ts

@@ -0,0 +1,40 @@
+type ContentItem = {
+    type: 'text';
+    text: string;
+};
+export interface ToolResult {
+    content: ContentItem[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+interface ToolExtra {
+    sessionId?: string;
+}
+export type AnyToolCallback = (args: Record<string, unknown>, extra: ToolExtra) => ToolResult | Promise<ToolResult>;
+interface SessionEntry {
+    calls: number;
+    totalEstimatedTokens: number;
+}
+export type DepthGuardState = Map<string, SessionEntry>;
+export declare function createDepthGuardState(): DepthGuardState;
+/**
+ * Wraps a tool handler to enforce a per-session call budget.
+ * Once `limit` calls have been made for a session, every further call returns
+ * TOOL_BUDGET_EXCEEDED without invoking the underlying handler.
+ * Callers without a sessionId (stdio transports — Claude Desktop, Cursor, etc.)
+ * share a single 'anon' bucket so the budget actually limits runaway tool use;
+ * giving each anon call a fresh UUID would defeat the purpose of the guard.
+ * `provardx_ping` is excluded from wrapping at the call site in server.ts.
+ */
+export declare function wrapWithDepthGuard(toolName: string, handler: AnyToolCallback, state: DepthGuardState, limit: number): AnyToolCallback;
+export declare function estimateTokens(payload: unknown): number;
+/**
+ * Appends a `_meta` key to `structuredContent` when PROVAR_MCP_EMIT_TOKEN_META=true.
+ * The `content[0].text` string is intentionally left unchanged — LLMs read that
+ * field, so including meta there would waste tokens on observability data.
+ *
+ * @param sessionTotalTokens - Cumulative estimated tokens for the session,
+ * included only on TOOL_BUDGET_EXCEEDED errors.
+ */
+export declare function attachMeta(response: ToolResult, toolName: string, detailLevel: string, sessionTotalTokens?: number): ToolResult;
+export {};

package/lib/mcp/utils/tokenMeta.js

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+const MAX_SESSIONS = 1000;
+export function createDepthGuardState() {
+    return new Map();
+}
+function getOrCreateEntry(state, sessionId) {
+    if (!state.has(sessionId)) {
+        if (state.size >= MAX_SESSIONS) {
+            const oldest = state.keys().next().value;
+            if (oldest !== undefined)
+                state.delete(oldest);
+        }
+        state.set(sessionId, { calls: 0, totalEstimatedTokens: 0 });
+    }
+    // Non-null guaranteed by the set above or pre-existing entry.
+    return state.get(sessionId);
+}
+/**
+ * Wraps a tool handler to enforce a per-session call budget.
+ * Once `limit` calls have been made for a session, every further call returns
+ * TOOL_BUDGET_EXCEEDED without invoking the underlying handler.
+ * Callers without a sessionId (stdio transports — Claude Desktop, Cursor, etc.)
+ * share a single 'anon' bucket so the budget actually limits runaway tool use;
+ * giving each anon call a fresh UUID would defeat the purpose of the guard.
+ * `provardx_ping` is excluded from wrapping at the call site in server.ts.
+ */
+export function wrapWithDepthGuard(toolName, handler, state, limit) {
+    return async (args, extra) => {
+        const sessionId = extra.sessionId ?? 'anon';
+        const entry = getOrCreateEntry(state, sessionId);
+        if (entry.calls >= limit) {
+            const payload = {
+                error: 'TOOL_BUDGET_EXCEEDED',
+                callsMade: entry.calls,
+                limit,
+                suggestion: 'Summarize progress and return control to the user.',
+            };
+            const response = {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(payload) }],
+                structuredContent: payload,
+            };
+            return attachMeta(response, toolName, 'standard', entry.totalEstimatedTokens);
+        }
+        entry.calls++;
+        const result = await handler(args, extra);
+        if (process.env['PROVAR_MCP_EMIT_TOKEN_META'] === 'true') {
+            entry.totalEstimatedTokens += estimateTokens(result);
+        }
+        const detailLevel = typeof args['detail'] === 'string' ? args['detail'] : 'standard';
+        return attachMeta(result, toolName, detailLevel);
+    };
+}
+// --------------------------------------------------------------------------- //
+// PDX-475 — Token meta attachment (PROVAR_MCP_EMIT_TOKEN_META)
+// --------------------------------------------------------------------------- //
+export function estimateTokens(payload) {
+    return Math.ceil(JSON.stringify(payload).length / 4);
+}
+/**
+ * Appends a `_meta` key to `structuredContent` when PROVAR_MCP_EMIT_TOKEN_META=true.
+ * The `content[0].text` string is intentionally left unchanged — LLMs read that
+ * field, so including meta there would waste tokens on observability data.
+ *
+ * @param sessionTotalTokens - Cumulative estimated tokens for the session,
+ * included only on TOOL_BUDGET_EXCEEDED errors.
+ */
+export function attachMeta(response, toolName, detailLevel, sessionTotalTokens) {
+    if (process.env['PROVAR_MCP_EMIT_TOKEN_META'] !== 'true')
+        return response;
+    const meta = {
+        tool: toolName,
+        detailLevel,
+        estimatedTokens: estimateTokens(response),
+    };
+    if (sessionTotalTokens !== undefined) {
+        meta['sessionTotalEstimatedTokens'] = sessionTotalTokens;
+    }
+    const existing = response.structuredContent ?? {};
+    return {
+        ...response,
+        structuredContent: { ...existing, _meta: meta },
+    };
+}
+//# sourceMappingURL=tokenMeta.js.map

package/lib/mcp/utils/tokenMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenMeta.js","sourceRoot":"","sources":["../../../src/mcp/utils/tokenMeta.ts"],"names":[],"mappings":"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"}

package/lib/mcp/utils/validationDiff.d.ts

@@ -0,0 +1,57 @@
+export type DiffableViolation = Record<string, unknown>;
+export interface DiffResult {
+    added: DiffableViolation[];
+    resolved: DiffableViolation[];
+    unchanged_count: number;
+    run_id: string;
+}
+/**
+ * Compute a stable 8-char context hash for a tool + context pair. Used to
+ * scope baseline run lookups so that a run_id from context A cannot be diffed
+ * against context B (different project, different suite, different file).
+ */
+export declare function computeContextHash(toolTag: string, context: string): string;
+/**
+ * Resolve the validation storage root for a given tool subdir. Honors the
+ * PROVAR_MCP_VALIDATION_DIR env var when set; otherwise falls back to
+ * `~/.provardx/validation/<subdir>`. The env override is useful for restricted
+ * CI/dev environments where the home directory is read-only or shared.
+ */
+export declare function resolveValidationDir(subdir: string): string;
+/** Generate a run ID from a context string (e.g. project path or suite name). */
+export declare function generateRunId(context: string): string;
+/**
+ * Check whether any prior runs exist in the given storage directory.
+ * Used by calcNextAction to determine the first-run heuristic.
+ */
+export declare function hasAnyRun(storageDir: string): boolean;
+/**
+ * Save the current violations as a new run in the storage directory.
+ * Caps the index at MAX_RUNS by evicting the oldest entry when full.
+ * Returns the generated run_id.
+ *
+ * When `contextHash` is provided, it is recorded alongside the run so that
+ * `loadBaselineViolations` can reject a baseline_run_id whose context does
+ * not match the calling context (prevents cross-context diffs).
+ */
+export declare function saveRun(storageDir: string, runId: string, violations: DiffableViolation[], contextHash?: string): string;
+/**
+ * Load the violations array for a given baseline run ID.
+ * Returns null if the run is not found in the index (BASELINE_NOT_FOUND).
+ * The filename is looked up from the index only — the run_id itself is never
+ * used to construct a file path, preventing path traversal.
+ *
+ * When `expectedContextHash` is provided, the record's `context_hash` must
+ * match. Records without a `context_hash` (written by older versions before
+ * H3) are treated as a mismatch and are effectively retired within one or
+ * two new runs as the FIFO cap evicts them. This guard prevents diffing a
+ * baseline from a different file/suite/project against the current context.
+ */
+export declare function loadBaselineViolations(storageDir: string, baselineRunId: string, expectedContextHash?: string): DiffableViolation[] | null;
+/**
+ * Compute the diff between a baseline and current violations array.
+ * Uses (rule_id + applies_to + full message) as the unique key.
+ * Duplicate violations (same key, multiple occurrences) are treated as
+ * distinct entries — each occurrence is counted separately (multiset semantics).
+ */
+export declare function computeDiff(baseline: DiffableViolation[], current: DiffableViolation[]): Omit<DiffResult, 'run_id'>;