# 014.0-DEV-INVALID-OPTION-ERROR: Invalid Command Line Option Error Handling

## Release Goal

**Release 0.6: Enhanced User Experience**

Provide clear, actionable error messages when users provide invalid command-line options, helping them quickly identify typos and learn the correct syntax.

## How This Story Contributes

Improves user experience by catching common mistakes (like `--json` instead of `--format=json`) and providing helpful guidance instead of silently ignoring invalid options or producing unexpected output.

## User Story

**Format**: So that I can quickly identify and fix command-line option errors, as a developer, I want to receive clear error messages when I provide invalid options, with suggestions for the correct usage.

**INVEST Criteria Compliance**:

- **Independent**: Adds option validation without changing existing functionality
- **Negotiable**: Error message format and suggestions can be refined
- **Valuable**: Reduces confusion and time spent debugging invalid options
- **Estimable**: Clear scope - validate options and display errors
- **Small**: Single iteration to add validation and error messages
- **Testable**: Can verify error messages appear for invalid options

## Acceptance Criteria

- [ ] **Unknown Option Detection**: Detects when user provides an option that doesn't exist (e.g., `--json`, `--formatx`)
- [ ] **Clear Error Message**: Displays error message indicating the invalid option
- [ ] **Exit with Error**: Exits with non-zero status code (typically 2 for usage errors)
- [ ] **Show Help**: Suggests using `--help` to see valid options
- [ ] **Helpful Suggestions**: Where possible, suggests the correct option (e.g., "Did you mean --format=json?")
- [ ] **List Valid Options**: Shows brief list of valid options or points to help
- [ ] **No Silent Failures**: Never silently ignores invalid options
- [ ] **Validates Option Values**: Validates values for options that accept them (e.g., `--format` must be `table`, `json`, or `xml`)

## Requirements (Current Implementation or To Be Implemented)

- **REQ-OPTION-VALIDATION**: Validate all command-line options against known options
- **REQ-UNKNOWN-OPTION-ERROR**: Display error for unknown options with option name
- **REQ-INVALID-VALUE-ERROR**: Display error for invalid option values with valid choices
- **REQ-ERROR-EXIT-CODE**: Exit with code 2 for usage/option errors
- **REQ-HELP-SUGGESTION**: Include suggestion to use `--help` in error message
- **REQ-DID-YOU-MEAN**: Provide "Did you mean..." suggestions for common typos
- **REQ-NO-PARTIAL-EXECUTION**: Do not attempt to run the tool with invalid options
- **REQ-CLEAR-FORMAT**: Error messages should be clear and concise
- **REQ-STDERR-OUTPUT**: Output error messages to stderr, not stdout

## Dependencies

- None (can be implemented independently)

## Example Error Messages

**Unknown option**:

```bash
$ dry-aged-deps --json
Error: Unknown option '--json'

Did you mean '--format=json'?

Use 'dry-aged-deps --help' to see all available options.
```

**Invalid option value**:

```bash
$ dry-aged-deps --format=yaml
Error: Invalid value 'yaml' for option '--format'

Valid values are: table, json, xml

Use 'dry-aged-deps --help' for more information.
```

**Typo in option name**:

```bash
$ dry-aged-deps --formatx
Error: Unknown option '--formatx'

Did you mean '--format'?

Use 'dry-aged-deps --help' to see all available options.
```

**Multiple errors**:

```bash
$ dry-aged-deps --json --formatx
Error: Unknown option '--json'

Did you mean '--format=json'?

Error: Unknown option '--formatx'

Did you mean '--format'?

Use 'dry-aged-deps --help' to see all available options.
```

## Usage Examples

```bash
# User tries --json (wrong)
$ dry-aged-deps --json
Error: Unknown option '--json'
Did you mean '--format=json'?
Use 'dry-aged-deps --help' to see all available options.
# Exit code: 2

# User corrects to --format=json (right)
$ dry-aged-deps --format=json
{ "packages": [...], "summary": {...} }
# Exit code: 0 or 1 depending on results

# User provides invalid format value
$ dry-aged-deps --format=yaml
Error: Invalid value 'yaml' for option '--format'
Valid values are: table, json, xml
Use 'dry-aged-deps --help' for more information.
# Exit code: 2
```

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Unit tests for option validation
- [ ] Tests verify error messages for unknown options
- [ ] Tests verify error messages for invalid values
- [ ] Tests verify exit code 2 for option errors
- [ ] Tests verify stderr output for errors
- [ ] Tests for "Did you mean" suggestions
- [ ] Integration tests with various invalid options
- [ ] Documentation updated (README.md shows error handling)
- [ ] Help text remains accessible despite errors

---

## Story Notes

**Common User Mistakes**:

- Using `--json` instead of `--format=json` (from npm conventions)
- Typos like `--formatx` or `--fromat`
- Invalid format values like `--format=yaml`
- Misspelling threshold options

**Error Message Best Practices**:

1. State what's wrong clearly
2. Suggest the correct alternative when possible
3. Point to help documentation
4. Exit with appropriate code (2 for usage errors)
5. Output to stderr, not stdout

**Exit Code Convention**:

- 0: Success, no safe updates available
- 1: Success, safe updates available
- 2: Usage error (invalid options, help requested)
- 3+: Runtime errors (npm failures, network issues, etc.)

**Gall's Law Compliance**: Adds validation layer before existing processing without changing core functionality.

**User Experience**: Reduces frustration and debugging time by catching errors early with helpful messages.