python-surveyor 0.3.0__tar.gz → 0.4.1__tar.gz

{python_surveyor-0.3.0/python_surveyor.egg-info → python_surveyor-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-surveyor
-Version: 0.3.0
+Version: 0.4.1
 Summary: Use python introspection to survey source code for final LLM judgement
 Author: Dave Cunningham
 License-Expression: MIT
@@ -9,6 +9,8 @@ Requires-Python: >=3.12
 License-File: LICENSE
 Requires-Dist: click>=8.1.0
 Provides-Extra: dev
+Requires-Dist: fastapi>=0.115.0; extra == "dev"
+Requires-Dist: flask>=3.0.0; extra == "dev"
 Requires-Dist: pyright==1.1.411; extra == "dev"
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"

{python_surveyor-0.3.0 → python_surveyor-0.4.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 where = ["."]
-include = ["python_surveyor"]
+include = ["python_surveyor*"]
 
 [project]
 name = "python-surveyor"
-version = "0.3.0"
+version = "0.4.1"
 description = "Use python introspection to survey source code for final LLM judgement"
 requires-python = ">=3.12"
 license = "MIT"
@@ -24,6 +24,8 @@ dependencies = [
 
 [project.optional-dependencies]
 dev = [
+    "fastapi>=0.115.0",
+    "flask>=3.0.0",
     "pyright==1.1.411",
     "pytest>=8.0.0",
     "pytest-cov",

python_surveyor-0.4.1/python_surveyor/checks/__init__.py

@@ -0,0 +1,152 @@
+"""Check registry used by dispatch and the ``list-checks`` command.
+
+Every check is a ``CheckSpec(check_id, description, run)`` where ``run`` has
+the signature ``run(source: SourceFile, corpus: Corpus) -> list[Finding]``.
+Checks that ignore ``corpus`` still take it, so the internal check API itself
+has no optional parameters.
+
+``SourceFile`` and ``Corpus`` are imported only under ``TYPE_CHECKING`` to
+avoid a circular import with :mod:`python_surveyor.scanner` (which imports
+this registry at module top-level).
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from python_surveyor.checks.broad_except import run as run_broad_except
+from python_surveyor.checks.fixture_naming import run as run_fixture_naming
+from python_surveyor.checks.future_annotations import run as run_future_annotations
+from python_surveyor.checks.nontoplevel_imports import run as run_nontoplevel_imports
+from python_surveyor.checks.optional_params import run as run_optional_params
+from python_surveyor.checks.suppressions import run as run_suppressions
+from python_surveyor.model import Finding
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import Corpus, SourceFile
+
+
+@dataclass(frozen=True)
+class CheckSpec:
+    """A single check: id, short description, longer explanation, and runner.
+
+    ``description`` is the one-liner shown by ``list-checks``.
+    ``explanation`` is shown as a header note when the text report has
+    findings for this check, so the reader understands *why* the smell
+    matters before judging each hit.
+    ``pylint_equivalents`` lists pylint check IDs that this check already
+    covers, so the ``suppression-comment`` check can skip ``# pylint:
+    disable=`` directives that are fully redundant with another check (the
+    list is parsed and checked against this set — no regex to maintain).
+    """
+
+    check_id: str
+    description: str
+    explanation: str
+    pylint_equivalents: tuple[str, ...]
+    run: "Callable[[SourceFile, Corpus], list[Finding]]"
+
+
+_ALL_CHECKS_DATA: tuple[
+    tuple[
+        str, str, str, tuple[str, ...], "Callable[[SourceFile, Corpus], list[Finding]]"
+    ],
+    ...,
+] = (
+    (
+        "broad-except",
+        "ExceptHandler with no type, or type Exception/BaseException "
+        "(including tuples and except*).",
+        "Catching a narrower exception type is usually better — it makes "
+        "the intent explicit and avoids swallowing unexpected bugs. When a "
+        "broad except is necessary, it should typically re-raise to "
+        "preserve the stack trace for actual bugs rather than silently "
+        "discarding them.",
+        ("broad-exception-caught",),
+        run_broad_except,
+    ),
+    (
+        "fixture-naming",
+        "@pytest.fixture function whose registered name does not match "
+        "its declared name (the redefined-outer-name collision case).",
+        "A pytest fixture function should be prefixed with `fixture_` and "
+        "register its real name via `name=` so the function parameter in "
+        "test functions doesn't shadow the fixture function name — the "
+        "`redefined-outer-name` pylint disable that AI code often adds to "
+        "silence this is a symptom, not a fix.",
+        ("redefined-outer-name",),
+        run_fixture_naming,
+    ),
+    (
+        "future-annotations-import",
+        "`from __future__ import annotations` (we never use 3.9).",
+        "`from __future__ import annotations` makes all type annotations "
+        "strings at runtime, which breaks any code that relies on "
+        "resolving types at runtime (e.g. `typing.get_type_hints`, "
+        "Pydantic models, FastAPI dependency injection). Since the "
+        "target is always Python 3.12+, it's unnecessary and should be "
+        "removed.",
+        (),
+        run_future_annotations,
+    ),
+    (
+        "non-toplevel-import",
+        "Import/ImportFrom not directly in Module.body, at any nesting depth.",
+        "Imports inside functions or blocks are usually a sign of lazy "
+        "import resolution — often masking circular dependencies that "
+        "should be fixed with proper architecture. There may be a good "
+        "reason (e.g. performance, test-harness monkeypatching), but "
+        "absent one, imports should be at module top level.",
+        ("import-outside-toplevel",),
+        run_nontoplevel_imports,
+    ),
+    (
+        "optional-param-default",
+        "FunctionDef with >=1 defaulted positional or keyword-only parameter, "
+        "excluding FastAPI/Flask route handlers (verified via real imports).",
+        "Defaulted parameters are often added to avoid updating existing "
+        "call sites, but they make it impossible for pyright to flag "
+        "callers that should be passing an explicit value — the type "
+        "checker sees the default and moves on. On internal APIs, every "
+        "caller should pass an explicit value so pyright can catch "
+        "missing or wrong arguments. FastAPI/Flask route handlers are "
+        "excluded because their defaults are a framework user interface "
+        "(query parameters, headers) and the handler is invoked by the "
+        "framework, not by application code — the 'not called from "
+        "anywhere' signal doesn't apply.",
+        (),
+        run_optional_params,
+    ),
+    (
+        "suppression-comment",
+        "# pylint: disable=... or # pyright: ignore without a "
+        "justifying comment block above.",
+        "Suppression comments disable a linter's check for a line or "
+        "region. They're sometimes necessary, but each one should have a "
+        "comment explaining *why* the suppression is warranted — without "
+        "that, the suppression is indistinguishable from silencing a real "
+        "problem.",
+        (),
+        run_suppressions,
+    ),
+)
+
+
+ALL_CHECKS: tuple[CheckSpec, ...] = tuple(
+    CheckSpec(
+        check_id=cid,
+        description=desc,
+        explanation=expl,
+        pylint_equivalents=equiv,
+        run=run,
+    )
+    for cid, desc, expl, equiv, run in _ALL_CHECKS_DATA
+)
+
+CHECKS_BY_ID: dict[str, CheckSpec] = {
+    check_spec.check_id: check_spec for check_spec in ALL_CHECKS
+}
+
+COVERED_PYLINT_IDS: frozenset[str] = frozenset(
+    eq for check in ALL_CHECKS for eq in check.pylint_equivalents
+)

python_surveyor-0.4.1/python_surveyor/checks/_util.py

@@ -0,0 +1,73 @@
+"""Shared helpers for check implementations.
+
+Every finding needs two pieces of context that are shared across all checks:
+the source line(s) at the finding location (so the reader can see the actual
+code) and any justifying comment block immediately above it (so the reader
+can judge whether the smell is intentional). Excerpt-line capping is a
+rendering concern and lives in :mod:`python_surveyor.report`.
+
+``SourceFile`` is imported only under ``TYPE_CHECKING`` to avoid a circular
+import with :mod:`python_surveyor.scanner`.
+"""
+
+import ast
+from typing import TYPE_CHECKING
+
+from python_surveyor.model import SourceExcerpt
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import SourceFile
+
+CONTROL_FLOW_NODES: tuple[type[ast.AST], ...] = (
+    ast.If,
+    ast.Try,
+    ast.With,
+    ast.For,
+    ast.While,
+)
+
+
+def is_pure_comment_line(text: str) -> bool:
+    """True if ``text`` is a ``#``-comment line (possibly indented, no code)."""
+    return text.strip().startswith("#")
+
+
+def preceding_comment_block(
+    source: "SourceFile", line: int
+) -> "tuple[int, int] | None":
+    """Return ``(start, end)`` inclusive of the contiguous comment block above
+    ``line``, or ``None`` if the line immediately above is not a comment.
+
+    Walks upward while each preceding line is a pure ``#``-comment line; blank
+    lines and code lines break the block.
+    """
+    end = line - 1
+    if end < 1:
+        return None
+    if not is_pure_comment_line(source.line_text(end)):
+        return None
+    start = end
+    while start - 1 >= 1 and is_pure_comment_line(source.line_text(start - 1)):
+        start -= 1
+    return start, end
+
+
+def justifying_comment(source: "SourceFile", line: int) -> tuple[SourceExcerpt, ...]:
+    """Return a 1-tuple excerpt for the comment block above ``line``, or ``()``.
+
+    If a preceding ``#``-comment block is found, it is attached as an excerpt
+    labeled "justifying comment". If no preceding comment block is found,
+    returns ``()`` — the absence of the excerpt is the signal that no
+    justifying comment exists, so no note is needed.
+    """
+    block = preceding_comment_block(source, line)
+    if block is None:
+        return ()
+    start, end = block
+    return (
+        SourceExcerpt(
+            path=source.path,
+            start_line=start,
+            end_line=end,
+        ),
+    )

python_surveyor-0.4.1/python_surveyor/checks/broad_except.py

@@ -0,0 +1,168 @@
+"""``broad-except`` check.
+
+Finds ``ExceptHandler`` nodes with no type, or with type
+``Exception``/``BaseException`` (including tuples and ``except*`` via
+``TryStar``). Two excerpts are attached: the ``try`` side (justifying
+comment above, the ``try`` line, and any comment block immediately after
+the ``try`` — but no code from inside the try body) and the ``except``
+side (the ``except`` line plus handler body, capped at ``_WINDOW``
+lines). If the two excerpts overlap, they are merged into one.
+
+Handlers that re-raise (bare ``raise``) or call ``logger.exception(...)``
+are not flagged — re-raising preserves the stack trace, and
+``logger.exception`` captures it (though the error is still swallowed).
+"""
+
+import ast
+from typing import TYPE_CHECKING
+
+from python_surveyor.checks._util import is_pure_comment_line, justifying_comment
+from python_surveyor.model import Finding, SourceExcerpt
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import Corpus, SourceFile
+
+_BROAD_NAMES = {"Exception", "BaseException"}
+_WINDOW = 5
+
+
+def _type_contains_broad(node: ast.expr | None) -> bool:
+    if node is None:
+        return True
+    if isinstance(node, ast.Name):
+        return node.id in _BROAD_NAMES
+    if isinstance(node, ast.Tuple):
+        return any(_type_contains_broad(elt) for elt in node.elts)
+    return False
+
+
+def _is_reraise(stmt: ast.stmt) -> bool:
+    """True if ``stmt`` is a bare ``raise`` (re-raises the current exception)."""
+    return isinstance(stmt, ast.Raise) and stmt.exc is None and stmt.cause is None
+
+
+def _is_logger_exception(stmt: ast.stmt) -> bool:
+    """True if ``stmt`` is ``<something>.exception(...)`` (e.g. ``logger.exception``)."""
+    if not isinstance(stmt, ast.Expr) or not isinstance(stmt.value, ast.Call):
+        return False
+    func = stmt.value.func
+    return isinstance(func, ast.Attribute) and func.attr == "exception"
+
+
+def _handler_re_raises_or_logs(handler: ast.ExceptHandler) -> bool:
+    """True if the handler body re-raises or calls ``logger.exception``."""
+    for stmt in handler.body:
+        for sub in ast.walk(stmt):
+            if isinstance(sub, ast.stmt) and (
+                _is_reraise(sub) or _is_logger_exception(sub)
+            ):
+                return True
+    return False
+
+
+def _body_end(handler: ast.ExceptHandler) -> int:
+    """Return the last line of the handler body (or the ``except`` line)."""
+    body = handler.body
+    if not body:
+        return handler.lineno
+    last = body[-1]
+    end = getattr(last, "end_lineno", None)
+    if end is None:
+        end = last.lineno
+    return max(end, handler.lineno)
+
+
+def _comment_block_end(source: "SourceFile", start: int) -> int:
+    """Return the last line of a contiguous comment block starting at ``start``.
+
+    If ``start`` is not a comment line, returns ``start - 1`` (an empty
+    block before ``start``).
+    """
+    total = len(source.lines)
+    end = start
+    while end + 1 <= total and is_pure_comment_line(source.line_text(end + 1)):
+        end += 1
+    return end
+
+
+def _try_except_excerpts(
+    source: "SourceFile",
+    jc_start: "int | None",
+    try_line: int,
+    handler_line: int,
+    body_end: int,
+) -> tuple[SourceExcerpt, ...]:
+    """Build excerpts for the try and except sides of a broad except.
+
+    The try-side excerpt is justifying comment (if any) + ``try`` line +
+    any comment block immediately after the ``try`` — never code from
+    inside the try body.  If there are no comments before or after the
+    ``try``, the try-side excerpt is omitted entirely.  The except-side
+    excerpt is the ``except`` line + handler body, capped at ``_WINDOW``
+    lines.  If the two overlap, they are merged into one excerpt.
+    """
+    has_jc = jc_start is not None
+    post_end = _comment_block_end(source, try_line)
+    has_post = post_end > try_line
+    second_start = handler_line
+    second_end = min(body_end, handler_line + _WINDOW)
+    if not has_jc and not has_post:
+        return (
+            SourceExcerpt(
+                path=source.path,
+                start_line=second_start,
+                end_line=second_end,
+            ),
+        )
+    first_start = jc_start if jc_start is not None else try_line
+    first_end = post_end
+    if first_end >= second_start:
+        merged_end = min(max(first_end, second_end), body_end)
+        return (
+            SourceExcerpt(
+                path=source.path,
+                start_line=first_start,
+                end_line=merged_end,
+            ),
+        )
+    return (
+        SourceExcerpt(
+            path=source.path,
+            start_line=first_start,
+            end_line=first_end,
+        ),
+        SourceExcerpt(
+            path=source.path,
+            start_line=second_start,
+            end_line=second_end,
+        ),
+    )
+
+
+def run(source: "SourceFile", _corpus: "Corpus") -> list[Finding]:
+    """Find broad ``except`` handlers and attach body + justifying-comment context."""
+    findings: list[Finding] = []
+    for node in ast.walk(source.tree):
+        if not isinstance(node, (ast.Try, ast.TryStar)):
+            continue
+        jc = justifying_comment(source, node.lineno)
+        jc_start = jc[0].start_line if jc else None
+        for handler in node.handlers:
+            if not _type_contains_broad(handler.type):
+                continue
+            if _handler_re_raises_or_logs(handler):
+                continue
+            body_end = _body_end(handler)
+            excerpts = _try_except_excerpts(
+                source, jc_start, node.lineno, handler.lineno, body_end
+            )
+            findings.append(
+                Finding(
+                    check_id="broad-except",
+                    path=source.path,
+                    line=handler.lineno,
+                    column=handler.col_offset,
+                    excerpts=excerpts,
+                )
+            )
+    return findings

python_surveyor-0.4.1/python_surveyor/checks/fixture_naming.py

@@ -0,0 +1,134 @@
+"""``fixture-naming`` check.
+
+Finds ``@pytest.fixture``/``@fixture``-decorated functions whose registered
+fixture name does not match the convention: the function should be prefixed
+with ``fixture_`` **and** ``name=`` should register the true fixture name.
+The ``def`` line is attached as an excerpt (extended upward to include any
+justifying comment block), and a note reports the effective registered name
+and the corpus lookup of parameter usages of that name elsewhere (the actual
+``redefined-outer-name`` collision sites).
+"""
+
+import ast
+from typing import TYPE_CHECKING
+
+from python_surveyor.checks._util import justifying_comment
+from python_surveyor.model import Finding, SourceExcerpt
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import Corpus, SourceFile
+
+
+def _decorator_info(
+    deco: ast.expr,
+) -> "tuple[bool, bool, str | None]":
+    """Return ``(is_fixture, has_name_kwarg, name_value)`` for a decorator."""
+    call: ast.Call | None = None
+    expr = deco
+    if isinstance(expr, ast.Call):
+        call = expr
+        expr = expr.func
+    is_fixture = False
+    if isinstance(expr, ast.Attribute) and expr.attr == "fixture":
+        if isinstance(expr.value, ast.Name) and expr.value.id == "pytest":
+            is_fixture = True
+    elif isinstance(expr, ast.Name) and expr.id == "fixture":
+        is_fixture = True
+    if not is_fixture or call is None:
+        return is_fixture, False, None
+    name_value: str | None = None
+    has_name = False
+    for kw in call.keywords:
+        if kw.arg == "name":
+            has_name = True
+            if isinstance(kw.value, ast.Constant) and isinstance(kw.value.value, str):
+                name_value = kw.value.value
+    return True, has_name, name_value
+
+
+def _collision_note(registered_name: str, corpus: "Corpus") -> str:
+    sites = corpus.param_locations.get(registered_name, ())
+    count = len(sites)
+    if count == 0:
+        return f"registered as `{registered_name}`; no parameter usages elsewhere"
+    cap = corpus.max_call_sites
+    samples = sorted(sites, key=lambda pair: (str(pair[0].path), pair[0].line))[:cap]
+    rendered = ", ".join(
+        f"{pair[0].path.name}:{pair[0].line} (in `{pair[1]}`)" for pair in samples
+    )
+    remaining = count - cap
+    if remaining > 0:
+        rendered += f", and {remaining} other(s)"
+    return (
+        f"registered as `{registered_name}`; parameter used in "
+        f"{count} other function(s): {rendered}"
+    )
+
+
+def _is_autouse(deco: ast.expr) -> bool:
+    """True if the decorator call has ``autouse=True``."""
+    if not isinstance(deco, ast.Call):
+        return False
+    for kw in deco.keywords:
+        if (
+            kw.arg == "autouse"
+            and isinstance(kw.value, ast.Constant)
+            and kw.value.value is True
+        ):
+            return True
+    return False
+
+
+def run(source: "SourceFile", corpus: "Corpus") -> list[Finding]:
+    """Find fixture-naming issues and attach source + collision-site context."""
+    if source.path.name == "conftest.py":
+        return []
+    findings: list[Finding] = []
+    for node in ast.walk(source.tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        fixture_deco: ast.expr | None = None
+        has_name_kwarg = False
+        name_value: str | None = None
+        for deco in node.decorator_list:
+            is_fixture, has_name, value = _decorator_info(deco)
+            if is_fixture:
+                fixture_deco = deco
+                has_name_kwarg = has_name
+                name_value = value
+                break
+        if fixture_deco is None:
+            continue
+        if _is_autouse(fixture_deco):
+            continue
+        starts_with_fixture_ = node.name.startswith("fixture_")
+        if has_name_kwarg and starts_with_fixture_:
+            continue
+        registered_name = name_value if name_value is not None else node.name
+        reasons: list[str] = []
+        if not has_name_kwarg:
+            reasons.append("no `name=` kwarg")
+        if not starts_with_fixture_:
+            reasons.append(f"name `{node.name}` lacks `fixture_` prefix")
+        jc = justifying_comment(source, node.lineno)
+        start = jc[0].start_line if jc else node.lineno
+        findings.append(
+            Finding(
+                check_id="fixture-naming",
+                path=source.path,
+                line=node.lineno,
+                column=node.col_offset,
+                excerpts=(
+                    SourceExcerpt(
+                        path=source.path,
+                        start_line=start,
+                        end_line=node.lineno,
+                    ),
+                ),
+                notes=(
+                    _collision_note(registered_name, corpus),
+                    f"reason: {'; '.join(reasons)}",
+                ),
+            )
+        )
+    return findings

python_surveyor-0.4.1/python_surveyor/checks/future_annotations.py

@@ -0,0 +1,46 @@
+"""``future-annotations-import`` check.
+
+Finds ``from __future__ import annotations``. The import line is attached
+as an excerpt (extended upward to include any justifying comment block),
+but the fix is always "delete the line" so there is little else to judge.
+"""
+
+import ast
+from typing import TYPE_CHECKING
+
+from python_surveyor.checks._util import justifying_comment
+from python_surveyor.model import Finding, SourceExcerpt
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import Corpus, SourceFile
+
+
+def run(source: "SourceFile", _corpus: "Corpus") -> list[Finding]:
+    """Find ``from __future__ import annotations`` directives."""
+    findings: list[Finding] = []
+    for node in source.tree.body:
+        if not isinstance(node, ast.ImportFrom):
+            continue
+        if node.module != "__future__":
+            continue
+        for alias in node.names:
+            if alias.name == "annotations":
+                jc = justifying_comment(source, node.lineno)
+                start = jc[0].start_line if jc else node.lineno
+                findings.append(
+                    Finding(
+                        check_id="future-annotations-import",
+                        path=source.path,
+                        line=node.lineno,
+                        column=node.col_offset,
+                        excerpts=(
+                            SourceExcerpt(
+                                path=source.path,
+                                start_line=start,
+                                end_line=node.lineno,
+                            ),
+                        ),
+                        notes=(),
+                    )
+                )
+    return findings