run-codeql 1.0.0__py3-none-any.whl

run_codeql/__init__.py

@@ -0,0 +1 @@
+"""run_codeql package."""

run_codeql/__main__.py

@@ -0,0 +1,3 @@
+from run_codeql.cli import main
+
+main()

run_codeql/cli.py

@@ -0,0 +1,224 @@
+"""CLI entrypoint and orchestration for run_codeql."""
+
+import argparse
+import concurrent.futures
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from run_codeql.download import fetch_codeql
+from run_codeql.logging_utils import configure_logging, err, log
+from run_codeql.sarif import build_sarif_summary
+from run_codeql.scanner import cleanup_reports, detect_langs, run_lang
+from run_codeql.settings import TOOLS_DIR
+
+
+def main() -> None:
+    """CLI main function."""
+    parser = argparse.ArgumentParser(
+        description="Run CodeQL code-quality analysis locally (mirrors GitHub 'Code Quality' check)",  # noqa: E501
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Outputs:\n"
+            "  Databases:  .codeql/db-<lang>/\n"
+            "  SARIF:      .codeql/reports/<lang>-code-quality.sarif\n\n"
+            "CodeQL CLI is auto-downloaded to ~/.codeql-tools/ if not on PATH.\n"
+            "Run from the root of any repository."
+        ),
+    )
+    parser.add_argument(
+        "--lang",
+        default=None,
+        help="Comma-separated languages to scan (default: auto-detected from repo contents)",
+    )
+    parser.add_argument(
+        "--keep-db",
+        action="store_true",
+        help="Reuse existing databases instead of recreating",
+    )
+    parser.add_argument(
+        "--keep-reports",
+        action="store_true",
+        help="Do not delete prior SARIF reports before running",
+    )
+    parser.add_argument(
+        "--no-fail",
+        action="store_true",
+        help="Exit 0 even if findings or scan errors exist",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Print each finding with rule, location, and message",
+    )
+    parser.add_argument(
+        "--report-only",
+        action="store_true",
+        help="Skip scanning; summarize existing SARIF reports from the last run",
+    )
+    parser.add_argument(
+        "--quiet",
+        "-q",
+        action="store_true",
+        help="Suppress log output; print only the final summaries (useful for agent/scripted use)",
+    )
+    parser.add_argument(
+        "--files",
+        default=None,
+        help=(
+            "Comma-separated file paths (or fnmatch patterns) to restrict findings to. "
+            "Paths are matched against the end of the SARIF artifact URI "
+            "(e.g. 'src/foo.py' or 'src/*.py')"
+        ),
+    )
+    parser.add_argument(
+        "--rule",
+        default=None,
+        help=(
+            "Comma-separated rule IDs (or fnmatch patterns) to restrict findings to "
+            "(e.g. 'py/unused-import' or 'py/*')"
+        ),
+    )
+    parser.add_argument(
+        "--limit",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Return at most N findings across all files (after --files filtering)",
+    )
+    parser.add_argument(
+        "--offset",
+        type=int,
+        default=0,
+        metavar="N",
+        help="Skip the first N findings before applying --limit (for pagination)",
+    )
+    args = parser.parse_args()
+
+    configure_logging(args.quiet)
+    if args.quiet:
+        print("[codeql-local] running in quiet mode", file=sys.stderr, flush=True)
+
+    file_patterns = [p.strip() for p in args.files.split(",") if p.strip()] if args.files else None
+    rule_patterns = [p.strip() for p in args.rule.split(",") if p.strip()] if args.rule else None
+
+    repo_root = Path.cwd()
+    work_dir = repo_root / ".codeql"
+    report_dir = work_dir / "reports"
+
+    if args.report_only:
+        filter_langs = (
+            {lang_name.strip() for lang_name in args.lang.split(",")} if args.lang else None
+        )
+        sarif_files = sorted(report_dir.glob("*.sarif"))
+        if filter_langs:
+            sarif_files = [
+                f for f in sarif_files if f.stem.removesuffix("-code-quality") in filter_langs
+            ]
+        if not sarif_files:
+            err(f"No SARIF files found in {report_dir}. Run without --report-only first.")
+            sys.exit(1)
+        log("===== Summaries (from previous scan) =====")
+        report_failed = False
+        findings_found = False
+        for sarif in sarif_files:
+            lang = sarif.stem.removesuffix("-code-quality")
+            summary = build_sarif_summary(
+                sarif,
+                verbose=args.verbose,
+                files=file_patterns,
+                rules=rule_patterns,
+                limit=args.limit,
+                offset=args.offset,
+            )
+            findings_found = findings_found or summary.total_findings > 0
+            report_failed = report_failed or summary.read_error
+            if (file_patterns is None and rule_patterns is None) or summary.matched_findings > 0:
+                print(f"[{lang}] SARIF: {sarif}\n{summary.text}")
+        should_fail = report_failed or findings_found
+        sys.exit(0 if args.no_fail else int(should_fail))
+
+    config_file = repo_root / ".github" / "codeql" / "codeql-config.yml"
+
+    if args.lang:
+        langs = [lang_name.strip() for lang_name in args.lang.split(",") if lang_name.strip()]
+    else:
+        langs = detect_langs(repo_root)
+    if not langs:
+        err("No languages detected. Use --lang to specify one or add supported source files.")
+        sys.exit(1)
+
+    TOOLS_DIR.mkdir(parents=True, exist_ok=True)
+    work_dir.mkdir(parents=True, exist_ok=True)
+    report_dir.mkdir(parents=True, exist_ok=True)
+
+    gitignore = work_dir / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text("*\n")
+
+    codeql = fetch_codeql()
+    cleanup_reports(report_dir, args.keep_reports, langs=langs if args.lang else None)
+
+    scan_failed = False
+    findings_found = False
+    threads_per_lang = max(1, (os.cpu_count() or 1) // len(langs)) if len(langs) > 1 else 0
+    log(f"Running {len(langs)} language(s) in parallel with {threads_per_lang} thread(s) each")
+    summaries: dict[str, tuple[str, int]] = {}  # lang -> (text, matched_findings)
+
+    def scan(lang: str) -> tuple[str, str, int, int, bool]:
+        try:
+            sarif = run_lang(
+                lang,
+                codeql,
+                args.keep_db,
+                repo_root,
+                work_dir,
+                report_dir,
+                config_file,
+                threads=threads_per_lang,
+                quiet=args.quiet,
+            )
+            summary = build_sarif_summary(
+                sarif,
+                verbose=args.verbose,
+                files=file_patterns,
+                rules=rule_patterns,
+                limit=args.limit,
+                offset=args.offset,
+            )
+            return (
+                lang,
+                f"[{lang}] SARIF: {sarif}\n{summary.text}",
+                summary.total_findings,
+                summary.matched_findings,
+                False,
+            )
+        except subprocess.CalledProcessError as exc:
+            err(f"{lang} failed (exit {exc.returncode})")
+            return (lang, f"[{lang}] FAILED (exit {exc.returncode})", 0, 0, True)
+
+    with concurrent.futures.ThreadPoolExecutor() as executor:
+        futures = {executor.submit(scan, lang): lang for lang in langs}
+        for future in concurrent.futures.as_completed(futures):
+            if future.exception():
+                scan_failed = True
+                lang = futures[future]
+                err(f"{lang} crashed unexpectedly: {future.exception()}")
+                summaries[lang] = (f"[{lang}] FAILED (unexpected exception)", 0)
+                continue
+            lang, text, finding_count, matched_count, failed = future.result()
+            summaries[lang] = (text, matched_count)
+            findings_found = findings_found or finding_count > 0
+            scan_failed = scan_failed or failed
+
+    log("===== Summaries =====")
+    for lang in langs:
+        if lang in summaries:
+            text, matched_count = summaries[lang]
+            if (file_patterns is None and rule_patterns is None) or matched_count > 0:
+                print(text)
+
+    should_fail = scan_failed or findings_found
+    sys.exit(0 if args.no_fail else int(should_fail))

run_codeql/download.py

@@ -0,0 +1,158 @@
+"""CodeQL download, integrity verification, and safe extraction."""
+
+import hashlib
+import os
+import platform
+import re
+import shutil
+import sys
+import tarfile
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Callable, TypeVar
+
+from run_codeql.logging_utils import LOGGER, err, log
+from run_codeql.settings import (
+    CODEQL_BIN,
+    CODEQL_VERSION,
+    DOWNLOAD_RETRY_ATTEMPTS,
+    DOWNLOAD_RETRY_SLEEP_SECONDS,
+    DOWNLOAD_TIMEOUT_SECONDS,
+    TOOLS_DIR,
+)
+
+T = TypeVar("T")
+
+
+def fetch_codeql() -> Path:
+    """Resolve an executable CodeQL binary, downloading and verifying if needed."""
+    which = shutil.which("codeql")
+    if which:
+        log(f"Using system CodeQL: {which}")
+        return Path(which)
+
+    if CODEQL_BIN.is_file() and os.access(CODEQL_BIN, os.X_OK):
+        log(f"Using downloaded CodeQL: {CODEQL_BIN}")
+        return CODEQL_BIN
+
+    system = platform.system()
+    if system == "Linux":
+        plat = "linux64"
+    elif system == "Darwin":
+        plat = "osx64"
+    else:
+        err(f"Unsupported platform for CodeQL auto-download: {system}")
+        sys.exit(1)
+
+    log(f"Downloading CodeQL CLI {CODEQL_VERSION} to {TOOLS_DIR}")
+    archive_name = f"codeql-bundle-{plat}.tar.gz"
+    url = (
+        f"https://github.com/github/codeql-action/releases/download/"
+        f"codeql-bundle-v{CODEQL_VERSION}/{archive_name}"
+    )
+    checksum_url = f"{url}.checksum.txt"
+    tmp = TOOLS_DIR / f"{archive_name}.part"
+    TOOLS_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        download_file_with_retry(url, tmp)
+        checksum_text = download_text_with_retry(checksum_url)
+        expected_checksum = parse_sha256_checksum(checksum_text, archive_name)
+        actual_checksum = compute_sha256(tmp)
+        if actual_checksum != expected_checksum:
+            raise ValueError(
+                f"Checksum mismatch for {archive_name}: expected {expected_checksum}, got {actual_checksum}"  # noqa: E501
+            )
+        with tarfile.open(tmp, "r:gz") as tar:
+            safe_extract_tar(tar, TOOLS_DIR)
+    except Exception as exc:
+        err(f"Failed to download/install CodeQL: {exc}")
+        sys.exit(1)
+    finally:
+        tmp.unlink(missing_ok=True)
+
+    if not (CODEQL_BIN.is_file() and os.access(CODEQL_BIN, os.X_OK)):
+        err(f"Downloaded CodeQL bundle missing binary at {CODEQL_BIN}")
+        sys.exit(1)
+
+    CODEQL_BIN.chmod(CODEQL_BIN.stat().st_mode | 0o111)
+    log(f"Downloaded CodeQL to {CODEQL_BIN}")
+    return CODEQL_BIN
+
+
+def _with_retries(action: str, operation: Callable[[], T]) -> T:
+    """Run an operation with bounded retries and fixed backoff."""
+    for attempt in range(1, DOWNLOAD_RETRY_ATTEMPTS + 1):
+        try:
+            return operation()
+        except (OSError, TimeoutError, urllib.error.URLError, ValueError) as exc:
+            if attempt == DOWNLOAD_RETRY_ATTEMPTS:
+                raise
+            LOGGER.warning(
+                "%s failed (%s), retrying in %ss (%s/%s)",
+                action,
+                exc,
+                DOWNLOAD_RETRY_SLEEP_SECONDS,
+                attempt,
+                DOWNLOAD_RETRY_ATTEMPTS,
+            )
+            time.sleep(DOWNLOAD_RETRY_SLEEP_SECONDS)
+    raise RuntimeError(f"{action} failed")
+
+
+def download_file_with_retry(url: str, destination: Path) -> None:
+    """Download a URL to disk with retries and timeout."""
+
+    def _download() -> None:
+        with urllib.request.urlopen(url, timeout=DOWNLOAD_TIMEOUT_SECONDS) as response:
+            with destination.open("wb") as out:
+                shutil.copyfileobj(response, out)
+
+    _with_retries(f"Download failed for {url}", _download)
+
+
+def download_text_with_retry(url: str) -> str:
+    """Download UTF-8 text from a URL with retries and timeout."""
+
+    def _download() -> str:
+        with urllib.request.urlopen(url, timeout=DOWNLOAD_TIMEOUT_SECONDS) as response:
+            return response.read().decode("utf-8")
+
+    return _with_retries(f"Download failed for {url}", _download)
+
+
+def parse_sha256_checksum(checksum_text: str, filename: str) -> str:
+    """Extract the expected SHA-256 digest for a file from checksum text."""
+    for line in checksum_text.splitlines():
+        parts = line.strip().split()
+        if len(parts) < 2:
+            continue
+        digest, name = parts[0], parts[1].lstrip("*")
+        if name == filename and re.fullmatch(r"[A-Fa-f0-9]{64}", digest):
+            return digest.lower()
+    raise ValueError(f"Checksum for {filename} not found")
+
+
+def compute_sha256(path: Path) -> str:
+    """Compute the SHA-256 digest for a file."""
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(8192), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def safe_extract_tar(tar: tarfile.TarFile, destination: Path) -> None:
+    """Extract a tar archive while blocking path traversal and link entries."""
+    dest = destination.resolve()
+    for member in tar.getmembers():
+        if member.issym() or member.islnk():
+            raise ValueError(f"Refusing to extract link from archive: {member.name}")
+        member_path = (dest / member.name).resolve()
+        if member_path != dest and dest not in member_path.parents:
+            raise ValueError(f"Refusing to extract path outside destination: {member.name}")
+    try:
+        tar.extractall(dest, filter="data")
+    except TypeError:
+        tar.extractall(dest)

run_codeql/logging_utils.py

@@ -0,0 +1,28 @@
+"""Logging setup for run_codeql CLI output."""
+
+import logging
+import sys
+
+LOGGER = logging.getLogger("codeql-local")
+LOGGER.addHandler(logging.NullHandler())
+LOGGER.propagate = False
+
+
+def configure_logging(quiet: bool) -> None:
+    """Configure CLI logging with timestamped stderr output."""
+    for handler in list(LOGGER.handlers):
+        LOGGER.removeHandler(handler)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("[codeql-local %(asctime)s] %(message)s", "%H:%M:%S"))
+    LOGGER.addHandler(handler)
+    LOGGER.setLevel(logging.ERROR if quiet else logging.INFO)
+
+
+def err(msg: str) -> None:
+    """Log an error with the CLI prefix convention."""
+    LOGGER.error("[error] %s", msg)
+
+
+def log(msg: str) -> None:
+    """Log an informational CLI message."""
+    LOGGER.info(msg)

