codebase-index 1.6.0__tar.gz → 1.7.0__tar.gz

codebase_index-1.7.0/.claude/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+1.7.0

codebase_index-1.7.0/.claude/skills/codebase-index/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: codebase-index
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+---
+
+# Codebase Index
+
+Use the local index before reading repository files.
+
+The operating principle is **Find → Trace → Predict**:
+
+- **Find** the implementation with ranked retrieval.
+- **Trace** behavior through definitions, callers, dependencies, and paths.
+- **Predict** change impact while preserving an explicit evidence trail.
+
+## Route the question
+
+| Intent | Command |
+|---|---|
+| Where is X implemented? | `codebase-index search "X" --json` |
+| How does X work? | `codebase-index explain "X" --json` |
+| What is this codebase? | `codebase-index architecture --json` |
+| Find a named symbol | `codebase-index symbol "X" --json` |
+| Who calls or references X? | `codebase-index refs "X" --json` |
+| What changes if X changes? | `codebase-index impact "X" --json` |
+| What does my current diff affect? | `codebase-index diff-impact --json` |
+| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
+| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Produce a human graph | `codebase-index graph "X" --output <path>` |
+
+Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
+error messages, and the default `hybrid` mode for mixed questions. Use pure
+`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
+
+Read [references/commands.md](references/commands.md) only when command options
+or routing remain unclear.
+
+## Evidence protocol
+
+1. Run the best-matching command with `--json`.
+2. Check `index` before trusting the payload:
+   - missing → run `codebase-index index`, then repeat;
+   - stale with fewer than 20 changed files → run `codebase-index update`;
+   - stale with 20 or more changed files → run `codebase-index index`;
+   - fresh → continue.
+3. Start with ranks 1–3. Read only `recommended_reads` line ranges.
+4. Trace one additional hop only when the question requires behavior,
+   ownership, or impact.
+5. Answer with `file:line` evidence and state uncertainty explicitly.
+
+Do not open whole files when a line range is available. A snippet may already
+be sufficient. `skeletonized: true` means the response intentionally folded
+unrelated body lines; read the supplied range when the missing body matters.
+
+## Confidence contract
+
+- **high** — answer from the indexed evidence.
+- **medium** — read the recommended ranges and confirm the key claim with one
+  targeted lookup if necessary.
+- **low** or no results — follow `fallback_suggestions`, then use a narrow
+  Grep/Glob fallback.
+
+On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
+empty result is inconclusive; confirm with targeted Grep before saying that
+nothing references the target.
+
+Edges carry `confidence`:
+
+- `extracted` — exact parser evidence;
+- `inferred` — heuristic resolution;
+- `ambiguous` — unresolved or non-unique.
+
+Never present an inferred or ambiguous chain as certain.
+
+## Answer contract
+
+Structure repository answers around:
+
+1. **Answer** — the direct conclusion.
+2. **Evidence** — the minimum supporting `file:line` references.
+3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
+4. **Next check** — only when another check would materially reduce uncertainty.
+
+Do not narrate every search step. Do not claim absence from a partial graph.
+Do not replace evidence with a generated HTML graph.
+
+For payload fields and failure handling, read
+[references/response-contract.md](references/response-contract.md).

codebase_index-1.7.0/.claude/skills/codebase-index/references/commands.md

@@ -0,0 +1,73 @@
+# Command Reference
+
+Load this reference only when the intent table in `SKILL.md` is insufficient.
+
+## Retrieval
+
+```bash
+codebase-index search "<query>" --json
+codebase-index explain "<topic or flow>" --json
+```
+
+Useful search options:
+
+- `--mode hybrid|fts|symbol|vector`
+- `--token-budget <tokens>`
+- `--limit <count>`
+- `--offset <pagination offset>`
+- `--raw` to disable snippet skeletonization
+- `--no-fallback` to suppress fallback suggestions
+
+`explain` uses the HOW_IT_WORKS intent and a larger default token budget. Prefer
+it over repeatedly rewording a broad search.
+
+## Code graph
+
+```bash
+codebase-index architecture --json
+codebase-index refs "<symbol>" --json
+codebase-index impact "<file-or-symbol>" --direction up --depth 2 --json
+codebase-index diff-impact --base HEAD --direction up --depth 2 --json
+codebase-index path "<source>" "<target>" --json
+codebase-index describe "<file-or-symbol>" --json
+```
+
+- `architecture` reads module analysis cached at index time.
+- `refs` finds definitions, calls, and graph-backed references.
+- `impact` walks dependents (`up`), dependencies (`down`), or both.
+- `diff-impact` aggregates impact for tracked changes relative to a verified
+  Git commit; new or excluded files are reported as unresolved.
+- `path` returns the shortest known dependency/call chain.
+- `describe` returns a node card with callers, callees, module, and centrality.
+
+Use `graph` only for a visualization intended for a person:
+
+```bash
+codebase-index graph "<target>" --direction both --depth 2 --output graph.html
+```
+
+For headless work, use `--output`; do not use `--open`. Exports also support
+`--format graphml|dot|neo4j`.
+
+## Index health
+
+```bash
+codebase-index stats --json
+codebase-index doctor
+codebase-index update
+codebase-index index
+```
+
+Run `stats` and `doctor` when several unrelated queries have low confidence.
+Low symbol counts or partial graph coverage can explain weak results.
+
+## Query examples
+
+```bash
+codebase-index search "auth token refresh" --json
+codebase-index search "AuthService class" --mode symbol --json
+codebase-index search "connection reset by peer" --mode fts --json
+codebase-index explain "checkout flow" --json
+codebase-index impact "User" --direction up --depth 2 --json
+codebase-index path "ApiController" "Database" --json
+```

codebase_index-1.7.0/.claude/skills/codebase-index/references/response-contract.md

@@ -0,0 +1,82 @@
+# Response Contract
+
+Load this reference when interpreting a retrieval packet or handling a weak
+result.
+
+## Ranked results
+
+Each result can contain:
+
+- `rank`
+- `path`
+- `line_start` / `line_end`
+- `symbols`
+- `score`
+- `reason`
+- `snippet`
+- `skeletonized`
+- `elided_lines`
+
+`recommended_reads` is the read plan. Start with its first one to three entries
+and use exact line ranges.
+
+`pagination.has_more` and `pagination.next_offset` indicate additional results.
+Prefer a more specific command or a larger token budget before paging.
+
+## Freshness
+
+The `index` object is part of the evidence contract:
+
+```text
+exists=false                           → index
+stale=true, files_changed_since_build<20 → update
+stale=true, files_changed_since_build≥20 → full index
+stale=false                            → proceed
+```
+
+Repeat the original query after rebuilding or updating.
+
+## Weak results
+
+Fallback is allowed only when:
+
+- results are empty;
+- confidence is low;
+- graph coverage is partial;
+- the requested information is not represented by the index.
+
+Use `fallback_suggestions.ripgrep` first. Otherwise construct one narrow Grep
+pattern from the most distinctive symbol, error, or path in the question.
+Avoid a full-repository scan unless targeted fallback also fails.
+
+If several queries are weak:
+
+```bash
+codebase-index stats --json
+codebase-index doctor
+```
+
+Report the limitation instead of inventing certainty.
+
+## Answer examples
+
+High confidence:
+
+```text
+Session validation is implemented in `src/auth/session.py:44`.
+The request middleware calls it from `src/http/auth.py:18`.
+```
+
+Partial graph:
+
+```text
+The index found no graph-backed callers, but coverage for Lua is partial.
+A targeted text search still finds two call sites in …
+```
+
+Inferred chain:
+
+```text
+The route-to-service link is parser-extracted; the service-to-model link is
+heuristic, so the final hop should be verified before refactoring.
+```

{codebase_index-1.6.0 → codebase_index-1.7.0}/.claude/skills/codebase-index/scripts/cbx

@@ -4,7 +4,7 @@
 # - Whitelists subcommands so the skill can never invoke destructive ones (clean/init/watch).
 set -euo pipefail
 
-ALLOWED="search explain symbol refs impact graph stats doctor update index"
+ALLOWED="search explain architecture symbol refs impact diff-impact path describe graph stats doctor update index"
 
 sub="${1:-}"
 case " $ALLOWED " in

{codebase_index-1.6.0/.opencode → codebase_index-1.7.0/.claude}/skills/codebase-index/scripts/cbx.ps1

@@ -8,7 +8,10 @@ param(
 )
 
 $ErrorActionPreference = "Stop"
-$allowed = @("search", "explain", "symbol", "refs", "impact", "graph", "stats", "doctor", "update", "index")
+$allowed = @(
+    "search", "explain", "architecture", "symbol", "refs", "impact", "diff-impact",
+    "path", "describe", "graph", "stats", "doctor", "update", "index"
+)
 
 if ($allowed -notcontains $Subcommand) {
     Write-Error "cbx: refusing subcommand '$Subcommand'. Allowed: $($allowed -join ', ')"

{codebase_index-1.6.0 → codebase_index-1.7.0}/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
     {
       "name": "codebase-index",
       "source": "./",
-      "description": "Local-first hybrid codebase index skill with auto-provisioned CLI."
+      "description": "Find, trace, and predict across a local codebase with evidence-bearing retrieval."
     }
   ]
 }

{codebase_index-1.6.0 → codebase_index-1.7.0}/.claude-plugin/plugin.json

@@ -2,8 +2,8 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "codebase-index",
   "displayName": "Codebase Index",
-  "description": "Local-first hybrid codebase index. Auto-provisions its Python CLI on first session start; the skill searches the index so Claude reads only the most relevant files.",
-  "version": "1.6.0",
+  "description": "Give Claude a precise local map of your codebase: find implementations, trace behavior, and predict change impact with file-line evidence.",
+  "version": "1.7.0",
   "author": {
     "name": "codebase-index contributors"
   },

codebase_index-1.7.0/.codex/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+1.7.0

codebase_index-1.7.0/.codex/skills/codebase-index/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: codebase-index
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+---
+
+# Codebase Index
+
+Use the local index before reading repository files.
+
+The operating principle is **Find → Trace → Predict**:
+
+- **Find** the implementation with ranked retrieval.
+- **Trace** behavior through definitions, callers, dependencies, and paths.
+- **Predict** change impact while preserving an explicit evidence trail.
+
+## Route the question
+
+| Intent | Command |
+|---|---|
+| Where is X implemented? | `codebase-index search "X" --json` |
+| How does X work? | `codebase-index explain "X" --json` |
+| What is this codebase? | `codebase-index architecture --json` |
+| Find a named symbol | `codebase-index symbol "X" --json` |
+| Who calls or references X? | `codebase-index refs "X" --json` |
+| What changes if X changes? | `codebase-index impact "X" --json` |
+| What does my current diff affect? | `codebase-index diff-impact --json` |
+| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
+| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Produce a human graph | `codebase-index graph "X" --output <path>` |
+
+Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
+error messages, and the default `hybrid` mode for mixed questions. Use pure
+`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
+
+Read [references/commands.md](references/commands.md) only when command options
+or routing remain unclear.
+
+## Evidence protocol
+
+1. Run the best-matching command with `--json`.
+2. Check `index` before trusting the payload:
+   - missing → run `codebase-index index`, then repeat;
+   - stale with fewer than 20 changed files → run `codebase-index update`;
+   - stale with 20 or more changed files → run `codebase-index index`;
+   - fresh → continue.
+3. Start with ranks 1–3. Read only `recommended_reads` line ranges.
+4. Trace one additional hop only when the question requires behavior,
+   ownership, or impact.
+5. Answer with `file:line` evidence and state uncertainty explicitly.
+
+Do not open whole files when a line range is available. A snippet may already
+be sufficient. `skeletonized: true` means the response intentionally folded
+unrelated body lines; read the supplied range when the missing body matters.
+
+## Confidence contract
+
+- **high** — answer from the indexed evidence.
+- **medium** — read the recommended ranges and confirm the key claim with one
+  targeted lookup if necessary.
+- **low** or no results — follow `fallback_suggestions`, then use a narrow
+  Grep/Glob fallback.
+
+On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
+empty result is inconclusive; confirm with targeted Grep before saying that
+nothing references the target.
+
+Edges carry `confidence`:
+
+- `extracted` — exact parser evidence;
+- `inferred` — heuristic resolution;
+- `ambiguous` — unresolved or non-unique.
+
+Never present an inferred or ambiguous chain as certain.
+
+## Answer contract
+
+Structure repository answers around:
+
+1. **Answer** — the direct conclusion.
+2. **Evidence** — the minimum supporting `file:line` references.
+3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
+4. **Next check** — only when another check would materially reduce uncertainty.
+
+Do not narrate every search step. Do not claim absence from a partial graph.
+Do not replace evidence with a generated HTML graph.
+
+For payload fields and failure handling, read
+[references/response-contract.md](references/response-contract.md).

