feat: add --format json structured output for agent consumption

[Alberto-Codes]

Summary

Add a --format json flag to docvet check and all subcommands, producing structured JSON output that AI agents can parse programmatically.

Motivation

Agents parse JSON natively. Terminal-formatted output requires pattern matching and is fragile. Structured output enables agents to:

• Programmatically iterate over findings
• Map findings to specific files and lines
• Understand severity and category without parsing prose
• Integrate docvet into automated fix loops

Proposed output schema

{
  "findings": [
    {
      "file": "src/foo/bar.py",
      "line": 42,
      "symbol": "parse_config",
      "rule": "missing-raises",
      "message": "Docstring missing Raises section for ValueError, FileNotFoundError",
      "category": "enrichment",
      "severity": "warning"
    }
  ],
  "summary": {
    "total": 3,
    "by_category": {"enrichment": 2, "freshness": 1},
    "files_checked": 5
  }
}

Design considerations

• --format flag with values: text (default, current behavior), json
• JSON output should include all fields needed for an agent to fix the issue
• Exit codes unchanged: 0 = clean, 1 = findings
• Consider SARIF format as a future option for GitHub Advanced Security integration

Related

• MCP server (will consume this same structured output internally)
• GitHub Action (#TBD) will use JSON output for PR annotations