scip-cli 2.5.0__tar.gz → 2.6.0__tar.gz

scip_cli-2.6.0/.agents/commands/migration-problems.md

@@ -0,0 +1,82 @@
+# Document migration problems
+
+Review this session (and any ports you just touched) and append **only** language / tooling walls to `migration-problems.md`.
+
+## Where to write
+
+| Repo | File |
+|------|------|
+| `scip-cli-go` | `migration-problems.md` |
+| `scip-cli-rust` | `migration-problems.md` |
+| `scip-cli-zig` | `migration-problems.md` |
+| `scip-cli` (Python) | Usually **none** — Python is the reference, not a port. Only add a note if the user asks. |
+
+If the workspace is one of the ports, edit that repo’s file. If several ports were touched, update each relevant file. Match existing numbering and section style in that file.
+
+Do **not** invent entries from first principles — only document walls you (or a subagent) actually hit in this work.
+
+---
+
+## Why this file exists
+
+These repos are an experiment: **which language is better for AI to code in?**
+
+`migration-problems.md` is evidence for that question. A reader should learn something about the **language, compiler, stdlib, or ecosystem tooling** — not about scip-cli product bugs or “we forgot a branch.”
+
+Ask before writing:
+
+> *If we ported a different CLI tomorrow, would this entry still teach something about coding in this language with an AI?*
+
+If **no** → do not add it.
+
+---
+
+## What TO put (include)
+
+Fundamental friction that slows or confuses an AI agent because of the **language or its tools**:
+
+| Category | Examples |
+|----------|----------|
+| **Compiler / type system** | Borrow checker traps; Zig shadowing rules; Go’s `module/v2` path rules; errors that force many tiny fix loops |
+| **Stdlib / API drift** | Zig 0.17 removed `std.fs.cwd`; training data assumes older APIs; crate APIs that don’t match Python intuition (`regex` no lookbehind) |
+| **Tooling loop cost** | Full `zig build -Doptimize=ReleaseFast` ~25s+ → fewer AI iterations; `gofmt`/`cargo fmt` rewrite every commit; clippy/rustc so strict the agent flails for N cycles |
+| **Ecosystem surprises** | CGO vs pure-Go SQLite; `anyhow::bail!` prefixes user errors; package name vs import path traps |
+| **Agent × language interaction** | Persistent shell + language-specific env scripts hanging; test runners with no skip → vacuously green |
+
+Entry shape (adapt to the file’s existing voice):
+
+- **Symptom** — what the agent saw (compile error, hang, parity fail)
+- **Cause** — language/tooling root cause (not “we missed a line of business logic”)
+- **Lesson** — what an AI (or human) should remember next time in this language
+- Optional: time sink / iteration count if it was large
+
+Prefer **one sharp entry** over a dump of every compile error.
+
+---
+
+## What NOT to put (exclude)
+
+| Do not document | Why |
+|-----------------|-----|
+| Product / logic bugs (“search printed duplicates”, “forgot DER fallback”) | Same bug in any language; says nothing about Go vs Rust vs Zig |
+| “We forgot to port X” / incomplete ports | Process failure, not language |
+| TODOs, wishlists, backlog | Wrong file (`todo.md` / docs) |
+| One-off typos, wrong SQL, missed edge cases in *our* code | Not language-fundamental |
+| Parity mismatches that are just divergent implementations | Unless caused by a real language constraint |
+| Generic “AI made a mistake” | Only if the language *systematically* induces that mistake (e.g. trained on old Zig stdlib) |
+
+**Litmus test:** Removing scip-cli from the story — does the entry still make sense?
+- ✅ “Zig ReleaseFast builds dominate the edit–compile loop”
+- ❌ “Search must dedupe Prisma typeLiterals by file:line”
+
+---
+
+## How to run this command
+
+1. Skim the conversation / diffs for walls that burned time.
+2. Open the target `migration-problems.md`; read the last few entries so style and numbers match.
+3. For each candidate, apply the litmus test. Drop application-logic noise.
+4. Append new entries (or fix an existing entry if you previously wrote the wrong *kind* of note).
+5. Do **not** commit unless the user asks. Briefly tell the user what you added (or that nothing qualified).
+
+If nothing in the session qualifies, say so — **empty is better than polluting the experiment.**

