@provartesting/provardx-cli 1.5.0 → 1.5.2

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'>;

package/lib/mcp/utils/validationDiff.js

@@ -0,0 +1,191 @@
+/*
+ * 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 { createHash } from 'node:crypto';
+const MAX_RUNS = 20;
+const INDEX_FILE = '.runs.json';
+const DEFAULT_ROOT_NAME = '.provardx';
+const VALIDATION_SUBDIR = 'validation';
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Stable 8-char hash of a string for use in run IDs. */
+function shortHash(input) {
+    return createHash('sha1').update(input).digest('hex').slice(0, 8);
+}
+/** Build a unique key for a violation so additions/resolutions can be detected. */
+function violationKey(v) {
+    const rule_id = String(v['rule_id'] ?? '');
+    const applies_to = Array.isArray(v['applies_to'])
+        ? v['applies_to'].join(',')
+        : String(v['applies_to'] ?? '');
+    const message = String(v['message'] ?? '');
+    return `${rule_id}||${applies_to}||${message}`;
+}
+function loadIndex(storageDir) {
+    const indexPath = path.join(storageDir, INDEX_FILE);
+    try {
+        return JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+    }
+    catch {
+        return { runs: [] };
+    }
+}
+function saveIndex(storageDir, index) {
+    const indexPath = path.join(storageDir, INDEX_FILE);
+    fs.writeFileSync(indexPath, JSON.stringify(index, null, 2), 'utf-8');
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * 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 function computeContextHash(toolTag, context) {
+    return shortHash(`${toolTag}|${context}`);
+}
+/**
+ * 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 function resolveValidationDir(subdir) {
+    const override = process.env['PROVAR_MCP_VALIDATION_DIR']?.trim();
+    if (override)
+        return path.join(override, subdir);
+    return path.join(os.homedir(), DEFAULT_ROOT_NAME, VALIDATION_SUBDIR, subdir);
+}
+/** Generate a run ID from a context string (e.g. project path or suite name). */
+export function generateRunId(context) {
+    const rand = Math.random().toString(36).slice(2, 6);
+    return `${Date.now()}-${shortHash(context)}-${rand}`;
+}
+/**
+ * Check whether any prior runs exist in the given storage directory.
+ * Used by calcNextAction to determine the first-run heuristic.
+ */
+export function hasAnyRun(storageDir) {
+    const index = loadIndex(storageDir);
+    return index.runs.length > 0;
+}
+/**
+ * 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 function saveRun(storageDir, runId, violations, contextHash) {
+    fs.mkdirSync(storageDir, { recursive: true });
+    const filename = `${runId}.json`;
+    fs.writeFileSync(path.join(storageDir, filename), JSON.stringify(violations), 'utf-8');
+    const index = loadIndex(storageDir);
+    index.runs.push({
+        run_id: runId,
+        timestamp: Date.now(),
+        filename,
+        ...(contextHash ? { context_hash: contextHash } : {}),
+    });
+    // Evict oldest entries when over the cap
+    while (index.runs.length > MAX_RUNS) {
+        const evicted = index.runs.shift();
+        if (evicted) {
+            try {
+                fs.unlinkSync(path.join(storageDir, evicted.filename));
+            }
+            catch {
+                /* best-effort eviction */
+            }
+        }
+    }
+    saveIndex(storageDir, index);
+    return runId;
+}
+/**
+ * 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 function loadBaselineViolations(storageDir, baselineRunId, expectedContextHash) {
+    const index = loadIndex(storageDir);
+    const record = index.runs.find((r) => r.run_id === baselineRunId);
+    if (!record)
+        return null;
+    if (expectedContextHash !== undefined && record.context_hash !== expectedContextHash) {
+        return null;
+    }
+    // Use the filename from the index, not the run_id
+    try {
+        const content = fs.readFileSync(path.join(storageDir, record.filename), 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return 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 function computeDiff(baseline, current) {
+    // Build multiset counts keyed by violation identity
+    const baselineCounts = new Map();
+    for (const v of baseline) {
+        const key = violationKey(v);
+        const entry = baselineCounts.get(key);
+        if (entry) {
+            entry.count++;
+        }
+        else {
+            baselineCounts.set(key, { count: 1, sample: v });
+        }
+    }
+    const currentCounts = new Map();
+    for (const v of current) {
+        const key = violationKey(v);
+        const entry = currentCounts.get(key);
+        if (entry) {
+            entry.count++;
+        }
+        else {
+            currentCounts.set(key, { count: 1, sample: v });
+        }
+    }
+    const added = [];
+    const resolved = [];
+    let unchanged_count = 0;
+    // Tally additions: occurrences in current that exceed baseline count
+    for (const [key, { count: curr, sample }] of currentCounts) {
+        const base = baselineCounts.get(key)?.count ?? 0;
+        unchanged_count += Math.min(base, curr);
+        const addedCount = curr - base;
+        for (let i = 0; i < addedCount; i++)
+            added.push(sample);
+    }
+    // Tally resolutions: occurrences in baseline that exceed current count
+    for (const [key, { count: base, sample }] of baselineCounts) {
+        const curr = currentCounts.get(key)?.count ?? 0;
+        const resolvedCount = base - Math.min(base, curr);
+        for (let i = 0; i < resolvedCount; i++)
+            resolved.push(sample);
+    }
+    return { added, resolved, unchanged_count };
+}
+//# sourceMappingURL=validationDiff.js.map

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

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

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

@@ -0,0 +1,15 @@
+export type NextAction = 'stop' | 'fix_and_revalidate' | 'inspect_failures';
+/** Fraction of passing tests expressed as 0–100 integer. Returns 0 when total is 0. */
+export declare function calcCompletenessScore(passing: number, total: number): number;
+/**
+ * Recommend what the agent should do next based on the completeness score,
+ * remaining violation count, and whether any prior runs exist on disk.
+ *
+ * - `stop`              → score is 100 AND no violations remain
+ * - `inspect_failures`  → first run (no baseline on disk) — review what's failing before trying to fix
+ * - `fix_and_revalidate`→ subsequent run — agent knows the failure set, should fix and re-run
+ *
+ * The secondary `remainingViolationCount` check prevents `stop` from firing when all
+ * tests pass but quality or best-practice violations are still present.
+ */
+export declare function calcNextAction(score: number, hasBaseline: boolean, remainingViolationCount?: number): NextAction;

package/lib/mcp/utils/validationScore.js

@@ -0,0 +1,31 @@
+/*
+ * 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
+ */
+/** Fraction of passing tests expressed as 0–100 integer. Returns 0 when total is 0. */
+export function calcCompletenessScore(passing, total) {
+    if (total === 0)
+        return 0;
+    return Math.round((passing / total) * 100);
+}
+/**
+ * Recommend what the agent should do next based on the completeness score,
+ * remaining violation count, and whether any prior runs exist on disk.
+ *
+ * - `stop`              → score is 100 AND no violations remain
+ * - `inspect_failures`  → first run (no baseline on disk) — review what's failing before trying to fix
+ * - `fix_and_revalidate`→ subsequent run — agent knows the failure set, should fix and re-run
+ *
+ * The secondary `remainingViolationCount` check prevents `stop` from firing when all
+ * tests pass but quality or best-practice violations are still present.
+ */
+export function calcNextAction(score, hasBaseline, remainingViolationCount = 0) {
+    if (score === 100 && remainingViolationCount === 0)
+        return 'stop';
+    if (!hasBaseline)
+        return 'inspect_failures';
+    return 'fix_and_revalidate';
+}
+//# sourceMappingURL=validationScore.js.map