run_codeql/sarif.py

@@ -0,0 +1,138 @@
+"""SARIF parsing and summary rendering."""
+
+import fnmatch
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SarifSummary:
+    """Rendered SARIF summary and metadata needed for exit semantics."""
+
+    text: str
+    total_findings: int
+    read_error: bool
+    matched_findings: int = 0  # findings that passed --files filter (before limit/offset)
+
+
+def _uri_matches(uri: str, patterns: list[str]) -> bool:
+    """Return True if *uri* matches any of the fnmatch *patterns*.
+
+    Each pattern is tested against both the full URI and the basename so
+    callers can pass either ``src/foo.py`` or just ``foo.py``.
+    """
+    for pat in patterns:
+        if fnmatch.fnmatch(uri, pat):
+            return True
+        if fnmatch.fnmatch(uri, f"*/{pat}"):
+            return True
+    return False
+
+
+def build_sarif_summary(
+    sarif: Path,
+    verbose: bool = False,
+    files: list[str] | None = None,
+    rules: list[str] | None = None,
+    limit: int | None = None,
+    offset: int = 0,
+) -> SarifSummary:
+    """Build a rendered SARIF summary and metadata for control flow.
+
+    Args:
+        sarif:   Path to the ``.sarif`` file.
+        verbose: Include per-finding details in the output text.
+        files:   Optional list of fnmatch patterns matched against artifact URIs.
+        rules:   Optional list of fnmatch patterns matched against rule IDs
+                 (e.g. ``['py/unused-import']`` or ``['py/*']``).
+        limit:   If set, return at most this many findings (after *offset*).
+        offset:  Skip this many findings before applying *limit* (pagination).
+    """
+    try:
+        data = json.loads(sarif.read_text(encoding="utf-8"))
+    except Exception as exc:
+        return SarifSummary(
+            text=f"  (could not read SARIF: {exc})", total_findings=0, read_error=True
+        )
+
+    # Collect all matching results first so we can apply offset/limit uniformly.
+    matched: list[dict] = []
+    rules_map: dict[str, dict] = {}
+
+    for run in data.get("runs", []):
+        rules_map.update(
+            {r["id"]: r for r in run.get("tool", {}).get("driver", {}).get("rules", [])}
+        )
+        for result in run.get("results", []):
+            if files is not None:
+                loc = result.get("locations", [{}])[0]
+                uri = loc.get("physicalLocation", {}).get("artifactLocation", {}).get("uri", "")
+                if not _uri_matches(uri, files):
+                    continue
+            if rules is not None:
+                rule_id = result.get("ruleId", "")
+                if not any(fnmatch.fnmatch(rule_id, pat) for pat in rules):
+                    continue
+            matched.append(result)
+
+    # Apply pagination.
+    paginated = matched[offset:]
+    if limit is not None:
+        paginated = paginated[:limit]
+
+    counts: dict[str, int] = {}
+    finding_lines: list[str] = []
+
+    for result in paginated:
+        level = result.get("level", "warning")
+        counts[level] = counts.get(level, 0) + 1
+
+        if verbose:
+            rule_id = result.get("ruleId", "unknown")
+            rule = rules_map.get(rule_id, {})
+            short_desc = rule.get("shortDescription", {}).get("text", "")
+            message = result.get("message", {}).get("text", "")
+            message = re.sub(r"\[([^\]]+)\]\(\d+\)", r"\1", message)
+            loc = result.get("locations", [{}])[0]
+            phys = loc.get("physicalLocation", {})
+            uri = phys.get("artifactLocation", {}).get("uri", "")
+            line = phys.get("region", {}).get("startLine", "")
+            location = f"{uri}:{line}" if line else uri
+            finding_lines.append(
+                f"  [{level}] {rule_id}\n"
+                f"    {short_desc}\n"
+                f"    {location}\n"
+                f"    {message}"
+            )
+
+    total_matched = len(matched)
+    total_shown = len(paginated)
+    total = sum(counts.values())
+
+    count_lines = [f"  {level}: {counts[level]}" for level in sorted(counts)]
+    if files is not None or rules is not None or limit is not None or offset:
+        count_lines.append(f"  Shown: {total_shown}  (matched: {total_matched})")
+    else:
+        count_lines.append(f"  Total: {total}")
+
+    if verbose and finding_lines:
+        return SarifSummary(
+            text="\n".join(count_lines) + "\n\n" + "\n\n".join(finding_lines),
+            total_findings=total,
+            read_error=False,
+            matched_findings=total_matched,
+        )
+    return SarifSummary(
+        text="\n".join(count_lines),
+        total_findings=total,
+        read_error=False,
+        matched_findings=total_matched,
+    )
+
+
+def summarize_sarif(sarif: Path, lang: str, verbose: bool = False) -> str:
+    """Render a SARIF summary string for CLI output."""
+    del lang  # reserved for future language-specific formatting
+    return build_sarif_summary(sarif, verbose=verbose).text

