Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
refactor(dead-code): move module-level rules out of the analyzer (#4039)
Raghav Chamadiya0e13fffb31cc
diff --git a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py b/packages/core/src/repowise/core/analysis/dead_code/analyzer.pyindex b08a535aa..a73e45db2 100644--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py@@ -5,8 +5,8 @@ All analysis is graph traversal + SQL. No LLM calls. Must complete inThe four detection passes (unreachable files, unused exports, unusedinternals, zombie packages) live as methods on this class. Constants,-data models, and dynamic-import markers live in sibling modules under-this package.+data models, dynamic-import markers and the symbol, decorator and+source-scan rules live in sibling modules under this package."""from __future__ import annotations@@ -14,8 +14,7 @@ from __future__ import annotationsimport contextlibimport fnmatchimport os-import re-from collections.abc import Iterable, Iterator+from collections.abc import Iteratorfrom collections.abc import Set as AbstractSetfrom dataclasses import dataclassfrom datetime import UTC, datetime@@ -26,7 +25,6 @@ import structlogfrom ...code_origin import code_origin, is_build_filefrom ...entry_candidacy import is_reachability_root-from ...ingestion.decorator_names import decorator_base as _decorator_basefrom ...ingestion.models import REACHABILITY_USE_EDGE_TYPESfrom ...ingestion.package_roots import package_manifest_namesfrom ...ingestion.symbol_identity import base_symbol_id, overload_sets@@ -39,16 +37,10 @@ from .constants import (_CONTAINER_USE_LANGUAGES,_DEAD_CODE_EXEMPT_LANGUAGES,_DEFAULT_DYNAMIC_PATTERNS,- _DELIBERATELY_UNUSED_ANNOTATIONS,- _FRAMEWORK_DECORATOR_SUFFIXES,- _FRAMEWORK_DECORATORS,- _FRAMEWORK_INNER_CLASS_NAMES,_NAMESPACE_IMPORT_LANGUAGES,_NEVER_PACKAGE_DIRS,_PREPROCESSED_LANGUAGES,_PROJECT_FILE_SUFFIXES,- _PURE_WRAPPER_DECORATOR_ATTRS,- _PURE_WRAPPER_DECORATOR_MODULES,_RUN_NOT_IMPORTED_LANGUAGES,_is_fixture_path,never_flag_path,@@ -59,6 +51,16 @@ from .csharp_reachability import (build_csharp_named_types,scanned_implementations,)+from .decorator_rules import ( # noqa: F401 (moved rules re-exported)+ _DEPRECATED_DECORATOR_BASES,+ _QUOTED_STR_RE,+ _carries_argument,+ _declared_deliberately_unused,+ _decorator_bases,+ _is_framework_registered,+ _is_receiver_registration,+ _is_symbol_deprecated,+)from .deletion_gate import apply_deletion_gatefrom .dynamic_markers import (find_dynamic_edge_files,@@ -73,12 +75,18 @@ from .entry_shape import ()from .file_reachability import (_NON_DEPENDENCY_EDGES,- CSHARP_SUFFIX,PackageFileMap,ReachabilityRescues,build_package_file_map,is_file_reachable,)+from .finding_helpers import (+ _LINES_UNKNOWN,+ _csharp_exports,+ _is_synthetic_node,+ _names_by_file,+ _symbol_span,+)from .go_name_uses import drop_go_package_usesfrom .jvm_reachability import defines_mainfrom .kotlin_multiplatform import settle_platform_declarations@@ -105,7 +113,34 @@ from .risk_factors import (path_risk_factors,risk_evidence,)+from .source_prepasses import ( # noqa: F401 (moved scans re-exported)+ _BUNDLER_CONFIG_STEMS,+ _RELATIVE_PATH_STRING_RE,+ _TS_PROBE_SUFFIXES,+ _find_bundler_alias_targets,+ _find_jsx_namespace_files,+ _find_ts_export_aliases,+ _posix_normpath,+)from .swift_reachability import build_swift_named_files+from .symbol_rules import ( # noqa: F401 (moved rules re-exported)+ _CPP_BUILTIN_MACROS,+ _CPP_TYPE_DECLARATION_KINDS,+ _ENTRY_POINT_SYMBOL_NAMES,+ _LANGUAGE_NON_IMPORTABLE,+ _NON_IMPORTABLE_SYMBOL_KINDS,+ _SFC_LANGUAGES,+ _SFC_NON_IMPORTABLE_KINDS,+ _TS_JS_IMPORTABLE_KINDS,+ _TYPE_DECLARATION_KINDS,+ _UNCALLABLE_TYPE_KINDS,+ _UNIVERSAL_NON_IMPORTABLE,+ _is_compiler_invoked,+ _is_declaration_only,+ _is_public_top_level,+ _nested_class_used,+ _non_importable_kinds,+)from .vbnet_modules import vbnet_module_names#: The unindexed scan below and the repo-wide absence check ask the same@@ -130,636 +165,10 @@ _IDENTIFIER_RE = IDENTIFIER_RE_UNINDEXED_SCAN_PER_FILE_BYTES = 4 * 1024 * 1024_UNINDEXED_SCAN_TOTAL_BYTES = 32 * 1024 * 1024-# ----------------------------------------------------------------------------# Deprecation detection-# -----------------------------------------------------------------------------#: Normalised decorator/annotation bases (after stripping leading ``@`` and-#: any call-argument ``(…)`` tail) that signal a symbol is deprecated.-#:-#: Rust inner-attr form (``deprecated``), C# stripped form (``Obsolete``), and-#: C++ stripped form (``deprecated``) are included verbatim because the-#: respective sibling-walk extractors in ``parser.py`` already strip the-#: language-specific bracket pairs before storing.-_DEPRECATED_DECORATOR_BASES: frozenset[str] = frozenset(- {- # Python / TypeScript / Scala / Swift- "deprecated",- "typing.deprecated",- "warnings.deprecated",- # Java / Kotlin (case-sensitive annotation names)- "Deprecated",- "kotlin.Deprecated",- "java.lang.Deprecated",- # C# (inner attr text after stripping [ ])- "Obsolete",- "System.Obsolete",- "System.ObsoleteAttribute",- }-)---#: Regex that strips quoted string literals from a decorator/annotation text-#: before splitting on ``@`` boundaries. Without this,-#: ``@app.route("/deprecated")`` would produce a token whose paren-stripped-#: base is ``app.route`` (correct), but a hypothetical annotation whose-#: *argument* contains ``@something`` would create a spurious token.-_QUOTED_STR_RE: re.Pattern[str] = re.compile(r'"[^"]*"')---def _declared_deliberately_unused(decorators: Iterable[str]) -> bool:- """True when the author has written that the symbol is deliberately uncalled.-- Distinct from the framework lists, which infer a caller we cannot see. Here- there may be no caller at all and the annotation says so, which is a- stronger signal than any heuristic. Read from the raw token because the- base name is shared with every other use of the same annotation.- """- for blob in decorators:- # A Java/Kotlin modifiers node delivers every annotation concatenated,- # so the blob is split the way ``_is_symbol_deprecated`` splits it —- # without this, ``@Named("unused-legacy-bean")`` beside an unrelated- # ``@SuppressWarnings`` reads as the author's statement.- for token in str(blob).split("@"):- if not token.strip():- continue- base = _decorator_base(token)- if any(- base == name and _carries_argument(token, argument, whole)- for name, argument, whole in _DELIBERATELY_UNUSED_ANNOTATIONS- ):- return True- return False---def _carries_argument(token: str, argument: str, whole: bool) -> bool:- """*argument* in the annotation *token*: a substring, or one whole quoted argument."""- if not whole:- return argument in token- return argument in (q[1:-1].lower() for q in _QUOTED_STR_RE.findall(token))---def _is_framework_registered(- decorators: list[str], meta_annotations: frozenset[str] = frozenset()-) -> bool:- """Whether any decorator wires the symbol into a framework dispatcher.-- Both dead-code passes ask this question, and both asked it with the same- lines copy-pasted. It lives here once because a registration rule that- drifts between the export pass and the internals pass is a bug nobody goes- looking for.-- Four spellings of one fact:-- * a known base name or dotted prefix (``@Component``, ``@app.route``);- * a known trailing attribute, for a receiver the prefix list cannot- anticipate because it is named locally (``@my_group.command``);- * any other attribute of a receiver that is not a pure wrapper- (``@nox.session``), see :func:`_is_receiver_registration`;- * a registration verb in the final path segment. Every suffix entry begins- with a dot, so that list can only ever see a *dotted* decorator, and- celery's ``@register_drainer('eventlet')`` is bare — invisible to all of- them. Reading the final segment covers both spellings at once:- ``@register``, ``@register_drainer``, ``@Field.register_lookup``. Held to- ``register`` exactly or a ``register_`` stem so that a past participle- guarding a handler (``@registered_only``) is not read as one.-- A qualified annotation (``@androidx.compose.ui.tooling.preview.Preview``)- is also matched by its type name, and *meta_annotations* names the repo's- own annotation classes that carry one of these (a Compose multipreview):- an unqualified use by its in-scope local name, a qualified use by its- fully qualified name.- """- bases = _decorator_bases(decorators)- type_names = [n for n in (b.rsplit(".", 1)[-1] for b in bases) if n[:1].isupper()]- if any(b.startswith(_FRAMEWORK_DECORATORS) for b in (*bases, *type_names)):- return True- if not meta_annotations.isdisjoint(bases):- return True- if any(b.endswith(_FRAMEWORK_DECORATOR_SUFFIXES) for b in bases):- return True- if any(_is_receiver_registration(b) for b in bases):- return True- return any(- segment == "register" or segment.startswith("register_")- for segment in (b.rsplit(".", 1)[-1] for b in bases)- )---def _decorator_bases(decorators: Iterable[str]) -> list[str]:- """The base name of every annotation in *decorators*.-- A Java or Kotlin modifiers blob carries all of a declaration's annotations- (``@Fork(1) @State(Scope.Thread) public``), so each blob is split on- ``@`` once its quoted arguments are blanked, the way- :func:`_is_symbol_deprecated` reads it. Reading only the blob's first- annotation missed every one after it.- """- return [- _decorator_base(token)- for blob in decorators- for token in _QUOTED_STR_RE.sub('""', str(blob)).split("@")- if token.strip()- ]---def _is_receiver_registration(base: str) -> bool:- """Whether a dotted decorator hands the symbol to a receiver object.-- ``@nox.session``, ``@mcp.tool()`` and ``@sub.handle(...)`` are the shape:- an attribute of some object, called later by that object. The lists above- can only name receivers someone thought of, so the rule is inverted: any- ``recv.attr`` is a registration unless it is a pure wrapper (functools,- typing, contextlib, ``@x.setter`` and the like), which returns the function- for an ordinary caller to call.-- Held to a lowercase attribute. A capitalised last segment is a qualified- type name (``@java.lang.Deprecated``, ``[System.Obsolete]``), an annotation- rather than a method on a receiver.-- Ceiling: matched on the text, so an aliased wrapper module- (``import functools as ft``) reads as a registration. That only ever hides- a finding.- """- receiver, _, attr = base.rpartition(".")- if not receiver or not (attr[:1].islower() or attr.startswith("_")):- return False- if receiver.split(".", 1)[0] in _PURE_WRAPPER_DECORATOR_MODULES:- return False- return attr not in _PURE_WRAPPER_DECORATOR_ATTRS---def _is_symbol_deprecated(sym_name: str, decorators: list[str]) -> bool:- """Return True when the symbol is marked deprecated by name suffix or annotation.-- Two mechanisms are checked in order:-- 1. **Name suffix**: the name ends with ``_DEPRECATED``, ``_LEGACY``, or- ``_COMPAT`` (original naming-convention check, preserved for backward- compatibility).-- 2. **Decorator / annotation**: each entry in *decorators* is treated as a- possibly multi-annotation modifier blob (Java/Kotlin ``modifiers`` node- delivers all annotations concatenated with whitespace in a single- string). Each entry is first cleaned of quoted substrings (to avoid- matching paths like ``"/deprecated"`` inside ``@app.route("/deprecated")``),- then split on ``@`` boundaries so every individual annotation is checked- independently. Each token is normalised via :func:`_decorator_base` and- tested against ``_DEPRECATED_DECORATOR_BASES`` and the lower-cased- ``"deprecated"`` catch-all.-- The *decorators* list is produced by ``parser.py`` ``_extract_symbols``:- - Python / Scala / Swift: full decorator text with leading ``@``- (e.g. ``"@deprecated"``, ``"@typing.deprecated"``).- - Java / Kotlin: full modifier-node text — one blob per declaration that- may contain several annotations plus visibility keywords- (e.g. ``"@Deprecated\n public"``,- ``"@Override\n @Deprecated\n public"``).- - Rust: inner attribute content stripped of ``#[…]``- (e.g. ``"deprecated"`` from ``#[deprecated]``).- - C#: inner attribute content stripped of ``[…]``- (e.g. ``"Obsolete"`` from ``[Obsolete]``).- - C++: inner attribute content stripped of ``[[…]]``- (e.g. ``"deprecated"`` from ``[[deprecated]]``).- """- # 1. Name suffix- if any(sym_name.endswith(s) for s in ("_DEPRECATED", "_LEGACY", "_COMPAT")):- return True- # 2. Decorator / annotation- for raw in decorators:- # Strip quoted strings first so path arguments like "/deprecated"- # inside ``@app.route("/deprecated")`` do not create false tokens.- cleaned = _QUOTED_STR_RE.sub('""', raw)- # Split on '@' to tokenize modifier blobs. A leading '@' produces- # an empty first element which the ``if not token`` guard discards.- # No-'@' forms (Rust/C#/C++ inner attrs: "deprecated", "Obsolete")- # yield a single token equal to the whole string.- for token in cleaned.split("@"):- token = token.strip()- if not token:- continue- base = _decorator_base(token)- if base in _DEPRECATED_DECORATOR_BASES or base.lower() == "deprecated":- return True- return False--# Symbol kinds that cannot be independently imported by name in any-# supported language. Flagging them as "unused exports" is a guaranteed-# false-positive — they're always accessed through an enclosing class /-# namespace. C# auto-properties land in the graph as ``variable``;-# fields / enum members / type aliases / namespace anchors share the-# same property.-_UNIVERSAL_NON_IMPORTABLE: frozenset[str] = frozenset(- {- "method",- "variable",- "field",- "property",- "enum_member",- "constant",- "type_alias",- "namespace",- "module",- "impl",- }-)--# Additional kinds skipped only for languages where the graph cannot yet-# observe interface usage. In practice these are DI-heavy languages-# whose canonical interface-consumption path is constructor injection —-# resolved by the type-use edge pass (see-# ``ingestion/type_ref_resolution.py``). Once a language emits-# ``via=type_use`` edges, its entry here can be removed.-#-# C# already has type-use coverage (ctor + method + delegate +-# primary-ctor param.type captures), so ``interface`` is *not* skipped-# for C# — a genuinely unused C# interface is now observable.-#-# TS / Python / JS interfaces were always imported by name and never-# needed the skip; treating them uniformly produced false negatives.-_LANGUAGE_NON_IMPORTABLE: dict[str, frozenset[str]] = {- "java": frozenset({"interface"}),- "kotlin": frozenset({"interface"}),- "scala": frozenset({"interface"}),-}---# Kinds allowed as top-level imports in TS/JS (top-level `export const` literals/objects)-_TS_JS_IMPORTABLE_KINDS: frozenset[str] = frozenset({"constant", "variable"})--# Single-file-component languages: the whole file is one component, so their-# exports behave unlike an ordinary module's — see _non_importable_kinds.-_SFC_LANGUAGES: frozenset[str] = frozenset({"svelte", "vue", "astro"})--# Every kind an SFC component prop can take, plus "class" for the synthetic-# component symbol itself — see _non_importable_kinds.-_SFC_NON_IMPORTABLE_KINDS: frozenset[str] = frozenset(- {"constant", "variable", "function", "class", "interface", "type_alias"}-)---def _non_importable_kinds(language: str) -> frozenset[str]:- """Per-language set of symbol kinds excluded from unused-export passes.-- Returns the union of the universal set and any language-specific- additions. Cheap to call — short lookup, no per-call allocation- when the language has no additions.- """- # An SFC's top-level exports are its props: Svelte's ``export let x`` is- # set by the PARENT as a markup attribute (``<Foo x={1} />``), never by an- # ``import { x }``. repowise models component instantiation as a call edge- # on the component, not as symbol-level edges on each prop, so every prop- # would read as an unused export.- #- # The component symbol itself needs the same treatment, which is why- # "class" is in the set. A component is reached as a whole module — by a- # markup tag, or by a router's ``import('@/views/profile')``, which binds- # no name at all — so it never carries the symbol-level inbound edge the- # unused-export pass looks for. On vue-element-admin that alone accounted- # for 45 of 53 findings, every one of them a false positive.- #- # Suppressing the whole pass is the honest ceiling: it costs the- # genuinely-dead named exports of a Svelte ``<script context="module">``- # or a Vue non-setup ``<script>``, which cannot be told apart from props- # without modelling attribute-to-prop binding across files.- if language in _SFC_LANGUAGES:- return _UNIVERSAL_NON_IMPORTABLE | _SFC_NON_IMPORTABLE_KINDS-- extra = _LANGUAGE_NON_IMPORTABLE.get(language)- if extra is None:- if language in ("typescript", "javascript"):- return _UNIVERSAL_NON_IMPORTABLE - _TS_JS_IMPORTABLE_KINDS- return _UNIVERSAL_NON_IMPORTABLE- return _UNIVERSAL_NON_IMPORTABLE | extra--# Preserved for tests / external callers that imported the old name.-# New code should prefer ``_non_importable_kinds(language)``.-_NON_IMPORTABLE_SYMBOL_KINDS: frozenset[str] = _UNIVERSAL_NON_IMPORTABLE | frozenset({"interface"})--# Aggregate *type* kinds that are never call targets. The unused-internal-# pass is a call-graph check ("private symbol with no incoming CALL edges"),-# which is meaningful for functions/methods but not for types: a struct or-# interface used only as a field/parameter/return type — especially within-# its own file — has no call edge and no observable symbol-level type edge,-# so "no callers" is not evidence of deadness. Such types are still subject-# to the *unused-export* pass (which reasons over import names / type_use),-# so genuinely-dead exported types are still surfaced there.-_UNCALLABLE_TYPE_KINDS: frozenset[str] = frozenset(- {- "struct",- "interface",- "enum",- "type_alias",- "impl",- }-)---#: C/C++ symbol kinds a bare ``class Env;`` / ``struct Options;`` can carry.-#: Paired with ``is_declaration`` this identifies a type forward declaration,-#: which is never a deletable unit — see the guard in ``_detect_unused_exports``.-#: Kinds that declare a type, which Java and C# use from their own package or-#: namespace without an import.-_TYPE_DECLARATION_KINDS: frozenset[str] = frozenset(- {"class", "interface", "struct", "enum", "record", "trait", "object"}-)--_CPP_TYPE_DECLARATION_KINDS: frozenset[str] = frozenset(- {- "class",- "struct",- "enum",- }-)--# Symbol names that are language-runtime entry points or compiler-implicit-# anchors — never invoked by user-authored callers, never dead.-_ENTRY_POINT_SYMBOL_NAMES: frozenset[str] = frozenset(- {- "Main", # C#, Java, Kotlin, Go, Rust, Swift, Scala- "main", # most others- # ---- Go runtime / test conventions ------------------------------- # ``func init`` is run by the Go runtime when the package is linked —- # never called by name, so it has no inbound call edge. ``TestMain``- # is the test-binary entry the ``go test`` runner invokes by reflection.- "init",- "TestMain",- "MauiProgram", # .NET MAUI- "Program", # C# top-level / classic console- "Startup", # ASP.NET Core legacy- "__module__", # synthetic per-file module anchor- "_start", # C runtime- # ---- Python WSGI / ASGI / app-factory conventions ---------------- # Loaded by external servers (uvicorn / gunicorn / hypercorn /- # Tornado / aiohttp / Django) via dotted-path string such as- # ``module:create_app`` or ``module:application``. The graph never- # sees a call edge from the launching server, so without this- # allowlist every web entry point shows up as an unused public- # symbol with 1.0 confidence.- "create_app",- "make_app",- "create_application",- "make_application",- "application",- "asgi_app",- "wsgi_app",- "asgi_application",- "wsgi_application",- "get_asgi_application",- "get_wsgi_application",- # ---- Windows DLL / COM entry points ------------------------------ # Invoked by the Windows loader or COM runtime; never referenced- # statically from user code.- "DllMain",- "DllGetClassObject",- "DllCanUnloadNow",- "DllRegisterServer",- "DllUnregisterServer",- "DllGetActivationFactory",- "DllInstall", # legacy MSI custom-action entry- # ---- Win32 GUI / console entry points ---------------------------- "wWinMain", # Unicode WinMain- "WinMain", # ANSI WinMain- "wmain", # Unicode console main- "ServiceMain", # Win32 service entry- # Screen savers: scrnsave.lib calls these three by name.- "ScreenSaverProc",- "ScreenSaverConfigureDialog",- "RegisterDialogClasses",- # ---- libFuzzer / Honggfuzz / AFL fuzz harness entries ------------- # The fuzzer driver invokes these by name via dlsym; no static- # caller will ever exist.- "LLVMFuzzerTestOneInput",- "LLVMFuzzerInitialize",- # ---- Windows hook / ETW callbacks invoked by macros / runtime ----- "LowLevelKeyboardProc",- "LowLevelMouseProc",- "RegisterProvider", # ETW provider registration (macro-invoked)- # ---- MSTest unit-test macro --------------------------------------- # ``TEST_METHOD(Name)`` expands into a public static function with- # ``TEST_METHOD`` as the captured symbol name; the runner finds it- # by attribute reflection. Same shape on every C++ unit test file.- "TEST_METHOD",- "TEST_CLASS",- "TEST_METHOD_INITIALIZE",- "TEST_METHOD_CLEANUP",- "TEST_CLASS_INITIALIZE",- "TEST_CLASS_CLEANUP",- "BEGIN_TEST_METHOD_PROPERTIES",- "END_TEST_METHOD_PROPERTIES",- # ---- Next.js (app + pages router) convention exports -------------- # Loaded by the Next.js runtime by name; never appear as user-code- # imports. The convention file globs already cover ``page.tsx``/- # ``route.ts``/``layout.tsx``, so this set only catches the long- # tail of route exports that escape file-glob protection (e.g.- # routes placed in non-standard paths). Limited to names that are- # distinctive enough not to risk masking dead code in unrelated- # files; common identifiers (``load``, ``action``, ``metadata``,- # ``config``, ``headers``, ``meta``, ``links``, ``runtime``) are- # deliberately omitted — they get file-level protection via the- # convention globs in :data:`_NEVER_FLAG_PATTERNS`.- "generateStaticParams",- "generateMetadata",- "generateViewport",- "generateImageMetadata",- "generateSitemaps",- "dynamicParams",- "fetchCache",- "preferredRegion",- "maxDuration",- "getStaticProps",- "getStaticPaths",- "getServerSideProps",- "getInitialProps",- "reportWebVitals",- # ---- Remix route module exports (distinctive names only) ---------- "shouldRevalidate",- "ErrorBoundary",- "CatchBoundary",- "HydrateFallback",- "clientLoader",- "clientAction",- # ---- SvelteKit page/layout module exports (distinctive names) ----- "trailingSlash",- # ---- JVM (Java + Kotlin) runtime / serialization / contract anchors ----- # ``main`` is already covered above; these are the rest of the names- # the JVM resolves through reflection / serialization / Lombok-equivalent- # generation, never through static call edges. ``INSTANCE`` is the- # Kotlin ``object Foo`` singleton field; the JVM accesses it directly.- "serialVersionUID",- "readObject",- "writeObject",- "readObjectNoData",- "readResolve",- "writeReplace",- "canEqual", # Lombok-equivalent generated method- "INSTANCE", # Kotlin object singleton field- "Companion", # Kotlin companion-object accessor- }-)---# Compiler-intrinsic preprocessor macros C/C++ libraries redefine as a-# fallback for compilers that don't ship them (``#if !defined(__has_include)-# \n#define __has_include(h) 0``). The tree-sitter cpp grammar extracts the-# ``#define`` as a ``preproc_function_def`` symbol, but the call sites are-# preprocessor ``#if __has_include(...)`` directives, which the static-# graph cannot observe — so without this skip every such fallback flags-# as an unused export.-_CPP_BUILTIN_MACROS: frozenset[str] = frozenset(- {- "__has_include",- "__has_include_next",- "__has_feature",- "__has_extension",- "__has_attribute",- "__has_cpp_attribute",- "__has_c_attribute",- "__has_declspec_attribute",- "__has_builtin",- "__has_warning",- "__builtin_expect",- "__builtin_unreachable",- "__builtin_assume",- "__builtin_constant_p",- "__is_identifier",- "__FILE__",- "__LINE__",- "__DATE__",- "__TIME__",- "__func__",- "__FUNCTION__",- "__PRETTY_FUNCTION__",- }-)logger = structlog.get_logger(__name__)-def _find_jsx_namespace_files(- parsed_files: dict,- source_map: dict[str, bytes] | None = None,-) -> set[str]:- """Return repo-relative paths of TS/TSX files that declare ``namespace JSX``.-- Symbols whose name is in :data:`_TS_JSX_NAMESPACE_TYPES` and whose- defining file lives in this set are integration points with the JSX- transformer — referenced implicitly by every JSX expression, never- imported by name. The scan is a cheap substring check; tree-sitter- grammar work for a richer signal would be wasted effort.- """- matches: set[str] = set()- for path, pf in parsed_files.items():- try:- file_info = getattr(pf, "file_info", None)- if file_info is None:- continue- src_path = Path(file_info.abs_path)- if src_path.suffix not in (".ts", ".tsx", ".d.ts"):- continue- source = read_source_text(path, file_info.abs_path, source_map)- # Match ``namespace JSX`` and ``declare namespace JSX`` — both- # are JSX transformer integration points in practice.- if "namespace JSX" in source:- matches.add(path)- except Exception:- continue- return matches---_BUNDLER_CONFIG_STEMS = ("vite.config", "webpack.config", "rollup.config", "rspack.config")--# Any quoted slash-containing path-ish string. Bundler configs reference-# alias targets both as ``'./src/shims/x.ts'`` and as bare segments fed to-# ``path.resolve(here, 'src/shims/x.ts')``; the parsed-files membership-# probe below keeps loose matches harmless.-_RELATIVE_PATH_STRING_RE = re.compile(r"""['"]((?:\.\.?/)?[\[email protected]]+(?:/[\[email protected]]+)+)['"]""")--_TS_PROBE_SUFFIXES = ("", ".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs")---def _find_bundler_alias_targets(- parsed_files: dict,- source_map: dict[str, bytes] | None = None,-) -> set[str]:- """Repo-relative paths referenced from bundler config files.-- Vite/webpack ``resolve.alias`` entries substitute a bare package import- with a local file (``shiki`` → ``src/shims/shiki.ts``): no source file- ever imports the shim path, only the config names it, so the shim reads- as unreachable. Any relative path string inside a bundler config that- resolves to an indexed file marks that file reachable.- """- targets: set[str] = set()- configs = [- (path, pf)- for path, pf in parsed_files.items()- if Path(path).name.startswith(_BUNDLER_CONFIG_STEMS)- ]- for path, pf in configs:- try:- file_info = getattr(pf, "file_info", None)- if file_info is None:- continue- source = read_source_text(path, file_info.abs_path, source_map)- except Exception:- continue- config_dir = Path(path).parent- for match in _RELATIVE_PATH_STRING_RE.finditer(source):- base = _posix_normpath(config_dir, match.group(1))- for suffix in _TS_PROBE_SUFFIXES:- candidate = base + suffix- if candidate in parsed_files:- targets.add(candidate)- break- return targets---def _posix_normpath(config_dir: Path, raw: str) -> str:- """Join *raw* onto *config_dir* and normalise ``.``/``..`` as POSIX."""- import posixpath-- return posixpath.normpath(posixpath.join(config_dir.as_posix(), raw))---def _find_ts_export_aliases(parsed_files: dict) -> dict[str, dict[str, str]]:- """Per-file ``{local_name: exported_alias}`` maps for TS/JS alias exports.-- ``export { ConversationHistoryWrapper as ConversationHistory }`` publishes- the symbol under the alias, so importers pull ``ConversationHistory`` and- the local name never appears in any ``imported_names`` edge. The unused-- export pass consults this map to match the alias as well.-- Inverted from what the parser already recorded, rather than scanned again.- This pass used to own a second regex over the same clause and a second read- of every TS/JS file; the parser now reads the clause once, with comments- stripped, and the two answers can no longer disagree.- """- aliases: dict[str, dict[str, str]] = {}- for path, pf in parsed_files.items():- published = getattr(pf, "export_aliases", None)- if not published:- continue- aliases[path] = {local: exported for exported, local in published.items()}- return aliases---def _is_synthetic_node(node: str) -> bool:- """True for non-file graph nodes that should be skipped in 'is this dead?' passes.-- Two synthetic prefixes exist:- - ``external:`` — third-party / unresolved imports.- - ``framework:`` — anchors added by ``framework_edges`` to model- convention-based loading (e.g. TYPO3 core loading ``ext_localconf.php``).-- Both are skipped when the analyzer asks "is this node itself dead?",- but they are treated differently in the zombie-package pass: ``framework:``- predecessors *do* count as cross-package importers (real framework-- mediated dependencies), whereas ``external:`` predecessors do not.- """- return node.startswith("external:") or node.startswith("framework:")--@dataclassclass _ExportFile:"""One file's facts, shared by every public symbol the export pass judges in it."""@@ -779,99 +188,12 @@ class _ExportFile:enclosing_ranges: list[tuple[int, int]]-def _is_compiler_invoked(sym: dict, sym_name: str) -> bool:- """Symbols the compiler or linker calls, which no graph edge can show."""- # Fallback definitions of compiler intrinsics (``__has_include``) are only- # ever used from preprocessor directives.- if sym.get("language") in ("cpp", "c") and sym_name in _CPP_BUILTIN_MACROS:- return True- # Rust proc-macro entry points are invoked by the compiler.- if sym.get("language") == "rust":- decorators = sym.get("decorators") or []- if any(d.startswith("proc_macro") for d in decorators):- return True- # Explicit export markers (``dllexport``, ``visibility("default")``) mean- # callers outside this binary.- return bool(sym.get("is_exported_symbol"))---def _is_declaration_only(sym: dict) -> bool:- """C/C++ declarations that are not a deletable unit of their own."""- # A prototype whose definition was found: the definition carries the- # finding. An unmatched prototype is still reported.- if sym.get("is_declaration") and sym.get("defined_by"):- return True- # A type forward declaration (``class Env;``) exists so its own file can- # name the type, which makes that file its user.- return bool(- sym.get("is_declaration")- and sym.get("language") in ("cpp", "c")- and sym.get("kind") in _CPP_TYPE_DECLARATION_KINDS- )---# Evidence line for a finding whose ``lines`` is ``None``: the count is-# omitted rather than estimated.-_LINES_UNKNOWN = "Line count unavailable: source was not read"--#: ``(days, confidence)`` rungs for a file with no commit in 90 days, oldest#: first. ``_is_old`` uses strict >, so days-1 gives >= semantics: a year or#: more untouched is 1.0, very likely dead._GIT_AGE_RUNGS: tuple[tuple[int, float], ...] = ((364, 1.0), (179, 0.9), (89, 0.8))-def _is_public_top_level(sym: dict, kinds: AbstractSet[str] | None) -> bool:- if sym.get("visibility") != "public" or sym.get("parent_name"):- return False- return kinds is None or sym.get("kind") in kinds---def _nested_class_used(node_data: dict, sym: dict) -> bool:- """Whether a nested class is one a framework reads or its module names.-- ``ingestion/python_local_refs.py`` records a nested class its module reaches- (``Outer.Inner``, or ``Inner`` inside ``Outer``) under its ``Outer.Inner``- name, since a bare inner name like ``ErrorModel`` repeats across classes.- """- parent = sym.get("parent_name")- if not parent:- return False- name = sym.get("name", "")- if name in _FRAMEWORK_INNER_CLASS_NAMES.get(sym.get("language", ""), ()):- return True- return f"{parent}.{name}" in (node_data.get("local_refs") or ())---def _csharp_exports(findings: list[DeadCodeFindingData]) -> list[DeadCodeFindingData]:- """The unused-export findings in ``.cs`` files."""- return [- f- for f in findings- if f.kind is DeadCodeKind.UNUSED_EXPORT and f.file_path.endswith(CSHARP_SUFFIX)- ]---def _names_by_file(findings: list[DeadCodeFindingData]) -> dict[str, set[str]]:- """File -> the symbol names *findings* report there."""- out: dict[str, set[str]] = {}- for f in findings:- out.setdefault(f.file_path, set()).add(f.symbol_name or "")- return out---def _symbol_span(data: dict) -> dict[str, int | None]:- """``lines``/``start_line``/``end_line`` for a symbol finding.-- Both-or-neither: a half-known span is worse than none. Spans are- inclusive, so a one-line symbol is 1 line; an unknown span is ``None``.- """- start, end = data.get("start_line") or None, data.get("end_line") or None- if start is None or end is None or end < start:- return {"lines": None, "start_line": None, "end_line": None}- return {"lines": end - start + 1, "start_line": start, "end_line": end}--class DeadCodeAnalyzer:"""Detects unreachable files, unused exports, unused internals, andzombie packages using the dependency graph and git metadata.diff --git a/packages/core/src/repowise/core/analysis/dead_code/decorator_rules.py b/packages/core/src/repowise/core/analysis/dead_code/decorator_rules.pynew file mode 100644index 000000000..f4ec225c4--- /dev/null+++ b/packages/core/src/repowise/core/analysis/dead_code/decorator_rules.py@@ -0,0 +1,155 @@+"""Decorator and annotation rules: framework registration, deprecation, deliberate disuse.++A Java or Kotlin ``modifiers`` node delivers every annotation of a declaration+as one blob (``@Override @Deprecated public``), so each rule blanks quoted+arguments and splits the blob on ``@`` before reading annotation bases. Rust,+C# and C++ attributes arrive with their brackets already stripped by the parser.+"""++from __future__ import annotations++import re+from collections.abc import Iterable++from ...ingestion.decorator_names import decorator_base as _decorator_base+from .constants import (+ _DELIBERATELY_UNUSED_ANNOTATIONS,+ _FRAMEWORK_DECORATOR_SUFFIXES,+ _FRAMEWORK_DECORATORS,+ _PURE_WRAPPER_DECORATOR_ATTRS,+ _PURE_WRAPPER_DECORATOR_MODULES,+)++#: Annotation bases (``@`` and any ``(...)`` tail stripped) that mark a symbol deprecated.+_DEPRECATED_DECORATOR_BASES: frozenset[str] = frozenset(+ {+ # Python / TypeScript / Scala / Swift+ "deprecated",+ "typing.deprecated",+ "warnings.deprecated",+ # Java / Kotlin (case-sensitive annotation names)+ "Deprecated",+ "kotlin.Deprecated",+ "java.lang.Deprecated",+ # C# (inner attr text after stripping [ ])+ "Obsolete",+ "System.Obsolete",+ "System.ObsoleteAttribute",+ }+)+++#: Quoted literals, blanked before splitting on ``@`` so an argument such as+#: ``"/deprecated"`` or ``"@x"`` never becomes a token of its own.+_QUOTED_STR_RE: re.Pattern[str] = re.compile(r'"[^"]*"')+++def _declared_deliberately_unused(decorators: Iterable[str]) -> bool:+ """True when the author has written that the symbol is deliberately uncalled.++ Distinct from the framework lists, which infer a caller we cannot see.+ Read from the raw token because the base name is shared with every other+ use of the same annotation.+ """+ for blob in decorators:+ # Split per annotation: ``@Named("unused-legacy-bean")`` beside an+ # unrelated ``@SuppressWarnings`` is not the author's statement.+ for token in str(blob).split("@"):+ if not token.strip():+ continue+ base = _decorator_base(token)+ if any(+ base == name and _carries_argument(token, argument, whole)+ for name, argument, whole in _DELIBERATELY_UNUSED_ANNOTATIONS+ ):+ return True+ return False+++def _carries_argument(token: str, argument: str, whole: bool) -> bool:+ """*argument* in the annotation *token*: a substring, or one whole quoted argument."""+ if not whole:+ return argument in token+ return argument in (q[1:-1].lower() for q in _QUOTED_STR_RE.findall(token))+++def _is_framework_registered(+ decorators: list[str], meta_annotations: frozenset[str] = frozenset()+) -> bool:+ """Whether any decorator wires the symbol into a framework dispatcher.++ Shared by the export and internal passes so the rule cannot drift between+ them. Four spellings of one fact:++ * a known base name or dotted prefix (``@Component``, ``@app.route``);+ * a known trailing attribute on a locally named receiver (``@my_group.command``);+ * any other attribute of a receiver that is not a pure wrapper+ (``@nox.session``), see :func:`_is_receiver_registration`;+ * a registration verb as the final segment, dotted or bare: ``register``+ exactly or a ``register_`` stem (``@register_drainer``), never a past+ participle such as ``@registered_only``.++ A qualified annotation is also matched by its type name, and+ *meta_annotations* names the repo's own annotation classes that carry one+ of these (a Compose multipreview).+ """+ bases = _decorator_bases(decorators)+ type_names = [n for n in (b.rsplit(".", 1)[-1] for b in bases) if n[:1].isupper()]+ if any(b.startswith(_FRAMEWORK_DECORATORS) for b in (*bases, *type_names)):+ return True+ if not meta_annotations.isdisjoint(bases):+ return True+ if any(b.endswith(_FRAMEWORK_DECORATOR_SUFFIXES) for b in bases):+ return True+ if any(_is_receiver_registration(b) for b in bases):+ return True+ return any(+ segment == "register" or segment.startswith("register_")+ for segment in (b.rsplit(".", 1)[-1] for b in bases)+ )+++def _decorator_bases(decorators: Iterable[str]) -> list[str]:+ """The base name of every annotation in *decorators*, one per ``@`` token."""+ return [+ _decorator_base(token)+ for blob in decorators+ for token in _QUOTED_STR_RE.sub('""', str(blob)).split("@")+ if token.strip()+ ]+++def _is_receiver_registration(base: str) -> bool:+ """Whether a dotted decorator hands the symbol to a receiver object.++ ``@nox.session`` or ``@mcp.tool()``: any ``recv.attr`` is a registration+ unless it is a pure wrapper (functools, typing, ``@x.setter``), which+ returns the function for an ordinary caller. A capitalised last segment is+ a qualified type name (``@java.lang.Deprecated``), not a receiver method.++ Ceiling: matched on the text, so an aliased wrapper module+ (``import functools as ft``) reads as a registration, which only hides a finding.+ """+ receiver, _, attr = base.rpartition(".")+ if not receiver or not (attr[:1].islower() or attr.startswith("_")):+ return False+ if receiver.split(".", 1)[0] in _PURE_WRAPPER_DECORATOR_MODULES:+ return False+ return attr not in _PURE_WRAPPER_DECORATOR_ATTRS+++def _is_symbol_deprecated(sym_name: str, decorators: list[str]) -> bool:+ """True when the name ends ``_DEPRECATED``/``_LEGACY``/``_COMPAT`` or an annotation says deprecated."""+ if any(sym_name.endswith(s) for s in ("_DEPRECATED", "_LEGACY", "_COMPAT")):+ return True+ for raw in decorators:+ cleaned = _QUOTED_STR_RE.sub('""', raw)+ # A bare attribute (Rust/C#/C++ ``deprecated``) is one token.+ for token in cleaned.split("@"):+ token = token.strip()+ if not token:+ continue+ base = _decorator_base(token)+ if base in _DEPRECATED_DECORATOR_BASES or base.lower() == "deprecated":+ return True+ return Falsediff --git a/packages/core/src/repowise/core/analysis/dead_code/finding_helpers.py b/packages/core/src/repowise/core/analysis/dead_code/finding_helpers.pynew file mode 100644index 000000000..176d17a8d--- /dev/null+++ b/packages/core/src/repowise/core/analysis/dead_code/finding_helpers.py@@ -0,0 +1,49 @@+"""Small finding and graph-node helpers shared by the dead-code passes."""++from __future__ import annotations++from .file_reachability import CSHARP_SUFFIX+from .models import DeadCodeFindingData, DeadCodeKind+++def _is_synthetic_node(node: str) -> bool:+ """True for ``external:`` (third-party) and ``framework:`` (convention-loading) anchors.++ Neither is ever judged dead itself. The zombie-package pass still counts a+ ``framework:`` predecessor as a cross-package importer, never an ``external:`` one.+ """+ return node.startswith("external:") or node.startswith("framework:")+++# Evidence line for a finding whose ``lines`` is ``None``: the count is+# omitted rather than estimated.+_LINES_UNKNOWN = "Line count unavailable: source was not read"+++def _csharp_exports(findings: list[DeadCodeFindingData]) -> list[DeadCodeFindingData]:+ """The unused-export findings in ``.cs`` files."""+ return [+ f+ for f in findings+ if f.kind is DeadCodeKind.UNUSED_EXPORT and f.file_path.endswith(CSHARP_SUFFIX)+ ]+++def _names_by_file(findings: list[DeadCodeFindingData]) -> dict[str, set[str]]:+ """File -> the symbol names *findings* report there."""+ out: dict[str, set[str]] = {}+ for f in findings:+ out.setdefault(f.file_path, set()).add(f.symbol_name or "")+ return out+++def _symbol_span(data: dict) -> dict[str, int | None]:+ """``lines``/``start_line``/``end_line`` for a symbol finding.++ Both-or-neither: a half-known span is worse than none. Spans are+ inclusive, so a one-line symbol is 1 line; an unknown span is ``None``.+ """+ start, end = data.get("start_line") or None, data.get("end_line") or None+ if start is None or end is None or end < start:+ return {"lines": None, "start_line": None, "end_line": None}+ return {"lines": end - start + 1, "start_line": start, "end_line": end}diff --git a/packages/core/src/repowise/core/analysis/dead_code/source_prepasses.py b/packages/core/src/repowise/core/analysis/dead_code/source_prepasses.pynew file mode 100644index 000000000..3e129281b--- /dev/null+++ b/packages/core/src/repowise/core/analysis/dead_code/source_prepasses.py@@ -0,0 +1,103 @@+"""Whole-repo source scans run once when the analyzer is built."""++from __future__ import annotations++import re+from pathlib import Path++from .dynamic_markers import read_source_text+++def _find_jsx_namespace_files(+ parsed_files: dict,+ source_map: dict[str, bytes] | None = None,+) -> set[str]:+ """Repo-relative TS/TSX files that declare ``namespace JSX``.++ Types there are used implicitly by every JSX expression, never imported+ by name. A substring check is enough.+ """+ matches: set[str] = set()+ for path, pf in parsed_files.items():+ try:+ file_info = getattr(pf, "file_info", None)+ if file_info is None:+ continue+ src_path = Path(file_info.abs_path)+ if src_path.suffix not in (".ts", ".tsx", ".d.ts"):+ continue+ source = read_source_text(path, file_info.abs_path, source_map)+ if "namespace JSX" in source:+ matches.add(path)+ except Exception:+ continue+ return matches+++_BUNDLER_CONFIG_STEMS = ("vite.config", "webpack.config", "rollup.config", "rspack.config")++# Any quoted slash-containing path-ish string. Bundler configs reference+# alias targets both as ``'./src/shims/x.ts'`` and as bare segments fed to+# ``path.resolve(here, 'src/shims/x.ts')``; the parsed-files membership+# probe below keeps loose matches harmless.+_RELATIVE_PATH_STRING_RE = re.compile(r"""['"]((?:\.\.?/)?[\[email protected]]+(?:/[\[email protected]]+)+)['"]""")++_TS_PROBE_SUFFIXES = ("", ".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs")+++def _find_bundler_alias_targets(+ parsed_files: dict,+ source_map: dict[str, bytes] | None = None,+) -> set[str]:+ """Repo-relative paths referenced from bundler config files.++ A ``resolve.alias`` entry substitutes a package import with a local shim+ that only the config names. Any relative path string in a bundler config+ that resolves to an indexed file marks that file reachable.+ """+ targets: set[str] = set()+ configs = [+ (path, pf)+ for path, pf in parsed_files.items()+ if Path(path).name.startswith(_BUNDLER_CONFIG_STEMS)+ ]+ for path, pf in configs:+ try:+ file_info = getattr(pf, "file_info", None)+ if file_info is None:+ continue+ source = read_source_text(path, file_info.abs_path, source_map)+ except Exception:+ continue+ config_dir = Path(path).parent+ for match in _RELATIVE_PATH_STRING_RE.finditer(source):+ base = _posix_normpath(config_dir, match.group(1))+ for suffix in _TS_PROBE_SUFFIXES:+ candidate = base + suffix+ if candidate in parsed_files:+ targets.add(candidate)+ break+ return targets+++def _posix_normpath(config_dir: Path, raw: str) -> str:+ """Join *raw* onto *config_dir* and normalise ``.``/``..`` as POSIX."""+ import posixpath++ return posixpath.normpath(posixpath.join(config_dir.as_posix(), raw))+++def _find_ts_export_aliases(parsed_files: dict) -> dict[str, dict[str, str]]:+ """Per-file ``{local_name: exported_alias}`` maps for TS/JS alias exports.++ ``export { Local as Alias }`` publishes the symbol under the alias, so+ importers name only ``Alias``. Inverted from the parser's record of the+ clause rather than scanned again.+ """+ aliases: dict[str, dict[str, str]] = {}+ for path, pf in parsed_files.items():+ published = getattr(pf, "export_aliases", None)+ if not published:+ continue+ aliases[path] = {local: exported for exported, local in published.items()}+ return aliasesdiff --git a/packages/core/src/repowise/core/analysis/dead_code/symbol_rules.py b/packages/core/src/repowise/core/analysis/dead_code/symbol_rules.pynew file mode 100644index 000000000..4d032ad53--- /dev/null+++ b/packages/core/src/repowise/core/analysis/dead_code/symbol_rules.py@@ -0,0 +1,287 @@+"""Symbol-kind and symbol-name rules the export and internal passes share."""++from __future__ import annotations++from collections.abc import Set as AbstractSet++from .constants import _FRAMEWORK_INNER_CLASS_NAMES++# Kinds no language imports by name: always reached through an enclosing+# class or namespace (C# auto-properties land in the graph as ``variable``).+_UNIVERSAL_NON_IMPORTABLE: frozenset[str] = frozenset(+ {+ "method",+ "variable",+ "field",+ "property",+ "enum_member",+ "constant",+ "type_alias",+ "namespace",+ "module",+ "impl",+ }+)++# Kinds skipped where the graph cannot yet see interface use (constructor+# injection without ``via=type_use`` edges). Drop a language once it emits them.+_LANGUAGE_NON_IMPORTABLE: dict[str, frozenset[str]] = {+ "java": frozenset({"interface"}),+ "kotlin": frozenset({"interface"}),+ "scala": frozenset({"interface"}),+}+++# Kinds allowed as top-level imports in TS/JS (top-level `export const` literals/objects)+_TS_JS_IMPORTABLE_KINDS: frozenset[str] = frozenset({"constant", "variable"})++# Single-file-component languages: the whole file is one component, so their+# exports behave unlike an ordinary module's; see _non_importable_kinds.+_SFC_LANGUAGES: frozenset[str] = frozenset({"svelte", "vue", "astro"})++# Every kind an SFC component prop can take, plus "class" for the synthetic+# component symbol itself; see _non_importable_kinds.+_SFC_NON_IMPORTABLE_KINDS: frozenset[str] = frozenset(+ {"constant", "variable", "function", "class", "interface", "type_alias"}+)+++def _non_importable_kinds(language: str) -> frozenset[str]:+ """Per-language set of symbol kinds excluded from unused-export passes.++ An SFC's exports are its props, set by the parent as markup attributes,+ and the component itself is reached as a whole module (a tag or a+ route-level ``import()``), so neither carries a symbol-level edge.+ Ceiling: the genuinely dead named exports of an SFC module script are+ missed too; telling them from props needs attribute-to-prop binding.+ """+ if language in _SFC_LANGUAGES:+ return _UNIVERSAL_NON_IMPORTABLE | _SFC_NON_IMPORTABLE_KINDS++ extra = _LANGUAGE_NON_IMPORTABLE.get(language)+ if extra is None:+ if language in ("typescript", "javascript"):+ return _UNIVERSAL_NON_IMPORTABLE - _TS_JS_IMPORTABLE_KINDS+ return _UNIVERSAL_NON_IMPORTABLE+ return _UNIVERSAL_NON_IMPORTABLE | extra+++# The universal set plus ``interface``; prefer ``_non_importable_kinds(language)``.+_NON_IMPORTABLE_SYMBOL_KINDS: frozenset[str] = _UNIVERSAL_NON_IMPORTABLE | frozenset({"interface"})++# Type kinds that are never call targets, so "no callers" says nothing about+# them in the unused-internal pass; the unused-export pass still judges them.+_UNCALLABLE_TYPE_KINDS: frozenset[str] = frozenset(+ {+ "struct",+ "interface",+ "enum",+ "type_alias",+ "impl",+ }+)+++#: Kinds that declare a type, which Java and C# use from their own package or+#: namespace without an import.+_TYPE_DECLARATION_KINDS: frozenset[str] = frozenset(+ {"class", "interface", "struct", "enum", "record", "trait", "object"}+)++#: C/C++ kinds a type forward declaration (``class Env;``) can carry.+_CPP_TYPE_DECLARATION_KINDS: frozenset[str] = frozenset(+ {+ "class",+ "struct",+ "enum",+ }+)++# Symbol names that are language-runtime entry points or compiler-implicit+# anchors: never invoked by user-authored callers, never dead.+_ENTRY_POINT_SYMBOL_NAMES: frozenset[str] = frozenset(+ {+ "Main", # C#, Java, Kotlin, Go, Rust, Swift, Scala+ "main", # most others+ # ---- Go runtime / test conventions ------------------------------+ # ``init`` runs when the package is linked; ``go test`` calls ``TestMain``.+ "init",+ "TestMain",+ "MauiProgram", # .NET MAUI+ "Program", # C# top-level / classic console+ "Startup", # ASP.NET Core legacy+ "__module__", # synthetic per-file module anchor+ "_start", # C runtime+ # ---- Python WSGI / ASGI / app-factory conventions ---------------+ # Loaded by an app server from a dotted path (``module:create_app``).+ "create_app",+ "make_app",+ "create_application",+ "make_application",+ "application",+ "asgi_app",+ "wsgi_app",+ "asgi_application",+ "wsgi_application",+ "get_asgi_application",+ "get_wsgi_application",+ # ---- Windows DLL / COM entry points -----------------------------+ # Invoked by the Windows loader or COM runtime.+ "DllMain",+ "DllGetClassObject",+ "DllCanUnloadNow",+ "DllRegisterServer",+ "DllUnregisterServer",+ "DllGetActivationFactory",+ "DllInstall", # legacy MSI custom-action entry+ # ---- Win32 GUI / console entry points ---------------------------+ "wWinMain", # Unicode WinMain+ "WinMain", # ANSI WinMain+ "wmain", # Unicode console main+ "ServiceMain", # Win32 service entry+ # Screen savers: scrnsave.lib calls these three by name.+ "ScreenSaverProc",+ "ScreenSaverConfigureDialog",+ "RegisterDialogClasses",+ # ---- libFuzzer / Honggfuzz / AFL fuzz harness entries ------------+ # The fuzzer driver invokes these by name via dlsym.+ "LLVMFuzzerTestOneInput",+ "LLVMFuzzerInitialize",+ # ---- Windows hook / ETW callbacks invoked by macros / runtime ----+ "LowLevelKeyboardProc",+ "LowLevelMouseProc",+ "RegisterProvider", # ETW provider registration (macro-invoked)+ # ---- MSTest unit-test macro --------------------------------------+ # ``TEST_METHOD(Name)`` is captured under the macro name; the runner+ # finds it by attribute reflection.+ "TEST_METHOD",+ "TEST_CLASS",+ "TEST_METHOD_INITIALIZE",+ "TEST_METHOD_CLEANUP",+ "TEST_CLASS_INITIALIZE",+ "TEST_CLASS_CLEANUP",+ "BEGIN_TEST_METHOD_PROPERTIES",+ "END_TEST_METHOD_PROPERTIES",+ # ---- Next.js (app + pages router) convention exports -------------+ # Route exports outside the convention globs. Distinctive names only:+ # common ones (``load``, ``config``, ``metadata``) are protected by the+ # file globs in :data:`_NEVER_FLAG_PATTERNS` instead.+ "generateStaticParams",+ "generateMetadata",+ "generateViewport",+ "generateImageMetadata",+ "generateSitemaps",+ "dynamicParams",+ "fetchCache",+ "preferredRegion",+ "maxDuration",+ "getStaticProps",+ "getStaticPaths",+ "getServerSideProps",+ "getInitialProps",+ "reportWebVitals",+ # ---- Remix route module exports (distinctive names only) ---------+ "shouldRevalidate",+ "ErrorBoundary",+ "CatchBoundary",+ "HydrateFallback",+ "clientLoader",+ "clientAction",+ # ---- SvelteKit page/layout module exports (distinctive names) ----+ "trailingSlash",+ # ---- JVM (Java + Kotlin) runtime / serialization / contract anchors ----+ # Resolved through reflection, serialization or generated code.+ "serialVersionUID",+ "readObject",+ "writeObject",+ "readObjectNoData",+ "readResolve",+ "writeReplace",+ "canEqual", # Lombok-equivalent generated method+ "INSTANCE", # Kotlin object singleton field+ "Companion", # Kotlin companion-object accessor+ }+)+++# Compiler intrinsics C/C++ libraries redefine as a fallback; their only+# callers are ``#if`` directives, which the graph cannot observe.+_CPP_BUILTIN_MACROS: frozenset[str] = frozenset(+ {+ "__has_include",+ "__has_include_next",+ "__has_feature",+ "__has_extension",+ "__has_attribute",+ "__has_cpp_attribute",+ "__has_c_attribute",+ "__has_declspec_attribute",+ "__has_builtin",+ "__has_warning",+ "__builtin_expect",+ "__builtin_unreachable",+ "__builtin_assume",+ "__builtin_constant_p",+ "__is_identifier",+ "__FILE__",+ "__LINE__",+ "__DATE__",+ "__TIME__",+ "__func__",+ "__FUNCTION__",+ "__PRETTY_FUNCTION__",+ }+)+++def _is_compiler_invoked(sym: dict, sym_name: str) -> bool:+ """Symbols the compiler or linker calls, which no graph edge can show."""+ # Fallback definitions of compiler intrinsics (``__has_include``) are only+ # ever used from preprocessor directives.+ if sym.get("language") in ("cpp", "c") and sym_name in _CPP_BUILTIN_MACROS:+ return True+ # Rust proc-macro entry points are invoked by the compiler.+ if sym.get("language") == "rust":+ decorators = sym.get("decorators") or []+ if any(d.startswith("proc_macro") for d in decorators):+ return True+ # Explicit export markers (``dllexport``, ``visibility("default")``) mean+ # callers outside this binary.+ return bool(sym.get("is_exported_symbol"))+++def _is_declaration_only(sym: dict) -> bool:+ """C/C++ declarations that are not a deletable unit of their own."""+ # A prototype whose definition was found: the definition carries the+ # finding. An unmatched prototype is still reported.+ if sym.get("is_declaration") and sym.get("defined_by"):+ return True+ # A type forward declaration (``class Env;``) exists so its own file can+ # name the type, which makes that file its user.+ return bool(+ sym.get("is_declaration")+ and sym.get("language") in ("cpp", "c")+ and sym.get("kind") in _CPP_TYPE_DECLARATION_KINDS+ )+++def _is_public_top_level(sym: dict, kinds: AbstractSet[str] | None) -> bool:+ if sym.get("visibility") != "public" or sym.get("parent_name"):+ return False+ return kinds is None or sym.get("kind") in kinds+++def _nested_class_used(node_data: dict, sym: dict) -> bool:+ """Whether a nested class is one a framework reads or its module names.++ ``ingestion/python_local_refs.py`` records a nested class its module reaches+ (``Outer.Inner``, or ``Inner`` inside ``Outer``) under its ``Outer.Inner``+ name, since a bare inner name like ``ErrorModel`` repeats across classes.+ """+ parent = sym.get("parent_name")+ if not parent:+ return False+ name = sym.get("name", "")+ if name in _FRAMEWORK_INNER_CLASS_NAMES.get(sym.get("language", ""), ()):+ return True+ return f"{parent}.{name}" in (node_data.get("local_refs") or ())