scip-cli 2.12.0__tar.gz → 3.1.0__tar.gz

{scip_cli-2.12.0 → scip_cli-3.1.0}/.github/workflows/ci.yml

@@ -29,7 +29,13 @@ jobs:
           python -m venv .venv
           source .venv/bin/activate
           pip install -e ".[dev]"
-          npm install -g github:flesler/scip-typescript#feat/incremental-tsc
+          # GitHub npx spec runs prepare (needs pnpm for snapshot fixtures); CI installs a built global binary instead.
+          git clone --depth 1 --branch feat/partial-files https://github.com/flesler/scip-typescript.git /tmp/scip-typescript
+          cd /tmp/scip-typescript
+          npm install --ignore-scripts
+          npm run build
+          npm install -g .
+          cd -
           mkdir -p ~/.local/bin
           curl -sL https://github.com/scip-code/scip/releases/download/v0.9.0/scip-linux-amd64.tar.gz | tar xz -C ~/.local/bin
           echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH

{scip_cli-2.12.0 → scip_cli-3.1.0}/.gitignore

@@ -49,5 +49,10 @@ dogfood.md
 
 # Local-only dev scripts (repo-specific smoke harnesses)
 scripts/deep-smoke.sh
+scripts/smoke.local.json
 tmp/
 *.db
+node_modules/
+
+# Generated when indexing the incremental-bench fixture (sources are .ts)
+tests/fixtures/incremental-bench/**/*.js

