codeguard-cli 2.0.0__py3-none-any.whl

codeguard/config/loader.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Find and load a CodeGuard config file."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from .schema import Config, SchemaError
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+_FILENAMES = ("codeguard.toml", ".codeguard.toml")
+
+
+class ConfigError(Exception):
+    """A config file was found but is malformed or has unknown keys."""
+
+
+def find_config(start: Path | None = None) -> Path | None:
+    """Walk up from *start* (cwd by default) looking for a config file.
+
+    Returns the first ``codeguard.toml`` / ``.codeguard.toml`` found, or the
+    first ``pyproject.toml`` that contains a ``[tool.codeguard]`` table.
+    """
+    here = (start or Path.cwd()).resolve()
+    for directory in (here, *here.parents):
+        for name in _FILENAMES:
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate
+        pyproject = directory / "pyproject.toml"
+        if pyproject.is_file() and _has_tool_table(pyproject):
+            return pyproject
+        if (directory / ".git").exists():
+            break
+    return None
+
+
+def _has_tool_table(pyproject: Path) -> bool:
+    try:
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    except (tomllib.TOMLDecodeError, OSError):
+        return False
+    return isinstance(data.get("tool"), dict) and "codeguard" in data["tool"]
+
+
+def load_config(path: Path | None) -> Config:
+    """Load and validate the config at *path*.
+
+    ``None`` -> an empty default :class:`Config`.  Raises :class:`ConfigError`
+    on a parse error or a schema violation.
+    """
+    if path is None:
+        return Config()
+
+    try:
+        raw = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{path}: invalid TOML: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+
+    tool_table = raw.get("tool", {})
+    if isinstance(tool_table, dict) and isinstance(tool_table.get("codeguard"), dict):
+        table = tool_table["codeguard"]
+    elif isinstance(raw.get("codeguard"), dict):
+        table = raw["codeguard"]
+    elif path.name == "pyproject.toml":
+        table = {}
+    else:
+        table = raw
+
+    if not isinstance(table, dict):
+        raise ConfigError(f"{path}: [codeguard] must be a table")
+
+    try:
+        cfg = Config.from_dict(table)
+    except SchemaError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+
+    cfg.source_dir = str(path.parent)
+    return cfg

codeguard/config/schema.py

