scip-cli 1.0.0__py3-none-any.whl

scip_cli/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: scip-cli
+description: Read when needing to find symbols, definitions, references, or members in TypeScript/JavaScript code
+---
+
+TypeScript/JavaScript only (.ts, .tsx, .js, .jsx) — not GraphQL, CSS, or other files.
+
+All commands are sub-commands of `scip-cli`. Run from the project root.
+
+## Quick Decision Guide
+
+| 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 |
+| "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 |
+| "What methods does this class have?" | `members ClassName` | All methods/fields with line ranges |
+
+## Gotchas
+
+- **Bare names** resolve functions, types (aliases + interfaces), and classes. Consts/variables need `def --type 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` or a qualified `src:…` name to disambiguate.
+- **First run** in a project may auto-index (one-time wait, ~10-30s for large codebases).
+- **Precision escape hatch**: qualified names like `src:hooks:usePatientEntries:usePatientEntries()` always work.
+
+## Details
+
+### def
+
+```bash
+def [--type <kind>] <symbol>
+```
+
+Kinds: `function`, `class`, `interface`, `type`, `method`, `variable` — use `--type` when the bare name isn't in the default set above.
+
+### refs
+
+```bash
+refs <symbol>
+```
+
+Returns `file:line` for each reference. Reads source files to find exact line numbers.
+
+### search
+
+```bash
+search [--kind <kind>] <pattern>
+```
+
+Returns `file:line Kind symbolName`. Filters noisy symbols (file-level, parameters, type literals).
+
+### symbols
+
+```bash
+symbols <file>
+```
+
+Returns `startLine-endLine kind name` for each symbol in the file.
+
+### rdeps
+
+```bash
+rdeps <file>
+```
+
+Returns list of files that import from this file.
+
+### members
+
+```bash
+members <symbol>
+```
+
+Returns `startLine:endLine kind name` for each member. Note: limited by database coverage — `enclosing_symbol` data is sparse for many indexers.

scip_cli/__init__.py

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

scip_cli/__main__.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""CLI entry point for scip-cli."""
+import argparse
+import sys
+
+from .commands import refs, def_cmd, search, symbols, rdeps, members, skill
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="scip-cli",
+        description="Fast code intelligence via SCIP indexes"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # refs
+    refs_parser = subparsers.add_parser("refs", help="Find references to a symbol")
+    refs_parser.add_argument("symbol", help="Symbol name")
+
+    # def
+    def_parser = subparsers.add_parser("def", help="Find symbol definition")
+    def_parser.add_argument("--type", dest="kind", help="Filter by kind (function, class, etc)")
+    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", help="Filter by kind")
+    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("file", help="File path or pattern")
+
+    # rdeps
+    rdeps_parser = subparsers.add_parser("rdeps", help="Find reverse dependencies of a file")
+    rdeps_parser.add_argument("file", help="File path or pattern")
+
+    # members
+    members_parser = subparsers.add_parser("members", help="List members of a class/interface")
+    members_parser.add_argument("symbol", help="Symbol name")
+
+    # skill
+    skill_parser = subparsers.add_parser("skill", help="Install or dump the scip-cli SKILL.md")
+    skill_parser.add_argument("path", nargs="?", help="Optional file path to write to (creates dirs)")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    # Dispatch to command handlers
+    if args.command == "refs":
+        refs.main(args)
+    elif args.command == "def":
+        def_cmd.main(args)
+    elif args.command == "search":
+        search.main(args)
+    elif args.command == "symbols":
+        symbols.main(args)
+    elif args.command == "rdeps":
+        rdeps.main(args)
+    elif args.command == "members":
+        members.main(args)
+    elif args.command == "skill":
+        skill.main(args)
+
+
+if __name__ == "__main__":
+    main()

scip_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for scip-cli."""

scip_cli/commands/def_cmd.py

@@ -0,0 +1,50 @@
+"""def command - find symbol definitions."""
+import sys
+
+from ..lib import (
+    get_db,
+    resolve_symbol,
+    find_project_root,
+    read_source_lines,
+    infer_kind,
+)
+
+
+def main(args):
+    """Find the definition of a symbol."""
+    db = get_db()
+    
+    symbols = resolve_symbol(db, args.symbol, args.kind)
+    if not symbols:
+        print(f"Symbol '{args.symbol}' not found", file=sys.stderr)
+        sys.exit(1)
+    
+    project_root = find_project_root()
+    if not project_root:
+        print("Error: Could not find project root", file=sys.stderr)
+        sys.exit(1)
+    
+    for symbol_id, symbol_str, display_name in symbols:
+        # Get definition location from defn_enclosing_ranges
+        row = db.execute("""
+            SELECT d.relative_path, der.start_line, der.end_line
+            FROM defn_enclosing_ranges der
+            JOIN documents d ON der.document_id = d.id
+            WHERE der.symbol_id = ?
+        """, (symbol_id,)).fetchone()
+        
+        if not row:
+            continue
+        
+        rel_path, start_line, end_line = row
+        kind = infer_kind(symbol_str)
+        
+        # Read source from filesystem
+        lines = read_source_lines(project_root, rel_path, start_line, end_line)
+        if lines is None:
+            source_snippet = "(could not read source)"
+        else:
+            source_snippet = ''.join(lines).rstrip('\n')
+        
+        print(f"{rel_path}:{start_line + 1}:{end_line + 1}")
+        print(source_snippet)

