codingest 0.1.5__tar.gz → 0.1.6__tar.gz

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

@@ -313,7 +313,7 @@ dependencies = [
 
 [[package]]
 name = "codingest"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "aho-corasick",
  "base64",
@@ -345,7 +345,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-cli"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "anyhow",
  "clap",
@@ -357,7 +357,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-mcp"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "anyhow",
  "codingest",
@@ -366,7 +366,7 @@ dependencies = [
 
 [[package]]
 name = "codingest-py"
-version = "0.1.5"
+version = "0.1.6"
 dependencies = [
  "codingest",
  "codingest-cli",

{codingest-0.1.5 → codingest-0.1.6}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["crates/codingest", "crates/codingest-cli", "crates/codingest-mcp", "
 resolver = "2"
 
 [workspace.package]
-version = "0.1.5"
+version = "0.1.6"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codingest
-Version: 0.1.5
+Version: 0.1.6
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3

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

@@ -486,6 +486,11 @@ 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.
+            "include_tests": false,
+            "include_docs": true,
             "nodes": nodes,
             "edges": edges,
             "build_a_secs": (build_a_secs * 1000.0).round() / 1000.0,

{codingest-0.1.5 → codingest-0.1.6}/crates/codingest/src/bin/codingest_stats.rs

@@ -15,10 +15,21 @@
 //! Usage:
 //!   cargo run -p codingest --bin codingest_stats --release -- <path>
 //!   cargo run -p codingest --bin codingest_stats --release -- <path> --include-tests
+//!   cargo run -p codingest --bin codingest_stats --release -- <path> --include-docs
 //!   cargo run -p codingest --bin codingest_stats --release -- <path> --function-metrics
 //!   cargo run -p codingest --bin codingest_stats --release -- <path> --edge-breakdown
 //!   cargo run -p codingest --bin codingest_stats --release -- <path> --dump-calls a,b,c
 //!
+//! `--include-docs` turns the docs pass on. It is **off by default**, which is
+//! the configuration every historical row in `dev-docs/bench/results/` was
+//! measured at, so the default is the comparable one; without the flag `:Doc`,
+//! `:MENTIONS` and `:DOCUMENTS` are structurally absent and no docs-pass
+//! regression — in node counts or in build time — can be seen here. Both the
+//! tests and the docs configuration are echoed into the emitted JSON so a
+//! recorded row states the configuration it was taken under, and an unknown
+//! flag is a usage error rather than a silently-ignored typo that would report
+//! a measurement under a mode it never ran in.
+//!
 //! `--edge-breakdown` appends a per-connection-type edge histogram to the JSON
 //! object, with `IMPORTS` split by endpoint node type (`IMPORTS(File->File)`
 //! vs `IMPORTS(File->Module)`) — the two are the same connection type but
@@ -231,37 +242,76 @@ fn dump_calls(graph: &DirGraph, names: &BTreeSet<String>) -> Vec<CallRow> {
     rows
 }
 
+const USAGE: &str = "usage: codingest_stats <path> [--include-tests] [--include-docs] \
+     [--function-metrics] [--edge-breakdown] [--dump-calls name1,name2,...]";
+
+/// Everything the command line can say, 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.
+#[derive(Debug, Default, PartialEq, Eq)]
+struct Options {
+    include_tests: bool,
+    include_docs: bool,
+    function_metrics: bool,
+    edge_breakdown: bool,
+    dump_calls: Option<BTreeSet<String>>,
+}
+
+/// Parse the arguments after `<path>`. Rejects anything unrecognised: a
+/// typo'd `--include-dcos` must not report a docs-off measurement as a docs-on
+/// one, which is the same reason `codingest_bench` rejects unknown flags.
+fn parse_options(args: &[String]) -> Result<Options, String> {
+    let mut out = Options::default();
+    let mut i = 0;
+    while i < args.len() {
+        match args[i].as_str() {
+            "--include-tests" => out.include_tests = true,
+            "--include-docs" => out.include_docs = true,
+            "--function-metrics" => out.function_metrics = true,
+            "--edge-breakdown" => out.edge_breakdown = true,
+            "--dump-calls" => {
+                let list = args.get(i + 1).ok_or_else(|| {
+                    "--dump-calls requires a comma-separated name list".to_string()
+                })?;
+                out.dump_calls = Some(
+                    list.split(',')
+                        .map(str::trim)
+                        .filter(|s| !s.is_empty())
+                        .map(str::to_string)
+                        .collect(),
+                );
+                i += 1;
+            }
+            other => return Err(format!("unknown argument `{other}`")),
+        }
+        i += 1;
+    }
+    Ok(out)
+}
+
 fn main() {
     let mut args = std::env::args().skip(1);
     let path = match args.next() {
         Some(p) => p,
         None => {
-            eprintln!(
-                "usage: codingest_stats <path> [--include-tests] [--function-metrics] \
-                 [--edge-breakdown] [--dump-calls name1,name2,...]"
-            );
+            eprintln!("{USAGE}");
             std::process::exit(2);
         }
     };
-    let options: Vec<_> = args.collect();
-    let include_tests = options.iter().any(|a| a == "--include-tests");
-    let emit_function_metrics = options.iter().any(|a| a == "--function-metrics");
-    let emit_edge_breakdown = options.iter().any(|a| a == "--edge-breakdown");
-    let dump_call_names: Option<BTreeSet<String>> = options
-        .iter()
-        .position(|a| a == "--dump-calls")
-        .map(|i| match options.get(i + 1) {
-            Some(list) => list
-                .split(',')
-                .map(str::trim)
-                .filter(|s| !s.is_empty())
-                .map(str::to_string)
-                .collect(),
-            None => {
-                eprintln!("--dump-calls requires a comma-separated name list");
-                std::process::exit(2);
-            }
-        });
+    let rest: Vec<String> = args.collect();
+    let options = match parse_options(&rest) {
+        Ok(options) => options,
+        Err(e) => {
+            eprintln!("{e}");
+            eprintln!("{USAGE}");
+            std::process::exit(2);
+        }
+    };
+    let include_tests = options.include_tests;
+    let include_docs = options.include_docs;
+    let emit_function_metrics = options.function_metrics;
+    let emit_edge_breakdown = options.edge_breakdown;
+    let dump_call_names = options.dump_calls.clone();
 
     let t = Instant::now();
     let (graph, stats) = match codingest::builder::run_with_options_stats(
@@ -270,7 +320,7 @@ fn main() {
         include_tests,
         None,
         None,
-        false,
+        include_docs,
     ) {
         Ok(pair) => pair,
         Err(e) => {
@@ -306,6 +356,7 @@ fn main() {
     let mut out = serde_json::json!({
         "path": path,
         "include_tests": include_tests,
+        "include_docs": include_docs,
         "build_secs": (build_secs * 1000.0).round() / 1000.0,
         "nodes": graph.graph.node_count(),
         "edges": graph.graph.edge_count(),
@@ -343,6 +394,97 @@ mod tests {
             .expect("corpus build")
     }
 
+    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_configuration() {
+        // Every row in dev-docs/bench/results/ predating --include-docs was
+        // measured tests-off/docs-off; the default must stay that way or old
+        // and new rows silently stop being comparable.
+        let parsed = opts(&[]).expect("empty argv parses");
+        assert_eq!(parsed, Options::default());
+        assert!(!parsed.include_tests);
+        assert!(!parsed.include_docs);
+    }
+
+    #[test]
+    fn parse_options_reads_every_flag_including_docs() {
+        let parsed = opts(&[
+            "--include-tests",
+            "--include-docs",
+            "--edge-breakdown",
+            "--function-metrics",
+            "--dump-calls",
+            "run, helper ,,other",
+        ])
+        .expect("all flags parse");
+        assert!(parsed.include_tests);
+        assert!(parsed.include_docs);
+        assert!(parsed.edge_breakdown);
+        assert!(parsed.function_metrics);
+        assert_eq!(
+            parsed.dump_calls,
+            Some(BTreeSet::from([
+                "run".to_string(),
+                "helper".to_string(),
+                "other".to_string()
+            ])),
+            "the name list is split, trimmed and empties dropped"
+        );
+    }
+
+    #[test]
+    fn parse_options_rejects_an_unknown_flag_but_not_a_dump_calls_value() {
+        // A typo must be a usage error: silently ignoring it would report a
+        // measurement under a configuration the run never used.
+        assert_eq!(
+            opts(&["--include-dcos"]),
+            Err("unknown argument `--include-dcos`".to_string())
+        );
+        assert_eq!(
+            opts(&["--dump-calls"]),
+            Err("--dump-calls requires a comma-separated name list".to_string())
+        );
+        // The value that follows --dump-calls is consumed, not re-inspected as
+        // a flag — even when it looks like one.
+        let parsed = opts(&["--dump-calls", "--include-docs", "--include-tests"])
+            .expect("the value after --dump-calls is a value");
+        assert!(!parsed.include_docs, "the value was not read as a flag");
+        assert!(parsed.include_tests);
+    }
+
+    #[test]
+    fn include_docs_is_what_makes_doc_nodes_visible() {
+        // The gap this flag closes: with the docs pass off — the hard-coded
+        // behaviour before it existed — a :Doc node cannot appear in any
+        // codingest_stats number, so no docs-pass regression can fail a gate.
+        fn doc_nodes(include_docs: bool) -> usize {
+            let graph = codingest::builder::run_with_options(
+                &corpus("docs_mdx"),
+                false,
+                true,
+                None,
+                None,
+                include_docs,
+            )
+            .expect("corpus build");
+            let params = HashMap::new();
+            let options = session::ExecuteOptions::eager(&params);
+            session::execute_read(&graph, "MATCH (d:Doc) RETURN d.name", &options)
+                .expect("query docs")
+                .result
+                .rows
+                .len()
+        }
+        assert_eq!(doc_nodes(false), 0, "docs off means no Doc node exists");
+        assert!(
+            doc_nodes(true) > 0,
+            "docs on must surface the docs_mdx corpus's Doc nodes"
+        );
+    }
+
     #[test]
     fn short_name_takes_the_rightmost_separator_of_any_flavour() {
         assert_eq!(short_name("pkg.util.helper"), "helper");

{codingest-0.1.5 → codingest-0.1.6}/crates/codingest/src/builder/call_edges.rs

@@ -229,6 +229,41 @@ fn qname_starts_with_any(qname: &str, scopes: &[String]) -> bool {
     false
 }
 
+/// D3: a closure-scoped definition — one the parser tagged with a non-zero
+/// `nesting_depth` — is lexically reachable only inside its enclosing scope
+/// unless it escapes. Every bare-name index over `functions` has to keep it
+/// out of the global tier and offer it to its own file only.
+pub(super) fn is_nested_function(function: &FunctionInfo) -> bool {
+    function
+        .metadata
+        .get("nesting_depth")
+        .and_then(|value| value.as_u64())
+        .is_some_and(|depth| depth > 0)
+}
+
+/// D3 candidate assembly: the globally visible targets for a call name plus
+/// the nested (closure-scoped) targets declared in the *caller's own file*.
+///
+/// Borrows both sides untouched in the common case — `storage` is filled only
+/// when a name has candidates on both sides, which is rare.
+pub(super) fn merge_candidates<'a, 'b>(
+    global: Option<&'b Vec<&'a str>>,
+    local: Option<&'b Vec<&'a str>>,
+    storage: &'b mut Vec<&'a str>,
+) -> &'b [&'a str] {
+    match (global, local) {
+        (Some(g), None) => g.as_slice(),
+        (None, Some(l)) => l.as_slice(),
+        (None, None) => &[],
+        (Some(g), Some(l)) => {
+            storage.reserve(g.len() + l.len());
+            storage.extend_from_slice(g);
+            storage.extend_from_slice(l);
+            storage.as_slice()
+        }
+    }
+}
+
 fn infer_lang_group(qname: &str) -> &'static str {
     if qname.contains("::") {
         "rust_cpp"
@@ -262,29 +297,62 @@ pub fn build_call_edges(
 ) -> (Vec<CallEdge>, CallResolutionStats) {
     let verbose = std::env::var_os("KGLITE_CODE_TREE_VERBOSE").is_some();
     let t0 = std::time::Instant::now();
-    // Bare name → every qualified_name that matches.
+    // D3 — a closure-scoped definition (`nesting_depth > 0`) is lexically
+    // callable only inside its enclosing scope unless it escapes. It
+    // therefore never joins the global lookups; it is offered only to
+    // callers in its own file. Without this the ~2 270 nested names opencode
+    // gains would flood the bare-name index: the Phase 1 spike measured
+    // multi-candidate names going 664 → 1 562 and 293 currently-unique names
+    // turning ambiguous, which is exactly the false-positive class v0.1.5's
+    // resolution metadata was built to keep out. Escape analysis (which
+    // nested functions really do leak cross-file) is the deliberate
+    // non-goal; same-file is the conservative approximation. The predicate
+    // itself is `is_nested_function` above — `build_references_fn_edges` and
+    // `build_decorates_edges` are bare-name indexes over the same population
+    // and gate on it too.
+    let is_nested = is_nested_function;
+
+    // Bare name → every qualified_name that matches. Top-level definitions
+    // only; nested ones go to `nested_names` below, keyed by file.
     let mut name_lookup: HashMap<&str, Vec<&str>> = HashMap::new();
+    let mut nested_names: HashMap<&str, HashMap<&str, Vec<&str>>> = HashMap::new();
     for fn_info in functions {
-        name_lookup
-            .entry(fn_info.name.as_str())
-            .or_default()
-            .push(fn_info.qualified_name.as_str());
+        let target = if is_nested(fn_info) {
+            nested_names
+                .entry(fn_info.file_path.as_str())
+                .or_default()
+                .entry(fn_info.name.as_str())
+                .or_default()
+        } else {
+            name_lookup.entry(fn_info.name.as_str()).or_default()
+        };
+        target.push(fn_info.qualified_name.as_str());
     }
     // Exact qualified call text → one ordinary function or every overload in
     // that same-scope group. Parser call sites keep the source-level base ID,
     // while graph identities carry a signature discriminator.
     let mut qualified_lookup: HashMap<&str, Vec<&str>> = HashMap::new();
+    let mut nested_qualified: HashMap<&str, HashMap<&str, Vec<&str>>> = HashMap::new();
     for function in functions {
         let qualified_name = function.qualified_name.as_str();
-        qualified_lookup
-            .entry(qualified_name)
-            .or_default()
-            .push(qualified_name);
+        let mut keys: Vec<&str> = vec![qualified_name];
         if let Some(base) = super::overload_base_qualified_name(qualified_name) {
-            qualified_lookup
-                .entry(base)
-                .or_default()
-                .push(qualified_name);
+            keys.push(base);
+        }
+        for key in keys {
+            if is_nested(function) {
+                nested_qualified
+                    .entry(function.file_path.as_str())
+                    .or_default()
+                    .entry(key)
+                    .or_default()
+                    .push(qualified_name);
+            } else {
+                qualified_lookup
+                    .entry(key)
+                    .or_default()
+                    .push(qualified_name);
+            }
         }
     }
 
@@ -348,6 +416,10 @@ pub fn build_call_edges(
             let caller_prefix = qname_to_prefix.get(caller_qn).copied();
             let caller_owner = qname_to_owner.get(caller_qn).copied();
             let caller_file = fn_info.file_path.as_str();
+            // D3: the nested definitions this caller may see — its own file's,
+            // and nothing else's.
+            let local_names = nested_names.get(caller_file);
+            let local_qualified = nested_qualified.get(caller_file);
 
             let mut out: Vec<(&str, &str, u32, Resolution, usize)> = Vec::new();
             let mut counts = Counts::default();
@@ -359,16 +431,22 @@ pub fn build_call_edges(
                     counts.excluded += 1;
                     continue;
                 }
-                if let Some(targets) = qualified_lookup.get(called_name.as_str()) {
+                let mut exact_storage: Vec<&str> = Vec::new();
+                let exact: &[&str] = merge_candidates(
+                    qualified_lookup.get(called_name.as_str()),
+                    local_qualified.and_then(|m| m.get(called_name.as_str())),
+                    &mut exact_storage,
+                );
+                if !exact.is_empty() {
                     counts.resolved += 1;
-                    for &target in targets {
+                    for &target in exact {
                         if target != caller_qn {
                             out.push((
                                 caller_qn,
                                 target,
                                 *line,
                                 Resolution::ExactQualified,
-                                targets.len(),
+                                exact.len(),
                             ));
                         }
                     }
@@ -379,10 +457,16 @@ pub fn build_call_edges(
                     None => (None, called_name.as_str()),
                 };
 
-                let Some(candidates) = name_lookup.get(method_name) else {
+                let mut name_storage: Vec<&str> = Vec::new();
+                let candidates: &[&str] = merge_candidates(
+                    name_lookup.get(method_name),
+                    local_names.and_then(|m| m.get(method_name)),
+                    &mut name_storage,
+                );
+                if candidates.is_empty() {
                     counts.no_candidate += 1;
                     continue;
-                };
+                }
 
                 if candidates.len() == 1 {
                     counts.resolved += 1;
@@ -393,7 +477,7 @@ pub fn build_call_edges(
                     continue;
                 }
 
-                let mut targets: &[&str] = candidates.as_slice();
+                let mut targets: &[&str] = candidates;
                 let mut filtered: Vec<&str>;
 
                 // Tier 0: receiver-type filter. Two sources of hints —
@@ -682,6 +766,97 @@ mod stats_tests {
         rows
     }
 
+    /// D3: mark a function as closure-scoped, the way the TS scope walk does.
+    fn nested(mut f: FunctionInfo, depth: u64) -> FunctionInfo {
+        f.metadata
+            .insert("nesting_depth".into(), serde_json::json!(depth));
+        f
+    }
+
+    /// D3 — a `nesting_depth > 0` definition never joins the global bare-name
+    /// lookup. Naively merging opencode's ~2 270 nested names into it took
+    /// multi-candidate names from 664 to 1 562 and flipped 293 unique names
+    /// ambiguous (Phase 1 spike), which is exactly the false-positive class
+    /// v0.1.5's resolution metadata exists to keep out.
+    #[test]
+    fn a_nested_definition_is_invisible_to_a_caller_in_another_file() {
+        let functions = vec![
+            func("b.consume", "b.ts", &[("helper", 3)]),
+            nested(func("a.outer.helper", "a.ts", &[]), 1),
+        ];
+        let (edges, _) = build_call_edges(
+            &functions,
+            &[],
+            &std::collections::HashSet::new(),
+            5,
+            &[],
+            &no_imports(),
+        );
+        assert!(
+            edges.is_empty(),
+            "leaked cross-file edges: {:?}",
+            edges
+                .iter()
+                .map(|e| (&e.caller, &e.callee))
+                .collect::<Vec<_>>()
+        );
+    }
+
+    /// …but a caller in its own file resolves it, top-level or nested.
+    #[test]
+    fn a_nested_definition_resolves_for_callers_in_its_own_file() {
+        let functions = vec![
+            func("a.outer", "a.ts", &[("helper", 3)]),
+            nested(func("a.outer.helper", "a.ts", &[("deeper", 5)]), 1),
+            nested(func("a.outer.helper.deeper", "a.ts", &[]), 2),
+        ];
+        let (edges, _) = build_call_edges(
+            &functions,
+            &[],
+            &std::collections::HashSet::new(),
+            5,
+            &[],
+            &no_imports(),
+        );
+        let mut pairs: Vec<_> = edges
+            .iter()
+            .map(|e| (e.caller.as_str(), e.callee.as_str()))
+            .collect();
+        pairs.sort();
+        assert_eq!(
+            pairs,
+            vec![
+                ("a.outer", "a.outer.helper"),
+                ("a.outer.helper", "a.outer.helper.deeper"),
+            ]
+        );
+    }
+
+    /// The gating is by *name visibility*, not by dropping the node: a
+    /// nested definition in one file must not shadow or suppress an
+    /// identically named top-level export in another.
+    #[test]
+    fn a_nested_name_does_not_disturb_the_global_lookup() {
+        let functions = vec![
+            func("b.consume", "b.ts", &[("helper", 3)]),
+            func("c.helper", "c.ts", &[]),
+            nested(func("a.outer.helper", "a.ts", &[]), 1),
+        ];
+        let (edges, _) = build_call_edges(
+            &functions,
+            &[],
+            &std::collections::HashSet::new(),
+            5,
+            &[],
+            &no_imports(),
+        );
+        assert_eq!(
+            meta(&edges),
+            vec![("c.helper", "unique_name", 1, false)],
+            "the cross-file caller must see exactly the top-level `helper`"
+        );
+    }
+
     #[test]
     fn unique_name_tier_is_labelled_and_counted() {
         let functions = vec![

{codingest-0.1.5 → codingest-0.1.6}/crates/codingest/src/builder/load/entity_frames.rs

@@ -463,7 +463,40 @@ pub(super) fn functions_df(
             ),
         ),
     ];
-    for key in ["symbol_kind", "role_hint"] {
+    // `nesting_depth` — 0 == top level. Written by the parsers only when it
+    // is non-zero, so this column appears only in a build that actually
+    // contains closure-scoped definitions, and NULL reads as "top level".
+    // Together with `parent_scope` below it replaces a Function→Function
+    // containment edge, which would have lied about node types: the
+    // enclosing scope is very often a `Constant` (an Effect-TS `layer`) or
+    // an anonymous literal, not a Function.
+    if fns
+        .iter()
+        .any(|function| function.metadata.contains_key("nesting_depth"))
+    {
+        columns.push((
+            "nesting_depth",
+            ColumnType::Int64,
+            int_col(
+                fns.iter()
+                    .map(|function| {
+                        function
+                            .metadata
+                            .get("nesting_depth")
+                            .and_then(|value| value.as_i64())
+                    })
+                    .collect(),
+            ),
+        ));
+    }
+    // Sparse string metadata, promoted only when some function in the build
+    // actually carries the key — so a corpus without it keeps its exact
+    // column set (and therefore its golden digest). `wrapped_by` is the
+    // TS/JS factory-unwrap label (`Effect.fn`, `Layer.effect`, `memoize`);
+    // `parent_scope` is the qualified name of the nearest named enclosing
+    // binding, so containment queries read `WHERE n.parent_scope = '…'`.
+    // Without promotion the parser would be writing metadata nothing reads.
+    for key in ["symbol_kind", "role_hint", "wrapped_by", "parent_scope"] {
         if fns.iter().any(|function| {
             function
                 .metadata