codingest 0.2.18__tar.gz → 0.2.20__tar.gz

{codingest-0.2.18 → codingest-0.2.20}/Cargo.lock

@@ -302,7 +302,7 @@ dependencies = [
 
 [[package]]
 name = "codingest"
-version = "0.2.18"
+version = "0.2.20"
 dependencies = [
  "aho-corasick",
  "base64 0.22.1",
@@ -338,7 +338,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-cli"
-version = "0.2.18"
+version = "0.2.20"
 dependencies = [
  "anyhow",
  "clap",
@@ -350,16 +350,18 @@ dependencies = [
 
 [[package]]
 name = "codingest-mcp"
-version = "0.2.18"
+version = "0.2.20"
 dependencies = [
  "anyhow",
  "codingest",
  "kglite-mcp-server",
+ "serde_json",
+ "tempfile",
 ]
 
 [[package]]
 name = "codingest-py"
-version = "0.2.18"
+version = "0.2.20"
 dependencies = [
  "codingest",
  "codingest-cli",
@@ -1366,9 +1368,9 @@ dependencies = [
 
 [[package]]
 name = "kglite"
-version = "0.17.3"
+version = "0.17.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c414d1f4ae2d7d0af3ce088b843fbc3622cac2c29467cc81bc2dc639006136e0"
+checksum = "ffc03d38445c638a848109cb8f9b22fca8a5e7fdbe571b686b9ae11c671fb3b7"
 dependencies = [
  "bzip2",
  "chrono",
@@ -1402,9 +1404,9 @@ dependencies = [
 
 [[package]]
 name = "kglite-mcp-server"
-version = "0.17.3"
+version = "0.17.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "764efb5d817e481d9c96302c185a71bceba6ed09a79b3c6ad2f131688c7384c9"
+checksum = "6bce52afae0ad63db082643cf33ca89476eb70c02f6c84dc8f5e360f8b4b6bac"
 dependencies = [
  "anyhow",
  "bytes",
@@ -1508,9 +1510,9 @@ dependencies = [
 
 [[package]]
 name = "mcp-methods"
-version = "0.4.8"
+version = "0.4.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bff1a460997aa714ab45ad88fc5dbfcbcaee4983e84b2512d2461a6d281c2386"
+checksum = "140792f5b2f41ef005ea26c180869d05afda7174a22d0aedec22708fadfa879f"
 dependencies = [
  "anyhow",
  "clap",

{codingest-0.2.18 → codingest-0.2.20}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/codingest", "crates/codingest-cli", "crates/codingest-mcp", "
 resolver = "2"
 
 [workspace.package]
-version = "0.2.18"
+version = "0.2.20"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT"
@@ -12,7 +12,15 @@ 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.17.3
+# kglite engine + MCP server — imported as crates.io libraries. The 0.17.4
+# floor rejects every unbound Cypher parameter before candidate selection, so
+# an empty label scan, inline map, WHERE or subquery cannot hide a missing
+# binding behind zero rows. Installing or clearing a declared schema now
+# invalidates cached diagnostics, including on the Python graph returned by
+# `codingest.build()`. The embedded MCP server gains bounded, navigable query
+# responses backed by retained complete results; the standalone codingest CLI
+# keeps complete JSON and CSV output.
+# The preceding 0.17.3
 # floor spans the 0.17.2 and 0.17.3 query releases. Nothing in codingest's
 # builder source moved for either release; the changes reach users through
 # `codingest query` and the embedded `codingest-mcp` server:
@@ -499,8 +507,8 @@ sha2 = "0.11"
 # and no disk storage. Neither 0.15.7 nor 0.15.8 changes the `kglite::api` we
 # call, graph output, property encoding, or `.kgl` serialization.
 # Keep both libraries aligned so the graph and server share one engine release.
-kglite = { version = "0.17.3", default-features = false }
-kglite-mcp-server = { version = "0.17.3", default-features = false }
+kglite = { version = "0.17.4", default-features = false }
+kglite-mcp-server = { version = "0.17.4", default-features = false }
 
 # Dependency debuginfo capped at line tables (kglite coordination, 2026-08-31,
 # after unbounded debug trees filled the build-cache disk to zero): a

{codingest-0.2.18 → codingest-0.2.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codingest
-Version: 0.2.18
+Version: 0.2.20
 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.17.3,<0.18
+Requires-Dist: kglite>=0.17.4,<0.18
 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
@@ -192,7 +192,7 @@ codingest skill install        # code-review Agent Skill
 ```
 
 The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
-commands. KGLite ≥0.17.3 is installed automatically as the query/storage
+commands. KGLite ≥0.17.4 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.
 
@@ -205,7 +205,7 @@ Python prerequisites.
 ```toml
 [dependencies]
 codingest = "0.2"
-kglite = "0.17.3"
+kglite = "0.17.4"
 ```
 
 ```rust
@@ -277,7 +277,7 @@ diagnostic.
 ## Dependency policy
 
 `kglite` and `kglite-mcp-server` use matching crates.io requirements with a
-0.17.3 minimum and a shared lockfile. This keeps the builder, persistence
+0.17.4 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.2.18 → codingest-0.2.20}/README.md

@@ -165,7 +165,7 @@ codingest skill install        # code-review Agent Skill
 ```
 
 The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
-commands. KGLite ≥0.17.3 is installed automatically as the query/storage
+commands. KGLite ≥0.17.4 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.
 
@@ -178,7 +178,7 @@ Python prerequisites.
 ```toml
 [dependencies]
 codingest = "0.2"
-kglite = "0.17.3"
+kglite = "0.17.4"
 ```
 
 ```rust
@@ -250,7 +250,7 @@ diagnostic.
 ## Dependency policy
 
 `kglite` and `kglite-mcp-server` use matching crates.io requirements with a
-0.17.3 minimum and a shared lockfile. This keeps the builder, persistence
+0.17.4 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.2.18 → codingest-0.2.20}/crates/codingest/Cargo.toml

@@ -10,7 +10,7 @@ keywords = ["knowledge-graph", "code-analysis", "tree-sitter", "cypher", "kglite
 categories = ["development-tools", "parser-implementations"]
 
 # Requires the kglite 0.15 engine API (`kglite::api::code_entities`); the
-# workspace pins the current engine floor (0.17.3).
+# workspace pins the current engine floor (0.17.4).
 
 [lib]
 name = "codingest"

{codingest-0.2.18 → codingest-0.2.20}/crates/codingest/src/builder/other_edges.rs

@@ -45,12 +45,14 @@ pub struct UsesTypeEdge {
     pub target_node_type: &'static str,
     /// Where in the function signature this type appears. Aggregates across
     /// all sites in the same function — a type used as both a parameter and
-    /// a return value yields `"both"`. Values: `"parameter"` | `"return"` |
-    /// `"both"` | `"signature"`. `"signature"` is the fallback when the
-    /// parser couldn't extract structured parameters (typically the AC
-    /// scanner found the type embedded in the signature string).
+    /// a return value yields `"both"`. Values: `"parameter"` | `"receiver"` |
+    /// `"return"` | `"both"` | `"signature"`. `"receiver"` is the implicit
+    /// input of a method, kept distinct from an explicit parameter;
+    /// `"signature"` is the fallback when the parser couldn't extract
+    /// structured parameters (typically the AC scanner found the type embedded
+    /// in the signature string).
     ///
-    /// Cypher: `WHERE r.position IN ['parameter','both']` for "consumes T",
+    /// Cypher: `WHERE r.position IN ['parameter','receiver','both']` for "consumes T",
     /// `WHERE r.position IN ['return','both']` for "produces T".
     pub position: &'static str,
 }

{codingest-0.2.18 → codingest-0.2.20}/crates/codingest/src/rev.rs

@@ -221,9 +221,28 @@ fn verify_rev(repo_root: &Path, rev: &str) -> Result<String, String> {
     Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
 }
 
+fn spawn_archive_extractor(
+    archive_stdout: impl Into<Stdio>,
+    dest: &Path,
+) -> Result<std::process::Child, String> {
+    Command::new("tar")
+        // Both bsdtar and GNU tar otherwise stop at the first end-of-archive
+        // blocks. Git can still be writing record padding at that point and
+        // receive SIGPIPE even though extraction completed successfully.
+        .arg("--ignore-zeros")
+        .arg("-x")
+        .arg("-C")
+        .arg(dest)
+        .stdin(archive_stdout)
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|e| format!("tar failed to start: {}", e))
+}
+
 /// Stream `git archive --format=tar <rev>` into `tar -x -C <dest>`. Both run
 /// concurrently over a pipe (bounded memory — the tar is never buffered
-/// whole); list args, no shell.
+/// whole); list args, no shell. The extractor reads through tar end markers to
+/// EOF so Git can finish writing record padding without receiving SIGPIPE.
 fn archive_into(repo_root: &Path, rev: &str, dest: &Path) -> Result<(), String> {
     let mut archive = Command::new("git")
         .arg("-C")
@@ -240,14 +259,7 @@ fn archive_into(repo_root: &Path, rev: &str, dest: &Path) -> Result<(), String>
         .take()
         .ok_or_else(|| "git archive produced no stdout".to_string())?;
 
-    let tar = Command::new("tar")
-        .arg("-x")
-        .arg("-C")
-        .arg(dest)
-        .stdin(Stdio::from(archive_stdout))
-        .stderr(Stdio::piped())
-        .spawn()
-        .map_err(|e| format!("tar failed to start: {}", e))?;
+    let tar = spawn_archive_extractor(Stdio::from(archive_stdout), dest)?;
 
     // tar reads the pipe as git writes; wait for the reader first, then the
     // writer, so neither blocks on a full pipe.
@@ -258,16 +270,14 @@ fn archive_into(repo_root: &Path, rev: &str, dest: &Path) -> Result<(), String>
         .wait_with_output()
         .map_err(|e| format!("git archive wait failed: {}", e))?;
 
-    if !archive_out.status.success() {
+    if !archive_out.status.success() || !tar_out.status.success() {
         return Err(format!(
-            "git archive failed: {}",
-            String::from_utf8_lossy(&archive_out.stderr).trim()
-        ));
-    }
-    if !tar_out.status.success() {
-        return Err(format!(
-            "tar extract failed: {}",
-            String::from_utf8_lossy(&tar_out.stderr).trim()
+            "archive pipeline failed: git archive status {}; stderr {:?}; \
+             tar extract status {}; stderr {:?}",
+            archive_out.status,
+            String::from_utf8_lossy(&archive_out.stderr).trim(),
+            tar_out.status,
+            String::from_utf8_lossy(&tar_out.stderr).trim(),
         ));
     }
     Ok(())
@@ -867,6 +877,110 @@ mod tests {
         assert!(error.contains("outside repository root"), "{error}");
     }
 
+    #[test]
+    fn archive_pipeline_reports_both_children_for_invalid_revision() {
+        let (repo, _) = commit_files(&[("app.py", "def compute():\n    return 1\n")]);
+        let destination = tempfile::tempdir().unwrap();
+        let error = archive_into(
+            repo.path(),
+            "revision-that-does-not-exist",
+            destination.path(),
+        )
+        .expect_err("invalid revision must fail");
+
+        assert!(error.contains("git archive status"), "{error}");
+        assert!(error.contains("tar extract status"), "{error}");
+        assert_eq!(error.matches("stderr").count(), 2, "{error}");
+        assert!(error.contains("revision-that-does-not-exist"), "{error}");
+        assert!(
+            !error.contains("git archive status exit status: 0"),
+            "{error}"
+        );
+    }
+
+    #[test]
+    fn archive_pipeline_reports_both_children_after_early_consumer_exit() {
+        let body = "x".repeat(4 * 1024 * 1024);
+        let (repo, revision) = commit_files(&[("large.bin", &body)]);
+        let missing_destination = repo.path().join("missing").join("destination");
+        let error = archive_into(repo.path(), &revision, &missing_destination)
+            .expect_err("missing extraction destination must fail");
+
+        assert!(error.contains("git archive status"), "{error}");
+        assert!(error.contains("tar extract status"), "{error}");
+        assert_eq!(error.matches("stderr").count(), 2, "{error}");
+        assert!(
+            error.contains(&missing_destination.to_string_lossy().to_string()),
+            "{error}"
+        );
+        assert!(
+            !error.contains("git archive status exit status: 0"),
+            "{error}"
+        );
+        assert!(
+            !error.contains("tar extract status exit status: 0"),
+            "{error}"
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn archive_extractor_drains_padding_after_end_marker() {
+        let expected = "def compute():\n    return 1\n";
+        let (repo, revision) = commit_files(&[("app.py", expected)]);
+        let archive_path = repo.path().join("fixture.tar");
+        let archive_file = std::fs::File::create(&archive_path).unwrap();
+        let archived = Command::new("git")
+            .arg("-C")
+            .arg(repo.path())
+            .args(["archive", "--format=tar"])
+            .arg(&revision)
+            .stdout(archive_file)
+            .stderr(Stdio::piped())
+            .output()
+            .unwrap();
+        assert!(
+            archived.status.success(),
+            "git archive fixture failed: {}",
+            String::from_utf8_lossy(&archived.stderr)
+        );
+
+        let destination = tempfile::tempdir().unwrap();
+        let mut producer = Command::new("sh")
+            .args([
+                "-c",
+                "cat \"$1\"; sleep 0.25; dd if=/dev/zero bs=1048576 count=4 2>/dev/null",
+                "padding-producer",
+            ])
+            .arg(&archive_path)
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped())
+            .spawn()
+            .unwrap();
+        let producer_stdout = producer.stdout.take().unwrap();
+        let extractor = spawn_archive_extractor(Stdio::from(producer_stdout), destination.path())
+            .expect("spawn archive extractor");
+        let extracted = extractor.wait_with_output().unwrap();
+        let produced = producer.wait_with_output().unwrap();
+
+        assert!(
+            extracted.status.success(),
+            "tar status {}; stderr {:?}",
+            extracted.status,
+            String::from_utf8_lossy(&extracted.stderr).trim()
+        );
+        assert!(
+            produced.status.success(),
+            "producer status {}; stderr {:?}",
+            produced.status,
+            String::from_utf8_lossy(&produced.stderr).trim()
+        );
+        assert_eq!(
+            std::fs::read_to_string(destination.path().join("app.py")).unwrap(),
+            expected
+        );
+    }
+
     fn build(dir: &Path, revs: &[String]) -> Arc<DirGraph> {
         build_code_tree_revs(dir, revs, Some(dir), false, false, None, None, false)
             .expect("build_code_tree_revs")

{codingest-0.2.18 → codingest-0.2.20}/crates/codingest-cli/Cargo.toml

@@ -14,7 +14,7 @@ name = "codingest"
 path = "src/main.rs"
 
 [dependencies]
-codingest = { version = "0.2.18", path = "../codingest" }
+codingest = { version = "0.2.20", path = "../codingest" }
 kglite = { workspace = true }
 anyhow = "1.0.104"
 clap = { version = "4.6.4", features = ["derive"] }

codingest-0.2.20/crates/codingest-cli/skills/codingest-code-review/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: codingest-code-review
+description: Use when reviewing a code change or answering structural questions about a codebase, including definitions, callers, dependencies, routes, affected tests, and history across git revisions. Builds a local Cypher-queryable code graph, uses it alongside the diff and literal search, and verifies every finding against exact source lines.
+---
+
+# Codingest code review
+
+Use Codingest for structural evidence during review. The graph complements the
+git diff, source reading, and literal-text search; it does not replace them.
+
+## Review workflow
+
+> **Prerequisites:** the `codingest` CLI must be on PATH. `pip install
+> codingest` also provides the builder-aware `codingest-mcp` server and a
+> compatible graph engine. Rust-only environments can alternatively use Cargo.
+> Examples that invoke the external `kglite` CLI require a compatible
+> `kglite>=0.17.4,<0.18`; verify `kglite --version` before using its
+> agent-response features.
+
+Inspect the diff and repository guidance first. Identify changed symbols and
+the base/head revisions, then build or refresh the graph without executing
+repository code:
+
+```bash
+codingest build . --output .kglite/code-review.kgl --format json
+```
+
+For a committed comparison, use one graph spanning both revisions:
+
+```bash
+codingest build . --revs '<base>' '<head>' \
+  --output .kglite/code-review.kgl --format json
+```
+
+Before reusing an artifact, check freshness:
+
+```bash
+codingest status --output .kglite/code-review.kgl --format json
+```
+
+## Work from the question
+
+Use this loop only as far as the question requires. It has no required map set
+or fixed query count.
+
+1. **Establish target and coverage.** Record the exact repository, revision,
+   symbol, path, or subsystem in scope. For a completeness or absence claim,
+   identify the relevant groups before retrieving their rows and record every
+   query, executor, or presentation boundary.
+2. **Retrieve a relevant relation.** Ask the smallest structural question that
+   can change the answer: callers, callees, implementers, imports, dependencies,
+   routes, tests, or revision identity.
+3. **Inspect selected source.** Open the implicated definitions and call sites
+   at exact lines. Graph edges identify candidates; source and executed tests
+   establish behavior.
+4. **Retain an evidence map.** Keep each working claim with its graph revision,
+   exact query or reference, concrete example or input state, what an assertion
+   actually guarantees, and any unresolved question. These fields can be a
+   compact note rather than separate documents.
+5. **Resolve consequential uncertainty.** Expand only when a contradiction,
+   missing precondition, or correctness risk could change the answer. Stop when
+   the requested conclusions have direct support.
+
+Choose the narrowest route for the uncertainty in front of you; these are
+alternatives, not a compulsory sequence. Reuse tool signatures already known
+in the current session. If a needed tool is not visible, discover that tool
+rather than loading a broad catalog.
+
+- **Known symbol or location:** read it directly. With MCP, use
+  `read_code_source` for a qualified name or `read_source` for a path, applying
+  `start_line`, `end_line`, and `max_chars` when a full body or file is not
+  needed.
+- **Exact structural question:** use `cypher_query`, or `kglite query` when the
+  compatible external CLI is installed. Reuse a schema already observed for
+  the same unchanged graph. Otherwise inspect only the needed node or
+  connection shape with `graph_overview` or `kglite describe`; do not retrieve
+  the whole schema by habit.
+- **Broad explanation or unfamiliar subsystem:** use bounded `explore`, starting
+  with a short topic, a few `max_entities`, shallow `max_depth`, and
+  `include_source: false` unless bodies are needed. Narrow to selected symbols
+  before reading source.
+- **Literal text:** use grep/ripgrep for error strings, comments, and config
+  keys, then open only the relevant matches.
+
+Every additional read should resolve a concrete uncertainty needed for the
+answer. Project only useful Cypher properties, return a few relevant candidates,
+and exclude unrelated fixtures, generated code, vendors, or examples when the
+question does not cover them. Reuse evidence already seen unless its source or
+active graph changed.
+
+Treat response presentation separately from query coverage. When an MCP
+response says the completed result was retained, follow its advertised action
+to expand the needed value or page within the authorized read-only
+investigation; this does not require separate human approval. Expansion cannot
+recover rows excluded by a Cypher `LIMIT`, an executor row limit, or tool-level
+omission. Broaden or regroup the query when those boundaries matter. Narrow a
+source range when only a source read was clipped. See
+[mcp-upgrade.md](references/mcp-upgrade.md) for the expansion procedure.
+
+Macro-generated structure may not exist as source-level graph nodes, and
+heuristic relationships are candidates rather than runtime proof. Inspect the
+source or an executed test before turning either limitation into a behavioral
+claim.
+
+## Verify the answer
+
+Before reporting a finding or a consequential conclusion, use focused reads to
+check:
+
+- each required precondition holds at the reviewed revision;
+- the stated input, state, or sequence reaches the claimed behavior;
+- a returned value or error observed below the claimed API boundary is traced
+  through catches, fallbacks, retries, and active options to that boundary;
+- one observed path is used as evidence for that case, not as a universal
+  outcome;
+- each cited assertion runs on that input and guarantees what the answer says;
+- every file and line reference still points to the supporting code; and
+- completeness, absence, ownership, and reachability claims are limited to the
+  coverage actually established.
+
+Label source-composed examples that were not executed. Leave unresolved
+questions explicit rather than converting them into findings.
+
+See [queries.md](references/queries.md) for query patterns,
+[public-repositories.md](references/public-repositories.md) for safe public-repo
+review, and [mcp-upgrade.md](references/mcp-upgrade.md) for the persistent MCP
+workflow.
+
+## What counts as a finding
+
+The workflow above verifies a finding against exact source lines. This is the
+prior question: what is eligible to be a finding at all.
+
+- **A finding names a concrete failure**: the input, state, or sequence, and the
+  wrong outcome it produces. A wrong result, a crash, data loss or corruption, a
+  broken contract with a caller or a persisted format, a security hole, a
+  *measured* performance regression, a check that cannot fail, or a claim the
+  code contradicts. **"No findings" is a valid review**, and a good one.
+- **Design, structure, naming, "consider using X", and "this won't scale" are
+  not findings** — they are mis-staged. Their venue is planning, where "I would
+  have designed this differently" is invited and settled before code exists.
+  After a plan is approved, review measures the implementation against that plan
+  and against correctness, never against a design the reviewer would have
+  preferred. A design opinion formed while reading a diff is input to the *next*
+  plan.
+- **A finding that cannot state its failure case is removed, not downgraded.**
+  Severity labels are how a preference gets laundered into a report: "Minor:
+  consider extracting this" is a preference wearing a label.
+- **One narrow exception**: citing a rule the project declared *before* the diff
+  existed — a documented ceiling, a boundary rule, a checklist — naming both the
+  rule and the violating line. That is enforcement, not taste.
+- **A review tool's effort or confidence level is orthogonal.** A higher level
+  buys more *speculative bugs*; it never buys permission to report preferences.
+- **A graph edge showing coupling is a fact, not a defect.** Structural evidence
+  answers "what would this change reach"; it does not by itself establish that
+  anything is wrong.
+
+## Honesty rules
+
+- Never invent labels, properties, connection types, response-control fields,
+  expansion-tool names, or retained-result IDs. Discover unfamiliar shapes and
+  controls; reuse them only while the graph and session remain unchanged.
+- Treat unresolved or missing graph edges as absence of evidence, not proof.
+- Quote paths and revisions passed through the shell.
+- Never build, import, or execute code from a repository merely to review it.
+- Use grep/ripgrep for exact tokens and the graph for relationships and impact.

codingest-0.2.20/crates/codingest-cli/skills/codingest-code-review/references/mcp-upgrade.md

@@ -0,0 +1,88 @@
+# When to use the MCP server
+
+The CLI skill is the low-friction path: no agent configuration, one process per
+command, and a review artifact that can be rebuilt explicitly.
+
+Upgrade to `codingest-mcp` when the work benefits from:
+
+- a graph kept warm across many queries;
+- watch mode and automatic refresh after file changes;
+- typed tool input/output schemas rather than shell quoting;
+- switching among several repository roots;
+- cached public-repository lifecycle and GitHub/source tools; or
+- long collaborative sessions where process startup becomes noticeable.
+
+The local-code-review MCP workspace covers a changing checkout. The
+open-source workspace covers cached public repositories and adds constrained
+source and GitHub tooling. Codingest builds the code graph; both workflows use
+KGLite's graph engine, query language, and read-tool surface.
+
+## Expand retained MCP evidence
+
+A bounded presentation is a view of a completed retained result. It does not
+change query semantics and expansion does not rerun the original tool. A
+Cypher `LIMIT`, an executor row limit, or a tool-level omission is different:
+excluded rows require another reviewed query.
+
+Use the response itself as the protocol contract:
+
+1. Discover the query tool's response-control property and the expansion tool
+   through the current session's tool listing. Names may be changed to avoid a
+   collision, so do not assume `_response` or `expand_response`.
+2. When the result is bounded, copy its complete advertised
+   `next.selected_value` action. Keep the action's `name` and
+   `arguments.result_id` unchanged.
+3. Choose a target actually advertised by the response. Apply its patch by
+   copying `json_pointer`, `offset`, and `response` to the action arguments
+   named `path`, `offset`, and `response`. Do not infer paths or semantic groups
+   that are absent from the returned navigation data.
+4. Dispatch the patched action and use the returned value as evidence from the
+   original completed result. Follow an advertised page action when more of the
+   same selected value is required.
+
+Within an already authorized read-only investigation, selecting an advertised
+page, requesting a larger per-call budget, or requesting an advertised full
+response needs no additional human approval. Copy the discovered control field
+and supported shape into that individual call. Do not turn expansion into a
+replay of the original query, especially when that tool may mutate state.
+
+Retained MCP results are short-lived, held in memory, and scoped to the current
+MCP session. Honor the retention and eviction facts in the response. If a
+handle is unavailable, rerun only a read that remains authorized and whose
+preconditions are still current.
+
+## External CLI agent output is optional
+
+The examples below require an external `kglite` CLI satisfying
+`>=0.17.4,<0.18`:
+
+```console
+kglite --version
+```
+
+The following source-composed example is exercised against a generated graph by
+the packaged-consumer test:
+
+<!-- example: kglite-agent-query -->
+```console
+kglite query <graph> "RETURN 'agent-evidence' AS evidence" --format agent
+```
+
+Agent output advertises executable expansion commands. Copy the returned
+command and its result ID; do not construct either. KGLite's CLI retention uses
+a private disk cache, so expansion can run in a later process. This lifecycle
+is separate from the MCP server's in-memory, session-scoped retention.
+
+If the compatible external CLI is unavailable, report the agent example as
+untested. Codingest's own query command remains the portable complete-output
+path and does not require response retention:
+
+```console
+codingest query "MATCH (n:Evidence) RETURN n.id ORDER BY n.id" \
+  --graph app.kgl --format json
+codingest query "MATCH (n:Evidence) RETURN n.id ORDER BY n.id" \
+  --graph app.kgl --format csv
+```
+
+Codingest JSON and CSV contain every row produced by the query and executor.
+They do not make a literal `LIMIT` or another execution boundary broader.