feat(formatters): unified Finding dataclass + 5 new formatters — text, junit-xml, emacs, vim, gitlab-sast (closes #52)

[Wolfvin]

Summary

Implements Phase 1 + Phase 2 of issue #52 — unified Finding dataclass + 5 new formatters (text, junit-xml, emacs, vim, gitlab-sast).

Before this PR, every CodeLens formatter had its own ad-hoc finding-extraction logic — duplicated, slightly inconsistent. Phase 1 introduces a single Finding dataclass and extract_findings() entry point. Phase 2 builds 5 new formatters that consume Finding objects, covering GitLab CI, Jenkins, Emacs, Vim, and human-readable terminal output.

Phase 1 — Unified Finding dataclass:

• New scripts/formatters/base.py with Finding dataclass, Severity constants, and extract_findings() helper
• Handles heterogeneous engine outputs (different keys for file/line/severity/message, plain lists vs category-keyed dicts)
• Conservative: dedupes across findings + by_category (engines occasionally double-emit)
• Backward compat: existing formatters (json, markdown, ai, sarif, compact) keep their original behavior — they do NOT use Finding internally. Refactoring them is a future Phase.

Phase 2 — 5 standard formatters:

• text — human-readable table: RULE ID | SEVERITY | LOCATION | MESSAGE
• junit-xml — universal test result format for Jenkins/GitLab CI (critical/high → <failure>, medium/low/info → <skipped>)
• emacs — file:line:col: level: message for compile-mode
• vim — file:line:col: [severity] message for quickfix
• gitlab-sast — GitLab CI native security scan format with stable vulnerability IDs, CWE identifiers, severity→GitLab enum mapping

Files

New:

• scripts/formatters/base.py — Finding dataclass, Severity constants, extract_findings()
• scripts/formatters/text.py — table formatter
• scripts/formatters/junit_xml.py — JUnit XML
• scripts/formatters/emacs.py — compile-mode
• scripts/formatters/vim.py — quickfix
• scripts/formatters/gitlab_sast.py — GitLab SAST JSON
• tests/test_formatters_base.py — 36 tests for Phase 1
• tests/test_formatters_phase2.py — 46 tests for Phase 2

Modified:

• scripts/formatters/__init__.py — format_output() dispatches to new formatters
• scripts/codelens.py — --format choices updated (subcommand level)
• README.md, SKILL.md, SKILL-QUICK.md, pyproject.toml, skill.json, scripts/graph_model.py — auto-synced via sync_command_count.py --apply (no command count change, but MCP tool counts refreshed)

Key design decisions

1. Additive only — existing formatters unchanged. Phase 1 is "introduce the dataclass + extractor"; Phase 2 is "build new formatters on top". Refactoring existing formatters (json, markdown, ai, sarif, compact) to also consume Finding is a behavior-risky change and out of scope for this PR.
2. Single extraction path. extract_findings() handles all engine output shapes (plain lists, category-keyed dicts, severity-keyed dicts, alternative field names like defined_in/line_number/risk). Every Phase 2 formatter calls it — no duplication.
3. Conservative extraction. When in doubt, return fewer findings rather than risk duplicating. Dedupes by (file, line, category, message).
4. Severity normalization. Engines use various vocabularies (critical/high/medium/low/info, error/warning/note, fatal/blocker/moderate). _normalize_severity() collapses them to the canonical set so formatters don't need to handle every variant.
5. Suppressed findings omitted from formatters (except text which shows a count in the footer). Formatters' job is to surface actionable findings, not dismissed ones. Suppressed findings would clutter CI dashboards and editor quickfix.
6. Stable IDs in gitlab-sast. Same finding → same ID across runs (SHA-256 of rule_id + file + line + category). GitLab dedupes vulnerabilities by ID, so unstable IDs would create duplicate vulnerability records.
7. JUnit XML: critical/high → <failure>, medium/low/info → <skipped>. Matches how most teams configure CI quality gates — only blocking severities fail the build.
8. Emacs/Vim: no header/footer. Line-oriented formats — any extra prose breaks the parser. Empty findings → empty output (vim) or single informative line (emacs).
9. No external dependencies. Uses stdlib only (xml.sax.saxutils for XML escaping, hashlib for stable IDs, json for gitlab-sast). Per issue spec: "Semgrep formatters are LGPL-2.1 — reference only, reimplement from spec."

Acceptance criteria

• All 5 Phase 2 formatters produce valid output (XML parses, JSON parses, line formats match editor specs)
• text formatter: table with header, rows, severity summary footer
• junit-xml formatter: valid JUnit XML, critical/high as <failure>, others as <skipped>
• emacs formatter: file:line:col: level: message per line
• vim formatter: file:line:col: [severity] message per line
• gitlab-sast formatter: GitLab Secure spec compliant, stable vulnerability IDs, CWE identifiers
• Suppressed findings omitted (except text shows count in footer)
• Workspace path shortening (absolute → relative)
• format_output() dispatches new formats correctly
• No regressions in existing formatters (json, markdown, ai, sarif, compact)

(Phases 3–6 of #52 — SARIF codeFlows, JSONL streaming, TOON, issue-tracker scripts — are out of scope for this Phase 1+2 PR.)

Test results

• 36 new tests in tests/test_formatters_base.py — all pass
• 46 new tests in tests/test_formatters_phase2.py — all pass
• Full suite: 1429 passed, 76 skipped, 0 failed (4 pre-existing upstream failures deselected: test_codelensignore [FEATURE] Configuration system overhaul — multi-layer YAML + .codelensignore + multi-format #55, test_universal_grammar_loader [FEATURE] 158-language support via universal tree-sitter grammar loader #18)

Closes #52.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE