@provartesting/provardx-cli 1.5.0 → 1.5.1

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"validationScore.js","sourceRoot":"","sources":["../../../src/mcp/utils/validationScore.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,KAAa;IAClE,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,WAAoB,EAAE,uBAAuB,GAAG,CAAC;IAC7F,IAAI,KAAK,KAAK,GAAG,IAAI,uBAAuB,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IAClE,IAAI,CAAC,WAAW;QAAE,OAAO,kBAAkB,CAAC;IAC5C,OAAO,oBAAoB,CAAC;AAC9B,CAAC"}

package/oclif.manifest.json

@@ -2036,5 +2036,5 @@
       ]
     }
   },
-  "version": "1.5.0"
+  "version": "1.5.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@provartesting/provardx-cli",
   "description": "A plugin for the Salesforce CLI to orchestrate testing activities and report quality metrics to Provar Quality Hub",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "mcpName": "io.github.ProvarTesting/provar",
   "license": "BSD-3-Clause",
   "plugins": [
@@ -158,6 +158,7 @@
         "src/mcp/rules/*.json",
         "docs/NITROX_COMPONENT_CATALOG.md",
         "docs/NITROX_CATALOG_SOURCE.json",
+        "docs/PROVAR_TOOL_GUIDE.md",
         "**/tsconfig.json",
         "messages/**"
       ],
@@ -180,6 +181,9 @@
     },
     "lint": {
       "command": "eslint src test --color --cache --cache-location .eslintcache",
+      "dependencies": [
+        "lint:script-names"
+      ],
       "files": [
         "src/**/*.ts",
         "test/**/*.ts",
@@ -189,6 +193,14 @@
       ],
       "output": []
     },
+    "lint:script-names": {
+      "command": "node scripts/lint-script-names.cjs",
+      "files": [
+        "scripts/lint-script-names.cjs",
+        "scripts/**/*"
+      ],
+      "output": []
+    },
     "test:compile": {
       "command": "tsc -p \"./test\" --pretty",
       "files": [