codebase_index-1.7.0/.codex/skills/codebase-index/references/commands.md

@@ -0,0 +1,73 @@
+# Command Reference
+
+Load this reference only when the intent table in `SKILL.md` is insufficient.
+
+## Retrieval
+
+```bash
+codebase-index search "<query>" --json
+codebase-index explain "<topic or flow>" --json
+```
+
+Useful search options:
+
+- `--mode hybrid|fts|symbol|vector`
+- `--token-budget <tokens>`
+- `--limit <count>`
+- `--offset <pagination offset>`
+- `--raw` to disable snippet skeletonization
+- `--no-fallback` to suppress fallback suggestions
+
+`explain` uses the HOW_IT_WORKS intent and a larger default token budget. Prefer
+it over repeatedly rewording a broad search.
+
+## Code graph
+
+```bash
+codebase-index architecture --json
+codebase-index refs "<symbol>" --json
+codebase-index impact "<file-or-symbol>" --direction up --depth 2 --json
+codebase-index diff-impact --base HEAD --direction up --depth 2 --json
+codebase-index path "<source>" "<target>" --json
+codebase-index describe "<file-or-symbol>" --json
+```
+
+- `architecture` reads module analysis cached at index time.
+- `refs` finds definitions, calls, and graph-backed references.
+- `impact` walks dependents (`up`), dependencies (`down`), or both.
+- `diff-impact` aggregates impact for tracked changes relative to a verified
+  Git commit; new or excluded files are reported as unresolved.
+- `path` returns the shortest known dependency/call chain.
+- `describe` returns a node card with callers, callees, module, and centrality.
+
+Use `graph` only for a visualization intended for a person:
+
+```bash
+codebase-index graph "<target>" --direction both --depth 2 --output graph.html
+```
+
+For headless work, use `--output`; do not use `--open`. Exports also support
+`--format graphml|dot|neo4j`.
+
+## Index health
+
+```bash
+codebase-index stats --json
+codebase-index doctor
+codebase-index update
+codebase-index index
+```
+
+Run `stats` and `doctor` when several unrelated queries have low confidence.
+Low symbol counts or partial graph coverage can explain weak results.
+
+## Query examples
+
+```bash
+codebase-index search "auth token refresh" --json
+codebase-index search "AuthService class" --mode symbol --json
+codebase-index search "connection reset by peer" --mode fts --json
+codebase-index explain "checkout flow" --json
+codebase-index impact "User" --direction up --depth 2 --json
+codebase-index path "ApiController" "Database" --json
+```

