Skip to content

[GOOD FIRST ISSUE] Document --format output formats and CSV header-only behavior in README #132

Description

@advaitpatel

Background

The README's Quick Start section documents --format json,html (see the "Write only the report formats you want" example) but doesn't have a dedicated section explaining what each of the four formats (json, csv, pdf, html) contains, or a known, intentional quirk: CSV always writes a header-only file when there are zero vulnerabilities, even if csv is in the requested --format list (see docs/CHANGELOG.md's Phase 2 notes). A new user piping that CSV into something expecting at least one data row could be confused by an empty-looking file that isn't actually broken.

Task

Add a short "Report formats" subsection to the README (near the existing "Machine-readable output" / "SARIF output" sections) that:

  • Briefly describes what's in each of json, csv, pdf, html
  • Notes the CSV header-only-on-zero-findings behavior explicitly, so it reads as intentional rather than a bug
  • Links out to --json and --sarif's existing dedicated sections rather than duplicating them

Acceptance criteria

  • New README subsection added, consistent in tone/formatting with the surrounding sections
  • No code changes — this is a docs-only issue
  • Doesn't duplicate the existing --json/--sarif sections, just cross-references them

Pointers

  • README.md — search for --format json,html and the "Machine-readable output" heading for where this fits
  • docs/CHANGELOG.md — search for "header-only" for the exact behavior to describe

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions