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

{scip_cli-2.1.0 → scip_cli-2.2.0}/.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 2.1.0
+Version: 2.2.0
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler

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

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

{scip_cli-2.1.0 → scip_cli-2.2.0}/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"))

{scip_cli-2.1.0 → scip_cli-2.2.0}/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
 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,14 +106,18 @@ 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,
         """
@@ -135,18 +141,22 @@ 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 in rows:
+        if analyze_noise(relative_path, symbol, include_tests=True):
+            continue
+        if live.same_file_export_noise(symbol):
+            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.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 +174,14 @@ 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 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 imports_summary(db, relative_path: str, limit: int = DEFAULT_LIMIT) -> list[str]:
@@ -240,6 +253,29 @@ 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 dead_export_rdeps_warning(db, relative_path: str, *, limit: int = DEFAULT_LIMIT) -> str | None:
+    """Warn when dead/unreferenced exports coexist with file importers (SCIP symbol split)."""
+    if not dead_in_file(db, relative_path, limit=limit) and not unreferenced_in_file(db, relative_path, limit=limit):
+        return None
+    importer_count = count_file_importers(db, relative_path)
+    if importer_count == 0:
+        return None
+    return (
+        f"Warning: {relative_path} has {importer_count} importer(s) but lists dead/unreferenced exports — "
+        "default-export, lazy(), or object-alias false positives are likely; verify with rg or rdeps"
+    )
+
+
 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)

{scip_cli-2.1.0 → scip_cli-2.2.0}/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.0/scip_cli/analyze/live.py

@@ -0,0 +1,139 @@
+"""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._build(db)
+
+    def _build(self, db) -> None:
+        for (doc_id,) in _fetch_all(
+            db,
+            """
+            SELECT DISTINCT der.document_id
+            FROM global_symbols gs
+            JOIN defn_enclosing_ranges der ON der.symbol_id = gs.id
+            WHERE gs.symbol LIKE '%/' AND gs.symbol NOT LIKE '%().'
+              AND EXISTS (
+                SELECT 1 FROM mentions m
+                JOIN chunks c ON m.chunk_id = c.id
+                WHERE m.symbol_id = gs.id AND m.role != 1 AND c.document_id != der.document_id
+              )
+            """,
+        ):
+            self.live_module_docs.add(doc_id)
+
+        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 dead_export_noise(self, symbol: str, def_doc_id: int) -> bool:
+        if is_module_symbol(symbol):
+            return True
+        base = export_value_base(symbol)
+        if base and base in self.live_alias_bases:
+            return True
+        return bool(base and def_doc_id in self.live_module_docs)
+
+    def same_file_export_noise(self, symbol: str) -> bool:
+        """Export used only in-file but live via module or export alias elsewhere."""
+        base = export_value_base(symbol)
+        if not base:
+            return False
+        return base in self.live_alias_bases
+
+    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, object literal)."""
+    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

{scip_cli-2.1.0 → scip_cli-2.2.0}/scip_cli/analyze/project.py

@@ -17,6 +17,7 @@ from .common import (
     stale_type_noise,
 )
 from .graph import FILE_EDGES_SQL, fetch_file_edges, find_longer_cycles
+from .live import LiveIndex, has_same_file_reference_usage
 from .sections import Check, Priority, run_checks
 
 
@@ -149,6 +150,26 @@ def cycles(
     return lines[:limit]
 
 
+def _format_dead_export_rows(
+    db,
+    rows,
+    live: LiveIndex,
+    *,
+    include_tests: bool,
+    limit: int,
+) -> list[str]:
+    lines = []
+    for symbol, path, loc, def_doc_id in rows:
+        if analyze_noise(path, symbol, include_tests=include_tests):
+            continue
+        if live.dead_export_noise(symbol, def_doc_id):
+            continue
+        lines.append(f"{short_name(symbol)}  loc={loc}  ({path})")
+        if len(lines) >= limit:
+            break
+    return lines
+
+
 def stale_types(
     db,
     limit: int = DEFAULT_LIMIT,
@@ -160,7 +181,7 @@ def stale_types(
     rows = fetch_all(
         db,
         f"""
