scip-cli 2.7.0__tar.gz → 2.9.0__tar.gz

{scip_cli-2.7.0 → scip_cli-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: scip-cli
-Version: 2.7.0
+Version: 2.9.0
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -35,19 +35,19 @@ AI agents waste tokens on grep and file scanning. scip-cli gives them precise, t
 - **Agent-first**: Install as a skill for Claude Code, Cursor, or any AI agent — precise code navigation without burning context
 - **Token-efficient**: One record per line, stderr for warnings, pipe-friendly output
 - **Fast**: Direct SQLite queries — 10x to 213x faster than alternatives
-- **`analyze`**: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope
+- `analyze`: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope
 - **Auto-indexing**: Indexes on first query, caches in SQLite, zero config
 
 ## Ports
 
 CLI/output parity ports of this project (Python is the reference):
 
-| Language           | Repository                                                        |
-| ------------------ | ----------------------------------------------------------------- |
-| Python (reference) | [flesler/scip-cli](https://github.com/flesler/scip-cli)           |
-| Go                 | [flesler/scip-cli-go](https://github.com/flesler/scip-cli-go)     |
-| Rust               | [flesler/scip-cli-rust](https://github.com/flesler/scip-cli-rust) |
-| Zig                | [flesler/scip-cli-zig](https://github.com/flesler/scip-cli-zig)   |
+|Language|Repository|
+|---|---|
+|Python (reference)|[flesler/scip-cli](https://github.com/flesler/scip-cli)|
+|Go|[flesler/scip-cli-go](https://github.com/flesler/scip-cli-go)|
+|Rust|[flesler/scip-cli-rust](https://github.com/flesler/scip-cli-rust)|
+|Zig|[flesler/scip-cli-zig](https://github.com/flesler/scip-cli-zig)|
 
 ## For AI Agents
 
@@ -244,13 +244,13 @@ Optional `.scip-cli.json` in the project root:
 
 Other environment variables:
 
-| Variable                       | Purpose                                                                                       |
-| ------------------------------ | --------------------------------------------------------------------------------------------- |
-| `SCIP_CLI_MAX_HEAP_MB`         | Node heap for `scip-typescript` / `scip-python` (overrides `maxHeapMb` in config)             |
-| `SCIP_CLI_TS_INDEX_BATCH_SIZE` | Split large TS repos into multiple `scip-typescript` runs (default: all tsconfigs in one run) |
-| `SCIP_CLI_MERGE_BATCH_SIZE`    | SQLite ATTACH batch size when merging part DBs (max 9)                                        |
-| `SCIP_CLI_MAX_DEF_LINES`       | Max definition lines in `code` output                                                         |
-| `SCIP_CLI_DEBUG`               | Log SQL queries to stderr                                                                     |
+|Variable|Purpose|
+|---|---|
+|`SCIP_CLI_MAX_HEAP_MB`|Node heap for `scip-typescript` / `scip-python` (overrides `maxHeapMb` in config)|
+|`SCIP_CLI_TS_INDEX_BATCH_SIZE`|Split large TS repos into multiple `scip-typescript` runs (default: all tsconfigs in one run)|
+|`SCIP_CLI_MERGE_BATCH_SIZE`|SQLite ATTACH batch size when merging part DBs (max 9)|
+|`SCIP_CLI_MAX_DEF_LINES`|Max definition lines in `code` output|
+|`SCIP_CLI_DEBUG`|Log SQL queries to stderr|
 
 **Version policy:** only the `scip` converter (`expt-convert`) is pinned to the 0.8.x release line because it defines the SQLite schema. Language indexers (`scip-typescript`, `scip-python` via `npx`; `scip-go` via `go install @latest`) install at latest on first use. `rust-analyzer` installs via `rustup component add`.
 
@@ -263,9 +263,12 @@ scip-cli reindex --path packages/server
 scip-cli reindex --path packages/api --path packages/worker
 scip-cli reindex --tsconfig 'apps/api/tsconfig.*.json'
 scip-cli reindex --tsconfig tsconfig.app.json --tsconfig tsconfig.spec.json
+scip-cli reindex --exclude '**/*.test.ts' '**/*.spec.ts'
+scip-cli reindex --exclude          # clear persisted excludes
+scip-cli reindex --fresh            # full index; clear metadata.json
 ```
 
-`--path` limits which discovered tsconfig **directories** are indexed (prefix match, same idea as query `--path`). `--tsconfig` skips discovery and indexes those `tsconfig*.json` **files** (repeatable; globs are expanded inside the tool). File-based runs default to one `scip-typescript` process per file so each gets its own heap (`SCIP_CLI_TS_INDEX_BATCH_SIZE` still overrides). Cannot combine `--path` and `--tsconfig`. **TypeScript only.** The scope is saved as `index-scope.json` next to `index.db` and reused until you run a full `scip-cli reindex` with no `--path`/`--tsconfig`.
+`--path` limits which discovered tsconfig **directories** are indexed (prefix match, same idea as query `--path`). `--tsconfig` skips discovery and indexes those `tsconfig*.json` **files** (repeatable; globs are expanded inside the tool). File-based runs default to one `scip-typescript` process per file so each gets its own heap (`SCIP_CLI_TS_INDEX_BATCH_SIZE` still overrides). Cannot combine `--path` and `--tsconfig`. **TypeScript only.** Scope and exclude defaults are saved in `metadata.json` next to `index.db` and reused on later `reindex` runs; use `reindex --fresh` to clear them and restore a full index. `--exclude` updates the persisted exclude list; a lone bare `--exclude` clears it.
 
 When a tsconfig (after `extends`) has `allowJs: true`, matching `.js`/`.jsx` files under that config's `include`/`files` are indexed too (same roots as `.ts`/`.tsx`). `allowJs: false` or unset leaves JavaScript out. JS-only repos with no `tsconfig.json` still use `--infer-tsconfig`.
 
@@ -286,24 +289,24 @@ scip-cli analyze --check dead_files --limit 25
 
 Sections are tagged `[high]`, `[medium]`, `[low]` and listed in that order.
 
-| Tier       | Project sections                                            | Action                                                               |
-| ---------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| **high**   | Cycles, unreferenced, dead exports, dead files, stale types | Nuke or fix cycles; delete unused; `_` prefix                        |
-| **medium** | Same-file only, change surface (file target)                | Module-private by usage                                              |
-| **low**    | Test-only consumers, coupling, bottlenecks, hotspots        | Noisy on Python (index omits many same-file calls); verify with `rg` |
+|Tier|Project sections|Action|
+|---|---|---|
+|**high**|Cycles, unreferenced, dead exports, dead files, stale types|Nuke or fix cycles; delete unused; `_` prefix|
+|**medium**|Same-file only, change surface (file target)|Module-private by usage|
+|**low**|Test-only consumers, coupling, bottlenecks, hotspots|Noisy on Python (index omits many same-file calls); verify with `rg`|
 
 Use `--priority high` for a quick gate; `--priority high,medium` adds context. File drill-down adds change surface and unused imports.
 
 **What to look at first**
 
-| Section                 | Easy pickings                                                                                          |
-| ----------------------- | ------------------------------------------------------------------------------------------------------ |
-| **Cycles**              | Import/mention cycles between production files — break the edge or extract shared code                 |
-| **Unreferenced**        | No usage in the index at all — delete                                                                  |
-| **Dead exports**        | No external refs — delete or `_` prefix                                                                |
-| **Stale types**         | Classes/types with no external consumer in the index — verify in-file or type-only use before removing |
-| **Same-file only**      | Used only inside defining file — rename to `_`                                                         |
-| **Test-only consumers** | Cross-file refs are all from tests — promote to e2e or accept as internal                              |
+|Section|Easy pickings|
+|---|---|
+|**Cycles**|Import/mention cycles between production files — break the edge or extract shared code|
+|**Unreferenced**|No usage in the index at all — delete|
+|**Dead exports**|No external refs — delete or `_` prefix|
+|**Stale types**|Classes/types with no external consumer in the index — verify in-file or type-only use before removing|
+|**Same-file only**|Used only inside defining file — rename to `_`|
+|**Test-only consumers**|Cross-file refs are all from tests — promote to e2e or accept as internal|
 
 **Per-file or package drill-down** on hubs or suspects:
 
@@ -346,7 +349,8 @@ scip_cli/
 ├── paths.py         # --path scope filtering
 ├── project.py       # Project root + language detection
 ├── cache.py         # Index cache paths
-├── scope.py         # Persisted reindex scope (index-scope.json)
+├── metadata.py      # Persisted reindex defaults (metadata.json)
+├── scope.py         # Scoped reindex helpers
 ├── debug.py         # SCIP_CLI_DEBUG stderr helpers
 ├── indexing.py      # SCIP index build + get_db
 ├── symbols.py       # Symbol parsing and kinds

{scip_cli-2.7.0 → scip_cli-2.9.0}/README.md

@@ -14,19 +14,19 @@ AI agents waste tokens on grep and file scanning. scip-cli gives them precise, t
 - **Agent-first**: Install as a skill for Claude Code, Cursor, or any AI agent — precise code navigation without burning context
 - **Token-efficient**: One record per line, stderr for warnings, pipe-friendly output
 - **Fast**: Direct SQLite queries — 10x to 213x faster than alternatives
-- **`analyze`**: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope
+- `analyze`: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope
 - **Auto-indexing**: Indexes on first query, caches in SQLite, zero config
 
 ## Ports
 
 CLI/output parity ports of this project (Python is the reference):
 
-| Language           | Repository                                                        |
-| ------------------ | ----------------------------------------------------------------- |
-| Python (reference) | [flesler/scip-cli](https://github.com/flesler/scip-cli)           |
-| Go                 | [flesler/scip-cli-go](https://github.com/flesler/scip-cli-go)     |
-| Rust               | [flesler/scip-cli-rust](https://github.com/flesler/scip-cli-rust) |
-| Zig                | [flesler/scip-cli-zig](https://github.com/flesler/scip-cli-zig)   |
+|Language|Repository|
+|---|---|
+|Python (reference)|[flesler/scip-cli](https://github.com/flesler/scip-cli)|
+|Go|[flesler/scip-cli-go](https://github.com/flesler/scip-cli-go)|
+|Rust|[flesler/scip-cli-rust](https://github.com/flesler/scip-cli-rust)|
+|Zig|[flesler/scip-cli-zig](https://github.com/flesler/scip-cli-zig)|
 
 ## For AI Agents
 
@@ -223,13 +223,13 @@ Optional `.scip-cli.json` in the project root:
 
 Other environment variables:
 
-| Variable                       | Purpose                                                                                       |
-| ------------------------------ | --------------------------------------------------------------------------------------------- |
-| `SCIP_CLI_MAX_HEAP_MB`         | Node heap for `scip-typescript` / `scip-python` (overrides `maxHeapMb` in config)             |
-| `SCIP_CLI_TS_INDEX_BATCH_SIZE` | Split large TS repos into multiple `scip-typescript` runs (default: all tsconfigs in one run) |
-| `SCIP_CLI_MERGE_BATCH_SIZE`    | SQLite ATTACH batch size when merging part DBs (max 9)                                        |
-| `SCIP_CLI_MAX_DEF_LINES`       | Max definition lines in `code` output                                                         |
-| `SCIP_CLI_DEBUG`               | Log SQL queries to stderr                                                                     |
+|Variable|Purpose|
+|---|---|
+|`SCIP_CLI_MAX_HEAP_MB`|Node heap for `scip-typescript` / `scip-python` (overrides `maxHeapMb` in config)|
+|`SCIP_CLI_TS_INDEX_BATCH_SIZE`|Split large TS repos into multiple `scip-typescript` runs (default: all tsconfigs in one run)|
+|`SCIP_CLI_MERGE_BATCH_SIZE`|SQLite ATTACH batch size when merging part DBs (max 9)|
+|`SCIP_CLI_MAX_DEF_LINES`|Max definition lines in `code` output|
+|`SCIP_CLI_DEBUG`|Log SQL queries to stderr|
 
 **Version policy:** only the `scip` converter (`expt-convert`) is pinned to the 0.8.x release line because it defines the SQLite schema. Language indexers (`scip-typescript`, `scip-python` via `npx`; `scip-go` via `go install @latest`) install at latest on first use. `rust-analyzer` installs via `rustup component add`.
 
@@ -242,9 +242,12 @@ scip-cli reindex --path packages/server
 scip-cli reindex --path packages/api --path packages/worker
 scip-cli reindex --tsconfig 'apps/api/tsconfig.*.json'
 scip-cli reindex --tsconfig tsconfig.app.json --tsconfig tsconfig.spec.json
+scip-cli reindex --exclude '**/*.test.ts' '**/*.spec.ts'
+scip-cli reindex --exclude          # clear persisted excludes
+scip-cli reindex --fresh            # full index; clear metadata.json
 ```
 
-`--path` limits which discovered tsconfig **directories** are indexed (prefix match, same idea as query `--path`). `--tsconfig` skips discovery and indexes those `tsconfig*.json` **files** (repeatable; globs are expanded inside the tool). File-based runs default to one `scip-typescript` process per file so each gets its own heap (`SCIP_CLI_TS_INDEX_BATCH_SIZE` still overrides). Cannot combine `--path` and `--tsconfig`. **TypeScript only.** The scope is saved as `index-scope.json` next to `index.db` and reused until you run a full `scip-cli reindex` with no `--path`/`--tsconfig`.
+`--path` limits which discovered tsconfig **directories** are indexed (prefix match, same idea as query `--path`). `--tsconfig` skips discovery and indexes those `tsconfig*.json` **files** (repeatable; globs are expanded inside the tool). File-based runs default to one `scip-typescript` process per file so each gets its own heap (`SCIP_CLI_TS_INDEX_BATCH_SIZE` still overrides). Cannot combine `--path` and `--tsconfig`. **TypeScript only.** Scope and exclude defaults are saved in `metadata.json` next to `index.db` and reused on later `reindex` runs; use `reindex --fresh` to clear them and restore a full index. `--exclude` updates the persisted exclude list; a lone bare `--exclude` clears it.
 
 When a tsconfig (after `extends`) has `allowJs: true`, matching `.js`/`.jsx` files under that config's `include`/`files` are indexed too (same roots as `.ts`/`.tsx`). `allowJs: false` or unset leaves JavaScript out. JS-only repos with no `tsconfig.json` still use `--infer-tsconfig`.
 
@@ -265,24 +268,24 @@ scip-cli analyze --check dead_files --limit 25
 
 Sections are tagged `[high]`, `[medium]`, `[low]` and listed in that order.
 
-| Tier       | Project sections                                            | Action                                                               |
-| ---------- | ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| **high**   | Cycles, unreferenced, dead exports, dead files, stale types | Nuke or fix cycles; delete unused; `_` prefix                        |
-| **medium** | Same-file only, change surface (file target)                | Module-private by usage                                              |
-| **low**    | Test-only consumers, coupling, bottlenecks, hotspots        | Noisy on Python (index omits many same-file calls); verify with `rg` |
+|Tier|Project sections|Action|
+|---|---|---|
+|**high**|Cycles, unreferenced, dead exports, dead files, stale types|Nuke or fix cycles; delete unused; `_` prefix|
+|**medium**|Same-file only, change surface (file target)|Module-private by usage|
+|**low**|Test-only consumers, coupling, bottlenecks, hotspots|Noisy on Python (index omits many same-file calls); verify with `rg`|
 
 Use `--priority high` for a quick gate; `--priority high,medium` adds context. File drill-down adds change surface and unused imports.
 
 **What to look at first**
 
-| Section                 | Easy pickings                                                                                          |
-| ----------------------- | ------------------------------------------------------------------------------------------------------ |
-| **Cycles**              | Import/mention cycles between production files — break the edge or extract shared code                 |
-| **Unreferenced**        | No usage in the index at all — delete                                                                  |
-| **Dead exports**        | No external refs — delete or `_` prefix                                                                |
-| **Stale types**         | Classes/types with no external consumer in the index — verify in-file or type-only use before removing |
-| **Same-file only**      | Used only inside defining file — rename to `_`                                                         |
-| **Test-only consumers** | Cross-file refs are all from tests — promote to e2e or accept as internal                              |
+|Section|Easy pickings|
+|---|---|
+|**Cycles**|Import/mention cycles between production files — break the edge or extract shared code|
+|**Unreferenced**|No usage in the index at all — delete|
+|**Dead exports**|No external refs — delete or `_` prefix|
+|**Stale types**|Classes/types with no external consumer in the index — verify in-file or type-only use before removing|
+|**Same-file only**|Used only inside defining file — rename to `_`|
+|**Test-only consumers**|Cross-file refs are all from tests — promote to e2e or accept as internal|
 
 **Per-file or package drill-down** on hubs or suspects:
 
@@ -325,7 +328,8 @@ scip_cli/
 ├── paths.py         # --path scope filtering
 ├── project.py       # Project root + language detection
 ├── cache.py         # Index cache paths
-├── scope.py         # Persisted reindex scope (index-scope.json)
+├── metadata.py      # Persisted reindex defaults (metadata.json)
+├── scope.py         # Scoped reindex helpers
 ├── debug.py         # SCIP_CLI_DEBUG stderr helpers
 ├── indexing.py      # SCIP index build + get_db
 ├── symbols.py       # Symbol parsing and kinds

{scip_cli-2.7.0 → scip_cli-2.9.0}/scip_cli/SKILL.md

@@ -11,16 +11,16 @@ 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?" | `code X`            | Definition snippet (capped at 80 lines by default). Use `members Class` for large classes |
-| "Where is X used/called?"                 | `refs X`            | Up to `--limit` file:line refs (default 10). Use `--limit` to raise cap                   |
-| "What's in this file?"                    | `symbols file`      | Up to `--limit` symbols (default 10). Bare filename works (`helper.ts`)                   |
-| "Find symbols by name"                    | `search name`       | Functions, types, interfaces, classes                                                     |
-| "What files depend on this file?"         | `rdeps file`        | Importers — bare name works                                                               |
-| "What does this symbol/file depend on?"   | `deps target`       | Outbound dependencies — symbols referenced within a function or file                      |
-| "What methods does this class have?"      | `members ClassName` | All methods/fields with line ranges                                                       |
-| "Health / risk / stale code?"             | `analyze`           | Multi-section SQL dashboard — omit target (project), pass file, or symbol                 |
+|Question|Use|What you get|
+|---|---|---|
+|"Where is X defined and what does it do?"|`code X`|Definition snippet (capped at 80 lines by default). Use `members Class` for large classes|
+|"Where is X used/called?"|`refs X`|Up to `--limit` file:line refs (default 10). Use `--limit` to raise cap|
+|"What's in this file?"|`symbols file`|Up to `--limit` symbols (default 10). Bare filename works (`helper.ts`)|
+|"Find symbols by name"|`search name`|Functions, types, interfaces, classes|
+|"What files depend on this file?"|`rdeps file`|Importers — bare name works|
+|"What does this symbol/file depend on?"|`deps target`|Outbound dependencies — symbols referenced within a function or file|
+|"What methods does this class have?"|`members ClassName`|All methods/fields with line ranges|
+|"Health / risk / stale code?"|`analyze`|Multi-section SQL dashboard — omit target (project), pass file, or symbol|
 
 ## Gotchas
 
@@ -61,18 +61,18 @@ Default `--limit` is 10 **reference lines** per symbol query (not mention chunks
 
 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.
 
-| Goal                         | Pipeline                                                                                                                                                    |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Blast radius of a file       | `scip-cli rdeps file.ts \|xargs -I{} scip-cli symbols {}`                                                                                                   |
-| Pre-change / health briefing | `scip-cli analyze` or `scip-cli analyze path/to/file.ts` or `scip-cli analyze SymbolName`                                                                   |
-| Files that import a symbol   | `scip-cli refs Foo --paths-only`                                                                                                                            |
-| 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) |
-| Find classes, list members   | `scip-cli search Handler --kind class --names-only \|xargs -I{} scip-cli members {}`                                                                        |
-| Members → definitions        | `scip-cli members Widget --names-only \|xargs -I{} scip-cli code Widget.{}`                                                                                 |
-| Find functions, show callers | `scip-cli search Publish --kind function --names-only \|xargs -I{} scip-cli refs {} --paths-only`                                                           |
-| Files touching a topic       | `scip-cli search Dynamo --paths-only`                                                                                                                       |
-| Count importers              | `scip-cli rdeps file.ts \|wc -l`                                                                                                                            |
-| Outbound dependency files    | `scip-cli deps file.ts --paths-only`                                                                                                                        |
+|Goal|Pipeline|
+|---|---|
+|Blast radius of a file|`scip-cli rdeps file.ts \|xargs -I{} scip-cli symbols {}`|
+|Pre-change / health briefing|`scip-cli analyze` or `scip-cli analyze path/to/file.ts` or `scip-cli analyze SymbolName`|
+|Files that import a symbol|`scip-cli refs Foo --paths-only`|
+|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)|
+|Find classes, list members|`scip-cli search Handler --kind class --names-only \|xargs -I{} scip-cli members {}`|
+|Members → definitions|`scip-cli members Widget --names-only \|xargs -I{} scip-cli code Widget.{}`|
+|Find functions, show callers|`scip-cli search Publish --kind function --names-only \|xargs -I{} scip-cli refs {} --paths-only`|
+|Files touching a topic|`scip-cli search Dynamo --paths-only`|
+|Count importers|`scip-cli rdeps file.ts \|wc -l`|
+|Outbound dependency files|`scip-cli deps file.ts --paths-only`|
 
 `rdeps` already prints bare paths. `deps --paths-only` deduplicates to unique files. `refs` defaults to `path:line`; add `--paths-only` to dedupe files. `search` / `members` need `--names-only` or `--paths-only` instead of `awk`.
 
@@ -136,12 +136,12 @@ Returns `startLine:endLine kind name` for each member. Members are found via SCI
 analyze [--limit N] [--path PATH] [--include-tests] [--priority LEVEL] [--check NAME] [target]
 ```
 
-| Target                                 | Output                                                                                          |
-| -------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| _(omit)_                               | Project-wide dashboards only                                                                    |
-| **directory** (`scip_cli`, `src/pkg/`) | Scoped project dashboards + per-file sections for each indexed file under the dir               |
-| **file**                               | Scoped project dashboards for that file + per-file sections + top symbols by external consumers |
-| **symbol**                             | Symbol pressure, consumers, dependencies, affected                                              |
+|Target|Output|
+|---|---|
+|_(omit)_|Project-wide dashboards only|
+|**directory** (`scip_cli`, `src/pkg/`)|Scoped project dashboards + per-file sections for each indexed file under the dir|
+|**file**|Scoped project dashboards for that file + per-file sections + top symbols by external consumers|
+|**symbol**|Symbol pressure, consumers, dependencies, affected|
 
 Sections are ordered **high → medium → low**. `[high]` cycles, unreferenced, dead exports, dead files, stale types; `[medium]` same-file-only, change surface (file); `[low]` test-only consumers (noisy on Python), coupling, bottlenecks, hotspots.
 
@@ -160,7 +160,11 @@ Directory detection uses the filesystem when present, otherwise an indexed path
 ### reindex
 
 ```bash
-reindex [--path DIR ...] [--tsconfig FILE_OR_GLOB ...] [--with-external]
+reindex [--path DIR ...] [--tsconfig FILE_OR_GLOB ...] [--exclude [GLOB ...]] [--fresh] [--with-external]
 ```
 
-`--path` and `--tsconfig` cannot be combined (**TypeScript only**). `--tsconfig` takes `tsconfig*.json` files (repeatable; globs expanded inside the tool). File-based runs default to one `scip-typescript` process per file so each gets its own heap (`SCIP_CLI_TS_INDEX_BATCH_SIZE` still overrides). Scope is saved as `index-scope.json` and reused until a full `reindex` with neither flag.
+`--path` and `--tsconfig` cannot be combined (**TypeScript only**). `--tsconfig` takes `tsconfig*.json` files (repeatable; globs expanded inside the tool). File-based runs default to one `scip-typescript` process per file so each gets its own heap (`SCIP_CLI_TS_INDEX_BATCH_SIZE` still overrides). Scope and exclude defaults are persisted in `metadata.json` next to `index.db` and reused on later `reindex` runs.
+
+`--exclude GLOB` omits matching files from the SQLite index after conversion (repeatable; merged with `excludeGlobs` in `.scip-cli.json`). Passing `--exclude` updates the persisted exclude list; a lone bare `--exclude` (no globs on that flag) clears it — `--exclude foo --exclude` keeps `foo`. Patterns without `/` match basenames (`*.test.ts`); patterns with `/` match repo-relative paths (`tests/**`, `**/__tests__/**`). Indexers still parse excluded files when production code imports them — post-process removal is authoritative.
+
+`--fresh` ignores persisted `metadata.json` and clears it before indexing unless `--path`, `--tsconfig`, or `--exclude` are set on the same command (use `reindex --fresh` to restore a full index).

{scip_cli-2.7.0 → scip_cli-2.9.0}/scip_cli/__init__.py

@@ -1,3 +1,3 @@
 """scip-cli: Fast code intelligence via SCIP indexes."""
 
-__version__ = "2.7.0"
+__version__ = "2.9.0"

{scip_cli-2.7.0 → scip_cli-2.9.0}/scip_cli/__main__.py

@@ -154,7 +154,7 @@ def main() -> None:
         "--path",
         action="append",
         metavar="PATH",
-        help="Index only tsconfig projects under PATH (repeatable; persisted until full reindex)",
+        help="Index only tsconfig projects under PATH (repeatable; persisted in metadata.json)",
     )
     reindex_parser.add_argument(
         "--tsconfig",
@@ -162,10 +162,26 @@ def main() -> None:
         metavar="GLOB",
         help=(
             "Index these tsconfig*.json files instead of auto-discovery "
-            "(repeatable, globs ok; persisted until full reindex). "
+            "(repeatable, globs ok; persisted in metadata.json). "
             "Cannot be combined with --path."
         ),
     )
+    reindex_parser.add_argument(
+        "--exclude",
+        action="append",
+        nargs="*",
+        metavar="GLOB",
+        help=(
+            "Omit indexed files matching GLOB from the SQLite index "
+            "(repeatable; merged with excludeGlobs in .scip-cli.json; persisted in metadata.json). "
+            "Bare --exclude clears persisted excludes."
+        ),
+    )
+    reindex_parser.add_argument(
+        "--fresh",
+        action="store_true",
+        help="Ignore persisted metadata.json; clear it unless scope/exclude flags are set on this run",
+    )
     reindex_parser.add_argument(
         "--with-external",
         action="store_true",

{scip_cli-2.7.0 → scip_cli-2.9.0}/scip_cli/commands/reindex.py

@@ -10,9 +10,9 @@ from ..cache import (
     promote_next_index,
 )
 from ..indexing import index_project, log_index_complete
+from ..metadata import UNSET, apply_metadata_updates
 from ..paths import normalize_path_scope
 from ..project import Language, find_project_root_and_language
-from ..scope import save_index_scope
 from ..tsconfig import expand_tsconfig_patterns
 
 
@@ -24,6 +24,8 @@ def main(args):
 
     path_args = getattr(args, "path", None) or []
     tsconfig_args = getattr(args, "tsconfig", None) or []
+    exclude_groups = getattr(args, "exclude", None)
+    fresh = getattr(args, "fresh", False)
     if path_args and tsconfig_args:
         print("Error: reindex --path and --tsconfig cannot be combined", file=sys.stderr)
         sys.exit(1)
@@ -32,6 +34,7 @@ def main(args):
         print(f"Error: reindex {flag} is only supported for TypeScript projects", file=sys.stderr)
         sys.exit(1)
 
+    scope_update: list[str] | object | None = UNSET
     if tsconfig_args:
         try:
             tsconfig_paths = expand_tsconfig_patterns(tsconfig_args, root)
@@ -39,12 +42,12 @@ def main(args):
             print(f"Error: {exc}", file=sys.stderr)
             sys.exit(1)
         scope_paths = [path.as_posix() for path in tsconfig_paths]
-        save_index_scope(root, scope_paths)
+        scope_update = scope_paths
         print(f"Index scope: {', '.join(scope_paths)}", file=sys.stderr)
         print(
             (
                 "Warning: scoped reindex replaces the cache with only these tsconfig files; "
-                "run reindex with no --path/--tsconfig to restore the full index"
+                "run reindex --fresh to restore the full index"
             ),
             file=sys.stderr,
         )
@@ -56,17 +59,22 @@ def main(args):
                 print(f"Error: invalid or empty --path: {path!r}", file=sys.stderr)
                 sys.exit(1)
             scope_paths.append(normalized)
-        save_index_scope(root, scope_paths)
+        scope_update = scope_paths
         print(f"Index scope: {', '.join(scope_paths)}", file=sys.stderr)
         print(
             (
                 "Warning: scoped reindex replaces the cache with only these projects; "
-                "run reindex with no --path/--tsconfig to restore the full index"
+                "run reindex --fresh to restore the full index"
             ),
             file=sys.stderr,
         )
-    else:
-        save_index_scope(root, None)
+
+    exclude_update: list[str] | object = UNSET
+    if exclude_groups is not None:
+        exclude_globs = [glob for group in exclude_groups for glob in group]
+        exclude_update = exclude_globs
+        if exclude_globs:
+            print(f"Index exclude: {', '.join(exclude_globs)}", file=sys.stderr)
 
     cache_dir = get_cache_dir(root)
     cache_dir.mkdir(parents=True, exist_ok=True)
@@ -76,6 +84,12 @@ def main(args):
         sys.exit(1)
 
     with index_build_lock(cache_dir):
+        apply_metadata_updates(
+            root,
+            fresh=fresh,
+            scope_paths=scope_update,
+            exclude_globs=exclude_update,
+        )
         cleanup_in_progress_index(cache_dir)
         try:
             # Pass --with-external flag to indexer via environment

{scip_cli-2.7.0 → scip_cli-2.9.0}/scip_cli/config.py

@@ -16,6 +16,7 @@ class ProjectSettings:
     max_heap_mb: int | None = None
     index_roots: list[str] = field(default_factory=list)
     only_index_roots: bool = False
+    exclude_globs: list[str] = field(default_factory=list)
 
 
 def load_project_config(project_root: Path) -> ProjectSettings:
@@ -44,10 +45,15 @@ def load_project_config(project_root: Path) -> ProjectSettings:
     if type(only_index_roots) is not bool:
         raise RuntimeError(f"Invalid {CONFIG_FILENAME}: onlyIndexRoots must be a boolean")
 
+    exclude_globs = data.get("excludeGlobs", [])
+    if not isinstance(exclude_globs, list) or not all(isinstance(p, str) for p in exclude_globs):
+        raise RuntimeError(f"Invalid {CONFIG_FILENAME}: excludeGlobs must be a string array")
+
     return ProjectSettings(
         max_heap_mb=max_heap_mb,
         index_roots=index_roots,
         only_index_roots=only_index_roots,
+        exclude_globs=exclude_globs,
     )
 
 

scip_cli-2.9.0/scip_cli/exclude.py

@@ -0,0 +1,90 @@
+"""Persisted index exclude globs and path matching."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path, PurePosixPath
+
+from .config import load_project_config
+from .metadata import IndexMetadata, load_metadata, save_metadata
+
+
+def load_persisted_exclude_globs(project_root: Path) -> tuple[str, ...]:
+    """Load exclude globs from persisted reindex metadata, if any."""
+    metadata = load_metadata(project_root)
+    return metadata.exclude_globs or ()
+
+
+def save_persisted_exclude_globs(project_root: Path, globs: list[str] | None) -> None:
+    """Persist or clear reindex exclude globs for a project."""
+    current = load_metadata(project_root)
+    save_metadata(
+        project_root,
+        IndexMetadata(
+            scope_paths=current.scope_paths,
+            exclude_globs=tuple(globs) if globs else None,
+        ),
+    )
+
+
+def resolve_exclude_globs(project_root: Path) -> tuple[str, ...]:
+    """Merge .scip-cli.json excludeGlobs with persisted reindex exclude globs."""
+    settings = load_project_config(project_root)
+    merged: list[str] = []
+    seen: set[str] = set()
+    for glob in (*settings.exclude_globs, *load_persisted_exclude_globs(project_root)):
+        if glob and glob not in seen:
+            seen.add(glob)
+            merged.append(glob)
+    return tuple(merged)
+
+
+def _glob_to_regex(pattern: str) -> re.Pattern[str]:
+    """Translate a repo-relative glob to a regex (supports **, *, ?)."""
+    normalized = pattern.replace("\\", "/").lstrip("/")
+    parts: list[str] = []
+    index = 0
+    while index < len(normalized):
+        char = normalized[index]
+        if char == "*":
+            if index + 1 < len(normalized) and normalized[index + 1] == "*":
+                if index + 2 < len(normalized) and normalized[index + 2] == "/":
+                    parts.append("(?:.+/)?")
+                    index += 3
+                    continue
+                parts.append(".*")
+                index += 2
+                continue
+            parts.append("[^/]*")
+            index += 1
+            continue
+        if char == "?":
+            parts.append("[^/]")
+            index += 1
+            continue
+        if char in ".^$+{}|()[]":
+            parts.append(re.escape(char))
+        else:
+            parts.append(char)
+        index += 1
+    return re.compile("^" + "".join(parts) + "$")
+
+
+def path_matches_glob(relative_path: str, pattern: str) -> bool:
+    """Return True when a repo-relative path matches an exclude glob.
+
+    Patterns without '/' match the basename only (e.g. ``*.test.ts``).
+    Patterns with '/' match the full posix path (``tests/**``, ``src/*.spec.ts``).
+    """
+    path = relative_path.replace("\\", "/").lstrip("/")
+    glob = pattern.replace("\\", "/").lstrip("/")
+    if not glob:
+        return False
+    target = PurePosixPath(path).name if "/" not in glob else path
+    return bool(_glob_to_regex(glob).match(target))
+
+
+def path_matches_any_glob(relative_path: str, patterns: tuple[str, ...] | list[str]) -> bool:
+    if not patterns:
+        return False
+    return any(path_matches_glob(relative_path, pattern) for pattern in patterns)

{scip_cli-2.7.0 → scip_cli-2.9.0}/scip_cli/indexing/convert.py

@@ -68,7 +68,13 @@ def prefix_document_paths(db_path: Path, prefix: str) -> None:
         conn.close()
 
 
-def convert_scip_to_db(scip_path, db_path, *, document_path_prefix: Path | str | None = None):
+def convert_scip_to_db(
+    scip_path,
+    db_path,
+    *,
+    document_path_prefix: Path | str | None = None,
+    exclude_globs: tuple[str, ...] | None = None,
+):
     """Convert a SCIP protobuf file to a SQLite index at db_path."""
     db_path = Path(db_path)
     db_path.parent.mkdir(parents=True, exist_ok=True)
@@ -88,7 +94,7 @@ def convert_scip_to_db(scip_path, db_path, *, document_path_prefix: Path | str |
     if not db_path.exists():
         raise RuntimeError("Failed to convert index")
 
-    postprocess_index(db_path)
+    postprocess_index(db_path, exclude_globs=exclude_globs or ())
     prefix = project_path_prefix(document_path_prefix)
     if prefix is not None:
         prefix_document_paths(db_path, prefix)