Skip to main content

lockdocs_core/
upgrade.rs

1//! Upgrade report (lockdocs Pro): the API difference between the pinned
2//! version of a package and a target version, limited to the symbols the
3//! project actually uses, with call sites and migration-guide pointers.
4//!
5//! This module only compares and scans; whether the caller may run it is
6//! decided by the binary's licence gate (`crates/lockdocs/src/pro.rs`).
7
8use crate::extract::{Entry, Kind};
9use crate::index::PackageIndex;
10use crate::{norm_name, Eco};
11use serde_json::{json, Value};
12use std::collections::{HashMap, HashSet};
13use std::path::{Path, PathBuf};
14
15/// What happened to a symbol between the two versions.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum Change {
18    Removed,
19    /// Renamed to the `new` entry (matched by signature shape or doc similarity).
20    Renamed,
21    SignatureChanged,
22    Deprecated,
23}
24
25impl Change {
26    pub fn as_str(self) -> &'static str {
27        match self {
28            Change::Removed => "removed",
29            Change::Renamed => "renamed",
30            Change::SignatureChanged => "signature_changed",
31            Change::Deprecated => "deprecated",
32        }
33    }
34}
35
36#[derive(Debug, Clone)]
37pub struct Diff {
38    pub change: Change,
39    pub old: Entry,
40    pub new: Option<Entry>,
41}
42
43/// A place in the project that mentions a changed symbol.
44#[derive(Debug, Clone, PartialEq, Eq)]
45pub struct CallSite {
46    pub path: String,
47    pub line: u32,
48}
49
50fn is_api(e: &Entry) -> bool {
51    e.kind != Kind::Prose && !e.legacy
52}
53
54fn squash(s: &str) -> String {
55    s.split_whitespace().collect::<Vec<_>>().join(" ")
56}
57
58fn parent(path: &str) -> &str {
59    path.rfind(['.', ':']).map_or("", |i| path[..i].trim_end_matches(':'))
60}
61
62/// The signature with the symbol's own name blanked, to compare across renames.
63fn shape(e: &Entry) -> String {
64    squash(&e.sig.replacen(&e.name, "_", 1))
65}
66
67fn deprecated(e: &Entry) -> bool {
68    let doc = e.doc.to_ascii_lowercase();
69    let sig = e.sig.to_ascii_lowercase();
70    doc.contains("@deprecated") || doc.contains("deprecated:") || doc.contains(".. deprecated::") || sig.contains("#[deprecated") || sig.contains("@deprecated")
71}
72
73fn words(s: &str) -> HashSet<String> {
74    s.split(|c: char| !c.is_alphanumeric())
75        .filter(|w| w.len() > 2)
76        .map(str::to_ascii_lowercase)
77        .collect()
78}
79
80fn similarity(a: &str, b: &str) -> f32 {
81    let (a, b) = (words(a), words(b));
82    if a.is_empty() || b.is_empty() {
83        return 0.0;
84    }
85    a.intersection(&b).count() as f32 / a.union(&b).count() as f32
86}
87
88/// Symbol-level difference. A path present in the new version (as a symbol or
89/// as a re-export) is never "removed".
90pub fn diff(old: &[Entry], new: &[Entry]) -> Vec<Diff> {
91    let new_by_path: HashMap<&str, &Entry> = new.iter().filter(|e| is_api(e)).map(|e| (e.path.as_str(), e)).collect();
92    let old_paths: HashSet<&str> = old.iter().filter(|e| is_api(e)).map(|e| e.path.as_str()).collect();
93    let mut added: Vec<&Entry> = new
94        .iter()
95        .filter(|e| is_api(e) && e.alias_of.is_none() && !old_paths.contains(e.path.as_str()))
96        .collect();
97    let mut out = Vec::new();
98    let mut seen = HashSet::new();
99    for o in old.iter().filter(|e| is_api(e)) {
100        if !seen.insert(o.path.as_str()) {
101            continue;
102        }
103        match new_by_path.get(o.path.as_str()) {
104            Some(n) => {
105                if deprecated(n) && !deprecated(o) {
106                    out.push(Diff {
107                        change: Change::Deprecated,
108                        old: o.clone(),
109                        new: Some((*n).clone()),
110                    });
111                } else if o.alias_of.is_none() && n.alias_of.is_none() && squash(&o.sig) != squash(&n.sig) {
112                    out.push(Diff {
113                        change: Change::SignatureChanged,
114                        old: o.clone(),
115                        new: Some((*n).clone()),
116                    });
117                }
118            }
119            None => {
120                // Best rename candidate: same kind and parent, equal signature shape or similar docs.
121                let best = added
122                    .iter()
123                    .enumerate()
124                    .filter(|(_, a)| a.kind == o.kind && parent(&a.path) == parent(&o.path))
125                    .map(|(i, a)| {
126                        let score = if !o.sig.is_empty() && shape(o) == shape(a) {
127                            1.0
128                        } else {
129                            similarity(&o.doc, &a.doc)
130                        };
131                        (i, score)
132                    })
133                    .filter(|(_, s)| *s >= 0.7)
134                    .max_by(|x, y| x.1.total_cmp(&y.1));
135                match best {
136                    Some((i, _)) => {
137                        let n = added.remove(i);
138                        out.push(Diff {
139                            change: Change::Renamed,
140                            old: o.clone(),
141                            new: Some(n.clone()),
142                        });
143                    }
144                    None => out.push(Diff {
145                        change: Change::Removed,
146                        old: o.clone(),
147                        new: None,
148                    }),
149                }
150            }
151        }
152    }
153    out
154}
155
156const SKIP_DIRS: &[&str] = &[
157    "node_modules",
158    "target",
159    ".git",
160    "vendor",
161    "dist",
162    "build",
163    "__pycache__",
164    ".venv",
165    "venv",
166    ".next",
167    "coverage",
168    ".tox",
169    "site-packages",
170];
171const MAX_FILES: usize = 5_000;
172const MAX_FILE_BYTES: u64 = 1024 * 1024;
173
174fn extensions(eco: Eco) -> &'static [&'static str] {
175    match eco {
176        Eco::Npm => &["ts", "tsx", "js", "jsx", "mjs", "cjs", "mts", "cts", "vue", "svelte"],
177        Eco::PyPI => &["py"],
178        Eco::Cargo => &["rs"],
179        Eco::Go => &["go"],
180    }
181}
182
183/// Strings that show a file uses the package.
184fn markers(eco: Eco, name: &str) -> Vec<String> {
185    let mut m = vec![name.to_string()];
186    match eco {
187        Eco::PyPI => {
188            m.push(norm_name(eco, name).replace('-', "_"));
189            m.push(name.replace('-', "_"));
190        }
191        Eco::Cargo => m.push(name.replace('-', "_")),
192        _ => {}
193    }
194    m
195}
196
197fn walk(dir: &Path, exts: &[&str], out: &mut Vec<PathBuf>) {
198    let Ok(rd) = std::fs::read_dir(dir) else { return };
199    let mut entries: Vec<_> = rd.flatten().collect();
200    entries.sort_by_key(|e| e.file_name());
201    for e in entries {
202        if out.len() >= MAX_FILES {
203            return;
204        }
205        let path = e.path();
206        let name = e.file_name().to_string_lossy().to_string();
207        match e.file_type() {
208            Ok(t) if t.is_dir() => {
209                if !SKIP_DIRS.contains(&name.as_str()) && !name.starts_with('.') {
210                    walk(&path, exts, out);
211                }
212            }
213            Ok(t) if t.is_file() => {
214                let ok_ext = path.extension().and_then(|x| x.to_str()).is_some_and(|x| exts.contains(&x));
215                if ok_ext && e.metadata().is_ok_and(|m| m.len() <= MAX_FILE_BYTES) {
216                    out.push(path);
217                }
218            }
219            _ => {}
220        }
221    }
222}
223
224fn is_ident(c: char) -> bool {
225    c.is_alphanumeric() || c == '_' || c == '$'
226}
227
228/// Does `line` use `name` as a whole identifier (members must follow `.` or `::`)?
229fn mentions(line: &str, name: &str, member: bool) -> bool {
230    let mut from = 0;
231    while let Some(i) = line[from..].find(name) {
232        let s = from + i;
233        let e = s + name.len();
234        let before = line[..s].chars().next_back();
235        let after = line[e..].chars().next();
236        let bounded = !before.is_some_and(is_ident) && !after.is_some_and(is_ident);
237        let member_ok = !member || line[..s].ends_with('.') || line[..s].ends_with("::");
238        if bounded && member_ok {
239            return true;
240        }
241        from = e;
242    }
243    false
244}
245
246/// Call sites per old symbol path, found by a textual scan of the project's
247/// source files that mention the package. Not a type-aware analysis: a member
248/// name matches when it follows `.` or `::`.
249pub fn call_sites(root: &Path, eco: Eco, package: &str, symbols: &[&Entry]) -> HashMap<String, Vec<CallSite>> {
250    let mut files = Vec::new();
251    walk(root, extensions(eco), &mut files);
252    let marks = markers(eco, package);
253    let mut found: HashMap<String, Vec<CallSite>> = HashMap::new();
254    for f in files {
255        let Ok(text) = std::fs::read_to_string(&f) else { continue };
256        if !marks.iter().any(|m| text.contains(m.as_str())) {
257            continue;
258        }
259        let rel = f.strip_prefix(root).unwrap_or(&f).to_string_lossy().replace('\\', "/");
260        for (i, line) in text.lines().enumerate() {
261            for s in symbols {
262                if s.name.is_empty() || !mentions(line, &s.name, s.kind == Kind::Method || s.kind == Kind::Field) {
263                    continue;
264                }
265                let v = found.entry(s.path.clone()).or_default();
266                if v.len() < 20 {
267                    v.push(CallSite {
268                        path: rel.clone(),
269                        line: i as u32 + 1,
270                    });
271                }
272            }
273        }
274    }
275    found
276}
277
278fn is_guide(file: &str) -> bool {
279    let base = file.rsplit('/').next().unwrap_or(file).to_ascii_uppercase();
280    ["CHANGELOG", "MIGRAT", "UPGRAD", "BREAKING", "HISTORY", "NEWS"]
281        .iter()
282        .any(|k| base.contains(k))
283}
284
285fn cite(idx: &PackageIndex, e: &Entry) -> String {
286    format!("{}@{} {}:{}", idx.name, idx.version, e.file, e.line)
287}
288
289/// Migration-guide sections of the target version: those that mention the symbol.
290fn guide_for<'a>(idx: &'a PackageIndex, name: &str) -> Vec<&'a Entry> {
291    idx.entries
292        .iter()
293        .filter(|e| e.kind == Kind::Prose && is_guide(&e.file) && !name.is_empty() && mentions(&e.doc, name, false))
294        .take(2)
295        .collect()
296}
297
298fn side(idx: &PackageIndex, e: &Entry) -> Value {
299    json!({"cite": cite(idx, e), "kind": e.kind.as_str(), "signature": squash(&e.sig)})
300}
301
302/// The report: the changes the project is exposed to, the rest as a count.
303pub struct Report {
304    pub text: String,
305    pub json: Value,
306}
307
308pub fn report(root: &Path, old: &PackageIndex, new: &PackageIndex) -> Report {
309    let diffs = diff(&old.entries, &new.entries);
310    let olds: Vec<&Entry> = diffs.iter().map(|d| &d.old).collect();
311    let sites = call_sites(root, old.eco, &old.name, &olds);
312    let mut affected = Vec::new();
313    let mut text = format!(
314        "Upgrade report: {} {} -> {} ({} API changes between the versions)\n",
315        old.name,
316        old.version,
317        new.version,
318        diffs.len()
319    );
320    let mut other = 0;
321    for d in &diffs {
322        let Some(cs) = sites.get(&d.old.path).filter(|c| !c.is_empty()) else {
323            other += 1;
324            continue;
325        };
326        let guide = guide_for(new, &d.old.name);
327        text.push_str(&format!(
328            "\n{} {}\n  was: {}  [{}]\n",
329            d.change.as_str().to_uppercase(),
330            d.old.path,
331            squash(&d.old.sig),
332            cite(old, &d.old)
333        ));
334        if let Some(n) = &d.new {
335            text.push_str(&format!("  now: {}  [{}]\n", squash(&n.sig), cite(new, n)));
336        }
337        text.push_str(&format!(
338            "  call sites: {}\n",
339            cs.iter().map(|c| format!("{}:{}", c.path, c.line)).collect::<Vec<_>>().join(", ")
340        ));
341        for g in &guide {
342            text.push_str(&format!("  migration: {} [{}]\n", g.name, cite(new, g)));
343        }
344        affected.push(json!({
345            "change": d.change.as_str(),
346            "symbol": d.old.path,
347            "old": side(old, &d.old),
348            "new": d.new.as_ref().map(|n| side(new, n)),
349            "call_sites": cs.iter().map(|c| json!({"path": c.path, "line": c.line})).collect::<Vec<_>>(),
350            "migration": guide.iter().map(|g| json!({"section": g.name, "cite": cite(new, g)})).collect::<Vec<_>>(),
351        }));
352    }
353    if affected.is_empty() {
354        text.push_str("\nNo changed API is used in this project's source files.\n");
355    }
356    let guides: Vec<&Entry> = new.entries.iter().filter(|e| e.kind == Kind::Prose && is_guide(&e.file)).take(5).collect();
357    if !guides.is_empty() {
358        text.push_str("\nMigration guide sections in the target version:\n");
359        for g in &guides {
360            text.push_str(&format!("  {} [{}]\n", g.name, cite(new, g)));
361        }
362    }
363    text.push_str(&format!(
364        "\n{other} other API changes are not used in this project. Call sites are textual matches in files that mention the package.\n"
365    ));
366    let json = json!({
367        "package": old.name, "from": old.version, "to": new.version,
368        "api_changes": diffs.len(), "affected": affected, "unaffected_changes": other,
369        "migration_guides": guides.iter().map(|g| json!({"section": g.name, "cite": cite(new, g)})).collect::<Vec<_>>(),
370    });
371    Report { text, json }
372}
373
374#[cfg(test)]
375mod tests {
376    use super::*;
377
378    fn e(kind: Kind, path: &str, sig: &str, doc: &str) -> Entry {
379        Entry {
380            kind,
381            name: path.rsplit(['.', ':']).next().unwrap().to_string(),
382            path: path.into(),
383            file: "index.d.ts".into(),
384            line: 1,
385            sig: sig.into(),
386            doc: doc.into(),
387            alias_of: None,
388            legacy: false,
389            prose_imports: Vec::new(),
390            prose_parents: Vec::new(),
391        }
392    }
393
394    #[test]
395    fn classifies_changes() {
396        let old = vec![
397            e(Kind::Function, "p.gone", "function gone(): void", "Does the thing."),
398            e(
399                Kind::Function,
400                "p.oldName",
401                "function oldName(a: string): number",
402                "Parse a number out of text.",
403            ),
404            e(Kind::Function, "p.sig", "function sig(a: string): void", ""),
405            e(Kind::Function, "p.dep", "function dep(): void", "Fine."),
406            e(Kind::Function, "p.same", "function same(): void", ""),
407            e(Kind::Function, "p.kept", "function kept(): void", ""),
408        ];
409        let mut kept_alias = e(Kind::Alias, "p.kept", "export { kept }", "");
410        kept_alias.alias_of = Some("kept".into());
411        let new = vec![
412            e(
413                Kind::Function,
414                "p.newName",
415                "function newName(a: string): number",
416                "Parse a number out of text.",
417            ),
418            e(Kind::Function, "p.sig", "function sig(a: string, b: number): void", ""),
419            e(Kind::Function, "p.dep", "function dep(): void", "@deprecated use other"),
420            e(Kind::Function, "p.same", "function   same():  void", ""),
421            kept_alias,
422        ];
423        let d = diff(&old, &new);
424        let by = |p: &str| d.iter().find(|x| x.old.path == p).map(|x| x.change);
425        assert_eq!(by("p.gone"), Some(Change::Removed));
426        assert_eq!(by("p.oldName"), Some(Change::Renamed));
427        assert_eq!(d.iter().find(|x| x.old.path == "p.oldName").unwrap().new.as_ref().unwrap().path, "p.newName");
428        assert_eq!(by("p.sig"), Some(Change::SignatureChanged));
429        assert_eq!(by("p.dep"), Some(Change::Deprecated));
430        assert_eq!(by("p.same"), None, "whitespace is not a change");
431        assert_eq!(by("p.kept"), None, "a re-export is not a removal");
432    }
433
434    #[test]
435    fn mentions_respects_boundaries_and_members() {
436        assert!(mentions("z.object({})", "object", true));
437        assert!(!mentions("const objects = 1", "object", false));
438        assert!(!mentions("object(1)", "object", true));
439        assert!(mentions("use x::spawn;", "spawn", true));
440        assert!(mentions("import { oldName } from 'p'", "oldName", false));
441    }
442}