Sprint 43: CLI Error Consistency + Import Validation — check() now loads imports (catches missing modules), build() emits JSON errors for lex/module/type failures, 4 new CLI regression tests (missing_import fixture), 18 CLI tests total

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sfw

planning/sprints/SPRINT_43_CLI_ERROR_CONSISTENCY.md

@@ -0,0 +1,184 @@
+# Sprint 43: CLI Error Consistency + Import Validation
+
+**Goal:** Close remaining CLI correctness gaps so `run`, `check`, and `build` have consistent import handling and JSON error behavior.
+**Estimated Effort:** 0.5-1 day
+
+---
+
+## Context
+
+Post-Sprint-42 verification still shows two launch-relevant issues:
+
+1. `check --error-format json` reports success for missing imports.
+2. `build --error-format json` can fail silently (non-zero exit, empty JSON output) on early errors.
+
+There is also process confusion around workspace/commit state, so this sprint includes explicit hygiene checks in CI/local verification.
+
+---
+
+## Agent Instructions
+
+1. Treat this as a correctness sprint, not a refactor sprint.
+2. Keep behavior aligned across `run`, `check`, and `build` for module loading and JSON error output.
+3. Add regression tests first-class (must fail before fix, pass after fix).
+4. Do not weaken or skip tests to get green.
+
+---
+
+## Task 43.1: Make `check` Validate Imports
+
+**Priority:** P0
+
+**Files (likely):**
+- `src/main.rs`
+- `src/module/loader.rs` (only if needed)
+- `tests/cli_tests.rs`
+- fixtures under `tests/fixtures/`
+
+### Requirements
+
+1. In `check(...)`, load imports the same way `run(...)` and `build(...)` do.
+2. Missing imports must produce an error (not success) in both human and JSON modes.
+3. Preserve existing `--partial` behavior, but include module errors in the structured response.
+
+### Acceptance Criteria
+
+1. `forma check --error-format json <file-with-missing-import>` returns non-zero and JSON with `success: false` and at least one `MODULE` error.
+2. `forma check <file-with-missing-import>` prints human-readable module error and exits non-zero.
+3. Existing successful-check flows still pass.
+
+---
+
+## Task 43.2: Ensure `build` Always Emits JSON Errors on Failure
+
+**Priority:** P0
+
+**Files (likely):**
+- `src/main.rs`
+- `tests/cli_tests.rs`
+
+### Requirements
+
+1. For all early `build(...)` failure paths (lex/parse/module/type/codegen/link), if `--error-format json` is set, emit a JSON error payload before returning.
+2. Eliminate silent JSON failures (non-zero with empty stdout/stderr JSON body).
+3. Keep current human-format output unchanged.
+
+### Acceptance Criteria
+
+1. `forma build --error-format json <file-with-missing-import>` returns non-zero and prints structured JSON error output.
+2. At least one regression test asserts that build failure in JSON mode is never silent.
+3. No regression in successful build JSON output.
+
+---
+
+## Task 43.3: CLI Parity Regression Tests
+
+**Priority:** P1
+
+**Files (likely):**
+- `tests/cli_tests.rs`
+- `tests/fixtures/missing_import.forma`
+
+### Requirements
+
+1. Add tests covering missing-import behavior for:
+- `run --error-format json`
+- `check --error-format json`
+- `build --error-format json`
+2. Assert parity of key fields (`success`, `code`, non-empty `errors`, exit status).
+
+### Acceptance Criteria
+
+1. All three commands fail consistently on missing import with structured JSON errors.
+2. New tests are deterministic and pass in CI.
+
+---
+
+## Task 43.4: Workspace Hygiene Guardrail
+
+**Priority:** P1
+
+**Files (likely):**
+- `.github/workflows/ci.yml` (optional)
+- docs/PR checklist (optional)
+
+### Requirements
+
+1. Add a lightweight verification step/checklist item in sprint output requiring:
+- `git status --short` capture before final summary
+- explicit list of intentionally untracked files (if any)
+2. Ensure sprint completion summaries clearly distinguish:
+- committed changes
+- uncommitted workspace edits
+
+### Acceptance Criteria
+
+1. Final verification output includes commit hash and clean/dirty status.
+2. No ambiguity about whether fixes are committed.
+
+---
+
+## Verification Checklist
+
+Run and include results in PR summary:
+
+1. `cargo test --all`
+2. `cargo clippy --all-targets -- -D warnings`
+3. `cargo clippy --all-features --all-targets -- -D warnings`
+4. `cargo fmt --all -- --check`
+5. `cargo build --release`
+6. Targeted CLI repros:
+- `forma check --error-format json tests/fixtures/missing_import.forma`
+- `forma build --error-format json tests/fixtures/missing_import.forma`
+- `forma run --error-format json tests/fixtures/missing_import.forma`
+7. `git status --short` and `git log --oneline -n 1`
+
+---
+
+## Out of Scope
+
+1. New module system features.
+2. Capability model changes.
+3. Broad CLI redesign.
+
+---
+
+## Definition of Done
+
+1. `check` no longer reports false success on missing imports.
+2. `build --error-format json` never fails silently.
+3. CLI parity tests cover and lock this behavior.
+4. Sprint summary includes explicit commit/worktree state.
+
+---
+
+## Coding Agent Prompt
+
+```text
+Implement Sprint 43: CLI Error Consistency + Import Validation.
+
+Fix these exact defects:
+1) `forma check --error-format json` currently returns success on missing imports.
+2) `forma build --error-format json` can fail silently (non-zero exit with no JSON error output) on early failures.
+
+Requirements:
+- Make `check` load/validate imports consistently with `run` and `build`.
+- Ensure `build` emits JSON-formatted errors for all failure paths when `--error-format json` is set.
+- Add regression tests in tests/cli_tests.rs using a missing-import fixture.
+- Keep human-readable output behavior intact.
+
+Validation to run:
+- cargo test --all
+- cargo clippy --all-targets -- -D warnings
+- cargo clippy --all-features --all-targets -- -D warnings
+- cargo fmt --all -- --check
+- cargo build --release
+- forma check/build/run --error-format json on missing-import fixture
+- git status --short
+- git log --oneline -n 1
+
+Deliverables:
+- code changes
+- regression tests
+- concise summary with file list, command results, and commit hash
+```

