python-surveyor 0.1.0__tar.gz

python_surveyor-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,18 @@
+# python-surveyor
+
+A scanner for code that finds potential issues.
+It is intentionally **recall-only**: every hit is a *candidate* with just enough
+context attached for a human (or an LLM agent) to make the judgement call. The
+tool never decides whether a hit is a real problem and never fixes anything.
+
+## Install
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+python-surveyor --help
+```

python_surveyor-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["python_surveyor"]
+
+[project]
+name = "python-surveyor"
+version = "0.1.0"
+description = "Use python introspection to survey source code for final LLM judgement"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Dave Cunningham" },
+]
+urls = { Homepage = "https://github.com/sparkprime/python-surveyor" }
+
+dependencies = [
+    "click>=8.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pyright==1.1.411",
+    "pytest>=8.0.0",
+    "pytest-cov",
+    "coverage",
+    "black == 26.5.1",
+    "isort == 8.0.1",
+    "pylint == 4.0.6",
+]
+
+[project.scripts]
+python-surveyor = "python_surveyor.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = [
+    "error",
+]
+xfail_strict = true
+log_level = "INFO"
+
+[tool.black]
+line-length = 88
+target-version = ["py312"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["python_surveyor"]
+
+[tool.pyright]
+include = ["python_surveyor", "tests"]
+venvPath = "."
+venv = ".venv"
+reportMissingTypeStubs = "none"
+reportUnknownMemberType = "none"
+reportUnknownArgumentType = "none"
+reportUnknownVariableType = "none"
+reportImportCycles = "none"
+
+[tool.pylint.'MASTER']
+ignore-paths = [
+    "^tests/",
+]
+
+[tool.pylint.'MESSAGES CONTROL']
+disable = [
+    "too-few-public-methods",
+    "too-many-arguments",
+    "too-many-positional-arguments",
+    "too-many-locals",
+    "too-many-branches",
+    "too-many-statements",
+    "too-many-return-statements",
+    "too-many-instance-attributes",
+    "too-many-nested-blocks",
+    "duplicate-code",
+    "fixme",
+]

python_surveyor-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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")