run_codeql/scanner.py

@@ -0,0 +1,144 @@
+"""Language detection and CodeQL scan orchestration helpers."""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from run_codeql.logging_utils import log
+from run_codeql.settings import (
+    EXT_TO_LANG,
+    IGNORE_DIRS,
+    LANG_CONFIG,
+    PACKAGES_DIR,
+    TOOLS_DIR,
+)
+
+
+def detect_langs(repo_root: Path) -> list[str]:
+    """Scan the repo for source files and return the CodeQL languages to run."""
+    found: set[str] = set()
+    for _, dirnames, filenames in os.walk(repo_root):
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS]
+        for fname in filenames:
+            lang = EXT_TO_LANG.get(Path(fname).suffix)
+            if lang:
+                found.add(lang)
+
+    workflows = repo_root / ".github" / "workflows"
+    if workflows.is_dir() and (any(workflows.glob("*.yml")) or any(workflows.glob("*.yaml"))):
+        found.add("actions")
+
+    langs = sorted(found)
+    log(f"Auto-detected languages: {', '.join(langs) if langs else '(none)'}")
+    return langs
+
+
+def ensure_pack(pack_name: str, codeql: Path, quiet: bool) -> None:
+    """Download a CodeQL query pack if it is not already in the local cache."""
+    pack_dir = PACKAGES_DIR / pack_name
+    if pack_dir.exists():
+        return
+    log(f"Downloading missing pack: {pack_name}")
+    subprocess.run(
+        [str(codeql), "pack", "download", pack_name],
+        check=True,
+        stdout=subprocess.DEVNULL if quiet else None,
+        stderr=subprocess.DEVNULL if quiet else None,
+    )
+
+
+def cleanup_reports(report_dir: Path, keep: bool, langs: list[str] | None = None) -> None:
+    """Clean reports before scanning based on target language scope."""
+    if keep:
+        return
+    report_dir.mkdir(parents=True, exist_ok=True)
+    if langs is None:
+        if report_dir.exists():
+            shutil.rmtree(report_dir)
+        report_dir.mkdir(parents=True, exist_ok=True)
+        return
+    for lang in set(langs):
+        target = report_dir / f"{lang}-code-quality.sarif"
+        target.unlink(missing_ok=True)
+
+
+def cleanup_db(work_dir: Path, lang: str, keep: bool) -> None:
+    """Remove an existing language DB unless reusing previous DBs."""
+    if keep:
+        return
+    db_dir = work_dir / f"db-{lang}"
+    if db_dir.exists():
+        shutil.rmtree(db_dir)
+
+
+def run_lang(
+    lang: str,
+    codeql: Path,
+    keep_db: bool,
+    repo_root: Path,
+    work_dir: Path,
+    report_dir: Path,
+    config_file: Path,
+    threads: int = 0,
+    quiet: bool = False,
+) -> Path:
+    """Run DB creation and analysis for one language and return SARIF path."""
+    cfg = LANG_CONFIG.get(lang, {})
+    lang_arg = cfg.get("lang_arg", lang)
+    suite = cfg.get("suite", f"codeql/{lang}-queries:codeql-suites/{lang}-code-quality.qls")
+    build_command = cfg.get("build_command")
+
+    db_dir = work_dir / f"db-{lang}"
+    sarif = report_dir / f"{lang}-code-quality.sarif"
+
+    cleanup_db(work_dir, lang, keep_db)
+
+    log(f"Creating DB for {lang}")
+    create_cmd = [
+        str(codeql),
+        "database",
+        "create",
+        str(db_dir),
+        f"--language={lang_arg}",
+        f"--source-root={repo_root}",
+        "--overwrite",
+        f"--threads={threads}",
+        "--no-run-unnecessary-builds",
+    ]
+    if config_file.is_file():
+        create_cmd += ["--codescanning-config", str(config_file)]
+    if build_command:
+        create_cmd += ["--command", build_command]
+
+    subprocess.run(
+        create_cmd,
+        check=True,
+        stdout=subprocess.DEVNULL if quiet else None,
+        stderr=subprocess.DEVNULL if quiet else None,
+    )
+
+    pack_name = suite.split(":")[0]
+    ensure_pack(pack_name, codeql, quiet=quiet)
+
+    log(f"Analyzing {lang}")
+    analyze_cmd = [
+        str(codeql),
+        "database",
+        "analyze",
+        str(db_dir),
+        suite,
+        "--format=sarif-latest",
+        f"--output={sarif}",
+        f"--threads={threads}",
+        "--ram=6144",
+        f"--search-path={TOOLS_DIR / 'codeql'}",
+    ]
+    subprocess.run(
+        analyze_cmd,
+        check=True,
+        stdout=subprocess.DEVNULL if quiet else None,
+        stderr=subprocess.DEVNULL if quiet else None,
+    )
+
+    return sarif