codebase_index-1.7.0/.codex/skills/codebase-index/references/response-contract.md

@@ -0,0 +1,82 @@
+# Response Contract
+
+Load this reference when interpreting a retrieval packet or handling a weak
+result.
+
+## Ranked results
+
+Each result can contain:
+
+- `rank`
+- `path`
+- `line_start` / `line_end`
+- `symbols`
+- `score`
+- `reason`
+- `snippet`
+- `skeletonized`
+- `elided_lines`
+
+`recommended_reads` is the read plan. Start with its first one to three entries
+and use exact line ranges.
+
+`pagination.has_more` and `pagination.next_offset` indicate additional results.
+Prefer a more specific command or a larger token budget before paging.
+
+## Freshness
+
+The `index` object is part of the evidence contract:
+
+```text
+exists=false                           → index
+stale=true, files_changed_since_build<20 → update
+stale=true, files_changed_since_build≥20 → full index
+stale=false                            → proceed
+```
+
+Repeat the original query after rebuilding or updating.
+
+## Weak results
+
+Fallback is allowed only when:
+
+- results are empty;
+- confidence is low;
+- graph coverage is partial;
+- the requested information is not represented by the index.
+
+Use `fallback_suggestions.ripgrep` first. Otherwise construct one narrow Grep
+pattern from the most distinctive symbol, error, or path in the question.
+Avoid a full-repository scan unless targeted fallback also fails.
+
+If several queries are weak:
+
+```bash
+codebase-index stats --json
+codebase-index doctor
+```
+
+Report the limitation instead of inventing certainty.
+
+## Answer examples
+
+High confidence:
+
+```text
+Session validation is implemented in `src/auth/session.py:44`.
+The request middleware calls it from `src/http/auth.py:18`.
+```
+
+Partial graph:
+
+```text
+The index found no graph-backed callers, but coverage for Lua is partial.
+A targeted text search still finds two call sites in …
+```
+
+Inferred chain:
+
+```text
+The route-to-service link is parser-extracted; the service-to-model link is
+heuristic, so the final hop should be verified before refactoring.
+```

