SPB Git

Repository Public License

Inspection.swift 18.5 KB 337 lines swift

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
Files main
Menu

Theme