run_codeql/settings.py

@@ -0,0 +1,78 @@
+"""Shared configuration and defaults for run_codeql."""
+
+import os
+from pathlib import Path
+
+
+def _int_env(name: str, default: int) -> int:
+    """Read a positive integer from environment with safe fallback."""
+    raw = os.getenv(name)
+    if not raw:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+CODEQL_VERSION = "2.24.2"
+TOOLS_DIR = Path.home() / ".codeql-tools"
+CODEQL_BIN = TOOLS_DIR / "codeql" / "codeql"
+PACKAGES_DIR = Path.home() / ".codeql" / "packages"
+DOWNLOAD_TIMEOUT_SECONDS = _int_env("RCQL_DOWNLOAD_TIMEOUT_SECONDS", 60)
+DOWNLOAD_RETRY_ATTEMPTS = _int_env("RCQL_DOWNLOAD_RETRY_ATTEMPTS", 3)
+DOWNLOAD_RETRY_SLEEP_SECONDS = _int_env("RCQL_DOWNLOAD_RETRY_SLEEP_SECONDS", 2)
+
+# Directories to skip when scanning for source files.
+IGNORE_DIRS = {
+    ".git",
+    ".codeql",
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    "node_modules",
+    "vendor",
+    "target",
+    "__pycache__",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+}
+
+# Maps file extensions to CodeQL language names.
+EXT_TO_LANG: dict[str, str] = {
+    ".py": "python",
+    ".rs": "rust",
+    ".js": "javascript-typescript",
+    ".jsx": "javascript-typescript",
+    ".ts": "javascript-typescript",
+    ".tsx": "javascript-typescript",
+    ".go": "go",
+    ".java": "java",
+    ".kt": "java",
+    ".cs": "csharp",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".cxx": "cpp",
+    ".c": "cpp",
+    ".rb": "ruby",
+    ".swift": "swift",
+}
+
+LANG_CONFIG = {
+    "javascript-typescript": {
+        "lang_arg": "javascript",
+        "suite": "codeql/javascript-queries:codeql-suites/javascript-code-quality.qls",
+    },
+    "rust": {
+        "suite": "codeql/rust-queries:codeql-suites/rust-security-and-quality.qls",
+        "build_command": "cd rust && cargo build --workspace --all-targets --locked",
+    },
+    "actions": {
+        "suite": "codeql/actions-queries:codeql-suites/actions-security-and-quality.qls",
+    },
+}

