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

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

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

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

@@ -8,7 +8,7 @@ include = ["python_surveyor*"]
 
 [project]
 name = "python-surveyor"
-version = "0.4.1"
+version = "0.5.0"
 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-0.5.0}/python_surveyor/__init__.py

@@ -1,7 +1,6 @@
 """python-surveyor: AST-based scanner for AI-generated-code smells."""
 
 from python_surveyor.model import (
-    CallSite,
     Finding,
     Location,
     ParseError,
@@ -9,7 +8,6 @@ from python_surveyor.model import (
 )
 
 __all__ = [
-    "CallSite",
     "Finding",
     "Location",
     "ParseError",

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/python_surveyor/checks/__init__.py

@@ -112,8 +112,7 @@ _ALL_CHECKS_DATA: tuple[
         "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.",
+        "framework, not by application code.",
         (),
         run_optional_params,
     ),

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/python_surveyor/checks/fixture_naming.py

@@ -51,7 +51,7 @@ def _collision_note(registered_name: str, corpus: "Corpus") -> str:
     count = len(sites)
     if count == 0:
         return f"registered as `{registered_name}`; no parameter usages elsewhere"
-    cap = corpus.max_call_sites
+    cap = corpus.max_samples
     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

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/python_surveyor/checks/optional_params.py

@@ -4,29 +4,26 @@ 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.
+and a note reports the defaulted parameter names.
 
 **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).
+are invoked by the framework rather than by application code, so the smell
+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
+from python_surveyor.model import Finding, SourceExcerpt
 
 if TYPE_CHECKING:
     from python_surveyor.scanner import Corpus, SourceFile
@@ -208,58 +205,6 @@ def _first_defaulted_line(
     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:
@@ -270,8 +215,8 @@ def _signature_end_line(
     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."""
+def run(source: "SourceFile", _corpus: "Corpus") -> list[Finding]:
+    """Find functions with defaulted params and attach signature context."""
     router_names = _framework_object_names(source.tree)
     findings: list[Finding] = []
     for node in ast.walk(source.tree):
@@ -302,10 +247,7 @@ def run(source: "SourceFile", corpus: "Corpus") -> list[Finding]:
                         end_line=end,
                     ),
                 ),
-                notes=(
-                    f"Defaulted params: {', '.join(defaulted)}",
-                    *_call_site_notes(node.name, defaulted, corpus),
-                ),
+                notes=(f"Defaulted params: {', '.join(defaulted)}",),
             )
         )
     return findings

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/python_surveyor/cli.py

@@ -45,11 +45,11 @@ def main() -> None:
     help="Cap excerpt line count (default 20).",
 )
 @click.option(
-    "--max-call-sites",
-    "max_call_sites",
+    "--max-samples",
+    "max_samples",
     type=int,
     default=10,
-    help="Cap call-site samples in notes (default 10).",
+    help="Cap note-sample counts (default 10).",
 )
 def scan_cmd(
     paths: tuple[str, ...],
@@ -57,7 +57,7 @@ def scan_cmd(
     excludes: tuple[str, ...],
     output: "Path | None",
     max_excerpt_lines: int,
-    max_call_sites: int,
+    max_samples: int,
 ) -> None:
     """Scan PATHS for AI-generated-code smells."""
     root_paths: tuple[str, ...] = paths if paths else (".",)
@@ -65,7 +65,7 @@ def scan_cmd(
         root_paths=root_paths,
         check_ids=check_ids if check_ids else None,
         excludes=excludes,
-        max_call_sites=max_call_sites,
+        max_samples=max_samples,
     )
     stream: TextIO
     if output is not None:

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/python_surveyor/model.py

@@ -12,22 +12,6 @@ class Location:
     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."""

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/python_surveyor/scanner.py

@@ -9,7 +9,7 @@ The scanner runs in two passes:
    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.
+   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
@@ -25,7 +25,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from python_surveyor.checks import ALL_CHECKS, COVERED_PYLINT_IDS, CheckSpec
-from python_surveyor.model import CallSite, Finding, Location, ParseError
+from python_surveyor.model import Finding, Location, ParseError
 
 DEFAULT_PRUNED_DIRS: tuple[str, ...] = (
     ".venv",
@@ -65,18 +65,16 @@ class SourceFile:
 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).
+    ``max_samples`` is the cap checks apply when sampling note entries (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
+    max_samples: int
     covered_pylint_ids: frozenset[str]
 
 
@@ -150,25 +148,6 @@ def _parse_file(path: Path) -> "tuple[SourceFile | None, ParseError | 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,
@@ -193,31 +172,17 @@ def _collect_params(
 
 def _build_corpus(
     source_files: list[SourceFile],
-    max_call_sites: int,
+    max_samples: int,
     covered_pylint_ids: frozenset[str],
 ) -> 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,
+        max_samples=max_samples,
         covered_pylint_ids=covered_pylint_ids,
     )
 
@@ -226,7 +191,7 @@ def scan(
     root_paths: tuple[str, ...],
     check_ids: "tuple[str, ...] | None",
     excludes: tuple[str, ...],
-    max_call_sites: int,
+    max_samples: int,
 ) -> ScanResult:
     """Run the full discover -> parse -> corpus -> checks pipeline."""
     if check_ids is None:
@@ -248,7 +213,7 @@ def scan(
             continue
         assert parsed is not None
         source_files.append(parsed)
-    corpus = _build_corpus(source_files, max_call_sites, COVERED_PYLINT_IDS)
+    corpus = _build_corpus(source_files, max_samples, COVERED_PYLINT_IDS)
     findings: list[Finding] = []
     for source_file in source_files:
         for check_spec in enabled_checks:

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

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

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/tests/test_optional_params.py

@@ -1,8 +1,6 @@
 """Tests for the ``optional-param-default`` check."""
 
-from python_surveyor.checks import COVERED_PYLINT_IDS
 from python_surveyor.checks.optional_params import run
-from python_surveyor.scanner import _build_corpus
 
 
 def test_defaulted_positional_param(make_source_file, empty_corpus):
@@ -11,8 +9,6 @@ def test_defaulted_positional_param(make_source_file, empty_corpus):
     findings = run(source_file, empty_corpus)
     assert len(findings) == 1
     assert findings[0].check_id == "optional-param-default"
-    notes = "\n".join(findings[0].notes)
-    assert "`f`" in notes
 
 
 def test_mixed_defaulted_positional(make_source_file, empty_corpus):
@@ -43,62 +39,6 @@ def test_args_kwargs_not_flagged(make_source_file, empty_corpus):
     assert findings == []
 
 
-def test_call_site_note_with_corpus(make_source_file):
-    source = "def helper(a=1):\n" "    pass\n" "def caller():\n" "    helper()\n"
-    source_file = make_source_file("a.py", source)
-    corpus = _build_corpus([source_file], 10, COVERED_PYLINT_IDS)
-    findings = run(source_file, corpus)
-    assert findings
-    notes = "\n".join(findings[0].notes)
-    assert "using defaults" in notes
-
-
-def test_call_site_note_not_called(make_source_file):
-    source = "def helper(a=1):\n" "    pass\n"
-    source_file = make_source_file("a.py", source)
-    corpus = _build_corpus([source_file], 10, COVERED_PYLINT_IDS)
-    findings = run(source_file, corpus)
-    assert findings
-    assert "not called from anywhere" in findings[0].notes[1]
-
-
-def test_call_site_note_override(make_source_file):
-    source = "def helper(a=1):\n" "    pass\n" "def caller():\n" "    helper(2)\n"
-    source_file = make_source_file("a.py", source)
-    corpus = _build_corpus([source_file], 10, COVERED_PYLINT_IDS)
-    findings = run(source_file, corpus)
-    notes = "\n".join(findings[0].notes)
-    assert "override every defaulted parameter" in notes
-
-
-def test_call_site_note_mixed(make_source_file):
-    source = (
-        "def helper(a=1):\n"
-        "    pass\n"
-        "def c1():\n"
-        "    helper()\n"
-        "def c2():\n"
-        "    helper(2)\n"
-    )
-    source_file = make_source_file("a.py", source)
-    corpus = _build_corpus([source_file], 10, COVERED_PYLINT_IDS)
-    findings = run(source_file, corpus)
-    notes = "\n".join(findings[0].notes)
-    assert "using defaults" in notes
-    assert "1 of 2" in notes
-
-
-def test_call_site_note_truncation(make_source_file):
-    source = "def helper(a=1):\n    pass\n"
-    for i in range(15):
-        source += f"def c{i}():\n    helper()\n"
-    source_file = make_source_file("a.py", source)
-    corpus = _build_corpus([source_file], 10, COVERED_PYLINT_IDS)
-    findings = run(source_file, corpus)
-    notes = "\n".join(findings[0].notes)
-    assert "and 5 other(s)" in notes
-
-
 def test_defaulted_param_names_in_notes(make_source_file, empty_corpus):
     source = "def f(a, b=2, *, c=3):\n    pass\n"
     source_file = make_source_file("a.py", source)

{python_surveyor-0.4.1 → python_surveyor-0.5.0}/tests/test_scanner.py

@@ -25,7 +25,7 @@ def test_scan_finds_smelly_file(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=None,
         excludes=(),
-        max_call_sites=5,
+        max_samples=5,
     )
     check_ids_found = {f.check_id for f in result.findings}
     assert "future-annotations-import" in check_ids_found
@@ -40,7 +40,7 @@ def test_scan_parse_error(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=None,
         excludes=(),
-        max_call_sites=5,
+        max_samples=5,
     )
     assert result.parse_errors
     assert result.parse_errors[0].path == broken
@@ -58,7 +58,7 @@ def test_scan_prunes_venv(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=None,
         excludes=(),
-        max_call_sites=5,
+        max_samples=5,
     )
     assert result.files_scanned == 1
     assert result.findings == ()
@@ -75,7 +75,7 @@ def test_scan_exclude_glob(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=None,
         excludes=("vendor",),
-        max_call_sites=5,
+        max_samples=5,
     )
     assert result.files_scanned == 1
 
@@ -89,7 +89,7 @@ def test_scan_check_subset(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=("future-annotations-import",),
         excludes=(),
-        max_call_sites=5,
+        max_samples=5,
     )
     assert all(f.check_id == "future-annotations-import" for f in result.findings)
     assert any(f.check_id == "future-annotations-import" for f in result.findings)
@@ -101,59 +101,10 @@ def test_scan_unknown_check_id_raises():
             root_paths=(".",),
             check_ids=("nonexistent-check",),
             excludes=(),
-            max_call_sites=5,
+            max_samples=5,
         )
 
 
-def test_build_corpus_call_sites(tmp_path):
-    source = (
-        "def helper():\n"
-        "    pass\n"
-        "def caller():\n"
-        "    helper()\n"
-        "    other.method()\n"
-    )
-    path = tmp_path / "a.py"
-    path.write_text(source, encoding="utf-8")
-    tree = ast.parse(source)
-    source_file = SourceFile(
-        path=path,
-        source=source,
-        lines=tuple(source.splitlines()),
-        tree=tree,
-        tokens=(),
-    )
-    corpus = _build_corpus([source_file], 5, COVERED_PYLINT_IDS)
-    assert "helper" in corpus.call_sites
-    assert "method" in corpus.call_sites
-    assert corpus.call_sites["helper"][0].positional_count == 0
-
-
-def test_build_corpus_call_args(tmp_path):
-    source = (
-        "def f(a, b=1, *, c=2):\n" "    pass\n" "f(1)\n" "f(1, 2, c=3)\n" "f(1, b=2)\n"
-    )
-    path = tmp_path / "a.py"
-    path.write_text(source, encoding="utf-8")
-    tree = ast.parse(source)
-    source_file = SourceFile(
-        path=path,
-        source=source,
-        lines=tuple(source.splitlines()),
-        tree=tree,
-        tokens=(),
-    )
-    corpus = _build_corpus([source_file], 5, COVERED_PYLINT_IDS)
-    sites = corpus.call_sites["f"]
-    assert len(sites) == 3
-    assert sites[0].positional_count == 1
-    assert sites[0].keywords == frozenset()
-    assert sites[1].positional_count == 2
-    assert sites[1].keywords == frozenset({"c"})
-    assert sites[2].positional_count == 1
-    assert sites[2].keywords == frozenset({"b"})
-
-
 def test_build_corpus_param_locations(tmp_path):
     source = "def f(db):\n" "    pass\n" "def g(db):\n" "    pass\n"
     path = tmp_path / "a.py"
@@ -182,7 +133,7 @@ def test_scan_result_is_sorted(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=None,
         excludes=(),
-        max_call_sites=5,
+        max_samples=5,
     )
     paths = [str(f.path) for f in result.findings]
     assert paths == sorted(paths)
@@ -190,13 +141,12 @@ def test_scan_result_is_sorted(tmp_path):
 
 def test_corpus_is_immutable():
     corpus = Corpus(
-        call_sites={},
         param_locations={},
-        max_call_sites=5,
+        max_samples=5,
         covered_pylint_ids=COVERED_PYLINT_IDS,
     )
     with pytest.raises(dataclasses.FrozenInstanceError):
-        corpus.max_call_sites = 10  # type: ignore[misc]
+        corpus.max_samples = 10  # type: ignore[misc]
 
 
 def test_scan_result_fields(tmp_path):
@@ -205,7 +155,7 @@ def test_scan_result_fields(tmp_path):
         root_paths=(str(tmp_path),),
         check_ids=None,
         excludes=(),
-        max_call_sites=5,
+        max_samples=5,
     )
     assert isinstance(result, ScanResult)
     assert result.files_scanned == 1