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

{scip_cli-2.0.0 → scip_cli-2.2.0}/.cursor/rules/agent.mdc

@@ -7,26 +7,32 @@ alwaysApply: true
 
 **Work from repo root.** CLI usage, flags, and user gotchas: `scip-cli skill` (source: `scip_cli/SKILL.md`). Read once per task — do not duplicate SKILL here.
 
-Use **`.venv/bin/scip-cli`** / **`.venv/bin/pytest`**. Uncommitted code: `PYTHONPATH=$PWD python -m scip_cli …` if the venv binary is stale.
+**Almost always:** bare `scip-cli` on PATH must be **this checkout live** (`pip install -e ".[dev]"`). All examples use `scip-cli` — never `.venv/bin/scip-cli`, `python -m scip_cli`, or other paths. Only swap to PyPI briefly to smoke-test a release.
 
 ## Bootstrap
 
+From repo root — keep this mapping for the whole dev session:
+
 ```bash
-python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
+scip-cli --version    # must match scip_cli/__init__.py
 pre-commit install
-scip-cli skill
+scip-cli skill ~/.claude/skills/scip-cli/
 ```
 
+After publishing: `pip install scip-cli` → smoke-test → `pip install -e ".[dev]"` to restore local.
+
+Optional venv for isolation only: create/activate, then same `pip install -e ".[dev]"` — `scip-cli` still runs from PATH, not a venv-relative path.
+
 Node.js + `npx` required for integration tests (`scip-typescript`). Optional: `SCIP_CLI_DEBUG=1` (SQL to stderr, truncated).
 
 ## Lint / test
 
 | Task | Command |
 |------|---------|
-| Full suite | `.venv/bin/pytest` |
-| E2e loop | `.venv/bin/pytest tests/test_e2e.py` |
-| Lint / format | `.venv/bin/ruff check .` / `ruff format .` |
+| Full suite | `pytest` |
+| 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.
 
@@ -35,11 +41,11 @@ Pre-commit: ruff + ruff-format + full pytest. E2e before commit on command chang
 **Dogfood on the repo itself** — faster and more honest than spawning reviewers:
 
 ```bash
-.venv/bin/scip-cli reindex
-.venv/bin/scip-cli analyze --limit 25
-.venv/bin/scip-cli analyze --priority high --limit 25   # dead code & cycles only
-.venv/bin/scip-cli analyze scip_cli --limit 15              # directory
-.venv/bin/scip-cli analyze scip_cli/queries.py --limit 20   # file (+ scoped project)
+scip-cli reindex
+scip-cli analyze --limit 25
+scip-cli analyze --priority high --limit 25   # dead code & cycles only
+scip-cli analyze scip_cli --limit 15              # directory
+scip-cli analyze scip_cli/queries.py --limit 20   # file (+ scoped project)
 ```
 
 Interpretation: README § *Finding easy wins with analyze*. Target = omit (project), directory, file, or symbol — not `--path` for scope.
@@ -63,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).
 
@@ -103,16 +110,64 @@ SQLite has **line ranges** (`defn_enclosing_ranges`) so LOC is cheap. That does
 
 **Rule:** size-only checks stay **low or file-drill-down**; never high/medium unless paired with a **structural smell** (cycle, dead export, zero production consumers). Prefer enriching existing low-tier lines (e.g. show `loc` on bottlenecks) over a new dashboard section.
 