{scip_cli-2.12.0 → scip_cli-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scip-cli
-Version: 2.12.0
+Version: 3.1.0
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -101,7 +101,8 @@ On **first index**, scip-cli runs language indexers and builds a SQLite cache. Y
 
 Install `scip-cli` and run it. On first index, scip-cli will:
 
-- Download `scip-typescript` / `scip-python` via `npx`, `scip-go` via `go install`, or `rust-analyzer` via `rustup` when not already on PATH
+- Install `scip-typescript` from the [flesler/scip-typescript](https://github.com/flesler/scip-typescript) fork (`feat/partial-files`) when not on PATH — clones, `npm install`, and builds into `~/.cache/scip-cli/tools/github-npm/` (upstream npm does not ship partial `--files` yet)
+- Download `scip-python` via `npx`, `scip-go` via `go install`, or `rust-analyzer` via `rustup` when not already on PATH
 - 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
 - Walk the repo for `tsconfig*.json` project roots (TypeScript monorepos), run `scip-typescript` per project (parallel by default), convert each partial index, then merge into one `index.db`
 
@@ -109,11 +110,12 @@ No `.scip-cli.json` required for discovery. Subsequent queries read the cached d
 
 **Option B: Install indexers globally ahead of time**
 
-Same indexing steps as Option A; this only avoids `npx` download on the first run:
+Same indexing steps as Option A; this only avoids the first-run download/build:
 
 ```bash
-# TypeScript/JavaScript indexer (also handles plain JS via --infer-tsconfig)
-npm install -g @sourcegraph/scip-typescript
+# TypeScript/JavaScript indexer — fork with partial --files (required for incremental reindex)
+git clone --depth 1 --branch feat/partial-files https://github.com/flesler/scip-typescript.git
+cd scip-typescript && npm install --ignore-scripts && npm run build && npm install -g .
 
 # Python indexer
 npm install -g @sourcegraph/scip-python
@@ -154,7 +156,7 @@ scip-cli <command> [arguments]
 - `deps <symbol|file>` - Find outbound dependencies (what a symbol or file calls) (`--path`, `--paths-only`)
 - `members <symbol>` - List members of a class/interface (`--path`)
 - `analyze [target]` - SQL health dashboards (`--limit`, `--per-check-limit`, `--priority`, `--check`, `--include-tests`). No target: project-wide; directory or file path; symbol name. See [Finding easy wins with `analyze`](#finding-easy-wins-with-analyze).
-- `reindex` - Force re-indexing of the current project (`--path` to limit scope; repeatable)
+- `reindex` - Force re-indexing (`--path`, `--tsconfig`, `--exclude`, `--fresh`, `--no-incremental`; incremental by default in git TS repos)
 - `skill [path]` - Install or dump the SKILL.md
 
 ### Examples
@@ -222,7 +224,10 @@ scip-cli deps greet --paths-only | sort -u
 3. Runs `scip-typescript` per project (in parallel when there are multiple projects; set `SCIP_CLI_INDEX_WORKERS=1` to force serial), `scip-python` for Python, `scip-go` for Go, or `rust-analyzer scip` for Rust
 4. Converts each SCIP output to SQLite with `scip expt-convert`, then merges partial databases when needed
 5. Caches the result in `~/.cache/scip-cli/projects/<dirname>-<hash>/index.db` (e.g. `my-monorepo-1a3f7a`)
-6. Subsequent queries are SQLite lookups against that cache (not re-indexing)
+6. Compacts the database after each reindex (`VACUUM` + WAL checkpoint)
+7. Subsequent queries are SQLite lookups against that cache (not re-indexing)
+
+**Incremental reindex (TypeScript, v3.0+):** plain `scip-cli reindex` in a git worktree is incremental by default — reuses unchanged tsconfig shards via `shards/manifest.json` (`git_commit` + per-shard `tsconfig_digest`). Dirty shards reindex only changed files (git delta → importer closure → fork `--files`) and upsert into the live `index.db`. Use `--no-incremental` or `--fresh` for a full rebuild; `--unversioned` and non-git projects always full-reindex. Bench locally with `scripts/bench_incremental_gate.sh --branch fixture`.
 
 ## Configuration
 
@@ -249,27 +254,28 @@ Other environment variables:
 |`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_INDEX_TIMING`|`1` — per-phase `INDEX_TIMING:` lines on stderr during reindex|
 |`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. `scip-typescript` installs via npx from the GitHub fork in `scip_cli/indexing/constants.py` when not on PATH (until upstream ships incremental flags). `scip-python` via `npx` at latest; `scip-go` via `go install @latest`. `rust-analyzer` installs via `rustup component add`.
+**Version policy:** only the `scip` converter (`expt-convert`) is pinned to the 0.8.x release line because it defines the SQLite schema. **TypeScript** uses [flesler/scip-typescript](https://github.com/flesler/scip-typescript) `feat/partial-files` (see `SCIP_TYPESCRIPT_NPX_PACKAGE` in `scip_cli/indexing/constants.py`) — auto-built when not on PATH; switch back to `@sourcegraph/scip-typescript` on npm once upstream merges `--files`. `scip-python` via `npx` at latest; `scip-go` via `go install @latest`. `rust-analyzer` installs via `rustup component add`.
 
 Large monorepos (>10 tsconfig projects) log per-project progress to stderr during indexing; smaller repos stay quiet aside from the final `Indexed … (size)` line.
 
 Scoped indexing without editing `.scip-cli.json`:
 
 ```bash
-scip-cli reindex --path packages/server
+scip-cli reindex --path packages/core
 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
-scip-cli reindex --incremental      # reuse unchanged project shards (see SKILL for language support)
+scip-cli reindex --no-incremental   # full rebuild; clears shard manifest
 ```
 
-`--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.
+`--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 repo-relative to the detected project root — run from monorepo root or shorten the glob). 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** for `--path` and `--tsconfig`. 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 (honored during incremental reindex too); a lone bare `--exclude` clears it. Incremental is the default in git TypeScript repos; `--no-incremental`, `--fresh`, `--unversioned`, or non-git force full reindex.
 
 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`.
 
@@ -338,35 +344,6 @@ Inspired by [scip-query](https://github.com/PlunderStruck/scip-query), scip-cli
 
 The speedup comes from using optimized direct SQLite queries and cutting some nice but very slow goodies (like ts-morph).
 
-## Architecture
-
-```
-scip_cli/
-├── __init__.py
-├── __main__.py      # CLI entry point
-├── cli_args.py      # Shared argparse helpers
-├── config.py        # .scip-cli.json loader
-├── discover.py      # TypeScript project discovery
-├── merge.py         # SQLite index merging
-├── scip_tool.py     # scip binary download
-├── sql.py           # SQLite helpers
-├── paths.py         # --path scope filtering
-├── project.py       # Project root + language detection
-├── cache.py         # Index cache paths
-├── 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
-├── queries.py       # Symbol/file SQL queries
-├── source.py        # Filesystem source reads
-├── output.py        # CLI formatting helpers
-├── session.py       # setup() and single-match resolution
-├── targets.py       # file-path heuristics (tests; analyze uses analyze/targets.py)
-├── analyze/         # SQL dashboard queries (project/file/symbol)
-└── commands/        # Subcommand implementations
-```
-
 ## Development
 
 ```bash

{scip_cli-2.12.0 → scip_cli-3.1.0}/README.md

@@ -80,7 +80,8 @@ On **first index**, scip-cli runs language indexers and builds a SQLite cache. Y
 
 Install `scip-cli` and run it. On first index, scip-cli will:
 
-- Download `scip-typescript` / `scip-python` via `npx`, `scip-go` via `go install`, or `rust-analyzer` via `rustup` when not already on PATH
+- Install `scip-typescript` from the [flesler/scip-typescript](https://github.com/flesler/scip-typescript) fork (`feat/partial-files`) when not on PATH — clones, `npm install`, and builds into `~/.cache/scip-cli/tools/github-npm/` (upstream npm does not ship partial `--files` yet)
+- Download `scip-python` via `npx`, `scip-go` via `go install`, or `rust-analyzer` via `rustup` when not already on PATH
 - 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
 - Walk the repo for `tsconfig*.json` project roots (TypeScript monorepos), run `scip-typescript` per project (parallel by default), convert each partial index, then merge into one `index.db`
 
@@ -88,11 +89,12 @@ No `.scip-cli.json` required for discovery. Subsequent queries read the cached d
 
 **Option B: Install indexers globally ahead of time**
 
-Same indexing steps as Option A; this only avoids `npx` download on the first run:
+Same indexing steps as Option A; this only avoids the first-run download/build:
 
 ```bash
-# TypeScript/JavaScript indexer (also handles plain JS via --infer-tsconfig)
-npm install -g @sourcegraph/scip-typescript
+# TypeScript/JavaScript indexer — fork with partial --files (required for incremental reindex)
+git clone --depth 1 --branch feat/partial-files https://github.com/flesler/scip-typescript.git
+cd scip-typescript && npm install --ignore-scripts && npm run build && npm install -g .
 
 # Python indexer
 npm install -g @sourcegraph/scip-python
@@ -133,7 +135,7 @@ scip-cli <command> [arguments]
 - `deps <symbol|file>` - Find outbound dependencies (what a symbol or file calls) (`--path`, `--paths-only`)
 - `members <symbol>` - List members of a class/interface (`--path`)
 - `analyze [target]` - SQL health dashboards (`--limit`, `--per-check-limit`, `--priority`, `--check`, `--include-tests`). No target: project-wide; directory or file path; symbol name. See [Finding easy wins with `analyze`](#finding-easy-wins-with-analyze).
-- `reindex` - Force re-indexing of the current project (`--path` to limit scope; repeatable)
+- `reindex` - Force re-indexing (`--path`, `--tsconfig`, `--exclude`, `--fresh`, `--no-incremental`; incremental by default in git TS repos)
 - `skill [path]` - Install or dump the SKILL.md
 
 ### Examples
@@ -201,7 +203,10 @@ scip-cli deps greet --paths-only | sort -u
 3. Runs `scip-typescript` per project (in parallel when there are multiple projects; set `SCIP_CLI_INDEX_WORKERS=1` to force serial), `scip-python` for Python, `scip-go` for Go, or `rust-analyzer scip` for Rust
 4. Converts each SCIP output to SQLite with `scip expt-convert`, then merges partial databases when needed
 5. Caches the result in `~/.cache/scip-cli/projects/<dirname>-<hash>/index.db` (e.g. `my-monorepo-1a3f7a`)
-6. Subsequent queries are SQLite lookups against that cache (not re-indexing)
+6. Compacts the database after each reindex (`VACUUM` + WAL checkpoint)
+7. Subsequent queries are SQLite lookups against that cache (not re-indexing)
+
+**Incremental reindex (TypeScript, v3.0+):** plain `scip-cli reindex` in a git worktree is incremental by default — reuses unchanged tsconfig shards via `shards/manifest.json` (`git_commit` + per-shard `tsconfig_digest`). Dirty shards reindex only changed files (git delta → importer closure → fork `--files`) and upsert into the live `index.db`. Use `--no-incremental` or `--fresh` for a full rebuild; `--unversioned` and non-git projects always full-reindex. Bench locally with `scripts/bench_incremental_gate.sh --branch fixture`.
 
 ## Configuration
 
@@ -228,27 +233,28 @@ Other environment variables:
 |`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_INDEX_TIMING`|`1` — per-phase `INDEX_TIMING:` lines on stderr during reindex|
 |`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. `scip-typescript` installs via npx from the GitHub fork in `scip_cli/indexing/constants.py` when not on PATH (until upstream ships incremental flags). `scip-python` via `npx` at latest; `scip-go` via `go install @latest`. `rust-analyzer` installs via `rustup component add`.
+**Version policy:** only the `scip` converter (`expt-convert`) is pinned to the 0.8.x release line because it defines the SQLite schema. **TypeScript** uses [flesler/scip-typescript](https://github.com/flesler/scip-typescript) `feat/partial-files` (see `SCIP_TYPESCRIPT_NPX_PACKAGE` in `scip_cli/indexing/constants.py`) — auto-built when not on PATH; switch back to `@sourcegraph/scip-typescript` on npm once upstream merges `--files`. `scip-python` via `npx` at latest; `scip-go` via `go install @latest`. `rust-analyzer` installs via `rustup component add`.
 
 Large monorepos (>10 tsconfig projects) log per-project progress to stderr during indexing; smaller repos stay quiet aside from the final `Indexed … (size)` line.
 
 Scoped indexing without editing `.scip-cli.json`:
 
 ```bash
-scip-cli reindex --path packages/server
+scip-cli reindex --path packages/core
 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
-scip-cli reindex --incremental      # reuse unchanged project shards (see SKILL for language support)
+scip-cli reindex --no-incremental   # full rebuild; clears shard manifest
 ```
 
-`--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.
+`--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 repo-relative to the detected project root — run from monorepo root or shorten the glob). 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** for `--path` and `--tsconfig`. 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 (honored during incremental reindex too); a lone bare `--exclude` clears it. Incremental is the default in git TypeScript repos; `--no-incremental`, `--fresh`, `--unversioned`, or non-git force full reindex.
 
 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`.
 
@@ -317,35 +323,6 @@ Inspired by [scip-query](https://github.com/PlunderStruck/scip-query), scip-cli
 
 The speedup comes from using optimized direct SQLite queries and cutting some nice but very slow goodies (like ts-morph).
 
-## Architecture
-
-```
-scip_cli/
-├── __init__.py
-├── __main__.py      # CLI entry point
-├── cli_args.py      # Shared argparse helpers
-├── config.py        # .scip-cli.json loader
-├── discover.py      # TypeScript project discovery
-├── merge.py         # SQLite index merging
-├── scip_tool.py     # scip binary download
-├── sql.py           # SQLite helpers
-├── paths.py         # --path scope filtering
-├── project.py       # Project root + language detection
-├── cache.py         # Index cache paths
-├── 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
-├── queries.py       # Symbol/file SQL queries
-├── source.py        # Filesystem source reads
-├── output.py        # CLI formatting helpers
-├── session.py       # setup() and single-match resolution
-├── targets.py       # file-path heuristics (tests; analyze uses analyze/targets.py)
-├── analyze/         # SQL dashboard queries (project/file/symbol)
-└── commands/        # Subcommand implementations
-```
-
 ## Development
 
 ```bash

scip_cli-3.1.0/scip_cli/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: scip-cli
+description: Read when needing symbol lookup or SQL health dashboards in code.
+---
+
+TypeScript/JavaScript, Python, Go, Rust — not GraphQL, CSS, or other files. Run from project root.
+
+**Contributors:** `pip install -e ".[dev]"` so bare `scip-cli` on PATH is this checkout.
+
+## Quick guide
+
+|Question|Command|Output|
+|---|---|---|
+|Definition / body|`code X`|Snippet (default 80 lines/def; `members Class` for big types)|
+|Usages|`refs X`|`file:line` refs|
+|Symbols in file|`symbols file`|`start-end kind name` (bare filename ok)|
+|Find by name|`search pattern`|Matching symbols|
+|Who imports this file?|`rdeps file`|Importer paths|
+|What does this use?|`deps target`|Outbound deps (symbol or file)|
+|Class members|`members Class`|Methods/fields + line ranges|
+|Health / risk|`analyze`|SQL dashboard — project, dir, file, or symbol|
+
+Default `--limit` is **10** on query commands unless noted. Stdout = records; stderr = warnings/progress. Pipe with `--paths-only` / `--names-only`.
+
+## Gotchas
+
+- **Bare names** — functions, types, classes. Members need qualifiers: `code Widget.run`, `members pkg.MyClass`. Consts/vars are not indexed — use `rg`. Class methods: `members Class`, not bare `code method`.
+- **Ambiguity** — `code`/`refs` return up to `--limit` matches; `members`/`analyze` pick first with stderr warning. Narrow with dotted names or query `--path`.
+- **Stale index** — run `reindex` after substantive edits (no auto-invalidation).
+- **Query `--path` ≠ reindex scope** — query `--path` filters results only. `reindex --path` / `--tsconfig` persist TS scope and replace cache; full `reindex` restores.
+- **Monorepos** — walks `tsconfig*.json` (skips `node_modules`, `.git`). Dedupes nested projects. Extra roots: `.scip-cli.json` (README). Query scope: `--path packages/api`.
+- **allowJs** — when tsconfig `allowJs: true`, matching `.js`/`.jsx` under `include`/`files` are indexed. No root `tsconfig.json`: `--infer-tsconfig`.
+- **First run** may auto-index (parallel by default, `SCIP_CLI_INDEX_WORKERS`). >10 tsconfigs log progress. Prerequisites: Node (TS/Python), Go, or Rust toolchain; `scip` converter auto-downloads. `brew install scip` is the wrong package.
+
+## Pipelines
+
+|Goal|Pipeline|
+|---|---|
+|Blast radius|`scip-cli rdeps file.ts \|xargs -I{} scip-cli symbols {}`|
+|Health briefing|`scip-cli analyze --limit 40 --per-check-limit 5`|
+|Importer files|`scip-cli refs Foo --paths-only`|
+|Symbols in importers|`scip-cli refs Foo --paths-only \|xargs -I{} scip-cli symbols {}`|
+|Classes → members|`scip-cli search Handler --kind class --names-only \|xargs -I{} scip-cli members {}`|
+|Members → defs|`scip-cli members Widget --names-only \|xargs -I{} scip-cli code Widget.{}`|
+|Topic files|`scip-cli search Dynamo --paths-only`|
+|Outbound files|`scip-cli deps file.ts --paths-only`|
+
+`xargs` reopens the index each call — cap fan-out with `--limit` on the first command.
+
+## Commands
+
+### code
+
+```bash
+code [--kind KIND] [--limit N] [--max-lines N] [--offset N] [--full] [--path PATH] [--snippet] [--line-numbers] <symbol> [...]
+```
+
+`--kind`: `function`, `method`, `class`, `property`. Multiple symbols: each block prefixed on stdout. `--max-lines` per body (default 80; also 32k char cap unless `--full` or `--max-lines 0`). `--offset` is body-relative. `SCIP_CLI_MAX_DEF_LINES` overrides cap.
+
+### refs
+
+```bash
+refs [--limit N] [--path PATH] [--paths-only] <symbol> [...]
+```
+
+`file:line` per ref (reads source for lines). Multi-symbol groups prefixed on stdout.
+
+### search
+
+```bash
+search [--kind KIND] [--limit N] [--path PATH] [--names-only] [--paths-only] <pattern> [...]
+```
+
+`file:line kind name`. Patterns OR'd. Filters noisy symbols.
+
+### symbols
+
+```bash
+symbols [--limit N] [--path PATH] <file>
+```
+
+### rdeps
+
+```bash
+rdeps [--limit N] [--path PATH] <file>
+```
+
+Bare importer paths on stdout.
+
+### deps
+
+```bash
+deps [--limit N] [--path PATH] [--paths-only] <symbol|file>
+```
+
+Symbol: deps inside definition range. File: external symbols referenced. Format `file:line  symbol`; `--paths-only` dedupes files.
+
+### members
+
+```bash
+members [--limit N] [--path PATH] [--names-only] <symbol>
+```
+
+`start:end kind name`. Prefix match under parent; missing ranges filled from source when needed.
+
+### analyze
+
+```bash
+analyze [--limit N] [--per-check-limit N] [--path PATH] [--include-tests] [--priority LEVEL] [--check NAME] [target]
+```
+
+|Target|Scope|
+|---|---|
+|_(omit)_|Project dashboards|
+|directory|Dir dashboards + per-file sections (indexed files under dir)|
+|file|File dashboards + top symbols by external consumers|
+|symbol|Pressure, consumers, deps, affected|
+
+Priority **high → medium → low**. `--limit` = total finding rows (default 20); headers/truncation don't count. `--per-check-limit` caps each section. Agents: `--limit 40 --per-check-limit 5`. `--priority high` or `high,medium` (`1`/`2`/`3`) skips lower tiers. `--check NAME` (repeatable/comma) ANDs with priority.
+
+**Easy wins:** cycles, dead exports, dead files (production). Stale types = types with no external refs. Dead = no cross-file refs in index, not `vulture`. Empty `rdeps` on a hit is often a SCIP miss — verify with `rg -F STEM` (basename in `(...)`, same-file hits ignored).
+
+### reindex
+
+```bash
+reindex [--path DIR ...] [--tsconfig GLOB ...] [--exclude [GLOB ...]] [--fresh] [--no-incremental] [--unversioned] [--with-external]
+```
+
+`--path` and `--tsconfig` are TS-only and mutually exclusive. `--tsconfig` globs expanded in-tool; one heap per file by default (`SCIP_CLI_TS_INDEX_BATCH_SIZE` overrides). Scope/exclude persist in `metadata.json`.
+
+`--exclude GLOB` drops matching docs post-convert (repeatable; merges `.scip-cli.json` `excludeGlobs`). Bare `--exclude` clears list; `--exclude foo --exclude` keeps `foo`. No `/` = basename; with `/` = repo-relative.
+
+`--fresh` clears persisted metadata (unless combined with scope flags on same command).
+
+**Incremental by default** in git TypeScript repos: reuses `shards/manifest.json` (`git_commit` + per-shard `tsconfig_digest`); skips clean shards. Dirty: git delta ∪ importer closure → fork `--files` → upsert live `index.db`; deletions remove documents. `--no-incremental` or `--fresh` forces full reindex and clears the manifest. Non-git, `--unversioned`, or non-TypeScript projects always full-reindex.

{scip_cli-2.12.0 → scip_cli-3.1.0}/scip_cli/__init__.py

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

{scip_cli-2.12.0 → scip_cli-3.1.0}/scip_cli/__main__.py

@@ -196,10 +196,19 @@ def main() -> None:
         help="Ignore persisted metadata.json; clear it unless scope/exclude flags are set on this run",
     )
     reindex_parser.add_argument(
-        "--incremental",
+        "--no-incremental",
         action="store_true",
         help=(
-            "Reuse cached per-project index parts when inputs are unchanged (full reindex clears the incremental cache)"
+            "Full reindex every shard and clear the shard manifest "
+            "(default: incremental in git TypeScript repos; --fresh also forces full)"
+        ),
+    )
+    reindex_parser.add_argument(
+        "--unversioned",
+        action="store_true",
+        help=(
+            "Discover sources via on-disk glob instead of git (persisted in metadata.json; "
+            "for tarballs or when gitignored files must be indexed). Cleared by reindex --fresh"
         ),
     )
     reindex_parser.add_argument(

{scip_cli-2.12.0 → scip_cli-3.1.0}/scip_cli/commands/reindex.py

@@ -12,12 +12,32 @@ from ..cache import (
 )
 from ..indexing import index_project, log_index_complete
 from ..indexing.shards import clear_shard_cache
-from ..metadata import UNSET, apply_metadata_updates
+from ..indexing.source_discovery import is_versioned_repo
+from ..metadata import UNSET, apply_metadata_updates, index_unversioned
 from ..paths import normalize_path_scope
 from ..project import Language, find_project_root_and_language
+from ..sql import finalize_index_db
 from ..tsconfig import expand_tsconfig_patterns
 
 
+def _resolve_incremental(
+    root,
+    lang,
+    *,
+    fresh: bool,
+    no_incremental: bool,
+    unversioned: bool,
+) -> bool:
+    """Incremental reindex when eligible; full reindex otherwise."""
+    if fresh or no_incremental:
+        return False
+    if lang != Language.TYPESCRIPT:
+        return False
+    if unversioned or index_unversioned(root):
+        return False
+    return is_versioned_repo(root)
+
+
 def main(args):
     root, lang = find_project_root_and_language()
     if not root:
@@ -28,13 +48,15 @@ def main(args):
     tsconfig_args = getattr(args, "tsconfig", None) or []
     exclude_groups = getattr(args, "exclude", None)
     fresh = getattr(args, "fresh", False)
-    incremental = getattr(args, "incremental", False)
-    if incremental and fresh:
-        print("Error: reindex --incremental and --fresh cannot be combined", file=sys.stderr)
-        sys.exit(1)
-    if incremental and lang is not None and lang != Language.TYPESCRIPT:
-        print("Error: reindex --incremental is only supported for TypeScript projects", file=sys.stderr)
-        sys.exit(1)
+    no_incremental = getattr(args, "no_incremental", False)
+    unversioned = getattr(args, "unversioned", False)
+    incremental = _resolve_incremental(
+        root,
+        lang,
+        fresh=fresh,
+        no_incremental=no_incremental,
+        unversioned=unversioned,
+    )
     if path_args and tsconfig_args:
         print("Error: reindex --path and --tsconfig cannot be combined", file=sys.stderr)
         sys.exit(1)
@@ -52,14 +74,11 @@ def main(args):
             sys.exit(1)
         scope_paths = [path.as_posix() for path in tsconfig_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 --fresh to restore the full index"
-            ),
-            file=sys.stderr,
-        )
+        if len(scope_paths) == 1:
+            print(f"Index scope: {scope_paths[0]}", file=sys.stderr)
+        else:
+            patterns = ", ".join(tsconfig_args)
+            print(f"Index scope: {patterns} ({len(scope_paths)} tsconfigs)", file=sys.stderr)
     elif path_args:
         scope_paths: list[str] = []
         for path in path_args:
@@ -69,14 +88,10 @@ def main(args):
                 sys.exit(1)
             scope_paths.append(normalized)
         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 --fresh to restore the full index"
-            ),
-            file=sys.stderr,
-        )
+        if len(scope_paths) == 1:
+            print(f"Index scope: {scope_paths[0]}", file=sys.stderr)
+        else:
+            print(f"Index scope: {len(scope_paths)} paths", file=sys.stderr)
 
     exclude_update: list[str] | object = UNSET
     if exclude_groups is not None:
