forge-workflow 0.0.9 → 0.0.10

package/scripts/test.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 /**
- * Cross-platform test runner for the lefthook pre-push hook.
+ * Cross-platform test runner shared by the pre-push hook and local validation.
  *
- * Runs only the tests affected by the changes being pushed when possible.
- * Falls back to the full suite only for package-level changes.
+ * It runs only the tests affected by known changes when possible and falls back
+ * to the full suite for package-level or unknown-file changes.
  */
 
 const { execFileSync: defaultExecFileSync, spawnSync: defaultSpawnSync } = require('node:child_process');
@@ -22,8 +22,49 @@ const PACKAGE_LEVEL_PATHS = new Set([
   'package-lock.json',
 ]);
 
+const KNOWN_TARGETABLE_PREFIXES = [
+  '.claude/commands/',
+  '.cursor/',
+  '.cline/',
+  '.roo/',
+  '.kilocode/',
+  '.opencode/',
+  '.codex/skills/',
+  '.forge/',
+  '.github/prompts/',
+  '.github/agentic-workflows/',
+  '.github/workflows/',
+  'test/',
+];
+
+const ALWAYS_RUN_RISK_TEST_TARGETS = [
+  // Windows + concurrent filesystem locking has failed post-merge; keep this
+  // in the fast PR lane until enough full-matrix runs prove it stable.
+  'test/project-memory.test.js',
+];
+
 const isWindows = process.platform === 'win32';
 
