sarj-python-lint 1.10.1__tar.gz → 1.13.0__tar.gz

{sarj_python_lint-1.10.1 → sarj_python_lint-1.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sarj-python-lint
-Version: 1.10.1
+Version: 1.13.0
 Summary: Custom Python lint rules — AST-based, pre-commit-friendly, hypermodern defaults
 Project-URL: Homepage, https://code-standards.sarj.ai/rules/python/
 Project-URL: Documentation, https://code-standards.sarj.ai/rules/python/

{sarj_python_lint-1.10.1 → sarj_python_lint-1.13.0}/pyproject.toml

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

{sarj_python_lint-1.10.1 → sarj_python_lint-1.13.0}/src/sarj_python_lint/rules/_registry.py

@@ -79,6 +79,7 @@ from sarj_python_lint.rules.no_restated_comment import NoRestatedComment
 from sarj_python_lint.rules.no_secret_in_log import NoSecretInLog
 from sarj_python_lint.rules.no_select_star import NoSelectStar
 from sarj_python_lint.rules.no_service_behavior_in_settings import NoServiceBehaviorInSettings
+from sarj_python_lint.rules.no_shallow_container_type_guard import NoShallowContainerTypeGuard
 from sarj_python_lint.rules.no_string_concat_in_loop import NoStringConcatInLoop
 from sarj_python_lint.rules.no_swallowed_asyncio_cancellation import NoSwallowedAsyncioCancellation
 from sarj_python_lint.rules.no_tautological_expect import NoTautologicalExpect
@@ -164,6 +165,7 @@ from sarj_python_lint.rules.require_nodecode_for_splitting_settings_field import
     RequireNoDecodeForSplittingSettingsField,
 )
 from sarj_python_lint.rules.require_port_for_service import RequirePortForService
