fix: improve error messages with more context

[jdx]

Summary

• InvalidFlag now includes a reason explaining why parsing failed:
  • "short flags must be a single character (use -- for long flags)"
  • "unexpected token (expected -x, --long, , or [arg])"
• invalid-default-subcommand lint now lists valid subcommands

🤖 Generated with Claude Code

---

Note

Improves error clarity in CLI usage parsing and linting.

• Refactors UsageErr::InvalidFlag to a struct variant with token, reason, labeled span, and full input, producing messages like Invalid flag {token}: {reason}
• Updates SpecFlag::from_str to return detailed reasons for parse failures (e.g., multi-char short flags, unexpected tokens) using the new InvalidFlag fields
• Enhances invalid-default-subcommand lint to append a list of valid subcommands (or note none are defined)
• Adds #[allow(unused_assignments)] to error module export to appease derive usage of struct fields

^{Written by Cursor Bugbot for commit 1bc558b. This will update automatically on new commits. Configure here.}

[Copilot]

Pull request overview

This PR improves error messages by adding contextual information to help users understand and fix parsing and validation errors.

Changes:

• Enhanced InvalidFlag error with structured fields and descriptive reasons for parsing failures
• Updated lint error message for invalid default subcommands to include a list of valid subcommands

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
lib/src/error.rs	Restructured InvalidFlag error variant from tuple to struct with token and reason fields
lib/src/spec/flag.rs	Updated flag parsing to use new InvalidFlag structure with context-specific error reasons
cli/src/cli/lint.rs	Enhanced default subcommand validation message to list valid subcommands or indicate when none exist

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The string literal is split across two lines unnecessarily. Consider moving the .to_string() call to the same line as the string literal or keeping the entire statement on one line for better readability.

Suggested change

	reason: "short flags must be a single character (use -- for long flags)"
	.to_string(),
	reason: "short flags must be a single character (use -- for long flags)".to_string(),

[codecov]

Codecov Report

❌ Patch coverage is 9.52381% with 19 lines in your changes missing coverage. Please review.
✅ Project coverage is 44.81%. Comparing base (9df7c86) to head (1bc558b).
⚠️ Report is 11 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/src/spec/flag.rs	0.00%	3 Missing and 8 partials ⚠️
cli/src/cli/lint.rs	20.00%	3 Missing and 5 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #449      +/-   ##
==========================================
- Coverage   47.36%   44.81%   -2.55%     
==========================================
  Files          47       47              
  Lines        6653     7145     +492     
  Branches     6653     7145     +492     
==========================================
+ Hits         3151     3202      +51     
- Misses       1739     1992     +253     
- Partials     1763     1951     +188     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.