fix(build): validate options and expose cause diagnostics

[kojiwakayama]

Description

• Reject unknown veryfront build options and suggest the closest documented option.
• Show the deepest error cause stack in verbose mode and point non-verbose users to --verbose.
• Redact absolute source paths from verbose stack frames while preserving filenames and line information.
• Strengthen the real build failure integration assertion so it verifies the typed configuration error.

The behavior changes were developed red-green: focused tests failed against the previous behavior, then passed after the implementation changes.

Related Issue(s)

Fixes veryfront/veryfront-issue-inbox#457
Fixes veryfront/veryfront-issue-inbox#458

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Code refactoring
• Test update

Checklist

• I have made corresponding changes to the documentation (not applicable, existing flags and behavior only)
• I have added tests that prove my fix is effective or that my feature works

Verification

• deno fmt --check on touched files
• deno lint on touched files
• deno check cli/shared/args.ts cli/commands/build/error-handler.ts cli/commands/build/handler.ts
• Focused build CLI suites: 73 steps passed
• Full parallel unit suite before review follow-up: 3814 tests passed, 0 failed, 1 ignored
• Manual human and --json invocations return exit code 2 for an unknown build option

Summary by CodeRabbit

• Bug Fixes

  • Build commands now reject unknown options and provide clearer errors with suggestions for likely typos.
  • Build error messages sanitize filesystem paths and offer more useful guidance.
  • Verbose mode can display relevant underlying error details, while diagnostic output remains limited for readability.

• Tests

  • Added coverage for invalid options, typo suggestions, nested build errors, stack-trace sanitization, and verbose error reporting.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8d4e7e4d-dbe4-46c9-8b96-fb66f8f59f25

📥 Commits

Reviewing files that changed from the base of the PR and between 09c6942 and beeb150.

📒 Files selected for processing (1)

• cli/commands/build/build-error.integration.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• cli/commands/build/build-error.integration.test.ts

---

📝 Walkthrough

Walkthrough

The build CLI now rejects unknown options with suggestions. Build-error handling traverses nested causes, redacts filesystem paths, limits stack output, and guides non-verbose users to --verbose.

Changes

Build CLI validation and diagnostics

Layer / File(s)	Summary
Unknown-option validation cli/shared/args.ts	createArgParser can reject unknown options, allow router-level options, and suggest the closest command-specific option.
Build parser wiring and coverage cli/commands/build/handler.ts, cli/commands/build/handler.test.ts	Build parsing enables unknown-option rejection. Tests cover invalid options and the --output-dir suggestion.
Causal build-error diagnostics cli/commands/build/error-handler.ts, cli/commands/build/error-handler.test.ts, cli/commands/build/build-error.integration.test.ts	Build errors use the deepest causal error for verbose diagnostics, redact filesystem paths, limit stack output, and show non-verbose guidance. Integration tests verify the configuration-validation error contract.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to beeb1

This PR makes localized build validation and error-diagnostics improvements, with focused and broader checks reported as passing; no actionable merge-blocking risk remains beyond normal review.

Sequence Diagram(s)

sequenceDiagram
  participant buildCommand
  participant handleBuildError
  participant CauseChain as Error.cause chain
  participant terminal
  buildCommand->>handleBuildError: rejected build error
  handleBuildError->>CauseChain: traverse nested causes
  CauseChain-->>handleBuildError: deepest error
  handleBuildError->>terminal: sanitized stack or verbose hint

Loading

Suggested reviewers: kwakayama

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: rejecting invalid build options and exposing underlying error-cause diagnostics.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/build-cli-validation-diagnostics

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

📦 Client bundle boundary

Entrypoint	Modules	Source size	Server leaks
src/index.client.ts	454	3062 KiB	⚠️ 39 known

A server module in a client graph aborts hydration in the browser. New leaks fail CI; known leaks are tracked in scripts/lint/client-bundle-baseline.json to burn down.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6e7aa5a6e9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".