codehound 1.2.0__tar.gz → 1.3.0__tar.gz

{codehound-1.2.0 → codehound-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codehound
-Version: 1.2.0
+Version: 1.3.0
 Summary: An AST-based static analyzer that hunts real correctness and async-safety bugs in Python code.
 Project-URL: Homepage, https://github.com/kratos0718/codehound
 Project-URL: Issues, https://github.com/kratos0718/codehound/issues
@@ -91,6 +91,9 @@ PYTHONPATH=src python -m codehound.cli scan path/to/project
 # scan a project (skips tests/, docs/, examples/, vendored code by default)
 codehound scan path/to/project
 
+# scan multiple files/directories in one invocation (what pre-commit does)
+codehound scan file1.py file2.py src/
+
 # only run specific checks
 codehound scan path/to/project --select CH001,CH006
 
@@ -98,6 +101,9 @@ codehound scan path/to/project --select CH001,CH006
 codehound scan path/to/project --format json
 codehound scan path/to/project --format csv
 
+# GitHub Code Scanning (Security tab) can ingest this directly
+codehound scan path/to/project --format sarif > results.sarif
+
 # list every available check
 codehound list
 ```
@@ -108,6 +114,29 @@ codehound list
 - run: codehound scan src   # fails the build on a regression
 ```
 
+### GitHub Action
+
+```yaml
+- uses: kratos0718/codehound@v1.2.0
+  with:
+    path: src
+    # select: CH001,CH006        # optional, defaults to all checks
+    # fail-on-findings: "false"  # optional, report without failing the build
+    # upload-sarif: "false"      # optional, skip the Code Scanning upload
+```
+
+Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in addition to failing the step (unless `fail-on-findings: "false"`).
+
+### pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/kratos0718/codehound
+    rev: v1.2.0
+    hooks:
+      - id: codehound
+```
+
 ---
 
 ## The checks
@@ -189,7 +218,9 @@ codehound/
 ├── core.py          # file discovery, AST parsing, the Finding/Check contract,
 │                    #   and a child→parent map so checks can ask "what's my
 │                    #   enclosing function / am I inside a `with`?"
-├── cli.py           # `scan` / `list`, text|json|csv output, CI-friendly exit codes
+├── cli.py           # `scan` / `list`, text|json|csv|sarif output, CI-friendly exit codes
+├── sarif.py         # SARIF 2.1.0 output for GitHub Code Scanning
+├── terminal.py      # colored text output (auto-disabled for non-TTY / NO_COLOR)
 └── checks/          # one small, independently-tested class per rule
     ├── blocking_async.py     (CH001)
     ├── mutable_defaults.py   (CH002)
@@ -227,10 +258,14 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 - [x] `asyncio.run()` inside a running loop — CH008
 - [x] Non-daemon thread started without a join — CH009 (the thread analog of CH006)
 - [x] Loop-variable closure capture in lambdas — CH010
+- [x] Pre-commit hook — `.pre-commit-hooks.yaml`
+- [x] GitHub Action — `action.yml`, uploads SARIF to Code Scanning
+- [x] SARIF output — `--format sarif`
+- [x] Colored terminal output (auto-disabled for non-TTY / `NO_COLOR`)
+- [x] Multi-path `scan` invocation (what the pre-commit hook needs)
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
 - [ ] Sync HTTP clients constructed inside async request handlers
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
-- [ ] Pre-commit hook
 
 ---
 

{codehound-1.2.0 → codehound-1.3.0}/README.md

@@ -71,6 +71,9 @@ PYTHONPATH=src python -m codehound.cli scan path/to/project
 # scan a project (skips tests/, docs/, examples/, vendored code by default)
 codehound scan path/to/project
 
+# scan multiple files/directories in one invocation (what pre-commit does)
+codehound scan file1.py file2.py src/
+
 # only run specific checks
 codehound scan path/to/project --select CH001,CH006
 
@@ -78,6 +81,9 @@ codehound scan path/to/project --select CH001,CH006
 codehound scan path/to/project --format json
 codehound scan path/to/project --format csv
 
+# GitHub Code Scanning (Security tab) can ingest this directly
+codehound scan path/to/project --format sarif > results.sarif
+
 # list every available check
 codehound list
 ```
@@ -88,6 +94,29 @@ codehound list
 - run: codehound scan src   # fails the build on a regression
 ```
 
+### GitHub Action
+
+```yaml
+- uses: kratos0718/codehound@v1.2.0
+  with:
+    path: src
+    # select: CH001,CH006        # optional, defaults to all checks
+    # fail-on-findings: "false"  # optional, report without failing the build
+    # upload-sarif: "false"      # optional, skip the Code Scanning upload
+```
+
+Uploads findings to the repo's **Security → Code Scanning** tab via SARIF, in addition to failing the step (unless `fail-on-findings: "false"`).
+
+### pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/kratos0718/codehound
+    rev: v1.2.0
+    hooks:
+      - id: codehound
+```
+
 ---
 
 ## The checks
@@ -169,7 +198,9 @@ codehound/
 ├── core.py          # file discovery, AST parsing, the Finding/Check contract,
 │                    #   and a child→parent map so checks can ask "what's my
 │                    #   enclosing function / am I inside a `with`?"
-├── cli.py           # `scan` / `list`, text|json|csv output, CI-friendly exit codes
+├── cli.py           # `scan` / `list`, text|json|csv|sarif output, CI-friendly exit codes
+├── sarif.py         # SARIF 2.1.0 output for GitHub Code Scanning
+├── terminal.py      # colored text output (auto-disabled for non-TTY / NO_COLOR)
 └── checks/          # one small, independently-tested class per rule
     ├── blocking_async.py     (CH001)
     ├── mutable_defaults.py   (CH002)
@@ -207,10 +238,14 @@ Every check has paired tests: the buggy pattern *is* flagged, and the idiomatic
 - [x] `asyncio.run()` inside a running loop — CH008
 - [x] Non-daemon thread started without a join — CH009 (the thread analog of CH006)
 - [x] Loop-variable closure capture in lambdas — CH010
+- [x] Pre-commit hook — `.pre-commit-hooks.yaml`
+- [x] GitHub Action — `action.yml`, uploads SARIF to Code Scanning
+- [x] SARIF output — `--format sarif`
+- [x] Colored terminal output (auto-disabled for non-TTY / `NO_COLOR`)
+- [x] Multi-path `scan` invocation (what the pre-commit hook needs)
 - [ ] Cross-module resolution for CH007/CH009 (currently same-file only)
 - [ ] Sync HTTP clients constructed inside async request handlers
 - [ ] `--fix` for the mechanical rules (CH002, CH003, CH004)
-- [ ] Pre-commit hook
 
 ---
 

{codehound-1.2.0 → codehound-1.3.0}/src/codehound/__init__.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from codehound.checks import ALL_CHECKS, get_checks
 from codehound.core import Check, Finding, scan_file, scan_path
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "ALL_CHECKS",

{codehound-1.2.0 → codehound-1.3.0}/src/codehound/cli.py

@@ -9,6 +9,8 @@ import sys
 from codehound import __version__
 from codehound.checks import ALL_CHECKS, get_checks
 from codehound.core import DEFAULT_SKIP_DIRS, scan_path
+from codehound.sarif import to_sarif
+from codehound.terminal import format_findings_text, format_summary
 
 
 def _cmd_scan(args: argparse.Namespace) -> int:
@@ -21,7 +23,10 @@ def _cmd_scan(args: argparse.Namespace) -> int:
     skip = set(DEFAULT_SKIP_DIRS)
     if args.include_tests:
         skip -= {"tests", "test", "testing"}
-    findings = scan_path(args.path, checks, skip_dirs=frozenset(skip))
+    findings = []
+    for path in args.paths:
+        findings.extend(scan_path(path, checks, skip_dirs=frozenset(skip)))
+    findings.sort(key=lambda f: (f.path, f.line, f.col, f.code))
 
     if args.format == "json":
         print(json.dumps([f.as_dict() for f in findings], indent=2))
@@ -30,18 +35,12 @@ def _cmd_scan(args: argparse.Namespace) -> int:
         for f in findings:
             msg = f.message.replace('"', "'")
             print(f'{f.path},{f.line},{f.col},{f.code},"{msg}"')
+    elif args.format == "sarif":
+        print(json.dumps(to_sarif(findings, ALL_CHECKS), indent=2))
     else:  # text
-        for f in findings:
-            print(f.as_text())
-        counts: dict[str, int] = {}
-        for f in findings:
-            counts[f.code] = counts.get(f.code, 0) + 1
-        summary = ", ".join(f"{k}: {v}" for k, v in sorted(counts.items()))
-        print(
-            f"\nFound {len(findings)} issue(s)"
-            + (f" ({summary})" if summary else ""),
-            file=sys.stderr,
-        )
+        for line in format_findings_text(findings):
+            print(line)
+        print(f"\n{format_summary(findings)}", file=sys.stderr)
 
     if findings and not args.exit_zero:
         return 1
@@ -62,17 +61,22 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--version", action="version", version=f"codehound {__version__}")
     sub = parser.add_subparsers(dest="command", required=True)
 
-    scan = sub.add_parser("scan", help="scan a file or directory for issues")
-    scan.add_argument("path", help="file or directory to scan")
+    scan = sub.add_parser("scan", help="scan one or more files/directories for issues")
+    scan.add_argument(
+        "paths",
+        nargs="+",
+        metavar="path",
+        help="file(s) or director(y/ies) to scan (accepts multiple, for pre-commit)",
+    )
     scan.add_argument(
         "--select",
         help="comma-separated check codes/names to run (default: all), e.g. CH001,CH006",
     )
     scan.add_argument(
         "--format",
-        choices=["text", "json", "csv"],
+        choices=["text", "json", "csv", "sarif"],
         default="text",
-        help="output format (default: text)",
+        help="output format (default: text; sarif for GitHub Code Scanning)",
     )
     scan.add_argument(
         "--include-tests",

codehound-1.3.0/src/codehound/sarif.py

@@ -0,0 +1,67 @@
+"""SARIF 2.1.0 output, so a `codehound` run can feed GitHub's Code Scanning
+tab directly (``github/codeql-action/upload-sarif``) instead of only being
+readable as CI log text.
+
+Deliberately minimal - just the fields GitHub's ingester actually needs:
+one ``tool.driver`` with a ``rules`` array (so finding codes get a name and
+description in the UI instead of a bare code), and one ``result`` per
+finding with a single physical location. No fingerprinting, no nested
+regions, no multi-run merging - those are real SARIF features this
+doesn't need yet.
+"""
+
+from __future__ import annotations
+
+from codehound import __version__
+from codehound.core import Check, Finding
+
+SARIF_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json"
+
+
+def _rule(check_cls: type[Check]) -> dict:
+    return {
+        "id": check_cls.code,
+        "name": check_cls.name,
+        "shortDescription": {"text": check_cls.description},
+        "helpUri": "https://github.com/kratos0718/codehound#the-checks",
+        "properties": {"tags": ["correctness", "codehound"]},
+    }
+
+
+def _result(finding: Finding) -> dict:
+    return {
+        "ruleId": finding.code,
+        "level": "error",
+        "message": {"text": finding.message},
+        "locations": [
+            {
+                "physicalLocation": {
+                    "artifactLocation": {"uri": finding.path.replace("\\", "/")},
+                    "region": {
+                        "startLine": max(finding.line, 1),
+                        "startColumn": max(finding.col + 1, 1),
+                    },
+                }
+            }
+        ],
+    }
+
+
+def to_sarif(findings: list[Finding], all_checks: list[type[Check]]) -> dict:
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "codehound",
+                        "informationUri": "https://github.com/kratos0718/codehound",
+                        "version": __version__,
+                        "rules": [_rule(c) for c in all_checks],
+                    }
+                },
+                "results": [_result(f) for f in findings],
+            }
+        ],
+    }