{scip_cli-2.5.0/.cursor → scip_cli-2.6.0/.agents}/rules/agent.mdc

@@ -28,13 +28,13 @@ Node.js + `npx` required for integration tests (`scip-typescript`). Optional: `S
 
 ## Lint / test
 
-| Task | Command |
-|------|---------|
-| **All checks** | `scripts/test.sh` (lint + format + types + tests) |
-| 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/` |
+|Task|Command|
+|---|---|
+|**All checks**|`scripts/test.sh` (lint + format + types + tests)|
+|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/`|
 
 Pre-commit: ruff + ruff-format + basedpyright + full pytest. E2e before commit on command changes.
 
@@ -54,12 +54,12 @@ scip-cli analyze scip_cli/queries.py --limit 20   # file (+ scoped project)
 
 Interpretation: README § *Finding easy wins with analyze*. Target = omit (project), directory, file, or symbol — not `--path` for scope.
 
-| Priority | Section | Action |
-|----------|---------|--------|
-| 1 | **Cycles** | Break production file dependency cycles (`cache`↔`scope` was one) |
-| 2 | **Unreferenced / dead exports** | No ref usage / no external refs — verify with `rg`, delete or `_` prefix |
-| 3 | **Same-file only** | Module-private by usage — rename to `_` |
-| 4 | **Stale types** | Low-consumer classes — merge or justify |
+|Priority|Section|Action|
+|---|---|---|
+|1|**Cycles**|Break production file dependency cycles (`cache`↔`scope` was one)|
+|2|**Unreferenced / dead exports**|No ref usage / no external refs — verify with `rg`, delete or `_` prefix|
+|3|**Same-file only**|Module-private by usage — rename to `_`|
+|4|**Stale types**|Low-consumer classes — merge or justify|
 
 `analyze` skips test paths by default (`tests/`, `*.test.*`, `*.spec.*`); `--include-tests` to include. Reindex after large edits.
 
@@ -82,19 +82,19 @@ Only skip step 1 when the issue is **outside the index** (runtime, CLI UX, docs
 
 ### Retrospective: caught manually, SQLite already had it
 
-| Issue we hit | Index signal | Analyze today | Gap / next check |
-|--------------|--------------|---------------|------------------|
-| `cache` ↔ `scope` import cycle | cross-file `mentions` edges | `[high] Cycles` | **Caught** — keep dogfooding cycles |
-| Cross-file dead export (`get_refs_for_symbols`) | def with no external `mentions` | `[high] Dead exports` | **Caught** |
-| Same-file-only dead code | def, `role=0` only in def file | `[high] Unreferenced` or `[medium] Same-file only` | **Caught** (since extended) |
-| Same-file helper without `_` (`run_with_fallback`) | same-file `role=0` or none | `[medium] Same-file only` / unreferenced | **Caught** — rename to `_` |
-| Typing-only dataclasses (`ProjectSettings`, `IndexScope`) | type `#` symbol, 0 consumer files | `[high] Stale types` + `stale_type_noise` | **Filtered** — index can't see annotations; document or optional `--types` |
-| `analyze/*` section runners “dead” | no external refs | noise filter in `common.py` | **Filtered** — framework pattern |
-| Unused import | `role=2` mention, no in-file use | `[high] Unused imports` (per file) | **Caught** on file target |
-| Hub before editing (`resolve_symbol`, `queries.py`) | fan-in / consumer count | `[medium] Change surface` / `[low] Hotspots` | **Caught** on file target; project hubs are low tier |
-| Symbol only used from tests | consumers all under `tests/` | `[low] Test-only consumers` | **Partial** — Python index often omits same-file `role=0`; verify with `rg` |
-| Indexer omits same-file Python calls | no `role=0` for in-module use | unreferenced / test-only false positives | **Index gap** — not fixable in SQL alone; demoted test-only to low |
-| Duplicate / parallel helpers | — | — | **Not in index** — `rg`, not analyze |
+|Issue we hit|Index signal|Analyze today|Gap / next check|
+|---|---|---|---|
+|`cache` ↔ `scope` import cycle|cross-file `mentions` edges|`[high] Cycles`|**Caught** — keep dogfooding cycles|
+|Cross-file dead export (`get_refs_for_symbols`)|def with no external `mentions`|`[high] Dead exports`|**Caught**|
+|Same-file-only dead code|def, `role=0` only in def file|`[high] Unreferenced` or `[medium] Same-file only`|**Caught** (since extended)|
+|Same-file helper without `_` (`run_with_fallback`)|same-file `role=0` or none|`[medium] Same-file only` / unreferenced|**Caught** — rename to `_`|
+|Typing-only dataclasses (`ProjectSettings`, `IndexScope`)|type `#` symbol, 0 consumer files|`[high] Stale types` + `stale_type_noise`|**Filtered** — index can't see annotations; document or optional `--types`|
+|`analyze/*` section runners “dead”|no external refs|noise filter in `common.py`|**Filtered** — framework pattern|
+|Unused import|`role=2` mention, no in-file use|`[high] Unused imports` (per file)|**Caught** on file target|
+|Hub before editing (`resolve_symbol`, `queries.py`)|fan-in / consumer count|`[medium] Change surface` / `[low] Hotspots`|**Caught** on file target; project hubs are low tier|
+|Symbol only used from tests|consumers all under `tests/`|`[low] Test-only consumers`|**Partial** — Python index often omits same-file `role=0`; verify with `rg`|
+|Indexer omits same-file Python calls|no `role=0` for in-module use|unreferenced / test-only false positives|**Index gap** — not fixable in SQL alone; demoted test-only to low|
+|Duplicate / parallel helpers|—|—|**Not in index** — `rg`, not analyze|
 
 Add new rows to `dogfood.md` when you find another gap; implement the SQL check before the next manual review pass.
 
