pyclichecker 2.4.1__py3-none-any.whl

pyclichecker/__init__.py

@@ -0,0 +1,29 @@
+"""Public API for pyclichecker."""
+
+from pyclichecker._version import VERSION, __version__
+from pyclichecker.cli import (
+    EXIT_CLEAN,
+    EXIT_FINDINGS,
+    EXIT_OPERATIONAL_ERROR,
+    main,
+)
+from pyclichecker.config import LintConfig
+from pyclichecker.diagnostics import RULES, Finding, Rule
+from pyclichecker.discovery import discover_python_files, lint_files
+from pyclichecker.rules import lint_source
+
+__all__ = [
+    "RULES",
+    "VERSION",
+    "EXIT_CLEAN",
+    "EXIT_FINDINGS",
+    "EXIT_OPERATIONAL_ERROR",
+    "Finding",
+    "LintConfig",
+    "Rule",
+    "__version__",
+    "discover_python_files",
+    "lint_files",
+    "lint_source",
+    "main",
+]

pyclichecker/__main__.py

@@ -0,0 +1,5 @@
+"""Run pyclichecker with ``python -m pyclichecker``."""
+
+from pyclichecker.cli import main
+
+raise SystemExit(main())

pyclichecker/_version.py

@@ -0,0 +1,10 @@
+"""Package version lookup."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pyclichecker")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+VERSION = __version__

pyclichecker/cli.py

@@ -0,0 +1,260 @@
+"""Command-line interface for pyclichecker."""
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from pyclichecker._version import VERSION
+from pyclichecker.config import LintConfig, parse_rule_codes
+from pyclichecker.diagnostics import RULES, Finding
+from pyclichecker.discovery import discover_python_files, lint_files
+
+EXIT_CLEAN = 0
+EXIT_FINDINGS = 1
+EXIT_OPERATIONAL_ERROR = 2
+
+
+def _expand_codes(value: str, parser: argparse.ArgumentParser) -> set[str]:
+    requested = parse_rule_codes(value)
+    if not requested or "ALL" in requested:
+        return set(RULES)
+
+    expanded: set[str] = set()
+    unknown: list[str] = []
+    for item in sorted(requested):
+        matches = {code for code in RULES if code == item or code.startswith(item)}
+        if matches:
+            expanded.update(matches)
+        else:
+            unknown.append(item)
+    if unknown:
+        parser.error(f"unknown rule code or prefix: {', '.join(unknown)}")
+    return expanded
+
+
+def _positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 0:
+        raise argparse.ArgumentTypeError("must be zero or greater")
+    return parsed
+
+
+def _add_threshold_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--max-function-lines",
+        type=_positive_int,
+        default=80,
+        metavar="N",
+        help="SLP008 threshold; zero disables the rule (default: 80)",
+    )
+    parser.add_argument(
+        "--narrating-comments",
+        type=_positive_int,
+        default=3,
+        metavar="N",
+        help="SLP007 threshold; zero disables the rule (default: 3)",
+    )
+    parser.add_argument(
+        "--duplicate-min-statements",
+        type=_positive_int,
+        default=4,
+        metavar="N",
+        help="minimum statements for SLP005 (default: 4)",
+    )
+    parser.add_argument(
+        "--duplicate-min-lines",
+        type=_positive_int,
+        default=6,
+        metavar="N",
+        help="minimum function lines for SLP005 (default: 6)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="pyclichecker",
+        description="Read-only linter for high-signal AI-generated Python code smells.",
+        epilog=(
+            "Examples:\n"
+            "  pyclichecker .\n"
+            "  pyclichecker src tests --ignore SLP004,SLP008\n"
+            "  pyclichecker app.py --format json\n"
+            "Inline suppression: # noqa: SLP003"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="Python files or directories (default: .)",
+    )
+    parser.add_argument(
+        "--select",
+        default="ALL",
+        help="comma-separated rule codes or prefixes (default: ALL)",
+    )
+    parser.add_argument(
+        "--ignore",
+        default="",
+        help="comma-separated rule codes or prefixes to ignore",
+    )
+    parser.add_argument(
+        "--exclude",
+        action="append",
+        default=[],
+        metavar="GLOB",
+        help="exclude a relative path glob; may be repeated",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "json", "github"),
+        default="text",
+        help="diagnostic output format",
+    )
+    parser.add_argument(
+        "--fail-on",
+        choices=("warning", "error", "never"),
+        default="warning",
+        help="minimum severity that produces exit 1",
+    )
+    _add_threshold_arguments(parser)
+    parser.add_argument(
+        "--list-rules",
+        action="store_true",
+        help="list rules and exit",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
+    return parser
+
+
+def _print_rules() -> None:
+    for rule in RULES.values():
+        print(f"{rule.code} {rule.severity:<7} {rule.title}: {rule.description}")
+
+
+def _render_text(
+    findings: Sequence[Finding],
+    *,
+    files_checked: int,
+    errors: Sequence[str],
+) -> None:
+    for finding in findings:
+        print(
+            f"{finding.path}:{finding.line}:{finding.column}: "
+            f"{finding.code} {finding.message}"
+        )
+    for error in errors:
+        print(f"pyclichecker: {error}", file=sys.stderr)
+
+    if findings:
+        print(f"Found {len(findings)} issue(s) in {files_checked} file(s).")
+    elif not errors:
+        print(f"No AI-slop findings in {files_checked} file(s).")
+
+
+def _render_json(
+    findings: Sequence[Finding],
+    *,
+    files_checked: int,
+    errors: Sequence[str],
+) -> None:
+    print(
+        json.dumps(
+            {
+                "version": VERSION,
+                "files_checked": files_checked,
+                "findings": [finding.as_dict() for finding in findings],
+                "errors": list(errors),
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+
+
+def _github_property(value: str) -> str:
+    return (
+        value.replace("%", "%25")
+        .replace("\r", "%0D")
+        .replace("\n", "%0A")
+        .replace(":", "%3A")
+        .replace(",", "%2C")
+    )
+
+
+def _github_message(value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _render_github(
+    findings: Sequence[Finding],
+    *,
+    errors: Sequence[str],
+) -> None:
+    for finding in findings:
+        message = _github_message(f"{finding.code} {finding.message}")
+        path = _github_property(finding.path)
+        print(
+            f"::{finding.severity} file={path},line={finding.line},"
+            f"col={finding.column}::{message}"
+        )
+    for error in errors:
+        print(f"::error title=pyclichecker::{_github_message(error)}")
+
+
+def _findings_fail(findings: Sequence[Finding], fail_on: str) -> bool:
+    if fail_on == "never":
+        return False
+    if fail_on == "warning":
+        return bool(findings)
+    return any(finding.severity == "error" for finding in findings)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line interface and return its process exit code."""
+
+    parser = build_parser()
+    arguments = parser.parse_args(argv)
+
+    if arguments.list_rules:
+        _print_rules()
+        return EXIT_CLEAN
+
+    selected = _expand_codes(arguments.select, parser)
+    ignored = _expand_codes(arguments.ignore, parser) if arguments.ignore else set()
+    config = LintConfig(
+        enabled_codes=frozenset(selected - ignored),
+        max_function_lines=arguments.max_function_lines,
+        narrating_comment_threshold=arguments.narrating_comments,
+        duplicate_min_statements=arguments.duplicate_min_statements,
+        duplicate_min_lines=arguments.duplicate_min_lines,
+    )
+    files, use_stdin, discovery_errors = discover_python_files(
+        arguments.paths,
+        exclude_patterns=arguments.exclude,
+    )
+    if not files and not use_stdin and not discovery_errors:
+        discovery_errors.append("no Python files found in the requested paths")
+
+    findings, files_checked, read_errors = lint_files(
+        files,
+        use_stdin=use_stdin,
+        config=config,
+    )
+    errors = [*discovery_errors, *read_errors]
+
+    if arguments.format == "json":
+        _render_json(findings, files_checked=files_checked, errors=errors)
+    elif arguments.format == "github":
+        _render_github(findings, errors=errors)
+    else:
+        _render_text(findings, files_checked=files_checked, errors=errors)
+
+    if errors:
+        return EXIT_OPERATIONAL_ERROR
+    if _findings_fail(findings, arguments.fail_on):
+        return EXIT_FINDINGS
+    return EXIT_CLEAN

