From 59a9125d7b0156988f718335b950c092c2e343a9 Mon Sep 17 00:00:00 2001 From: smittie2000 Date: Tue, 27 Oct 2026 18:42:56 +0200 Subject: [PATCH] craft-update: doc comments for the functions and tests this PR touches CodeRabbit's docstring check counted 76% of the functions this PR touches as documented, below its 80% threshold. install_at, the Linux detect, linux_location and three tests had none. Co-Authored-By: Claude Opus 5.5 --- crates/update/src/install.rs | 7 +++++++ crates/update/src/release.rs | 4 ++++ crates/update/src/self_update.rs | 4 ++++ 3 files changed, 15 insertions(+) diff --git a/crates/update/src/install.rs b/crates/update/src/install.rs index 3e3bcfcc2..6f5077af0 100644 --- a/crates/update/src/install.rs +++ b/crates/update/src/install.rs @@ -58,6 +58,11 @@ pub fn install( type RecordCommit<'a> = Option<&'a mut dyn FnMut(&Record) -> Result<(), String>>; +/// [`install`], with `commit` called once a portable ZIP's new files are in place and its version +/// checked, so the caller can save its record; an error from it rolls the previous copy back +/// (Windows only; ignored elsewhere). Refuses before downloading when the app is running, the +/// asset isn't the release's version (`bind_artifact_version`), a newer copy is installed, or the +/// link isn't the release's own (`check_download_link`). #[allow(clippy::too_many_arguments)] pub fn install_at( app: &App, @@ -2615,6 +2620,8 @@ mod tests { assert!(result.unwrap_err().contains("installed version 0.5.0 is newer")); } + /// An asset whose file name, link tag or link file name isn't the release's is refused before + /// the download, and so is one in another app's releases or with a foreign `SHA256SUMS.txt`. #[test] fn install_rejects_an_artifact_whose_version_is_not_the_advertised_one() { // The release advertises 99.0.0, but the selected artifact is an older official build diff --git a/crates/update/src/release.rs b/crates/update/src/release.rs index 48216a76c..1939539a7 100644 --- a/crates/update/src/release.rs +++ b/crates/update/src/release.rs @@ -439,6 +439,8 @@ mod tests { } } + /// A link that shares the download prefix as text but climbs into another repository with `..` + /// or an encoded separator or dot isn't under it. #[test] fn traversal_cannot_escape_the_repository() { // Raw-prefix matches but the interpreted path climbs into another repository (CWE-180). @@ -476,6 +478,8 @@ mod tests { assert_eq!(parse_github_release_list("[]", REPO, false).unwrap(), None); } + /// `SHA256SUMS.txt` lines, the tag in a `releases/latest` redirect, and the release built from + /// both; malformed lines, traversing names and `.`/`..` tags are dropped. #[test] fn reads_checksums_and_redirects() { let sums = parse_sha256sums(&format!("{HASH} photocraft-0.5.0-macos-universal.dmg\n{HASH} *b.zip\nnot a line\n{HASH} ../escape\n")); diff --git a/crates/update/src/self_update.rs b/crates/update/src/self_update.rs index 18fc2cf30..861557730 100644 --- a/crates/update/src/self_update.rs +++ b/crates/update/src/self_update.rs @@ -214,6 +214,9 @@ fn msi_install_dir(app: &App) -> Option { (!dir.is_empty()).then(|| PathBuf::from(dir)) } +/// How the running copy at `exe` was installed on Linux, or `None` when it isn't this app's to +/// update: a Flatpak bundle installed per user, an AppImage, the deb/rpm/Arch package at +/// `/usr/bin/`, or a standalone copy outside the package managers' folders ([`linux_location`]). #[cfg(target_os = "linux")] fn detect(app: &App, exe: &Path) -> Option { if process::in_sandbox() { @@ -263,6 +266,7 @@ enum LinuxLocation { Elsewhere, } +/// Which [`LinuxLocation`] `exe` is in, from its path alone. #[cfg_attr(not(target_os = "linux"), allow(dead_code))] fn linux_location(app: &App, exe: &Path) -> LinuxLocation { if exe == Path::new("/usr/bin").join(app.id) {