codingest 0.1.3__tar.gz → 0.1.5__tar.gz

{codingest-0.1.3 → codingest-0.1.5}/Cargo.lock

@@ -313,7 +313,7 @@ dependencies = [
 
 [[package]]
 name = "codingest"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "aho-corasick",
  "base64",
@@ -345,7 +345,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-cli"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "anyhow",
  "clap",
@@ -357,7 +357,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-mcp"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "anyhow",
  "codingest",
@@ -366,7 +366,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-py"
-version = "0.1.3"
+version = "0.1.5"
 dependencies = [
  "codingest",
  "codingest-cli",
@@ -1393,9 +1393,9 @@ dependencies = [
 
 [[package]]
 name = "kglite"
-version = "0.14.5"
+version = "0.15.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e03ddfab585aa45e1f8149d78477b677fd253b9c9b0a8d04bdcd3829c50c8caf"
+checksum = "4664fc457e5dd762f5775977f06eb5377634556fffae45e4a86e2eb1e1eb0bfb"
 dependencies = [
  "bzip2",
  "chrono",
@@ -1428,9 +1428,9 @@ dependencies = [
 
 [[package]]
 name = "kglite-mcp-server"
-version = "0.14.5"
+version = "0.15.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "67bcf469c57b9c6bdc51493ec362a90c98c085f79a0de75c203dc42e3612b6ea"
+checksum = "e5e5d2207a45eb77c90e60a772bc8cc60ceac3d7c6f3ad2b948e8079355e1df4"
 dependencies = [
  "anyhow",
  "bytes",
@@ -1532,9 +1532,9 @@ dependencies = [
 
 [[package]]
 name = "mcp-methods"
-version = "0.4.1"
+version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ccd3c31a95d7775d6d930a174aeffdc416c2ad6ffce0eee1cad262a007340175"
+checksum = "caa2079c12e642cd4b9a20543c85305eb5ffee04b1d565feab47b084db167a99"
 dependencies = [
  "anyhow",
  "clap",

codingest-0.1.5/Cargo.toml

@@ -0,0 +1,42 @@
+[workspace]
+members = ["crates/codingest", "crates/codingest-cli", "crates/codingest-mcp", "crates/codingest-py"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.5"
+edition = "2021"
+rust-version = "1.88"
+license = "MIT"
+repository = "https://github.com/kkollsga/codingest"
+
+[workspace.dependencies]
+base64 = "0.22"
+sha2 = "0.11"
+# kglite engine + MCP server — imported as crates.io libraries. The 0.15.5
+# floor adds the two workspace controls codingest asked upstream for:
+# `workspace.sandbox_root`, a real containment boundary that confines
+# `set_root_dir` to a subtree instead of trusting the caller's path, and
+# `workspace.adopt_client_roots`. Both land on top of the generic
+# workspace-graph hooks, tri-state `durable` levels, typed
+# constraint/conflict exceptions carrying a stable `.code`, and the
+# deterministic Postcard persistence stack inherited from 0.14.5/0.15.0-0.15.3.
+# 0.15.4 is deliberately skipped: it was WAL/durability and mapped-graph work
+# we consume none of — codingest uses no `durable=` level, no `MappedGraph`,
+# and no disk storage. Neither patch changes `kglite::api`, graph output,
+# property encoding, or `.kgl` serialization.
+# Keep both libraries aligned so the graph and server share one engine release.
+kglite = { version = "0.15.5", default-features = false }
+kglite-mcp-server = { version = "0.15.5", default-features = false }
+
+# Mirror KGLite's release codegen so the standalone builder has
+# performance parity with the in-tree component (see KGLite
+# workspace Cargo.toml).
+[profile.release]
+lto = "thin"
+codegen-units = 1
+strip = "symbols"
+
+[profile.profiling]
+inherits = "release"
+debug = "line-tables-only"
+strip = "none"

{codingest-0.1.3 → codingest-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codingest
-Version: 0.1.3
+Version: 0.1.5
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
-Requires-Dist: kglite>=0.14.5,<0.15
+Requires-Dist: kglite>=0.15.5,<0.16
 License-File: LICENSE
 Summary: Build fast, queryable code graphs for AI agents, MCP code review, and local or GitHub repository analysis.
 Keywords: ai-agents,mcp,code-review,knowledge-graph,code-analysis,github,tree-sitter,cypher
@@ -136,9 +136,16 @@ The bundled terminal command offers the same workflow:
 ```bash
 codingest build /path/to/repo
 codingest status --output /path/to/repo/.kglite/code-review.kgl
+codingest query -g /path/to/repo/.kglite/code-review.kgl \
+  "MATCH (f:Function)-[:CALLS]->(g:Function) RETURN f.name, g.name LIMIT 20"
 kglite describe /path/to/repo/.kglite/code-review.kgl --connections
 ```
 
+`codingest query` prints unbounded TSV to stdout (use `--format csv|json`, or
+Cypher `LIMIT` to bound rows), warns on stderr when the graph has gone stale,
+and with `--require-fresh` refuses a stale graph with exit code 3 — see
+[docs/cli.md](docs/cli.md).
+
 ## Analyse an open-source repository
 
 ```python
@@ -180,7 +187,7 @@ codingest skill install        # code-review Agent Skill
 ```
 
 The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
-commands. KGLite ≥0.14.5 is installed automatically as the query/storage
+commands. KGLite ≥0.15.5 is installed automatically as the query/storage
 engine; its MCP server and the transitive `mcp-methods` framework power the
 builder-aware Codingest server. Nothing else needs to be installed.
 
@@ -193,7 +200,7 @@ Python prerequisites.
 ```toml
 [dependencies]
 codingest = "0.1"
-kglite = "0.14.5"
+kglite = "0.15.5"
 ```
 
 ```rust
@@ -237,23 +244,35 @@ cargo test --workspace
 cargo test -p codingest --test parity
 ```
 
-### The golden-digest oracle
+### The golden-digest oracle (also the determinism gate)
 
 KGLite deleted its in-tree `code_tree` builder on 2026-07-16, so the old
 two-builder parity sweep is gone. The authority it enforced was **frozen** while
 the builders were still verified identical, into per-corpus SHA-256 digests
 under `crates/codingest/tests/goldens/` (committed fixtures — no network). The
-`golden_parity` test builds each corpus with only the codingest builder, digests
-a canonical exhaustive graph rendering, and compares to the frozen golden. The
-multi-rev fixture is guarded instead by `rev_self_consistency`. Regenerate
-goldens only for deliberate builder-behavior changes:
+`golden_parity` test builds each corpus **three times** with only the codingest
+builder, digests a canonical exhaustive graph rendering, and requires every
+build to match every other build *and* the frozen golden. Repeating the build is
+what makes this the determinism gate: hash iteration order is randomized per
+`HashMap`, so an order-dependent builder fails it (the
+`tests/corpus/dup_minified_assets` fixture reproduces the original DEFINES-edge
+nondeterminism bug). Disagreement between builds is reported as NONDETERMINISM;
+agreement between builds but not with the golden is reported as a behaviour
+change. The multi-rev fixture is guarded instead by `rev_self_consistency`.
+Regenerate goldens only for deliberate builder-behavior changes:
 `cargo test -p codingest --test parity -- --ignored capture_goldens` (details in
 `crates/codingest/tests/goldens/README.md`).
 
+Everything the gate needs is committed to this repository, so it is hermetic and
+runs in CI. It replaced a local-only `make` step that asserted an exact edge
+count against a *sibling* checkout — a verdict this project did not control.
+`make determinism-soak REPO=…` keeps the large-repo reproducer available as a
+diagnostic.
+
 ## Dependency policy
 
 `kglite` and `kglite-mcp-server` use matching crates.io requirements with a
-0.14.5 minimum and a shared lockfile. This keeps the builder, persistence
+0.15.5 minimum and a shared lockfile. This keeps the builder, persistence
 handoff, and embedded MCP server on one compatible engine patch line.
 
 ## Parity with the (now-removed) in-tree component

{codingest-0.1.3 → codingest-0.1.5}/README.md

@@ -109,9 +109,16 @@ The bundled terminal command offers the same workflow:
 ```bash
 codingest build /path/to/repo
 codingest status --output /path/to/repo/.kglite/code-review.kgl
+codingest query -g /path/to/repo/.kglite/code-review.kgl \
+  "MATCH (f:Function)-[:CALLS]->(g:Function) RETURN f.name, g.name LIMIT 20"
 kglite describe /path/to/repo/.kglite/code-review.kgl --connections
 ```
 
+`codingest query` prints unbounded TSV to stdout (use `--format csv|json`, or
+Cypher `LIMIT` to bound rows), warns on stderr when the graph has gone stale,
+and with `--require-fresh` refuses a stale graph with exit code 3 — see
+[docs/cli.md](docs/cli.md).
+
 ## Analyse an open-source repository
 
 ```python
@@ -153,7 +160,7 @@ codingest skill install        # code-review Agent Skill
 ```
 
 The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
-commands. KGLite ≥0.14.5 is installed automatically as the query/storage
+commands. KGLite ≥0.15.5 is installed automatically as the query/storage
 engine; its MCP server and the transitive `mcp-methods` framework power the
 builder-aware Codingest server. Nothing else needs to be installed.
 
@@ -166,7 +173,7 @@ Python prerequisites.
 ```toml
 [dependencies]
 codingest = "0.1"
-kglite = "0.14.5"
+kglite = "0.15.5"
 ```
 
 ```rust
@@ -210,23 +217,35 @@ cargo test --workspace
 cargo test -p codingest --test parity
 ```
 
-### The golden-digest oracle
+### The golden-digest oracle (also the determinism gate)
 
 KGLite deleted its in-tree `code_tree` builder on 2026-07-16, so the old
 two-builder parity sweep is gone. The authority it enforced was **frozen** while
 the builders were still verified identical, into per-corpus SHA-256 digests
 under `crates/codingest/tests/goldens/` (committed fixtures — no network). The
-`golden_parity` test builds each corpus with only the codingest builder, digests
-a canonical exhaustive graph rendering, and compares to the frozen golden. The
-multi-rev fixture is guarded instead by `rev_self_consistency`. Regenerate
-goldens only for deliberate builder-behavior changes:
+`golden_parity` test builds each corpus **three times** with only the codingest
+builder, digests a canonical exhaustive graph rendering, and requires every
+build to match every other build *and* the frozen golden. Repeating the build is
+what makes this the determinism gate: hash iteration order is randomized per
+`HashMap`, so an order-dependent builder fails it (the
+`tests/corpus/dup_minified_assets` fixture reproduces the original DEFINES-edge
+nondeterminism bug). Disagreement between builds is reported as NONDETERMINISM;
+agreement between builds but not with the golden is reported as a behaviour
+change. The multi-rev fixture is guarded instead by `rev_self_consistency`.
+Regenerate goldens only for deliberate builder-behavior changes:
 `cargo test -p codingest --test parity -- --ignored capture_goldens` (details in
 `crates/codingest/tests/goldens/README.md`).
 
+Everything the gate needs is committed to this repository, so it is hermetic and
+runs in CI. It replaced a local-only `make` step that asserted an exact edge
+count against a *sibling* checkout — a verdict this project did not control.
+`make determinism-soak REPO=…` keeps the large-repo reproducer available as a
+diagnostic.
+
 ## Dependency policy
 
 `kglite` and `kglite-mcp-server` use matching crates.io requirements with a
-0.14.5 minimum and a shared lockfile. This keeps the builder, persistence
+0.15.5 minimum and a shared lockfile. This keeps the builder, persistence
 handoff, and embedded MCP server on one compatible engine patch line.
 
 ## Parity with the (now-removed) in-tree component

{codingest-0.1.3 → codingest-0.1.5}/crates/codingest/Cargo.toml

@@ -9,8 +9,8 @@ description = "codingest — standalone extraction of KGLite's code-tree compone
 keywords = ["knowledge-graph", "code-analysis", "tree-sitter", "cypher", "kglite"]
 categories = ["development-tools", "parser-implementations"]
 
-# Requires the kglite 0.14 engine API (`kglite::api::code_entities`); the
-# workspace pins the current 0.14 patch floor.
+# Requires the kglite 0.15 engine API (`kglite::api::code_entities`); the
+# workspace pins the current 0.15 patch floor (0.15.5).
 
 [lib]
 name = "codingest"

{codingest-0.1.3 → codingest-0.1.5}/crates/codingest/src/bin/codingest_bench.rs

@@ -16,16 +16,41 @@
 //! MISMATCH is a query-result determinism regression, and the A/B delta is
 //! run-to-run timing variance. The release gate fails on any MISMATCH.
 //!
+//! # The corpus is defined by the harness, not by the working directory
+//!
+//! A benchmark number is comparable to another only if both were measured on
+//! the same input. The builder walks whatever is on disk: it skips dot-dirs,
+//! `target/`, `node_modules/`, `venv/` and `__pycache__/` by name, but it has
+//! no notion of `.gitignore`, so a repository's *untracked* working state
+//! (scratch folders, local notes, generated markdown) is ingested — notably
+//! through the docs pass. Benchmarking a working tree therefore measures a
+//! corpus nobody else can reconstruct. Measured on this workspace: a clean
+//! `git worktree` of a commit scored 1,115 nodes / 3,692 edges while the
+//! working tree at that same commit scored 1,170 / 3,759 — a ~5% swing with no
+//! builder or engine involvement, which silently invalidated published numbers.
+//!
+//! So this harness defines its own corpus. By default it materializes the
+//! target's **git-tracked** files into a temporary directory and builds that:
+//! the input is then a function of the committed content plus any uncommitted
+//! edits to tracked files, reproducible on any machine at the same revision.
+//! Every run prints `corpus_sha256`, so two numbers can be *checked* for
+//! comparability rather than assumed comparable. `--include-untracked` restores
+//! the old build-the-directory-as-is behaviour for a one-off measurement of a
+//! non-git tree, and prints a NOT-REPRODUCIBLE banner.
+//!
 //! Usage:
 //!   cargo run -p codingest --bin codingest_bench --release -- <path>
 //!   cargo run -p codingest --bin codingest_bench --release -- <path> --json
+//!   cargo run -p codingest --bin codingest_bench --release -- <path> --include-untracked
 
 use kglite::api::session::{execute_read, ExecuteOptions, ExecuteOutcome};
 use kglite::api::{DirGraph, GraphRead, Value};
+use sha2::{Digest, Sha256};
 use std::collections::hash_map::DefaultHasher;
 use std::collections::HashMap;
 use std::hash::{Hash, Hasher};
-use std::path::Path;
+use std::path::{Path, PathBuf};
+use std::process::Command;
 use std::time::Instant;
 
 const WARMUP: usize = 3;
@@ -92,6 +117,153 @@ fn min(v: &[f64]) -> f64 {
     v.iter().cloned().fold(f64::INFINITY, f64::min)
 }
 
+// ── corpus selection ─────────────────────────────────────────────────────
+
+/// How the benchmark input was assembled. See the module docs.
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum CorpusMode {
+    /// Git-tracked files of the target, copied into a tempdir. Reproducible.
+    TrackedOnly,
+    /// The target directory exactly as it sits on disk. Not reproducible if
+    /// the tree carries untracked or git-ignored content.
+    WorkingTree,
+}
+
+impl CorpusMode {
+    fn as_str(self) -> &'static str {
+        match self {
+            CorpusMode::TrackedOnly => "tracked-only",
+            CorpusMode::WorkingTree => "working-tree",
+        }
+    }
+}
+
+/// The resolved benchmark input: the directory to build, plus the identity of
+/// the content in it.
+struct Corpus {
+    build_dir: PathBuf,
+    mode: CorpusMode,
+    /// Why we ended up in `mode` — printed so the choice is never silent.
+    reason: String,
+    files: usize,
+    bytes: u64,
+    /// `None` in `WorkingTree` mode: the ingested set is not enumerable
+    /// without duplicating the builder's walk, and an approximate identity is
+    /// worse than an explicit absence.
+    sha256: Option<String>,
+    /// Owns the tempdir for the process lifetime; dropping it deletes the copy.
+    _tmp: Option<tempfile::TempDir>,
+}
+
+fn hex(bytes: &[u8]) -> String {
+    bytes.iter().map(|b| format!("{b:02x}")).collect()
+}
+
+/// Git-tracked paths under `target`, relative to it. `None` when `target` is
+/// not inside a git work tree (or git is unavailable).
+fn git_tracked_files(target: &Path) -> Option<Vec<String>> {
+    let out = Command::new("git")
+        .arg("-C")
+        .arg(target)
+        .args(["ls-files", "-z", "--cached"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let stdout = String::from_utf8(out.stdout).ok()?;
+    Some(
+        stdout
+            .split('\0')
+            .filter(|s| !s.is_empty())
+            .map(str::to_string)
+            .collect(),
+    )
+}
+
+/// Copy `rels` (relative to `target`) into a fresh tempdir and return the
+/// corpus, including a content digest over the sorted `(path, sha256(bytes))`
+/// pairs. Two runs with the same digest measured the same input.
+fn materialize_tracked(target: &Path, mut rels: Vec<String>) -> std::io::Result<Corpus> {
+    rels.sort();
+    let tmp = tempfile::Builder::new()
+        .prefix("codingest-bench-corpus-")
+        .tempdir()?;
+    let root = tmp.path().to_path_buf();
+
+    let mut manifest = Sha256::new();
+    let mut files = 0usize;
+    let mut bytes = 0u64;
+
+    for rel in &rels {
+        let src = target.join(rel);
+        // `ls-files` lists index entries; a tracked-but-deleted file, or a
+        // gitlink (submodule) directory, has nothing to copy.
+        let Ok(data) = std::fs::read(&src) else {
+            continue;
+        };
+        let dst = root.join(rel);
+        if let Some(parent) = dst.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::write(&dst, &data)?;
+
+        let mut file_hash = Sha256::new();
+        file_hash.update(&data);
+        manifest.update(rel.as_bytes());
+        manifest.update(b"\0");
+        manifest.update(hex(&file_hash.finalize()).as_bytes());
+        manifest.update(b"\n");
+
+        files += 1;
+        bytes += data.len() as u64;
+    }
+
+    Ok(Corpus {
+        build_dir: root,
+        mode: CorpusMode::TrackedOnly,
+        reason: format!("git-tracked content of {}", target.display()),
+        files,
+        bytes,
+        sha256: Some(hex(&manifest.finalize())),
+        _tmp: Some(tmp),
+    })
+}
+
+/// Resolve the benchmark input for `target`.
+///
+/// Default is `TrackedOnly`; it degrades to `WorkingTree` only when the target
+/// is not in a git work tree, and says so. `--include-untracked` forces
+/// `WorkingTree`.
+fn resolve_corpus(target: &Path, include_untracked: bool) -> Corpus {
+    let working_tree = |reason: String| Corpus {
+        build_dir: target.to_path_buf(),
+        mode: CorpusMode::WorkingTree,
+        reason,
+        files: 0,
+        bytes: 0,
+        sha256: None,
+        _tmp: None,
+    };
+
+    if include_untracked {
+        return working_tree("--include-untracked requested".to_string());
+    }
+    let Some(rels) = git_tracked_files(target) else {
+        return working_tree(format!("{} is not in a git work tree", target.display()));
+    };
+    if rels.is_empty() {
+        return working_tree(format!("git tracks no files under {}", target.display()));
+    }
+    match materialize_tracked(target, rels) {
+        Ok(corpus) => corpus,
+        Err(e) => {
+            eprintln!("warning: could not materialize the tracked-only corpus: {e}");
+            working_tree(format!("tracked-only materialization failed: {e}"))
+        }
+    }
+}
+
 struct QueryResult {
     name: String,
     rows: usize,
@@ -114,12 +286,30 @@ fn main() {
     };
     let rest: Vec<String> = args.collect();
     let json = rest.iter().any(|a| a == "--json");
+    let include_untracked = rest.iter().any(|a| a == "--include-untracked");
+    // Reject unknown flags rather than silently ignoring them: a typo'd
+    // `--include-untraked` would otherwise change nothing and be reported as a
+    // measurement taken under a mode it never ran in.
+    if let Some(bad) = rest
+        .iter()
+        .find(|a| !matches!(a.as_str(), "--json" | "--include-untracked"))
+    {
+        eprintln!("unknown argument `{bad}`");
+        eprintln!("usage: codingest_bench <path> [--json] [--include-untracked]");
+        std::process::exit(2);
+    }
     let target = Path::new(&path);
 
+    // Resolve the corpus BEFORE any timing: by default this copies the
+    // target's git-tracked files into a tempdir so the measured input is
+    // reproducible from the revision alone (see the module docs).
+    let corpus = resolve_corpus(target, include_untracked);
+    let build_dir = corpus.build_dir.as_path();
+
     // Two independent codingest builds with identical arguments:
     // verbose=false, include_tests=false, save_to=None, max_loc=None, docs=true.
     let t = Instant::now();
-    let graph_a = codingest::builder::run_with_options(target, false, false, None, None, true)
+    let graph_a = codingest::builder::run_with_options(build_dir, false, false, None, None, true)
         .unwrap_or_else(|e| {
             eprintln!("build A failed: {e}");
             std::process::exit(1);
@@ -127,7 +317,7 @@ fn main() {
     let build_a_secs = t.elapsed().as_secs_f64();
 
     let t = Instant::now();
-    let graph_b = codingest::builder::run_with_options(target, false, false, None, None, true)
+    let graph_b = codingest::builder::run_with_options(build_dir, false, false, None, None, true)
         .unwrap_or_else(|e| {
             eprintln!("build B failed: {e}");
             std::process::exit(1);
@@ -291,6 +481,11 @@ fn main() {
     if json {
         let out = serde_json::json!({
             "path": path,
+            "corpus_mode": corpus.mode.as_str(),
+            "corpus_reason": corpus.reason,
+            "corpus_files": corpus.sha256.as_ref().map(|_| corpus.files),
+            "corpus_bytes": corpus.sha256.as_ref().map(|_| corpus.bytes),
+            "corpus_sha256": corpus.sha256,
             "nodes": nodes,
             "edges": edges,
             "build_a_secs": (build_a_secs * 1000.0).round() / 1000.0,
@@ -316,6 +511,22 @@ fn main() {
 
     println!("codingest Cypher benchmark — query-parity across two independent builds");
     println!("target : {path}");
+    match &corpus.sha256 {
+        Some(digest) => println!(
+            "corpus : {} — {} files, {} bytes, sha256 {}\n         ({})",
+            corpus.mode.as_str(),
+            corpus.files,
+            corpus.bytes,
+            digest,
+            corpus.reason,
+        ),
+        None => println!(
+            "corpus : {} — NOT REPRODUCIBLE: untracked and git-ignored content \
+             is ingested\n         ({})",
+            corpus.mode.as_str(),
+            corpus.reason,
+        ),
+    }
     println!("graph  : {nodes} nodes / {edges} edges  (identical across both builds)");
     println!("build  : A {build_a_secs:.3}s | B {build_b_secs:.3}s  (one-off, context)");
     println!("anchor : in-hub  = {hot_in}");