forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/preflight/gates.js

@@ -0,0 +1,237 @@
+'use strict';
+
+/**
+ * Gate composition + real sub-runners for `forge preflight`.
+ *
+ * Each real runner takes an injectable `spawn` (defaults to spawnSync) so the
+ * composition and the runners are unit-testable without touching the shell.
+ * The four gates give DETERMINISTIC-GATE PARITY with CI on the blast radius of
+ * a change, without the slow full matrix:
+ *
+ *   1. lint     — eslint --max-warnings 0 on changed files (or all with --all)
+ *   2. drift    — skills-mirror + registry-sync + agentic-workflow structural asserts
+ *   3. sonar    — eslint-plugin-sonarjs (cognitive-complexity=15 + parity rules)
+ *   4. affected — only the tests mapped from the changed files
+ *
+ * @module preflight/gates
+ */
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
+const nodeFs = require('node:fs');
+const { getAffectedTestFiles } = require('../commands/test');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/** Filter a changed-file list down to the JS files eslint should look at. */
+function lintableFiles(files) {
+  if (!Array.isArray(files)) return [];
+  return files.filter((f) => /\.(mjs|cjs|js)$/.test(f) && !f.includes('node_modules'));
+}
+
+/** Short, bounded summary for a spawn result. */
+function statusSummary(result, okMsg, failMsg) {
+  return result && result.status === 0
+    ? { ok: true, summary: okMsg }
+    : { ok: false, summary: failMsg };
+}
+
+/**
+ * Gate 1 — ESLint on the change blast radius (or the whole tree with --all).
+ * `files === null` means "lint everything" (`eslint .`).
+ */
+function runEslint(files, { projectRoot, spawn = spawnSync } = {}) {
+  const lintAll = files === null;
+  const targets = lintAll ? ['.'] : lintableFiles(files);
+  if (targets.length === 0) {
+    return { ok: true, summary: 'no changed JS files' };
+  }
+  const result = spawn(
+    'npx',
+    ['eslint', '--max-warnings', '0', ...targets],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    result,
+    lintAll ? 'whole tree clean' : `${targets.length} changed file(s) clean`,
+    'eslint reported errors/warnings',
+  );
+}
+
+/**
+ * Gate 2 — deterministic structural asserts that CI enforces:
+ *   - skills mirror drift (test/structural/skills-sync-drift.test.js)
+ *   - SUBCOMMANDS<->ISSUE_COMMANDS registry sync (test/commands/_resolve-command-opts.test.js)
+ *   - committed agentic-workflow mirror (scripts/sync-agentic-workflow.js --check)
+ */
+function runStructural({ projectRoot, spawn = spawnSync, fs = nodeFs } = {}) {
+  const exists = (rel) => {
+    try {
+      return fs.existsSync(path.join(projectRoot, rel));
+    } catch {
+      return false;
+    }
+  };
+
+  // These are Forge's OWN internal structural asserts. A consumer repo does not
+  // contain them and can NEVER satisfy them, so only run the ones that actually
+  // exist in this project. If none do, the gate is not applicable here — report
+  // an explicit SKIP rather than a false pass or an impossible failure.
+  const structuralTests = [
+    'test/structural/skills-sync-drift.test.js',
+    'test/commands/_resolve-command-opts.test.js',
+  ].filter(exists);
+  const agenticScript = 'scripts/sync-agentic-workflow.js';
+  const hasAgentic = exists(agenticScript);
+
+  if (structuralTests.length === 0 && !hasAgentic) {
+    return {
+      ok: true,
+      skipped: true,
+      summary: 'no Forge-internal structural checks in this repo (consumer context)',
+    };
+  }
+
+  if (structuralTests.length > 0) {
+    const bun = spawn(
+      'bun',
+      ['test', '--timeout', '15000', ...structuralTests],
+      { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+    );
+    if (!bun || bun.status !== 0) {
+      return { ok: false, summary: 'skills-mirror / registry-sync asserts failed' };
+    }
+  }
+
+  if (!hasAgentic) {
+    return { ok: true, summary: 'skills + registry in sync (no agentic-workflow mirror here)' };
+  }
+
+  const agentic = spawn(
+    'node',
+    [agenticScript, '--check'],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    agentic,
+    'skills + registry + agentic-workflow in sync',
+    'agentic-workflow mirror drift (run: node scripts/sync-agentic-workflow.js)',
+  );
+}
+
+/**
+ * Gate 3 — SonarCloud parity via eslint-plugin-sonarjs, using an isolated flat
+ * config (cognitive-complexity pinned to 15 + the parity rules) so it never
+ * merges with the repo's main eslint config.
+ * `files === null` means "scan everything" (whole-tree `--all` mode) — mirrors
+ * runEslint so `--all` never leaves sonar as a vacuous "no changed files" pass.
+ */
+function runSonar(files, { projectRoot, spawn = spawnSync } = {}) {
+  const scanAll = files === null;
+  const targets = scanAll ? ['.'] : lintableFiles(files);
+  if (targets.length === 0) {
+    return { ok: true, summary: 'no changed JS files' };
+  }
+  const config = path.join(projectRoot, 'scripts', 'preflight-sonar.eslint.config.mjs');
+  const result = spawn(
+    'npx',
+    ['eslint', '--no-config-lookup', '--config', config, '--max-warnings', '0', ...targets],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    result,
+    scanAll ? 'sonarjs clean (whole tree)' : `sonarjs clean (${targets.length} file(s))`,
+    'sonarjs parity violations (e.g. cognitive-complexity > 15)',
+  );
+}
+
+/**
+ * Gate 4 — run ONLY the tests mapped from the changed files (reuses the
+ * pre-push affected-test mapping). No affected tests → fast-lane pass.
+ */
+function runAffectedTests({
+  projectRoot,
+  changedFiles: _changedFiles,
+  spawn = spawnSync,
+  resolveTests,
+} = {}) {
+  const resolver = typeof resolveTests === 'function'
+    ? resolveTests
+    // strict:true so a failed `git diff` THROWS here instead of returning [] —
+    // otherwise a git error would masquerade as "no affected tests" (fast-lane
+    // green), a fail-OPEN. The catch below turns that throw into a closed gate.
+    : () => getAffectedTestFiles(projectRoot, execFileSync, nodeFs, { strict: true });
+  let targets;
+  try {
+    targets = resolver() || [];
+  } catch (err) {
+    // A resolver ERROR must NOT masquerade as "no affected tests" (green).
+    // We could not determine what to run, so fail closed — never a vacuous pass.
+    const reason = err && err.message ? err.message : String(err);
+    return { ok: false, summary: `affected-test resolution failed — fail-closed (${reason})` };
+  }
+  if (targets.length === 0) {
+    return { ok: true, summary: 'no affected tests resolved (fast lane)' };
+  }
+  const result = spawn(
+    'bun',
+    ['test', '--timeout', '15000', ...targets],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    result,
+    `${targets.length} affected test file(s) passed`,
+    'affected tests failed',
+  );
+}
+
+/**
+ * Compose the ordered gate list. Each gate delegates to a sub-runner that can
+ * be injected via `deps` for testing; defaults wire the real runners above.
+ *
+ * @param {Object} args
+ * @param {string} args.projectRoot
+ * @param {string[]} args.changedFiles
+ * @param {boolean} [args.runAll]  - lint/scan whole tree instead of changed files
+ * @param {Object} [args.deps]     - { eslint, structural, sonar, affected }
+ * @returns {{ name: string, run: () => Promise<{ok:boolean, summary?:string}> }[]}
+ */
+function buildGates({ projectRoot, changedFiles = [], runAll = false, deps = {} }) {
+  const eslint = deps.eslint || ((files) => runEslint(files, { projectRoot }));
+  const structural = deps.structural || (() => runStructural({ projectRoot }));
+  const sonar = deps.sonar || ((files) => runSonar(files, { projectRoot }));
+  const affected = deps.affected || (() => runAffectedTests({ projectRoot, changedFiles }));
+
+  // Under --all, scope BOTH lint and sonar to the whole tree (null). Otherwise
+  // sonar would receive changedFiles=[] and report a vacuous "no changed files"
+  // pass while lint scanned everything — a fail-open hole on the remedy path.
+  const scanTargets = runAll ? null : changedFiles;
+
+  // Affected-tests maps from the change set, which is empty under --all. Running
+  // the WHOLE suite here defeats preflight's fast purpose (and hangs on Windows),
+  // so mark it explicitly not-run — never a vacuous green. CI runs the full suite.
+  const affectedGate = runAll
+    ? async () => ({
+      ok: true,
+      skipped: true,
+      summary: 'whole-tree mode (--all): affected-test mapping N/A — run the full suite (CI does)',
+    })
+    : async () => affected();
+
+  return [
+    { name: 'lint', run: async () => eslint(scanTargets) },
+    { name: 'drift/registry/mirror', run: async () => structural() },
+    { name: 'sonar (cognitive-complexity=15)', run: async () => sonar(scanTargets) },
+    { name: 'affected-tests', run: affectedGate },
+  ];
+}
+
+module.exports = {
+  buildGates,
+  lintableFiles,
+  runEslint,
+  runStructural,
+  runSonar,
+  runAffectedTests,
+};

package/lib/preflight/runner.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Fast-fail gate runner for `forge preflight`.
+ *
+ * Executes an ordered list of gates one at a time. The first gate to fail
+ * short-circuits the run: every later gate is reported as `skipped` and never
+ * executed. This keeps preflight FAST — an agent fixes the first broken gate
+ * and re-runs rather than waiting for the whole matrix.
+ *
+ * A gate is `{ name: string, run: () => Promise<{ ok: boolean, summary?: string }> }`.
+ * The sub-runner behind each `run` is injected by the composer (see gates.js),
+ * so this module stays pure and trivially testable.
+ *
+ * @module preflight/runner
+ */
+
+/**
+ * @typedef {Object} GateOutcome
+ * @property {boolean} ok       - Whether the gate passed.
+ * @property {string} [summary] - Short human-readable result line.
+ *
+ * @typedef {Object} Gate
+ * @property {string} name
+ * @property {() => Promise<GateOutcome>} run
+ *
+ * @typedef {Object} GateResult
+ * @property {string} name
+ * @property {boolean|null} ok       - true/false, or null when skipped.
+ * @property {boolean} skipped
+ * @property {string} summary
+ * @property {number} [durationMs]
+ */
+
+/**
+ * Execute a single gate, normalizing thrown errors into a failed outcome.
+ *
+ * @param {Gate} gate
+ * @returns {Promise<GateResult>}
+ */
+async function executeGate(gate) {
+  const started = Date.now();
+  let outcome;
+  try {
+    outcome = await gate.run();
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    outcome = { ok: false, summary: `error: ${message}` };
+  }
+  const durationMs = Date.now() - started;
+  const skipped = !!outcome?.skipped;
+  // A skipped gate is a pass-through: it is neither a pass nor a failure, so it
+  // must never short-circuit later gates (see runGates fast-fail). BUT a skip
+  // must never MASK an explicit failure — a gate that reports {ok:false} has
+  // failed regardless of a skipped flag, so it stays failed and short-circuits.
+  const explicitOk = !!outcome?.ok;
+  const ok = skipped ? outcome?.ok !== false : explicitOk;
+  // Contract: an explicit ok:false can never normalize to a pass. Guards against
+  // a future edit reintroducing the skip-masks-failure bug (4b73b6bf).
+  if (outcome && outcome.ok === false && ok === true) {
+    throw new Error('executeGate contract violation: skipped must not override an explicit ok:false');
+  }
+  return {
+    name: gate.name,
+    ok,
+    skipped,
+    summary: outcome?.summary || '',
+    durationMs,
+  };
+}
+
+/** Live-log label for a gate result — SKIP must never read as PASS. */
+function gateLogMark(result) {
+  if (result.skipped) return 'SKIP';
+  return result.ok ? 'PASS' : 'FAIL';
+}
+
+/**
+ * Run gates in order, fast-failing at the first failure.
+ *
+ * @param {Gate[]} gates
+ * @param {{ log?: (line: string) => void }} [options]
+ * @returns {Promise<{ ok: boolean, results: GateResult[], failedIndex: number }>}
+ */
+async function runGates(gates, options = {}) {
+  const log = typeof options.log === 'function' ? options.log : () => {};
+  const results = [];
+  let ok = true;
+  let failedIndex = -1;
+
+  for (const gate of gates) {
+    if (!ok) {
+      results.push({
+        name: gate.name,
+        ok: null,
+        skipped: true,
+        summary: 'skipped (earlier gate failed)',
+      });
+      continue;
+    }
+
+    const result = await executeGate(gate);
+    results.push(result);
+    const suffix = result.summary ? ` — ${result.summary}` : '';
+    log(`${gateLogMark(result)} ${gate.name}${suffix}`);
+
+    if (!result.ok) {
+      ok = false;
+      failedIndex = results.length - 1;
+    }
+  }
+
+  return { ok, results, failedIndex };
+}
+
+module.exports = { runGates };

package/lib/project-discovery.js

@@ -263,16 +263,6 @@ async function detectInstalledAgents(projectPath) {
           }
         ]
       },
