sarj-python-lint 0.18.1__tar.gz → 0.19.0__tar.gz

{sarj_python_lint-0.18.1 → sarj_python_lint-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sarj-python-lint
-Version: 0.18.1
+Version: 0.19.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://github.com/sarj-ai/standards/tree/main/packages/python
 Project-URL: Repository, https://github.com/sarj-ai/standards
@@ -60,6 +60,31 @@ measured against.
     - id: sarj-sleep-with-computed-arg-in-test     # SARJ047
 ```
 
+### Private access, first-party only (0.19.0)
+
+```yaml
+    - id: sarj-no-first-party-private-import       # SARJ048
+```
+
+Reaching past a module's public surface is a design finding when the module is
+ours and an unavoidable fact of life when it is not: a dependency that moves an
+API private in a minor release leaves no edit that satisfies the lint.
+
+`SARJ048` fires only when the module declaring the private name resolves to a
+package inside your own project. Third-party privates are never flagged.
+
+**It replaces ruff's `PLC2701 import-private-name`,** whose only exemption is
+*same top-level package* — a different question, and one that cannot separate
+`from bulbul.stores.task_store import _row_to_task` (real; export it) from
+`from livekit.agents.inference_runner import _InferenceRunner` (no fix exists).
+`sarj-lint-configs` ≥ 0.8.0 ships `PLC2701` in its ignore list for exactly this
+reason; if you take that config, turn this hook on, or you lose the check
+entirely.
+
+Attribute access (`session._stt`) is out of scope and stays with ruff's
+`SLF001`, which cannot make the distinction either — see the rationale in
+`ruff.strict.toml`.
+
 Adopting these against an existing suite is easier through the baseline ratchet
 than as a big-bang fix — snapshot the current counts, then let them only shrink:
 

{sarj_python_lint-0.18.1 → sarj_python_lint-0.19.0}/README.md

@@ -42,6 +42,31 @@ measured against.
     - id: sarj-sleep-with-computed-arg-in-test     # SARJ047
 ```
 
+### Private access, first-party only (0.19.0)
+
+```yaml
+    - id: sarj-no-first-party-private-import       # SARJ048
+```
+
+Reaching past a module's public surface is a design finding when the module is
+ours and an unavoidable fact of life when it is not: a dependency that moves an
+API private in a minor release leaves no edit that satisfies the lint.
+
+`SARJ048` fires only when the module declaring the private name resolves to a
+package inside your own project. Third-party privates are never flagged.
+
+**It replaces ruff's `PLC2701 import-private-name`,** whose only exemption is
+*same top-level package* — a different question, and one that cannot separate
+`from bulbul.stores.task_store import _row_to_task` (real; export it) from
+`from livekit.agents.inference_runner import _InferenceRunner` (no fix exists).
+`sarj-lint-configs` ≥ 0.8.0 ships `PLC2701` in its ignore list for exactly this
+reason; if you take that config, turn this hook on, or you lose the check
+entirely.
+
+Attribute access (`session._stt`) is out of scope and stays with ruff's
+`SLF001`, which cannot make the distinction either — see the rationale in
+`ruff.strict.toml`.
+
 Adopting these against an existing suite is easier through the baseline ratchet
 than as a big-bang fix — snapshot the current counts, then let them only shrink:
 

{sarj_python_lint-0.18.1 → sarj_python_lint-0.19.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sarj-python-lint"
-version = "0.18.1"
+version = "0.19.0"
 description = "Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults"
 readme = "README.md"
 authors = [{ name = "sarj-ai" }]

sarj_python_lint-0.19.0/src/sarj_python_lint/rules/_first_party.py

@@ -0,0 +1,192 @@
+"""Shared first-party / third-party module resolution.
+
+Every "don't reach into privates" rule needs one thing no purely syntactic
+checker has: whether the module that *declares* the private name is ours or
+somebody else's. Reaching into our own module's underscore names is a design
+problem we can fix by exporting a public surface. Reaching into a dependency's
+underscore names is often the only option available — when a library moves an
+API private in a minor release, the "just use the public API" advice names an
+API that no longer exists, and the lint finding becomes an instruction to
+perform an impossible edit.
+
+Resolution is filesystem-based and deliberately conservative:
+
+* a module is FIRST-PARTY when its top-level name is a package directory (one
+  containing `__init__.py`) found inside the enclosing project;
+* everything else — stdlib, site-packages, anything unresolvable — is treated
+  as THIRD-PARTY, because the failure mode of guessing "third-party" is a
+  missed finding, while the failure mode of guessing "first-party" is exactly
+  the impossible-edit demand these rules exist to avoid.
+
+The `__init__.py` requirement is load-bearing, not incidental: bulbul carries a
+`python/bulbul/livekit/` directory of SIP trunk JSON, and a name-only match
+would have classified the `livekit` dependency as first-party and re-flagged
+the very imports this distinction exists to exempt. Requiring an importable
+package makes a top-level name collide only when a real first-party package
+shadows the distribution — at which point flagging it is correct.
+
+The project root is the nearest ancestor holding `.git`, falling back to the
+topmost contiguous run of ancestors holding `pyproject.toml` (worktrees,
+sdist checkouts, and vendored trees all resolve). Scanning stops at the first
+package directory on each branch, so only *top-level* package names are
+collected — `agent.lk.custom_models` contributes `agent`, never `lk`.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+import sys
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+# `.git` is a file, not a directory, inside a linked worktree — test existence,
+# never `is_dir()`.
+_GIT_MARKER = ".git"
+_PROJECT_MARKER = "pyproject.toml"
+
+# Never descend into these: a virtualenv or vendored tree holds *third-party*
+# packages, and collecting their names would classify every dependency as ours.
+_SKIP_DIR_NAMES = frozenset({
+    ".git",
+    ".mypy_cache",
+    ".next",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".tox",
+    ".turbo",
+    ".venv",
+    "__pycache__",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+})
+
+# Deep enough for a uv/pnpm-style monorepo (`<root>/packages/python/src/<pkg>`),
+# shallow enough that the scan stays a few hundred `iterdir()` calls.
+_MAX_SCAN_DEPTH = 5
+
+# Hard stop so a pathological tree (a huge monorepo, a symlink loop) degrades to
+# "nothing is first-party" — under-flagging — rather than hanging the linter.
+_MAX_DIRS_SCANNED = 3000
+
+# Walking up forever from a relative path is how a linter ends up scanning $HOME.
+_MAX_ANCESTORS = 24
+
+
+def is_first_party_module(module: str, path: Path) -> bool:
+    """Report whether dotted `module` is declared inside `path`'s own project.
+
+    Returns:
+        True when the module's top-level name resolves to a first-party package.
+
+    """
+    top = module.partition(".")[0]
+    if not top or top in sys.stdlib_module_names:
+        return False
+    root = _project_root(path)
+    if root is None:
+        return False
+    return top in _first_party_roots(root)
+
+
+def own_top_package(path: Path) -> str | None:
+    """Return the name of the top-level package `path` itself belongs to.
+
+    The OUTERMOST importable ancestor wins rather than the outermost of an
+    unbroken `__init__.py` run, because PEP 420 namespace subpackages are
+    routine — bulbul's `agent/agent/lk/custom_models/` carries no `__init__.py`
+    while `agent/agent/` does, and a break-on-first-gap walk would report the
+    file as belonging to no package at all.
+
+    Returns:
+        The top-level package name, or None when `path` is not inside a package.
+
+    """
+    resolved = _resolved(path)
+    if resolved is None:
+        return None
+    root = _project_root(resolved)
+    top: str | None = None
+    for ancestor in list(resolved.parents)[:_MAX_ANCESTORS]:
+        if (ancestor / "__init__.py").exists():
+            top = ancestor.name
+        if ancestor == root:
+            break
+    return top
+
+
+def _resolved(path: Path) -> Path | None:
+    try:
+        return path.resolve()
+    except OSError:
+        return None
+
+
+@lru_cache(maxsize=256)
+def _project_root(path: Path) -> Path | None:
+    """Locate the project boundary above `path`, memoized per file path.
+
+    Returns:
+        The project root directory, or None when no marker is found.
+
+    """
+    resolved = _resolved(path)
+    if resolved is None:
+        return None
+    ancestors = list(resolved.parents)[:_MAX_ANCESTORS]
+    for ancestor in ancestors:
+        if (ancestor / _GIT_MARKER).exists():
+            return ancestor
+    # No VCS boundary: take the OUTERMOST directory of the unbroken run of
+    # pyproject.toml ancestors, which is the workspace root in a uv workspace.
+    outermost: Path | None = None
+    for ancestor in ancestors:
+        if not (ancestor / _PROJECT_MARKER).exists():
+            if outermost is not None:
+                break
+            continue
+        outermost = ancestor
+    return outermost
+
+
+@lru_cache(maxsize=32)
+def _first_party_roots(root: Path) -> frozenset[str]:
+    """Collect the top-level package names declared anywhere under `root`.
+
+    Returns:
+        Every directory name under `root` that is an importable package.
+
+    """
+    names: set[str] = set()
+    queue: list[tuple[Path, int]] = [(root, 0)]
+    scanned = 0
+    while queue:
+        directory, depth = queue.pop()
+        scanned += 1
+        if scanned > _MAX_DIRS_SCANNED:
+            break
+        try:
+            entries = sorted(directory.iterdir())
+        except OSError:
+            continue
+        for entry in entries:
+            if entry.name.startswith(".") or entry.name in _SKIP_DIR_NAMES:
+                continue
+            try:
+                if not entry.is_dir():
+                    continue
+                is_package = (entry / "__init__.py").exists()
+            except OSError:
+                continue
+            if is_package:
+                names.add(entry.name)
+            elif depth + 1 < _MAX_SCAN_DEPTH:
+                queue.append((entry, depth + 1))
+    return frozenset(names)

{sarj_python_lint-0.18.1 → sarj_python_lint-0.19.0}/src/sarj_python_lint/rules/_registry.py

@@ -18,6 +18,9 @@ from sarj_python_lint.rules.no_cors_wildcard_with_credentials import (
 )
 from sarj_python_lint.rules.no_fat_try_blocks import NoFatTryBlocks
 from sarj_python_lint.rules.no_file_level_suppression import NoFileLevelSuppression
+from sarj_python_lint.rules.no_first_party_private_import import (
+    NoFirstPartyPrivateImport,
+)
 from sarj_python_lint.rules.no_fstring_in_log import NoFstringInLog
 from sarj_python_lint.rules.no_isinstance_union_chain import NoIsinstanceUnionChain
 from sarj_python_lint.rules.no_offset_pagination import NoOffsetPagination
@@ -116,6 +119,7 @@ REGISTRY: dict[str, type[Rule]] = {
     XfailRequiresStrict.id: XfailRequiresStrict,
     SleepWithComputedArgInTest.id: SleepWithComputedArgInTest,
     ZeroAssertionTest.id: ZeroAssertionTest,
+    NoFirstPartyPrivateImport.id: NoFirstPartyPrivateImport,
 }
 
 __all__ = ["REGISTRY"]

sarj_python_lint-0.19.0/src/sarj_python_lint/rules/no_first_party_private_import.py

@@ -0,0 +1,184 @@
+"""SARJ048: importing a private name — but only when the private name is OURS.
+
+Reaching past a module's public surface is a design finding when the module is
+ours and an unavoidable fact of life when it is not. `from bulbul.stores.task_store
+import _row_to_task` says a first-party module has a helper someone needed and
+did not export; the fix is to export it. `from livekit.agents.inference_runner
+import _InferenceRunner` says a dependency moved an API private in a minor
+release — livekit-agents 1.6.6 did exactly this to bulbul's custom EOU runner —
+and there is no edit that satisfies the lint short of vendoring the library or
+pinning it forever. A rule that cannot tell those apart is an instruction to
+perform an impossible edit, which is how blanket suppressions get born.
+
+This rule fires ONLY on the first case. Third-party privates are never flagged.
+
+Ruff's `PLC2701 import-private-name` is the rule this replaces, and it does not
+make the distinction. Its exemption is *same top-level package*, not
+*first-party*: measured over bulbul's five packages it produced 80 findings, of
+which 77 were first-party (real) and 3 were livekit reaches with no available
+fix. Ruff has no configuration surface that separates them — the check is
+purely lexical and never resolves an import to a location on disk. Pyright's
+`reportPrivateUsage` fires on the same third-party import and likewise has no
+first-party/third-party knob, so it still needs a per-line `# pyright: ignore`
+at the reach site; this rule does not change that, it only stops ruff from
+demanding a second, unfixable suppression on the same line.
+
+Fires on:
+
+* `from <first-party module> import _name` — a private symbol,
+* `from <first-party package>._private_module import Name`, and
+  `import <first-party package>._private_module` — a private *submodule*, which
+  is just as much a non-public surface as a private symbol.
+
+Deliberately NOT flagged:
+
+* **anything third-party.** A module is first-party only when its top-level
+  name resolves to a package directory inside the enclosing project (see
+  `_first_party.py`); stdlib, site-packages and anything unresolvable are
+  third-party. Unresolvable defaults to third-party on purpose: a missed
+  finding is a smaller failure than an unfixable one.
+* **relative imports** (`from . import _helper`, `from ._impl import Thing`) —
+  a relative import cannot leave its own package by construction, and a
+  package's own internals are its own business. This matches PLC2701.
+* **same-top-level-package absolute imports** — `from agent.lk.get_models
+  import _wire_fallback_metric` written from inside the `agent` package is the
+  spelled-out form of the bullet above. Written from `agent/tests/` — which is
+  not inside the package — it fires, because a white-box test reaching into a
+  module's internals from outside is the finding, not the exemption.
+* **dunder names** (`__version__`, `__all__`) — conventional module metadata,
+  not private internals.
+* **a private TOP-LEVEL package name** — `from _infra.fakes import FakeStt`,
+  bulbul's shared test-support package. The underscore there is the package's
+  own name, not a hidden corner of somebody else's module: there is no public
+  spelling to switch to and no surface to widen. PLC2701 flags these (14 hits
+  in bulbul's `agent` package alone) with no available fix. Private *sub*module
+  segments still fire.
+* `_`-prefixed *aliases* (`import json as _json`) — the alias is local shorthand
+  and the imported name is public.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, override
+
+from sarj_python_lint.rule_base import Diagnostic, Rule, parse_or_none
+from sarj_python_lint.rules._first_party import is_first_party_module, own_top_package
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class NoFirstPartyPrivateImport(Rule):
+    """A private name imported out of one of OUR modules — export it instead."""
+
+    id: str = "no-first-party-private-import"
+    code: str = "SARJ048"
+    description: str = (
+        "Importing a private (`_`-prefixed) name or module from a FIRST-PARTY module reaches past a "
+        "surface we control and can widen. Third-party privates are never flagged — that API is not ours to change."
+    )
+
+    @override
+    def check(self, path: Path, source: str) -> list[Diagnostic]:
+        """Flag every private import whose defining module is first-party.
+
+        Returns:
+            One diagnostic per private name (or private module) imported from
+            one of this project's own modules, sorted by position.
+
+        """
+        tree = parse_or_none(path, source)
+        if tree is None:
+            return []
+        own_top = own_top_package(path)
+        diags = [
+            Diagnostic(path=path, line=line, col=col, code=self.code, message=_message(module, name))
+            for line, col, module, name in _private_imports(tree)
+            if _is_ours(module, path, own_top)
+        ]
+        diags.sort(key=lambda d: (d.line, d.col))
+        return diags
+
+
+def _message(module: str, name: str) -> str:
+    return (
+        f"`{name}` is private to `{module}`, which is first-party — importing it reaches past a public "
+        f"surface we own and can widen. Export it under a public name, or move the caller behind a "
+        f"function `{module}` already exports. (Private imports from third-party packages are never flagged.)"
+    )
+
+
+def _is_ours(module: str, path: Path, own_top: str | None) -> bool:
+    """Report whether `module` is a first-party module OUTSIDE the file's own package.
+
+    Returns:
+        True when the private import crosses into another first-party package.
+
+    """
+    top = module.partition(".")[0]
+    if own_top is not None and top == own_top:
+        return False
+    return is_first_party_module(module, path)
+
+
+def _private_imports(tree: ast.Module) -> list[tuple[int, int, str, str]]:
+    """Collect `(line, col, defining module, private name)` for every private import.
+
+    Returns:
+        One entry per private symbol or private module segment imported
+        absolutely; relative imports are skipped.
+
+    """
+    hits: list[tuple[int, int, str, str]] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            hits.extend(_from_import_hits(node))
+        elif isinstance(node, ast.Import):
+            hits.extend(_plain_import_hits(node))
+    return hits
+
+
+def _from_import_hits(node: ast.ImportFrom) -> list[tuple[int, int, str, str]]:
+    # `node.level` > 0 is a relative import: inside its own package by construction.
+    if node.level or not node.module:
+        return []
+    private_segment = _private_segment(node.module)
+    if private_segment is not None:
+        return [(node.lineno, node.col_offset + 1, node.module, private_segment)]
+    return [
+        (alias.lineno, alias.col_offset + 1, node.module, alias.name)
+        for alias in node.names
+        if _is_private_name(alias.name)
+    ]
+
+
+def _plain_import_hits(node: ast.Import) -> list[tuple[int, int, str, str]]:
+    hits: list[tuple[int, int, str, str]] = []
+    for alias in node.names:
+        private_segment = _private_segment(alias.name)
+        if private_segment is not None:
+            hits.append((alias.lineno, alias.col_offset + 1, alias.name, private_segment))
+    return hits
+
+
+def _private_segment(module: str) -> str | None:
+    """Return the first private component BELOW the top level of a dotted module path.
+
+    The top-level name is deliberately excluded. `pkg._internals` is a module
+    `pkg` chose not to publish and could publish; a top-level package that is
+    simply *named* `_infra` — bulbul's shared test-support package — has no
+    other spelling and no wider surface to widen, so flagging its import asks
+    for an edit that does not exist.
+
+    Returns:
+        The private segment, or None when every component below the top is public.
+
+    """
+    return next((part for part in module.split(".")[1:] if _is_private_name(part)), None)
+
+
+def _is_private_name(name: str) -> bool:
+    # `__version__` / `__all__` are module metadata by convention, not internals.
+    return name.startswith("_") and not (name.startswith("__") and name.endswith("__"))