@@ -102,15 +102,15 @@ Add new rows to `dogfood.md` when you find another gap; implement the SQL check
 
 SQLite has **line ranges** (`defn_enclosing_ranges`) so LOC is cheap. That does **not** mean “big function” belongs next to dead exports.
 
-| Idea | In index? | Verdict |
-|------|-----------|---------|
-| **LOC ≥ N** alone | Yes | **LOW at best** — noisy (`main`, argparse, legitimate parsers). Not a nuke candidate. |
-| **LOC + fan-in** (large hub) | Yes | **Already covered** by `[low] Bottlenecks` (fan-in × fan-out). Add `loc=` to that output if helpful; don’t duplicate as medium. |
-| **LOC + consumers** on file target | Yes | **Change surface** (medium) already sorts by consumers with line ranges — drill there. |
-| **Symbol pressure** | Yes | **Per-symbol** `analyze Foo` shows `loc × fan_in × fan_out`. |
-| **God class / many members** | Yes | Use `members Class` — not analyze. |
-| **File byte size / cyclomatic complexity** | No | Out of scope for SCIP index. |
-| **Fat file (many symbols)** | Yes | Low value; coupling/hotspots approximate module heat. |
+|Idea|In index?|Verdict|
+|---|---|---|
+|**LOC ≥ N** alone|Yes|**LOW at best** — noisy (`main`, argparse, legitimate parsers). Not a nuke candidate.|
+|**LOC + fan-in** (large hub)|Yes|**Already covered** by `[low] Bottlenecks` (fan-in × fan-out). Add `loc=` to that output if helpful; don’t duplicate as medium.|
+|**LOC + consumers** on file target|Yes|**Change surface** (medium) already sorts by consumers with line ranges — drill there.|
+|**Symbol pressure**|Yes|**Per-symbol** `analyze Foo` shows `loc × fan_in × fan_out`.|
+|**God class / many members**|Yes|Use `members Class` — not analyze.|
+|**File byte size / cyclomatic complexity**|No|Out of scope for SCIP index.|
+|**Fat file (many symbols)**|Yes|Low value; coupling/hotspots approximate module heat.|
 
 **Rule:** size-only checks stay **low or file-drill-down**; never high/medium unless paired with a **structural smell** (cycle, dead export, zero production consumers). Prefer enriching existing low-tier lines (e.g. show `loc` on bottlenecks) over a new dashboard section.
 
