@saiteja1123/mcp-server 1.1.4 → 1.1.6

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

@@ -0,0 +1,548 @@
+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 { validateRalphComparisonArtifact } from './ralph-compare.js';
+
+export const RALPH_FAILURE_STATE_SCHEMA_VERSION = 'ralph_failure_state.v1';
+export const RALPH_FAILURE_STATE_STEPPER_ID = 'ralph.track';
+export const RALPH_FAILURE_STATE_STEPPER_VERSION = '1.0.0';
+export const RALPH_ESCALATION_STATUSES = Object.freeze([
+  'normal',
+  'escalated',
+  'manualReview',
+  'acceptedRisk',
+]);
+
+export const DEFAULT_RALPH_LOOP_RETRY = Object.freeze({
+  maxAttempts: 3,
+  escalateAt: 2,
+  trackSeverities: ['critical', 'high'],
+});
+
+const FAILURE_STATE_FILE = 'ralph-failure-state.json';
+const SHA256 = /^[a-f0-9]{64}$/i;
+const UUIDISH = /^[a-zA-Z0-9_.:-]+$/;
+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 RISKY_SEVERITY.has(severity) || severity === 'medium' || severity === 'low' ? severity : 'medium';
+}
+
+function normalizeRetryConfig(input = {}) {
+  const trackSeverities = asArray(input.trackSeverities, 'ralphLoop.retry.trackSeverities')
+    .map((item) => normalizeSeverity(item))
+    .filter((item, index, all) => all.indexOf(item) === index);
+  const maxAttempts = Number.isInteger(Number(input.maxAttempts)) ? Number(input.maxAttempts) : DEFAULT_RALPH_LOOP_RETRY.maxAttempts;
+  const escalateAt = Number.isInteger(Number(input.escalateAt)) ? Number(input.escalateAt) : DEFAULT_RALPH_LOOP_RETRY.escalateAt;
+  if (maxAttempts < 1) throw new Error('ralphLoop.retry.maxAttempts must be at least 1');
+  if (escalateAt < 1) throw new Error('ralphLoop.retry.escalateAt must be at least 1');
+  if (escalateAt > maxAttempts) throw new Error('ralphLoop.retry.escalateAt must not exceed maxAttempts');
+  return {
+    maxAttempts,
+    escalateAt,
+    trackSeverities: trackSeverities.length > 0 ? trackSeverities : [...DEFAULT_RALPH_LOOP_RETRY.trackSeverities],
+  };
+}
+
+function taskIdByFindingId(agentFixTasks = {}) {
+  const map = new Map();
+  for (const task of asArray(agentFixTasks.tasks, 'agentFixTasks.tasks')) {
+    for (const findingId of asArray(task.findingIds, 'agentFixTask.findingIds')) {
+      if (!map.has(findingId)) map.set(findingId, task.taskId || null);
+    }
+  }
+  return map;
+}
+
+function previousFailureMap(previousFailureState = {}) {
+  return new Map(
+    asArray(previousFailureState.failures, 'ralphFailureState.failures')
+      .map((record) => [record.findingKey, record]),
+  );
+}
+
+function shouldTrackSeverity(severity, retryConfig) {
+  return retryConfig.trackSeverities.includes(normalizeSeverity(severity));
+}
+
+function failureReasonFor(status, severity) {
+  return `${status}_${normalizeSeverity(severity)}`;
+}
+
+function nextActionFor({ escalationStatus, attemptCount, retryConfig, comparisonStatus }) {
+  if (escalationStatus === 'manualReview') {
+    return 'Manual review required before treating this finding as resolved or accepted.';
+  }
+  if (escalationStatus === 'acceptedRisk') {
+    return 'Accepted-risk record is preserved; do not claim the finding is fixed without explicit approval evidence.';
+  }
+  if (escalationStatus === 'escalated' || attemptCount >= retryConfig.maxAttempts) {
+    return 'Repeated failure threshold reached; require human review or accepted-risk approval before release reliance.';
+  }
+  if (comparisonStatus === 'new') {
+    return 'New high-risk finding detected; apply the smallest safe local fix and rerun Vibesecur verification.';
+  }
+  return 'Apply a narrower local fix, rerun relevant tests, and compare again through MCP Deep Scan.';
+}
+
+function escalationStatusFor({ comparisonStatus, attemptCount, retryConfig, lowConfidence }) {
+  if (comparisonStatus === 'manualReview' || lowConfidence) return 'manualReview';
+  if (comparisonStatus === 'acceptedRisk') return 'acceptedRisk';
+  if (attemptCount >= retryConfig.maxAttempts) return 'escalated';
+  if (attemptCount >= retryConfig.escalateAt) return 'escalated';
+  return 'normal';
+}
+
+export function buildRalphFailureStateArtifact({
+  comparisonArtifact,
+  previousFailureState = {},
+  agentFixTasks = {},
+  retryConfig = DEFAULT_RALPH_LOOP_RETRY,
+  generatedAt = nowIso(),
+  sourceRefs = {},
+} = {}) {
+  const comparison = validateRalphComparisonArtifact(comparisonArtifact);
+  const previous = cloneSourceSafe(previousFailureState || {}, 'ralphFailureState.previous');
+  const tasks = cloneSourceSafe(agentFixTasks || {}, 'ralphFailureState.agentFixTasks');
+  const retry = normalizeRetryConfig(retryConfig);
+  const priorByKey = previousFailureMap(previous);
+  const taskIds = taskIdByFindingId(tasks);
+  const failures = [];
+  let resolvedCount = 0;
+
+  for (const row of comparison.comparisons) {
+    const severity = normalizeSeverity(row.current?.severity || row.previous?.severity || 'medium');
+    const findingId = row.current?.id || row.previous?.id || null;
+    const prior = priorByKey.get(row.findingKey) || null;
+
+    if (row.status === 'resolved' || row.status === 'improved') {
+      if (prior) resolvedCount += 1;
+      continue;
+    }
+
+    if (row.status === 'manualReview') {
+      failures.push({
+        findingKey: row.findingKey,
+        findingId,
+        taskId: findingId ? (taskIds.get(findingId) || prior?.taskId || null) : (prior?.taskId || null),
+        severity,
+        attemptCount: prior?.attemptCount || 0,
+        lastFailureReason: row.manualReviewReason || 'manual_review_required',
+        lastSeenAt: generatedAt,
+        escalationStatus: 'manualReview',
+        comparisonStatus: row.status,
+        nextAction: nextActionFor({
+          escalationStatus: 'manualReview',
+          attemptCount: prior?.attemptCount || 0,
+          retryConfig: retry,
+          comparisonStatus: row.status,
+        }),
+      });
+      continue;
+    }
+
+    if (row.status === 'acceptedRisk') {
+      failures.push({
+        findingKey: row.findingKey,
+        findingId,
+        taskId: findingId ? (taskIds.get(findingId) || prior?.taskId || null) : (prior?.taskId || null),
+        severity,
+        attemptCount: prior?.attemptCount || 0,
+        lastFailureReason: 'accepted_risk_recorded',
+        lastSeenAt: generatedAt,
+        escalationStatus: 'acceptedRisk',
+        comparisonStatus: row.status,
+        acceptedRiskRef: row.acceptedRiskRef || null,
+        nextAction: nextActionFor({
+          escalationStatus: 'acceptedRisk',
+          attemptCount: prior?.attemptCount || 0,
+          retryConfig: retry,
+          comparisonStatus: row.status,
+        }),
+      });
+      continue;
+    }
+
+    const increments = row.status === 'unchanged' || row.status === 'worsened';
+    const tracked = shouldTrackSeverity(severity, retry);
+    if (!tracked && row.status !== 'new') continue;
+
+    let attemptCount = prior?.attemptCount || 0;
+    if (row.status === 'new' && tracked) {
+      attemptCount = 1;
+    } else if (increments && tracked) {
+      attemptCount += 1;
+    } else if (row.status === 'new') {
+      continue;
+    } else if (!increments) {
+      continue;
+    }
+
+    const escalationStatus = escalationStatusFor({
+      comparisonStatus: row.status,
+      attemptCount,
+      retryConfig: retry,
+      lowConfidence: row.matchConfidence === 'low',
+    });
+    failures.push({
+      findingKey: row.findingKey,
+      findingId,
+      taskId: findingId ? (taskIds.get(findingId) || prior?.taskId || null) : (prior?.taskId || null),
+      severity,
+      attemptCount,
+      lastFailureReason: failureReasonFor(row.status, severity),
+      lastSeenAt: generatedAt,
+      escalationStatus,
+      comparisonStatus: row.status,
+      nextAction: nextActionFor({
+        escalationStatus,
+        attemptCount,
+        retryConfig: retry,
+        comparisonStatus: row.status,
+      }),
+    });
+  }
+
+  failures.sort((a, b) => b.attemptCount - a.attemptCount || a.findingKey.localeCompare(b.findingKey));
+
+  const artifact = {
+    schemaVersion: RALPH_FAILURE_STATE_SCHEMA_VERSION,
+    generatedAt: requireIsoDate(generatedAt, 'ralphFailureState.generatedAt'),
+    root: cloneSourceSafe(comparison.root || {}, 'ralphFailureState.root'),
+    sources: {
+      ralphComparison: sourceRefs.ralphComparison || 'ralph_comparison',
+      previousFailureState: sourceRefs.previousFailureState || null,
+      agentFixTasks: sourceRefs.agentFixTasks || null,
+    },
+    retryConfig: retry,
+    summary: {
+      activeFailureCount: failures.length,
+      repeatedFailureCount: failures.filter((item) => item.attemptCount > 1).length,
+      escalatedCount: failures.filter((item) => item.escalationStatus === 'escalated').length,
+      manualReviewCount: failures.filter((item) => item.escalationStatus === 'manualReview').length,
+      acceptedRiskCount: failures.filter((item) => item.escalationStatus === 'acceptedRisk').length,
+      resolvedCount,
+      topRepeatedFailures: failures
+        .filter((item) => item.attemptCount > 1)
+        .slice(0, 5)
+        .map((item) => ({
+          findingKey: item.findingKey,
+          findingId: item.findingId,
+          attemptCount: item.attemptCount,
+          severity: item.severity,
+          escalationStatus: item.escalationStatus,
+        })),
+    },
+    reportHandoff: {
+      repeatedFailureRiskVisible: failures.some((item) => item.attemptCount > 1 || item.escalationStatus === 'escalated'),
+      requiresHumanReview: failures.some((item) =>
+        item.escalationStatus === 'manualReview' || item.attemptCount >= retry.maxAttempts),
+      topRepeatedFailures: failures
+        .filter((item) => item.attemptCount > 1)
+        .slice(0, 5),
+      note: 'Repeated failure tracking uses comparison metadata only; no raw source or remediation diffs are stored.',
+    },
+    failures,
+    privacy: {
+      rawSourceStored: false,
+      secretValuesCaptured: false,
+      remediationDiffsStored: false,
+      artifactStorage: 'local_metadata_and_hash_refs',
+    },
+  };
+
+  return validateRalphFailureStateArtifact(artifact);
+}
+
+function validateFailureRecord(input = {}) {
+  assertSourceSafePayload(input, 'ralphFailureState.record');
+  const escalationStatus = requireString(input.escalationStatus, 'ralphFailureState.escalationStatus', { max: 40 });
+  if (!RALPH_ESCALATION_STATUSES.includes(escalationStatus)) {
+    throw new Error(`ralphFailureState.escalationStatus must be one of ${RALPH_ESCALATION_STATUSES.join(', ')}`);
+  }
+  const record = {
+    findingKey: requireString(input.findingKey, 'ralphFailureState.findingKey', { max: 64, pattern: SHA256 }),
+    findingId: optionalString(input.findingId, 'ralphFailureState.findingId', { max: 120, pattern: UUIDISH }),
+    taskId: optionalString(input.taskId, 'ralphFailureState.taskId', { max: 120, pattern: UUIDISH }),
+    severity: normalizeSeverity(input.severity),
+    attemptCount: Number.isInteger(input.attemptCount) ? input.attemptCount : 0,
+    lastFailureReason: requireString(input.lastFailureReason, 'ralphFailureState.lastFailureReason', { max: 500 }),
+    lastSeenAt: requireIsoDate(input.lastSeenAt, 'ralphFailureState.lastSeenAt'),
+    escalationStatus,
+    comparisonStatus: requireString(input.comparisonStatus, 'ralphFailureState.comparisonStatus', { max: 40 }),
+    acceptedRiskRef: optionalString(input.acceptedRiskRef, 'ralphFailureState.acceptedRiskRef', { max: 160, pattern: UUIDISH }),
+    nextAction: requireString(input.nextAction, 'ralphFailureState.nextAction', { max: 700 }),
+  };
+  if (record.attemptCount < 0) throw new Error('ralphFailureState.attemptCount must be zero or greater');
+  if (record.escalationStatus === 'acceptedRisk' && !record.acceptedRiskRef) {
+    throw new Error('acceptedRisk failure records require acceptedRiskRef');
+  }
+  assertSourceSafePayload(record, 'ralphFailureState.record');
+  return record;
+}
+
+export function validateRalphFailureStateArtifact(input = {}) {
+  assertSourceSafePayload(input, 'ralphFailureStateArtifact');
+  const artifact = {
+    schemaVersion: requireString(input.schemaVersion, 'ralphFailureState.schemaVersion', { max: 80, pattern: UUIDISH }),
+    generatedAt: requireIsoDate(input.generatedAt, 'ralphFailureState.generatedAt'),
+    root: cloneSourceSafe(input.root || {}, 'ralphFailureState.root'),
+    sources: cloneSourceSafe(input.sources || {}, 'ralphFailureState.sources'),
+    retryConfig: normalizeRetryConfig(input.retryConfig || DEFAULT_RALPH_LOOP_RETRY),
+    summary: cloneSourceSafe(input.summary || {}, 'ralphFailureState.summary'),
+    reportHandoff: cloneSourceSafe(input.reportHandoff || {}, 'ralphFailureState.reportHandoff'),
+    failures: asArray(input.failures, 'ralphFailureState.failures').map(validateFailureRecord),
+    privacy: cloneSourceSafe(input.privacy || {}, 'ralphFailureState.privacy'),
+  };
+  if (artifact.schemaVersion !== RALPH_FAILURE_STATE_SCHEMA_VERSION) {
+    throw new Error(`ralphFailureState.schemaVersion must be ${RALPH_FAILURE_STATE_SCHEMA_VERSION}`);
+  }
+  return artifact;
+}
+
+export function hashRalphFailureStateArtifact(artifact) {
+  assertSourceSafePayload(artifact, 'ralphFailureStateArtifact');
+  return sha256(stableStringify(validateRalphFailureStateArtifact(artifact)));
+}
+
+async function readLocalArtifact({ rootPath, ref, type }) {
+  if (!ref || ref.type !== type || ref.storage !== 'local' || !ref.uri) {
+    throw new Error(`Ralph failure tracking 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 failure tracking artifact ref for ${type} escapes the bound root`);
+  }
+  const raw = await fs.readFile(target, 'utf8');
+  if (!ref.hash) {
+    throw new Error(`Ralph failure tracking requires ${type} artifact refs to include a hash`);
+  }
+  const actualHash = sha256(raw);
+  if (actualHash.toLowerCase() !== String(ref.hash).toLowerCase()) {
+    throw new Error(`Ralph failure tracking ${type} artifact hash mismatch: expected ${ref.hash}, got ${actualHash}`);
+  }
+  const parsed = JSON.parse(raw);
+  assertSourceSafePayload(parsed, `ralphFailureState.${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, type, fallbackId) {
+  if (!input || typeof input !== 'object') return null;
+  if (!input.uri || !input.hash) return null;
+  return {
+    id: input.id || fallbackId,
+    type,
+    storage: input.storage || 'local',
+    uri: input.uri,
+    hash: input.hash,
+  };
+}
+
+export async function writeRalphFailureStateArtifact({ rootPath, runId, artifact }) {
+  const safeArtifact = validateRalphFailureStateArtifact(artifact);
+  const safeRunId = validateRunIdSegment(runId, 'runId');
+  const relativeUri = `.vibesecur/deep-scans/${safeRunId}/${FAILURE_STATE_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 ralphFailureTrackStepper() {
+  return {
+    id: RALPH_FAILURE_STATE_STEPPER_ID,
+    version: RALPH_FAILURE_STATE_STEPPER_VERSION,
+    title: 'Ralph Failure Tracking Stepper',
+    category: 'ralph_loop',
+    requiredInputs: ['ralph_comparison'],
+    producedArtifacts: ['ralph_failure_state'],
+    defaultTimeoutMs: 30000,
+    async run({ runId, config = {}, state = {}, tools = {} }) {
+      const rootPath = tools.rootPath || config.rootPath || '.';
+      const startedAt = nowIso();
+      const comparisonRef = findArtifactRef(state, 'ralph_comparison', ['ralph.compare']);
+      if (!comparisonRef) {
+        return {
+          stepperId: RALPH_FAILURE_STATE_STEPPER_ID,
+          version: RALPH_FAILURE_STATE_STEPPER_VERSION,
+          status: 'skipped',
+          startedAt,
+          finishedAt: nowIso(),
+          evidence: [],
+          findings: [],
+          artifacts: [],
+          receipts: [],
+          summary: 'Ralph failure tracking skipped because no ralph_comparison artifact was available.',
+          skippedReason: 'Missing ralph_comparison artifact from ralph.compare.',
+          nextActions: ['Run ralph.compare with a baseline deterministic scan before tracking repeated failures.'],
+        };
+      }
+
+      const compareStep = state.stepResults?.['ralph.compare'];
+      if (compareStep?.status === 'skipped') {
+        return {
+          stepperId: RALPH_FAILURE_STATE_STEPPER_ID,
+          version: RALPH_FAILURE_STATE_STEPPER_VERSION,
+          status: 'skipped',
+          startedAt,
+          finishedAt: nowIso(),
+          evidence: [],
+          findings: [],
+          artifacts: [],
+          receipts: [],
+          summary: 'Ralph failure tracking skipped because comparison was skipped.',
+          skippedReason: compareStep.skippedReason || 'ralph.compare did not produce comparison evidence.',
+          nextActions: ['Provide previousDeterministicScanRef on rerun to enable comparison and failure tracking.'],
+        };
+      }
+
+      const tasksRef = findArtifactRef(state, 'agent_fix_tasks', ['ralph.tasks']);
+      const previousRef = normalizeRef(config.previousFailureStateRef, 'ralph_failure_state', 'artifact-previous-failure-state');
+      const comparisonArtifact = await readLocalArtifact({
+        rootPath,
+        ref: comparisonRef,
+        type: 'ralph_comparison',
+      });
+      const previousFailureState = previousRef
+        ? await readLocalArtifact({
+          rootPath,
+          ref: previousRef,
+          type: 'ralph_failure_state',
+        })
+        : {};
+      const agentFixTasks = tasksRef
+        ? await readLocalArtifact({
+          rootPath,
+          ref: tasksRef,
+          type: 'agent_fix_tasks',
+        })
+        : { tasks: [] };
+
+      const retryConfig = normalizeRetryConfig(
+        config.retry
+        || state.graphProfile?.ralphLoop?.retry
+        || DEFAULT_RALPH_LOOP_RETRY,
+      );
+
+      const artifact = buildRalphFailureStateArtifact({
+        comparisonArtifact,
+        previousFailureState,
+        agentFixTasks,
+        retryConfig,
+        generatedAt: config.generatedAt || startedAt,
+        sourceRefs: {
+          ralphComparison: comparisonRef.id,
+          previousFailureState: previousRef?.id || null,
+          agentFixTasks: tasksRef?.id || null,
+        },
+      });
+      const contentHash = hashRalphFailureStateArtifact(artifact);
+      const written = await writeRalphFailureStateArtifact({ rootPath, runId, artifact });
+      const safeRunId = validateRunIdSegment(runId, 'runId');
+      const ref = createArtifactRef({
+        id: `artifact-${safeRunId}-ralph-failure-state`,
+        type: 'ralph_failure_state',
+        storage: 'local',
+        uri: written.uri,
+        hash: written.hash,
+        preview: 'Ralph repeated failure state with attempt counts and escalation metadata only.',
+        metadata: {
+          schemaVersion: RALPH_FAILURE_STATE_SCHEMA_VERSION,
+          contentHash,
+          generatedBy: RALPH_FAILURE_STATE_STEPPER_ID,
+          activeFailureCount: artifact.summary.activeFailureCount,
+          repeatedFailureCount: artifact.summary.repeatedFailureCount,
+          escalatedCount: artifact.summary.escalatedCount,
+        },
+      });
+
+      return {
+        stepperId: RALPH_FAILURE_STATE_STEPPER_ID,
+        version: RALPH_FAILURE_STATE_STEPPER_VERSION,
+        status: 'passed',
+        startedAt,
+        finishedAt: nowIso(),
+        evidence: [{
+          type: 'hash',
+          label: 'Ralph failure state artifact hash',
+          hash: ref.hash,
+          preview: 'Repeated failure tracking artifact written locally.',
+          summary: `${artifact.summary.repeatedFailureCount} repeated failure(s), ${artifact.summary.escalatedCount} escalated.`,
+          metadata: {
+            artifactId: ref.id,
+            contentHash,
+            ralphComparisonArtifactId: comparisonRef.id,
+          },
+        }],
+        findings: [],
+        artifacts: [ref],
+        receipts: [],
+        summary: `Ralph failure tracking generated: ${artifact.summary.activeFailureCount} active failure(s), ${artifact.summary.repeatedFailureCount} repeated, ${artifact.summary.escalatedCount} escalated.`,
+        nextActions: ['Use ralph-failure-state report handoff fields for release governance and human review decisions.'],
+      };
+    },
+  };
+}