codeguard-cli 2.0.0__py3-none-any.whl

codeguard/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CodeGuard — static analysis for Python, focused on AI-code failure modes."""
+
+from __future__ import annotations
+
+__version__ = "2.0.0"
+__all__ = ["__version__"]

codeguard/cli/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CodeGuard CLI package."""

codeguard/cli/_run.py

@@ -0,0 +1,230 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Shared implementation behind ``codeguard scan`` and ``codeguard ci``."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from codeguard import __version__
+from codeguard.cli import formatters as fmt
+from codeguard.config import ConfigError, find_config, load_config
+from codeguard.engine.baseline import Baseline, apply_baseline
+from codeguard.engine.discovery import DiscoveryConfig, discover
+from codeguard.engine.finding import Finding
+from codeguard.engine.gitdiff import changed_files, default_base, is_git_repo
+from codeguard.engine.policy import apply_config, gating_findings
+from codeguard.engine.registry import REGISTRY
+from codeguard.engine.runner import AnalysisRunner
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_USAGE = 2
+EXIT_CONFIG = 3
+EXIT_INTERNAL = 4
+
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+FORMATS = ["human", "json", "json-legacy", "sarif", "github", "rdjson", "junit"]
+
+
+def console(no_color: bool) -> Console:
+    return Console(stderr=True, no_color=no_color)
+
+
+@dataclass
+class RunOptions:
+    paths: tuple[Path, ...]
+    config_path: Path | None = None
+    output_format: str | None = None
+    rule_ids: tuple[str, ...] = ()
+    excludes: tuple[str, ...] = ()
+    includes: tuple[str, ...] = ()
+    fail_on: str | None = None
+    exit_zero: bool = False
+    min_severity: str | None = None
+    show_suppressed: bool = False
+    no_gitignore: bool = False
+    jobs: int | None = None
+    quiet: bool = False
+    no_color: bool = False
+    stdin_filename: str = "stdin.py"
+    output: Path | None = None
+    baseline_path: Path | None = None
+    now: str | None = None  # pin the date for `until=` suppression expiry
+    diff_ref: str | None = None
+    diff_auto: bool = False  # `ci` -- pick a base branch if diff_ref not given
+    sarif_out: Path | None = None  # `ci` -- also write SARIF here
+
+
+def execute(opt: RunOptions) -> int:
+    """Run a scan and return the process exit code."""
+    err = console(opt.no_color)
+
+    first = Path(opt.paths[0]) if opt.paths and str(opt.paths[0]) != "-" else Path.cwd()
+    scan_root = first if first.is_dir() else first.parent
+
+    try:
+        cfg_file = opt.config_path or find_config(scan_root)
+        config = load_config(cfg_file)
+    except ConfigError as exc:
+        err.print(f"[bold red]Config error:[/bold red] {exc}")
+        return EXIT_CONFIG
+
+    root = Path(config.source_dir) if config.source_dir else scan_root
+
+    output_format = (opt.output_format or config.output).lower()
+    fail_on = opt.fail_on
+    if opt.min_severity and not fail_on:
+        err.print("[yellow]warning:[/yellow] --severity is deprecated; use --fail-on.")
+        fail_on = opt.min_severity
+    threshold = (fail_on or config.fail_on).lower()
+
+    n_jobs = opt.jobs if opt.jobs is not None else config.jobs
+    if n_jobs == 0:
+        n_jobs = os.cpu_count() or 1
+
+    selected = list(opt.rule_ids) or config.enable or None
+    if selected is not None:
+        bad = [r for r in selected if r not in REGISTRY]
+        if bad:
+            err.print(f"[bold red]Error:[/bold red] unknown rule ID(s): {', '.join(bad)}.")
+            return EXIT_USAGE
+    disabled = set(config.disable)
+    active_ids = [
+        r.id
+        for r in REGISTRY.all()
+        if (selected is None or r.id in selected) and r.id not in disabled
+    ]
+    now = None
+    if opt.now:
+        from datetime import date
+
+        try:
+            now = date.fromisoformat(opt.now)
+        except ValueError:
+            err.print(f"[bold red]Error:[/bold red] --now must be YYYY-MM-DD, got {opt.now!r}")
+            return EXIT_USAGE
+    runner = AnalysisRunner(rule_ids=active_ids, now=now)
+
+    disc = DiscoveryConfig(
+        include=[*config.include, *opt.includes],
+        exclude=[*config.exclude, *opt.excludes],
+        respect_gitignore=config.gitignore and not opt.no_gitignore,
+    )
+
+    # --- collect --------------------------------------------------------
+    diff_ref = opt.diff_ref
+    if diff_ref is None and opt.diff_auto:
+        if not is_git_repo(root):
+            err.print("[bold red]Error:[/bold red] not a git repository; `ci` needs one.")
+            return EXIT_USAGE
+        diff_ref = default_base(root)
+        if diff_ref is None:
+            err.print("[yellow]warning:[/yellow] no base branch found; scanning all files.")
+
+    try:
+        findings = _collect(opt, runner, disc, n_jobs, root, diff_ref, err)
+    except SystemExit as exc:  # _collect signalled a usage error
+        return int(exc.code or EXIT_USAGE)
+    except Exception as exc:
+        err.print(f"[bold red]Internal error:[/bold red] {exc}")
+        return EXIT_INTERNAL
+
+    findings = apply_config(findings, config, root=str(root))
+
+    # --- baseline ------------------------------------------------------
+    baseline_path = opt.baseline_path
+    if baseline_path is None and config.baseline:
+        candidate = root / config.baseline
+        if candidate.is_file():
+            baseline_path = candidate
+    if baseline_path is not None:
+        try:
+            baseline = Baseline.load(baseline_path)
+        except ValueError as exc:
+            err.print(f"[bold red]Config error:[/bold red] {exc}")
+            return EXIT_CONFIG
+        findings = apply_baseline(findings, baseline)
+
+    findings.sort(key=lambda f: (f.location.file, f.location.line, f.location.col, f.rule_id))
+
+    # --- render -------------------------------------------------------
+    text = _render(output_format, findings, opt, err)
+
+    if opt.sarif_out is not None:
+        opt.sarif_out.write_text(
+            fmt.format_sarif(findings, tool_version=__version__), encoding="utf-8"
+        )
+        if not opt.quiet:
+            err.print(f"SARIF written to [bold]{opt.sarif_out}[/bold]")
+
+    if opt.output:
+        opt.output.write_text(text, encoding="utf-8")
+        if not opt.quiet:
+            err.print(f"Results written to [bold]{opt.output}[/bold]")
+    else:
+        click.echo(text, nl=False)
+
+    # --- exit code --------------------------------------------------
+    if opt.exit_zero:
+        return EXIT_OK
+    return EXIT_FINDINGS if gating_findings(findings, threshold) else EXIT_OK
+
+
+def _collect(
+    opt: RunOptions,
+    runner: AnalysisRunner,
+    disc: DiscoveryConfig,
+    jobs: int,
+    root: Path,
+    diff_ref: str | None,
+    err: Console,
+) -> list[Finding]:
+    targets = list(opt.paths) or [Path(".")]
+
+    if any(str(p) == "-" for p in targets):
+        source = sys.stdin.read()
+        try:
+            return runner.run(source, filename=opt.stdin_filename)
+        except SyntaxError as exc:
+            err.print(f"[yellow]warning:[/yellow] stdin: syntax error on line {exc.lineno}")
+            return []
+
+    for p in targets:
+        if not p.exists():
+            err.print(f"[bold red]Error:[/bold red] path does not exist: {p}")
+            raise SystemExit(EXIT_USAGE)
+
+    files = discover(targets, disc, root=root)
+
+    if diff_ref is not None:
+        changed = {p.resolve() for p in changed_files(diff_ref, root=root)}
+        files = [f for f in files if f.resolve() in changed]
+
+    return runner.run_files(files, jobs=jobs)
+
+
+def _render(output_format: str, findings: list[Finding], opt: RunOptions, err: Console) -> str:
+    ss = opt.show_suppressed
+    if output_format == "human":
+        return fmt.format_human(findings, show_suppressed=ss)
+    if output_format == "json":
+        return fmt.format_json(findings, show_suppressed=ss, tool_version=__version__)
+    if output_format == "json-legacy":
+        if not opt.quiet:
+            err.print("[yellow]warning:[/yellow] --format json-legacy is deprecated.")
+        return fmt.format_json_legacy(findings, show_suppressed=ss)
+    if output_format == "sarif":
+        return fmt.format_sarif(findings, tool_version=__version__)
+    if output_format == "github":
+        return fmt.format_github(findings, show_suppressed=ss)
+    if output_format == "rdjson":
+        return fmt.format_rdjson(findings, show_suppressed=ss, tool_version=__version__)
+    if output_format == "junit":
+        return fmt.format_junit(findings, show_suppressed=ss)
+    raise click.BadParameter(f"unknown format: {output_format}")