@@ -118,33 +118,55 @@ SQLite has **line ranges** (`defn_enclosing_ranges`) so LOC is cheap. That does
 
 The e2e fixture and this repo's own index are **small** — every query looks fast here. That hides blowups on real projects (40MB+ indexes, dense graphs).
 
-**Before merging new or heavily changed SQL** (`queries.py`, `analyze/*`):
-
-1. Time it against **1–2 existing checks** on a **large cached index** you already have (not the fixture):
-   ```bash
-   python3 -u -c "
-   import sqlite3, time, sys
-   from pathlib import Path
-   sys.path.insert(0, '.')
-   from scip_cli.analyze import project as p
-   from scip_cli.sql import configure_read_connection
-   db_path = Path.home() / '.cache/scip-cli/projects/<project-slug>/index.db'
-   db = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
-   configure_read_connection(db)
-   for name, fn in [('hotspots', p.hotspots), ('cycles', p.cycles), ('dead_exports', p.dead_exports)]:
-       t = time.perf_counter(); fn(db, limit=25); print(f'{name}: {(time.perf_counter()-t)*1000:.0f}ms')
-   "
-   ```
-2. Flag anything **notably slower** than peers — orders of magnitude or multi-second, not a few ms drift.
-3. Swap in your new/changed check for one of the rows; keep a fast peer (e.g. `hotspots`) and a heavy peer (e.g. `dead_exports`).
-
-**In CI:** `tests/test_e2e_perf.py` (whole commands) and `tests/test_analyze_perf.py` (per-check on mini DB) catch gross regressions on the tiny fixture only — they **will not** catch large-repo OOMs. Use the manual benchmark above for that.
+### Scaled :memory: benchmark (primary)
+
+`tests/bench_db.py` generates a deterministic 1000-file / ~15K-symbol / ~100K-mention DB in `:memory:`. `tests/test_bench_queries.py` times all key queries on it.
+
+**Before/after comparison flow:**
+
+```bash
+# 1. Before changes — save baseline
+scripts/bench.sh --baseline
+
+# 2. Make your SQL/query changes
+
+# 3. Compare — runs current, diffs against baseline
+scripts/bench.sh --compare
+
+# Or just run current without comparison
+scripts/bench.sh
+```
+
+Output per query: `BENCH:<name>:<elapsed_ms>`. The compare table shows ratio (>1.0 = regression, <1.0 = improvement).
+
+**When to use:** Any change to `queries.py`, `analyze/*`, `symbols.py` SQL clauses, or `sql.py` pragmas. Run `scripts/bench.sh --compare` before committing.
+
+### Large cached index benchmark (secondary)
+
+For queries that behave differently on real 40MB+ indexes vs the synthetic DB:
+
+```bash
+python3 -u -c "
+import sqlite3, time, sys
+from pathlib import Path
+sys.path.insert(0, '.')
+from scip_cli.analyze import project as p
+from scip_cli.sql import configure_read_connection
+db_path = Path.home() / '.cache/scip-cli/projects/<project-slug>/index.db'
+db = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
+configure_read_connection(db)
+for name, fn in [('hotspots', p.hotspots), ('cycles', p.cycles), ('dead_exports', p.dead_exports)]:
+    t = time.perf_counter(); fn(db, limit=25); print(f'{name}: {(time.perf_counter()-t)*1000:.0f}ms')
+"
+```
+
+**In CI:** `tests/test_e2e_perf.py` (whole commands) and `tests/test_analyze_perf.py` (per-check on mini DB) catch gross regressions on the tiny fixture only — they **will not** catch large-repo OOMs. Use `scripts/bench.sh --compare` for that.
 
 ## TDD
 
 ### Default: extend the shared fixture
 
-**One indexed TS project** — `tests/fixtures/sample-project/` — indexed once per session via `indexed_fixture` (`conftest.py`). Stable names live in `tests/fixture_catalog.py`.
+**One indexed TS project** — `tests/fixtures/typescript-project/` — indexed once per session via `indexed_fixture` (`conftest.py`). Stable names live in `tests/fixture_catalog.py`.
 
 1. **Red** — add a **minimal** `.ts` file (or tweak an existing one) that reproduces the SCIP shape; assert in `tests/test_e2e.py` or `tests/test_e2e_analyze_patterns.py` using `cli` / `open_index_db` + analyze helpers.
 2. **Green** — fix `scip_cli/` (commands, `analyze/*`, `queries.py`, …).
