@surlymochan/evalid 0.0.0-stage → 0.3.1

package/src/core/atoms/policy/gate.js

@@ -0,0 +1,90 @@
+import { readJsonFile, resolveChangePath, writeJsonFile } from '../../change-artifacts.js';
+import { resolveEffectivePolicy } from '../../policy-overlay.js';
+
+export async function policyGate(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id;
+  if (!changeId) throw new Error('change_id is required for P2.policy.gate');
+
+  const policyResult = resolveEffectivePolicy({
+    projectRoot,
+    changeId,
+    executionMode: input.execution_mode || null,
+    writeArtifact: true,
+  });
+  if (!policyResult.ok) {
+    const packet = {
+      version: 1,
+      ok: false,
+      generated_at: new Date().toISOString(),
+      failed_checks: [{ code: policyResult.error.code, message: policyResult.error.message }],
+      policy_error: policyResult.error,
+    };
+    const outputPath = resolveChangePath(projectRoot, changeId, 'policy_gate.json');
+    writeJsonFile(outputPath, packet);
+    return { ...packet, policy_gate_file: outputPath };
+  }
+
+  const policy = policyResult.policy;
+  const failedChecks = [
+    ...checkCoverage(projectRoot, changeId, policy),
+    ...checkReviewers(projectRoot, changeId, policy),
+    ...checkSmoke(projectRoot, changeId, policy),
+  ];
+  const packet = {
+    version: 1,
+    ok: failedChecks.length === 0,
+    generated_at: new Date().toISOString(),
+    execution_mode: policy.execution_mode || 'personal',
+    failed_checks: failedChecks,
+    advisory: policy.execution_mode !== 'team',
+  };
+  const outputPath = resolveChangePath(projectRoot, changeId, 'policy_gate.json');
+  writeJsonFile(outputPath, packet);
+  return { ...packet, policy_gate_file: outputPath };
+}
+
+function checkCoverage(projectRoot, changeId, policy) {
+  const threshold = policy?.coding?.min_changed_line_coverage;
+  if (threshold === undefined) return [];
+  const quality = readJsonFile(resolveChangePath(projectRoot, changeId, 'tdd/quality-0.json'), {});
+  const actual = Number(
+    quality.changed_line_coverage
+    ?? quality.incremental_line_coverage
+    ?? quality.coverage
+    ?? quality.gate_value,
+  );
+  if (!Number.isFinite(actual)) {
+    return [{ code: 'coverage_evidence_missing', message: 'changed-line coverage evidence is missing', expected: Number(threshold), actual: null }];
+  }
+  return actual >= Number(threshold)
+    ? []
+    : [{ code: 'coverage_below_policy', message: 'changed-line coverage is below team policy', expected: Number(threshold), actual }];
+}
+
+function checkReviewers(projectRoot, changeId, policy) {
+  const threshold = policy?.review?.min_reviewers;
+  if (threshold === undefined) return [];
+  const review = readJsonFile(resolveChangePath(projectRoot, changeId, 'review.json'), {});
+  const reviewers = Array.isArray(review.reviewers)
+    ? review.reviewers
+    : Array.isArray(review.approved_by)
+      ? review.approved_by
+      : [];
+  return reviewers.length >= Number(threshold)
+    ? []
+    : [{ code: 'reviewers_below_policy', message: 'reviewer count is below team policy', expected: Number(threshold), actual: reviewers.length }];
+}
+
+function checkSmoke(projectRoot, changeId, policy) {
+  const threshold = policy?.deploy?.required_smoke_pass_rate;
+  if (threshold === undefined) return [];
+  const smoke = readJsonFile(resolveChangePath(projectRoot, changeId, 'smoke.json'), {});
+  const actual = Number(smoke.pass_rate ?? smoke.required_smoke_pass_rate ?? smoke.smoke_pass_rate);
+  if (!Number.isFinite(actual)) {
+    return [{ code: 'smoke_evidence_missing', message: 'smoke pass-rate evidence is missing', expected: Number(threshold), actual: null }];
+  }
+  return actual >= Number(threshold)
+    ? []
+    : [{ code: 'smoke_pass_rate_below_policy', message: 'smoke pass rate is below team policy', expected: Number(threshold), actual }];
+}

