Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(dead-code): stop reporting programs and the files a runner executes (#2916)

Raghav Chamadiya6e2057340e76
diff --git a/docs/layers/DEAD_CODE.md b/docs/layers/DEAD_CODE.md
index bf479dc54..646c378af 100644
--- a/docs/layers/DEAD_CODE.md
+++ b/docs/layers/DEAD_CODE.md
@@ -191,6 +191,8 @@ these, so they are never flagged rather than flagged and down-weighted.
|-------|---------|
| Entry points | Anything the graph marked `is_entry_point`, plus `__init__.py`, `__main__.py`, `conftest.py`, `manage.py`, `wsgi.py`, `asgi.py`, `setup.py`, `main.go`, `build.rs` |
| Shell scripts | `*.sh`, `*.bash`, `*.zsh`. Invoked by name from CI configs and Makefiles; static reachability is meaningless |
+| Programs | Any file whose first line is a shebang, and any Python file with a top-level `if __name__ == "__main__":` block. Nothing imports an entry point |
+| Files a runner names | A file a CI workflow (`.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`, `.buildkite/`), build or task file (`Makefile`, `Justfile`, `Dockerfile`, `noxfile.py`, `tox.ini`), manifest (`pyproject.toml`, `package.json`, `setup.cfg`) or shell script names by path. A doc that names a file only caps it at `0.40` |
| Framework routes | Next.js `page.tsx` / `layout.tsx` / `route.ts` / `middleware.ts`, SvelteKit `+page.svelte`, Nuxt `pages/*.vue`, Remix entry files, ASP.NET minimal-API `Apis/` / `Endpoints/`, Blazor and Razor code-behind |
| Test files | `*_test.go`, `*.test.ts`, `*.spec.ts`, `*_test.cc`, `*Test.java`, `**/tests/*.rs`, `src/test/java/`, MSTest and xUnit project layouts, `__tests__/`, `__mocks__/` |
| Generated code | protoc `*.pb.go` / `*.pb.cs` / `*.pb.cc`, Qt MOC/UIC/RCC, Bison/Flex, SWIG, Cython, stringer, MapStruct `*MapperImpl.java`, Dagger, AutoValue, Roslyn `*.g.cs`, Dart `*.g.dart` / `*.freezed.dart`, `**/generated/**` |
@@ -224,7 +226,9 @@ the pass.
Zombie-package detection additionally ignores directories that are not packages
at all: `.github`, `.vscode`, `.devcontainer`, `docs`, `scripts`, `assets`,
-`static`, `public`, `tests`, `benches`, `fuzz`, and their siblings.
+`static`, `public`, `tests`, `benches`, `fuzz`, and their siblings, and any
+directory whose code is only Dockerfiles, Makefiles and shell scripts, which
+are run rather than imported.
## Dynamic-import awareness
diff --git a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
index eac96324f..f7a9b0a97 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/analyzer.py
@@ -1,4 +1,4 @@
-"""DeadCodeAnalyzer — pure graph + git-metadata dead-code detection.
+"""DeadCodeAnalyzer — pure graph + git-metadata dead-code detection.
All analysis is graph traversal + SQL. No LLM calls. Must complete in
< 10 seconds.
@@ -42,6 +42,7 @@ from .constants import (
_PREPROCESSED_LANGUAGES,
_PURE_WRAPPER_DECORATOR_ATTRS,
_PURE_WRAPPER_DECORATOR_MODULES,
+ _RUN_NOT_IMPORTED_LANGUAGES,
_is_fixture_path,
never_flag_path,
)
@@ -52,7 +53,7 @@ from .dynamic_markers import (
find_dynamic_import_files,
read_source_text,
)
-from .entry_shape import clamp_entry_shaped
+from .entry_shape import clamp_entry_shaped, drop_program_entries
from .file_reachability import (
PackageFileMap,
ReachabilityRescues,
@@ -92,7 +93,7 @@ _IDENTIFIER_RE = IDENTIFIER_RE
#: omission is the bug.
#: Read budgets for the unindexed scan. These files are skipped *because* they
-#: are large — one corpus repo ships a 104 MB generated parser — so the scan is
+#: are large — one corpus repo ships a 104 MB generated parser — so the scan is
#: bounded per file and in total. Tree-sitter costs ~95 MB of RSS per MB of
#: source; this pass is a byte scan and costs far less, but the bound is what
#: keeps it from ever becoming the expensive thing.
@@ -104,7 +105,7 @@ _UNINDEXED_SCAN_TOTAL_BYTES = 32 * 1024 * 1024
# ---------------------------------------------------------------------------
#: Normalised decorator/annotation bases (after stripping leading ``@`` and
-#: any call-argument ``(…)`` tail) that signal a symbol is deprecated.
+#: 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
@@ -146,7 +147,7 @@ def _declared_deliberately_unused(decorators: Iterable[str]) -> bool:
"""
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 —
+ # 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("@"):
@@ -165,7 +166,7 @@ def _decorator_base(raw: str) -> str:
"""Return the normalised base name of a single decorator/annotation token.
Strips a leading ``@``, trims whitespace, and drops any call-argument
- ``(…)`` tail. For multi-word tokens (e.g. a Java modifier blob fragment
+ ``(…)`` tail. For multi-word tokens (e.g. a Java modifier blob fragment
``"Deprecated\n public"``) only the first whitespace-delimited word is
kept, so visibility keywords that trail the annotation name are discarded.
@@ -178,7 +179,7 @@ def _decorator_base(raw: str) -> str:
base = base[:paren].strip()
else:
# Handle trailing visibility keywords in modifier blobs:
- # "Deprecated\n public" → "Deprecated"
+ # "Deprecated\n public" → "Deprecated"
parts = base.split()
base = parts[0] if parts else base
return base
@@ -201,7 +202,7 @@ def _is_framework_registered(decorators: list[str]) -> bool:
(``@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
+ 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
@@ -268,15 +269,15 @@ def _is_symbol_deprecated(sym_name: str, decorators: list[str]) -> bool:
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
+ - 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 ``#[…]``
+ - Rust: inner attribute content stripped of ``#[…]``
(e.g. ``"deprecated"`` from ``#[deprecated]``).
- - C#: inner attribute content stripped of ``[…]``
+ - C#: inner attribute content stripped of ``[…]``
(e.g. ``"Obsolete"`` from ``[Obsolete]``).
- - C++: inner attribute content stripped of ``[[…]]``
+ - C++: inner attribute content stripped of ``[[…]]``
(e.g. ``"deprecated"`` from ``[[deprecated]]``).
"""
# 1. Name suffix
@@ -302,7 +303,7 @@ def _is_symbol_deprecated(sym_name: str, decorators: list[str]) -> bool:
# 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 /
+# 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.
@@ -323,14 +324,14 @@ _UNIVERSAL_NON_IMPORTABLE: frozenset[str] = frozenset(
# 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 —
+# 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.
+# 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.
@@ -345,11 +346,11 @@ _LANGUAGE_NON_IMPORTABLE: dict[str, frozenset[str]] = {
_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.
+# exports behave unlike an ordinary module's — see _non_importable_kinds.
_SFC_LANGUAGES: frozenset[str] = frozenset({"svelte", "vue"})
# Every kind an SFC component prop can take, plus "class" for the synthetic
-# component symbol itself — see _non_importable_kinds.
+# component symbol itself — see _non_importable_kinds.
_SFC_NON_IMPORTABLE_KINDS: frozenset[str] = frozenset(
{"constant", "variable", "function", "class", "interface", "type_alias"}
)
@@ -359,7 +360,7 @@ 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
+ 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
@@ -369,9 +370,9 @@ def _non_importable_kinds(language: str) -> frozenset[str]:
# 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
+ # "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
+ # 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.
#
@@ -396,8 +397,8 @@ _NON_IMPORTABLE_SYMBOL_KINDS: frozenset[str] = _UNIVERSAL_NON_IMPORTABLE | froze
# 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,
+# 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.
@@ -414,7 +415,7 @@ _UNCALLABLE_TYPE_KINDS: frozenset[str] = frozenset(
#: 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``.
+#: 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(
@@ -430,13 +431,13 @@ _CPP_TYPE_DECLARATION_KINDS: frozenset[str] = frozenset(
)
# Symbol names that are language-runtime entry points or compiler-implicit
-# anchors — never invoked by user-authored callers, never dead.
+# 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 —
+ # ``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",
@@ -513,7 +514,7 @@ _ENTRY_POINT_SYMBOL_NAMES: frozenset[str] = frozenset(
# 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
+ # deliberately omitted — they get file-level protection via the
# convention globs in :data:`_NEVER_FLAG_PATTERNS`.
"generateStaticParams",
"generateMetadata",
@@ -561,7 +562,7 @@ _ENTRY_POINT_SYMBOL_NAMES: frozenset[str] = frozenset(
# \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
+# graph cannot observe — so without this skip every such fallback flags
# as an unused export.
_CPP_BUILTIN_MACROS: frozenset[str] = frozenset(
{
@@ -601,7 +602,7 @@ def _find_jsx_namespace_files(
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
+ 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.
"""
@@ -615,7 +616,7 @@ def _find_jsx_namespace_files(
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
+ # Match ``namespace JSX`` and ``declare namespace JSX`` — both
# are JSX transformer integration points in practice.
if "namespace JSX" in source:
matches.add(path)
@@ -642,7 +643,7 @@ def _find_bundler_alias_targets(
"""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
+ 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.
@@ -705,8 +706,8 @@ 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
+ - ``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?",
@@ -818,7 +819,7 @@ class DeadCodeAnalyzer:
self.git_meta_map = git_meta_map or {}
# Source files ingestion could not read (currently: dropped on size).
# An unread importer is invisible to the graph, so "no importers" stops
- # meaning "unused" and starts meaning "we did not look" — which is how
+ # meaning "unused" and starts meaning "we did not look" — which is how
# one skipped entry point turned into 38 deletion-ready components at
# high confidence (#1237). ``(path, reason)`` pairs; the reason rides
# along so the evidence line can say why.
@@ -863,7 +864,7 @@ class DeadCodeAnalyzer:
self._jsx_namespace_files: set[str] = _find_jsx_namespace_files(
parsed_files or {}, source_map
)
- # Files substituted in via bundler ``resolve.alias`` config — named
+ # Files substituted in via bundler ``resolve.alias`` config — named
# by the config, never imported by path.
self._bundler_alias_targets: set[str] = _find_bundler_alias_targets(
parsed_files or {}, source_map
@@ -880,7 +881,7 @@ class DeadCodeAnalyzer:
# because the whitelist arrives per ``analyze()`` call and the map does
# not.
self._package_files: PackageFileMap | None = None
- # Cache for JSX prop-guard extraction: maps pred_file → list of
+ # Cache for JSX prop-guard extraction: maps pred_file → list of
# (parent_fn, child_component, guard_prop) triples. Populated lazily
# by _get_unsatisfied_prop_guard so each TSX/JSX file is read from
# disk and parsed by tree-sitter at most once per analysis run.
@@ -959,11 +960,12 @@ class DeadCodeAnalyzer:
# deserves.
findings = self._clamp_for_unindexed_importers(findings)
# Same position and for the same reason. This one asks the wider
- # version of the same question — not "could an unread file explain
+ # version of the same question — not "could an unread file explain
# this" but "did we look anywhere except the import graph".
findings = clamp_unverified_absence(findings, self._source_map)
findings = drop_internals_used_in_own_file(findings, self._source_map)
findings = clamp_path_mentions(findings, self._source_map)
+ findings = drop_program_entries(findings, self._source_map)
type_names = self._public_top_level_names(findings, kinds=_TYPE_DECLARATION_KINDS)
findings = drop_reference_assembly_api(findings, self._source_map, type_names)
findings = clamp_named_types(findings, self._source_map, type_names)
@@ -1002,9 +1004,9 @@ class DeadCodeAnalyzer:
# The three skips left here are *scoping*, not reachability: a test
# file is perfectly reachable, it is just not something this pass
# reports. Everything that answers "can anything get to this file"
- # — entry points, API contracts, never-flag globs, the whitelist,
+ # — entry points, API contracts, never-flag globs, the whitelist,
# barrels, bundler-alias shims and the package-granular languages
- # (Go / JVM / C-C++) — lives in the predicate, which the overview
+ # (Go / JVM / C-C++) — lives in the predicate, which the overview
# assembler calls with the same state so the two cannot disagree.
# See :mod:`file_reachability`.
if node_data.get("language", "unknown") in _DEAD_CODE_EXEMPT_LANGUAGES:
@@ -1111,7 +1113,7 @@ class DeadCodeAnalyzer:
# Exported symbols only, for the same reason stated the other way:
# an importer can only reach what a file exports, so a match on an
# internal one is a name collision rather than evidence. That is
- # not hypothetical — a published API dump lists a public `add`, and
+ # not hypothetical — a published API dump lists a public `add`, and
# every unrelated private `add` in the repo would clamp with it.
if finding.kind is DeadCodeKind.UNUSED_INTERNAL:
continue
@@ -1162,7 +1164,7 @@ class DeadCodeAnalyzer:
# environment / script / asset). These are files the never-flag allowlist
# didn't catch but that are commonly referenced outside static
# imports, so "in_degree=0" is weak evidence. Cap confidence below the
- # deletion-ready threshold and surface the factors as evidence — the
+ # deletion-ready threshold and surface the factors as evidence — the
# finding still shows up as a review candidate.
risk_factors = path_risk_factors(node)
if risk_factors:
@@ -1224,7 +1226,7 @@ class DeadCodeAnalyzer:
if self._is_old(last_commit, days=days):
return confidence
if age_days is not None and age_days < 30:
- return 0.55 # Recently created — may be WIP
+ return 0.55 # Recently created — may be WIP
return 0.7
def _member_is_used(self, sym_id: str, language: str | None) -> bool:
@@ -1237,7 +1239,7 @@ class DeadCodeAnalyzer:
**The use must come from outside the container.** A class's own methods
are predecessors of each other, so counting them would make any class
- with two methods where one calls the other rescue itself — evidence
+ with two methods where one calls the other rescue itself — evidence
about the inside of a container is not evidence that anything reaches
it.
@@ -1525,7 +1527,7 @@ class DeadCodeAnalyzer:
# Symbol-level usage signal: any incoming ``calls`` /
# ``method_implements`` / ``reads`` / ``extends`` /
# ``implements`` / ``type_use`` edge means somewhere in
- # the codebase actually uses this symbol — even if the
+ # the codebase actually uses this symbol — even if the
# file-level ``imported_names`` machinery missed it. A use of one
# member of an overload set uses the set.
if unsatisfied_guard is None and self._has_inbound_use(sym_id):
@@ -1769,7 +1771,7 @@ class DeadCodeAnalyzer:
# symbol-level edge of their own; reading only ``calls`` here
# reported all three as unused. The set is shared with the
# unused-export pass, so it also carries types this population can
- # never hold — a method or an interface is filtered out above.
+ # never hold — a method or an interface is filtered out above.
# ``new X(..)`` lands on X's constructor (``path::X::X``) when X
# declares one, and constructing a type uses it.
if self._has_inbound_use(node) or self._has_inbound_use(
@@ -1781,7 +1783,7 @@ class DeadCodeAnalyzer:
# into a sibling module and stored in a lookup dict
# (``HANDLERS = {"python": _extract_python_heritage, ...}``).
# The function is reached at runtime via dict lookup, so no
- # direct ``calls`` edge ever lands in the graph — but the
+ # direct ``calls`` edge ever lands in the graph — but the
# ``imports`` edge into its file carries the symbol name. If
# any cross-file importer pulled this symbol by name,
# something is actively referencing it; do not flag.
@@ -1792,7 +1794,7 @@ class DeadCodeAnalyzer:
continue
# Private symbols keep the standard 0.65 base confidence even if deprecated.
- # A private symbol has no external consumer by construction —
+ # A private symbol has no external consumer by construction —
# deprecated + uncalled is the strongest possible delete signal and
# must not be buried below the default min_confidence floor.
# (0.3 is reserved for unused *exports*, where an invisible consumer
@@ -1905,7 +1907,7 @@ class DeadCodeAnalyzer:
if self._name_matches_dynamic(sym_name, dynamic_patterns):
return False
- # Framework-decorator skip — same shape as unused-export. A
+ # Framework-decorator skip — same shape as unused-export. A
# private ``@PostConstruct``/``@EventListener``/``@Scheduled``
# method is invoked by the container, not by a source call.
decorators = node_data.get("decorators") or []
@@ -1917,7 +1919,7 @@ class DeadCodeAnalyzer:
"""Detect monorepo packages with no incoming inter_package edges.
``framework:`` predecessors (synthetic anchors added by
- ``framework_edges``) count as cross-package importers — TYPO3 / Django
+ ``framework_edges``) count as cross-package importers — TYPO3 / Django
/ etc. wiring is a real cross-cutting dependency. ``external:``
predecessors do not count (they represent third-party imports).
"""
@@ -1979,12 +1981,12 @@ class DeadCodeAnalyzer:
# and any other dotfile directory at the repo root.
if pkg in _NEVER_PACKAGE_DIRS or pkg.startswith("."):
return False
- # A real package contains at least one source-code file. If
- # every file under the candidate dir is config/data (YAML,
- # JSON, MD, TOML), it is not a package — it is metadata.
+ # A real package contains at least one source file something could
+ # import. Config and data (YAML, JSON, MD, TOML) is metadata, and a
+ # folder of Dockerfiles and shell scripts is run, never imported.
return any(
self.graph.nodes.get(f, {}).get("language", "unknown")
- not in _DEAD_CODE_EXEMPT_LANGUAGES
+ not in _DEAD_CODE_EXEMPT_LANGUAGES | _RUN_NOT_IMPORTED_LANGUAGES
for f in files
)
@@ -2010,7 +2012,7 @@ class DeadCodeAnalyzer:
owner_counts: dict[str, int] = {}
for f in files:
# git_meta_map values are plain dicts (see pipeline/phases/analysis.py);
- # use .get() not getattr() — getattr on a dict never finds arbitrary
+ # use .get() not getattr() — getattr on a dict never finds arbitrary
# string keys and always returns the default, silently zeroing all
# git-activity metadata on zombie-package findings.
gm = self.git_meta_map.get(f)
@@ -2051,9 +2053,9 @@ class DeadCodeAnalyzer:
return True
if never_flag_path(path):
return True
- # Workspace-driven never-flag — set by language warmups that read
+ # Workspace-driven never-flag — set by language warmups that read
# the build manifest (Gradle non-``main`` source sets, Cargo
- # ``[[example]]`` / ``[[bench]]`` targets, …). Lets each language
+ # ``[[example]]`` / ``[[bench]]`` targets, …). Lets each language
# learn conventions from its own build files instead of us
# extending the hardcoded glob list every time a repo defines a
# custom source set like ``testFixtures`` / ``javaPoet`` /
@@ -2081,7 +2083,7 @@ class DeadCodeAnalyzer:
for pred in self.graph.predecessors(file_node):
if self.graph[pred][file_node].get("edge_type") in implementor_edges:
return True
- # Symbol-level incoming edges — interfaces typically receive
+ # Symbol-level incoming edges — interfaces typically receive
# ``implements`` edges on the type symbol, not on the file.
for succ in self.graph.successors(file_node):
succ_data = self.graph.nodes.get(succ, {})
diff --git a/packages/core/src/repowise/core/analysis/dead_code/constants.py b/packages/core/src/repowise/core/analysis/dead_code/constants.py
index d0c167d54..b511e83be 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/constants.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/constants.py
@@ -1,4 +1,4 @@
-"""Static configuration for dead-code detection.
+"""Static configuration for dead-code detection.
These tuples / frozensets shape what the analyzer treats as "always
alive" (framework decorators, never-flag path globs) and where to skip
@@ -71,7 +71,7 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
"*/sitecustomize.py",
"usercustomize.py",
"*/usercustomize.py",
- # Next.js / Remix / SvelteKit framework route files — loaded by the
+ # Next.js / Remix / SvelteKit framework route files — loaded by the
# framework at runtime, never imported via module imports.
"*/page.tsx",
"*/page.ts",
@@ -102,7 +102,7 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
# ---- .NET / C# conventions --------------------------------------
# Implicit / generated / framework-loaded files that have no
# static importers by design.
- "*GlobalUsings.cs", # global usings — file-implicit, never imported by symbol
+ "*GlobalUsings.cs", # global usings — file-implicit, never imported by symbol
"*.xaml.cs", # XAML code-behind, wired by the source generator
"*.xaml",
"*.razor",
@@ -126,7 +126,7 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
# the build packs as the public surface. Nothing imports them, and every
# type they list is public API.
"*/ref/*.cs",
- "*MauiProgram.cs", # MAUI app entry — invoked by host, not imported
+ "*MauiProgram.cs", # MAUI app entry — invoked by host, not imported
"*App.xaml.cs",
"*AppShell.xaml.cs",
# Aspire / ServiceDefaults host wiring is consumed by AppHost project graph,
@@ -516,7 +516,7 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
"doc.go",
"*/docs.go",
"docs.go",
- # Mage build files (``//go:build mage``, ``package main``) — run by the
+ # Mage build files (``//go:build mage``, ``package main``) — run by the
# ``mage`` tool, excluded from normal builds, never imported.
"*/magefile.go",
"magefile.go",
@@ -574,13 +574,13 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
"*.spec.cts",
"*/__tests__/*",
"*/__mocks__/*",
- # Storybook stories — loaded by Storybook indexer via glob.
+ # Storybook stories — loaded by Storybook indexer via glob.
"*.stories.ts",
"*.stories.tsx",
"*.stories.js",
"*.stories.jsx",
"*.stories.mdx",
- # Benchmarks — invoked by vitest/tinybench/bench scripts, not imported.
+ # Benchmarks — invoked by vitest/tinybench/bench scripts, not imported.
"*.bench.ts",
"*.bench.tsx",
"*.bench.js",
@@ -632,7 +632,7 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
"proxy.ts",
"sitemap.ts",
"robots.ts",
- # Remix root/entry files — invoked by the framework runtime.
+ # Remix root/entry files — invoked by the framework runtime.
"*/entry.client.ts",
"*/entry.client.tsx",
"*/entry.server.ts",
@@ -740,7 +740,7 @@ _NEVER_FLAG_PATTERNS: tuple[str, ...] = (
_FRAMEWORK_DECORATORS: tuple[str, ...] = (
"pytest.fixture",
"pytest.mark",
- # Unqualified ``from pytest import fixture`` form — the decorator text is
+ # Unqualified ``from pytest import fixture`` form — the decorator text is
# bare ``fixture``, which the dotted prefixes above never match.
"fixture",
# Flask
@@ -766,7 +766,7 @@ _FRAMEWORK_DECORATORS: tuple[str, ...] = (
"app.websocket",
"app.middleware",
"app.exception_handler",
- # asynccontextmanager / contextmanager — used as values
+ # asynccontextmanager / contextmanager — used as values
# (e.g. FastAPI(lifespan=...)) rather than imported by name.
"asynccontextmanager",
"contextmanager",
@@ -779,10 +779,10 @@ _FRAMEWORK_DECORATORS: tuple[str, ...] = (
"app.task",
"celery.task",
"shared_task",
- # Click CLI commands — registered with the parent group/command.
+ # Click CLI commands — registered with the parent group/command.
"click.command",
"click.group",
- # Typer — same shape.
+ # Typer — same shape.
"typer.command",
"typer.callback",
# ---- JVM: Spring / Jakarta / Quarkus / Micronaut stereotypes ----
@@ -870,7 +870,7 @@ _FRAMEWORK_DECORATORS: tuple[str, ...] = (
"ArchTest",
"Container", # Testcontainers
"DynamicTest",
- "JsonCreator", # Jackson factory method — reflectively invoked
+ "JsonCreator", # Jackson factory method — reflectively invoked
"JsonProperty",
"Mojo", # Maven plugin entry
"Goal",
@@ -968,6 +968,46 @@ _PURE_WRAPPER_DECORATOR_ATTRS: frozenset[str] = frozenset(
# is a deliberate act.
_CONTAINER_USE_LANGUAGES: frozenset[str] = frozenset({"csharp"})
+# Languages whose files are run, never imported: a directory holding only these
+# (a ``docker/`` folder of Dockerfiles and an entrypoint script) is not a package
+# anything could import.
+_RUN_NOT_IMPORTED_LANGUAGES: frozenset[str] = frozenset({"dockerfile", "makefile", "shell"})
+
+# Files that run, build or ship what they name by path: CI workflows, build
+# and task files, package manifests and shell scripts. A file named there is
+# executed or packaged, which is a use, not a mention.
+_RUNNER_FILE_NAMES: frozenset[str] = frozenset(
+ {
+ "Makefile",
+ "makefile",
+ "GNUmakefile",
+ "Justfile",
+ "justfile",
+ "Dockerfile",
+ "Jenkinsfile",
+ "Procfile",
+ "noxfile.py",
+ "tox.ini",
+ "pyproject.toml",
+ "setup.cfg",
+ "package.json",
+ ".gitlab-ci.yml",
+ ".pre-commit-config.yaml",
+ }
+)
+_RUNNER_DIRS: tuple[str, ...] = (".github/workflows/", ".circleci/", ".buildkite/")
+_RUNNER_SUFFIXES: tuple[str, ...] = (".sh", ".bash", ".ps1", ".bat", ".cmd", ".dockerfile")
+
+
+def is_runner_file(path: str) -> bool:
+ """Whether *path* is a file that runs or ships the files it names."""
+ name = path.rpartition("/")[2]
+ return (
+ name in _RUNNER_FILE_NAMES
+ or name.startswith("Dockerfile")
+ or name.endswith(_RUNNER_SUFFIXES)
+ or any(f"/{d}" in f"/{path}" for d in _RUNNER_DIRS)
+ )
# Languages whose imports name a namespace, never a file, so a file no edge
# reaches is not evidence that nothing uses it: a same-namespace ``new T()``
# needs no ``using``, and one ``using`` stands for every file of the namespace.
diff --git a/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py b/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py
index 07de93d1d..bdebf2bbf 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/entry_shape.py
@@ -13,7 +13,9 @@ never imported in the first place:
* a file exporting everything such a set exports, plus more (a tool that
also exports its input type), belongs to the same set.
-Each caps the finding to the review tier; none drops it. The cap also stops
+Each caps the finding to the review tier, except a program: a file whose
+first line is a shebang or that runs under a ``__main__`` guard is an entry
+point, so :func:`drop_program_entries` removes it. The cap also stops
"no commits in 90 days" lifting such a file to the high tier, since an
untouched loaded file is not an unused one. Shape is not proof of use, so the
file stays listed as a candidate for a person to check.
@@ -78,22 +80,64 @@ def _is_main_guard(test: ast.expr) -> bool:
)
-def _script_reason(path: str, blob: bytes) -> str | None:
- """Why *blob* reads as something run rather than imported, or None."""
- if blob.startswith(b"#!"):
- return "Starts with a shebang, so it is run directly rather than imported"
+def _parse_python(path: str, blob: bytes) -> ast.Module | None:
+ """*blob* parsed, when it is Python source that parses; else None."""
if REGISTRY.from_extension(PurePosixPath(path).suffix) != "python" or path.endswith(".pyi"):
return None
try:
- return _python_script_reason(ast.parse(blob))
+ return ast.parse(blob)
except (SyntaxError, ValueError, RecursionError):
return None
-def _python_script_reason(tree: ast.Module) -> str | None:
+def _program_reason(path: str, blob: bytes) -> str | None:
+ """Why *blob* says it is a program: a shebang or a Python main guard."""
+ if blob.startswith(b"#!"):
+ return "Starts with a shebang, so it is run directly rather than imported"
+ tree = _parse_python(path, blob) if b"__main__" in blob else None
+ if tree is not None and any(
+ isinstance(stmt, ast.If) and _is_main_guard(stmt.test) for stmt in tree.body
+ ):
+ return 'Has an `if __name__ == "__main__"` block, so it is run as a script'
+ return None
+
+
+def is_program(path: str, blob: bytes) -> bool:
+ """Whether *blob* says it is a program: a shebang, or a Python main guard.
+
+ Either is the author stating the file is started by a command. Statements
+ at module level are weaker (an imported module can run code on load), so
+ they only cap a finding, through :func:`_script_reason`.
+ """
+ return _program_reason(path, blob) is not None
+
+
+def drop_program_entries(
+ findings: list[DeadCodeFindingData], source_map: dict[str, bytes]
+) -> list[DeadCodeFindingData]:
+ """Drop unreachable files that are programs: nothing imports an entry point.
+
+ "No importer" is the wrong claim for a file whose first line is a shebang
+ or that runs under ``if __name__ == "__main__"``. Returns a new list.
+ """
+ return [
+ f
+ for f in findings
+ if f.kind is not DeadCodeKind.UNREACHABLE_FILE
+ or not is_program(f.file_path, source_map.get(f.file_path, b""))
+ ]
+
+
+def _script_reason(path: str, blob: bytes) -> str | None:
+ """Why *blob* reads as something run rather than imported, or None."""
+ if reason := _program_reason(path, blob):
+ return reason
+ tree = _parse_python(path, blob)
+ return _module_statement_reason(tree) if tree is not None else None
+
+
+def _module_statement_reason(tree: ast.Module) -> str | None:
for stmt in tree.body:
- if isinstance(stmt, ast.If) and _is_main_guard(stmt.test):
- return 'Has an `if __name__ == "__main__"` block, so it is run as a script'
# A bare constant is a docstring or ``...``; anything else executes on load.
if isinstance(stmt, _LOOPS_AND_BLOCKS) or (
isinstance(stmt, ast.Expr) and not isinstance(stmt.value, ast.Constant)
diff --git a/packages/core/src/repowise/core/analysis/dead_code/name_occurrences.py b/packages/core/src/repowise/core/analysis/dead_code/name_occurrences.py
index ace627edb..c008e758b 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/name_occurrences.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/name_occurrences.py
@@ -1,4 +1,4 @@
-"""Did we actually look — the knowledge term behind a dead-code confidence.
+"""Did we actually look — the knowledge term behind a dead-code confidence.
Every other input to a dead-code confidence scores *how strong the evidence
for deadness is*. None of them asks the second question a confidence has to
@@ -6,7 +6,7 @@ answer before a user can act on it without checking: **would a use have been
visible to us at all?**
``_detect_unused_exports`` promotes a finding to the top of the scale when the
-defining file has importers — the argument being that our import graph
+defining file has importers — the argument being that our import graph
demonstrably works for this file, so the symbol's absence from every importer's
imported names means something. That argument assumes *using a symbol requires
importing it*. It holds in Python and TypeScript. It is false for:
@@ -50,17 +50,18 @@ from collections.abc import Mapping
from dataclasses import dataclass
from enum import Enum
+from .constants import is_runner_file
from .models import DeadCodeFindingData, DeadCodeKind
from .risk_factors import RISK_CAP_CONFIDENCE
-#: Identifier shape, matched over raw bytes so nothing has to be decoded — the
+#: Identifier shape, matched over raw bytes so nothing has to be decoded — the
#: scan covers every indexed file, and decoding them all would dominate it.
#: ASCII-only is deliberate: a non-ASCII identifier that fails to match can
#: only under-suppress, which is the safe direction.
IDENTIFIER_RE = re.compile(rb"[A-Za-z_][A-Za-z0-9_]{2,}")
#: Shortest name this check can answer for. :data:`IDENTIFIER_RE` needs three
-#: characters, so a two-character name matches nowhere — including on its own
+#: characters, so a two-character name matches nowhere — including on its own
#: declaration. Reading that as "the name appears nowhere" would turn the
#: strongest verdict into the least reliable one, so a name this short is
#: treated as a question we cannot ask rather than as an answer.
@@ -108,7 +109,7 @@ def occurrence_files(
One pass over the whole indexed source. The candidate names are known
before the scan starts, so the returned map only ever holds the few names
some finding actually asks about rather than every identifier in the
- repository — which is what keeps this affordable on a large tree.
+ repository — which is what keeps this affordable on a large tree.
"""
found: dict[bytes, set[str]] = {}
if not names:
@@ -128,7 +129,7 @@ def _uses_in_own_file(
) -> dict[int, _Verdict]:
"""Where each of *findings* is named in its own file outside its own span.
- Reached only for a name no other file mentions — the same-translation-unit
+ Reached only for a name no other file mentions — the same-translation-unit
shape, where a C++ helper struct used inside the very function below it is
the use the import graph cannot see. A recursive call sits *inside* the
declaration and correctly does not count; a doc comment above it sits
@@ -138,7 +139,7 @@ def _uses_in_own_file(
* The split is on ``\\n`` alone. ``bytes.splitlines`` also breaks on a bare
``\\r`` and on the form-feed family, which the parser's row counter does
- not — so a lone ``\\r`` inside a string literal (a progress-bar ``print``
+ not — so a lone ``\\r`` inside a string literal (a progress-bar ``print``
is the common one) would shift every line after it and make a symbol's
own recursive call land outside its recorded span.
* A sibling declaration's *header line* is excluded as well as the judged
@@ -184,12 +185,12 @@ def _token(name: str) -> bytes:
The one rule is that the result must be something :data:`IDENTIFIER_RE`
would actually match, because a token the scan cannot produce is absent
- from every file including the one that declares it — and reading that as
+ from every file including the one that declares it — and reading that as
"the name appears nowhere" would turn the strongest verdict into the least
reliable one. Two shapes fail it, for different reasons:
* a non-ASCII name, since ``encode(errors="ignore")`` drops characters
- rather than failing and would search for ``caf`` on behalf of ``café``,
+ rather than failing and would search for ``caf`` on behalf of ``café``,
letting an unrelated ``caf`` elsewhere read as a use;
* a name carrying a character the identifier shape does not admit, such as
the ``$`` in a JVM or JavaScript synthetic name, which the scan would
@@ -209,7 +210,7 @@ def _is_own_type_sibling(occurrence: str, declaring: str) -> bool:
A ``.d.ts`` beside ``runtime.js`` restates that module's exports as types.
It declares the same names a second time and calls none of them, so
counting it as a use makes every symbol in a generated binding module look
- alive — measured as the single largest source of lost true positives on
+ alive — measured as the single largest source of lost true positives on
this corpus.
Deliberately narrow: only the same directory and the same stem. A ``.d.ts``
@@ -304,15 +305,15 @@ def clamp_unverified_absence(
name = finding.symbol_name
# ``reason`` carries this, not only ``evidence``. The unchanged reason
# asserts "has no importers" as the ground for the finding, which is
- # the very inference this check has just declined to make — and it is
+ # the very inference this check has just declined to make — and it is
# the field every surface renders, where the evidence list reaches
# only the JSON ones.
if verdict.answer is _Answer.USED:
finding.reason = f"'{name}' is not imported, but is named elsewhere in the repo"
detail = f"is written at {verdict.used_at}"
else:
- # Both remaining answers mean the same thing to a reader — we did
- # not establish an absence — so they share a reason and differ only
+ # Both remaining answers mean the same thing to a reader — we did
+ # not establish an absence — so they share a reason and differ only
# in the evidence line, which is where the distinction is useful.
finding.reason = f"'{name}' is not imported, and its use could not be verified"
detail = (
@@ -431,8 +432,8 @@ def _token_spellings(token: str) -> list[str]:
start = slash + 1
-def _first_file_naming(targets: set[str], source_map: dict[str, bytes]) -> dict[str, str]:
- """For each of *targets* another file names by path, the first such file."""
+def _files_naming(targets: set[str], source_map: dict[str, bytes]) -> dict[str, list[str]]:
+ """For each of *targets* other files name by path, those files in path order."""
wanted: dict[str, set[str]] = {}
for target in targets:
for key in _path_keys(target):
@@ -441,15 +442,22 @@ def _first_file_naming(targets: set[str], source_map: dict[str, bytes]) -> dict[
# every path-shaped token in a repository names none of the candidates.
tails = {key.rpartition("/")[2] for key in wanted}
- named_in: dict[str, str] = {}
+ named_in: dict[str, list[str]] = {}
for path, blob in sorted(source_map.items()):
- for match in _PATH_TOKEN_RE.finditer(blob):
- for target in _targets_named_by(match.group().decode("ascii"), wanted, tails):
- if target != path:
- named_in.setdefault(target, path)
+ for target in _targets_in(blob, wanted, tails) - {path}:
+ named_in.setdefault(target, []).append(path)
return named_in
+def _targets_in(blob: bytes, wanted: dict[str, set[str]], tails: set[str]) -> set[str]:
+ """The targets any path-shaped token of *blob* names."""
+ return {
+ target
+ for match in _PATH_TOKEN_RE.finditer(blob)
+ for target in _targets_named_by(match.group().decode("ascii"), wanted, tails)
+ }
+
+
def _targets_named_by(token: str, wanted: dict[str, set[str]], tails: set[str]) -> set[str]:
"""The targets one path-shaped *token* names, through any of its spellings."""
tail = token.strip(".").rpartition("/")[2]
@@ -461,41 +469,43 @@ def _targets_named_by(token: str, wanted: dict[str, set[str]], tails: set[str])
def clamp_path_mentions(
findings: list[DeadCodeFindingData], source_map: dict[str, bytes]
) -> list[DeadCodeFindingData]:
- """Cap unreachable files that another file names by path.
+ """Cap unreachable files another file names by path; drop those a runner names.
"Nothing imports this" is not "nothing uses this". A build script reads a
template by path, a JSON manifest lists example files, a doc links a
script, ``package.json`` names a bin: each loads the file without an import
edge, and such a file reported as deletion-ready breaks whatever reads it.
- A mention is not proof of use either, so the finding is capped to the
- review tier rather than dropped.
+ A mention in a doc is not proof of use, so that finding is capped to the
+ review tier. A CI workflow, build file, manifest or shell script runs or
+ ships what it names (``python scripts/emit_sample_dsl.py`` in a workflow),
+ so a file one of those names is dropped.
One scan over the indexed source. That already holds JSON, YAML, Markdown,
shell and ``package.json``: each has a language spec, so ingestion reads
- it. A file's mention of itself is not a use. Mutates in place and returns
- the same list; never raises a confidence and never removes a finding.
+ it. A file's mention of itself is not a use. Returns a new list; never
+ raises a confidence.
"""
- if not source_map:
- return findings
- candidates = [
- f
- for f in findings
- if f.kind is DeadCodeKind.UNREACHABLE_FILE and f.confidence > RISK_CAP_CONFIDENCE
- ]
- if not candidates:
+ unreachable = [f for f in findings if f.kind is DeadCodeKind.UNREACHABLE_FILE]
+ if not source_map or not unreachable:
return findings
- named_in = _first_file_naming({f.file_path for f in candidates}, source_map)
- for finding in candidates:
- where = named_in.get(finding.file_path)
- if where is None:
- continue
- finding.confidence = min(finding.confidence, RISK_CAP_CONFIDENCE)
- finding.safe_to_delete = False
- finding.evidence.append(f"Named by path in {where}, which may load it without an import")
- return findings
-
-
+ named_in = _files_naming({f.file_path for f in unreachable}, source_map)
+ run = {
+ id(f) for f in unreachable if any(map(is_runner_file, named_in.get(f.file_path, ())))
+ }
+ for finding in unreachable:
+ if id(finding) not in run:
+ _cap_named_by_path(finding, named_in.get(finding.file_path))
+ return [f for f in findings if id(f) not in run]
+
+
+def _cap_named_by_path(finding: DeadCodeFindingData, namers: list[str] | None) -> None:
+ """Cap *finding* to the review tier when a file names it by path."""
+ if not namers or finding.confidence <= RISK_CAP_CONFIDENCE:
+ return
+ finding.confidence = RISK_CAP_CONFIDENCE
+ finding.safe_to_delete = False
+ finding.evidence.append(f"Named by path in {namers[0]}, which may load it without an import")
def _is_reference_assembly(path: str) -> bool:
"""A .NET reference-assembly source: ``src/libraries/X/ref/X.cs``."""
return path.endswith(".cs") and "/ref/" in f"/{path}"
diff --git a/tests/unit/dead_code/test_entry_shape.py b/tests/unit/dead_code/test_entry_shape.py
index e61336479..468d493f5 100644
--- a/tests/unit/dead_code/test_entry_shape.py
+++ b/tests/unit/dead_code/test_entry_shape.py
@@ -184,7 +184,7 @@ def test_an_already_capped_sibling_still_counts_but_is_not_touched_again():
# --- through the analyzer --------------------------------------------------------
-def test_the_analyzer_applies_the_cap_and_keeps_the_finding():
+def test_the_analyzer_drops_a_program_and_keeps_a_library_module():
g = _build_graph(
nodes={
"pkg/main.py": {"is_entry_point": True, "symbols": []},
@@ -209,7 +209,8 @@ def test_the_analyzer_applies_the_cap_and_keeps_the_finding():
)
by_path = {f.file_path: f for f in report.findings if f.kind == DeadCodeKind.UNREACHABLE_FILE}
assert by_path["pkg/old.py"].confidence == 1.0
- assert by_path["pkg/run_once.py"].confidence == RISK_CAP_CONFIDENCE
+ # A main guard makes it a program: nothing imports an entry point.
+ assert "pkg/run_once.py" not in by_path
# --- members of a loaded set that export more --------------------------------------
diff --git a/tests/unit/dead_code/test_path_mentions.py b/tests/unit/dead_code/test_path_mentions.py
index d264e077b..31dbfa3b8 100644
--- a/tests/unit/dead_code/test_path_mentions.py
+++ b/tests/unit/dead_code/test_path_mentions.py
@@ -2,8 +2,9 @@
A build script that reads a file by path, or a JSON manifest that lists it,
uses the file without an import edge. The pass caps such a finding to the
-review tier; it never matches on a bare stem, and a file nobody names keeps
-its confidence.
+review tier, and drops it when a CI workflow, build file, manifest or shell
+script names it; it never matches on a bare stem, and a file nobody names
+keeps its confidence.
"""
from __future__ import annotations
@@ -35,10 +36,15 @@ def _file(path: str, confidence: float = 1.0) -> DeadCodeFindingData:
def _clamp(path: str, source: dict[str, str]) -> DeadCodeFindingData:
finding = _file(path)
- clamp_path_mentions([finding], {p: s.encode() for p, s in source.items()})
+ kept = clamp_path_mentions([finding], {p: s.encode() for p, s in source.items()})
+ assert kept == [finding], "the finding was dropped"
return finding
+def _dropped(path: str, source: dict[str, str]) -> bool:
+ return clamp_path_mentions([_file(path)], {p: s.encode() for p, s in source.items()}) == []
+
+
def test_a_json_manifest_listing_example_files_caps_them():
manifest = '{"examples": ["examples/basic/run.py", "./examples/advanced/run.py"]}'
source = {"examples.json": manifest, "examples/basic/run.py": "print(1)\n"}
@@ -49,10 +55,14 @@ def test_a_json_manifest_listing_example_files_caps_them():
assert "examples.json" in finding.evidence[-1]
-def test_a_build_script_reading_a_python_file_by_path_caps_it():
+def test_a_build_script_running_a_python_file_by_path_drops_it():
script = "#!/bin/sh\npython tools/codegen/emit.py > out.txt\n"
- finding = _clamp("tools/codegen/emit.py", {"scripts/build.sh": script})
- assert finding.confidence == RISK_CAP_CONFIDENCE
+ assert _dropped("tools/codegen/emit.py", {"scripts/build.sh": script})
+
+
+def test_a_ci_workflow_running_a_script_drops_it():
+ workflow = "steps:\n - run: python scripts/emit_sample_dsl.py --check\n"
+ assert _dropped("scripts/emit_sample_dsl.py", {".github/workflows/ci.yml": workflow})
def test_dir_and_basename_with_extension_is_enough():
@@ -62,8 +72,7 @@ def test_dir_and_basename_with_extension_is_enough():
def test_a_build_output_path_names_its_source():
pkg = '{"main": "src/cli/index.js"}'
- finding = _clamp("src/cli/index.ts", {"package.json": pkg})
- assert finding.confidence == RISK_CAP_CONFIDENCE
+ assert _dropped("src/cli/index.ts", {"package.json": pkg})
def test_a_bare_stem_never_matches():
diff --git a/tests/unit/dead_code/test_script_entry_points.py b/tests/unit/dead_code/test_script_entry_points.py
new file mode 100644
index 000000000..77df57a45
--- /dev/null
+++ b/tests/unit/dead_code/test_script_entry_points.py
@@ -0,0 +1,69 @@
+"""Programs and the files a runner names are entry points, not dead files.
+
+From elasticsearch (``distribution/src/bin/elasticsearch``, a shebang
+launcher) and repowise itself (``scripts/emit_sample_dsl.py``, run only from
+``.github/workflows/ci.yml``; ``docker/``, a folder of Dockerfiles reported as
+a zombie package).
+"""
+
+from __future__ import annotations
+
+from repowise.core.analysis.dead_code import DeadCodeAnalyzer, DeadCodeKind
+from tests.unit.dead_code._helpers import _build_graph, _old_date
+
+_OLD = {"commit_count_90d": 0, "last_commit_at": _old_date(400)}
+
+
+def _unreachable(nodes: dict, source: dict[str, bytes]) -> set[str]:
+ graph = _build_graph(nodes)
+ report = DeadCodeAnalyzer(
+ graph, git_meta_map={path: dict(_OLD) for path in nodes}, source_map=source
+ ).analyze({"detect_unused_exports": False, "detect_zombie_packages": False})
+ return {f.file_path for f in report.findings if f.kind is DeadCodeKind.UNREACHABLE_FILE}
+
+
+def test_a_shebang_launcher_is_not_unreachable():
+ path = "distribution/src/bin/elasticsearch"
+ files = _unreachable(
+ {path: {"language": "shell", "symbols": []}, "lib/old.py": {"symbols": []}},
+ {path: b"#!/bin/bash\nexec java -cp lib org.Main\n", "lib/old.py": b"X = 1\n"},
+ )
+ assert files == {"lib/old.py"}
+
+
+def test_a_python_main_guard_is_not_unreachable():
+ body = b"def main():\n pass\n\nif __name__ == '__main__':\n main()\n"
+ files = _unreachable({"tools/gen.py": {"symbols": []}}, {"tools/gen.py": body})
+ assert files == set()
+
+
+def test_a_script_a_ci_workflow_runs_is_not_unreachable():
+ workflow = b"jobs:\n check:\n steps:\n - run: python scripts/emit_sample_dsl.py\n"
+ files = _unreachable(
+ {"scripts/emit_sample_dsl.py": {"symbols": []}, ".github/workflows/ci.yml": {"language": "yaml"}},
+ {"scripts/emit_sample_dsl.py": b"print('dsl')\n", ".github/workflows/ci.yml": workflow},
+ )
+ assert files == set()
+
+
+def test_a_file_only_a_doc_names_stays_listed():
+ files = _unreachable(
+ {"pkg/legacy.py": {"symbols": []}, "docs/notes.md": {"language": "markdown"}},
+ {"pkg/legacy.py": b"X = 1\n", "docs/notes.md": b"See pkg/legacy.py.\n"},
+ )
+ assert files == {"pkg/legacy.py"}
+
+
+def test_a_folder_of_dockerfiles_is_not_a_zombie_package():
+ graph = _build_graph(
+ {
+ "docker/Dockerfile": {"language": "dockerfile"},
+ "docker/entrypoint.sh": {"language": "shell"},
+ "pkg/a.py": {"symbols": []},
+ "lib/b.py": {"symbols": []},
+ }
+ )
+ report = DeadCodeAnalyzer(graph).analyze({"min_confidence": 0.0})
+ zombies = {f.file_path for f in report.findings if f.kind is DeadCodeKind.ZOMBIE_PACKAGE}
+ assert "docker" not in zombies
+ assert {"pkg", "lib"} <= zombies