diff: tell a rename from a real change

Cargo.toml

@@ -53,6 +53,7 @@ oxc_ast = "0.143"
 oxc_ast_visit = "0.143"
 oxc_codegen = "0.143"
 oxc_parser = "0.143"
+oxc_semantic = "0.143"
 oxc_span = "0.143"
 
 cellar-core = { path = "crates/cellar-core", version = "0.1.0" }

README.md

@@ -135,3 +135,9 @@ Copyright (c) 2026 Rajeh Taher
 Copyright (c) 2026 Polymorfa (Softium LLC)
 
 Licensed under the MIT License. See [LICENSE](LICENSE) for the full text.
+
+## Semantic diffs
+
+Run `cellar diff OLD NEW --semantic` to compare local bindings without treating a rename as a program change. Free names, literals, declaration kinds, async/generator flags and optional access remain significant. Parse diagnostics produce an `unknown` verdict. Semantic classification covers the primary definition and stored variants even when the textual diff exceeds `maxDiffBytes`.
+
+Text, JSON and Markdown reports include the verdict and localized function names. Changed enclosing functions are collapsed when an inner edit explains them; whole function additions and removals retain their outer name. Counts describe this localized report. `--include-noise-only` also shows modules classified as rename-only.

crates/cellar-core/Cargo.toml

@@ -15,6 +15,14 @@ categories = ["development-tools", "parser-implementations"]
 doctest = false
 
 [dependencies]
+# The shape engine needs a real AST and, more importantly, a symbol table: an
+# identifier is only erasable once you know which binding it resolves to.
+oxc_allocator = { workspace = true }
+oxc_ast = { workspace = true }
+oxc_ast_visit = { workspace = true }
+oxc_parser = { workspace = true }
+oxc_semantic = { workspace = true }
+oxc_span = { workspace = true }
 anyhow = { version = "1.0", default-features = false, features = ["std"] }
 hex = { version = "0.4", default-features = false, features = ["std"] }
 rayon = "1.12"

crates/cellar-core/src/diff.rs

@@ -23,6 +23,7 @@
 
 use crate::filter::FilterSet;
 use crate::model::{BundleId, ModuleEntry, ModuleIndex, SCHEMA_VERSION};
+use crate::shape;
 
 /// Supplies module source text on demand. Implemented by
 /// [`BundleHandle`](crate::store::BundleHandle); a test can supply its own.
@@ -53,6 +54,14 @@
     /// Report modules whose only changed lines are noise. When false they are
     /// counted in the summary but left out of `changes`.
     pub include_noise_only: bool,
+    /// Classify each changed module by comparing the two programs with their
+    /// local names erased, and name the functions that really changed.
+    ///
+    /// Off by default because it parses both sides of every changed module,
+    /// which the sha256 comparison does not. It costs roughly a second per
+    /// thousand modules and is the difference between "7,400 modules differ"
+    /// and a list you can read.
+    pub semantic: bool,
 }
 
 impl Default for DiffOptions {
@@ -63,6 +72,7 @@
             max_diff_bytes: 1 << 20,
             max_hunk_bytes: 64 * 1024,
             include_noise_only: false,
+            semantic: false,
         }
     }
 }
@@ -103,6 +113,34 @@
     /// Every changed line matched the filter's `noiseCode` rules.
     #[serde(default, skip_serializing_if = "is_false")]
     pub noise_only: bool,
+    /// What the program did, as opposed to what the text did.
+    ///
+    /// `noiseOnly` above is a line-level guess: it can recognise a changed line
+    /// that *looks* like transpiler output, and nothing more. It cannot see a
+    /// rename cascade, which is the dominant form of noise in a minified bundle
+    /// — inserting one binding renames every local after it, and each of those
+    /// lines looks like real code because it is real code that means exactly
+    /// what it meant before. This field is decided by comparing the two modules
+    /// with their local names erased, so `renamedOnly` is a proof rather than a
+    /// pattern match. Absent when the semantic pass was not requested or the
+    /// module did not parse.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub verdict: Option<shape::Verdict>,
+    /// The functions that actually changed, by the name they are exported
+    /// under. A module reported as changed with this list empty changed only
+    /// outside its functions — a dependency, a top-level constant.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub functions_changed: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub functions_added: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub functions_removed: Vec<String>,
+    /// Functions whose program is unchanged however they were renamed or moved,
+    /// and the total. `40/46 kept` is the sentence a reviewer needs.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub functions_kept: Option<u32>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub functions_total: Option<u32>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub lines_added: Option<u32>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -192,6 +230,12 @@
                     deps_added: retain_signal(&n.deps, &[], filter),
                     deps_removed: vec![],
                     deps_noise_only: false,
