scip-cli 2.1.0__tar.gz → 2.2.1__tar.gz

{scip_cli-2.1.0 → scip_cli-2.2.1}/.cursor/rules/agent.mdc

@@ -31,7 +31,7 @@ Node.js + `npx` required for integration tests (`scip-typescript`). Optional: `S
 | Task | Command |
 |------|---------|
 | Full suite | `pytest` |
-| E2e loop | `pytest tests/test_e2e.py` |
+| E2e loop | `pytest tests/test_e2e.py tests/test_e2e_analyze_patterns.py` |
 | Lint / format | `ruff check .` / `ruff format .` |
 
 Pre-commit: ruff + ruff-format + full pytest. E2e before commit on command changes.
@@ -69,9 +69,10 @@ When you or a review subagent finds a repo issue — bug, dead code, cycle, risk
 
 If **yes** (the signal is in `documents`, `mentions`, `global_symbols`, `defn_enclosing_ranges`):
 
-1. **Extend `analyze` first** — new or tuned SQL check in `scip_cli/analyze/`, priority in `sections.py`, tests in `tests/test_analyze.py` + `analyze_db.py`.
-2. **Dogfood** — `reindex` → confirm the issue appears (or the false positive is filtered).
-3. **Then** fix the production code (or document a known blind spot).
+1. **Red on the fixture** — minimal generic repro + e2e test (see **TDD → External project feedback**). Do not name real customer repos in tests.
+2. **Extend `analyze`** — new or tuned SQL/heuristic in `scip_cli/analyze/`, priority in `sections.py`; unit tests only for graph/SQL plumbing (`analyze_db.py`, `test_analyze_graph.py`).
+3. **Dogfood** — `reindex` on this repo (or re-run fixture e2e) → confirm signal appears or false positive is filtered.
+4. **Then** fix production code in the other repo (or document a known blind spot).
 
 Only skip step 1 when the issue is **outside the index** (runtime, CLI UX, docs drift, git, env, concurrency, test harness).
 
@@ -137,14 +138,36 @@ The e2e fixture and this repo's own index are **small** — every query looks fa
 
 ## TDD
 
-1. **Red** — `tests/test_e2e.py` + `fixture_catalog` constants.
-2. **Green** — `scip_cli/commands/*.py`.
-3. **Refactor** — unit tests for pure helpers only.
+### Default: extend the shared fixture
 
-- **E2e** (`cli` fixture): in-process `main()`, TS project indexed once per session — default for behavior.
-- **Unit**: `:memory:` SQLite, `tests/analyze_db.py`, merge/index prune tests.
+**One indexed TS project** — `tests/fixtures/sample-project/` — indexed once per session via `indexed_fixture` (`conftest.py`). Stable names live in `tests/fixture_catalog.py`.
+
+1. **Red** — add a **minimal** `.ts` file (or tweak an existing one) that reproduces the SCIP shape; assert in `tests/test_e2e.py` or `tests/test_e2e_analyze_patterns.py` using `cli` / `open_index_db` + analyze helpers.
+2. **Green** — fix `scip_cli/` (commands, `analyze/*`, `queries.py`, …).
+3. **Refactor** — only if a pure helper deserves isolation.
+
+- **E2e** (`cli` / `indexed_fixture`): in-process `main()` or direct Python API on the **real** index — default for behavior.
 - **No subprocess** for CLI tests; no `reindex` in e2e (mutates `~/.cache/scip-cli`).
-- New symbols: extend `tests/fixtures/sample-project/` + `fixture_catalog.py`.
+- New symbols/paths: fixture file + `fixture_catalog.py` constant — never hardcode paths in test bodies.
+
+### External project feedback → fixture (mandatory workflow)
+
+When dogfooding **another repo** surfaces a bug or false positive (analyze noise, dead-export mistake, cycle, stale type, refs mismatch):
+
+1. **Capture the pattern, not the project** — note the SCIP shape (module `/`, export alias `foo0:`, lazy import, `Props#`, barrel cycle, …). Do **not** copy real repo names, paths, or filenames into tests or docs.
+2. **Red on the fixture** — smallest TS repro under `tests/fixtures/sample-project/` with generic names (`LazyPanel`, `evictItem`, `OrphanWidget`, …). E2e test proves the bug against **real `scip-typescript`** output.
+3. **Green** — fix analyze heuristics / SQL / CLI; dogfood on this repo if applicable.
+4. **Verify** — `pytest tests/test_e2e_analyze_patterns.py` (or full `pytest`); only then trim redundant tests.
+
+**Prefer fixture e2e over fake SQLite graphs.** `tests/analyze_db.py` (`AnalyzeDbBuilder`, `:memory:`) is for SQL/dashboard **plumbing** and graph primitives (`test_analyze_graph.py`, `mini_codebase_db`) — not for reproducing production SCIP symbol shapes. Hand-built symbols often diverge from scip-typescript (path format, `0:` aliases, module rows) and can pass while production still breaks.
+
+| Use fixture e2e | Use `analyze_db` unit |
+|-----------------|----------------------|
+| False positives / analyze checks from real projects | Tarjan, edge-type SQL, `run_all` section wiring |
+| Any behavior that depends on indexer symbol strings | Noise filters with one or two synthetic rows |
+| CLI commands (`refs`, `search`, `analyze` output) | Merge/index prune tests |
+
+If both layers help during development, **keep both until e2e passes**, then delete duplicate in-memory repros — fixture is the source of truth.
 
 ## Codebase map (contributors)
 

{scip_cli-2.1.0 → scip_cli-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 2.1.0
+Version: 2.2.1
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -255,7 +255,7 @@ Use `--priority high` for a quick gate; `--priority high,medium` adds context. F
 | **Cycles** | Import/mention cycles between production files — break the edge or extract shared code |
 | **Unreferenced** | No usage in the index at all — delete |
 | **Dead exports** | No external refs — delete or `_` prefix |
-| **Stale types** | Classes/types with ≤1 external consumer — merge, inline, or document why they stay |
+| **Stale types** | Classes/types with no external consumer in the index — verify in-file or type-only use before removing |
 | **Same-file only** | Used only inside defining file — rename to `_` |
 | **Test-only consumers** | Cross-file refs are all from tests — promote to e2e or accept as internal |
 

{scip_cli-2.1.0 → scip_cli-2.2.1}/README.md

@@ -235,7 +235,7 @@ Use `--priority high` for a quick gate; `--priority high,medium` adds context. F
 | **Cycles** | Import/mention cycles between production files — break the edge or extract shared code |
 | **Unreferenced** | No usage in the index at all — delete |
 | **Dead exports** | No external refs — delete or `_` prefix |
-| **Stale types** | Classes/types with ≤1 external consumer — merge, inline, or document why they stay |
+| **Stale types** | Classes/types with no external consumer in the index — verify in-file or type-only use before removing |
 | **Same-file only** | Used only inside defining file — rename to `_` |
 | **Test-only consumers** | Cross-file refs are all from tests — promote to e2e or accept as internal |
 

{scip_cli-2.1.0 → scip_cli-2.2.1}/scip_cli/SKILL.md

@@ -128,10 +128,12 @@ analyze [--limit N] [--path PATH] [--include-tests] [target]
 
 Sections are ordered **high → medium → low**. `[high]` cycles, unreferenced, dead exports, stale types; `[medium]` same-file-only, change surface (file); `[low]` test-only consumers (noisy on Python), coupling, bottlenecks, hotspots.
 
+`--limit` caps **result rows across the whole run** (default 20); remaining checks are skipped once the cap is reached. `(none)` sections and section headers do not count.
+
 `--priority high` or `--priority high,medium` (also `1`/`2`/`3`) skips lower tiers.
 
 Directory detection uses the filesystem when present, otherwise an indexed path prefix. `--path` narrows ambiguous file/symbol resolution only (not directory scope — pass the dir as `target`).
 
 **Dogfood loop:** `reindex` → `analyze --limit 25` → `analyze scip_cli` or `analyze scip_cli/queries.py` on suspects. Skips test paths in project-wide and directory runs (`tests/`, `*.test.*`, `*.spec.*`); `--include-tests` to include them. File-target analyze always includes that file.
 
-**Easy pickings:** **Cycles** and **dead exports** (production paths) — cross-file cleanup. **Stale types** — low-use classes. Ignore `analyze/*` section helpers in dead exports. “Dead” = no refs from *other* files in the index, not `vulture`.
+**Easy pickings:** **Cycles** and **dead exports** (production paths) — cross-file cleanup. **Stale types** — types with no external refs in the index. Ignore `analyze/*` section helpers in dead exports. “Dead” = no refs from *other* files in the index, not `vulture`.

{scip_cli-2.1.0 → scip_cli-2.2.1}/scip_cli/__init__.py

@@ -1,3 +1,3 @@
 """scip-cli: Fast code intelligence via SCIP indexes."""
 
-__version__ = "2.1.0"
+__version__ = "2.2.1"

{scip_cli-2.1.0 → scip_cli-2.2.1}/scip_cli/__main__.py

@@ -115,7 +115,7 @@ def main():
         help="Omit for project-wide; directory for scoped project + per-file; file or symbol for focused checks",
     )
     add_path_argument(analyze_parser)
-    add_limit_argument(analyze_parser, default=20, help_suffix="rows per section")
+    add_limit_argument(analyze_parser, default=20, help_suffix="result rows total")
     analyze_parser.add_argument(
         "--include-tests",
         action="store_true",

{scip_cli-2.1.0 → scip_cli-2.2.1}/scip_cli/analyze/common.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 
 from ..sql import debug_execute
-from ..symbols import extract_leaf_name
+from ..symbols import extract_leaf_name, is_module_symbol
 
 DEFAULT_LIMIT = 20
 
@@ -25,8 +25,14 @@ def fetch_one(db, sql: str, params=()):
 
 
 def short_name(symbol: str) -> str:
+    if is_module_symbol(symbol):
+        return "(module)"
     leaf = extract_leaf_name(symbol)
-    return leaf or symbol.split("/")[-1][:60]
+    if leaf:
+        return leaf
+    if symbol.endswith("/"):
+        return "(module)"
+    return symbol.split("/")[-1][:60]
 
 
 def is_test_path(relative_path: str) -> bool:
@@ -53,10 +59,19 @@ def is_cli_entrypoint(relative_path: str, symbol: str) -> bool:
     return path == "scip_cli/__main__.py" or "/commands/" in path
 
 
+def is_generated_analyze_path(relative_path: str) -> bool:
+    p = relative_path.replace("\\", "/")
+    if "/types/prisma/" in p:
+        return True
+    return p.endswith("types/resolvers.ts")
+
+
 def analyze_noise(relative_path: str, symbol: str, *, include_tests: bool = False) -> bool:
     """True for rows that clutter analyze dashboards (test paths, module-private helpers)."""
     if not include_tests and is_test_path(relative_path):
         return True
+    if is_generated_analyze_path(relative_path):
+        return True
     if short_name(symbol).startswith("_"):
         return True
     if is_cli_entrypoint(relative_path, symbol):
@@ -80,12 +95,20 @@ def is_analyze_dashboard_export(relative_path: str, symbol: str) -> bool:
     return "()." in symbol or name.endswith(")")
 
 
+def is_component_props_type(symbol: str) -> bool:
+    """React-style Props interfaces — rarely referenced outside the component file."""
+    name = short_name(symbol)
+    return bool(name and name.endswith("Props") and "#" in symbol.split("/")[-1])
+
+
 def stale_type_noise(relative_path: str, symbol: str, consumers: int) -> bool:
     """Dataclass-style types with no SCIP consumers (typing-only)."""
+    if is_component_props_type(symbol):
+        return True
     if consumers > 0:
         return False
     name = short_name(symbol)
-    if not name or not name[0].isupper():
+    if not name or name == "(module)" or not name[0].isupper():
         return False
     path = relative_path.replace("\\", "/")
     return path.endswith(("config.py", "scope.py", "analyze/targets.py"))
@@ -104,7 +127,7 @@ def cycle_path_noise(cycle_line: str, *, include_tests: bool = False) -> bool:
     return any(is_test_path(part.strip()) for part in parts if part.strip())
 
 
-def section(title: str, lines: list[str]) -> tuple[str, list[str]]:
+def section(title: str, lines: list[str], *, preface: str | None = None) -> tuple[str, list[str], str | None]:
     if not lines:
-        return title, ["(none)"]
-    return title, lines
+        return title, ["(none)"], None
+    return title, lines, preface

{scip_cli-2.1.0 → scip_cli-2.2.1}/scip_cli/analyze/file.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from .common import DEFAULT_LIMIT, SYM_DEF_JOIN, analyze_noise, fetch_all, short_name
+from .live import LiveIndex, file_has_scip_importers, has_same_file_reference_usage
 from .sections import Check, Priority, run_checks
 from .symbol import symbol_pressure
 
@@ -82,10 +83,11 @@ def file_consumers(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[s
 
 
 def unreferenced_in_file(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str]:
+    live = LiveIndex(db)
     rows = fetch_all(
         db,
         """
-        SELECT gs.symbol, der.start_line, der.end_line
+        SELECT gs.symbol, der.start_line, der.end_line, def_d.id
         FROM global_symbols gs
         JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
         JOIN documents def_d ON der.document_id = def_d.id
@@ -104,18 +106,22 @@ def unreferenced_in_file(db, relative_path: str, limit: int = DEFAULT_LIMIT) ->
         """,
         (relative_path, limit),
     )
-    return [
-        f"{short_name(symbol)}  {start + 1}:{end + 1}"
-        for symbol, start, end in rows
-        if not analyze_noise(relative_path, symbol, include_tests=True)
-    ]
+    lines = []
+    for symbol, start, end, def_doc_id in rows:
+        if analyze_noise(relative_path, symbol, include_tests=True):
+            continue
+        if live.dead_export_noise(symbol, def_doc_id):
+            continue
+        lines.append(f"{short_name(symbol)}  {start + 1}:{end + 1}")
+    return lines
 
 
 def same_file_only_in_file(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str]:
+    live = LiveIndex(db)
     rows = fetch_all(
         db,
         """
-        SELECT gs.symbol, der.start_line, der.end_line
+        SELECT gs.symbol, der.start_line, der.end_line, def_d.id
         FROM global_symbols gs
         JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
         JOIN documents def_d ON der.document_id = def_d.id
@@ -135,18 +141,24 @@ def same_file_only_in_file(db, relative_path: str, limit: int = DEFAULT_LIMIT) -
         """,
         (relative_path, limit),
     )
-    return [
-        f"{short_name(symbol)}  {start + 1}:{end + 1}"
-        for symbol, start, end in rows
-        if not analyze_noise(relative_path, symbol, include_tests=True)
-    ]
+    lines = []
+    for symbol, start, end, def_doc_id in rows:
+        if analyze_noise(relative_path, symbol, include_tests=True):
+            continue
+        if live.same_file_export_noise(symbol, def_doc_id):
+            continue
+        if not file_has_scip_importers(db, relative_path, live=live, def_doc_id=def_doc_id):
+            continue
+        lines.append(f"{short_name(symbol)}  {start + 1}:{end + 1}")
+    return lines
 
 
 def dead_in_file(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str]:
+    live = LiveIndex(db)
     rows = fetch_all(
         db,
         """
-        SELECT gs.symbol, der.start_line, der.end_line
+        SELECT gs.id, gs.symbol, der.start_line, der.end_line, def_d.id
         FROM global_symbols gs
         JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
         JOIN documents def_d ON der.document_id = def_d.id
@@ -164,11 +176,16 @@ def dead_in_file(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str
         """,
         (relative_path, limit),
     )
-    return [
-        f"{short_name(symbol)}  {start + 1}:{end + 1}"
-        for symbol, start, end in rows
-        if not analyze_noise(relative_path, symbol, include_tests=True)
-    ]
+    lines = []
+    for sym_id, symbol, start, end, def_doc_id in rows:
+        if analyze_noise(relative_path, symbol, include_tests=True):
+            continue
+        if has_same_file_reference_usage(db, sym_id, def_doc_id):
+            continue
+        if live.dead_export_noise(symbol, def_doc_id):
+            continue
+        lines.append(f"{short_name(symbol)}  {start + 1}:{end + 1}")
+    return lines
 
 
 def imports_summary(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str]:
@@ -240,6 +257,16 @@ def coupling_for(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str
     return [f"{other}  shared={shared}" for other, shared in rows]
 
 
+def count_file_importers(db, relative_path: str) -> int:
+    from ..queries import get_file_symbols, get_importer_paths
+
+    symbols = get_file_symbols(db, relative_path)
+    if not symbols:
+        return 0
+    symbol_ids = [row[0] for row in symbols]
+    return len(get_importer_paths(db, symbol_ids, relative_path))
+
+
 def top_symbol_pressure(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str]:
     """Pressure metrics for the most-consumed exports in a file."""
     cap = min(5, limit)
@@ -321,8 +348,10 @@ def _run_file_checks(
     db,
     limit: int,
     priorities,
-) -> list[tuple[str, list[str]]]:
-    return run_checks(checks, db, limit, priorities)
+    *,
+    budget=None,
+) -> list[tuple[str, list[str], str | None]]:
+    return run_checks(checks, db, limit, priorities, budget=budget)
 
 
 def run_all(
@@ -330,12 +359,14 @@ def run_all(
     relative_path: str,
     limit: int = DEFAULT_LIMIT,
     priorities=None,
-) -> list[tuple[str, list[str]]]:
+    budget=None,
+) -> list[tuple[str, list[str], str | None]]:
     return _run_file_checks(
         _file_checks(relative_path, include_top_symbols=True),
         db,
         limit,
         priorities,
+        budget=budget,
     )
 
 
@@ -344,11 +375,13 @@ def run_all_sections_only(
     relative_path: str,
     limit: int = DEFAULT_LIMIT,
     priorities=None,
-) -> list[tuple[str, list[str]]]:
+    budget=None,
+) -> list[tuple[str, list[str], str | None]]:
     """Per-file sections without top-symbols (directory batch)."""
     return _run_file_checks(
         _file_checks(relative_path, include_top_symbols=False),
         db,
         limit,
         priorities,
+        budget=budget,
     )

{scip_cli-2.1.0 → scip_cli-2.2.1}/scip_cli/analyze/graph.py

@@ -4,16 +4,19 @@ from __future__ import annotations
 
 from collections import defaultdict
 
+from ..symbols import cycle_runtime_edge_sql
 from .common import fetch_all
 
-FILE_EDGES_SQL = """
+FILE_EDGES_SQL = f"""
     SELECT DISTINCT d1.relative_path AS from_file, d2.relative_path AS to_file
     FROM mentions m
     JOIN chunks c ON m.chunk_id = c.id
     JOIN documents d1 ON c.document_id = d1.id
     JOIN defn_enclosing_ranges der ON m.symbol_id = der.symbol_id
     JOIN documents d2 ON der.document_id = d2.id
+    JOIN global_symbols gs ON gs.id = der.symbol_id
     WHERE d1.id != d2.id AND m.role != 1
+      AND {cycle_runtime_edge_sql()}
 """
 
 

scip_cli-2.2.1/scip_cli/analyze/live.py

@@ -0,0 +1,168 @@
+"""Heuristics for SCIP symbols that look dead but are live via module or export-alias indirection."""
+
+from __future__ import annotations
+
+import re
+
+from ..sql import debug_execute
+from ..symbols import extract_leaf_name, is_module_symbol
+
+_EXTERNAL_MENTION = """
+    SELECT 1 FROM mentions m
+    JOIN chunks c ON m.chunk_id = c.id
+    WHERE m.symbol_id = ? AND m.role != 1 AND c.document_id != ?
+    LIMIT 1
+"""
+
+
+def _fetch_all(db, sql: str, params=()) -> list:
+    return debug_execute(db, sql, params).fetchall()
+
+
+def _fetch_one(db, sql: str, params=()):
+    return debug_execute(db, sql, params).fetchone()
+
+
+def is_export_alias_symbol(symbol: str) -> bool:
+    tail = symbol.split("/")[-1]
+    return tail.endswith("0:") and "()." not in tail
+
+
+def export_alias_base(symbol: str) -> str | None:
+    if not is_export_alias_symbol(symbol):
+        return None
+    tail = symbol.split("/")[-1]
+    return tail[:-2]
+
+
+def export_value_base(symbol: str) -> str | None:
+    """Base name for a default-exported function or class/type definition."""
+    if symbol.endswith("()."):
+        return extract_leaf_name(symbol) or None
+    if symbol.endswith("#") and "#typeLiteral" not in symbol and "()." not in symbol.split("/")[-1]:
+        leaf = extract_leaf_name(symbol)
+        return leaf or None
+    return None
+
+
+def _def_doc_id_from_symbol(db, symbol: str) -> int | None:
+    match = re.search(r"`([^`]+)`", symbol)
+    if not match:
+        return None
+    filename = match.group(1)
+    row = _fetch_one(
+        db,
+        "SELECT id FROM documents WHERE relative_path GLOB ? OR relative_path = ? LIMIT 1",
+        (f"*/{filename}", filename),
+    )
+    return row[0] if row else None
+
+
+class LiveIndex:
+    """Precomputed live-module docs and export-alias bases for one analyze pass."""
+
+    def __init__(self, db) -> None:
+        self.live_module_docs: set[int] = set()
+        self.live_alias_bases: set[str] = set()
+        self.module_importers: dict[int, int] = {}
+        self._build(db)
+
+    def _build(self, db) -> None:
+        for doc_id, importer_count in _fetch_all(
+            db,
+            """
+            SELECT der.document_id, COUNT(DISTINCT c.document_id)
+            FROM global_symbols gs
+            JOIN defn_enclosing_ranges der ON der.symbol_id = gs.id
+            JOIN mentions m ON m.symbol_id = gs.id AND m.role != 1
+            JOIN chunks c ON m.chunk_id = c.id
+            WHERE gs.symbol LIKE '%/' AND gs.symbol NOT LIKE '%().'
+              AND c.document_id != der.document_id
+            GROUP BY der.document_id
+            """,
+        ):
+            self.live_module_docs.add(doc_id)
+            self.module_importers[doc_id] = importer_count
+
+        for sym_id, symbol in _fetch_all(
+            db,
+            """
+            SELECT id, symbol FROM global_symbols
+            WHERE symbol LIKE '%0:' AND symbol NOT LIKE '%().'
+            """,
+        ):
+            base = export_alias_base(symbol)
+            if not base:
+                continue
+            def_doc = _def_doc_id_from_symbol(db, symbol)
+            if def_doc is None:
+                continue
+            if _fetch_one(db, _EXTERNAL_MENTION, (sym_id, def_doc)):
+                self.live_alias_bases.add(base)
+
+    def possibly_live_label(self, symbol: str, def_doc_id: int) -> str | None:
+        """Proof of liveness via module or export alias (used to suppress false dead-export hits)."""
+        if is_module_symbol(symbol):
+            if def_doc_id not in self.live_module_docs:
+                return None
+            count = self.module_importers.get(def_doc_id, 0)
+            return f"module_import:{count}"
+        base = export_value_base(symbol)
+        if not base:
+            return None
+        if base in self.live_alias_bases:
+            return "export_alias"
+        if def_doc_id in self.live_module_docs:
+            count = self.module_importers.get(def_doc_id, 0)
+            return f"default_export:{count}"
+        return None
+
+    def dead_export_noise(self, symbol: str, def_doc_id: int) -> bool:
+        """Suppress from dead_exports when live via module or export alias."""
+        return self.possibly_live_label(symbol, def_doc_id) is not None or is_module_symbol(symbol)
+
+    def same_file_export_noise(self, symbol: str, def_doc_id: int | None = None) -> bool:
+        """Export used only in-file but live via module or export alias elsewhere."""
+        base = export_value_base(symbol)
+        if not base:
+            return False
+        if base in self.live_alias_bases:
+            return True
+        return def_doc_id is not None and def_doc_id in self.live_module_docs
+
+    def stale_type_live_noise(self, symbol: str, def_doc_id: int) -> bool:
+        """Class/type looks unused but file is live via default export or module import."""
+        base = export_value_base(symbol)
+        if not base:
+            return False
+        if base in self.live_alias_bases:
+            return True
+        return def_doc_id in self.live_module_docs
+
+
+def has_same_file_reference_usage(db, symbol_id: int, def_doc_id: int) -> bool:
+    """Type or value referenced in the same file (extends, signatures, handler registration)."""
+    row = _fetch_one(
+        db,
+        """
+        SELECT 1 FROM mentions m
+        JOIN chunks c ON m.chunk_id = c.id
+        WHERE m.symbol_id = ? AND m.role = 0 AND c.document_id = ?
+        LIMIT 1
+        """,
+        (symbol_id, def_doc_id),
+    )
+    return row is not None
+
+
+def file_has_scip_importers(db, relative_path: str, *, live: LiveIndex, def_doc_id: int) -> bool:
+    """True when the index shows another file importing this module or its symbols."""
+    if def_doc_id in live.live_module_docs:
+        return True
+    from ..queries import get_file_symbols, get_importer_paths
+
+    symbols = get_file_symbols(db, relative_path)
+    if not symbols:
+        return False
+    symbol_ids = [row[0] for row in symbols]
+    return bool(get_importer_paths(db, symbol_ids, relative_path))