descry-codegraph 0.1.1__tar.gz → 0.2.0__tar.gz

{descry_codegraph-0.1.1 → descry_codegraph-0.2.0}/.github/workflows/ci.yml

@@ -73,4 +73,9 @@ jobs:
       - name: Audit resolved environment
         run: |
           . .venv/bin/activate
-          pip-audit --skip-editable
+          # CVE-2026-3219 (GHSA-58qw-9mgm-455v): concatenated tar/ZIP
+          # interpretation conflict in pip itself. Affects pip <= 26.0.1
+          # with no patched version upstream. pip is a build-time
+          # installer in the venv, not a runtime dep we ship.
+          # Re-evaluate when pip ships a fix.
+          pip-audit --skip-editable --ignore-vuln CVE-2026-3219

{descry_codegraph-0.1.1 → descry_codegraph-0.2.0}/.github/workflows/release.yml

@@ -70,7 +70,12 @@ jobs:
       - name: Audit resolved environment
         run: |
           . .venv/bin/activate
-          pip-audit --skip-editable
+          # CVE-2026-3219 (GHSA-58qw-9mgm-455v): concatenated tar/ZIP
+          # interpretation conflict in pip itself. Affects pip <= 26.0.1
+          # with no patched version upstream. pip is a build-time
+          # installer in the venv, not a runtime dep we ship.
+          # Re-evaluate when pip ships a fix.
+          pip-audit --skip-editable --ignore-vuln CVE-2026-3219
 
   publish-testpypi:
     name: Publish to TestPyPI

descry_codegraph-0.2.0/CHANGELOG.md

