# Decorators whose presence means a symbol's callers cannot be determined by
# reading the code. One shell-glob pattern per line, matched against the
# decorator's dotted base name (`event.listens_for`, not the full call).
#
# Precision matters more than coverage. A flag on every decorated symbol is
# worth exactly as much as no flag at all: @property and @staticmethod do not
# belong here, because a call to a property is still statically visible.
#
# Every entry below was added from the decorator census printed by
# `spanda parse`, which lists what a codebase actually uses. Grow this file
# from that census rather than guessing.

# HTTP route handlers. The web framework calls these when a request arrives;
# nothing in the codebase calls them by name. In a web application these are
# by far the largest population of untraceable callers.
*.get
*.post
*.put
*.patch
*.delete
*.head
*.options
*.websocket

# ORM and signal event hooks: the framework calls these, nothing else does.
*.listens_for
*.receiver
*.connect

# Dependency injection: the container decides the caller at runtime.
Depends
*.Depends

# Dispatch registries: the concrete implementation is chosen at runtime.
*.register
*.hookimpl

# Pydantic validators, run by the model during construction. (~144)
field_validator
model_validator
*.field_validator
*.model_validator
validator
root_validator

# pytest fixtures, injected into tests by matching parameter names. Renaming a
# fixture silently detaches it from every test that requested it. (~478)
*.fixture
fixture

# Temporal workflow and activity entry points, invoked by the worker. (~54)
*.defn
workflow.run
workflow.signal
workflow.query

# LLM tool registration: the model chooses which to call, by name. (~36)
tool
tool_decorator

# Added after a human vetting of the "unreferenced" list found four live
# symbols in it. Not from the census: from the miss.
#
# ASGI middleware registered on the app; the framework calls it per request.
*.middleware
*.exception_handler
# MCP server handlers: the client's requests are routed to these by the SDK.
*.list_tools
*.call_tool
*.list_resources
*.read_resource
*.list_prompts
*.get_prompt
*.tool
*.resource
*.prompt

# Classes a framework owns by inheritance. A SQLAlchemy model is a mapped
# table whether or not any Python names the class: Alembic owns it, and
# deleting the class orphans the table. Eleven such models sat on a dead
# list before this section existed. Syntax: `class:<base glob>`, matched
# against the base names as written in the class statement.
class:Base
class:DeclarativeBase
class:SQLModel
class:db.Model
class:models.Model
class:Model

# Methods a framework calls by name on a subclass of its own base class.
# A decorator cannot express this: nothing is written at the definition
# except the override itself, and the base lives outside the codebase, so
# the resolver never sees the call. Syntax: `method:<base>.<method>`, both
# globs, matched against the base names as written in the class statement
# — `BaseHTTPMiddleware` and `starlette.middleware.base.BaseHTTPMiddleware`
# both match the short form.
method:BaseHTTPMiddleware.dispatch
method:HTTPEndpoint.get
method:HTTPEndpoint.post
method:HTTPEndpoint.put
method:HTTPEndpoint.patch
method:HTTPEndpoint.delete
method:HTTPEndpoint.head
method:HTTPEndpoint.options
method:WebSocketEndpoint.on_connect
method:WebSocketEndpoint.on_receive
method:WebSocketEndpoint.on_disconnect
method:Thread.run
method:Process.run
method:TestCase.setUp
method:TestCase.tearDown

# Decorators known NOT to hide a caller. Listed so that they can be told
# apart from decorators this file has never heard of: a symbol with no
# callers and a decorator on neither list is reported as *unrecognised*,
# never as dead. That is how the four misses above would have surfaced as
# questions instead of being vetted by hand. Syntax: `harmless:<glob>`.
#
#   pytest markers: a marker does not dispatch anything. The test function is
#   called by pytest, but flagging ~3,000 test functions would swamp the
#   report without telling anyone something they did not already know.
harmless:pytest.mark.*
harmless:mark.*
#   wrappers: calls to the decorated symbol stay visible at their call sites.
harmless:lru_cache
harmless:cache
harmless:cached_property
harmless:wraps
harmless:functools.*
harmless:dataclass
harmless:dataclasses.dataclass
harmless:contextmanager
harmless:asynccontextmanager
harmless:contextlib.*
harmless:total_ordering
harmless:singledispatch
harmless:unique
harmless:retry
harmless:*.retry
#   calling convention and typing: part of the signature hash already.
harmless:property
harmless:staticmethod
harmless:classmethod
harmless:abstractmethod
harmless:abc.abstractmethod
harmless:*.setter
harmless:*.getter
harmless:*.deleter
harmless:overload
harmless:typing.overload
harmless:final
harmless:override
harmless:typing.*