src/main.rs

@@ -845,6 +845,43 @@ fn check(file: &PathBuf, partial: bool, error_format: ErrorFormat) -> Result<(),
         }
     };
 
+    // Load imports (module system)
+    let mut module_loader = ModuleLoader::from_source_file(file);
+    let ast = match module_loader.load_imports(&ast) {
+        Ok(imported_items) => {
+            let mut combined_items = imported_items;
+            combined_items.extend(ast.items);
+            forma::parser::SourceFile {
+                items: combined_items,
+                span: ast.span,
+            }
+        }
+        Err(e) => {
+            let error_span = e.span.unwrap_or(forma::lexer::Span {
+                start: 0,
+                end: 0,
+                line: 1,
+                column: 1,
+            });
+            match error_format {
+                ErrorFormat::Human => {
+                    ctx.error(error_span, &format!("module error: {}", e));
+                }
+                ErrorFormat::Json => {
+                    json_errors.push(span_to_json_error(
+                        &filename,
+                        error_span,
+                        "MODULE",
+                        &format!("{}", e),
+                        None,
+                    ));
+                    output_json_errors(json_errors, None);
+                }
+            }
+            return Err(format!("module error: {}", e));
+        }
+    };
+
     let mut error_count = 0;
 
     // Type check
@@ -1256,6 +1293,9 @@ fn build(
                 )),
             }
         }
+        if matches!(error_format, ErrorFormat::Json) {
+            output_json_errors(json_errors, None);
+        }
         return Err("Lexer errors".into());
     }
 
@@ -1294,7 +1334,30 @@ fn build(
                 span: parsed_ast.span,
             }
         }
