Skip to main content

deno_doc/diff/
mod.rs

1// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
2
3mod class;
4mod r#enum;
5mod function;
6mod interface;
7mod js_doc;
8mod namespace;
9mod ts_type;
10mod type_alias;
11mod variable;
12
13use deno_ast::ModuleSpecifier;
14use indexmap::IndexMap;
15use indexmap::IndexSet;
16use serde::Deserialize;
17use serde::Serialize;
18
19use std::sync::Arc;
20
21use crate::Symbol;
22use crate::node::Declaration;
23use crate::node::DeclarationDef;
24use crate::node::DeclarationKind;
25use crate::node::DocNodeKind;
26use crate::parser::ParseOutput;
27
28pub use class::ClassDiff;
29pub use class::ConstructorDiff;
30pub use class::ConstructorsDiff;
31pub use class::IndexSignatureDiff;
32pub use class::IndexSignaturesDiff;
33pub use class::MethodDiff;
34pub use class::MethodsDiff;
35pub use class::PropertiesDiff;
36pub use class::PropertyDiff;
37pub use r#enum::EnumDiff;
38pub use function::FunctionDiff;
39pub use function::ParamsDiff;
40pub use interface::CallSignaturesDiff;
41pub use interface::InterfaceConstructorsDiff;
42pub use interface::InterfaceDiff;
43pub use interface::InterfaceIndexSignatureDiff;
44pub use interface::InterfaceIndexSignaturesDiff;
45pub use interface::InterfaceMethodDiff;
46pub use interface::InterfaceMethodsDiff;
47pub use interface::InterfacePropertiesDiff;
48pub use interface::InterfacePropertyDiff;
49pub use js_doc::JsDocDiff;
50pub use js_doc::TagsDiff;
51pub use namespace::NamespaceDiff;
52pub use ts_type::TsTypeDiff;
53pub use ts_type::TypeParamsDiff;
54pub use type_alias::TypeAliasDiff;
55pub use variable::VariableDiff;
56
57/// Maximum change percentage for two items to be considered a rename.
58pub(crate) const RENAME_THRESHOLD: f64 = 0.10;
59
60/// Trait for diff types that support rename detection via change percentage.
61pub(crate) trait RenameCandidate: Sized {
62  type Item;
63
64  /// Whether two items are structurally compatible for a rename
65  /// (e.g. same kind, same is_static).
66  fn is_candidate(old: &Self::Item, new: &Self::Item) -> bool;
67
68  /// Compute the diff between old and new items.
69  fn compute(old: &Self::Item, new: &Self::Item) -> Option<Self>;
70
71  /// The fraction of fields that changed (0.0 = identical, 1.0 = everything).
72  fn delta(&self) -> f64;
73
74  /// Wrap an optional diff as a rename entry (setting name and name_change).
75  fn with_rename(
76    diff: Option<Self>,
77    old: &Self::Item,
78    new: &Self::Item,
79  ) -> Self;
80}
81
82/// Detect renames among added/removed pairs using diff delta threshold.
83/// Matched pairs are moved into `modified` and removed from `added`/`removed`.
84pub(crate) fn detect_renames<D: RenameCandidate>(
85  added: &mut Vec<D::Item>,
86  removed: &mut Vec<D::Item>,
87  modified: &mut Vec<D>,
88) {
89  let mut matched_added = IndexSet::new();
90  let mut matched_removed = IndexSet::new();
91
92  for (r_idx, removed_item) in removed.iter().enumerate() {
93    for (a_idx, added_item) in added.iter().enumerate() {
94      if matched_added.contains(&a_idx) {
95        continue;
96      }
97
98      if !D::is_candidate(removed_item, added_item) {
99        continue;
100      }
101
102      let diff = D::compute(removed_item, added_item);
103      let pct = diff.as_ref().map_or(0.0, |d| d.delta());
104      if pct <= RENAME_THRESHOLD {
105        modified.push(D::with_rename(diff, removed_item, added_item));
106        matched_added.insert(a_idx);
107        matched_removed.insert(r_idx);
108        break;
109      }
110    }
111  }
112
113  let mut i = 0;
114  added.retain(|_| {
115    let keep = !matched_added.contains(&i);
116    i += 1;
117    keep
118  });
119  let mut i = 0;
120  removed.retain(|_| {
121    let keep = !matched_removed.contains(&i);
122    i += 1;
123    keep
124  });
125}
126
127#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
128#[serde(rename_all = "camelCase")]
129pub struct Change<T> {
130  pub old: T,
131  pub new: T,
132}
133
134impl<T> Change<T> {
135  pub fn new(old: T, new: T) -> Self {
136    Self { old, new }
137  }
138}
139
140#[derive(Debug, Clone, Serialize, Deserialize, Default)]
141#[serde(rename_all = "camelCase")]
142pub struct DocDiff {
143  #[serde(skip_serializing_if = "Vec::is_empty", default)]
144  pub added_modules: Vec<ModuleSpecifier>,
145  #[serde(skip_serializing_if = "Vec::is_empty", default)]
146  pub removed_modules: Vec<ModuleSpecifier>,
147  #[serde(skip_serializing_if = "IndexMap::is_empty", default)]
148  pub modified_modules: IndexMap<ModuleSpecifier, ModuleDiff>,
149}
150
151impl DocDiff {
152  pub fn diff(old: &ParseOutput, new: &ParseOutput) -> Self {
153    let old_modules = old.keys().collect::<IndexSet<_>>();
154    let new_modules = new.keys().collect::<IndexSet<_>>();
155
156    let added_modules = new_modules
157      .difference(&old_modules)
158      .map(|s| (*s).clone())
159      .collect::<Vec<_>>();
160    let removed_modules = old_modules
161      .difference(&new_modules)
162      .map(|s| (*s).clone())
163      .collect::<Vec<_>>();
164
165    let mut modified_modules = IndexMap::new();
166
167    for specifier in old_modules.intersection(&new_modules) {
168      let old_doc = old.get(*specifier).unwrap();
169      let new_doc = new.get(*specifier).unwrap();
170
171      let module_diff = ModuleDiff::diff(&old_doc.symbols, &new_doc.symbols);
172
173      if module_diff.has_changes() {
174        modified_modules.insert((*specifier).clone(), module_diff);
175      }
176    }
177
178    DocDiff {
179      added_modules,
180      removed_modules,
181      modified_modules,
182    }
183  }
184
185  pub fn has_changes(&self) -> bool {
186    !self.added_modules.is_empty()
187      || !self.removed_modules.is_empty()
188      || !self.modified_modules.is_empty()
189  }
190}
191
192#[derive(Debug, Clone, Serialize, Deserialize, Default)]
193#[serde(rename_all = "camelCase")]
194pub struct ModuleDiff {
195  #[serde(skip_serializing_if = "Vec::is_empty", default)]
196  pub added: Vec<Symbol>,
197  #[serde(skip_serializing_if = "Vec::is_empty", default)]
198  pub removed: Vec<Symbol>,
199  #[serde(skip_serializing_if = "Vec::is_empty", default)]
200  pub modified: Vec<SymbolDiff>,
201}
202
203impl ModuleDiff {
204  pub fn diff(old_nodes: &[Arc<Symbol>], new_nodes: &[Arc<Symbol>]) -> Self {
205    let old_map = build_name_map(old_nodes);
206    let new_map = build_name_map(new_nodes);
207
208    let mut added: Vec<Symbol> = Vec::new();
209    let mut removed: Vec<Symbol> = Vec::new();
210    let mut modified = Vec::new();
211
212    for (name, node) in &new_map {
213      if !old_map.contains_key(name) {
214        added.push((*node).clone());
215      }
216    }
217
218    for (name, node) in &old_map {
219      if !new_map.contains_key(name) {
220        removed.push((*node).clone());
221      }
222    }
223
224    // Rename detection among added/removed Symbols
225    let mut matched_added = IndexSet::new();
226    let mut matched_removed = IndexSet::new();
227
228    for (r_idx, removed_node) in removed.iter().enumerate() {
229      for (a_idx, added_node) in added.iter().enumerate() {
230        if matched_added.contains(&a_idx) {
231          continue;
232        }
233
234        if let Some(rename_diff) = try_detect_rename(removed_node, added_node) {
235          modified.push(rename_diff);
236          matched_added.insert(a_idx);
237          matched_removed.insert(r_idx);
238          break;
239        }
240      }
241    }
242
243    let mut i = 0;
244    added.retain(|_| {
245      let keep = !matched_added.contains(&i);
246      i += 1;
247      keep
248    });
249    let mut i = 0;
250    removed.retain(|_| {
251      let keep = !matched_removed.contains(&i);
252      i += 1;
253      keep
254    });
255
256    // Modifications: same name in both
257    for (name, old_node) in &old_map {
258      if let Some(new_node) = new_map.get(name)
259        && let Some(diff) = SymbolDiff::diff(old_node, new_node)
260      {
261        modified.push(diff);
262      }
263    }
264
265    ModuleDiff {
266      added,
267      removed,
268      modified,
269    }
270  }
271
272  pub fn has_changes(&self) -> bool {
273    !self.added.is_empty()
274      || !self.removed.is_empty()
275      || !self.modified.is_empty()
276  }
277}
278
279/// Detect if two Symbols are a rename of each other.
280/// Returns a SymbolDiff with name_change set if below threshold.
281fn try_detect_rename(old: &Symbol, new: &Symbol) -> Option<SymbolDiff> {
282  let old_kinds: IndexSet<DocNodeKind> =
283    old.declarations.iter().map(|d| d.def.to_kind()).collect();
284  let new_kinds: IndexSet<DocNodeKind> =
285    new.declarations.iter().map(|d| d.def.to_kind()).collect();
286
287  if old_kinds.is_disjoint(&new_kinds) {
288    return None;
289  }
290
291  // Use first common kind to check rename threshold
292  let first_kind = *old_kinds.intersection(&new_kinds).next()?;
293  let old_decl = old
294    .declarations
295    .iter()
296    .find(|d| d.def.to_kind() == first_kind)?;
297  let new_decl = new
298    .declarations
299    .iter()
300    .find(|d| d.def.to_kind() == first_kind)?;
301
302  let def_diff = DeclarationDefDiff::diff(&old_decl.def, &new_decl.def);
303  let pct = def_diff
304    .as_ref()
305    .map_or(0.0, |d| d.change_percentage(&old_decl.def, &new_decl.def));
306
307  if pct > RENAME_THRESHOLD {
308    return None;
309  }
310
311  let declarations =
312    DeclarationsDiff::diff(&old.declarations, &new.declarations);
313
314  Some(SymbolDiff {
315    name: new.name.clone(),
316    name_change: Some(Change::new(old.name.clone(), new.name.clone())),
317    is_default_change: if old.is_default != new.is_default {
318      Some(Change::new(old.is_default, new.is_default))
319    } else {
320      None
321    },
322    declarations,
323  })
324}
325
326fn build_name_map(nodes: &[Arc<Symbol>]) -> IndexMap<&str, &Symbol> {
327  nodes
328    .iter()
329    .map(|n| (n.name.as_ref(), n.as_ref()))
330    .collect()
331}
332
333#[derive(Debug, Clone, Serialize, Deserialize)]
334#[serde(rename_all = "camelCase")]
335pub struct SymbolDiff {
336  pub name: Box<str>,
337  #[serde(skip_serializing_if = "Option::is_none")]
338  pub name_change: Option<Change<Box<str>>>,
339  #[serde(skip_serializing_if = "Option::is_none")]
340  pub is_default_change: Option<Change<bool>>,
341  #[serde(skip_serializing_if = "Option::is_none")]
342  pub declarations: Option<DeclarationsDiff>,
343}
344
345#[derive(Debug, Clone, Serialize, Deserialize, Default)]
346#[serde(rename_all = "camelCase")]
347pub struct DeclarationsDiff {
348  #[serde(skip_serializing_if = "Vec::is_empty", default)]
349  pub added: Vec<Declaration>,
350  #[serde(skip_serializing_if = "Vec::is_empty", default)]
351  pub removed: Vec<Declaration>,
352  #[serde(skip_serializing_if = "Vec::is_empty", default)]
353  pub modified: Vec<DeclarationDiff>,
354}
355
356impl DeclarationsDiff {
357  pub fn diff(old: &[Declaration], new: &[Declaration]) -> Option<Self> {
358    let old_map = old
359      .iter()
360      .map(|d| (d.def.to_kind(), d))
361      .collect::<IndexMap<_, _>>();
362    let new_map = new
363      .iter()
364      .map(|d| (d.def.to_kind(), d))
365      .collect::<IndexMap<_, _>>();
366
367    let mut added = Vec::new();
368    let mut removed = Vec::new();
369    let mut modified = Vec::new();
370
371    for (kind, new_decl) in &new_map {
372      match old_map.get(kind) {
373        Some(old_decl) => {
374          if let Some(diff) = DeclarationDiff::diff(old_decl, new_decl) {
375            modified.push(diff);
376          }
377        }
378        None => {
379          added.push((*new_decl).clone());
380        }
381      }
382    }
383
384    for (kind, old_decl) in &old_map {
385      if !new_map.contains_key(kind) {
386        removed.push((*old_decl).clone());
387      }
388    }
389
390    if added.is_empty() && removed.is_empty() && modified.is_empty() {
391      return None;
392    }
393
394    Some(DeclarationsDiff {
395      added,
396      removed,
397      modified,
398    })
399  }
400}
401
402#[derive(Debug, Clone, Serialize, Deserialize)]
403#[serde(rename_all = "camelCase")]
404pub struct DeclarationDiff {
405  pub kind: DocNodeKind,
406  #[serde(skip_serializing_if = "Option::is_none")]
407  pub def_changes: Option<DeclarationDefDiff>,
408  #[serde(skip_serializing_if = "Option::is_none")]
409  pub js_doc_changes: Option<JsDocDiff>,
410  #[serde(skip_serializing_if = "Option::is_none")]
411  pub declaration_kind_change: Option<Change<DeclarationKind>>,
412}
413
414impl DeclarationDiff {
415  pub fn diff(old: &Declaration, new: &Declaration) -> Option<Self> {
416    let def_changes = DeclarationDefDiff::diff(&old.def, &new.def);
417
418    let js_doc_changes = JsDocDiff::diff(&old.js_doc, &new.js_doc);
419
420    let declaration_kind_change =
421      if old.declaration_kind != new.declaration_kind {
422        Some(Change::new(old.declaration_kind, new.declaration_kind))
423      } else {
424        None
425      };
426
427    if def_changes.is_none()
428      && js_doc_changes.is_none()
429      && declaration_kind_change.is_none()
430    {
431      return None;
432    }
433
434    Some(DeclarationDiff {
435      kind: old.def.to_kind(),
436      def_changes,
437      js_doc_changes,
438      declaration_kind_change,
439    })
440  }
441}
442
443impl SymbolDiff {
444  pub fn diff(old: &Symbol, new: &Symbol) -> Option<Self> {
445    let declarations =
446      DeclarationsDiff::diff(&old.declarations, &new.declarations);
447
448    let is_default_change = if old.is_default != new.is_default {
449      Some(Change::new(old.is_default, new.is_default))
450    } else {
451      None
452    };
453
454    if declarations.is_none() && is_default_change.is_none() {
455      return None;
456    }
457
458    Some(SymbolDiff {
459      name: old.name.clone(),
460      name_change: None,
461      is_default_change,
462      declarations,
463    })
464  }
465}
466
467#[derive(Debug, Clone, Serialize, Deserialize)]
468#[serde(tag = "type", rename_all = "camelCase")]
469pub enum DeclarationDefDiff {
470  Function(FunctionDiff),
471  Variable(VariableDiff),
472  Enum(EnumDiff),
473  Class(ClassDiff),
474  TypeAlias(TypeAliasDiff),
475  Namespace(NamespaceDiff),
476  Interface(InterfaceDiff),
477  // ignore Reference
478}
479
480impl DeclarationDefDiff {
481  pub fn change_percentage(
482    &self,
483    old: &DeclarationDef,
484    new: &DeclarationDef,
485  ) -> f64 {
486    match (self, old, new) {
487      (DeclarationDefDiff::Function(d), _, _) => d.change_percentage(),
488      (DeclarationDefDiff::Variable(d), _, _) => d.change_percentage(),
489      (DeclarationDefDiff::TypeAlias(d), _, _) => d.change_percentage(),
490      (
491        DeclarationDefDiff::Enum(d),
492        DeclarationDef::Enum(old_def),
493        DeclarationDef::Enum(new_def),
494      ) => d.change_percentage(old_def, new_def),
495      (
496        DeclarationDefDiff::Class(d),
497        DeclarationDef::Class(old_def),
498        DeclarationDef::Class(new_def),
499      ) => d.change_percentage(old_def, new_def),
500      (
501        DeclarationDefDiff::Interface(d),
502        DeclarationDef::Interface(old_def),
503        DeclarationDef::Interface(new_def),
504      ) => d.change_percentage(old_def, new_def),
505      (
506        DeclarationDefDiff::Namespace(d),
507        DeclarationDef::Namespace(old_def),
508        DeclarationDef::Namespace(new_def),
509      ) => d.change_percentage(old_def, new_def),
510      _ => 1.0,
511    }
512  }
513
514  pub fn as_function(&self) -> Option<&FunctionDiff> {
515    match self {
516      DeclarationDefDiff::Function(d) => Some(d),
517      _ => None,
518    }
519  }
520
521  pub fn as_variable(&self) -> Option<&VariableDiff> {
522    match self {
523      DeclarationDefDiff::Variable(d) => Some(d),
524      _ => None,
525    }
526  }
527
528  pub fn as_enum(&self) -> Option<&EnumDiff> {
529    match self {
530      DeclarationDefDiff::Enum(d) => Some(d),
531      _ => None,
532    }
533  }
534
535  pub fn as_class(&self) -> Option<&ClassDiff> {
536    match self {
537      DeclarationDefDiff::Class(d) => Some(d),
538      _ => None,
539    }
540  }
541
542  pub fn as_type_alias(&self) -> Option<&TypeAliasDiff> {
543    match self {
544      DeclarationDefDiff::TypeAlias(d) => Some(d),
545      _ => None,
546    }
547  }
548
549  pub fn as_namespace(&self) -> Option<&NamespaceDiff> {
550    match self {
551      DeclarationDefDiff::Namespace(d) => Some(d),
552      _ => None,
553    }
554  }
555
556  pub fn as_interface(&self) -> Option<&InterfaceDiff> {
557    match self {
558      DeclarationDefDiff::Interface(d) => Some(d),
559      _ => None,
560    }
561  }
562
563  pub fn diff(old: &DeclarationDef, new: &DeclarationDef) -> Option<Self> {
564    match (old, new) {
565      (
566        DeclarationDef::Function(old_def),
567        DeclarationDef::Function(new_def),
568      ) => {
569        FunctionDiff::diff(old_def, new_def).map(DeclarationDefDiff::Function)
570      }
571
572      (
573        DeclarationDef::Variable(old_def),
574        DeclarationDef::Variable(new_def),
575      ) => {
576        VariableDiff::diff(old_def, new_def).map(DeclarationDefDiff::Variable)
577      }
578
579      (DeclarationDef::Enum(old_def), DeclarationDef::Enum(new_def)) => {
580        EnumDiff::diff(old_def, new_def).map(DeclarationDefDiff::Enum)
581      }
582
583      (DeclarationDef::Class(old_def), DeclarationDef::Class(new_def)) => {
584        ClassDiff::diff(old_def, new_def).map(DeclarationDefDiff::Class)
585      }
586
587      (
588        DeclarationDef::TypeAlias(old_def),
589        DeclarationDef::TypeAlias(new_def),
590      ) => {
591        TypeAliasDiff::diff(old_def, new_def).map(DeclarationDefDiff::TypeAlias)
592      }
593
594      (
595        DeclarationDef::Namespace(old_def),
596        DeclarationDef::Namespace(new_def),
597      ) => {
598        NamespaceDiff::diff(old_def, new_def).map(DeclarationDefDiff::Namespace)
599      }
600
601      (
602        DeclarationDef::Interface(old_def),
603        DeclarationDef::Interface(new_def),
604      ) => {
605        InterfaceDiff::diff(old_def, new_def).map(DeclarationDefDiff::Interface)
606      }
607
608      (DeclarationDef::Reference(..), DeclarationDef::Reference(..)) => None,
609
610      _ => unreachable!(),
611    }
612  }
613}