Skip to content

armgit / peel

Public Imported from GitHub
0

Uninstall Mac apps with every file they leave behind, and see why each belongs. Free up space, fine-tune macOS, and set up Terminal.

Comments say only what the code can't

Țugui Dragoșb71a8df87137
diff --git a/Packages/PeelCore/Sources/PeelCommandLine/Commands/AppCommands.swift b/Packages/PeelCore/Sources/PeelCommandLine/Commands/AppCommands.swift
index c0c3f73e..991dc0e7 100644
--- a/Packages/PeelCore/Sources/PeelCommandLine/Commands/AppCommands.swift
+++ b/Packages/PeelCore/Sources/PeelCommandLine/Commands/AppCommands.swift
@@ -85,7 +85,6 @@ struct LeftoversCommand: AsyncParsableCommand {
/// finds the key.
let appSize: Int64?
let leftovers: [LeftoverRecord]
- /// The folders macOS kept Peel out of, where the app may have left more.
let unreadableLocations: [String]
init(app: InstalledApp, appSize: Int64?, leftovers: [Leftover], unreadableLocations: [SearchLocation]) {
@@ -213,13 +212,12 @@ struct UninstallCommand: AsyncParsableCommand {
@OptionGroup var output: OutputOptions
- /// What `--json` writes once the command is done: each item and why it stays when it does, then, unless it
- /// was a dry run, what moved and what failed, and why.
+ /// What `--json` writes once the command is done.
struct Report: Encodable {
struct Item: Encodable {
let path: String
let size: MeasuredSize
- /// Why the item stays where it is, in the words `peel history --refused` uses, or `null` when it moves.
+ /// Why the item stays, in the words `peel history --refused` uses, or `null` when it moves.
let stays: String?
private enum CodingKeys: String, CodingKey {
@@ -260,12 +258,10 @@ struct UninstallCommand: AsyncParsableCommand {
let items: [Item]
let moved: [String]
let failed: [Failure]
- /// Whether the privacy permissions were reset, or `null` when that wasn't done: not asked for, or a dry run.
+ /// Whether the privacy permissions were reset, or `null` when that wasn't asked for or it was a dry run.
let privacyReset: Bool?
- /// The leftovers that stay because they need administrator access, and those left for review.
let needsAdministrator: Int
let needsReview: Int
- /// The folders macOS kept Peel out of, where the app may have left more.
let unreadableLocations: [String]
private enum CodingKeys: String, CodingKey {
diff --git a/Packages/PeelCore/Sources/PeelCommandLine/Commands/FileCommands.swift b/Packages/PeelCore/Sources/PeelCommandLine/Commands/FileCommands.swift
index f76172dd..eb0efe1f 100644
--- a/Packages/PeelCore/Sources/PeelCommandLine/Commands/FileCommands.swift
+++ b/Packages/PeelCore/Sources/PeelCommandLine/Commands/FileCommands.swift
@@ -16,7 +16,7 @@ struct OrphansCommand: AsyncParsableCommand {
@OptionGroup var output: OutputOptions
- /// What `--json` writes: the groups, and the folders macOS kept Peel out of, where there may be more.
+ /// What `--json` writes.
struct Report: Encodable {
let groups: [Group]
let unreadableLocations: [String]
@@ -336,15 +336,14 @@ struct ProjectsCommand: AsyncParsableCommand {
Self.notes(for: scan).forEach(Output.note)
}
- /// What `--json` writes: the build output, and the chosen folders macOS kept Peel out of, where there may be
- /// more.
+ /// What `--json` writes.
struct Report: Encodable {
let artifacts: [Record]
let unreadableLocations: [String]
}
- /// What the scan couldn't look at, said on standard error whatever the output, so that "Nothing built was
- /// found" or an empty list is not read as folders with nothing built in them.
+ /// What the scan couldn't look at, said on standard error whatever the output, so that an empty answer is not
+ /// read as nothing being there.
static func notes(for scan: ProjectArtifacts.Scan) -> [String] {
var notes: [String] = []
if !scan.unreadableLocations.isEmpty {
@@ -453,8 +452,8 @@ struct DuplicatesCommand: AsyncParsableCommand {
struct Found: Encodable {
let folders: [FolderRecord]
let files: [Record]
- /// Folders macOS kept Peel out of, and chosen folders it didn't look in: there may be duplicates there.
let unreadableLocations: [String]
+ /// Chosen folders the scan didn't look in.
let skippedLocations: [String]
}
@@ -506,8 +505,8 @@ struct DuplicatesCommand: AsyncParsableCommand {
Self.notes(for: scan).forEach(Output.note)
}
- /// What the scan didn't look at, said on standard error whatever the output, so that "No duplicates found."
- /// or an empty list is not read as a folder without any.
+ /// What the scan didn't look at, said on standard error whatever the output, so that an empty answer is not
+ /// read as nothing being there.
static func notes(for scan: DuplicateScan) -> [String] {
var notes: [String] = []
if !scan.unreadableLocations.isEmpty {
diff --git a/Packages/PeelCore/Sources/PeelCommandLine/Support/Output.swift b/Packages/PeelCore/Sources/PeelCommandLine/Support/Output.swift
index 9b4ee242..81446fc3 100644
--- a/Packages/PeelCore/Sources/PeelCommandLine/Support/Output.swift
+++ b/Packages/PeelCore/Sources/PeelCommandLine/Support/Output.swift
@@ -106,8 +106,7 @@ enum Output {
write(paddedCells(rows).map { indent + $0 + "\n" }.joined())
}
- /// Returns each row as one line, every cell made `plain` and every cell but the last padded to its column's
- /// width in terminal cells.
+ /// The rows of `table`, one line each, padded in terminal cells.
static func paddedCells(_ rows: [[String]]) -> [String] {
let rows = rows.map { $0.map(plain) }
let locale = newlocale(LC_CTYPE_MASK, "UTF-8", nil)
@@ -123,8 +122,7 @@ enum Output {
}
}
- /// The terminal cells `text` takes: two for a character drawn as an emoji or as a wide East Asian one, none
- /// for a mark that combines with the character before it, and one for anything else.
+ /// The terminal cells `text` takes: two for an emoji or a wide East Asian character, none for a combining mark.
static func cells(_ text: String, in locale: locale_t?) -> Int {
text.reduce(0) { total, character in
let scalars = character.unicodeScalars
diff --git a/Packages/PeelCore/Sources/PeelCore/Apps/DefaultApps.swift b/Packages/PeelCore/Sources/PeelCore/Apps/DefaultApps.swift
index 93557238..241620bc 100644
--- a/Packages/PeelCore/Sources/PeelCore/Apps/DefaultApps.swift
+++ b/Packages/PeelCore/Sources/PeelCore/Apps/DefaultApps.swift
@@ -13,8 +13,8 @@ public struct DefaultRole: Sendable, Hashable, Identifiable {
public let kind: Kind
/// The uniform type identifier, or the scheme without its colon.
public let identifier: String
- /// What a kind of file is called, such as "PDF document", or what the app calls it when macOS has no name for
- /// it. For a link, the scheme and its colon, which the app replaces with its own words.
+ /// What a kind of file is called, such as "PDF document". For a link, the scheme and its colon, which the app
+ /// replaces with its own words.
public let name: String
/// The apps that could take over, best first, without this one.
public let others: [String]
@@ -67,9 +67,8 @@ public enum DefaultApps {
}
}
- /// What a kind of file is called. A type macOS made up from an extension that no app registers has no
- /// description, and Finder calls such a file by the name the app that opens it gives that kind of document, in
- /// the app's own translation. Without one, the extension says more than Finder's "Document".
+ /// What a kind of file is called: macOS's description, or, for a type no app registers, the name the app that
+ /// opens it gives that kind of document, as Finder does, or else its extension.
static func name(of type: UTType, calledByTheApp appName: String?, in bundle: Bundle?) -> String {
if let description = type.localizedDescription { return description }
if let appName {
diff --git a/Packages/PeelCore/Sources/PeelCore/BackgroundItems/BackgroundItems.swift b/Packages/PeelCore/Sources/PeelCore/BackgroundItems/BackgroundItems.swift
index d7dcd81f..8cc3430d 100644
--- a/Packages/PeelCore/Sources/PeelCore/BackgroundItems/BackgroundItems.swift
+++ b/Packages/PeelCore/Sources/PeelCore/BackgroundItems/BackgroundItems.swift
@@ -68,8 +68,7 @@ public enum BackgroundItems {
}.sorted { $0.label < $1.label }
}
- /// What `launchctl` reports right now: the loaded jobs, with the process ID of each one running, and the
- /// jobs marked disabled or enabled. Each is nil when `launchctl` answered in a form Peel cannot read.
+ /// What `launchctl` reports right now. Each part is nil when `launchctl` answered in a form Peel cannot read.
struct Loaded {
var user: [String: Int32?]? = [:]
var system: [String: Int32?]? = [:]
diff --git a/Packages/PeelCore/Sources/PeelCore/BackgroundItems/Launchctl.swift b/Packages/PeelCore/Sources/PeelCore/BackgroundItems/Launchctl.swift
index 941b5487..82933705 100644
--- a/Packages/PeelCore/Sources/PeelCore/BackgroundItems/Launchctl.swift
+++ b/Packages/PeelCore/Sources/PeelCore/BackgroundItems/Launchctl.swift
@@ -21,7 +21,7 @@ enum Launchctl {
}
/// Parses `launchctl list`: "PID\tStatus\tLabel", where PID is "-" for jobs that aren't running. Nil when the
- /// output does not start with that header: `launchctl`'s output can change, and another form says nothing.
+ /// output does not start with that header, since another form says nothing.
static func parseList(_ output: String) -> [String: Int32?]? {
let lines = output.split(whereSeparator: \.isNewline)
guard lines.first == "PID\tStatus\tLabel" else { return nil }
diff --git a/Packages/PeelCore/Sources/PeelCore/Home/FoundLastTime.swift b/Packages/PeelCore/Sources/PeelCore/Home/FoundLastTime.swift
index b72dec74..f8b1975f 100644
--- a/Packages/PeelCore/Sources/PeelCore/Home/FoundLastTime.swift
+++ b/Packages/PeelCore/Sources/PeelCore/Home/FoundLastTime.swift
@@ -1,9 +1,7 @@
public import Foundation
-/// What each tool found the last time it looked, kept so Home can say it after Peel is opened again.
-///
-/// A tool is named by the app. A finding is how many things the tool found, their size when the tool measures
-/// them, and when it looked. A tool that finds nothing leaves the list.
+/// What each tool found the last time it looked, kept so Home can say it after Peel is opened again. The app names
+/// the tools.
public struct FoundLastTime: Sendable, Equatable {
public struct Finding: Sendable, Equatable {
public let count: Int
@@ -22,8 +20,7 @@ public struct FoundLastTime: Sendable, Equatable {
public init() {}
- /// Reads what `data` holds. Any process can write an app's preferences, so an entry that makes no sense
- /// is left out, and the others are kept.
+ /// Reads what `data` holds, leaving out an entry that makes no sense: any process can write an app's preferences.
public init(data: Data?) {
guard let data, let entries = try? JSONDecoder().decode([String: Entry].self, from: data) else { return }
for (tool, entry) in entries {
diff --git a/Packages/PeelCore/Sources/PeelCore/Leftovers/LeftoverScanner.swift b/Packages/PeelCore/Sources/PeelCore/Leftovers/LeftoverScanner.swift
index acde7390..61550cf1 100644
--- a/Packages/PeelCore/Sources/PeelCore/Leftovers/LeftoverScanner.swift
+++ b/Packages/PeelCore/Sources/PeelCore/Leftovers/LeftoverScanner.swift
@@ -21,9 +21,8 @@ public struct LeftoverScanner: Sendable {
static let walk: Measure = { await FileSize.contents(of: $0) }
- /// For tests, which say how each folder answers instead of waiting out the budget, and can count what the
- /// guard is asked. They leave out Launch Services, whose answers depend on what is installed on the Mac
- /// running them.
+ /// For tests, which say how each folder answers and can count what the guard is asked. They leave out Launch
+ /// Services, whose answers depend on what is installed on the Mac running them.
init(
environment: SearchEnvironment,
exclusions: Exclusions = .none,
@@ -267,9 +266,9 @@ public struct LeftoverScanner: Sendable {
///
/// In the home folder and at the top of a Library, the app's name alone is weak evidence: a hidden `~/.jotter`
/// can belong to a command-line tool of the same name rather than to the Jotter app, and hold work that exists
- /// nowhere else. This is decided here and not
- /// in the matcher, because `nested(in:)` takes an item only on strong evidence, and weaker evidence would
- /// drop items such as `~/.config/zed` from the scan instead of showing them unselected.
+ /// nowhere else. This is decided here and not in the matcher, because `nested(in:)` takes an item only on strong
+ /// evidence, and weaker evidence would drop items such as `~/.config/zed` from the scan instead of showing them
+ /// unselected.
private static func heldBack(
_ match: LeftoverMatch,
in kind: SearchLocation.Kind,
diff --git a/Packages/PeelCore/Sources/PeelCore/Packages/PackageReceipts.swift b/Packages/PeelCore/Sources/PeelCore/Packages/PackageReceipts.swift
index b4f00c90..24f50838 100644
--- a/Packages/PeelCore/Sources/PeelCore/Packages/PackageReceipts.swift
+++ b/Packages/PeelCore/Sources/PeelCore/Packages/PackageReceipts.swift
@@ -85,10 +85,10 @@ public enum PackageReceipts {
await receipts(installing: url, exclusions: exclusions, pkgutil: pkgutil)
}
- /// `pkgutil --file-info-plist` matches a path against the receipt's file list, which is relative to the package's
- /// install location. With the install location `Applications`, an app is found as `/Example.app`, not as
- /// `/Applications/Example.app`. So the leading folders are dropped one at a time until a package answers,
- /// and the answer counts only if that package really installed this path.
+ /// `pkgutil --file-info-plist` matches a path against the receipt's file list, which is relative to the
+ /// package's install location: with the install location `Applications`, an app is found as `/Example.app`. So
+ /// the leading folders are dropped one at a time until a package answers, and the answer counts only if that
+ /// package really installed this path.
@concurrent
static func receipts(installing url: URL, exclusions: Exclusions, pkgutil: @escaping Pkgutil) async -> [PackageReceipt] {
let wanted = PathPattern.comparablePath(of: PathPattern.canonical(url))
diff --git a/Packages/PeelCore/Sources/PeelCore/Search/FileSearch.swift b/Packages/PeelCore/Sources/PeelCore/Search/FileSearch.swift
index ca20f189..fde7b493 100644
--- a/Packages/PeelCore/Sources/PeelCore/Search/FileSearch.swift
+++ b/Packages/PeelCore/Sources/PeelCore/Search/FileSearch.swift
@@ -108,7 +108,6 @@ public enum FileSearch {
let allows = allows ?? RemovalGuard(environment: environment, exclusions: exclusions).allowsRemoval(of:)
var candidates: [(url: URL, info: stat, belongsToAnApp: Bool)] = []
for path in paths {
- // A stopped search reads nothing more; nobody will look at what it would have found.
guard !Task.isCancelled else { return FileSearchResults(didRun: false) }
var info = stat()
guard lstat(path, &info) == 0, info.st_mode & S_IFMT == S_IFREG else { continue }
@@ -208,9 +207,8 @@ public enum FileSearch {
}
}
-/// One Spotlight query, run without blocking a thread and stopped when the task that waits for it is. Everything
-/// about the query happens on its own serial queue, where Spotlight delivers its results and notifications, so
-/// the query is never touched from two threads at once.
+/// One Spotlight query, run without blocking a thread and stopped with the task that waits for it. It is only ever
+/// touched on its own serial queue, where Spotlight also delivers its results.
private final class SpotlightGathering: @unchecked Sendable {
private let query: MDQuery
private let queue = DispatchQueue(label: "com.tuguidragos.Peel.FileSearch")
@@ -223,7 +221,6 @@ private final class SpotlightGathering: @unchecked Sendable {
self.query = query
}
- /// The paths the query found, or nil when it could not run or the task was canceled.
func paths() async -> [String]? {
await withTaskCancellationHandler {
await withCheckedContinuation { continuation in
@@ -250,8 +247,7 @@ private final class SpotlightGathering: @unchecked Sendable {
}
}
- /// Reads each result's path from the result itself: Spotlight does not carry `kMDItemPath` in a query's value
- /// lists, which `MDQueryGetAttributeValueOfResultAtIndex` reads, so a query built to gather it finds no paths.
+ /// Reads each result's path from the result itself, since a query's value lists never carry `kMDItemPath`.
private func foundPaths() -> [String] {
MDQueryDisableUpdates(query)
return (0..<MDQueryGetResultCount(query)).compactMap { index in
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/BackgroundItemActionsTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/BackgroundItemActionsTests.swift
index fa985172..f20db622 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/BackgroundItemActionsTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/BackgroundItemActionsTests.swift
@@ -189,8 +189,8 @@ struct DeclaredBackgroundItemsTests {
#expect(items.first?.isDisabled == true)
}
- /// Where `launchctl` answered in a form Peel cannot read, a job's state is not known, never "not loaded",
- /// whether its list of jobs or its overrides could not be read. Its loaded jobs are not asked about either.
+ /// Where `launchctl` answered its jobs or its overrides in a form Peel cannot read, a job's state is not known,
+ /// never "not loaded".
@Test func aJobWhoseStateCouldNotBeReadIsNotKnown() throws {
let directory = try TemporaryDirectory()
try directory.file("home/Library/LaunchAgents/agent.plist", contents: job("com.example.agent"))
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/CommandLineTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/CommandLineTests.swift
index 6f93e59f..78716166 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/CommandLineTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/CommandLineTests.swift
@@ -32,8 +32,7 @@ struct CommandLineTests {
])
}
- /// The app ships `Support/peel.1`, which `Scripts/generate_manual.py` writes from the tool. A command added to
- /// the tool without the page being written again would be missing from `man peel`.
+ /// `man peel` reads `Support/peel.1`, which `Scripts/generate_manual.py` writes again when a command is added.
@Test func theManualPageNamesEveryCommand() throws {
let page = try String(contentsOf: StringCatalogTests.repository.appending(path: "Support/peel.1"), encoding: .utf8)
func names(of command: any ParsableCommand.Type) -> [String] {
@@ -224,8 +223,7 @@ struct CommandLineTests {
#expect(json["appSize"] is NSNull)
}
- /// `peel uninstall --json` says, once it is done, what was to move and what stayed and why, what moved, and
- /// what failed and why, with every key in every record.
+ /// `peel uninstall --json` says what stays and why, what moved and what failed, with every key in every record.
@Test func theUninstallReportSaysWhatMovedWhatStayedAndWhy() throws {
let app = URL(filePath: "/Applications/Editor.app", directoryHint: .isDirectory)
let support = URL(filePath: "/Users/me/Library/Application Support/Editor", directoryHint: .isDirectory)
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/DefaultAppsTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/DefaultAppsTests.swift
index 25a25de9..9f6ae318 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/DefaultAppsTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/DefaultAppsTests.swift
@@ -77,8 +77,7 @@ struct DefaultAppsTests {
#expect(DefaultApps.declaredTypes(in: info).map(\.identifier) == ["com.adobe.pdf", "public.png"])
}
- /// macOS has no description for a type it made up from an extension no app registers, and Finder calls such a
- /// file by the name the app that opens it gives that kind of document, in the app's own translation.
+ /// A type no app registers is called what the app that opens it calls that kind of document, as Finder does.
@Test func namesAKindMacOSCannotDescribeAsTheAppDoes() throws {
let directory = try TemporaryDirectory()
let app = try directory.directory("Example.app")
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/DeveloperCachesTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/DeveloperCachesTests.swift
index 96ad23f4..6a3fe3b6 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/DeveloperCachesTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/DeveloperCachesTests.swift
@@ -302,9 +302,8 @@ struct DeveloperCachesTests {
#expect(Set(locations.map(\.kind)) == [.models, .environments])
}
- /// What a tool keeps for the person to install again: Xcode's hardware support installers, which Apple
- /// suggests copying to other Macs, the Asset Store packages Unity downloaded, and Vagrant's boxes, some added
- /// from a file that is gone.
+ /// Xcode's hardware support installers, Unity's Asset Store packages and Vagrant's boxes are kept for the person
+ /// to install again.
@Test func downloadsKeptToInstallAgainAreListedButNeverSelected() async throws {
let directory = try TemporaryDirectory()
try directory.file("Library/Developer/Packages/HardwareSupport.pkg", bytes: 400_000)
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/FileCommandTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/FileCommandTests.swift
index 1a7cb83b..6bba6034 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/FileCommandTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/FileCommandTests.swift
@@ -376,8 +376,7 @@ struct FileCommandTests {
])
}
- /// `peel orphans --json` says for each file whether `--remove` leaves it and why, and which folders macOS kept
- /// Peel out of, so a script can tell an empty list from one that could not look everywhere.
+ /// `peel orphans --json` says why `--remove` leaves each file it leaves, and which folders macOS kept Peel out of.
@Test func theOrphansListSaysWhatStaysAndWhereItCouldNotLook() throws {
let directory = try TemporaryDirectory()
let group = OrphanGroup(identifier: "com.example.gone", items: [
@@ -395,8 +394,7 @@ struct FileCommandTests {
#expect(report["unreadableLocations"] as? [String] == ["/Users/me/Library/Containers"])
}
- /// A chosen folder Peel didn't look in, such as a repository, is said, so "No duplicates found." is not read
- /// as a folder without any.
+ /// A chosen folder Peel didn't look in, such as a repository, is said, so an empty answer is not read as none.
@Test func saysWhichFoldersItDidNotLookIn() {
let skipped = URL(filePath: "/Users/me/Projects/app", directoryHint: .isDirectory)
let scan = DuplicateScan(groups: [], unreadableLocations: [], skippedLocations: [skipped])
@@ -421,8 +419,7 @@ struct FileCommandTests {
#expect(found["skippedLocations"] as? [String] == ["/Users/me/Projects/app"])
}
- /// A chosen folder macOS kept Peel out of is said whatever the output, so "Nothing built was found" is not
- /// read as a folder with nothing built in it.
+ /// A chosen folder macOS kept Peel out of is said whatever the output, so an empty answer is not read as none.
@Test func saysWhenItCouldNotLookInAChosenFolder() throws {
let locked = URL(filePath: "/Users/me/Library/Safari", directoryHint: .isDirectory)
let scan = ProjectArtifacts.Scan(artifacts: [], wasCutShort: true, unreadableLocations: [locked])
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/FileSearchTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/FileSearchTests.swift
index 51b0b5fb..849927a8 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/FileSearchTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/FileSearchTests.swift
@@ -15,8 +15,7 @@ struct FileSearchTests {
#expect(!FileSearch.isAppData(URL(filePath: "/Users/x/Libraryish/cache.db"), home: home))
}
- /// A Spotlight query over the whole Mac can take seconds, so a search is stopped like any scan: it comes back
- /// at once and reads nothing more.
+ /// A search is stopped like any scan: it comes back at once and reads nothing more.
@Test func aStoppedSearchStops() async throws {
let unanswered = Unanswered()
var search = FileSearchCriteria()
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/LaunchctlTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/LaunchctlTests.swift
index 01c01aae..144846d1 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/LaunchctlTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/LaunchctlTests.swift
@@ -29,8 +29,7 @@ struct LaunchctlTests {
#expect(jobs["application.com.example.jotter.22249290.22249296"] == .some(22251))
}
- /// `launchctl`'s output is not an interface and can change. An answer in a form Peel does not recognize says
- /// nothing about which jobs are loaded, so it is read as not known rather than as no jobs at all.
+ /// An answer in a form Peel does not recognize is read as not known, never as no jobs at all.
@Test func anAnswerInAnotherFormIsNotKnown() {
#expect(Launchctl.parseList("Label\tPID\ncom.example.agent\t-\n") == nil)
#expect(Launchctl.parseList("Could not connect to the domain.\n") == nil)
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/LeftoverScannerTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/LeftoverScannerTests.swift
index bb32d1e0..e87f80ff 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/LeftoverScannerTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/LeftoverScannerTests.swift
@@ -66,9 +66,8 @@ struct LeftoverScannerTests {
)
}
- /// The guard reads every spelling of a path from the disk, and a location holds thousands of entries that are
- /// nobody's business: files named after no app, and files inside a folder the scan looks into. It is asked
- /// only about what the scan would take or walk into, and what it refuses stays out as before.
+ /// The guard, which reads every spelling of a path from the disk, is asked only about what the scan would take
+ /// or walk into, and what it refuses stays out.
@Test func asksTheGuardOnlyAboutWhatItWouldTakeOrWalkInto() async throws {
let directory = try TemporaryDirectory()
for index in 1...200 {
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/PackageReceiptsTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/PackageReceiptsTests.swift
index f34df4a6..be7601b2 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/PackageReceiptsTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/PackageReceiptsTests.swift
@@ -70,9 +70,8 @@ struct PackageReceiptsTests {
#expect(PackageReceipts.topLevel(files: files, installLocation: "/", exists: { _ in true }).offered.isEmpty)
}
- /// `pkgutil --file-info-plist` matches a path against the receipt's file list, which leaves out the
- /// package's install prefix (such as `Applications`). So the path is asked about again without its leading
- /// folders, and the answer is believed only if the receipt really installed that path.
+ /// A receipt's file list leaves out the install prefix, such as `Applications`, so the path is asked about again
+ /// without its leading folders, and the answer is believed only if the receipt really installed that path.
@Test func findsThePackageThatInstalledAnAppUnderAnInstallPrefix() async throws {
let directory = try TemporaryDirectory()
let volume = PathPattern.canonical(directory.url).path(percentEncoded: false)
@@ -206,8 +205,7 @@ struct PackageReceiptsTests {
#expect(empty.receipts.isEmpty)
}
- /// An answer that is not the property list `pkgutil` prints says nothing about what is installed, so it is
- /// no answer, rather than a list of packages read from whatever text came back.
+ /// An answer that is not the property list `pkgutil` prints says nothing about what is installed.
@Test func anAnswerInAnotherFormIsNoAnswer() async {
let error: PackageReceipts.Pkgutil = { _ in "Error: the receipts could not be read.\n" }
let scan = await PackageReceipts.list(exclusions: .none, pkgutil: error)
diff --git a/Packages/PeelCore/Tests/PeelCoreTests/TrashServiceTests.swift b/Packages/PeelCore/Tests/PeelCoreTests/TrashServiceTests.swift
index fb2f8164..db1a2ffa 100644
--- a/Packages/PeelCore/Tests/PeelCoreTests/TrashServiceTests.swift
+++ b/Packages/PeelCore/Tests/PeelCoreTests/TrashServiceTests.swift
@@ -504,8 +504,8 @@ struct TrashServiceTests {
}
}
- /// A folder refused by its name is refused before anything inside it is read. The checks for a library, a
- /// browser wallet and work kept in a cache look a level or two down, which costs a read of every folder there.
+ /// A folder refused by its name is refused before anything inside it is read, since the checks that look a
+ /// level or two down cost a read of every folder there.
@Test func refusesByNameBeforeReadingWhatIsInside() throws {
let directory = try TemporaryDirectory()
for index in 0..<300 {
diff --git a/Peel/Model/FileSearchLibrary.swift b/Peel/Model/FileSearchLibrary.swift
index 2fbd81dd..e2f156d0 100644
--- a/Peel/Model/FileSearchLibrary.swift
+++ b/Peel/Model/FileSearchLibrary.swift
@@ -7,17 +7,15 @@ final class FileSearchLibrary {
var criteria = FileSearchCriteria()
private(set) var results: FileSearchResults?
private(set) var searchedCriteria: FileSearchCriteria?
- /// The search this page runs, which a newer one or the Stop button ends.
let scanRun = ScanRun()
- /// True while a search runs, and while one is due because the words changed since the last one was asked.
- /// Typing cancels the running search at once and starts the next a moment later, and the page stays busy
- /// between the two.
+ /// True while a search runs, and while one is due because the words changed since the last was asked, so the
+ /// page stays busy between two searches while someone types.
var isSearching: Bool {
scanRun.isRunning || (criteria.isSearchable && criteria != searchedCriteria)
}
private(set) var isRemoving = false
var selectedURLs: Set<URL> = []
- /// The file the detail shows, chosen in the list. Checking a file for the Trash is `selectedURLs`, apart.
+ /// The file the detail shows. The files selected for the Trash are `selectedURLs`.
var chosen: URL?
/// The files Select All selects: not the ones that need an administrator, and not the ones an app keeps
/// for itself, which stay listed with the reason beside them.
@@ -41,7 +39,6 @@ final class FileSearchLibrary {
let criteria = criteria
searchedCriteria = criteria
guard criteria.isSearchable else {
- // Nothing is asked of Spotlight anymore, so a search still running for the old words is stopped.
scanRun.stop()
results = nil
selectedURLs = []
diff --git a/Peel/Model/FoundLastTimeStore.swift b/Peel/Model/FoundLastTimeStore.swift
index 5783c358..3659a362 100644
--- a/Peel/Model/FoundLastTimeStore.swift
+++ b/Peel/Model/FoundLastTimeStore.swift
@@ -2,8 +2,7 @@ import Foundation
import Observation
import PeelCore
-/// What each tool found the last time it looked, as Home lists it. It is kept in the app's user defaults, beside
-/// `LifetimeStats`, so Home can say it again after Peel is opened.
+/// What each tool found the last time it looked, kept in the app's user defaults so Home can list it.
@Observable
final class FoundLastTimeStore {
private static let key = "home.foundLastTime"
@@ -26,7 +25,7 @@ final class FoundLastTimeStore {
}
}
-/// How many things a tool found when it last looked, and their size when the tool measures what it finds.
+/// What a tool found when it looked, with no size for what has none, such as updates.
struct Looked: Equatable {
let count: Int
let size: SizeTotal?
@@ -55,7 +54,6 @@ extension IntelLibrary {
}
extension HomebrewLibrary {
- /// The packages with a newer version waiting.
var looked: Looked? {
packages.map { Looked(count: $0.count(where: \.isOutdated), size: nil) }
}
@@ -86,7 +84,6 @@ extension InstallerLibrary {
}
extension DuplicateLibrary {
- /// The groups of copies, and what moving every copy but one of each would free.
var looked: Looked? {
scan.map { scan in
let reclaimable = scan.groups.reduce(0) { $0 + $1.reclaimableSize } + scan.folderGroups.reduce(0) { $0 + $1.reclaimableSize }
diff --git a/Peel/PeelApp.swift b/Peel/PeelApp.swift
index 37390f00..e9e5cddf 100644
--- a/Peel/PeelApp.swift
+++ b/Peel/PeelApp.swift
@@ -89,8 +89,8 @@ struct PeelApp: App {
}
}
- /// Records what each tool finds whenever it finds it, with its page open or not, so Home can list it. Each tool
- /// is followed on its own, so one that looks again leaves the others' dates as they were.
+ /// Records what each tool finds, its page open or not, so Home can list it. Each tool is followed on its own, so
+ /// one that looks again leaves the others' dates as they were.
private func followFindings() async {
let tools: [(Tool, @MainActor @Sendable () -> Looked?)] = [
(.applications, { [library] in library.looked }),
@@ -138,10 +138,8 @@ struct PeelApp: App {
notifications.notify(updatesAvailable: found.count, firstName: found[0].name, firstApp: found[0].url)
}
- /// Whether the menu bar item shows, which is whether Peel watches the Trash. `MenuBarExtra` writes the item's
- /// visibility back into this binding each time the app's scenes update, which a scrolling list can make happen
- /// at every step, even when nothing changed. Every write to `AppStorage` makes each `AppStorage` in the app read
- /// again and redraw what shows it, so writing the value already held is left out.
+ /// Whether the menu bar item shows. `MenuBarExtra` writes it back at every scene update, and each write to an
+ /// `AppStorage` makes every `AppStorage` in the app read again, so a write of the value it holds is left out.
private var menuBarItemIsInserted: Binding<Bool> {
Binding {
watchesTrash
diff --git a/Peel/Views/BackgroundItems/BackgroundItemDetailView.swift b/Peel/Views/BackgroundItems/BackgroundItemDetailView.swift
index 24bb9824..ec71a14e 100644
--- a/Peel/Views/BackgroundItems/BackgroundItemDetailView.swift
+++ b/Peel/Views/BackgroundItems/BackgroundItemDetailView.swift
@@ -121,8 +121,6 @@ struct BackgroundItemDetailView: View {
}
}
- // Leaves out the section when it would be empty: some jobs have no Start, Stop, Enable, or Disable
- // buttons, and a job macOS registered for an app has no file to show.
if hasOwnControls || finderURL != nil {
Section {
if item.canMoveToTrash {
diff --git a/Peel/Views/Duplicates/DuplicateScanForm.swift b/Peel/Views/Duplicates/DuplicateScanForm.swift
index 5beecb6e..d637cb26 100644
--- a/Peel/Views/Duplicates/DuplicateScanForm.swift
+++ b/Peel/Views/Duplicates/DuplicateScanForm.swift
@@ -2,8 +2,7 @@ import PeelCore
import SwiftUI
import UniformTypeIdentifiers
-/// What a scan looks at, in a popover from the toolbar, so the settings can change without costing the results:
-/// they apply to the next scan.
+/// What a scan looks at, in a popover from the toolbar: a change applies to the next scan and costs no results.
struct DuplicateScanForm: View {
private static let sizes: [Int64] = [100_000, 1_000_000, 10_000_000, 100_000_000]
diff --git a/Peel/Views/FileSearch/FileSearchList.swift b/Peel/Views/FileSearch/FileSearchList.swift
index 6339633f..44687733 100644
--- a/Peel/Views/FileSearch/FileSearchList.swift
+++ b/Peel/Views/FileSearch/FileSearchList.swift
@@ -1,7 +1,7 @@
import PeelCore
import SwiftUI
-/// The files a search found, with every state of the search, in the list column as every tool keeps its items.
+/// The files a search found, and every state of the search, in the list column.
struct FileSearchList: View {
@Environment(FileSearchLibrary.self) private var search
@Environment(ExclusionsStore.self) private var exclusions
@@ -88,8 +88,7 @@ struct FileSearchList: View {
couldNotLook: search.results?.didRun == false ? "Spotlight Didn’t Answer" : nil,
wasStopped: search.scanRun.wasStopped || !search.criteria.isSearchable
)
- // The name is typed in the search field at the top of the column, where other pages filter their lists.
- // Here the field is part of the search, so it is always shown.
+ // Here the column's search field is part of the search, so it is always shown.
.columnSearch(text: $search.criteria.name, prompt: "Search Files", when: true)
.navigationTitle(Text(Tool.fileSearch.title))
.toolbar {
diff --git a/Peel/Views/History/HistoryDetailView.swift b/Peel/Views/History/HistoryDetailView.swift
index d994366d..6ae5f961 100644
--- a/Peel/Views/History/HistoryDetailView.swift
+++ b/Peel/Views/History/HistoryDetailView.swift
@@ -261,12 +261,11 @@ private struct HistoryRecordRow: View {
label: [record.originalURL.abbreviatedPath, String(localized: place.title), record.size.byteCount]
.joined(separator: ", ")
)
- // A click on the record selects it, as a click on a checkbox's title does. VoiceOver hears the record
- // as the checkbox's name.
item
.contentShape(.rect)
.onTapGesture { history.setSelected(!isSelected, record) }
.checkboxTitle()
+ // The checkbox's label already reads the record.
.accessibilityHidden(true)
}
.disabled(place != .inTrash)
diff --git a/Peel/Views/NativeCheckbox.swift b/Peel/Views/NativeCheckbox.swift
index 3f4c4591..e4ae4f80 100644
--- a/Peel/Views/NativeCheckbox.swift
+++ b/Peel/Views/NativeCheckbox.swift
@@ -1,18 +1,12 @@
import AppKit
import SwiftUI
-/// A checkbox for a list's rows: AppKit's own button, at the size AppKit gives it.
-///
-/// SwiftUI's checkbox `Toggle` is the same button, but SwiftUI asks the button for its size every time the list
-/// measures a row, and a list measures each row as it scrolls into view, so a list of them drops frames while it
-/// scrolls. This one answers the size from a table read once for each control size.
+/// AppKit's checkbox, for the rows of a list. A checkbox `Toggle` is the same button, but SwiftUI asks it for its size
+/// each time the list measures a row, which drops frames while a long list scrolls. This one reads its size once.
struct NativeCheckbox: NSViewRepresentable {
@Binding var isOn: Bool
- /// What VoiceOver reads, since the checkbox has no title of its own.
let label: String
- /// The help tag, which VoiceOver also reads unless there is a hint.
var help: String?
- /// What VoiceOver reads after the label, in place of the help tag.
var hint: String?
func makeCoordinator() -> Coordinator {
@@ -47,8 +41,7 @@ struct NativeCheckbox: NSViewRepresentable {
if button.accessibilityHelp() != hint ?? help { button.setAccessibilityHelp(hint ?? help) }
}
- /// AppKit's standard checkbox with no title. `init(checkboxWithTitle:target:action:)` makes the same button but
- /// sizes it to its title twice on the way, and a list makes one for every row that scrolls into view.
+ /// Not `init(checkboxWithTitle:target:action:)`, which sizes the button to its title twice on the way.
private static func checkbox() -> NSButton {
let button = NSButton(frame: .zero)
button.setButtonType(.switch)
@@ -81,8 +74,7 @@ struct NativeCheckbox: NSViewRepresentable {
}
extension VerticalAlignment {
- /// The middle of the first line of a checkbox's title, which the checkbox is centered on. A checkbox's own is
- /// its center; its title's is set by `checkboxTitleLine()`.
+ /// The middle of the first line of a checkbox's title, which the checkbox is centered on.
nonisolated static let checkboxTitleLine = VerticalAlignment(CheckboxTitleLine.self)
private nonisolated enum CheckboxTitleLine: AlignmentID {
@@ -93,14 +85,13 @@ extension VerticalAlignment {
}
extension View {
- /// Draws this view as a checkbox's title, which a disabled checkbox dims two levels, primary content to tertiary,
- /// secondary to quaternary and tertiary to quinary, as SwiftUI's own checkbox toggle draws its label.
+ /// Draws this view as a checkbox's title, dimmed two levels when disabled, as SwiftUI dims its checkbox's label.
func checkboxTitle() -> some View {
modifier(CheckboxTitleStyle())
}
- /// Marks this text as the first line of a checkbox's title. Its middle is its baseline less half the height of
- /// its capitals, where AppKit and SwiftUI center their own checkbox beside a title.
+ /// Marks this text as the first line of a checkbox's title, whose middle is its baseline less half its cap height,
+ /// where AppKit centers a checkbox beside its title.
func checkboxTitleLine() -> some View {
modifier(CheckboxTitleLineGuide())
}
diff --git a/Peel/Views/RemovalRow.swift b/Peel/Views/RemovalRow.swift
index f8b95303..9589c811 100644
--- a/Peel/Views/RemovalRow.swift
+++ b/Peel/Views/RemovalRow.swift
@@ -28,8 +28,7 @@ struct RemovalRow: View {
/// False when no row of the table has a note. The note column is then left out, so the sizes end at the
/// same edge as the page's totals and Select All.
var hasNoteColumn = true
- /// True in a list whose rows are chosen to show them in the detail column. A click on such a row chooses it,
- /// and only its checkbox selects the item.
+ /// A click on the row chooses it for the detail column, and only the checkbox selects the item.
var isChoosable = false
/// The object the checkbox writes to. A `Binding` here would rebuild every row in the list: see `RowSelection`.
let selection: any RowSelection
@@ -65,18 +64,16 @@ struct RemovalRow: View {
}
}
- /// The checkbox, and beside it the item it selects. VoiceOver hears the two as one checkbox, as it would a
- /// checkbox's title, so the item itself is hidden from it.
private var checkboxAndItem: some View {
HStack(alignment: .checkboxTitleLine, spacing: 5) {
NativeCheckbox(
isOn: Binding(get: { isSelected }, set: { selection.setSelected($0, for: url) }),
label: spokenItem,
- // The label reads every column, so the hint adds only the warning from the note.
hint: warning.map { String(Self.commandsMarked($0).characters) }
)
clickableItem
.checkboxTitle()
+ // The checkbox's label already reads the item.
.accessibilityHidden(true)
}
.disabled(isLocked || isExcluded || isLeftAlone)
@@ -87,14 +84,12 @@ struct RemovalRow: View {
if isChoosable {
item
} else {
- // A click on the item selects it, as a click on a checkbox's title does.
item
.contentShape(.rect)
.onTapGesture { selection.setSelected(!isSelected, for: url) }
}
}
- /// The item as the checkbox's title reads it: its path, its badge, its kind and its size.
private var spokenItem: String {
let badge = badgeKind.map { String(localized: $0.title) }
let size = isMeasured ? size.byteCount : String(localized: "Unknown")
diff --git a/Peel/Views/RescanButton.swift b/Peel/Views/RescanButton.swift
index 511eebf6..49c40e24 100644
--- a/Peel/Views/RescanButton.swift
+++ b/Peel/Views/RescanButton.swift
@@ -6,9 +6,9 @@ struct RescanButton: View {
@Binding var isRunning: Bool
var isDisabled = false
var title: LocalizedStringResource = "Rescan"
- /// The page's scan. While it runs, the button turns into Stop, as Safari's Reload does. Nil where the work
- /// can't be stopped halfway, such as reading one file. Stop is not offered while the button is disabled: the
- /// scan after a move to the Trash takes the moved rows off the list, and stopping it would leave them listed.
+ /// The page's scan: while it runs, the button turns into Stop, as Safari's Reload does. Nil where the work can't
+ /// be stopped halfway. A disabled button offers no Stop: stopping the scan after a move to the Trash would leave
+ /// the moved rows listed.
var scan: (any StoppableWork)?
let action: () async -> Void
diff --git a/Peel/Views/RowButtonStyle.swift b/Peel/Views/RowButtonStyle.swift
index e55c2fe1..fb3c5173 100644
--- a/Peel/Views/RowButtonStyle.swift
+++ b/Peel/Views/RowButtonStyle.swift
@@ -1,20 +1,14 @@
import SwiftUI
-/// The style of a button in a List row. It looks like `.plain`, which draws the label at three quarters while it is
-/// pressed and at half while it is disabled, and it tracks the press with a gesture of its own.
-///
-/// A List takes keyboard focus as a whole, so a button in one of its rows is only ever pressed with the pointer or
-/// through accessibility. A standard style still makes each such button a place keyboard focus could go, and the
-/// window's list of those changes as rows scroll in and out, which updates the window's focus, its toolbar and the
-/// app's scenes at every step of a scroll. A button with this style costs none of that.
+/// The style of a button in a List row: it looks like `.plain` but is no place keyboard focus could go, which a List
+/// never sends to a row's button anyway. With a standard style, rows scrolling in and out change the window's places
+/// for focus, which updates its toolbar and the app's scenes at every step of a scroll.
struct RowButtonStyle: PrimitiveButtonStyle {
func makeBody(configuration: Configuration) -> some View {
PressableLabel(configuration: configuration)
}
}
-/// Pressed while the pointer is down inside the label, and pressed for real only when it comes up there, as a
-/// button is.
private struct PressableLabel: View {
let configuration: RowButtonStyle.Configuration
@Environment(\.isEnabled) private var isEnabled
diff --git a/Peel/Views/ToolSummaries.swift b/Peel/Views/ToolSummaries.swift
index 6fea48ca..8a155f4b 100644
--- a/Peel/Views/ToolSummaries.swift
+++ b/Peel/Views/ToolSummaries.swift
@@ -2,8 +2,7 @@ import Accessibility
import PeelCore
import SwiftUI
-// What each tool found, in numbers: the summary its detail pane shows before anything is chosen, and what
-// VoiceOver reads when a scan ends.
+// What each tool found: the summary its pane shows, and what VoiceOver reads when a scan ends.
//
// Each sentence is one localized string with its numbers inside, so a translation can put the parts in any
// order, as Japanese or Turkish need. The sentences avoid verbs that would have to agree with a number, and the
@@ -150,9 +149,8 @@ extension RemovalHistoryStore {
}
extension View {
- /// Tells VoiceOver what a scan found when it ends, since a scan can take minutes and the list fills in
- /// silently. A stopped scan is announced as stopped. `couldNotLook` is the title of the page's message for a
- /// scan that could not look, which is read in place of "Nothing found." when nothing was found.
+ /// Tells VoiceOver how a scan ended, since the list fills in silently: what it found, that it was stopped, or
+ /// `couldNotLook`, the title of the page's message, in place of "Nothing found." when it could not look.
func announcesScan(
_ isScanning: Bool,
found summary: AttributedString?,