Repository Public License
1// ORIX Convert — Packages/ORIXConvertCore/Sources/ConvertCore/Inspection.swift2// Description: Inspection façade. FileInspector merges content detection, the owning engine's inspection and generic3// file facts; SmartDropAnalyzer analyses a dropped batch (files and folders) and says, per file and per4// format group, what can really be done with it.5// Author: Simon-Pierre Boucher — contact@spboucher.ai6import Foundation7import UniformTypeIdentifiers89/// Facts read from the file system (never from the content).10public struct FileFacts: Sendable, Hashable, Codable {11 public var size: Int64?12 public var created: Date?13 public var modified: Date?14 /// POSIX permission bits (e.g. `0o644`).15 public var posixPermissions: Int?16 public var isDirectory = false17 public var isSymbolicLink = false18 public var isHidden = false19 /// The `com.apple.quarantine` extended attribute is present (file downloaded or received).20 public var isQuarantined = false21 /// The `com.apple.metadata:kMDItemWhereFroms` extended attribute is present (the value is not read).22 public var hasWhereFroms = false23 /// Uniform Type Identifier the system assigns to the item (derived from its name).24 public var uti: String?25 public init() {}26}2728/// Everything known about one file.29public struct InspectedFile: Sendable {30 public let url: URL31 public let detection: DetectionResult32 public let facts: FileFacts33 /// Engine inspection merged with a "File" group of generic fields. When no engine can inspect the format, only34 /// the generic fields are present and every typed member is `nil`.35 public let inspection: FileInspection36 /// Engine that inspected the content, if one did.37 public let engineID: String?38 /// Why the engine could not inspect the file, when it tried and failed.39 public let engineError: String?40}4142public struct FileInspector: Sendable {43 public let registry: FormatRegistry44 public init(registry: FormatRegistry) { self.registry = registry }4546 /// Reads file-system facts. Missing values stay `nil`/`false`.47 public static func facts(of url: URL) -> FileFacts {48 var facts = FileFacts()49 if let attributes = try? FileManager.default.attributesOfItem(atPath: url.path) {50 let type = attributes[.type] as? FileAttributeType51 facts.isDirectory = type == .typeDirectory52 facts.isSymbolicLink = type == .typeSymbolicLink53 facts.size = facts.isDirectory ? nil : (attributes[.size] as? NSNumber)?.int64Value54 facts.created = attributes[.creationDate] as? Date55 facts.modified = attributes[.modificationDate] as? Date56 facts.posixPermissions = (attributes[.posixPermissions] as? NSNumber)?.intValue57 }58 let values = try? url.resourceValues(forKeys: [.isHiddenKey, .contentTypeKey])59 facts.isHidden = values?.isHidden ?? url.lastPathComponent.hasPrefix(".")60 facts.uti = values?.contentType?.identifier61 facts.isQuarantined = getxattr(url.path, "com.apple.quarantine", nil, 0, 0, XATTR_NOFOLLOW) >= 062 facts.hasWhereFroms = getxattr(url.path, "com.apple.metadata:kMDItemWhereFroms", nil, 0, 0, XATTR_NOFOLLOW) >= 063 return facts64 }6566 /// Detects, inspects with the engine that knows the format (when `deep`), and merges generic facts.67 public func inspect(_ url: URL, deep: Bool = true) async -> InspectedFile {68 let detection = FileTypeDetector.detect(url)69 let facts = Self.facts(of: url)70 var inspection = FileInspection(format: detection.format ?? "unknown")71 var engineID: String?72 var engineError: String?73 if deep, let format = detection.format, let engine = registry.inspector(for: format) {74 do {75 inspection = try await engine.inspect(url, format: format)76 engineID = engine.id77 } catch {78 engineError = (error as? LocalizedError)?.errorDescription ?? error.localizedDescription79 }80 }81 inspection.fields.insert(contentsOf: Self.genericFields(detection: detection, facts: facts), at: 0)82 return InspectedFile(url: url, detection: detection, facts: facts, inspection: inspection, engineID: engineID, engineError: engineError)83 }8485 static func genericFields(detection: DetectionResult, facts: FileFacts) -> [InspectionField] {86 let iso = ISO8601DateFormatter()87 var fields: [InspectionField] = []88 fields.append(InspectionField("File", "Format", detection.fileFormat?.name ?? "Unknown"))89 fields.append(InspectionField("File", "Detection", "\(detection.confidence.rawValue): \(detection.evidence)"))90 if let encoding = detection.textEncoding { fields.append(InspectionField("File", "Text encoding", encoding.rawValue)) }91 if let size = facts.size { fields.append(InspectionField("File", "Size", "\(size) bytes")) }92 if let created = facts.created { fields.append(InspectionField("File", "Created", iso.string(from: created))) }93 if let modified = facts.modified { fields.append(InspectionField("File", "Modified", iso.string(from: modified))) }94 if let permissions = facts.posixPermissions { fields.append(InspectionField("File", "Permissions", String(permissions, radix: 8))) }95 if let uti = facts.uti { fields.append(InspectionField("File", "Type identifier", uti)) }96 fields.append(InspectionField("File", "Quarantine attribute", facts.isQuarantined ? "Present" : "Absent"))97 fields.append(InspectionField("File", "Download origin attribute", facts.hasWhereFroms ? "Present" : "Absent"))98 return fields99 }100}101102// MARK: - Smart Drop103104public struct SmartDropItem: Sendable, Identifiable {105 public let url: URL106 public let detection: DetectionResult107 public let facts: FileFacts108 public let inspection: FileInspection109 /// Plain conversions available for the detected format, best first.110 public let targets: [ConversionTarget]111 /// What the app should propose first.112 public let recommended: [ConversionTarget]113 /// Named operations (merge, split, extract…).114 public let operations: [ConversionTarget]115 /// Destinations reachable only through an intermediate format.116 public let chainedDestinations: [FormatID]117 /// Problems worth showing before converting (wrong extension, unknown format, empty or protected file…).118 public let warnings: [ConversionWarning]119 public var id: URL { url }120 public var format: FormatID? { detection.format }121 public var isSupported: Bool { !targets.isEmpty || !operations.isEmpty }122}123124/// Files of a batch sharing one detected format.125public struct SmartDropGroup: Sendable, Identifiable {126 /// `nil` groups the files whose format is unknown.127 public let format: FormatID?128 public let urls: [URL]129 public let targets: [ConversionTarget]130 public let recommended: [ConversionTarget]131 public let operations: [ConversionTarget]132 public var id: String { format?.rawValue ?? "unknown" }133}134135/// A dropped plain folder (its files are also analysed individually).136public struct SmartDropFolder: Sendable {137 public let url: URL138 /// Files found inside (hidden files excluded), up to the analyzer's bound.139 public let fileCount: Int140 /// What can be done with the folder as a whole (e.g. create an archive), from paths whose source is `folder`.141 public let targets: [ConversionTarget]142}143144public struct SmartDropAnalysis: Sendable {145 public let items: [SmartDropItem]146 /// Groups by detected format, largest first.147 public let groups: [SmartDropGroup]148 public let folders: [SmartDropFolder]149 /// Dropped items that were not analysed, and why.150 public let skipped: [(url: URL, reason: String)]151 /// The file bound was reached: more files exist than were analysed.152 public let truncated: Bool153 /// Destinations every supported file of the batch can be converted to directly.154 public let commonDestinations: [FormatID]155 /// Operations offered for the selection as a whole, whatever it contains — any files and folders become ONE156 /// output ("Create ZIP archive"). Enqueue with `ConversionJobManager.enqueueGeneric`.157 public let selectionOperations: [ConversionTarget]158 /// Operations offered for each regular file whatever its format ("Compress to gzip"), one job per file.159 public let fileOperations: [ConversionTarget]160 public var isMixed: Bool { groups.count > 1 }161}162163public struct SmartDropAnalyzer: Sendable {164 public struct Configuration: Sendable {165 /// Most files analysed per drop (folders are expanded up to this bound).166 public var maxFiles: Int167 /// Engine inspections running at once.168 public var maxConcurrentInspections: Int169 /// Run the engines' `inspect` (dimensions, duration…) in addition to detection.170 public var deepInspection: Bool171 /// Deepest folder level expanded.172 public var maxDepth: Int173 public init(maxFiles: Int = 5000, maxConcurrentInspections: Int = 4, deepInspection: Bool = true, maxDepth: Int = 32) {174 self.maxFiles = max(1, maxFiles); self.maxConcurrentInspections = max(1, maxConcurrentInspections)175 self.deepInspection = deepInspection; self.maxDepth = max(0, maxDepth)176 }177 }178179 public let registry: FormatRegistry180 public let configuration: Configuration181182 public init(registry: FormatRegistry, configuration: Configuration = Configuration()) {183 self.registry = registry; self.configuration = configuration184 }185186 /// Analyses dropped files and folders. Folders are expanded recursively (hidden files and symbolic links are187 /// skipped; iWork packages count as files) until `maxFiles` is reached.188 public func analyze(_ urls: [URL]) async -> SmartDropAnalysis {189 var files: [URL] = []190 var folders: [(URL, Int)] = []191 var skipped: [(url: URL, reason: String)] = []192 var truncated = false193 let fm = FileManager.default194 var seen = Set<String>()195196 func add(_ url: URL) {197 guard files.count < configuration.maxFiles else { truncated = true; return }198 if seen.insert(url.standardizedFileURL.path).inserted { files.append(url) }199 }200 func expand(_ directory: URL, depth: Int) -> Int {201 guard depth <= configuration.maxDepth else { skipped.append((directory, "Folder nesting is too deep.")); return 0 }202 guard let children = try? fm.contentsOfDirectory(at: directory, includingPropertiesForKeys: [.isDirectoryKey, .isSymbolicLinkKey, .isHiddenKey]) else {203 skipped.append((directory, "The folder could not be read."))204 return 0205 }206 var count = 0207 for child in children.sorted(by: { $0.lastPathComponent.localizedStandardCompare($1.lastPathComponent) == .orderedAscending }) {208 if truncated { break }209 let values = try? child.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey, .isHiddenKey])210 if values?.isHidden == true || child.lastPathComponent.hasPrefix(".") || values?.isSymbolicLink == true { continue }211 if values?.isDirectory == true, FileTypeDetector.detect(child).format == .folder {212 count += expand(child, depth: depth + 1)213 } else {214 add(child)215 count += 1216 }217 }218 return count219 }220221 for url in urls {222 var isDirectory: ObjCBool = false223 guard fm.fileExists(atPath: url.path, isDirectory: &isDirectory) else {224 skipped.append((url, "The item does not exist."))225 continue226 }227 if isDirectory.boolValue, FileTypeDetector.detect(url).format == .folder {228 folders.append((url, expand(url, depth: 0)))229 } else {230 add(url)231 }232 }233234 let inspector = FileInspector(registry: registry)235 let resolver = ConversionCapabilityResolver(registry: registry)236 let deep = configuration.deepInspection237 var inspected = [InspectedFile?](repeating: nil, count: files.count)238 await withTaskGroup(of: (Int, InspectedFile).self) { group in239 var next = 0240 func submit() {241 guard next < files.count else { return }242 let index = next, url = files[next]243 next += 1244 group.addTask { (index, await inspector.inspect(url, deep: deep)) }245 }246 for _ in 0..<min(configuration.maxConcurrentInspections, files.count) { submit() }247 for await (index, file) in group {248 inspected[index] = file249 if !Task.isCancelled { submit() }250 }251 }252253 var capabilityCache: [FormatID: ConversionCapabilities] = [:]254 func capabilities(_ format: FormatID) -> ConversionCapabilities {255 if let cached = capabilityCache[format] { return cached }256 let value = resolver.capabilities(for: format)257 capabilityCache[format] = value258 return value259 }260 var items: [SmartDropItem] = []261 for file in inspected.compactMap({ $0 }) {262 let caps = file.detection.format.map(capabilities)263 items.append(SmartDropItem(url: file.url, detection: file.detection, facts: file.facts, inspection: file.inspection,264 targets: caps?.targets ?? [], recommended: caps?.recommended ?? [], operations: caps?.operations ?? [],265 chainedDestinations: caps?.chainedDestinations ?? [], warnings: Self.warnings(for: file, capabilities: caps, registry: registry)))266 }267268 var grouped: [String: [SmartDropItem]] = [:]269 for item in items { grouped[item.format?.rawValue ?? "", default: []].append(item) }270 let groups = grouped.values.map { members -> SmartDropGroup in271 let first = members[0]272 return SmartDropGroup(format: first.format, urls: members.map(\.url), targets: first.targets, recommended: first.recommended, operations: first.operations)273 }.sorted { ($1.urls.count, $0.id) < ($0.urls.count, $1.id) }274275 let supported = items.filter { !$0.targets.isEmpty }276 var common = supported.first.map { Set($0.targets.map(\.destination)) } ?? []277 for item in supported.dropFirst() { common.formIntersection(item.targets.map(\.destination)) }278279 let folderCaps = capabilities(.folder)280 let generic = resolver.genericOperations()281 // A folder itself: everything declared from `.folder` except what applies to one regular file at a time.282 let perFile = Set(generic.forEachFile.map(\.id))283 let folderTargets = folderCaps.targets + folderCaps.operations.filter { !perFile.contains($0.id) }284 return SmartDropAnalysis(items: items, groups: groups,285 folders: folders.map { SmartDropFolder(url: $0.0, fileCount: $0.1, targets: folderTargets) },286 skipped: skipped, truncated: truncated, commonDestinations: common.sorted(),287 selectionOperations: generic.forSelection, fileOperations: generic.forEachFile)288 }289290 /// Everything to show the user before converting `item` to `destination`: the limitations of every step of the291 /// plan (as `info` warnings), the engine's own preflight warnings for this file and these options, and the292 /// item's generic warnings. Throws when no plan exists.293 public func preflight(_ item: SmartDropItem, to destination: FormatID, operation: String? = nil, options: ConversionOptions = .init()) throws -> (plan: ConversionPlan, warnings: [ConversionWarning]) {294 guard let source = item.format else { throw ConversionError.malformedInput("The format of \(item.url.lastPathComponent) could not be recognised.") }295 let plan = try ConversionPlanner(registry: registry).plan(from: source, to: destination, operation: operation)296 var warnings = item.warnings297 if plan.isChained {298 warnings.append(ConversionWarning(.info, code: "chained-plan", "Converted in two steps through \(plan.intermediates.map { $0.rawValue.uppercased() }.joined(separator: ", "))."))299 }300 for limitation in plan.limitations { warnings.append(ConversionWarning(.info, code: "limitation", limitation)) }301 if let first = plan.steps.first, let engine = registry.engine(id: first.engine) {302 let request = ConversionRequest(source: item.url, sourceFormat: first.source, destinationFormat: first.destination, operation: first.operation,303 options: plan.isChained ? .init() : options)304 warnings += engine.preflight(request, inspection: item.inspection)305 }306 var seen = Set<ConversionWarning>()307 return (plan, warnings.filter { seen.insert($0).inserted })308 }309310 static func warnings(for file: InspectedFile, capabilities: ConversionCapabilities?, registry: FormatRegistry) -> [ConversionWarning] {311 var warnings: [ConversionWarning] = []312 let name = file.url.lastPathComponent313 guard let format = file.detection.format else {314 return [ConversionWarning(.caution, code: "unknown-format", "\(name): the format could not be recognised (\(file.detection.evidence)).")]315 }316 if file.detection.mismatch {317 warnings.append(ConversionWarning(.caution, code: "extension-mismatch",318 "\(name): the extension .\(file.detection.fileExtension) does not match the content (\(file.detection.evidence))."))319 }320 if file.facts.size == 0 { warnings.append(ConversionWarning(.caution, code: "empty-file", "\(name) is empty.")) }321 if file.inspection.isEncrypted == true {322 warnings.append(ConversionWarning(.caution, code: "encrypted", "\(name) is protected; a password may be needed."))323 }324 if let error = file.engineError {325 warnings.append(ConversionWarning(.caution, code: "inspection-failed", "\(name) could not be inspected: \(error)"))326 }327 if capabilities?.isSupported != true {328 if let missing = registry.unavailablePaths(from: format).first {329 warnings.append(ConversionWarning(.caution, code: "engine-unavailable", "\(format.rawValue.uppercased()) conversions are unavailable in this build: \(missing.reason)"))330 } else {331 warnings.append(ConversionWarning(.info, code: "unsupported-format", "\(name): no conversion is available for \(format.rawValue.uppercased())."))332 }333 }334 return warnings335 }336}337