scip_cli/commands/members.py

@@ -0,0 +1,84 @@
+"""members command - list members of a class/interface."""
+import sys
+import re
+
+from ..lib import (
+    get_db,
+    resolve_symbol,
+    warn_ambiguous,
+    get_members,
+    infer_kind,
+    extract_leaf_name,
+    read_source_lines,
+    find_project_root,
+)
+
+
+def main(args):
+    """List members of a class or interface."""
+    db = get_db()
+    
+    symbols = resolve_symbol(db, args.symbol)
+    if not symbols:
+        print(f"Symbol '{args.symbol}' not found", file=sys.stderr)
+        sys.exit(1)
+    
+    if len(symbols) > 1:
+        warn_ambiguous(args.symbol, symbols, "symbol")
+    
+    symbol_id, symbol_str, display_name = symbols[0]
+    members = get_members(db, symbol_id)
+    
+    if not members:
+        print(f"No members found for '{args.symbol}'", file=sys.stderr)
+        sys.exit(1)
+    
+    # Get parent's file path and line range for fallback
+    project_root = find_project_root()
+    parent_def = db.execute("""
+        SELECT d.relative_path, der.start_line, der.end_line
+        FROM defn_enclosing_ranges der
+        JOIN documents d ON der.document_id = d.id
+        WHERE der.symbol_id = ?
+    """, (symbol_id,)).fetchone()
+    
+    parent_file = parent_def[0] if parent_def else None
+    parent_start = parent_def[1] if parent_def else None
+    parent_end = parent_def[2] if parent_def else None
+    
+    # Check if any members need line number lookup
+    needs_lookup = any(m[3] is None for m in members)
+    
+    # Read source file once if needed
+    source_lines = None
+    if needs_lookup and project_root and parent_file and parent_start is not None:
+        source_lines = read_source_lines(project_root, parent_file, parent_start, parent_end)
+    
+    for member_id, member_symbol, member_name, start_line, end_line in members:
+        kind = infer_kind(member_symbol)
+        short = extract_leaf_name(member_symbol)
+        
+        # Skip function parameters (they have ().( in the symbol)
+        if ").(" in member_symbol:
+            continue
+        
+        # If no line numbers from DB, try to find in source
+        if start_line is None and source_lines:
+            if "<constructor>" in member_symbol:
+                pattern = rf'^\s*constructor\s*\('
+            elif "<get>" in member_symbol:
+                pattern = rf'^\s*(?:public\s+|private\s+|protected\s+|static\s+|readonly\s+)*get\s+{re.escape(short)}\s*\('
+            elif "<set>" in member_symbol:
+                pattern = rf'^\s*(?:public\s+|private\s+|protected\s+|static\s+)*set\s+{re.escape(short)}\s*\('
+            else:
+                # Regular property/method - handle TypeScript modifiers
+                pattern = rf'^\s*(?:public\s+|private\s+|protected\s+|static\s+|readonly\s+)*{re.escape(short)}\s*\??\s*[:=(]'
+            
+            for i, line in enumerate(source_lines):
+                if re.match(pattern, line):
+                    start_line = parent_start + i
+                    end_line = start_line
+                    break
+        
+        line_info = f"{start_line + 1}:{end_line + 1}" if start_line is not None else "??"
+        print(f"{line_info} {kind} {short}")

scip_cli/commands/rdeps.py

