codingest 0.1.7__tar.gz → 0.2.0__tar.gz

{codingest-0.1.7 → codingest-0.2.0}/Cargo.lock

@@ -124,17 +124,6 @@ dependencies = [
  "stable_deref_trait",
 ]
 
-[[package]]
-name = "async-trait"
-version = "0.1.91"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 3.0.3",
-]
-
 [[package]]
 name = "atomic-polyfill"
 version = "1.0.3"
@@ -162,6 +151,12 @@ version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
+[[package]]
+name = "base64"
+version = "0.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
+
 [[package]]
 name = "bit-set"
 version = "0.8.0"
@@ -313,10 +308,10 @@ dependencies = [
 
 [[package]]
 name = "codingest"
-version = "0.1.7"
+version = "0.2.0"
 dependencies = [
  "aho-corasick",
- "base64",
+ "base64 0.22.1",
  "kglite",
  "rayon",
  "regex",
@@ -345,7 +340,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-cli"
-version = "0.1.7"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "clap",
@@ -357,7 +352,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-mcp"
-version = "0.1.7"
+version = "0.2.0"
 dependencies = [
  "anyhow",
  "codingest",
@@ -366,7 +361,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-py"
-version = "0.1.7"
+version = "0.2.0"
 dependencies = [
  "codingest",
  "codingest-cli",
@@ -475,9 +470,9 @@ dependencies = [
 
 [[package]]
 name = "darling"
-version = "0.23.0"
+version = "0.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
+checksum = "88490bf1b990d87eaaa7ac8aa887f629a08e7359765b4911faf63c3763347d23"
 dependencies = [
  "darling_core",
  "darling_macro",
@@ -485,26 +480,26 @@ dependencies = [
 
 [[package]]
 name = "darling_core"
-version = "0.23.0"
+version = "0.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0"
+checksum = "084e274f91c482280130e1e34e0b8d6e66776a060d7b6de7b84289ca778868c4"
 dependencies = [
  "ident_case",
  "proc-macro2",
  "quote",
  "strsim",
- "syn 2.0.119",
+ "syn 3.0.3",
 ]
 
 [[package]]
 name = "darling_macro"
-version = "0.23.0"
+version = "0.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
+checksum = "68f5792fa0d41cd2325ce0ffa64f0a340eaebd4971a3a0c5e1ffd2cc488a355e"
 dependencies = [
  "darling_core",
  "quote",
- "syn 2.0.119",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -1393,9 +1388,9 @@ dependencies = [
 
 [[package]]
 name = "kglite"
-version = "0.15.6"
+version = "0.15.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a8cf3016156af6dafbc1041fa443e94002686b6deeee0fea38f9b712c50c96f8"
+checksum = "ab3210d1c2855536403c7e86725fe673ed4fce3b950bef81832324523b5d0357"
 dependencies = [
  "bzip2",
  "chrono",
@@ -1428,9 +1423,9 @@ dependencies = [
 
 [[package]]
 name = "kglite-mcp-server"
-version = "0.15.6"
+version = "0.15.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "afaf8e38626f3991d7d7fca93df9230ec7160af894e855bc5cbe49e6c0342ab3"
+checksum = "920fed2716305e6be2663153782183c150330b643c06bf349dfaaf764fef54fe"
 dependencies = [
  "anyhow",
  "bytes",
@@ -1532,9 +1527,9 @@ dependencies = [
 
 [[package]]
 name = "mcp-methods"
-version = "0.4.3"
+version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "caa2079c12e642cd4b9a20543c85305eb5ffee04b1d565feab47b084db167a99"
+checksum = "d6d41f37fa137ea40a0cd505729e41ae1156ed119dcf8f240210579889c5ba29"
 dependencies = [
  "anyhow",
  "clap",
@@ -1945,12 +1940,11 @@ dependencies = [
 
 [[package]]
 name = "rmcp"
-version = "2.2.0"
+version = "3.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "14db48ee17a9ba61810ab1a9c1beb7d06d8136ae39ac25a1137f10d357af01af"
+checksum = "094c075f6698deef5a657cf4df6b684dff65157d255978b92b552ec22503f17a"
 dependencies = [
- "async-trait",
- "base64",
+ "base64 0.23.1",
  "chrono",
  "futures",
  "pastey",
@@ -1963,19 +1957,20 @@ dependencies = [
  "tokio",
  "tokio-util",
  "tracing",
+ "uuid",
 ]
 
 [[package]]
 name = "rmcp-macros"
-version = "2.2.0"
+version = "3.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "783d787bf21813b285f13019adc49e11af501c658890c1e519f31f937c68b7e3"
+checksum = "737d947bcfd946fae6a179a4ef6487be6dcf25c930c2393856b820f1386e52a6"
 dependencies = [
  "darling",
  "proc-macro2",
  "quote",
  "serde_json",
- "syn 2.0.119",
+ "syn 3.0.3",
 ]
 
 [[package]]
@@ -2830,7 +2825,7 @@ version = "2.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "02d1a66277ed75f640d608235660df48c8e3c19f3b4edb6a263315626cc3c01d"
 dependencies = [
- "base64",
+ "base64 0.22.1",
  "flate2",
  "log",
  "once_cell",
@@ -2866,6 +2861,17 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
+[[package]]
+name = "uuid"
+version = "1.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
+dependencies = [
+ "getrandom 0.4.3",
+ "js-sys",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "valuable"
 version = "0.1.1"

codingest-0.2.0/Cargo.toml

@@ -0,0 +1,83 @@
+[workspace]
+members = ["crates/codingest", "crates/codingest-cli", "crates/codingest-mcp", "crates/codingest-py"]
+resolver = "2"
+
+[workspace.package]
+version = "0.2.0"
+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.11
+# floor brings three things, only one of which changes what we run:
+#   * 0.15.10's `add_connections` resolves its edge-property columns once per
+#     call instead of once per cell — upstream measured 66.7ms -> 30.4ms
+#     (-54%) on 60k edges x 10 property columns. That is exactly the shape of
+#     our `control_edges_df` handoff, so it lands on the `calls` stage.
+#   * The `NodeData` -> `NodeView` API break from 0.15.9, made migratable in
+#     0.15.11. 0.15.9 deleted `NodeData`'s inherent property accessors and
+#     0.15.11 finally shipped reachable replacements: reads go through
+#     `DirGraph::node_view(idx)`, and by-index writes through the inherent
+#     `DirGraph::set_node_property(idx, "key", value)`. We migrated 21 read
+#     sites and the 2 `revs`/`rev_fp` write sites in `rev.rs` for this floor.
+#     It is a compile-time break only — the storage path behind both spellings
+#     is the one the removed methods already called, so it is NOT
+#     output-affecting.
+#     NOTE: do NOT reach the write side via `GraphWrite::set_node_property`
+#     with an `InternedKey::from_str` key. That key is never registered: it
+#     reads back within the session but breaks property enumeration and is
+#     silently dropped by `save_graph`. The inherent string-keyed calls
+#     register the name; use them.
+#   * 0.15.11's `kglite::api::embeddings` ingest API and `text_score()` query-
+#     vector arguments — codingest consumes neither.
+# Per the 0.15.9-0.15.11 changelogs, graph output, property encoding and
+# `.kgl` serialization are unchanged; the frozen parity goldens are what
+# proves it, and they must not move across this bump.
+#
+# Floor history. The 0.15.8
+# floor added recorded storage modes, `--storage` conversion on an existing
+# graph, and boot-validated Cypher recipe catalogs — none of which codingest
+# consumes — plus two changes that do reach us: workspace-graph producers now
+# receive deduplicated changed-path hints alongside full-build requests (our
+# `with_workspace_graph` producer lives in codingest-mcp), and the optimized-
+# plan cache no longer lets a write loop evict other graphs' cached read plans.
+# `OpenGraphResult` gained a `converted_from` field — a documented struct-
+# literal break we are not exposed to, as codingest constructs no
+# `OpenGraphResult`. 0.15.7 aligned the embedded server on mcp-methods 0.4.4
+# and rmcp 3.1.1; dynamic handlers use rmcp's response envelope while
+# preserving their payloads and MCP behavior. The 0.15.6 engine fixes
+# mixed-selection vector dispatch, mixed-metric exact search,
+# community-detection modularity scoring, sampled-centrality validation, and
+# persisted HNSW validation, while adding the bulk node-degree primitive and
+# graph-algorithm/vector-search performance improvements. It builds on the two
+# workspace controls codingest asked upstream for in 0.15.5:
+# `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 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.15.11", default-features = false }
+kglite-mcp-server = { version = "0.15.11", 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.7 → codingest-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codingest
-Version: 0.1.7
+Version: 0.2.0
 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.15.6,<0.16
+Requires-Dist: kglite>=0.15.11,<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
@@ -191,7 +191,7 @@ codingest skill install        # code-review Agent Skill
 ```
 
 The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
-commands. KGLite ≥0.15.6 is installed automatically as the query/storage
+commands. KGLite ≥0.15.11 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.
 
@@ -204,7 +204,7 @@ Python prerequisites.
 ```toml
 [dependencies]
 codingest = "0.1"
-kglite = "0.15.6"
+kglite = "0.15.11"
 ```
 
 ```rust
@@ -276,7 +276,7 @@ diagnostic.
 ## Dependency policy
 
 `kglite` and `kglite-mcp-server` use matching crates.io requirements with a
-0.15.6 minimum and a shared lockfile. This keeps the builder, persistence
+0.15.11 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.7 → codingest-0.2.0}/README.md

@@ -164,7 +164,7 @@ codingest skill install        # code-review Agent Skill
 ```
 
 The wheel bundles every grammar plus the `codingest` and `codingest-mcp`
-commands. KGLite ≥0.15.6 is installed automatically as the query/storage
+commands. KGLite ≥0.15.11 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.
 
@@ -177,7 +177,7 @@ Python prerequisites.
 ```toml
 [dependencies]
 codingest = "0.1"
-kglite = "0.15.6"
+kglite = "0.15.11"
 ```
 
 ```rust
@@ -249,7 +249,7 @@ diagnostic.
 ## Dependency policy
 
 `kglite` and `kglite-mcp-server` use matching crates.io requirements with a
-0.15.6 minimum and a shared lockfile. This keeps the builder, persistence
+0.15.11 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.7 → codingest-0.2.0}/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 0.15 patch floor (0.15.6).
+# workspace pins the current 0.15 patch floor (0.15.11).
 
 [lib]
 name = "codingest"
@@ -46,7 +46,7 @@ sha2 = { workspace = true }
 
 serde = { version = "1.0.229", features = ["derive"] }
 serde_json = "1.0.151"
-regex = "1"
+regex = "1.13.1"
 rayon = "1.12"
 tree-sitter = "0.26.11"
 tree-sitter-python = "0.25.0"
@@ -65,8 +65,8 @@ tree-sitter-css = "0.25.0"
 tree-sitter-dart = "0.2.0"
 toml = "1.1.3"
 walkdir = "2.5.0"
-tempfile = "3"
+tempfile = "3.27.0"
 aho-corasick = "1.1.4"
 
 [dev-dependencies]
-tempfile = "3"
+tempfile = "3.27.0"

{codingest-0.1.7 → codingest-0.2.0}/crates/codingest/src/bin/codingest_bench.rs

@@ -42,6 +42,7 @@
 //!   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
+//!   cargo run -p codingest --bin codingest_bench --release -- <path> --no-docs
 
 use kglite::api::session::{execute_read, ExecuteOptions, ExecuteOutcome};
 use kglite::api::{DirGraph, GraphRead, Value};
@@ -264,6 +265,69 @@ fn resolve_corpus(target: &Path, include_untracked: bool) -> Corpus {
     }
 }
 
+// ── command line ─────────────────────────────────────────────────────────
+
+const USAGE: &str = "usage: codingest_bench <path> [--json] [--include-untracked] [--no-docs]";
+
+/// Everything the command line can say after `<path>`, parsed once so the
+/// configuration a run was taken under is a value that can be echoed and
+/// tested rather than a scatter of `any(|a| a == …)` predicates — the shape
+/// `codingest_stats` already uses.
+#[derive(Debug, PartialEq, Eq)]
+struct Options {
+    json: bool,
+    include_untracked: bool,
+    /// DECISION (2026-08-10): this default points the OPPOSITE way to
+    /// `codingest_stats`' `--include-docs`, deliberately.
+    ///
+    /// Both binaries obey the same rule — a binary's default must reproduce
+    /// that binary's own historical rows, or old and new numbers silently stop
+    /// being comparable — and they have mirror-image histories. Every
+    /// `codingest_stats` row predating its flag was captured docs-OFF, so it
+    /// defaults off and opts in. This harness hardcoded docs-ON from the day it
+    /// was written, so every bench row ever filed (`BENCHMARKS.md`, the ad-hoc
+    /// results log) is a docs-ON measurement: it keeps docs-ON as the default
+    /// and gains an explicit `--no-docs` opt-OUT.
+    ///
+    /// The asymmetry is therefore not an inconsistency to be tidied away; it is
+    /// what keeps each binary's own series continuous. Neither default is
+    /// self-describing, which is why the effective value is echoed in the JSON
+    /// (`include_docs`) and in the human header either way — no row can be
+    /// filed without stating the mode it was taken under.
+    include_docs: bool,
+}
+
+impl Default for Options {
+    fn default() -> Self {
+        Self {
+            json: false,
+            include_untracked: false,
+            include_docs: true,
+        }
+    }
+}
+
+/// Parse the arguments after `<path>`.
+///
+/// Rejects anything unrecognised rather than silently ignoring it: a typo'd
+/// `--include-untraked` or `--nodocs` would otherwise change nothing and the
+/// run would be reported as a measurement taken under a mode it never ran in.
+/// That includes `--include-docs`: it is `codingest_stats`' spelling, it is not
+/// this binary's, and accepting it as a no-op would teach the wrong muscle
+/// memory for the one flag whose two binaries disagree.
+fn parse_options(args: &[String]) -> Result<Options, String> {
+    let mut out = Options::default();
+    for arg in args {
+        match arg.as_str() {
+            "--json" => out.json = true,
+            "--include-untracked" => out.include_untracked = true,
+            "--no-docs" => out.include_docs = false,
+            other => return Err(format!("unknown argument `{other}`")),
+        }
+    }
+    Ok(out)
+}
+
 struct QueryResult {
     name: String,
     rows: usize,
@@ -280,24 +344,20 @@ fn main() {
     let path = match args.next() {
         Some(p) => p,
         None => {
-            eprintln!("usage: code_tree_bench <path> [--json]");
+            eprintln!("{USAGE}");
             std::process::exit(2);
         }
     };
     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]");
+    let Options {
+        json,
+        include_untracked,
+        include_docs,
+    } = parse_options(&rest).unwrap_or_else(|e| {
+        eprintln!("{e}");
+        eprintln!("{USAGE}");
         std::process::exit(2);
-    }
+    });
     let target = Path::new(&path);
 
     // Resolve the corpus BEFORE any timing: by default this copies the
@@ -306,22 +366,27 @@ fn main() {
     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.
+    // Two independent codingest builds with identical arguments: verbose=false,
+    // include_tests=false, save_to=None, max_loc=None, docs=`include_docs`
+    // (ON unless `--no-docs`). Both sides MUST take the same value — the A/B
+    // comparison is a determinism check, so a configuration difference between
+    // them would surface as a MISMATCH and be read as a builder regression.
     let t = Instant::now();
-    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);
-        });
+    let graph_a =
+        codingest::builder::run_with_options(build_dir, false, false, None, None, include_docs)
+            .unwrap_or_else(|e| {
+                eprintln!("build A failed: {e}");
+                std::process::exit(1);
+            });
     let build_a_secs = t.elapsed().as_secs_f64();
 
     let t = Instant::now();
-    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);
-        });
+    let graph_b =
+        codingest::builder::run_with_options(build_dir, false, false, None, None, include_docs)
+            .unwrap_or_else(|e| {
+                eprintln!("build B failed: {e}");
+                std::process::exit(1);
+            });
     let build_b_secs = t.elapsed().as_secs_f64();
 
     let a: &DirGraph = &graph_a;
@@ -486,11 +551,15 @@ fn main() {
             "corpus_files": corpus.sha256.as_ref().map(|_| corpus.files),
             "corpus_bytes": corpus.sha256.as_ref().map(|_| corpus.bytes),
             "corpus_sha256": corpus.sha256,
-            // Fixed build configuration, echoed so a recorded row states it.
-            // Unlike codingest_stats, this harness has always built docs-ON,
-            // so the docs pass IS in its build times and node counts.
+            // Build configuration, echoed so a recorded row states it rather
+            // than inheriting it from whoever reads the row. `include_docs` is
+            // the EFFECTIVE value, not the default: docs are ON unless
+            // `--no-docs` was passed, and when they are on the docs pass is in
+            // these build times and node counts. Every historical bench row was
+            // taken docs-ON — see `Options::include_docs` for why that is this
+            // binary's default and the opposite of codingest_stats'.
             "include_tests": false,
-            "include_docs": true,
+            "include_docs": include_docs,
             "nodes": nodes,
             "edges": edges,
             "build_a_secs": (build_a_secs * 1000.0).round() / 1000.0,
@@ -532,6 +601,9 @@ fn main() {
             corpus.reason,
         ),
     }
+    // The effective build configuration, printed for the same reason the JSON
+    // echoes it: a pasted bench table must carry the mode it was taken under.
+    println!("config : include_tests=false include_docs={include_docs}");
     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}");
@@ -568,3 +640,63 @@ fn main() {
         mismatches
     );
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn opts(args: &[&str]) -> Result<Options, String> {
+        parse_options(&args.iter().map(|a| a.to_string()).collect::<Vec<_>>())
+    }
+
+    #[test]
+    fn parse_options_defaults_to_the_historical_docs_on_configuration() {
+        // Every bench row ever filed was measured docs-ON, because this harness
+        // hardcoded docs-ON before the flag existed. The default must stay that
+        // way or old and new rows silently stop being comparable. This is the
+        // MIRROR of codingest_stats' equivalent test, which asserts docs-OFF —
+        // same rule, opposite history. See `Options::include_docs`.
+        let parsed = opts(&[]).expect("empty argv parses");
+        assert_eq!(parsed, Options::default());
+        assert!(parsed.include_docs, "bench must default to docs-ON");
+        assert!(!parsed.json);
+        assert!(!parsed.include_untracked);
+    }
+
+    #[test]
+    fn parse_options_reads_every_flag() {
+        let parsed =
+            opts(&["--json", "--include-untracked", "--no-docs"]).expect("all flags parse");
+        assert!(parsed.json);
+        assert!(parsed.include_untracked);
+        assert!(!parsed.include_docs);
+    }
+
+    #[test]
+    fn no_docs_turns_docs_off_on_its_own() {
+        // The one flag whose absence is not the interesting case: assert it
+        // flips the value rather than merely parsing.
+        assert!(!opts(&["--no-docs"]).expect("parses").include_docs);
+        assert!(opts(&["--json"]).expect("parses").include_docs);
+    }
+
+    #[test]
+    fn parse_options_rejects_an_unknown_flag() {
+        // A silently-ignored typo would report a measurement taken under a mode
+        // the run never used — the reason this parser is strict at all.
+        let err = opts(&["--include-untraked"]).expect_err("typo must not parse");
+        assert!(err.contains("--include-untraked"), "unhelpful error: {err}");
+        assert!(opts(&["--nodocs"]).is_err(), "`--nodocs` must not parse");
+    }
+
+    #[test]
+    fn parse_options_rejects_the_stats_spelling_of_the_docs_flag() {
+        // `--include-docs` is codingest_stats' flag. Accepting it here as a
+        // harmless no-op (docs are already on) would teach that the two
+        // binaries share a spelling for the one flag on which they disagree —
+        // and would then silently accept `--include-docs` from a user who meant
+        // to CHANGE the mode. Rejecting it is what makes the asymmetry visible
+        // at the moment it matters.
+        assert!(opts(&["--include-docs"]).is_err());
+    }
+}