@@ -0,0 +1,172 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The ``codeguard.toml`` schema, as validated dataclasses.
+
+A single ``[tool.codeguard]`` table (or the top-level table of a standalone
+``codeguard.toml``) maps to :class:`Config`.  :func:`Config.from_dict` validates
+and raises :class:`~codeguard.config.loader.ConfigError` with a precise message
+on anything unknown or malformed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any
+
+from codeguard.engine.finding import Severity
+from codeguard.lang.base import Language
+
+_SEVERITIES = {s.value for s in Severity}
+_LANGUAGES = {lang.value for lang in Language}
+
+
+class SchemaError(Exception):
+    """A schema violation, re-raised as ConfigError by the loader."""
+
+
+def _expect_str_list(value: Any, key: str) -> list[str]:
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise SchemaError(f"{key!r} must be a list of strings")
+    return list(value)
+
+
+def _expect_bool(value: Any, key: str) -> bool:
+    if not isinstance(value, bool):
+        raise SchemaError(f"{key!r} must be true or false")
+    return value
+
+
+def _expect_severity(value: Any, key: str) -> str:
+    if value not in _SEVERITIES:
+        raise SchemaError(f"{key!r} must be one of {sorted(_SEVERITIES)}, got {value!r}")
+    return str(value)
+
+
+@dataclass
+class RuleSettings:
+    """Per-rule tuning from ``[tool.codeguard.rules.<ID>]``."""
+
+    severity: str | None = None
+    confidence_min: float | None = None
+
+    @classmethod
+    def from_dict(cls, rule_id: str, data: dict[str, Any]) -> RuleSettings:
+        out = cls()
+        for k, v in data.items():
+            if k == "severity":
+                out.severity = _expect_severity(v, f"rules.{rule_id}.severity")
+            elif k == "confidence_min":
+                if not isinstance(v, (int, float)) or not (0.0 <= float(v) <= 1.0):
+                    raise SchemaError(f"rules.{rule_id}.confidence_min must be in [0.0, 1.0]")
+                out.confidence_min = float(v)
+            else:
+                raise SchemaError(f"unknown key rules.{rule_id}.{k}")
+        return out
+
+
+@dataclass
+class RuleOverride:
+    """A path-scoped override from ``[[tool.codeguard.overrides]]``."""
+
+    path: str
+    disable: list[str] = field(default_factory=list)
+    enable: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RuleOverride:
+        if "path" not in data or not isinstance(data["path"], str):
+            raise SchemaError("each [[overrides]] needs a string 'path'")
+        out = cls(path=data["path"])
+        for k, v in data.items():
+            if k == "path":
+                continue
+            if k == "disable":
+                out.disable = _expect_str_list(v, "overrides.disable")
+            elif k == "enable":
+                out.enable = _expect_str_list(v, "overrides.enable")
+            else:
+                raise SchemaError(f"unknown key overrides.{k}")
+        return out
+
+
+@dataclass
+class Config:
+    """The whole ``[tool.codeguard]`` table."""
+
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    languages: list[str] = field(default_factory=list)
+    gitignore: bool = True
+    fail_on: str = "info"
+    output: str = "human"
+    jobs: int = 0  # 0 = auto
+    baseline: str | None = None
+    rule_paths: list[str] = field(default_factory=list)
+    enable: list[str] = field(default_factory=list)
+    disable: list[str] = field(default_factory=list)
+    severity_remap: dict[str, str] = field(default_factory=dict)
+    rules: dict[str, RuleSettings] = field(default_factory=dict)
+    overrides: list[RuleOverride] = field(default_factory=list)
+    #: Directory the config was loaded from (for resolving relative paths).
+    source_dir: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Config:
+        out = cls()
+        known = {f.name for f in fields(cls)} - {
+            "rules",
+            "overrides",
+            "source_dir",
+            "enable",
+            "disable",
+        }
+        for key, value in data.items():
+            if key in ("include", "exclude", "languages", "rule_paths"):
+                lst = _expect_str_list(value, key)
+                if key == "languages":
+                    bad = set(lst) - _LANGUAGES
+                    if bad:
+                        raise SchemaError(f"unknown language(s): {sorted(bad)}")
+                setattr(out, key, lst)
+            elif key == "gitignore":
+                out.gitignore = _expect_bool(value, key)
+            elif key == "fail_on":
+                if value != "never":
+                    _expect_severity(value, key)
+                out.fail_on = str(value)
+            elif key == "output":
+                if value not in {"human", "json", "json-legacy", "sarif"}:
+                    raise SchemaError(f"'output' must be a valid format, got {value!r}")
+                out.output = str(value)
+            elif key == "jobs":
+                if not isinstance(value, int) or value < 0:
+                    raise SchemaError("'jobs' must be a non-negative integer (0 = auto)")
+                out.jobs = value
+            elif key == "baseline":
+                if not isinstance(value, str):
+                    raise SchemaError("'baseline' must be a string path")
+                out.baseline = value
+            elif key == "severity_remap":
+                if not isinstance(value, dict):
+                    raise SchemaError("'severity_remap' must be a table of rule-id -> severity")
+                for rid, sev in value.items():
+                    _expect_severity(sev, f"severity_remap.{rid}")
+                out.severity_remap = dict(value)
+            elif key == "rules":
+                if not isinstance(value, dict):
+                    raise SchemaError("'[rules]' must be a table")
+                for rid, rdata in value.items():
+                    if rid == "enable":
+                        out.enable = _expect_str_list(rdata, "rules.enable")
+                    elif rid == "disable":
+                        out.disable = _expect_str_list(rdata, "rules.disable")
+                    elif isinstance(rdata, dict):
+                        out.rules[rid] = RuleSettings.from_dict(rid, rdata)
+                    else:
+                        raise SchemaError(f"'[rules.{rid}]' must be a table")
+            elif key == "overrides":
+                if not isinstance(value, list):
+                    raise SchemaError("'overrides' must be an array of tables")
+                out.overrides = [RuleOverride.from_dict(o) for o in value]
+            elif key not in known:
+                raise SchemaError(f"unknown key {key!r}")
+        return out

codeguard/engine/__init__.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: Apache-2.0
+"""CodeGuard rule engine."""
+
+from .context import RuleContext
+from .finding import Category, Finding, Fix, Location, Severity, TextEdit, Triage
+from .registry import REGISTRY, RuleRegistry
+from .rule import AstRule, Rule, TreeSitterRule
+from .runner import AnalysisRunner
+
+__all__ = [
+    "REGISTRY",
+    "AnalysisRunner",
+    "AstRule",
+    "Category",
+    "Finding",
+    "Fix",
+    "Location",
+    "Rule",
+    "RuleContext",
+    "RuleRegistry",
+    "Severity",
+    "TextEdit",
+    "TreeSitterRule",
+    "Triage",
+]

