codeguard-cli 2.0.0__py3-none-any.whl

codeguard/engine/finding.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Finding -- the atomic output unit of a CodeGuard analysis run."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field, replace
+
+_SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"]
+
+
+class Severity(str, enum.Enum):
+    """Finding severity, in descending order of urgency."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+    def __lt__(self, other: Severity) -> bool:  # type: ignore[override]
+        return _SEVERITY_ORDER.index(self.value) > _SEVERITY_ORDER.index(other.value)
+
+    def __le__(self, other: Severity) -> bool:  # type: ignore[override]
+        return self == other or self < other
+
+    def __gt__(self, other: Severity) -> bool:  # type: ignore[override]
+        return other < self
+
+    def __ge__(self, other: Severity) -> bool:  # type: ignore[override]
+        return self == other or self > other
+
+
+class Category(str, enum.Enum):
+    """Rule category."""
+
+    SECURITY = "security"
+    QUALITY = "quality"
+    PERFORMANCE = "performance"
+    AI_SMELL = "ai-smell"
+    META = "meta"
+
+
+@dataclass(frozen=True)
+class Location:
+    """Precise source location of a finding.
+
+    Line and column numbers are **1-indexed** to match what editors and SARIF
+    expect.  ``col`` is the start column; ``end_line`` / ``end_col`` are optional
+    end positions.
+    """
+
+    file: str
+    line: int
+    col: int
+    end_line: int | None = None
+    end_col: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.line < 1:
+            raise ValueError(f"line must be >= 1, got {self.line}")
+        if self.col < 1:
+            raise ValueError(f"col must be >= 1, got {self.col}")
+
+
+@dataclass(frozen=True)
+class TextEdit:
+    """A single replacement in a source file, for an autofix.
+
+    Reserved for the autofix milestone; no rule emits one today.
+    """
+
+    start_line: int
+    start_col: int
+    end_line: int
+    end_col: int
+    replacement: str
+
+
+@dataclass(frozen=True)
+class Fix:
+    """A suggested code change that resolves a finding.
+
+    Reserved for the autofix milestone; ``Finding.fix`` is always ``None`` today.
+    """
+
+    description: str
+    edits: tuple[TextEdit, ...]
+    safe: bool = True
+
+
+@dataclass(frozen=True)
+class Triage:
+    """A verdict on whether a finding is a true positive.
+
+    Reserved for a post-2.0 offline triage layer; ``Finding.triage`` is always
+    ``None`` today.
+    """
+
+    verdict: str  # "true" | "false" | "uncertain"
+    rationale: str
+    source: str  # "heuristic" | "offline-model" | "human"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single diagnostic produced by a rule.
+
+    ``rule_id`` is a stable public contract -- it will never be renumbered.
+    Tools, IDE plugins, and inline suppressions key on it.
+
+    Attributes
+    ----------
+    rule_id:
+        Stable rule identifier, e.g. ``CG-SEC-001``.
+    title:
+        Short (<= 80 char) human-readable title.
+    description:
+        Full explanation of what was detected and why it matters.
+    severity:
+        How urgent this finding is.
+    category:
+        Broad category the rule belongs to.
+    location:
+        Where in the source the finding was detected.
+    cwe:
+        CWE identifier, e.g. ``CWE-89``.
+    owasp:
+        OWASP category reference, e.g. ``A03:2021 - Injection``.
+    fix_suggestion:
+        Actionable one-sentence fix.  Optional but strongly encouraged.
+    confidence:
+        Detection confidence in ``[0.0, 1.0]``.  ``1.0`` means the rule is
+        certain; ``< 1.0`` signals heuristic detection.
+    suppressed:
+        True when a ``# codeguard: ignore[RULE-ID]`` comment (or the file-level
+        form) applied to this finding.  Suppressed findings are still returned so
+        callers can audit suppression usage.
+    fingerprint:
+        Stable identity of this finding across reformatting and line moves,
+        assigned by the runner.  Empty until assigned.
+    fix:
+        A suggested autofix, or ``None``.  Reserved for a later milestone.
+    triage:
+        A true/false-positive verdict, or ``None``.  Reserved for a later
+        milestone.
+    """
+
+    rule_id: str
+    title: str
+    description: str
+    severity: Severity
+    category: Category
+    location: Location
+    cwe: str | None = None
+    owasp: str | None = None
+    fix_suggestion: str | None = None
+    confidence: float = 1.0
+    suppressed: bool = False
+    baselined: bool = False
+    fingerprint: str = ""
+    fix: Fix | None = field(default=None)
+    triage: Triage | None = field(default=None)
+
+    def __post_init__(self) -> None:
+        if not self.rule_id:
+            raise ValueError("rule_id must not be empty")
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(f"confidence must be in [0.0, 1.0], got {self.confidence!r}")
+
+    def as_suppressed(self) -> Finding:
+        """Return a copy of this finding with ``suppressed=True``."""
+        return replace(self, suppressed=True)
+
+    def with_fingerprint(self, fingerprint: str) -> Finding:
+        """Return a copy of this finding with ``fingerprint`` set."""
+        return replace(self, fingerprint=fingerprint)
+
+    def as_baselined(self) -> Finding:
+        """Return a copy of this finding marked as present in the baseline."""
+        return replace(self, baselined=True)
+
+    def to_dict(self) -> dict:  # type: ignore[type-arg]
+        """Serialise to a plain dict suitable for JSON output."""
+        return {
+            "rule_id": self.rule_id,
+            "title": self.title,
+            "description": self.description,
+            "severity": self.severity.value,
+            "category": self.category.value,
+            "location": {
+                "file": self.location.file,
+                "line": self.location.line,
+                "col": self.location.col,
+                "end_line": self.location.end_line,
+                "end_col": self.location.end_col,
+            },
+            "cwe": self.cwe,
+            "owasp": self.owasp,
+            "fix_suggestion": self.fix_suggestion,
+            "confidence": self.confidence,
+            "suppressed": self.suppressed,
+            "baselined": self.baselined,
+            "fingerprint": self.fingerprint,
+        }

