fix(cli): exit non-zero when wheels validate finds errors (#2907)

* fix(cli): exit non-zero when wheels validate finds errors

wheels validate printed its report and returned "" on every path, so the
process exited 0 even when validation found errors and CI could not gate
on it (framework review H5, same family as #2890 / CLI audit H6).

- errors found: record the failure inside the try, throw
  Wheels.ValidationFailed after the report is flushed (runTests pattern,
  out of reach of the catch-all)
- analyzer crash: the catch now prints then rethrows instead of
  swallowing, matching migrate()
- no app/ directory: throw Wheels.InvalidArguments after the red hint,
  matching the other user-error paths
- warnings-only stays exit 0: results.valid is true when no
  severity=="error" issues exist, so validate remains usable as a soft
  linter; output text and ordering are unchanged

Adds ValidateCommandSpec covering all four paths. Verified locally on the
Lucee 7 docker harness: 4/4 new specs pass, InfoCommandSpec's existing
validate case stays green.

Intentional behavior change: scripts that relied on exit 0 despite
reported errors will now fail; the MCP wheels_validate tool surfaces a
proper tool error instead of a silent empty result. Out of scope: U1
(wheels upgrade check exit code) and the runTests mid-run HTTP
catch-swallow.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Peter Amiri <peter@alurium.com>

* fix(cli): address Reviewer A/B consensus findings (round 1)

- Replace stale "Both commands always exit 0" claim in
  web/sites/guides/.../code-quality.mdx with accurate split:
  validate exits non-zero on errors, analyze always exits 0.
- Condense the two multi-line comment blocks in Module.cfc::validate()
  (3-line and 5-line) to single-line per CLAUDE.md "one short line max"
  convention — invariants preserved, just shorter prose.
- Condense the 11-line component docstring and 4-line $makeProject()
  docstring in ValidateCommandSpec.cfc to single-line comments for the
  same reason.

All changes are pure comment/text edits; no runtime behaviour change.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

* fix(cli): address Reviewer A consensus findings (round 2)

- cli/lucli/tests/specs/commands/ValidateCommandSpec.cfc lines 7-8:
  condense 2-line comment block to single-line per CLAUDE.md
  ("Never write multi-paragraph docstrings or multi-line comment
  blocks — one short line max").
- cli/lucli/tests/specs/commands/ValidateCommandSpec.cfc lines 17-19:
  condense 3-line comment block to single-line, same rule.

Comment-only changes; no runtime behaviour impact. Test bodies and
the four-case coverage matrix are untouched.

Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

---------

Signed-off-by: Peter Amiri <peter@alurium.com>
Signed-off-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: 3 people

cli/lucli/Module.cfc

@@ -1728,12 +1728,16 @@ component extends="modules.BaseModule" {
 	public string function validate() {
 		if (!directoryExists(variables.projectRoot & "/app")) {
 			out("No app/ directory found. Are you in a Wheels project?", "red");
-			return "";
+			// throw maps to non-zero exit; return "" would silently succeed.
+			throw(type = "Wheels.InvalidArguments", message = "No app/ directory found — run wheels validate from a Wheels project root.");
 		}
 
 		out("Validating...", "cyan");
 		out("");
 
+		var validationFailed = false;
+		var issueCount = 0;
+
 		try {
 			var analysis = getService("analysis");
 			var results = analysis.validate();
@@ -1749,8 +1753,19 @@ component extends="modules.BaseModule" {
 				var severity = issue.severity == "error" ? "red" : "yellow";
 				out("  [#uCase(issue.severity)#] #fileName# — #issue.message#", severity);
 			}
+
+			// Capture before try ends; throwing inside would be swallowed by the catch.
+			validationFailed = !results.valid;
+			issueCount = results.totalIssues;
 		} catch (any e) {
 			out("Validation failed: #e.message#", "red");
+			// rethrow maps to non-zero exit; an analyzer crash must not exit 0.
+			rethrow;
+		}
+
+		// Throw after the full report flushes — errors exit non-zero, warnings stay green.
+		if (validationFailed) {
+			throw(type = "Wheels.ValidationFailed", message = "Validation found #issueCount# issue(s) — see the report above.");
 		}
 
 		return "";

cli/lucli/tests/specs/commands/ValidateCommandSpec.cfc

@@ -0,0 +1,75 @@
+// Covers all four validate() exit paths; each case gets its own temp project.
+component extends="wheels.wheelstest.system.BaseSpec" {
+
+	function beforeAll() {
+		variables.roots = [];
+
+		// Missing extends="Model" → Analysis.validateModel error → results.valid = false.
+		variables.errorRoot = $makeProject();
+		fileWrite(variables.errorRoot & "/app/models/Bad.cfc", "component { function config() {} }");
+		variables.errorMod = new cli.lucli.Module(cwd = variables.errorRoot);
+
+		// Project with no offending files at all.
+		variables.cleanRoot = $makeProject();
+		variables.cleanMod = new cli.lucli.Module(cwd = variables.cleanRoot);
+
+		// Hash without cfparam → validateView warning; results.valid stays true.
+		variables.warningRoot = $makeProject();
+		directoryCreate(variables.warningRoot & "/app/views/things", true, true);
+		fileWrite(variables.warningRoot & "/app/views/things/index.cfm", "<p>##foo##</p>");
+		variables.warningMod = new cli.lucli.Module(cwd = variables.warningRoot);
+
+		// Project root with no app/ directory — user-error path.
+		variables.noAppRoot = $makeProject(includeApp = false);
+		variables.noAppMod = new cli.lucli.Module(cwd = variables.noAppRoot);
+	}
+
+	function afterAll() {
+		for (var root in variables.roots) {
+			if (len(root) > 10 && directoryExists(root)) {
+				directoryDelete(root, true);
+			}
+		}
+	}
+
+	// vendor/wheels stub anchors resolveProjectRoot to the temp dir.
+	private string function $makeProject(boolean includeApp = true) {
+		var root = getTempDirectory() & "wheels-cli-validate-" & createUUID();
+		directoryCreate(root & "/vendor/wheels", true, true);
+		if (arguments.includeApp) {
+			directoryCreate(root & "/app/models", true, true);
+			directoryCreate(root & "/app/controllers", true, true);
+			directoryCreate(root & "/app/views", true, true);
+			directoryCreate(root & "/config", true, true);
+		}
+		arrayAppend(variables.roots, root);
+		return root;
+	}
+
+	function run() {
+
+		describe("wheels validate exit codes", () => {
+
+			it("throws Wheels.ValidationFailed when validation finds errors", () => {
+				expect(() => variables.errorMod.validate()).toThrow(type = "Wheels.ValidationFailed");
+			});
+
+			it("returns normally on a clean project", () => {
+				variables.cleanMod.validate();
+				expect(true).toBeTrue();
+			});
+
+			it("stays green when only warnings exist", () => {
+				variables.warningMod.validate();
+				expect(true).toBeTrue();
+			});
+
+			it("throws Wheels.InvalidArguments when no app directory exists", () => {
+				expect(() => variables.noAppMod.validate()).toThrow(type = "Wheels.InvalidArguments");
+			});
+
+		});
+
+	}
+
+}

web/sites/guides/src/content/docs/v4-0-0/command-line-tools/wheels-commands/code-quality.mdx

@@ -140,7 +140,7 @@ wheels validate
 wheels analyze
 ```
 
-Run `validate` first and read its output for any ✗ errors or ⚠ warnings. Then run `analyze` for a broader look at health scores and anti-patterns. Both commands always exit 0 regardless of findings, so read each report before moving on — the results are in the output, not the exit code.
+Run `validate` first and read its output for any ✗ errors or ⚠ warnings. Then run `analyze` for a broader look at health scores and anti-patterns. `wheels validate` exits non-zero when it finds error-severity issues, so you can gate CI on it. `wheels analyze` always exits 0 — its findings live in the output only.
 
 ### Scope the analysis