-      {
-        name: 'copilot',
-        checks: [
-          // .github/copilot-instructions.md
-          async () => {
-            const copilotFile = path.join(projectPath, '.github', 'copilot-instructions.md');
-            return fs.existsSync(copilotFile);
-          }
-        ]
-      },
       {
         name: 'cursor',
         checks: [
@@ -283,39 +273,6 @@ async function detectInstalledAgents(projectPath) {
           }
         ]
       },
-      {
-        name: 'cline',
-        checks: [
-          async () => fs.existsSync(path.join(projectPath, '.clinerules')),
-          async () => {
-            const clineDir = path.join(projectPath, '.cline');
-            return fs.existsSync(clineDir) && (await fs.promises.stat(clineDir)).isDirectory();
-          }
-        ]
-      },
-      {
-        name: 'kilocode',
-        checks: [
-          async () => {
-            const kilocodeDir = path.join(projectPath, '.kilocode');
-            return fs.existsSync(kilocodeDir) && (await fs.promises.stat(kilocodeDir)).isDirectory();
-          },
-          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'workflows', 'forge-workflow.md')),
-          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'rules', 'workflow.md')),
-          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'skills', 'forge-workflow', 'SKILL.md'))
-        ]
-      },
-      {
-        name: 'roo',
-        checks: [
-          async () => fs.existsSync(path.join(projectPath, '.roorules')),
-          async () => {
-            const rooDir = path.join(projectPath, '.roo');
-            return fs.existsSync(rooDir) && (await fs.promises.stat(rooDir)).isDirectory();
-          },
-          async () => fs.existsSync(path.join(projectPath, '.roo', 'rules'))
-        ]
-      },
       {
         name: 'codex',
         checks: [
@@ -325,16 +282,6 @@ async function detectInstalledAgents(projectPath) {
             return fs.existsSync(codexDir) && (await fs.promises.stat(codexDir)).isDirectory();
           }
         ]
-      },
-      {
-        name: 'opencode',
-        checks: [
-          // opencode.json file
-          async () => {
-            const opencodeJson = path.join(projectPath, 'opencode.json');
-            return fs.existsSync(opencodeJson);
-          }
-        ]
       }
     ];