feat: add scan format option (#32)

* fix: remove duplicate include_spec check in _collect_files; test: add 9 edge case tests covering remove non-dry-run, dynamic routes, utility CSS prefixes, read errors, skip names, page/layout component exclusion

* fix: update CSS class regex to capture Tailwind utility classes with colon prefixes

* fix: correct ruff known-first-party, add py.typed marker, relative import in __main__, packaging tests

* feat: add --format option to scan with pretty/compact/github/json output

---------

Co-authored-by: DevForge Engineer <engineer@devforge.dev>

Author: Coding-Dev-Tools

src/deadcode/cli.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
-import click
 import json
 import sys
 from pathlib import Path
+
+import click
 from rich.console import Console
 from rich.table import Table
 
@@ -16,7 +17,9 @@
 console = Console()
 err_console = Console(stderr=True)
 
+FORMAT_HELP = "Output format: pretty (default), compact, github, or json"
 ALL_CATEGORIES = ["unused_export", "dead_route", "orphaned_css", "unreferenced_component"]
+FORMAT_CHOICES = click.Choice(["pretty", "compact", "github", "json"])
 
 
 @click.group()
@@ -64,12 +67,13 @@ def _get_fail_threshold(ctx: click.Context) -> int:
 
 
 @cli.command()
-@click.option("--json-output", "-j", is_flag=True, help="Output as JSON")
+@click.option("--json-output", "-j", is_flag=True, help="Alias for --format=json (deprecated)")
+@click.option("--format", type=FORMAT_CHOICES, default="pretty", help=FORMAT_HELP)
 @click.option("--category", "-c", type=click.Choice(ALL_CATEGORIES), default=None, help="Filter by category")
 @click.option("--fail", "fail_threshold", type=int, default=None,
               help="Exit code 1 if findings >= threshold (overrides .deadcode.yml)")
 @click.pass_context
-def scan(ctx: click.Context, json_output: bool, category: str | None, fail_threshold: int | None) -> None:
+def scan(ctx: click.Context, json_output: bool, format: str | None, category: str | None, fail_threshold: int | None) -> None:
     """Scan project for dead code."""
     project = ctx.obj["project"]
     ignore = _merge_config_ignore(ctx)
@@ -92,7 +96,10 @@ def scan(ctx: click.Context, json_output: bool, category: str | None, fail_thres
     if not category and config and config.categories:
         findings = [f for f in findings if f.category in config.categories]
 
-    if json_output:
+    # Determine effective format (legacy --json-output maps to json)
+    effective_format = "json" if json_output else (format or "pretty")
+
+    if effective_format == "json":
         output = {
             "files_scanned": result.files_scanned,
             "findings": [
@@ -103,6 +110,26 @@ def scan(ctx: click.Context, json_output: bool, category: str | None, fail_thres
             "errors": result.errors,
         }
         console.print(json.dumps(output, indent=2, default=str))
+    elif effective_format == "compact":
+        if not findings:
+            console.print("OK — 0 findings")
+        else:
+            for f in findings:
+                console.print(f"{f.file}:{f.line} \u2014 {f.category}: {f.name}")
+            console.print(f"\n{len(findings)} findings")
+    elif effective_format == "github":
+        # GitHub Actions annotation syntax
+        # ::warning file={name},line={line},endLine={line}::{message}
+        if not findings:
+            console.print("deadcode: 0 findings")
+        else:
+            for f in findings:
+                level = "error" if f.removable else "warning"
+                msg = f"{f.category}: {f.name}"
+                if f.detail:
+                    msg += f" ({f.detail[:120]})"
+                console.print(f"::{level} file={f.file},line={f.line}::{msg}")
+            console.print(f"\n::notice::deadcode: {len(findings)} findings")
     else:
         # Summary
         console.print(f"\n[bold]DeadCode Scan[/bold] — {result.files_scanned} files scanned\n")
@@ -149,7 +176,7 @@ def scan(ctx: click.Context, json_output: bool, category: str | None, fail_thres
     # CI fail threshold
     effective_threshold = fail_threshold if fail_threshold is not None else _get_fail_threshold(ctx)
     if effective_threshold >= 0 and len(findings) >= effective_threshold:
-        if not json_output:
+        if effective_format not in ("json", "github"):
             console.print(f"\n[red]FAIL: {len(findings)} findings >= threshold {effective_threshold}[/red]")
         sys.exit(1)
 

tests/test_scanner.py

@@ -388,3 +388,51 @@ def test_include_patterns_none_scans_all(self, tmp_path):
         scanner = DeadCodeScanner(tmp_path)
         result = scanner.scan()
         assert result.files_scanned == 2
+
+class TestScanFormat:
+    """Tests for the new --format scan option."""
+
+    def test_format_compact(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan", "--format=compact"])
+        assert result.exit_code == 0
+
+    def test_format_github(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan", "--format=github"])
+        assert result.exit_code == 0
+
+    def test_format_compact_with_findings(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan", "--format=compact"])
+        assert result.exit_code == 0
+        assert "unusedHelper" in result.output or "No dead code" in result.output
+
+    def test_format_github_with_findings(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan", "--format=github"])
+        assert result.exit_code == 0
+        assert "::" in result.output or "No dead code" in result.output
+
+    def test_format_json_legacy_alias(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan", "--json-output"])
+        assert result.exit_code == 0
+        data = json.loads(result.output, strict=False)
+        assert "findings" in data
+
+    def test_format_json_explicit(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan", "--format=json"])
+        assert result.exit_code == 0
+        data = json.loads(result.output, strict=False)
+        assert "findings" in data
+
+    def test_format_compact_empty(self, runner, tmp_path):
+        result = runner.invoke(cli, ["-p", str(tmp_path), "scan", "--format=compact"])
+        assert result.exit_code == 0
+        assert "OK \u2014 0 findings" in result.output
+
+    def test_format_github_empty(self, runner, tmp_path):
+        result = runner.invoke(cli, ["-p", str(tmp_path), "scan", "--format=github"])
+        assert result.exit_code == 0
+        assert "deadcode: 0 findings" in result.output
+
+    def test_format_pretty_default(self, runner, sample_project):
+        result = runner.invoke(cli, ["-p", str(sample_project), "scan"])
+        assert result.exit_code == 0
+        assert "DeadCode Scan" in result.output