run_codeql-1.0.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: run-codeql
+Version: 1.0.0
+Summary: Run CodeQL code-quality analysis locally, mirroring the GitHub 'Code Quality' check
+Project-URL: Homepage, https://github.com/dereknorrbom/run-codeql
+Project-URL: Repository, https://github.com/dereknorrbom/run-codeql
+Project-URL: Bug Tracker, https://github.com/dereknorrbom/run-codeql/issues
+Author-email: Derek Norrbom <dereknorrbom@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Derek Norrbom
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: code-quality,codeql,linting,security,static-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# run-codeql
+
+A pip-installable CLI tool that runs [CodeQL](https://codeql.github.com/) code-quality analysis locally, mirroring the GitHub "Code Quality" check. Install once, run from any repository.
+
+## Installation
+
+```sh
+pip install run-codeql
+```
+
+This installs two commands: `run-codeql` and the shorthand `rcql`.
+
+## Requirements
+
+- Python 3.10+
+- CodeQL CLI — auto-downloaded to `~/.codeql-tools/` on first run if not already on `PATH` (SHA-256 verified, with retry/timeout policy)
+
+## Usage
+
+Run from the root of any repository:
+
+```sh
+rcql                        # auto-detect languages, run full scan
+rcql --lang python          # scan only Python
+rcql --lang python,actions  # scan multiple specific languages
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `--lang` | Comma-separated languages to scan (default: auto-detected) |
+| `--report-only` | Skip scanning; summarize existing SARIF reports from the last run |
+| `--verbose`, `-v` | Print each finding with rule ID, location, and message |
+| `--quiet`, `-q` | Suppress log output; print only final summaries (for agent/scripted use) |
+| `--files` | Comma-separated file paths or fnmatch patterns to restrict findings to (e.g. `src/foo.py` or `src/*.py`) |
+| `--rule` | Comma-separated rule IDs or fnmatch patterns to restrict findings to (e.g. `py/unused-import` or `py/*`) |
+| `--limit N` | Return at most N findings (after `--files`/`--rule` filtering) |
+| `--offset N` | Skip the first N findings before applying `--limit` (for pagination) |
+| `--keep-db` | Reuse existing databases instead of recreating them |
+| `--keep-reports` | Do not delete prior SARIF reports before running |
+| `--no-fail` | Exit 0 even if findings or scan errors exist |
+
+Download behavior can be tuned with environment variables:
+`RCQL_DOWNLOAD_TIMEOUT_SECONDS`, `RCQL_DOWNLOAD_RETRY_ATTEMPTS`, and `RCQL_DOWNLOAD_RETRY_SLEEP_SECONDS`.
+
+Report cleanup behavior before scans:
+- with `--lang`, only the matching `<lang>-code-quality.sarif` reports are replaced
+- without `--lang`, all prior SARIF reports are cleared first
+- with `--keep-reports`, no reports are deleted
+
+### Language auto-detection
+
+When `--lang` is not specified, the tool scans the repo for source files and detects which CodeQL languages to run. Common dependency directories are skipped (`node_modules`, `vendor`, `target`, `.venv`, etc.).
+
+Supported languages: `python`, `rust`, `javascript-typescript`, `go`, `java`, `csharp`, `cpp`, `ruby`, `swift`, `actions`
+
+GitHub Actions workflows (`.github/workflows/*.yml` and `.github/workflows/*.yaml`) are detected automatically and trigger the `actions` scanner.
+
+### Outputs
+
+- Databases: `.codeql/db-<lang>/`
+- SARIF reports: `.codeql/reports/<lang>-code-quality.sarif`
+
+A `.codeql/.gitignore` with `*` is created automatically on first run so these artifacts are not committed.
+
+By default, `rcql` exits non-zero if any findings are present or any language scan fails. Use `--no-fail` to force a zero exit code for informational/reporting workflows.
+
+## Common workflows
+
+### Full scan
+
+```sh
+cd ~/projects/my-repo
+rcql
+```
+
+### Quick re-summary after a previous scan
+
+```sh
+rcql --report-only
+rcql --report-only --verbose
+rcql --report-only --lang rust
+```
+
+### Agent-friendly output
+
+Produces clean, structured output suitable for an AI agent — no log noise, findings include rule ID, file location, and message:
+
+```sh
+rcql -q -v --report-only
+```
+
+Example output:
+
+```
+[python] SARIF: /path/to/.codeql/reports/python-code-quality.sarif
+  error: 1
+  warning: 2
+  Total: 3
+
+  [error] py/sql-injection
+    SQL injection
+    src/db.py:42
+    This query depends on user-provided value.
+
+  [warning] py/unused-import
+    Unused import
+    src/utils.py:3
+    Import of 'os' is not used.
+```
+
+### Filtering findings for large codebases
+
+When a scan returns hundreds or thousands of findings, use `--files`, `--rule`, `--limit`, and `--offset` to slice the results. These flags work with both `--report-only` and live scans.
+
+**Filter to a specific file:**
+
+```sh
+rcql -q -v --report-only --files src/models/user.py
+```
+
+**Filter using a glob pattern:**
+
+```sh
+rcql -q -v --report-only --files 'src/api/*.py'
+```
+
+**Filter to a specific rule:**
+
+```sh
+rcql -q -v --report-only --rule py/unused-import
+```
+
+**Filter to an entire rule category:**
+
+```sh
+rcql -q -v --report-only --rule 'py/*'
+```
+
+**Combine file and rule filters:**
+
+```sh
+rcql -q -v --report-only --files src/models/user.py --rule py/unused-import
+```
+
+**Paginate through a large result set:**
+
+```sh
+# First 20 findings
+rcql -q -v --report-only --limit 20
+
+# Next 20
+rcql -q -v --report-only --limit 20 --offset 20
+```
+
+When any filter or pagination flag is active, the summary line changes from `Total: N` to `Shown: X  (matched: Y)` so you can see both how many were returned and how many matched in total.
+
+Language blocks with zero matching findings are automatically suppressed when `--files` or `--rule` is active, so only relevant output is shown.
+
+### Single-language scan
+
+```sh
+rcql --lang actions --no-fail
+```
+
+## Parallel execution
+
+When scanning multiple languages, all scans run in parallel with CPU threads divided evenly across languages. Log timestamps make this visible.
+
+## Upgrading CodeQL
+
+The CodeQL version is pinned in the package. The checksum for each release is fetched live from GitHub at download time, so no manual SHA updates are needed. To use a newer CodeQL version, update `CODEQL_VERSION` in `run_codeql/settings.py` and delete `~/.codeql-tools/` to trigger a fresh download on next run.
+
+## Development
+
+```sh
+git clone https://github.com/YOUR_USERNAME/run-codeql
+cd run-codeql
+pip install -e ".[dev]"
+```
+
+### Make targets
+
+| Target | Description |
+|--------|-------------|
+| `make test` | Run the test suite |
+| `make cov` | Run tests with coverage report |
+| `make lint` | Run ruff (check only) |
+| `make fmt` | Auto-format with black and ruff --fix |
+| `make fmt-check` | Check formatting without modifying files |
+| `make check` | fmt-check + lint (CI-safe, no modifications) |
+| `make fix` | lint + fmt combined (auto-fix everything) |
+| `make install` | Install in editable mode with dev deps |
+
+### Running tests
+
+```sh
+make test       # run all 100+ tests
+make cov        # with per-line coverage report
+```
+
+Tests cover SARIF filtering, language detection, download integrity, extraction safety, and CLI behavior using fixture SARIF files. No CodeQL installation is required to run the tests.
+
+### Package layout
+
+| File | Purpose |
+|------|---------|
+| `run_codeql/cli.py` | Argument parsing and orchestration |
+| `run_codeql/download.py` | CodeQL download, retry, checksum, extraction |
+| `run_codeql/scanner.py` | Language detection and per-language scan execution |
+| `run_codeql/sarif.py` | SARIF parsing, filtering, and summary rendering |
+| `run_codeql/settings.py` | Constants and environment-tunable defaults |
+
+## Contributing
+
+Contributions are welcome. Please:
+
+1. Fork the repo and create a feature branch
+2. Run `make check` and `make test` before submitting
+3. Open a pull request with a clear description of the change
+
+## License
+
+MIT

run_codeql-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+run_codeql/__init__.py,sha256=AR8O-VPOn7oYYfbgnTsl9x4NNnJvPGv6_m2H5UYz40s,26
+run_codeql/__main__.py,sha256=qypp4Fi9rWOw64J7kVgXr1r2JtFPd1F2tziFYThqjt4,40
+run_codeql/cli.py,sha256=ouEUyHlR7IF8i3mncQTj7GLhl7ZmNNYPe7aVTx_C6NI,8158
+run_codeql/download.py,sha256=_aV629-NBZGPgBJEkUI6xZJkMMAECOcmMfotbmSFvNY,5483
+run_codeql/logging_utils.py,sha256=y4p7bqUkTMJoaEl3dCgL6vjjkA6Lu-FvkdvITKhJwwc,827
+run_codeql/sarif.py,sha256=pjnXLZIc_Pm0bZtnuopx5w25JE0t08-J3AN38weTcgs,4924
+run_codeql/scanner.py,sha256=PqdZIav3RHWN7NwVLg9Vw7tOhwnQ4vyJlt2md5pOEH0,4173
+run_codeql/settings.py,sha256=0iDXgWJC_5Nc9Lc0UhQqXV16uDYN1YGMJbupqSUJL8I,2028
+run_codeql-1.0.0.dist-info/METADATA,sha256=S2-IkXx88SZe-zqJjoVLccvbQ0QB5VbWkoaGP-XW0tg,9638
+run_codeql-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+run_codeql-1.0.0.dist-info/entry_points.txt,sha256=LWD5_50tO1UVkYF2_k3MtCNcSsxUnzx48Vr0oEwFtp8,78
+run_codeql-1.0.0.dist-info/licenses/LICENSE,sha256=jsTyDqXTGaB22CrjsfiI6aTXheUkbVf3-PymiZk6pH4,1070
+run_codeql-1.0.0.dist-info/RECORD,,

run_codeql-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

run_codeql-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+rcql = run_codeql.cli:main
+run-codeql = run_codeql.cli:main

run_codeql-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Derek Norrbom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.