scip-cli 1.2.0__tar.gz → 1.3.0__tar.gz

{scip_cli-1.2.0/scip_cli.egg-info → scip_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 1.2.0
+Version: 1.3.0
 Summary: Fast code intelligence via SCIP indexes
 Home-page: https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -79,18 +79,21 @@ python -m scip_cli --help
 
 ### 2. Install prerequisites (optional)
 
-scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
+On **first index**, scip-cli runs language indexers and builds a SQLite cache. You can let it fetch tools on demand, or install them globally ahead of time so the first run does not download via `npx`:
 
 **Option A: Zero extra setup (recommended)**
 
 Install `scip-cli` and run it. On first index, scip-cli will:
 
-- Download `scip-typescript` / `scip-python` via `npx` when needed
+- Download `scip-typescript` / `scip-python` via `npx` 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`
 
-No `.scip-cli.json` required — TypeScript monorepos are discovered by walking the repo for `tsconfig*.json` files (skipping `node_modules`, `.git`, etc.).
+No `.scip-cli.json` required for discovery. Subsequent queries read the cached database only.
 
-**Option B: Install globally for better performance**
+**Option B: Install indexers globally ahead of time**
+
+Same indexing steps as Option A; this only avoids `npx` download on the first run:
 
 ```bash
 # TypeScript/JavaScript indexer (also handles plain JS via --infer-tsconfig)
@@ -127,7 +130,7 @@ scip-cli <command> [arguments]
 - `symbols <file>` - List all symbols in a file (`--path`; bare filename OK)
 - `rdeps <file>` - Find files that depend on a file (`--path`)
 - `members <symbol>` - List members of a class/interface (`--path`)
-- `reindex` - Force re-indexing of the current project
+- `reindex` - Force re-indexing of the current project (`--path` to limit scope; repeatable)
 - `skill [path]` - Install or dump the SKILL.md
 
 ### Examples
@@ -160,7 +163,7 @@ scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
 
 ### Pipelines
 
-Stdout is one record per line; stderr carries warnings. Pipe-friendly flags: `refs --paths-only`, `search --names-only` / `--paths-only`, `members --names-only`. `rdeps` already prints bare file paths.
+Stdout is one record per line; stderr carries warnings and ambiguity notices. Kinds are lowercase (`function`, `class`, `method`, `property`, `variable`). Pipe-friendly flags: `refs --paths-only`, `search --names-only` / `--paths-only`, `members --names-only`. `rdeps` already prints bare file paths.
 
 ```bash
 # What do importers of this file export?
@@ -180,10 +183,10 @@ scip-cli members Widget --names-only | xargs -I{} scip-cli def Widget.{}
 
 1. On first query, automatically detects project language from `package.json` (TS/JS) or `pyproject.toml`/`setup.py` (Python)
 2. For TypeScript monorepos, walks the repository for `tsconfig*.json` project roots (nested ancestors deduped; root included only when its `include` is broad)
-3. Indexes using `scip-typescript` (adds `--infer-tsconfig` for JS-only projects) or `scip-python`
-4. Converts the SCIP index to SQLite using `scip expt-convert`
-5. Caches the database in `~/.cache/scip-cli/projects/<project-hash>-<config-hash>/index.db`
-6. Subsequent queries are instant SQLite lookups
+3. Runs `scip-typescript` per project (in parallel when there are multiple projects; set `SCIP_CLI_INDEX_WORKERS=1` to force serial), or `scip-python` for Python
+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)
 
 ## Configuration
 
@@ -192,16 +195,27 @@ Optional `.scip-cli.json` in the project root:
 ```json
 {
   "maxHeapMb": 8192,
-  "indexRoots": ["packages/api", "services/worker"],
+  "indexRoots": ["packages/core", "apps/worker"],
   "onlyIndexRoots": false
 }
 ```
 
 - `maxHeapMb` — Node heap for `scip-typescript` / `scip-python` (default **8192 MB** when omitted). Overridden by `SCIP_CLI_MAX_HEAP_MB`. This is the V8 heap cap, not total RAM usage.
-- `indexRoots` — extra TypeScript project directories to index, merged with auto-discovered projects.
-- `onlyIndexRoots` — skip auto-discovery and index only `indexRoots` (faster for focused work).
+- `indexRoots` — extra TypeScript project directories to include on **first index**, merged with auto-discovered projects.
+- `onlyIndexRoots` — skip auto-discovery and index **only** `indexRoots` (smaller initial index when you only care about part of a monorepo).
+
+`SCIP_CLI_INDEX_WORKERS` controls parallel `scip-typescript` runs during first index (default: up to 8). Merge into one database is always serial.
+
+Scoped indexing without editing `.scip-cli.json`:
+
+```bash
+scip-cli reindex --path entrypoints/server
+scip-cli reindex --path packages/api --path packages/worker
+```
+
+`--path` limits which discovered tsconfig projects are indexed (prefix match, same idea as query `--path`). 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`.
 
-Changing `.scip-cli.json` indexing options (`indexRoots`, `onlyIndexRoots`) uses a separate cache entry automatically. Run `scip-cli reindex` to refresh an existing cache after code changes.
+Run `scip-cli reindex` after changing scope, `.scip-cli.json` index settings, or when you want a fresh index.
 
 This is separate from `.scipquery.json`, which belongs to [scip-query](https://github.com/PlunderStruck/scip-query) and configures its analyzers, watch mode, and diff-gate — not read by scip-cli.
 

{scip_cli-1.2.0 → scip_cli-1.3.0}/README.md

@@ -55,18 +55,21 @@ python -m scip_cli --help
 
 ### 2. Install prerequisites (optional)
 
-scip-cli can automatically download the required indexing tools when needed, or you can install them globally for faster performance:
+On **first index**, scip-cli runs language indexers and builds a SQLite cache. You can let it fetch tools on demand, or install them globally ahead of time so the first run does not download via `npx`:
 
 **Option A: Zero extra setup (recommended)**
 
 Install `scip-cli` and run it. On first index, scip-cli will:
 
-- Download `scip-typescript` / `scip-python` via `npx` when needed
+- Download `scip-typescript` / `scip-python` via `npx` 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`
 
-No `.scip-cli.json` required — TypeScript monorepos are discovered by walking the repo for `tsconfig*.json` files (skipping `node_modules`, `.git`, etc.).
+No `.scip-cli.json` required for discovery. Subsequent queries read the cached database only.
 
-**Option B: Install globally for better performance**
+**Option B: Install indexers globally ahead of time**
+
+Same indexing steps as Option A; this only avoids `npx` download on the first run:
 
 ```bash
 # TypeScript/JavaScript indexer (also handles plain JS via --infer-tsconfig)
@@ -103,7 +106,7 @@ scip-cli <command> [arguments]
 - `symbols <file>` - List all symbols in a file (`--path`; bare filename OK)
 - `rdeps <file>` - Find files that depend on a file (`--path`)
 - `members <symbol>` - List members of a class/interface (`--path`)
-- `reindex` - Force re-indexing of the current project
+- `reindex` - Force re-indexing of the current project (`--path` to limit scope; repeatable)
 - `skill [path]` - Install or dump the SKILL.md
 
 ### Examples
@@ -136,7 +139,7 @@ scip-cli skill ~/.claude/skills/scip-cli/SKILL.md
 
 ### Pipelines
 
-Stdout is one record per line; stderr carries warnings. Pipe-friendly flags: `refs --paths-only`, `search --names-only` / `--paths-only`, `members --names-only`. `rdeps` already prints bare file paths.
+Stdout is one record per line; stderr carries warnings and ambiguity notices. Kinds are lowercase (`function`, `class`, `method`, `property`, `variable`). Pipe-friendly flags: `refs --paths-only`, `search --names-only` / `--paths-only`, `members --names-only`. `rdeps` already prints bare file paths.
 
 ```bash
 # What do importers of this file export?
@@ -156,10 +159,10 @@ scip-cli members Widget --names-only | xargs -I{} scip-cli def Widget.{}
 
 1. On first query, automatically detects project language from `package.json` (TS/JS) or `pyproject.toml`/`setup.py` (Python)
 2. For TypeScript monorepos, walks the repository for `tsconfig*.json` project roots (nested ancestors deduped; root included only when its `include` is broad)
-3. Indexes using `scip-typescript` (adds `--infer-tsconfig` for JS-only projects) or `scip-python`
-4. Converts the SCIP index to SQLite using `scip expt-convert`
-5. Caches the database in `~/.cache/scip-cli/projects/<project-hash>-<config-hash>/index.db`
-6. Subsequent queries are instant SQLite lookups
+3. Runs `scip-typescript` per project (in parallel when there are multiple projects; set `SCIP_CLI_INDEX_WORKERS=1` to force serial), or `scip-python` for Python
+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)
 
 ## Configuration
 
@@ -168,16 +171,27 @@ Optional `.scip-cli.json` in the project root:
 ```json
 {
   "maxHeapMb": 8192,
-  "indexRoots": ["packages/api", "services/worker"],
+  "indexRoots": ["packages/core", "apps/worker"],
   "onlyIndexRoots": false
 }
 ```
 
 - `maxHeapMb` — Node heap for `scip-typescript` / `scip-python` (default **8192 MB** when omitted). Overridden by `SCIP_CLI_MAX_HEAP_MB`. This is the V8 heap cap, not total RAM usage.
-- `indexRoots` — extra TypeScript project directories to index, merged with auto-discovered projects.
-- `onlyIndexRoots` — skip auto-discovery and index only `indexRoots` (faster for focused work).
+- `indexRoots` — extra TypeScript project directories to include on **first index**, merged with auto-discovered projects.
+- `onlyIndexRoots` — skip auto-discovery and index **only** `indexRoots` (smaller initial index when you only care about part of a monorepo).
+
+`SCIP_CLI_INDEX_WORKERS` controls parallel `scip-typescript` runs during first index (default: up to 8). Merge into one database is always serial.
+
+Scoped indexing without editing `.scip-cli.json`:
+
+```bash
+scip-cli reindex --path entrypoints/server
+scip-cli reindex --path packages/api --path packages/worker
+```
+
+`--path` limits which discovered tsconfig projects are indexed (prefix match, same idea as query `--path`). 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`.
 
-Changing `.scip-cli.json` indexing options (`indexRoots`, `onlyIndexRoots`) uses a separate cache entry automatically. Run `scip-cli reindex` to refresh an existing cache after code changes.
+Run `scip-cli reindex` after changing scope, `.scip-cli.json` index settings, or when you want a fresh index.
 
 This is separate from `.scipquery.json`, which belongs to [scip-query](https://github.com/PlunderStruck/scip-query) and configures its analyzers, watch mode, and diff-gate — not read by scip-cli.
 

{scip_cli-1.2.0 → scip_cli-1.3.0}/scip_cli/SKILL.md

@@ -22,7 +22,7 @@ All commands are sub-commands of `scip-cli`. Run from the project root.
 
 - **Bare names** resolve functions, types (aliases + interfaces), and classes. Use dotted qualifiers to disambiguate members: `def Widget.run`, `refs Foo.setBar`, `search MyClass.myMethod`, `members pkg.MyClass`. Consts/variables need `def --kind variable X` or `search --kind variable X`. Class methods need `members ClassName`, not bare `def methodName`.
 - **Ambiguous types** (e.g. `Opts` in multiple hooks) — `def` returns all matches; `refs` returns refs for all matching symbols. Use `--limit N` to cap results, or use `search` with a more specific pattern to disambiguate.
-- **First run** in a project may auto-index (one-time wait; large monorepos with many `tsconfig.json` files take longer). JS-only projects (no `tsconfig.json`) are supported automatically.
+- **First run** in a project may auto-index (one-time wait; large monorepos with many `tsconfig.json` files take longer). Projects index in parallel by default (`SCIP_CLI_INDEX_WORKERS`; merge is serial). JS-only projects (no `tsconfig.json`) are supported automatically.
 - **Monorepos** are indexed by walking for `tsconfig*.json` under the repo (skips `node_modules`, `.git`, etc.). Nested parent/child projects are deduped. Add extra roots or limit indexing with `.scip-cli.json` (see README). Use `--path packages/api` (or any file/dir) to scope queries.
 - **Prerequisites**: Node.js (for `npx` indexers). The `scip` converter auto-downloads on first use if missing; `scip-typescript` / `scip-python` download via `npx`. Optional `.scip-cli.json` for extra index roots or heap tuning. `brew install scip` installs an unrelated optimization solver — scip-cli ignores it and downloads the real binary.
 
@@ -48,7 +48,7 @@ refs [--limit N] [--path PATH] [--paths-only] <symbol>
 
 Returns `file:line` for each reference. Reads source files to find exact line numbers.
 
-Default `--limit` is 10. When multiple symbols match, refs are grouped by symbol with `# <symbol>` headers. Use `--paths-only` for unique file paths (pipe-friendly).
+Default `--limit` is 10. When multiple symbols match, refs are grouped by symbol with `# <leaf-name>` headers on **stderr** (stdout stays pipe-clean). Use `--paths-only` for unique file paths (pipe-friendly).
 
 ### Pipelines
 
@@ -75,7 +75,7 @@ Each `xargs` invocation reopens the index (fast on cache hit). Use `--limit` on
 search [--kind <kind>] [--limit N] [--path PATH] [--names-only] [--paths-only] <pattern>
 ```
 
-Returns `file:line Kind symbolName`. Filters noisy symbols (file-level, parameters, type literals).
+Returns `file:line kind symbolName` (kinds are lowercase: `function`, `class`, etc.). Filters noisy symbols (file-level, parameters, type literals).
 
 Default `--limit` is 10.
 

{scip_cli-1.2.0 → scip_cli-1.3.0}/scip_cli/__init__.py

@@ -1,2 +1,2 @@
 """scip-cli: Fast code intelligence via SCIP indexes."""
-__version__ = "1.2.0"
+__version__ = "1.3.0"

{scip_cli-1.2.0 → scip_cli-1.3.0}/scip_cli/__main__.py

@@ -6,7 +6,7 @@ import sqlite3
 import sys
 
 from . import __version__
-from .cli_args import add_names_only_argument, add_path_argument, add_paths_only_argument, add_paths_only_argument
+from .cli_args import add_names_only_argument, add_path_argument, add_paths_only_argument
 from .symbols import SymbolKind
 from .commands import refs, def_cmd, search, symbols, rdeps, members, skill, reindex
 
@@ -87,7 +87,13 @@ def main():
     skill_parser.add_argument("path", nargs="?", help="Optional file path to write to (creates dirs)")
 
     # reindex
-    subparsers.add_parser("reindex", help="Force re-indexing of the current project")
+    reindex_parser = subparsers.add_parser("reindex", help="Force re-indexing of the current project")
+    reindex_parser.add_argument(
+        "--path",
+        action="append",
+        metavar="PATH",
+        help="Index only tsconfig projects under PATH (repeatable; persisted until full reindex)",
+    )
 
     args = parser.parse_args()
 

scip_cli-1.3.0/scip_cli/cache.py

@@ -0,0 +1,70 @@
+"""Index cache path resolution."""
+import re
+from pathlib import Path
+
+from .project import find_project_root
+from .scope import project_root_hash
+
+INDEX_DB = "index.db"
+INDEX_DB_NEXT = "index.db.next"
+CACHE_SLUG_MAX_LEN = 48
+
+
+def index_db_path(cache_dir: Path, *, replace: bool = False) -> Path:
+    return Path(cache_dir) / (INDEX_DB_NEXT if replace else INDEX_DB)
+
+
+def _unlink_sqlite_sidecars(db_path: Path) -> None:
+    for suffix in ("-wal", "-shm"):
+        sidecar = Path(f"{db_path}{suffix}")
+        if sidecar.is_file():
+            sidecar.unlink()
+
+
+def cleanup_in_progress_index(cache_dir: Path) -> None:
+    """Remove a failed or abandoned index.db.next build."""
+    next_db = index_db_path(cache_dir, replace=True)
+    if next_db.is_file():
+        next_db.unlink()
+    _unlink_sqlite_sidecars(next_db)
+
+
+def promote_next_index(cache_dir: Path) -> None:
+    """Atomically swap index.db.next over the live index.db."""
+    cache_dir = Path(cache_dir)
+    next_db = index_db_path(cache_dir, replace=True)
+    live_db = index_db_path(cache_dir, replace=False)
+    if not next_db.is_file():
+        raise RuntimeError("index.db.next is missing")
+
+    _unlink_sqlite_sidecars(live_db)
+    if live_db.is_file():
+        live_db.unlink()
+    next_db.rename(live_db)
+
+
+def project_cache_slug(project_root: Path) -> str:
+    """Human-readable cache directory name for a project root."""
+    root = Path(project_root).resolve()
+    parts = root.parts
+    slug_base = root.name or (parts[-1] if parts else "project")
+    slug = re.sub(r"[^a-zA-Z0-9._-]+", "-", slug_base).strip("-") or "project"
+    if len(slug) > CACHE_SLUG_MAX_LEN:
+        slug = slug[:CACHE_SLUG_MAX_LEN].rstrip("-")
+    digest = project_root_hash(root)[:6]
+    return f"{slug}-{digest}"
+
+
+def get_cache_dir(project_root):
+    """Get the cache directory for a project (one dir per repo root)."""
+    root = Path(project_root).resolve()
+    return Path.home() / ".cache" / "scip-cli" / "projects" / project_cache_slug(root)
+
+
+def find_db(project_root=None):
+    """Find the index.db for the given project (or cwd)."""
+    root = project_root or find_project_root()
+    if not root:
+        return None
+    cache = index_db_path(get_cache_dir(root), replace=False)
+    return cache if cache.is_file() else None

scip_cli-1.3.0/scip_cli/commands/reindex.py

@@ -0,0 +1,55 @@
+"""Force re-indexing of the current project."""
+import sys
+
+from ..cache import (
+    cleanup_in_progress_index,
+    get_cache_dir,
+    index_db_path,
+    promote_next_index,
+)
+from ..indexing import _index_project
+from ..paths import normalize_path_scope
+from ..project import detect_language, find_project_root
+from ..scope import save_index_scope
+
+
+def main(args):
+    root = find_project_root()
+    if not root:
+        print("Error: Could not find project root", file=sys.stderr)
+        sys.exit(1)
+
+    path_args = getattr(args, "path", None) or []
+    if path_args:
+        scope_paths = [normalize_path_scope(path, root) for path in path_args]
+        save_index_scope(root, scope_paths)
+        print(f"Index scope: {', '.join(scope_paths)}", file=sys.stderr)
+    else:
+        save_index_scope(root, None)
+
+    cache_dir = get_cache_dir(root)
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    cleanup_in_progress_index(cache_dir)
+
+    lang = detect_language(root)
+    if lang is None:
+        print(f"Error: No supported project markers found in {root}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Re-indexing {root} ({lang})...", file=sys.stderr)
+    try:
+        _index_project(root, lang, cache_dir, replace=True)
+    except RuntimeError as e:
+        cleanup_in_progress_index(cache_dir)
+        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():
+        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)
+    print(f"Updated {index_db_path(cache_dir, replace=False)}", file=sys.stderr)
+    print("Re-indexing complete", file=sys.stderr)

{scip_cli-1.2.0 → scip_cli-1.3.0}/scip_cli/commands/search.py

@@ -43,7 +43,7 @@ def is_noisy_symbol(symbol_str):
         return True
     if symbol_str.endswith("/__init__:"):
         return True
-    if "typeLiteral" in symbol_str:
+    if "typeLiteral" in symbol_str and infer_kind(symbol_str) != SymbolKind.PROPERTY:
         return True
     if ").(" in symbol_str:
         return True

{scip_cli-1.2.0 → scip_cli-1.3.0}/scip_cli/constants.py

@@ -1,7 +1,14 @@
 """Shared constants for scip-cli."""
 
+import os
+
 INDEX_TIMEOUT = 300
 DEFAULT_MAX_HEAP_MB = 8192
 DEFAULT_MAX_DEF_LINES = 80
 DEFAULT_MAX_DEF_CHARS = 32_000
 SCIP_INSTALL_URL = "https://github.com/scip-code/scip/releases"
+
+
+def default_index_workers() -> int:
+    """Default parallel TypeScript project indexers (merge stays single-threaded)."""
+    return min(8, os.cpu_count() or 4)

{scip_cli-1.2.0 → scip_cli-1.3.0}/scip_cli/indexing.py

@@ -8,12 +8,14 @@ import sqlite3
 import subprocess
 import sys
 import tempfile
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from pathlib import Path
 
-from .cache import find_db, get_cache_dir
+from .cache import find_db, get_cache_dir, index_db_path
 from .config import CONFIG_FILENAME, load_project_config, resolve_index_roots
-from .constants import DEFAULT_MAX_HEAP_MB, INDEX_TIMEOUT, SCIP_INSTALL_URL
+from .constants import DEFAULT_MAX_HEAP_MB, INDEX_TIMEOUT, SCIP_INSTALL_URL, default_index_workers
 from .discover import discover_typescript_projects
+from .scope import load_index_scope, projects_matching_scope
 from .merge import merge_sqlite_indexes
 from .project import detect_language, find_project_root
 from .scip_tool import ensure_scip_binary
@@ -73,6 +75,16 @@ def indexer_env(project_root=None):
 def typescript_projects(root: Path) -> list[Path]:
     """Resolve the TypeScript project list for a repository."""
     settings = load_project_config(root)
+    scope = load_index_scope(root)
+
+    if scope is not None:
+        discovered = list(discover_typescript_projects(root))
+        filtered = projects_matching_scope(discovered, scope.paths)
+        if not filtered:
+            joined = ", ".join(scope.paths)
+            raise RuntimeError(f"No TypeScript projects found under index scope: {joined}")
+        return sorted(filtered, key=str)
+
     configured = resolve_index_roots(root, settings) if settings.index_roots else []
 
     if settings.only_index_roots:
@@ -135,11 +147,10 @@ def _warn_old_scip(binary):
         )
 
 
-def _convert_scip_to_db(scip_path, cache_dir):
-    """Convert a SCIP protobuf file to SQLite in cache_dir/index.db."""
-    cache_dir = Path(cache_dir)
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    db_path = cache_dir / "index.db"
+def _convert_scip_to_db(scip_path, db_path):
+    """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)
     if db_path.exists():
         db_path.unlink()
 
@@ -147,8 +158,8 @@ def _convert_scip_to_db(scip_path, cache_dir):
     _warn_old_scip(scip_binary)
 
     result = _run_subprocess(
-        [scip_binary, "expt-convert", str(scip_path), "--output", "index.db"],
-        cwd=str(cache_dir),
+        [scip_binary, "expt-convert", str(scip_path), "--output", db_path.name],
+        cwd=str(db_path.parent),
     )
     if result.returncode != 0:
         print(result.stderr, file=sys.stderr)
@@ -166,65 +177,132 @@ def _typescript_index_args(root, output_scip, projects):
     return args
 
 
-def _index_typescript(root, cache_dir, projects, env):
-    """Index one or more TypeScript projects and write cache_dir/index.db."""
+def _index_workers():
+    """Parallel workers for per-project scip-typescript runs (merge stays serial)."""
+    env_val = os.environ.get("SCIP_CLI_INDEX_WORKERS")
+    if env_val is not None:
+        try:
+            return max(1, int(env_val))
+        except ValueError:
+            raise RuntimeError(
+                f"Invalid SCIP_CLI_INDEX_WORKERS: expected an integer, got {env_val!r}"
+            ) from None
+    return default_index_workers()
+
+
+def _index_one_ts_project(root, project, work_dir, env):
+    """Index one TypeScript project into work_dir/index.db."""
+    root = Path(root)
+    work_dir = Path(work_dir)
+    work_dir.mkdir(parents=True, exist_ok=True)
+    label = "." if project == Path(".") else str(project)
+    part_scip = work_dir / "index.scip"
+    index_args = _typescript_index_args(root, part_scip, [project])
+    result = run_with_fallback(
+        "scip-typescript",
+        "@sourcegraph/scip-typescript",
+        str(root),
+        index_args,
+        env=env,
+    )
+    if result.returncode != 0:
+        return label, None, result.stderr.strip() or "indexing failed"
+    _convert_scip_to_db(part_scip, work_dir / "index.db")
+    return label, work_dir / "index.db", None
+
+
+def _index_typescript(root, cache_dir, projects, env, *, replace=False):
+    """Index one or more TypeScript projects and write the merged index.db."""
     root = Path(root)
     cache_dir = Path(cache_dir)
+    output_db = index_db_path(cache_dir, replace=replace)
+    workers = _index_workers()
+    use_parallel = len(projects) > 1 and workers > 1
 
     with tempfile.TemporaryDirectory() as tmpdir:
         tmpdir_path = Path(tmpdir)
         part_dbs: list[Path] = []
         skipped = 0
+        total = len(projects)
 
-        for index, project in enumerate(projects, start=1):
-            label = "." if project == Path(".") else str(project)
-            if len(projects) > 1:
-                print(
-                    f"Indexing TypeScript project {index}/{len(projects)}: {label}",
-                    file=sys.stderr,
-                )
-
-            part_scip = tmpdir_path / f"part-{index}.scip"
-            index_args = _typescript_index_args(root, part_scip, [project])
-            result = run_with_fallback(
-                "scip-typescript",
-                "@sourcegraph/scip-typescript",
-                str(root),
-                index_args,
-                env=env,
+        if use_parallel:
+            print(
+                f"Indexing {total} TypeScript projects ({workers} workers; merge is serial)...",
+                file=sys.stderr,
             )
-            if result.returncode != 0:
-                skipped += 1
-                print(
-                    f"Warning: skipped {label}: {result.stderr.strip() or 'indexing failed'}",
-                    file=sys.stderr,
+            completed = 0
+            with ThreadPoolExecutor(max_workers=workers) as pool:
+                futures = {
+                    pool.submit(
+                        _index_one_ts_project,
+                        root,
+                        project,
+                        tmpdir_path / f"part-{index}",
+                        env,
+                    ): index
+                    for index, project in enumerate(projects, start=1)
+                }
+                for future in as_completed(futures):
+                    index = futures[future]
+                    label, db_path, error = future.result()
+                    completed += 1
+                    if db_path is None:
+                        skipped += 1
+                        print(
+                            f"Warning: skipped {label}: {error}",
+                            file=sys.stderr,
+                        )
+                    else:
+                        part_dbs.append((index, db_path))
+                        print(
+                            f"Indexed {completed}/{total}: {label}",
+                            file=sys.stderr,
+                        )
+            part_dbs = [db for _, db in sorted(part_dbs, key=lambda item: item[0])]
+        else:
+            for index, project in enumerate(projects, start=1):
+                label = "." if project == Path(".") else str(project)
+                if total > 1:
+                    print(
+                        f"Indexing TypeScript project {index}/{total}: {label}",
+                        file=sys.stderr,
+                    )
+                label, db_path, error = _index_one_ts_project(
+                    root,
+                    project,
+                    tmpdir_path / f"part-{index}",
+                    env,
                 )
-                continue
-
-            part_cache = tmpdir_path / f"part-{index}"
-            _convert_scip_to_db(part_scip, part_cache)
-            part_dbs.append(part_cache / "index.db")
+                if db_path is None:
+                    skipped += 1
+                    print(f"Warning: skipped {label}: {error}", file=sys.stderr)
+                    continue
+                part_dbs.append(db_path)
 
         if not part_dbs:
             raise RuntimeError("Failed to index project")
 
         indexed = len(part_dbs)
-        total = len(projects)
-        if total > 1:
+        if total > 1 and not use_parallel:
             print(
                 f"Indexed {indexed}/{total} TypeScript projects"
                 + (f" ({skipped} skipped)" if skipped else ""),
                 file=sys.stderr,
             )
+        elif total > 1 and use_parallel:
+            print(
+                f"Finished indexing {indexed}/{total} TypeScript projects"
+                + (f" ({skipped} skipped)" if skipped else ""),
+                file=sys.stderr,
+            )
 
         if len(part_dbs) == 1:
-            shutil.copy2(part_dbs[0], cache_dir / "index.db")
-            return
-
-        merge_sqlite_indexes(part_dbs, cache_dir / "index.db")
+            shutil.copy2(part_dbs[0], output_db)
+        else:
+            merge_sqlite_indexes(part_dbs, output_db)
 
 
-def _index_project(root, lang, cache_dir):
+def _index_project(root, lang, cache_dir, *, replace=False):
     """Run the language-specific indexer and convert to DB."""
     cache_dir = Path(cache_dir)
     cache_dir.mkdir(parents=True, exist_ok=True)
@@ -238,7 +316,7 @@ def _index_project(root, lang, cache_dir):
                 f"Indexing {len(projects)} TypeScript projects",
                 file=sys.stderr,
             )
-        _index_typescript(root, cache_dir, projects, env)
+        _index_typescript(root, cache_dir, projects, env, replace=replace)
         return
 
     with tempfile.TemporaryDirectory() as tmpdir:
@@ -258,7 +336,7 @@ def _index_project(root, lang, cache_dir):
             print(result.stderr, file=sys.stderr)
             raise RuntimeError("Failed to index project")
 
-        _convert_scip_to_db(index_scip, cache_dir)
+        _convert_scip_to_db(index_scip, index_db_path(cache_dir, replace=replace))
 
 
 def get_db(project_root=None):