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.
Files changed (62) hide show
  1. scip_cli-1.2.0/PKG-INFO +267 -0
  2. scip_cli-1.2.0/README.md +243 -0
  3. {scip_cli-1.0.3 → scip_cli-1.2.0}/pyproject.toml +3 -0
  4. scip_cli-1.2.0/scip_cli/SKILL.md +108 -0
  5. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/__init__.py +1 -1
  6. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/__main__.py +49 -2
  7. scip_cli-1.2.0/scip_cli/cache.py +34 -0
  8. scip_cli-1.2.0/scip_cli/cli_args.py +33 -0
  9. scip_cli-1.2.0/scip_cli/commands/def_cmd.py +57 -0
  10. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/members.py +22 -13
  11. scip_cli-1.2.0/scip_cli/commands/rdeps.py +46 -0
  12. scip_cli-1.2.0/scip_cli/commands/refs.py +136 -0
  13. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/reindex.py +3 -1
  14. scip_cli-1.2.0/scip_cli/commands/search.py +212 -0
  15. scip_cli-1.2.0/scip_cli/commands/symbols.py +37 -0
  16. scip_cli-1.2.0/scip_cli/config.py +67 -0
  17. scip_cli-1.2.0/scip_cli/constants.py +7 -0
  18. scip_cli-1.2.0/scip_cli/discover.py +128 -0
  19. scip_cli-1.2.0/scip_cli/indexing.py +292 -0
  20. scip_cli-1.2.0/scip_cli/lib.py +64 -0
  21. scip_cli-1.2.0/scip_cli/merge.py +174 -0
  22. scip_cli-1.2.0/scip_cli/output.py +112 -0
  23. scip_cli-1.2.0/scip_cli/paths.py +48 -0
  24. scip_cli-1.2.0/scip_cli/project.py +29 -0
  25. scip_cli-1.2.0/scip_cli/queries.py +320 -0
  26. scip_cli-1.2.0/scip_cli/scip_tool.py +150 -0
  27. scip_cli-1.2.0/scip_cli/session.py +46 -0
  28. scip_cli-1.2.0/scip_cli/source.py +65 -0
  29. scip_cli-1.2.0/scip_cli/sql.py +24 -0
  30. scip_cli-1.2.0/scip_cli/symbols.py +133 -0
  31. scip_cli-1.2.0/scip_cli.egg-info/PKG-INFO +267 -0
  32. scip_cli-1.2.0/scip_cli.egg-info/SOURCES.txt +49 -0
  33. scip_cli-1.2.0/tests/test_cache.py +22 -0
  34. scip_cli-1.2.0/tests/test_composability.py +181 -0
  35. scip_cli-1.2.0/tests/test_config.py +56 -0
  36. scip_cli-1.2.0/tests/test_discover.py +118 -0
  37. scip_cli-1.2.0/tests/test_indexer_env.py +36 -0
  38. scip_cli-1.2.0/tests/test_merge.py +136 -0
  39. {scip_cli-1.0.3 → scip_cli-1.2.0}/tests/test_pure_functions.py +296 -25
  40. scip_cli-1.2.0/tests/test_scip_tool.py +17 -0
  41. scip_cli-1.2.0/tests/test_smoke_cli.py +157 -0
  42. scip_cli-1.2.0/tests/test_typescript_projects.py +53 -0
  43. scip_cli-1.0.3/PKG-INFO +0 -161
  44. scip_cli-1.0.3/README.md +0 -137
  45. scip_cli-1.0.3/scip_cli/SKILL.md +0 -75
  46. scip_cli-1.0.3/scip_cli/commands/def_cmd.py +0 -39
  47. scip_cli-1.0.3/scip_cli/commands/rdeps.py +0 -39
  48. scip_cli-1.0.3/scip_cli/commands/refs.py +0 -83
  49. scip_cli-1.0.3/scip_cli/commands/search.py +0 -131
  50. scip_cli-1.0.3/scip_cli/commands/symbols.py +0 -35
  51. scip_cli-1.0.3/scip_cli/lib.py +0 -462
  52. scip_cli-1.0.3/scip_cli.egg-info/PKG-INFO +0 -161
  53. scip_cli-1.0.3/scip_cli.egg-info/SOURCES.txt +0 -24
  54. {scip_cli-1.0.3 → scip_cli-1.2.0}/LICENSE +0 -0
  55. {scip_cli-1.0.3 → scip_cli-1.2.0}/MANIFEST.in +0 -0
  56. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/__init__.py +0 -0
  57. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli/commands/skill.py +0 -0
  58. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli.egg-info/dependency_links.txt +0 -0
  59. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli.egg-info/entry_points.txt +0 -0
  60. {scip_cli-1.0.3 → scip_cli-1.2.0}/scip_cli.egg-info/top_level.txt +0 -0
  61. {scip_cli-1.0.3 → scip_cli-1.2.0}/setup.cfg +0 -0
  62. {scip_cli-1.0.3 → scip_cli-1.2.0}/setup.py +0 -0
@@ -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
+ [![PyPI version](https://badge.fury.io/py/scip-cli.svg)](https://badge.fury.io/py/scip-cli)
28
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
@@ -0,0 +1,243 @@
1
+ # scip-cli
2
+
3
+ [![PyPI version](https://badge.fury.io/py/scip-cli.svg)](https://badge.fury.io/py/scip-cli)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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
@@ -8,3 +8,6 @@ python_files = ["test_*.py"]
8
8
  python_classes = ["Test*"]
9
9
  python_functions = ["test_*"]
10
10
  addopts = "-v"
11
+ markers = [
12
+ "integration: indexes the bundled sample project (requires scip-typescript)",
13
+ ]
@@ -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.3"
2
+ __version__ = "1.2.0"