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

{python_surveyor-0.4.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.4.0
+Version: 0.4.1
 Summary: Use python introspection to survey source code for final LLM judgement
 Author: Dave Cunningham
 License-Expression: MIT

{python_surveyor-0.4.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.4.0"
+version = "0.4.1"
 description = "Use python introspection to survey source code for final LLM judgement"
 requires-python = ">=3.12"
 license = "MIT"

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

python_surveyor-0.4.1/python_surveyor/checks/nontoplevel_imports.py

@@ -0,0 +1,125 @@
+"""``non-toplevel-import`` check.
+
+Finds ``Import``/``ImportFrom`` nodes that are not direct children of
+``Module.body`` (i.e. nested inside a function, class, or control-flow block
+at any depth). The import line is attached as an excerpt (extended upward to
+include any justifying comment block), and a note names the nearest
+enclosing scope so the agent can judge whether the late import is justified
+(e.g. test-harness monkeypatching) or just laziness.
+"""
+
+import ast
+from typing import TYPE_CHECKING
+
+from python_surveyor.checks._util import (
+    CONTROL_FLOW_NODES,
+    justifying_comment,
+)
+from python_surveyor.model import Finding, SourceExcerpt
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import Corpus, SourceFile
+
+_SCOPE_LABELS = {
+    ast.FunctionDef: "function",
+    ast.AsyncFunctionDef: "function",
+    ast.ClassDef: "class",
+    ast.If: "if block",
+    ast.Try: "try block",
+    ast.With: "with block",
+    ast.For: "for block",
+    ast.While: "while block",
+    ast.ExceptHandler: "except block",
+    ast.TryStar: "try* block",
+}
+
+
+def _is_type_checking_test(test: ast.expr) -> bool:
+    """True for ``if TYPE_CHECKING:`` / ``if typing.TYPE_CHECKING:`` guards."""
+    if isinstance(test, ast.Name) and test.id == "TYPE_CHECKING":
+        return True
+    return (
+        isinstance(test, ast.Attribute)
+        and test.attr == "TYPE_CHECKING"
+        and isinstance(test.value, ast.Name)
+        and test.value.id == "typing"
+    )
+
+
+def _scope_label(node: ast.AST) -> str:
+    kind = _SCOPE_LABELS.get(type(node))
+    if kind is None:
+        return "nested block"
+    name = getattr(node, "name", None)
+    if name:
+        return f"{kind} `{name}`"
+    return kind
+
+
+def _walk(
+    body: list[ast.stmt],
+    scope_stack: list[ast.AST],
+    source: "SourceFile",
+    findings: list[Finding],
+) -> None:
+    for stmt in body:
+        new_stack = scope_stack
+        if isinstance(
+            stmt,
+            (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef),
+        ):
+            new_stack = scope_stack + [stmt]
+        elif isinstance(stmt, CONTROL_FLOW_NODES):
+            if isinstance(stmt, ast.If) and _is_type_checking_test(stmt.test):
+                new_stack = scope_stack
+            else:
+                new_stack = scope_stack + [stmt]
+        if isinstance(stmt, (ast.Import, ast.ImportFrom)) and scope_stack:
+            _record(stmt, source, scope_stack, findings)
+        for child_field in ("body", "orelse", "finalbody"):
+            child_body = getattr(stmt, child_field, None)
+            if isinstance(child_body, list):
+                _walk(child_body, new_stack, source, findings)
+        if isinstance(stmt, ast.Try):
+            for handler in stmt.handlers:
+                _walk(handler.body, new_stack + [handler], source, findings)
+
+
+def _record(
+    stmt: "ast.Import | ast.ImportFrom",
+    source: "SourceFile",
+    scope_stack: list[ast.AST],
+    findings: list[Finding],
+) -> None:
+    line = stmt.lineno
+    jc = justifying_comment(source, line)
+    start = jc[0].start_line if jc else line
+    nearest = scope_stack[-1] if scope_stack else None
+    note = (
+        f"inside {_scope_label(nearest)}"
+        if nearest is not None
+        else "at module top-level"
+    )
+    findings.append(
+        Finding(
+            check_id="non-toplevel-import",
+            path=source.path,
+            line=line,
+            column=stmt.col_offset,
+            excerpts=(
+                SourceExcerpt(
+                    path=source.path,
+                    start_line=start,
+                    end_line=line,
+                ),
+            ),
+            notes=(note,),
+        )
+    )
+
+
+def run(source: "SourceFile", _corpus: "Corpus") -> list[Finding]:
+    """Find non-top-level imports and attach source + enclosing-scope context."""
+    findings: list[Finding] = []
+    _walk(source.tree.body, [], source, findings)
+    return findings

python_surveyor-0.4.1/python_surveyor/checks/optional_params.py

@@ -0,0 +1,311 @@
+"""``optional-param-default`` check.
+
+Finds any ``FunctionDef``/``AsyncFunctionDef`` with at least one defaulted
+positional or keyword-only parameter (``*args``/``**kwargs`` names are not
+"parameters" for this purpose). The signature (justifying comment + ``def``
+line, with non-defaulted leading params elided) is attached as an excerpt,
+and notes report the defaulted parameter names plus call sites that rely on
+at least one default value (capped at ``corpus.max_call_sites``, with
+"and N other(s)" when truncated) — call sites that override every default
+are not listed, since they don't exercise the default path.
+
+**Framework route handlers are excluded.** FastAPI/Flask route handlers use
+defaulted params as a user interface (query parameters, headers, etc.) and
+are invoked by the framework rather than by application code, so the
+"missing call sites" signal this check looks for doesn't apply. A handler is
+recognised only when its decorator (e.g. ``@app.get(...)``, ``@router.post(
+...)``, ``@app.route(...)``) is a call on a name that is statically traced,
+via imports in the same file, to an actual ``fastapi.FastAPI`` /
+``fastapi.APIRouter`` / ``flask.Flask`` / ``flask.Blueprint`` instance. Only
+direct ``name = Ctor()`` assignments are tracked — factory functions that
+build and return an app/router are not (this matches the heuristic, not
+exhaustive, philosophy of the other checks).
+"""
+
+import ast
+from typing import TYPE_CHECKING
+
+from python_surveyor.checks._util import justifying_comment
+from python_surveyor.model import CallSite, Finding, SourceExcerpt
+
+if TYPE_CHECKING:
+    from python_surveyor.scanner import Corpus, SourceFile
+
+
+# Framework classes whose instances expose route-decorator methods. Mapped
+# from fully-qualified ``module.ClassName`` to the set of attribute names
+# that route handlers are registered with.
+_FRAMEWORK_CLASSES: dict[str, frozenset[str]] = {
+    "fastapi.FastAPI": frozenset(
+        {
+            "get",
+            "post",
+            "put",
+            "delete",
+            "patch",
+            "options",
+            "head",
+            "trace",
+            "websocket",
+            "api_route",
+            "route",
+        }
+    ),
+    "fastapi.APIRouter": frozenset(
+        {
+            "get",
+            "post",
+            "put",
+            "delete",
+            "patch",
+            "options",
+            "head",
+            "trace",
+            "websocket",
+            "api_route",
+        }
+    ),
+    "flask.Flask": frozenset(
+        {"get", "post", "put", "delete", "patch", "options", "head", "route"}
+    ),
+    "flask.Blueprint": frozenset(
+        {"get", "post", "put", "delete", "patch", "options", "head", "route"}
+    ),
+}
+
+
+def _framework_import_bindings(
+    tree: ast.Module,
+) -> dict[str, str]:
+    """Map locally-bound names to fully-qualified ``module.Name`` for framework imports.
+
+    Handles ``from fastapi import FastAPI``, ``from fastapi import APIRouter as
+    AR``, and ``import fastapi`` / ``import fastapi as fa``. Only names that
+    resolve to a known framework class (``fastapi.FastAPI`` etc.) are kept.
+    """
+    bindings: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            if node.module not in ("fastapi", "flask"):
+                continue
+            for alias in node.names:
+                fq = f"{node.module}.{alias.name}"
+                if fq in _FRAMEWORK_CLASSES:
+                    local = alias.asname if alias.asname else alias.name
+                    bindings[local] = fq
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name in ("fastapi", "flask"):
+                    local = alias.asname if alias.asname else alias.name
+                    bindings[local] = alias.name
+    return bindings
+
+
+def _resolve_call_qualname(func: ast.expr, bindings: dict[str, str]) -> str | None:
+    """Resolve the called function to a fully-qualified name, or ``None``.
+
+    Handles bare ``FastAPI()`` (``Name`` resolved via bindings) and dotted
+    ``fastapi.FastAPI()`` / ``fa.FastAPI()`` (``Attribute`` whose value is a
+    module-alias name in bindings).
+    """
+    if isinstance(func, ast.Name):
+        return bindings.get(func.id)
+    if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+        module_alias = bindings.get(func.value.id)
+        if module_alias is not None:
+            return f"{module_alias}.{func.attr}"
+    return None
+
+
+def _framework_object_names(tree: ast.Module) -> set[str]:
+    """Return names of variables bound to real FastAPI/Flask app/router instances.
+
+    Only direct ``name = Ctor(...)`` assignments at any depth are tracked.
+    Factory functions that build and return an app/router are not recognised
+    — see the module docstring for the rationale.
+    """
+    bindings = _framework_import_bindings(tree)
+    if not bindings:
+        return set()
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        target: ast.expr | None = None
+        value: ast.expr | None = None
+        if isinstance(node, ast.Assign):
+            if len(node.targets) != 1:
+                continue
+            target = node.targets[0]
+            value = node.value
+        elif isinstance(node, ast.AnnAssign) and node.value is not None:
+            target = node.target
+            value = node.value
+        if not isinstance(target, ast.Name) or value is None:
+            continue
+        if not isinstance(value, ast.Call):
+            continue
+        fq = _resolve_call_qualname(value.func, bindings)
+        if fq is not None and fq in _FRAMEWORK_CLASSES:
+            names.add(target.id)
+    return names
+
+
+def _is_route_decorator(deco: ast.expr, router_names: set[str]) -> bool:
+    """True if ``deco`` is a ``@<router>.<verb>(...)`` call on a known router.
+
+    ``<router>`` must be a name in ``router_names`` (a verified framework
+    app/router instance) and ``<verb>`` must be a route-registration method
+    for that object's class (e.g. ``get``, ``post``, ``route``).
+    """
+    if not isinstance(deco, ast.Call):
+        return False
+    func = deco.func
+    if not isinstance(func, ast.Attribute):
+        return False
+    if not isinstance(func.value, ast.Name):
+        return False
+    if func.value.id not in router_names:
+        return False
+    # ``router_names`` only contains verified framework instances, so any
+    # attribute on them that matches a known route verb is a route decorator.
+    for verbs in _FRAMEWORK_CLASSES.values():
+        if func.attr in verbs:
+            return True
+    return False
+
+
+def _defaulted_param_names(
+    func: "ast.FunctionDef | ast.AsyncFunctionDef",
+) -> list[str]:
+    """Return the names of positional and keyword-only params that have defaults."""
+    args = func.args
+    names: list[str] = []
+    positional_defaults = len(args.defaults)
+    for i, arg in enumerate(args.args):
+        if i >= len(args.args) - positional_defaults:
+            names.append(arg.arg)
+    for idx, default in enumerate(args.kw_defaults):
+        if default is not None:
+            names.append(args.kwonlyargs[idx].arg)
+    return names
+
+
+def _first_defaulted_line(
+    func: "ast.FunctionDef | ast.AsyncFunctionDef",
+) -> int:
+    """Return the source line of the first defaulted parameter.
+
+    Non-defaulted positional params before the first default are elided
+    from the excerpt, so the reader sees only the params that matter.
+    """
+    args = func.args
+    positional_defaults = len(args.defaults)
+    first_defaulted_idx = len(args.args) - positional_defaults
+    if positional_defaults > 0:
+        return args.args[first_defaulted_idx].lineno
+    for idx, default in enumerate(args.kw_defaults):
+        if default is not None:
+            return args.kwonlyargs[idx].lineno
+    return func.lineno
+
+
+def _param_uses_default(
+    param_name: str,
+    param_index: int,
+    call: CallSite,
+) -> bool:
+    """True if the call site does not pass this param (uses the default)."""
+    if param_name in call.keywords:
+        return False
+    if param_index < call.positional_count:
+        return False
+    return True
+
+
+def _call_site_notes(
+    name: str,
+    defaulted_params: list[str],
+    corpus: "Corpus",
+) -> tuple[str, ...]:
+    """Return notes describing call sites that use at least one default value.
+
+    Call sites that override every defaulted param are not listed — they
+    don't exercise the default path and only add noise.  Call sites that
+    use at least one default are listed (capped at ``corpus.max_call_sites``)
+    with "and N other(s)" when truncated.
+    """
+    sites = corpus.call_sites.get(name, ())
+    total = len(sites)
+    if total == 0:
+        return (f"`{name}` not called from anywhere scanned",)
+    using_default: list[CallSite] = []
+    for site in sites:
+        for idx, param_name in enumerate(defaulted_params):
+            if _param_uses_default(param_name, idx, site):
+                using_default.append(site)
+                break
+    using_default_sorted = sorted(
+        using_default, key=lambda s: (str(s.location.path), s.location.line)
+    )
+    cap = corpus.max_call_sites
+    shown = using_default_sorted[:cap]
+    if not shown:
+        return (f"All {total} call site(s) override every defaulted parameter",)
+    parts = [f"{s.location.path.name}:{s.location.line}" for s in shown]
+    remaining = len(using_default) - len(shown)
+    if remaining > 0:
+        parts.append(f"and {remaining} other(s)")
+    sites_str = ", ".join(parts)
+    return (
+        f"Call sites using defaults ({len(using_default)} of {total}): {sites_str}",
+    )
+
+
+def _signature_end_line(
+    node: "ast.FunctionDef | ast.AsyncFunctionDef",
+) -> int:
+    """Return the last line of the ``def`` signature (the ``:`` line)."""
+    if not node.body:
+        return node.lineno
+    first_body = node.body[0]
+    return max(node.lineno, first_body.lineno - 1)
+
+
+def run(source: "SourceFile", corpus: "Corpus") -> list[Finding]:
+    """Find functions with defaulted params and attach signature + call-site context."""
+    router_names = _framework_object_names(source.tree)
+    findings: list[Finding] = []
+    for node in ast.walk(source.tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if router_names and any(
+            _is_route_decorator(deco, router_names) for deco in node.decorator_list
+        ):
+            continue
+        defaulted = _defaulted_param_names(node)
+        if not defaulted:
+            continue
+        jc = justifying_comment(source, node.lineno)
+        jc_start = jc[0].start_line if jc else None
+        sig_start = _first_defaulted_line(node)
+        start = jc_start if jc_start is not None else sig_start
+        end = _signature_end_line(node)
+        findings.append(
+            Finding(
+                check_id="optional-param-default",
+                path=source.path,
+                line=node.lineno,
+                column=node.col_offset,
+                excerpts=(
+                    SourceExcerpt(
+                        path=source.path,
+                        start_line=start,
+                        end_line=end,
+                    ),
+                ),
+                notes=(
+                    f"Defaulted params: {', '.join(defaulted)}",
+                    *_call_site_notes(node.name, defaulted, corpus),
+                ),
+            )
+        )
+    return findings

python_surveyor-0.4.1/python_surveyor/checks/suppressions.py

@@ -0,0 +1,96 @@
+"""``suppression-comment`` check.
+
+Finds ``# pylint: disable=...`` / ``# pyright: ignore`` directives via
+``tokenize`` (not regex) so they aren't matched by strings or multi-line
+constructs. The source line is attached as an excerpt (extended upward to
+include any justifying comment block immediately above) so the reader can see
+both the suppression and its justification in one contiguous block.
+
+When a ``# pylint: disable=...`` is a standalone comment (not a trailing
+comment on a code line), it applies to all lines below until a matching
+``# pylint: enable=...`` or the end of the file. In that case the excerpt is
+extended downward to show what code is being suppressed, capped at
+``_MAX_SUPPRESSED_LINES`` lines.
+"""
+
+import re
+import tokenize
+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
+
+_SUPPRESSION_RE = re.compile(r"pylint:\s*disable[-\w]*\s*=|pyright:\s*ignore")
+_PYLINT_DISABLE_RE = re.compile(r"pylint:\s*disable[-\w]*\s*=\s*(.+)")
+_ENABLE_RE = re.compile(r"pylint:\s*enable[-\w]*\s*=")
+_MAX_SUPPRESSED_LINES = 10
+
+
+def _all_pylint_ids_covered(comment: str, covered: frozenset[str]) -> bool:
+    m = _PYLINT_DISABLE_RE.search(comment)
+    if m is None:
+        return False
+    ids = {part.strip() for part in m.group(1).split(",") if part.strip()}
+    return ids <= covered
+
+
+def _is_standalone_comment(source: "SourceFile", row: int) -> bool:
+    """True if the suppression comment is a whole-line comment, not trailing."""
+    line = source.line_text(row)
+    return line.strip().startswith("#")
+
+
+def _find_enable_or_end(source: "SourceFile", row: int) -> int:
+    """Return the last line covered by a standalone ``disable`` at ``row``.
+
+    Walks downward from ``row + 1`` looking for ``# pylint: enable=...``.
+    If found, returns the line before it. If not found, returns either
+    ``row + _MAX_SUPPRESSED_LINES`` or the last line of the file,
+    whichever comes first.
+    """
+    total = len(source.lines)
+    limit = min(row + _MAX_SUPPRESSED_LINES, total)
+    for candidate in range(row + 1, limit + 1):
+        text = source.line_text(candidate)
+        if _ENABLE_RE.search(text):
+            return candidate - 1
+    return limit
+
+
+def run(source: "SourceFile", corpus: "Corpus") -> list[Finding]:
+    """Find suppression comments and attach source + justifying-comment context."""
+    findings: list[Finding] = []
+    for token in source.tokens:
+        if token.type != tokenize.COMMENT:
+            continue
+        if not _SUPPRESSION_RE.search(token.string):
+            continue
+        if _all_pylint_ids_covered(token.string, corpus.covered_pylint_ids):
+            continue
+        row = token.start[0]
+        jc = justifying_comment(source, row)
+        start = jc[0].start_line if jc else row
+        if _is_standalone_comment(source, row):
+            end = _find_enable_or_end(source, row)
+        else:
+            end = row
+        findings.append(
+            Finding(
+                check_id="suppression-comment",
+                path=source.path,
+                line=row,
+                column=token.start[1],
+                excerpts=(
+                    SourceExcerpt(
+                        path=source.path,
+                        start_line=start,
+                        end_line=end,
+                    ),
+                ),
+                notes=(),
+            )
+        )
+    return findings

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-surveyor
-Version: 0.4.0
+Version: 0.4.1
 Summary: Use python introspection to survey source code for final LLM judgement
 Author: Dave Cunningham
 License-Expression: MIT

{python_surveyor-0.4.0 → python_surveyor-0.4.1}/python_surveyor.egg-info/SOURCES.txt

@@ -13,6 +13,14 @@ python_surveyor.egg-info/dependency_links.txt
 python_surveyor.egg-info/entry_points.txt
 python_surveyor.egg-info/requires.txt
 python_surveyor.egg-info/top_level.txt
+python_surveyor/checks/__init__.py
+python_surveyor/checks/_util.py
+python_surveyor/checks/broad_except.py
+python_surveyor/checks/fixture_naming.py
+python_surveyor/checks/future_annotations.py
+python_surveyor/checks/nontoplevel_imports.py
+python_surveyor/checks/optional_params.py
+python_surveyor/checks/suppressions.py
 tests/test_broad_except.py
 tests/test_cli.py
 tests/test_fixture_naming.py