@@ -0,0 +1,52 @@
+"""rdeps command - find reverse dependencies of a file."""
+import sys
+
+from ..lib import (
+    get_db,
+    resolve_file,
+    warn_ambiguous,
+    get_file_symbols,
+    get_refs_for_symbols,
+)
+
+
+def main(args):
+    """Find all files that import from this file."""
+    db = get_db()
+    
+    # Resolve file pattern to actual path
+    files = resolve_file(db, args.file)
+    if not files:
+        print(f"File '{args.file}' not found", file=sys.stderr)
+        sys.exit(1)
+    
+    if len(files) > 1:
+        warn_ambiguous(args.file, files, "file")
+    
+    file_path = files[0]
+    
+    # Get all symbols defined in this file
+    symbols = get_file_symbols(db, file_path)
+    if not symbols:
+        print(f"No symbols found in '{file_path}'", file=sys.stderr)
+        sys.exit(1)
+    
+    # Get all symbol IDs
+    symbol_ids = [s[0] for s in symbols]
+    
+    # Find all references to these symbols from OTHER files in one query
+    refs = get_refs_for_symbols(db, symbol_ids)
+    
+    # Collect unique file paths that reference this file
+    rdeps = set()
+    for symbol_id, ref_list in refs.items():
+        for ref_path, ref_line in ref_list:
+            if ref_path != file_path:
+                rdeps.add(ref_path)
+    
+    if not rdeps:
+        print(f"No reverse dependencies found for '{file_path}'", file=sys.stderr)
+        sys.exit(1)
+    
+    for dep_path in sorted(rdeps):
+        print(dep_path)

scip_cli/commands/refs.py

