descry-codegraph 1.1.0__tar.gz → 1.2.1__tar.gz

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/.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.1.0 → descry_codegraph-1.2.1}/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 (3382 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.1.0 → descry_codegraph-1.2.1}/CHANGELOG.md

@@ -4,6 +4,59 @@ 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.1] — 2026-11-13
+
+### Fixed
+
+- Python: an index no longer ends with `RecursionError` on a class statement
+  in a method whose base is written through `self` or `cls`
+  (`class Extra(self.form_class)`). The base is read in the scope around the
+  class statement, as Python evaluates it.
+- Python: an index no longer ends with `TypeError: unhashable type: 'list'`
+  where a method assigns an attribute that a base declares as a property
+  with a setter and then reads it.
+
+## [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

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: descry-codegraph
-Version: 1.1.0
+Version: 1.2.1
 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.1.0 → descry_codegraph-1.2.1}/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.1.0 → descry_codegraph-1.2.1}/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.1.0 → descry_codegraph-1.2.1}/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.1.0 → descry_codegraph-1.2.1}/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
 ```

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/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.

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/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.1.0 → descry_codegraph-1.2.1}/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.1.0 → descry_codegraph-1.2.1}/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 |
 |---|---|---|

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/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)" })),

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "descry-codegraph"
-version = "1.1.0"
+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.1.0 → descry_codegraph-1.2.1}/src/descry/__init__.py

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

descry_codegraph-1.2.1/src/descry/_files.py

@@ -0,0 +1,158 @@
+"""Writing files into a directory the indexed repository may have shipped."""
+
+import contextlib
+import fnmatch
+import glob
+import os
+import re
+import secrets
+import stat
+import time
+from pathlib import Path
+
+try:
+    import fcntl as _fcntl  # Unix only
+except ImportError:
+    _fcntl = None
+
+# A temporary nothing has written to for this long belongs to a writer that
+# was killed before it could replace its target or remove the temporary.
+_ORPHANED_AFTER = 3600
+
+
+def create_sibling(path: Path) -> tuple[int, Path]:
+    """Create a new file beside `path` to write it atomically, then replace it.
+
+    The name is random and the file is created with `O_EXCL`, so neither a
+    leftover nor a symlink a repository put at a name it could guess is
+    opened or followed. The mode is the one `open(path, "w")` gives.
+    Temporaries for `path` that are orphaned are removed first.
+    Returns the open descriptor and the file's path.
+    """
+    remove_orphans(path.parent, glob.escape(path.name))
+    tmp = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0)
+    return os.open(tmp, flags, 0o666), tmp
+
+
+def open_regular(path: Path, mode: str = "rb", **kwargs):
+    """`path` opened for reading if it is a regular file: never through a
+    symlink at its name, nor a FIFO or a device, which a repository can ship
+    where descry keeps files and a read of which would never end. OSError
+    for anything else."""
+    return os.fdopen(_open_regular_fd(path, os.O_RDONLY), mode, **kwargs)
+
+
+def _open_regular_fd(path: Path, flags: int) -> int:
+    """`os.open(path, flags)` if the file is regular: never through a symlink
+    at its name, nor a FIFO or a device. OSError for anything else."""
+    flags |= getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)
+    # Without O_NOFOLLOW (Windows), the name must be a regular file, or
+    # missing, before the open and the very file opened after it.
+    named = None
+    if not hasattr(os, "O_NOFOLLOW"):
+        with contextlib.suppress(FileNotFoundError):
+            named = os.lstat(path)
+        if named and not stat.S_ISREG(named.st_mode):
+            raise OSError(f"{path} is not a regular file")
+    fd = os.open(path, flags, 0o666)
+    opened = os.fstat(fd)
+    if not stat.S_ISREG(opened.st_mode) or (
+        named and not os.path.samestat(named, opened)
+    ):
+        os.close(fd)
+        raise OSError(f"{path} is not a regular file")
+    return fd
+
+
+def remove_orphans(directory: Path, names: str) -> None:
+    """Remove the temporaries `create_sibling` made in `directory` for targets
+    whose names match the glob `names`, that nothing has written to for
+    `_ORPHANED_AFTER` seconds."""
+    cutoff = time.time() - _ORPHANED_AFTER
+    for tmp in directory.glob(f".{names}.*.tmp"):
+        target, _, token = tmp.name[1:-4].rpartition(".")
+        try:
+            st = tmp.lstat()
+            if (
+                re.fullmatch(r"[0-9a-f]{16}", token)
+                and fnmatch.fnmatchcase(target, names)
+                and not stat.S_ISDIR(st.st_mode)
+                and st.st_mtime < cutoff
+            ):
+                tmp.unlink()
+        except OSError:
+            continue
+
+
+@contextlib.contextmanager
+def file_lock(lock_path: Path, timeout: float = 600.0, create: bool = True):
+    """Cross-process advisory lock; with `create` False a missing lock file
+    raises FileNotFoundError instead of being created.
+
+    Uses fcntl.flock on Unix and msvcrt.locking on Windows. Both are held on
+    an open handle, so the OS releases them when the holder exits.
+
+    The lock file is never unlinked. Removing it would break mutual
+    exclusion: a waiter blocked on the old inode and a newcomer that
+    recreates the path hold locks on two different inodes and both enter.
+    An empty lock file is cheap; correctness is not.
+
+    The cache directory may have come with the repository, so the lock file
+    is opened without following a symlink or waiting on a FIFO, never
+    truncated, and refused unless it is a regular file.
+    """
+    if _fcntl is not None:
+        poll_seconds = 0.05
+
+        def lock(f):
+            _fcntl.flock(f, _fcntl.LOCK_EX | _fcntl.LOCK_NB)
+
+        def unlock(f):
+            _fcntl.flock(f, _fcntl.LOCK_UN)
+
+    else:
+        # Windows fallback: lock the first byte of the (always empty) lock file.
+        import msvcrt
+
+        poll_seconds = 0.1
+
+        def lock(f):
+            msvcrt.locking(f.fileno(), msvcrt.LK_NBLCK, 1)
+
+        def unlock(f):
+            msvcrt.locking(f.fileno(), msvcrt.LK_UNLCK, 1)
+
+    fd = _open_regular_fd(
+        lock_path, os.O_WRONLY | os.O_APPEND | (os.O_CREAT if create else 0)
+    )
+    with os.fdopen(fd, "a", encoding="utf-8") as f:
+        # Poll non-blocking so the timeout is honoured; a blocking lock would
+        # wait forever regardless of the argument.
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                lock(f)
+                break
+            except OSError:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(
+                        f"Timed out waiting for the lock at {lock_path}"
+                    ) from None
+                time.sleep(poll_seconds)
+        try:
+            yield
+        finally:
+            unlock(f)
+
+
+def lock_held(lock_path: Path) -> bool:
+    """Whether another holder has `lock_path`'s `file_lock`; False where
+    the lock file is missing or cannot be opened, which it never creates."""
+    try:
+        with file_lock(lock_path, timeout=0, create=False):
+            return False
+    except TimeoutError:
+        return True
+    except OSError:
+        return False

{descry_codegraph-1.1.0 → descry_codegraph-1.2.1}/src/descry/cli.py

@@ -14,6 +14,7 @@ import json
 import os
 import sys
 
+from descry import __version__
 from descry._answers import fail
 from descry._streams import write_utf8
 from descry.handlers import (
@@ -249,6 +250,7 @@ def build_parser():
         prog="descry",
         description="Codebase knowledge graph tools",
     )
+    parser.add_argument("--version", action="version", version=f"descry {__version__}")
     subparsers = parser.add_subparsers(dest="command")
     answers = argparse.ArgumentParser(add_help=False)
     answers.add_argument(