@@ -98,6 +113,7 @@ def main(args):
             fresh=fresh,
             scope_paths=scope_update,
             exclude_globs=exclude_update,
+            unversioned=unversioned if unversioned else UNSET,
         )
         cleanup_in_progress_index(cache_dir)
         if fresh or not incremental:
@@ -110,7 +126,7 @@ def main(args):
                 os.environ["SCIP_CLI_KEEP_EXTERNAL"] = "1"
 
             started = time.perf_counter()
-            _output_db, skipped, total = index_project(
+            _output_db, skipped, total, promote = index_project(
                 root,
                 lang,
                 cache_dir,
@@ -124,13 +140,26 @@ def main(args):
             print(f"Error: {e}", file=sys.stderr)
             sys.exit(1)
 
-        next_db = index_db_path(cache_dir, replace=True)
-        if not next_db.is_file():
+        live_db = index_db_path(cache_dir, replace=False)
+        from scip_cli.indexing.performance import phase
+
+        if promote:
+            next_db = index_db_path(cache_dir, replace=True)
+            if not next_db.is_file():
+                cleanup_in_progress_index(cache_dir)
+                print("Error: No index.db found after indexing", file=sys.stderr)
+                sys.exit(1)
+            with phase("finalize"):
+                finalize_index_db(next_db)
+            with phase("promote"):
+                promote_next_index(cache_dir)
+        elif live_db.is_file():
+            with phase("finalize"):
+                finalize_index_db(live_db)
+        elif not live_db.is_file():
             cleanup_in_progress_index(cache_dir)
             print("Error: No index.db found after indexing", file=sys.stderr)
             sys.exit(1)
-
-        promote_next_index(cache_dir)
         log_index_complete(
             index_db_path(cache_dir, replace=False),
             lang.value,

{scip_cli-2.12.0 → scip_cli-3.1.0}/scip_cli/exclude.py

@@ -88,3 +88,15 @@ def path_matches_any_glob(relative_path: str, patterns: tuple[str, ...] | list[s
     if not patterns:
         return False
     return any(path_matches_glob(relative_path, pattern) for pattern in patterns)
+
+
+def filter_excluded_paths(
+    paths: tuple[str, ...] | frozenset[str] | list[str],
+    exclude_globs: tuple[str, ...],
+) -> tuple[str, ...]:
+    """Drop repo-relative paths that match persisted/config exclude globs."""
+    if not exclude_globs:
+        if isinstance(paths, tuple):
+            return paths
+        return tuple(sorted(paths))
+    return tuple(sorted(path for path in paths if not path_matches_any_glob(path, exclude_globs)))

{scip_cli-2.12.0 → scip_cli-3.1.0}/scip_cli/indexing/constants.py

@@ -8,11 +8,11 @@ SCIP_INSTALL_URL = "https://github.com/scip-code/scip/releases"
 # Language indexers (npx / go install) use latest on first use.
 # The scip expt-convert binary is pinned separately in scip_tool.py (DB schema).
 #
-# scip-typescript npx fallback (when the binary is not on PATH). Fork adds
-# --incremental / --ts-build-info-dir for reindex --incremental. Switch back to
-# @sourcegraph/scip-typescript once upstream merges and releases; otherwise
-# publish the fork to npm long-term.
-SCIP_TYPESCRIPT_NPX_PACKAGE = "github:flesler/scip-typescript#feat/incremental-tsc"
+# TODO: Remove github_npm.py and runners github: branch when switching back to upstream npm.
+# scip-typescript npx fallback (when the binary is not on PATH). Fork adds --files
+# for partial document indexing. Pin >= ce6e9c9.
+SCIP_TYPESCRIPT_NPX_PACKAGE = "github:flesler/scip-typescript#feat/partial-files"
+
 # scip-typescript accepts many tsconfig paths per invocation (one .scip, one convert, no merge).
 # Split only when SCIP_CLI_TS_INDEX_BATCH_SIZE is set (OOM/timeout tuning).
 DEFAULT_TS_INDEX_BATCH_SIZE = None