# 009.0-DEV-XML-OUTPUT: XML Output Format

## Release Goal

**Release 0.5: Machine-Readable Output**

Add XML output format to enable integration with enterprise tools and systems that require XML-formatted data. Many build servers, reporting tools, and enterprise platforms consume XML.

## How This Story Contributes

Enables integration with enterprise tools that expect XML format. Complements JSON output to support a wider range of automation and integration scenarios.

## User Story

**Format**: So that I can integrate dry-aged-deps with enterprise tools that require XML format, as a developer, I want to output results in XML format instead of human-readable tables or JSON.

**INVEST Criteria Compliance**:

- **Independent**: Adds new output format without changing existing functionality
- **Negotiable**: XML structure and element names can be refined
- **Valuable**: Enables enterprise tool integration and compatibility
- **Estimable**: Clear scope - format existing data as XML
- **Small**: Single iteration to add XML formatter (similar to JSON)
- **Testable**: Can verify XML output is valid and complete

## Acceptance Criteria

- [ ] **CLI Flag**: Accepts `--format=xml` to enable XML output
- [ ] **Valid XML**: Output is valid, well-formed XML with proper declaration
- [ ] **Complete Data**: Includes all relevant information (same as JSON output)
- [ ] **Summary Section**: Includes summary statistics
- [ ] **Exit Codes**: Returns appropriate exit codes (0 = no errors, 1 = updates available, 2 = error)
- [ ] **No Console Noise**: Suppresses console.log messages in XML mode (only XML output)
- [ ] **Error Handling**: Errors output as XML with error element
- [ ] **Schema Valid**: XML follows consistent schema structure
- [ ] **Help Documentation**: `--help` shows xml as valid --format option

## Requirements (Current Implementation or To Be Implemented)

- **REQ-CLI-FLAG**: Support `--format=xml` command-line flag
- **REQ-XML-SCHEMA**: Define consistent XML output schema
- **REQ-COMPLETE-DATA**: Include all package information in output
- **REQ-SUMMARY-STATS**: Include filtering statistics
- **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 XML
- **REQ-ERROR-FORMAT**: Format errors as XML when in XML mode
- **REQ-VALIDATION**: Validate format value is one of: `table` (default), `json`, `xml`
- **REQ-XML-DECLARATION**: Include proper XML declaration and encoding

## Dependencies

- **008.0-DEV-JSON-OUTPUT**: Similar formatter pattern, can reuse output data structure

## Example Output Schemas

**XML Output**:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<outdated-packages timestamp="2025-11-10T09:30:00.000Z">
  <packages>
    <package>
      <name>express</name>
      <type>prod</type>
      <current>4.17.1</current>
      <wanted>4.18.1</wanted>
      <latest>4.18.2</latest>
      <recommended>4.18.2</recommended>
      <age>45</age>
      <vulnerabilities>
        <count>0</count>
        <max-severity>none</max-severity>
        <details>
          <info>0</info>
          <low>0</low>
          <moderate>0</moderate>
          <high>0</high>
          <critical>0</critical>
        </details>
      </vulnerabilities>
      <filtered>false</filtered>
      <filter-reason></filter-reason>
    </package>
  </packages>
  <summary>
    <total-outdated>5</total-outdated>
    <safe-updates>1</safe-updates>
    <filtered-by-age>2</filtered-by-age>
    <filtered-by-security>2</filtered-by-security>
    <thresholds>
      <prod>
        <min-age>30</min-age>
        <min-severity>moderate</min-severity>
      </prod>
      <dev>
        <min-age>7</min-age>
        <min-severity>high</min-severity>
      </dev>
    </thresholds>
  </summary>
</outdated-packages>
```

**XML Error Output**:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<outdated-packages timestamp="2025-11-10T09:30:00.000Z">
  <error>
    <message>Failed to run npm outdated</message>
    <code>NPM_ERROR</code>
    <details>npm command not found</details>
  </error>
</outdated-packages>
```

## Usage Examples

```bash
# Get XML output
dry-aged-deps --format=xml

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

# Use with xmllint for validation/formatting
dry-aged-deps --format=xml | xmllint --format -

# Parse with xpath in scripts
dry-aged-deps --format=xml | xmllint --xpath '//package/name' -
```

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Unit tests for XML formatter
- [ ] Tests verify XML validity (can be parsed by XML parser)
- [ ] Tests verify complete data in output
- [ ] Tests verify special character escaping
- [ ] Tests verify exit codes
- [ ] Integration tests with --format=xml flag
- [ ] Documentation updated (README.md shows XML output example)
- [ ] Help text includes xml as valid format option
- [ ] Backward compatible (table remains default)

---

## Story Notes

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

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

**Enterprise Integration**: XML format enables integration with build servers (Jenkins, TeamCity), reporting tools, and enterprise monitoring systems that expect XML.

**Character Escaping**: Proper XML escaping is critical - package names or versions with special characters must be handled correctly.

**Future Enhancement**: Could add XSLT stylesheet reference for browser-based viewing and formatting.