@@ -159,29 +181,29 @@ The e2e fixture and this repo's own index are **small** — every query looks fa
 When dogfooding **another repo** surfaces a bug or false positive (analyze noise, dead-export mistake, cycle, stale type, refs mismatch):
 
 1. **Capture the pattern, not the project** — note the SCIP shape (module `/`, export alias `foo0:`, lazy import, `Props#`, barrel cycle, …). Do **not** copy real repo names, paths, or filenames into tests or docs.
-2. **Red on the fixture** — smallest TS repro under `tests/fixtures/sample-project/` with generic names (`LazyPanel`, `evictItem`, `OrphanWidget`, …). E2e test proves the bug against **real `scip-typescript`** output.
+2. **Red on the fixture** — smallest TS repro under `tests/fixtures/typescript-project/` with generic names (`LazyPanel`, `evictItem`, `OrphanWidget`, …). E2e test proves the bug against **real `scip-typescript`** output.
 3. **Green** — fix analyze heuristics / SQL / CLI; dogfood on this repo if applicable.
 4. **Verify** — `pytest tests/test_e2e_analyze_patterns.py` (or full `pytest`); only then trim redundant tests.
 
 **Prefer fixture e2e over fake SQLite graphs.** `tests/analyze_db.py` (`AnalyzeDbBuilder`, `:memory:`) is for SQL/dashboard **plumbing** and graph primitives (`test_analyze_graph.py`, `mini_codebase_db`) — not for reproducing production SCIP symbol shapes. Hand-built symbols often diverge from scip-typescript (path format, `0:` aliases, module rows) and can pass while production still breaks.
 
-| Use fixture e2e | Use `analyze_db` unit |
-|-----------------|----------------------|
-| False positives / analyze checks from real projects | Tarjan, edge-type SQL, `run_all` section wiring |
-| Any behavior that depends on indexer symbol strings | Noise filters with one or two synthetic rows |
-| CLI commands (`refs`, `search`, `analyze` output) | Merge/index prune tests |
+|Use fixture e2e|Use `analyze_db` unit|
+|---|---|
+|False positives / analyze checks from real projects|Tarjan, edge-type SQL, `run_all` section wiring|
+|Any behavior that depends on indexer symbol strings|Noise filters with one or two synthetic rows|
+|CLI commands (`refs`, `search`, `analyze` output)|Merge/index prune tests|
 
 If both layers help during development, **keep both until e2e passes**, then delete duplicate in-memory repros — fixture is the source of truth.
 
 ## Codebase map (contributors)
 
-| Area | Path | Notes |
-|------|------|-------|
-| Commands | `scip_cli/commands/` | Thin; SQL in `queries.py` / `analyze/` |
-| Index build | `scip_cli/indexing.py` | `index.db.next` → promote; flock; `>10` tsconfigs log progress |
-| Variable prune | postprocess + `merge.py` | Omit const/let/var on **COPY**, not DELETE — no `variable` kind |
-| Session | `scip_cli/session.py` | `setup()`, `resolve_one_symbol` (limit 2 for ambiguity) |
-| Analyze filters | `scip_cli/analyze/common.py` | `is_test_path`, `analyze_noise` (`_` helpers) |
+|Area|Path|Notes|
+|---|---|---|
+|Commands|`scip_cli/commands/`|Thin; SQL in `queries.py` / `analyze/`|
+|Index build|`scip_cli/indexing.py`|`index.db.next` → promote; flock; `>10` tsconfigs log progress|
+|Variable prune|postprocess + `merge.py`|Omit const/let/var on **COPY**, not DELETE — no `variable` kind|
+|Session|`scip_cli/session.py`|`setup()`, `resolve_one_symbol` (limit 2 for ambiguity)|
+|Analyze filters|`scip_cli/analyze/common.py`|`is_test_path`, `analyze_noise` (`_` helpers)|
 
 `todo.md` = tracked work; `dogfood.md` = future ideas only. Wishlist/backlog in `docs/` per workspace rules.
 
