scip-cli 1.0.0__tar.gz

scip_cli-1.0.0/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/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include pyproject.toml
+recursive-include scip_cli *.md

scip_cli-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,130 @@
+# 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/pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v"

scip_cli-1.0.0/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-1.0.0/scip_cli/__init__.py

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

scip_cli-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-1.0.0/scip_cli/commands/__init__.py

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

scip_cli-1.0.0/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-1.0.0/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-1.0.0/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)