Metadata-Version: 2.5
Name: scip-atlas
Version: 1.0.0
Summary: Git metadata and search overlay for scip-cli indexes
Project-URL: Homepage, https://github.com/flesler/scip-atlas
Author: Ariel Flesler
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: basedpyright>=1.39.9; extra == 'dev'
Requires-Dist: build>=1; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: tomli>=2.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# scip-atlas

Python CLI that reads a [scip-cli](https://github.com/flesler/scip-cli) SQLite index plus a git worktree and **upserts a sidecar SQLite file** (`atlas.db`). The two databases are the artifact you ship. Consumers `ATTACH` and join on path strings.

## Install

```bash
pip install -e ".[dev]"
pip install -e ../scip-cli   # for integration tests / indexing
pre-commit install

# Fast loop while iterating (skips integration unless sync/summarize core changed):
./scripts/test.sh --changed
# scip-atlas is on PATH inside the active venv (same as scip-cli)
```

## Usage

```bash
# From the repo root (after scip-cli reindex):
cd /path/to/repo
scip-atlas sync
scip-atlas summarize

# Defaults: git root = cwd, index = ~/.cache/scip-cli/projects/<slug>/index.db, sidecar = atlas.db beside index
# Override when needed:
scip-atlas sync --repo /path/to/repo --index /path/to/index.db --sidecar /path/to/atlas.db

# Index can include tests; atlas skips git/summary augment by default (same globs as scip-cli)
scip-atlas sync --include-tests
scip-atlas sync --exclude 'generated/**'

# SQL across index + sidecar (`files`, … are SELECT-only views; sidecar DML via atlas.*):
scip-atlas query 'SELECT COUNT(*) FROM documents d JOIN files f ON f.relative_path = d.relative_path'
scip-atlas query --write "DELETE FROM atlas.files WHERE relative_path = 'path/removed/from/index'"
```

`summarize` uses `~/.config/scip-atlas/config.toml` (`[models.*]` endpoints, `[prompts]`, `[summarize]` limits). First run copies a template and exits until `models.<name>.configured = true`. After upgrading scip-atlas, merge new template keys without losing your models:

```bash
scip-atlas config merge --dry-run   # preview
scip-atlas config merge             # writes backup, then merges
```

See [docs/spec.md](docs/spec.md) § Config file.

## Query without git

Copy both files anywhere (`sync` checkpoints WAL so `atlas.db` alone is enough). Join on `relative_path`. **`scip-atlas query`** attaches the sidecar and exposes sidecar tables as unqualified names for **SELECT** (TEMP VIEWs). **`--write`** allows mutations; target the sidecar with **`atlas.files`**, **`atlas.dirs`**, etc. (not unqualified names). Index writes are possible but prefer `scip-cli reindex`.

```sql
ATTACH '/path/to/atlas.db' AS atlas;

SELECT d.relative_path, ct.name, c.commit_time, c.message
FROM documents d
JOIN atlas.files f ON f.relative_path = d.relative_path
JOIN atlas.commits c ON c.sha = f.commit_sha
JOIN atlas.committers ct ON ct.email = c.committer_email
WHERE d.relative_path = 'src/helper.ts';

SELECT relative_path, name, parent_path
FROM atlas.dirs
WHERE parent_path = 'src';

SELECT relative_path, name FROM atlas.files WHERE name LIKE 'Handler%' LIMIT 10;
```

## Docs

| Doc | What it is |
|-----|------------|
| [docs/prd.md](docs/prd.md) | Why it exists, scope |
| [docs/spec.md](docs/spec.md) | Schema, commands, incremental rules |
| [docs/roadmap.md](docs/roadmap.md) | Staged delivery |
| [CHANGELOG.md](CHANGELOG.md) | Release notes |

## Development

```bash
./scripts/test.sh          # ruff, basedpyright, pytest
./scripts/smoke.sh         # end-to-end: index fixture, sync, ATTACH, FTS
pytest -m integration -q   # needs scip-typescript (npx)
```

## Sibling tools

1. **scip-cli** — SCIP → SQLite index (structure, refs, analyze).
2. **scip-atlas** (this) — git metadata + search overlay + LLM summaries.