+                    verdict: None,
+                    functions_changed: Vec::new(),
+                    functions_added: Vec::new(),
+                    functions_removed: Vec::new(),
+                    functions_kept: None,
+                    functions_total: None,
                     exports_added: n.exports.clone(),
                     exports_removed: vec![],
                     similarity: None,
@@ -214,6 +258,12 @@
                     deps_added: vec![],
                     deps_removed: retain_signal(&o.deps, &[], filter),
                     deps_noise_only: false,
+                    verdict: None,
+                    functions_changed: Vec::new(),
+                    functions_added: Vec::new(),
+                    functions_removed: Vec::new(),
+                    functions_kept: None,
+                    functions_total: None,
                     exports_added: vec![],
                     exports_removed: o.exports.clone(),
                     similarity: None,
@@ -242,12 +292,38 @@
                         "module exceeds maxDiffBytes ({} bytes); old={} new={}",
                         opts.max_diff_bytes, o.stored_len, n.stored_len
                     ));
-                } else {
+                }
+                if !too_big || opts.semantic {
                     let old_text = old_src.load(o)?;
                     let new_text = new_src.load(n)?;
-                    apply_text_diff(&mut change, &old_text, &new_text, filter, opts);
+                    if !too_big { apply_text_diff(&mut change, &old_text, &new_text, filter, opts); }
+                    if opts.semantic {
+                        if o.variants.is_empty() && n.variants.is_empty() {
+                            apply_semantic_diff(&mut change, &old_text, &new_text);
+                        } else {
+                            let definitions = |entry: &ModuleEntry, primary: String, loader: &dyn SourceLoader| -> Result<Vec<String>> {
+                                let mut texts = vec![primary];
+                                for variant in &entry.variants {
+                                    let mut v = entry.clone(); v.file = variant.file.clone(); v.raw_sha256 = variant.sha256.clone();
+                                    texts.push(loader.load(&v)?);
+                                }
+                                Ok(texts)
+                            };
+                            apply_definition_diff(&mut change, definitions(o, old_text, old_src)?, definitions(n,new_text,new_src)?);
+                        }
+                    }
                 }
 
+                // A proof outranks a guess. The line rules can only recognise
+                // changed lines that *look* like transpiler output; the shape
+                // comparison knows the two programs are the same one, whatever
+                // the lines say. Where they disagree, take the proof — that is
+                // the whole reason for computing it.
+                match change.verdict {
+                    Some(shape::Verdict::RenamedOnly) => change.noise_only = true,
+                    Some(shape::Verdict::Changed | shape::Verdict::Unknown) => change.noise_only = false,
+                    _ => {}
+                }
                 if change.noise_only {
                     summary.noise_only += 1;
                     if !opts.include_noise_only {
@@ -322,13 +398,70 @@
         exports_removed: diff_lists(&o.exports, &n.exports),
         similarity: None,
         noise_only: false,
+        verdict: None,
+        functions_changed: Vec::new(),
+        functions_added: Vec::new(),
+        functions_removed: Vec::new(),
+        functions_kept: None,
+        functions_total: None,
         lines_added: None,
         lines_removed: None,
         hunks: None,
         hunks_omitted: None,
     }
 }
 
