descry-codegraph 1.0.2__tar.gz → 1.2.0__tar.gz

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/.github/workflows/release.yml

@@ -32,16 +32,16 @@ jobs:
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.12"
-      - name: Verify tag matches pyproject version
+      - name: Verify tag matches package version
         # A manual run that targets PyPI must be dispatched from the release tag.
         if: github.event_name == 'push' || inputs.target == 'pypi'
         env:
           GIT_TAG: ${{ github.ref_name }}
         run: |
-          PKG_VERSION=$(python -c "import tomllib; print(tomllib.loads(open('pyproject.toml','rb').read().decode())['project']['version'])")
+          PKG_VERSION=$(PYTHONPATH=src python -c "import descry; print(descry.__version__)")
           TAG_VERSION="${GIT_TAG#v}"
           if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
-            echo "::error::tag $GIT_TAG does not match pyproject version $PKG_VERSION"
+            echo "::error::tag $GIT_TAG does not match package version $PKG_VERSION"
             exit 1
           fi
       - name: Build sdist + wheel

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/AGENTS.md

@@ -23,7 +23,7 @@ just test tests/test_config.py::TestFromToml::test_from_toml_basic  # one test
 just test -k "cross_lang and not slow"                            # by expression
 ```
 
-Python 3.11+ required (enforced by `pyproject.toml`). Pre-commit gate: `just lint && just fmt && just test` all pass (3343 tests pass; a handful more are skipped where the environment lacks their fixture — a drop is a regression signal).
+Python 3.11+ required (enforced by `pyproject.toml`). Pre-commit gate: `just lint && just fmt && just test` all pass (3380 tests pass; a handful more are skipped where the environment lacks their fixture — a drop is a regression signal).
 
 Invoke the tool while developing:
 
@@ -43,7 +43,7 @@ Packaging: `pyproject.toml` defines four console scripts — `descry`, `descry-m
 
 **Two graph phases:**
 
-1. **Generate** (`generate.py`, invoked via `descry index` or `descry-generate`) — walks the project, parses source files with regex + AST (`_parsing.py` holds what every parser shares; each language has its `<lang>_parser.py`), resolves calls (`CallResolver` in `resolver.py`) from imports, declared and returned types, scope and the class hierarchy, optionally runs SCIP indexers (rust-analyzer, scip-typescript) for type-aware call resolution, optionally builds embeddings. Writes `.descry_cache/codebase_graph.json`. A call is resolved, left unresolved with the definitions that fit recorded as `candidates`, or dropped as external. Never resolve by name alone when more than one definition fits, never by file path, and never guess the type of a receiver: an unknown receiver stays unresolved.
+1. **Generate** (`generate.py`, invoked via `descry index` or `descry-generate`) — walks the project, parses source files with regex + AST (`_parsing.py` holds what every parser shares; each language has its `<lang>_parser.py`), resolves calls (`CallResolver` in `resolver.py`) from imports, declared and returned types, scope and the class hierarchy, optionally runs SCIP indexers (rust-analyzer, scip-typescript) for type-aware call resolution, optionally builds embeddings. Writes `.descry_cache/codebase_graph.json` last, once its embeddings are written (the graph is built under a temporary name and dated when the walk began), and holds `index.lock` for the whole run. A call is resolved, left unresolved with the definitions that fit recorded as `candidates`, or dropped as external. Never resolve by name alone when more than one definition fits, never by file path, and never guess the type of a receiver: an unknown receiver stays unresolved.
 2. **Query** (`query.py` → `GraphQuerier`) — loads the cached graph and answers callers/callees/flow/path/context queries. All service methods lazy-load the querier; freshness is tracked by graph file mtime.
 
 **Graph schema is versioned.** `src/descry/_graph.py` exports `CURRENT_SCHEMA` (currently `2`) and `load_graph_with_schema()`. Every graph-consuming code path must load via this helper — it raises `GraphSchemaError` on mismatch so stale graphs are rejected rather than silently producing wrong results. If you change the graph shape in a breaking way, bump `CURRENT_SCHEMA`.
