gemstack-ai 1.1.2 → 1.2.0

package/src/lib/runner-adapters.js

@@ -0,0 +1,347 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { writeJsonAtomic } = require('./state');
+
+/**
+ * Spawns node:test runner safely with explicit argv and shell: false.
+ *
+ * @param {string} rootPath
+ * @param {Array<string>} testFiles
+ * @param {object} options
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string, durationMs: number }>}
+ */
+function executeNodeTestRunner(rootPath, testFiles, options = {}) {
+  return new Promise((resolve) => {
+    const startTime = Date.now();
+    const args = ['--test', '--test-reporter=tap', ...(testFiles || [])];
+
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.NODE_TEST_CONTEXT;
+    delete cleanEnv.NODE_TEST_WORKER_ID;
+
+    const child = spawn(process.execPath, args, {
+      cwd: rootPath,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: cleanEnv
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+
+    child.on('error', (err) => {
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr: err.message,
+        durationMs: Date.now() - startTime
+      });
+    });
+
+    child.on('close', (exitCode) => {
+      resolve({
+        exitCode: exitCode === null ? 1 : exitCode,
+        stdout,
+        stderr,
+        durationMs: Date.now() - startTime
+      });
+    });
+  });
+}
+
+/**
+ * Parses node:test TAP output to extract physical counts and test events.
+ *
+ * @param {string} tapOutput
+ * @returns {{ physicalTotal: number, passed: number, failed: number, skipped: number, todo: number, cancelled: number, tests: Array<object> }}
+ */
+function parseNodeTestTap(tapOutput) {
+  const lines = (tapOutput || '').split('\n');
+  const tests = [];
+  const suites = [];
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+  let todo = 0;
+  let cancelled = 0;
+
+  const idRegex = /\b(TEST-[A-Z0-9]+-[A-Z0-9]+)\b/;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // TAP test line format: ok 1 - title # duration_ms
+    // or: not ok 2 - title # duration_ms
+    if (trimmed.startsWith('ok ') || trimmed.startsWith('not ok ')) {
+      const isNotOk = trimmed.startsWith('not ok ');
+      const rest = isNotOk ? trimmed.slice(7) : trimmed.slice(3);
+
+      // Remove test number: "1 - title..."
+      const numMatch = rest.match(/^\d+\s*-\s*(.*)/);
+      const titleAndDirectives = numMatch ? numMatch[1] : rest;
+
+      // Lookahead in YAML diagnostic block for "type: 'suite'" vs "type: 'test'"
+      let eventType = null;
+      let durationMs = 0;
+
+      for (let j = i + 1; j < Math.min(i + 15, lines.length); j++) {
+        const nextTrimmed = lines[j].trim();
+        if (nextTrimmed === '...') break;
+        if (nextTrimmed.startsWith('ok ') || nextTrimmed.startsWith('not ok ')) break;
+
+        const typeMatch = nextTrimmed.match(/^type:\s*['"]?([a-zA-Z0-9_-]+)['"]?/i);
+        if (typeMatch) {
+          eventType = typeMatch[1].toLowerCase();
+        }
+
+        const durMatch = nextTrimmed.match(/^duration_ms:\s*([\d.]+)/i);
+        if (durMatch) {
+          durationMs = parseFloat(durMatch[1]);
+        }
+      }
+
+      // Check inline duration if not in YAML
+      if (!durationMs) {
+        const durMatchInline = titleAndDirectives.match(/duration_ms\s*[:=]\s*([\d.]+)/i) ||
+                               titleAndDirectives.match(/time=([\d.]+)ms/i);
+        if (durMatchInline) durationMs = parseFloat(durMatchInline[1]);
+      }
+
+      // If explicit suite container event in TAP, classify as SUITE and exclude from physical tests
+      if (eventType === 'suite') {
+        suites.push({
+          kind: 'SUITE',
+          title: titleAndDirectives.split('#')[0].trim(),
+          durationMs
+        });
+        continue;
+      }
+
+      let rawOutcome = isNotOk ? 'FAIL' : 'PASS';
+
+      if (/#\s*SKIP\b/i.test(titleAndDirectives)) {
+        rawOutcome = 'SKIP';
+      } else if (/#\s*TODO\b/i.test(titleAndDirectives)) {
+        rawOutcome = 'TODO';
+      } else if (/#\s*CANCELLED\b/i.test(titleAndDirectives)) {
+        rawOutcome = 'CANCELLED';
+      }
+
+      const idMatch = titleAndDirectives.match(idRegex);
+      const canonicalId = idMatch ? idMatch[1] : null;
+
+      if (rawOutcome === 'PASS') passed++;
+      else if (rawOutcome === 'FAIL') failed++;
+      else if (rawOutcome === 'SKIP') skipped++;
+      else if (rawOutcome === 'TODO') todo++;
+      else if (rawOutcome === 'CANCELLED') cancelled++;
+
+      tests.push({
+        kind: 'TEST',
+        id: canonicalId,
+        title: titleAndDirectives.split('#')[0].trim(),
+        rawOutcome,
+        durationMs,
+        isSupporting: canonicalId === null
+      });
+    }
+  }
+
+  const physicalTotal = passed + failed + skipped + todo + cancelled;
+
+  return {
+    physicalTotal,
+    passed,
+    failed,
+    skipped,
+    todo,
+    cancelled,
+    tests,
+    suites
+  };
+}
+
+/**
+ * Reconciles canonical acceptance requirements with runner execution traces.
+ *
+ * @param {Array<object>} canonicalMatrix
+ * @param {Array<object>} planBindings
+ * @param {Array<object>} executedEvents
+ * @returns {object}
+ */
+function reconcileTestRun(canonicalMatrix, planBindings, executedEvents) {
+  const boundCanonicalIds = new Set((planBindings || []).map(b => b.test_id));
+  const expectedRequired = (canonicalMatrix || []).filter(m => m.gate === 'REQUIRED');
+  const validCanonicalIds = new Set((canonicalMatrix || []).map(m => m.id));
+
+  const executedCanonical = [];
+  const executedSupporting = [];
+  const executedIdCounts = {};
+
+  for (const ev of (executedEvents || [])) {
+    if (ev.id) {
+      executedCanonical.push(ev);
+      executedIdCounts[ev.id] = (executedIdCounts[ev.id] || 0) + 1;
+    } else {
+      executedSupporting.push(ev);
+    }
+  }
+
+  // 1. Check duplicate physical execution identities
+  const duplicates = Object.keys(executedIdCounts).filter(id => executedIdCounts[id] > 1);
+
+  // 2. Check orphans (physical test claimed canonical ID absent from SPEC)
+  const orphans = Object.keys(executedIdCounts).filter(id => !validCanonicalIds.has(id));
+
+  // 3. Check missing vs not executed
+  const executedIdSet = new Set(Object.keys(executedIdCounts));
+  const missing = [];
+  const notExecuted = [];
+
+  for (const req of expectedRequired) {
+    if (!boundCanonicalIds.has(req.id)) {
+      missing.push(req.id);
+    } else if (!executedIdSet.has(req.id)) {
+      notExecuted.push(req.id);
+    }
+  }
+
+  // 4. Check phantoms (phantom test: claimed executed/pass but absent from runner events)
+  const phantoms = [];
+
+  // 5. Arithmetic equation validation
+  const canonicalCount = executedCanonical.length;
+  const supportingCount = executedSupporting.length;
+  const totalPhysical = executedEvents.length;
+
+  const mathValid = (canonicalCount + supportingCount === totalPhysical);
+
+  return {
+    mathValid,
+    totalPhysical,
+    canonicalCount,
+    supportingCount,
+    duplicates,
+    orphans,
+    missing,
+    notExecuted,
+    phantoms
+  };
+}
+
+/**
+ * Executes a PACKAGE_SCRIPT gate safely without shell: true.
+ *
+ * @param {string} rootPath
+ * @param {object} gateConfig
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string }>}
+ */
+function executePackageScriptGate(rootPath, gateConfig) {
+  return new Promise((resolve) => {
+    const pkgPath = path.join(rootPath, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      const err = new Error('package.json not found for PACKAGE_SCRIPT gate');
+      err.code = 'REQUIRED_GATE_MISSING';
+      return resolve({ exitCode: 1, stdout: '', stderr: err.message, error: err });
+    }
+
+    let pkg;
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch (e) {
+      const err = new Error('Failed to parse package.json: ' + e.message);
+      err.code = 'REQUIRED_GATE_MISSING';
+      return resolve({ exitCode: 1, stdout: '', stderr: err.message, error: err });
+    }
+
+    if (!pkg.scripts || !pkg.scripts[gateConfig.script]) {
+      const err = new Error('Script "' + gateConfig.script + '" not found in package.json');
+      err.code = 'REQUIRED_GATE_MISSING';
+      return resolve({ exitCode: 1, stdout: '', stderr: err.message, error: err });
+    }
+
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.NODE_TEST_CONTEXT;
+    delete cleanEnv.NODE_TEST_WORKER_ID;
+
+    let execBinary = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    let execArgs = ['run', gateConfig.script];
+
+    // On Windows, node.js spawn('npm.cmd', ..., { shell: false }) triggers EINVAL in node 22+ unless .cmd is spawned via cmd /c or direct npm-cli.js
+    if (process.platform === 'win32') {
+      const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+      if (fs.existsSync(npmCli)) {
+        execBinary = process.execPath;
+        execArgs = [npmCli, 'run', gateConfig.script];
+      }
+    }
+
+    const child = spawn(execBinary, execArgs, {
+      cwd: rootPath,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: cleanEnv
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+
+    child.on('error', (err) => {
+      resolve({ exitCode: 1, stdout, stderr: err.message, error: err });
+    });
+
+    child.on('close', (exitCode) => {
+      resolve({ exitCode: exitCode === null ? 1 : exitCode, stdout, stderr });
+    });
+  });
+}
+
+/**
+ * Assembles and atomically writes the feature-local closure.json manifest.
+ *
+ * @param {string} targetDir
+ * @param {object} manifestData
+ * @returns {object} Written manifest
+ */
+function generateClosureManifest(targetDir, manifestData) {
+  const closurePath = path.join(targetDir, 'closure.json');
+
+  const manifest = {
+    schema: 'gemstack-closure',
+    version: 1,
+    feature: manifestData.feature,
+    generated_at: manifestData.generated_at || new Date().toISOString(),
+    status: manifestData.status,
+    closure_context: manifestData.closure_context,
+    acceptance_signature: manifestData.acceptance_signature,
+    canonical_summary: manifestData.canonical_summary,
+    physical_summary: manifestData.physical_summary,
+    reconciliation: manifestData.reconciliation,
+    task_traceability_summary: manifestData.task_traceability_summary,
+    required_gates: manifestData.required_gates || {},
+    supplemental_gates: manifestData.supplemental_gates || {},
+    exceptions: manifestData.exceptions || [],
+    evidence_sources: manifestData.evidence_sources || [],
+    blockers: manifestData.blockers || [],
+    warnings: manifestData.warnings || []
+  };
+
+  writeJsonAtomic(closurePath, manifest);
+  return manifest;
+}
+
+module.exports = {
+  executeNodeTestRunner,
+  parseNodeTestTap,
+  reconcileTestRun,
+  executePackageScriptGate,
+  generateClosureManifest
+};

package/src/lib/test-matrix.js

@@ -0,0 +1,187 @@
+const crypto = require('node:crypto');
+const { normalizeContent } = require('./hasher');
+
+const CANONICAL_LAYERS = ['UNIT', 'INTEGRATION', 'E2E', 'CLI'];
+const CANONICAL_GATES = ['REQUIRED', 'SUPPLEMENTAL'];
+const CANONICAL_ID_REGEX = /^TEST-[A-Z0-9]+-[A-Z0-9]+$/;
+const REQUIRED_FIELDS = ['id', 'category', 'layer', 'description', 'pass_criteria', 'gate'];
+
+/**
+ * Extracts the single column-0 gemstack-test-matrix block from markdown.
+ *
+ * @param {string} markdownContent
+ * @returns {{ matrix: Array<object>|null, isLegacy: boolean }}
+ */
+function extractTestMatrixBlock(markdownContent) {
+  const normalized = normalizeContent(markdownContent);
+  const lines = normalized.split('\n');
+  const fence = '```';
+  const header = '```gemstack-test-matrix';
+
+  const blocks = [];
+  let inBlock = false;
+  let blockLines = [];
+
+  for (const line of lines) {
+    if (!inBlock) {
+      if (line.trimEnd() === header) {
+        inBlock = true;
+        blockLines = [];
+      }
+    } else {
+      if (line.trimEnd() === fence) {
+        inBlock = false;
+        blocks.push(blockLines.join('\n'));
+      } else {
+        blockLines.push(line);
+      }
+    }
+  }
+
+  if (blocks.length === 0) {
+    return { matrix: null, isLegacy: true };
+  }
+
+  if (blocks.length > 1) {
+    const err = new Error(`Multiple gemstack-test-matrix blocks detected (${blocks.length}). Exactly one is permitted.`);
+    err.code = 'TEST_MATRIX_PARSE_ERROR';
+    throw err;
+  }
+
+  const jsonRaw = blocks[0].trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonRaw);
+  } catch (parseErr) {
+    const err = new Error(`Failed to parse gemstack-test-matrix JSON: ${parseErr.message}`);
+    err.code = 'TEST_MATRIX_PARSE_ERROR';
+    throw err;
+  }
+
+  return { matrix: parsed, isLegacy: false };
+}
+
+/**
+ * Validates a canonical test matrix array.
+ *
+ * @param {any} matrix
+ * @returns {Array<object>} Sanitized array of canonical test objects
+ */
+function validateTestMatrix(matrix) {
+  if (!Array.isArray(matrix)) {
+    const err = new Error('gemstack-test-matrix must be a JSON array of test objects');
+    err.code = 'TEST_MATRIX_INVALID_SHAPE';
+    throw err;
+  }
+
+  const seenIds = new Set();
+  const validated = [];
+
+  for (let i = 0; i < matrix.length; i++) {
+    const item = matrix[i];
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      const err = new Error(`Item at index ${i} in gemstack-test-matrix must be a non-null object`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    // Check unknown fields
+    const keys = Object.keys(item);
+    for (const k of keys) {
+      if (!REQUIRED_FIELDS.includes(k)) {
+        const err = new Error(`Item at index ${i} contains unknown field: "${k}"`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+    }
+
+    // Check required fields and empty values
+    for (const rf of REQUIRED_FIELDS) {
+      if (!(rf in item)) {
+        const err = new Error(`Item at index ${i} missing required field: "${rf}"`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+      if (typeof item[rf] !== 'string' || item[rf].trim().length === 0) {
+        const err = new Error(`Item at index ${i} field "${rf}" must be a non-empty string`);
+        err.code = 'TEST_MATRIX_INVALID_SHAPE';
+        throw err;
+      }
+    }
+
+    // Validate ID regex
+    if (!CANONICAL_ID_REGEX.test(item.id)) {
+      const err = new Error(`Item at index ${i} has invalid ID "${item.id}". Must match ^TEST-[A-Z0-9]+-[A-Z0-9]+$`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    // Validate duplicate ID
+    if (seenIds.has(item.id)) {
+      const err = new Error(`Duplicate test ID detected in gemstack-test-matrix: "${item.id}"`);
+      err.code = 'TEST_MATRIX_DUPLICATE_ID';
+      throw err;
+    }
+    seenIds.add(item.id);
+
+    // Validate enum fields
+    if (!CANONICAL_LAYERS.includes(item.layer)) {
+      const err = new Error(`Item "${item.id}" has invalid layer "${item.layer}". Must be one of: ${CANONICAL_LAYERS.join(', ')}`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    if (!CANONICAL_GATES.includes(item.gate)) {
+      const err = new Error(`Item "${item.id}" has invalid gate "${item.gate}". Must be one of: ${CANONICAL_GATES.join(', ')}`);
+      err.code = 'TEST_MATRIX_INVALID_SHAPE';
+      throw err;
+    }
+
+    validated.push({
+      id: item.id,
+      category: item.category,
+      layer: item.layer,
+      description: item.description,
+      pass_criteria: item.pass_criteria,
+      gate: item.gate
+    });
+  }
+
+  return validated;
+}
+
+/**
+ * Computes deterministic SHA-256 acceptanceSignature digest over canonical test matrix.
+ *
+ * @param {Array<object>} matrix
+ * @returns {string} 64-character lowercase hexadecimal digest
+ */
+function computeAcceptanceSignature(matrix) {
+  const validated = validateTestMatrix(matrix);
+
+  // Sort canonical records by id using deterministic code-unit ordering
+  const sorted = [...validated].sort((a, b) => (a.id < b.id ? -1 : (a.id > b.id ? 1 : 0)));
+
+  // Normalize each record with ASCII-sorted keys: category, description, gate, id, layer, pass_criteria
+  const normalizedRecords = sorted.map(rec => ({
+    category: rec.category,
+    description: rec.description,
+    gate: rec.gate,
+    id: rec.id,
+    layer: rec.layer,
+    pass_criteria: rec.pass_criteria
+  }));
+
+  const canonicalJson = JSON.stringify(normalizedRecords);
+  return crypto.createHash('sha256').update(canonicalJson, 'utf8').digest('hex');
+}
+
+module.exports = {
+  CANONICAL_LAYERS,
+  CANONICAL_GATES,
+  CANONICAL_ID_REGEX,
+  REQUIRED_FIELDS,
+  extractTestMatrixBlock,
+  validateTestMatrix,
+  computeAcceptanceSignature
+};