-        SELECT gs.symbol, def_d.relative_path,
+        SELECT gs.id, gs.symbol, def_d.relative_path, def_d.id,
                COUNT(DISTINCT CASE WHEN ref_d.id != def_d.id THEN ref_d.id END) AS consumers
         FROM global_symbols gs
         {SYM_DEF_JOIN}
@@ -177,13 +198,21 @@ def stale_types(
         """,
         (*scope_params, limit * 5),
     )
-    lines = [
-        f"{short_name(symbol)}  consumers={consumers}  ({path})"
-        for symbol, path, consumers in rows
-        if not analyze_noise(path, symbol, include_tests=include_tests)
-        and not stale_type_noise(path, symbol, consumers)
-    ]
-    return lines[:limit]
+    lines = []
+    live = LiveIndex(db)
+    for sym_id, symbol, path, def_doc_id, consumers in rows:
+        if analyze_noise(path, symbol, include_tests=include_tests):
+            continue
+        if stale_type_noise(path, symbol, consumers):
+            continue
+        if consumers == 0 and has_same_file_reference_usage(db, sym_id, def_doc_id):
+            continue
+        if live.stale_type_live_noise(symbol, def_doc_id):
+            continue
+        lines.append(f"{short_name(symbol)}  consumers={consumers}  ({path})")
+        if len(lines) >= limit:
+            break
+    return lines
 
 
 def unreferenced_symbols(
@@ -198,7 +227,8 @@ def unreferenced_symbols(
         db,
         f"""
         SELECT gs.symbol, def_d.relative_path,
-               sym_def.end_line - sym_def.start_line + 1 AS loc
+               sym_def.end_line - sym_def.start_line + 1 AS loc,
+               def_d.id
         FROM global_symbols gs
         {SYM_DEF_JOIN}
         WHERE NOT EXISTS (
@@ -215,12 +245,7 @@ def unreferenced_symbols(
         """,
         (*scope_params, limit * 5),
     )
-    lines = [
-        f"{short_name(symbol)}  loc={loc}  ({path})"
-        for symbol, path, loc in rows
-        if not analyze_noise(path, symbol, include_tests=include_tests)
-    ]
-    return lines[:limit]
+    return _format_dead_export_rows(db, rows, LiveIndex(db), include_tests=include_tests, limit=limit)
 
 
 def same_file_only(
@@ -231,6 +256,7 @@ def same_file_only(
     scope: str | None = None,
 ) -> list[str]:
     scope_clause, scope_params = path_filter_sql(db, scope, doc_alias="def_d")
+    live = LiveIndex(db)
     rows = fetch_all(
         db,
         f"""
@@ -253,12 +279,16 @@ def same_file_only(
         """,
         (*scope_params, limit * 5),
     )
-    lines = [
-        f"{short_name(symbol)}  loc={loc}  ({path})"
-        for symbol, path, loc in rows
-        if not analyze_noise(path, symbol, include_tests=include_tests)
-    ]
-    return lines[:limit]
+    lines = []
+    for symbol, path, loc in rows:
+        if analyze_noise(path, symbol, include_tests=include_tests):
+            continue
+        if live.same_file_export_noise(symbol):
+            continue
+        lines.append(f"{short_name(symbol)}  loc={loc}  ({path})")
+        if len(lines) >= limit:
+            break
+    return lines
 
 
 def symbols_test_only_consumers(
@@ -316,7 +346,8 @@ def dead_exports(
         db,
         f"""
         SELECT gs.symbol, def_d.relative_path,
-               sym_def.end_line - sym_def.start_line + 1 AS loc
+               sym_def.end_line - sym_def.start_line + 1 AS loc,
+               def_d.id
         FROM global_symbols gs
         {SYM_DEF_JOIN}
         WHERE NOT EXISTS (
@@ -332,12 +363,50 @@ def dead_exports(
         """,
         (*scope_params, limit * 5),
     )
-    lines = [
-        f"{short_name(symbol)}  loc={loc}  ({path})"
-        for symbol, path, loc in rows
-        if not analyze_noise(path, symbol, include_tests=include_tests)
-    ]
-    return lines[:limit]
+    return _format_dead_export_rows(db, rows, LiveIndex(db), include_tests=include_tests, limit=limit)
+
+
+def possibly_unused_exports(
+    db,
+    limit: int = DEFAULT_LIMIT,
+    *,
+    include_tests: bool = False,
+    scope: str | None = None,
+) -> list[str]:
+    """Exports with no direct external refs but live via module import or export alias."""
+    scope_clause, scope_params = path_filter_sql(db, scope, doc_alias="def_d")
+    live = LiveIndex(db)
+    rows = fetch_all(
+        db,
+        f"""
+        SELECT gs.symbol, def_d.relative_path,
+               sym_def.end_line - sym_def.start_line + 1 AS loc,
+               def_d.id
+        FROM global_symbols gs
+        {SYM_DEF_JOIN}
+        WHERE NOT EXISTS (
+            SELECT 1
+            FROM mentions m
+            JOIN chunks c ON m.chunk_id = c.id
+            WHERE m.symbol_id = gs.id
+              AND m.role != 1
+              AND c.document_id != def_d.id
+        ){scope_clause}
+        ORDER BY loc DESC, def_d.relative_path
+        LIMIT ?
+        """,
+        (*scope_params, limit * 5),
+    )
+    lines = []
+    for symbol, path, loc, def_doc_id in rows:
+        if analyze_noise(path, symbol, include_tests=include_tests):
+            continue
+        if not live.dead_export_noise(symbol, def_doc_id):
+            continue
+        lines.append(f"{short_name(symbol)}  loc={loc}  (live via module/alias)  ({path})")
+        if len(lines) >= limit:
+            break
+    return lines
 
 
 def top_coupling(
@@ -388,6 +457,12 @@ def run_all(
         Check("cycles", Priority.HIGH, f"Cycles (file dependencies){suffix}", cycles),
         Check("unreferenced", Priority.HIGH, f"Unreferenced symbols (no refs){suffix}", unreferenced_symbols),
         Check("dead_exports", Priority.HIGH, f"Dead exports (no external refs){suffix}", dead_exports),
+        Check(
+            "possibly_unused",
+            Priority.MEDIUM,
+            f"Possibly unused exports (live via module/alias){suffix}",
+            possibly_unused_exports,
+        ),
         Check("stale_types", Priority.HIGH, f"Stale types (≤1 external consumer){suffix}", stale_types),
         Check("same_file_only", Priority.MEDIUM, f"Same-file only (consider _prefix){suffix}", same_file_only),
         Check(

{scip_cli-2.1.0 → scip_cli-2.2.0}/scip_cli/commands/analyze.py

@@ -45,6 +45,9 @@ def _project_sections(
 
 
 def _file_sections(db, path: str, *, limit: int, priorities) -> list[tuple[str, list[str]]]:
+    warn = file_checks.dead_export_rdeps_warning(db, path, limit=limit)
+    if warn:
+        print(warn, file=sys.stderr)
     return file_checks.run_all(db, path, limit=limit, priorities=priorities)
 
 

{scip_cli-2.1.0 → scip_cli-2.2.0}/scip_cli/commands/refs.py

@@ -4,7 +4,7 @@ import re
 import sys
 
 from ..cli_args import path_scope_from_args
-from ..output import limit_and_warn, maybe_print_symbol_header, symbol_output_label
+from ..output import limit_and_warn, maybe_print_symbol_header, symbol_output_label, warn_ambiguous_refs
 from ..paths import path_filter_sql, path_in_scope
 from ..queries import resolve_symbol
 from ..session import setup
@@ -120,7 +120,9 @@ def _resolve_symbol_groups(db, names, limit, path_scope):
         if not symbols:
             print(f"Symbol '{query_name}' not found", file=sys.stderr)
             continue
-        groups.append((query_name, limit_and_warn(symbols, limit, "symbols")))
+        trimmed = limit_and_warn(symbols, limit, "symbols")
+        warn_ambiguous_refs(query_name, trimmed, db)
+        groups.append((query_name, trimmed))
     return groups