scip-cli 3.1.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.1.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.1.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.1.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.1.0 → scip_cli-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: scip-cli
-Version: 3.1.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)
 
@@ -155,6 +157,7 @@ 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 (`--path`, `--tsconfig`, `--exclude`, `--fresh`, `--no-incremental`; incremental by default in git TS repos)
 - `skill [path]` - Install or dump the SKILL.md
@@ -192,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
 ```
@@ -227,7 +234,7 @@ scip-cli deps greet --paths-only | sort -u
 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`.
+**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
 
@@ -303,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.
 
@@ -329,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
 

{scip_cli-3.1.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)
 
@@ -134,6 +136,7 @@ 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 (`--path`, `--tsconfig`, `--exclude`, `--fresh`, `--no-incremental`; incremental by default in git TS repos)
 - `skill [path]` - Install or dump the SKILL.md
@@ -171,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
 ```
@@ -206,7 +213,7 @@ scip-cli deps greet --paths-only | sort -u
 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`.
+**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
 
@@ -282,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.
 
@@ -308,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
 

{scip_cli-3.1.0 → scip_cli-3.2.0}/scip_cli/SKILL.md

@@ -19,6 +19,7 @@ TypeScript/JavaScript, Python, Go, Rust — not GraphQL, CSS, or other files. Ru
 |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|
+|Raw SQL|`query "SELECT …"`|Rows from `index.db` (`--format tsv|csv|json`)|
 
 Default `--limit` is **10** on query commands unless noted. Stdout = records; stderr = warnings/progress. Pipe with `--paths-only` / `--names-only`.
 
@@ -103,6 +104,22 @@ members [--limit N] [--path PATH] [--names-only] <symbol>
 
 `start:end kind name`. Prefix match under parent; missing ranges filled from source when needed.
 
+### query
+
+```bash
+query [--format tsv|csv|json] [--write] <sql> [...]
+```
+
+SQL against the cached project `index.db`. **Read-only by default** (`PRAGMA query_only`); `--write` allows mutations (commits after each statement). Default `--format` is **tsv** (header row + tab-separated values). `csv` and `json` (array of objects) are also supported. Prefer `reindex` over hand-editing the cache.
+
+Introspect schema (SQLite catalog + `PRAGMA`):
+
+```bash
+query "SELECT name FROM sqlite_schema WHERE type='table' ORDER BY 1"
+query "PRAGMA table_info(mentions)"
+query "SELECT m.name AS table_name, p.name AS column_name, p.type FROM sqlite_schema m JOIN pragma_table_info(m.name) p WHERE m.type='table' AND m.name NOT LIKE 'sqlite_%' ORDER BY 1, p.cid"
+```
+
 ### analyze
 
 ```bash
@@ -116,9 +133,9 @@ analyze [--limit N] [--per-check-limit N] [--path PATH] [--include-tests] [--pri
 |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.
+Priority **high → medium → low**. `[high]` cycles, dead exports, dead files, stale types (project unreferenced omitted when dead exports runs; file unreferenced omitted when dead-in-file runs). `[medium]` same-file-only, change surface (file). `[low]` single-importer files (`[test-only]` tag), test-only consumers, coupling, bottlenecks, hotspots. `--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).
+**Easy wins:** cycles, dead exports, dead files (production). Stale types = types with no external refs. Dead = no cross-file refs in index, not `vulture`. Shebang plus manifest entrypoints (`package.json` main/bin/scripts, dist→src mapping; each Python package for pyproject/setup/setup.cfg) are never project-level dead files/exports. `single_importer_files` rows with only test importers are tagged `[test-only]`. File-scoped `analyze path/to/cli.ts` still reports unused symbols in that file. Empty `rdeps` on a hit is often a SCIP miss — verify with `rg -F STEM` (basename in `(...)`, same-file hits ignored).
 
 ### reindex
 

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

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

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

@@ -18,7 +18,7 @@ from .cli_args import (
     add_paths_only_argument,
     positive_int,
 )
-from .commands import analyze, code, deps, members, rdeps, refs, reindex, search, skill, symbols
+from .commands import analyze, code, deps, members, query, rdeps, refs, reindex, search, skill, symbols
 from .symbols import SymbolKind
 
 # Set up debug logging based on SCIP_CLI_DEBUG env var
@@ -122,6 +122,20 @@ def main() -> None:
     members_parser.add_argument("symbol", help="Symbol name")
 
     # skill
+    query_parser = subparsers.add_parser("query", help="Run SQL against the project index database")
+    query_parser.add_argument("sql", nargs="+", help="SQL to execute")
+    query_parser.add_argument(
+        "--format",
+        choices=("tsv", "csv", "json"),
+        default="tsv",
+        help="Output format (default: tsv)",
+    )
+    query_parser.add_argument(
+        "--write",
+        action="store_true",
+        help="Allow INSERT/UPDATE/DELETE (default: read-only)",
+    )
+
     skill_parser = subparsers.add_parser("skill", help="Install or dump the scip-cli SKILL.md")
     skill_parser.add_argument("path", nargs="?", help="Optional file path to write to (creates dirs)")
 
@@ -234,6 +248,7 @@ def main() -> None:
         "rdeps": rdeps.main,
         "deps": deps.main,
         "members": members.main,
+        "query": query.main,
         "skill": skill.main,
         "analyze": analyze.main,
         "reindex": reindex.main,

{scip_cli-3.1.0 → scip_cli-3.2.0}/scip_cli/analyze/common.py