pyclichecker/config.py

@@ -0,0 +1,23 @@
+"""Configuration for lint rules."""
+
+import re
+from dataclasses import dataclass
+
+from pyclichecker.diagnostics import RULES
+
+
+@dataclass(frozen=True, slots=True)
+class LintConfig:
+    """Resolved configuration for one lint run."""
+
+    enabled_codes: frozenset[str] = frozenset(RULES)
+    max_function_lines: int = 80
+    narrating_comment_threshold: int = 3
+    duplicate_min_statements: int = 4
+    duplicate_min_lines: int = 6
+
+
+def parse_rule_codes(value: str) -> set[str]:
+    """Parse a comma- or whitespace-separated list of rule codes."""
+
+    return {item.strip().upper() for item in re.split(r"[,\s]+", value) if item.strip()}

pyclichecker/diagnostics.py

@@ -0,0 +1,149 @@
+"""Rule metadata and diagnostics."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Rule:
+    """Metadata for one lint rule."""
+
+    code: str
+    severity: str
+    title: str
+    description: str
+
+
+RULES = {
+    rule.code: rule
+    for rule in (
+        Rule("SLP000", "error", "invalid-python", "Python source cannot be parsed."),
+        Rule(
+            "SLP001",
+            "error",
+            "placeholder-implementation",
+            "Concrete function contains only pass, ellipsis, or NotImplementedError.",
+        ),
+        Rule(
+            "SLP002",
+            "error",
+            "swallowed-exception",
+            "Exception handler silently discards an exception.",
+        ),
+        Rule(
+            "SLP003",
+            "warning",
+            "broad-exception-fallback",
+            "Broad exception handler converts unexpected failures into fallback behavior.",
+        ),
+        Rule(
+            "SLP004",
+            "warning",
+            "fake-async",
+            "Async function contains no await, async iteration, async context, or yield.",
+        ),
+        Rule(
+            "SLP005",
+            "warning",
+            "duplicate-implementation",
+            "Function body duplicates another implementation in the same file.",
+        ),
+        Rule(
+            "SLP006",
+            "error",
+            "placeholder-configuration",
+            "Configuration-like variable contains an obvious placeholder value.",
+        ),
+        Rule(
+            "SLP007",
+            "warning",
+            "narrating-comments",
+            "Function contains a cluster of comments that merely narrate operations.",
+        ),
+        Rule(
+            "SLP008",
+            "warning",
+            "oversized-function",
+            "Function is large enough to warrant decomposition or focused review.",
+        ),
+        Rule(
+            "SLP009",
+            "warning",
+            "unchecked-subprocess",
+            "subprocess.run can fail without its outcome being observed.",
+        ),
+        Rule(
+            "SLP010",
+            "warning",
+            "missing-network-timeout",
+            "Synchronous network call omits its timeout or sets it to None.",
+        ),
+        Rule(
+            "SLP011",
+            "warning",
+            "unchecked-http-response",
+            "HTTP response is consumed without checking whether the request succeeded.",
+        ),
+        Rule(
+            "SLP012",
+            "warning",
+            "environment-specific-path",
+            "Source contains an absolute path tied to one user's home directory.",
+        ),
+        Rule(
+            "SLP013",
+            "warning",
+            "blocking-in-async",
+            "Async function directly calls a known blocking API.",
+        ),
+        Rule(
+            "SLP014",
+            "warning",
+            "assertion-free-test",
+            "Test function has no explicit result or expected-failure oracle.",
+        ),
+        Rule(
+            "SLP015",
+            "warning",
+            "overridable-init-call",
+            "Constructor dispatches to an overridable same-class method before "
+            "instance state initialization is complete.",
+        ),
+        Rule(
+            "SLP016",
+            "warning",
+            "conditional-instance-state",
+            "Instance attribute is not initialized on every successful constructor path.",
+        ),
+        Rule(
+            "SLP017",
+            "warning",
+            "shared-mutable-class-state",
+            "Instance method mutates mutable state inherited from the class.",
+        ),
+    )
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """One source-level lint diagnostic."""
+
+    path: str
+    line: int
+    column: int
+    code: str
+    message: str
+
+    @property
+    def severity(self) -> str:
+        return RULES[self.code].severity
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "path": self.path,
+            "line": self.line,
+            "column": self.column,
+            "code": self.code,
+            "severity": self.severity,
+            "message": self.message,
+        }

pyclichecker/discovery.py

@@ -0,0 +1,150 @@
+"""File discovery and source loading."""
+
+import fnmatch
+import os
+import sys
+import tokenize
+from collections.abc import Iterable, Sequence
+from pathlib import Path
+
+from pyclichecker.config import LintConfig
+from pyclichecker.diagnostics import Finding
+from pyclichecker.rules import lint_source
+
+DEFAULT_EXCLUDED_DIRECTORIES = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".svn",
+        ".tox",
+        ".venv",
+        "__pycache__",
+        "build",
+        "dist",
+        "node_modules",
+        "site-packages",
+        "venv",
+    }
+)
+
+
+def _matches_exclude(relative_path: Path, patterns: Sequence[str]) -> bool:
+    value = relative_path.as_posix()
+    return any(
+        fnmatch.fnmatch(value, pattern) or fnmatch.fnmatch(relative_path.name, pattern)
+        for pattern in patterns
+    )
+
+
+def _python_files_in_directory(
+    root: Path,
+    *,
+    exclude_patterns: Sequence[str],
+) -> Iterable[Path]:
+    for current, directories, files in os.walk(root):
+        current_path = Path(current)
+        relative_current = current_path.relative_to(root)
+        directories[:] = sorted(
+            directory
+            for directory in directories
+            if directory not in DEFAULT_EXCLUDED_DIRECTORIES
+            and not _matches_exclude(relative_current / directory, exclude_patterns)
+        )
+        for filename in sorted(files):
+            if not filename.endswith(".py"):
+                continue
+            path = current_path / filename
+            relative_path = path.relative_to(root)
+            if not _matches_exclude(relative_path, exclude_patterns):
+                yield path
+
+
+def discover_python_files(
+    inputs: Sequence[str],
+    *,
+    exclude_patterns: Sequence[str] = (),
+) -> tuple[list[Path], bool, list[str]]:
+    """Resolve CLI inputs into unique Python files, stdin, and errors."""
+
+    files: list[Path] = []
+    use_stdin = False
+    errors: list[str] = []
+    seen: set[Path] = set()
+
+    for raw_input in inputs or (".",):
+        if raw_input == "-":
+            use_stdin = True
+            continue
+
+        path = Path(raw_input).expanduser()
+        if not path.exists():
+            errors.append(f"path does not exist: {raw_input}")
+            continue
+        if path.is_file():
+            if path.suffix != ".py":
+                errors.append(f"not a Python file: {raw_input}")
+                continue
+            candidates = (path,)
+        elif path.is_dir():
+            candidates = _python_files_in_directory(
+                path,
+                exclude_patterns=exclude_patterns,
+            )
+        else:
+            errors.append(f"unsupported path type: {raw_input}")
+            continue
+
+        for candidate in candidates:
+            identity = candidate.resolve()
+            if identity not in seen:
+                seen.add(identity)
+                files.append(candidate)
+
+    return sorted(files, key=lambda item: item.as_posix()), use_stdin, errors
+
+
+def _display_path(path: Path) -> str:
+    try:
+        return path.resolve().relative_to(Path.cwd().resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def lint_files(
+    files: Sequence[Path],
+    *,
+    use_stdin: bool,
+    config: LintConfig,
+) -> tuple[list[Finding], int, list[str]]:
+    """Load and lint discovered files and optional standard input."""
+
+    findings: list[Finding] = []
+    errors: list[str] = []
+    files_checked = 0
+
+    if use_stdin:
+        findings.extend(lint_source(sys.stdin.read(), path="<stdin>", config=config))
+        files_checked += 1
+
+    for path in files:
+        display_path = _display_path(path)
+        try:
+            with tokenize.open(path) as source_file:
+                source = source_file.read()
+        except (OSError, SyntaxError, UnicodeError) as error:
+            errors.append(f"{display_path}: {error}")
+            continue
+        findings.extend(lint_source(source, path=display_path, config=config))
+        files_checked += 1
+
+    return (
+        sorted(
+            findings,
+            key=lambda item: (item.path, item.line, item.column, item.code),
+        ),
+        files_checked,
+        errors,
+    )