codehound-1.3.0/src/codehound/terminal.py

@@ -0,0 +1,57 @@
+"""Colored text output for a terminal, plain text everywhere else.
+
+Color only when stdout is actually a terminal, and never when ``NO_COLOR``
+is set (https://no-color.org) or ``TERM=dumb`` - the same convention ruff,
+eslint, and most modern CLI tools follow, so piping to a file or into `less`
+never ends up with raw escape codes in it.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+_RED = "\033[31m"
+_YELLOW = "\033[33m"
+_CYAN = "\033[36m"
+_DIM = "\033[2m"
+_BOLD = "\033[1m"
+_RESET = "\033[0m"
+
+
+def _color_enabled(stream=None) -> bool:
+    stream = stream or sys.stdout
+    if os.environ.get("NO_COLOR") is not None:
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def format_finding_text(finding, color: bool) -> str:
+    if not color:
+        return finding.as_text()
+    return (
+        f"{_CYAN}{finding.path}{_RESET}:{_DIM}{finding.line}:{finding.col}{_RESET}: "
+        f"{_RED}{_BOLD}{finding.code}{_RESET} {finding.message}"
+    )
+
+
+def format_findings_text(findings, stream=None) -> list[str]:
+    color = _color_enabled(stream)
+    return [format_finding_text(f, color) for f in findings]
+
+
+def format_summary(findings, stream=None) -> str:
+    color = _color_enabled(stream)
+    counts: dict[str, int] = {}
+    for f in findings:
+        counts[f.code] = counts.get(f.code, 0) + 1
+    summary = ", ".join(f"{k}: {v}" for k, v in sorted(counts.items()))
+    count_str = str(len(findings))
+    if color and findings:
+        count_str = f"{_YELLOW}{_BOLD}{count_str}{_RESET}"
+    line = f"Found {count_str} issue(s)"
+    if summary:
+        line += f" ({summary})"
+    return line

codehound-1.3.0/tests/test_output_formats.py

@@ -0,0 +1,74 @@
+"""Tests for the non-default output formats: SARIF and colored text.
+
+Scan results themselves are covered by test_checks.py; these tests only
+check that each format serializes a Finding correctly.
+"""
+
+from __future__ import annotations
+
+from codehound.checks import ALL_CHECKS
+from codehound.core import Finding
+from codehound.sarif import to_sarif
+from codehound.terminal import format_finding_text, format_summary
+
+
+def _sample_finding() -> Finding:
+    return Finding(path="pkg/mod.py", line=10, col=4, code="CH002", message="test message")
+
+
+def test_sarif_has_required_top_level_shape():
+    doc = to_sarif([_sample_finding()], ALL_CHECKS)
+    assert doc["version"] == "2.1.0"
+    assert "$schema" in doc
+    assert len(doc["runs"]) == 1
+    run = doc["runs"][0]
+    assert run["tool"]["driver"]["name"] == "codehound"
+
+
+def test_sarif_includes_a_rule_entry_per_check():
+    doc = to_sarif([], ALL_CHECKS)
+    rule_ids = {r["id"] for r in doc["runs"][0]["tool"]["driver"]["rules"]}
+    assert rule_ids == {c.code for c in ALL_CHECKS}
+
+
+def test_sarif_result_location_and_1_indexed_column():
+    doc = to_sarif([_sample_finding()], ALL_CHECKS)
+    result = doc["runs"][0]["results"][0]
+    assert result["ruleId"] == "CH002"
+    loc = result["locations"][0]["physicalLocation"]
+    assert loc["artifactLocation"]["uri"] == "pkg/mod.py"
+    # Finding.col is a 0-indexed ast col_offset; SARIF columns are 1-indexed.
+    assert loc["region"]["startLine"] == 10
+    assert loc["region"]["startColumn"] == 5
+
+
+def test_sarif_with_no_findings_has_empty_results():
+    doc = to_sarif([], ALL_CHECKS)
+    assert doc["runs"][0]["results"] == []
+
+
+def test_colored_text_contains_plain_text_content():
+    finding = _sample_finding()
+    colored = format_finding_text(finding, color=True)
+    plain = format_finding_text(finding, color=False)
+    assert plain == finding.as_text()
+    assert "\033[" in colored
+    assert "CH002" in colored
+    assert "test message" in colored
+    assert "pkg/mod.py" in colored
+
+
+def test_summary_reports_correct_counts():
+    findings = [
+        Finding(path="a.py", line=1, col=0, code="CH001", message="x"),
+        Finding(path="b.py", line=2, col=0, code="CH001", message="y"),
+        Finding(path="c.py", line=3, col=0, code="CH002", message="z"),
+    ]
+    summary = format_summary(findings)
+    assert "Found 3 issue(s)" in summary
+    assert "CH001: 2" in summary
+    assert "CH002: 1" in summary
+
+
+def test_summary_with_no_findings():
+    assert format_summary([]) == "Found 0 issue(s)"