scip-cli 1.0.3__tar.gz → 1.1.0__tar.gz

{scip_cli-1.0.3/scip_cli.egg-info → scip_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 1.0.3
+Version: 1.1.0
 Summary: Fast code intelligence via SCIP indexes
 Home-page: https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -40,10 +40,27 @@ Fast code intelligence CLI for TypeScript/JavaScript and Python projects. Query
 
 ### 1. Install scip-cli
 
+**From PyPI:**
+
 ```bash
 pip install scip-cli
 ```
 
+**From source (local development):**
+
+```bash
+git clone https://github.com/flesler/scip-cli.git
+cd scip-cli
+pip install .
+```
+
+For editable development (where `pip install -e .` fails due to permissions):
+
+```bash
+export PYTHONPATH=/path/to/scip-cli:$PYTHONPATH
+python -m scip_cli --help
+```
+
 ### 2. Install prerequisites (optional)
 
 scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
@@ -156,6 +173,19 @@ scip_cli/
     └── skill.py
 ```
 
+## Development
+
+### Debug Logging
+
+Set `SCIP_CLI_DEBUG=1` to enable SQL query logging to stderr:
+
+```bash
+SCIP_CLI_DEBUG=1 scip-cli refs MyFunction
+# Shows: SQL: SELECT ... | params: (...)
+```
+
+This is useful for testing and debugging SQL queries without exposing a `--debug` flag to users.
+
 ## License
 
 MIT

{scip_cli-1.0.3 → scip_cli-1.1.0}/README.md

@@ -16,10 +16,27 @@ Fast code intelligence CLI for TypeScript/JavaScript and Python projects. Query
 
 ### 1. Install scip-cli
 
+**From PyPI:**
+
 ```bash
 pip install scip-cli
 ```
 
+**From source (local development):**
+
+```bash
+git clone https://github.com/flesler/scip-cli.git
+cd scip-cli
+pip install .
+```
+
+For editable development (where `pip install -e .` fails due to permissions):
+
+```bash
+export PYTHONPATH=/path/to/scip-cli:$PYTHONPATH
+python -m scip_cli --help
+```
+
 ### 2. Install prerequisites (optional)
 
 scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
@@ -132,6 +149,19 @@ scip_cli/
     └── skill.py
 ```
 
+## Development
+
+### Debug Logging
+
+Set `SCIP_CLI_DEBUG=1` to enable SQL query logging to stderr:
+
+```bash
+SCIP_CLI_DEBUG=1 scip-cli refs MyFunction
+# Shows: SQL: SELECT ... | params: (...)
+```
+
+This is useful for testing and debugging SQL queries without exposing a `--debug` flag to users.
+
 ## License
 
 MIT

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/SKILL.md

@@ -11,8 +11,8 @@ All commands are sub-commands of `scip-cli`. Run from the project root.
 
 | Question | Use | What you get |
 |----------|-----|--------------|
-| "Where is X defined and what does it do?" | `def X` | Functions: full body. Classes: full definition. Multiple exact matches returned together |
-| "Where is X used/called?" | `refs X` | All file:line locations (~0.03s). Ambiguous bare names → first match only |
+| "Where is X defined and what does it do?" | `def X` | Functions: full body. Classes: full definition. Use `--limit` to cap results |
+| "Where is X used/called?" | `refs X` | All file:line locations. Shows refs for all matching symbols. Use `--limit` to cap |
 | "What's in this file?" | `symbols file` | All symbols — bare filename works (`HistoryTab`, `usePatientEntries`) |
 | "Find symbols by name" | `search name` | Functions, types, interfaces, classes. Use `--kind variable` for consts |
 | "What files depend on this file?" | `rdeps file` | Importers — bare name works |
@@ -21,7 +21,7 @@ All commands are sub-commands of `scip-cli`. Run from the project root.
 ## Gotchas
 
 - **Bare names** resolve functions, types (aliases + interfaces), and classes. Consts/variables need `def --kind variable X` or `search --kind variable X`. Class methods need `members ClassName`, not bare `def methodName`.
-- **Ambiguous types** (e.g. `Opts` in multiple hooks) — `def` returns all; `refs` picks the first and warns. Use `search` with a more specific pattern to disambiguate.
+- **Ambiguous types** (e.g. `Opts` in multiple hooks) — `def` returns all matches; `refs` returns refs for all matching symbols. Use `--limit N` to cap results, or use `search` with a more specific pattern to disambiguate.
 - **First run** in a project may auto-index (one-time wait, ~10-30s for large codebases). JS-only projects (no `tsconfig.json`) are supported automatically.
 
 ## Details
@@ -29,43 +29,53 @@ All commands are sub-commands of `scip-cli`. Run from the project root.
 ### def
 
 ```bash
-def [--kind <kind>] <symbol>
+def [--kind <kind>] [--limit N] <symbol>
 ```
 
 Kinds: `function`, `method`, `class`, `property`, `variable` — use `--kind` when the bare name isn't in the default set above.
 
+Default `--limit` is 10. Use `--limit 0` for unlimited (not recommended for large codebases).
+
 ### refs
 
 ```bash
-refs <symbol>
+refs [--limit N] <symbol>
 ```
 
 Returns `file:line` for each reference. Reads source files to find exact line numbers.
 
+Default `--limit` is 10. When multiple symbols match, refs are grouped by symbol with `# <symbol>` headers.
+
 ### search
 
 ```bash
-search [--kind <kind>] <pattern>
+search [--kind <kind>] [--limit N] <pattern>
 ```
 
 Returns `file:line Kind symbolName`. Filters noisy symbols (file-level, parameters, type literals).
 
+Default `--limit` is 10.
+
 ### symbols
 
 ```bash
-symbols <file>
+symbols [--limit N] <file>
 ```
 
 Returns `startLine-endLine kind name` for each symbol in the file.
 
+Default `--limit` is 10.
+
 ### rdeps
 
 ```bash
-rdeps <file>
+rdeps [--limit N] <file>
 ```
 
 Returns list of files that import from this file.
 
+Default `--limit` is 10.
+
 ### members
 
 ```bash

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/__init__.py

@@ -1,2 +1,2 @@
 """scip-cli: Fast code intelligence via SCIP indexes."""
-__version__ = "1.0.3"
+__version__ = "1.1.0"

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/__main__.py

@@ -1,11 +1,23 @@
 """CLI entry point for scip-cli."""
 import argparse
+import logging
+import os
 import sys
 
 from . import __version__
 from .lib import SymbolKind
 from .commands import refs, def_cmd, search, symbols, rdeps, members, skill, reindex
 
+# Set up debug logging based on SCIP_CLI_DEBUG env var
+if os.environ.get("SCIP_CLI_DEBUG"):
+    logging.basicConfig(
+        level=logging.DEBUG,
+        format="%(name)s: %(message)s",
+        stream=sys.stderr
+    )
+else:
+    logging.disable(logging.DEBUG)
+
 
 def main():
     parser = argparse.ArgumentParser(
@@ -18,23 +30,28 @@ def main():
     # refs
     refs_parser = subparsers.add_parser("refs", help="Find references to a symbol")
     refs_parser.add_argument("symbol", help="Symbol name")
+    refs_parser.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
 
     # def
     def_parser = subparsers.add_parser("def", help="Find symbol definition")
     def_parser.add_argument("--kind", choices=SymbolKind.filterable_values(), help="Filter by kind")
+    def_parser.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     def_parser.add_argument("symbol", help="Symbol name")
 
     # search
     search_parser = subparsers.add_parser("search", help="Search symbols by pattern")
     search_parser.add_argument("--kind", choices=SymbolKind.filterable_values(), help="Filter by kind")
+    search_parser.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     search_parser.add_argument("pattern", help="Search pattern")
 
     # symbols
     symbols_parser = subparsers.add_parser("symbols", help="List symbols in a file")
+    symbols_parser.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     symbols_parser.add_argument("file", help="File path or pattern")
 
     # rdeps
     rdeps_parser = subparsers.add_parser("rdeps", help="Find reverse dependencies of a file")
+    rdeps_parser.add_argument("--limit", type=int, default=10, help="Max results (default: 10)")
     rdeps_parser.add_argument("file", help="File path or pattern")
 
     # members

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/commands/def_cmd.py

@@ -7,6 +7,7 @@ from ..lib import (
     read_source_lines,
     infer_kind,
     get_def_location,
+    format_line_range,
 )
 
 
@@ -14,11 +15,15 @@ def main(args):
     """Find the definition of a symbol."""
     db, project_root = setup()
     try:
-        symbols = resolve_symbol(db, args.symbol, args.kind)
+        limit = args.limit
+        symbols = resolve_symbol(db, args.symbol, args.kind, limit=limit + 1)
         if not symbols:
             print(f"Symbol '{args.symbol}' not found", file=sys.stderr)
             sys.exit(1)
 
+        hit_limit = len(symbols) > limit
+        symbols = symbols[:limit]
+
         for symbol_id, symbol_str, display_name in symbols:
             row = get_def_location(db, symbol_id)
             if not row:
@@ -33,7 +38,10 @@ def main(args):
             else:
                 source_snippet = ''.join(lines).rstrip('\n')
 
-            print(f"{rel_path}:{start_line + 1}:{end_line + 1}")
+            print(f"{rel_path}:{format_line_range(start_line, end_line)}")
             print(source_snippet)
+
+        if hit_limit:
+            print(f"# Warning: more than {limit} symbols match, showing first {limit}", file=sys.stderr)
     finally:
         db.close()

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/commands/members.py

@@ -10,6 +10,7 @@ from ..lib import (
     infer_kind,
     extract_leaf_name,
     read_source_lines,
+    format_line_range,
     SymbolKind,
 )
 
@@ -79,7 +80,7 @@ def main(args):
                         end_line = start_line
                         break
 
-            line_info = f"{start_line + 1}:{end_line + 1}" if start_line is not None else "??"
+            line_info = format_line_range(start_line, end_line)
             print(f"{line_info} {kind} {short}")
     finally:
         db.close()

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/commands/rdeps.py

@@ -13,6 +13,7 @@ def main(args):
     """Find all files that import from this file."""
     db, _ = setup()
     try:
+        limit = args.limit
         file_path = resolve_one_file(db, args.file)
 
         symbols = get_file_symbols(db, file_path)
@@ -33,7 +34,14 @@ def main(args):
             print(f"No reverse dependencies found for '{file_path}'", file=sys.stderr)
             sys.exit(1)
 
-        for dep_path in sorted(rdeps):
+        sorted_rdeps = sorted(rdeps)
+        hit_limit = len(sorted_rdeps) > limit
+        sorted_rdeps = sorted_rdeps[:limit]
+
+        for dep_path in sorted_rdeps:
             print(dep_path)
+
+        if hit_limit:
+            print(f"# Warning: more than {limit} reverse dependencies, showing first {limit}", file=sys.stderr)
     finally:
         db.close()

scip_cli-1.1.0/scip_cli/commands/refs.py

@@ -0,0 +1,116 @@
+"""refs command - find all references to a symbol."""
+import sys
+
+from ..lib import (
+    setup,
+    resolve_symbol,
+    read_source_lines,
+    extract_leaf_name,
+)
+
+
+def get_exact_refs(db, symbol_id, project_root, max_refs):
+    """Get references with exact line numbers by reading source files."""
+    sym_row = db.execute("SELECT symbol FROM global_symbols WHERE id = ?", (symbol_id,)).fetchone()
+    if not sym_row:
+        return [], False
+
+    leaf = extract_leaf_name(sym_row[0])
+
+    chunks = db.execute("""
+        SELECT c.id, c.document_id, c.start_line, c.end_line, d.relative_path
+        FROM mentions m
+        JOIN chunks c ON m.chunk_id = c.id
+        JOIN documents d ON c.document_id = d.id
+        WHERE m.symbol_id = ? AND m.role != 1
+        LIMIT ?
+    """, (symbol_id, max_refs + 1)).fetchall()
+
+    hit_limit = len(chunks) > max_refs
+    if hit_limit:
+        chunks = chunks[:max_refs]
+
+    if not chunks:
+        return [], False
+
+    by_doc = {}
+    for chunk_id, doc_id, start_line, end_line, rel_path in chunks:
+        if doc_id not in by_doc:
+            by_doc[doc_id] = {'path': rel_path, 'chunks': []}
+        by_doc[doc_id]['chunks'].append((chunk_id, start_line, end_line))
+
+    results = []
+
+    for doc_id, info in by_doc.items():
+        rel_path = info['path']
+        chunks_list = info['chunks']
+        if not chunks_list:
+            continue
+
+        min_line = min(c[1] for c in chunks_list)
+        max_line = max(c[2] for c in chunks_list)
+
+        lines = read_source_lines(project_root, rel_path, min_line, max_line)
+        if lines is None:
+            for chunk_id, start_line, end_line in chunks_list:
+                if start_line is not None:
+                    results.append((rel_path, start_line + 1))
+            continue
+
+        for chunk_id, start_line, end_line in chunks_list:
+            if start_line is None:
+                continue
+            offset = min_line
+            found = False
+            for line_idx in range(start_line - offset, min(end_line - offset + 1, len(lines))):
+                if leaf in lines[line_idx]:
+                    results.append((rel_path, line_idx + offset + 1))
+                    found = True
+                    break
+            if not found:
+                results.append((rel_path, start_line + 1))
+
+    return results, hit_limit
+
+
+def main(args):
+    """Find all references to a symbol."""
+    db, project_root = setup()
+    try:
+        limit = args.limit
+
+        # Get symbols with LIMIT + 1 to detect if we hit the limit
+        symbols = resolve_symbol(db, args.symbol, limit=limit + 1)
+        if not symbols:
+            print(f"Symbol '{args.symbol}' not found", file=sys.stderr)
+            sys.exit(1)
+
+        symbols_hit_limit = len(symbols) > limit
+        symbols = symbols[:limit]
+
+        all_refs = []
+        for symbol_id, symbol_str, display_name in symbols:
+            refs, refs_hit_limit = get_exact_refs(db, symbol_id, project_root, limit)
+            if refs:
+                all_refs.append((symbol_str, refs, refs_hit_limit))
+
+        if not all_refs:
+            print(f"No references found for '{args.symbol}'", file=sys.stderr)
+            sys.exit(1)
+
+        if symbols_hit_limit:
+            print(f"# Warning: more than {limit} symbols match, showing first {limit}", file=sys.stderr)
+
+        for symbol_str, refs, refs_hit_limit in all_refs:
+            if len(all_refs) > 1:
+                print(f"# {symbol_str}")
+            if refs_hit_limit:
+                print(f"# Warning: more than {limit} refs for this symbol")
+            seen = set()
+            for path, line in refs:
+                key = (path, line)
+                if key not in seen:
+                    seen.add(key)
+                    print(f"{path}:{line}")
+    finally:
+        db.close()

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/commands/search.py

@@ -78,6 +78,7 @@ def main(args):
     """Search symbols by pattern."""
     db, _ = setup()
     try:
+        limit = args.limit
         # Escape LIKE wildcards in user pattern
         escaped_pattern = escape_like(args.pattern)
         
@@ -95,15 +96,18 @@ def main(args):
             rows = [r for r in rows if infer_kind(r[1]) == args.kind]
             
             # Apply LIMIT after filtering
-            rows = rows[:100]
+            hit_limit = len(rows) > limit
+            rows = rows[:limit]
         else:
-            rows = db.execute("""
+            rows = db.execute(f"""
                 SELECT gs.id, gs.symbol, gs.display_name, der.start_line
                 FROM global_symbols gs
                 LEFT JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
                 WHERE gs.symbol LIKE ? ESCAPE '\\'
-                LIMIT 100
+                LIMIT {limit + 1}
             """, (f"%{escaped_pattern}%",)).fetchall()
+            hit_limit = len(rows) > limit
+            rows = rows[:limit]
 
         if not rows:
             if args.kind:
@@ -127,5 +131,8 @@ def main(args):
 
             kind_display = kind_to_display(kind)
             print(f"{file_path}:{line} {kind_display} {symbol_name}")
+
+        if hit_limit:
+            print(f"# Warning: more than {limit} results, showing first {limit}", file=sys.stderr)
     finally:
         db.close()

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/commands/symbols.py

@@ -7,6 +7,7 @@ from ..lib import (
     get_file_symbols,
     infer_kind,
     extract_leaf_name,
+    format_line_range,
 )
 
 
@@ -16,20 +17,24 @@ def main(args):
     try:
         file_path = resolve_one_file(db, args.file)
 
-        symbols = get_file_symbols(db, file_path)
+        limit = args.limit
+        symbols = get_file_symbols(db, file_path, limit=limit + 1)
         if not symbols:
             print(f"No symbols found in '{file_path}'", file=sys.stderr)
             sys.exit(1)
 
+        hit_limit = len(symbols) > limit
+        symbols = symbols[:limit]
+
         for symbol_id, symbol_str, display_name, start_line, end_line in symbols:
             if symbol_str.endswith('/'):
                 continue
             kind = infer_kind(symbol_str)
             short = extract_leaf_name(symbol_str)
-            if start_line is not None and end_line is not None:
-                line_info = f"{start_line + 1}-{end_line + 1}"
-            else:
-                line_info = "??"
+            line_info = format_line_range(start_line, end_line, sep="-")
             print(f"{line_info} {kind} {short}")
+
+        if hit_limit:
+            print(f"# Warning: more than {limit} symbols, showing first {limit}", file=sys.stderr)
     finally:
         db.close()

{scip_cli-1.0.3 → scip_cli-1.1.0}/scip_cli/lib.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """Core library for scip-cli: indexing, symbol resolution, and source reading."""
 import hashlib
+import logging
 import os
 import sqlite3
 import subprocess
@@ -9,6 +10,15 @@ import tempfile
 from enum import Enum
 from pathlib import Path
 
+logger = logging.getLogger(__name__)
+
+
+def _debug_execute(db, sql, params=()):
+    """Execute SQL with optional debug logging."""
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug("SQL: %s | params: %s", sql.strip()[:200], params)
+    return db.execute(sql, params)
+
 
 INDEX_TIMEOUT = 300
 
@@ -189,7 +199,7 @@ def infer_kind(symbol):
     return SymbolKind.UNKNOWN
 
 
-def resolve_symbol(db, name, kind_filter=None):
+def resolve_symbol(db, name, kind_filter=None, limit=None):
     """Resolve bare name to symbol_id(s).
     
     Two-phase resolution: exact leaf match first, then substring fallback.
@@ -198,27 +208,34 @@ def resolve_symbol(db, name, kind_filter=None):
         db: sqlite3 connection
         name: bare symbol name (e.g., "useDictation")
         kind_filter: optional kind filter ('function', 'class', etc)
+        limit: optional limit for results (no limit if None)
     
     Returns:
         List of (symbol_id, symbol, display_name) tuples
     """
     escaped = escape_like(name)
-    rows = db.execute("""
+    
+    # Build LIMIT clause
+    limit_clause = f"LIMIT {limit}" if limit else ""
+    
+    sql = f"""
         SELECT id, symbol, display_name FROM global_symbols 
         WHERE symbol LIKE ? ESCAPE '\\' OR symbol LIKE ? ESCAPE '\\' OR symbol LIKE ? ESCAPE '\\'
-    """, (
+        {limit_clause}
+    """
+    params = (
         f"%/{escaped}().",
         f"%/{escaped}#",
         f"%/{escaped}.",
-    )).fetchall()
+    )
+    rows = _debug_execute(db, sql, params).fetchall()
 
     results = list(rows)
 
     if not results:
-        rows = db.execute(
-            "SELECT id, symbol, display_name FROM global_symbols WHERE symbol LIKE ? ESCAPE '\\'",
-            (f"%{escaped}%",)
-        ).fetchall()
+        sql = f"SELECT id, symbol, display_name FROM global_symbols WHERE symbol LIKE ? ESCAPE '\\' {limit_clause}"
+        params = (f"%{escaped}%",)
+        rows = _debug_execute(db, sql, params).fetchall()
         results = [r for r in rows if name in r[1].split("/")[-1]]
 
     if kind_filter and results:
@@ -237,7 +254,7 @@ def resolve_file(db, file_pattern):
     Returns:
         List of matching relative_paths
     """
-    rows = db.execute(
+    rows = _debug_execute(db, 
         "SELECT relative_path FROM documents WHERE relative_path = ?",
         (file_pattern,)
     ).fetchall()
@@ -251,27 +268,35 @@ def resolve_file(db, file_pattern):
     else:
         pattern = escaped.replace("*", "%")
 
-    rows = db.execute(
+    rows = _debug_execute(db, 
         "SELECT relative_path FROM documents WHERE relative_path LIKE ? ESCAPE '\\'",
         (pattern,)
     ).fetchall()
     return [r[0] for r in rows]
 
 
-def get_file_symbols(db, relative_path):
+def get_file_symbols(db, relative_path, limit=None):
     """Get all symbols defined in a file.
     
+    Args:
+        db: sqlite3 connection
+        relative_path: file path
+        limit: optional limit (no limit if None)
+    
     Returns:
         List of (symbol_id, symbol, display_name, start_line, end_line) tuples
     """
-    return db.execute("""
+    limit_clause = f"LIMIT {limit}" if limit else ""
+    sql = f"""
         SELECT gs.id, gs.symbol, gs.display_name, der.start_line, der.end_line
         FROM global_symbols gs
         JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
         JOIN documents d ON der.document_id = d.id
         WHERE d.relative_path = ?
         ORDER BY der.start_line
-    """, (relative_path,)).fetchall()
+        {limit_clause}
+    """
+    return _debug_execute(db, sql, (relative_path,)).fetchall()
 
 
 def get_refs_for_symbols(db, symbol_ids):
@@ -284,7 +309,7 @@ def get_refs_for_symbols(db, symbol_ids):
         return {}
 
     placeholders = ','.join('?' * len(symbol_ids))
-    rows = db.execute(f"""
+    rows = _debug_execute(db, f"""
         SELECT m.symbol_id, d.relative_path, c.start_line
         FROM mentions m
         JOIN chunks c ON m.chunk_id = c.id
@@ -308,12 +333,12 @@ def get_members(db, symbol_id):
         List of (symbol_id, symbol, display_name, start_line, end_line) tuples.
         Function parameters are already filtered out.
     """
-    row = db.execute("SELECT symbol FROM global_symbols WHERE id = ?", (symbol_id,)).fetchone()
+    row = _debug_execute(db, "SELECT symbol FROM global_symbols WHERE id = ?", (symbol_id,)).fetchone()
     if not row:
         return []
     parent_symbol = row[0]
 
-    rows = db.execute("""
+    rows = _debug_execute(db, """
         SELECT gs.id, gs.symbol, gs.display_name, der.start_line, der.end_line
         FROM global_symbols gs
         LEFT JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
@@ -324,7 +349,7 @@ def get_members(db, symbol_id):
     if not rows:
         # Escape LIKE metacharacters in parent_symbol before using as prefix
         escaped_parent = escape_like(parent_symbol)
-        rows = db.execute("""
+        rows = _debug_execute(db, """
             SELECT gs.id, gs.symbol, gs.display_name, der.start_line, der.end_line
             FROM global_symbols gs
             LEFT JOIN defn_enclosing_ranges der ON gs.id = der.symbol_id
@@ -341,7 +366,7 @@ def get_def_location(db, symbol_id):
     Returns:
         Tuple of (relative_path, start_line, end_line) or None
     """
-    return db.execute("""
+    return _debug_execute(db, """
         SELECT d.relative_path, der.start_line, der.end_line
         FROM defn_enclosing_ranges der
         JOIN documents d ON der.document_id = d.id
@@ -408,6 +433,24 @@ def warn_ambiguous(name, matches, context="symbol"):
     print(f"Ambiguous {context} '{name}' ({len(matches)} matches). Using first match: {label}", file=sys.stderr)
 
 
+def format_line_range(start_line, end_line, sep=":"):
+    """Format a line range as a string, handling None values.
+
+    Args:
+        start_line: 0-indexed start line, or None
+        end_line: 0-indexed end line (inclusive), or None
+        sep: separator between values (default ":" for "start:end")
+
+    Returns:
+        Formatted string like "10:20" or "??" if unavailable
+    """
+    if start_line is not None and end_line is not None:
+        return f"{start_line + 1}{sep}{end_line + 1}"
+    if start_line is not None:
+        return f"{start_line + 1}{sep}?"
+    return "??"
+
+
 def setup():
     """Setup command execution: find project root and get DB connection.
     

{scip_cli-1.0.3 → scip_cli-1.1.0/scip_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 1.0.3
+Version: 1.1.0
 Summary: Fast code intelligence via SCIP indexes
 Home-page: https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -40,10 +40,27 @@ Fast code intelligence CLI for TypeScript/JavaScript and Python projects. Query
 
 ### 1. Install scip-cli
 
+**From PyPI:**
+
 ```bash
 pip install scip-cli
 ```
 
+**From source (local development):**
+
+```bash
+git clone https://github.com/flesler/scip-cli.git
+cd scip-cli
+pip install .
+```
+
+For editable development (where `pip install -e .` fails due to permissions):
+
+```bash
+export PYTHONPATH=/path/to/scip-cli:$PYTHONPATH
+python -m scip_cli --help
+```
+
 ### 2. Install prerequisites (optional)
 
 scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
@@ -156,6 +173,19 @@ scip_cli/
     └── skill.py
 ```
 
+## Development
+
+### Debug Logging
+
+Set `SCIP_CLI_DEBUG=1` to enable SQL query logging to stderr:
+
+```bash
+SCIP_CLI_DEBUG=1 scip-cli refs MyFunction
+# Shows: SQL: SELECT ... | params: (...)
+```
+
+This is useful for testing and debugging SQL queries without exposing a `--debug` flag to users.
+
 ## License
 
 MIT

{scip_cli-1.0.3 → scip_cli-1.1.0}/tests/test_pure_functions.py

@@ -3,8 +3,9 @@ import pytest
 import sqlite3
 import tempfile
 from pathlib import Path
-from scip_cli.lib import extract_leaf_name, infer_kind, escape_like, resolve_symbol, resolve_file, read_source_lines, detect_language, SymbolKind
+from scip_cli.lib import extract_leaf_name, infer_kind, escape_like, resolve_symbol, resolve_file, read_source_lines, detect_language, SymbolKind, format_line_range
 from scip_cli.commands.search import parse_symbol, is_noisy_symbol
+from scip_cli.commands.refs import get_exact_refs
 
 
 class TestDetectLanguage:
@@ -391,3 +392,141 @@ class TestReadSourceLines:
 
             lines = read_source_lines(project_root, "nonexistent.ts")
             assert lines is None
+
+
+class TestFormatLineRange:
+    def test_both_defined(self):
+        assert format_line_range(0, 10) == "1:11"
+        assert format_line_range(9, 15) == "10:16"
+
+    def test_only_start_defined(self):
+        assert format_line_range(5, None) == "6:?"
+
+    def test_neither_defined(self):
+        assert format_line_range(None, None) == "??"
+        assert format_line_range(None, 10) == "??"
+
+    def test_custom_separator(self):
+        assert format_line_range(0, 10, sep="-") == "1-11"
+        assert format_line_range(None, None, sep="_") == "??"
+
+
+class TestGetExactRefs:
+    """Tests for get_exact_refs function in refs command."""
+
+    def _create_test_db(self):
+        """Create a test database with minimal schema."""
+        conn = sqlite3.connect(":memory:")
+        conn.executescript("""
+            CREATE TABLE global_symbols (
+                id INTEGER PRIMARY KEY,
+                symbol TEXT,
+                display_name TEXT
+            );
+            CREATE TABLE documents (
+                id INTEGER PRIMARY KEY,
+                relative_path TEXT
+            );
+            CREATE TABLE chunks (
+                id INTEGER PRIMARY KEY,
+                document_id INTEGER,
+                start_line INTEGER,
+                end_line INTEGER
+            );
+            CREATE TABLE mentions (
+                id INTEGER PRIMARY KEY,
+                symbol_id INTEGER,
+                chunk_id INTEGER,
+                role INTEGER
+            );
+        """)
+        return conn
+
+    def test_no_symbol(self):
+        """Test when symbol doesn't exist."""
+        conn = self._create_test_db()
+        refs, hit_limit = get_exact_refs(conn, 999, "/tmp", 10)
+        assert refs == []
+        assert hit_limit is False
+        conn.close()
+
+    def test_no_mentions(self):
+        """Test when symbol exists but has no references."""
+        conn = self._create_test_db()
+        conn.execute(
+            "INSERT INTO global_symbols (id, symbol, display_name) VALUES (?, ?, ?)",
+            (1, "scip-python test/test `test.py`/foo().", "foo")
+        )
+        conn.commit()
+        refs, hit_limit = get_exact_refs(conn, 1, "/tmp", 10)
+        assert refs == []
+        assert hit_limit is False
+        conn.close()
+
+    def test_single_reference(self):
+        """Test with a single reference."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            conn = self._create_test_db()
+            # Create test file
+            test_file = Path(tmpdir) / "test.py"
+            test_file.write_text("def foo():\n    pass\n\nfoo()\n")
+
+            # Insert data
+            conn.execute(
+                "INSERT INTO global_symbols (id, symbol, display_name) VALUES (?, ?, ?)",
+                (1, "scip-python test/test `test.py`/foo().", "foo")
+            )
+            conn.execute(
+                "INSERT INTO documents (id, relative_path) VALUES (?, ?)",
+                (1, "test.py")
+            )
+            conn.execute(
+                "INSERT INTO chunks (id, document_id, start_line, end_line) VALUES (?, ?, ?, ?)",
+                (1, 1, 3, 3)
+            )
+            conn.execute(
+                "INSERT INTO mentions (symbol_id, chunk_id, role) VALUES (?, ?, ?)",
+                (1, 1, 0)
+            )
+            conn.commit()
+
+            refs, hit_limit = get_exact_refs(conn, 1, tmpdir, 10)
+            assert len(refs) == 1
+            assert refs[0] == ("test.py", 4)  # Line 4 (1-indexed)
+            assert hit_limit is False
+            conn.close()
+
+    def test_max_refs_limit(self):
+        """Test that max_refs limit is respected."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            conn = self._create_test_db()
+            # Create test file
+            test_file = Path(tmpdir) / "test.py"
+            test_file.write_text("foo()\nfoo()\nfoo()\n")
+
+            # Insert symbol
+            conn.execute(
+                "INSERT INTO global_symbols (id, symbol, display_name) VALUES (?, ?, ?)",
+                (1, "scip-python test/test `test.py`/foo().", "foo")
+            )
+            conn.execute(
+                "INSERT INTO documents (id, relative_path) VALUES (?, ?)",
+                (1, "test.py")
+            )
+            # Insert 3 mentions
+            for i in range(3):
+                conn.execute(
+                    "INSERT INTO chunks (id, document_id, start_line, end_line) VALUES (?, ?, ?, ?)",
+                    (i + 1, 1, i, i)
+                )
+                conn.execute(
+                    "INSERT INTO mentions (symbol_id, chunk_id, role) VALUES (?, ?, ?)",
+                    (1, i + 1, 0)
+                )
+            conn.commit()
+
+            # Limit to 2 refs
+            refs, hit_limit = get_exact_refs(conn, 1, tmpdir, 2)
+            assert len(refs) == 2
+            assert hit_limit is True
+            conn.close()

scip_cli-1.0.3/scip_cli/commands/refs.py

@@ -1,83 +0,0 @@
-"""refs command - find all references to a symbol."""
-import sys
-
-from ..lib import (
-    setup,
-    resolve_one_symbol,
-    read_source_lines,
-    extract_leaf_name,
-)
-
-
-def get_exact_refs(db, symbol_id, project_root):
-    """Get references with exact line numbers by reading source files."""
-    sym_row = db.execute("SELECT symbol FROM global_symbols WHERE id = ?", (symbol_id,)).fetchone()
-    if not sym_row:
-        return []
-
-    leaf = extract_leaf_name(sym_row[0])
-
-    chunks = db.execute("""
-        SELECT c.id, c.document_id, c.start_line, c.end_line, d.relative_path
-        FROM mentions m
-        JOIN chunks c ON m.chunk_id = c.id
-        JOIN documents d ON c.document_id = d.id
-        WHERE m.symbol_id = ? AND m.role != 1
-    """, (symbol_id,)).fetchall()
-
-    if not chunks:
-        return []
-
-    by_doc = {}
-    for chunk_id, doc_id, start_line, end_line, rel_path in chunks:
-        if doc_id not in by_doc:
-            by_doc[doc_id] = {'path': rel_path, 'chunks': []}
-        by_doc[doc_id]['chunks'].append((chunk_id, start_line, end_line))
-
-    results = []
-
-    for doc_id, info in by_doc.items():
-        rel_path = info['path']
-        min_line = min(c[1] for c in info['chunks'])
-        max_line = max(c[2] for c in info['chunks'])
-
-        lines = read_source_lines(project_root, rel_path, min_line, max_line)
-        if lines is None:
-            for chunk_id, start_line, end_line in info['chunks']:
-                results.append((rel_path, start_line + 1))
-            continue
-
-        for chunk_id, start_line, end_line in info['chunks']:
-            offset = min_line
-            found = False
-            for line_idx in range(start_line - offset, min(end_line - offset + 1, len(lines))):
-                if leaf in lines[line_idx]:
-                    results.append((rel_path, line_idx + offset + 1))
-                    found = True
-                    break
-            if not found:
-                results.append((rel_path, start_line + 1))
-
-    return results
-
-
-def main(args):
-    """Find all references to a symbol."""
-    db, project_root = setup()
-    try:
-        symbol_id, _, _ = resolve_one_symbol(db, args.symbol)
-
-        refs = get_exact_refs(db, symbol_id, project_root)
-
-        if not refs:
-            print(f"No references found for '{args.symbol}'", file=sys.stderr)
-            sys.exit(1)
-
-        seen = set()
-        for path, line in refs:
-            key = (path, line)
-            if key not in seen:
-                seen.add(key)
-                print(f"{path}:{line}")
-    finally:
-        db.close()