+/// Decide what the *program* did, and name the functions it did it in.
+///
+/// The text diff above answers "which lines are different", which in a minified
+/// bundle is mostly a question about the minifier. This answers "is this a
+/// different program", and when it is, "which functions" — the two things a
+/// reviewer actually wants and neither of which a line diff can supply.
+fn apply_semantic_diff(change: &mut ModuleChange, old_text: &str, new_text: &str) {
+    let verdict = shape::compare(old_text, new_text);
+    change.verdict = Some(verdict);
+    // Nothing to localise: either the program is the same, or one side did not
+    // parse and any function list would be invented rather than measured.
+    if !matches!(verdict, shape::Verdict::Changed) {
+        return;
+    }
+
+    let d = shape::diff_functions(old_text, new_text);
+    change.functions_changed = d.changed.iter().map(|c| c.label.clone()).collect();
+    change.functions_added = d.added.iter().map(|f| f.label.clone()).collect();
+    change.functions_removed = d.removed.iter().map(|f| f.label.clone()).collect();
+    change.functions_kept = Some(d.kept as u32);
+    change.functions_total = Some(d.total as u32);
+}
+
+// Compare the complete definition multiset, not only whichever copy was primary.
+// Exact canonical matches are removed before pairing remaining changed definitions.
+fn apply_definition_diff(change: &mut ModuleChange, old: Vec<String>, new: Vec<String>) {
+    let shapes = |texts: Vec<String>| -> Option<Vec<(String,String)>> {
+        texts.into_iter().map(|text| shape::shape(&text).map(|s| (s.hash,text))).collect()
+    };
+    let (Some(mut old), Some(mut new)) = (shapes(old),shapes(new)) else {
+        change.verdict = Some(shape::Verdict::Unknown); return;
+    };
+    old.sort(); new.sort();
+    new.retain(|(hash,_)| {
+        if let Some(i) = old.iter().position(|(h,_)| h==hash) { old.remove(i); false } else { true }
+    });
+    if old.is_empty() && new.is_empty() { change.verdict=Some(shape::Verdict::RenamedOnly); return; }
+    change.verdict=Some(shape::Verdict::Changed);
+    let mut kept=0; let mut total=0;
+    for i in 0..old.len().max(new.len()) {
+        let a=old.get(i).map(|(_,t)| t.as_str()).unwrap_or("");
+        let b=new.get(i).map(|(_,t)| t.as_str()).unwrap_or("");
+        let d=shape::diff_functions(a,b); kept+=d.kept; total+=d.total;
+        let prefix=|label: &str| format!("definition {}/{label}",i+1);
+        change.functions_changed.extend(d.changed.iter().map(|c| prefix(&c.label)));
+        change.functions_added.extend(d.added.iter().map(|f| prefix(&f.label)));
+        change.functions_removed.extend(d.removed.iter().map(|f| prefix(&f.label)));
+    }
+    change.functions_kept=Some(kept as u32); change.functions_total=Some(total as u32);
+}
+
 fn apply_text_diff(
     change: &mut ModuleChange,
     old_text: &str,
@@ -423,9 +556,32 @@
             chunk: "c.js".to_string(),
             form: SourceForm::Pretty,
             variants: vec![],
         }
     }
 
