python-surveyor 0.1.0__py3-none-any.whl

python_surveyor/__init__.py

@@ -0,0 +1,17 @@
+"""python-surveyor: AST-based scanner for AI-generated-code smells."""
+
+from python_surveyor.model import (
+    CallSite,
+    Finding,
+    Location,
+    ParseError,
+    SourceExcerpt,
+)
+
+__all__ = [
+    "CallSite",
+    "Finding",
+    "Location",
+    "ParseError",
+    "SourceExcerpt",
+]

python_surveyor/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m python_surveyor` entry point."""
+
+from python_surveyor.cli import main
+
+if __name__ == "__main__":
+    main()

python_surveyor/cli.py

@@ -0,0 +1,102 @@
+"""``click`` CLI: ``scan`` and ``list-checks`` commands."""
+
+import sys
+from pathlib import Path
+from typing import TextIO
+
+import click
+
+from python_surveyor.checks import ALL_CHECKS
+from python_surveyor.report import render_json, render_text
+from python_surveyor.scanner import scan
+
+
+@click.group()
+def main() -> None:
+    """python-surveyor: AST-based scanner for AI-generated-code smells."""
+
+
+@main.command("scan")
+@click.argument("paths", nargs=-1, type=click.Path(exists=True))
+@click.option(
+    "--check",
+    "check_ids",
+    multiple=True,
+    help="Restrict to this check id (repeatable).",
+)
+@click.option(
+    "--exclude",
+    "excludes",
+    multiple=True,
+    help="fnmatch pattern to exclude (repeatable, additive to defaults).",
+)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    help="Output format. Default: text.",
+)
+@click.option(
+    "--output",
+    "output",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Write to PATH instead of stdout.",
+)
+@click.option(
+    "--max-excerpt-lines",
+    "max_excerpt_lines",
+    type=int,
+    default=20,
+    help="Cap excerpt line count (default 20).",
+)
+@click.option(
+    "--max-call-sites",
+    "max_call_sites",
+    type=int,
+    default=5,
+    help="Cap call-site samples in notes (default 5).",
+)
+def scan_cmd(
+    paths: tuple[str, ...],
+    check_ids: tuple[str, ...],
+    excludes: tuple[str, ...],
+    fmt: str,
+    output: "Path | None",
+    max_excerpt_lines: int,
+    max_call_sites: int,
+) -> None:
+    """Scan PATHS for AI-generated-code smells."""
+    root_paths: tuple[str, ...] = paths if paths else (".",)
+    result = scan(
+        root_paths=root_paths,
+        check_ids=check_ids if check_ids else None,
+        excludes=excludes,
+        max_call_sites=max_call_sites,
+    )
+    stream: TextIO
+    if output is not None:
+        stream = output.open("w", encoding="utf-8")
+    else:
+        stream = sys.stdout
+    try:
+        if fmt == "json":
+            render_json(result, max_excerpt_lines, stream)
+        else:
+            render_text(result, max_excerpt_lines, stream)
+    finally:
+        if output is not None:
+            stream.close()
+
+
+@main.command("list-checks")
+def list_checks_cmd() -> None:
+    """List available check ids and descriptions."""
+    click.echo("id\tdescription")
+    for check_spec in ALL_CHECKS:
+        click.echo(f"{check_spec.check_id}\t{check_spec.description}")
+
+
+if __name__ == "__main__":
+    main()

python_surveyor/model.py

@@ -0,0 +1,65 @@
+"""Frozen dataclasses shared by scanner, checks, and report renderers.
+
+All construction uses required positional fields; there are no
+default-valued fields on ``Finding``/``SourceExcerpt``, consistent with the
+"no optional params on internal APIs" rule this tool itself checks for.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Location:
+    """A single source position."""
+
+    path: Path
+    line: int
+
+
+@dataclass(frozen=True)
+class CallSite:
+    """A call to a name, with enough info to tell if defaulted params are used.
+
+    ``positional_count`` is the number of positional args (not counting
+    ``*args`` spreads). ``keywords`` is the set of keyword arg names (not
+    counting ``**kwargs`` spreads). Together these let the
+    ``optional-param-default`` check determine whether a call site uses the
+    default value or passes an explicit one.
+    """
+
+    location: Location
+    positional_count: int
+    keywords: frozenset[str]
+
+
+@dataclass(frozen=True)
+class SourceExcerpt:
+    """A literal slice of source worth showing verbatim."""
+
+    label: str
+    path: Path
+    start_line: int
+    end_line: int
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A candidate smell detected by a check."""
+
+    check_id: str
+    path: Path
+    line: int
+    column: int
+    message: str
+    excerpts: tuple[SourceExcerpt, ...]
+    notes: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class ParseError:
+    """A file that could not be ``ast.parse``-d."""
+
+    path: Path
+    line: int
+    message: str

python_surveyor/report.py

@@ -0,0 +1,137 @@
+"""Render a ``ScanResult`` as text or JSON.
+
+Text output groups findings by ``check_id``; each finding is shown as
+``path:line:col -- message`` followed by labeled excerpts (with the line
+range in the header) and note lines. Parse errors get their own leading
+section. Excerpts are capped to ``--max-excerpt-lines`` with a truncation
+note.
+
+JSON output is a flat list of the same fields for programmatic use (excerpt
+text is not included — only the line range, so consumers can lazy-load).
+"""
+
+import json
+from pathlib import Path
+from typing import TextIO
+
+from python_surveyor.checks import CHECKS_BY_ID
+from python_surveyor.scanner import ScanResult
+
+
+def _read_excerpt_lines(
+    path: Path, start: int, end: int, max_lines: int
+) -> "tuple[list[str], str | None]":
+    """Read ``[start, end]`` from ``path``, capping to ``max_lines``.
+
+    Returns ``(lines, truncation_note)``.
+    """
+    try:
+        all_lines = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return ([], None)
+    available_end = min(end, len(all_lines))
+    if available_end < start:
+        return ([], None)
+    span = available_end - start + 1
+    if span <= max_lines:
+        return (all_lines[start - 1 : available_end], None)
+    capped_end = start + max_lines - 1
+    return (
+        all_lines[start - 1 : capped_end],
+        f"excerpt truncated at {max_lines} lines",
+    )
+
+
+def render_text(
+    result: ScanResult,
+    max_excerpt_lines: int,
+    stream: TextIO,
+) -> None:
+    """Render ``result`` as human-readable text to ``stream``."""
+    stream.write(f"# scan: {result.files_scanned} file(s) scanned\n\n")
+    if result.parse_errors:
+        stream.write("## parse errors\n\n")
+        for err in result.parse_errors:
+            stream.write(f"{err.path}:{err.line} -- {err.message}\n")
+        stream.write("\n")
+    current_check: str | None = None
+    counter = 0
+    for finding in result.findings:
+        if finding.check_id != current_check:
+            current_check = finding.check_id
+            counter = 0
+            stream.write(f"## {current_check}\n\n")
+            spec = CHECKS_BY_ID.get(current_check)
+            if spec is not None:
+                stream.write(f"{spec.explanation}\n\n")
+        counter += 1
+        for excerpt in finding.excerpts:
+            lines, truncation = _read_excerpt_lines(
+                excerpt.path,
+                excerpt.start_line,
+                excerpt.end_line,
+                max_excerpt_lines,
+            )
+            stream.write(
+                f"({counter}) {excerpt.path}:"
+                f"{excerpt.start_line}-{excerpt.end_line}\n"
+            )
+            for line in lines:
+                stream.write(f"{line}\n")
+            if truncation:
+                stream.write(f"... {truncation}\n")
+        for note in finding.notes:
+            stream.write(f"  note: {note}\n")
+        stream.write("\n")
+    if not result.findings:
+        stream.write("no findings.\n")
+
+
+def render_json(
+    result: ScanResult,
+    max_excerpt_lines: int,
+    stream: TextIO,
+) -> None:
+    """Render ``result`` as JSON to ``stream``.
+
+    ``max_excerpt_lines`` is accepted for API symmetry with
+    :func:`render_text`; JSON emits ranges only, not source text.
+    """
+    del max_excerpt_lines
+    findings_payload = []
+    for finding in result.findings:
+        excerpts_payload = [
+            {
+                "label": excerpt.label,
+                "path": str(excerpt.path),
+                "start_line": excerpt.start_line,
+                "end_line": excerpt.end_line,
+            }
+            for excerpt in finding.excerpts
+        ]
+        findings_payload.append(
+            {
+                "check_id": finding.check_id,
+                "path": str(finding.path),
+                "line": finding.line,
+                "column": finding.column,
+                "message": finding.message,
+                "excerpts": excerpts_payload,
+                "notes": list(finding.notes),
+            }
+        )
+    parse_errors_payload = [
+        {
+            "path": str(err.path),
+            "line": err.line,
+            "message": err.message,
+        }
+        for err in result.parse_errors
+    ]
+    payload = {
+        "files_scanned": result.files_scanned,
+        "findings": findings_payload,
+        "parse_errors": parse_errors_payload,
+    }
+    json.dump(payload, stream, indent=2)
+    stream.write("\n")

python_surveyor/scanner.py

@@ -0,0 +1,251 @@
+"""Discovery, parsing, ``Corpus`` building, and check orchestration.
+
+The scanner runs in two passes:
+
+1. **Discover + parse.** Walk the given paths, prune the default
+   ignore-directories plus anything matching ``--exclude``, read every
+   ``*.py`` file, ``ast.parse`` it. Files that fail to parse become a
+   ``ParseError`` and are excluded from further analysis rather than silently
+   dropped.
+2. **Build a ``Corpus``** over the successfully parsed files, giving every
+   check a cheap, already-built answer to "does anything in what we scanned
+   call/use this identifier" without re-parsing.
+3. **Run checks.** Every check has the same signature so the internal check
+   API itself has no optional parameters.
+4. **Sort** findings by ``(check_id, path, line)`` and return a
+   ``ScanResult``.
+"""
+
+import ast
+import fnmatch
+import os
+import tokenize
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from python_surveyor.checks import ALL_CHECKS, CheckSpec
+from python_surveyor.model import CallSite, Finding, Location, ParseError
+
+DEFAULT_PRUNED_DIRS: tuple[str, ...] = (
+    ".venv",
+    ".git",
+    "__pycache__",
+    "build",
+    "dist",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".tox",
+    ".ruff_cache",
+)
+
+
+def _endswith_egg_info(name: str) -> bool:
+    return name.endswith(".egg-info")
+
+
+@dataclass(frozen=True, eq=False)
+class SourceFile:
+    """A parsed file plus its source text and tokens."""
+
+    path: Path
+    source: str
+    lines: tuple[str, ...]
+    tree: ast.Module
+    tokens: tuple[tokenize.TokenInfo, ...]
+
+    def line_text(self, line_no: int) -> str:
+        """Return the (1-indexed) line's text, or ``""`` if out of range."""
+        if 1 <= line_no <= len(self.lines):
+            return self.lines[line_no - 1]
+        return ""
+
+
+@dataclass(frozen=True)
+class Corpus:
+    """Cross-file indices built once over every successfully parsed file.
+
+    ``call_sites`` answers "is this name called anywhere we scanned?".
+    ``param_locations`` answers "is this name used as a parameter anywhere?"
+    and pairs each hit with the enclosing function's name so the
+    fixture-naming check can spot redefined-outer-name collisions.
+    ``max_call_sites`` is the cap the ``optional-param-default`` check applies
+    when sampling call sites into a note (set by the scanner from the CLI
+    flag so checks don't need optional parameters of their own).
+    """
+
+    call_sites: dict[str, tuple[CallSite, ...]]
+    param_locations: dict[str, tuple[tuple[Location, str], ...]]
+    max_call_sites: int
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    """The output of a scan: findings plus any parse errors encountered."""
+
+    findings: tuple[Finding, ...]
+    parse_errors: tuple[ParseError, ...]
+    files_scanned: int
+
+
+def _discover(root_paths: tuple[str, ...], excludes: tuple[str, ...]) -> Iterator[Path]:
+    """Walk ``root_paths`` and yield ``*.py`` file paths, pruning ignored dirs."""
+    pruned_dirs = set(DEFAULT_PRUNED_DIRS)
+    for root in root_paths:
+        root_path = Path(root)
+        if root_path.is_file():
+            if root_path.suffix == ".py":
+                yield root_path
+            continue
+        for dirpath, dirnames, filenames in os.walk(root_path):
+            kept_dirs: list[str] = []
+            for dirname in dirnames:
+                if dirname in pruned_dirs or _endswith_egg_info(dirname):
+                    continue
+                if any(
+                    fnmatch.fnmatch(dirname, pattern) for pattern in excludes
+                ) or any(
+                    fnmatch.fnmatch(os.path.join(dirpath, dirname), pattern)
+                    for pattern in excludes
+                ):
+                    continue
+                kept_dirs.append(dirname)
+            dirnames[:] = kept_dirs
+            for filename in filenames:
+                if not filename.endswith(".py"):
+                    continue
+                if any(fnmatch.fnmatch(filename, pattern) for pattern in excludes):
+                    continue
+                yield Path(dirpath) / filename
+
+
+def _parse_file(path: Path) -> "tuple[SourceFile | None, ParseError | None]":
+    try:
+        source = path.read_text(encoding="utf-8")
+    except OSError as err:
+        return None, ParseError(path=path, line=0, message=str(err))
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as err:
+        line = err.lineno if err.lineno is not None else 0
+        return None, ParseError(path=path, line=line, message=err.msg)
+    token_list: list[tokenize.TokenInfo] = []
+    try:
+        with tokenize.open(str(path)) as readline:
+            token_list = list(tokenize.generate_tokens(readline.readline))
+    except (tokenize.TokenError, IndentationError, SyntaxError):
+        token_list = []
+    lines = tuple(source.splitlines())
+    return (
+        SourceFile(
+            path=path,
+            source=source,
+            lines=lines,
+            tree=tree,
+            tokens=tuple(token_list),
+        ),
+        None,
+    )
+
+
+def _resolve_call_name(node: ast.Call) -> str | None:
+    func = node.func
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None
+
+
+def _call_positional_count(node: ast.Call) -> int:
+    """Count positional args (excluding ``*args`` spreads)."""
+    return sum(1 for arg in node.args if not isinstance(arg, ast.Starred))
+
+
+def _call_keywords(node: ast.Call) -> frozenset[str]:
+    """Return the set of keyword arg names (excluding ``**kwargs`` spreads)."""
+    return frozenset(kw.arg for kw in node.keywords if kw.arg is not None)
+
+
+def _collect_params(
+    func_node: "ast.FunctionDef | ast.AsyncFunctionDef",
+    path: Path,
+    param_locations: dict[str, list[tuple[Location, str]]],
+) -> None:
+    args = func_node.args
+    skip_names = {"self", "cls"}
+    names: list[str] = []
+    for arg in args.args:
+        if arg.arg not in skip_names:
+            names.append(arg.arg)
+    for arg in args.kwonlyargs:
+        names.append(arg.arg)
+    for name in names:
+        param_locations.setdefault(name, []).append(
+            (Location(path=path, line=func_node.lineno), func_node.name)
+        )
+
+
+def _build_corpus(source_files: list[SourceFile], max_call_sites: int) -> Corpus:
+    call_sites: dict[str, list[CallSite]] = {}
+    param_locations: dict[str, list[tuple[Location, str]]] = {}
+    for source_file in source_files:
+        for node in ast.walk(source_file.tree):
+            if isinstance(node, ast.Call):
+                resolved = _resolve_call_name(node)
+                if resolved is None:
+                    continue
+                call_sites.setdefault(resolved, []).append(
+                    CallSite(
+                        location=Location(path=source_file.path, line=node.lineno),
+                        positional_count=_call_positional_count(node),
+                        keywords=_call_keywords(node),
+                    )
+                )
+                continue
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                _collect_params(node, source_file.path, param_locations)
+    return Corpus(
+        call_sites={k: tuple(v) for k, v in call_sites.items()},
+        param_locations={k: tuple(v) for k, v in param_locations.items()},
+        max_call_sites=max_call_sites,
+    )
+
+
+def scan(
+    root_paths: tuple[str, ...],
+    check_ids: "tuple[str, ...] | None",
+    excludes: tuple[str, ...],
+    max_call_sites: int,
+) -> ScanResult:
+    """Run the full discover -> parse -> corpus -> checks pipeline."""
+    if check_ids is None:
+        enabled_checks: tuple[CheckSpec, ...] = tuple(ALL_CHECKS)
+    else:
+        wanted = set(check_ids)
+        enabled_checks = tuple(
+            check_spec for check_spec in ALL_CHECKS if check_spec.check_id in wanted
+        )
+        missing = wanted - {check_spec.check_id for check_spec in enabled_checks}
+        if missing:
+            raise ValueError(f"unknown check ids: {sorted(missing)}")
+    source_files: list[SourceFile] = []
+    parse_errors: list[ParseError] = []
+    for path in _discover(root_paths, excludes):
+        parsed, parse_err = _parse_file(path)
+        if parse_err is not None:
+            parse_errors.append(parse_err)
+            continue
+        assert parsed is not None
+        source_files.append(parsed)
+    corpus = _build_corpus(source_files, max_call_sites)
+    findings: list[Finding] = []
+    for source_file in source_files:
+        for check_spec in enabled_checks:
+            findings.extend(check_spec.run(source_file, corpus))
+    findings.sort(key=lambda f: (f.check_id, str(f.path), f.line))
+    return ScanResult(
+        findings=tuple(findings),
+        parse_errors=tuple(parse_errors),
+        files_scanned=len(source_files),
+    )

python_surveyor-0.1.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: python-surveyor
+Version: 0.1.0
+Summary: Use python introspection to survey source code for final LLM judgement
+Author: Dave Cunningham
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sparkprime/python-surveyor
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: click>=8.1.0
+Provides-Extra: dev
+Requires-Dist: pyright==1.1.411; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: black==26.5.1; extra == "dev"
+Requires-Dist: isort==8.0.1; extra == "dev"
+Requires-Dist: pylint==4.0.6; extra == "dev"
+Dynamic: license-file

python_surveyor-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+python_surveyor/__init__.py,sha256=os_lOpeA_qqAQrIUw-ztrBY0jmrOjSdMF7EuGV2rQ2M,287
+python_surveyor/__main__.py,sha256=qM_59puxdldIVyuFxKcmKt2K9Me4y3opAh1LIEtoOP0,124
+python_surveyor/cli.py,sha256=A5GveO4aWQoQNPx0JhpuEehILrHDk7ZAJYzD43SxOZE,2504
+python_surveyor/model.py,sha256=AcBbwncH1EoHocDzk-umUakxxFx9RwBtX81wSD0BE2I,1548
+python_surveyor/report.py,sha256=AbQuKBSch7kiO7J_MMYGIzunstGqmkCs4RCr9-wDjpo,4426
+python_surveyor/scanner.py,sha256=3fK5wPsOsoFGkcSgmgMlBwBEeSqSOcjSNlEfwbfVi-Y,8856
+python_surveyor-0.1.0.dist-info/licenses/LICENSE,sha256=e0bQqTIJZymR3Os44UpqdNU4g3pl9GLMfZ3YKr-XY3Q,1072
+python_surveyor-0.1.0.dist-info/METADATA,sha256=kiUUo8yj-EmfCs_K-MYq4VmuUhR2xkFOWCSOWcYbuB4,681
+python_surveyor-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_surveyor-0.1.0.dist-info/entry_points.txt,sha256=uDhKSL-x9NOPj8uQOKtqey799vSFh-4xi4ArqHXu8eA,61
+python_surveyor-0.1.0.dist-info/top_level.txt,sha256=8BSg7FuIKg3pHoyhRmrAB52wRr__RuuUj0WJ8CjyfBE,16
+python_surveyor-0.1.0.dist-info/RECORD,,

python_surveyor-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_surveyor-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+python-surveyor = python_surveyor.cli:main

python_surveyor-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dave Cunningham
+
+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.

python_surveyor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+python_surveyor