+## SQL / analyze benchmarks
+
+The e2e fixture and this repo's own index are **small** — every query looks fast here. That hides blowups on real projects (40MB+ indexes, dense graphs).
+
+**Before merging new or heavily changed SQL** (`queries.py`, `analyze/*`):
+
+1. Time it against **1–2 existing checks** on a **large cached index** you already have (not the fixture):
+   ```bash
+   python3 -u -c "
+   import sqlite3, time, sys
+   from pathlib import Path
+   sys.path.insert(0, '.')
+   from scip_cli.analyze import project as p
+   from scip_cli.sql import configure_read_connection
+   db_path = Path.home() / '.cache/scip-cli/projects/<project-slug>/index.db'
+   db = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
+   configure_read_connection(db)
+   for name, fn in [('hotspots', p.hotspots), ('cycles', p.cycles), ('dead_exports', p.dead_exports)]:
+       t = time.perf_counter(); fn(db, limit=25); print(f'{name}: {(time.perf_counter()-t)*1000:.0f}ms')
+   "
+   ```
+2. Flag anything **notably slower** than peers — orders of magnitude or multi-second, not a few ms drift.
+3. Swap in your new/changed check for one of the rows; keep a fast peer (e.g. `hotspots`) and a heavy peer (e.g. `dead_exports`).
+
+**In CI:** `tests/test_e2e_perf.py` (whole commands) and `tests/test_analyze_perf.py` (per-check on mini DB) catch gross regressions on the tiny fixture only — they **will not** catch large-repo OOMs. Use the manual benchmark above for that.
+
 ## 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.0.0 → scip_cli-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 2.0.0
+Version: 2.2.0
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -62,17 +62,24 @@ scip-cli skill
 pip install scip-cli
 ```
 
-**Local development** (use a project venv — do not rely on global `pip`):
+**Local development** — almost always keep bare `scip-cli` mapped to this checkout via editable install. You edit the repo; the CLI you run is live code, not a frozen PyPI copy.
 
 ```bash
 cd scip-cli
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
 scip-cli --version
 ```
 
-`pip install -e .` keeps `scip-cli` on your PATH inside the venv while you edit the repo. Run tests with `pytest` from the same venv.
+All docs and examples use `scip-cli` (never `.venv/bin/scip-cli` or `python -m scip_cli`). After publishing, briefly `pip install scip-cli` to smoke-test PyPI, then `pip install -e ".[dev]"` again.
+
+Optional venv for isolation — activate it, run the same editable install, still invoke `scip-cli` on PATH:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Tests and lint: `pytest`, `ruff check .` from the same environment.
 
 ### 2. Install prerequisites (optional)
 

{scip_cli-2.0.0 → scip_cli-2.2.0}/README.md

@@ -42,17 +42,24 @@ scip-cli skill
 pip install scip-cli
 ```
 
-**Local development** (use a project venv — do not rely on global `pip`):
+**Local development** — almost always keep bare `scip-cli` mapped to this checkout via editable install. You edit the repo; the CLI you run is live code, not a frozen PyPI copy.
 
 ```bash
 cd scip-cli
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
 scip-cli --version
 ```
 
-`pip install -e .` keeps `scip-cli` on your PATH inside the venv while you edit the repo. Run tests with `pytest` from the same venv.
+All docs and examples use `scip-cli` (never `.venv/bin/scip-cli` or `python -m scip_cli`). After publishing, briefly `pip install scip-cli` to smoke-test PyPI, then `pip install -e ".[dev]"` again.
+
+Optional venv for isolation — activate it, run the same editable install, still invoke `scip-cli` on PATH:
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Tests and lint: `pytest`, `ruff check .` from the same environment.
 
 ### 2. Install prerequisites (optional)
 

{scip_cli-2.0.0 → scip_cli-2.2.0}/scip_cli/SKILL.md

@@ -7,6 +7,8 @@ TypeScript/JavaScript (.ts, .tsx, .js, .jsx) and Python (.py) — not GraphQL, C
 
 All commands are sub-commands of `scip-cli`. Run from the project root.
 
+**Contributors:** keep `pip install -e .` (or `pip install -e ".[dev]"` in this repo) so bare `scip-cli` on PATH runs your live checkout — not a venv-relative path.
+
 ## Quick Decision Guide
 
 | Question                                  | Use                 | What you get                                                                              |

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

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