codeguard/engine/fingerprint.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Stable finding fingerprints.
+
+A fingerprint identifies "the same finding" across reformatting, whitespace
+changes, and line moves, so a baseline entry or a suppression stays matched to
+its finding.  It deliberately *does* change when the finding's own statement or
+its enclosing scope changes -- that is what makes diff/baseline workflows
+meaningful.
+
+Scheme ``codeguard/v1``:
+
+    sha256(rule_id \\0 relative_path \\0 scope \\0 normalized_statement)[:16]
+
+where *scope* is the dotted name of the enclosing function/class (Python) and
+*normalized_statement* is the finding's own source line with string and number
+literals masked and comments / whitespace stripped.  Line numbers are
+deliberately excluded so a finding survives being moved within its scope.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import os
+import re
+
+SCHEME = "codeguard/v1"
+
+_STRING_RE = re.compile(r"""(['"]).*?(?<!\\)\1""", re.DOTALL)
+_NUMBER_RE = re.compile(r"(?<![A-Za-z_])\d[\d_]*(?:\.\d[\d_]*)?")
+_COMMENT_RE = re.compile(r"(#|//).*$")
+_WS_RE = re.compile(r"\s+")
+
+_SCOPE_NODES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+
+def relative_path(file: str, *, root: str | None = None) -> str:
+    """Normalise *file* to a forward-slash path relative to *root* (cwd by default).
+
+    Fingerprints assume runs happen from the project root (as pre-commit and CI
+    do).  Paths that cannot be made relative are returned unchanged.
+    """
+    if file in ("<stdin>", "<string>"):
+        return file
+    base = root or os.getcwd()
+    try:
+        rel = os.path.relpath(file, base)
+    except ValueError:
+        rel = file
+    return rel.replace(os.sep, "/")
+
+
+def _normalize(text: str) -> str:
+    text = _STRING_RE.sub("STR", text)
+    text = _COMMENT_RE.sub("", text)
+    text = _NUMBER_RE.sub("NUM", text)
+    return _WS_RE.sub("", text)
+
+
+def _normalized_statement(source: str, line: int) -> str:
+    lines = source.splitlines()
+    if 1 <= line <= len(lines):
+        return _normalize(lines[line - 1])
+    return ""
+
+
+def python_scope(tree: ast.AST, line: int) -> str:
+    """Return the dotted name of the innermost function/class enclosing *line*.
+
+    ``""`` for module level.  E.g. ``"MyClass.method"`` or ``"handler"``.
+    """
+    path: list[str] = []
+
+    def visit(node: ast.AST, prefix: list[str]) -> None:
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, _SCOPE_NODES):
+                start = child.lineno
+                end = getattr(child, "end_lineno", start)
+                if start <= line <= end:
+                    prefix.append(child.name)
+                    path[:] = list(prefix)
+                    visit(child, prefix)
+                    prefix.pop()
+            else:
+                visit(child, prefix)
+
+    visit(tree, [])
+    return ".".join(path)
+
+
+def compute(rule_id: str, rel_path: str, source: str, line: int, *, scope: str = "") -> str:
+    """Return the 16-hex-char fingerprint for a finding."""
+    payload = f"{rule_id}\0{rel_path}\0{scope}\0{_normalized_statement(source, line)}"
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]