@@ -161,6 +161,11 @@ def is_test_path(relative_path: str) -> bool:
     return name == "conftest.py"
 
 
+def is_package_init_module(relative_path: str) -> bool:
+    """Python package __init__.py — import surface, not a nuke candidate for dead_files."""
+    return relative_path.replace("\\", "/").endswith("__init__.py")
+
+
 def is_dynamic_loader_path(relative_path: str) -> bool:
     """True for migration files typically loaded by filename; SCIP has no import edge."""
     p = relative_path.replace("\\", "/").lower()

scip_cli-3.2.0/scip_cli/analyze/entrypoints/__init__.py

@@ -0,0 +1,77 @@
+"""CLI entrypoints that SCIP never links via import edges."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from pathlib import Path
+
+from ...project import Language, detect_language
+from ...source import file_has_shebang
+from . import golang as golang_entrypoints
+from . import python as python_entrypoints
+from . import rust as rust_entrypoints
+from . import typescript as typescript_entrypoints
+from .paths import canonical_rel
+
+_DECLARED_LOADERS = {
+    Language.TYPESCRIPT: typescript_entrypoints.declared_entrypoint_paths,
+    Language.PYTHON: python_entrypoints.declared_entrypoint_paths,
+    Language.GOLANG: golang_entrypoints.declared_entrypoint_paths,
+    Language.RUST: rust_entrypoints.declared_entrypoint_paths,
+}
+
+
+class EntrypointIndex:
+    """Declared CLI entrypoints (manifest + shebang) for one analyze pass."""
+
+    _root: Path | None
+    _declared_paths: set[str]
+    _shebang_cache: dict[str, bool]
+
+    def __init__(self, project_root: Path | None) -> None:
+        self._root = project_root.resolve() if project_root is not None else None
+        self._declared_paths = set()
+        self._shebang_cache = {}
+        if self._root is not None:
+            lang = detect_language(self._root)
+            if lang is not None:
+                loader = _DECLARED_LOADERS.get(lang)
+                if loader is not None:
+                    self._declared_paths.update(loader(self._root))
+
+    def is_entrypoint(self, relative_path: str) -> bool:
+        if self._root is None:
+            return False
+        canonical = canonical_rel(relative_path)
+        if canonical in self._declared_paths:
+            return True
+        if python_entrypoints.is_python_entrypoint_file(relative_path):
+            return True
+        if canonical in self._shebang_cache:
+            return self._shebang_cache[canonical]
+        has_shebang = file_has_shebang(self._root, relative_path)
+        self._shebang_cache[canonical] = has_shebang
+        return has_shebang
+
+
+_CURRENT: ContextVar[EntrypointIndex | None] = ContextVar("scip_cli_entrypoint_index", default=None)
+
+
+def bind_entrypoints(project_root: Path | str | None) -> object:
+    root = Path(project_root) if project_root is not None else None
+    return _CURRENT.set(EntrypointIndex(root))
+
+
+def reset_entrypoints(token) -> None:
+    _CURRENT.reset(token)
+
+
+def is_entrypoint_path(relative_path: str) -> bool:
+    index = _CURRENT.get()
+    if index is None:
+        return False
+    return index.is_entrypoint(relative_path)
+
+
+def entrypoints_bound() -> bool:
+    return _CURRENT.get() is not None

scip_cli-3.2.0/scip_cli/analyze/entrypoints/golang.py

@@ -0,0 +1,28 @@
+"""Entrypoints for Go modules (main.go and cmd/*/main.go)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...discover import discover_golang_modules
+from .paths import path_in_repo
+
+
+def declared_entrypoint_paths(project_root: Path) -> set[str]:
+    repo_root = project_root.resolve()
+    paths: set[str] = set()
+    for mod_rel in discover_golang_modules(repo_root):
+        mod_root = repo_root / mod_rel
+        if (mod_root / "main.go").is_file():
+            paths.add(path_in_repo(repo_root, mod_rel, "main.go"))
+        cmd_dir = mod_root / "cmd"
+        if not cmd_dir.is_dir():
+            continue
+        for child in cmd_dir.iterdir():
+            if not child.is_dir():
+                continue
+            main_go = child / "main.go"
+            if main_go.is_file():
+                rel = main_go.relative_to(mod_root).as_posix()
+                paths.add(path_in_repo(repo_root, mod_rel, rel))
+    return paths

scip_cli-3.2.0/scip_cli/analyze/entrypoints/paths.py

@@ -0,0 +1,34 @@
+"""Shared path normalization for entrypoint manifests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def canonical_rel(relative_path: str) -> str:
+    return relative_path.replace("\\", "/").lstrip("./")
+
+
+def path_in_repo(_repo_root: Path, package_rel: Path, path_in_package: str) -> str:
+    """Map a path relative to a package dir to a repo-relative path."""
+    rel = path_in_package.replace("\\", "/").lstrip("./")
+    if not package_rel.parts:
+        return canonical_rel(rel)
+    prefix = package_rel.as_posix().strip("/")
+    return canonical_rel(f"{prefix}/{rel}")
+
+
+def normalize_path_under_root(project_root: Path, raw: str, *, extensions: tuple[str, ...]) -> str | None:
+    text = raw.strip().strip("'\"")
+    if not text:
+        return None
+    if not any(text.endswith(ext) for ext in extensions):
+        return None
+    root = project_root.resolve()
+    path = Path(text)
+    if path.is_absolute():
+        try:
+            return canonical_rel(str(path.resolve().relative_to(root)))
+        except ValueError:
+            return None
+    return canonical_rel(text)