+from sarj_python_lint.rules.require_precise_factory_signature import RequirePreciseFactorySignature
 from sarj_python_lint.rules.require_public_dependency_contract import RequirePublicDependencyContract
 from sarj_python_lint.rules.require_pydantic_for_external_json import (
     RequirePydanticForExternalJson,
@@ -199,6 +201,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         RequireExplicitContractImplementation.id: RequireExplicitContractImplementation,
         DiscourageNullableConstructorParameters.id: DiscourageNullableConstructorParameters,
         RequirePublicDependencyContract.id: RequirePublicDependencyContract,
+        RequirePreciseFactorySignature.id: RequirePreciseFactorySignature,
         RequireExplicitServiceContract.id: RequireExplicitServiceContract,
         AsyncCleanupRegisteredSynchronously.id: AsyncCleanupRegisteredSynchronously,
         SubprocessKillWithoutReap.id: SubprocessKillWithoutReap,
@@ -260,6 +263,7 @@ REGISTRY: Mapping[str, type[Rule]] = MappingProxyType(
         NoHiddenConstructorFallback.id: NoHiddenConstructorFallback,
         NoInjectedModuleLoader.id: NoInjectedModuleLoader,
         NoNullableDependencyFallback.id: NoNullableDependencyFallback,
+        NoShallowContainerTypeGuard.id: NoShallowContainerTypeGuard,
         NoFileLevelEscapeHatchSuppression.id: NoFileLevelEscapeHatchSuppression,
         NoInvalidArgumentNameSuppression.id: NoInvalidArgumentNameSuppression,
         NoFastapiOnEvent.id: NoFastapiOnEvent,

sarj_python_lint-1.13.0/src/sarj_python_lint/rules/no_shallow_container_type_guard.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    Rule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+    is_suppressed,
+)
+from sarj_python_lint.rules._imports import TYPING_SOURCES
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+    from sarj_python_lint.rules._imports import ImportIndex
+
+
+_CONTAINERS = frozenset({"dict", "list", "set"})
+_MAPPING_SLOTS = 2
+_SLOTS = frozenset({"object", "str", "int", "bool", "float", "bytes"})
+_BUILTINS = _SLOTS | _CONTAINERS | {"isinstance"}
+_MUTATION_TARGETS = {f"builtins.{symbol}" for symbol in _BUILTINS} | {
+    "typing.TypeGuard",
+    "typing.TypeIs",
+    "typing_extensions.TypeGuard",
+    "typing_extensions.TypeIs",
+}
+_BAD = "from typing import TypeGuard\ndef is_mapping(value: object) -> TypeGuard[dict[str, object]]:\n    return isinstance(value, dict)\n"
+_GOOD = _BAD.replace("dict[str, object]", "dict[object, object]")
+
+
+@final
+class NoShallowContainerTypeGuard(Rule):
+    id = "no-shallow-container-type-guard"
+    code = "SARJ472"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Do not claim typed container contents from a container-only type guard.",
+        rationale="TypeGuard and TypeIs let callers trust their declared narrowing. Checking only dict, list, or set does not validate keys, values, or elements, so callers can perform operations that fail at runtime.",
+        remediation="Use object for unchecked container slots, or validate their contents when the narrower contract is required. Keep constrained input types that already prove the contents.",
+        category=RuleCategory.CORRECTNESS,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Checks top-level, undecorated, non-generic synchronous functions with one positional parameter proven to be builtin object and a single return isinstance(parameter, builtin_container), optionally after a docstring.",
+            "The TypeGuard or TypeIs target must be a matching builtin dict, list, or set whose slots all resolve to object, str, int, bool, float, or bytes; at least one slot must be narrower than object.",
+            "Includes authored tests; generated and vendor source is excluded. String annotations, constrained input types, unions, Any, TypeVars, Protocols, assignment aliases, nested definitions, and content validators are not inferred.",
+            "Annotation imports include TYPE_CHECKING imports. Runtime imports use conservative file-wide shadow facts, so unrelated local rebinding can cause false negatives. Wildcard imports, explicit writes to relevant builtin or typing attributes, and exception, pattern or walrus bindings that shadow relevant names or imported aliases exclude the file; dynamic namespace mutation is not inferred.",
+            "No autofix: widening the return contract can require caller changes, while adding content validation changes behavior and cost.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="unchecked-dictionary-keys",
+                title="A container check does not prove string keys",
+                outcome=ExampleOutcome.MATCH,
+                files=(ExampleFile.python("app/values.py", _BAD),),
+                focus_path=PurePosixPath("app/values.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="honest-dictionary-keys",
+                title="Unchecked keys retain their object type",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(ExampleFile.python("app/values.py", _GOOD),),
+                focus_path=PurePosixPath("app/values.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        if context.tree is None or context.generated or _ambiguous_symbols(context):
+            return []
+        findings: list[Diagnostic] = []
+        for function in context.tree.body:
+            if not isinstance(function, ast.FunctionDef):
+                continue
+            statement = _shallow_guard(function, context)
+            if statement is None or is_suppressed(context.source_lines, statement.lineno, self.code):
+                continue
+            findings.append(
+                Diagnostic(
+                    path=context.path,
+                    line=statement.lineno,
+                    col=statement.col_offset + 1,
+                    code=self.code,
+                    message="Container-only isinstance check does not validate the declared container contents; use object for unchecked slots or validate the contents required by the return type.",
+                    severity=Severity.WARNING,
+                )
+            )
+        return findings
+
+
+def _shallow_guard(function: ast.FunctionDef, context: PythonFileContext) -> ast.Return | None:
+    arguments = function.args
+    positional = (*arguments.posonlyargs, *arguments.args)
+    if function.decorator_list or function.type_params or len(positional) != 1:
+        return None
+    if arguments.kwonlyargs or arguments.vararg is not None or arguments.kwarg is not None:
+        return None
+    parameter = positional[0]
+    if _builtin_symbol(parameter.annotation, context.module_imports) != "object":
+        return None
+    name = _guarded_container(function.returns, context.module_imports)
+    if name is None:
+        return None
+    body = function.body
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        body = body[1:]
+    if len(body) != 1 or not isinstance(body[0], ast.Return):
+        return None
+    statement = body[0]
+    call = statement.value
+    if not isinstance(call, ast.Call) or call.keywords:
+        return None
+    match call.args:
+        case [ast.Name(id=guarded_name), checked_container] if (
+            guarded_name == parameter.arg
+            and _builtin_symbol(call.func, context.imports) == "isinstance"
+            and _builtin_symbol(checked_container, context.imports) == name
+        ):
+            return statement
+        case _:
+            return None
+
+
+def _guarded_container(annotation: ast.expr | None, imports: ImportIndex) -> str | None:
+    if not isinstance(annotation, ast.Subscript) or imports.resolved_symbol(
+        annotation.value, sources=TYPING_SOURCES
+    ) not in {"TypeGuard", "TypeIs"}:
+        return None
+    container = annotation.slice
+    if not isinstance(container, ast.Subscript):
+        return None
+    name = _builtin_symbol(container.value, imports)
+    if name not in _CONTAINERS:
+        return None
+    slots = container.slice.elts if isinstance(container.slice, ast.Tuple) else [container.slice]
+    kinds = [_builtin_symbol(slot, imports) for slot in slots]
+    if (
+        len(kinds) != (_MAPPING_SLOTS if name == "dict" else 1)
+        or any(kind not in _SLOTS for kind in kinds)
+        or all(kind == "object" for kind in kinds)
+    ):
+        return None
+    return name
+
+
+def _builtin_symbol(node: ast.expr | None, imports: ImportIndex) -> str | None:
+    if node is None:
+        return None
+    symbol = imports.resolved_symbol(node, sources=frozenset({"builtins"}))
+    if symbol in _BUILTINS:
+        return symbol
+    if isinstance(node, ast.Name) and node.id in _BUILTINS and imports.builtin_is_unshadowed(node.id):
+        return node.id
+    return None
+
+
+def _ambiguous_symbols(context: PythonFileContext) -> bool:
+    sensitive_names = _BUILTINS | {
+        name
+        for name, target in context.module_imports.bindings.items()
+        if target.module in TYPING_SOURCES | {"builtins"}
+        and (target.symbol is None or target.symbol in _BUILTINS | {"TypeGuard", "TypeIs"})
+    }
+    for node in context.nodes(
+        ast.ImportFrom, ast.Attribute, ast.ExceptHandler, ast.MatchAs, ast.MatchStar, ast.MatchMapping, ast.NamedExpr
+    ):
+        match node:
+            case ast.ImportFrom(names=aliases):
+                if any(alias.name == "*" for alias in aliases):
+                    return True
+            case ast.Attribute(ctx=(ast.Store() | ast.Del())):
+                if context.module_imports.resolved_qualified_name(node) in _MUTATION_TARGETS:
+                    return True
+            case (
+                ast.ExceptHandler(name=name)
+                | ast.MatchAs(name=name)
+                | ast.MatchStar(name=name)
+                | ast.MatchMapping(rest=name)
+                | ast.NamedExpr(target=ast.Name(id=name))
+            ):
+                if name in sensitive_names:
+                    return True
+            case _:
+                pass
+    return False

sarj_python_lint-1.13.0/src/sarj_python_lint/rules/require_precise_factory_signature.py

@@ -0,0 +1,252 @@
+from __future__ import annotations
+
+import ast
+from pathlib import PurePosixPath
+from typing import TYPE_CHECKING, ClassVar, final, override
+
+from sarj_python_lint.rule_base import (
+    AutofixPolicy,
+    Diagnostic,
+    ExampleFile,
+    ExampleOutcome,
+    ProjectRule,
+    RuleCategory,
+    RuleDocumentation,
+    RuleExample,
+    Severity,
+)
+from sarj_python_lint.rules._ast_index import walk
+from sarj_python_lint.rules._paths import is_generated, is_test_path, is_test_support_path
+
+
+if TYPE_CHECKING:
+    from sarj_python_lint._file_context import PythonFileContext
+
+
+_CALLABLE_ARITY = 2
+
+_CALLABLES = frozenset({"typing.Callable", "collections.abc.Callable", "typing_extensions.Callable"})
+
+
+@final
+class RequirePreciseFactorySignature(ProjectRule):
+    id = "require-precise-factory-signature"
+    code = "SARJ473"
+    documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
+        default_level=Severity.WARNING,
+        summary="Keep fixed keyword factory calls behind a precise callable signature.",
+        rationale="Callable[..., T] erases argument checking, so misspelled keywords and incompatible injected factories pass strict typing and can fail at runtime.",
+        remediation="Use an exact callable Protocol for substitutable factories. Use type[T] when this dependency genuinely requires a class, accounting for subclass constructor compatibility.",
+        category=RuleCategory.ARCHITECTURE,
+        autofix=AutofixPolicy.NONE,
+        limitations=(
+            "Only undecorated module-level functions with proven standard Callable[..., OwnedClass] parameters directly called with at least one named keyword are considered. Imported classes require scanned first-party declarations.",
+            "Tests, test support, generated code, unresolved/string/generic annotations, positional-only calls, unpacking, forwarding, nested captures, rebinding and ambiguous imports are excluded. Import capture checks are conservative across the file, so an unrelated local pattern, exception or walrus binding can prevent a warning.",
+            "A fixed call demonstrates signature erasure, not a current runtime defect. Genuine dynamic APIs can use a reasoned suppression. No autofix: the correct contract depends on whether classes or function factories are intended.",
+        ),
+        examples=(
+            RuleExample(
+                example_id="erased-factory",
+                title="Keyword arguments escape checking",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        "from collections.abc import Callable\nclass Result: pass\ndef build(factory: Callable[..., Result]):\n    return factory(size=4)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="exact-factory",
+                title="Factory declares its keyword contract",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "app/service.py",
+                        "from typing import Protocol\nclass Result: pass\nclass Factory(Protocol):\n    def __call__(self, *, size: int) -> Result: ...\ndef build(factory: Factory):\n    return factory(size=4)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("app/service.py"),
+                expected_count=0,
+                public=True,
+            ),
+        ),
+    )
+    description = documentation.summary
+
+    @override
+    def check_context(self, context: PythonFileContext) -> list[Diagnostic]:
+        tree = context.tree
+        if tree is None or context.generated or is_test_path(context.path) or is_test_support_path(context.path):
+            return []
+        if any(alias.name == "*" for node in context.nodes(ast.ImportFrom) for alias in node.names):
+            return []
+        findings: list[Diagnostic] = []
+        for function in tree.body:
+            if (
+                not isinstance(function, (ast.FunctionDef, ast.AsyncFunctionDef))
+                or function.decorator_list
+                or function.type_params
+            ):
+                continue
+            for argument in (*function.args.posonlyargs, *function.args.args, *function.args.kwonlyargs):
+                result = _factory_result(argument.annotation, context)
+                if (
+                    result is None
+                    or not _fixed_calls(function, argument.arg, context)
+                    or not _owned_result(result, function, context)
+                ):
+                    continue
+                findings.append(
+                    Diagnostic(
+                        path=context.path,
+                        line=argument.lineno,
+                        col=argument.col_offset + 1,
+                        code=self.code,
+                        message=f"`{argument.arg}` is called with fixed keywords but Callable[..., T] erases its argument contract; use a precise callable signature.",
+                        severity=Severity.WARNING,
+                    )
+                )
+        return sorted(findings, key=lambda finding: (finding.line, finding.col))
+
+
+def _factory_result(annotation: ast.expr | None, context: PythonFileContext) -> ast.Name | ast.Attribute | None:
+    if (
+        not isinstance(annotation, ast.Subscript)
+        or context.module_imports.resolved_qualified_name(annotation.value) not in _CALLABLES
+    ):
+        return None
+    if not isinstance(annotation.slice, ast.Tuple) or len(annotation.slice.elts) != _CALLABLE_ARITY:
+        return None
+    parameters, result = annotation.slice.elts
+    if (
+        not isinstance(parameters, ast.Constant)
+        or parameters.value is not Ellipsis
+        or not isinstance(result, (ast.Name, ast.Attribute))
+    ):
+        return None
+    root = _root(annotation.value)
+    if (root is not None and _captured_import_root(root, context)) or any(
+        isinstance(node.ctx, (ast.Store, ast.Del)) and _root(node) == root for node in context.nodes(ast.Attribute)
+    ):
+        return None
+    return result
+
+
+def _fixed_calls(function: ast.FunctionDef | ast.AsyncFunctionDef, name: str, context: PythonFileContext) -> bool:
+    contents = [node for statement in function.body for node in walk(statement)]
+    references = [node for node in contents if isinstance(node, ast.Name) and node.id == name]
+    return (
+        bool(references)
+        and not any(_binds_name(node, name) for node in contents)
+        and all(_direct_keyword_call(reference, function, context) for reference in references)
+    )
+
+
+def _direct_keyword_call(
+    reference: ast.Name, function: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext
+) -> bool:
+    call = context.parents.get(reference)
+    if not isinstance(call, ast.Call) or call.func is not reference or not call.keywords:
+        return False
+    if any(keyword.arg is None for keyword in call.keywords) or any(isinstance(arg, ast.Starred) for arg in call.args):
+        return False
+    parent = context.parents.get(call)
+    while parent is not None and parent is not function:
+        if isinstance(
+            parent,
+            (
+                ast.FunctionDef,
+                ast.AsyncFunctionDef,
+                ast.Lambda,
+                ast.ClassDef,
+                ast.ListComp,
+                ast.SetComp,
+                ast.DictComp,
+                ast.GeneratorExp,
+            ),
+        ):
+            return False
+        parent = context.parents.get(parent)
+    return parent is function
+
+
+def _owned_result(
+    result: ast.Name | ast.Attribute, function: ast.FunctionDef | ast.AsyncFunctionDef, context: PythonFileContext
+) -> bool:
+    tree = context.tree
+    if tree is None:
+        return False
+    root = _root(result)
+    if any(isinstance(node.ctx, (ast.Store, ast.Del)) and _root(node) == root for node in context.nodes(ast.Attribute)):
+        return False
+    local = next(
+        (
+            node
+            for node in tree.body
+            if isinstance(node, ast.ClassDef) and isinstance(result, ast.Name) and node.name == result.id
+        ),
+        None,
+    )
+    if local is not None:
+        return local.lineno < function.lineno and _stable_class(tree, local.name)
+    if root not in context.module_imports.bindings or (root is not None and _captured_import_root(root, context)):
+        return False
+    project = context.session.project
+    if project is None or (unit := project.unit_or_source(context.path, context.source, tree)) is None:
+        return False
+    summary = project.class_for(unit, result)
+    if (
+        summary is None
+        or (declaration := project.source_unit(summary.symbol.module)) is None
+        or declaration.tree is None
+    ):
+        return False
+    return not (
+        is_generated(declaration.path, declaration.source)
+        or is_test_path(declaration.path)
+        or is_test_support_path(declaration.path)
+    ) and _stable_class(declaration.tree, summary.symbol.name)
+
+
+def _stable_class(tree: ast.Module, name: str) -> bool:
+    declarations = [node for node in tree.body if isinstance(node, ast.ClassDef) and node.name == name]
+    if len(declarations) != 1 or declarations[0].decorator_list:
+        return False
+    return not any(_binds_name(node, name) for node in walk(tree) if node is not declarations[0])
+
+
+def _captured_import_root(name: str, context: PythonFileContext) -> bool:
+    return any(
+        _binds_name(node, name)
+        for node in context.nodes(ast.MatchAs, ast.MatchStar, ast.MatchMapping, ast.ExceptHandler)
+    ) or any(node.target.id == name for node in context.nodes(ast.NamedExpr))
+
+
+def _binds_name(node: ast.AST, name: str) -> bool:
+    match node:
+        case (
+            ast.Name(id=bound, ctx=(ast.Store() | ast.Del()))
+            | ast.arg(arg=bound)
+            | ast.FunctionDef(name=bound)
+            | ast.AsyncFunctionDef(name=bound)
+            | ast.ClassDef(name=bound)
+            | ast.ExceptHandler(name=str() as bound)
+            | ast.MatchAs(name=str() as bound)
+            | ast.MatchStar(name=str() as bound)
+            | ast.MatchMapping(rest=str() as bound)
+        ):
+            return bound == name
+        case ast.alias(name=imported, asname=alias):
+            return (alias or imported.split(".")[0]) == name
+        case _:
+            return False
+
+
+def _root(node: ast.expr) -> str | None:
+    while isinstance(node, ast.Attribute):
+        node = node.value
+    return node.id if isinstance(node, ast.Name) else None

{sarj_python_lint-1.10.1 → sarj_python_lint-1.13.0}/src/sarj_python_lint/rules/unused_test_factory_option.py

@@ -38,14 +38,15 @@ class UnusedTestFactoryOption(Rule):
     code = "SARJ443"
     documentation: ClassVar[RuleDocumentation | None] = RuleDocumentation(
         default_level=Severity.WARNING,
-        summary="A private test factory exposes a literal option that visible callers never vary.",
+        summary="A private test factory exposes an option that visible callers never vary.",
         rationale="Unused customization obscures the values that actually distinguish test scenarios.",
         remediation="Keep the value in the factory's construction instead of exposing an unused option; retain it if external callers need it.",
         category=RuleCategory.TESTING,
         autofix=AutofixPolicy.NONE,
         limitations=(
             "Only module-level private _make_ and _build_ helpers with straight-line local assignments ending in a construction return are considered; control flow and standalone side effects are excluded.",
-            "Only literal defaults with direct, unambiguous calls in this file are reported. Explicit options require at least two calls with the same effective literal value. Decorators, rebinding, callable escapes, reflection, and argument unpacking exclude the helper.",
+            "Literal defaults and stable earlier module-local function defaults are considered. Callable options are reported only when every direct caller omits them; explicit literal options require at least two calls with the same effective value.",
+            "Decorators, rebinding, shadowing, callable escapes, reflection, argument unpacking, and ambiguous provider mutation or patch targets exclude the affected helper or callable option.",
             "Cross-module callers cannot be proven absent. Shared helpers require an exact suppression; this advisory never autofixes signatures or changes default evaluation timing.",
         ),
         examples=(
@@ -77,6 +78,36 @@ class UnusedTestFactoryOption(Rule):
                 expected_count=0,
                 public=True,
             ),
+            RuleExample(
+                example_id="unused-callable-option",
+                scenario="callable-default",
+                title="Use an unexercised local dependency directly",
+                outcome=ExampleOutcome.MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _read():\n    return 'value'\n\ndef _make_widget(*, read=_read):\n    return Widget(read=read)\n\n_make_widget()\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=1,
+                public=True,
+            ),
+            RuleExample(
+                example_id="exercised-callable-option",
+                scenario="callable-default",
+                title="Keep a dependency that a caller replaces",
+                outcome=ExampleOutcome.NO_MATCH,
+                files=(
+                    ExampleFile.python(
+                        "tests/test_widget.py",
+                        "def _read():\n    return 'value'\n\ndef _make_widget(*, read=_read):\n    return Widget(read=read)\n\n_make_widget(read=other)\n",
+                    ),
+                ),
+                focus_path=PurePosixPath("tests/test_widget.py"),
+                expected_count=0,
+                public=True,
+            ),
         ),
     )
     description = documentation.summary
@@ -173,6 +204,27 @@ def _factory_findings(
                 ),
             )
         )