package/src/core/atoms/policy/resolve.js

@@ -0,0 +1,11 @@
+import { resolveEffectivePolicy } from '../../policy-overlay.js';
+
+export async function policyResolve(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id || null;
+  return resolveEffectivePolicy({
+    projectRoot,
+    changeId,
+    executionMode: input.execution_mode || null,
+  });
+}

package/src/core/atoms/storage/sync.js

@@ -0,0 +1,57 @@
+import { copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { resolveChangePath, writeJsonFile } from '../../change-artifacts.js';
+
+export async function storageSync(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const changeId = context.changeId || input.change_id;
+  if (!changeId) throw new Error('change_id is required for storage.sync');
+
+  const provider = input.provider || 'file';
+  const direction = input.direction || 'import';
+  if (!['file', 'mock'].includes(provider)) {
+    return { ok: false, error: `Unsupported storage provider: ${provider}` };
+  }
+  if (!['import', 'export'].includes(direction)) {
+    return { ok: false, error: `Unsupported storage direction: ${direction}` };
+  }
+
+  const source = input.source ? resolve(projectRoot, input.source) : null;
+  const target = resolve(projectRoot, '.xflow', 'storage', normalizeStoragePath(input.target || 'artifact.json'));
+  let copied = false;
+  if (provider === 'file' && direction === 'import') {
+    if (!source || !existsSync(source)) {
+      return { ok: false, error: `storage source not found: ${source || '(missing)'}` };
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(source, target);
+    copied = true;
+  }
+
+  const evidence = {
+    version: 1,
+    provider,
+    direction,
+    source,
+    target,
+    copied,
+    generated_at: new Date().toISOString(),
+  };
+  const outputPath = resolveChangePath(projectRoot, changeId, `storage/${provider}-${direction}.json`);
+  writeJsonFile(outputPath, evidence);
+  return {
+    ok: true,
+    storage_sync_file: outputPath,
+    storage_target: target,
+    evidence,
+  };
+}
+
+function normalizeStoragePath(value) {
+  return String(value || 'artifact.json')
+    .replace(/^\.+/, '')
+    .replace(/\\/g, '/')
+    .replace(/\/+/g, '/')
+    .replace(/^\/+/, '');
+}

package/src/core/atoms/workflow/advance.js

@@ -0,0 +1,25 @@
+import { resolveChangePath } from '../../change-artifacts.js';
+import { advanceWorkflowState } from '../../workflow-state.js';
+
+export async function workflowAdvance(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const workflowName = context.workflow?.name || input.workflow || null;
+  const changeId = context.changeId || input.change_id || null;
+  const phaseOrder = Array.isArray(context.workflow?.phases) ? context.workflow.phases.map((phase) => phase.id) : [];
+  const expectedPhase = input.phase || context.phase?.id || null;
+  const artifactPath = input.artifact_path
+    || (changeId && expectedPhase ? resolveChangePath(projectRoot, changeId, `${expectedPhase}.json`) : null);
+
+  const workflowState = advanceWorkflowState(projectRoot, {
+    expectedPhase,
+    artifactPath,
+    workflowName,
+    changeId,
+    phaseOrder,
+  });
+
+  return {
+    ok: true,
+    workflow_state: workflowState,
+  };
+}

package/src/core/atoms/workflow/guard.js

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+import { resolveChangePath } from '../../change-artifacts.js';
+import { advanceWorkflowState, loadWorkflowState, resolveWorkflowStateFile, saveWorkflowState } from '../../workflow-state.js';
+
+const VALID_ARTIFACT_STATUSES = new Set(['draft', 'ready', 'blocked', 'pass', 'fail', 'done', 'completed', 'accepted', 'needs_human']);
+
+function makeId(prefix) {
+  return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 12)}`;
+}
+
+function resolveCommand(input = {}) {
+  if (Array.isArray(input.command) && input.command.length > 0) {
+    return input.command.map((part) => String(part));
+  }
+  if (typeof input.command === 'string' && input.command.trim()) {
+    return ['sh', '-c', input.command];
+  }
+  if (Array.isArray(input.commands) && input.commands.length > 0) {
+    return input.commands.map((part) => String(part));
+  }
+  throw new Error('E2.workflow.guard requires a command');
+}
+
+function validateArtifact(artifactPath, expectedPhase, gateToken) {
+  const raw = readFileSync(artifactPath, 'utf8');
+  const artifact = JSON.parse(raw);
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    throw new Error('Workflow artifact must be a JSON object');
+  }
+  if (artifact.phase !== expectedPhase) {
+    throw new Error(`Workflow artifact phase mismatch: expected ${expectedPhase}, got ${String(artifact.phase || '')}`);
+  }
+  if (!VALID_ARTIFACT_STATUSES.has(String(artifact.status || ''))) {
+    throw new Error(`Workflow artifact status must be one of: ${[...VALID_ARTIFACT_STATUSES].join(', ')}`);
+  }
+  if (typeof artifact.summary !== 'string' || artifact.summary.trim().length === 0) {
+    throw new Error('Workflow artifact summary is required');
+  }
+  if (artifact.gate_token !== gateToken) {
+    throw new Error('Workflow artifact gate token mismatch');
+  }
+  return artifact;
+}
+
+export async function workflowGuard(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const workflowName = context.workflow?.name || input.workflow || null;
+  const changeId = context.changeId || input.change_id || null;
+  const phaseOrder = Array.isArray(context.workflow?.phases) ? context.workflow.phases.map((phase) => phase.id) : [];
+  const expectedPhase = input.phase || context.phase?.id || null;
+  if (!expectedPhase) {
+    throw new Error('phase is required for E2.workflow.guard');
+  }
+
+  const artifactPath = input.artifact_path
+    || (changeId ? resolveChangePath(projectRoot, changeId, `${expectedPhase}.json`) : null);
+  if (!artifactPath) {
+    throw new Error('artifact_path is required for E2.workflow.guard');
+  }
+
+  const command = resolveCommand(input);
+  const gateToken = makeId('gt');
+  const state = loadWorkflowState(projectRoot, { workflowName, changeId, phaseOrder, currentPhase: expectedPhase });
+  if (state.current_phase && state.current_phase !== expectedPhase) {
+    throw new Error(`Workflow guard blocked: current phase is ${state.current_phase}, requested ${expectedPhase}`);
+  }
+
+  const nextState = {
+    ...state,
+    workflow: state.workflow || workflowName || null,
+    change_id: state.change_id || changeId || null,
+    current_phase: state.current_phase || expectedPhase,
+    current_artifact_path: artifactPath,
+    pending_gate_token: gateToken,
+    pending_gate_phase: expectedPhase,
+    pending_gate_issued_at: new Date().toISOString(),
+  };
+  saveWorkflowState(projectRoot, nextState);
+
+  const env = {
+    ...process.env,
+    AS_XFLOW_WORKFLOW_ID: String(nextState.workflow_id || ''),
+    AS_XFLOW_WORKFLOW_PHASE: expectedPhase,
+    AS_XFLOW_WORKFLOW_STATE_FILE: resolveWorkflowStateFile(projectRoot),
+    AS_XFLOW_WORKFLOW_ARTIFACT_PATH: artifactPath,
+    AS_XFLOW_WORKFLOW_GATE_TOKEN: gateToken,
+  };
+
+  const result = spawnSync(command[0], command.slice(1), {
+    cwd: projectRoot,
+    env,
+    encoding: 'utf8',
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      status: result.status,
+      signal: result.signal || null,
+      workflow_state: nextState,
+    };
+  }
+
+  validateArtifact(artifactPath, expectedPhase, gateToken);
+  const advanced = advanceWorkflowState(projectRoot, {
+    expectedPhase,
+    artifactPath,
+    workflowName,
+    changeId,
+    phaseOrder,
+  });
+
+  return {
+    ok: true,
+    status: result.status,
+    signal: result.signal || null,
+    workflow_state: advanced,
+    artifact_path: artifactPath,
+  };
+}

package/src/core/atoms/workflow/state-load.js

@@ -0,0 +1,37 @@
+import { resolveBoundMissionId } from '../../bindings.js';
+import { getMissionDetail } from '../../mission-state.js';
+import { readStore, resolveDataFile } from '../../state-store.js';
+import { loadWorkflowState, resolveWorkflowStateFile, saveWorkflowState } from '../../workflow-state.js';
+
+export async function workflowStateLoad(input = {}, context = {}) {
+  const projectRoot = context.projectRoot || process.cwd();
+  const workflowName = context.workflow?.name || input.workflow || null;
+  const changeId = context.changeId || input.change_id || null;
+  const phaseOrder = Array.isArray(context.workflow?.phases) ? context.workflow.phases.map((phase) => phase.id) : [];
+  const currentPhase = context.phase?.id || input.phase || phaseOrder[0] || null;
+  const stateFile = resolveWorkflowStateFile(projectRoot);
+  const workflowState = loadWorkflowState(projectRoot, { workflowName, changeId, phaseOrder, currentPhase });
+  saveWorkflowState(projectRoot, workflowState);
+
+  const missionId = resolveBoundMissionId({
+    projectRoot,
+    changeId,
+    missionId: input.mission_id || null,
+    runtimeMissionId: context.runtime?.missionId || null,
+  });
+
+  let missionDetail = null;
+  if (missionId) {
+    const dataFile = resolveDataFile({ projectRoot, explicitPath: input.data_file || null });
+    const store = await readStore(dataFile);
+    missionDetail = getMissionDetail(store, missionId);
+  }
+
+  return {
+    ok: true,
+    state_file: stateFile,
+    workflow_state: workflowState,
+    mission_id: missionId,
+    mission_detail: missionDetail,
+  };
+}

package/src/core/bindings.js

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function bindingsFile(projectRoot) {
+  return resolve(projectRoot, '.as-xflow', 'bindings.json');
+}
+
+export function readBindings(projectRoot) {
+  const file = bindingsFile(projectRoot);
+  if (!existsSync(file)) {
+    return {};
+  }
+
+  try {
+    const raw = readFileSync(file, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function readBinding(projectRoot, changeId) {
+  return readBindings(projectRoot)[changeId] || null;
+}
+
+export function resolveBoundMissionId({ projectRoot, changeId, missionId = null, runtimeMissionId = null } = {}) {
+  if (missionId) {
+    return missionId;
+  }
+  if (runtimeMissionId) {
+    return runtimeMissionId;
+  }
+  if (!changeId) {
+    return null;
+  }
+  return readBinding(projectRoot, changeId)?.mission_id || null;
+}

package/src/core/change-artifacts.js

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+export function resolveChangeDir(projectRoot, changeId) {
+  if (!changeId) {
+    throw new Error('change_id is required');
+  }
+  return resolve(projectRoot, 'specs', 'changes', changeId);
+}
+
+export function resolveChangePath(projectRoot, changeId, relativePath) {
+  return resolve(resolveChangeDir(projectRoot, changeId), relativePath);
+}
+
+export function ensureParentDir(filePath) {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+export function writeJsonFile(filePath, payload) {
+  ensureParentDir(filePath);
+  writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return filePath;
+}
+
+export function writeTextFile(filePath, content) {
+  ensureParentDir(filePath);
+  writeFileSync(filePath, content.endsWith('\n') ? content : `${content}\n`, 'utf8');
+  return filePath;
+}
+
+export function readJsonFile(filePath, fallback = null) {
+  if (!existsSync(filePath)) {
+    return fallback;
+  }
+  try {
+    const raw = readFileSync(filePath, 'utf8');
+    return raw.trim() ? JSON.parse(raw) : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function collectExistingFiles(paths) {
+  return paths.filter((filePath) => existsSync(filePath));
+}
+
+export function summarizeFinding(finding = {}) {
+  if (typeof finding === 'string') {
+    return finding.trim();
+  }
+  return String(finding.summary || finding.title || finding.rationale || '').trim();
+}
+
+export function summarizeTeamRun(teamRun = {}) {
+  const findings = Array.isArray(teamRun.findings)
+    ? teamRun.findings.map((finding) => summarizeFinding(finding)).filter(Boolean)
+    : [];
+  return {
+    pattern: teamRun.pattern || null,
+    verdict: teamRun.verdict || null,
+    evidence_bundle: teamRun.evidence_bundle || null,
+    findings,
+    qa_acceptance_packet: teamRun.qa_acceptance_packet || null,
+    workspace_evidence: teamRun.workspace_evidence || null,
+  };
+}
+
+export function makeArtifactEnvelope({ phase, changeId, missionId = null, phaseRun = null, phaseEntry = null, extra = {} }) {
+  const teamRun = phaseEntry?.team_run || {};
+  return {
+    version: 1,
+    phase,
+    change_id: changeId,
+    mission_id: missionId,
+    phase_run_id: phaseRun?.phase_run_id || null,
+    generated_at: nowIso(),
+    summary: phaseEntry?.summary || phaseRun?.summary || '',
+    status: phaseEntry?.effective_status || phaseEntry?.status || phaseRun?.status || 'needs_human',
+    team_run: summarizeTeamRun(teamRun),
+    phase_health: phaseEntry?.health_check || null,
+    source: {
+      phase_run_file: phaseRun?.phase_run_file || null,
+      deployed_url: phaseRun?.deployed_url || null,
+    },
+    ...extra,
+  };
+}
+
+export function renderMarkdownArtifact({ title, phase, envelope }) {
+  const lines = [
+    `# ${title}`,
+    '',
+    `- phase: ${phase}`,
+    `- change_id: ${envelope.change_id}`,
+    `- mission_id: ${envelope.mission_id || ''}`,
+    `- phase_run_id: ${envelope.phase_run_id || ''}`,
+    `- status: ${envelope.status || ''}`,
+    '',
+  ];
+
+  if (envelope.summary) {
+    lines.push('## Summary', '', envelope.summary, '');
+  }
+
+  const verdictStatus = envelope.team_run?.verdict?.status;
+  const verdictRationale = envelope.team_run?.verdict?.rationale;
+  if (verdictStatus || verdictRationale) {
+    lines.push('## Verdict', '');
+    if (verdictStatus) lines.push(`- status: ${verdictStatus}`);
+    if (verdictRationale) lines.push(`- rationale: ${verdictRationale}`);
+    lines.push('');
+  }
+
+  if (Array.isArray(envelope.team_run?.findings) && envelope.team_run.findings.length > 0) {
+    lines.push('## Findings', '');
+    for (const finding of envelope.team_run.findings) {
+      lines.push(`- ${finding}`);
+    }
+    lines.push('');
+  }
+
+  if (envelope.qa_acceptance_packet) {
+    lines.push('## QA Acceptance', '');
+    lines.push('```json');
+    lines.push(JSON.stringify(envelope.qa_acceptance_packet, null, 2));
+    lines.push('```', '');
+  }
+
+  return lines.join('\n');
+}