{codebase_index-1.6.0/.opencode → codebase_index-1.7.0/.codex}/skills/codebase-index/scripts/cbx

@@ -4,7 +4,7 @@
 # - Whitelists subcommands so the skill can never invoke destructive ones (clean/init/watch).
 set -euo pipefail
 
-ALLOWED="search explain symbol refs impact graph stats doctor update index"
+ALLOWED="search explain architecture symbol refs impact diff-impact path describe graph stats doctor update index"
 
 sub="${1:-}"
 case " $ALLOWED " in

{codebase_index-1.6.0 → codebase_index-1.7.0}/.codex/skills/codebase-index/scripts/cbx.ps1

@@ -8,7 +8,10 @@ param(
 )
 
 $ErrorActionPreference = "Stop"
-$allowed = @("search", "explain", "symbol", "refs", "impact", "graph", "stats", "doctor", "update", "index")
+$allowed = @(
+    "search", "explain", "architecture", "symbol", "refs", "impact", "diff-impact",
+    "path", "describe", "graph", "stats", "doctor", "update", "index"
+)
 
 if ($allowed -notcontains $Subcommand) {
     Write-Error "cbx: refusing subcommand '$Subcommand'. Allowed: $($allowed -join ', ')"

{codebase_index-1.6.0 → codebase_index-1.7.0}/.github/workflows/ci.yml

@@ -5,12 +5,14 @@ on:
     branches: [main]
   pull_request:
 
+permissions: read-all
+
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
       - run: python -m pip install --upgrade pip
@@ -31,8 +33,8 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python-version }}
       - run: python -m pip install --upgrade pip

{codebase_index-1.6.0 → codebase_index-1.7.0}/.github/workflows/release.yml

@@ -5,12 +5,14 @@ on:
     tags: ["v*"]
   workflow_dispatch:   # manual (re)publish — e.g. push an already-tagged version to PyPI
 
+permissions: read-all
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: "3.12"
       - run: pip install -e ".[dev,build]"
@@ -22,7 +24,7 @@ jobs:
         run: twine check dist/*
       - name: Clean-machine smoke
         run: python scripts/release_smoke.py
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: dist
           path: dist/
@@ -36,13 +38,13 @@ jobs:
     permissions:
       contents: write   # create the GitHub release
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: dist
           path: dist
       - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2
         with:
           files: dist/*
           generate_release_notes: true
@@ -54,9 +56,9 @@ jobs:
     permissions:
       id-token: write   # OIDC for PyPI Trusted Publishing — no token stored anywhere
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: dist
           path: dist
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+        uses: pypa/gh-action-pypi-publish@ba38be9e461d3875417946c167d0b5f3d385a247 # release/v1

codebase_index-1.7.0/.opencode/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+1.7.0