@@ -0,0 +1,107 @@
+"""refs command - find all references to a symbol."""
+import sys
+
+from ..lib import (
+    get_db,
+    resolve_symbol,
+    warn_ambiguous,
+    find_project_root,
+    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."""
+    # Get symbol name once
+    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])
+    
+    # Get all chunks that reference this symbol
+    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 []
+    
+    # Group by document
+    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 each document, read source and find exact lines
+    for doc_id, info in by_doc.items():
+        rel_path = info['path']
+        
+        # Get min/max line range for this document
+        min_line = min(c[1] for c in info['chunks'])
+        max_line = max(c[2] for c in info['chunks'])
+        
+        # Read only the needed range
+        lines = read_source_lines(project_root, rel_path, min_line, max_line)
+        if lines is None:
+            # If can't read file, fall back to chunk start lines
+            for chunk_id, start_line, end_line in info['chunks']:
+                results.append((rel_path, start_line + 1))
+            continue
+        
+        # Search for the symbol in each chunk's line range
+        for chunk_id, start_line, end_line in info['chunks']:
+            # Search within the chunk range (adjusted for offset)
+            offset = min_line
+            for line_idx in range(start_line - offset, min(end_line - offset + 1, len(lines))):
+                line = lines[line_idx]
+                # Simple check: does the line contain the symbol name?
+                if leaf in line:
+                    results.append((rel_path, line_idx + offset + 1))
+                    break  # One match per chunk is enough
+            else:
+                # Fallback to chunk start line
+                results.append((rel_path, start_line + 1))
+    
+    return results
+
+
+def main(args):
+    """Find all references to a symbol."""
+    db = get_db()
+    
+    symbols = resolve_symbol(db, args.symbol)
+    if not symbols:
+        print(f"Symbol '{args.symbol}' not found", file=sys.stderr)
+        sys.exit(1)
+    
+    warn_ambiguous(args.symbol, symbols, "symbol")
+    
+    symbol_id, symbol_str, display_name = symbols[0]
+    
+    project_root = find_project_root()
+    if not project_root:
+        print("Error: Could not find project root", file=sys.stderr)
+        sys.exit(1)
+    
+    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)
+    
+    # Deduplicate and sort
+    seen = set()
+    for path, line in refs:
+        key = (path, line)
+        if key not in seen:
+            seen.add(key)
+            print(f"{path}:{line}")

scip_cli/commands/search.py

@@ -0,0 +1,120 @@
+"""search command - search symbols by pattern."""
+import sys
+import re
+
+from ..lib import (
+    get_db,
+    infer_kind,
+)
+
+
+def parse_symbol(symbol):
+    """Parse SCIP symbol into (file_path, symbol_name).
+    
+    Example:
+        scip-typescript npm rovetia-app 1.2 src/hooks/`useDictation.ts`/useDictation().
+        -> ('src/hooks/useDictation.ts', 'useDictation()')
+    """
+    # Find the backtick-wrapped file path
+    match = re.search(r'`([^`]+)`', symbol)
+    if not match:
+        return ('?', '?')
+    
+    filename = match.group(1)
+    
+    # Get the directory path before the backtick
+    before = symbol[:match.start()]
+    # Extract path after version (4th space-separated token)
+    parts = before.split()
+    if len(parts) >= 5:
+        dir_path = ' '.join(parts[4:])
+        file_path = dir_path + filename
+    else:
+        file_path = filename
+    
+    # Symbol name is everything after the closing backtick + /
+    after_file = symbol[match.end():]
+    if after_file.startswith('/'):
+        after_file = after_file[1:]
+    
+    # Remove trailing .
+    symbol_name = after_file.rstrip('.')
+    
+    return (file_path, symbol_name)
+
+
+def is_noisy_symbol(symbol_str):
+    """Filter out noisy symbols (file-level, parameters, etc)."""
+    # File-level symbol (ends with /)
+    if symbol_str.endswith('/'):
+        return True
+    
+    # Parameters (contain 0: like "phrases0:")
+    if re.search(r'\d+:', symbol_str):
+        return True
+    
+    # Anonymous type literals (contain "typeLiteral")
+    if 'typeLiteral' in symbol_str:
+        return True
+    
+    # Function parameters (like "isNotSupportedError().(err)")
+    if ').(' in symbol_str:
+        return True
+    
+    return False
+
+
+def kind_to_display(kind):
+    """Convert kind to display format (capitalized like bash version)."""
+    kind_map = {
+        'function': 'Function',
+        'method': 'Method',
+        'class': 'Class',
+        'interface': 'Interface',
+        'type': 'TypeAlias',
+        'variable': 'Variable',
+    }
+    return kind_map.get(kind, 'Unknown')
+
+
+def main(args):
+    """Search symbols by pattern."""
+    db = get_db()
+    
+    # Search symbols with line numbers in one query
+    rows = db.execute("""
+        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 ?
+        LIMIT 100
+    """, (f"%{args.pattern}%",)).fetchall()
+    
+    if not rows:
+        print(f"No symbols found matching '{args.pattern}'", file=sys.stderr)
+        sys.exit(1)
+    
+    # Filter by kind if requested
+    if args.kind:
+        rows = [r for r in rows if infer_kind(r[1]) == args.kind]
+        if not rows:
+            print(f"No {args.kind} symbols found matching '{args.pattern}'", file=sys.stderr)
+            sys.exit(1)
+    
+    for symbol_id, symbol_str, display_name, start_line in rows:
+        # Skip noisy symbols
+        if is_noisy_symbol(symbol_str):
+            continue
+        
+        kind = infer_kind(symbol_str)
+        file_path, symbol_name = parse_symbol(symbol_str)
+        
+        line = start_line + 1 if start_line is not None else 0
+        
+        # Clean up symbol name: remove SCIP notation
+        symbol_name = symbol_name.rstrip('.#')
+        if symbol_name.endswith('()'):
+            symbol_name = symbol_name[:-2]
+        
+        kind_display = kind_to_display(kind)
+        print(f"{file_path}:{line} {kind_display} {symbol_name}")

scip_cli/commands/skill.py

@@ -0,0 +1,24 @@
+"""skill command - install the scip-cli skill file."""
+import sys
+from pathlib import Path
+
+
+def main(args):
+    """Dump or install the scip-cli SKILL.md."""
+    skill_path = Path(__file__).parent.parent / "SKILL.md"
+    
+    if not skill_path.exists():
+        print("Error: SKILL.md not found in package", file=sys.stderr)
+        sys.exit(1)
+    
+    content = skill_path.read_text()
+    
+    if args.path:
+        # Write to file, creating parent directories
+        target = Path(args.path).expanduser()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content)
+        print(f"Installed skill to {target}")
+    else:
+        # Print to stdout
+        print(content)

scip_cli/commands/symbols.py

@@ -0,0 +1,42 @@
+"""symbols command - list symbols in a file."""
+import sys
+
+from ..lib import (
+    get_db,
+    resolve_file,
+    warn_ambiguous,
+    get_file_symbols,
+    infer_kind,
+    extract_leaf_name,
+)
+
+
+def main(args):
+    """List all symbols in a file."""
+    db = get_db()
+    
+    # Resolve file pattern to actual path
+    files = resolve_file(db, args.file)
+    if not files:
+        print(f"File '{args.file}' not found", file=sys.stderr)
+        sys.exit(1)
+    
+    if len(files) > 1:
+        warn_ambiguous(args.file, files, "file")
+    
+    file_path = files[0]
+    
+    # Get all symbols defined in this file
+    symbols = get_file_symbols(db, file_path)
+    if not symbols:
+        print(f"No symbols found in '{file_path}'", file=sys.stderr)
+        sys.exit(1)
+    
+    for symbol_id, symbol_str, display_name, start_line, end_line in symbols:
+        # Skip file-level symbols (end with /)
+        if symbol_str.endswith('/'):
+            continue
+        kind = infer_kind(symbol_str)
+        short = extract_leaf_name(symbol_str)
+        line_info = f"{start_line + 1}-{end_line + 1}" if start_line is not None else "??"
+        print(f"{line_info} {kind} {short}")

scip_cli/lib.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+"""Common utilities for read-symbol Python scripts."""
+import hashlib
+import os
+import sqlite3
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def find_project_root(start_dir=None):
+    """Walk up from start_dir (or cwd) to find project root."""
+    markers = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"]
+    d = Path(start_dir or os.getcwd()).resolve()
+    while d != d.parent:
+        if any((d / m).exists() for m in markers):
+            return d
+        d = d.parent
+    return None
+
+
+def detect_language(project_root):
+    """Detect language from project markers.
+    
+    Returns: 'typescript', 'python', 'rust', 'go', or 'typescript' (default)
+    """
+    root = Path(project_root)
+    if (root / "tsconfig.json").exists() or (root / "package.json").exists():
+        return "typescript"
+    elif (root / "pyproject.toml").exists() or (root / "setup.py").exists():
+        return "python"
+    elif (root / "Cargo.toml").exists():
+        return "rust"
+    elif (root / "go.mod").exists():
+        return "go"
+    else:
+        return "typescript"  # default
+
+
+def find_db(project_root=None):
+    """Find the index.db for the given project (or cwd)."""
+    root = project_root or find_project_root()
+    if not root:
+        return None
+    h = hashlib.sha256(str(root).encode()).hexdigest()[:12]
+    cache = Path.home() / ".cache" / "scip-query" / "projects" / h / "index.db"
+    if cache.exists():
+        return cache
+    return None
+
+
+def get_db(project_root=None):
+    """Get a sqlite3 connection to the index.db.
+    
+    If no index exists, auto-index the project with the detected language.
+    """
+    db_path = find_db(project_root)
+    if not db_path:
+        # Auto-index
+        root = project_root or find_project_root()
+        if not root:
+            print("Error: Could not find project root", file=sys.stderr)
+            sys.exit(1)
+        
+        lang = detect_language(root)
+        print(f"Auto-indexing {root} ({lang})...", file=sys.stderr)
+        
+        # Create cache directory
+        h = hashlib.sha256(str(root).encode()).hexdigest()[:12]
+        cache_dir = Path.home() / ".cache" / "scip-query" / "projects" / h
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        
+        # Run language-specific indexer
+        with tempfile.TemporaryDirectory() as tmpdir:
+            index_scip = os.path.join(tmpdir, "index.scip")
+            
+            if lang == "typescript":
+                indexer_cmd = ["scip-typescript", "index", "--output", index_scip]
+            elif lang == "python":
+                indexer_cmd = ["scip-python", "index", ".", "--output", index_scip]
+            else:
+                print(f"Error: Unsupported language '{lang}'", file=sys.stderr)
+                sys.exit(1)
+            
+            result = subprocess.run(
+                indexer_cmd,
+                cwd=str(root),
+                capture_output=True,
+                text=True
+            )
+            
+            if result.returncode != 0:
+                print(f"Error: Failed to index project", file=sys.stderr)
+                print(result.stderr, file=sys.stderr)
+                sys.exit(1)
+            
+            # Convert index.scip to index.db
+            index_db = cache_dir / "index.db"
+            result = subprocess.run(
+                ["scip", "expt-convert", index_scip, "--output", str(index_db)],
+                capture_output=True,
+                text=True
+            )
+            
+            if result.returncode != 0:
+                print(f"Error: Failed to convert index", file=sys.stderr)
+                print(result.stderr, file=sys.stderr)
+                sys.exit(1)
+        
+        # Try again
+        db_path = find_db(project_root)
+        if not db_path:
+            print("Error: No index.db found after indexing", file=sys.stderr)
+            sys.exit(1)
+    
+    return sqlite3.connect(str(db_path))
+
+
+def infer_kind(symbol):
+    """Infer symbol kind from symbol string pattern.
+    
+    Returns: 'function', 'method', 'class', 'interface', 'type', 'property', 'variable', or 'unknown'
+    """
+    # Method: has # in middle and ends with ().
+    if "#" in symbol and symbol.endswith("()."):
+        return "method"
+    # Function: ends with (). but no # before it
+    if symbol.endswith("().") and "#" not in symbol.split("/")[-1]:
+        return "function"
+    # Class: ends with # and name starts with uppercase
+    if symbol.endswith("#"):
+        name = symbol.split("/")[-1].rstrip("#")
+        if name and name[0].isupper():
+            # Could be class or interface - check if it's an interface
+            # Interfaces often have "Interface" in display_name or are in .d.ts
+            return "class"  # default to class
+    # Type alias: ends with # and name starts with uppercase (but not class)
+    if symbol.endswith("#"):
+        return "type"
+    # Property: type literal property (ParentClass#typeLiteral0:propertyName.)
+    if "#typeLiteral" in symbol and ":" in symbol and symbol.endswith("."):
+        return "property"
+    # Variable/const: ends with . but not ()
+    if symbol.endswith(".") and not symbol.endswith("()."):
+        return "variable"
+    return "unknown"
+
+
+def resolve_symbol(db, name, kind_filter=None):
+    """Resolve bare name to symbol_id(s).
+    
+    Args:
+        db: sqlite3 connection
+        name: bare symbol name (e.g., "useDictation")
+        kind_filter: optional kind filter ('function', 'class', etc)
+    
+    Returns:
+        List of (symbol_id, symbol, display_name) tuples
+    """
+    # Try exact leaf match first with single query using OR
+    rows = db.execute("""
+        SELECT id, symbol, display_name FROM global_symbols 
+        WHERE symbol LIKE ? OR symbol LIKE ? OR symbol LIKE ?
+    """, (
+        f"%/{name}().",      # function/method
+        f"%/{name}#",        # class/interface/type
+        f"%/{name}.",        # variable/property
+    )).fetchall()
+    
+    results = list(rows)
+    
+    # If no exact match, try contains
+    if not results:
+        rows = db.execute(
+            "SELECT id, symbol, display_name FROM global_symbols WHERE symbol LIKE ?",
+            (f"%{name}%",)
+        ).fetchall()
+        # Filter to leaf matches (name appears after last /)
+        results = [r for r in rows if name in r[1].split("/")[-1]]
+    
+    # Apply kind filter if provided
+    if kind_filter and results:
+        filtered = [r for r in results if infer_kind(r[1]) == kind_filter]
+        if filtered:
+            results = filtered
+    
+    return results
+
+
+def resolve_file(db, file_pattern):
+    """Resolve file pattern to relative_path.
+    
+    Args:
+        db: sqlite3 connection
+        file_pattern: file path or pattern (e.g., "useDictation" or "src/hooks/useDictation.ts")
+    
+    Returns:
+        List of matching relative_paths
+    """
+    # Try exact match first
+    rows = db.execute(
+        "SELECT relative_path FROM documents WHERE relative_path = ?",
+        (file_pattern,)
+    ).fetchall()
+    if rows:
+        return [r[0] for r in rows]
+    
+    # Try LIKE match
+    if "/" not in file_pattern and "." not in file_pattern:
+        # Bare name - search in filename
+        pattern = f"%{file_pattern}%"
+    else:
+        pattern = file_pattern.replace("*", "%")
+    
+    rows = db.execute(
+        "SELECT relative_path FROM documents WHERE relative_path LIKE ?",
+        (pattern,)
+    ).fetchall()
+    return [r[0] for r in rows]
+
+
+def get_file_symbols(db, relative_path):
+    """Get all symbols defined in a file.
+    
+    Returns:
+        List of (symbol_id, symbol, display_name, start_line, end_line) tuples
+    """
+    rows = db.execute("""
+        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()
+    return rows
+
+
+def get_refs_for_symbols(db, symbol_ids):
+    """Get all references for multiple symbol_ids in one query.
+    
+    Args:
+        db: sqlite3 connection
+        symbol_ids: list of symbol IDs
+    
+    Returns:
+        Dict mapping symbol_id -> list of (relative_path, start_line) tuples
+    """
+    if not symbol_ids:
+        return {}
+    
+    placeholders = ','.join('?' * len(symbol_ids))
+    rows = db.execute(f"""
+        SELECT m.symbol_id, d.relative_path, c.start_line
+        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 IN ({placeholders}) AND m.role != 1
+    """, symbol_ids).fetchall()
+    
+    result = {}
+    for symbol_id, path, line in rows:
+        if symbol_id not in result:
+            result[symbol_id] = []
+        result[symbol_id].append((path, line))
+    
+    return result
+
+
+def get_members(db, symbol_id):
+    """Get members (children) of a symbol.
+    
+    Returns:
+        List of (symbol_id, symbol, display_name, start_line, end_line) tuples
+    """
+    # Get the symbol string for this symbol_id
+    row = db.execute("SELECT symbol FROM global_symbols WHERE id = ?", (symbol_id,)).fetchone()
+    if not row:
+        return []
+    parent_symbol = row[0]
+    
+    # Try enclosing_symbol first
+    rows = db.execute("""
+        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
+        WHERE gs.enclosing_symbol = ?
+        ORDER BY der.start_line
+    """, (parent_symbol,)).fetchall()
+    
+    # Fall back to symbol prefix matching if no results
+    if not rows:
+        rows = db.execute("""
+            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
+            WHERE gs.symbol LIKE ? AND gs.symbol != ?
+            ORDER BY der.start_line
+        """, (parent_symbol + '%', parent_symbol)).fetchall()
+    
+    # Filter out function parameters (contain "().(" pattern)
+    rows = [r for r in rows if ").(" not in r[1]]
+    
+    return rows
+
+
+def extract_leaf_name(symbol_str):
+    """Extract the leaf name from a SCIP symbol string.
+    
+    Example:
+        .../useDictationOrRecording(). -> useDictationOrRecording
+        .../UseDictationOrRecordingOptions# -> UseDictationOrRecordingOptions
+        .../UseDictationOrRecordingOptions#typeLiteral0:onFallbackToRecording. -> onFallbackToRecording
+        .../GameEngine#config. -> config
+        .../GameEngine#`<get>aliveHeroes`(). -> aliveHeroes
+    """
+    leaf = symbol_str.split("/")[-1].rstrip(".#")
+    if leaf.endswith("()"):
+        leaf = leaf[:-2]
+    # Handle type literal properties (ParentClass#typeLiteral0:propertyName)
+    if ":" in leaf:
+        leaf = leaf.split(":")[-1]
+    # Handle class members (ParentClass#memberName)
+    if "#" in leaf:
+        leaf = leaf.split("#")[-1]
+    # Remove backticks
+    leaf = leaf.replace("`", "")
+    # Handle getters/setters: <get>name -> name
+    if leaf.startswith("<get>"):
+        leaf = leaf[5:]
+    elif leaf.startswith("<set>"):
+        leaf = leaf[5:]
+    return leaf
+
+
+def read_source_lines(project_root, relative_path, start_line=None, end_line=None):
+    """Read source lines from filesystem.
+    
+    Args:
+        project_root: Project root path
+        relative_path: Relative path to file
+        start_line: Optional start line (0-indexed)
+        end_line: Optional end line (0-indexed, inclusive)
+    
+    Returns:
+        List of lines, or None if file cannot be read
+    """
+    full_path = os.path.join(str(project_root), relative_path)
+    try:
+        with open(full_path, 'r', encoding='utf-8') as f:
+            lines = f.readlines()
+            if start_line is not None and end_line is not None:
+                return lines[start_line:end_line + 1]
+            return lines
+    except Exception:
+        return None
+
+
+def warn_ambiguous(name, matches, context="symbol"):
+    """Print warning if multiple matches found.
+    
+    Args:
+        name: The search pattern
+        matches: List of matches
+        context: Description of what was searched (e.g., "symbol", "file")
+    """
+    if len(matches) > 1:
+        print(f"Ambiguous {context} '{name}' ({len(matches)} matches). Using first match: {matches[0][1] if isinstance(matches[0], tuple) else matches[0]}", file=sys.stderr)

scip_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: scip-cli
+Version: 1.0.0
+Summary: Fast code intelligence via SCIP indexes
+Home-page: https://github.com/flesler/scip-cli
+Author: Ariel Flesler
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+# scip-cli
+
+[![PyPI version](https://badge.fury.io/py/scip-cli.svg)](https://badge.fury.io/py/scip-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Fast code intelligence CLI for TypeScript/JavaScript projects. Query SCIP indexes directly via SQLite for instant results.
+
+## Features
+
+- **Fast**: Direct SQLite queries, 100-500x faster than bash wrappers
+- **Simple**: Single binary with subcommands
+- **Auto-indexing**: Automatically indexes projects on first query
+- **Token-efficient**: Clean, minimal output optimized for AI consumption
+
+## Installation
+
+### 1. Install scip-cli
+
+```bash
+pip install scip-cli
+```
+
+### 2. Install prerequisites
+
+scip-cli requires two external tools for indexing:
+
+**For TypeScript/JavaScript projects:**
+
+```bash
+# Install scip-typescript (SCIP indexer)
+npm install -g @sourcegraph/scip-typescript
+
+# Install scip (SCIP CLI for index conversion)
+npm install -g @sourcegraph/scip
+```
+
+**Verify installation:**
+
+```bash
+scip-cli --help
+scip-typescript --version
+scip --version
+```
+
+## Prerequisites
+
+- Python 3.7+
+- `scip-typescript` (for indexing TypeScript/JavaScript)
+- `scip` CLI (for converting indexes)
+
+## Usage
+
+All commands are subcommands of `scip-cli`:
+
+```bash
+scip-cli <command> [arguments]
+```
+
+### Commands
+
+- `refs <symbol>` - Find all references to a symbol
+- `def <symbol>` - Find symbol definition with source code
+- `search <pattern>` - Search symbols by name pattern
+- `symbols <file>` - List all symbols in a file
+- `rdeps <file>` - Find files that depend on a file
+- `members <symbol>` - List members of a class/interface
+- `skill [path]` - Install or dump the SKILL.md
+
+### Examples
+
+```bash
+# Find where useDictation is used
+scip-cli refs useDictation
+
+# Get definition of useDictation
+scip-cli def useDictation
+
+# Search for symbols matching "Dictation"
+scip-cli search Dictation
+
+# List symbols in a file
+scip-cli symbols src/hooks/useDictation.ts
+
+# Find files that import from useDictation.ts
+scip-cli rdeps src/hooks/useDictation.ts
+
+# List members of a class
+scip-cli members UseDictationOptions
+
+# Install skill file
+scip-cli skill ~/.claude/skills/scip/SKILL.md
+```
+
+## How It Works
+
+1. On first query, automatically indexes the project using `scip-typescript`
+2. Converts the SCIP index to SQLite using `scip expt-convert`
+3. Caches the database in `~/.cache/scip-query/projects/<hash>/index.db`
+4. Subsequent queries are instant SQLite lookups
+
+## Performance
+
+Compared to bash wrappers:
+- `refs`: 6.4s → 0.03s (213x faster)
+- `def`: 2.8s → 0.05s (56x faster)
+- `search`: 2.6s → 0.03s (87x faster)
+- `symbols`: 0.3s → 0.02s (15x faster)
+- `rdeps`: 0.2s → 0.02s (10x faster)
+- `members`: 3.1s → 0.03s (103x faster)
+
+## Architecture
+
+```
+scip_cli/
+├── __init__.py
+├── __main__.py    # CLI entry point
+├── lib.py         # Core utilities (indexing, symbol resolution)
+└── commands/      # Subcommand implementations
+    ├── refs.py
+    ├── def_cmd.py
+    ├── search.py
+    ├── symbols.py
+    ├── rdeps.py
+    ├── members.py
+    └── skill.py
+```
+
+## License
+
+MIT

scip_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+scip_cli/SKILL.md,sha256=FegRCcs89-zfgRYRIK-jEER8Oo7W1mfH_nh6TcJ9Pnc,2565
+scip_cli/__init__.py,sha256=n7LqaekbFRVz8NfgMtvorJznVidEAbvYHnCwq4UmhrE,79
+scip_cli/__main__.py,sha256=fF4bAaprUmJwo7qc8T2h4DMMdcE39ky9LoypKhvJmPg,2346
+scip_cli/lib.py,sha256=43oqd8wry7mZo0bd_-jUJAq8ApD-tKFOA9nSSeuiiJs,12552
+scip_cli/commands/__init__.py,sha256=kPFvjkdKpwb__8ce7gmDLM0Shi7aCNCjYCoctY8NxQw,36
+scip_cli/commands/def_cmd.py,sha256=jGywWvbYbnSM0XqwNz0xV7ZFpYOQP73SuZQHqqDLBrY,1489
+scip_cli/commands/members.py,sha256=6ayDcEXicbAKAKE0-M82viesZVkGgRSOrV1t47_MVL4,3112
+scip_cli/commands/rdeps.py,sha256=oQIYtkqUZNJ_NOAitz3tl-Wn6ZGbwjY2jec99wpVYpo,1409
+scip_cli/commands/refs.py,sha256=z_jBTMXxtElSBycchrR2ZNqmtdVJ4TMEWYArkW0hAU0,3531
+scip_cli/commands/search.py,sha256=gYt0F7DRnh3fnx76yiPAes4sPGe7YnGYSxGPCljti8g,3500
+scip_cli/commands/skill.py,sha256=34MtCB8K5zeOwr2IoH34O9VcwDgZXMqo0bFZ2_DdDY0,706
+scip_cli/commands/symbols.py,sha256=IEQo2iAlPAVlhSwGdJ17Egi0GLik9pQAmI9KsCG19Jc,1174
+scip_cli-1.0.0.dist-info/licenses/LICENSE,sha256=lFrvF9tXp4iR2I6tUUH1uZn2Fi3-YO2zftDzjHG7jeY,1070
+scip_cli-1.0.0.dist-info/METADATA,sha256=78WMIKLkzB7HOy3jywtwyQeYwOPd-8z1qE2GB7Th6zE,3838
+scip_cli-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scip_cli-1.0.0.dist-info/entry_points.txt,sha256=UhydAcSviNn3eyCU0DHIKqTsUYs9PEFCbT5Ks6yAPOQ,52
+scip_cli-1.0.0.dist-info/top_level.txt,sha256=oyGHgK3piiQuYzJ0_H7unVzQOMdsIjIk6yX05o6-zXc,9
+scip_cli-1.0.0.dist-info/RECORD,,

scip_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scip_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scip-cli = scip_cli.__main__:main

scip_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel Flesler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scip_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scip_cli