@saiteja1123/mcp-server 1.1.4 → 1.1.6

package/src/deep-scan/ralph-compare.js

@@ -0,0 +1,498 @@
+import crypto from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import { createArtifactRef, validateRunIdSegment } from './contracts.js';
+import { assertSourceSafePayload, cloneSourceSafe } from './sourceSafe.js';
+import { indexAcceptedRiskForComparison, readAcceptedRiskRegister } from './ralph-accept.js';
+
+export const RALPH_COMPARISON_SCHEMA_VERSION = 'ralph_comparison.v1';
+export const RALPH_COMPARISON_STEPPER_ID = 'ralph.compare';
+export const RALPH_COMPARISON_STEPPER_VERSION = '1.0.0';
+export const RALPH_COMPARISON_STATUSES = Object.freeze([
+  'resolved',
+  'unchanged',
+  'new',
+  'worsened',
+  'improved',
+  'acceptedRisk',
+  'manualReview',
+]);
+
+const COMPARISON_FILE = 'ralph-comparison.json';
+const SHA256 = /^[a-f0-9]{64}$/i;
+const UUIDISH = /^[a-zA-Z0-9_.:-]+$/;
+const SEVERITY_ORDER = Object.freeze({ critical: 4, high: 3, medium: 2, low: 1 });
+const RISKY_SEVERITY = new Set(['critical', 'high']);
+const nowIso = () => new Date().toISOString();
+
+function stableSort(value) {
+  if (Array.isArray(value)) return value.map(stableSort);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value)
+    .sort()
+    .reduce((acc, key) => {
+      acc[key] = stableSort(value[key]);
+      return acc;
+    }, {});
+}
+
+function stableStringify(value) {
+  return JSON.stringify(stableSort(value));
+}
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function requireString(value, name, { max = 500, pattern = null } = {}) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} must be a non-empty string`);
+  if (value.length > max) throw new Error(`${name} must be ${max} characters or fewer`);
+  if (pattern && !pattern.test(value)) throw new Error(`${name} has an invalid format`);
+  return value;
+}
+
+function optionalString(value, name, options) {
+  if (value === undefined || value === null) return null;
+  return requireString(value, name, options);
+}
+
+function requireIsoDate(value, name) {
+  requireString(value, name, { max: 40 });
+  if (Number.isNaN(Date.parse(value))) throw new Error(`${name} must be an ISO timestamp`);
+  return value;
+}
+
+function asArray(value, name) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${name} must be an array`);
+  return value;
+}
+
+function normalizeSeverity(value) {
+  const severity = String(value || 'medium').toLowerCase();
+  return Object.prototype.hasOwnProperty.call(SEVERITY_ORDER, severity) ? severity : 'medium';
+}
+
+function severityScore(value) {
+  return SEVERITY_ORDER[normalizeSeverity(value)];
+}
+
+function isSha256(value) {
+  return typeof value === 'string' && SHA256.test(value);
+}
+
+function buildFindingIdentity(finding = {}) {
+  if (isSha256(finding.fingerprint)) return finding.fingerprint;
+  if (finding.id) return sha256(`id:${String(finding.id)}`);
+  const source = finding.source || {};
+  const seed = stableStringify({
+    ruleId: finding.ruleId || 'unknown_rule',
+    filePath: source.filePath || 'unknown_file',
+    lineNumber: Number.isInteger(source.lineNumber) ? source.lineNumber : null,
+    endLineNumber: Number.isInteger(source.endLineNumber) ? source.endLineNumber : null,
+    snippetPreview: finding.snippetPreview || null,
+  });
+  return sha256(seed);
+}
+
+function mapFindings(findings = []) {
+  const mapped = new Map();
+  for (const finding of findings) {
+    const hasFingerprint = isSha256(finding.fingerprint);
+    const hasId = typeof finding.id === 'string' && finding.id.trim().length > 0;
+    const key = buildFindingIdentity(finding);
+    const confidence = hasFingerprint && hasId ? 'high' : (hasFingerprint || hasId ? 'medium' : 'low');
+    const keySource = hasFingerprint ? 'fingerprint' : (hasId ? 'id' : 'synthetic');
+    if (!mapped.has(key)) mapped.set(key, { finding, confidence, keySource });
+  }
+  return mapped;
+}
+
+function acceptedRiskMap(agentFixTasks = {}) {
+  const map = new Map();
+  const tasks = asArray(agentFixTasks.tasks, 'agentFixTasks.tasks');
+  for (const task of tasks) {
+    if (!task || !task.acceptedRiskRef) continue;
+    for (const findingId of asArray(task.findingIds, 'agentFixTask.findingIds')) {
+      if (!map.has(findingId)) map.set(findingId, task.acceptedRiskRef);
+    }
+  }
+  return map;
+}
+
+function findingSnapshot(finding = null) {
+  if (!finding) return null;
+  return {
+    id: optionalString(finding.id, 'finding.id', { max: 120, pattern: UUIDISH }),
+    ruleId: optionalString(finding.ruleId, 'finding.ruleId', { max: 80, pattern: UUIDISH }),
+    severity: normalizeSeverity(finding.severity),
+    category: optionalString(finding.category, 'finding.category', { max: 80, pattern: UUIDISH }),
+    filePath: optionalString(finding.source?.filePath, 'finding.source.filePath', { max: 300 }),
+    lineNumber: Number.isInteger(finding.source?.lineNumber) ? finding.source.lineNumber : null,
+    fingerprint: buildFindingIdentity(finding),
+  };
+}
+
+function summarizeComparison(rows) {
+  const byStatus = RALPH_COMPARISON_STATUSES.reduce((acc, status) => ({ ...acc, [status]: 0 }), {});
+  let unresolvedHighOrCritical = 0;
+  let riskyNewCount = 0;
+  for (const row of rows) {
+    byStatus[row.status] += 1;
+    const severity = row.current?.severity || row.previous?.severity || 'low';
+    const unresolved = ['new', 'worsened', 'unchanged', 'acceptedRisk', 'manualReview'].includes(row.status);
+    if (unresolved && RISKY_SEVERITY.has(severity)) unresolvedHighOrCritical += 1;
+    if (row.status === 'new' && RISKY_SEVERITY.has(severity)) riskyNewCount += 1;
+  }
+  return {
+    total: rows.length,
+    byStatus,
+    unresolvedHighOrCritical,
+    riskyNewCount,
+    acceptedRiskCount: byStatus.acceptedRisk,
+    manualReviewCount: byStatus.manualReview,
+  };
+}
+
+// Resolve the accepted-risk reference for one finding. A canonical accepted-risk
+// register (VIB-85) is authoritative when it knows the finding: an active record
+// marks it accepted, an expired record reverts it to unresolved and suppresses the
+// legacy AgentFixTask field. Findings the register does not know fall back to the
+// legacy task acceptedRiskRef for backward compatibility.
+function resolveAcceptedRiskRef({ key, currentFinding, registerIndex, taskMap }) {
+  const findingId = currentFinding?.id || null;
+  const known = registerIndex.knownByKey.get(key)
+    || (findingId ? registerIndex.knownById.get(findingId) : null)
+    || null;
+  if (known) {
+    const active = registerIndex.activeByKey.get(key)
+      || (findingId ? registerIndex.activeById.get(findingId) : null)
+      || null;
+    return active ? active.riskId : null;
+  }
+  return findingId ? (taskMap.get(findingId) || null) : null;
+}
+
+export function buildRalphComparisonArtifact({
+  previousDeterministicScan = {},
+  currentDeterministicScan = {},
+  agentFixTasks = {},
+  acceptedRiskRegister = null,
+  generatedAt = nowIso(),
+  sourceRefs = {},
+} = {}) {
+  const previous = cloneSourceSafe(previousDeterministicScan, 'ralphCompare.previousDeterministicScan');
+  const current = cloneSourceSafe(currentDeterministicScan, 'ralphCompare.currentDeterministicScan');
+  const tasks = cloneSourceSafe(agentFixTasks, 'ralphCompare.agentFixTasks');
+  const acceptedRiskByFindingId = acceptedRiskMap(tasks);
+  const registerIndex = indexAcceptedRiskForComparison({
+    register: acceptedRiskRegister || { records: [] },
+    generatedAt,
+  });
+  const previousFindings = mapFindings(previous.findings || []);
+  const currentFindings = mapFindings(current.findings || []);
+  const allKeys = [...new Set([...previousFindings.keys(), ...currentFindings.keys()])].sort();
+
+  const comparisons = allKeys.map((key) => {
+    const previousRecord = previousFindings.get(key) || null;
+    const currentRecord = currentFindings.get(key) || null;
+    const previousFinding = previousRecord?.finding || null;
+    const currentFinding = currentRecord?.finding || null;
+    const previousSnapshot = findingSnapshot(previousFinding);
+    const currentSnapshot = findingSnapshot(currentFinding);
+    const acceptedRiskRef = resolveAcceptedRiskRef({
+      key,
+      currentFinding,
+      registerIndex,
+      taskMap: acceptedRiskByFindingId,
+    });
+    const lowConfidence = previousRecord?.confidence === 'low' || currentRecord?.confidence === 'low';
+    const manualReviewReason = lowConfidence
+      ? 'Low-confidence finding match (synthetic identity fallback) requires manual review before resolve/new claims.'
+      : null;
+
+    let status = 'unchanged';
+    if (acceptedRiskRef) {
+      status = 'acceptedRisk';
+    } else if (lowConfidence) {
+      status = 'manualReview';
+    } else if (previousFinding && !currentFinding) {
+      status = 'resolved';
+    } else if (!previousFinding && currentFinding) {
+      status = 'new';
+    } else {
+      const previousSeverity = severityScore(previousFinding?.severity);
+      const currentSeverity = severityScore(currentFinding?.severity);
+      if (currentSeverity > previousSeverity) status = 'worsened';
+      else if (currentSeverity < previousSeverity) status = 'improved';
+      else status = 'unchanged';
+    }
+
+    return {
+      findingKey: key,
+      status,
+      acceptedRiskRef,
+      manualReviewReason,
+      matchConfidence: lowConfidence ? 'low' : 'high',
+      previous: previousSnapshot,
+      current: currentSnapshot,
+    };
+  });
+
+  const summary = summarizeComparison(comparisons);
+  const artifact = {
+    schemaVersion: RALPH_COMPARISON_SCHEMA_VERSION,
+    generatedAt: requireIsoDate(generatedAt, 'ralphComparison.generatedAt'),
+    root: {
+      name: current.root?.name || previous.root?.name || tasks.root?.name || 'project',
+      pathHash: current.root?.pathHash || previous.root?.pathHash || tasks.root?.pathHash || null,
+    },
+    sources: {
+      previousDeterministicScan: sourceRefs.previousDeterministicScan || 'previous_deterministic_scan',
+      currentDeterministicScan: sourceRefs.currentDeterministicScan || 'current_deterministic_scan',
+      agentFixTasks: sourceRefs.agentFixTasks || null,
+      acceptedRiskRegister: sourceRefs.acceptedRiskRegister || null,
+    },
+    summary,
+    reportHandoff: {
+      unresolvedHighOrCritical: summary.unresolvedHighOrCritical,
+      newHighOrCritical: summary.riskyNewCount,
+      acceptedRiskCount: summary.acceptedRiskCount,
+      manualReviewCount: summary.manualReviewCount,
+      canMarkFixed: summary.byStatus.new === 0
+        && summary.byStatus.worsened === 0
+        && summary.unresolvedHighOrCritical === 0
+        && summary.byStatus.manualReview === 0,
+      note: 'Comparison shows resolved, unchanged, new, worsened, improved, accepted-risk, and low-confidence manual-review records without raw source.',
+    },
+    comparisons,
+    privacy: {
+      rawSourceStored: false,
+      secretValuesCaptured: false,
+      comparisonUsesHashesAndMetadata: true,
+      artifactStorage: 'local_metadata_and_hash_refs',
+    },
+  };
+
+  return validateRalphComparisonArtifact(artifact);
+}
+
+function validateComparisonRow(input = {}) {
+  assertSourceSafePayload(input, 'ralphComparison.row');
+  const status = requireString(input.status, 'ralphComparison.row.status', { max: 40 });
+  if (!RALPH_COMPARISON_STATUSES.includes(status)) {
+    throw new Error(`ralphComparison.row.status must be one of ${RALPH_COMPARISON_STATUSES.join(', ')}`);
+  }
+  const row = {
+    findingKey: requireString(input.findingKey, 'ralphComparison.row.findingKey', { max: 64, pattern: SHA256 }),
+    status,
+    acceptedRiskRef: optionalString(input.acceptedRiskRef, 'ralphComparison.row.acceptedRiskRef', { max: 160, pattern: UUIDISH }),
+    manualReviewReason: optionalString(input.manualReviewReason, 'ralphComparison.row.manualReviewReason', { max: 500 }),
+    matchConfidence: optionalString(input.matchConfidence, 'ralphComparison.row.matchConfidence', { max: 40 }),
+    previous: input.previous ? cloneSourceSafe(input.previous, 'ralphComparison.row.previous') : null,
+    current: input.current ? cloneSourceSafe(input.current, 'ralphComparison.row.current') : null,
+  };
+  if (!row.previous && !row.current) {
+    throw new Error('ralphComparison rows must include previous or current finding snapshot');
+  }
+  if (row.status === 'acceptedRisk' && !row.acceptedRiskRef) {
+    throw new Error('acceptedRisk rows require acceptedRiskRef');
+  }
+  if (row.status === 'manualReview' && !row.manualReviewReason) {
+    throw new Error('manualReview rows require manualReviewReason');
+  }
+  return row;
+}
+
+export function validateRalphComparisonArtifact(input = {}) {
+  assertSourceSafePayload(input, 'ralphComparisonArtifact');
+  const artifact = {
+    schemaVersion: requireString(input.schemaVersion, 'ralphComparison.schemaVersion', { max: 80, pattern: UUIDISH }),
+    generatedAt: requireIsoDate(input.generatedAt, 'ralphComparison.generatedAt'),
+    root: cloneSourceSafe(input.root || {}, 'ralphComparison.root'),
+    sources: cloneSourceSafe(input.sources || {}, 'ralphComparison.sources'),
+    summary: cloneSourceSafe(input.summary || {}, 'ralphComparison.summary'),
+    reportHandoff: cloneSourceSafe(input.reportHandoff || {}, 'ralphComparison.reportHandoff'),
+    comparisons: asArray(input.comparisons, 'ralphComparison.comparisons').map(validateComparisonRow),
+    privacy: cloneSourceSafe(input.privacy || {}, 'ralphComparison.privacy'),
+  };
+  if (artifact.schemaVersion !== RALPH_COMPARISON_SCHEMA_VERSION) {
+    throw new Error(`ralphComparison.schemaVersion must be ${RALPH_COMPARISON_SCHEMA_VERSION}`);
+  }
+  return artifact;
+}
+
+export function hashRalphComparisonArtifact(artifact) {
+  assertSourceSafePayload(artifact, 'ralphComparisonArtifact');
+  return sha256(stableStringify(validateRalphComparisonArtifact(artifact)));
+}
+
+async function readLocalArtifact({ rootPath, ref, type }) {
+  if (!ref || ref.type !== type || ref.storage !== 'local' || !ref.uri) {
+    throw new Error(`Ralph comparison requires a local ${type} artifact reference`);
+  }
+  const resolvedRoot = path.resolve(rootPath);
+  const target = path.resolve(resolvedRoot, ref.uri);
+  const relative = path.relative(resolvedRoot, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Ralph comparison artifact ref for ${type} escapes the bound root`);
+  }
+  const raw = await fs.readFile(target, 'utf8');
+  if (!ref.hash) {
+    throw new Error(`Ralph comparison requires ${type} artifact refs to include a hash`);
+  }
+  const actualHash = sha256(raw);
+  if (actualHash.toLowerCase() !== String(ref.hash).toLowerCase()) {
+    throw new Error(`Ralph comparison ${type} artifact hash mismatch: expected ${ref.hash}, got ${actualHash}`);
+  }
+  const parsed = JSON.parse(raw);
+  assertSourceSafePayload(parsed, `ralphComparison.${type}`);
+  return parsed;
+}
+
+function findArtifactRef(state, type, preferredKeys = []) {
+  const artifacts = state?.artifacts || {};
+  for (const key of preferredKeys) {
+    if (artifacts[key]?.type === type) return artifacts[key];
+  }
+  return Object.values(artifacts).find((ref) => ref?.type === type) || null;
+}
+
+function normalizeRef(input = null) {
+  if (!input || typeof input !== 'object') return null;
+  if (!input.uri || !input.hash) return null;
+  return {
+    id: input.id || 'artifact-baseline-deterministic-scan',
+    type: 'deterministic_scan',
+    storage: input.storage || 'local',
+    uri: input.uri,
+    hash: input.hash,
+  };
+}
+
+export async function writeRalphComparisonArtifact({ rootPath, runId, artifact }) {
+  const safeArtifact = validateRalphComparisonArtifact(artifact);
+  const safeRunId = validateRunIdSegment(runId, 'runId');
+  const relativeUri = `.vibesecur/deep-scans/${safeRunId}/${COMPARISON_FILE}`;
+  const target = path.join(path.resolve(rootPath), relativeUri);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const serialized = `${JSON.stringify(stableSort(safeArtifact), null, 2)}\n`;
+  const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, serialized, 'utf8');
+  await fs.rename(tmp, target);
+  return {
+    uri: relativeUri,
+    hash: sha256(serialized),
+  };
+}
+
+export function ralphComparisonStepper() {
+  return {
+    id: RALPH_COMPARISON_STEPPER_ID,
+    version: RALPH_COMPARISON_STEPPER_VERSION,
+    title: 'Ralph Comparison Stepper',
+    category: 'ralph_loop',
+    requiredInputs: ['deterministic_scan'],
+    producedArtifacts: ['ralph_comparison'],
+    defaultTimeoutMs: 30000,
+    async run({ runId, config = {}, state = {}, tools = {} }) {
+      const rootPath = tools.rootPath || config.rootPath || '.';
+      const startedAt = nowIso();
+      const previousRef = normalizeRef(config.previousDeterministicScanRef);
+      if (!previousRef) {
+        return {
+          stepperId: RALPH_COMPARISON_STEPPER_ID,
+          version: RALPH_COMPARISON_STEPPER_VERSION,
+          status: 'skipped',
+          startedAt,
+          finishedAt: nowIso(),
+          evidence: [],
+          findings: [],
+          artifacts: [],
+          receipts: [],
+          summary: 'Ralph comparison skipped because no previous deterministic scan artifact reference was supplied.',
+          skippedReason: 'Missing previousDeterministicScanRef in step configuration.',
+          nextActions: ['Pass previousDeterministicScanRef { uri, hash } to compare rerun findings.'],
+        };
+      }
+      const currentRef = findArtifactRef(state, 'deterministic_scan', ['rules.scan']);
+      const tasksRef = findArtifactRef(state, 'agent_fix_tasks', ['ralph.tasks']);
+      const previousDeterministicScan = await readLocalArtifact({
+        rootPath,
+        ref: previousRef,
+        type: 'deterministic_scan',
+      });
+      const currentDeterministicScan = await readLocalArtifact({
+        rootPath,
+        ref: currentRef,
+        type: 'deterministic_scan',
+      });
+      const agentFixTasks = tasksRef
+        ? await readLocalArtifact({
+          rootPath,
+          ref: tasksRef,
+          type: 'agent_fix_tasks',
+        })
+        : { tasks: [] };
+      const { register: acceptedRiskRegister, exists: hasAcceptedRiskRegister } = await readAcceptedRiskRegister({ rootPath });
+      const artifact = buildRalphComparisonArtifact({
+        previousDeterministicScan,
+        currentDeterministicScan,
+        agentFixTasks,
+        acceptedRiskRegister,
+        generatedAt: config.generatedAt || startedAt,
+        sourceRefs: {
+          previousDeterministicScan: previousRef.id || 'artifact-previous-deterministic-scan',
+          currentDeterministicScan: currentRef.id,
+          agentFixTasks: tasksRef?.id || null,
+          acceptedRiskRegister: hasAcceptedRiskRegister ? 'accepted_risk_register' : null,
+        },
+      });
+      const contentHash = hashRalphComparisonArtifact(artifact);
+      const written = await writeRalphComparisonArtifact({ rootPath, runId, artifact });
+      const safeRunId = validateRunIdSegment(runId, 'runId');
+      const ref = createArtifactRef({
+        id: `artifact-${safeRunId}-ralph-comparison`,
+        type: 'ralph_comparison',
+        storage: 'local',
+        uri: written.uri,
+        hash: written.hash,
+        preview: 'Ralph comparison with resolved, unchanged, new, worsened, improved, accepted-risk, and manual-review statuses.',
+        metadata: {
+          schemaVersion: RALPH_COMPARISON_SCHEMA_VERSION,
+          contentHash,
+          generatedBy: RALPH_COMPARISON_STEPPER_ID,
+          total: artifact.summary.total,
+          unresolvedHighOrCritical: artifact.summary.unresolvedHighOrCritical,
+          acceptedRiskCount: artifact.summary.acceptedRiskCount,
+        },
+      });
+
+      return {
+        stepperId: RALPH_COMPARISON_STEPPER_ID,
+        version: RALPH_COMPARISON_STEPPER_VERSION,
+        status: 'passed',
+        startedAt,
+        finishedAt: nowIso(),
+        evidence: [{
+          type: 'hash',
+          label: 'Ralph comparison artifact hash',
+          hash: ref.hash,
+          preview: 'Rerun comparison artifact written locally.',
+          summary: `${artifact.summary.byStatus.resolved} resolved, ${artifact.summary.byStatus.new} new, ${artifact.summary.byStatus.worsened} worsened, ${artifact.summary.byStatus.manualReview} manual-review.`,
+          metadata: {
+            artifactId: ref.id,
+            contentHash,
+            previousDeterministicScanArtifactId: previousRef.id || null,
+            currentDeterministicScanArtifactId: currentRef.id,
+          },
+        }],
+        findings: [],
+        artifacts: [ref],
+        receipts: [],
+        summary: `Ralph comparison generated: ${artifact.summary.total} tracked findings, ${artifact.summary.byStatus.resolved} resolved, ${artifact.summary.byStatus.new} new, ${artifact.summary.byStatus.acceptedRisk} accepted-risk, ${artifact.summary.byStatus.manualReview} manual-review.`,
+        nextActions: ['Use ralph-comparison artifact for report/passport handoff and repeat the fix-rerun loop for unresolved risks.'],
+      };
+    },
+  };
+}