+    for argument, default in _factory_options(function):
+        if (
+            argument.arg in supplied
+            or not isinstance(default, ast.Name)
+            or not _is_stable_local_callable(tree, function, default.id, node_index=node_index)
+            or is_suppressed(lines, argument.lineno, code)
+        ):
+            continue
+        findings.append(
+            Diagnostic(
+                path=path,
+                line=argument.lineno,
+                col=argument.col_offset + 1,
+                code=code,
+                severity=Severity.WARNING,
+                message=(
+                    f"No direct caller in this file supplies `{function.name}.{argument.arg}`; use the stable local "
+                    f"callable `{default.id}` in the factory instead of exposing an unused option. Retain it if external callers need it."
+                ),
+            )
+        )
     return findings
 
 
@@ -258,18 +310,49 @@ def _factory_argument_is_invariant(argument: ast.arg, default: ast.Constant, bou
     )
 
 
-def _literal_factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.Constant]]:
-    options: list[tuple[ast.arg, ast.Constant]] = []
+def _factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.expr]]:
     positional = [*function.args.posonlyargs, *function.args.args]
     defaults = [
         *zip(positional[len(positional) - len(function.args.defaults) :], function.args.defaults, strict=True),
         *zip(function.args.kwonlyargs, function.args.kw_defaults, strict=True),
     ]
     used = {node.id for node in nodes(function, ast.Name) if isinstance(node.ctx, ast.Load)}
