fix(cli): address PR #66 review issues for export report

Fix TOCTOU race in capturePreState, extract duplicated determineAction
logic, add diagnostics for nil checksums and decode failures, create
parent directories before report write, improve error descriptions for
non-LocalizedError types, and add ReportStats factory methods.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: alexey1312

Sources/ExFigCLI/Report/AssetManifest.swift

@@ -14,7 +14,7 @@ struct ManifestEntry: Encodable {
     /// What happened to this file during export.
     let action: FileAction
 
-    /// FNV-1a 64-bit content checksum (16-char hex), `nil` for deleted files.
+    /// FNV-1a 64-bit content checksum (16-char hex), `nil` for deleted files or unreadable content.
     let checksum: String?
 
     /// Type of asset (e.g., "color", "icon", "image", "typography").

Sources/ExFigCLI/Report/ExportReport.swift

@@ -42,6 +42,32 @@ struct ExportReport: Encodable {
     /// Current report schema version.
     static let currentVersion = 1
 
+    init(
+        version: Int = ExportReport.currentVersion,
+        command: String,
+        config: String,
+        startTime: String,
+        endTime: String,
+        duration: TimeInterval,
+        success: Bool,
+        error: String?,
+        stats: ReportStats,
+        warnings: [String],
+        manifest: AssetManifest?
+    ) {
+        self.version = version
+        self.command = command
+        self.config = config
+        self.startTime = startTime
+        self.endTime = endTime
+        self.duration = duration
+        self.success = success
+        self.error = error
+        self.stats = stats
+        self.warnings = warnings
+        self.manifest = manifest
+    }
+
     /// Serializes the report to pretty-printed JSON with sorted keys.
     func jsonData() throws -> Data {
         try JSONCodec.encodePrettySorted(self)
@@ -59,4 +85,20 @@ struct ReportStats: Encodable {
     let typography: Int
 
     static let zero = ReportStats(colors: 0, icons: 0, images: 0, typography: 0)
+
+    static func colors(_ count: Int) -> ReportStats {
+        .init(colors: count, icons: 0, images: 0, typography: 0)
+    }
+
+    static func icons(_ count: Int) -> ReportStats {
+        .init(colors: 0, icons: count, images: 0, typography: 0)
+    }
+
+    static func images(_ count: Int) -> ReportStats {
+        .init(colors: 0, icons: 0, images: count, typography: 0)
+    }
+
+    static func typography(_ count: Int) -> ReportStats {
+        .init(colors: 0, icons: 0, images: 0, typography: count)
+    }
 }

Sources/ExFigCLI/Report/ExportReportHelper.swift

@@ -60,7 +60,7 @@ func withExportReport(
         endTime: formatter.string(from: endTime),
         duration: endTime.timeIntervalSince(startTime),
         success: exportError == nil,
-        error: exportError?.localizedDescription,
+        error: exportError.map { describeExportError($0) },
         stats: buildStats(exportCount),
         warnings: warningCollector.getAll(),
         manifest: manifestTracker.buildManifest(previousReportPath: reportPath)
@@ -73,3 +73,12 @@ func withExportReport(
 }
 
 // swiftlint:enable function_parameter_count
+
+private func describeExportError(_ error: any Error) -> String {
+    if let localized = error as? LocalizedError,
+       let description = localized.errorDescription
+    {
+        return description
+    }
+    return String(describing: error)
+}

Sources/ExFigCLI/Report/ExportReportWriter.swift

@@ -5,9 +5,18 @@ import Foundation
 /// Same pattern as `Batch.swift` report writing (lines 710-716):
 /// wrap write in do/catch, warn on failure, never propagate the error.
 func writeExportReport(_ report: ExportReport, to path: String, ui: TerminalUI) {
+    let data: Data
+    do {
+        data = try report.jsonData()
+    } catch {
+        ui.warning("Failed to serialize export report: \(error.localizedDescription)")
+        return
+    }
+
     do {
-        let data = try report.jsonData()
         let url = URL(fileURLWithPath: path)
+        let directory = url.deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
         try data.write(to: url)
         ui.info("Report written to: \(path)")
     } catch {

Sources/ExFigCLI/Report/ManifestTracker.swift

@@ -20,8 +20,11 @@ final class ManifestTracker: Sendable {
     /// Default asset type for all recorded entries.
     let defaultAssetType: String
 
+    private let workingDirectory: String
+
     init(assetType: String) {
         defaultAssetType = assetType
+        workingDirectory = FileManager.default.currentDirectoryPath
     }
 
     /// Pre-write filesystem state for a file path.
@@ -35,13 +38,11 @@ final class ManifestTracker: Sendable {
     /// Must be called BEFORE the file is written to disk, so that existing content
     /// can be compared for action detection (created vs. modified vs. unchanged).
     func capturePreState(for path: String) -> PreWriteState {
-        let fileExisted = FileManager.default.fileExists(atPath: path)
-        let existingChecksum: String? = if fileExisted, let existingData = FileManager.default.contents(atPath: path) {
-            FNV1aHasher.hashToHex(existingData)
+        if let existingData = FileManager.default.contents(atPath: path) {
+            PreWriteState(fileExisted: true, existingChecksum: FNV1aHasher.hashToHex(existingData))
         } else {
-            nil
+            PreWriteState(fileExisted: false, existingChecksum: nil)
         }
-        return PreWriteState(fileExisted: fileExisted, existingChecksum: existingChecksum)
     }
 
     /// Record a file write operation after successful write.
@@ -55,14 +56,7 @@ final class ManifestTracker: Sendable {
         let assetType = assetType ?? defaultAssetType
         let relativePath = makeRelativePath(path)
         let newChecksum = FNV1aHasher.hashToHex(data)
-
-        let action: FileAction = if !preState.fileExisted {
-            .created
-        } else if let existingChecksum = preState.existingChecksum {
-            existingChecksum == newChecksum ? .unchanged : .modified
-        } else {
-            .modified
-        }
+        let action = determineAction(preState: preState, newChecksum: newChecksum)
 
         entries.withLock {
             $0.append(ManifestEntry(
@@ -94,14 +88,12 @@ final class ManifestTracker: Sendable {
             nil
         }
 
-        let action: FileAction = if !preState.fileExisted {
-            .created
-        } else if let existingChecksum = preState.existingChecksum, let newChecksum {
-            existingChecksum == newChecksum ? .unchanged : .modified
-        } else {
-            .modified
+        if newChecksum == nil {
+            WarningCollectorStorage.current?.add("Manifest: could not compute checksum for \(relativePath)")
         }
 
+        let action = determineAction(preState: preState, newChecksum: newChecksum)
+
         entries.withLock {
             $0.append(ManifestEntry(
                 path: relativePath,
@@ -125,30 +117,46 @@ final class ManifestTracker: Sendable {
         var allEntries = entries.withLock { $0 }
 
         if let previousPath = previousReportPath,
-           let previousData = FileManager.default.contents(atPath: previousPath),
-           let previousReport = try? JSONCodec.decode(PreviousReportManifest.self, from: previousData)
+           let previousData = FileManager.default.contents(atPath: previousPath)
         {
-            let currentPaths = Set(allEntries.map(\.path))
-            for previousEntry in previousReport.manifest?.files ?? []
-                where !currentPaths.contains(previousEntry.path)
-            {
-                allEntries.append(ManifestEntry(
-                    path: previousEntry.path,
-                    action: .deleted,
-                    checksum: nil,
-                    assetType: previousEntry.assetType
-                ))
+            do {
+                let previousReport = try JSONCodec.decode(PreviousReportManifest.self, from: previousData)
+                let currentPaths = Set(allEntries.map(\.path))
+                for previousEntry in previousReport.manifest?.files ?? []
+                    where !currentPaths.contains(previousEntry.path)
+                {
+                    allEntries.append(ManifestEntry(
+                        path: previousEntry.path,
+                        action: .deleted,
+                        checksum: nil,
+                        assetType: previousEntry.assetType
+                    ))
+                }
+            } catch {
+                let message = "Could not read previous report at \(previousPath): "
+                    + "\(error.localizedDescription). Deleted file detection skipped."
+                WarningCollectorStorage.current?.add(message)
             }
         }
 
         return AssetManifest(files: allEntries)
     }
 
-    /// Make path relative to current working directory.
+    /// Determine file action based on pre-write state and new checksum.
+    private func determineAction(preState: PreWriteState, newChecksum: String?) -> FileAction {
+        if !preState.fileExisted {
+            .created
+        } else if let existingChecksum = preState.existingChecksum, let newChecksum {
+            existingChecksum == newChecksum ? .unchanged : .modified
+        } else {
+            .modified
+        }
+    }
+
+    /// Make path relative to working directory captured at init time.
     private func makeRelativePath(_ absolutePath: String) -> String {
-        let cwd = FileManager.default.currentDirectoryPath
-        if absolutePath.hasPrefix(cwd + "/") {
-            return String(absolutePath.dropFirst(cwd.count + 1))
+        if absolutePath.hasPrefix(workingDirectory + "/") {
+            return String(absolutePath.dropFirst(workingDirectory.count + 1))
         }
         return absolutePath
     }

Sources/ExFigCLI/Subcommands/ExportColors.swift

@@ -56,7 +56,7 @@ extension ExFigCommand {
                 reportPath: report,
                 configInput: options.input,
                 ui: ui,
-                buildStats: { ReportStats(colors: $0, icons: 0, images: 0, typography: 0) },
+                buildStats: { .colors($0) },
                 export: { try await performExport(client: client, ui: ui) }
             )
         }

Sources/ExFigCLI/Subcommands/ExportIcons.swift

@@ -57,7 +57,7 @@ extension ExFigCommand {
                 reportPath: report,
                 configInput: options.input,
                 ui: ui,
-                buildStats: { ReportStats(colors: 0, icons: $0, images: 0, typography: 0) },
+                buildStats: { .icons($0) },
                 export: { try await performExport(client: client, ui: ui) }
             )
         }

Sources/ExFigCLI/Subcommands/ExportImages.swift

@@ -56,7 +56,7 @@ extension ExFigCommand {
                 reportPath: report,
                 configInput: options.input,
                 ui: ui,
-                buildStats: { ReportStats(colors: 0, icons: 0, images: $0, typography: 0) },
+                buildStats: { .images($0) },
                 export: { try await performExport(client: client, ui: ui) }
             )
         }

Sources/ExFigCLI/Subcommands/ExportTypography.swift

@@ -45,7 +45,7 @@ extension ExFigCommand {
                 reportPath: report,
                 configInput: options.input,
                 ui: ui,
-                buildStats: { ReportStats(colors: 0, icons: 0, images: 0, typography: $0) },
+                buildStats: { .typography($0) },
                 export: { try await performExport(client: client, ui: ui) }
             )
         }

Tests/ExFigTests/Report/ManifestTrackerTests.swift

@@ -279,7 +279,7 @@ final class AssetManifestTests: XCTestCase {
             ManifestEntry(path: "Same.swift", action: .unchanged, checksum: "fedcba9876543210", assetType: "image"),
         ])
 
-        let data = try JSONEncoder().encode(manifest)
+        let data = try JSONCodec.encode(manifest)
         let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
         let files = json?["files"] as? [[String: Any]]
 
@@ -297,7 +297,7 @@ final class AssetManifestTests: XCTestCase {
 
     func testEmptyManifest() throws {
         let manifest = AssetManifest(files: [])
-        let data = try JSONEncoder().encode(manifest)
+        let data = try JSONCodec.encode(manifest)
         let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
         let files = json?["files"] as? [Any]