scip-cli 3.0.0__tar.gz → 3.2.0__tar.gz

scip_cli-3.2.0/.agents/commands/dogfood.md

@@ -0,0 +1,15 @@
+# Dogfood analyze on this repo
+
+Human-invoked pass before broad review. From repo root with editable `scip-cli` on PATH:
+
+```bash
+scip-cli reindex
+scip-cli analyze --limit 25
+scip-cli analyze --priority high --limit 25
+scip-cli analyze scip_cli --limit 15
+scip-cli analyze scip_cli/queries.py --limit 20
+```
+
+Interpret README § *Finding easy wins with analyze* (cycles → dead exports → same-file → stale types). Fix or extend `analyze` per `agent.mdc` § Analyze feedback loop before spawning review subagents.
+
+Do not commit unless the user asks.

scip_cli-3.2.0/.agents/commands/release.md

@@ -0,0 +1,69 @@
+---
+argument-hint: "[major | minor | patch]"
+---
+
+# Release scip-cli (tag + GitHub)
+
+Bump level: **`$ARGUMENTS`** — must be exactly `major`, `minor`, or `patch`. Compute the next semver from `scip_cli/__init__.py` (same rules as `scripts/publish.sh`: patch +1; minor +1 and patch 0; major +1 and minor/patch 0). Tag and release **`vX.Y.Z`** for that computed version.
+
+## Commit messages (this repo)
+
+- **Day-to-day:** sentence case, verb first — e.g. `Add entrypoint fixtures`, `Pass indexer binary name to npx fallback`. **Not** Conventional Commits (`feat(scope):`, `chore:`, …).
+- **Version bump commit:** subject **only** `vX.Y.Z` (same string as the tag), e.g. `v3.2.0`.
+
+Do not commit, tag, or push unless the user invoked this release command.
+
+## Preflight
+
+1. Repo root; working tree clean before the bump commit.
+2. `./scripts/test.sh`
+3. If `$ARGUMENTS` is missing or not `major`/`minor`/`patch`, stop and ask.
+4. After bump, `git rev-parse "vX.Y.Z"` must fail (tag must not exist yet).
+
+## Bump version
+
+Use the bump logic in `scripts/publish.sh` (or run that script’s Python block with `BUMP_LEVEL=$ARGUMENTS`). Then:
+
+```bash
+git add scip_cli/__init__.py
+git commit -m "vX.Y.Z"
+```
+
+## Tag (non-interactive — never open the editor)
+
+Always pass **both** tag name and message on the command line:
+
+```bash
+git tag -a "vX.Y.Z" -m "vX.Y.Z"
+```
+
+Do **not** run bare `git tag vX.Y.Z` (Git may open an editor for the annotation).
+
+Push branch and tag:
+
+```bash
+git push origin HEAD "vX.Y.Z"
+```
+
+## GitHub release (`gh`)
+
+Read `~/.claude/skills/gh/references/releases.md`. Use the repo scripts:
+
+```bash
+GH_SCRIPTS="${GH_SCRIPTS:-$HOME/.claude/skills/gh/scripts}"
+REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo flesler/scip-cli)"
+
+"$GH_SCRIPTS/release-notes.sh" X.Y.Z --install '```bash
+pip install scip-cli=={{VERSION}}
+```'
+
+"$GH_SCRIPTS/sync-github-release.sh" "$REPO" X.Y.Z \
+  --install '```bash
+pip install scip-cli=={{VERSION}}
+```' \
+  --execute
+```
+
+**Do not** run `gh release create` by hand unless the user rejects the script path. **Do not** upload PyPI (`twine`) or run full `./scripts/publish.sh` unless the user explicitly asks.
+
+Report: bump level, new version, tag pushed, release URL, PyPI skipped unless requested.

{scip_cli-3.0.0 → scip_cli-3.2.0}/.agents/rules/agent.mdc

@@ -7,6 +7,8 @@ alwaysApply: true
 
 **Work from repo root.** CLI usage, flags, and user gotchas: `scip-cli skill` (source: `scip_cli/SKILL.md`). Read once per task — do not duplicate SKILL here.
 
