diffctx 1.10.2__tar.gz → 1.11.0__tar.gz

{diffctx-1.10.2 → diffctx-1.11.0}/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.11.0] - 2026-07-07
+
+### Changed
+
+- **The default `--format` is now `md` (Markdown), previously `yaml`.** Markdown
+  is ~7% more token-efficient than YAML on real diffs and is preferred by
+  reviewers for code-fragment-heavy output (evidence:
+  `benchmarks/real_world_diff_bench/`). YAML remains available via `-f yaml`.
+  This also changes the default stdout format of `treemapper` (a passthrough
+  wrapper over this engine); downstream scripts that parse the default output
+  must now pass `-f yaml` explicitly. (#104)
+
 ## [1.10.0] - 2026-06-20
 
 ### Changed

{diffctx-1.10.2 → diffctx-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffctx
-Version: 1.10.2
+Version: 1.11.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -101,9 +101,9 @@ lines outward and stops as soon as additional context stops paying for itself.
 ## Install (30 seconds)
 
 ```bash
-pipx install diffctx                    # recommended — isolated CLI, no venv needed
+uvx diffctx . --diff HEAD~1             # zero-install, run once via uv
+pipx install diffctx                    # recommended for repeat use — isolated CLI, no venv needed
 pip install diffctx                     # or: into an active environment
-pipx install 'diffctx[tree-sitter]'     # + AST parsing for smarter diff context
 pipx install 'diffctx[mcp]'             # + MCP server for AI assistants
 ```
 
@@ -201,7 +201,7 @@ diffctx graph . --level file -f graphml -o g.xml # file-level graph as GraphML
 <!-- BEGIN USAGE -->
 ```bash
 # full codebase export:
-diffctx .                                # YAML to stdout + token count
+diffctx .                                # Markdown to stdout + token count
 diffctx . -f md -c                       # Markdown → clipboard
 diffctx . -f json -o tree.json           # JSON → file
 diffctx . --no-content                   # structure only, no file contents
@@ -356,6 +356,18 @@ Auto-discovered files:
 - `.diffctx/ignore` — diffctx-specific ignore patterns
 - `.diffctx/whitelist` — Include-only filter (only matched files included)
 
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success — output contains content |
+| `1`  | Runtime error (bad path, permission denied, etc.) |
+| `2`  | Usage error (invalid flags/arguments) |
+| `3`  | Environment error (`--diff` outside a git repo, git not installed, no commits yet) |
+| `4`  | `--diff` produced no semantic context (clean working tree, binary-only, everything filtered out) — output is still emitted, but scripts can detect the empty case. Deletion/rename-only diffs are NOT empty: they list `deleted_files`/`renamed_files` and exit `0` |
+| `130`| Interrupted (Ctrl-C) |
+| `141`| Broken pipe (e.g. piping into `head`) |
+
 ## Content Placeholders
 
 - `<file too large: N bytes>` — exceeds `--max-file-bytes`

{diffctx-1.10.2 → diffctx-1.11.0}/README.md

@@ -24,9 +24,9 @@ lines outward and stops as soon as additional context stops paying for itself.
 ## Install (30 seconds)
 
 ```bash
-pipx install diffctx                    # recommended — isolated CLI, no venv needed
+uvx diffctx . --diff HEAD~1             # zero-install, run once via uv
+pipx install diffctx                    # recommended for repeat use — isolated CLI, no venv needed
 pip install diffctx                     # or: into an active environment
-pipx install 'diffctx[tree-sitter]'     # + AST parsing for smarter diff context
 pipx install 'diffctx[mcp]'             # + MCP server for AI assistants
 ```
 
@@ -124,7 +124,7 @@ diffctx graph . --level file -f graphml -o g.xml # file-level graph as GraphML
 <!-- BEGIN USAGE -->
 ```bash
 # full codebase export:
-diffctx .                                # YAML to stdout + token count
+diffctx .                                # Markdown to stdout + token count
 diffctx . -f md -c                       # Markdown → clipboard
 diffctx . -f json -o tree.json           # JSON → file
 diffctx . --no-content                   # structure only, no file contents
@@ -279,6 +279,18 @@ Auto-discovered files:
 - `.diffctx/ignore` — diffctx-specific ignore patterns
 - `.diffctx/whitelist` — Include-only filter (only matched files included)
 
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Success — output contains content |
+| `1`  | Runtime error (bad path, permission denied, etc.) |
+| `2`  | Usage error (invalid flags/arguments) |
+| `3`  | Environment error (`--diff` outside a git repo, git not installed, no commits yet) |
+| `4`  | `--diff` produced no semantic context (clean working tree, binary-only, everything filtered out) — output is still emitted, but scripts can detect the empty case. Deletion/rename-only diffs are NOT empty: they list `deleted_files`/`renamed_files` and exit `0` |
+| `130`| Interrupted (Ctrl-C) |
+| `141`| Broken pipe (e.g. piping into `head`) |
+
 ## Content Placeholders
 
 - `<file too large: N bytes>` — exceeds `--max-file-bytes`

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/Cargo.lock

@@ -63,9 +63,9 @@ dependencies = [
 
 [[package]]
 name = "anyhow"
-version = "1.0.102"
+version = "1.0.103"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
 
 [[package]]
 name = "base64"
@@ -194,7 +194,7 @@ checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
 [[package]]
 name = "diffctx"
-version = "1.10.0"
+version = "1.11.0"
 dependencies = [
  "anyhow",
  "clap",

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "diffctx"
-version = "1.10.0"
+version = "1.11.0"
 edition = "2024"
 rust-version = "1.85"
 

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/analytics.rs

@@ -190,9 +190,7 @@ pub fn quotient_graph(
             None => return,
         };
         let cat = graph
-            .edge_categories
-            .get(&(src.clone(), dst.clone()))
-            .copied()
+            .edge_category(src, dst)
             .unwrap_or(EdgeCategory::Generic);
 
         if src_key == dst_key {
@@ -415,15 +413,15 @@ pub fn hotspots(
     }
 
     let mut out_deg: FxHashMap<Arc<str>, u32> = FxHashMap::default();
-    for ((src, _dst), cat) in &graph.edge_categories {
+    graph.for_each_categorized_edge(|src, _dst, cat| {
         if let Some(filter) = edge_types
-            && !filter.contains(cat)
+            && !filter.contains(&cat)
         {
-            continue;
+            return;
         }
         let rel: Arc<str> = Arc::from(relative_path(src.path.as_ref(), root));
         *out_deg.entry(rel).or_insert(0) += 1;
-    }
+    });
 
     let max_deg = out_deg.values().copied().max().unwrap_or(0).max(1);
     let max_churn = churn
@@ -601,7 +599,7 @@ mod tests {
         }
         for (s, d, w, c) in edges {
             g.add_edge(s.clone(), d.clone(), *w);
-            g.edge_categories.insert((s.clone(), d.clone()), *c);
+            g.insert_edge_category(s.clone(), d.clone(), *c);
         }
         g.freeze();
         g

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/config/limits.rs

@@ -28,7 +28,10 @@ impl Default for AlgorithmLimits {
             max_generated_lines: 30,
             skip_expensive_threshold: 2000,
             rare_identifier_threshold: 3,
-            overhead_per_fragment: 18,
+            // Measured against real YAML serialization (path/lines/kind/symbol
+            // keys + quoting): actual scaffold runs ~40-45 tokens/fragment,
+            // not 18 - the old estimate let --budget overshoot by ~18%.
+            overhead_per_fragment: 40,
         }
     }
 }

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/config/needs.rs

@@ -1,5 +1,7 @@
 use once_cell::sync::Lazy;
 
+use super::env_overrides::read_env_fraction;
+
 pub struct NeedsConfig {
     pub min_symbol_length: usize,
     pub background_min_ident_length: usize,
@@ -54,8 +56,8 @@ impl Default for NeedsConfig {
             test_mentions: 0.6,
             mentions_fallback: 0.3,
 
-            min_rel_for_bonus: 0.03,
-            relatedness_bonus: 0.25,
+            min_rel_for_bonus: read_env_fraction("DIFFCTX_MIN_REL_FOR_BONUS", 0.03),
+            relatedness_bonus: read_env_fraction("DIFFCTX_RELATEDNESS_BONUS", 0.25),
         }
     }
 }

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/config/scoring.rs

@@ -1,6 +1,6 @@
 use once_cell::sync::Lazy;
 
-use super::env_overrides::read_env_open_fraction;
+use super::env_overrides::{read_env_fraction, read_env_open_fraction};
 
 pub struct EgoScoringConfig {
     pub identifier_overlap_epsilon: f64,
@@ -11,7 +11,7 @@ pub struct EgoScoringConfig {
 impl Default for EgoScoringConfig {
     fn default() -> Self {
         Self {
-            identifier_overlap_epsilon: 0.1,
+            identifier_overlap_epsilon: read_env_fraction("DIFFCTX_EGO_LEXICAL_EPS", 0.1),
             identifier_overlap_cap: 10,
             per_hop_decay: read_env_open_fraction("DIFFCTX_EGO_PER_HOP_DECAY", 0.5),
         }

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/edges/mod.rs

@@ -12,7 +12,9 @@ use rayon::prelude::*;
 use rustc_hash::FxHashMap;
 use tracing::debug;
 
-use crate::graph::EdgeCategory;
+use crate::graph::{
+    CompactEdge, CompactEdges, EdgeCategory, dedup_compact_edges, intern_fragment_nodes,
+};
 use crate::types::FragmentId;
 
 pub type EdgeDict = FxHashMap<(FragmentId, FragmentId), f64>;
@@ -66,11 +68,18 @@ pub fn get_all_builders() -> Vec<Box<dyn EdgeBuilder>> {
     all
 }
 
+/// Collect edges from all builders directly into the interned compact
+/// representation. Each builder's FragmentId-keyed map is converted and
+/// dropped inside the parallel closure, so at no point does the full
+/// edge universe exist as string-keyed hashmaps — the peak that used to
+/// OOM-kill multi-million-edge instances. Merge semantics match the
+/// historical maps exactly: max weight across builders, category from
+/// the first builder (in registration order) that produced the edge.
 pub fn collect_all_edges(
     fragments: &[Fragment],
     repo_root: Option<&Path>,
     skip_expensive: bool,
-) -> (EdgeDict, EdgeCategories) {
+) -> CompactEdges {
     let mut all_builders: Vec<(&str, Box<dyn EdgeBuilder>)> = Vec::new();
     for cat in builder_categories() {
         if skip_expensive && EXPENSIVE_CATEGORIES.contains(&cat.name) {
@@ -82,39 +91,48 @@ pub fn collect_all_edges(
         }
     }
 
+    let (node_to_idx, idx_to_node) = intern_fragment_nodes(fragments);
     let category_weights = *crate::config::category_weights::CATEGORY_WEIGHTS;
-    let per_builder_edges: Vec<(EdgeDict, Vec<((FragmentId, FragmentId), EdgeCategory)>)> =
-        all_builders
-            .par_iter()
-            .map(|(cat_name, builder)| {
-                let cat_label = builder.category_label().unwrap_or(cat_name);
-                let category = EdgeCategory::from_str(cat_label);
-                let multiplier = category_weights.multiplier(category);
-                let mut edges = builder.build(fragments, repo_root);
-                if multiplier != 1.0 {
-                    for w in edges.values_mut() {
-                        *w *= multiplier;
-                    }
-                }
-                let cats: Vec<_> = edges.keys().map(|k| (k.clone(), category)).collect();
-                (edges, cats)
-            })
-            .collect();
-
-    let mut all_edges: EdgeDict = FxHashMap::default();
-    let mut edge_categories: EdgeCategories = FxHashMap::default();
-    for (edges, cats) in per_builder_edges {
-        for ((src, dst), weight) in edges {
-            if weight > *all_edges.get(&(src.clone(), dst.clone())).unwrap_or(&0.0) {
-                all_edges.insert((src.clone(), dst.clone()), weight);
+    let per_builder_edges: Vec<Vec<CompactEdge>> = all_builders
+        .par_iter()
+        .map(|(cat_name, builder)| {
+            let cat_label = builder.category_label().unwrap_or(cat_name);
+            let category = EdgeCategory::from_str(cat_label);
+            let multiplier = category_weights.multiplier(category);
+            let edges = builder.build(fragments, repo_root);
+            let mut compact = Vec::with_capacity(edges.len());
+            for ((src, dst), weight) in edges {
+                let s = match node_to_idx.get(&src) {
+                    Some(&i) => i,
+                    None => continue,
+                };
+                let d = match node_to_idx.get(&dst) {
+                    Some(&i) => i,
+                    None => continue,
+                };
+                compact.push(CompactEdge {
+                    src: s,
+                    dst: d,
+                    weight: weight * multiplier,
+                    category,
+                });
             }
-        }
-        for (key, cat) in cats {
-            edge_categories.entry(key).or_insert(cat);
-        }
+            compact
+        })
+        .collect();
+
+    let total: usize = per_builder_edges.iter().map(|v| v.len()).sum();
+    let mut edges: Vec<CompactEdge> = Vec::with_capacity(total);
+    for v in per_builder_edges {
+        edges.extend(v);
     }
+    dedup_compact_edges(&mut edges);
 
-    (all_edges, edge_categories)
+    CompactEdges {
+        node_to_idx,
+        idx_to_node,
+        edges,
+    }
 }
 
 pub fn discover_all_related_files(

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/filtering.rs

@@ -85,14 +85,14 @@ fn classify_semantic_edges(
     let mut reverse_deps: FxHashMap<Arc<str>, FxHashSet<Arc<str>>> = FxHashMap::default();
     let mut direct_edge_paths: FxHashSet<Arc<str>> = FxHashSet::default();
 
-    for ((src, dst), category) in &graph.edge_categories {
-        if *category != EdgeCategory::Semantic {
-            continue;
+    graph.for_each_categorized_edge(|src, dst, category| {
+        if category != EdgeCategory::Semantic {
+            return;
         }
         let src_changed = changed_paths.contains(&src.path);
         let dst_changed = changed_paths.contains(&dst.path);
         if !(src_changed ^ dst_changed) {
-            continue;
+            return;
         }
 
         let (changed_frag, other_frag) = if src_changed { (src, dst) } else { (dst, src) };
@@ -112,7 +112,7 @@ fn classify_semantic_edges(
         } else {
             direct_edge_paths.insert(other_frag.path.clone());
         }
-    }
+    });
 
     (reverse_deps, direct_edge_paths)
 }
@@ -172,11 +172,11 @@ fn find_config_generic_code_files(
         })
         .collect();
 
-    for ((src, dst), category) in &graph.edge_categories {
+    graph.for_each_categorized_edge(|src, dst, category| {
         let src_changed = changed_paths.contains(&src.path);
         let dst_changed = changed_paths.contains(&dst.path);
         if !(src_changed ^ dst_changed) {
-            continue;
+            return;
         }
         let other_path = if src_changed { &dst.path } else { &src.path };
         match category {
@@ -189,7 +189,7 @@ fn find_config_generic_code_files(
             }
             _ => {}
         }
-    }
+    });
 
     let generic_only: FxHashSet<Arc<str>> = has_generic_config
         .difference(&has_real_edge)

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/fragmentation.rs

@@ -293,7 +293,18 @@ pub fn process_files_for_fragments(
                     // truncation), which can drop the small fragment covering the
                     // edited hunk before core identification runs.
                     let generated = !is_changed && is_generated_file(file_path, content);
-                    let cap = if generated { max_generated } else { max_frags };
+                    // Changed files also get 10x cap headroom: the biggest-N
+                    // truncation below keeps the LONGEST fragments, and the
+                    // edited hunk is typically a small leaf that would be
+                    // dropped first (hunks are only known later, in core
+                    // identification). max_changed_file_size still bounds cost.
+                    let cap = if generated {
+                        max_generated
+                    } else if is_changed {
+                        max_frags.saturating_mul(10)
+                    } else {
+                        max_frags
+                    };
                     if raw_frags.len() > cap {
                         raw_frags.sort_by(|a, b| b.line_count().cmp(&a.line_count()));
                         raw_frags.truncate(cap);

{diffctx-1.10.2 → diffctx-1.11.0}/diffctx/src/git.rs

@@ -143,6 +143,21 @@ pub fn is_git_repo(path: &Path) -> bool {
     run_git(path, &["rev-parse", "--git-dir"]).is_ok()
 }
 
+/// Resolves the actual working-tree root for `path`, which may be a
+/// subdirectory of the repository. `git diff`/`git cat-file` paths are
+/// always reported relative to this root, not to an arbitrary `-C` cwd -
+/// running the pipeline with `path` still set to a subdirectory silently
+/// produces zero fragments because file lookups get double-prefixed
+/// (e.g. `src/src/app.py`).
+pub fn find_toplevel(path: &Path) -> Option<PathBuf> {
+    let out = run_git(path, &["rev-parse", "--show-toplevel"]).ok()?;
+    let trimmed = out.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    Some(PathBuf::from(trimmed))
+}
+
 pub fn get_diff_text(repo_root: &Path, diff_range: Option<&str>) -> Result<String> {
     let mut args: Vec<&str> = vec!["diff"];
     args.extend_from_slice(SAFE_DIFF_FLAGS);
@@ -455,6 +470,41 @@ pub fn get_renamed_paths(
     Ok((old_paths, pure_new_paths))
 }
 
+/// Rename pairs as repo-relative display paths (`old -> new`), for the output
+/// header. Unlike `get_renamed_paths` this preserves the pairing and does not
+/// canonicalize (the old path no longer exists on disk).
+pub fn get_rename_pairs(
+    repo_root: &Path,
+    diff_range: Option<&str>,
+) -> Result<Vec<(String, String)>> {
+    let mut args: Vec<&str> = vec!["diff"];
+    args.extend_from_slice(SAFE_DIFF_FLAGS);
+    args.extend_from_slice(&["--diff-filter=R", "--name-status", "-M", "-z"]);
+    if let Some(range) = diff_range {
+        validate_diff_range(range)?;
+        args.push(range);
+    }
+    let output = run_git(repo_root, &args)?;
+    let parts: Vec<&str> = output.split('\0').collect();
+
+    let mut pairs = Vec::new();
+    let mut i = 0;
+    while i < parts.len() {
+        if parts[i].starts_with('R') {
+            if i + 2 < parts.len() && !parts[i + 1].is_empty() && !parts[i + 2].is_empty() {
+                pairs.push((
+                    parts[i + 1].replace('\\', "/"),
+                    parts[i + 2].replace('\\', "/"),
+                ));
+            }
+            i += 3;
+        } else {
+            i += 1;
+        }
+    }
+    Ok(pairs)
+}
+
 pub fn split_diff_range(range: &str) -> (Option<String>, Option<String>) {
     match RANGE_RE.captures(range) {
         None => (None, None),