codeguard/engine/baseline.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Baseline files -- freeze the findings that exist today so CI only fails on new ones.
+
+A baseline is a JSON file of finding fingerprints.  ``scan --baseline path`` marks
+any finding whose fingerprint is in the file as ``baselined`` (excluded from the
+exit code, still shown).  ``codeguard baseline create / update / prune`` manages
+the file.
+
+Fingerprints (see :mod:`codeguard.engine.fingerprint`) are stable across
+reformatting and line moves, so a baselined finding stays matched as the file
+around it changes -- and a genuinely new problem is not.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .finding import Finding
+
+SCHEMA_VERSION = 1
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+@dataclass
+class Baseline:
+    """The contents of a baseline file."""
+
+    fingerprints: dict[str, dict[str, str]] = field(default_factory=dict)
+    tool_version: str = "0.0.0"
+    created: str = field(default_factory=_now)
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_findings(cls, findings: list[Finding], *, tool_version: str = "0.0.0") -> Baseline:
+        b = cls(tool_version=tool_version)
+        b._add(findings)
+        return b
+
+    @classmethod
+    def load(cls, path: Path) -> Baseline:
+        """Load a baseline file.  Raises ``ValueError`` on a malformed file."""
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            raise ValueError(f"{path}: cannot read baseline: {exc}") from exc
+        if not isinstance(data, dict) or "fingerprints" not in data:
+            raise ValueError(f"{path}: not a CodeGuard baseline file")
+        fps = data.get("fingerprints", {})
+        if not isinstance(fps, dict):
+            raise ValueError(f"{path}: 'fingerprints' must be an object")
+        return cls(
+            fingerprints={str(k): dict(v) for k, v in fps.items()},
+            tool_version=str(data.get("tool_version", "0.0.0")),
+            created=str(data.get("created", _now())),
+        )
+
+    # ------------------------------------------------------------------
+    # Query / mutate
+    # ------------------------------------------------------------------
+
+    def __contains__(self, fingerprint: object) -> bool:
+        return fingerprint in self.fingerprints
+
+    def __len__(self) -> int:
+        return len(self.fingerprints)
+
+    def _add(self, findings: list[Finding]) -> None:
+        for f in findings:
+            if not f.fingerprint or f.fingerprint in self.fingerprints:
+                continue
+            self.fingerprints[f.fingerprint] = {
+                "rule_id": f.rule_id,
+                "file": f.location.file,
+                "first_seen": _now(),
+            }
+
+    def updated_with(self, findings: list[Finding]) -> Baseline:
+        """Return a copy with any new findings added (existing ``first_seen`` kept)."""
+        out = Baseline(
+            fingerprints=dict(self.fingerprints),
+            tool_version=self.tool_version,
+            created=self.created,
+        )
+        out._add(findings)
+        return out
+
+    def pruned(self, live_fingerprints: set[str]) -> Baseline:
+        """Return a copy with entries that no longer correspond to a finding removed."""
+        return Baseline(
+            fingerprints={k: v for k, v in self.fingerprints.items() if k in live_fingerprints},
+            tool_version=self.tool_version,
+            created=self.created,
+        )
+
+    # ------------------------------------------------------------------
+    # Serialise
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "version": SCHEMA_VERSION,
+            "created": self.created,
+            "tool_version": self.tool_version,
+            "fingerprints": dict(sorted(self.fingerprints.items())),
+        }
+
+    def save(self, path: Path) -> None:
+        path.write_text(json.dumps(self.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+
+def apply_baseline(findings: list[Finding], baseline: Baseline) -> list[Finding]:
+    """Return *findings* with those present in *baseline* marked ``baselined``."""
+    return [f.as_baselined() if f.fingerprint in baseline else f for f in findings]

codeguard/engine/context.py

@@ -0,0 +1,61 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``RuleContext`` -- everything a rule needs to analyse one file."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass, field
+
+from codeguard.lang.base import Language, LanguageSupport
+from codeguard.lang.node import SourceNode
+
+
+@dataclass
+class RuleContext:
+    """Per-file analysis context handed to :meth:`~codeguard.engine.rule.Rule.analyze`.
+
+    Attributes
+    ----------
+    filename:
+        Path (or ``"<stdin>"``) the source came from.
+    source:
+        Raw source text.
+    language:
+        The detected :class:`~codeguard.lang.base.Language`.
+    lang:
+        The parser backend for *language* (for structural ``query()`` access).
+    root:
+        The parsed tree as a uniform :class:`~codeguard.lang.node.SourceNode`.
+    dataflow:
+        Reserved for the intraprocedural taint pass (a later milestone); always
+        ``None`` today.
+    """
+
+    filename: str
+    source: str
+    language: Language
+    lang: LanguageSupport
+    root: SourceNode
+    dataflow: None = None
+    _lines: list[str] | None = field(default=None, repr=False, compare=False)
+
+    @property
+    def lines(self) -> list[str]:
+        """Source split into lines, cached."""
+        if self._lines is None:
+            self._lines = self.source.splitlines()
+        return self._lines
+
+    @property
+    def python_ast(self) -> ast.Module:
+        """The native :class:`ast.Module` for a Python file.
+
+        Raises
+        ------
+        TypeError
+            If this context is not for Python source.
+        """
+        node = self.root.native
+        if not isinstance(node, ast.Module):
+            raise TypeError(f"python_ast requested for a {self.language.value} context")
+        return node

codeguard/engine/discovery.py

@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: Apache-2.0
+"""File discovery -- decide which files a scan should look at.
+
+Rules never touch the filesystem; the runner asks this module for a list of
+files.  Discovery honours ``.gitignore`` (repo root), a built-in skip list for
+directories that never contain first-party source, and user ``--include`` /
+``--exclude`` globs.  Directory symlinks are not followed and every file is
+de-duplicated by real path.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import pathspec
+
+from codeguard.lang.registry import language_for_path
+
+#: Directory names that never hold first-party source.  Pruned before globbing.
+DEFAULT_SKIP_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        ".bzr",
+        "node_modules",
+        ".venv",
+        "venv",
+        "env",
+        ".env",
+        "__pycache__",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        ".tox",
+        ".nox",
+        ".eggs",
+        "dist",
+        "build",
+        "site-packages",
+        ".cache",
+        ".idea",
+        ".vscode",
+    }
+)
+
+#: Filename globs skipped by default (generated / vendored artefacts).
+DEFAULT_SKIP_FILES: tuple[str, ...] = ("*.min.js", "*.bundle.js", "*.d.ts")
+
+
+@dataclass
+class DiscoveryConfig:
+    """Inputs that shape a discovery pass."""
+
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    respect_gitignore: bool = True
+    skip_dirs: frozenset[str] = DEFAULT_SKIP_DIRS
+    skip_files: tuple[str, ...] = DEFAULT_SKIP_FILES
+
+
+def _load_gitignore(root: Path) -> pathspec.PathSpec[Any] | None:
+    patterns: list[str] = []
+    for rel in (".gitignore", ".git/info/exclude"):
+        p = root / rel
+        if p.is_file():
+            patterns.extend(p.read_text(encoding="utf-8", errors="replace").splitlines())
+    if not patterns:
+        return None
+    return pathspec.PathSpec.from_lines("gitignore", patterns)
+
+
+def _spec(patterns: Iterable[str]) -> pathspec.PathSpec[Any] | None:
+    patterns = [p for p in patterns if p.strip()]
+    return pathspec.PathSpec.from_lines("gitignore", patterns) if patterns else None
+
+
+def discover(
+    paths: Sequence[str | Path],
+    config: DiscoveryConfig | None = None,
+    *,
+    root: str | Path | None = None,
+) -> list[Path]:
+    """Return the sorted, de-duplicated list of files to scan.
+
+    Parameters
+    ----------
+    paths:
+        Files or directories given on the command line.
+    config:
+        Discovery settings.  Defaults are used when omitted.
+    root:
+        Base directory for ``.gitignore`` lookup and relative-path matching.
+        Defaults to the current working directory.
+    """
+    cfg = config or DiscoveryConfig()
+    base = Path(root or os.getcwd()).resolve()
+
+    gitignore = _load_gitignore(base) if cfg.respect_gitignore else None
+    include_spec = _spec(cfg.include)
+    exclude_spec = _spec([*cfg.exclude, *cfg.skip_files])
+
+    seen: set[Path] = set()
+    out: list[Path] = []
+
+    def rel(p: Path) -> str:
+        try:
+            return p.resolve().relative_to(base).as_posix()
+        except ValueError:
+            return p.name
+
+    def want(p: Path) -> bool:
+        if language_for_path(p) is None:
+            return False
+        r = rel(p)
+        if exclude_spec and exclude_spec.match_file(r):
+            return False
+        if gitignore and gitignore.match_file(r):
+            return False
+        if include_spec and not include_spec.match_file(r):
+            return False
+        return True
+
+    def add(p: Path) -> None:
+        real = p.resolve()
+        if real in seen:
+            return
+        seen.add(real)
+        out.append(p)
+
+    for raw in paths:
+        start = Path(raw)
+        if start.is_file():
+            # An explicitly named file bypasses include/exclude/gitignore
+            # (the user asked for it) but still must be a supported language.
+            if language_for_path(start) is not None:
+                add(start)
+            continue
+        if not start.is_dir():
+            continue
+        for dirpath, dirnames, filenames in os.walk(start, followlinks=False):
+            d = Path(dirpath)
+            dirnames[:] = [
+                name
+                for name in dirnames
+                if name not in cfg.skip_dirs
+                and not (d / name).is_symlink()
+                and not (gitignore and gitignore.match_file(rel(d / name) + "/"))
+            ]
+            for name in filenames:
+                fp = d / name
+                if not fp.is_symlink() and want(fp):
+                    add(fp)
+
+    out.sort(key=lambda p: p.as_posix())
+    return out