+**Cursor:** Skills in `.cursor/skills/` (`test`, `sql-bench`, `new-command`) — folder name = frontmatter `name:`; agent reads when relevant. Slash commands in `.cursor/commands/` only for workflows you invoke (`dogfood`, `migration-problems`, `release`); never pair the same workflow as both.
+
 **Almost always:** bare `scip-cli` on PATH must be **this checkout live** (`pip install -e ".[dev]"`). All examples use `scip-cli` — never `.venv/bin/scip-cli`, `python -m scip_cli`, or other paths. Only swap to PyPI briefly to smoke-test a release.
 
 ## Bootstrap
@@ -34,11 +36,11 @@ Node.js + `npx` required for integration tests (`scip-typescript`). Optional: `S
 |Full suite|`pytest`|
 |E2e loop|`pytest tests/test_e2e.py tests/test_e2e_analyze_patterns.py`|
 |Lint / format|`ruff check .` / `ruff format .`|
-|Typecheck|`basedpyright scip_cli/`|
+|Typecheck|`basedpyright --warnings scip_cli/ scripts/`|
 
-Pre-commit: ruff + ruff-format + basedpyright + full pytest. E2e before commit on command changes.
+Pre-commit, CI, and publish: `./scripts/test.sh` (same gate). No pre-push hook. E2e before commit on command changes.
 
-**Use `scripts/test.sh`** before committing to catch all issues (lint, format, types, tests). This matches what pre-commit runs.
+**Use `scripts/test.sh`** before committing to catch all issues (lint, format, types, tests). This matches what pre-commit and CI run.
 
 ## Improving this repo (do this before review subagents)
 

scip_cli-3.2.0/.agents/skills/new-command/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: new-command
+description: Read when adding or changing a scip-cli CLI subcommand.
+---
+
+# New or changed CLI command
+
+User-facing reference lives in `scip_cli/SKILL.md` + `README.md` (must match `scip_cli/__main__.py` flags). Run `scip-cli skill` to verify dump.
+
+## Checklist
+
+1. **`scip_cli/commands/<name>.py`** — `main(args)`; thin handler. Use `session.setup()` for index DB unless the command is `reindex` / `skill`.
+2. **`scip_cli/__main__.py`** — import; `add_parser`; wire `dispatch["<name>"] = <module>.main`.
+3. **Shared flags** — reuse `scip_cli/cli_args.py` (`add_path_argument`, `add_limit_argument`, …) when siblings use them.
+4. **SQL** — keep queries in `scip_cli/queries.py` or `scip_cli/analyze/`, not fat command modules.
+5. **Docs** — quick-guide row + `### <name>` section in `scip_cli/SKILL.md`; bullet in README § Commands.
+6. **Tests** — `tests/test_e2e.py` (or `test_e2e_analyze_patterns.py` for analyze-only); add `scip_cli.commands.<name>.setup` to `tests/e2e_harness.py` `COMMAND_SETUP_PATHS`.
+7. **Verify** — follow skill `test`; run narrowed pytest then e2e loop.
+
+## Patterns
+
+- **Read-only DB:** `db, project_root = setup()` in `try` / `finally: db.close()`. Connection already has `configure_read_connection` via `get_db`.
+- **Errors:** raise `RuntimeError` or let `sqlite3.Error` bubble — `__main__.main` maps them to stderr + exit code.
+- **Output:** stdout = records; stderr = warnings (match existing commands).
+
+## Map
+
+|Concern|Path|
+|---|---|
+|Entry / argparse|`scip_cli/__main__.py`|
+|Handlers|`scip_cli/commands/`|
+|Index open|`scip_cli/session.py`, `scip_cli/indexing/core.py`|
+|User skill install|`scip-cli skill <path>` copies `scip_cli/SKILL.md`|
+
+## Cursor repo conventions
+
+- **Skills** (`.cursor/skills/<name>/`, frontmatter `name:` = folder name): agent reads when the task matches — e.g. `test`, `sql-bench`, `new-command`.
+- **Commands** (`.cursor/commands/`): only workflows **you** invoke with slash — e.g. `dogfood`, `migration-problems`. Never duplicate the same workflow as a skill and a command.