@@ -206,4 +228,4 @@ scip-cli analyze --limit 25
 scip-cli analyze scip_cli/queries.py --limit 20   # drill into hubs
 ```
 
-Project-wide analyze skips test paths by default; `--include-tests` to include. See README **Finding easy wins with analyze**.
+Project-wide analyze skips test paths by default; `--include-tests` to include. See README **Finding easy wins with analyze**.

scip_cli-2.6.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        id: setup_python
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Restore cached virtualenv
+        uses: actions/cache/restore@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.setup_python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
+          path: .venv
+
+      - name: Create venv and install dependencies
+        run: |
+          python -m venv .venv
+          source .venv/bin/activate
+          pip install -e ".[dev]"
+          npm install -g @sourcegraph/scip-typescript
+          mkdir -p ~/.local/bin
+          curl -sL https://github.com/scip-code/scip/releases/download/v0.9.0/scip-linux-amd64.tar.gz | tar xz -C ~/.local/bin
+          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
+          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
+
+      - name: Save cached virtualenv
+        uses: actions/cache/save@v4
+        with:
+          key: venv-${{ runner.os }}-${{ steps.setup_python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
+          path: .venv
+
+      - name: Run publish gate
+        run: ./scripts/test.sh

{scip_cli-2.5.0 → scip_cli-2.6.0}/.gitignore

@@ -10,8 +10,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
-lib64/
 parts/
 sdist/
 var/
@@ -19,6 +17,7 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+.ruff_cache/
 
 # Virtual environments
 venv/
@@ -51,3 +50,4 @@ dogfood.md
 # Local-only dev scripts (repo-specific smoke harnesses)
 scripts/deep-smoke.sh
 tmp/
+*.db

scip_cli-2.6.0/AGENTS.md

@@ -0,0 +1 @@
+.cursor/rules/agent.mdc

{scip_cli-2.5.0 → scip_cli-2.6.0}/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-ariel.flesler@gmail.com.
+aflesler@gmail.com.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

{scip_cli-2.5.0 → scip_cli-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scip-cli
-Version: 2.5.0
+Version: 2.6.0
 Summary: Fast code intelligence via SCIP indexes
 Project-URL: Homepage, https://github.com/flesler/scip-cli
 Author: Ariel Flesler
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://badge.fury.io/py/scip-cli.svg)](https://badge.fury.io/py/scip-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Token-efficient code intelligence for AI agents. Precise refs, definitions, and repo health analysis via SCIP indexes — TypeScript/JavaScript, Python, Go, and Rust.
+Python CLI for AI agents. Queries SCIP indexes for precise refs, definitions, and repo health analysis — TypeScript/JavaScript, Python, Go, Rust.
 
 ## Why
 
@@ -38,6 +38,17 @@ AI agents waste tokens on grep and file scanning. scip-cli gives them precise, t
 - **`analyze`**: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope
 - **Auto-indexing**: Indexes on first query, caches in SQLite, zero config
 
+## Ports
+
+CLI/output parity ports of this project (Python is the reference):
+
+| Language           | Repository                                                        |
+| ------------------ | ----------------------------------------------------------------- |
+| Python (reference) | [flesler/scip-cli](https://github.com/flesler/scip-cli)           |
+| Go                 | [flesler/scip-cli-go](https://github.com/flesler/scip-cli-go)     |
+| Rust               | [flesler/scip-cli-rust](https://github.com/flesler/scip-cli-rust) |
+| Zig                | [flesler/scip-cli-zig](https://github.com/flesler/scip-cli-zig)   |
+
 ## For AI Agents
 
 Install as a reusable skill so your agent always knows how to navigate the codebase:
@@ -250,9 +261,13 @@ Scoped indexing without editing `.scip-cli.json`:
 ```bash
 scip-cli reindex --path packages/server
 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
 ```
 
-`--path` limits which discovered tsconfig projects are indexed (prefix match, same idea as query `--path`). **TypeScript only** — other languages reject `reindex --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`.
+`--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.** 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`/`--tsconfig`.
+
+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`.
 
 Run `scip-cli reindex` after changing scope, `.scip-cli.json` index settings, or when you want a fresh index.
 