+
+    #[test]
+    fn semantic_runs_above_hunk_cap_and_overrides_line_noise() {
+        let a=idx(1,vec![entry("M","a",&[],2048)]);let b=idx(2,vec![entry("M","b",&[],2048)]);
+        let opts=DiffOptions{semantic:true,max_diff_bytes:1,..Default::default()};
+        let d=diff_bundles(&a,&loader(&[("M","var a=babelHelpers.x")]),&b,&loader(&[("M","const a=babelHelpers.x")]),&keep_all(),&opts).unwrap();
+        assert_eq!(d.changes.len(),1);let m=&d.changes[0];assert!(m.hunks_omitted.is_some());
+        assert_eq!(m.verdict,Some(shape::Verdict::Changed));assert!(!m.noise_only);
+    }
+    #[test]
+    fn semantic_compares_primary_and_variants() {
+        use crate::model::ModuleVariant;
+        struct Files(BTreeMap<String,String>);
+        impl SourceLoader for Files { fn load(&self,e:&ModuleEntry)->Result<String>{Ok(self.0[&e.file].clone())} }
+        let mut a=entry("M","primary",&[],10);let mut b=a.clone();
+        a.variants.push(ModuleVariant{sha256:"a".into(),file:"old.js".into(),raw_len:10,deps_added:vec![],deps_removed:vec![]});
+        b.variants.push(ModuleVariant{sha256:"b".into(),file:"new.js".into(),raw_len:10,deps_added:vec![],deps_removed:vec![]});
+        let files=Files(BTreeMap::from([("modules/M.js".into(),"var e={};e.primary=function(){return 0}".into()),("old.js".into(),"var e={};e.variant=function(){return 1}".into()),("new.js".into(),"var e={};e.variant=function(){return 2}".into())]));
+        let d=diff_bundles(&idx(1,vec![a.clone()]),&files,&idx(2,vec![b.clone()]),&files,&keep_all(),&DiffOptions{semantic:true,..Default::default()}).unwrap();
+        assert_eq!(d.changes[0].verdict,Some(shape::Verdict::Changed));assert!(d.changes[0].functions_changed.iter().any(|s| s.ends_with("/variant")));
+        b.variants.clear();let d=diff_bundles(&idx(1,vec![a]),&files,&idx(2,vec![b]),&files,&keep_all(),&DiffOptions{semantic:true,..Default::default()}).unwrap();
+        assert_eq!(d.changes[0].verdict,Some(shape::Verdict::Changed));assert!(!d.changes[0].functions_removed.is_empty());
+    }
     fn keep_all() -> FilterSet {
         FilterSet::compile(Filter {
             name: "all".into(),
@@ -521,6 +677,67 @@
         assert!(d.changes[0].hunks.as_ref().unwrap().contains("sendStanza"));
     }
 
+    /// The case the line rules cannot reach. Every changed line here is real
+    /// code that reads as real code; only erasing the names shows the two
+    /// programs are the same one.
+    #[test]
+    fn a_rename_cascade_is_noise_the_line_rules_cannot_see() {
+        let old = idx(1, vec![entry("M", "aaa", &[], 90)]);
+        let new = idx(2, vec![entry("M", "bbb", &[], 90)]);
+        let ol = loader(&[("M", "var h = 1, y = 2;\nfunction f() { return h + y }\n")]);
+        let nl = loader(&[("M", "var y = 1, C = 2;\nfunction g() { return y + C }\n")]);
+
+        // Without the semantic pass this is three changed lines of ordinary
+        // code, and the line rules are right to call it a change on what they
+        // can see.
+        let d = diff_bundles(&old, &ol, &new, &nl, &keep_all(), &DiffOptions::default()).unwrap();
+        assert_eq!(d.changes.len(), 1);
+        assert!(!d.changes[0].noise_only);
+
+        let opts = DiffOptions {
+            semantic: true,
+            include_noise_only: true,
+            ..Default::default()
+        };
+        let d = diff_bundles(&old, &ol, &new, &nl, &keep_all(), &opts).unwrap();
+        assert_eq!(d.changes[0].verdict, Some(shape::Verdict::RenamedOnly));
+        assert!(d.changes[0].noise_only, "a proof outranks the line rules");
+        assert_eq!(d.summary.noise_only, 1);
+    }
+
+    /// And it must not swallow a real edit hiding inside that same cascade.
+    #[test]
+    fn a_real_change_inside_a_cascade_is_named() {
+        let old = idx(1, vec![entry("M", "aaa", &[], 90)]);
+        let new = idx(2, vec![entry("M", "bbb", &[], 90)]);
+        // A real module shape: the factory's last parameter is the exports
+        // object, and that is what makes `check` a name rather than a letter.
+        let ol = loader(&[(
+            "M",
+            "__d(\"M\", [], (function(t, n, r, o, a, i, l) {\n\
+             \x20 var h = 1;\n  function f(t) { return t > 4 }\n  l.check = f;\n}), 98)\n",
+        )]);
+        let nl = loader(&[(
+            "M",
+            "__d(\"M\", [], (function(e, s, d, f, g, h, j) {\n\
+             \x20 var y = 1;\n  function q(n) { return n > 5 }\n  j.check = q;\n}), 98)\n",
+        )]);
+
+        let opts = DiffOptions {
+            semantic: true,
+            ..Default::default()
+        };
+        let d = diff_bundles(&old, &ol, &new, &nl, &keep_all(), &opts).unwrap();
+        let c = &d.changes[0];
+        assert_eq!(c.verdict, Some(shape::Verdict::Changed));
+        assert!(!c.noise_only);
+        assert_eq!(
+            c.functions_changed,
+            vec!["check"],
+            "named, not just counted"
+        );
+    }
+
     #[test]
     fn noise_deps_are_excluded_but_the_fact_of_change_is_kept() {
         let old = idx(1, vec![entry("M", "aaa", &["React"], 10)]);

crates/cellar-core/src/lib.rs

@@ -25,6 +25,7 @@ pub mod graph;
 pub mod model;
 pub mod naming;
 pub mod search;
+pub mod shape;
 pub mod store;
 
 pub use diff::{BundleDiff, ChangeKind, DiffOptions, ModuleChange, SourceLoader, diff_bundles};