scip_cli-3.2.0/.agents/skills/sql-bench/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: sql-bench
+description: Read when changing queries.py, analyze SQL, symbols SQL, or sql.py.
+---
+
+# SQL / query performance
+
+Small fixture DB hides regressions on 40MB+ indexes. CI perf tests only catch gross mistakes on the tiny project.
+
+## Required before commit
+
+Touching `scip_cli/queries.py`, `scip_cli/analyze/*`, `scip_cli/symbols.py` SQL, or `scip_cli/sql.py`:
+
+```bash
+scripts/bench.sh --baseline   # once per change series
+# … edit …
+scripts/bench.sh --compare
+```
+
+Synthetic scale: `tests/bench_db.py` + `tests/test_bench_queries.py`. Lines `BENCH:<name>:<ms>`; compare table ratio >1.0 = regression.
+
+## Correctness vs speed
+
+- Behavior / SCIP shapes → fixture e2e (skill `test`).
+- Graph plumbing only → `analyze_db` unit tests.
+
+## Optional: real cached index
+
+Replace `<project-slug>` under `~/.cache/scip-cli/projects/` — snippet in `agent.mdc` § Large cached index benchmark.

scip_cli-3.2.0/.agents/skills/test/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: test
+description: Read when running or writing scip-cli tests (pytest, e2e, CI parity).
+---
+
+# scip-cli tests
+
+Repo root only. Bootstrap: `.cursor/rules/agent.mdc` (editable install, Node for fixture index).
+
+## Pick a suite
+
+|Goal|Command|
+|---|---|
+|Pre-commit / CI / publish|`scripts/test.sh`|
+|Full|`pytest`|
+|CLI + fixture index|`pytest tests/test_e2e.py tests/test_e2e_analyze_patterns.py`|
+|One class / test|`pytest tests/test_e2e.py::TestQuery -q`|
+|Analyze unit / graph|`pytest tests/test_analyze_graph.py tests/test_analyze.py`|
+|SQL perf (not correctness)|`scripts/bench.sh` — see skill `sql-bench`|
+
+`scripts/test.sh` uses `.venv/bin/{ruff,basedpyright,pytest}`; create venv + `pip install -e ".[dev]"` if missing.
+
+## E2e rules
+
+- In-process only: `tests/e2e_harness.py` (`CliRunner`, `run_cli`) patches `scip_cli.commands.<cmd>.setup` — **never** subprocess `scip-cli` in tests.
+- **Never** call `reindex` in e2e (mutates `~/.cache/scip-cli`).
+- Session fixture `indexed_fixture` indexes `tests/fixtures/typescript-project/` once (real `scip-typescript`).
+- Stable symbols/paths: add constants to `tests/fixture_catalog.py`; import in tests — do not hardcode fixture paths in test bodies.
+- New CLI command: append `scip_cli.commands.<cmd>.setup` to `COMMAND_SETUP_PATHS` in `e2e_harness.py`.
+
+## Fixture vs in-memory DB
+
+|Need|Layer|
+|---|---|
+|SCIP symbol shapes, analyze false positives, CLI output|Fixture e2e (`test_e2e*.py`)|
+|Tarjan, section wiring, one-off SQL plumbing|`tests/analyze_db.py` + `test_analyze_graph.py`|
+
+Prefer fixture e2e for indexer-dependent behavior. Details: `agent.mdc` § TDD.
+
+## After command / flag changes
+
+Run e2e loop at minimum before commit; `scripts/test.sh` before push.

{scip_cli-3.0.0 → scip_cli-3.2.0}/.gitignore

@@ -45,7 +45,6 @@ Thumbs.db
 # Project specific
 TODO.md
 todo.md
-dogfood.md
 
 # Local-only dev scripts (repo-specific smoke harnesses)
 scripts/deep-smoke.sh

scip_cli-3.2.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ci-gate
+        name: CI gate (scripts/test.sh)
+        entry: bash scripts/test.sh
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-commit]