+/**
+ * @typedef {Object} TestExecutionPlan
+ * @property {string[]} changedFiles
+ * @property {boolean} hasUnmappedFiles
+ * @property {boolean} hasUnknownChangedFiles
+ * @property {boolean} hasZeroResolvedTests
+ * @property {'targeted'|'full'} mode
+ * @property {string} reason
+ * @property {boolean} runE2E
+ * @property {boolean} runFullSuite
+ * @property {boolean} runTestEnv
+ * @property {boolean} runWorkflowTests
+ * @property {string[]} testTargets
+ */
+
+/**
+ * Detects the package manager to use for running test commands in this checkout.
+ *
+ * @returns {'bun'|'pnpm'|'yarn'|'npm'} The package manager inferred from lockfiles.
+ */
 function detectPackageManager() {
   if (fs.existsSync('bun.lockb') || fs.existsSync('bun.lock')) return 'bun';
   if (fs.existsSync('pnpm-lock.yaml')) return 'pnpm';
@@ -31,6 +72,12 @@ function detectPackageManager() {
   return 'npm';
 }
 
+/**
+ * Removes Git hook-only environment variables before spawning nested Git-aware commands.
+ *
+ * @param {NodeJS.ProcessEnv} [sourceEnv=process.env] Environment variables to sanitize.
+ * @returns {NodeJS.ProcessEnv} A copy of the environment without hook-specific Git variables.
+ */
 function stripGitHookEnv(sourceEnv = process.env) {
   const env = { ...sourceEnv };
   for (const key of Object.keys(env)) {
@@ -43,21 +90,78 @@ function stripGitHookEnv(sourceEnv = process.env) {
   return env;
 }
 
-function classifyPushTests(projectRoot, execFileSync = defaultExecFileSync) {
-  const changedFiles = getChangedFiles(execFileSync, { sinceUpstream: true });
-  const testTargets = getAffectedTestFiles(projectRoot, execFileSync, fs, { sinceUpstream: true });
+/**
+ * Checks whether a changed path belongs to a known test-targetable area.
+ *
+ * @param {string} file Repository-relative changed file path.
+ * @returns {boolean} True when the path can be handled by targeted test selection.
+ */
+function isKnownTargetablePath(file) {
+  if (file === '.gitignore') {
+    return true;
+  }
+
+  if (file.startsWith('docs/plans/')) {
+    return true;
+  }
+
+  return KNOWN_TARGETABLE_PREFIXES.some((prefix) => file.startsWith(prefix));
+}
+
+/**
+ * Determines whether the resolved test targets require workflow-specific validation.
+ *
+ * @param {string[]} testTargets Repository-relative test file paths.
+ * @returns {boolean} True when workflow tests are part of the target set.
+ */
+function includesWorkflowTarget(testTargets) {
+  return testTargets.some((target) => target === 'test/ci-workflow.test.js'
+    || target === 'test/structural/agentic-workflow-sync.test.js'
+    || target.startsWith('test/workflows/'));
+}
+
+/**
+ * Deduplicates test targets while preserving the original execution order.
+ *
+ * @param {string[]} testTargets Repository-relative test file paths.
+ * @returns {string[]} Unique test targets in first-seen order.
+ */
+function uniqueTestTargets(testTargets) {
+  return [...new Set(testTargets)];
+}
+
+function isExtraLaneOnlyPath(file) {
+  return file.startsWith('test/e2e/') || file.startsWith('test-env/');
+}
+
+/**
+ * Builds the execution plan used by PR, pre-push, and local validation test lanes.
+ *
+ * @param {string} projectRoot Absolute or relative repository root.
+ * @param {typeof defaultExecFileSync} [execFileSync=defaultExecFileSync] Command runner used to inspect Git state.
+ * @param {{sinceUpstream?: boolean}} [options={}] Test selection options.
+ * @returns {TestExecutionPlan} The computed test execution plan.
+ */
+function buildTestExecutionPlan(projectRoot, execFileSync = defaultExecFileSync, options = {}) {
+  const diffOptions = {
+    sinceUpstream: options.sinceUpstream !== false,
+  };
+  const changedFiles = getChangedFiles(execFileSync, diffOptions);
+  const affectedTestTargets = getAffectedTestFiles(projectRoot, execFileSync, fs, diffOptions);
 
   let runFullSuite = false;
   let runTestEnv = false;
   let runE2E = false;
+  let runWorkflowTests = includesWorkflowTarget(affectedTestTargets);
   let hasUnmappedFiles = false;
-  const hasUnknownChangedFiles = changedFiles.length === 0 && testTargets.length === 0;
+  const hasUnknownChangedFiles = changedFiles.length === 0 && affectedTestTargets.length === 0;
 
   for (const file of changedFiles) {
     if (PACKAGE_LEVEL_PATHS.has(file) || file.startsWith('packages/')) {
       runFullSuite = true;
       runTestEnv = true;
       runE2E = true;
+      runWorkflowTests = true;
       break;
     }
 
@@ -71,29 +175,80 @@ function classifyPushTests(projectRoot, execFileSync = defaultExecFileSync) {
       continue;
     }
 
-    if ((file.startsWith('lib/') || file.startsWith('scripts/')) && file.endsWith('.js')) {
+    if ((file.startsWith('lib/') || file.startsWith('scripts/')) && (file.endsWith('.js') || file.endsWith('.sh'))) {
       runTestEnv = true;
+      if (file === 'scripts/behavioral-judge.sh') {
+        runWorkflowTests = true;
+      }
       continue;
     }
 
-    if (file.startsWith('test/') || file.startsWith('.github/workflows/') || file.startsWith('.claude/commands/')) {
+    if (file.startsWith('.github/workflows/') || file.startsWith('.github/agentic-workflows/')) {
+      runWorkflowTests = true;
+    }
+
+    if (isKnownTargetablePath(file)) {
       continue;
     }
 
     hasUnmappedFiles = true;
   }
 
+  const hasOnlyExtraLaneChanges = changedFiles.length > 0
+    && changedFiles.every(isExtraLaneOnlyPath);
+  const hasZeroResolvedTests = changedFiles.length > 0
+    && affectedTestTargets.length === 0
+    && !runFullSuite
+    && !hasOnlyExtraLaneChanges;
+  const shouldRunFullSuite = runFullSuite || hasUnmappedFiles || hasUnknownChangedFiles || hasZeroResolvedTests;
+
+  const reason = hasUnmappedFiles
+    ? 'unmapped pushed files require full unit coverage'
+    : hasUnknownChangedFiles
+      ? 'changed files could not be resolved safely'
+      : hasZeroResolvedTests
+        ? 'known changes did not resolve runnable tests'
+      : runFullSuite
+        ? 'package-level changes detected'
+        : 'known changes mapped to targeted tests';
+
   return {
     changedFiles,
     hasUnmappedFiles,
     hasUnknownChangedFiles,
+    hasZeroResolvedTests,
+    mode: shouldRunFullSuite ? 'full' : 'targeted',
+    reason,
     runE2E,
-    runFullSuite: runFullSuite || hasUnmappedFiles || hasUnknownChangedFiles,
+    runFullSuite: shouldRunFullSuite,
     runTestEnv,
-    testTargets,
+    runWorkflowTests,
+    testTargets: shouldRunFullSuite
+      ? affectedTestTargets
+      : uniqueTestTargets([...affectedTestTargets, ...ALWAYS_RUN_RISK_TEST_TARGETS]),
   };
 }
 
+/**
+ * Classifies the pushed changes into the test plan enforced by the pre-push hook.
+ *
+ * @param {string} projectRoot Absolute or relative repository root.
+ * @param {typeof defaultExecFileSync} [execFileSync=defaultExecFileSync] Command runner used to inspect Git state.
+ * @returns {TestExecutionPlan} The pre-push test execution plan.
+ */
+function classifyPushTests(projectRoot, execFileSync = defaultExecFileSync) {
+  return buildTestExecutionPlan(projectRoot, execFileSync, { sinceUpstream: true });
+}
+
+/**
+ * Runs a command and returns its exit status, throwing only when process spawning fails.
+ *
+ * @param {string} command Executable name.
+ * @param {string[]} args Command arguments.
+ * @param {import('node:child_process').SpawnSyncOptions} [options={}] Spawn options.
+ * @param {typeof defaultSpawnSync} [spawnSync=defaultSpawnSync] Process runner.
+ * @returns {number} Process exit status, or 1 when no status is reported.
+ */
 function runCommand(command, args, options = {}, spawnSync = defaultSpawnSync) {
   const result = spawnSync(command, args, {
     stdio: 'inherit',
@@ -108,40 +263,43 @@ function runCommand(command, args, options = {}, spawnSync = defaultSpawnSync) {
   return result.status ?? 1;
 }
 
-function runPrePushTests(projectRoot = process.cwd(), deps = {}) {
+/**
+ * Executes a computed test plan and any extra targeted validation lanes.
+ *
+ * @param {TestExecutionPlan} plan Test plan to execute.
+ * @param {Object} [deps={}] Runtime dependencies for tests.
+ * @returns {number} Exit status for the executed plan.
+ */
+function runTestExecutionPlan(plan, deps = {}) {
   const spawnSync = deps.spawnSync || defaultSpawnSync;
-  const execFileSync = deps.execFileSync || defaultExecFileSync;
   const pkgManager = deps.pkgManager || detectPackageManager();
   const env = deps.env || stripGitHookEnv(process.env);
-  const plan = classifyPushTests(projectRoot, execFileSync);
+  const bunCommand = deps.bunCommand || env.BUN_EXE || process.env.BUN_EXE || 'bun';
+  const label = deps.label || 'tests';
 
-  console.log(`Running pre-push tests (${pkgManager})...`);
+  console.log(`Running ${label} (${pkgManager})...`);
 
   try {
     if (plan.runFullSuite) {
-      const reason = plan.hasUnmappedFiles
-        ? 'unmapped pushed files require full unit coverage'
-        : plan.hasUnknownChangedFiles
-          ? 'changed files could not be resolved safely'
-          : 'package-level changes detected';
-      console.log(`  Mode: full suite (${reason})`);
-      const status = runCommand(pkgManager, ['run', 'test'], { env }, spawnSync);
+      console.log(`  Mode: full suite (${plan.reason})`);
+      const status = runCommand('node', ['scripts/test-full-suite.js'], { env }, spawnSync);
       if (status !== 0) return status;
     } else if (plan.testTargets.length > 0) {
       console.log(`  Mode: targeted (${plan.testTargets.length} test file${plan.testTargets.length === 1 ? '' : 's'})`);
-      const status = runCommand(pkgManager, ['run', 'test', ...plan.testTargets], { env }, spawnSync);
+      const command = pkgManager === 'bun' ? bunCommand : pkgManager;
+      const status = runCommand(command, ['run', 'test', ...plan.testTargets], { env }, spawnSync);
       if (status !== 0) return status;
     }
 
     if (plan.runE2E) {
       console.log('  Extra: running affected e2e tests');
-      const status = runCommand('bun', ['test', 'test/e2e/'], { env }, spawnSync);
+      const status = runCommand(bunCommand, ['test', 'test/e2e/'], { env }, spawnSync);
       if (status !== 0) return status;
     }
 
-    if (plan.runTestEnv) {
+    if (!plan.runFullSuite && plan.runTestEnv) {
       console.log('  Extra: running affected edge-case tests');
-      const status = runCommand('bun', ['test', 'test-env/'], { env }, spawnSync);
+      const status = runCommand(bunCommand, ['test', 'test-env/'], { env }, spawnSync);
       if (status !== 0) return status;
     }
 
@@ -149,19 +307,52 @@ function runPrePushTests(projectRoot = process.cwd(), deps = {}) {
     return 0;
   } catch (error) {
     console.error('');
-    console.error(`Failed to run tests: ${error.message}`);
+    console.error(`Failed to run ${label}: ${error.message}`);
     console.error('');
     return 1;
   }
 }
 
+/**
+ * Runs the pre-push test plan for the current checkout.
+ *
+ * @param {string} [projectRoot=process.cwd()] Repository root.
+ * @param {Object} [deps={}] Runtime dependencies for tests.
+ * @returns {number} Exit status for pre-push tests.
+ */
+function runPrePushTests(projectRoot = process.cwd(), deps = {}) {
+  const execFileSync = deps.execFileSync || defaultExecFileSync;
+  const plan = classifyPushTests(projectRoot, execFileSync);
+  return runTestExecutionPlan(plan, { ...deps, label: 'pre-push tests' });
+}
+
+/**
+ * Runs the local validation test plan for the current checkout.
+ *
+ * @param {string} [projectRoot=process.cwd()] Repository root.
+ * @param {Object} [deps={}] Runtime dependencies for tests.
+ * @returns {number} Exit status for local validation tests.
+ */
+function runLocalValidationTests(projectRoot = process.cwd(), deps = {}) {
+  const execFileSync = deps.execFileSync || defaultExecFileSync;
+  const plan = buildTestExecutionPlan(projectRoot, execFileSync, { sinceUpstream: true });
+  return runTestExecutionPlan(plan, { ...deps, label: 'local validation tests' });
+}
+
 if (require.main === module) {
-  process.exit(runPrePushTests());
+  const exitCode = process.argv.includes('--validate')
+    ? runLocalValidationTests()
+    : runPrePushTests();
+  process.exit(exitCode);
 }
 
 module.exports = {
+  ALWAYS_RUN_RISK_TEST_TARGETS,
+  buildTestExecutionPlan,
   classifyPushTests,
   detectPackageManager,
+  runLocalValidationTests,
   runPrePushTests,
+  runTestExecutionPlan,
   stripGitHookEnv,
 };

package/scripts/validate.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+const bunCommand = process.env.BUN_EXE || 'bun';
+
+function color(code, text) {
+  return process.stdout.isTTY ? `\u001b[${code}m${text}\u001b[0m` : text;
+}
+
+function printHeader(title) {
+  const line = '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━';
+  console.log('');
+  console.log(color('0;34', line));
+  console.log(color('0;34', `▶ ${title}`));
+  console.log(color('0;34', line));
+}
+
+function printStatus(kind, message) {
+  const palette = {
+    error: ['0;31', '✗'],
+    success: ['0;32', '✓'],
+    warning: ['1;33', '⚠'],
+  };
+  const [code, prefix] = palette[kind];
+  console.log(color(code, `${prefix} ${message}`));
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+    stdio: options.captureOutput ? ['inherit', 'pipe', 'pipe'] : 'inherit',
+    shell: false,
+    env: options.env || process.env,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  return result;
+}
+
+function combinedOutput(result) {
+  return [result.stdout, result.stderr].filter(Boolean).join('');
+}
+
+function hasBlockingAuditSeverity(output = '') {
+  if (typeof output !== 'string' || output.length === 0) {
+    return false;
+  }
+
+  return [
+    /\b(?:critical|high)\s+severity\b/i,
+    /\bseverity\s*:?\s*(?:critical|high)\b/i,
+  ].some((pattern) => pattern.test(output));
+}
+
+function main(options = {}) {
+  const runCommand = options.runCommand ?? run;
+  const activeBunCommand = options.bunCommand ?? bunCommand;
+  console.log('');
+  console.log(color('0;34', '╔═══════════════════════════════════════════╗'));
+  console.log(color('0;34', '║   Forge Quality Gate - Running Checks    ║'));
+  console.log(color('0;34', '╚═══════════════════════════════════════════╝'));
+
+  printHeader('1/4: Type Check');
+  const typecheck = runCommand(activeBunCommand, ['run', 'typecheck'], { captureOutput: true });
+  const typecheckOutput = combinedOutput(typecheck);
+  if (typecheckOutput) {
+    process.stdout.write(typecheckOutput);
+    if (!typecheckOutput.endsWith('\n')) {
+      process.stdout.write('\n');
+    }
+  }
+  if ((typecheck.status ?? 1) !== 0) {
+    printStatus('error', 'Type check failed');
+    return 1;
+  }
+  if (/no typescript in project|skipping type check/i.test(typecheckOutput)) {
+    printStatus('warning', 'SKIPPED (no TypeScript in project)');
+  } else {
+    printStatus('success', 'Type check passed');
+  }
+
+  printHeader('2/4: Lint');
+  const lint = runCommand(activeBunCommand, ['run', 'lint']);
+  if ((lint.status ?? 1) !== 0) {
+    printStatus('error', 'Lint failed');
+    return 1;
+  }
+  printStatus('success', 'Lint passed');
+
+  printHeader('3/4: Security Audit');
+  const audit = runCommand(activeBunCommand, ['audit'], { captureOutput: true });
+  const auditOutput = combinedOutput(audit);
+  if (auditOutput) {
+    process.stdout.write(auditOutput);
+    if (!auditOutput.endsWith('\n')) {
+      process.stdout.write('\n');
+    }
+  }
+  if (hasBlockingAuditSeverity(auditOutput)) {
+    printStatus('error', 'Security audit found critical/high vulnerabilities');
+    return 1;
+  }
+  if ((audit.status ?? 1) === 0) {
+    printStatus('success', 'Security audit passed');
+  } else {
+    printStatus('warning', 'Security audit found issues (moderate/low — non-blocking)');
+  }
+
+  printHeader('4/4: Tests');
+  const tests = runCommand('node', ['scripts/test.js', '--validate']);
+  if ((tests.status ?? 1) !== 0) {
+    printStatus('error', 'Tests failed');
+    return 1;
+  }
+  printStatus('success', 'All tests passed');
+
+  console.log('');
+  console.log(color('0;32', '╔═══════════════════════════════════════════╗'));
+  console.log(color('0;32', '║     ✓ All Checks Passed Successfully     ║'));
+  console.log(color('0;32', '╚═══════════════════════════════════════════╝'));
+  console.log('');
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main());
+}
+
+module.exports = {
+  color,
+  combinedOutput,
+  hasBlockingAuditSeverity,
+  main,
+  printHeader,
+  printStatus,
+  run,
+};

package/scripts/validate.sh

@@ -44,6 +44,23 @@ print_warning() {
   echo -e "${YELLOW}⚠ $1${NC}"
 }
 
+run_validate_tests() {
+  if [[ "${OS:-}" == "Windows_NT" && ( -n "${MSYSTEM:-}" || "${OSTYPE:-}" == msys* || "${OSTYPE:-}" == cygwin* ) ]]; then
+    local bun_exe
+    bun_exe="$(where.exe bun 2>/dev/null | tr -d '\r' | grep -i 'bun\.exe$' | head -n 1)"
+
+    if [[ -n "$bun_exe" ]]; then
+      cmd.exe /d /c "set \"BUN_EXE=$bun_exe\" && node scripts\\test.js --validate"
+      return $?
+    fi
+
+    cmd.exe /d /c "node scripts\\test.js --validate"
+    return $?
+  fi
+
+  node scripts/test.js --validate
+}
+
 echo ""
 echo -e "${BLUE}╔═══════════════════════════════════════════╗${NC}"
 echo -e "${BLUE}║   Forge Quality Gate - Running Checks    ║${NC}"
@@ -78,7 +95,7 @@ fi
 
 # Step 4: Tests
 print_header "4/4: Tests"
-if bun test; then
+if run_validate_tests; then
   print_success "All tests passed"
 else
   print_error "Tests failed"