# 008.0-DEV-JSON-OUTPUT: JSON Output Format

## Release Goal

**Release 0.5: Machine-Readable Output**

Add JSON output format to enable programmatic consumption of dry-aged-deps results in CI/CD pipelines, automation scripts, and integration with other tools.

## How This Story Contributes

Enables automation and integration by providing structured, machine-readable output. CI/CD systems can parse JSON to make decisions about updates, generate reports, or trigger alerts.

## User Story

**Format**: So that I can integrate dry-aged-deps into automated workflows and CI/CD pipelines, as a developer, I want to output results in JSON format instead of human-readable tables.

**INVEST Criteria Compliance**:

- **Independent**: Adds new output format without changing existing functionality
- **Negotiable**: JSON structure and field names can be refined
- **Valuable**: Enables automation, scripting, and tool integration
- **Estimable**: Clear scope - format existing data as JSON
- **Small**: Single iteration to add JSON formatter
- **Testable**: Can verify JSON output is valid and complete

## Acceptance Criteria

- [ ] **CLI Flag**: Accepts `--format=json` to enable JSON output
- [ ] **Valid JSON**: Output is valid, parseable JSON
- [ ] **Complete Data**: Includes all relevant information (name, current, latest, age, vulnerabilities, severity)
- [ ] **Summary Section**: Includes summary statistics (total packages, filtered counts)
- [ ] **Exit Codes**: Returns appropriate exit codes (0 = no errors, 1 = updates available, 2 = error)
- [ ] **No Console Noise**: Suppresses console.log messages in JSON mode (only JSON output)
- [ ] **Error Handling**: Errors output as JSON with error field
- [ ] **Default Behavior**: Table format remains default when no --format specified
- [ ] **Help Documentation**: `--help` shows --format option

## Requirements (Current Implementation or To Be Implemented)

- **REQ-CLI-FLAG**: Support `--format=json` command-line flag
- **REQ-JSON-SCHEMA**: Define consistent JSON output schema
- **REQ-COMPLETE-DATA**: Include all package information in output
- **REQ-SUMMARY-STATS**: Include filtering statistics (packages checked, filtered by age, filtered by security)
- **REQ-EXIT-CODES**: Exit 0 if no errors occurred, 1 if safe updates available, 2 on error
- **REQ-SILENT-MODE**: Suppress warning/info console messages when outputting JSON
- **REQ-ERROR-FORMAT**: Format errors as JSON objects when in JSON mode
- **REQ-VALIDATION**: Validate format value is one of: `table` (default), `json`, `xml`
- **REQ-FORMAT-ERROR**: Display clear error message for invalid format values
- **REQ-EXCLUSIVE-FORMAT**: Only one format can be specified at a time

## Dependencies

- None (can be implemented independently)

## Example Output Schemas

**JSON Output**:

```json
{
  "packages": [
    {
      "name": "express",
      "type": "prod",
      "current": "4.17.1",
      "wanted": "4.18.1",
      "latest": "4.18.2",
      "recommended": "4.18.2",
      "age": 45,
      "vulnerabilities": {
        "count": 0,
        "maxSeverity": "none",
        "details": {
          "info": 0,
          "low": 0,
          "moderate": 0,
          "high": 0,
          "critical": 0
        }
      },
      "filtered": false,
      "filterReason": null
    }
  ],
  "summary": {
    "totalOutdated": 5,
    "safeUpdates": 1,
    "filteredByAge": 2,
    "filteredBySecurity": 2,
    "thresholds": {
      "prod": {
        "minAge": 30,
        "minSeverity": "moderate"
      },
      "dev": {
        "minAge": 7,
        "minSeverity": "high"
      }
    }
  },
  "timestamp": "2025-11-10T09:30:00.000Z"
}
```

**JSON Error Output**:

```json
{
  "error": {
    "message": "Failed to run npm outdated",
    "code": "NPM_ERROR",
    "details": "npm command not found"
  },
  "timestamp": "2025-11-10T09:30:00.000Z"
}
```

## Usage Examples

```bash
# Get JSON output
dry-aged-deps --format=json

# Use in CI/CD pipeline
UPDATES=$(dry-aged-deps --format=json)
UPDATE_COUNT=$(echo $UPDATES | jq '.summary.safeUpdates')
if [ $UPDATE_COUNT -gt 0 ]; then
  echo "Safe updates available!"
fi

# Save to file
dry-aged-deps --format=json > outdated.json
```

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Unit tests for JSON formatter
- [ ] Tests verify JSON validity (JSON.parse succeeds)
- [ ] Tests verify complete data in output
- [ ] Tests verify exit codes
- [ ] Integration tests with --format=json flag
- [ ] Documentation updated (README.md shows JSON output example)
- [ ] Help text includes --format option
- [ ] Backward compatible (table remains default)

---

## Story Notes

**Gall's Law Compliance**: Adds JSON formatter alongside existing table formatter without changing core logic.

**Backward Compatibility**: Table format remains default - JSON is opt-in via --format=json flag.

**CI/CD Integration**: JSON output enables automated decision-making in pipelines (e.g., auto-create PR if safe updates exist).

**Tooling Integration**: JSON output can be consumed by monitoring tools, dashboards, or custom scripts.

**Future Enhancement**: Story 009.0 will add XML format for compatibility with existing enterprise tools.