@thejoseki/clawform 2.3.0 → 2.3.2

package/src/commands/validate.js

@@ -1,349 +1,349 @@
-import { readFile, writeFile, mkdtemp, rm } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { tmpdir } from 'node:os';
-import { execa } from 'execa';
-import { ValidateTemplateCommand } from '@aws-sdk/client-cloudformation';
-import { logger } from '../lib/logger.js';
-import { cfnClient } from '../lib/aws-client.js';
-import {
-  loadOverrides,
-  filterExpired,
-  injectSuppressions,
-  detectUnauthorizedSuppressions,
-} from '../lib/lint-overrides.js';
-import { assertLicensed } from '../lib/license.js';
-import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
-
-const LINT_LEVEL = { Error: 'E', Warning: 'W', Informational: 'I' };
-const OVERRIDES_PATH = join(process.cwd(), 'rules', 'lint-overrides.md');
-const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
-
-// cfn-guard rules ship with the clawform package. A consumer project that
-// installed clawform (plugin cache / node_modules) has no `rules.guard/` in
-// cwd — resolving relative to cwd used to make cfn-guard exit non-zero
-// ("missing rules dir"), which was counted as a CRITICAL and failed every
-// validate for exactly the installed-plugin case. Resolve from the package
-// root; a project-local `rules.guard/` (consumer-authored rules) wins when
-// present so consumers can extend without forking.
-export function resolveGuardRulesDir({ cwd = process.cwd(), pkgRoot = PKG_ROOT } = {}) {
-  const local = join(cwd, 'rules.guard');
-  if (existsSync(local)) return local;
-  return join(pkgRoot, 'rules.guard');
-}
-
-export default async function validate({ file, skipAws = false }) {
-  await assertLicensed({ command: 'validate', client: resolveLicenseClient() });
-  logger.step(`clawform validate ${file}`);
-  const body = await readFile(file, 'utf8');
-
-  const lint = await runCfnLint(file);
-  const nag = await runCfnNag(file);
-
-  // Wave 3 overrides hook: load the audited allowlist, partition expired,
-  // inject active suppressions into a temp copy for cfn-guard, then run the
-  // anti-rot check against the ORIGINAL template (inline suppressions without
-  // an overrides row are folded into the critical count and gate /deploy).
-  const overrides = loadOverrides(OVERRIDES_PATH);
-  const { active, expired } = filterExpired(overrides, new Date());
-  for (const e of expired) {
-    logger.warn(
-      `lint-override expired ${e.ruleId} (scope=${e.scopeGlob}, expired ${e.expires.toISOString().slice(0, 10)}). ` +
-      `Re-evaluate in rules/lint-overrides.md or remove the row.`,
-    );
-  }
-
-  const { guard, unauthorized } = await runCfnGuardWithOverrides(file, body, active);
-
-  for (const u of unauthorized) {
-    logger.error(`unauthorized inline SuppressedRules: ${u.resourceId} suppresses ${u.ruleId} with no rules/lint-overrides.md row`);
-  }
-
-  const aws = skipAws ? null : await runValidateTemplate(body);
-
-  const critical =
-    (lint?.errors ?? 0) + (nag?.failures ?? 0) + (guard?.failures ?? 0) + (aws?.errors ?? 0)
-    + unauthorized.length;
-  const warnings = (lint?.warnings ?? 0) + (nag?.warnings ?? 0) + (guard?.warnings ?? 0);
-  // A "skipped" tool contributes 0 errors AND 0 warnings under nullish-coalescing —
-  // before this gate, a fresh dev box with no cfn-lint / cfn-nag installed would
-  // print "All checks passed" exit 0 even though the only thing that ran was the
-  // shallow CloudFormation ValidateTemplate. That silently bypasses every Layer-2
-  // rule the rule files promise (W11/W12/F2/W2/W9/W35/W74/W2001/...).
-  const skipped = [
-    lint?.skipped ? 'cfn-lint' : null,
-    nag?.skipped ? 'cfn-nag' : null,
-    guard?.skipped ? 'cfn-guard' : null,
-    !aws ? 'ValidateTemplate (--skip-aws)' : null,
-  ].filter(Boolean);
-
-  logger.info('');
-  logger.info('Summary:');
-  logger.info(`  cfn-lint       ${formatCount(lint)}`);
-  logger.info(`  cfn-nag        ${formatCount(nag)}`);
-  logger.info(`  cfn-guard      ${formatCount(guard)}`);
-  logger.info(`  ValidateTemplate ${formatCount(aws)}`);
-  // Surface unauthorized inline suppressions in the Summary so a clean
-  // lint/nag/guard run still gives the user a visible cause for exit 1.
-  logger.info(`  lint-overrides ${unauthorized.length === 0 ? '✓ clean' : `🔴 ${unauthorized.length} unauthorized suppression(s)`}`);
-
-  if (critical > 0) {
-    logger.error(`${critical} CRITICAL finding(s). Fix before /deploy.`);
-    process.exit(1);
-  } else if (warnings > 0) {
-    logger.warn(`${warnings} warning(s). Review then proceed.`);
-  } else if (skipped.length > 0) {
-    // Don't print "All checks passed" when we didn't actually run every check.
-    logger.warn(
-      `Partial pass — ${skipped.length} tool(s) skipped: ${skipped.join(', ')}. ` +
-      `Install missing tools (pip install cfn-lint / gem install cfn-nag / cargo install cfn-guard --locked) before relying on this as a deploy gate.`,
-    );
-  } else {
-    logger.ok('All checks passed.');
-  }
-}
-
-function formatCount(r) {
-  if (!r) return '⊘ skipped';
-  if (r.skipped) return `⊘ skipped (${r.skipReason})`;
-  const e = r.errors ?? r.failures ?? 0;
-  const w = r.warnings ?? 0;
-  if (e === 0 && w === 0) return '✓ clean';
-  return `${e ? '🔴' : '🟡'} ${e} error(s), ${w} warning(s)`;
-}
-
-// Exported for unit tests (validate-runners.test.js). The default export is
-// still the orchestrator — these helpers stay internal to validate(), but the
-// runner tests need to drive them directly with a mocked execa.
-export async function runCfnLint(file) {
-  const result = await execa('cfn-lint', ['--format', 'json', file], { reject: false });
-  if (toolMissing(result)) {
-    logger.warn('cfn-lint not found. Install: pip install cfn-lint');
-    return { skipped: true, skipReason: 'not installed' };
-  }
-  const stdout = result.stdout ?? '';
-  const stderr = result.stderr ?? '';
-
-  // M4 — cfn-lint exits non-zero on rule-engine errors (bad template path,
-  // unrecognized flag, broken plugin). Previously we fell through to JSON.parse
-  // and either crashed (M5) or silently returned 0/0. Surface a real error so
-  // /deploy is gated. cfn-lint ALSO exits non-zero when it just found
-  // findings — those are handled below via parsed JSON, so we only fail loud
-  // when stdout has no parseable findings AND stderr looks like a tool error.
-  // Empty stdout is valid (no findings) — short-circuit before the JSON path.
-  if (!stdout.trim()) {
-    if (result.failed && stderr.trim()) {
-      const firstLine = stderr.split(/\r?\n/)[0].trim();
-      return { errors: 1, warnings: 0, message: `cfn-lint exited non-zero: ${firstLine}` };
-    }
-    return { errors: 0, warnings: 0 };
-  }
-
-  // M5 — guard JSON.parse so a malformed stdout (rule-engine crashed mid-output,
-  // or cfn-lint printed a non-JSON banner) surfaces as a finding rather than
-  // crashing the whole validate command.
-  let findings;
-  try {
-    findings = JSON.parse(stdout);
-  } catch {
-    const preview = stdout.slice(0, 100).replace(/\s+/g, ' ');
-    return {
-      errors: 1,
-      warnings: 0,
-      message: `cfn-lint returned non-JSON output (length ${stdout.length}): ${preview}`,
-    };
-  }
-  // P1 — JSON.parse can succeed on shapes that aren't a findings array
-  // (e.g. cfn-lint plugin returning `{ "error": "..." }`, or stdout being
-  // a bare `null`/string/number from a wrapped script). Surface as a
-  // warning so /deploy is not silently gated on a shape we can't iterate.
-  if (!Array.isArray(findings)) {
-    logger.warn(`cfn-lint returned unexpected JSON shape: ${typeof findings}`);
-    return { errors: 0, warnings: 1 };
-  }
-  let errors = 0;
-  let warnings = 0;
-  for (const f of findings) {
-    const lvl = LINT_LEVEL[f.Level] ?? 'I';
-    if (lvl === 'E') {
-      errors++;
-      logger.error(`cfn-lint ${f.Rule?.Id ?? ''} ${f.Location?.Start ? `L${f.Location.Start.LineNumber}` : ''}: ${f.Message}`);
-    } else if (lvl === 'W') {
-      warnings++;
-      logger.warn(`cfn-lint ${f.Rule?.Id ?? ''}: ${f.Message}`);
-    }
-  }
-  return { errors, warnings };
-}
-
-export async function runCfnNag(file) {
-  const cmd = process.platform === 'win32' ? 'cfn_nag_scan.bat' : 'cfn_nag_scan';
-  // P3 — use the short form `-o json` for the output-format flag. Both `-o`
-  // and `--output-format` are valid cfn-nag flags, but the test suite asserts
-  // the short form so that a future refactor doesn't silently drop into
-  // cfn-nag's default text output (which would trip the M5 JSON.parse catch
-  // as a false-positive critical finding on every run).
-  const result = await execa(cmd, ['--input-path', file, '-o', 'json'], { reject: false });
-  if (toolMissing(result)) {
-    logger.warn('cfn-nag not found. Install: gem install cfn-nag');
-    return { skipped: true, skipReason: 'not installed' };
-  }
-  const stdout = result.stdout ?? '';
-  const stderr = result.stderr ?? '';
-
-  // M4 — cfn-nag exits non-zero when violations are found AND when the tool
-  // itself fails (broken ruby env, malformed template path). cfn-nag with no
-  // findings emits a JSON array, so empty stdout typically means the tool
-  // crashed before producing output — surface that loudly instead of masking
-  // it as failures: 0.
-  if (!stdout.trim()) {
-    if (result.failed && stderr.trim()) {
-      const firstLine = stderr.split(/\r?\n/)[0].trim();
-      return { failures: 1, warnings: 0, message: `cfn-nag exited non-zero: ${firstLine}` };
-    }
-    // P2 — exit 0 with empty stdout is suspicious: even a clean cfn-nag run
-    // emits `[]` (or the per-file JSON array). True empty stdout usually means
-    // a wrapper/redirect ate the output. Emit an observability nudge but
-    // don't false-fail — we already know the tool exited clean.
-    logger.warn('cfn-nag produced no output (expected JSON findings array, empty)');
-    return { failures: 0, warnings: 0 };
-  }
-
-  // M5 — guard JSON.parse so a malformed stdout (ruby stack-trace, banner
-  // text from a flag mismatch) surfaces as a finding rather than crashing
-  // the whole validate command.
-  let parsed;
-  try {
-    parsed = JSON.parse(stdout);
-  } catch {
-    const preview = stdout.slice(0, 100).replace(/\s+/g, ' ');
-    return {
-      failures: 1,
-      warnings: 0,
-      message: `cfn-nag returned non-JSON output (length ${stdout.length}): ${preview}`,
-    };
-  }
-  // P1 — even with successful JSON parse, the shape must be the per-file
-  // findings array. cfn-nag has historically returned `{ "violations": [...] }`
-  // in some wrappers and a bare object in error cases; either crashes the
-  // for..of below. Surface as a warning instead of an unhandled TypeError.
-  if (!Array.isArray(parsed)) {
-    logger.warn(`cfn-nag returned unexpected JSON shape: ${typeof parsed}`);
-    return { failures: 0, warnings: 1 };
-  }
-  let failures = 0;
-  let warnings = 0;
-  for (const entry of parsed) {
-    for (const v of entry.file_results?.violations ?? []) {
-      if (v.type === 'FAIL') {
-        failures++;
-        logger.error(`cfn-nag ${v.id}: ${v.message} (${v.logical_resource_ids?.join(', ') ?? ''})`);
-      } else if (v.type === 'WARN') {
-        warnings++;
-        logger.warn(`cfn-nag ${v.id}: ${v.message}`);
-      }
-    }
-  }
-  return { failures, warnings };
-}
-
-// Wraps runCfnGuard with the Wave 3 overrides flow: when there are no active
-// overrides, run cfn-guard against the original file (preserves the test
-// surface of runCfnGuard). When there are, write the injected copy to a
-// tmpdir and run cfn-guard against that temp path; clean up regardless.
-// Also runs the anti-rot detector against the ORIGINAL template body.
-async function runCfnGuardWithOverrides(file, body, activeOverrides) {
-  const unauthorized = detectUnauthorizedSuppressions(body, activeOverrides);
-  if (activeOverrides.length === 0) {
-    return { guard: await runCfnGuard(file), unauthorized };
-  }
-  const injected = injectSuppressions(body, activeOverrides);
-  const dir = await mkdtemp(join(tmpdir(), 'clawform-validate-'));
-  const tempPath = join(dir, 'template.yaml');
-  try {
-    await writeFile(tempPath, injected, 'utf8');
-    const guard = await runCfnGuard(tempPath);
-    return { guard, unauthorized };
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-}
-
-async function runCfnGuard(file) {
-  // Probe for the binary first so a missing install yields a clean "skipped"
-  // instead of confusing rule-engine output.
-  const probe = await execa('cfn-guard', ['--version'], { reject: false });
-  if (toolMissing(probe)) {
-    logger.warn('cfn-guard not found. Install: cargo install cfn-guard --locked');
-    return { skipped: true, skipReason: 'not installed' };
-  }
-
-  const result = await execa(
-    'cfn-guard',
-    [
-      'validate',
-      '-d',
-      file,
-      '-r',
-      resolveGuardRulesDir(),
-      '--show-summary',
-      'all',
-      '--output-format',
-      'single-line-summary',
-    ],
-    { reject: false },
-  );
-
-  const stdout = result.stdout ?? '';
-  const stderr = result.stderr ?? '';
-
-  // cfn-guard exits non-zero when any rule fails. Each failing rule line is
-  // surfaced as a critical finding; cfn-guard 3.x does not have a "warning"
-  // severity, so everything that fires is counted as a failure.
-  let failures = 0;
-  const warnings = 0;
-  if (result.exitCode !== 0) {
-    const lines = stdout.split(/\r?\n/).filter((l) => l.trim());
-    for (const line of lines) {
-      // single-line-summary emits one line per rule outcome; only count FAIL.
-      if (/\bFAIL\b/i.test(line) || /Status\s*=\s*FAIL/i.test(line)) {
-        failures++;
-        logger.error(`cfn-guard ${line.trim()}`);
-      }
-    }
-    if (failures === 0) {
-      // Non-zero exit but no parseable FAIL line — surface raw output so the
-      // user can debug rule-engine errors (bad rule syntax, missing rules dir).
-      failures = 1;
-      logger.error(`cfn-guard: ${stderr.trim() || stdout.trim() || 'non-zero exit'}`);
-    }
-  }
-  return { failures, warnings };
-}
-
-function toolMissing(r) {
-  if (!r.failed) return false;
-  const stderr = r.stderr ?? '';
-  const msg = r.shortMessage ?? r.message ?? '';
-  // Linux/Mac: spawn ENOENT. Windows cmd: "is not recognized as an internal or external command".
-  return r.code === 'ENOENT'
-    || r.errno === -2
-    || /\bENOENT\b/i.test(msg)
-    || /is not recognized as an internal or external command/i.test(stderr)
-    || /command not found/i.test(stderr);
-}
-
-async function runValidateTemplate(body) {
-  try {
-    const client = cfnClient();
-    const out = await client.send(new ValidateTemplateCommand({ TemplateBody: body }));
-    if (out.Capabilities?.length) {
-      logger.info(`Template requires capabilities: ${out.Capabilities.join(', ')} — pass via --capabilities on deploy.`);
-    }
-    return { errors: 0, warnings: 0 };
-  } catch (err) {
-    logger.error(`ValidateTemplate: ${err.message}`);
-    return { errors: 1, warnings: 0 };
-  }
-}
+import { readFile, writeFile, mkdtemp, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+import { execa } from 'execa';
+import { ValidateTemplateCommand } from '@aws-sdk/client-cloudformation';
+import { logger } from '../lib/logger.js';
+import { cfnClient } from '../lib/aws-client.js';
+import {
+  loadOverrides,
+  filterExpired,
+  injectSuppressions,
+  detectUnauthorizedSuppressions,
+} from '../lib/lint-overrides.js';
+import { assertLicensed } from '../lib/license.js';
+import { resolveClient as resolveLicenseClient } from '../lib/license-client.js';
+
+const LINT_LEVEL = { Error: 'E', Warning: 'W', Informational: 'I' };
+const OVERRIDES_PATH = join(process.cwd(), 'rules', 'lint-overrides.md');
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// cfn-guard rules ship with the clawform package. A consumer project that
+// installed clawform (plugin cache / node_modules) has no `rules.guard/` in
+// cwd — resolving relative to cwd used to make cfn-guard exit non-zero
+// ("missing rules dir"), which was counted as a CRITICAL and failed every
+// validate for exactly the installed-plugin case. Resolve from the package
+// root; a project-local `rules.guard/` (consumer-authored rules) wins when
+// present so consumers can extend without forking.
+export function resolveGuardRulesDir({ cwd = process.cwd(), pkgRoot = PKG_ROOT } = {}) {
+  const local = join(cwd, 'rules.guard');
+  if (existsSync(local)) return local;
+  return join(pkgRoot, 'rules.guard');
+}
+
+export default async function validate({ file, skipAws = false }) {
+  await assertLicensed({ command: 'validate', client: resolveLicenseClient() });
+  logger.step(`clawform validate ${file}`);
+  const body = await readFile(file, 'utf8');
+
+  const lint = await runCfnLint(file);
+  const nag = await runCfnNag(file);
+
+  // Wave 3 overrides hook: load the audited allowlist, partition expired,
+  // inject active suppressions into a temp copy for cfn-guard, then run the
+  // anti-rot check against the ORIGINAL template (inline suppressions without
+  // an overrides row are folded into the critical count and gate /deploy).
+  const overrides = loadOverrides(OVERRIDES_PATH);
+  const { active, expired } = filterExpired(overrides, new Date());
+  for (const e of expired) {
+    logger.warn(
+      `lint-override expired ${e.ruleId} (scope=${e.scopeGlob}, expired ${e.expires.toISOString().slice(0, 10)}). ` +
+      `Re-evaluate in rules/lint-overrides.md or remove the row.`,
+    );
+  }
+
+  const { guard, unauthorized } = await runCfnGuardWithOverrides(file, body, active);
+
+  for (const u of unauthorized) {
+    logger.error(`unauthorized inline SuppressedRules: ${u.resourceId} suppresses ${u.ruleId} with no rules/lint-overrides.md row`);
+  }
+
+  const aws = skipAws ? null : await runValidateTemplate(body);
+
+  const critical =
+    (lint?.errors ?? 0) + (nag?.failures ?? 0) + (guard?.failures ?? 0) + (aws?.errors ?? 0)
+    + unauthorized.length;
+  const warnings = (lint?.warnings ?? 0) + (nag?.warnings ?? 0) + (guard?.warnings ?? 0);
+  // A "skipped" tool contributes 0 errors AND 0 warnings under nullish-coalescing —
+  // before this gate, a fresh dev box with no cfn-lint / cfn-nag installed would
+  // print "All checks passed" exit 0 even though the only thing that ran was the
+  // shallow CloudFormation ValidateTemplate. That silently bypasses every Layer-2
+  // rule the rule files promise (W11/W12/F2/W2/W9/W35/W74/W2001/...).
+  const skipped = [
+    lint?.skipped ? 'cfn-lint' : null,
+    nag?.skipped ? 'cfn-nag' : null,
+    guard?.skipped ? 'cfn-guard' : null,
+    !aws ? 'ValidateTemplate (--skip-aws)' : null,
+  ].filter(Boolean);
+
+  logger.info('');
+  logger.info('Summary:');
+  logger.info(`  cfn-lint       ${formatCount(lint)}`);
+  logger.info(`  cfn-nag        ${formatCount(nag)}`);
+  logger.info(`  cfn-guard      ${formatCount(guard)}`);
+  logger.info(`  ValidateTemplate ${formatCount(aws)}`);
+  // Surface unauthorized inline suppressions in the Summary so a clean
+  // lint/nag/guard run still gives the user a visible cause for exit 1.
+  logger.info(`  lint-overrides ${unauthorized.length === 0 ? '✓ clean' : `🔴 ${unauthorized.length} unauthorized suppression(s)`}`);
+
+  if (critical > 0) {
+    logger.error(`${critical} CRITICAL finding(s). Fix before /deploy.`);
+    process.exit(1);
+  } else if (warnings > 0) {
+    logger.warn(`${warnings} warning(s). Review then proceed.`);
+  } else if (skipped.length > 0) {
+    // Don't print "All checks passed" when we didn't actually run every check.
+    logger.warn(
+      `Partial pass — ${skipped.length} tool(s) skipped: ${skipped.join(', ')}. ` +
+      `Install missing tools (pip install cfn-lint / gem install cfn-nag / cargo install cfn-guard --locked) before relying on this as a deploy gate.`,
+    );
+  } else {
+    logger.ok('All checks passed.');
+  }
+}
+
+function formatCount(r) {
+  if (!r) return '⊘ skipped';
+  if (r.skipped) return `⊘ skipped (${r.skipReason})`;
+  const e = r.errors ?? r.failures ?? 0;
+  const w = r.warnings ?? 0;
+  if (e === 0 && w === 0) return '✓ clean';
+  return `${e ? '🔴' : '🟡'} ${e} error(s), ${w} warning(s)`;
+}
+
+// Exported for unit tests (validate-runners.test.js). The default export is
+// still the orchestrator — these helpers stay internal to validate(), but the
+// runner tests need to drive them directly with a mocked execa.
+export async function runCfnLint(file) {
+  const result = await execa('cfn-lint', ['--format', 'json', file], { reject: false });
+  if (toolMissing(result)) {
+    logger.warn('cfn-lint not found. Install: pip install cfn-lint');
+    return { skipped: true, skipReason: 'not installed' };
+  }
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  // M4 — cfn-lint exits non-zero on rule-engine errors (bad template path,
+  // unrecognized flag, broken plugin). Previously we fell through to JSON.parse
+  // and either crashed (M5) or silently returned 0/0. Surface a real error so
+  // /deploy is gated. cfn-lint ALSO exits non-zero when it just found
+  // findings — those are handled below via parsed JSON, so we only fail loud
+  // when stdout has no parseable findings AND stderr looks like a tool error.
+  // Empty stdout is valid (no findings) — short-circuit before the JSON path.
+  if (!stdout.trim()) {
+    if (result.failed && stderr.trim()) {
+      const firstLine = stderr.split(/\r?\n/)[0].trim();
+      return { errors: 1, warnings: 0, message: `cfn-lint exited non-zero: ${firstLine}` };
+    }
+    return { errors: 0, warnings: 0 };
+  }
+
+  // M5 — guard JSON.parse so a malformed stdout (rule-engine crashed mid-output,
+  // or cfn-lint printed a non-JSON banner) surfaces as a finding rather than
+  // crashing the whole validate command.
+  let findings;
+  try {
+    findings = JSON.parse(stdout);
+  } catch {
+    const preview = stdout.slice(0, 100).replace(/\s+/g, ' ');
+    return {
+      errors: 1,
+      warnings: 0,
+      message: `cfn-lint returned non-JSON output (length ${stdout.length}): ${preview}`,
+    };
+  }
+  // P1 — JSON.parse can succeed on shapes that aren't a findings array
+  // (e.g. cfn-lint plugin returning `{ "error": "..." }`, or stdout being
+  // a bare `null`/string/number from a wrapped script). Surface as a
+  // warning so /deploy is not silently gated on a shape we can't iterate.
+  if (!Array.isArray(findings)) {
+    logger.warn(`cfn-lint returned unexpected JSON shape: ${typeof findings}`);
+    return { errors: 0, warnings: 1 };
+  }
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    const lvl = LINT_LEVEL[f.Level] ?? 'I';
+    if (lvl === 'E') {
+      errors++;
+      logger.error(`cfn-lint ${f.Rule?.Id ?? ''} ${f.Location?.Start ? `L${f.Location.Start.LineNumber}` : ''}: ${f.Message}`);
+    } else if (lvl === 'W') {
+      warnings++;
+      logger.warn(`cfn-lint ${f.Rule?.Id ?? ''}: ${f.Message}`);
+    }
+  }
+  return { errors, warnings };
+}
+
+export async function runCfnNag(file) {
+  const cmd = process.platform === 'win32' ? 'cfn_nag_scan.bat' : 'cfn_nag_scan';
+  // P3 — use the short form `-o json` for the output-format flag. Both `-o`
+  // and `--output-format` are valid cfn-nag flags, but the test suite asserts
+  // the short form so that a future refactor doesn't silently drop into
+  // cfn-nag's default text output (which would trip the M5 JSON.parse catch
+  // as a false-positive critical finding on every run).
+  const result = await execa(cmd, ['--input-path', file, '-o', 'json'], { reject: false });
+  if (toolMissing(result)) {
+    logger.warn('cfn-nag not found. Install: gem install cfn-nag');
+    return { skipped: true, skipReason: 'not installed' };
+  }
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  // M4 — cfn-nag exits non-zero when violations are found AND when the tool
+  // itself fails (broken ruby env, malformed template path). cfn-nag with no
+  // findings emits a JSON array, so empty stdout typically means the tool
+  // crashed before producing output — surface that loudly instead of masking
+  // it as failures: 0.
+  if (!stdout.trim()) {
+    if (result.failed && stderr.trim()) {
+      const firstLine = stderr.split(/\r?\n/)[0].trim();
+      return { failures: 1, warnings: 0, message: `cfn-nag exited non-zero: ${firstLine}` };
+    }
+    // P2 — exit 0 with empty stdout is suspicious: even a clean cfn-nag run
+    // emits `[]` (or the per-file JSON array). True empty stdout usually means
+    // a wrapper/redirect ate the output. Emit an observability nudge but
+    // don't false-fail — we already know the tool exited clean.
+    logger.warn('cfn-nag produced no output (expected JSON findings array, empty)');
+    return { failures: 0, warnings: 0 };
+  }
+
+  // M5 — guard JSON.parse so a malformed stdout (ruby stack-trace, banner
+  // text from a flag mismatch) surfaces as a finding rather than crashing
+  // the whole validate command.
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    const preview = stdout.slice(0, 100).replace(/\s+/g, ' ');
+    return {
+      failures: 1,
+      warnings: 0,
+      message: `cfn-nag returned non-JSON output (length ${stdout.length}): ${preview}`,
+    };
+  }
+  // P1 — even with successful JSON parse, the shape must be the per-file
+  // findings array. cfn-nag has historically returned `{ "violations": [...] }`
+  // in some wrappers and a bare object in error cases; either crashes the
+  // for..of below. Surface as a warning instead of an unhandled TypeError.
+  if (!Array.isArray(parsed)) {
+    logger.warn(`cfn-nag returned unexpected JSON shape: ${typeof parsed}`);
+    return { failures: 0, warnings: 1 };
+  }
+  let failures = 0;
+  let warnings = 0;
+  for (const entry of parsed) {
+    for (const v of entry.file_results?.violations ?? []) {
+      if (v.type === 'FAIL') {
+        failures++;
+        logger.error(`cfn-nag ${v.id}: ${v.message} (${v.logical_resource_ids?.join(', ') ?? ''})`);
+      } else if (v.type === 'WARN') {
+        warnings++;
+        logger.warn(`cfn-nag ${v.id}: ${v.message}`);
+      }
+    }
+  }
+  return { failures, warnings };
+}
+
+// Wraps runCfnGuard with the Wave 3 overrides flow: when there are no active
+// overrides, run cfn-guard against the original file (preserves the test
+// surface of runCfnGuard). When there are, write the injected copy to a
+// tmpdir and run cfn-guard against that temp path; clean up regardless.
+// Also runs the anti-rot detector against the ORIGINAL template body.
+async function runCfnGuardWithOverrides(file, body, activeOverrides) {
+  const unauthorized = detectUnauthorizedSuppressions(body, activeOverrides);
+  if (activeOverrides.length === 0) {
+    return { guard: await runCfnGuard(file), unauthorized };
+  }
+  const injected = injectSuppressions(body, activeOverrides);
+  const dir = await mkdtemp(join(tmpdir(), 'clawform-validate-'));
+  const tempPath = join(dir, 'template.yaml');
+  try {
+    await writeFile(tempPath, injected, 'utf8');
+    const guard = await runCfnGuard(tempPath);
+    return { guard, unauthorized };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+async function runCfnGuard(file) {
+  // Probe for the binary first so a missing install yields a clean "skipped"
+  // instead of confusing rule-engine output.
+  const probe = await execa('cfn-guard', ['--version'], { reject: false });
+  if (toolMissing(probe)) {
+    logger.warn('cfn-guard not found. Install: cargo install cfn-guard --locked');
+    return { skipped: true, skipReason: 'not installed' };
+  }
+
+  const result = await execa(
+    'cfn-guard',
+    [
+      'validate',
+      '-d',
+      file,
+      '-r',
+      resolveGuardRulesDir(),
+      '--show-summary',
+      'all',
+      '--output-format',
+      'single-line-summary',
+    ],
+    { reject: false },
+  );
+
+  const stdout = result.stdout ?? '';
+  const stderr = result.stderr ?? '';
+
+  // cfn-guard exits non-zero when any rule fails. Each failing rule line is
+  // surfaced as a critical finding; cfn-guard 3.x does not have a "warning"
+  // severity, so everything that fires is counted as a failure.
+  let failures = 0;
+  const warnings = 0;
+  if (result.exitCode !== 0) {
+    const lines = stdout.split(/\r?\n/).filter((l) => l.trim());
+    for (const line of lines) {
+      // single-line-summary emits one line per rule outcome; only count FAIL.
+      if (/\bFAIL\b/i.test(line) || /Status\s*=\s*FAIL/i.test(line)) {
+        failures++;
+        logger.error(`cfn-guard ${line.trim()}`);
+      }
+    }
+    if (failures === 0) {
+      // Non-zero exit but no parseable FAIL line — surface raw output so the
+      // user can debug rule-engine errors (bad rule syntax, missing rules dir).
+      failures = 1;
+      logger.error(`cfn-guard: ${stderr.trim() || stdout.trim() || 'non-zero exit'}`);
+    }
+  }
+  return { failures, warnings };
+}
+
+function toolMissing(r) {
+  if (!r.failed) return false;
+  const stderr = r.stderr ?? '';
+  const msg = r.shortMessage ?? r.message ?? '';
+  // Linux/Mac: spawn ENOENT. Windows cmd: "is not recognized as an internal or external command".
+  return r.code === 'ENOENT'
+    || r.errno === -2
+    || /\bENOENT\b/i.test(msg)
+    || /is not recognized as an internal or external command/i.test(stderr)
+    || /command not found/i.test(stderr);
+}
+
+async function runValidateTemplate(body) {
+  try {
+    const client = cfnClient();
+    const out = await client.send(new ValidateTemplateCommand({ TemplateBody: body }));
+    if (out.Capabilities?.length) {
+      logger.info(`Template requires capabilities: ${out.Capabilities.join(', ')} — pass via --capabilities on deploy.`);
+    }
+    return { errors: 0, warnings: 0 };
+  } catch (err) {
+    logger.error(`ValidateTemplate: ${err.message}`);
+    return { errors: 1, warnings: 0 };
+  }
+}