-        Err(e) => return Err(format!("Module error: {}", e)),
+        Err(e) => {
+            let error_span = e.span.unwrap_or(forma::lexer::Span {
+                start: 0,
+                end: 0,
+                line: 1,
+                column: 1,
+            });
+            match error_format {
+                ErrorFormat::Human => {
+                    ctx.error(error_span, &format!("module error: {}", e));
+                }
+                ErrorFormat::Json => {
+                    json_errors.push(span_to_json_error(
+                        &filename,
+                        error_span,
+                        "MODULE",
+                        &format!("{}", e),
+                        None,
+                    ));
+                    output_json_errors(json_errors, None);
+                }
+            }
+            return Err(format!("Module error: {}", e));
+        }
     };
 
     // Type check
@@ -1312,6 +1375,9 @@ fn build(
                 )),
             }
         }
+        if matches!(error_format, ErrorFormat::Json) {
+            output_json_errors(json_errors, None);
+        }
         return Err("Type errors".into());
     }
 

tests/cli_tests.rs

@@ -240,3 +240,98 @@ fn test_cli_run_contract_violation() {
         "forma run contract_fail.forma should exit nonzero (contract violation)"
     );
 }
+
+#[test]
+fn test_cli_check_missing_import() {
+    let output = Command::new(forma_bin())
+        .args(["check"])
+        .arg(fixture("missing_import.forma"))
+        .output()
+        .expect("failed to execute forma");
+    assert!(
+        !output.status.success(),
+        "forma check missing_import.forma should exit nonzero"
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let combined = format!("{}{}", stdout, stderr);
+    assert!(
+        combined.contains("module") || combined.contains("Module"),
+        "error should mention module, got stdout: {}, stderr: {}",
+        stdout,
+        stderr
+    );
+}
+
+#[test]
+fn test_cli_check_missing_import_json() {
+    let output = Command::new(forma_bin())
+        .args(["--error-format", "json", "check"])
+        .arg(fixture("missing_import.forma"))
+        .output()
+        .expect("failed to execute forma");
+    assert!(
+        !output.status.success(),
+        "forma --error-format json check missing_import.forma should exit nonzero"
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("\"MODULE\""),
+        "JSON output should contain MODULE error category, got: {}",
+        stdout
+    );
+    assert!(
+        stdout.contains("\"errors\""),
+        "JSON output should contain errors key, got: {}",
+        stdout
+    );
+}
+
+#[test]
+fn test_cli_build_missing_import_json() {
+    // Module error happens before LLVM codegen, so this test works regardless of llvm feature
+    let output = Command::new(forma_bin())
+        .args(["--error-format", "json", "build"])
+        .arg(fixture("missing_import.forma"))
+        .output()
+        .expect("failed to execute forma");
+    assert!(
+        !output.status.success(),
+        "forma --error-format json build missing_import.forma should exit nonzero"
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("\"MODULE\""),
+        "JSON output should contain MODULE error category, got: {}",
+        stdout
+    );
+    assert!(
+        stdout.contains("\"errors\""),
+        "JSON output should contain errors key, got: {}",
+        stdout
+    );
+}
+
+#[test]
+fn test_cli_run_missing_import_json() {
+    let output = Command::new(forma_bin())
+        .args(["--error-format", "json", "run", "--allow-all"])
+        .arg(fixture("missing_import.forma"))
+        .output()
+        .expect("failed to execute forma");
+    assert!(
+        !output.status.success(),
+        "forma --error-format json run --allow-all missing_import.forma should exit nonzero"
+    );
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    assert!(
+        stdout.contains("\"MODULE\""),
+        "JSON output should contain MODULE error category, got: {}",
+        stdout
+    );
+    assert!(
+        stdout.contains("\"errors\""),
+        "JSON output should contain errors key, got: {}",
+        stdout
+    );
+}

tests/fixtures/missing_import.forma

@@ -0,0 +1,4 @@
+us nonexistent_module
+
+f main()
+    print("hello")