scip-cli 1.0.3__tar.gz → 1.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- scip_cli-1.2.0/PKG-INFO +267 -0
- scip_cli-1.2.0/README.md +243 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/pyproject.toml +3 -0
- scip_cli-1.2.0/scip_cli/SKILL.md +108 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/__init__.py +1 -1
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/__main__.py +49 -2
- scip_cli-1.2.0/scip_cli/cache.py +34 -0
- scip_cli-1.2.0/scip_cli/cli_args.py +33 -0
- scip_cli-1.2.0/scip_cli/commands/def_cmd.py +57 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/members.py +22 -13
- scip_cli-1.2.0/scip_cli/commands/rdeps.py +46 -0
- scip_cli-1.2.0/scip_cli/commands/refs.py +136 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/reindex.py +3 -1
- scip_cli-1.2.0/scip_cli/commands/search.py +212 -0
- scip_cli-1.2.0/scip_cli/commands/symbols.py +37 -0
- scip_cli-1.2.0/scip_cli/config.py +67 -0
- scip_cli-1.2.0/scip_cli/constants.py +7 -0
- scip_cli-1.2.0/scip_cli/discover.py +128 -0
- scip_cli-1.2.0/scip_cli/indexing.py +292 -0
- scip_cli-1.2.0/scip_cli/lib.py +64 -0
- scip_cli-1.2.0/scip_cli/merge.py +174 -0
- scip_cli-1.2.0/scip_cli/output.py +112 -0
- scip_cli-1.2.0/scip_cli/paths.py +48 -0
- scip_cli-1.2.0/scip_cli/project.py +29 -0
- scip_cli-1.2.0/scip_cli/queries.py +320 -0
- scip_cli-1.2.0/scip_cli/scip_tool.py +150 -0
- scip_cli-1.2.0/scip_cli/session.py +46 -0
- scip_cli-1.2.0/scip_cli/source.py +65 -0
- scip_cli-1.2.0/scip_cli/sql.py +24 -0
- scip_cli-1.2.0/scip_cli/symbols.py +133 -0
- scip_cli-1.2.0/scip_cli.egg-info/PKG-INFO +267 -0
- scip_cli-1.2.0/scip_cli.egg-info/SOURCES.txt +49 -0
- scip_cli-1.2.0/tests/test_cache.py +22 -0
- scip_cli-1.2.0/tests/test_composability.py +181 -0
- scip_cli-1.2.0/tests/test_config.py +56 -0
- scip_cli-1.2.0/tests/test_discover.py +118 -0
- scip_cli-1.2.0/tests/test_indexer_env.py +36 -0
- scip_cli-1.2.0/tests/test_merge.py +136 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/tests/test_pure_functions.py +296 -25
- scip_cli-1.2.0/tests/test_scip_tool.py +17 -0
- scip_cli-1.2.0/tests/test_smoke_cli.py +157 -0
- scip_cli-1.2.0/tests/test_typescript_projects.py +53 -0
- scip_cli-1.0.3/PKG-INFO +0 -161
- scip_cli-1.0.3/README.md +0 -137
- scip_cli-1.0.3/scip_cli/SKILL.md +0 -75
- scip_cli-1.0.3/scip_cli/commands/def_cmd.py +0 -39
- scip_cli-1.0.3/scip_cli/commands/rdeps.py +0 -39
- scip_cli-1.0.3/scip_cli/commands/refs.py +0 -83
- scip_cli-1.0.3/scip_cli/commands/search.py +0 -131
- scip_cli-1.0.3/scip_cli/commands/symbols.py +0 -35
- scip_cli-1.0.3/scip_cli/lib.py +0 -462
- scip_cli-1.0.3/scip_cli.egg-info/PKG-INFO +0 -161
- scip_cli-1.0.3/scip_cli.egg-info/SOURCES.txt +0 -24
- {scip_cli-1.0.3 → scip_cli-1.2.0}/LICENSE +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/MANIFEST.in +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/__init__.py +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/skill.py +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli.egg-info/dependency_links.txt +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli.egg-info/entry_points.txt +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli.egg-info/top_level.txt +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/setup.cfg +0 -0
- {scip_cli-1.0.3 → scip_cli-1.2.0}/setup.py +0 -0
scip_cli-1.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: scip-cli
|
|
3
|
+
Version: 1.2.0
|
|
4
|
+
Summary: Fast code intelligence via SCIP indexes
|
|
5
|
+
Home-page: https://github.com/flesler/scip-cli
|
|
6
|
+
Author: Ariel Flesler
|
|
7
|
+
License: MIT
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Topic :: Software Development :: Code Generators
|
|
12
|
+
Requires-Python: >=3.9
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Dynamic: author
|
|
16
|
+
Dynamic: classifier
|
|
17
|
+
Dynamic: description
|
|
18
|
+
Dynamic: description-content-type
|
|
19
|
+
Dynamic: home-page
|
|
20
|
+
Dynamic: license
|
|
21
|
+
Dynamic: license-file
|
|
22
|
+
Dynamic: requires-python
|
|
23
|
+
Dynamic: summary
|
|
24
|
+
|
|
25
|
+
# scip-cli
|
|
26
|
+
|
|
27
|
+
[](https://badge.fury.io/py/scip-cli)
|
|
28
|
+
[](https://opensource.org/licenses/MIT)
|
|
29
|
+
|
|
30
|
+
Fast code intelligence CLI for TypeScript/JavaScript and Python projects. Query SCIP indexes directly via SQLite for instant results.
|
|
31
|
+
|
|
32
|
+
## Features
|
|
33
|
+
|
|
34
|
+
- **Fast**: Direct SQLite queries, eliminating skippable overhead
|
|
35
|
+
- **Simple**: Single binary with subcommands
|
|
36
|
+
- **Auto-indexing**: Automatically indexes projects on first query
|
|
37
|
+
- **Token-efficient**: Clean, minimal output optimized for AI consumption
|
|
38
|
+
|
|
39
|
+
## For AI Agents
|
|
40
|
+
|
|
41
|
+
If you're an AI agent, run this to see the quick reference:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
scip-cli skill
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Or install it to your skills folder:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
This enables commands like `def`, `refs`, `search`, `symbols`, `rdeps`, and `members` - just ask "where is X?" or "find references to X".
|
|
54
|
+
|
|
55
|
+
## Installation
|
|
56
|
+
|
|
57
|
+
### 1. Install scip-cli
|
|
58
|
+
|
|
59
|
+
**From PyPI:**
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
pip install scip-cli
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**From source (local development):**
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
git clone https://github.com/flesler/scip-cli.git
|
|
69
|
+
cd scip-cli
|
|
70
|
+
pip install .
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
For editable development (where `pip install -e .` fails due to permissions):
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
export PYTHONPATH=/path/to/scip-cli:$PYTHONPATH
|
|
77
|
+
python -m scip_cli --help
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### 2. Install prerequisites (optional)
|
|
81
|
+
|
|
82
|
+
scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
|
|
83
|
+
|
|
84
|
+
**Option A: Zero extra setup (recommended)**
|
|
85
|
+
|
|
86
|
+
Install `scip-cli` and run it. On first index, scip-cli will:
|
|
87
|
+
|
|
88
|
+
- Download `scip-typescript` / `scip-python` via `npx` when needed
|
|
89
|
+
- Download the `scip` converter binary from [GitHub releases](https://github.com/scip-code/scip/releases) into `~/.cache/scip-cli/bin/` when not already on PATH
|
|
90
|
+
|
|
91
|
+
No `.scip-cli.json` required — TypeScript monorepos are discovered by walking the repo for `tsconfig*.json` files (skipping `node_modules`, `.git`, etc.).
|
|
92
|
+
|
|
93
|
+
**Option B: Install globally for better performance**
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
# TypeScript/JavaScript indexer (also handles plain JS via --infer-tsconfig)
|
|
97
|
+
npm install -g @sourcegraph/scip-typescript
|
|
98
|
+
|
|
99
|
+
# Python indexer
|
|
100
|
+
npm install -g @sourcegraph/scip-python
|
|
101
|
+
|
|
102
|
+
# SCIP CLI for index conversion (GitHub release — not on npm)
|
|
103
|
+
# https://github.com/scip-code/scip/releases (v0.8.1+ recommended)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
**Verify installation:**
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
scip-cli --help
|
|
110
|
+
scip-typescript --version # Only if you chose Option B
|
|
111
|
+
scip --version # Install from GitHub releases; v0.8.1+ recommended
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Usage
|
|
115
|
+
|
|
116
|
+
All commands are subcommands of `scip-cli`:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
scip-cli <command> [arguments]
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Commands
|
|
123
|
+
|
|
124
|
+
- `refs <symbol>` - Find all references to a symbol (`--path` to scope)
|
|
125
|
+
- `def <symbol>` - Find symbol definition with source code (`--path`, `--max-lines`)
|
|
126
|
+
- `search <pattern>` - Search symbols by name pattern (`--path`)
|
|
127
|
+
- `symbols <file>` - List all symbols in a file (`--path`; bare filename OK)
|
|
128
|
+
- `rdeps <file>` - Find files that depend on a file (`--path`)
|
|
129
|
+
- `members <symbol>` - List members of a class/interface (`--path`)
|
|
130
|
+
- `reindex` - Force re-indexing of the current project
|
|
131
|
+
- `skill [path]` - Install or dump the SKILL.md
|
|
132
|
+
|
|
133
|
+
### Examples
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
# Find where greet is used
|
|
137
|
+
scip-cli refs greet
|
|
138
|
+
|
|
139
|
+
# Get definition of greet
|
|
140
|
+
scip-cli def greet
|
|
141
|
+
|
|
142
|
+
# Search for symbols matching "Widget"
|
|
143
|
+
scip-cli search Widget
|
|
144
|
+
|
|
145
|
+
# Scope to a subdirectory
|
|
146
|
+
scip-cli def greet --path packages/api
|
|
147
|
+
|
|
148
|
+
# List symbols by bare filename
|
|
149
|
+
scip-cli symbols helper.ts
|
|
150
|
+
|
|
151
|
+
# Find files that import from a module
|
|
152
|
+
scip-cli rdeps src/helper.ts
|
|
153
|
+
|
|
154
|
+
# List members of a class
|
|
155
|
+
scip-cli members Widget
|
|
156
|
+
|
|
157
|
+
# Install skill file
|
|
158
|
+
scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### Pipelines
|
|
162
|
+
|
|
163
|
+
Stdout is one record per line; stderr carries warnings. Pipe-friendly flags: `refs --paths-only`, `search --names-only` / `--paths-only`, `members --names-only`. `rdeps` already prints bare file paths.
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
# What do importers of this file export?
|
|
167
|
+
scip-cli rdeps src/helper.ts | xargs -I{} scip-cli symbols {}
|
|
168
|
+
|
|
169
|
+
# Which files reference a symbol?
|
|
170
|
+
scip-cli refs greet --paths-only
|
|
171
|
+
|
|
172
|
+
# Classes matching a name → list their members
|
|
173
|
+
scip-cli search Handler --kind class --names-only | xargs -I{} scip-cli members {}
|
|
174
|
+
|
|
175
|
+
# Walk class members to their definitions
|
|
176
|
+
scip-cli members Widget --names-only | xargs -I{} scip-cli def Widget.{}
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## How It Works
|
|
180
|
+
|
|
181
|
+
1. On first query, automatically detects project language from `package.json` (TS/JS) or `pyproject.toml`/`setup.py` (Python)
|
|
182
|
+
2. For TypeScript monorepos, walks the repository for `tsconfig*.json` project roots (nested ancestors deduped; root included only when its `include` is broad)
|
|
183
|
+
3. Indexes using `scip-typescript` (adds `--infer-tsconfig` for JS-only projects) or `scip-python`
|
|
184
|
+
4. Converts the SCIP index to SQLite using `scip expt-convert`
|
|
185
|
+
5. Caches the database in `~/.cache/scip-cli/projects/<project-hash>-<config-hash>/index.db`
|
|
186
|
+
6. Subsequent queries are instant SQLite lookups
|
|
187
|
+
|
|
188
|
+
## Configuration
|
|
189
|
+
|
|
190
|
+
Optional `.scip-cli.json` in the project root:
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
{
|
|
194
|
+
"maxHeapMb": 8192,
|
|
195
|
+
"indexRoots": ["packages/api", "services/worker"],
|
|
196
|
+
"onlyIndexRoots": false
|
|
197
|
+
}
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
- `maxHeapMb` — Node heap for `scip-typescript` / `scip-python` (default **8192 MB** when omitted). Overridden by `SCIP_CLI_MAX_HEAP_MB`. This is the V8 heap cap, not total RAM usage.
|
|
201
|
+
- `indexRoots` — extra TypeScript project directories to index, merged with auto-discovered projects.
|
|
202
|
+
- `onlyIndexRoots` — skip auto-discovery and index only `indexRoots` (faster for focused work).
|
|
203
|
+
|
|
204
|
+
Changing `.scip-cli.json` indexing options (`indexRoots`, `onlyIndexRoots`) uses a separate cache entry automatically. Run `scip-cli reindex` to refresh an existing cache after code changes.
|
|
205
|
+
|
|
206
|
+
This is separate from `.scipquery.json`, which belongs to [scip-query](https://github.com/PlunderStruck/scip-query) and configures its analyzers, watch mode, and diff-gate — not read by scip-cli.
|
|
207
|
+
|
|
208
|
+
## Performance
|
|
209
|
+
|
|
210
|
+
Inspired by [scip-query](https://github.com/PlunderStruck/scip-query), scip-cli is a lightweight Python reimplementation optimized for speed. Compared to the original bash wrapper scripts:
|
|
211
|
+
|
|
212
|
+
- `refs`: 6.4s → 0.03s (213x faster)
|
|
213
|
+
- `def`: 2.8s → 0.05s (56x faster)
|
|
214
|
+
- `search`: 2.6s → 0.03s (87x faster)
|
|
215
|
+
- `symbols`: 0.3s → 0.02s (15x faster)
|
|
216
|
+
- `rdeps`: 0.2s → 0.02s (10x faster)
|
|
217
|
+
- `members`: 3.1s → 0.03s (103x faster)
|
|
218
|
+
|
|
219
|
+
The speedup comes from direct SQLite queries instead of shell command chains, eliminating subprocess overhead.
|
|
220
|
+
|
|
221
|
+
## Architecture
|
|
222
|
+
|
|
223
|
+
```
|
|
224
|
+
scip_cli/
|
|
225
|
+
├── __init__.py
|
|
226
|
+
├── __main__.py # CLI entry point
|
|
227
|
+
├── cli_args.py # Shared argparse helpers
|
|
228
|
+
├── config.py # .scip-cli.json loader
|
|
229
|
+
├── discover.py # TypeScript project discovery
|
|
230
|
+
├── merge.py # SQLite index merging
|
|
231
|
+
├── scip_tool.py # scip binary download
|
|
232
|
+
├── constants.py # Shared constants
|
|
233
|
+
├── sql.py # SQLite helpers
|
|
234
|
+
├── paths.py # --path scope filtering
|
|
235
|
+
├── project.py # Project root + language detection
|
|
236
|
+
├── cache.py # Index cache paths
|
|
237
|
+
├── indexing.py # SCIP index build + get_db
|
|
238
|
+
├── symbols.py # Symbol parsing and kinds
|
|
239
|
+
├── queries.py # Symbol/file SQL queries
|
|
240
|
+
├── source.py # Filesystem source reads
|
|
241
|
+
├── output.py # CLI formatting helpers
|
|
242
|
+
├── session.py # setup() and single-match resolution
|
|
243
|
+
└── commands/ # Subcommand implementations
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
## Development
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
pip install -e .
|
|
250
|
+
pytest tests/ -q
|
|
251
|
+
pytest tests/ -m integration -q # indexes tests/fixtures/sample-project (needs scip-typescript)
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### Debug Logging
|
|
255
|
+
|
|
256
|
+
Set `SCIP_CLI_DEBUG=1` to enable SQL query logging to stderr:
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
SCIP_CLI_DEBUG=1 scip-cli refs MyFunction
|
|
260
|
+
# Shows: SQL: SELECT ... | params: (...)
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
This is useful for testing and debugging SQL queries without exposing a `--debug` flag to users.
|
|
264
|
+
|
|
265
|
+
## License
|
|
266
|
+
|
|
267
|
+
MIT
|
scip_cli-1.2.0/README.md
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# scip-cli
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/py/scip-cli)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
|
|
6
|
+
Fast code intelligence CLI for TypeScript/JavaScript and Python projects. Query SCIP indexes directly via SQLite for instant results.
|
|
7
|
+
|
|
8
|
+
## Features
|
|
9
|
+
|
|
10
|
+
- **Fast**: Direct SQLite queries, eliminating skippable overhead
|
|
11
|
+
- **Simple**: Single binary with subcommands
|
|
12
|
+
- **Auto-indexing**: Automatically indexes projects on first query
|
|
13
|
+
- **Token-efficient**: Clean, minimal output optimized for AI consumption
|
|
14
|
+
|
|
15
|
+
## For AI Agents
|
|
16
|
+
|
|
17
|
+
If you're an AI agent, run this to see the quick reference:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
scip-cli skill
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Or install it to your skills folder:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
This enables commands like `def`, `refs`, `search`, `symbols`, `rdeps`, and `members` - just ask "where is X?" or "find references to X".
|
|
30
|
+
|
|
31
|
+
## Installation
|
|
32
|
+
|
|
33
|
+
### 1. Install scip-cli
|
|
34
|
+
|
|
35
|
+
**From PyPI:**
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install scip-cli
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
**From source (local development):**
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
git clone https://github.com/flesler/scip-cli.git
|
|
45
|
+
cd scip-cli
|
|
46
|
+
pip install .
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
For editable development (where `pip install -e .` fails due to permissions):
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
export PYTHONPATH=/path/to/scip-cli:$PYTHONPATH
|
|
53
|
+
python -m scip_cli --help
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### 2. Install prerequisites (optional)
|
|
57
|
+
|
|
58
|
+
scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
|
|
59
|
+
|
|
60
|
+
**Option A: Zero extra setup (recommended)**
|
|
61
|
+
|
|
62
|
+
Install `scip-cli` and run it. On first index, scip-cli will:
|
|
63
|
+
|
|
64
|
+
- Download `scip-typescript` / `scip-python` via `npx` when needed
|
|
65
|
+
- Download the `scip` converter binary from [GitHub releases](https://github.com/scip-code/scip/releases) into `~/.cache/scip-cli/bin/` when not already on PATH
|
|
66
|
+
|
|
67
|
+
No `.scip-cli.json` required — TypeScript monorepos are discovered by walking the repo for `tsconfig*.json` files (skipping `node_modules`, `.git`, etc.).
|
|
68
|
+
|
|
69
|
+
**Option B: Install globally for better performance**
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# TypeScript/JavaScript indexer (also handles plain JS via --infer-tsconfig)
|
|
73
|
+
npm install -g @sourcegraph/scip-typescript
|
|
74
|
+
|
|
75
|
+
# Python indexer
|
|
76
|
+
npm install -g @sourcegraph/scip-python
|
|
77
|
+
|
|
78
|
+
# SCIP CLI for index conversion (GitHub release — not on npm)
|
|
79
|
+
# https://github.com/scip-code/scip/releases (v0.8.1+ recommended)
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Verify installation:**
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
scip-cli --help
|
|
86
|
+
scip-typescript --version # Only if you chose Option B
|
|
87
|
+
scip --version # Install from GitHub releases; v0.8.1+ recommended
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Usage
|
|
91
|
+
|
|
92
|
+
All commands are subcommands of `scip-cli`:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
scip-cli <command> [arguments]
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Commands
|
|
99
|
+
|
|
100
|
+
- `refs <symbol>` - Find all references to a symbol (`--path` to scope)
|
|
101
|
+
- `def <symbol>` - Find symbol definition with source code (`--path`, `--max-lines`)
|
|
102
|
+
- `search <pattern>` - Search symbols by name pattern (`--path`)
|
|
103
|
+
- `symbols <file>` - List all symbols in a file (`--path`; bare filename OK)
|
|
104
|
+
- `rdeps <file>` - Find files that depend on a file (`--path`)
|
|
105
|
+
- `members <symbol>` - List members of a class/interface (`--path`)
|
|
106
|
+
- `reindex` - Force re-indexing of the current project
|
|
107
|
+
- `skill [path]` - Install or dump the SKILL.md
|
|
108
|
+
|
|
109
|
+
### Examples
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
# Find where greet is used
|
|
113
|
+
scip-cli refs greet
|
|
114
|
+
|
|
115
|
+
# Get definition of greet
|
|
116
|
+
scip-cli def greet
|
|
117
|
+
|
|
118
|
+
# Search for symbols matching "Widget"
|
|
119
|
+
scip-cli search Widget
|
|
120
|
+
|
|
121
|
+
# Scope to a subdirectory
|
|
122
|
+
scip-cli def greet --path packages/api
|
|
123
|
+
|
|
124
|
+
# List symbols by bare filename
|
|
125
|
+
scip-cli symbols helper.ts
|
|
126
|
+
|
|
127
|
+
# Find files that import from a module
|
|
128
|
+
scip-cli rdeps src/helper.ts
|
|
129
|
+
|
|
130
|
+
# List members of a class
|
|
131
|
+
scip-cli members Widget
|
|
132
|
+
|
|
133
|
+
# Install skill file
|
|
134
|
+
scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Pipelines
|
|
138
|
+
|
|
139
|
+
Stdout is one record per line; stderr carries warnings. Pipe-friendly flags: `refs --paths-only`, `search --names-only` / `--paths-only`, `members --names-only`. `rdeps` already prints bare file paths.
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
# What do importers of this file export?
|
|
143
|
+
scip-cli rdeps src/helper.ts | xargs -I{} scip-cli symbols {}
|
|
144
|
+
|
|
145
|
+
# Which files reference a symbol?
|
|
146
|
+
scip-cli refs greet --paths-only
|
|
147
|
+
|
|
148
|
+
# Classes matching a name → list their members
|
|
149
|
+
scip-cli search Handler --kind class --names-only | xargs -I{} scip-cli members {}
|
|
150
|
+
|
|
151
|
+
# Walk class members to their definitions
|
|
152
|
+
scip-cli members Widget --names-only | xargs -I{} scip-cli def Widget.{}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## How It Works
|
|
156
|
+
|
|
157
|
+
1. On first query, automatically detects project language from `package.json` (TS/JS) or `pyproject.toml`/`setup.py` (Python)
|
|
158
|
+
2. For TypeScript monorepos, walks the repository for `tsconfig*.json` project roots (nested ancestors deduped; root included only when its `include` is broad)
|
|
159
|
+
3. Indexes using `scip-typescript` (adds `--infer-tsconfig` for JS-only projects) or `scip-python`
|
|
160
|
+
4. Converts the SCIP index to SQLite using `scip expt-convert`
|
|
161
|
+
5. Caches the database in `~/.cache/scip-cli/projects/<project-hash>-<config-hash>/index.db`
|
|
162
|
+
6. Subsequent queries are instant SQLite lookups
|
|
163
|
+
|
|
164
|
+
## Configuration
|
|
165
|
+
|
|
166
|
+
Optional `.scip-cli.json` in the project root:
|
|
167
|
+
|
|
168
|
+
```json
|
|
169
|
+
{
|
|
170
|
+
"maxHeapMb": 8192,
|
|
171
|
+
"indexRoots": ["packages/api", "services/worker"],
|
|
172
|
+
"onlyIndexRoots": false
|
|
173
|
+
}
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- `maxHeapMb` — Node heap for `scip-typescript` / `scip-python` (default **8192 MB** when omitted). Overridden by `SCIP_CLI_MAX_HEAP_MB`. This is the V8 heap cap, not total RAM usage.
|
|
177
|
+
- `indexRoots` — extra TypeScript project directories to index, merged with auto-discovered projects.
|
|
178
|
+
- `onlyIndexRoots` — skip auto-discovery and index only `indexRoots` (faster for focused work).
|
|
179
|
+
|
|
180
|
+
Changing `.scip-cli.json` indexing options (`indexRoots`, `onlyIndexRoots`) uses a separate cache entry automatically. Run `scip-cli reindex` to refresh an existing cache after code changes.
|
|
181
|
+
|
|
182
|
+
This is separate from `.scipquery.json`, which belongs to [scip-query](https://github.com/PlunderStruck/scip-query) and configures its analyzers, watch mode, and diff-gate — not read by scip-cli.
|
|
183
|
+
|
|
184
|
+
## Performance
|
|
185
|
+
|
|
186
|
+
Inspired by [scip-query](https://github.com/PlunderStruck/scip-query), scip-cli is a lightweight Python reimplementation optimized for speed. Compared to the original bash wrapper scripts:
|
|
187
|
+
|
|
188
|
+
- `refs`: 6.4s → 0.03s (213x faster)
|
|
189
|
+
- `def`: 2.8s → 0.05s (56x faster)
|
|
190
|
+
- `search`: 2.6s → 0.03s (87x faster)
|
|
191
|
+
- `symbols`: 0.3s → 0.02s (15x faster)
|
|
192
|
+
- `rdeps`: 0.2s → 0.02s (10x faster)
|
|
193
|
+
- `members`: 3.1s → 0.03s (103x faster)
|
|
194
|
+
|
|
195
|
+
The speedup comes from direct SQLite queries instead of shell command chains, eliminating subprocess overhead.
|
|
196
|
+
|
|
197
|
+
## Architecture
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
scip_cli/
|
|
201
|
+
├── __init__.py
|
|
202
|
+
├── __main__.py # CLI entry point
|
|
203
|
+
├── cli_args.py # Shared argparse helpers
|
|
204
|
+
├── config.py # .scip-cli.json loader
|
|
205
|
+
├── discover.py # TypeScript project discovery
|
|
206
|
+
├── merge.py # SQLite index merging
|
|
207
|
+
├── scip_tool.py # scip binary download
|
|
208
|
+
├── constants.py # Shared constants
|
|
209
|
+
├── sql.py # SQLite helpers
|
|
210
|
+
├── paths.py # --path scope filtering
|
|
211
|
+
├── project.py # Project root + language detection
|
|
212
|
+
├── cache.py # Index cache paths
|
|
213
|
+
├── indexing.py # SCIP index build + get_db
|
|
214
|
+
├── symbols.py # Symbol parsing and kinds
|
|
215
|
+
├── queries.py # Symbol/file SQL queries
|
|
216
|
+
├── source.py # Filesystem source reads
|
|
217
|
+
├── output.py # CLI formatting helpers
|
|
218
|
+
├── session.py # setup() and single-match resolution
|
|
219
|
+
└── commands/ # Subcommand implementations
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Development
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
pip install -e .
|
|
226
|
+
pytest tests/ -q
|
|
227
|
+
pytest tests/ -m integration -q # indexes tests/fixtures/sample-project (needs scip-typescript)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Debug Logging
|
|
231
|
+
|
|
232
|
+
Set `SCIP_CLI_DEBUG=1` to enable SQL query logging to stderr:
|
|
233
|
+
|
|
234
|
+
```bash
|
|
235
|
+
SCIP_CLI_DEBUG=1 scip-cli refs MyFunction
|
|
236
|
+
# Shows: SQL: SELECT ... | params: (...)
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
This is useful for testing and debugging SQL queries without exposing a `--debug` flag to users.
|
|
240
|
+
|
|
241
|
+
## License
|
|
242
|
+
|
|
243
|
+
MIT
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scip-cli
|
|
3
|
+
description: Read when needing to find symbols, definitions, references, or members in TypeScript/JavaScript or Python code
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
TypeScript/JavaScript (.ts, .tsx, .js, .jsx) and Python (.py) — not GraphQL, CSS, or other files.
|
|
7
|
+
|
|
8
|
+
All commands are sub-commands of `scip-cli`. Run from the project root.
|
|
9
|
+
|
|
10
|
+
## Quick Decision Guide
|
|
11
|
+
|
|
12
|
+
| Question | Use | What you get |
|
|
13
|
+
| ----------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------- |
|
|
14
|
+
| "Where is X defined and what does it do?" | `def X` | Definition snippet (capped at 80 lines by default). Use `members Class` for large classes |
|
|
15
|
+
| "Where is X used/called?" | `refs X` | All file:line locations. Shows refs for all matching symbols. Use `--limit` to cap |
|
|
16
|
+
| "What's in this file?" | `symbols file` | All symbols — bare filename works (`helper.ts`, `widget.ts`) |
|
|
17
|
+
| "Find symbols by name" | `search name` | Functions, types, interfaces, classes. Use `--kind variable` for consts |
|
|
18
|
+
| "What files depend on this file?" | `rdeps file` | Importers — bare name works |
|
|
19
|
+
| "What methods does this class have?" | `members ClassName` | All methods/fields with line ranges |
|
|
20
|
+
|
|
21
|
+
## Gotchas
|
|
22
|
+
|
|
23
|
+
- **Bare names** resolve functions, types (aliases + interfaces), and classes. Use dotted qualifiers to disambiguate members: `def Widget.run`, `refs Foo.setBar`, `search MyClass.myMethod`, `members pkg.MyClass`. Consts/variables need `def --kind variable X` or `search --kind variable X`. Class methods need `members ClassName`, not bare `def methodName`.
|
|
24
|
+
- **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.
|
|
25
|
+
- **First run** in a project may auto-index (one-time wait; large monorepos with many `tsconfig.json` files take longer). JS-only projects (no `tsconfig.json`) are supported automatically.
|
|
26
|
+
- **Monorepos** are indexed by walking for `tsconfig*.json` under the repo (skips `node_modules`, `.git`, etc.). Nested parent/child projects are deduped. Add extra roots or limit indexing with `.scip-cli.json` (see README). Use `--path packages/api` (or any file/dir) to scope queries.
|
|
27
|
+
- **Prerequisites**: Node.js (for `npx` indexers). The `scip` converter auto-downloads on first use if missing; `scip-typescript` / `scip-python` download via `npx`. Optional `.scip-cli.json` for extra index roots or heap tuning. `brew install scip` installs an unrelated optimization solver — scip-cli ignores it and downloads the real binary.
|
|
28
|
+
|
|
29
|
+
## Details
|
|
30
|
+
|
|
31
|
+
### def
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
def [--kind <kind>] [--limit N] [--max-lines N] [--path PATH] <symbol>
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Kinds: `function`, `method`, `class`, `property`, `variable` — use `--kind` when the bare name isn't in the default set above.
|
|
38
|
+
|
|
39
|
+
`--limit` caps how many matching symbols are shown (default 10). `--max-lines` caps source lines **per definition body** (default 80) so huge functions/classes do not flood context. Use `--max-lines 0` for the full body. Override default via `SCIP_CLI_MAX_DEF_LINES`.
|
|
40
|
+
|
|
41
|
+
For large classes, prefer `members ClassName` first, then `def Class.method` for one member.
|
|
42
|
+
|
|
43
|
+
### refs
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
refs [--limit N] [--path PATH] [--paths-only] <symbol>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Returns `file:line` for each reference. Reads source files to find exact line numbers.
|
|
50
|
+
|
|
51
|
+
Default `--limit` is 10. When multiple symbols match, refs are grouped by symbol with `# <symbol>` headers. Use `--paths-only` for unique file paths (pipe-friendly).
|
|
52
|
+
|
|
53
|
+
### Pipelines
|
|
54
|
+
|
|
55
|
+
Commands emit one record per line on stdout; warnings and progress go to stderr. Use `--paths-only` / `--names-only` when piping into another `scip-cli` command.
|
|
56
|
+
|
|
57
|
+
| Goal | Pipeline |
|
|
58
|
+
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
59
|
+
| Blast radius of a file | `scip-cli rdeps file.ts \| xargs -I{} scip-cli symbols {}` |
|
|
60
|
+
| Files that import a symbol | `scip-cli refs Foo --paths-only` |
|
|
61
|
+
| Symbols in referencing files | `scip-cli refs Foo --paths-only \| xargs -I{} scip-cli symbols {}` (barrel files may have no symbols; prefer `search Foo --paths-only` for definition files) |
|
|
62
|
+
| Find classes, list members | `scip-cli search Handler --kind class --names-only \| xargs -I{} scip-cli members {}` |
|
|
63
|
+
| Members → definitions | `scip-cli members Widget --names-only \| xargs -I{} scip-cli def Widget.{}` |
|
|
64
|
+
| Find functions, show callers | `scip-cli search Publish --kind function --names-only \| xargs -I{} scip-cli refs {} --paths-only` |
|
|
65
|
+
| Files touching a topic | `scip-cli search Dynamo --paths-only` |
|
|
66
|
+
| Count importers | `scip-cli rdeps file.ts \| wc -l` |
|
|
67
|
+
|
|
68
|
+
`rdeps` already prints bare paths. `refs` defaults to `path:line`; add `--paths-only` to dedupe files. `search` / `members` need `--names-only` or `--paths-only` instead of `awk`.
|
|
69
|
+
|
|
70
|
+
Each `xargs` invocation reopens the index (fast on cache hit). Use `--limit` on the first command to cap fan-out.
|
|
71
|
+
|
|
72
|
+
### search
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
search [--kind <kind>] [--limit N] [--path PATH] [--names-only] [--paths-only] <pattern>
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Returns `file:line Kind symbolName`. Filters noisy symbols (file-level, parameters, type literals).
|
|
79
|
+
|
|
80
|
+
Default `--limit` is 10.
|
|
81
|
+
|
|
82
|
+
### symbols
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
symbols [--limit N] [--path PATH] <file>
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Returns `startLine-endLine kind name` for each symbol in the file.
|
|
89
|
+
|
|
90
|
+
Default `--limit` is 10.
|
|
91
|
+
|
|
92
|
+
### rdeps
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
rdeps [--limit N] [--path PATH] <file>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Returns list of files that import from this file.
|
|
99
|
+
|
|
100
|
+
Default `--limit` is 10.
|
|
101
|
+
|
|
102
|
+
### members
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
members [--limit N] [--path PATH] [--names-only] <symbol>
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Returns `startLine:endLine kind name` for each member. Note: limited by database coverage — `enclosing_symbol` data is sparse for many indexers.
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
"""scip-cli: Fast code intelligence via SCIP indexes."""
|
|
2
|
-
__version__ = "1.0
|
|
2
|
+
__version__ = "1.2.0"
|