codeguard/cli/commands.py

@@ -0,0 +1,390 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Auxiliary CLI commands: list-rules, explain, validate, init."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+
+import codeguard.rules  # noqa: F401  -- register built-in rules
+from codeguard import __version__
+from codeguard.cli.formatters import finding_help_uri
+from codeguard.config import ConfigError, find_config, load_config
+from codeguard.engine.finding import Finding
+from codeguard.engine.registry import REGISTRY
+
+_STARTER_TOML = """\
+# CodeGuard configuration -- https://mevichitra.github.io/codeguard/configuration/
+# (In pyproject.toml, use the [tool.codeguard] table instead of [codeguard].)
+
+[codeguard]
+exclude = ["**/*.min.js", "tests/fixtures/**"]
+fail_on = "high"          # exit 1 only on findings at or above this severity
+gitignore = true
+
+[codeguard.rules]
+disable = []
+"""
+
+
+def register(group: click.Group) -> None:
+    group.add_command(_list_rules)
+    group.add_command(_explain)
+    group.add_command(_validate)
+    group.add_command(_init)
+    group.add_command(_baseline)
+    group.add_command(_suppressions)
+
+
+@click.command("list-rules")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table")
+@click.option("--language", "language", default=None, help="Filter by language.")
+@click.option("--category", "category", default=None, help="Filter by category.")
+@click.option("--severity", "severity", default=None, help="Filter by severity.")
+def _list_rules(fmt: str, language: str | None, category: str | None, severity: str | None) -> None:
+    """List every registered rule."""
+    rows: list[dict[str, object]] = []
+    for rule in REGISTRY.all():
+        langs = sorted(lang.value for lang in rule.languages)
+        if language and language.lower() not in langs:
+            continue
+        if category and rule.category.value != category.lower():
+            continue
+        if severity and rule.severity.value != severity.lower():
+            continue
+        rows.append(
+            {
+                "id": rule.id,
+                "title": rule.title,
+                "severity": rule.severity.value,
+                "category": rule.category.value,
+                "languages": langs,
+                "cwe": rule.cwe,
+            }
+        )
+
+    if fmt == "json":
+        click.echo(json.dumps(rows, indent=2))
+        return
+
+    if not rows:
+        click.echo("No rules match.")
+        return
+    width = max(len(str(row["id"])) for row in rows)
+    for row in rows:
+        langs_str = ",".join(row["languages"])  # type: ignore[arg-type]
+        click.echo(f"{row['id']:<{width}}  {row['severity']:<8}  {langs_str:<20}  {row['title']}")
+
+
+@click.command("explain")
+@click.argument("rule_id")
+def _explain(rule_id: str) -> None:
+    """Show the full description of a rule."""
+    rule = REGISTRY.get(rule_id)
+    if rule is None:
+        click.echo(f"Unknown rule: {rule_id}", err=True)
+        sys.exit(2)
+    langs = ", ".join(sorted(lang.value for lang in rule.languages))
+    click.echo(f"{rule.id}  --  {rule.title}\n")
+    click.echo(f"Severity:  {rule.severity.value}")
+    click.echo(f"Category:  {rule.category.value}")
+    click.echo(f"Languages: {langs}")
+    if rule.cwe:
+        click.echo(f"CWE:       {rule.cwe}")
+    if rule.owasp:
+        click.echo(f"OWASP:     {rule.owasp}")
+    click.echo(f"Docs:      {rule.help_uri or finding_help_uri(rule.id)}\n")
+    click.echo(rule.description)
+
+
+@click.command("validate")
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Config file to validate (default: discovered).",
+)
+def _validate(config_path: Path | None) -> None:
+    """Validate a codeguard.toml (or pyproject [tool.codeguard])."""
+    path = config_path or find_config()
+    if path is None:
+        click.echo("No config file found. Nothing to validate.")
+        return
+    try:
+        cfg = load_config(path)
+    except ConfigError as exc:
+        click.echo(f"Invalid: {exc}", err=True)
+        sys.exit(3)
+
+    unknown = [
+        rid
+        for rid in {*cfg.enable, *cfg.disable, *cfg.severity_remap, *cfg.rules}
+        if rid not in REGISTRY
+    ]
+    if unknown:
+        click.echo(f"Invalid: {path}: unknown rule ID(s): {', '.join(sorted(unknown))}", err=True)
+        sys.exit(3)
+    conflict = set(cfg.enable) & set(cfg.disable)
+    if conflict:
+        click.echo(
+            f"Invalid: {path}: rule(s) both enabled and disabled: {', '.join(sorted(conflict))}",
+            err=True,
+        )
+        sys.exit(3)
+
+    click.echo(f"OK: {path}")
+
+
+@click.command("init")
+@click.option("--force", is_flag=True, help="Overwrite an existing codeguard.toml.")
+def _init(force: bool) -> None:
+    """Write a starter codeguard.toml in the current directory."""
+    target = Path("codeguard.toml")
+    if target.exists() and not force:
+        click.echo("codeguard.toml already exists (use --force to overwrite).", err=True)
+        sys.exit(2)
+    target.write_text(_STARTER_TOML, encoding="utf-8")
+    click.echo(f"Wrote {target}")
+
+
+# ---------------------------------------------------------------------------
+# baseline
+# ---------------------------------------------------------------------------
+
+
+def _scan_for_baseline(paths: tuple[Path, ...], config_path: Path | None) -> list[Finding]:
+    """Full scan (all rules, config applied) used to build/refresh a baseline."""
+    from codeguard.config import load_config
+    from codeguard.engine.discovery import DiscoveryConfig, discover
+    from codeguard.engine.policy import apply_config
+    from codeguard.engine.runner import AnalysisRunner
+
+    targets = [Path(p) for p in paths] or [Path(".")]
+    first = targets[0]
+    root = first if first.is_dir() else first.parent
+
+    cfg_file = config_path or find_config(root)
+    config = load_config(cfg_file)
+    cfg_root = Path(config.source_dir) if config.source_dir else root
+
+    disc = DiscoveryConfig(
+        include=list(config.include),
+        exclude=list(config.exclude),
+        respect_gitignore=config.gitignore,
+    )
+    findings = AnalysisRunner().run_files(discover(targets, disc, root=cfg_root))
+    findings = apply_config(findings, config, root=str(cfg_root))
+    return [f for f in findings if not f.suppressed]
+
+
+@click.group("baseline")
+def _baseline() -> None:
+    """Create and maintain a baseline file (findings that must not fail CI)."""
+
+
+@_baseline.command("create")
+@click.argument("paths", nargs=-1, type=click.Path(path_type=Path))
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=Path(".codeguard-baseline.json"),
+    show_default=True,
+)
+def _baseline_create(paths: tuple[Path, ...], config_path: Path | None, output: Path) -> None:
+    """Snapshot every current finding into a new baseline file."""
+    from codeguard.engine.baseline import Baseline
+
+    findings = _scan_for_baseline(paths, config_path)
+    Baseline.from_findings(findings, tool_version=__version__).save(output)
+    click.echo(f"Wrote {output} ({len(findings)} finding(s) baselined)")
+
+
+@_baseline.command("update")
+@click.argument("paths", nargs=-1, type=click.Path(path_type=Path))
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+)
+@click.option(
+    "--baseline",
+    "-b",
+    "baseline_file",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=Path(".codeguard-baseline.json"),
+    show_default=True,
+)
+def _baseline_update(
+    paths: tuple[Path, ...], config_path: Path | None, baseline_file: Path
+) -> None:
+    """Add newly-appeared findings to the baseline (keeps existing entries)."""
+    from codeguard.engine.baseline import Baseline
+
+    if not baseline_file.exists():
+        click.echo(f"No baseline at {baseline_file}; run `baseline create` first.", err=True)
+        sys.exit(2)
+    findings = _scan_for_baseline(paths, config_path)
+    before = len(Baseline.load(baseline_file))
+    updated = Baseline.load(baseline_file).updated_with(findings)
+    updated.save(baseline_file)
+    click.echo(f"Updated {baseline_file} (+{len(updated) - before} new entry/entries)")
+
+
+@_baseline.command("prune")
+@click.argument("paths", nargs=-1, type=click.Path(path_type=Path))
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+)
+@click.option(
+    "--baseline",
+    "-b",
+    "baseline_file",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=Path(".codeguard-baseline.json"),
+    show_default=True,
+)
+def _baseline_prune(paths: tuple[Path, ...], config_path: Path | None, baseline_file: Path) -> None:
+    """Drop baseline entries whose finding no longer occurs."""
+    from codeguard.engine.baseline import Baseline
+
+    if not baseline_file.exists():
+        click.echo(f"No baseline at {baseline_file}.", err=True)
+        sys.exit(2)
+    live = {f.fingerprint for f in _scan_for_baseline(paths, config_path) if f.fingerprint}
+    before = len(Baseline.load(baseline_file))
+    pruned = Baseline.load(baseline_file).pruned(live)
+    pruned.save(baseline_file)
+    click.echo(f"Pruned {baseline_file} (-{before - len(pruned)} stale entry/entries)")
+
+
+# ---------------------------------------------------------------------------
+# suppressions
+# ---------------------------------------------------------------------------
+
+
+@click.group("suppressions")
+def _suppressions() -> None:
+    """Inspect `# codeguard: ignore[...]` comments across the codebase."""
+
+
+@_suppressions.command("list")
+@click.argument("paths", nargs=-1, type=click.Path(path_type=Path))
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+)
+@click.option("--expired", is_flag=True, help="Show only expired suppressions (exit 1 if any).")
+@click.option("--unused", is_flag=True, help="Show only suppressions that suppress nothing.")
+@click.option("--format", "fmt", type=click.Choice(["table", "json"]), default="table")
+@click.option(
+    "--now",
+    "now_str",
+    metavar="YYYY-MM-DD",
+    default=None,
+    help="Date used to evaluate `until=` (default: today).",
+)
+def _suppressions_list(
+    paths: tuple[Path, ...],
+    config_path: Path | None,
+    expired: bool,
+    unused: bool,
+    fmt: str,
+    now_str: str | None,
+) -> None:
+    """List every suppression comment with its status (active / expired / unused)."""
+    import json as _json
+    from datetime import date
+
+    from codeguard.config import load_config
+    from codeguard.engine.discovery import DiscoveryConfig, discover
+    from codeguard.engine.runner import AnalysisRunner
+    from codeguard.engine.suppressions import SuppressionSet
+    from codeguard.lang.registry import language_for_path
+
+    today = date.fromisoformat(now_str) if now_str else date.today()
+
+    targets = [Path(p) for p in paths] or [Path(".")]
+    first = targets[0]
+    root = first if first.is_dir() else first.parent
+    config = load_config(config_path or find_config(root))
+    cfg_root = Path(config.source_dir) if config.source_dir else root
+    disc = DiscoveryConfig(
+        include=list(config.include),
+        exclude=list(config.exclude),
+        respect_gitignore=config.gitignore,
+    )
+    files = discover(targets, disc, root=cfg_root)
+    runner = AnalysisRunner()
+
+    rows: list[dict[str, object]] = []
+    for path in files:
+        if language_for_path(path) is None:
+            continue
+        source = path.read_text(encoding="utf-8", errors="replace")
+        suppset = SuppressionSet.parse(source)
+        if not suppset.all():
+            continue
+        try:
+            findings = runner.run(source, filename=str(path), now=today)
+        except SyntaxError:
+            findings = []
+        suppressed_at = {(f.rule_id, f.location.line) for f in findings if f.suppressed}
+        suppressed_rules = {f.rule_id for f in findings if f.suppressed}
+
+        for supp in suppset.all():
+            if supp.is_expired(today):
+                status = "expired"
+            elif supp.file_level:
+                status = "active" if supp.rule_ids & suppressed_rules else "unused"
+            else:
+                status = (
+                    "active"
+                    if any((rid, supp.line) in suppressed_at for rid in supp.rule_ids)
+                    else "unused"
+                )
+            rows.append(
+                {
+                    "file": str(path),
+                    "line": supp.line,
+                    "rules": sorted(supp.rule_ids),
+                    "scope": "file" if supp.file_level else "line",
+                    "reason": supp.reason,
+                    "until": supp.until.isoformat() if supp.until else None,
+                    "status": status,
+                }
+            )
+
+    if expired:
+        rows = [r for r in rows if r["status"] == "expired"]
+    if unused:
+        rows = [r for r in rows if r["status"] == "unused"]
+
+    if fmt == "json":
+        click.echo(_json.dumps(rows, indent=2))
+    elif not rows:
+        click.echo("No suppressions." if not (expired or unused) else "None.")
+    else:
+        for r in rows:
+            rules = ",".join(r["rules"])  # type: ignore[arg-type]
+            reason = r["reason"] or "(no reason)"
+            click.echo(f"{r['file']}:{r['line']}  {r['status']:<8} {rules:<24} {reason}")
+
+    if expired and rows:
+        sys.exit(1)