codeguard/engine/gitdiff.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Git helpers for diff-aware scanning.
+
+``scan --diff <ref>`` and ``codeguard ci`` only look at files that changed, so a
+pull request is checked in seconds and only *new* problems surface.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+_CANDIDATE_BASES = (
+    "origin/main",
+    "origin/master",
+    "main",
+    "master",
+    "origin/HEAD",
+)
+
+
+def _git(args: list[str], *, root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), *args],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (OSError, FileNotFoundError):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout
+
+
+def is_git_repo(root: Path) -> bool:
+    return _git(["rev-parse", "--git-dir"], root=root) is not None
+
+
+def default_base(root: Path) -> str | None:
+    """Best guess at the branch a PR would target."""
+    for ref in _CANDIDATE_BASES:
+        if _git(["rev-parse", "--verify", "--quiet", ref], root=root) is not None:
+            return ref
+    return None
+
+
+def changed_files(
+    ref: str,
+    *,
+    root: Path,
+    use_merge_base: bool = True,
+    include_untracked: bool = True,
+) -> list[Path]:
+    """Return the files that changed relative to *ref* (added / modified, not deleted).
+
+    ``use_merge_base`` compares against ``git merge-base ref HEAD`` (``ref...HEAD``),
+    which is what you want for a pull request.  Set it False to diff against the
+    literal *ref*.
+    """
+    spec = f"{ref}...HEAD" if use_merge_base else f"{ref}..HEAD"
+    names: set[str] = set()
+
+    committed = _git(["diff", "--name-only", "--diff-filter=d", spec], root=root)
+    if committed:
+        names.update(line for line in committed.splitlines() if line)
+
+    # Uncommitted (working tree + index) changes vs HEAD, so a local run before
+    # committing still sees the edits.
+    working = _git(["diff", "--name-only", "--diff-filter=d", "HEAD"], root=root)
+    if working:
+        names.update(line for line in working.splitlines() if line)
+
+    if include_untracked:
+        untracked = _git(["ls-files", "--others", "--exclude-standard"], root=root)
+        if untracked:
+            names.update(line for line in untracked.splitlines() if line)
+
+    return sorted((root / name) for name in names if (root / name).is_file())

