pdftract/notes/pdftract-37qim.md

# Verification Note: pdftract-37qim

## Task: CLI parsing + validation (multi-format flags, --ndjson exclusivity, stdout uniqueness)

## Summary
The CLI parsing + validation for multi-output was already implemented in `crates/pdftract-cli/src/output.rs`. This verification confirms that the implementation meets all acceptance criteria.

## Pre-existing Work
The implementation was already present in the codebase. This task primarily verified that:
1. The `OutputConfig` struct and `build_specs()` method correctly validate output configurations
2. All validation rules from the plan (lines 2261-2265) are enforced
3. The CLI integration in `main.rs` uses the output configuration correctly

## Fixes Made
- Fixed compilation errors in `crates/pdftract-core/src/span/mod.rs` by adding missing `column: None` field to two constructors (`new()` and `empty()`)

## Verification Results

### Acceptance Criteria - ALL PASS

1. **`--json a.json --md b.md -> 2 OutputSpecs built`** - PASS
   - Test: `test_multiple_format_flags`
   - Verified: `cargo nextest run -p pdftract-cli --lib output::tests::test_multiple_format_flags`

2. **`--json a.json --json b.json -> CLI error "duplicate format"`** - PASS
   - CLI test: `./target/debug/pdftract extract --json a.json --json b.json tests/fixtures/empty.pdf`
   - Output: `Error: duplicate format: --json and --json both specify json output`

3. **`--ndjson --md b.md -> CLI error "--ndjson cannot be combined"`** - PASS (critical test line 2302)
   - CLI test: `./target/debug/pdftract extract --ndjson --md b.md tests/fixtures/empty.pdf`
   - Output: `error: the argument '--ndjson' cannot be used with '--md <PATH>'`
   - Note: clap's `conflicts_with_all` catches this at parse time

4. **`--md - --json out.json -> 2 specs, MD=Stdout, JSON=File`** - PASS
   - Test: `test_stdout_with_file`
   - Verified: MD goes to stdout, JSON goes to file

5. **`--md - --json - -> CLI error "at most one stdout"`** - PASS
   - CLI test: `./target/debug/pdftract extract --md - --json - tests/fixtures/empty.pdf`
   - Output: `Error: at most one output may be stdout (-); multiple formats cannot all write to stdout`

6. **`--format json,md -o out -> 2 specs, out.json + out.md`** - PASS
   - Test: `test_format_with_base`
   - CLI test: `./target/debug/pdftract extract --format json,md -o out tests/fixtures/empty.pdf`
   - Output: `Producing 2 outputs: json -> out.json, markdown -> out.md`

### Additional Verification

- **Default behavior (no output flags)** - PASS
  - Per line 2242-2243: Single output to stdout (default)
  - `test_output_config_default` confirms JSON to stdout when no flags specified

- **`--format without -o` error** - PASS
  - CLI test: `./target/debug/pdftract extract --format json tests/fixtures/empty.pdf`
  - Output: `Error: --format requires -o (output base path)`

- **Cross-format duplication detection** - PASS
  - Tests: `test_duplicate_format_json_flag_and_format_list`, `test_duplicate_format_md_flag_and_format_list`, `test_duplicate_format_text_flag_and_format_list`
  - Validates that `--json` and `--format json` cannot both specify JSON output

## Implementation Details

### OutputConfig Structure
Located in `crates/pdftract-cli/src/output.rs`:
- `OutputConfig` struct stores parsed CLI flags
- `build_specs()` method validates and builds `Vec<OutputSpec>`
- Validation rules:
  1. Each format can appear at most once
  2. At most one output can be stdout
  3. `--ndjson` cannot be combined with other formats
  4. `--format` requires `-o`

### CLI Integration
Located in `crates/pdftract-cli/src/main.rs`:
- `cmd_extract()` creates `OutputConfig` from CLI args
- Calls `build_specs()` and reports errors with `exit(2)`
- Iterates over output specs and writes each to its destination
- Uses `AtomicFileWriter` for file outputs (atomic writes)

### Test Coverage
All 23 tests in `output::tests` pass:
- Format parsing (`test_format_from_str`)
- Extension mapping (`test_format_extension`)
- Destination handling (`test_destination_from_path`)
- Single format flags (`test_single_format_flag_json`, `test_single_format_flag_md`, `test_single_format_flag_text`)
- Multiple format flags (`test_multiple_format_flags`)
- Stdout handling (`test_stdout_with_file`, `test_multiple_stdout_rejected`)
- NDJSON exclusivity (`test_ndjson_exclusive_with_json`, `test_ndjson_exclusive_with_md`, `test_ndjson_exclusive_with_text`)
- Format auto-naming (`test_format_with_base`, `test_format_with_all_formats`, `test_output_spec_auto_named`)
- Duplicate detection (`test_duplicate_format_json_flag_and_format_list`, etc.)

## References
- Plan section: Phase 6.6 CLI design + validation rules (lines 2221-2247, 2261-2303)
- Critical test: Line 2302 - `--ndjson --md b.md` → rejected at CLI parse time

## PASS/WARN/FAIL Summary
- **PASS**: All 6 acceptance criteria
- **WARN**: None
- **FAIL**: None

## Files Modified
- `crates/pdftract-core/src/span/mod.rs` - Fixed compilation errors (added `column: None` to constructors)

## Files Verified
- `crates/pdftract-cli/src/output.rs` - Core validation logic
- `crates/pdftract-cli/src/main.rs` - CLI integration