@@ -70,7 +70,7 @@ These are load-bearing — see the `### Security` sections of `CHANGELOG.md`. Do
 - **The default cache directory stays inside the project.** A repository can ship `.descry_cache`, or its `scip` or `parse` subdirectory, as a symlink to another directory; `DescryConfig.cache_dir_error()` refuses indexing and embedding there, and only `DESCRY_CACHE_DIR` names a cache outside the project.
 - **A parse is reused only from an entry descry wrote.** Each file's parse is kept in `<cache>/parse` as JSON, never pickle, with an HMAC of the entry's name and content under a key in the user's state directory (`$XDG_STATE_HOME/descry/parse.key` when that is absolute, else `~/.local/state`; `%LOCALAPPDATA%` on Windows); where the key would be inside the project, no entry is read or kept. An entry a repository ships, or one moved to another file's name, fails the check and the file is parsed again; restoring an entry cannot stop an index.
 - **TOML-sourced subprocess args are validated.** `_validate_toolchain`, `_validate_scip_extra_arg`, `_validate_embedding_model` in `handlers.py` reject short flags, shell metacharacters, and out-of-root local paths. New TOML → subprocess plumbing must validate.
-- **Web UI is local-only by design.** `descry-web` binds `127.0.0.1`, has no auth, and deliberately omits `CORSMiddleware` so browsers enforce same-origin — a tab on `evil.com` cannot read `/api/source`. State-changing requests are refused unless same-origin (`Origin` / `Sec-Fetch-Site`), so it cannot trigger `/api/index` either. The host middleware rejects non-loopback `Host` headers to defeat DNS-rebinding that would otherwise bypass the 127.0.0.1 bind. `/api/source` enforces project-root containment, rejects non-regular files, files over `[code_files] max_file_mb` (10 by default; 0, which a repository's `.descry.toml` can set, lifts the cap) and files with a NUL byte in their first 8 KiB, and opens every path component with `O_NOFOLLOW` (on Windows, which has no `openat`, it checks after opening that the file opened is the one the path resolves to, inside the root). `/api/index` (and `/api/index/stream`) take no path parameter (always indexes the configured root). `DescryService` runs one index at a time for every interface and stops the indexer's whole process tree when a run ends early. The page's remote scripts carry SRI hashes and every response carries the Content-Security-Policy that `web/server.py` builds from the page's own tags, allowing exactly those asset URLs; a new remote script needs an SRI hash. Don't add a `--host 0.0.0.0` flag, don't add `CORSMiddleware`, and don't expose network listeners.
+- **Web UI is local-only by design.** `descry-web` binds `127.0.0.1`, has no auth, and deliberately omits `CORSMiddleware` so browsers enforce same-origin — a tab on `evil.com` cannot read `/api/source`. State-changing requests are refused unless same-origin (`Origin` / `Sec-Fetch-Site`), so it cannot trigger `/api/index` either. The host middleware rejects non-loopback `Host` headers to defeat DNS-rebinding that would otherwise bypass the 127.0.0.1 bind. `/api/source` enforces project-root containment, rejects non-regular files, files over `[code_files] max_file_mb` (10 by default; 0, which a repository's `.descry.toml` can set, lifts the cap) and files with a NUL byte in their first 8 KiB, and opens every path component with `O_NOFOLLOW` (on Windows, which has no `openat`, it checks after opening that the file opened is the one the path resolves to, inside the root). `/api/index` (and `/api/index/stream`) take no path parameter (always indexes the configured root). `DescryService` runs one index at a time for every interface, refuses one while another process holds the project's `index.lock`, and stops the indexer's whole process tree when a run ends early. The page's remote scripts carry SRI hashes and every response carries the Content-Security-Policy that `web/server.py` builds from the page's own tags, allowing exactly those asset URLs; a new remote script needs an SRI hash. Don't add a `--host 0.0.0.0` flag, don't add `CORSMiddleware`, and don't expose network listeners.
 - **MCP `index(path=...)`** is restricted to the configured project root; a path below it narrows the walk but still writes the root's graph.
 - **Embedding cache** uses numpy safe-mode load + JSON sidecar + atomic writes, keyed by the graph's bytes and time and the recipe. A rebuild reuses a node's vector, by the digest of its text, only from a cache descry signed with the key in the user's state directory (`signing_key()` in `_parse_cache.py`), so a shipped cache is never reused. `MODEL_REGISTRY` in `embeddings.py` is the single source of truth for which models descry ships pinned configurations for — each entry carries its revision and its task prompts. **`trust_remote_code` is always `False`**: there is no registry field, loader parameter or config key that enables it, so descry never executes code from a model repository — do not add one. A model named in `.descry.toml` that is not registered is loaded unpinned. Adding a model means adding a registry entry, not editing the loader.
 - **The cache key is the embedding recipe's identity.** `_recipe_fingerprint()` folds in the resolved repo id, the pinned revision, `RECIPE_VERSION`, `DOCSTRING_CHAR_LIMIT`, the prompt names, the entry's loading options, and whether source code is embedded (`CODE_CHAR_LIMIT`). Anything that changes the vectors without changing the graph must be added there and `RECIPE_VERSION` bumped, or a stale cache is served against freshly-encoded queries — comparing two different embedding spaces.

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to Descry will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [semver](https://semver.org/) from 1.0.0.
 
+## [1.2.0] — 2026-11-04
+
+### Added
+
+- `descry --version`; the skill's CLI reference lists it.
+
+### Changed
+
+- An index publishes the graph only once its embeddings are written, so
+  searches during a re-index stay hybrid on the previous graph. Before, the
+  new graph appeared first: searches fell back to keyword-only until the
+  embeddings were done, one stalled for `[timeouts] embedding_seconds`
+  (60 s by default), and after ten minutes `semantic` reported the model
+  unavailable.
+- During a first index, a tool that needs the graph and `status` answer
+  "No graph yet: an index is building it", and the text header reads
+  `[Graph: BUILDING]`, instead of saying no graph exists.
+- An index of a project another process is indexing is refused as `busy`
+  (`index`, `ensure`, the web's index stream, and `descry-generate`).
+- `ensure` re-indexes when files the graph tracks changed or were removed
+  since it was written, as well as when it is older than `max_stale_hours`.
+  A file dated in the future is not counted as changed, there or in
+  `status`.
+- The graph is dated when its index began, so a file edited while an index
+  runs counts as changed since it; before, an edit made before the graph
+  was written was missed.
+
+### Security
+
+- Windows: a lock file in the cache directory (`embeddings.lock`,
+  `index.lock`) that the repository ships as a symlink is refused instead
+  of followed, so an index neither locks nor creates the file it names, as
+  on other platforms.
+
+### Documentation
+
+- README: the MCP server is `descry-mcp.exe` on Windows, and
+  `python -m descry.mcp_server` starts it on every platform. Install
+  lines quote the extra (`"descry-codegraph[all]"`) so zsh does not
+  read the brackets as a glob.
+
+## [1.1.0] — 2026-11-03
+
+### Added
+
+- `callers` and `callees` take `exclude_tests` (CLI `--exclude-tests`, MCP
+  `exclude_tests`, web `?exclude_tests=true`), as `search` does.
+- `status` answers `changed_since_index`: how many files the graph tracks
+  are newer than it or gone; every text answer's header says so
+  (`| 2 file(s) changed since index`).
+- `descry index` logs its progress every 15 seconds while it parses and
+  while it resolves calls.
+
+### Changed
+
+- Rust: `<X as Trait>::f(x)` calls `X`'s impl of `Trait::f`, the trait's
+  default body where the impl has none, and `<dyn Trait>::f(x)` is
+  `Trait::f(x)`; the callee was read from the trait's type arguments
+  (`Trait>::f`).
+- Rust: a call on an element of a `vec![..]` a `let` binds reads what its
+  elements hold (`d[0].go()`).
+- Search: the keyword side leaves out the words a question or prompt is
+  written with ("where", "which", "the", "function"), so a whole prompt
+  searches what it asks about; a search of such words alone is unchanged.
+- Rust: glob re-exports that lead back round a cycle are walked once per
+  file: the walk that entered the cycle gives every module of it its answer.
+- Search: while an embedding model load is under way (the MCP server's at
+  its start, or the one an index run begins), a search answers keyword-only
+  instead of waiting; a search that finds no load under way, as each CLI
+  command's, begins one and waits as before.
+
 ## [1.0.2] — 2026-10-31
 
 ### Fixed

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/CONTRACT.md

@@ -59,7 +59,7 @@ as its type (`limit=ten`) is `invalid` there too.
 
 | tool | parameters | answer |
 |---|---|---|
-| `callers`, `callees` | `symbol`, `limit`=20 | `symbol`, `total`, counts, `more` (counts), `callers` / `callees` (references) |
+| `callers`, `callees` | `symbol`, `limit`=20, `exclude_tests`=false | `symbol`, `total`, counts, `more` (counts), `callers` / `callees` (references) |
 | `context` | `symbol`, `brief`, `full`, `expand_callees`, `deduplicate`, `depth`=1, `max_tokens`=2000, `callee_budget`=2000, `head_lines`, `max_output_tokens` | `symbol` (definition), `brief`; brief: `callers`, `callees` (counts); else `depth`, `callers`, `callees` (references), `callers_more`, `callees_more` (counts), `examples` (`file`, `line`, `candidates`), `members` (`id`, `name`, `line`, `tokens`), `tests`, `configs` (`id`, `line`, `type`), `omitted`, `truncated`; with `deduplicate`, a symbol shown before answers `symbol` and `repeated` only |
 | `flow` | `start`, `direction`=forward, `depth`=3, `target`, `inline_threshold`=100 | `start`, `direction`, `asked`, `depth`, `target`, `root` (tree: `id`, `name`, `type`, `tokens`, `file`, `line`, `kind`, `candidates`, `children`, `more`, `more_possible`, `seen`), `path_to_target`?, `cut`? |
 | `path` | `start`, `end`, `max_depth`=10, `direction`=forward | `status` (`found`, `not_found`, `timeout`), `start`, `end`, `direction`, `max_depth`, `hops` (`caller`, `callee` references, `file`, `line`) |
@@ -73,7 +73,7 @@ as its type (`limit=ten`) is `invalid` there too.
 | `churn` | `time_range`, `path_filter`, `limit`=20, `mode`=symbols, `exclude_generated`=true | `mode`, `time_range`, `path_filter`, `truncation_note`?, and `symbols`, `files`, `pairs` (with `file_level`?) or `message` |
 | `changes` | `commit_range`, `time_range`, `path_filter`, `show_callers`=true, `limit`=50 | `range`, `commits`, `files_count`, `symbols_count`, and `symbols` (with `callers`) or `changed_files`; or `message` |
 | `evolution` | `symbol`, `time_range`, `limit`=10, `show_diff`, `crate` | `node_id`, `mode` (`lines`, `file`), `truncation_note`?, `authors`, `commits` (`hash`, `date`, and in `lines` mode `added`, `removed`); or `message` |
-| `status` | — | `exists`, `age_str`, `age_hours`, `nodes`, `edges`, `languages`, `stale`, `error`, `scip` (`state`, `indexers`, `cached`), `embeddings` (`state`, `nodes`, `model`) |
+| `status` | — | `exists`, `age_str`, `age_hours`, `nodes`, `edges`, `languages`, `stale`, `changed_since_index`, `error`, `scip` (`state`, `indexers`, `cached`), `embeddings` (`state`, `nodes`, `model`) |
 | `health` | — | `status`, `version`, `project_root`, `cache_dir`, `warm`, `max_depth` (the deepest a `flow` or `context` goes), `features`, `graph` |
 | `ensure` | `max_age_hours` | `action` (`ready`, `refreshed`, `generated`), `summary`, `graph` (status) |
 | `index` | `path`=. (not on the web, which always indexes the project root) | the graph's status after the run |

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 1.0.2
+Version: 1.2.0
 Summary: Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis
 Project-URL: Homepage, https://github.com/06chaynes/descry
 Project-URL: Repository, https://github.com/06chaynes/descry
@@ -165,7 +165,7 @@ yourself, which is also loaded unpinned.
 
 ```bash
 # Install with all optional features
-pip install descry-codegraph[all]
+pip install "descry-codegraph[all]"
 
 # Index your project
 cd your-project
@@ -225,6 +225,8 @@ Or with a specific Python path:
 
 Descry uses the standard MCP stdio transport. Any MCP-compatible host can spawn `descry-mcp` as a subprocess.
 
+On Windows the executable is `descry-mcp.exe`. `python -m descry.mcp_server`, with the Python descry is installed in, starts the same server on every platform.
+
 ## Tools
 
 Descry provides 19 tools, available through all interfaces:
@@ -233,7 +235,7 @@ Descry provides 19 tools, available through all interfaces:
 |------|-------------|
 | `health` | Diagnostic check — version, graph status, feature availability |
 | `status` | Graph existence and freshness |
-| `ensure` | Ensure graph exists and is fresh (regenerates if stale) |
+| `ensure` | Ensure graph exists and is fresh (regenerates if stale or files changed) |
 | `index` | Regenerate graph, SCIP indices, and embeddings |
 | `search` | Search symbol names and docstrings (keyword + semantic) |
 | `semantic` | Pure semantic search using embeddings only |
@@ -410,19 +412,19 @@ pip install descry-codegraph
 ### With MCP server
 
 ```bash
-pip install descry-codegraph[mcp]
+pip install "descry-codegraph[mcp]"
 ```
 
 ### With Web UI
 
 ```bash
-pip install descry-codegraph[web]
+pip install "descry-codegraph[web]"
 ```
 
 ### With semantic search
 
 ```bash
-pip install descry-codegraph[embeddings]
+pip install "descry-codegraph[embeddings]"
 ```
 
 To select `embeddinggemma-2`, install its extra instead (adds Pillow and
@@ -435,7 +437,7 @@ pip install "descry-codegraph[embeddinggemma-2]"
 ### Everything
 
 ```bash
-pip install descry-codegraph[all]
+pip install "descry-codegraph[all]"
 ```
 
 ### Choosing a torch build
@@ -489,7 +491,7 @@ Requires [uv](https://github.com/astral-sh/uv) and [just](https://github.com/cas
 
 3. **Query** — All tools query the cached graph. Keyword search uses TF-IDF scoring. Semantic search uses sentence-transformer embeddings. Call-graph traversal follows edges in the graph.
 
-4. **Freshness** — `ensure` regenerates the graph when its age exceeds `[project] max_stale_hours` (default 24), or the `--max-age-hours` flag (CLI) / `max_age_hours` argument (MCP) when one is given. The same setting drives the "STALE" badge in `descry status`. The MCP server pre-warms the graph on startup.
+4. **Freshness** — `ensure` regenerates the graph when files it indexed changed or were removed since it was written, and when its age exceeds `[project] max_stale_hours` (default 24), or the `--max-age-hours` flag (CLI) / `max_age_hours` argument (MCP) when one is given. The same setting drives the "STALE" badge in `descry status`. The MCP server pre-warms the graph on startup.
 
 ## Design Notes
 

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/README.md

@@ -104,7 +104,7 @@ yourself, which is also loaded unpinned.
 
 ```bash
 # Install with all optional features
-pip install descry-codegraph[all]
+pip install "descry-codegraph[all]"
 
 # Index your project
 cd your-project
@@ -164,6 +164,8 @@ Or with a specific Python path:
 
 Descry uses the standard MCP stdio transport. Any MCP-compatible host can spawn `descry-mcp` as a subprocess.
 
+On Windows the executable is `descry-mcp.exe`. `python -m descry.mcp_server`, with the Python descry is installed in, starts the same server on every platform.
+
 ## Tools
 
 Descry provides 19 tools, available through all interfaces:
@@ -172,7 +174,7 @@ Descry provides 19 tools, available through all interfaces:
 |------|-------------|
 | `health` | Diagnostic check — version, graph status, feature availability |
 | `status` | Graph existence and freshness |
-| `ensure` | Ensure graph exists and is fresh (regenerates if stale) |
+| `ensure` | Ensure graph exists and is fresh (regenerates if stale or files changed) |
 | `index` | Regenerate graph, SCIP indices, and embeddings |
 | `search` | Search symbol names and docstrings (keyword + semantic) |
 | `semantic` | Pure semantic search using embeddings only |
@@ -349,19 +351,19 @@ pip install descry-codegraph
 ### With MCP server
 
 ```bash
-pip install descry-codegraph[mcp]
+pip install "descry-codegraph[mcp]"
 ```
 
 ### With Web UI
 
 ```bash
-pip install descry-codegraph[web]
+pip install "descry-codegraph[web]"
 ```
 
 ### With semantic search
 
 ```bash
-pip install descry-codegraph[embeddings]
+pip install "descry-codegraph[embeddings]"
 ```
 
 To select `embeddinggemma-2`, install its extra instead (adds Pillow and
@@ -374,7 +376,7 @@ pip install "descry-codegraph[embeddinggemma-2]"
 ### Everything
 
 ```bash
-pip install descry-codegraph[all]
+pip install "descry-codegraph[all]"
 ```
 
 ### Choosing a torch build
@@ -428,7 +430,7 @@ Requires [uv](https://github.com/astral-sh/uv) and [just](https://github.com/cas
 
 3. **Query** — All tools query the cached graph. Keyword search uses TF-IDF scoring. Semantic search uses sentence-transformer embeddings. Call-graph traversal follows edges in the graph.
 
-4. **Freshness** — `ensure` regenerates the graph when its age exceeds `[project] max_stale_hours` (default 24), or the `--max-age-hours` flag (CLI) / `max_age_hours` argument (MCP) when one is given. The same setting drives the "STALE" badge in `descry status`. The MCP server pre-warms the graph on startup.
+4. **Freshness** — `ensure` regenerates the graph when files it indexed changed or were removed since it was written, and when its age exceeds `[project] max_stale_hours` (default 24), or the `--max-age-hours` flag (CLI) / `max_age_hours` argument (MCP) when one is given. The same setting drives the "STALE" badge in `descry status`. The MCP server pre-warms the graph on startup.
 
 ## Design Notes
 

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/claude-skill/README.md

@@ -29,7 +29,7 @@ without forcing it on simple file-read tasks.
 ## Prerequisites
 
 - Python 3.11+.
-- `descry-codegraph` installed: `pip install descry-codegraph[all]`.
+- `descry-codegraph` installed: `pip install "descry-codegraph[all]"`.
 - Optional but recommended: the MCP server registered (see below).
 - Optional: `rust-analyzer` (Rust SCIP), `scip-typescript` (TS SCIP),
   `scip-python` (Python SCIP) for type-aware call resolution.

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/claude-skill/descry/SKILL.md

@@ -83,7 +83,7 @@ under the project root. Before the first query in a session:
 
 ```bash
 descry status   # Is there a graph? How old is it?
-descry ensure   # Regenerate if missing or stale (respects max_stale_hours)
+descry ensure   # Regenerate if missing, stale (max_stale_hours) or files changed
 ```
 
 `descry ensure` is safe to call unconditionally — it no-ops if the graph is
@@ -92,12 +92,12 @@ refreshes SCIP indices and embeddings, which can take minutes on large
 Rust workspaces). If the user hasn't asked for indexing and no graph exists,
 prompt them before running `descry index`.
 
-Graph freshness is tracked by file mtime, and `descry ensure` rebuilds only
-a graph older than `[project] max_stale_hours` (24 by default). After the
-user edits code that changes structure (new symbols, renames), run
-`descry index` before querying again: `ensure` may report the graph ready
-while it still shows the old layout. Cached queriers, semantic searchers,
-and dedup caches all invalidate by mtime.
+Graph freshness is tracked by file mtime: `descry ensure` rebuilds a graph
+older than `[project] max_stale_hours` (24 by default), or one whose files
+changed or were removed since it was written. A file added since is not
+noticed: after the user adds files, run `descry index` before querying
+again. Cached queriers, semantic searchers, and dedup caches all invalidate
+by mtime.
 
 ## Commands — grouped by intent
 

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/claude-skill/descry/references/cli-reference.md

@@ -7,9 +7,10 @@ the detected project root. Freshness is managed via `descry status` /
 ## Global discovery
 
 ```bash
+descry --version            # installed version
 descry health               # version, graph status, SCIP/embeddings/git state
 descry status               # just the graph: exists? nodes? edges? stale?
-descry ensure               # regenerate only if missing or stale
+descry ensure               # regenerate only if missing, unusable, stale or files changed
 descry index [path]         # force full rebuild (SCIP + embeddings)
 descry embedding-models     # registered embedding models, and the one selected
 ```
@@ -43,8 +44,8 @@ descry quick <symbol>
 ## Call graph
 
 ```bash
-descry callers <symbol> [--limit N]           # default 20
-descry callees <symbol> [--limit N]           # default 20
+descry callers <symbol> [--limit N] [--exclude-tests]   # default 20
+descry callees <symbol> [--limit N] [--exclude-tests]   # default 20
 
 descry flow <start>
     [--direction forward|backward]   # default forward

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/claude-skill/descry/references/mcp-tools.md

@@ -23,7 +23,7 @@ This is descry's prompt-injection defense — preserve it when quoting.
 ### Freshness and diagnostics
 - `descry_health` — version, graph status, feature availability.
 - `descry_status` — graph existence / freshness only.
-- `descry_ensure` — regenerate iff missing or stale.
+- `descry_ensure` — regenerate iff missing, unusable, stale or files it indexed changed.
 - `descry_index(path=".")` — authoritative rebuild. A `path` below the
   project root narrows which files are walked; the result still replaces
   the root's graph. Paths outside the root are rejected.
@@ -35,8 +35,8 @@ This is descry's prompt-injection defense — preserve it when quoting.
 - `descry_quick(symbol, full=False, brief=False)` — search + context in one.
 
 ### Call graph
-- `descry_callers(symbol, limit=20)`
-- `descry_callees(symbol, limit=20)`
+- `descry_callers(symbol, limit=20, exclude_tests=False)`
+- `descry_callees(symbol, limit=20, exclude_tests=False)`
 - `descry_flow(start, direction="forward", depth=3, target=None, inline_threshold=100)`
 - `descry_path(start, end, max_depth=10, direction="forward")`
 

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/claude-skill/descry/references/recipes.md

@@ -140,9 +140,9 @@ Requires an OpenAPI spec: set `[cross_lang] openapi_path = "..."` in
 - **Don't** use `descry search` for behavior-worded queries; `descry semantic`
   is built for that and will do better.
 - **Don't** bypass `status` on a stale graph. Out-of-date graphs
-  produce plausible-looking wrong answers. After edits that change
-  structure, `descry index` (not `ensure`, which rebuilds only a graph
-  older than `max_stale_hours`) brings the graph current.
+  produce plausible-looking wrong answers. After edits, `descry ensure`
+  rebuilds a graph whose files changed or were removed; after adding
+  files, `descry index` brings the graph current.
 - **Don't** shell out to grep when the question is structural. Even one
   descry call beats three Greps for "who calls X".
 

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/docs/CERTAINTY.md

@@ -54,8 +54,9 @@ answers; a call dropped as one out of the project is not among them.
 
 ## Keeping up with the source
 
-An index is a snapshot. `status` says how old it is; `ensure` builds it
-again when it is older than `[project] max_stale_hours`. An index after a
-change parses only the files that changed, and resolves again only the
-calls of files whose resolution read something that changed, so its
+An index is a snapshot. `status` says how old it is and how many of its
+files changed since; `ensure` builds it again when it is older than
+`[project] max_stale_hours` or files it holds changed or were removed. An
+index after a change parses only the files that changed, and resolves again
+only the calls of files whose resolution read something that changed, so its
 answers are those a full index would give.

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/docs/TOOLS.md

@@ -30,7 +30,7 @@ MCP `descry_health`; web `GET /api/health`; CLI `usage: descry health [--json]`
 
 ## ensure
 
-Ensure the codebase graph exists and is fresh. Call this FIRST before other descry queries. Regenerates if missing or older than max_age_hours (default: the project's configured max_stale_hours). Returns graph status with node/edge counts. WARNING: May take 30-60 seconds if regeneration is needed.
+Ensure the codebase graph exists and is fresh. Call this FIRST before other descry queries. Regenerates if missing, older than max_age_hours (default: the project's configured max_stale_hours), or if files it indexed changed since. Returns graph status with node/edge counts. WARNING: May take 30-60 seconds if regeneration is needed.
 
 | parameter | type | default |
 |---|---|---|
@@ -46,22 +46,23 @@ Check if the codebase graph exists and its freshness. Returns existence, age, an
 
 No parameters.
 
-Answer: `exists`, `age_str`, `age_hours`, `nodes`, `edges`, `languages`, `stale`, `error`, `scip` (`state`, `indexers`, `cached`), `embeddings` (`state`, `nodes`, `model`)
+Answer: `exists`, `age_str`, `age_hours`, `nodes`, `edges`, `languages`, `stale`, `changed_since_index`, `error`, `scip` (`state`, `indexers`, `cached`), `embeddings` (`state`, `nodes`, `model`)
 
 MCP `descry_status`; web `GET /api/status`; CLI `usage: descry status [--json]`
 
 ## callers
 
-Find all functions/methods that call a given symbol. More reliable than grep for call relationships - distinguishes actual calls from definitions and comments. Use for impact analysis before refactoring or to understand usage patterns.
+Find all functions/methods that call a given symbol. More reliable than grep for call relationships - distinguishes actual calls from definitions and comments. Use for impact analysis before refactoring or to understand usage patterns. Set exclude_tests=true to leave out test callers.
 
 | parameter | type | default |
 |---|---|---|
 | `symbol` | string | required |
 | `limit` | integer | 20 |
+| `exclude_tests` | boolean | false |
 
 Answer: `symbol`, `total`, counts, `more` (counts), `callers` / `callees` (references)
 
-MCP `descry_callers`; web `GET /api/callers`; CLI `usage: descry callers [--json] [--limit LIMIT] symbol`
+MCP `descry_callers`; web `GET /api/callers`; CLI `usage: descry callers [--json] [--limit LIMIT] [--exclude-tests] symbol`
 
 `descry callers load --json`:
 
@@ -91,16 +92,17 @@ MCP `descry_callers`; web `GET /api/callers`; CLI `usage: descry callers [--json
 
 ## callees
 
-Find what functions/methods a given symbol calls. Use for dependency analysis and understanding what a function relies on.
+Find what functions/methods a given symbol calls. Use for dependency analysis and understanding what a function relies on. Set exclude_tests=true to leave out test callees.
 
 | parameter | type | default |
 |---|---|---|
 | `symbol` | string | required |
 | `limit` | integer | 20 |
+| `exclude_tests` | boolean | false |
 
 Answer: `symbol`, `total`, counts, `more` (counts), `callers` / `callees` (references)
 
-MCP `descry_callees`; web `GET /api/callees`; CLI `usage: descry callees [--json] [--limit LIMIT] symbol`
+MCP `descry_callees`; web `GET /api/callees`; CLI `usage: descry callees [--json] [--limit LIMIT] [--exclude-tests] symbol`
 
 `descry callees main --json`:
 

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/pi-extension/descry-cli.py

@@ -38,11 +38,13 @@ def main():
     p = subparsers.add_parser("callers")
     p.add_argument("--symbol", required=True)
     p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--exclude-tests", action="store_true")
 
     # callees
     p = subparsers.add_parser("callees")
     p.add_argument("--symbol", required=True)
     p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--exclude-tests", action="store_true")
 
     # context
     p = subparsers.add_parser("context")
@@ -157,9 +159,9 @@ async def dispatch(args):
         elif cmd == "status":
             return await service.status()
         elif cmd == "callers":
-            return await service.callers(args.symbol, args.limit)
+            return await service.callers(args.symbol, args.limit, args.exclude_tests)
         elif cmd == "callees":
-            return await service.callees(args.symbol, args.limit)
+            return await service.callees(args.symbol, args.limit, args.exclude_tests)
         elif cmd == "context":
             return await service.context(
                 args.symbol,

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/pi-extension/descry-tools.ts

@@ -72,7 +72,7 @@ export default function (pi: ExtensionAPI) {
 		label: "Descry Ensure",
 		description:
 			"Ensure the codebase graph exists and is fresh. Call this FIRST before other descry queries. " +
-			"Regenerates if missing or older than max_age_hours. Returns graph status with node/edge counts. " +
+			"Regenerates if missing, older than max_age_hours, or if files it indexed changed since. Returns graph status with node/edge counts. " +
 			"WARNING: May take 30-60 seconds if regeneration is needed.",
 		parameters: Type.Object({
 			max_age_hours: Type.Optional(Type.Number({ description: "Max graph age in hours before regeneration (default: the project's max_stale_hours)" })),
@@ -124,10 +124,12 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({
 			symbol: Type.String({ description: "A node ID, or a symbol name" }),
 			limit: Type.Optional(Type.Number({ description: "Max results", default: 20 })),
+			exclude_tests: Type.Optional(Type.Boolean({ description: "Exclude test files", default: false })),
 		}),
 		async execute(_toolCallId, params, signal) {
 			const args = ["--symbol", params.symbol];
 			if (params.limit !== undefined) args.push("--limit", String(params.limit));
+			if (params.exclude_tests) args.push("--exclude-tests");
 			const result = await runDescry("callers", args, signal);
 			return { content: [{ type: "text", text: result }] };
 		},
@@ -142,10 +144,12 @@ export default function (pi: ExtensionAPI) {
 		parameters: Type.Object({
 			symbol: Type.String({ description: "A node ID, or a symbol name" }),
 			limit: Type.Optional(Type.Number({ description: "Max results", default: 20 })),
+			exclude_tests: Type.Optional(Type.Boolean({ description: "Exclude test files", default: false })),
 		}),
 		async execute(_toolCallId, params, signal) {
 			const args = ["--symbol", params.symbol];
 			if (params.limit !== undefined) args.push("--limit", String(params.limit));
+			if (params.exclude_tests) args.push("--exclude-tests");
 			const result = await runDescry("callees", args, signal);
 			return { content: [{ type: "text", text: result }] };
 		},

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "descry-codegraph"
-version = "1.0.2"
+dynamic = ["version"]
 description = "Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis"
 requires-python = ">=3.11"
 authors = [{name = "Christian Haynes"}]
@@ -72,5 +72,8 @@ extend-exclude = ["src/descry/scip/pb2.py"]
 requires = ["hatchling>=1.27"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+path = "src/descry/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/descry"]

{descry_codegraph-1.0.2 → descry_codegraph-1.2.0}/src/descry/__init__.py

@@ -1,4 +1,4 @@
 """Descry — Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis."""
 
-__version__ = "1.0.2"
+__version__ = "1.2.0"
 __all__ = ["__version__"]