@jaimevalasek/aioson 1.30.2 → 1.36.0

package/src/harness/contract-integrity-gate.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { validateContract } = require('./contract-schema');
+const { checkContractIntegrity } = require('./contract-integrity');
+const { evaluateStaticCriteria } = require('./static-criteria');
+const { detectRuntimeFeature, gitChangedFiles } = require('./detect-runtime-feature');
+const { runHarnessCheck } = require('../commands/harness-check');
+
+function readJsonSafe(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return { exists: false, value: null, error: null };
+    return { exists: true, value: JSON.parse(fs.readFileSync(filePath, 'utf8')), error: null };
+  } catch (err) {
+    return { exists: true, value: null, error: err };
+  }
+}
+
+function progressCompletedSteps(progress) {
+  if (!progress || typeof progress !== 'object') return [];
+  return [
+    progress.completed_steps,
+    progress.changed_files,
+    progress.touched_files
+  ].flatMap((value) => Array.isArray(value) ? value : []);
+}
+
+function makeSilentLogger() {
+  return {
+    lines: [],
+    errors: [],
+    log(message = '') { this.lines.push(String(message)); },
+    error(message = '') { this.errors.push(String(message)); }
+  };
+}
+
+async function evaluateContractIntegrityGate(targetDir, slug, options = {}) {
+  const planDir = path.join(targetDir, '.aioson', 'plans', slug);
+  const contractPath = path.join(planDir, 'harness-contract.json');
+  const progressPath = path.join(planDir, 'progress.json');
+  const progressRead = readJsonSafe(progressPath);
+  const completedSteps = progressRead.value ? progressCompletedSteps(progressRead.value) : [];
+  const changedFiles = options.changedFiles || gitChangedFiles(targetDir);
+  const runtime = detectRuntimeFeature(targetDir, slug, { completedSteps, changedFiles });
+
+  const contractRead = readJsonSafe(contractPath);
+  if (!contractRead.exists) {
+    if (!runtime.isRuntimeFeature) {
+      return { ok: true, slug, has_contract: false, runtime, errors: [], warnings: [] };
+    }
+    return {
+      ok: false,
+      slug,
+      has_contract: false,
+      runtime,
+      errors: [{
+        code: 'missing_runtime_contract',
+        message: `runtime feature detected (${runtime.signals.join(', ')}) but .aioson/plans/${slug}/harness-contract.json is missing — author it with the §2c RG-* runtime-gate criteria (run \`aioson harness:init . --slug=${slug}\`, or have @sheldon/@dev produce it), then re-run the stage.`
+      }],
+      warnings: []
+    };
+  }
+
+  if (contractRead.error) {
+    return {
+      ok: false,
+      slug,
+      has_contract: true,
+      runtime,
+      errors: [{
+        code: 'contract_invalid_json',
+        message: `invalid JSON in .aioson/plans/${slug}/harness-contract.json: ${contractRead.error.message}`
+      }],
+      warnings: []
+    };
+  }
+
+  const schemaResult = validateContract(contractRead.value);
+  if (!schemaResult.ok) {
+    return {
+      ok: false,
+      slug,
+      has_contract: true,
+      runtime,
+      errors: schemaResult.errors.map((err) => ({
+        code: 'contract_schema_invalid',
+        message: `${err.field}: ${err.reason}`
+      })),
+      warnings: schemaResult.warnings || []
+    };
+  }
+
+  const integrity = checkContractIntegrity(contractRead.value, {
+    isRuntimeFeature: runtime.isRuntimeFeature
+  });
+  const errors = [...integrity.errors];
+  const warnings = [...integrity.warnings];
+  let checkReport = null;
+
+  if (options.runChecks) {
+    // The full path runs the expensive runtime (RG-*) commands AND re-evaluates
+    // the cheap static (SG-*) criteria as part of its report — so it owns both.
+    checkReport = await runHarnessCheck({
+      args: [targetDir],
+      options: {
+        slug,
+        json: true,
+        strict: Boolean(options.strict || runtime.isRuntimeFeature)
+      },
+      logger: makeSilentLogger(),
+      t: () => undefined
+    });
+    if (!checkReport.ok) {
+      errors.push({
+        code: 'harness_check_failed',
+        message: `aioson harness:check failed for ${slug}; see .aioson/plans/${slug}/last-check-output.json`
+      });
+    }
+  } else {
+    // SG-* static criteria are build-independent (pure fs + RegExp + parse) — they
+    // gate at EVERY stage, even when the expensive runtime checks are deferred to
+    // the last gate (A5). Evaluate them directly here so a stubbed/placeholder
+    // implementation cannot pass @dev-done just because the build smoke runs later.
+    const staticResult = evaluateStaticCriteria({
+      criteria: Array.isArray(contractRead.value.criteria) ? contractRead.value.criteria : [],
+      cwd: targetDir
+    });
+    for (const check of staticResult.checks) {
+      if (!check.ok) {
+        errors.push({
+          code: 'static_criteria_failed',
+          message: `${check.id}: ${check.detail}`
+        });
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    slug,
+    has_contract: true,
+    runtime,
+    integrity,
+    checkReport,
+    errors,
+    warnings
+  };
+}
+
+function formatContractIntegrityGateError(result, stageName = null) {
+  const header = stageName
+    ? `[Harness Contract Gate BLOCKED] Cannot complete @${stageName} for "${result.slug}".`
+    : `[Harness Contract Gate BLOCKED] Feature "${result.slug}" cannot close.`;
+  const lines = [header];
+  for (const err of result.errors || []) {
+    lines.push(`- ${err.code}: ${err.message}`);
+  }
+  if (result.runtime && result.runtime.signals && result.runtime.signals.length) {
+    lines.push(`Runtime signals: ${result.runtime.signals.join(', ')}`);
+  }
+  lines.push(`Run: aioson harness:check . --slug=${result.slug} --json`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  evaluateContractIntegrityGate,
+  formatContractIntegrityGateError,
+  gitChangedFiles,
+  progressCompletedSteps
+};

package/src/harness/contract-integrity.js

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * Contract-integrity check — the deterministic core of @validator's Step 0
+ * (harness-contract.md §2c). Catches two contract-SHAPE failures a blind
+ * executor must never let through on a runtime feature:
+ *
+ *   1. missing_runtime_gate — a runtime feature whose contract carries NONE of
+ *      the RG-* runtime-gate criteria (build / migrate / boot / smoke). The
+ *      app's build, migrations, boot and Core happy-path are then unverified —
+ *      the exact green-but-broken failure mode §2c exists to stop.
+ *   2. duplicate_verification — two binary criteria sharing an identical
+ *      `verification` command (padding 11 criteria out of 6 real commands to
+ *      fake an "11/11" score).
+ *
+ * This is contract-SHAPE verification, never a product judgment. Runtime-feature
+ * detection (see detect-runtime-feature.js) only fires on signals the framework
+ * can locate deterministically; the Play `manifest.json` `has_api` flag lives in
+ * the target app and stays with the LLM @validator. `isRuntimeFeature: false`
+ * therefore means "no reliable runtime signal", not "proven non-runtime" — so a
+ * duplicate on a non-runtime contract is reported as a warning, not a hard error.
+ */
+
+const RUNTIME_GATE_IDS = Object.freeze(['RG-build', 'RG-migrate', 'RG-boot', 'RG-smoke']);
+
+function normId(id) {
+  return String(id || '').trim().toLowerCase();
+}
+
+const RUNTIME_GATE_ID_SET = new Set(RUNTIME_GATE_IDS.map(normId));
+
+/**
+ * A criterion counts as a runtime-gate criterion when its id is one of the
+ * canonical RG-* ids (case-insensitive) or starts with `rg-`. We deliberately
+ * match on the id, not the verification text, so a contract author opts in
+ * explicitly (an RG-smoke that runs a unit test is a lie the author signs).
+ */
+function isRuntimeGateCriterion(criterion) {
+  const id = normId(criterion && criterion.id);
+  return RUNTIME_GATE_ID_SET.has(id) || id.startsWith('rg-');
+}
+
+function hasRuntimeGate(contract) {
+  const criteria = Array.isArray(contract && contract.criteria) ? contract.criteria : [];
+  return criteria.some(isRuntimeGateCriterion);
+}
+
+/**
+ * Groups of criterion ids that share an identical non-empty `verification`
+ * command among `binary: true` criteria. Each group has length >= 2.
+ */
+function findDuplicateVerifications(contract) {
+  const criteria = Array.isArray(contract && contract.criteria) ? contract.criteria : [];
+  const byCommand = new Map();
+  for (const criterion of criteria) {
+    if (!criterion || criterion.binary !== true) continue;
+    const command = typeof criterion.verification === 'string' ? criterion.verification.trim() : '';
+    if (!command) continue;
+    if (!byCommand.has(command)) byCommand.set(command, []);
+    byCommand.get(command).push(criterion.id);
+  }
+  const duplicates = [];
+  for (const [command, ids] of byCommand) {
+    if (ids.length > 1) duplicates.push({ command, ids });
+  }
+  return duplicates;
+}
+
+/**
+ * @param {object} contract  parsed harness-contract.json
+ * @param {{ isRuntimeFeature?: boolean }} options
+ * @returns {{ ok: boolean, errors: Array<{code,message}>, warnings: Array<{code,message}>, isRuntimeFeature: boolean }}
+ *   `ok === false` only when there is at least one blocking error. Warnings never
+ *   set `ok = false` (advisory).
+ */
+function checkContractIntegrity(contract, options = {}) {
+  const isRuntimeFeature = Boolean(options.isRuntimeFeature);
+  const errors = [];
+  const warnings = [];
+
+  const duplicates = findDuplicateVerifications(contract);
+  for (const dup of duplicates) {
+    const entry = {
+      code: 'duplicate_verification',
+      message: `criteria ${dup.ids.join(', ')} share an identical verification command ("${dup.command}") — each binary criterion must map to a distinct check (harness-contract.md §2c).`
+    };
+    // Padding only fakes coverage on a runtime feature; on a non-runtime
+    // contract a shared command (e.g. two ACs both proven by `npm test`) can be
+    // legitimate, so it is advisory there.
+    if (isRuntimeFeature) errors.push(entry);
+    else warnings.push(entry);
+  }
+
+  if (isRuntimeFeature && !hasRuntimeGate(contract)) {
+    errors.push({
+      code: 'missing_runtime_gate',
+      message: 'runtime feature but the contract has no RG-build / RG-migrate / RG-boot / RG-smoke criterion — the app\'s build, migrations, boot and Core happy-path are unverified. Add the §2c runtime-gate criteria, then re-run @dev.'
+    });
+  }
+
+  return { ok: errors.length === 0, errors, warnings, isRuntimeFeature };
+}
+
+module.exports = {
+  RUNTIME_GATE_IDS,
+  normId,
+  isRuntimeGateCriterion,
+  hasRuntimeGate,
+  findDuplicateVerifications,
+  checkContractIntegrity
+};