@@ -347,7 +362,7 @@ scip_cli/
 ```bash
 pip install -e ".[dev]"
 pytest tests/ -q
-pytest tests/ -m integration -q   # indexes tests/fixtures/sample-project (needs scip-typescript)
+pytest tests/ -m integration -q   # indexes tests/fixtures/typescript-project (needs scip-typescript)
 ```
 
 ### Debug Logging

{scip_cli-2.5.0 → scip_cli-2.6.0}/README.md

@@ -3,7 +3,7 @@
 [![PyPI version](https://badge.fury.io/py/scip-cli.svg)](https://badge.fury.io/py/scip-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Token-efficient code intelligence for AI agents. Precise refs, definitions, and repo health analysis via SCIP indexes — TypeScript/JavaScript, Python, Go, and Rust.
+Python CLI for AI agents. Queries SCIP indexes for precise refs, definitions, and repo health analysis — TypeScript/JavaScript, Python, Go, Rust.
 
 ## Why
 
@@ -17,6 +17,17 @@ AI agents waste tokens on grep and file scanning. scip-cli gives them precise, t
 - **`analyze`**: Find dead exports, import cycles, stale types, coupling hotspots — actionable health dashboards at project, file, or symbol scope
 - **Auto-indexing**: Indexes on first query, caches in SQLite, zero config
 
+## Ports
+
+CLI/output parity ports of this project (Python is the reference):
+
+| Language           | Repository                                                        |
+| ------------------ | ----------------------------------------------------------------- |
+| Python (reference) | [flesler/scip-cli](https://github.com/flesler/scip-cli)           |
+| Go                 | [flesler/scip-cli-go](https://github.com/flesler/scip-cli-go)     |
+| Rust               | [flesler/scip-cli-rust](https://github.com/flesler/scip-cli-rust) |
+| Zig                | [flesler/scip-cli-zig](https://github.com/flesler/scip-cli-zig)   |
+
 ## For AI Agents
 
 Install as a reusable skill so your agent always knows how to navigate the codebase:
@@ -229,9 +240,13 @@ Scoped indexing without editing `.scip-cli.json`:
 ```bash
 scip-cli reindex --path packages/server
 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
 ```
 
-`--path` limits which discovered tsconfig projects are indexed (prefix match, same idea as query `--path`). **TypeScript only** — other languages reject `reindex --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`.
+`--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.** 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`/`--tsconfig`.
+
+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`.
 
 Run `scip-cli reindex` after changing scope, `.scip-cli.json` index settings, or when you want a fresh index.
 
@@ -326,7 +341,7 @@ scip_cli/
 ```bash
 pip install -e ".[dev]"
 pytest tests/ -q
-pytest tests/ -m integration -q   # indexes tests/fixtures/sample-project (needs scip-typescript)
+pytest tests/ -m integration -q   # indexes tests/fixtures/typescript-project (needs scip-typescript)
 ```
 
 ### Debug Logging

{scip_cli-2.5.0 → scip_cli-2.6.0}/SECURITY.md

@@ -2,16 +2,16 @@
 
 ## Supported Versions
 
-| Version | Supported          |
-| ------- | ------------------ |
-| latest  | :white_check_mark: |
-| < latest| :x:                |
+|Version|Supported|
+|---|---|
+|latest|:white_check_mark:|
+|< latest|:x:|
 
 ## Reporting a Vulnerability
 
 **Do not open public issues for security vulnerabilities.**
 
-If you discover a security vulnerability, please email **ariel.flesler@gmail.com** with:
+If you discover a security vulnerability, please email **aflesler@gmail.com** with:
 
 - Description of the vulnerability
 - Steps to reproduce or proof of concept

scip_cli-2.6.0/docs/port.md

@@ -0,0 +1,80 @@
+
+---
+
+## Experimental Task: Add --freq Flag to Symbols Command
+
+**Task**: Add `--freq` flag to sort symbols by frequency of occurrence
+
+### Execution Summary
+- **Start time**: Tue Jun 30 03:36:42 PM -03 2026
+- **End time**: Tue Jun 30 03:39:51 PM -03 2026
+- **Total elapsed time**: ~3 minutes
+- **Tool calls made**: ~15 calls
+
+### Changes Made
+- **scip_cli/__main__.py**: Added `--freq` boolean argument to the symbols command parser
+- **scip_cli/commands/symbols.py**: 
+  - Added `Counter` import from collections
+  - Implemented `_sort_by_frequency()` function that counts symbol name occurrences and sorts by frequency (descending) with alphabetical tie-breaking
+  - Modified `main()` to apply frequency sorting when `--freq` flag is present
+- **tests/test_symbols_freq.py**: Created comprehensive test file with 3 tests:
+  1. `test_freq_flag_sorts_by_frequency`: Verifies symbols are sorted by frequency
+  2. `test_freq_flag_with_ties_sorts_alphabetically`: Verifies alphabetical ordering for ties
+  3. `test_without_freq_flag_maintains_original_order`: Ensures original behavior without flag
+
+### Problems Encountered
+- **Linting issues**: Initial test file had unused import and long line - fixed by removing import and breaking up assertion message
+- **Formatting**: Test file needed reformatting with ruff - fixed by running `ruff format`
+
+### Tests Added
+- **test_freq_flag_sorts_by_frequency**: Verifies that first symbol has count >= last symbol's count
+- **test_freq_flag_with_ties_sorts_alphabetically**: Verifies symbols with same frequency appear in alphabetical order
+- **test_without_freq_flag_maintains_original_order**: Verifies line-number ordering without --freq flag
+
+### Gate Results
+- Tests: **passed** (298/298 tests passing, including 3 new tests)
+- Linting: **passed** (ruff check clean)
+- Formatting: **passed** (ruff format applied)
+
+### AI Experience Notes
+The task was straightforward with clear code structure. The scip-cli codebase is well-organized with commands separated into individual modules. Adding the CLI flag was simple via argparse. The frequency sorting implementation using Counter was intuitive. Tests leveraged existing e2e harness patterns. Minor friction with linting/formatting but easily resolved. No type errors or unexpected issues encountered.
+
+---
+
+## Experimental Task: Add --freq Flag to Symbols Command (Verification Run)
+
+**Task**: Verify that `--freq` flag implementation is complete and working correctly
+
+### Execution Summary
+- **Start time**: Tue Jun 30 03:40:54 PM -03 2026
+- **End time**: Tue Jun 30 03:42:10 PM -03 2026
+- **Total elapsed time**: ~1.5 minutes
+- **Tool calls made**: ~12 calls
+
+### Changes Made
+No changes were needed - the implementation was already complete:
+- **scip_cli/__main__.py**: `--freq` boolean argument already added to symbols command parser (lines 92-96)
+- **scip_cli/commands/symbols.py**: 
+  - `_sort_by_frequency()` function already implemented (lines 42-62)
+  - Frequency counting using `Counter` from collections
+  - Sorting by frequency descending, then alphabetically for ties
+  - Integration in `main()` with `getattr(args, "freq", False)` check
+- **tests/test_symbols_freq.py**: 3 comprehensive tests already present and passing
+
+### Problems Encountered
+- **None**: Implementation was already complete and all tests passing
+- Verified existing implementation meets all requirements
+
+### Tests Added
+No new tests added - verified existing tests:
+- **test_freq_flag_sorts_by_frequency**: Verifies descending frequency order ✓
+- **test_freq_flag_with_ties_sorts_alphabetically**: Verifies alphabetical tie-breaking ✓
+- **test_without_freq_flag_maintains_original_order**: Verifies default behavior ✓
+
+### Gate Results
+- Tests: **passed** (298/298 tests passing, including 3 freq tests)
+- Python compile: **passed** (no syntax errors)
+- Linting: **passed** (ruff check clean)
+
+### AI Experience Notes
+This verification run confirmed the implementation is complete and production-ready. The code is clean, well-structured, and follows Python best practices. All tests pass without modification. The use of `getattr(args, "freq", False)` provides safe fallback if flag is missing. Counter-based frequency counting is efficient and idiomatic. No refactoring needed.