codeguard/engine/policy.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Apply configuration to a raw finding list.
+
+Keeps the CLI thin: given the findings from a scan plus a
+:class:`~codeguard.config.schema.Config`, produce the findings to report
+(severity remapped, per-path rules applied, confidence floors enforced) and
+decide whether any of them should fail the run.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pathspec
+
+from codeguard.config.schema import Config
+from codeguard.engine.finding import Finding, Severity
+from codeguard.engine.fingerprint import relative_path
+
+_SEV = {s.value: s for s in Severity}
+
+
+def _matches(path_glob: str, rel_file: str) -> bool:
+    spec = pathspec.PathSpec.from_lines("gitignore", [path_glob])
+    return spec.match_file(rel_file)
+
+
+def apply_config(
+    findings: list[Finding], config: Config, *, root: str | None = None
+) -> list[Finding]:
+    """Return the findings to report after severity remap + per-path overrides.
+
+    Findings suppressed by a path override are returned with ``suppressed=True``
+    (like inline suppressions) so ``--show-suppressed`` and SARIF still see them.
+    """
+    remap = dict(config.severity_remap)
+    per_rule = config.rules
+
+    out: list[Finding] = []
+    for f in findings:
+        rel_file = relative_path(f.location.file, root=root)
+        new_sev = f.severity
+        if f.rule_id in remap:
+            new_sev = _SEV[remap[f.rule_id]]
+        rs = per_rule.get(f.rule_id)
+        if rs and rs.severity:
+            new_sev = _SEV[rs.severity]
+
+        suppressed = f.suppressed
+        for ov in config.overrides:
+            if _matches(ov.path, rel_file):
+                if ov.disable and (f.rule_id in ov.disable or "ALL" in ov.disable):
+                    suppressed = True
+                if ov.enable and f.rule_id not in ov.enable:
+                    suppressed = True
+
+        if new_sev != f.severity or suppressed != f.suppressed:
+            f = replace(f, severity=new_sev, suppressed=suppressed)
+
+        if rs and rs.confidence_min is not None and f.confidence < rs.confidence_min:
+            continue
+
+        out.append(f)
+    return out
+
+
+def gating_findings(findings: list[Finding], fail_on: str) -> list[Finding]:
+    """The findings that should fail the run: active, not baselined, and at or
+    above the ``fail_on`` threshold.  ``fail_on == "never"`` -> always empty.
+    """
+    if fail_on == "never":
+        return []
+    threshold = _SEV[fail_on]
+    return [f for f in findings if not f.suppressed and not f.baselined and f.severity >= threshold]

codeguard/engine/registry.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Rule registry — the central catalogue of all registered CodeGuard rules."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .rule import Rule
+
+
+class RuleRegistry:
+    """Central registry that maps rule IDs to :class:`~codeguard.engine.rule.Rule` instances.
+
+    Rules self-register at import time via :meth:`register`.  The module-level
+    :data:`REGISTRY` singleton is what the runner uses; tests may construct
+    isolated registries to avoid cross-rule interference.
+
+    Example
+    -------
+    ::
+
+        from codeguard.engine.registry import REGISTRY
+
+        for rule in REGISTRY:
+            print(rule.id, rule.title)
+    """
+
+    def __init__(self) -> None:
+        self._rules: dict[str, Rule] = {}
+
+    def register(self, rule: Rule) -> None:
+        """Register *rule*.
+
+        Raises
+        ------
+        ValueError
+            If another rule with the same ``id`` is already registered.
+            Rule IDs are a public contract; duplicates are a hard error.
+        TypeError
+            If *rule* does not have a non-empty ``id`` attribute.
+        """
+        if not getattr(rule, "id", None):
+            raise TypeError(f"{rule!r} does not have a non-empty 'id' attribute")
+        if rule.id in self._rules:
+            existing = self._rules[rule.id]
+            raise ValueError(
+                f"Rule ID conflict: {rule.id!r} is already registered by "
+                f"{existing.__class__.__qualname__}. "
+                f"Rule IDs are permanent — claim a new one."
+            )
+        self._rules[rule.id] = rule
+
+    def get(self, rule_id: str) -> Rule | None:
+        """Return the rule for *rule_id*, or ``None`` if not registered."""
+        return self._rules.get(rule_id)
+
+    def all(self) -> list[Rule]:
+        """Return all registered rules, sorted by ID."""
+        return sorted(self._rules.values(), key=lambda r: r.id)
+
+    def __iter__(self) -> Iterator[Rule]:
+        return iter(self.all())
+
+    def __len__(self) -> int:
+        return len(self._rules)
+
+    def __contains__(self, rule_id: object) -> bool:
+        return rule_id in self._rules
+
+    def __repr__(self) -> str:
+        ids = sorted(self._rules)
+        return f"RuleRegistry({ids})"
+
+
+#: Module-level singleton used by the runner and all rules.
+REGISTRY: RuleRegistry = RuleRegistry()