diff --git a/crates/menu/Cargo.toml b/crates/menu/Cargo.toml index b597b9488..1e0f6072d 100644 --- a/crates/menu/Cargo.toml +++ b/crates/menu/Cargo.toml @@ -47,7 +47,9 @@ required-features = ["screen-testing"] # The test reads AppKit's menu bar back and feeds it real events, through safe objc2 calls. [target.'cfg(target_os = "macos")'.dev-dependencies] objc2 = { version = "0.6.4", default-features = false, features = ["std"] } -objc2-app-kit = { version = "0.3.2", default-features = false, features = ["std", "NSApplication", "NSControl", "NSEvent", "NSMenu", "NSMenuItem", "NSResponder"] } +# The event constructors this test calls are gated on `NSGraphicsContext` in objc2-app-kit; +# enabling only `NSEvent` leaves those associated functions unavailable. +objc2-app-kit = { version = "0.3.2", default-features = false, features = ["std", "NSApplication", "NSControl", "NSEvent", "NSGraphicsContext", "NSMenu", "NSMenuItem", "NSResponder"] } objc2-foundation = { version = "0.3.2", default-features = false, features = ["std", "NSDate", "NSGeometry", "NSRunLoop", "NSString"] } [lints] diff --git a/crates/menu/tests/mac_appkit.rs b/crates/menu/tests/mac_appkit.rs index 0fe512b42..2f2966568 100644 --- a/crates/menu/tests/mac_appkit.rs +++ b/crates/menu/tests/mac_appkit.rs @@ -103,7 +103,7 @@ fn main() { .push(Node::Item(Item::new("layer.mergeVisible", "Merge Visible").alternate(Alternate::new(Mods::ALT, "layer.stampVisible")))); } for n in 1..documents { - bar.documents.push(Document::new(format!("doc.{n}"), format!("Untitled-{}", n + 1))); + bar.documents.push(Document::new(CommandRef::new(format!("doc.{n}")), format!("Untitled-{}", n + 1))); } bar }; diff --git a/crates/platform/src/temp.rs b/crates/platform/src/temp.rs index 9ac40da86..e2ece0b3c 100644 --- a/crates/platform/src/temp.rs +++ b/crates/platform/src/temp.rs @@ -121,18 +121,24 @@ fn check_plain(name: &str) -> std::io::Result<()> { /// `is_symlink()` is never true. // cadcraft: crates/ui-egui/src/control.rs:609 is_private_shot_dir pub fn is_private_dir(meta: &Metadata) -> bool { - if !meta.is_dir() || meta.file_type().is_symlink() { - return false; - } - #[cfg(unix)] - { - use std::os::unix::fs::PermissionsExt as _; - meta.permissions().mode() & 0o077 == 0 - } - #[cfg(not(unix))] - { - true - } + // A real directory, so nothing is followed, whose mode grants group and other nothing; the + // mode comes off this same snapshot, never a second stat. + meta.is_dir() && !meta.file_type().is_symlink() && has_private_mode(meta) +} + +/// The Unix half of [`is_private_dir`]: `meta`'s mode has no group or other permission bit. It +/// reads the mode off the same snapshot the caller was given, so it never stats another file. +#[cfg(unix)] +fn has_private_mode(meta: &Metadata) -> bool { + use std::os::unix::fs::PermissionsExt as _; + meta.permissions().mode() & 0o077 == 0 +} + +/// Without Unix mode bits, the documented fallback accepts a real directory once the caller has +/// rejected files and symlinks; this does not inspect or make a claim about platform ACLs. +#[cfg(not(unix))] +fn has_private_mode(_meta: &Metadata) -> bool { + true } /// Temporary folders the app owns until it is done with them: print previews open in the system diff --git a/crates/platform/src/temp_tests.rs b/crates/platform/src/temp_tests.rs index 71684bfae..386589df1 100644 --- a/crates/platform/src/temp_tests.rs +++ b/crates/platform/src/temp_tests.rs @@ -11,6 +11,9 @@ fn private_dir_is_owner_only_and_removed_on_drop() { let path = dir.path().to_path_buf(); assert!(is_private_dir(&std::fs::symlink_metadata(&path).unwrap())); let (file_path, _file) = dir.create("a.txt").unwrap(); + assert_eq!(file_path.file_name(), Some(std::ffi::OsStr::new("a.txt")), "the created path is the plain name, as asked"); + assert_eq!(file_path.parent(), Some(path.as_path()), "the file is created inside the private folder"); + assert!(std::fs::symlink_metadata(&file_path).is_ok(), "the file exists on disk on every platform"); #[cfg(unix)] { use std::os::unix::fs::PermissionsExt as _; diff --git a/crates/ui-contract/src/testing/index.rs b/crates/ui-contract/src/testing/index.rs index 846377d92..063f3c2aa 100644 --- a/crates/ui-contract/src/testing/index.rs +++ b/crates/ui-contract/src/testing/index.rs @@ -1,6 +1,9 @@ //! The components index: every registered component type, grouped by gallery level, with its module and the purpose its derive recorded //! from the doc comment, and every craft-behavior module with the first sentence of its module docs. //! +//! A page is not Rustdoc: an intra-doc link to a qualified Rust path keeps its label and loses its destination, which the +//! page would read as a file beside it (`super::CustomSettings`). +//! //! The generator binary writes `docs/components-index.md` from [`components_index`] over //! `craft_ui::testing::library_registrations()`; a trial of craft-ui compares the two. @@ -9,12 +12,71 @@ use std::path::{Path, PathBuf}; use crate::contract::{Level, Registration, catalog}; -/// The first sentence of the first paragraph of `lines`, without its final full stop, safe inside a table cell. +/// The first sentence of the first paragraph of `lines`, without its final full stop, as a table cell. fn purpose(lines: &[&str]) -> String { let paragraph: Vec<&str> = lines.iter().map(|line| line.trim()).take_while(|line| !line.is_empty()).collect(); let text = paragraph.join(" "); let sentence = text.split_once(". ").map_or(text.as_str(), |(first, _)| first); - sentence.trim_end_matches('.').replace('|', "\\|") + cell_text(sentence.trim_end_matches('.')) +} + +/// `text` as one Markdown table cell: `|` escaped so it does not end the cell, and an intra-doc link to a qualified Rust +/// path kept as its label alone, which the page would otherwise read as a file beside it. +/// +/// A destination's own parentheses are counted, so a URL keeps them and a method link ends with the call's `()`. +fn cell_text(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + // `copied` is where `out` has reached in `text`; `at` is where the next link starts being looked for. + let (mut copied, mut at) = (0, 0); + while let Some(bracket) = text[at..].find('[').map(|open| at + open) { + let label_start = bracket + 1; + let Some(label_end) = text[label_start..].find(']').map(|close| label_start + close) else { break }; + // Only `[label](destination)` is a link; a bracketed label on its own is the doc comment's own text. + if !text[label_end + 1..].starts_with('(') { + at = label_end + 1; + continue; + } + // A destination may hold its own parentheses, so it ends where they balance. + let Some(close) = closing_paren(text, label_end + 1) else { break }; + if is_rust_path(&text[label_end + 2..close]) { + out.push_str(&text[copied..bracket]); + out.push_str(&text[label_start..label_end]); + copied = close + 1; + } + at = close + 1; + } + out.push_str(&text[copied..]); + out.replace('|', "\\|") +} + +/// The index of the `)` that closes the `(` at `open`, counting the parentheses inside it: a URL holds its own +/// (`…/Rust_(programming_language)`) and a method's destination ends with the call's `()`. +fn closing_paren(text: &str, open: usize) -> Option { + let mut depth = 0usize; + for (at, character) in text[open..].char_indices() { + match character { + '(' => depth += 1, + ')' if depth == 1 => return Some(open + at), + ')' => depth = depth.saturating_sub(1), + _ => {} + } + } + None +} + +/// Whether `destination` is a qualified Rust path, as a doc comment's intra-doc link writes one: `super::CustomSettings`, +/// `ParamDialog::previews`, `Self::extent()`. +/// +/// Only a qualified path is flattened. `Canvas` and `README` are written the same way, and an extensionless destination is +/// more likely a file beside the page, so one without `::` stays a link. +fn is_rust_path(destination: &str) -> bool { + // A segment is a name, a type's name before its arguments, or a method's call. + let is_segment = |segment: &str| { + let name = segment.trim_end_matches("()").split('<').next().unwrap_or(segment); + !name.is_empty() && name.chars().all(|character| character.is_ascii_alphanumeric() || character == '_') + }; + let segments: Vec<&str> = destination.trim().split("::").collect(); + segments.len() > 1 && segments.iter().all(|segment| is_segment(segment)) } fn table_row(cells: &[&str]) -> String { @@ -59,7 +121,7 @@ fn registered_rows(registered: &[&'static Registration]) -> Vec { name: entry.name.clone(), shape: format!("{:?}", probe.shape), module: probe.module.to_owned(), - purpose: probe.purpose.replace('|', "\\|"), + purpose: cell_text(probe.purpose), }); } if let Some(probe) = entry.registration.pattern_probe() { @@ -68,7 +130,7 @@ fn registered_rows(registered: &[&'static Registration]) -> Vec { name: entry.name.clone(), shape: probe.kind.label().to_owned(), module: probe.module.to_owned(), - purpose: probe.purpose.replace('|', "\\|"), + purpose: cell_text(probe.purpose), }); } } diff --git a/crates/ui/tests/it/components_index.rs b/crates/ui/tests/it/components_index.rs index e932828e1..922928958 100644 --- a/crates/ui/tests/it/components_index.rs +++ b/crates/ui/tests/it/components_index.rs @@ -24,3 +24,69 @@ fn the_level_tables_name_only_registered_types_and_story_groups() { let stale = stale_table_rows(&library_registrations()); assert!(stale.is_empty(), "stale level table rows: {stale:#?}"); } + +/// A scratch workspace contains only this trial's behaviour docs, never a user's settings or files. +struct Scratch(std::path::PathBuf); + +impl Scratch { + fn new() -> Self { + let base = Path::new(env!("CARGO_TARGET_TMPDIR")); + std::fs::create_dir_all(base).expect("the test target's temporary directory exists"); + for attempt in 0..32 { + let path = base.join(format!("components-index-links-{}-{attempt}", std::process::id())); + match std::fs::create_dir(&path) { + Ok(()) => return Self(path), + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => continue, + Err(error) => panic!("create private scratch directory {path:?}: {error}"), + } + } + panic!("no unused components-index scratch directory"); + } +} + +impl Drop for Scratch { + fn drop(&mut self) { + let _ = std::fs::remove_dir_all(&self.0); + } +} + +/// Generated Markdown keeps valid reader-facing links, but a qualified Rustdoc target is rendered as its label. +#[trial] +fn purpose_links_keep_web_files_and_anchors_but_not_rustdoc_paths() { + let scratch = Scratch::new(); + let modules = scratch.0.join("crates/behavior/src"); + std::fs::create_dir_all(&modules).expect("scratch behaviour modules"); + let cases = [ + ("the view of the [`Canvas`](super::Canvas)", "the view of the `Canvas`"), + ("when it [`previews`](ParamDialog::previews)", "when it `previews`"), + ("the [`extent`](Self::extent()) it has", "the `extent` it has"), + ("the [`Rust`](https://example.com/wiki/Rust_(language)) book", "the [`Rust`](https://example.com/wiki/Rust_(language)) book"), + ("the [guide](README)", "the [guide](README)"), + ("the [licence](LICENSE)", "the [licence](LICENSE)"), + ("the [guide](docs/guide.md)", "the [guide](docs/guide.md)"), + ("the [note](#anchor)", "the [note](#anchor)"), + ("a | b", r"a \| b"), + ("a [`x`](super::X", "a [`x`](super::X"), + ("a [`Param`]", "a [`Param`]"), + ("the [bare](Canvas)", "the [bare](Canvas)"), + ]; + for (index, (source, _)) in cases.iter().enumerate() { + std::fs::write(modules.join(format!("case_{index}.rs")), format!("//! {source}\n")).expect("write one owned scratch module"); + } + let index = components_index(&scratch.0, &[]); + for (number, (_, expected)) in cases.iter().enumerate() { + assert!( + index.contains(&format!("| `craft_behavior::case_{number}` | {expected} |")), + "case {number} did not preserve its reader-facing text: {index}" + ); + } +} + +/// A Rustdoc target is not a file beside this page. Exercise the actual library registrations as well as the fixture. +#[trial] +fn purpose_links_in_the_real_index_have_no_rustdoc_destinations() { + let root = Path::new(env!("CARGO_MANIFEST_DIR")).join("../.."); + let index = components_index(&root, &library_registrations()); + let targets: Vec<_> = index.split("](").skip(1).filter_map(|rest| rest.split(')').next()).filter(|target| target.contains("::")).collect(); + assert!(targets.is_empty(), "the rendered index still links qualified Rust paths: {targets:?}"); +} diff --git a/crates/update/src/detect/macos.rs b/crates/update/src/detect/macos.rs index 65a6b0227..af78dcea0 100644 --- a/crates/update/src/detect/macos.rs +++ b/crates/update/src/detect/macos.rs @@ -14,6 +14,8 @@ pub fn candidates(app: &App) -> Vec { out } +/// The first of [`candidates`]' folders that holds a bundle of this app, read as [`read_bundle`] +/// reads it. pub fn detect(app: &App) -> Option { candidates(app).iter().find_map(|p| read_bundle(app, p)) } diff --git a/crates/update/src/install/macos.rs b/crates/update/src/install/macos.rs index e9a134f9c..b467d4481 100644 --- a/crates/update/src/install/macos.rs +++ b/crates/update/src/install/macos.rs @@ -50,6 +50,8 @@ pub struct Expect<'a> { } impl<'a> Expect<'a> { + /// What a release's own app must prove before it replaces an installed one: a Developer ID + /// signature by [`TEAM_ID`], the release's version, and that the installed app has quit. pub fn release(release: &'a Release) -> Self { Self { team: Some(TEAM_ID), version: release.version.as_ref(), quit_first: true } } @@ -72,7 +74,11 @@ static SIGNATURE_CHECKS: Queue = Queue::new(); /// How a job waits for its turn at the signature check: `phase` hears of the wait, and `stop` /// can cancel it. pub struct CheckTurn<'a> { + /// Whether the job was cancelled, asked again while the check waits for its turn; a cancelled + /// check doesn't run. pub stop: &'a Stop, + /// Hears of the wait ([`JobPhase::Waiting`]), then of the check itself + /// ([`JobPhase::Installing`]). pub phase: &'a mut dyn FnMut(JobPhase), } @@ -85,6 +91,11 @@ const CODESIGN: &str = "/usr/bin/codesign"; /// Stops a `codesign` that hangs. const CODESIGN_TIMEOUT: Duration = Duration::from_secs(600); +/// Installs the app from a release's `dmg`: attaches it at a fresh mount point in `paths.cache`, +/// checks the app inside against `expect`, and copies it into place over `existing` (else into +/// `destination`, else `/Applications` or `~/Applications`). `replace` allows replacing a copy +/// this launcher didn't install, and `wait` hears of the signature check's turn. Returns the +/// installed bundle, with the image detached again. #[allow(clippy::too_many_arguments)] pub fn install_dmg( app: &App, diff --git a/crates/update/src/self_update.rs b/crates/update/src/self_update.rs index cba25ab86..63fd10749 100644 --- a/crates/update/src/self_update.rs +++ b/crates/update/src/self_update.rs @@ -34,6 +34,7 @@ use crate::{InstallSource, Installed}; use crate::http::{Http, Stop}; use crate::install::{self, Job}; use crate::paths::Paths; +#[cfg(any(windows, target_os = "linux"))] use crate::process; /// How this running launcher was installed. diff --git a/crates/update/src/self_update/detect.rs b/crates/update/src/self_update/detect.rs index 5268ec3d7..af85b09bd 100644 --- a/crates/update/src/self_update/detect.rs +++ b/crates/update/src/self_update/detect.rs @@ -2,7 +2,9 @@ #[cfg(windows)] use super::helper::is_own_executable; -use super::{App, Install, PackageKind, Path, PathBuf, Paths, Platform, Release, Version, pick_asset, process, version}; +use super::{App, Install, Path, PathBuf, Paths, Platform, Release, Version, pick_asset, version}; +#[cfg(target_os = "linux")] +use super::{PackageKind, process}; /// Makes an installed copy believe it's this version, to try the self-update against the current /// release. The restart helper drops it, so it lasts one run. diff --git a/crates/window/src/desktop.rs b/crates/window/src/desktop.rs index 599cd3772..f49fc6d45 100644 --- a/crates/window/src/desktop.rs +++ b/crates/window/src/desktop.rs @@ -67,11 +67,11 @@ pub fn theme_svgs(theme: &str, icons: [&str; N]) -> [Option Option { let mut inside = false; @@ -25,7 +25,7 @@ pub(crate) fn ini_value(text: &str, section: &str, key: &str) -> Option None } -#[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd", test))] +#[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd"))] /// KWin's button order (`[org.kde.kdecoration2]` `ButtonsOnLeft` / `ButtonsOnRight`, one letter a /// button: `I` minimize, `A` maximize, `X` close) as a GTK layout string. Missing keys keep KWin's /// defaults: the window menu on the left, minimize, maximize and close on the right. @@ -46,7 +46,7 @@ pub(crate) fn kwin_layout(kwinrc: &str) -> String { format!("{}:{}", side("ButtonsOnLeft", "MS"), side("ButtonsOnRight", "HIAX")) } -#[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd", test))] +#[cfg(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd", target_os = "netbsd"))] /// The `gtk-decoration-layout` and `gtk-theme-name` of a GTK 3 `settings.ini`. pub(crate) fn gtk_settings(settings_ini: &str) -> (Option, Option) { (ini_value(settings_ini, "Settings", "gtk-decoration-layout"), ini_value(settings_ini, "Settings", "gtk-theme-name")) @@ -219,7 +219,7 @@ pub(crate) fn read_gtk_theme(var: &dyn Fn(&str) -> Option) -> Option String { diff --git a/docs/components-index.md b/docs/components-index.md index ebd99db9f..6bdea003e 100644 --- a/docs/components-index.md +++ b/docs/components-index.md @@ -26,7 +26,7 @@ Grouped by gallery level, then shape, then name. | `Pasteboard` | Leaf | `craft_ui_canvas::canvas::pasteboard` | The pasteboard and page frames under a document | | `Picture` | Leaf | `craft_ui_widgets::display::picture` | A picture of an image the caller makes (`new`) or of what a content painter paints (`painter`); both sit in a rect of the same token sizes | | `PixelGrid` | Leaf | `craft_ui_canvas::canvas_controls::pixel_grid` | The pixel grid over a raster document | -| `RasterDisplay` | Leaf | `craft_ui_canvas::canvas::raster` | The document display of one canvas: the document drawn through the view of the [`Canvas`](super::Canvas) it is shown in, at the canvas rect | +| `RasterDisplay` | Leaf | `craft_ui_canvas::canvas::raster` | The document display of one canvas: the document drawn through the view of the `Canvas` it is shown in, at the canvas rect | | `RotateView` | Leaf | `craft_ui_canvas::canvas::rotate` | The compass of a turned view: a dial whose needle points where the document's up lies on screen | | `Rulers` | Leaf | `craft_ui_canvas::canvas::rulers` | The rulers of a canvas: ticks and labels counted from a zero point, level whatever the view's rotation, a pointer marker, the guide drag-out and the zero point's corner | | `SelectionOutline` | Leaf | `craft_ui_canvas::canvas_controls::outline` | Highlights over the selected shapes, in the host's colour (a layer's colour), else the overlay line colour | @@ -194,11 +194,11 @@ Grouped by gallery level, then shape, then name. | `OutputPathRow` | Pattern | `craft_ui_patterns::patterns::form_dialogs::export::path_row` | "Output To", a list of name templates (`[Comp Name].[fileExtension]`) and the resulting file name as a link, for render queues and export dialogs (After Effects' Render Queue) | | `PaneArea` | Pattern | `craft_ui_patterns::patterns::dock::panes` | The app's side panes, bottom panes and floating panes around its document | | `PanelMenu` | Pattern | `craft_ui_widgets::menu::panel` | The rows of one panel's menu: the host's rows, a separator, then the dock's rows | -| `ParamDialog` | Pattern | `craft_ui_patterns::patterns::form_dialogs::dialog` | A dialog from a parameter list: one row per [`Param`], the Preview check box when it [`previews`](ParamDialog::previews), with a preview pane when the host gives a picture, and OK, Cancel, extra buttons and a footer note | +| `ParamDialog` | Pattern | `craft_ui_patterns::patterns::form_dialogs::dialog` | A dialog from a parameter list: one row per [`Param`], the Preview check box when it `previews`, with a preview pane when the host gives a picture, and OK, Cancel, extra buttons and a footer note | | `ParamRows` | Pattern | `craft_ui_patterns::patterns::form_dialogs::rows` | The rows of a parameter list: a group of one labelled field per visible [`Param`], the control chosen by its [`ParamKind`], in a panel the host lays out or inside a dialog | | `PasswordDialog` | Pattern | `craft_ui_patterns::patterns::form_dialogs::password` | A question with a lock icon, the message, the masked field and the buttons | | `PathRow` | Pattern | `craft_ui_patterns::patterns::form_dialogs::path_row` | A text field with the path, taking the row's room, and a Browse button after it, for a row whose enclosing `Field` shows the label | -| `PathSetting` | Pattern | `craft_ui_patterns::patterns::preferences::path_setting` | A path setting for a custom row or page of Preferences ([`CustomSettings`](super::CustomSettings)): the label, then a text field with the path and a Browse… button, over the draft value at `key` | +| `PathSetting` | Pattern | `craft_ui_patterns::patterns::preferences::path_setting` | A path setting for a custom row or page of Preferences (`CustomSettings`): the label, then a text field with the path and a Browse… button, over the draft value at `key` | | `PdfExportDialog` | Pattern | `craft_ui_patterns::patterns::form_dialogs::pdf_export` | File > Save as PDF: a preset row, Standard and Compatibility, and a list of sections (General, Compression, Marks and Bleeds, Output, Advanced, Security and Summary) beside the shown section | | `PreferencesWindow` | Pattern | `craft_ui_patterns::patterns::preferences::window` | The preferences window: a search field over a page list and the shown page, with OK, Cancel and Apply under them | | `PresetBrowser` | Pattern | `craft_ui_patterns::patterns::presets::browser` | A library of named presets shown as thumbnails |