fix(lint): eliminate silent failures in PathDataLengthRule and improve test coverage

- Emit warning diagnostic instead of silently returning empty array when URL parsing fails
- Emit warning when Figma returns nil SVG URL for components (previously silently dropped)
- Include icon names in batch failure diagnostics for better debuggability
- Extract validateParsedSVG as internal method for unit testability
- Add tests: components API failure, RTL variant filtering, variant deduplication,
  nil SVG URL handling, pathData critical error (happy path), short pathData (no error)
- Update LintEngine rule count test from 8 to 9
- Add SVGKit dependency to ExFigTests for direct ParsedSVG construction
- Document lint rule testability patterns in CLAUDE.md

Author: alexey1312

CLAUDE.md

@@ -341,6 +341,8 @@ Uses `FigmaAPI.Client.request(SomeEndpoint(...))` directly (no convenience metho
 - Lint rules checking component names MUST use `comp.iconName` (not `comp.name`) — for variants, `name` is the variant value, not the icon name
 - Deduplicate variants by `containingComponentSet.nodeId` before grouping — multiple variants of one set are NOT duplicates
 - Adding error handling to `check()` increases cyclomatic complexity — extract per-entry logic into private methods
+- For unit-testable validation logic in lint rules, use `internal` (not `private`) methods — allows `@testable import` testing without network calls (e.g., `validateParsedSVG`)
+- `LintEngineTests.defaultEngineHasAllRules` checks exact set of rule IDs — must add new rule ID when registering in `LintEngine.default`
 - `NodesEndpoint` supports `geometry: .paths` parameter — returns `fillGeometry`/`strokeGeometry` with SVG path data on vector nodes. **Not suitable for pathData validation** — Figma's SVG export flattens masks/booleans into different paths than raw geometry
 - `PathDataLengthRule` checks ALL platform icon entries (iOS/Android/Flutter/Web), deduplicates by fileId+frame+page. Downloads SVGs via `ImageEndpoint` + `URLSession`, parses with `SVGParser`, validates with `PathDataValidator`. Only reports critical >32,767 byte errors (800-char threshold removed as too noisy). Groups by fileId, batches ImageEndpoint by 50, parallelizes SVG downloads (max 10 concurrent) and fileIds
 
@@ -517,6 +519,7 @@ NooraUI.formatLink("url", useColors: true)  // underlined primary
 | JSON output empty in quiet | `ui.info()` suppressed when `outputMode == .quiet` — machine-readable output (JSON) must use `TerminalOutputManager.shared.print()` directly |
 | `Bundle.module` in tests | SPM test targets without declared resources don't have `Bundle.module` — use `Bundle.main` or temp bundle |
 | SwiftFormat breaks `::` syntax | SwiftFormat 0.60.1+ required for Swift 6.3 module selectors (`FigmaAPI::Client`) |
+| `SVGKit` types in tests | Add `.product(name: "SVGKit", package: "swift-svgkit")` to ExFigTests dependencies in Package.swift for direct `ParsedSVG`/`SVGPath` construction |
 | `fillGeometry` wrong pathData | `fillGeometry` returns raw node geometry, NOT the SVG export result. Figma flattens masks/booleans into different paths. Use `ImageEndpoint` SVG download + `SVGParser` for accurate pathData validation |
 | `NodesEndpoint` no `fillGeometry` | Requires `geometry: .paths` param (swift-figma-api 0.4.0+). Fields are `nil` without it. Useful for geometry inspection but NOT for pathData length validation |
 | MCP SDK 0.12.0 breaking | `.text` has 3 associated values — pattern match as `.text(text, _, _)`; `GetPrompt.arguments` is `[String: String]?` now |

Package.swift

@@ -226,6 +226,7 @@ let package = Package(
             dependencies: [
                 "ExFigCLI",
                 .product(name: "FigmaAPI", package: "swift-figma-api"),
+                .product(name: "SVGKit", package: "swift-svgkit"),
                 "ExFig-Flutter",
                 "ExFig-Web",
                 .product(name: "CustomDump", package: "swift-custom-dump"),

Sources/ExFigCLI/Lint/Rules/PathDataLengthRule.swift

@@ -125,21 +125,37 @@ struct PathDataLengthRule: LintRule {
                     ImageEndpoint(fileId: fileId, nodeIds: nodeIds, params: SVGParams())
                 )
             } catch {
+                let batchNames = batch.prefix(5).map(\.iconName).joined(separator: ", ")
+                let suffix = batch.count > 5 ? " and \(batch.count - 5) more" : ""
+                let msg = "Cannot fetch SVG URLs for \(batch.count) icon(s) "
+                    + "(\(batchNames)\(suffix)): \(error.localizedDescription)"
                 diagnostics.append(diagnostic(
                     severity: .warning,
-                    message: "Cannot fetch SVG URLs: \(error.localizedDescription)",
+                    message: msg,
                     suggestion: "Check FIGMA_PERSONAL_TOKEN and file permissions"
                 ))
                 continue
             }
 
+            var missingURLNames: [String] = []
             for comp in batch {
                 if let urlOpt = imageURLs[comp.nodeId], let url = urlOpt {
                     results.append(SVGItem(
                         name: comp.iconName, nodeId: comp.nodeId, url: url
                     ))
+                } else {
+                    missingURLNames.append(comp.iconName)
                 }
             }
+            if !missingURLNames.isEmpty {
+                let names = missingURLNames.prefix(5).joined(separator: ", ")
+                let suffix = missingURLNames.count > 5 ? " and \(missingURLNames.count - 5) more" : ""
+                diagnostics.append(diagnostic(
+                    severity: .warning,
+                    message: "Figma returned no SVG URL for \(missingURLNames.count) icon(s): \(names)\(suffix)",
+                    suggestion: "These icons could not be rendered — check they are not empty components"
+                ))
+            }
         }
 
         return results
@@ -177,7 +193,15 @@ struct PathDataLengthRule: LintRule {
     }
 
     private func validateSingleIcon(item: SVGItem) async -> [LintDiagnostic] {
-        guard let url = URL(string: item.url) else { return [] }
+        guard let url = URL(string: item.url) else {
+            return [diagnostic(
+                severity: .warning,
+                message: "Invalid SVG URL for '\(item.name)' — cannot validate pathData",
+                componentName: item.name,
+                nodeId: item.nodeId,
+                suggestion: "Re-run lint; if persistent, the Figma API may be returning malformed URLs"
+            )]
+        }
 
         let svgData: Data
         do {
@@ -205,7 +229,13 @@ struct PathDataLengthRule: LintRule {
             )]
         }
 
-        let issues = PathDataValidator().validate(svg: svg, iconName: item.name)
+        return validateParsedSVG(svg, name: item.name, nodeId: item.nodeId)
+    }
+
+    /// Validates a parsed SVG and returns diagnostics for critical pathData issues.
+    /// Internal for testability.
+    func validateParsedSVG(_ svg: ParsedSVG, name: String, nodeId: String) -> [LintDiagnostic] {
+        let issues = PathDataValidator().validate(svg: svg, iconName: name)
 
         // Only report critical issues (>32,767 bytes) — the 800-char lint threshold
         // is too noisy for most icon sets (flags, illustrations regularly exceed it)
@@ -215,11 +245,11 @@ struct PathDataLengthRule: LintRule {
                 severity: .error,
                 message: """
                 pathData exceeds 32,767 bytes (\(issue.result.byteLength) bytes) \
-                in \(item.name)/\(issue.pathName). \
+                in \(name)/\(issue.pathName). \
                 This will cause STRING_TOO_LARGE error during Android build.
                 """,
-                componentName: item.name,
-                nodeId: item.nodeId,
+                componentName: name,
+                nodeId: nodeId,
                 suggestion: "Simplify the path in Figma or use raster format (PNG/WebP)"
             )
         }