{scip_cli-3.0.0 → scip_cli-3.2.0}/CONTRIBUTING.md

@@ -48,11 +48,10 @@ cd scip-cli
 # Install with dev dependencies
 pip install -e ".[dev]"
 
-# Install pre-commit hooks
+# Install pre-commit hook (same command as CI — no pre-push hook)
 pre-commit install
 
-# Run tests
-pytest
+./scripts/test.sh
 
 # Run linter
 ruff check .

{scip_cli-3.0.0 → scip_cli-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scip-cli
-Version: 3.0.0
+Version: 3.2.0
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -26,6 +26,8 @@ Description-Content-Type: text/markdown
 
 Python CLI for AI agents. Queries SCIP indexes for precise refs, definitions, and repo health analysis — TypeScript/JavaScript, Python, Go, Rust.
 
+**Related (optional):** [scip-atlas](https://github.com/flesler/scip-atlas) builds `atlas.db` (git paths, commits, owners) from this cache's `index.db`. [scip-atlas-web](https://github.com/flesler/scip-atlas-web) packs both into a slim DB and a single-file browser explorer. You do not need them for CLI or agent workflows.
+
 ## Why
 
 AI agents waste tokens on grep and file scanning. scip-cli gives them precise, type-aware code navigation in milliseconds — and `analyze` surfaces dead code, cycles, and coupling so agents (and humans) can fix real problems fast.
@@ -91,7 +93,7 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 ```
 
-Tests and lint: `pytest`, `ruff check .`, `basedpyright scip_cli/` from the same environment (or `scripts/test.sh` for the publish gate).
+Tests and lint: `scripts/test.sh` (same as CI and pre-commit), or run `pytest`, `ruff check .`, `basedpyright --warnings scip_cli/ scripts/` from `.venv`.
 
 ### 2. Install prerequisites (optional)
 
@@ -101,7 +103,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 +112,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
@@ -153,8 +157,9 @@ scip-cli <command> [arguments]
 - `rdeps <file>` - Find files that depend on a file (`--path`)
 - `deps <symbol|file>` - Find outbound dependencies (what a symbol or file calls) (`--path`, `--paths-only`)
 - `members <symbol>` - List members of a class/interface (`--path`)
+- `query <sql>` - SQL against the project index (`--format tsv|csv|json`, default tsv; read-only unless `--write`)
 - `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
@@ -190,6 +195,10 @@ scip-cli members Widget
 # Project health dashboard (or: scip-cli analyze src/foo.ts / scip-cli analyze greet)
 scip-cli analyze
 
+# List index tables / columns (read-only SQL)
+scip-cli query "SELECT name FROM sqlite_schema WHERE type='table' ORDER BY 1"
+scip-cli query "PRAGMA table_info(global_symbols)"
+
 # Install skill file
 scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
 ```
@@ -222,7 +231,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 `python scripts/bench_incremental_gate.py --branch fixture`.
 
 ## Configuration
 
@@ -249,27 +261,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`.
 
@@ -297,7 +310,7 @@ Sections are tagged `[high]`, `[medium]`, `[low]` and listed in that order.
 |---|---|---|
 |**high**|Cycles, dead exports, dead files, stale types (unreferenced is omitted when dead exports is on)|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`|
+|**low**|Single-importer files (`[test-only]` when sole importer is tests), 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.
 
@@ -323,7 +336,7 @@ scip-cli analyze scip_cli --limit 15              # directory: scoped project +
 
 **Defaults:** project-wide and directory analyze skip `tests/`, `*.test.*`, `*.spec.*`, `conftest.py`, and `__tests__/`. Pass `--include-tests` to include them. File-target analyze always includes that file.
 
-**Limits:** "Dead export" means no cross-file mentions in the index — not unreachable code. Same-file private helpers are expected. Re-run `reindex` after large changes; the index is a snapshot.
+**Limits:** "Dead export" means no cross-file mentions in the index — not unreachable code. Same-file private helpers are expected. Shebang lines and manifest entrypoints (`package.json` main/bin/scripts with dist→src mapping for TypeScript; Python `pyproject`/`setup.py`/`setup.cfg` scripts) are excluded from project-level dead files and dead exports. Re-run `reindex` after large changes; the index is a snapshot.
 
 ## Performance
 
@@ -338,35 +351,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.0.0 → scip_cli-3.2.0}/README.md

@@ -5,6 +5,8 @@
 
 Python CLI for AI agents. Queries SCIP indexes for precise refs, definitions, and repo health analysis — TypeScript/JavaScript, Python, Go, Rust.
 
+**Related (optional):** [scip-atlas](https://github.com/flesler/scip-atlas) builds `atlas.db` (git paths, commits, owners) from this cache's `index.db`. [scip-atlas-web](https://github.com/flesler/scip-atlas-web) packs both into a slim DB and a single-file browser explorer. You do not need them for CLI or agent workflows.
+
 ## Why
 
 AI agents waste tokens on grep and file scanning. scip-cli gives them precise, type-aware code navigation in milliseconds — and `analyze` surfaces dead code, cycles, and coupling so agents (and humans) can fix real problems fast.
@@ -70,7 +72,7 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e ".[dev]"
 ```
 
-Tests and lint: `pytest`, `ruff check .`, `basedpyright scip_cli/` from the same environment (or `scripts/test.sh` for the publish gate).
+Tests and lint: `scripts/test.sh` (same as CI and pre-commit), or run `pytest`, `ruff check .`, `basedpyright --warnings scip_cli/ scripts/` from `.venv`.
 
 ### 2. Install prerequisites (optional)
 
@@ -80,7 +82,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 +91,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
@@ -132,8 +136,9 @@ scip-cli <command> [arguments]
 - `rdeps <file>` - Find files that depend on a file (`--path`)
 - `deps <symbol|file>` - Find outbound dependencies (what a symbol or file calls) (`--path`, `--paths-only`)
 - `members <symbol>` - List members of a class/interface (`--path`)
+- `query <sql>` - SQL against the project index (`--format tsv|csv|json`, default tsv; read-only unless `--write`)
 - `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
@@ -169,6 +174,10 @@ scip-cli members Widget
 # Project health dashboard (or: scip-cli analyze src/foo.ts / scip-cli analyze greet)
 scip-cli analyze
 
+# List index tables / columns (read-only SQL)
+scip-cli query "SELECT name FROM sqlite_schema WHERE type='table' ORDER BY 1"
+scip-cli query "PRAGMA table_info(global_symbols)"
+
 # Install skill file
 scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
 ```
@@ -201,7 +210,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 `python scripts/bench_incremental_gate.py --branch fixture`.
 
 ## Configuration
 
@@ -228,27 +240,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`.
 
@@ -276,7 +289,7 @@ Sections are tagged `[high]`, `[medium]`, `[low]` and listed in that order.
 |---|---|---|
 |**high**|Cycles, dead exports, dead files, stale types (unreferenced is omitted when dead exports is on)|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`|
+|**low**|Single-importer files (`[test-only]` when sole importer is tests), 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.
 
@@ -302,7 +315,7 @@ scip-cli analyze scip_cli --limit 15              # directory: scoped project +
 
 **Defaults:** project-wide and directory analyze skip `tests/`, `*.test.*`, `*.spec.*`, `conftest.py`, and `__tests__/`. Pass `--include-tests` to include them. File-target analyze always includes that file.
 
-**Limits:** "Dead export" means no cross-file mentions in the index — not unreachable code. Same-file private helpers are expected. Re-run `reindex` after large changes; the index is a snapshot.
+**Limits:** "Dead export" means no cross-file mentions in the index — not unreachable code. Same-file private helpers are expected. Shebang lines and manifest entrypoints (`package.json` main/bin/scripts with dist→src mapping for TypeScript; Python `pyproject`/`setup.py`/`setup.cfg` scripts) are excluded from project-level dead files and dead exports. Re-run `reindex` after large changes; the index is a snapshot.
 
 ## Performance
 
@@ -317,35 +330,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