@@ -0,0 +1,369 @@
+# Changelog
+
+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 pre-1.0 semver (minor-version bumps may include breaking changes; see README versioning stance).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-04-20
+
+A large feature + resolution-quality release. Seven new SCIP language
+adapters land (Java/Kotlin/Scala, Go, Ruby, PHP, C#/VB, C/C++, Dart)
+alongside a language-general STDLIB_FILTER sweep that brought CALLS
+resolution above 90% on 20 of 26 measured corpora. The release also
+folds in a full session of convergence-audit hardening: user-input
+parsing no longer 500s on garbage query strings, subprocess output
+tolerates non-UTF-8 bytes, and the documented security invariants match
+what the code actually does.
+
+Graph schema stays at v1 — existing `.descry_cache/codebase_graph.json`
+files remain readable. CLI subcommands and MCP tool names are unchanged
+(19 of each, 1:1 parity).
+
+### Added
+
+- **Dart / Flutter support** via `scip-dart` (Milestone D). DartAdapter
+  discovers projects by `pubspec.yaml` at the root or under
+  `packages/*` (melos / workspace layout); runs `scip-dart ./` from the
+  package root and uses `output_mode="rename"` to move the emitted
+  `index.scip` into the cache. DartParser handles imports
+  (`package:` / `dart:` / relative), classes (including `abstract`,
+  `base`, `sealed`, `final`, `interface class`, `mixin class`), mixins,
+  extensions, enums, typedefs, top-level constants, class inheritance
+  (`extends` → INHERITS edge), and call sites with null-safe receiver
+  chains (`?.method()`). Dart has heavy top-level code (top-level
+  functions, top-level variable initializers), so the parser emits
+  calls at file scope too — unlike Java/C# parsers which gate calls on
+  non-file context. pub smoke test hit **71%** resolution
+  (10,279 / 14,490 CALLS edges) — below the 91.2% Rust bar, accepted
+  as the Dart ceiling for test-heavy codebases where pub's internal
+  test-helper DSL (`servePackages`, `d.file`, `runPub`, etc.) contributes
+  the bulk of unresolved calls.
+- **Java / Kotlin / Scala support** via `scip-java` (Milestone J of Wave 2).
+  JavaParser extracts classes, interfaces, enums, records, methods,
+  constructors, fields, imports, and call sites. JavaAdapter ships a
+  Gradle init-script that strips `-Werror` so scip-java works out of the
+  box on Apache projects (Kafka, etc.) whose builds treat warnings as
+  fatal. Kafka smoke test hit **92.7%** CALLS resolution.
+- **Go support** via `scip-go` (Milestone G). GoParser covers packages,
+  grouped imports, type declarations, free functions, methods with
+  receivers, const/var blocks, and call sites. Kubernetes smoke test
+  hit **98.3%** resolution.
+- **Ruby support** via `scip-ruby` (Milestone R). RubyParser uses
+  indent-based context tracking (Ruby uses `end` not `}`); extracts
+  classes with INHERITS edges, modules, methods (including `self.foo`,
+  `foo?`, `foo!`), `attr_reader/writer/accessor`, `require` /
+  `require_relative`, and top-level constants. Rails smoke test hit
+  **87.8%** — below the 91.2% Rust bar, accepted as the Ruby-without-
+  Sorbet ceiling (scip-ruby falls back to `# typed: false` heuristics
+  when Sorbet annotations are absent).
+- **PHP support** via `scip-php` (Milestone P, third-party indexer by
+  davidrjenni). PhpParser handles namespaces, classes / interfaces /
+  traits / enums, `public/protected/private function`, properties,
+  constants, and method / static / instance calls; Allman-brace lookahead
+  (scan up to 10 lines for the opening `{`) was needed for Laravel's
+  style. Laravel smoke test hit **88.6%**.
+- **C# / VB.NET support** via `scip-dotnet` (Milestone N). DotnetAdapter
+  sets `DOTNET_ROLL_FORWARD=LatestMajor` so scip-dotnet's net9 target
+  runs on systems with only net10 installed. Serilog smoke test hit
+  **83.7%**.
+- **C / C++ support** via `scip-clang` (Milestone C). ClangAdapter emits
+  scheme `cxx` (verified from real indexes; not `scip-clang` as a name
+  might suggest). Discovery gives top priority to root-level
+  `compile_commands.json` so Bear-backed Makefile builds and top-level
+  CMake projects work as a single unit. ClangParser avoids regex
+  catastrophic backtracking (which hit >20s on Redis `src/dict.c` in
+  an early draft) via a hand-rolled `_extract_function_name` that scans
+  right-to-left through the argument list. Redis smoke test hit
+  **79.2%**; headers lag .c files (63.3% vs 81.2%) due to scip-clang
+  compdb-coverage limits on transitively-included headers.
+
+### Changed
+
+- **CALLS resolution rose above the 90% bar on 20 of 26 measured
+  corpora** (up from ~10 pre-sweep) via a focused language-general
+  filter pass — zero codebase-specific entries. The sweep expanded
+  `STDLIB_FILTER` / `STDLIB_PREFIXES` across every supported language:
+  - **TypeScript / JavaScript**: `_JSTS_CONTROL_KEYWORDS` filter in
+    the `TSParser` regex fallback (rejects `if(`, `while(`, `for(`,
+    `switch(` captures — removes ~37k spurious unresolved on the
+    TypeScript compiler alone), tslib emit helpers (`__awaiter`,
+    `__generator`, `__rest`, `__spreadArray`, `__classPrivateFieldGet`,
+    `__addDisposableResource`, …), DOM APIs (`textContent`,
+    `getAttribute`, `classList`, `appendChild`, …), Array/Object
+    statics (`isArray`, `fromEntries`, `defineProperty`, …),
+    Playwright (`page.*`), Vitest/Jest todo / only / each / snapshot
+    modifiers, React core hooks + TanStack Query + Node `assert`
+    strict variants + Lingui / nanoid / uuid.* / date-fns / RN-Expo
+    surface. ast-grep now rejects `$FUNC` captures that include parens
+    or non-identifier characters (stops curried-call shape like
+    `test.runIf(isBuild)(…)` from polluting CALLS targets).
+  - **C#**: `var` added to `_DOTNET_CONTROL_KEYWORDS` (fixes ~1k/file
+    spurious `var (` captures on modern C# codebases) along with the
+    full modern declaration vocabulary (`record`, `partial`, `sealed`,
+    `override`, `static`, `params`, `required`, `scoped`, `file`,
+    `global`) and every primitive alias (`object`, `string`, `bool`,
+    `int`, `long`, `byte`, `char`, `float`, `double`, `decimal`,
+    `nint`, `nuint`). Moq (`It.IsAny`, `Mock.Of`, `Setup`, `Verify`,
+    `ReturnsAsync`), FakeItEasy (`A.CallTo`, `A.Fake`, `A.Dummy`),
+    ASP.NET Core DI (`Add*`, `Use*`, `Map*`, `GetRequiredService`),
+    .NET Reflection + Span/Memory, `System.String` statics, Selenium
+    WebDriver.
+  - **Java**: AssertJ (full `assertThat*` surface, `hasCauseInstanceOf`,
+    `isThrownBy`, `satisfies`), BDDMockito (`given`, `willReturn`,
+    `willThrow`), Project Reactor (`StepVerifier`, `expectNext`,
+    `flatMap`, `switchIfEmpty`, `subscribeOn`), Mockito static
+    (`mockStatic`, `mockConstruction`, `invocation.getArgument`),
+    Hamcrest matcher vocabulary, Apache Lucene types, ANTLR-generated
+    runtime, `java.time` / `java.util.Properties` / `java.nio.Buffer`
+    / `java.io.File`, `java.sql.*` + `java.util.Locale.*`,
+    `jakarta.servlet` + `javax.xml.sax`, reflection extras.
+  - **Go**: `encoding/binary` (`BigEndian/LittleEndian.Uint*/PutUint*`),
+    `sync` lock methods (`Lock`, `Unlock`, `RLock`, `RUnlock`,
+    `Add`/`Done`/`Wait`), `bytes.Buffer` + `strings.Builder` common
+    methods, `golang.org/x/sync/errgroup`, `go.uber.org/goleak`,
+    AWS SDK v2 helpers (`aws.Int32`, `aws.String`, …), ULID,
+    `klog.`/`ginkgo.`/`Gomega.`/`testify.` prefixes.
+  - **Rust**: clap CLI (`value_name`, `help_heading`, `get_one`,
+    `get_flag`, `long_about`, subcommand builders), snapbox test
+    (`stdout_eq`, `stderr_eq`, `subset_matches`), integer arithmetic
+    (`wrapping_*`, `saturating_*`, `checked_*`, `overflowing_*`,
+    `rotate_*`, `count_ones`/`_zeros`), atomic compare-exchange /
+    fetch variants, pointer `as_ptr`/`as_mut_ptr`/`copy_nonoverlapping`/
+    `read_volatile`, slice `is_ascii_*`/`split_whitespace`/
+    `char_indices`, fd `from_raw_fd`/`as_raw_fd`/`borrow_raw`.
+  - **C / C++**: TCL C API (`Tcl_*` prefix — sqlite bindings),
+    LLVM C API (`LLVM*` — postgres JIT), CPython C API (`Py_*`,
+    `PyObject_*`, `PyDict_*`, …), Win32 C API (`CreateFile`,
+    `GetLastError`, `LoadLibrary`, registry, `HeapAlloc`, …), POSIX
+    pthread full surface (`pthread_mutex_*`, `pthread_cond_*`,
+    `pthread_rwlock_*`, `pthread_spin_*`, `pthread_barrier_*`),
+    stdarg (`va_start`, `va_end`, `va_arg`, `va_copy`), C11
+    stdatomic, BSD-specific strings (`strlcpy`, `strlcat`, `arc4random_*`,
+    `reallocarray`), BSD socket byte-order (`ntohs`, `htonl`, …) +
+    full socket API, OpenSSL (`BN_`, `HMAC_`, `EC_KEY_`, `ENGINE_`),
+    jemalloc (public `mallocx`/`xallocx`/`rallocx`/`sallocx`/
+    `dallocx`/`nallocx` + internals `edata_`, `emap_`, `sz_`, `pa_`,
+    `hpa_`, `prof_`, `tsd_`, `tsdn_`, `atomic_*_zu`).
+  - **PHP**: PHPUnit `assertIs*` full surface + PHPUnit:: qualified
+    variants, Mockery extras (`makePartial`, `withArgs`), Carbon +
+    PHP `DateTime` full method set, `version_compare`, binary /
+    encoding / output stdlib (`pack`, `unpack`, `bin2hex`,
+    `curl_setopt_array`, `ob_start`/`ob_end_flush`, `strspn`, `strtr`,
+    `addslashes`), PSR-7 HTTP helpers (`getStatusCode`, `withHeader`,
+    `withBody`, `getUri`).
+  - **Ruby**: Full `String` / `Enumerable` / `Hash` / `IO` method
+    surface (`gsub`, `scan`, `end_with?`, `is_a?`, `key?`, `sysread`,
+    `each_with_object`, `tally`, …), `SecureRandom`/`Addrinfo`/
+    `Socket`/`TCP*`/`UDP*`/`UNIX*`/`IPAddr`/`Resolv`/`Zlib`/`CGI`/
+    `ERB`/`Liquid::` prefixes, JRuby Java-side API (`RubyString.`,
+    `RubyArray.`, `RubyHash.`, `ByteList.`, `ThreadContext.`, …) +
+    bare `newString`, `newFixnum`, `callMethod`, `getRuntime`.
+  - **Dart**: `package:test_descriptor` (`d.file`, `d.dir`,
+    `d.nothing`), `package:test_process` (`shouldExit`), `dart:typed_data`
+    fromList constructors, `dart:convert` (`JsonEncoder`, `Utf8Decoder`,
+    `LineSplitter`), `package:shelf` Response helpers, `package:args`
+    CLI builders (`addFlag`, `addOption`, `addSubcommand`,
+    `wasParsed`), `package:yaml` loaders, Dart SDK error types
+    (`StateError`, `UnsupportedError`, `FormatException`, …),
+    pub_semver (`Version`, `VersionConstraint`).
+- **`is_non_project_call` now splits on `->` in addition to `.` and
+  `::`** so PHP `$obj->method()` and C `struct_ptr->method()` resolve
+  their bare method name against `STDLIB_FILTER` — previously
+  `headers->set`, `response->getStatusCode` never matched. Laravel /
+  Symfony resolution climbed 88% → 91%.
+
+### Fixed
+
+- **SCIP incremental re-indexing** no longer silently degrades to zero
+  for adapters outside rust / typescript / python. `_hash_project` now
+  falls back to `_hash_generic_adapter` (walks the adapter's declared
+  extensions + hashes paths + bytes) for java / go / ruby / php /
+  dotnet / clang / dart, instead of raising `ValueError: Unknown project
+  type`. Before this fix, every second+ index produced a `.scip`-less
+  graph that looked successful in logs but had no SCIP-resolved CALLS
+  edges.
+- **SCIP Strategy 1 name match.** `ScipIndex.resolve`'s exact
+  (file, line) lookup used to fall back to the first candidate in the
+  definitions map when no name matched. Downstream, the cross-crate
+  name check in `generate.py` would reject those mismatched targets,
+  but by then Strategy 2 (fuzzy resolve by name) had already been
+  skipped. Tighten Strategy 1 to require a name match; non-matching
+  line lookups now fall through to fuzzy. Measured: pub Dart 52% →
+  71%, Redis C 79.2% → 80.4%.
+- **`changes` no longer crashes on non-UTF-8 git diff output.**
+  `GitHistoryAnalyzer._run_git` previously used `subprocess.run(text=True)`
+  which raises `UnicodeDecodeError` the moment `git diff` emits a byte
+  that isn't valid UTF-8 (observed on c-postgres — byte 0x92 — and
+  rust-coreutils — byte 0xfd, both carrying Latin-1 content in older
+  source files). All subprocess callers that capture stdout/stderr
+  (`git_history.py`, `scip/cache.py`, `scip/adapter.py`, `ast_grep.py`)
+  now decode with `encoding="utf-8", errors="replace"` so a stray
+  non-UTF-8 byte becomes `U+FFFD` instead of aborting the tool.
+  Regression: `tests/test_git_history.py::TestGitHistoryNonUtf8Output`
+  seeds a throwaway repo with 0x92 / 0xfd bytes and asserts
+  `_run_git` + `get_changes` stay clean.
+- **User-input numeric parsing is crash-safe.** The web API's
+  `?limit=foo` / `?depth=bar` inputs and the `DESCRY_SCIP_WORKERS` /
+  `DESCRY_PRIME_THREADS` / `DESCRY_SCIP_TIMEOUT` env-var overrides
+  previously called `int(raw)` directly; a non-integer value raised
+  `ValueError` and surfaced as a 500 (web) or a hard crash during
+  SCIP cache init (env var). Web handlers now go through the new
+  `_int_param(request, name, default)` helper that returns the
+  default on parse failure; env-var paths catch `ValueError`, log a
+  warning, and fall through to the auto-tuned default.
+- **Exception chains preserved on re-raise.** Three sites in
+  `git_history.py` and one in `embeddings.py` re-raised exceptions
+  without `from err` / `from None`, which hid the underlying cause in
+  tracebacks. Now `FileNotFoundError` → `GitError("git not found")` /
+  `TimeoutExpired` → `GitError("timed out")` / `FileExistsError` →
+  `TimeoutError("embeddings lock")` all use `from None` (cause
+  already captured in the message), and `_verify_git`'s internal
+  re-raise uses `from err` to preserve the inner git failure.
+- **`descry.__version__` matches `pyproject.toml`.** Since the 0.1.1
+  tag, the package version string was `"0.1.0"` in `__init__.py` but
+  `"0.1.1"` in `pyproject.toml`, so `descry health` reported the
+  wrong version. Bumped `__init__.py` and added this to the release
+  gate so a future mismatch is caught before tagging.
+- **Documented security invariants now match the code.** `CLAUDE.md`
+  said `descry-web` "allows CORS `*`"; in reality the code omits
+  `CORSMiddleware` entirely so browsers enforce same-origin by
+  default (with `TrustedHostMiddleware` defeating DNS-rebinding).
+  The subprocess-sanitization list also named only `scip-typescript`
+  as the representative SCIP indexer — now enumerates all ten.
+- **Implicit-`Optional` annotations in `query.py` made explicit.**
+  11 signatures across `flow` / `trace_flow_structured` /
+  `get_context_prompt` / `find_trait_impls` used `x: int = None`
+  (which PEP 484 prohibits); now `int | None = None`.
+- **Pure-JavaScript repos no longer drop every CALLS edge.** ast-grep
+  has separate `typescript` and `javascript` grammars; the
+  `extract_calls_typescript` / `extract_imports_typescript` helpers
+  hardcoded `-l typescript` for the subprocess, which returns no
+  matches when fed `.js` / `.jsx` / `.mjs` / `.cjs`. Caught by the
+  pre-publish corpus sweep against express (100% .js): scip-typescript
+  emitted 9,702 references but the graph had **0 CALLS edges**. New
+  `_ast_grep_lang_for(file_path)` routes to `javascript` for JS-family
+  extensions; express now resolves 58% of CALLS (graph went 1,353 →
+  6,117 edges). 0.1.x users on pure-JS repos were silently affected.
+
+### Changed
+
+- **Configuration docs now cover every parsed field.** README's
+  `[cross_lang]` TOML section (with `openapi_path`,
+  `backend_handler_patterns`, `frontend_api_patterns`, `api_prefixes`)
+  and `[timeouts] index_minutes` were parsed at runtime but undocumented;
+  added. Four `DESCRY_*` env vars (`SCIP_WORKERS`, `SCIP_TIMEOUT`,
+  `PRIME_THREADS`, `AST_GREP_MAX_FILES`) were honoured by the code but
+  missing from the environment-variables table; added.
+
+### Known limitations (surfaced by the pre-publish corpus sweep)
+
+These aren't regressions in 0.2.0 — they're scenarios the new corpus
+coverage made visible. Documenting so users know what to expect.
+
+- **Kotlin codebases need scip-java to be useful.** Descry has no
+  `.kt` / `.scala` parser baseline; Kotlin and Scala source files are
+  walked by the file walker but produce no nodes when scip-java
+  doesn't run. scip-java in turn fails on Kotlin-DSL Gradle projects
+  that use precompiled-script-plugins (observed on both `ktorio/ktor`
+  and `Kotlin/kotlinx.coroutines` — same upstream task-ordering
+  error). Practical effect: pure-Kotlin repos with that build
+  pattern will produce a near-empty graph. Mixed Java+Kotlin repos
+  index the Java side only. The `JavaAdapter` now pre-flights for
+  this scenario and skips scip-java with a clear log message
+  ("scip-java incompatibility: kotlin-dsl precompiled-script-plugins
+  in <path>") instead of a confusing 1100-byte stderr dump from the
+  failed Gradle invocation. Detection covers `buildSrc/` and any
+  `includeBuild()` participants in `settings.gradle{,.kts}`.
+- **C++ resolution ceiling without scip-clang.** scip-clang requires
+  a working `compile_commands.json` with all transitive deps
+  available (Boost, gflags, glog, fmt, etc. for `facebook/folly`).
+  When deps are missing scip-clang is skipped and the regex
+  `ClangParser` baseline reaches ~46–54% on modern template-heavy
+  C++ (folly 46%, abseil-cpp 54%). With a working compdb scip-clang
+  contributes ~40% of resolved CALLS; the rest is regex fallback.
+  Plain C codebases (redis, sqlite, postgres, curl) sit at 72–80%
+  on regex baseline alone.
+- **scip-java does not support Ant.** Maven, Gradle, sbt, and Mill
+  are supported; Ant projects (e.g. `apache/cassandra`) fall back
+  to the regex `JavaParser`, which still reaches ~86% on its own.
+- **scip-dart needs `dart pub get` first.** scip-dart aborts with
+  "Unable to locate packageConfig" when the project hasn't been
+  bootstrapped. Run `dart pub get` (or `flutter pub get` for Flutter
+  packages) before `descry index` to get type-aware Dart resolution.
+- **scip-dotnet honours `global.json` SDK pins.** When a project
+  pins an SDK not installed on the host (e.g. `PowerShell/PowerShell`
+  pins .NET 11 preview), scip-dotnet's adapter detects the
+  incompatibility and falls back to the regex `DotnetParser`. The
+  regex baseline alone reached 90% on PowerShell, so the fallback
+  is usually fine.
+- **Pinned Rust toolchains need `rust-analyzer` installed.** A
+  `rust-toolchain.toml` pin (e.g. `helix` pins `1.90.0`) means
+  rust-analyzer must be installed for that specific toolchain
+  via `rustup component add rust-analyzer --toolchain <version>`.
+  Otherwise scip-rust emits per-crate warnings and the regex
+  `RustParser` baseline carries the project (~80%).
+
+## [0.1.1] — 2026-04-17
+
+Patch release focused on making cross-language tracing actually configurable,
+plus a round of dead-code cleanup. No breaking changes.
+
+### Fixed
+
+- **Cross-language tracing is now configurable from `.descry.toml`.** The
+  `DescryConfig.openapi_path` field existed in 0.1.0 but had no TOML loader
+  and the web `/api/cross-lang` handler hardcoded `public/api/latest.json`,
+  so custom spec locations silently did nothing. Added a `[cross_lang]`
+  section with `openapi_path`, `backend_handler_patterns`,
+  `frontend_api_patterns`, and `api_prefixes` keys. Web and CLI/MCP now
+  both honour the config and pass all four through to `CrossLangTracer`.
+- `[cross_lang] openapi_path` is containment-checked against the project
+  root; a crafted `.descry.toml` cannot point the indexer at files outside
+  the configured project.
+
+### Removed
+
+Dead code with no call sites anywhere in the tree was pruned:
+
+- `DescryConfig.project_markers` (auto-detect used a module constant).
+- `DescryConfig.use_tree_sitter_ts` (scaffolding field with no consumer).
+- `descry.query.MAX_INLINE_THRESHOLD` constant.
+- `CrossLangTracer.endpoint_to_node_id()` and module-level
+  `_create_cross_lang_edges()` helper.
+- `SemanticSearcher._find_similar()` (distinct from
+  `GraphQuerier._find_similar_nodes`, which remains).
+- `descry.ast_grep.extract_imports_typescript_batch()`.
+- `ScipIndex.get_definition_location()` and `get_symbol_info()`.
+- `TypeScriptSymbolTable.file_dir` attribute.
+- `DescryService._clear_dedup_cache()` (superseded by `reset_caches()` in
+  the 0.1.0 hardening sweep).
+
+A `vulture --min-confidence 80` sweep on `src/descry/` now reports zero
+findings outside generated protobuf code.
+
+## [0.1.0] — 2026-04-16
+
+Initial public PyPI release. Descry is a polyglot codebase knowledge graph toolkit with three interfaces: CLI (`descry`), MCP server (`descry-mcp`), and local web UI (`descry-web`).
+
+### Features
+
+- **Indexer**: Parses Rust, Python, TypeScript, JavaScript, and Svelte into a cached knowledge graph of symbols (functions, classes, constants) and edges (calls, imports, defines).
+- **SCIP integration**: Optional type-aware call resolution via `rust-analyzer` and `scip-typescript`; regex fallback otherwise.
+- **Semantic search**: Optional embeddings via sentence-transformers (Jina code embeddings by default; model pinned by revision).
+- **19 MCP tools**: search, callers, callees, context, flow, path, impls, structure, flatten, cross-lang (preview), churn, evolution, changes, semantic, quick, index, status, ensure, health.
+- **Web UI**: Starlette + Alpine.js; 20+ UI panels for browsing the graph visually.
+- **Configuration**: `.descry.toml` + env-var overrides for cache dir, timeouts, embedding model, SCIP toolchain, excluded dirs.
+
+### Security
+
+- Git argument injection hardening on all user-controlled inputs (commit ranges, symbol names, file paths, pathspecs).
+- Safe embedding-cache storage (JSON sidecar + safe-mode numpy load) with atomic writes and content-addressed cache keys.
+- Default embedding model revision pinned for supply-chain integrity; `trust_remote_code` defaults to `False` for user-supplied models.
+- TOML-sourced subprocess args (scip toolchain, extra args, embedding model path) are validated.
+- Subprocess env sanitized against known credential patterns.
+- Web UI path traversal containment on `/api/source` + regular-file / size / text-file checks.
+- MCP `descry_index(path=...)` restricted to project root.
+- Graph JSON carries `schema_version`; mismatched graphs are rejected with an actionable error.
+

{descry_codegraph-0.1.1 → descry_codegraph-0.2.0}/CLAUDE.md

@@ -23,7 +23,7 @@ just test tests/test_handlers.py::test_index     # 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 (195 tests currently — 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 (497 tests currently — a drop is a regression signal).
 
 Invoke the tool while developing:
 
@@ -58,9 +58,9 @@ Packaging: `pyproject.toml` defines four console scripts — `descry`, `descry-m
 
 These are load-bearing — see `SECURITY.md` and the `## Security` section of `CHANGELOG.md`. Do not weaken without a review:
 
-- **Subprocess env sanitization.** Every subprocess call (git, rust-analyzer, scip-typescript, ast-grep, `descry-generate`) must pass `env=safe_env()` from `src/descry/_env.py`, which filters credential-shaped env vars by regex.
+- **Subprocess env sanitization.** Every subprocess call — git, every SCIP indexer (`rust-analyzer`, `scip-typescript`, `scip-python`, `scip-java`, `scip-go`, `scip-ruby`, `scip-php`, `scip-dotnet`, `scip-clang`, `scip-dart`), ast-grep, and the `descry-generate` child process — must pass `env=safe_env()` from `src/descry/_env.py`, which filters credential-shaped env vars by regex.
 - **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 allows CORS `*`. `/api/source` enforces project-root containment, rejects non-regular files / non-text content / >10 MiB, and uses `O_NOFOLLOW` on the final open. `/api/index` (and `/api/index/stream`) take no path parameter (always indexes the configured root). Don't add a `--host 0.0.0.0` flag or 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` or trigger `/api/index`. `TrustedHostMiddleware` 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 / non-text content / >10 MiB, and uses `O_NOFOLLOW` on the final open. `/api/index` (and `/api/index/stream`) take no path parameter (always indexes the configured root). 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.
 - **Embedding cache** uses numpy safe-mode load + JSON sidecar + atomic writes + content-addressed keys. Default embedding model revision is pinned for supply-chain integrity; `trust_remote_code` defaults to `False` for user-supplied models.
 

{descry_codegraph-0.1.1 → descry_codegraph-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: descry-codegraph
-Version: 0.1.1
+Version: 0.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
@@ -67,7 +67,7 @@ Description-Content-Type: text/markdown
 
 Polyglot codebase knowledge graph with call-graph analysis, semantic search, and SCIP integration. Built for AI coding agents (MCP), with CLI and Web UI interfaces.
 
-Descry indexes your codebase into a knowledge graph of symbols (functions, classes, constants) and their relationships (calls, imports, defines). It supports Rust, Python, TypeScript, JavaScript, Svelte, Go, Java, and more — with type-aware resolution via SCIP for Rust and TypeScript.
+Descry indexes your codebase into a knowledge graph of symbols (functions, classes, constants) and their relationships (calls, imports, defines). SCIP-backed type-aware resolution is available for Rust, TypeScript, JavaScript, Svelte, Python, Java (+ Kotlin / Scala), Go, Ruby, PHP, C# (+ VB.NET), C / C++, and Dart. The `.js` / `.jsx` / `.svelte` paths run through `scip-typescript`; pure Kotlin / Scala source needs `scip-java` (which doesn't always work on Kotlin-DSL Gradle projects — see [CHANGELOG](CHANGELOG.md#020--2026-04-20) known limitations).
 
 > ### ⚠️ Disclaimer — please read
 >
@@ -124,6 +124,7 @@ descry quick handle_request
 | **MCP Server** | `descry-mcp` | AI coding agents (Claude Code, etc.) |
 | **Web UI** | `descry-web` | Visual exploration at `http://127.0.0.1:8787` |
 | **Pi Extension** | See `pi-extension/` | Pi coding agent integration |
+| **Claude Code Skill** | See `claude-skill/` | Teaches Claude when/how to reach for descry |
 
 ## MCP Setup
 
@@ -161,7 +162,7 @@ Descry uses the standard MCP stdio transport. Any MCP-compatible host can spawn
 
 ## Tools
 
-Descry provides 18 tools, available through all interfaces:
+Descry provides 19 tools, available through all interfaces:
 
 | Tool | Description |
 |------|-------------|
@@ -187,35 +188,49 @@ Descry provides 18 tools, available through all interfaces:
 
 ## Configuration
 
-Descry works zero-config by auto-detecting your project root (looks for `.git`, `Cargo.toml`, `package.json`, `pyproject.toml`). For customization, add a `.descry.toml` to your project root:
+Descry works zero-config by auto-detecting your project root. The walker looks for any of: `.git`, `.descry.toml`, `Cargo.toml`, `package.json`, `pyproject.toml`, `setup.py`, `go.mod`, `Gemfile`, `composer.json`, `build.gradle{,.kts}`, `settings.gradle{,.kts}`, `pom.xml`, `build.sbt`, `global.json`, `pubspec.yaml`, `CMakeLists.txt`, or `compile_commands.json`.
+
+For customization, add a `.descry.toml` to your project root.
+
+> **Heads-up on list-typed fields.** Several settings below are **lists that REPLACE descry's defaults** when set, not merge. These include `[project] excluded_dirs`, `[code_files] extensions`, `[test_detection] path_patterns` / `file_suffixes`, and `[git] churn_exclusions`. Leave them out unless you have a specific reason — descry's defaults already cover a wide language matrix. If you do set them, copy the full default list (see `_DEFAULT_*` constants in `src/descry/handlers.py`) and modify from there. `[syntax.lang_map]` is the one list-shaped field that *merges* with defaults.
 
 ```toml
 [project]
-excluded_dirs = ["target", "node_modules", "dist", ".git", "__pycache__", "build", "vendor"]
-max_stale_hours = 48
+# OPTIONAL — REPLACES the 25-element default. Leave unset to keep defaults
+# (.git, .gradle, .next, .svelte-kit, .venv, node_modules, target, build, …).
+# excluded_dirs = ["target", "node_modules", "dist", "build", "vendor"]
+max_stale_hours = 24
 
 [features]
-enable_scip = true        # Type-aware resolution (requires rust-analyzer or scip-typescript)
+enable_scip = true         # Type-aware resolution (auto-detects which indexers are on PATH)
 enable_embeddings = true   # Semantic search (requires sentence-transformers)
 
 [embeddings]
 model = "jinaai/jina-code-embeddings-0.5b"
 
 [test_detection]
-path_patterns = ["/tests/", "/test/", "/__tests__/"]
-file_suffixes = ["_test.rs", ".test.ts", ".spec.ts", "_test.py"]
+# OPTIONAL — REPLACES defaults. Defaults cover Rust/Python/TS/Go/Ruby/Java/Kotlin/
+# Scala/PHP/C#/Dart/C/C++ test conventions.
+# path_patterns = ["/tests/", "/test/", "/__tests__/"]
+# file_suffixes = ["_test.rs", ".test.ts", ".spec.ts", "_test.py"]
 
 [code_files]
-extensions = [".rs", ".py", ".ts", ".tsx", ".js", ".jsx", ".svelte", ".go", ".java"]
+# OPTIONAL — REPLACES the 30-element default (.rs/.py/.ts/.tsx/.js/.jsx/.svelte/
+# .go/.java/.kt/.scala/.rb/.rake/.gemspec/.php/.cs/.vb/.c/.cc/.cpp/.cxx/.cu/.h/
+# .hh/.hpp/.hxx/.dart/.css/.scss/.html). Leave unset to keep defaults.
+# extensions = [".rs", ".py", ".ts", ".tsx", ".go", ".java"]
 
 [git]
-churn_exclusions = [".descry_cache/", "Cargo.lock", "package-lock.json"]
+# OPTIONAL — REPLACES defaults (.descry_cache/, .beads/, Cargo.lock,
+# package-lock.json, yarn.lock, pnpm-lock.yaml).
+# churn_exclusions = [".descry_cache/", "Cargo.lock", "package-lock.json"]
 timeout = 30
 
 [timeouts]
 scip_minutes = 0       # 0 = unlimited
 embedding_seconds = 60
 query_ms = 4000
+index_minutes = 30     # Timeout for `descry index` subprocess
 
 [query]
 max_depth = 3
@@ -231,8 +246,16 @@ skip_crates = []         # Crate names to skip during SCIP indexing
 toolchain = "1.92.0"     # Pin rust-analyzer version via rustup
 
 [syntax.lang_map]
+# MERGES with defaults (additive). Maps file extensions to syntax-highlight names.
 ".svelte" = "svelte"
 ".proto" = "protobuf"
+
+[cross_lang]
+# Frontend -> backend handler tracing via OpenAPI spec.
+openapi_path = "public/api/openapi.json"   # must resolve inside project_root
+backend_handler_patterns = ["backend/src/routes"]  # path substrings; empty = no filter
+frontend_api_patterns = ["webapp/src/lib/api"]     # same
+api_prefixes = ["/api/v1", "/api/v2", "/api"]      # stripped when matching spec paths
 ```
 
 ### Environment Variables
@@ -243,6 +266,10 @@ toolchain = "1.92.0"     # Pin rust-analyzer version via rustup
 | `DESCRY_CACHE_DIR` | `.descry_cache/` | Override cache directory location |
 | `DESCRY_NO_SCIP` | `false` | Disable SCIP indexing |
 | `DESCRY_NO_EMBEDDINGS` | `false` | Disable semantic search |
+| `DESCRY_SCIP_WORKERS` | auto | Max parallel SCIP indexer workers (overrides the memory-based default) |
+| `DESCRY_SCIP_TIMEOUT` | auto | Per-project SCIP indexer timeout in minutes (`0` / `none` disables) |
+| `DESCRY_PRIME_THREADS` | auto | Threads used when pre-warming `rust-analyzer` cache |
+| `DESCRY_AST_GREP_MAX_FILES` | `5000` | Skip ast-grep per-file invocation on repos larger than this many target-language files |
 
 Configuration precedence: defaults < `.descry.toml` < environment variables.
 
@@ -250,15 +277,20 @@ Configuration precedence: defaults < `.descry.toml` < environment variables.
 
 | Language | Parsing | SCIP (Type-Aware) | Requirements |
 |----------|---------|-------------------|--------------|
-| Rust | Regex + AST | Yes | `rust-analyzer` via rustup |
-| TypeScript | Regex (+ Tree-sitter opt-in) | Yes | `scip-typescript` via npm; `descry-codegraph[ast]` for tree-sitter |
-| Python | Regex + AST | Yes | `scip-python` via npm |
-| JavaScript | Regex (+ Tree-sitter opt-in) | — | `descry-codegraph[ast]` for tree-sitter |
-| Svelte | Regex | — | — |
-| Go | Regex | — | — |
-| Java | Regex | — | — |
-
-The tree-sitter TS/TSX/JS parser is currently extractor-only (symbol discovery) and ships behind the `ast` extra + `[features] use_tree_sitter_ts = true` in `.descry.toml`. It runs alongside the regex parser and is a stepping stone toward full AST-driven extraction in a future release.
+| Rust | Regex (+ ast-grep when `sg` on PATH) | Yes | `rust-analyzer` via rustup |
+| TypeScript | Regex (+ ast-grep when `sg` on PATH) | Yes | `scip-typescript` via npm |
+| JavaScript | Regex (+ ast-grep when `sg` on PATH) | Yes (via `scip-typescript`) | `scip-typescript` via npm |
+| Svelte | Regex | Yes (via `scip-typescript`) | `scip-typescript` via npm |
+| Python | Regex + Python `ast` module | Yes | `scip-python` via npm |
+| Java / Kotlin / Scala | Regex (Java only — `.kt` / `.scala` produce no nodes when scip-java doesn't run) | Yes | `scip-java` (`coursier install scip-java`); see [CHANGELOG](CHANGELOG.md#020--2026-04-20) for the Kotlin-DSL Gradle limitation |
+| Go | Regex | Yes | `scip-go` (`go install github.com/sourcegraph/scip-go/cmd/scip-go@latest`) |
+| Ruby | Regex | Yes | `scip-ruby` gem or direct binary |
+| PHP | Regex | Yes | `scip-php` via `composer require --dev davidrjenni/scip-php` (third-party indexer) |
+| C# / VB.NET | Regex (C# only) | Yes | `scip-dotnet` via `dotnet tool install --global scip-dotnet` |
+| C / C++ | Regex | Yes | `scip-clang` binary + `compile_commands.json` (CMake `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON`, Meson+Ninja, or `bear -- make`) |
+| Dart / Flutter | Regex | Yes | `scip-dart` via `dart pub global activate scip_dart`; requires `dart pub get` at project root |
+
+`ast-grep` is the `sg` Rust binary (install via Homebrew or `cargo install ast-grep`) — when present on `PATH`, descry uses it for higher-fidelity call extraction in Rust, TypeScript, and JavaScript files. It's auto-disabled on TS/JS corpora over `DESCRY_AST_GREP_MAX_FILES` (default 5,000) where per-file subprocess overhead would dominate. The `descry-codegraph[ast]` Python extra installs `tree-sitter*` packages that are scaffolding for a future AST-driven parser at `src/descry/tree_sitter_parser.py` — currently not wired into the active pipeline.
 
 SCIP provides precise call-graph resolution (resolving which specific function is called through traits, generics, etc.). Without SCIP, Descry falls back to regex-based name matching which handles most cases but may produce false positives on overloaded names.
 
@@ -315,17 +347,19 @@ 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` checks graph age against `max_stale_hours` and regenerates if needed. The MCP server pre-warms the graph on startup.
+4. **Freshness** — `ensure` regenerates the graph when its age exceeds the `--max-age-hours` flag (CLI) / `max_age_hours` argument (MCP), defaulting to 24 hours. The `[project] max_stale_hours` config drives the "STALE" badge in `descry status` output but does not by itself trigger regeneration. The MCP server pre-warms the graph on startup.
 
 ## Design Notes
 
-### Web UI is local-only (CORS + auth)
+### Web UI is local-only — same-origin + DNS-rebind defenses
 
-`descry-web` is designed as a single-user local development tool. It binds to `127.0.0.1` by default, allows cross-origin requests (`allow_origins=["*"]`), and does not require authentication. This is deliberate:
+`descry-web` is designed as a single-user local development tool. It binds to `127.0.0.1` by default, has no authentication, and **deliberately omits `CORSMiddleware`** so browsers enforce same-origin by default — a tab on `evil.com` cannot read `/api/source` or trigger `/api/index`. This is deliberate:
 
 - The UI is served by the same process that reads your repository; any authentication layer would be a shared-secret between your browser and your own terminal.
-- Path traversal and file-serving endpoints are hardened independently of CORS: `/api/source` enforces project-root containment, rejects non-regular files, caps size at 10 MiB, and refuses non-text content (with `O_NOFOLLOW` on the final open to defeat symlink swaps).
-- The reindex endpoints accept no path parameter; they always index the configured project root.
+- `TrustedHostMiddleware` rejects requests whose `Host` header isn't loopback (`127.0.0.1`, `localhost`, `::1`), defeating DNS-rebinding attacks that would otherwise bypass the 127.0.0.1 bind.
+- The `--host` flag is validated by `_loopback_host` and rejects non-loopback values with a clear error pointing at the reverse-proxy guidance.
+- Path-traversal hardening on `/api/source` is independent of any CORS posture: it enforces project-root containment, rejects non-regular files, caps size at 10 MiB, refuses non-text content, and uses `O_NOFOLLOW` on the final open to defeat symlink swaps.
+- The reindex endpoints (`/api/index`, `/api/index/stream`) accept no path parameter; they always index the configured project root.
 
 **Do not expose `descry-web` to an untrusted network.** If you need remote access, put it behind your own authenticated reverse proxy.
 
@@ -333,7 +367,7 @@ Requires [uv](https://github.com/astral-sh/uv) and [just](https://github.com/cas
 
 Descry is pre-1.0. Minor version bumps (`0.1.x` → `0.2.x`) may include breaking changes to the library API, graph schema, CLI, or MCP tool signatures. Patch releases (`0.1.0` → `0.1.1`) will not introduce breaking changes. Once we reach `1.0.0`, the project will follow [semver](https://semver.org/) strictly.
 
-The public library API in v0.1 is limited to `descry.__version__`. Submodules (`descry.handlers`, `descry.query`, etc.) are not considered stable API yet.
+The only stable public API in pre-1.0 releases is `descry.__version__`. Submodules (`descry.handlers`, `descry.query`, etc.) are not considered stable API yet — refactor freely.
 
 ## Further Reading