-    for argument, default in defaults:
-        if argument.arg not in used or not isinstance(default, ast.Constant):
-            continue
-        if default.value is not None and not isinstance(default.value, (str, bytes, int, float)):
-            continue
-        options.append((argument, default))
-    return options
+    return [(argument, default) for argument, default in defaults if argument.arg in used and default is not None]
+
+
+def _literal_factory_options(function: ast.FunctionDef) -> list[tuple[ast.arg, ast.Constant]]:
+    return [
+        (argument, default)
+        for argument, default in _factory_options(function)
+        if isinstance(default, ast.Constant)
+        and (default.value is None or isinstance(default.value, (str, bytes, int, float)))
+    ]
+
+
+def _is_stable_local_callable(
+    tree: ast.Module,
+    factory: ast.FunctionDef,
+    name: str,
+    *,
+    node_index: NodeIndex | None = None,
+) -> bool:
+    if not any(
+        isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+        and node.name == name
+        and node.lineno < factory.lineno
+        and not node.decorator_list
+        for node in tree.body
+    ) or not _has_unambiguous_factory_name(tree, name, node_index=node_index):
+        return False
+    return not (
+        any(node.id == name and not isinstance(node.ctx, ast.Load) for node in nodes(tree, ast.Name, index=node_index))
+        or any(
+            not isinstance(node.ctx, ast.Load) and any(child.id == name for child in nodes(node.value, ast.Name))
+            for node in nodes(tree, ast.Attribute, index=node_index)
+        )
+        or any(
+            isinstance(node.value, str)
+            and (node.value.rsplit(".", 1)[-1] == name or factory.name in node.value.split("."))
+            for node in nodes(tree, ast.Constant, index=node_index)
+        )
+    )