{scip_cli-2.0.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.0.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.2.0/scip_cli/analyze/graph.py

@@ -0,0 +1,133 @@
+"""File dependency graph helpers for analyze (cycle detection)."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from ..symbols import cycle_runtime_edge_sql
+from .common import fetch_all
+
+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()}
+"""
+
+
+def fetch_file_edges(db) -> list[tuple[str, str]]:
+    return fetch_all(db, FILE_EDGES_SQL)
+
+
+def _tarjan_sccs(graph: dict[str, list[str]], nodes: set[str]) -> list[list[str]]:
+    index = 0
+    stack: list[str] = []
+    on_stack: set[str] = set()
+    indices: dict[str, int] = {}
+    lowlink: dict[str, int] = {}
+    sccs: list[list[str]] = []
+
+    def strongconnect(vertex: str) -> None:
+        nonlocal index
+        indices[vertex] = index
+        lowlink[vertex] = index
+        index += 1
+        stack.append(vertex)
+        on_stack.add(vertex)
+        for neighbor in graph.get(vertex, ()):
+            if neighbor not in indices:
+                strongconnect(neighbor)
+                lowlink[vertex] = min(lowlink[vertex], lowlink[neighbor])
+            elif neighbor in on_stack:
+                lowlink[vertex] = min(lowlink[vertex], indices[neighbor])
+        if lowlink[vertex] == indices[vertex]:
+            component: list[str] = []
+            while True:
+                w = stack.pop()
+                on_stack.remove(w)
+                component.append(w)
+                if w == vertex:
+                    break
+            sccs.append(component)
+
+    for node in nodes:
+        if node not in indices:
+            strongconnect(node)
+    return sccs
+
+
+def _cycles_in_scc(
+    graph: dict[str, list[str]],
+    scc_nodes: list[str],
+    *,
+    max_depth: int,
+    limit: int,
+) -> list[str]:
+    if len(scc_nodes) <= 2:
+        return []
+
+    scc = set(scc_nodes)
+    subgraph: dict[str, list[str]] = defaultdict(list)
+    for src in scc:
+        for dst in graph.get(src, ()):
+            if dst in scc:
+                subgraph[src].append(dst)
+
+    found: dict[tuple[str, ...], str] = {}
+
+    def record(path: list[str]) -> None:
+        key = min(tuple(path[i:] + path[:i]) for i in range(len(path)))
+        if key not in found:
+            found[key] = " -> ".join([*path, path[0]])
+
+    for origin in sorted(scc):
+        stack: list[tuple[str, list[str]]] = [(origin, [origin])]
+        while stack:
+            node, path = stack.pop()
+            if len(path) > max_depth:
+                continue
+            for nxt in subgraph.get(node, ()):
+                if nxt == origin and len(path) >= 2:
+                    record(path)
+                    if len(found) >= limit:
+                        return sorted(found.values())[:limit]
+                elif nxt not in path:
+                    stack.append((nxt, [*path, nxt]))
+    return sorted(found.values())
+
+
+def find_longer_cycles(
+    edges: list[tuple[str, str]],
+    *,
+    max_depth: int = 8,
+    limit: int,
+) -> list[str]:
+    """Find directed cycles with 3+ distinct files (2-node pairs use the SQL two-way check)."""
+    if limit <= 0 or not edges:
+        return []
+
+    graph: dict[str, list[str]] = defaultdict(list)
+    nodes: set[str] = set()
+    for src, dst in edges:
+        graph[src].append(dst)
+        nodes.add(src)
+        nodes.add(dst)
+
+    found: dict[tuple[str, ...], str] = {}
+    for component in _tarjan_sccs(graph, nodes):
+        if len(component) <= 2:
+            continue
+        for line in _cycles_in_scc(graph, component, max_depth=max_depth, limit=limit):
+            path = line.split(" -> ")
+            body = path[:-1]
+            key = min(tuple(body[i:] + body[:i]) for i in range(len(body)))
+            if key not in found:
+                found[key] = line
+            if len(found) >= limit:
+                return sorted(found.values())[:limit]
+    return sorted(found.values())[:limit]