Tests/ExFigTests/Lint/LintRulesTests.swift

@@ -4,6 +4,7 @@ import ExFigConfig
 import ExFigCore
 import FigmaAPI
 import Foundation
+import SVGKit
 import Testing
 
 // MARK: - Test Helpers
@@ -629,7 +630,7 @@ struct LintEngineTests {
         #expect(!diagnostics.contains { $0.ruleId == "component-not-frame" })
     }
 
-    @Test("default engine registers all 8 rules")
+    @Test("default engine registers all 9 rules")
     func defaultEngineHasAllRules() {
         let ruleIds = Set(LintEngine.default.rules.map(\.id))
         let expected: Set = [
@@ -641,6 +642,7 @@ struct LintEngineTests {
             "alias-chain-integrity",
             "dark-mode-variables",
             "dark-mode-suffix",
+            "path-data-length",
         ]
         #expect(ruleIds == expected)
     }
@@ -807,6 +809,127 @@ struct PathDataLengthRuleTests {
         #expect(warnings.count == 1)
         #expect(warnings.first?.componentName == "ic_a")
     }
+
+    @Test("emits error when components API fails")
+    func emitsErrorWhenComponentsFail() async throws {
+        let client = MockClient()
+        client.setError(URLError(.notConnectedToInternet), for: ComponentsEndpoint.self)
+
+        let config = makeAndroidIconsConfig(frameName: "Icons")
+        let context = makeLintContext(config: config, client: client)
+        let diagnostics = try await rule.check(context: context)
+
+        #expect(diagnostics.count == 1)
+        #expect(diagnostics.first?.severity == .error)
+        #expect(diagnostics.first?.message.contains("Cannot fetch components") == true)
+    }
+
+    @Test("skips RTL variants")
+    func skipsRTLVariants() async throws {
+        let client = MockClient()
+        client.setResponse([
+            Component.make(nodeId: "1:1", name: "ic_home", frameName: "Icons", pageName: "Page"),
+            makeVariantComponent(
+                nodeId: "1:2", name: "RTL=On", frameName: "Icons", pageName: "Page",
+                componentSetName: "ic_home"
+            ),
+        ], for: ComponentsEndpoint.self)
+
+        let imageURLs: [NodeId: ImagePath?] = ["1:1": "https://invalid.test/home.svg"]
+        client.setResponse(imageURLs, for: ImageEndpoint.self)
+
+        let config = makeAndroidIconsConfig(frameName: "Icons", pageName: "Page")
+        let context = makeLintContext(config: config, client: client)
+        let diagnostics = try await rule.check(context: context)
+
+        // Only ic_home checked, RTL variant skipped — one warning from download failure
+        let warnings = diagnostics.filter { $0.severity == .warning }
+        #expect(warnings.count == 1)
+        #expect(warnings.first?.componentName == "ic_home")
+    }
+
+    @Test("deduplicates variants by component set")
+    func deduplicatesVariants() async throws {
+        let client = MockClient()
+        client.setResponse([
+            makeVariantComponent(
+                nodeId: "1:1", name: "Style=Default", frameName: "Icons", pageName: "Page",
+                componentSetName: "ic_star", componentSetNodeId: "set:1"
+            ),
+            makeVariantComponent(
+                nodeId: "1:2", name: "Style=Filled", frameName: "Icons", pageName: "Page",
+                componentSetName: "ic_star", componentSetNodeId: "set:1"
+            ),
+        ], for: ComponentsEndpoint.self)
+
+        // Only one SVG URL — only first variant should be checked
+        let imageURLs: [NodeId: ImagePath?] = ["1:1": "https://invalid.test/star.svg"]
+        client.setResponse(imageURLs, for: ImageEndpoint.self)
+
+        let config = makeAndroidIconsConfig(frameName: "Icons", pageName: "Page")
+        let context = makeLintContext(config: config, client: client)
+        let diagnostics = try await rule.check(context: context)
+
+        // One warning from download failure — proves only one variant was checked
+        let warnings = diagnostics.filter { $0.severity == .warning }
+        #expect(warnings.count == 1)
+    }
+
+    @Test("warns when Figma returns nil SVG URL")
+    func warnsWhenNilSVGURL() async throws {
+        let client = MockClient()
+        client.setResponse([
+            Component.make(nodeId: "1:1", name: "ic_empty", frameName: "Icons", pageName: "Page"),
+        ], for: ComponentsEndpoint.self)
+
+        // ImageEndpoint returns nil URL for the component
+        let imageURLs: [NodeId: ImagePath?] = ["1:1": nil]
+        client.setResponse(imageURLs, for: ImageEndpoint.self)
+
+        let config = makeAndroidIconsConfig(frameName: "Icons", pageName: "Page")
+        let context = makeLintContext(config: config, client: client)
+        let diagnostics = try await rule.check(context: context)
+
+        #expect(diagnostics.contains { $0.message.contains("no SVG URL") })
+    }
+
+    @Test("validates pathData and reports critical errors")
+    func reportsPathDataCriticalError() {
+        // Generate a path that exceeds 32,767 bytes
+        let longPath = String(repeating: "M0 0L1 1", count: 5000)
+        let svg = ParsedSVG(
+            width: 24, height: 24, viewportWidth: 24, viewportHeight: 24,
+            paths: [SVGPath(
+                pathData: longPath, commands: [], fill: nil, fillType: .none,
+                stroke: nil, strokeWidth: nil, strokeLineCap: nil, strokeLineJoin: nil,
+                strokeDashArray: nil, strokeDashOffset: nil, fillRule: nil, opacity: nil,
+                fillOpacity: nil
+            )]
+        )
+
+        let diagnostics = rule.validateParsedSVG(svg, name: "ic_complex", nodeId: "1:1")
+
+        #expect(diagnostics.count == 1)
+        #expect(diagnostics.first?.severity == .error)
+        #expect(diagnostics.first?.message.contains("32,767 bytes") == true)
+        #expect(diagnostics.first?.componentName == "ic_complex")
+    }
+
+    @Test("no error for short pathData")
+    func noErrorForShortPathData() {
+        let svg = ParsedSVG(
+            width: 24, height: 24, viewportWidth: 24, viewportHeight: 24,
+            paths: [SVGPath(
+                pathData: "M12 2L22 12L12 22L2 12Z", commands: [], fill: nil, fillType: .none,
+                stroke: nil, strokeWidth: nil, strokeLineCap: nil, strokeLineJoin: nil,
+                strokeDashArray: nil, strokeDashOffset: nil, fillRule: nil, opacity: nil,
+                fillOpacity: nil
+            )]
+        )
+
+        let diagnostics = rule.validateParsedSVG(svg, name: "ic_simple", nodeId: "1:1")
+        #expect(diagnostics.isEmpty)
+    }
 }
 
 // swiftlint:enable file_length