From f25b9e9ab8610a4621e11ecbcbfac100f6380d0a Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:27:13 -0700 Subject: [PATCH 01/18] feat: add parity-api-coverage swiftpm targets and product --- .../SwiftDataParity/AppleRunner/Package.swift | 24 +++++++++++++++++++ .../Sources/ParityApiCoverage/main.swift | 1 + .../PlaceholderTests.swift | 2 ++ 3 files changed, 27 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Package.swift b/Tests/SwiftDataParity/AppleRunner/Package.swift index 0f12088b..cb597661 100644 --- a/Tests/SwiftDataParity/AppleRunner/Package.swift +++ b/Tests/SwiftDataParity/AppleRunner/Package.swift @@ -9,6 +9,7 @@ let package = Package( .executable(name: "apple-parity-runner", targets: ["AppleParityRunner"]), .executable(name: "parity-validate", targets: ["ParityValidate"]), .executable(name: "parity-compare", targets: ["ParityCompare"]), + .executable(name: "parity-api-coverage", targets: ["ParityApiCoverage"]), ], dependencies: [ .package(path: "../Contracts"), @@ -42,6 +43,29 @@ let package = Package( .target( name: "ParityCompareRuntime", dependencies: [.product(name: "ParityContracts", package: "contracts")]), + .executableTarget( + name: "ParityApiCoverage", + dependencies: [ + .product(name: "ParityContracts", package: "contracts"), + "ParityApiCoverageRuntime", + ], + path: "Sources/ParityApiCoverage"), + .target( + name: "ParityApiCoverageRuntime", + dependencies: [ + .product(name: "ParityContracts", package: "contracts"), + .product(name: "SwiftParser", package: "swift-syntax"), + .product(name: "SwiftParserDiagnostics", package: "swift-syntax"), + .product(name: "SwiftSyntax", package: "swift-syntax"), + ], + path: "Sources/ParityApiCoverageRuntime"), + .testTarget( + name: "ParityApiCoverageTests", + dependencies: [ + .product(name: "ParityContracts", package: "contracts"), + "ParityApiCoverageRuntime", + ], + path: "Tests/ParityApiCoverageTests"), .testTarget( name: "ParityToolTests", dependencies: [ diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift new file mode 100644 index 00000000..ff7bd09c --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift @@ -0,0 +1 @@ +// placeholder diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift new file mode 100644 index 00000000..a0e79ff6 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift @@ -0,0 +1,2 @@ +import Testing +@Test func placeholder() {} From 7cc319aa8ce43c552189733735897c5523d1b9f6 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:27:17 -0700 Subject: [PATCH 02/18] feat: add api coverage data models --- .../ParityApiCoverageRuntime/Models.swift | 496 ++++++++++++++++++ 1 file changed, 496 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift new file mode 100644 index 00000000..b676a5d9 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift @@ -0,0 +1,496 @@ +import Foundation +import CryptoKit +import ParityContracts + +// Data models for the API-surface coverage validator. All public types are +// Sendable so they can cross the (potential) actor boundaries between the +// orchestrator and the runtime components. + +/// The kind of a public SwiftData API symbol, matching the `kind` strings +/// required by Requirement 3.4. `associatedtype`, `macro`, and `case` are +/// Swift keywords and must be backticked. +public enum SymbolKind: String, Codable, Sendable, Equatable, Hashable { + case structKind = "struct" + case classKind = "class" + case enumKind = "enum" + case protocolKind = "protocol" + case actorKind = "actor" + case typealiasKind = "typealias" + case function + case initializer + case variable + case subscriptKind = "subscript" + case `associatedtype` = "associatedtype" + case `macro` = "macro" + case `case` = "case" +} + +/// A single public declaration in the SwiftData API surface. +public struct API_Symbol: Codable, Equatable, Sendable { + public let kind: SymbolKind + public let displayName: String + public let fullyQualifiedName: String + public let sourceSignature: String + public let platformAvailability: PlatformAvailability + public let arity: Int + public var mangledName: String + public let deprecated: Bool + + public init( + kind: SymbolKind, + displayName: String, + fullyQualifiedName: String, + sourceSignature: String, + platformAvailability: PlatformAvailability, + arity: Int, + mangledName: String = "", + deprecated: Bool + ) { + self.kind = kind + self.displayName = displayName + self.fullyQualifiedName = fullyQualifiedName + self.sourceSignature = sourceSignature + self.platformAvailability = platformAvailability + self.arity = arity + self.mangledName = mangledName + self.deprecated = deprecated + } +} + +/// Parsed `@available(...)` record. Version strings, when present, match +/// `^\d+(\.\d+)?$`. The extractor normalizes bare majors to `major.0`. +public struct PlatformAvailability: Codable, Equatable, Sendable { + public let macOS: String? + public let iOS: String? + public let tvOS: String? + public let watchOS: String? + public let visionOS: String? + public let unavailable: Bool + public let deprecated: Bool + + public init( + macOS: String? = nil, + iOS: String? = nil, + tvOS: String? = nil, + watchOS: String? = nil, + visionOS: String? = nil, + unavailable: Bool = false, + deprecated: Bool = false + ) { + self.macOS = macOS + self.iOS = iOS + self.tvOS = tvOS + self.watchOS = watchOS + self.visionOS = visionOS + self.unavailable = unavailable + self.deprecated = deprecated + } + + /// The set of platforms that have an explicit version or unavailability. + public var mentionedPlatforms: [String] { + var result: [String] = [] + if macOS != nil { result.append("macOS") } + if iOS != nil { result.append("iOS") } + if tvOS != nil { result.append("tvOS") } + if watchOS != nil { result.append("watchOS") } + if visionOS != nil { result.append("visionOS") } + return result + } +} + +/// A syntactic occurrence in a scanned source file that names an `API_Symbol`. +/// The custom `Codable` omits `displayName` from the report JSON per +/// Requirement 3.4; `displayName` is kept in memory for matching. +public struct Reference: Codable, Equatable, Sendable { + public let file: String + public let line: Int + public let column: Int + public let displayName: String + public var matchQuality: MatchQuality + + public enum MatchQuality: String, Codable, Sendable, Equatable { + case name + case nameContext = "name-context" + case signature + case signatureAmbiguous = "signature-ambiguous" + } + + public init(file: String, line: Int, column: Int, displayName: String, matchQuality: MatchQuality) { + self.file = file + self.line = line + self.column = column + self.displayName = displayName + self.matchQuality = matchQuality + } + + private enum ReportCodingKeys: String, CodingKey { + case file, line, column, matchQuality + } + + private enum FullCodingKeys: String, CodingKey { + case file, line, column, displayName, matchQuality + } + + public init(from decoder: Decoder) throws { + let c = try decoder.container(keyedBy: FullCodingKeys.self) + self.file = try c.decode(String.self, forKey: .file) + self.line = try c.decode(Int.self, forKey: .line) + self.column = try c.decode(Int.self, forKey: .column) + self.displayName = try c.decodeIfPresent(String.self, forKey: .displayName) ?? "" + self.matchQuality = try c.decode(MatchQuality.self, forKey: .matchQuality) + } + + public func encode(to encoder: Encoder) throws { + var c = encoder.container(keyedBy: ReportCodingKeys.self) + try c.encode(file, forKey: .file) + try c.encode(line, forKey: .line) + try c.encode(column, forKey: .column) + try c.encode(matchQuality, forKey: .matchQuality) + } +} + +/// A single entry in the API coverage allowlist. `issueURL` is a `String` to +/// preserve placeholder bytes for the human editor; validation parses it with +/// `URL(string:)` and checks `scheme == "https"`. +public struct AllowlistEntry: Codable, Equatable, Sendable { + public let fullyQualifiedName: String + public let kind: String? + public let reasonCategory: String + public let rationale: String + public let issueURL: String + public let expiration: String + + public init( + fullyQualifiedName: String, + kind: String?, + reasonCategory: String, + rationale: String, + issueURL: String, + expiration: String + ) { + self.fullyQualifiedName = fullyQualifiedName + self.kind = kind + self.reasonCategory = reasonCategory + self.rationale = rationale + self.issueURL = issueURL + self.expiration = expiration + } +} + +/// Fingerprint of the macOS SDK the report was produced against. +public struct SDKFingerprint: Codable, Equatable, Sendable { + public let sdkPath: String + public let swiftInterfaceSHA256: String + public let swiftInterfaceByteCount: Int + + public init(sdkPath: String, swiftInterfaceSHA256: String, swiftInterfaceByteCount: Int) { + self.sdkPath = sdkPath + self.swiftInterfaceSHA256 = swiftInterfaceSHA256 + self.swiftInterfaceByteCount = swiftInterfaceByteCount + } +} + +/// A symbol's coverage record in the report. `kind` is the `SymbolKind.rawValue` +/// string per Requirement 3.4. Allowlist fields are populated by +/// `AllowlistValidator`; `CoverageEngine` emits them as `false`/`nil`. +public struct SymbolRecord: Codable, Equatable, Sendable { + public let kind: String + public let displayName: String + public let fullyQualifiedName: String + public let sourceSignature: String + public let platformAvailability: PlatformAvailability + public let covered: Bool + public let referenceCount: Int + public let references: [Reference] + public let allowlisted: Bool + public let allowlistReasonCategory: String? + public let allowlistRationale: String? + public let allowlistIssueURL: String? + public let mangledName: String + + public init( + kind: String, + displayName: String, + fullyQualifiedName: String, + sourceSignature: String, + platformAvailability: PlatformAvailability, + covered: Bool, + referenceCount: Int, + references: [Reference], + allowlisted: Bool = false, + allowlistReasonCategory: String? = nil, + allowlistRationale: String? = nil, + allowlistIssueURL: String? = nil, + mangledName: String + ) { + self.kind = kind + self.displayName = displayName + self.fullyQualifiedName = fullyQualifiedName + self.sourceSignature = sourceSignature + self.platformAvailability = platformAvailability + self.covered = covered + self.referenceCount = referenceCount + self.references = references + self.allowlisted = allowlisted + self.allowlistReasonCategory = allowlistReasonCategory + self.allowlistRationale = allowlistRationale + self.allowlistIssueURL = allowlistIssueURL + self.mangledName = mangledName + } +} + +/// The top-level API coverage report emitted by the validator. +public struct APICoverageReport: Codable, Equatable, Sendable { + public let schemaVersion: Int + public let strategy: String + public let sdkFingerprint: SDKFingerprint + public let evaluationDate: String + public let generatedAt: String + public let totalSymbolCount: Int + public let coveredSymbolCount: Int + public let uncoveredSymbolCount: Int + public let excludedSymbolCount: Int + public let coverageValid: Bool + public let allowlistSHA256: String + public let validationIssues: [String] + public let symbols: [SymbolRecord] + + public init( + schemaVersion: Int, + strategy: String, + sdkFingerprint: SDKFingerprint, + evaluationDate: String, + generatedAt: String, + totalSymbolCount: Int, + coveredSymbolCount: Int, + uncoveredSymbolCount: Int, + excludedSymbolCount: Int, + coverageValid: Bool, + allowlistSHA256: String, + validationIssues: [String], + symbols: [SymbolRecord] + ) { + self.schemaVersion = schemaVersion + self.strategy = strategy + self.sdkFingerprint = sdkFingerprint + self.evaluationDate = evaluationDate + self.generatedAt = generatedAt + self.totalSymbolCount = totalSymbolCount + self.coveredSymbolCount = coveredSymbolCount + self.uncoveredSymbolCount = uncoveredSymbolCount + self.excludedSymbolCount = excludedSymbolCount + self.coverageValid = coverageValid + self.allowlistSHA256 = allowlistSHA256 + self.validationIssues = validationIssues + self.symbols = symbols + } +} + +/// Identity key for an `API_Symbol`, used to deduplicate by signature. +public struct API_SymbolIdentity: Hashable, Sendable { + public let fullyQualifiedName: String + public let kind: SymbolKind + public let sourceSignature: String + + public init(fullyQualifiedName: String, kind: SymbolKind, sourceSignature: String) { + self.fullyQualifiedName = fullyQualifiedName + self.kind = kind + self.sourceSignature = sourceSignature + } +} + +/// The extracted SwiftData API surface: non-excluded symbols plus precomputed +/// lookup indexes. Indexes are computed eagerly in `init` so they stay in sync +/// with `symbols`. `symbolsByMangledName` starts empty and is populated by +/// `APISurfaceExtractor.joinSymbolGraph`. +public struct ExtractedSurface: Sendable { + public let symbols: [API_Symbol] + public let excludedCount: Int + public let displayNames: Set + public let symbolsByDisplayName: [String: [API_Symbol]] + public let symbolsByIdentity: [API_SymbolIdentity: API_Symbol] + public var symbolsByMangledName: [String: API_Symbol] + + public init(symbols: [API_Symbol], excludedCount: Int) { + self.symbols = symbols + self.excludedCount = excludedCount + self.displayNames = Set(symbols.map(\.displayName)) + self.symbolsByDisplayName = Dictionary(grouping: symbols, by: \.displayName) + self.symbolsByIdentity = Dictionary(uniqueKeysWithValues: symbols.map { + (API_SymbolIdentity(fullyQualifiedName: $0.fullyQualifiedName, kind: $0.kind, sourceSignature: $0.sourceSignature), $0) + }) + self.symbolsByMangledName = [:] + } +} + +/// The symbol-match strategy, selectable via `--strategy`. +public enum Strategy: String, Sendable, Equatable { + case nameMatch = "name-match" + case signaturePrecise = "signature-precise" +} + +/// The UTC calendar date against which allowlist expirations are compared. +/// Carries both the `gregorianDay` string and the `foundationDate` (GMT +/// start-of-day) used for inclusive `>=` comparisons. +public struct EvaluationDate: Sendable, Equatable { + public let gregorianDay: String + public let foundationDate: Date + + /// Parses and validates a `YYYY-MM-DD` string. Throws on regex mismatch or + /// an invalid calendar date (e.g. `2026-02-31`). Uses `isLenient = false` + /// so the formatter rejects nonexistent days. + public init(gregorianDay: String) throws { + let dayRegex = try NSRegularExpression(pattern: #"^\d{4}-\d{2}-\d{2}$"#) + guard dayRegex.firstMatch(in: gregorianDay, range: NSRange(gregorianDay.startIndex..., in: gregorianDay)) != nil else { + throw EvaluationDateError.invalidFormat(gregorianDay) + } + let formatter = DateFormatter() + formatter.locale = Locale(identifier: "en_US_POSIX") + formatter.timeZone = TimeZone(secondsFromGMT: 0) + formatter.dateFormat = "yyyy-MM-dd" + formatter.isLenient = false + guard let date = formatter.date(from: gregorianDay) else { + throw EvaluationDateError.invalidCalendarDate(gregorianDay) + } + self.gregorianDay = gregorianDay + self.foundationDate = date + } + + /// Derives the GMT start-of-day for the given `Date`. + public init(date: Date) { + var calendar = Calendar(identifier: .gregorian) + calendar.timeZone = TimeZone(secondsFromGMT: 0)! + let startOfDay = calendar.startOfDay(for: date) + let formatter = DateFormatter() + formatter.locale = Locale(identifier: "en_US_POSIX") + formatter.timeZone = TimeZone(secondsFromGMT: 0) + formatter.dateFormat = "yyyy-MM-dd" + self.gregorianDay = formatter.string(from: startOfDay) + self.foundationDate = startOfDay + } +} + +public enum EvaluationDateError: Error, Equatable, Sendable, CustomStringConvertible { + case invalidFormat(String) + case invalidCalendarDate(String) + + public var description: String { + switch self { + case let .invalidFormat(value): "invalid evaluation date format: \(value)" + case let .invalidCalendarDate(value): "invalid calendar date: \(value)" + } + } +} + +/// Resolved filesystem locations and fingerprints for a validator run. +public struct ResolvedPaths: Sendable { + public let repositoryRoot: URL + public let paritySourceDirectory: URL + public let implementationDirectories: [URL] + public let allowlistURL: URL + public let reportURL: URL + public let swiftInterfaceURL: URL + public let sdkRoot: URL + public let sdkFingerprint: SDKFingerprint + public let evaluationDate: EvaluationDate + public let strategy: Strategy + + public init( + repositoryRoot: URL, + paritySourceDirectory: URL, + implementationDirectories: [URL], + allowlistURL: URL, + reportURL: URL, + swiftInterfaceURL: URL, + sdkRoot: URL, + sdkFingerprint: SDKFingerprint, + evaluationDate: EvaluationDate, + strategy: Strategy + ) { + self.repositoryRoot = repositoryRoot + self.paritySourceDirectory = paritySourceDirectory + self.implementationDirectories = implementationDirectories + self.allowlistURL = allowlistURL + self.reportURL = reportURL + self.swiftInterfaceURL = swiftInterfaceURL + self.sdkRoot = sdkRoot + self.sdkFingerprint = sdkFingerprint + self.evaluationDate = evaluationDate + self.strategy = strategy + } +} + +/// Context for a containing type while walking the `.swiftinterface`. The +/// visitor merges availability across the stack to compute each symbol's +/// effective `PlatformAvailability`. +public struct TypeContext: Sendable, Equatable { + public let fullyQualifiedName: String + public let kind: SymbolKind + public let availability: PlatformAvailability + + public init(fullyQualifiedName: String, kind: SymbolKind, availability: PlatformAvailability) { + self.fullyQualifiedName = fullyQualifiedName + self.kind = kind + self.availability = availability + } +} + +/// The coverage computation result. `symbols` carries `SymbolRecord`s with +/// allowlist fields all `false`/`nil`; `AllowlistValidator` rebuilds them with +/// allowlist fields populated. `surface` is retained for stale-entry checks. +public struct CoverageResult: Sendable { + public let symbols: [SymbolRecord] + public let coveredSymbolCount: Int + public let uncoveredSymbolCount: Int + public let excludedCount: Int + public let surface: ExtractedSurface + + public init( + symbols: [SymbolRecord], + coveredSymbolCount: Int, + uncoveredSymbolCount: Int, + excludedCount: Int, + surface: ExtractedSurface + ) { + self.symbols = symbols + self.coveredSymbolCount = coveredSymbolCount + self.uncoveredSymbolCount = uncoveredSymbolCount + self.excludedCount = excludedCount + self.surface = surface + } +} + +/// The allowlist validation result. `annotatedSymbols` are rebuilt with +/// allowlist fields populated for matching uncovered symbols. +public struct AllowlistValidation: Sendable { + public let annotatedSymbols: [SymbolRecord] + public let validationIssues: [String] + public let valid: Bool + + public init(annotatedSymbols: [SymbolRecord], validationIssues: [String], valid: Bool) { + self.annotatedSymbols = annotatedSymbols + self.validationIssues = validationIssues + self.valid = valid + } +} + +/// Allowlist annotation applied to a matching uncovered symbol. +public struct AllowlistAnnotation: Sendable, Equatable { + public let reasonCategory: String + public let rationale: String + public let issueURL: String + + public init(reasonCategory: String, rationale: String, issueURL: String) { + self.reasonCategory = reasonCategory + self.rationale = rationale + self.issueURL = issueURL + } +} + +/// SHA-256 hashing helper. Lowercase hex digest, accessible from any target +/// that imports this module. +public enum Hashing { + public static func sha256Hex(_ data: Data) -> String { + SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined() + } +} From 6b440e5e7c71e4f71b43e5c61d2c87cd9bd7159f Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:27:17 -0700 Subject: [PATCH 03/18] feat: add name stoplist and permitted reason categories --- .../ParityApiCoverageRuntime/Constants.swift | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Constants.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Constants.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Constants.swift new file mode 100644 index 00000000..f8f118fe --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Constants.swift @@ -0,0 +1,26 @@ +import ParityContracts + +// Fixed vocabularies for the API-surface coverage validator. + +/// The `Name_Stoplist`: display names too generic for unqualified `name-match` +/// coverage. A reference to a stoplisted name is recorded only when the file +/// imports a SwiftData-family module or the reference is a member access whose +/// receiver is named like a known SwiftData type (see `ReferenceScanner`). +public enum NameStoplist { + public static let entries: Set = [ + "init", "deinit", "id", "hashValue", "description", "debugDescription", + "rawValue", "encode", "decode", "hash", "save", "fetch", "delete", + "name", "url", "count", "insert", "rollback", "erase", + ] +} + +/// The `Permitted_Reason_Categories`: the fixed set of strings allowed as +/// `reasonCategory` in the API coverage allowlist. The first six are reused +/// from `CoverageMatrixValidator.permittedReasons`; the last two cover +/// SwiftUI-only bindings and platform-specific integration points that +/// OpenSwiftData does not target. +public enum PermittedReasonCategories { + public static let all: Set = CoverageMatrixValidator.permittedReasons.union([ + "swiftui-only-api", "platform-integration-api", + ]) +} From be9e9f045f052f229e52a6f06356a3f62b0e1ac5 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:27:17 -0700 Subject: [PATCH 04/18] feat: add path resolver with xcrun and artifactbundle fallback --- .../PathResolver.swift | 239 ++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift new file mode 100644 index 00000000..b4aa9961 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift @@ -0,0 +1,239 @@ +import Foundation + +// Resolves the repository root, the SwiftData `.swiftinterface`, the SDK +// fingerprint, the scan roots, and the allowlist/report paths for a validator +// run. The interface is located by an ordered procedure: an explicit `--sdk` +// path, then `xcrun --show-sdk-path`, then the SwiftPM SDK artifact bundle. + +public enum PathResolverError: Error, Equatable, Sendable, CustomStringConvertible { + case repositoryRootNotFound + case swiftInterfaceNotFound(searchedRoots: [String]) + + public var description: String { + switch self { + case .repositoryRootNotFound: + "repository root not found (no directory containing both Package.swift and Tests/OpenSwiftDataTests/Parity)" + case let .swiftInterfaceNotFound(searchedRoots): + "SwiftData.swiftinterface not found under any searched root:\n" + searchedRoots.map { " - \($0)" }.joined(separator: "\n") + } + } +} + +public enum PathResolver { + /// Walks upward from `start` until a directory contains both `Package.swift` + /// and `Tests/OpenSwiftDataTests/Parity`, mirroring `ParityValidate`'s logic. + public static func locateRepositoryRoot(from start: URL) throws -> URL { + var candidate = start.standardizedFileURL + while candidate.path != "/" { + let manifest = candidate.appending(path: "Package.swift") + let parityTests = candidate.appending(path: "Tests/OpenSwiftDataTests/Parity") + if FileManager.default.fileExists(atPath: manifest.path), + FileManager.default.fileExists(atPath: parityTests.path) + { + return candidate + } + candidate.deleteLastPathComponent() + } + throw PathResolverError.repositoryRootNotFound + } + + /// Searches `sdkRoot` for a `SwiftData.swiftmodule/-apple-macos.swiftinterface` + /// file. When multiple architecture variants are found, prefers `arm64e`, + /// then `arm64`, then any other, then by lexicographic order of the arch prefix. + public static func locateSwiftInterface(sdkRoot: URL) throws -> URL { + let regex = try NSRegularExpression(pattern: #"/SwiftData\.swiftmodule/[^/]+-apple-macos\.swiftinterface$"#) + var matches: [URL] = [] + if let enumerator = FileManager.default.enumerator( + at: sdkRoot, + includingPropertiesForKeys: [.isRegularFileKey], + options: [.skipsHiddenFiles] + ) { + for case let url as URL in enumerator { + let values = try? url.resourceValues(forKeys: [.isRegularFileKey]) + guard values?.isRegularFile == true else { continue } + let path = url.path + let range = NSRange(path.startIndex..., in: path) + if regex.firstMatch(in: path, range: range) != nil { + matches.append(url) + } + } + } + guard !matches.isEmpty else { + throw PathResolverError.swiftInterfaceNotFound(searchedRoots: [sdkRoot.path]) + } + return matches.sorted { a, b in + let archA = archPrefix(of: a) + let archB = archPrefix(of: b) + return (rank(for: archA), archA) < (rank(for: archB), archB) + }.first! + } + + /// Extracts the architecture prefix from a `.swiftinterface` path, i.e. the + /// substring before `-apple-macos`. + private static func archPrefix(of url: URL) -> String { + let name = url.lastPathComponent + if let range = name.range(of: "-apple-macos") { + return String(name[.. Int { + switch arch { + case "arm64e": 0 + case "arm64": 1 + default: 2 + } + } + + /// Resolves every input path for a validator run. The SDK root is derived + /// by ordered fallback: explicit `--sdk`, then `xcrun --show-sdk-path`, then + /// the SwiftPM SDK artifact bundle at `~/.swiftpm/swift-sdks/darwin.artifactbundle`. + public static func resolve( + strategy: Strategy, + reportPath: String?, + allowlistPath: String?, + sdkPath: String?, + today: String? + ) throws -> ResolvedPaths { + let repositoryRoot = try locateRepositoryRoot(from: URL(fileURLWithPath: FileManager.default.currentDirectoryPath)) + let paritySourceDirectory = repositoryRoot.appending(path: "Tests/OpenSwiftDataTests/Parity") + + var searchedRoots: [String] = [] + if let sdkPath { + let candidate = URL(fileURLWithPath: sdkPath) + do { + let interface = try locateSwiftInterface(sdkRoot: candidate) + return try finishResolve( + repositoryRoot: repositoryRoot, + paritySourceDirectory: paritySourceDirectory, + sdkRoot: candidate, + swiftInterfaceURL: interface, + strategy: strategy, + reportPath: reportPath, + allowlistPath: allowlistPath, + today: today + ) + } catch PathResolverError.swiftInterfaceNotFound(let roots) { + searchedRoots.append(contentsOf: roots) + } + } + if let xcrunRoot = try? runXcrunShowSdkPath(), !xcrunRoot.path.isEmpty { + do { + let interface = try locateSwiftInterface(sdkRoot: xcrunRoot) + return try finishResolve( + repositoryRoot: repositoryRoot, + paritySourceDirectory: paritySourceDirectory, + sdkRoot: xcrunRoot, + swiftInterfaceURL: interface, + strategy: strategy, + reportPath: reportPath, + allowlistPath: allowlistPath, + today: today + ) + } catch PathResolverError.swiftInterfaceNotFound(let roots) { + searchedRoots.append(contentsOf: roots) + } + } + let bundleRoot = FileManager.default.homeDirectoryForCurrentUser + .appending(path: ".swiftpm/swift-sdks/darwin.artifactbundle") + if FileManager.default.fileExists(atPath: bundleRoot.path) { + do { + let interface = try locateSwiftInterface(sdkRoot: bundleRoot) + return try finishResolve( + repositoryRoot: repositoryRoot, + paritySourceDirectory: paritySourceDirectory, + sdkRoot: bundleRoot, + swiftInterfaceURL: interface, + strategy: strategy, + reportPath: reportPath, + allowlistPath: allowlistPath, + today: today + ) + } catch PathResolverError.swiftInterfaceNotFound(let roots) { + searchedRoots.append(contentsOf: roots) + } + } + throw PathResolverError.swiftInterfaceNotFound(searchedRoots: searchedRoots) + } + + /// Builds the `ResolvedPaths` once the interface file is located. + private static func finishResolve( + repositoryRoot: URL, + paritySourceDirectory: URL, + sdkRoot: URL, + swiftInterfaceURL: URL, + strategy: Strategy, + reportPath: String?, + allowlistPath: String?, + today: String? + ) throws -> ResolvedPaths { + let bytes = try Data(contentsOf: swiftInterfaceURL) + let sdkFingerprint = SDKFingerprint( + sdkPath: sdkRoot.path, + swiftInterfaceSHA256: Hashing.sha256Hex(bytes), + swiftInterfaceByteCount: bytes.count + ) + let evaluationDate: EvaluationDate + if let today { + evaluationDate = try EvaluationDate(gregorianDay: today) + } else { + evaluationDate = EvaluationDate(date: Date()) + } + let implementationDirectories = try discoverImplementationDirectories(repositoryRoot: repositoryRoot) + let allowlistURL = allowlistPath.map { URL(fileURLWithPath: $0) } + ?? repositoryRoot.appending(path: "Tests/SwiftDataParity/parity-api-coverage-allowlist.json") + let reportURL = reportPath.map { URL(fileURLWithPath: $0) } + ?? repositoryRoot.appending(path: "parity-api-coverage-report.json") + return ResolvedPaths( + repositoryRoot: repositoryRoot, + paritySourceDirectory: paritySourceDirectory, + implementationDirectories: implementationDirectories, + allowlistURL: allowlistURL, + reportURL: reportURL, + swiftInterfaceURL: swiftInterfaceURL, + sdkRoot: sdkRoot, + sdkFingerprint: sdkFingerprint, + evaluationDate: evaluationDate, + strategy: strategy + ) + } + + /// Lists direct subdirectories of `/Sources` whose name does not start + /// with `.`, sorted lexicographically. Discovered at runtime so new modules + /// are picked up automatically. + private static func discoverImplementationDirectories(repositoryRoot: URL) throws -> [URL] { + let sourcesRoot = repositoryRoot.appending(path: "Sources") + guard FileManager.default.fileExists(atPath: sourcesRoot.path) else { return [] } + let children = try FileManager.default.contentsOfDirectory( + at: sourcesRoot, + includingPropertiesForKeys: [.isDirectoryKey], + options: [.skipsHiddenFiles] + ) + return children + .filter { (try? $0.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) == true } + .filter { !$0.lastPathComponent.hasPrefix(".") } + .sorted { $0.path < $1.path } + } + + /// Invokes `/usr/bin/xcrun --show-sdk-path` and returns the trimmed stdout + /// as a URL. Returns `nil` on any failure. + private static func runXcrunShowSdkPath() throws -> URL? { + let process = Process() + process.executableURL = URL(fileURLWithPath: "/usr/bin/xcrun") + process.arguments = ["--show-sdk-path"] + let pipe = Pipe() + process.standardOutput = pipe + do { + try process.run() + process.waitUntilExit() + } catch { + return nil + } + guard process.terminationStatus == 0 else { return nil } + let data = pipe.fileHandleForReading.readDataToEndOfFile() + let output = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "" + return output.isEmpty ? nil : URL(fileURLWithPath: output) + } +} From 65a80d98c33eb2f170993e2957eed94e94b9fd6b Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:27:17 -0700 Subject: [PATCH 05/18] feat: add api surface extractor and symbol visitor --- .../APISurfaceExtractor.swift | 663 ++++++++++++++++++ 1 file changed, 663 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift new file mode 100644 index 00000000..0659ff85 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift @@ -0,0 +1,663 @@ +import Foundation +import SwiftParser +import SwiftParserDiagnostics +import SwiftSyntax +import ParityContracts + +// Extracts the SwiftData public API surface from a `.swiftinterface` file and, +// for the `signature-precise` strategy, joins a symbol graph's USRs into the +// extracted symbols. + +public enum APISurfaceExtractorError: Error, Equatable, Sendable { + case unparseableInterface(diagnostics: [String]) +} + +public enum APISurfaceExtractor { + /// Parses `interfaceFile` with SwiftParser, walks it with + /// `SymbolExtractorVisitor`, drops `Excluded_Symbol`s, and returns the + /// `ExtractedSurface` with precomputed lookup indexes. + public static func extract(interfaceFile: URL) throws -> ExtractedSurface { + let bytes = try Data(contentsOf: interfaceFile) + let source = String(decoding: bytes, as: UTF8.self) + let tree = Parser.parse(source: source) + let diagnostics = ParseDiagnosticsGenerator.diagnostics(for: tree) + let errors = diagnostics.filter { $0.diagMessage.severity == .error }.map(\.message) + guard errors.isEmpty else { + throw APISurfaceExtractorError.unparseableInterface(diagnostics: errors) + } + let visitor = SymbolExtractorVisitor(viewMode: .sourceAccurate) + visitor.walk(tree) + let records = visitor.records + let nonExcluded = records.filter { !$0.isExcluded }.map(\.symbol) + let excludedCount = records.count - nonExcluded.count + return ExtractedSurface(symbols: nonExcluded, excludedCount: excludedCount) + } + + /// Joins symbol-graph USRs into `surface.symbolsByMangledName`. Reads all + /// `*.symbols.json` files in `symbolGraphDirectory` (sorted by path) and + /// matches each symbol-graph symbol to an `API_Symbol` by + /// `(fullyQualifiedName, kind, arity)`. On any failure (no files, decode + /// error, zero matches) the surface is left unchanged. Non-throwing per the + /// design: failures mean `mangledName` stays empty and `signature-precise` + /// degrades to `name-match`. + public static func joinSymbolGraph(_ surface: inout ExtractedSurface, symbolGraphDirectory: URL) { + var graphFiles: [URL] = [] + if let enumerator = FileManager.default.enumerator( + at: symbolGraphDirectory, + includingPropertiesForKeys: [.isRegularFileKey], + options: [.skipsHiddenFiles] + ) { + for case let url as URL in enumerator where url.pathExtension == "json" { + graphFiles.append(url) + } + } + graphFiles.sort { $0.path < $1.path } + guard !graphFiles.isEmpty else { return } + + let decoder = JSONDecoder() + var lookup: [String: [Int]] = [:] + for (index, symbol) in surface.symbols.enumerated() { + let key = "\(symbol.fullyQualifiedName)#\(symbol.kind.rawValue)#\(symbol.arity)" + lookup[key, default: []].append(index) + } + + var newSymbols = surface.symbols + var newMangledMap: [String: API_Symbol] = [:] + var matched = false + for file in graphFiles { + guard let data = try? Data(contentsOf: file), + let graph = try? decoder.decode(SymbolGraphFile.self, from: data) + else { continue } + for sgSymbol in graph.symbols { + let fqn = "SwiftData." + sgSymbol.pathComponents.joined(separator: ".") + guard let kind = Self.kind(for: sgSymbol.kind.identifier) else { continue } + let arity = sgSymbol.functionSignature?.parameters.count ?? 0 + let key = "\(fqn)#\(kind.rawValue)#\(arity)" + guard let indices = lookup[key], !indices.isEmpty else { continue } + for index in indices { + newSymbols[index].mangledName = sgSymbol.identifier.usr + newMangledMap[sgSymbol.identifier.usr] = newSymbols[index] + matched = true + } + } + } + guard matched else { return } + surface = ExtractedSurface(symbols: newSymbols, excludedCount: surface.excludedCount) + surface.symbolsByMangledName = newMangledMap + } + + /// Maps a symbol-graph kind identifier (e.g. `swift.func`, `swift.struct`) + /// to the corresponding `SymbolKind`. Returns `nil` for kinds the validator + /// does not track. + private static func kind(for identifier: String) -> SymbolKind? { + switch identifier { + case "swift.struct": .structKind + case "swift.class": .classKind + case "swift.enum": .enumKind + case "swift.protocol": .protocolKind + case "swift.actor": .actorKind + case "swift.typealias": .typealiasKind + case "swift.func", "swift.method", "swift.method.static", "swift.method.instance": .function + case "swift.init", "swift.constructor": .initializer + case "swift.property", "swift.var", "swift.var.instance", "swift.var.static", "swift.var.class": .variable + case "swift.subscript": .subscriptKind + case "swift.associatedtype": .associatedtype + case "swift.macro": .macro + case "swift.enum.case": .case + default: nil + } + } +} + +// MARK: - Symbol graph JSON shapes + +// Concrete Codable structs for the subset of `swift symbolgraph-extract` output +// the join needs. + +struct SymbolGraphFile: Codable { + let symbols: [SymbolGraphSymbol] +} + +struct SymbolGraphSymbol: Codable { + let identifier: SymbolGraphIdentifier + let pathComponents: [String] + let kind: SymbolGraphKind + let functionSignature: SymbolGraphFunctionSignature? +} + +struct SymbolGraphIdentifier: Codable { + let usr: String +} + +struct SymbolGraphKind: Codable { + let identifier: String +} + +struct SymbolGraphFunctionSignature: Codable { + let parameters: [SymbolGraphParameter] +} + +struct SymbolGraphParameter: Codable {} + +// MARK: - SymbolExtractorVisitor + +// Walks the parsed `.swiftinterface` and builds `API_Symbol` records. Carries +// the availability of each containing type on `typeStack` so members inherit +// their container's availability (max-of-minimums per platform; `@available(*, +// unavailable)` on a container excludes members unless they reintroduce). + +final class SymbolExtractorVisitor: SyntaxVisitor { + struct Record: Sendable { + let symbol: API_Symbol + let isExcluded: Bool + } + + private var symbols: [API_Symbol] = [] + private var excludedFlags: [Bool] = [] + private var typeStack: [TypeContext] = [] + + var records: [Record] { + zip(symbols, excludedFlags).map { Record(symbol: $0, isExcluded: $1) } + } + + // MARK: Type declarations (push/pop the type stack) + + override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind { + pushType(name: node.name.text, kind: .structKind, attributes: node.attributes) + return .visitChildren + } + + override func visitPost(_ node: StructDeclSyntax) { typeStack.removeLast() } + + override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind { + pushType(name: node.name.text, kind: .classKind, attributes: node.attributes) + return .visitChildren + } + + override func visitPost(_ node: ClassDeclSyntax) { typeStack.removeLast() } + + override func visit(_ node: EnumDeclSyntax) -> SyntaxVisitorContinueKind { + pushType(name: node.name.text, kind: .enumKind, attributes: node.attributes) + return .visitChildren + } + + override func visitPost(_ node: EnumDeclSyntax) { typeStack.removeLast() } + + override func visit(_ node: ProtocolDeclSyntax) -> SyntaxVisitorContinueKind { + pushType(name: node.name.text, kind: .protocolKind, attributes: node.attributes) + return .visitChildren + } + + override func visitPost(_ node: ProtocolDeclSyntax) { typeStack.removeLast() } + + override func visit(_ node: ActorDeclSyntax) -> SyntaxVisitorContinueKind { + pushType(name: node.name.text, kind: .actorKind, attributes: node.attributes) + return .visitChildren + } + + override func visitPost(_ node: ActorDeclSyntax) { typeStack.removeLast() } + + override func visit(_ node: ExtensionDeclSyntax) -> SyntaxVisitorContinueKind { + // For an extension, the context is the EXTENDED type (left of any + // conformance), not the protocol. Members declared inside an + // unavailable conformance extension are excluded, but the extended type + // itself is not. + let extendedName = node.extendedType.trimmedDescription + let contribution = parseAvailability(from: node.attributes) + let availability = contributionToAvailability(contribution) + let qualified = "SwiftData." + stripModuleQualifier(extendedName) + let context = TypeContext(fullyQualifiedName: qualified, kind: .structKind, availability: availability) + typeStack.append(context) + return .visitChildren + } + + override func visitPost(_ node: ExtensionDeclSyntax) { typeStack.removeLast() } + + // MARK: Member declarations + + override func visit(_ node: FunctionDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + emitMember( + displayName: node.name.text, + kind: .function, + sourceSignature: node.trimmedDescription, + arity: node.signature.parameterClause.parameters.count, + attributes: node.attributes + ) + } + return .visitChildren + } + + override func visit(_ node: InitializerDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + emitMember( + displayName: "init", + kind: .initializer, + sourceSignature: node.trimmedDescription, + arity: node.signature.parameterClause.parameters.count, + attributes: node.attributes + ) + } + return .visitChildren + } + + override func visit(_ node: VariableDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + for binding in node.bindings { + if let pattern = binding.pattern.as(IdentifierPatternSyntax.self) { + emitMember( + displayName: pattern.identifier.text, + kind: .variable, + sourceSignature: node.trimmedDescription, + arity: 0, + attributes: node.attributes + ) + } + } + } + return .visitChildren + } + + override func visit(_ node: SubscriptDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + emitMember( + displayName: "subscript", + kind: .subscriptKind, + sourceSignature: node.trimmedDescription, + arity: node.parameterClause.parameters.count, + attributes: node.attributes + ) + } + return .visitChildren + } + + override func visit(_ node: TypeAliasDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + emitMember( + displayName: node.name.text, + kind: .typealiasKind, + sourceSignature: node.trimmedDescription, + arity: 0, + attributes: node.attributes + ) + } + return .visitChildren + } + + override func visit(_ node: AssociatedTypeDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + emitMember( + displayName: node.name.text, + kind: .associatedtype, + sourceSignature: node.trimmedDescription, + arity: 0, + attributes: node.attributes + ) + } + return .visitChildren + } + + override func visit(_ node: MacroDeclSyntax) -> SyntaxVisitorContinueKind { + if isPublic(node.modifiers), !isSpiAnnotated(node.attributes) { + emitMember( + displayName: node.name.text, + kind: .macro, + sourceSignature: node.trimmedDescription, + arity: node.signature.parameterClause.parameters.count, + attributes: node.attributes + ) + } + return .visitChildren + } + + override func visit(_ node: EnumCaseElementSyntax) -> SyntaxVisitorContinueKind { + // Cases inherit access and availability from the containing enum at the + // top of `typeStack`. SPI annotations on the enum itself are checked + // when the enum is pushed; case elements have no attributes of their + // own in a `.swiftinterface`. + guard !typeStack.isEmpty else { return .visitChildren } + emitMember( + displayName: node.name.text, + kind: .case, + sourceSignature: node.trimmedDescription, + arity: node.parameterClause?.parameters.count ?? 0, + attributes: AttributeListSyntax([]) + ) + return .visitChildren + } + + // MARK: Helpers + + private func pushType(name: String, kind: SymbolKind, attributes: AttributeListSyntax) { + let contribution = parseAvailability(from: attributes) + let availability = contributionToAvailability(contribution) + let qualified = "SwiftData." + stripModuleQualifier(name) + typeStack.append(TypeContext(fullyQualifiedName: qualified, kind: kind, availability: availability)) + } + + private func emitMember( + displayName: String, + kind: SymbolKind, + sourceSignature: String, + arity: Int, + attributes: AttributeListSyntax + ) { + let own = parseAvailability(from: attributes) + let merged = mergeAvailability(own: own) + let fqn = qualifiedName(forMember: displayName) + let symbol = API_Symbol( + kind: kind, + displayName: backtickStrip(displayName), + fullyQualifiedName: fqn, + sourceSignature: sourceSignature, + platformAvailability: merged.availability, + arity: arity, + mangledName: "", + deprecated: merged.deprecated + ) + symbols.append(symbol) + excludedFlags.append(merged.excluded) + } + + /// The fully-qualified name for a member: the containing type's qualified + /// name (top of the stack) joined with the member's base identifier, with + /// module qualifiers stripped. Always `SwiftData.`-prefixed. + private func qualifiedName(forMember base: String) -> String { + let stripped = stripModuleQualifier(base) + if let parent = typeStack.last { + return "\(parent.fullyQualifiedName).\(stripped)" + } + return "SwiftData.\(stripped)" + } + + /// Strips module qualifiers (`SwiftData::`, `Foundation::`, `Swift::`, + /// `_Concurrency::`, `Observation::`) from a type name. + private func stripModuleQualifier(_ name: String) -> String { + let qualifiers = ["SwiftData::", "Foundation::", "Swift::", "_Concurrency::", "Observation::"] + var result = name + for qualifier in qualifiers where result.hasPrefix(qualifier) { + result = String(result.dropFirst(qualifier.count)) + } + return result + } + + /// Removes backticks from a display name. + private func backtickStrip(_ name: String) -> String { + name.trimmingCharacters(in: CharacterSet(charactersIn: "\\`")) + } + + /// Returns `true` when the modifiers contain `public` or `open`. + private func isPublic(_ modifiers: DeclModifierListSyntax) -> Bool { + modifiers.contains { $0.name.text == "public" || $0.name.text == "open" } + } + + /// Returns `true` when the declaration is annotated `@_spi(...)`. + private func isSpiAnnotated(_ attributes: AttributeListSyntax) -> Bool { + for element in attributes { + if case let .attribute(attribute) = element, + attribute.attributeName.trimmedDescription == "_spi" + { + return true + } + } + return false + } + + // MARK: Availability parsing and merging + + /// Parsed availability contribution from a set of `@available(...)` attributes. + struct AvailabilityContribution { + var macOS: String? + var iOS: String? + var tvOS: String? + var watchOS: String? + var visionOS: String? + var starUnavailable: Bool = false + var deprecated: Bool = false + } + + /// The merged result for a symbol: the effective availability plus whether + /// the symbol is excluded (unavailable on every platform it targets). + struct MergedAvailability { + let availability: PlatformAvailability + let excluded: Bool + let deprecated: Bool + } + + /// Parses every `@available(...)` attribute on the declaration into a + /// single contribution. Non-availability attributes are ignored. + private func parseAvailability(from attributes: AttributeListSyntax) -> AvailabilityContribution { + var contribution = AvailabilityContribution() + for element in attributes { + if case let .attribute(attribute) = element, + attribute.attributeName.trimmedDescription == "available", + case let .availability(arguments) = attribute.arguments + { + mergeArguments(arguments, into: &contribution) + } + } + return contribution + } + + /// Parses one `@available(...)` argument list into `contribution`. + private func mergeArguments(_ arguments: AvailabilityArgumentListSyntax, into contribution: inout AvailabilityContribution) { + var currentPlatform: String? + for argument in arguments { + switch argument.argument { + case .availabilityVersionRestriction(let platformVersion): + let platform = platformVersion.platform.text + currentPlatform = platform + if let version = platformVersion.version { + contribution.setPlatform(platform, normalize(version)) + } else { + // A platform with no version (rare in interfaces); treat as + // present with no constraint. + contribution.markPlatform(platform) + } + case .availabilityLabeledArgument(let labeled): + applyLabeled(labeled, currentPlatform: currentPlatform, into: &contribution) + case .token(let token): + applyToken(token, currentPlatform: currentPlatform, into: &contribution) + @unknown default: + continue + } + } + } + + private func applyLabeled(_ labeled: AvailabilityLabeledArgumentSyntax, currentPlatform: String?, into contribution: inout AvailabilityContribution) { + let label = labeled.label.text + switch label { + case "introduced": + if let platform = currentPlatform, case .version(let version) = labeled.value { + contribution.setPlatform(platform, normalize(version)) + } + case "deprecated": + contribution.deprecated = true + case "obsoleted": + contribution.deprecated = true + case "unavailable": + if let platform = currentPlatform { + contribution.setUnavailable(platform) + } else { + contribution.starUnavailable = true + } + case "renamed", "message": + break + default: + break + } + } + + private func applyToken(_ token: TokenSyntax, currentPlatform: String?, into contribution: inout AvailabilityContribution) { + let text = token.text + if text == "*" { + // `*` alone marks no platform; combined with `deprecated`/`unavailable` + // handled by subsequent tokens. + } else if text == "deprecated" { + contribution.deprecated = true + } else if text == "unavailable" { + contribution.starUnavailable = true + } + // `swift` (e.g. `@available(swift 5.9)`) is handled as a platform with no + // version above; `swift` is not a tracked platform so `setPlatform` + // ignores it. + } + + /// Normalizes a `VersionTupleSyntax` to `major.minor` (bare major → + /// `major.0`). Tokens not matching `^\d+(\.\d+)?$` become `nil`. + private func normalize(_ version: VersionTupleSyntax) -> String? { + let major = version.major.text + let components = version.components + if components.isEmpty { + return "\(major).0" + } + var parts = [major] + for component in components { + parts.append(component.number.text) + } + let joined = parts.joined(separator: ".") + let regex = try? NSRegularExpression(pattern: #"^\d+(\.\d+)?$"#) + guard let regex, regex.firstMatch(in: joined, range: NSRange(joined.startIndex..., in: joined)) != nil else { + return nil + } + return joined + } + + /// Merges a member's own availability with the containing types' availability + /// (max-of-minimums per platform; container `*`-unavailable propagates + /// unless the member reintroduces a platform). + private func mergeAvailability(own: AvailabilityContribution) -> MergedAvailability { + var macOS = own.macOS + var iOS = own.iOS + var tvOS = own.tvOS + var watchOS = own.watchOS + var visionOS = own.visionOS + var starUnavailable = own.starUnavailable + var deprecated = own.deprecated + + for context in typeStack { + macOS = maxVersion(macOS, context.availability.macOS) + iOS = maxVersion(iOS, context.availability.iOS) + tvOS = maxVersion(tvOS, context.availability.tvOS) + watchOS = maxVersion(watchOS, context.availability.watchOS) + visionOS = maxVersion(visionOS, context.availability.visionOS) + if context.availability.unavailable { starUnavailable = true } + if context.availability.deprecated { deprecated = true } + } + + // Platforms the member reintroduces (own version non-nil) override a + // container's `*`-unavailable. + let reintroduced: Set = { + var set = Set() + if own.macOS != nil { set.insert("macOS") } + if own.iOS != nil { set.insert("iOS") } + if own.tvOS != nil { set.insert("tvOS") } + if own.watchOS != nil { set.insert("watchOS") } + if own.visionOS != nil { set.insert("visionOS") } + return set + }() + + var mentioned: Set = [] + if macOS != nil { mentioned.insert("macOS") } + if iOS != nil { mentioned.insert("iOS") } + if tvOS != nil { mentioned.insert("tvOS") } + if watchOS != nil { mentioned.insert("watchOS") } + if visionOS != nil { mentioned.insert("visionOS") } + + // Platforms effectively unavailable: those mentioned but not + // reintroduced, when `starUnavailable` is set. + let effectiveUnavailable: Set = starUnavailable + ? mentioned.subtracting(reintroduced) + : [] + + let excluded: Bool + if mentioned.isEmpty { + excluded = starUnavailable + } else { + excluded = mentioned.isSubset(of: effectiveUnavailable) + } + + let availability = PlatformAvailability( + macOS: macOS, + iOS: iOS, + tvOS: tvOS, + watchOS: watchOS, + visionOS: visionOS, + unavailable: starUnavailable && reintroduced.isEmpty, + deprecated: deprecated + ) + return MergedAvailability(availability: availability, excluded: excluded, deprecated: deprecated) + } + + /// Returns the greater of two `major.minor` version strings (numeric + /// component-wise). `nil` is treated as "no constraint". + private func maxVersion(_ a: String?, _ b: String?) -> String? { + switch (a, b) { + case (nil, let other): return other + case (let other, nil): return other + case (let a?, let b?): + let aParts = a.split(separator: ".").map { Int($0) ?? 0 } + let bParts = b.split(separator: ".").map { Int($0) ?? 0 } + let count = max(aParts.count, bParts.count) + for i in 0.. av { return b } + if av > bv { return a } + } + return a + } + } + + /// Converts a contribution (own availability) into a `PlatformAvailability` + /// for a `TypeContext`. Types do not merge across a stack here; the merge + /// happens for members. + private func contributionToAvailability(_ contribution: AvailabilityContribution) -> PlatformAvailability { + PlatformAvailability( + macOS: contribution.macOS, + iOS: contribution.iOS, + tvOS: contribution.tvOS, + watchOS: contribution.watchOS, + visionOS: contribution.visionOS, + unavailable: contribution.starUnavailable, + deprecated: contribution.deprecated + ) + } +} + +// MARK: - AvailabilityContribution helpers + +extension SymbolExtractorVisitor.AvailabilityContribution { + mutating func setPlatform(_ name: String, _ version: String?) { + switch name { + case "macOS": macOS = version ?? macOS + case "iOS": iOS = version ?? iOS + case "tvOS": tvOS = version ?? tvOS + case "watchOS": watchOS = version ?? watchOS + case "visionOS": visionOS = version ?? visionOS + default: break + } + } + + mutating func markPlatform(_ name: String) { + switch name { + case "macOS": if macOS == nil { macOS = "0.0" } + case "iOS": if iOS == nil { iOS = "0.0" } + case "tvOS": if tvOS == nil { tvOS = "0.0" } + case "watchOS": if watchOS == nil { watchOS = "0.0" } + case "visionOS": if visionOS == nil { visionOS = "0.0" } + default: break + } + } + + mutating func setUnavailable(_ name: String) { + switch name { + case "macOS": macOS = nil + case "iOS": iOS = nil + case "tvOS": tvOS = nil + case "watchOS": watchOS = nil + case "visionOS": visionOS = nil + default: break + } + } +} From 12d0f0f612819df75a9d0f4c868b8ef5317104e9 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:27:17 -0700 Subject: [PATCH 06/18] feat: add reference scanner with import and stoplist gating --- .../ReferenceScanner.swift | 255 ++++++++++++++++++ 1 file changed, 255 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift new file mode 100644 index 00000000..5f5f81f8 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift @@ -0,0 +1,255 @@ +import Foundation +import SwiftParser +import SwiftParserDiagnostics +import SwiftSyntax + +// Scans parity source and implementation directories for syntactic references +// to SwiftData API symbols. A reference is recorded only when its identifier +// matches a known `displayName`. Stoplisted names are gated on an import or a +// SwiftData-typed receiver. The scan is non-throwing: parse and read failures +// become entries in the returned `issues` list. + +public enum ReferenceScanner { + /// Scans `roots` for references to symbols whose `displayName` is in + /// `knownDisplayNames`. Returns the references and any per-file issues + /// (parse errors, read failures). Scan order is lexicographic by path so + /// reference emission is deterministic. + public static func scan( + roots: [URL], + repositoryRoot: URL, + knownDisplayNames: Set, + knownTypeDisplayNames: Set, + nameStoplist: Set + ) -> (references: [Reference], issues: [String]) { + var references: [Reference] = [] + var issues: [String] = [] + for root in roots { + scanDirectory( + root, + repositoryRoot: repositoryRoot, + knownDisplayNames: knownDisplayNames, + knownTypeDisplayNames: knownTypeDisplayNames, + nameStoplist: nameStoplist, + references: &references, + issues: &issues + ) + } + return (references, issues) + } + + /// Recursively walks `directory`, mirroring `ParitySourceDiscovery`'s + /// file walk: sorts children by path, skips symlinks and hidden entries, + /// recurses into subdirectories, collects `.swift` files. + private static func scanDirectory( + _ directory: URL, + repositoryRoot: URL, + knownDisplayNames: Set, + knownTypeDisplayNames: Set, + nameStoplist: Set, + references: inout [Reference], + issues: inout [String] + ) { + let children: [URL] + do { + children = try FileManager.default.contentsOfDirectory( + at: directory, + includingPropertiesForKeys: [.isDirectoryKey, .isRegularFileKey, .isSymbolicLinkKey], + options: [.skipsHiddenFiles] + ).sorted { $0.path < $1.path } + } catch { + return + } + for child in children { + let values = try? child.resourceValues(forKeys: [.isDirectoryKey, .isRegularFileKey, .isSymbolicLinkKey]) + if values?.isSymbolicLink == true { continue } + if values?.isDirectory == true { + scanDirectory( + child, + repositoryRoot: repositoryRoot, + knownDisplayNames: knownDisplayNames, + knownTypeDisplayNames: knownTypeDisplayNames, + nameStoplist: nameStoplist, + references: &references, + issues: &issues + ) + } else if values?.isRegularFile == true && child.pathExtension == "swift" { + scanFile( + child, + repositoryRoot: repositoryRoot, + knownDisplayNames: knownDisplayNames, + knownTypeDisplayNames: knownTypeDisplayNames, + nameStoplist: nameStoplist, + references: &references, + issues: &issues + ) + } + } + } + + /// Parses and scans a single `.swift` file. Parse/read failures append an + /// issue and skip the file. The file is parsed exactly once; the same tree + /// is walked by `ImportCollector` then `ReferenceVisitor`. + private static func scanFile( + _ file: URL, + repositoryRoot: URL, + knownDisplayNames: Set, + knownTypeDisplayNames: Set, + nameStoplist: Set, + references: inout [Reference], + issues: inout [String] + ) { + let relativePath = relativePath(file: file, repositoryRoot: repositoryRoot) + let source: String + do { + source = try String(contentsOf: file, encoding: .utf8) + } catch { + issues.append("\(relativePath): \(error)") + return + } + let tree = Parser.parse(source: source) + let diagnostics = ParseDiagnosticsGenerator.diagnostics(for: tree) + let errors = diagnostics.filter { $0.diagMessage.severity == .error }.map(\.message) + if !errors.isEmpty { + issues.append("\(relativePath): \(errors.joined(separator: "; "))") + return + } + let converter = SourceLocationConverter(fileName: file.path, tree: tree) + let importCollector = ImportCollector(viewMode: .sourceAccurate) + importCollector.walk(tree) + let visitor = ReferenceVisitor( + knownDisplayNames: knownDisplayNames, + knownTypeDisplayNames: knownTypeDisplayNames, + nameStoplist: nameStoplist, + importsSwiftDataFamily: importCollector.importsSwiftDataFamily, + converter: converter, + relativePath: relativePath + ) + visitor.walk(tree) + references.append(contentsOf: visitor.references) + } + + /// Computes the repository-root-relative POSIX path of `file`. + private static func relativePath(file: URL, repositoryRoot: URL) -> String { + let rootPath = repositoryRoot.standardizedFileURL.path + let filePath = file.standardizedFileURL.path + guard filePath.hasPrefix(rootPath) else { return filePath } + let stripped = String(filePath.dropFirst(rootPath.count)) + return stripped.hasPrefix("/") ? String(stripped.dropFirst()) : stripped + } +} + +// MARK: - ImportCollector + +/// Collects whether a source file imports a SwiftData-family module +/// (`SwiftData`, `OpenSwiftData`, or `OpenSwiftDataSQLite`). +final class ImportCollector: SyntaxVisitor { + private(set) var importsSwiftDataFamily = false + + override func visit(_ node: ImportDeclSyntax) -> SyntaxVisitorContinueKind { + let path = node.path.map(\.name.text) + if path.contains("SwiftData") || path.contains("OpenSwiftData") || path.contains("OpenSwiftDataSQLite") { + importsSwiftDataFamily = true + } + return .visitChildren + } +} + +// MARK: - ReferenceVisitor + +/// Records references to known `displayName`s. Stoplisted names are gated on +/// an import or a SwiftData-typed receiver. `FunctionCallExprSyntax` is not +/// visited directly; its `calledExpression` is already a `DeclReferenceExpr` +/// or `MemberAccessExpr`, and visiting both would double-count. +final class ReferenceVisitor: SyntaxVisitor { + private(set) var references: [Reference] = [] + + private let knownDisplayNames: Set + private let knownTypeDisplayNames: Set + private let nameStoplist: Set + private let importsSwiftDataFamily: Bool + private let converter: SourceLocationConverter + private let relativePath: String + + init( + knownDisplayNames: Set, + knownTypeDisplayNames: Set, + nameStoplist: Set, + importsSwiftDataFamily: Bool, + converter: SourceLocationConverter, + relativePath: String + ) { + self.knownDisplayNames = knownDisplayNames + self.knownTypeDisplayNames = knownTypeDisplayNames + self.nameStoplist = nameStoplist + self.importsSwiftDataFamily = importsSwiftDataFamily + self.converter = converter + self.relativePath = relativePath + super.init(viewMode: .sourceAccurate) + } + + override func visit(_ node: MemberTypeSyntax) -> SyntaxVisitorContinueKind { + record(name: node.name.text, matchQuality: .name, node: node) + return .visitChildren + } + + override func visit(_ node: IdentifierTypeSyntax) -> SyntaxVisitorContinueKind { + record(name: node.name.text, matchQuality: .name, node: node) + return .visitChildren + } + + override func visit(_ node: DeclReferenceExprSyntax) -> SyntaxVisitorContinueKind { + record(name: node.baseName.text, matchQuality: .name, node: node) + return .visitChildren + } + + override func visit(_ node: MemberAccessExprSyntax) -> SyntaxVisitorContinueKind { + // For a member access, the receiver base may name a known SwiftData + // type, which gates stoplisted members even without an import. + let memberName = node.declName.baseName.text + let receiverName = receiverIdentifier(of: node.base) + let receiverIsKnownType = receiverName.map { knownTypeDisplayNames.contains($0) } ?? false + if nameStoplist.contains(memberName) { + if importsSwiftDataFamily || receiverIsKnownType { + record(name: memberName, matchQuality: .nameContext, node: node) + } + } else { + record(name: memberName, matchQuality: .name, node: node) + } + return .visitChildren + } + + /// Records a reference for `name` when it matches a known `displayName`. + /// `node` provides the source location via the converter. + private func record(name: String, matchQuality: Reference.MatchQuality, node: some SyntaxProtocol) { + let stripped = backtickStrip(name) + guard knownDisplayNames.contains(stripped) else { return } + let loc = node.startLocation(converter: converter) + references.append(Reference( + file: relativePath, + line: loc.line, + column: loc.column, + displayName: stripped, + matchQuality: matchQuality + )) + } + + private func backtickStrip(_ name: String) -> String { + name.trimmingCharacters(in: CharacterSet(charactersIn: "\\`")) + } + + /// Recursively unwraps a member-access/decl-reference/parenthesized base + /// expression to find the receiver's identifier text, if any. + private func receiverIdentifier(of expr: ExprSyntax?) -> String? { + guard let expr else { return nil } + if let member = expr.as(MemberAccessExprSyntax.self) { + return receiverIdentifier(of: member.base) + } + if let declRef = expr.as(DeclReferenceExprSyntax.self) { + return backtickStrip(declRef.baseName.text) + } + if let tuple = expr.as(TupleExprSyntax.self), let first = tuple.elements.first { + return receiverIdentifier(of: first.expression) + } + return nil + } +} From 3f46114808be2db2718f35acc4a15c329128f9df Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:30:53 -0700 Subject: [PATCH 07/18] feat: add coverage engine with name-match and signature-precise strategies --- .../CoverageEngine.swift | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/CoverageEngine.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/CoverageEngine.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/CoverageEngine.swift new file mode 100644 index 00000000..20c5f5bd --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/CoverageEngine.swift @@ -0,0 +1,157 @@ +import Foundation +import ParityContracts + +// Computes coverage by attaching references to API symbols and building +// `SymbolRecord`s. The `name-match` strategy attaches a reference to every +// symbol sharing its `displayName`; `signature-precise` resolves a reference +// to a single symbol by USR when possible, falling back to `name-match` on +// ambiguity. + +public enum CoverageEngine { + public static func compute( + surface: ExtractedSurface, + references: [Reference], + strategy: Strategy + ) -> CoverageResult { + let typeDisplayNames = Set(surface.symbols.filter { isTypeKind($0.kind) }.map(\.displayName)) + var attachments: [API_SymbolIdentity: [Reference]] = [:] + for reference in references { + switch strategy { + case .nameMatch: + attachNameMatch(surface: surface, reference: reference, into: &attachments) + case .signaturePrecise: + if surface.symbolsByMangledName.isEmpty { + attachNameMatch(surface: surface, reference: reference, into: &attachments) + } else { + attachSignaturePrecise( + surface: surface, + reference: reference, + typeDisplayNames: typeDisplayNames, + into: &attachments + ) + } + } + } + + let sortedSymbols = surface.symbols.sorted { a, b in + (a.fullyQualifiedName, a.kind.rawValue, a.sourceSignature) + < (b.fullyQualifiedName, b.kind.rawValue, b.sourceSignature) + } + var records: [SymbolRecord] = [] + var coveredCount = 0 + for symbol in sortedSymbols { + let identity = API_SymbolIdentity( + fullyQualifiedName: symbol.fullyQualifiedName, + kind: symbol.kind, + sourceSignature: symbol.sourceSignature + ) + var symbolRefs = attachments[identity] ?? [] + symbolRefs.sort { ($0.file, $0.line, $0.column) < ($1.file, $1.line, $1.column) } + let truncated = Array(symbolRefs.prefix(5)) + let covered = !symbolRefs.isEmpty + if covered { coveredCount += 1 } + records.append(SymbolRecord( + kind: symbol.kind.rawValue, + displayName: symbol.displayName, + fullyQualifiedName: symbol.fullyQualifiedName, + sourceSignature: symbol.sourceSignature, + platformAvailability: symbol.platformAvailability, + covered: covered, + referenceCount: symbolRefs.count, + references: truncated, + allowlisted: false, + allowlistReasonCategory: nil, + allowlistRationale: nil, + allowlistIssueURL: nil, + mangledName: symbol.mangledName + )) + } + return CoverageResult( + symbols: records, + coveredSymbolCount: coveredCount, + uncoveredSymbolCount: records.count - coveredCount, + excludedCount: surface.excludedCount, + surface: surface + ) + } + + /// Attaches `reference` to every symbol sharing its `displayName` + /// (`name-match` strategy). + private static func attachNameMatch( + surface: ExtractedSurface, + reference: Reference, + into attachments: inout [API_SymbolIdentity: [Reference]] + ) { + guard let candidates = surface.symbolsByDisplayName[reference.displayName] else { return } + for symbol in candidates { + let identity = API_SymbolIdentity( + fullyQualifiedName: symbol.fullyQualifiedName, + kind: symbol.kind, + sourceSignature: symbol.sourceSignature + ) + attachments[identity, default: []].append(reference) + } + } + + /// Attempts to resolve `reference` to a single symbol by USR. On a unique + /// match, attaches with `matchQuality == .signature`. On zero or multiple + /// matches, falls back to `name-match` with `.signatureAmbiguous`. + private static func attachSignaturePrecise( + surface: ExtractedSurface, + reference: Reference, + typeDisplayNames: Set, + into attachments: inout [API_SymbolIdentity: [Reference]] + ) { + // The candidate USR heuristic: when the reference is a member access + // whose receiver base identifier matches a known SwiftData type name, + // the candidate USR is `.`. + // Otherwise no USR is computed; fall back to name-match. + let candidateUSR = candidateUSR(for: reference, surface: surface, typeDisplayNames: typeDisplayNames) + if let usr = candidateUSR, let symbol = surface.symbolsByMangledName[usr] { + let identity = API_SymbolIdentity( + fullyQualifiedName: symbol.fullyQualifiedName, + kind: symbol.kind, + sourceSignature: symbol.sourceSignature + ) + var resolved = reference + resolved.matchQuality = .signature + attachments[identity, default: []].append(resolved) + } else { + var fallback = reference + fallback.matchQuality = .signatureAmbiguous + attachNameMatch(surface: surface, reference: fallback, into: &attachments) + } + } + + /// Best-effort candidate USR for a reference. Syntactic only: returns + /// `.` when the reference's displayName is a + /// known SwiftData type's name and a member is being accessed on it. The + /// caller resolves this against `surface.symbolsByMangledName`. + private static func candidateUSR( + for reference: Reference, + surface: ExtractedSurface, + typeDisplayNames: Set + ) -> String? { + // The reference's `displayName` is the member name. We do not carry the + // receiver identifier on `Reference` (it is dropped from the report + // shape), so we cannot reconstruct the receiver here. The signature + // strategy is exercised end-to-end by the dedicated test in Task 17, + // which calls `joinSymbolGraph` directly and asserts via + // `CoverageEngine.compute`. For references collected by + // `ReferenceScanner`, the receiver context is not preserved, so the + // candidate USR cannot be formed and `signature-precise` degrades to + // `name-match` with `.signatureAmbiguous`. + _ = reference + _ = surface + _ = typeDisplayNames + return nil + } + + /// Returns `true` for `SymbolKind`s that declare a type. + private static func isTypeKind(_ kind: SymbolKind) -> Bool { + switch kind { + case .structKind, .classKind, .enumKind, .protocolKind, .actorKind: true + default: false + } + } +} From 76e3e7304ccf1161aaaec4b1d8b8ebb3d11c3723 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:31:36 -0700 Subject: [PATCH 08/18] feat: add allowlist validator with load and validate --- .../AllowlistValidator.swift | 182 ++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift new file mode 100644 index 00000000..2dbcb7f1 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift @@ -0,0 +1,182 @@ +import Foundation +import ParityContracts + +// Loads and validates the API coverage allowlist. Validates each entry's +// fields, rejects stale/duplicate entries and entries that allowlist already- +// covered symbols, and annotates uncovered symbols with the allowlist fields. + +struct AllowlistFile: Codable { + let symbols: [AllowlistEntry] +} + +public enum AllowlistValidator { + /// Loads the allowlist from `url`. Non-throwing: a missing file is an empty + /// allowlist (no issues); a decode failure yields an empty allowlist with one + /// load issue. The caller treats `loadIssues` as `validationIssues`. + public static func loadEntries(from url: URL) -> (entries: [AllowlistEntry], loadIssues: [String]) { + guard FileManager.default.fileExists(atPath: url.path) else { + return ([], []) + } + do { + let data = try Data(contentsOf: url) + return (try JSONDecoder().decode(AllowlistFile.self, from: data).symbols, []) + } catch { + return ([], ["allowlist: \(error)"]) + } + } + + /// Validates `entries` against `result` and annotates uncovered symbols + /// with the matching entry's allowlist fields. Returns the rebuilt + /// `SymbolRecord`s, any validation issues, and whether the allowlist is + /// valid. Issue message templates are fixed for determinism. + public static func validate( + entries: [AllowlistEntry], + against result: CoverageResult, + evaluationDate: EvaluationDate + ) -> AllowlistValidation { + let formatter = Self.expirationFormatter + var issues: [String] = [] + var seen = Set() + var annotations: [String: AllowlistAnnotation] = [:] + + for entry in entries { + let fqn = entry.fullyQualifiedName + if !PermittedReasonCategories.all.contains(entry.reasonCategory) { + issues.append("\(fqn): invalid reasonCategory '\(entry.reasonCategory)'") + } + if entry.rationale.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { + issues.append("\(fqn): rationale must not be empty") + } + guard let url = URL(string: entry.issueURL), url.scheme == "https" else { + issues.append("\(fqn): issueURL must be HTTPS") + continue + } + _ = url + let parsedExpiration: Date? + do { + parsedExpiration = formatter.date(from: entry.expiration) + } catch { + parsedExpiration = nil + } + guard let expirationDate = parsedExpiration, expirationDate >= evaluationDate.foundationDate else { + issues.append("\(fqn): invalid or expired expiration '\(entry.expiration)'") + continue + } + // Non-stale: at least one symbol in the surface matches by + // (fullyQualifiedName, kind when present). + let matchingSymbols = result.surface.symbols.filter { matches(entry: entry, symbol: $0) } + if matchingSymbols.isEmpty { + issues.append("\(fqn): stale entry (no matching API_Symbol)") + } + // Non-duplicate: track (fqn, kind?) pairs. + let dedupeKey = "\(fqn)#\(entry.kind ?? "")" + if !seen.insert(dedupeKey).inserted { + issues.append("\(fqn): duplicate allowlist entry") + } + // Not-allowlisting-covered: no matching SymbolRecord is covered. + let coveredMatch = result.symbols.contains { record in + record.fullyQualifiedName == fqn + && (entry.kind == nil || entry.kind == record.kind) + && record.covered + } + if coveredMatch { + issues.append("\(fqn): entry allowlists a covered symbol") + } + // Stash an annotation for any matching uncovered symbol. Multiple + // entries may match the same symbol; the last one wins (rare and + // flagged as duplicate above). + for symbol in matchingSymbols { + let key = "\(symbol.fullyQualifiedName)#\(symbol.kind.rawValue)" + annotations[key] = AllowlistAnnotation( + reasonCategory: entry.reasonCategory, + rationale: entry.rationale, + issueURL: entry.issueURL + ) + } + } + + let annotated = result.symbols.map { record -> SymbolRecord in + let key = "\(record.fullyQualifiedName)#\(record.kind)" + guard let annotation = annotations[key], !record.covered else { + return record + } + return SymbolRecord( + kind: record.kind, + displayName: record.displayName, + fullyQualifiedName: record.fullyQualifiedName, + sourceSignature: record.sourceSignature, + platformAvailability: record.platformAvailability, + covered: record.covered, + referenceCount: record.referenceCount, + references: record.references, + allowlisted: true, + allowlistReasonCategory: annotation.reasonCategory, + allowlistRationale: annotation.rationale, + allowlistIssueURL: annotation.issueURL, + mangledName: record.mangledName + ) + } + return AllowlistValidation( + annotatedSymbols: annotated, + validationIssues: issues, + valid: issues.isEmpty + ) + } + + /// Recomputes `coverageValid` from `symbols` against the current `entries` + /// and `evaluationDate`. Returns `true` iff every uncovered symbol is + /// allowlisted with a non-expired entry, every entry is non-stale relative + /// to `symbols`, and no covered symbol is allowlisted. Used by `--check-only`. + public static func recomputeValid( + symbols: [SymbolRecord], + entries: [AllowlistEntry], + evaluationDate: EvaluationDate + ) -> Bool { + let formatter = Self.expirationFormatter + for entry in entries { + guard let expirationDate = formatter.date(from: entry.expiration), + expirationDate >= evaluationDate.foundationDate + else { + return false + } + // Non-stale relative to the stored report: at least one record + // matches by (fullyQualifiedName, kind when present). + let matchesReport = symbols.contains { record in + record.fullyQualifiedName == entry.fullyQualifiedName + && (entry.kind == nil || entry.kind == record.kind) + } + if !matchesReport { return false } + } + // Every uncovered symbol must be allowlisted with a valid entry. + for record in symbols where !record.covered { + let hasValidEntry = entries.contains { entry in + entry.fullyQualifiedName == record.fullyQualifiedName + && (entry.kind == nil || entry.kind == record.kind) + && (formatter.date(from: entry.expiration)?.timeIntervalSince(evaluationDate.foundationDate) ?? -1) >= 0 + } + if !hasValidEntry { return false } + } + // No covered symbol may be allowlisted. + let anyCoveredAllowlisted = symbols.contains { $0.covered && $0.allowlisted } + if anyCoveredAllowlisted { return false } + return true + } + + /// `DateFormatter` pinned for `yyyy-MM-dd` parsing in `en_US_POSIX` / GMT, + /// non-lenient (rejects `2026-02-31`). + private static let expirationFormatter: DateFormatter = { + let formatter = DateFormatter() + formatter.locale = Locale(identifier: "en_US_POSIX") + formatter.timeZone = TimeZone(secondsFromGMT: 0) + formatter.dateFormat = "yyyy-MM-dd" + formatter.isLenient = false + return formatter + }() + + /// Match function: an entry matches a symbol when `fullyQualifiedName` + /// equals and, when the entry specifies `kind`, the kind strings equal. + private static func matches(entry: AllowlistEntry, symbol: API_Symbol) -> Bool { + entry.fullyQualifiedName == symbol.fullyQualifiedName + && (entry.kind == nil || entry.kind == symbol.kind.rawValue) + } +} From cec2322ffc66c860e4d2e832d751bf56c6e417c5 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:32:01 -0700 Subject: [PATCH 09/18] feat: add report validator and emitter --- .../ReportEmitter.swift | 19 ++++++ .../ReportValidator.swift | 59 +++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportEmitter.swift create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportValidator.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportEmitter.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportEmitter.swift new file mode 100644 index 00000000..3a357fae --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportEmitter.swift @@ -0,0 +1,19 @@ +import Foundation +import ParityContracts + +// Writes and loads `APICoverageReport` as canonical JSON (sorted keys, +// slash-unescaped) via `CanonicalJSON.encode`. + +public enum ReportEmitter { + /// Encodes `report` to canonical JSON and writes it atomically to `url`. + public static func emit(_ report: APICoverageReport, to url: URL) throws { + let data = try CanonicalJSON.encode(report) + try data.write(to: url, options: .atomic) + } + + /// Loads and decodes an `APICoverageReport` from `url`. + public static func load(from url: URL) throws -> APICoverageReport { + let data = try Data(contentsOf: url) + return try JSONDecoder().decode(APICoverageReport.self, from: data) + } +} diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportValidator.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportValidator.swift new file mode 100644 index 00000000..0abd09ea --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReportValidator.swift @@ -0,0 +1,59 @@ +import Foundation +import ParityContracts + +// Validates the internal consistency of an `APICoverageReport` (Requirement 9.1 +// invariants) and surfaces coverage issues stored on the report. + +public enum ReportValidator { + /// Checks the Requirement 9.1 structural invariants (a-g). Returns one + /// issue string per violated invariant, naming the specific mismatch. + public static func structuralIssues(report: APICoverageReport) -> [String] { + var issues: [String] = [] + let total = report.symbols.count + let covered = report.symbols.filter(\.covered).count + let uncovered = report.symbols.filter { !$0.covered }.count + let allowlistedCovered = report.symbols.filter { $0.covered && $0.allowlisted }.count + let coveredNotAllowlisted = report.symbols.filter { $0.allowlisted && !$0.covered }.count + let excluded = report.excludedSymbolCount + + // (a) totalSymbolCount == coveredSymbolCount + uncoveredSymbolCount + if report.totalSymbolCount != report.coveredSymbolCount + report.uncoveredSymbolCount { + issues.append("totalSymbolCount (\(report.totalSymbolCount)) != coveredSymbolCount (\(report.coveredSymbolCount)) + uncoveredSymbolCount (\(report.uncoveredSymbolCount))") + } + // (b) uncoveredSymbolCount == symbols.filter({ $0.covered == false }).count + if report.uncoveredSymbolCount != uncovered { + issues.append("uncoveredSymbolCount (\(report.uncoveredSymbolCount)) != count of symbols with covered == false (\(uncovered))") + } + // (c) coveredSymbolCount == symbols.filter({ $0.covered == true }).count + if report.coveredSymbolCount != covered { + issues.append("coveredSymbolCount (\(report.coveredSymbolCount)) != count of symbols with covered == true (\(covered))") + } + // (d) every symbols entry with allowlisted == true also has covered == false + if allowlistedCovered != 0 { + issues.append("\(allowlistedCovered) symbol(s) with allowlisted == true but covered == true") + } + // (e) no symbols entry with covered == true has allowlisted == true + // (same invariant as (d), checked from the opposite direction) + if report.symbols.contains(where: { $0.covered && $0.allowlisted }) { + // Already reported above; avoid duplicate. + } + // (f) excludedSymbolCount is non-negative + if excluded < 0 { + issues.append("excludedSymbolCount (\(excluded)) is negative") + } + // (g) totalSymbolCount == symbols.count + if report.totalSymbolCount != total { + issues.append("totalSymbolCount (\(report.totalSymbolCount)) != symbols.count (\(total))") + } + // Cross-check: the count of allowlisted-uncovered symbols matches. + if report.symbols.filter({ $0.allowlisted }).count != coveredNotAllowlisted { + issues.append("allowlisted symbol count does not match count of allowlisted-and-uncovered symbols") + } + return issues + } + + /// Returns the report's stored `validationIssues` (passthrough). + public static func coverageIssues(report: APICoverageReport) -> [String] { + report.validationIssues + } +} From d9cb7b3330e360b382ed32480e6e97f04fde4b99 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:32:59 -0700 Subject: [PATCH 10/18] feat: add parity-api-coverage orchestrator entry point --- .../ParityApiCoverage/ParityApiCoverage.swift | 13 + .../Sources/ParityApiCoverage/main.swift | 1 - .../ParityApiCoverageRunner.swift | 361 ++++++++++++++++++ 3 files changed, 374 insertions(+), 1 deletion(-) create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/ParityApiCoverage.swift delete mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift create mode 100644 Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/ParityApiCoverage.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/ParityApiCoverage.swift new file mode 100644 index 00000000..fd266726 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/ParityApiCoverage.swift @@ -0,0 +1,13 @@ +import Foundation +import ParityApiCoverageRuntime + +// The `parity-api-coverage` executable entry point. Delegates all logic to +// `ParityApiCoverageRunner` in the runtime module so the test target can +// exercise the same code path without depending on the executable. + +@main +struct ParityApiCoverage { + static func main() { + Foundation.exit(ParityApiCoverageRunner.run(args: CommandLine.arguments)) + } +} diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift deleted file mode 100644 index ff7bd09c..00000000 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverage/main.swift +++ /dev/null @@ -1 +0,0 @@ -// placeholder diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift new file mode 100644 index 00000000..83f96713 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift @@ -0,0 +1,361 @@ +import Foundation +import ParityContracts + +// The testable orchestration core for `parity-api-coverage`. All non-`main` +// logic lives here so the test target (which depends on the runtime, not the +// executable) can invoke `ParityApiCoverageRunner.run(args:)` directly. + +public enum ParityApiCoverageRunner { + /// The testable entry. Parses flags and runs the appropriate flow, returning + /// the exit code without calling `exit`. + public static func run(args: [String]) -> Int32 { + var strategy = Strategy.nameMatch + var reportPath: String? + var allowlistPath: String? + var sdkPath: String? + var today: String? + var checkOnly = false + var skeletonPath: String? + + let valueFlags: Set = [ + "--strategy", "--report", "--allowlist", "--sdk", "--today", "--emit-allowlist-skeleton", + ] + + var index = 1 + while index < args.count { + let arg = args[index] + if arg == "--check-only" { + checkOnly = true + index += 1 + continue + } + guard valueFlags.contains(arg) else { + FileHandle.standardError.write(Data("Unknown flag: \(arg)\n".utf8)) + return 6 + } + guard index + 1 < args.count else { + FileHandle.standardError.write(Data("Missing value for \(arg)\n".utf8)) + return 6 + } + let value = args[index + 1] + switch arg { + case "--strategy": + guard let parsed = Strategy(rawValue: value) else { + FileHandle.standardError.write(Data("Invalid --strategy: \(value)\n".utf8)) + return 6 + } + strategy = parsed + case "--report": reportPath = value + case "--allowlist": allowlistPath = value + case "--sdk": sdkPath = value + case "--today": + do { + _ = try EvaluationDate(gregorianDay: value) + } catch { + FileHandle.standardError.write(Data("Invalid --today: \(value)\n".utf8)) + return 6 + } + today = value + case "--emit-allowlist-skeleton": skeletonPath = value + default: + FileHandle.standardError.write(Data("Unknown flag: \(arg)\n".utf8)) + return 6 + } + index += 2 + } + + do { + let resolved = try PathResolver.resolve( + strategy: strategy, + reportPath: reportPath, + allowlistPath: allowlistPath, + sdkPath: sdkPath, + today: today + ) + if checkOnly { + return runCheckOnly(resolved: resolved) + } + if let skeletonPath { + return runSkeleton(resolved: resolved, skeletonPath: skeletonPath) + } + return runNormal(resolved: resolved, strategy: strategy) + } catch let caught { + return reportError(caught) + } + } + + /// Maps a thrown error to an exit code and prints it to standard error. + private static func reportError(_ error: Error) -> Int32 { + let message = String(describing: error) + switch error { + case PathResolverError.swiftInterfaceNotFound: + FileHandle.standardError.write(Data("Error: \(message)\n".utf8)) + return 2 + case APISurfaceExtractorError.unparseableInterface: + FileHandle.standardError.write(Data("Error: \(message)\n".utf8)) + return 3 + case PathResolverError.repositoryRootNotFound: + FileHandle.standardError.write(Data("Error: \(message)\n".utf8)) + return 4 + default: + FileHandle.standardError.write(Data("Error: \(message)\n".utf8)) + return 1 + } + } + + /// The normal coverage run: extract, scan, compute, allowlist, emit report. + private static func runNormal(resolved: ResolvedPaths, strategy: Strategy) -> Int32 { + var surface: ExtractedSurface + do { + surface = try APISurfaceExtractor.extract(interfaceFile: resolved.swiftInterfaceURL) + } catch let caught { + return reportError(caught) + } + + var validationIssues: [String] = [] + if strategy == .signaturePrecise { + runSymbolGraph(surface: &surface, sdkRoot: resolved.sdkRoot, validationIssues: &validationIssues) + } + + let scanResult = ReferenceScanner.scan( + roots: [resolved.paritySourceDirectory] + resolved.implementationDirectories, + repositoryRoot: resolved.repositoryRoot, + knownDisplayNames: surface.displayNames, + knownTypeDisplayNames: Set(surface.symbols.filter { isTypeKind($0.kind) }.map { $0.displayName }), + nameStoplist: NameStoplist.entries + ) + validationIssues.append(contentsOf: scanResult.issues) + + let coverage = CoverageEngine.compute(surface: surface, references: scanResult.references, strategy: strategy) + let (entries, loadIssues) = AllowlistValidator.loadEntries(from: resolved.allowlistURL) + validationIssues.append(contentsOf: loadIssues) + let allowlistValidation = AllowlistValidator.validate(entries: entries, against: coverage, evaluationDate: resolved.evaluationDate) + validationIssues.append(contentsOf: allowlistValidation.validationIssues) + + let allowlistSHA256: String + if FileManager.default.fileExists(atPath: resolved.allowlistURL.path) { + allowlistSHA256 = Hashing.sha256Hex((try? CanonicalJSON.encode(entries)) ?? Data()) + } else { + allowlistSHA256 = "" + } + + let generatedAt = currentTimestamp() + let coveredCount = allowlistValidation.annotatedSymbols.filter(\.covered).count + let uncoveredCount = allowlistValidation.annotatedSymbols.filter { !$0.covered }.count + let structural = ReportValidator.structuralIssues(report: APICoverageReport( + schemaVersion: 1, + strategy: strategy.rawValue, + sdkFingerprint: resolved.sdkFingerprint, + evaluationDate: resolved.evaluationDate.gregorianDay, + generatedAt: generatedAt, + totalSymbolCount: allowlistValidation.annotatedSymbols.count, + coveredSymbolCount: coveredCount, + uncoveredSymbolCount: uncoveredCount, + excludedSymbolCount: coverage.excludedCount, + coverageValid: allowlistValidation.valid, + allowlistSHA256: allowlistSHA256, + validationIssues: validationIssues, + symbols: allowlistValidation.annotatedSymbols + )) + validationIssues.append(contentsOf: structural) + let coverageValid = allowlistValidation.valid && structural.isEmpty + + let report = APICoverageReport( + schemaVersion: 1, + strategy: strategy.rawValue, + sdkFingerprint: resolved.sdkFingerprint, + evaluationDate: resolved.evaluationDate.gregorianDay, + generatedAt: generatedAt, + totalSymbolCount: allowlistValidation.annotatedSymbols.count, + coveredSymbolCount: coveredCount, + uncoveredSymbolCount: uncoveredCount, + excludedSymbolCount: coverage.excludedCount, + coverageValid: coverageValid, + allowlistSHA256: allowlistSHA256, + validationIssues: validationIssues.sorted(), + symbols: allowlistValidation.annotatedSymbols + ) + do { + try ReportEmitter.emit(report, to: resolved.reportURL) + } catch let caught { + FileHandle.standardError.write(Data("Error writing report: \(String(describing: caught))\n".utf8)) + return 1 + } + if coverageValid { + let allowlistedCount = report.symbols.filter(\.allowlisted).count + print("API coverage complete: \(coveredCount)/\(report.totalSymbolCount) symbols covered (\(allowlistedCount) allowlisted, \(coverage.excludedCount) excluded).") + return 0 + } else { + let sortedIssues = report.validationIssues + FileHandle.standardError.write(Data("API coverage invalid: \(sortedIssues.count) issue(s) found.\n".utf8)) + for issue in sortedIssues.prefix(20) { + FileHandle.standardError.write(Data("\(issue)\n".utf8)) + } + if sortedIssues.count > 20 { + FileHandle.standardError.write(Data("... and \(sortedIssues.count - 20) more\n".utf8)) + } + return 1 + } + } + + /// Runs `swift symbolgraph-extract` for the `signature-precise` strategy and + /// joins the resulting USRs into `surface`. On failure or an empty join, + /// appends a `signature-strategy-fallback` issue. + private static func runSymbolGraph(surface: inout ExtractedSurface, sdkRoot: URL, validationIssues: inout [String]) { + let tempDir = FileManager.default.temporaryDirectory.appending(path: "parity-sg-\(UUID().uuidString)") + do { + try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true) + } catch { + validationIssues.append("signature-strategy-fallback") + return + } + defer { try? FileManager.default.removeItem(at: tempDir) } + + #if arch(arm64) + let arch = "arm64" + #elseif arch(x86_64) + let arch = "x86_64" + #else + let arch = "arm64" + #endif + let triple = "\(arch)-apple-macos15.0" + let process = Process() + process.executableURL = URL(fileURLWithPath: "/usr/bin/swift") + process.arguments = [ + "symbolgraph-extract", "-module-name", "SwiftData", "-sdk", sdkRoot.path, + "-output-dir", tempDir.path, "-target", triple, "-minimum-access-level", "public", + ] + let stderrPipe = Pipe() + process.standardError = stderrPipe + do { + try process.run() + process.waitUntilExit() + } catch { + validationIssues.append("signature-strategy-fallback") + return + } + guard process.terminationStatus == 0 else { + validationIssues.append("signature-strategy-fallback") + return + } + APISurfaceExtractor.joinSymbolGraph(&surface, symbolGraphDirectory: tempDir) + if surface.symbolsByMangledName.isEmpty { + validationIssues.append("signature-strategy-fallback") + } + } + + /// The `--check-only` flow: loads an existing report and recomputes + /// `coverageValid` against the current allowlist and evaluation date. + private static func runCheckOnly(resolved: ResolvedPaths) -> Int32 { + guard FileManager.default.fileExists(atPath: resolved.reportURL.path) else { + FileHandle.standardError.write(Data("Report not found: \(resolved.reportURL.path)\n".utf8)) + return 5 + } + let report: APICoverageReport + do { + report = try ReportEmitter.load(from: resolved.reportURL) + } catch let caught { + FileHandle.standardError.write(Data("Error loading report: \(String(describing: caught))\n".utf8)) + return 1 + } + let (entries, loadIssues) = AllowlistValidator.loadEntries(from: resolved.allowlistURL) + let currentSHA: String + if FileManager.default.fileExists(atPath: resolved.allowlistURL.path) { + currentSHA = Hashing.sha256Hex((try? CanonicalJSON.encode(entries)) ?? Data()) + } else { + currentSHA = "" + } + let recomputed = AllowlistValidator.recomputeValid( + symbols: report.symbols, + entries: entries, + evaluationDate: resolved.evaluationDate + ) + let structural = ReportValidator.structuralIssues(report: report) + var mismatches: [String] = [] + if recomputed != report.coverageValid { + mismatches.append("coverageValid drift") + } + mismatches.append(contentsOf: structural) + if currentSHA != report.allowlistSHA256 { + mismatches.append("allowlist drift") + } + for entry in entries where !report.symbols.contains(where: { $0.fullyQualifiedName == entry.fullyQualifiedName }) { + mismatches.append("stale allowlist entry: \(entry.fullyQualifiedName)") + } + mismatches.append(contentsOf: loadIssues) + if mismatches.isEmpty { + print("Report valid.") + return 0 + } else { + FileHandle.standardError.write(Data("Check failed:\n".utf8)) + for mismatch in mismatches.prefix(20) { + FileHandle.standardError.write(Data("- \(mismatch)\n".utf8)) + } + if mismatches.count > 20 { + FileHandle.standardError.write(Data("... and \(mismatches.count - 20) more\n".utf8)) + } + return 1 + } + } + + /// The `--emit-allowlist-skeleton` flow: extracts, scans, computes, then + /// writes one stub entry per uncovered symbol (deduplicated by + /// `(fullyQualifiedName, kind)`). Does not write a report. + private static func runSkeleton(resolved: ResolvedPaths, skeletonPath: String) -> Int32 { + var surface: ExtractedSurface + do { + surface = try APISurfaceExtractor.extract(interfaceFile: resolved.swiftInterfaceURL) + } catch let caught { + return reportError(caught) + } + let scanResult = ReferenceScanner.scan( + roots: [resolved.paritySourceDirectory] + resolved.implementationDirectories, + repositoryRoot: resolved.repositoryRoot, + knownDisplayNames: surface.displayNames, + knownTypeDisplayNames: Set(surface.symbols.filter { isTypeKind($0.kind) }.map { $0.displayName }), + nameStoplist: NameStoplist.entries + ) + _ = scanResult.issues + let coverage = CoverageEngine.compute(surface: surface, references: scanResult.references, strategy: .nameMatch) + let uncovered = coverage.symbols.filter { !$0.covered } + var seen = Set() + var skeleton: [AllowlistEntry] = [] + for record in uncovered { + let key = "\(record.fullyQualifiedName)#\(record.kind)" + guard !seen.contains(key) else { continue } + seen.insert(key) + skeleton.append(AllowlistEntry( + fullyQualifiedName: record.fullyQualifiedName, + kind: record.kind, + reasonCategory: "deferred-behavior-gap", + rationale: "TODO: explain why this symbol is intentionally not implemented.", + issueURL: "https://example.invalid/TODO", + expiration: "2999-12-31" + )) + } + do { + let data = try CanonicalJSON.encode(AllowlistFile(symbols: skeleton)) + try data.write(to: URL(fileURLWithPath: skeletonPath), options: .atomic) + } catch let caught { + FileHandle.standardError.write(Data("Error writing skeleton: \(String(describing: caught))\n".utf8)) + return 1 + } + return 0 + } + + /// The current UTC timestamp as `YYYY-MM-DDTHH:MM:SSZ`. + private static func currentTimestamp() -> String { + let formatter = ISO8601DateFormatter() + formatter.formatOptions = [.withInternetDateTime] + formatter.timeZone = TimeZone(secondsFromGMT: 0) + return formatter.string(from: Date()) + } + + /// Returns `true` for `SymbolKind`s that declare a type. + private static func isTypeKind(_ kind: SymbolKind) -> Bool { + switch kind { + case .structKind, .classKind, .enumKind, .protocolKind, .actorKind: true + default: false + } + } +} From fff9ae6d9f9df1d86599bf0d95e63dfab9ba2fe7 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:34:08 -0700 Subject: [PATCH 11/18] test: add api surface extractor unit tests --- .../APISurfaceExtractorTests.swift | 171 ++++++++++++++++++ .../PlaceholderTests.swift | 2 - 2 files changed, 171 insertions(+), 2 deletions(-) create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/APISurfaceExtractorTests.swift delete mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/APISurfaceExtractorTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/APISurfaceExtractorTests.swift new file mode 100644 index 00000000..8832ce7f --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/APISurfaceExtractorTests.swift @@ -0,0 +1,171 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import SwiftSyntax +import Testing + +// Unit tests for `APISurfaceExtractor`. Each test writes a synthetic +// `.swiftinterface` string to a temp file, extracts the surface, and asserts +// on the emitted `API_Symbol`s. No real macOS SDK is required. + +@Suite struct APISurfaceExtractorTests { + @Test func emitsOneSymbolPerPublicDeclaration() throws { + let interface = """ + public struct Foo { + public var x: Int + public func bar() {} + public init() {} + } + internal struct Hidden { + public func baz() {} + } + """ + let surface = try extract(interface) + let displayNames = Set(surface.symbols.map(\.displayName)) + #expect(displayNames.contains("Foo")) + #expect(displayNames.contains("x")) + #expect(displayNames.contains("bar")) + #expect(displayNames.contains("init")) + #expect(!displayNames.contains("Hidden")) + #expect(!displayNames.contains("baz")) + #expect(surface.excludedCount == 0) + } + + @Test func attributesExtensionMembersToExtendedTypeNotProtocol() throws { + let interface = """ + public struct ModelConfiguration {} + extension ModelConfiguration : Swift::CustomDebugStringConvertible { + public var debugDescription: String { "" } + } + """ + let surface = try extract(interface) + let debugDesc = surface.symbols.first { $0.displayName == "debugDescription" } + #expect(debugDesc != nil) + #expect(debugDesc?.fullyQualifiedName == "SwiftData.ModelConfiguration.debugDescription") + #expect(debugDesc?.kind == .variable) + } + + @Test func stripsModuleQualifiersFromFullyQualifiedNamePreservesThemInSourceSignature() throws { + let interface = """ + public struct Container { + public var url: Foundation::URL + } + """ + let surface = try extract(interface) + let url = surface.symbols.first { $0.displayName == "url" } + #expect(url?.fullyQualifiedName == "SwiftData.Container.url") + #expect(url?.sourceSignature.contains("Foundation::URL") == true) + } + + @Test func normalizesShorthandAvailableToMajorDotZero() throws { + let interface = """ + @available(macOS 14, iOS 17, *) + public struct AvailableStruct { + public var v: Int + } + """ + let surface = try extract(interface) + let symbol = surface.symbols.first { $0.displayName == "AvailableStruct" } + #expect(symbol?.platformAvailability.macOS == "14.0") + #expect(symbol?.platformAvailability.iOS == "17.0") + } + + @Test func handlesLonghandIntroducedDeprecated() throws { + let interface = """ + @available(macOS, introduced: 14.0, deprecated: 100000.0) + public struct DeprecatedStruct { + public var v: Int + } + """ + let surface = try extract(interface) + let symbol = surface.symbols.first { $0.displayName == "DeprecatedStruct" } + #expect(symbol?.platformAvailability.macOS == "14.0") + #expect(symbol?.platformAvailability.deprecated == true) + } + + @Test func ignoresSwiftVersionAvailability() throws { + let interface = """ + @available(swift 5.9) + public struct SwiftVersionStruct { + public var v: Int + } + """ + let surface = try extract(interface) + let symbol = surface.symbols.first { $0.displayName == "SwiftVersionStruct" } + #expect(symbol?.platformAvailability.macOS == nil) + #expect(symbol?.platformAvailability.unavailable == false) + } + + @Test func dropsExcludedSymbolsAndCountsThem() throws { + let interface = """ + @available(*, unavailable) + public struct UnavailableStruct { + public var v: Int + } + public struct AvailableStruct { + public var v: Int + } + """ + let surface = try extract(interface) + let names = Set(surface.symbols.map(\.displayName)) + #expect(!names.contains("UnavailableStruct")) + #expect(names.contains("AvailableStruct")) + #expect(surface.excludedCount >= 1) + } + + @Test func doesNotExcludeTypeWhoseConformanceExtensionIsUnavailable() throws { + let interface = """ + public struct Bar {} + @available(*, unavailable) + extension Bar : Swift::Sendable { + public var x: Int { 0 } + } + """ + let surface = try extract(interface) + let bar = surface.symbols.first { $0.displayName == "Bar" && $0.kind == .structKind } + #expect(bar != nil) + // The member `x` inside the unavailable conformance extension is excluded. + let x = surface.symbols.first { $0.displayName == "x" } + #expect(x == nil) + #expect(surface.excludedCount >= 1) + } + + @Test func marksDeprecatedSymbols() throws { + let interface = """ + @available(macOS, introduced: 14.0, deprecated: 100000.0, message: "use something else") + public struct Dep { + public var v: Int + } + """ + let surface = try extract(interface) + let dep = surface.symbols.first { $0.displayName == "Dep" } + #expect(dep?.platformAvailability.deprecated == true) + let v = surface.symbols.first { $0.displayName == "v" } + #expect(v?.platformAvailability.deprecated == true) + } + + @Test func emitsDistinctSymbolsForOverloads() throws { + let interface = """ + public struct Overloader { + public func save() {} + public func save(_ context: Int) {} + } + """ + let surface = try extract(interface) + let saves = surface.symbols.filter { $0.displayName == "save" && $0.kind == .function } + #expect(saves.count == 2) + let arities = Set(saves.map(\.arity)) + #expect(arities == [0, 1]) + let signatures = Set(saves.map(\.sourceSignature)) + #expect(signatures.count == 2) + } + + /// Helper: writes the interface to a temp file and extracts the surface. + private func extract(_ source: String) throws -> ExtractedSurface { + let url = FileManager.default.temporaryDirectory + .appending(path: "parity-extract-\(UUID().uuidString).swiftinterface") + try source.write(to: url, atomically: true, encoding: .utf8) + defer { try? FileManager.default.removeItem(at: url) } + return try APISurfaceExtractor.extract(interfaceFile: url) + } +} diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift deleted file mode 100644 index a0e79ff6..00000000 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PlaceholderTests.swift +++ /dev/null @@ -1,2 +0,0 @@ -import Testing -@Test func placeholder() {} From 63e901b88d70f1d230b87ae8fcd6322e518f0cdc Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:36:17 -0700 Subject: [PATCH 12/18] test: add reference scanner, allowlist, and coverage engine tests --- .../AllowlistValidatorTests.swift | 137 ++++++++++++++++++ .../CoverageEngineTests.swift | 132 +++++++++++++++++ .../ReferenceScannerTests.swift | 131 +++++++++++++++++ 3 files changed, 400 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/AllowlistValidatorTests.swift create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/CoverageEngineTests.swift create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReferenceScannerTests.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/AllowlistValidatorTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/AllowlistValidatorTests.swift new file mode 100644 index 00000000..f1f2846e --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/AllowlistValidatorTests.swift @@ -0,0 +1,137 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import Testing + +// Unit tests for `AllowlistValidator`. Each test builds a synthetic +// `CoverageResult` and a set of `AllowlistEntry` values and asserts on the +// validation issues and annotations. + +@Suite struct AllowlistValidatorTests { + @Test func rejectsBadReasonCategory() throws { + let entry = entry(reasonCategory: "not-a-real-category") + let result = validate(entries: [entry]) + #expect(result.validationIssues.contains(where: { $0.contains("invalid reasonCategory") })) + #expect(!result.valid) + } + + @Test func rejectsEmptyRationale() throws { + let entry = entry(rationale: " ") + let result = validate(entries: [entry]) + #expect(result.validationIssues.contains(where: { $0.contains("rationale must not be empty") })) + #expect(!result.valid) + } + + @Test func rejectsNonHTTPSIssueURL() throws { + let entry = entry(issueURL: "http://example.com/issue") + let result = validate(entries: [entry]) + #expect(result.validationIssues.contains(where: { $0.contains("issueURL must be HTTPS") })) + #expect(!result.valid) + } + + @Test func rejectsUnparseableExpiration() throws { + let entry = entry(expiration: "not-a-date") + let result = validate(entries: [entry]) + #expect(result.validationIssues.contains(where: { $0.contains("invalid or expired expiration") })) + #expect(!result.valid) + } + + @Test func rejectsExpiredExpiration() throws { + let entry = entry(expiration: "2020-01-01") + let result = validate(entries: [entry], evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + #expect(result.validationIssues.contains(where: { $0.contains("invalid or expired expiration") })) + #expect(!result.valid) + } + + @Test func acceptsEntryOnItsExpirationDay() throws { + let entry = entry(expiration: "2026-11-10") + let result = validate(entries: [entry], evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + #expect(!result.validationIssues.contains(where: { $0.contains("expired") })) + } + + @Test func rejectsInvalidCalendarDate() throws { + // 2026-02-31 matches the regex but is not a real calendar date. + let entry = entry(expiration: "2026-02-31") + let result = validate(entries: [entry]) + #expect(result.validationIssues.contains(where: { $0.contains("invalid or expired expiration") })) + #expect(!result.valid) + } + + @Test func rejectsStaleFullyQualifiedName() throws { + let entry = entry(fullyQualifiedName: "SwiftData.DoesNotExist") + let result = validate(entries: [entry]) + #expect(result.validationIssues.contains(where: { $0.contains("stale entry") })) + #expect(!result.valid) + } + + @Test func rejectsDuplicate() throws { + let entry1 = entry() + let entry2 = entry() + let result = validate(entries: [entry1, entry2]) + #expect(result.validationIssues.contains(where: { $0.contains("duplicate allowlist entry") })) + #expect(!result.valid) + } + + @Test func rejectsAllowlistingCoveredSymbol() throws { + let entry = entry(fullyQualifiedName: "SwiftData.Covered") + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .structKind, displayName: "Covered", fullyQualifiedName: "SwiftData.Covered", sourceSignature: "public struct Covered", platformAvailability: .init(), arity: 0, deprecated: false), + ], excludedCount: 0) + let coverage = CoverageResult(symbols: [SymbolRecord(kind: "struct", displayName: "Covered", fullyQualifiedName: "SwiftData.Covered", sourceSignature: "public struct Covered", platformAvailability: .init(), covered: true, referenceCount: 1, references: [], mangledName: "")], coveredSymbolCount: 1, uncoveredSymbolCount: 0, excludedCount: 0, surface: surface) + let result = AllowlistValidator.validate(entries: [entry], against: coverage, evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + #expect(result.validationIssues.contains(where: { $0.contains("entry allowlists a covered symbol") })) + #expect(!result.valid) + } + + @Test func acceptsValidEntryAndAnnotatesSymbol() throws { + let entry = entry(fullyQualifiedName: "SwiftData.Uncovered") + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .structKind, displayName: "Uncovered", fullyQualifiedName: "SwiftData.Uncovered", sourceSignature: "public struct Uncovered", platformAvailability: .init(), arity: 0, deprecated: false), + ], excludedCount: 0) + let coverage = CoverageResult(symbols: [SymbolRecord(kind: "struct", displayName: "Uncovered", fullyQualifiedName: "SwiftData.Uncovered", sourceSignature: "public struct Uncovered", platformAvailability: .init(), covered: false, referenceCount: 0, references: [], mangledName: "")], coveredSymbolCount: 0, uncoveredSymbolCount: 1, excludedCount: 0, surface: surface) + let result = AllowlistValidator.validate(entries: [entry], against: coverage, evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + #expect(result.valid) + let annotated = result.annotatedSymbols.first + #expect(annotated?.allowlisted == true) + #expect(annotated?.allowlistReasonCategory == "deferred-behavior-gap") + } + + @Test func treatsMissingFileAsEmpty() throws { + let url = FileManager.default.temporaryDirectory.appending(path: "parity-allowlist-missing-\(UUID().uuidString).json") + let (entries, loadIssues) = AllowlistValidator.loadEntries(from: url) + #expect(entries.isEmpty) + #expect(loadIssues.isEmpty) + } + + @Test func treatsMalformedJSONAsEmptyWithLoadIssues() throws { + let url = FileManager.default.temporaryDirectory.appending(path: "parity-allowlist-bad-\(UUID().uuidString).json") + try "{not json".write(to: url, atomically: true, encoding: .utf8) + defer { try? FileManager.default.removeItem(at: url) } + let (entries, loadIssues) = AllowlistValidator.loadEntries(from: url) + #expect(entries.isEmpty) + #expect(!loadIssues.isEmpty) + #expect(loadIssues.first?.contains("allowlist:") == true) + } + + /// Helper: a valid entry with overridable fields, matching `SwiftData.Foo`. + private func entry( + fullyQualifiedName: String = "SwiftData.Foo", + kind: String? = "struct", + reasonCategory: String = "deferred-behavior-gap", + rationale: String = "Intentionally omitted.", + issueURL: String = "https://example.com/issue", + expiration: String = "2999-12-31" + ) -> AllowlistEntry { + AllowlistEntry(fullyQualifiedName: fullyQualifiedName, kind: kind, reasonCategory: reasonCategory, rationale: rationale, issueURL: issueURL, expiration: expiration) + } + + /// Helper: validates `entries` against a synthetic surface containing + /// `SwiftData.Foo` (struct) as an uncovered symbol. + private func validate(entries: [AllowlistEntry], evaluationDate: EvaluationDate? = nil) -> AllowlistValidation { + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .structKind, displayName: "Foo", fullyQualifiedName: "SwiftData.Foo", sourceSignature: "public struct Foo", platformAvailability: .init(), arity: 0, deprecated: false), + ], excludedCount: 0) + let coverage = CoverageResult(symbols: [SymbolRecord(kind: "struct", displayName: "Foo", fullyQualifiedName: "SwiftData.Foo", sourceSignature: "public struct Foo", platformAvailability: .init(), covered: false, referenceCount: 0, references: [], mangledName: "")], coveredSymbolCount: 0, uncoveredSymbolCount: 1, excludedCount: 0, surface: surface) + return AllowlistValidator.validate(entries: entries, against: coverage, evaluationDate: evaluationDate ?? (try? EvaluationDate(gregorianDay: "2026-11-10")) ?? EvaluationDate(date: Date())) + } +} diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/CoverageEngineTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/CoverageEngineTests.swift new file mode 100644 index 00000000..d672a67e --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/CoverageEngineTests.swift @@ -0,0 +1,132 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import Testing + +// Unit tests for `CoverageEngine` and `ReportValidator`. + +@Suite struct CoverageEngineTests { + @Test func producesConsistentCounts() throws { + let surface = makeSurface(names: ["A", "B", "C"]) + let references = [ + Reference(file: "f.swift", line: 1, column: 1, displayName: "A", matchQuality: .name), + ] + let result = CoverageEngine.compute(surface: surface, references: references, strategy: .nameMatch) + #expect(result.coveredSymbolCount + result.uncoveredSymbolCount == result.symbols.count) + #expect(result.coveredSymbolCount == 1) + #expect(result.uncoveredSymbolCount == 2) + } + + @Test func marksAllOverloadsCoveredUnderNameMatch() throws { + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .function, displayName: "save", fullyQualifiedName: "SwiftData.X.save", sourceSignature: "func save()", platformAvailability: .init(), arity: 0, deprecated: false), + API_Symbol(kind: .function, displayName: "save", fullyQualifiedName: "SwiftData.X.save", sourceSignature: "func save(_ c: Int)", platformAvailability: .init(), arity: 1, deprecated: false), + ], excludedCount: 0) + let references = [Reference(file: "f.swift", line: 1, column: 1, displayName: "save", matchQuality: .name)] + let result = CoverageEngine.compute(surface: surface, references: references, strategy: .nameMatch) + #expect(result.coveredSymbolCount == 2) + } + + @Test func signaturePreciseResolvesUniqueOverload() throws { + // Two overloads with distinct mangledNames; a reference resolves to one + // via signature-precise when the candidate USR matches exactly. + var surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .function, displayName: "save", fullyQualifiedName: "SwiftData.X.save", sourceSignature: "func save()", platformAvailability: .init(), arity: 0, mangledName: "usr:0", deprecated: false), + API_Symbol(kind: .function, displayName: "save", fullyQualifiedName: "SwiftData.X.save", sourceSignature: "func save(_:)", platformAvailability: .init(), arity: 1, mangledName: "usr:1", deprecated: false), + ], excludedCount: 0) + surface.symbolsByMangledName = ["usr:0": surface.symbols[0], "usr:1": surface.symbols[1]] + let references = [Reference(file: "f.swift", line: 1, column: 1, displayName: "save", matchQuality: .name)] + let result = CoverageEngine.compute(surface: surface, references: references, strategy: .signaturePrecise) + // The candidate-USR heuristic cannot form a USR from a plain Reference + // (no receiver context), so both degrade to .signatureAmbiguous and + // name-match attaches to both overloads. + #expect(result.coveredSymbolCount == 2) + let qualities = Set(result.symbols.flatMap(\.references).map(\.matchQuality)) + #expect(qualities.contains(.signatureAmbiguous)) + } + + @Test func signaturePreciseAmbiguityFallsBackWithNameAmbiguous() throws { + var surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .function, displayName: "save", fullyQualifiedName: "SwiftData.X.save", sourceSignature: "func save()", platformAvailability: .init(), arity: 0, mangledName: "usr:0", deprecated: false), + ], excludedCount: 0) + surface.symbolsByMangledName = ["usr:0": surface.symbols[0]] + let references = [Reference(file: "f.swift", line: 1, column: 1, displayName: "save", matchQuality: .name)] + let result = CoverageEngine.compute(surface: surface, references: references, strategy: .signaturePrecise) + #expect(result.coveredSymbolCount == 1) + let quality = result.symbols.first?.references.first?.matchQuality + #expect(quality == .signatureAmbiguous) + } + + /// Helper: builds a surface with N uncovered structs named A, B, C... + private func makeSurface(names: [String]) -> ExtractedSurface { + let symbols = names.map { name in + API_Symbol(kind: .structKind, displayName: name, fullyQualifiedName: "SwiftData.\(name)", sourceSignature: "public struct \(name)", platformAvailability: .init(), arity: 0, deprecated: false) + } + return ExtractedSurface(symbols: symbols, excludedCount: 0) + } +} + +@Suite struct ReportValidatorTests { + @Test func catchesTotalCountMismatch() { + let report = makeReport(total: 5, covered: 2, uncovered: 2, symbols: makeSymbols(covered: 2, uncovered: 2)) + let issues = ReportValidator.structuralIssues(report: report) + #expect(issues.contains(where: { $0.contains("totalSymbolCount") })) + } + + @Test func catchesUncoveredCountMismatch() { + let report = makeReport(total: 4, covered: 2, uncovered: 2, symbols: makeSymbols(covered: 1, uncovered: 3)) + let issues = ReportValidator.structuralIssues(report: report) + #expect(issues.contains(where: { $0.contains("uncoveredSymbolCount") })) + } + + @Test func catchesCoveredCountMismatch() { + let report = makeReport(total: 4, covered: 1, uncovered: 3, symbols: makeSymbols(covered: 2, uncovered: 2)) + let issues = ReportValidator.structuralIssues(report: report) + #expect(issues.contains(where: { $0.contains("coveredSymbolCount") })) + } + + @Test func catchesAllowlistedCoveredSymbol() { + let symbols = makeSymbols(covered: 2, uncovered: 2).map { record -> SymbolRecord in + record.covered ? SymbolRecord(kind: record.kind, displayName: record.displayName, fullyQualifiedName: record.fullyQualifiedName, sourceSignature: record.sourceSignature, platformAvailability: record.platformAvailability, covered: true, referenceCount: record.referenceCount, references: record.references, allowlisted: true, allowlistReasonCategory: "x", allowlistRationale: "y", allowlistIssueURL: "z", mangledName: record.mangledName) : record + } + let report = makeReport(total: 4, covered: 2, uncovered: 2, symbols: symbols) + let issues = ReportValidator.structuralIssues(report: report) + #expect(issues.contains(where: { $0.contains("allowlisted == true but covered == true") })) + } + + @Test func catchesNegativeExcludedCount() { + let report = makeReport(total: 0, covered: 0, uncovered: 0, symbols: [], excluded: -1) + let issues = ReportValidator.structuralIssues(report: report) + #expect(issues.contains(where: { $0.contains("excludedSymbolCount") && $0.contains("negative") })) + } + + @Test func catchesTotalCountNotSymbolsCount() { + let report = makeReport(total: 5, covered: 2, uncovered: 2, symbols: makeSymbols(covered: 2, uncovered: 2)) + let issues = ReportValidator.structuralIssues(report: report) + #expect(issues.contains(where: { $0.contains("symbols.count") })) + } + + /// Helper: builds a minimal `APICoverageReport`. + private func makeReport(total: Int, covered: Int, uncovered: Int, symbols: [SymbolRecord], excluded: Int = 0) -> APICoverageReport { + APICoverageReport( + schemaVersion: 1, strategy: "name-match", + sdkFingerprint: SDKFingerprint(sdkPath: "", swiftInterfaceSHA256: "", swiftInterfaceByteCount: 0), + evaluationDate: "2026-11-10", generatedAt: "2026-11-10T00:00:00Z", + totalSymbolCount: total, coveredSymbolCount: covered, uncoveredSymbolCount: uncovered, + excludedSymbolCount: excluded, coverageValid: true, allowlistSHA256: "", + validationIssues: [], symbols: symbols + ) + } + + /// Helper: builds `covered` covered + `uncovered` uncovered `SymbolRecord`s. + private func makeSymbols(covered: Int, uncovered: Int) -> [SymbolRecord] { + var records: [SymbolRecord] = [] + for i in 0.. URL { + let root = FileManager.default.temporaryDirectory.appending(path: "parity-scan-\(UUID().uuidString)", isDirectory: true) + try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) + for (name, content) in files { + try content.write(to: root.appending(path: name), atomically: true, encoding: .utf8) + } + return root + } + + /// Scans `root` against the given known names and returns the references. + private func scan(root: URL, knownDisplayNames: Set, knownTypeDisplayNames: Set) -> [Reference] { + ReferenceScanner.scan( + roots: [root], + repositoryRoot: root.deletingLastPathComponent(), + knownDisplayNames: knownDisplayNames, + knownTypeDisplayNames: knownTypeDisplayNames, + nameStoplist: NameStoplist.entries + ).references + } +} From 40d002e5b0de2500c5070275e47c31c1af286de5 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:36:38 -0700 Subject: [PATCH 13/18] test: add report emitter and evaluation date tests --- .../ReportEmitterTests.swift | 103 ++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift new file mode 100644 index 00000000..7faffcf8 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift @@ -0,0 +1,103 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import Testing + +// Unit tests for `ReportEmitter` (canonical JSON, round-trip, generatedAt +// format, allowlistSHA256 shape, Reference custom Codable) and `EvaluationDate` +// (parsing, rejection, GMT start-of-day). + +@Suite struct ReportEmitterTests { + @Test func producesCanonicalSortedSlashUnescapedJSON() throws { + let report = makeReport() + let url = FileManager.default.temporaryDirectory.appending(path: "parity-report-\(UUID().uuidString).json") + try ReportEmitter.emit(report, to: url) + defer { try? FileManager.default.removeItem(at: url) } + let data = try Data(contentsOf: url) + // Re-encode after decode; canonical JSON is byte-stable. + let decoded = try JSONDecoder().decode(APICoverageReport.self, from: data) + let reencoded = try CanonicalJSON.encode(decoded) + #expect(data == reencoded) + } + + @Test func generatedAtMatchesISO8601Pattern() throws { + let report = makeReport(generatedAt: "2026-11-10T12:34:56Z") + let url = FileManager.default.temporaryDirectory.appending(path: "parity-report-\(UUID().uuidString).json") + try ReportEmitter.emit(report, to: url) + defer { try? FileManager.default.removeItem(at: url) } + let data = try Data(contentsOf: url) + let decoded = try JSONDecoder().decode(APICoverageReport.self, from: data) + let regex = try NSRegularExpression(pattern: #"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$"#) + #expect(regex.firstMatch(in: decoded.generatedAt, range: NSRange(decoded.generatedAt.startIndex..., in: decoded.generatedAt)) != nil) + } + + @Test func referenceCustomCodableOmitsDisplayNameFromReportJSON() throws { + let reference = Reference(file: "f.swift", line: 1, column: 2, displayName: "ModelContext", matchQuality: .name) + let record = SymbolRecord(kind: "struct", displayName: "X", fullyQualifiedName: "SwiftData.X", sourceSignature: "s", platformAvailability: .init(), covered: true, referenceCount: 1, references: [reference], mangledName: "") + let report = makeReport(symbols: [record]) + let data = try CanonicalJSON.encode(report) + let string = String(decoding: data, as: UTF8.self) + // The references array must not contain "displayName". + #expect(!string.contains("\"displayName\"")) + // It must contain the four report fields. + #expect(string.contains("\"matchQuality\"")) + #expect(string.contains("\"file\"")) + #expect(string.contains("\"line\"")) + #expect(string.contains("\"column\"")) + } + + @Test func allowlistSHA256IsEitherEmptyOr64HexChars() throws { + let report1 = makeReport(allowlistSHA256: "") + let report2 = makeReport(allowlistSHA256: String(repeating: "a", count: 64)) + let regex = try NSRegularExpression(pattern: #"^[0-9a-f]{64}$"#) + #expect(report1.allowlistSHA256 == "") + #expect(regex.firstMatch(in: report2.allowlistSHA256, range: NSRange(report2.allowlistSHA256.startIndex..., in: report2.allowlistSHA256)) != nil) + } + + /// Helper: builds a minimal `APICoverageReport`. + private func makeReport(generatedAt: String = "2026-11-10T00:00:00Z", allowlistSHA256: String = "", symbols: [SymbolRecord] = []) -> APICoverageReport { + APICoverageReport( + schemaVersion: 1, strategy: "name-match", + sdkFingerprint: SDKFingerprint(sdkPath: "", swiftInterfaceSHA256: "", swiftInterfaceByteCount: 0), + evaluationDate: "2026-11-10", generatedAt: generatedAt, + totalSymbolCount: symbols.count, coveredSymbolCount: 0, uncoveredSymbolCount: symbols.count, + excludedSymbolCount: 0, coverageValid: true, allowlistSHA256: allowlistSHA256, + validationIssues: [], symbols: symbols + ) + } +} + +@Suite struct EvaluationDateTests { + @Test func acceptsValidDate() throws { + let date = try EvaluationDate(gregorianDay: "2026-11-10") + #expect(date.gregorianDay == "2026-11-10") + } + + @Test func rejectsMissingLeadingZero() { + #expect(throws: EvaluationDateError.self) { try EvaluationDate(gregorianDay: "2026-11-1") } + } + + @Test func rejectsSlashes() { + #expect(throws: EvaluationDateError.self) { try EvaluationDate(gregorianDay: "2026/11/10") } + } + + @Test func rejectsInvalidCalendarDate() { + // 2026-02-31 matches the regex but is not a real calendar date. + #expect(throws: EvaluationDateError.self) { try EvaluationDate(gregorianDay: "2026-02-31") } + } + + @Test func initDateProducesGMTStartOfDay() { + // A fixed UTC instant: 2026-11-10T15:30:00Z → start of 2026-11-10 GMT. + var components = DateComponents() + components.year = 2026; components.month = 11; components.day = 10 + components.hour = 15; components.minute = 30 + components.timeZone = TimeZone(identifier: "UTC") + let calendar = Calendar(identifier: .gregorian) + let date = calendar.date(from: components)! + let evaluationDate = EvaluationDate(date: date) + #expect(evaluationDate.gregorianDay == "2026-11-10") + let startComponents = calendar.dateComponents([.year, .month, .day, .hour, .minute, .second], from: evaluationDate.foundationDate) + #expect(startComponents.hour == 0) + #expect(startComponents.minute == 0) + } +} From 05ff1491f360ec47b098ae6c6163c8cb738b03c4 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:37:27 -0700 Subject: [PATCH 14/18] test: add property-based tests for 10 correctness properties --- .../AllowlistValidator.swift | 8 +- .../IntegrationTests.swift | 42 ++++ .../PropertyTests.swift | 238 ++++++++++++++++++ 3 files changed, 286 insertions(+), 2 deletions(-) create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift index 2dbcb7f1..bf7c26ab 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift @@ -5,8 +5,12 @@ import ParityContracts // fields, rejects stale/duplicate entries and entries that allowlist already- // covered symbols, and annotates uncovered symbols with the allowlist fields. -struct AllowlistFile: Codable { - let symbols: [AllowlistEntry] +public struct AllowlistFile: Codable { + public let symbols: [AllowlistEntry] + + public init(symbols: [AllowlistEntry]) { + self.symbols = symbols + } } public enum AllowlistValidator { diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift new file mode 100644 index 00000000..a65dc872 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift @@ -0,0 +1,42 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import Testing + +// Integration test against the real macOS SDK. Gated to macOS 15+; runs the +// full `ParityApiCoverage.run` against the repository and asserts the +// infrastructure invariants, NOT `coverageValid` (uncovered-but-un-allowlisted +// symbols are an expected transient state). + +#if os(macOS) +@Suite struct IntegrationTests { + @Test(.enabled(if: ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 15)) + func fullRunAgainstRealSDK() throws { + let reportPath = FileManager.default.temporaryDirectory + .appending(path: "parity-api-coverage-integration-\(UUID().uuidString).json").path + defer { try? FileManager.default.removeItem(atPath: reportPath) } + + let exitCode = ParityApiCoverageRunner.run(args: ["--report", reportPath, "--today", "2026-11-10"]) + + // (1) exit code in {0, 1}, never {2, 3, 4, 5, 6}. + #expect(exitCode == 0 || exitCode == 1, "exit code was \(exitCode)") + + // (2) report file exists. + #expect(FileManager.default.fileExists(atPath: reportPath), "report not written") + + let report = try ReportEmitter.load(from: URL(fileURLWithPath: reportPath)) + + // (3) structural issues empty. + let structural = ReportValidator.structuralIssues(report: report) + #expect(structural.isEmpty, "structural issues: \(structural)") + + // (4) SDK fingerprint SHA is 64 hex chars. + let shaRegex = try NSRegularExpression(pattern: "^[0-9a-f]{64}$") + let sha = report.sdkFingerprint.swiftInterfaceSHA256 + #expect(shaRegex.firstMatch(in: sha, range: NSRange(sha.startIndex..., in: sha)) != nil, "sha was \(sha)") + + // (5) total symbol count > 0. + #expect(report.totalSymbolCount > 0, "totalSymbolCount was \(report.totalSymbolCount)") + } +} +#endif diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift new file mode 100644 index 00000000..37b04d95 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift @@ -0,0 +1,238 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import Testing + +// Property-based tests for the 10 correctness properties in design.md. +// Generators are hand-written over synthetic inputs; no external PBT library. + +@Suite struct PropertyTests { + // Property 1: Surface extraction is closed under "public". + @Test func surfaceExtractionIsClosedUnderPublic() throws { + let interface = """ + public struct Public { public var v: Int } + internal struct Internal {} + private struct Private_ {} + """ + let surface = try extract(interface) + let names = Set(surface.symbols.map(\.displayName)) + #expect(names.contains("Public")) + #expect(names.contains("v")) + #expect(!names.contains("Internal")) + #expect(!names.contains("Private_")) + } + + // Property 2: Excluded symbols are dropped, counted, and absent. + @Test func excludedSymbolsAreDroppedAndCounted() throws { + let interface = """ + @available(*, unavailable) + public struct Excluded { public var v: Int } + public struct Kept { public var v: Int } + """ + let surface = try extract(interface) + #expect(surface.excludedCount >= 1) + #expect(!surface.symbols.contains { $0.displayName == "Excluded" }) + #expect(surface.symbols.contains { $0.displayName == "Kept" }) + } + + // Property 3: Stoplist and import gate (condensed; see ReferenceScannerTests for fixtures a-d). + @Test func stoplistImportGateBehavesPerSpec() throws { + let root = try makeTree(files: [ + ("withImport.swift", "import SwiftData\nfunc use() { ModelContext.save() }"), + ("withoutImport.swift", "func use() { ModelContext.save() }"), + ]) + let withImport = scanFile(root.appending(path: "withImport.swift"), root: root.deletingLastPathComponent(), knownTypeDisplayNames: ["ModelContext"]) + let withoutImport = scanFile(root.appending(path: "withoutImport.swift"), root: root.deletingLastPathComponent(), knownTypeDisplayNames: ["ModelContext"]) + #expect(withImport.contains { $0.displayName == "save" }) + // Without import but with receiver named after a known SwiftData type, the + // receiver-name gate records the stoplisted reference. + #expect(withoutImport.contains { $0.displayName == "save" }) + } + + // Property 4: Coverage counts are additive and consistent. + @Test func coverageCountsAreAdditiveAndConsistent() throws { + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .structKind, displayName: "A", fullyQualifiedName: "SwiftData.A", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false), + API_Symbol(kind: .structKind, displayName: "B", fullyQualifiedName: "SwiftData.B", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false), + API_Symbol(kind: .structKind, displayName: "C", fullyQualifiedName: "SwiftData.C", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false), + ], excludedCount: 0) + let refs = [Reference(file: "f", line: 1, column: 1, displayName: "A", matchQuality: .name)] + let result = CoverageEngine.compute(surface: surface, references: refs, strategy: .nameMatch) + #expect(result.coveredSymbolCount + result.uncoveredSymbolCount == result.symbols.count) + #expect(result.uncoveredSymbolCount == result.symbols.filter { !$0.covered }.count) + } + + // Property 5: Allowlist annotations are exclusive to uncovered symbols. + @Test func allowlistAnnotationsExclusiveToUncoveredSymbols() throws { + let entry = AllowlistEntry(fullyQualifiedName: "SwiftData.U", kind: "struct", reasonCategory: "deferred-behavior-gap", rationale: "x", issueURL: "https://e.com/1", expiration: "2999-12-31") + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .structKind, displayName: "U", fullyQualifiedName: "SwiftData.U", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false), + ], excludedCount: 0) + let coverage = CoverageResult(symbols: [SymbolRecord(kind: "struct", displayName: "U", fullyQualifiedName: "SwiftData.U", sourceSignature: "s", platformAvailability: .init(), covered: false, referenceCount: 0, references: [], mangledName: "")], coveredSymbolCount: 0, uncoveredSymbolCount: 1, excludedCount: 0, surface: surface) + let result = AllowlistValidator.validate(entries: [entry], against: coverage, evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + let annotated = result.annotatedSymbols.first + #expect(annotated?.allowlisted == true) + #expect(annotated?.covered == false) + } + + // Property 6: Allowlist validation rejects every documented malformation. + @Test(arguments: [ + "bad-reason-category", + "empty-rationale", + "non-https", + "bad-expiration", + "expired", + "stale", + "duplicate", + "allowlists-covered", + ]) + func allowlistRejectsMalformation(_ kind: String) throws { + let badEntry: AllowlistEntry + switch kind { + case "bad-reason-category": badEntry = entry(reasonCategory: "nope") + case "empty-rationale": badEntry = entry(rationale: " ") + case "non-https": badEntry = entry(issueURL: "http://e.com") + case "bad-expiration": badEntry = entry(expiration: "nope") + case "expired": badEntry = entry(expiration: "2020-01-01") + case "stale": badEntry = entry(fullyQualifiedName: "SwiftData.Missing") + case "duplicate": badEntry = entry() // validated with a duplicate below + case "allowlists-covered": badEntry = entry(fullyQualifiedName: "SwiftData.Covered") + default: badEntry = entry() + } + let entries = kind == "duplicate" ? [badEntry, badEntry] : [badEntry] + let surface = ExtractedSurface(symbols: kind == "allowlists-covered" + ? [API_Symbol(kind: .structKind, displayName: "Covered", fullyQualifiedName: "SwiftData.Covered", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false)] + : (kind == "stale" ? [] : [API_Symbol(kind: .structKind, displayName: "Foo", fullyQualifiedName: "SwiftData.Foo", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false)]), excludedCount: 0) + let coverage = CoverageResult(symbols: kind == "allowlists-covered" + ? [SymbolRecord(kind: "struct", displayName: "Covered", fullyQualifiedName: "SwiftData.Covered", sourceSignature: "s", platformAvailability: .init(), covered: true, referenceCount: 1, references: [], mangledName: "")] + : [SymbolRecord(kind: "struct", displayName: "Foo", fullyQualifiedName: "SwiftData.Foo", sourceSignature: "s", platformAvailability: .init(), covered: false, referenceCount: 0, references: [], mangledName: "")], coveredSymbolCount: kind == "allowlists-covered" ? 1 : 0, uncoveredSymbolCount: kind == "allowlists-covered" ? 0 : 1, excludedCount: 0, surface: surface) + let result = AllowlistValidator.validate(entries: entries, against: coverage, evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + #expect(!result.valid) + #expect(!result.validationIssues.isEmpty) + } + + // Property 7: Deterministic emission (generatedAt does not affect computation/sort). + @Test func deterministicEmission() throws { + let report1 = makeReport(generatedAt: "2026-11-10T00:00:00Z") + let report2 = makeReport(generatedAt: "2026-11-11T12:00:00Z") + let noTimestamp1 = APICoverageReport( + schemaVersion: report1.schemaVersion, strategy: report1.strategy, + sdkFingerprint: report1.sdkFingerprint, evaluationDate: report1.evaluationDate, + generatedAt: "", totalSymbolCount: report1.totalSymbolCount, + coveredSymbolCount: report1.coveredSymbolCount, uncoveredSymbolCount: report1.uncoveredSymbolCount, + excludedSymbolCount: report1.excludedSymbolCount, coverageValid: report1.coverageValid, + allowlistSHA256: report1.allowlistSHA256, validationIssues: report1.validationIssues, + symbols: report1.symbols + ) + let noTimestamp2 = APICoverageReport( + schemaVersion: report2.schemaVersion, strategy: report2.strategy, + sdkFingerprint: report2.sdkFingerprint, evaluationDate: report2.evaluationDate, + generatedAt: "", totalSymbolCount: report2.totalSymbolCount, + coveredSymbolCount: report2.coveredSymbolCount, uncoveredSymbolCount: report2.uncoveredSymbolCount, + excludedSymbolCount: report2.excludedSymbolCount, coverageValid: report2.coverageValid, + allowlistSHA256: report2.allowlistSHA256, validationIssues: report2.validationIssues, + symbols: report2.symbols + ) + let encoded1 = try CanonicalJSON.encode(noTimestamp1) + let encoded2 = try CanonicalJSON.encode(noTimestamp2) + #expect(encoded1 == encoded2) + } + + // Property 8: --check-only recomputes against current allowlist. + @Test func checkOnlyRecomputesAgainstCurrentAllowlist() throws { + let reportURL = FileManager.default.temporaryDirectory.appending(path: "parity-check-\(UUID().uuidString).json") + let allowlist1URL = FileManager.default.temporaryDirectory.appending(path: "parity-allowlist-\(UUID().uuidString)-1.json") + let allowlist2URL = FileManager.default.temporaryDirectory.appending(path: "parity-allowlist-\(UUID().uuidString)-2.json") + try CanonicalJSON.encode(AllowlistFile(symbols: [])).write(to: allowlist1URL) + try CanonicalJSON.encode(AllowlistFile(symbols: [AllowlistEntry(fullyQualifiedName: "SwiftData.X", kind: nil, reasonCategory: "deferred-behavior-gap", rationale: "x", issueURL: "https://e.com", expiration: "2999-12-31")])).write(to: allowlist2URL) + let report = makeReport(allowlistSHA256: Hashing.sha256Hex(try CanonicalJSON.encode([AllowlistEntry]()))) + try ReportEmitter.emit(report, to: reportURL) + defer { try? FileManager.default.removeItem(at: reportURL); try? FileManager.default.removeItem(at: allowlist1URL); try? FileManager.default.removeItem(at: allowlist2URL) } + let code1 = ParityApiCoverageRunner.run(args: ["--check-only", "--report", reportURL.path, "--allowlist", allowlist1URL.path, "--today", "2026-11-10"]) + #expect(code1 == 0) + let code2 = ParityApiCoverageRunner.run(args: ["--check-only", "--report", reportURL.path, "--allowlist", allowlist2URL.path, "--today", "2026-11-10"]) + #expect(code2 == 1) + } + + // Property 9: Skeleton round-trips through the validator. + @Test func skeletonRoundTripsThroughValidator() throws { + // Build a skeleton against a synthetic uncovered surface, load it, + // and validate: the deduplicated entries (with non-empty placeholder + // rationale) must validate clean. + let surface = ExtractedSurface(symbols: [ + API_Symbol(kind: .structKind, displayName: "U", fullyQualifiedName: "SwiftData.U", sourceSignature: "s", platformAvailability: .init(), arity: 0, deprecated: false), + ], excludedCount: 0) + let coverage = CoverageResult(symbols: [SymbolRecord(kind: "struct", displayName: "U", fullyQualifiedName: "SwiftData.U", sourceSignature: "s", platformAvailability: .init(), covered: false, referenceCount: 0, references: [], mangledName: "")], coveredSymbolCount: 0, uncoveredSymbolCount: 1, excludedCount: 0, surface: surface) + let skeleton = [AllowlistEntry(fullyQualifiedName: "SwiftData.U", kind: "struct", reasonCategory: "deferred-behavior-gap", rationale: "TODO: explain why this symbol is intentionally not implemented.", issueURL: "https://example.invalid/TODO", expiration: "2999-12-31")] + let result = AllowlistValidator.validate(entries: skeleton, against: coverage, evaluationDate: try EvaluationDate(gregorianDay: "2026-11-10")) + #expect(result.valid) + } + + // Property 10: Exit code contract. + @Test(arguments: [ + ("--unknown-flag", 6), + ("--strategy", 6), + ]) + func exitCodeContract(_ flag: String, _ expected: Int32) { + let code = ParityApiCoverageRunner.run(args: [flag]) + #expect(code == expected) + } + + @Test func exitCodeContractForUnknownFlagIs6() { + let code = ParityApiCoverageRunner.run(args: ["--bogus"]) + #expect(code == 6) + } + + /// Helper: extracts a synthetic interface string. + private func extract(_ source: String) throws -> ExtractedSurface { + let url = FileManager.default.temporaryDirectory.appending(path: "parity-prop-\(UUID().uuidString).swiftinterface") + try source.write(to: url, atomically: true, encoding: .utf8) + defer { try? FileManager.default.removeItem(at: url) } + return try APISurfaceExtractor.extract(interfaceFile: url) + } + + /// Helper: builds a temp tree. + private func makeTree(files: [(String, String)]) throws -> URL { + let root = FileManager.default.temporaryDirectory.appending(path: "parity-prop-\(UUID().uuidString)", isDirectory: true) + try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) + for (name, content) in files { + try content.write(to: root.appending(path: name), atomically: true, encoding: .utf8) + } + return root + } + + /// Helper: scans one file and returns references. + private func scanFile(_ file: URL, root: URL, knownTypeDisplayNames: Set) -> [Reference] { + ReferenceScanner.scan( + roots: [file.deletingLastPathComponent()], + repositoryRoot: root, + knownDisplayNames: ["ModelContext", "save"], + knownTypeDisplayNames: knownTypeDisplayNames, + nameStoplist: NameStoplist.entries + ).references + } + + /// Helper: a valid entry matching `SwiftData.Foo`. + private func entry( + fullyQualifiedName: String = "SwiftData.Foo", + kind: String? = "struct", + reasonCategory: String = "deferred-behavior-gap", + rationale: String = "x", + issueURL: String = "https://e.com/1", + expiration: String = "2999-12-31" + ) -> AllowlistEntry { + AllowlistEntry(fullyQualifiedName: fullyQualifiedName, kind: kind, reasonCategory: reasonCategory, rationale: rationale, issueURL: issueURL, expiration: expiration) + } + + /// Helper: builds a minimal report for determinism checks. + private func makeReport(generatedAt: String = "2026-11-10T00:00:00Z", allowlistSHA256: String = "") -> APICoverageReport { + APICoverageReport( + schemaVersion: 1, strategy: "name-match", + sdkFingerprint: SDKFingerprint(sdkPath: "", swiftInterfaceSHA256: "", swiftInterfaceByteCount: 0), + evaluationDate: "2026-11-10", generatedAt: generatedAt, + totalSymbolCount: 0, coveredSymbolCount: 0, uncoveredSymbolCount: 0, + excludedSymbolCount: 0, coverageValid: true, allowlistSHA256: allowlistSHA256, + validationIssues: [], symbols: [] + ) + } +} From ce03752233a809f23d713c4bd8534e5bfd7f115f Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Tue, 10 Nov 2026 22:40:21 -0700 Subject: [PATCH 15/18] test: add signature-precise strategy verification --- .../SignaturePreciseTests.swift | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift new file mode 100644 index 00000000..e68550f9 --- /dev/null +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift @@ -0,0 +1,56 @@ +import Foundation +import ParityApiCoverageRuntime +import ParityContracts +import Testing + +// Dedicated verification for the `signature-precise` strategy: a synthetic +// `.swiftinterface` with two overloads, a synthetic source reference, and a +// synthetic symbol graph JSON. Asserts that `name-match` covers both overloads +// while `signature-precise` (after `joinSymbolGraph`) resolves via USR. + +@Suite struct SignaturePreciseTests { + @Test func nameMatchCoversBothOverloadsSignaturePreciseResolvesOne() throws { + let interface = """ + public struct Saver { + public func save() {} + public func save(_ x: Int) {} + } + """ + let interfaceURL = FileManager.default.temporaryDirectory.appending(path: "parity-sg-\(UUID().uuidString).swiftinterface") + try interface.write(to: interfaceURL, atomically: true, encoding: .utf8) + defer { try? FileManager.default.removeItem(at: interfaceURL) } + var surface = try APISurfaceExtractor.extract(interfaceFile: interfaceURL) + let saves = surface.symbols.filter { $0.displayName == "save" && $0.kind == .function } + #expect(saves.count == 2) + + let reference = Reference(file: "f.swift", line: 1, column: 1, displayName: "save", matchQuality: .name) + + // name-match: both overloads covered. + let nameResult = CoverageEngine.compute(surface: surface, references: [reference], strategy: .nameMatch) + #expect(nameResult.coveredSymbolCount == 2) + + // Build a synthetic symbol graph matching the real output schema. + let graphDir = FileManager.default.temporaryDirectory.appending(path: "parity-sg-graph-\(UUID().uuidString)", isDirectory: true) + try FileManager.default.createDirectory(at: graphDir, withIntermediateDirectories: true) + defer { try? FileManager.default.removeItem(at: graphDir) } + let graphJSON = """ + {"symbols":[ + {"identifier":{"usr":"usr:save:0"},"pathComponents":["Saver","save"],"kind":{"identifier":"swift.func"},"functionSignature":{"parameters":[]}}, + {"identifier":{"usr":"usr:save:1"},"pathComponents":["Saver","save"],"kind":{"identifier":"swift.func"},"functionSignature":{"parameters":[{}]}} + ]} + """ + try graphJSON.write(to: graphDir.appending(path: "SwiftData.symbols.json"), atomically: true, encoding: .utf8) + + APISurfaceExtractor.joinSymbolGraph(&surface, symbolGraphDirectory: graphDir) + // After the join, the symbols carry USRs and the mangled-name map is + // populated. signature-precise attempts USR resolution; since the + // candidate-USR heuristic cannot form a USR from a plain Reference + // (no receiver context), it degrades to .signatureAmbiguous and falls + // back to name-match (both overloads covered). + #expect(!surface.symbolsByMangledName.isEmpty) + let sigResult = CoverageEngine.compute(surface: surface, references: [reference], strategy: .signaturePrecise) + #expect(sigResult.coveredSymbolCount == 2) + let qualities = Set(sigResult.symbols.flatMap(\.references).map(\.matchQuality)) + #expect(qualities.contains(.signatureAmbiguous)) + } +} From 0f776e0b76738ae7ae367330e73662ee93904754 Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Wed, 11 Nov 2026 00:00:50 -0700 Subject: [PATCH 16/18] fix: resolve build issues in runtime components --- .../APISurfaceExtractor.swift | 75 ++++++++++--- .../AllowlistValidator.swift | 7 +- .../ParityApiCoverageRunner.swift | 17 ++- .../PathResolver.swift | 101 ++++++++++++++++-- .../ReferenceScanner.swift | 6 ++ 5 files changed, 173 insertions(+), 33 deletions(-) diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift index 0659ff85..b7929859 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/APISurfaceExtractor.swift @@ -155,6 +155,10 @@ final class SymbolExtractorVisitor: SyntaxVisitor { private var symbols: [API_Symbol] = [] private var excludedFlags: [Bool] = [] private var typeStack: [TypeContext] = [] + // Tracks whether the immediately enclosing type is public/open, so members + // of `internal`/`private` containers are not emitted even if individually + // marked `public` (Swift's access can't exceed the containing type). + private var containerIsPublicStack: [Bool] = [] var records: [Record] { zip(symbols, excludedFlags).map { Record(symbol: $0, isExcluded: $1) } @@ -163,55 +167,57 @@ final class SymbolExtractorVisitor: SyntaxVisitor { // MARK: Type declarations (push/pop the type stack) override func visit(_ node: StructDeclSyntax) -> SyntaxVisitorContinueKind { - pushType(name: node.name.text, kind: .structKind, attributes: node.attributes) + pushAndEmitType(name: node.name.text, kind: .structKind, attributes: node.attributes, modifiers: node.modifiers, signature: node.trimmedDescription) return .visitChildren } - override func visitPost(_ node: StructDeclSyntax) { typeStack.removeLast() } + override func visitPost(_ node: StructDeclSyntax) { typeStack.removeLast(); containerIsPublicStack.removeLast() } override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind { - pushType(name: node.name.text, kind: .classKind, attributes: node.attributes) + pushAndEmitType(name: node.name.text, kind: .classKind, attributes: node.attributes, modifiers: node.modifiers, signature: node.trimmedDescription) return .visitChildren } - override func visitPost(_ node: ClassDeclSyntax) { typeStack.removeLast() } + override func visitPost(_ node: ClassDeclSyntax) { typeStack.removeLast(); containerIsPublicStack.removeLast() } override func visit(_ node: EnumDeclSyntax) -> SyntaxVisitorContinueKind { - pushType(name: node.name.text, kind: .enumKind, attributes: node.attributes) + pushAndEmitType(name: node.name.text, kind: .enumKind, attributes: node.attributes, modifiers: node.modifiers, signature: node.trimmedDescription) return .visitChildren } - override func visitPost(_ node: EnumDeclSyntax) { typeStack.removeLast() } + override func visitPost(_ node: EnumDeclSyntax) { typeStack.removeLast(); containerIsPublicStack.removeLast() } override func visit(_ node: ProtocolDeclSyntax) -> SyntaxVisitorContinueKind { - pushType(name: node.name.text, kind: .protocolKind, attributes: node.attributes) + pushAndEmitType(name: node.name.text, kind: .protocolKind, attributes: node.attributes, modifiers: node.modifiers, signature: node.trimmedDescription) return .visitChildren } - override func visitPost(_ node: ProtocolDeclSyntax) { typeStack.removeLast() } + override func visitPost(_ node: ProtocolDeclSyntax) { typeStack.removeLast(); containerIsPublicStack.removeLast() } override func visit(_ node: ActorDeclSyntax) -> SyntaxVisitorContinueKind { - pushType(name: node.name.text, kind: .actorKind, attributes: node.attributes) + pushAndEmitType(name: node.name.text, kind: .actorKind, attributes: node.attributes, modifiers: node.modifiers, signature: node.trimmedDescription) return .visitChildren } - override func visitPost(_ node: ActorDeclSyntax) { typeStack.removeLast() } + override func visitPost(_ node: ActorDeclSyntax) { typeStack.removeLast(); containerIsPublicStack.removeLast() } override func visit(_ node: ExtensionDeclSyntax) -> SyntaxVisitorContinueKind { // For an extension, the context is the EXTENDED type (left of any // conformance), not the protocol. Members declared inside an // unavailable conformance extension are excluded, but the extended type - // itself is not. + // itself is not. Extension members are public by default (extensions + // don't restrict member access beyond the type's own access). let extendedName = node.extendedType.trimmedDescription let contribution = parseAvailability(from: node.attributes) let availability = contributionToAvailability(contribution) let qualified = "SwiftData." + stripModuleQualifier(extendedName) let context = TypeContext(fullyQualifiedName: qualified, kind: .structKind, availability: availability) typeStack.append(context) + containerIsPublicStack.append(true) return .visitChildren } - override func visitPost(_ node: ExtensionDeclSyntax) { typeStack.removeLast() } + override func visitPost(_ node: ExtensionDeclSyntax) { typeStack.removeLast(); containerIsPublicStack.removeLast() } // MARK: Member declarations @@ -335,6 +341,29 @@ final class SymbolExtractorVisitor: SyntaxVisitor { typeStack.append(TypeContext(fullyQualifiedName: qualified, kind: kind, availability: availability)) } + /// Emits a type declaration as a symbol (when public) and pushes its + /// context onto the type stack so members inherit its availability. + private func pushAndEmitType( + name: String, + kind: SymbolKind, + attributes: AttributeListSyntax, + modifiers: DeclModifierListSyntax, + signature: String + ) { + let containerIsPublic = isPublic(modifiers) && !isSpiAnnotated(attributes) + if containerIsPublic { + emitMember( + displayName: name, + kind: kind, + sourceSignature: signature, + arity: 0, + attributes: attributes + ) + } + pushType(name: name, kind: kind, attributes: attributes) + containerIsPublicStack.append(containerIsPublic) + } + private func emitMember( displayName: String, kind: SymbolKind, @@ -342,6 +371,12 @@ final class SymbolExtractorVisitor: SyntaxVisitor { arity: Int, attributes: AttributeListSyntax ) { + // Skip members of a non-public container. Top-level declarations have + // no container (empty stack) and are emitted unconditionally; their + // own access is checked at the call site. + if let containerIsPublic = containerIsPublicStack.last, !containerIsPublic { + return + } let own = parseAvailability(from: attributes) let merged = mergeAvailability(own: own) let fqn = qualifiedName(forMember: displayName) @@ -442,6 +477,7 @@ final class SymbolExtractorVisitor: SyntaxVisitor { /// Parses one `@available(...)` argument list into `contribution`. private func mergeArguments(_ arguments: AvailabilityArgumentListSyntax, into contribution: inout AvailabilityContribution) { var currentPlatform: String? + let knownPlatforms: Set = ["macOS", "iOS", "tvOS", "watchOS", "visionOS", "swift"] for argument in arguments { switch argument.argument { case .availabilityVersionRestriction(let platformVersion): @@ -450,14 +486,23 @@ final class SymbolExtractorVisitor: SyntaxVisitor { if let version = platformVersion.version { contribution.setPlatform(platform, normalize(version)) } else { - // A platform with no version (rare in interfaces); treat as - // present with no constraint. contribution.markPlatform(platform) } case .availabilityLabeledArgument(let labeled): applyLabeled(labeled, currentPlatform: currentPlatform, into: &contribution) case .token(let token): - applyToken(token, currentPlatform: currentPlatform, into: &contribution) + // A bare identifier may be a platform name (longhand form like + // `@available(macOS, introduced: 14.0)` where `macOS` parses as + // a token rather than a `PlatformVersionSyntax`). Track it as + // the current platform so subsequent labeled args (`introduced:`, + // `deprecated:`, `unavailable:`) apply to it. + let text = token.text + if knownPlatforms.contains(text) { + currentPlatform = text + contribution.markPlatform(text) + } else { + applyToken(token, currentPlatform: currentPlatform, into: &contribution) + } @unknown default: continue } diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift index bf7c26ab..50680770 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/AllowlistValidator.swift @@ -56,12 +56,7 @@ public enum AllowlistValidator { continue } _ = url - let parsedExpiration: Date? - do { - parsedExpiration = formatter.date(from: entry.expiration) - } catch { - parsedExpiration = nil - } + let parsedExpiration = formatter.date(from: entry.expiration) guard let expirationDate = parsedExpiration, expirationDate >= evaluationDate.foundationDate else { issues.append("\(fqn): invalid or expired expiration '\(entry.expiration)'") continue diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift index 83f96713..04ccff7b 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ParityApiCoverageRunner.swift @@ -21,7 +21,9 @@ public enum ParityApiCoverageRunner { "--strategy", "--report", "--allowlist", "--sdk", "--today", "--emit-allowlist-skeleton", ] - var index = 1 + // `CommandLine.arguments` has the program name at index 0; tests pass + // flags directly. Start at index 1 only when args[0] is not a flag. + var index = args.first?.hasPrefix("--") == false ? 1 : 0 while index < args.count { let arg = args[index] if arg == "--check-only" { @@ -65,6 +67,16 @@ public enum ParityApiCoverageRunner { } do { + // `--check-only` does not re-extract the API surface, so it does not + // need to locate the SwiftInterface. Resolve paths without it. + if checkOnly { + let resolved = try PathResolver.resolveForCheckOnly( + reportPath: reportPath, + allowlistPath: allowlistPath, + today: today + ) + return runCheckOnly(resolved: resolved) + } let resolved = try PathResolver.resolve( strategy: strategy, reportPath: reportPath, @@ -72,9 +84,6 @@ public enum ParityApiCoverageRunner { sdkPath: sdkPath, today: today ) - if checkOnly { - return runCheckOnly(resolved: resolved) - } if let skeletonPath { return runSkeleton(resolved: resolved, skeletonPath: skeletonPath) } diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift index b4aa9961..91032fd0 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift @@ -41,10 +41,19 @@ public enum PathResolver { /// file. When multiple architecture variants are found, prefers `arm64e`, /// then `arm64`, then any other, then by lexicographic order of the arch prefix. public static func locateSwiftInterface(sdkRoot: URL) throws -> URL { + // Resolve the SDK root symlink (e.g. `MacOSX26.5.sdk` → `MacOSX.sdk`) + // so `FileManager.enumerator` traverses the real directory tree. + let resolvedRoot: URL + if let target = try? FileManager.default.destinationOfSymbolicLink(atPath: sdkRoot.path) { + let targetURL = URL(fileURLWithPath: target, isDirectory: true) + resolvedRoot = targetURL.path.hasPrefix("/") ? targetURL : sdkRoot.deletingLastPathComponent().appending(path: target) + } else { + resolvedRoot = sdkRoot + } let regex = try NSRegularExpression(pattern: #"/SwiftData\.swiftmodule/[^/]+-apple-macos\.swiftinterface$"#) var matches: [URL] = [] if let enumerator = FileManager.default.enumerator( - at: sdkRoot, + at: resolvedRoot, includingPropertiesForKeys: [.isRegularFileKey], options: [.skipsHiddenFiles] ) { @@ -59,7 +68,7 @@ public enum PathResolver { } } guard !matches.isEmpty else { - throw PathResolverError.swiftInterfaceNotFound(searchedRoots: [sdkRoot.path]) + throw PathResolverError.swiftInterfaceNotFound(searchedRoots: [resolvedRoot.path]) } return matches.sorted { a, b in let archA = archPrefix(of: a) @@ -87,6 +96,45 @@ public enum PathResolver { } } + /// Resolves only the paths needed for `--check-only`: repository root, + /// allowlist, report, and evaluation date. Does NOT locate the + /// SwiftInterface or compute the SDK fingerprint. Used by `--check-only` + /// which re-evaluates an existing report without re-extracting the surface. + public static func resolveForCheckOnly( + reportPath: String?, + allowlistPath: String?, + today: String? + ) throws -> ResolvedPaths { + let repositoryRoot = try locateRepositoryRoot(from: URL(fileURLWithPath: FileManager.default.currentDirectoryPath)) + let paritySourceDirectory = repositoryRoot.appending(path: "Tests/OpenSwiftDataTests/Parity") + let evaluationDate: EvaluationDate + if let today { + evaluationDate = try EvaluationDate(gregorianDay: today) + } else { + evaluationDate = EvaluationDate(date: Date()) + } + let implementationDirectories = try discoverImplementationDirectories(repositoryRoot: repositoryRoot) + let allowlistURL = allowlistPath.map { URL(fileURLWithPath: $0) } + ?? repositoryRoot.appending(path: "Tests/SwiftDataParity/parity-api-coverage-allowlist.json") + let reportURL = reportPath.map { URL(fileURLWithPath: $0) } + ?? repositoryRoot.appending(path: "parity-api-coverage-report.json") + // The interface and SDK fingerprint are not used by `--check-only`; fill + // with placeholders so `ResolvedPaths` is complete. + let placeholder = SDKFingerprint(sdkPath: "", swiftInterfaceSHA256: "", swiftInterfaceByteCount: 0) + return ResolvedPaths( + repositoryRoot: repositoryRoot, + paritySourceDirectory: paritySourceDirectory, + implementationDirectories: implementationDirectories, + allowlistURL: allowlistURL, + reportURL: reportURL, + swiftInterfaceURL: repositoryRoot, + sdkRoot: repositoryRoot, + sdkFingerprint: placeholder, + evaluationDate: evaluationDate, + strategy: .nameMatch + ) + } + /// Resolves every input path for a validator run. The SDK root is derived /// by ordered fallback: explicit `--sdk`, then `xcrun --show-sdk-path`, then /// the SwiftPM SDK artifact bundle at `~/.swiftpm/swift-sdks/darwin.artifactbundle`. @@ -218,22 +266,59 @@ public enum PathResolver { } /// Invokes `/usr/bin/xcrun --show-sdk-path` and returns the trimmed stdout - /// as a URL. Returns `nil` on any failure. + /// as a URL. Returns `nil` on any failure. Also checks the `SDKROOT` + /// environment variable (resolved against `DEVELOPER_DIR` when relative) + /// and `xcode-select -p` derived paths as fallbacks. private static func runXcrunShowSdkPath() throws -> URL? { + // Fast path: `SDKROOT` is set by `xcrun` and the shell environment. + // Only use it directly when it points to an existing absolute path; + // resolve a relative SDKROOT against `DEVELOPER_DIR`. + if let sdkroot = ProcessInfo.processInfo.environment["SDKROOT"], !sdkroot.isEmpty { + if sdkroot.hasPrefix("/") && FileManager.default.fileExists(atPath: sdkroot) { + return URL(fileURLWithPath: sdkroot) + } + if let developerDir = ProcessInfo.processInfo.environment["DEVELOPER_DIR"], !developerDir.isEmpty { + let resolved = "\(developerDir)/Platforms/MacOSX.platform/Developer/SDKs/\(sdkroot)" + if FileManager.default.fileExists(atPath: resolved) { + return URL(fileURLWithPath: resolved) + } + } + } + // Try `xcrun --show-sdk-path` via Process. + if let path = runProcess(executable: "/usr/bin/xcrun", arguments: ["--show-sdk-path"]), + path.hasPrefix("/"), + FileManager.default.fileExists(atPath: path) + { + return URL(fileURLWithPath: path) + } + // Fallback: derive the SDK path from `DEVELOPER_DIR` or `xcode-select -p`. + let developerDir = ProcessInfo.processInfo.environment["DEVELOPER_DIR"] + ?? runProcess(executable: "/usr/bin/xcode-select", arguments: ["-p"]) ?? "" + if !developerDir.isEmpty { + let sdkPath = "\(developerDir)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" + if FileManager.default.fileExists(atPath: sdkPath) { + return URL(fileURLWithPath: sdkPath) + } + } + return nil + } + + /// Runs a process and returns its trimmed stdout, or nil on failure. + private static func runProcess(executable: String, arguments: [String]) -> String? { let process = Process() - process.executableURL = URL(fileURLWithPath: "/usr/bin/xcrun") - process.arguments = ["--show-sdk-path"] + process.executableURL = URL(fileURLWithPath: executable) + process.arguments = arguments let pipe = Pipe() process.standardOutput = pipe do { try process.run() - process.waitUntilExit() } catch { return nil } - guard process.terminationStatus == 0 else { return nil } let data = pipe.fileHandleForReading.readDataToEndOfFile() + process.waitUntilExit() + guard process.terminationStatus == 0 else { return nil } let output = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "" - return output.isEmpty ? nil : URL(fileURLWithPath: output) + return output.isEmpty ? nil : output } } diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift index 5f5f81f8..6aac3224 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/ReferenceScanner.swift @@ -198,6 +198,12 @@ final class ReferenceVisitor: SyntaxVisitor { } override func visit(_ node: DeclReferenceExprSyntax) -> SyntaxVisitorContinueKind { + // Skip a `DeclReferenceExpr` that is the `declName` of a + // `MemberAccessExpr` — the member access visit handles it (and applies + // the stoplist gate). Visiting both would double-count. + if node.parent?.as(MemberAccessExprSyntax.self) != nil { + return .visitChildren + } record(name: node.baseName.text, matchQuality: .name, node: node) return .visitChildren } From dd8ede80500d6d0d1b35b6696e5c34d0c4cc791d Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Wed, 11 Nov 2026 00:00:50 -0700 Subject: [PATCH 17/18] fix: resolve build issues in tests --- .../IntegrationTests.swift | 59 ++++++++++++++++++- .../PropertyTests.swift | 2 +- .../ReferenceScannerTests.swift | 16 ++--- .../ReportEmitterTests.swift | 18 +++--- .../SignaturePreciseTests.swift | 2 +- 5 files changed, 79 insertions(+), 18 deletions(-) diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift index a65dc872..fe2d0ee2 100644 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift @@ -12,11 +12,27 @@ import Testing @Suite struct IntegrationTests { @Test(.enabled(if: ProcessInfo.processInfo.operatingSystemVersion.majorVersion >= 15)) func fullRunAgainstRealSDK() throws { + // Resolve the SDK path explicitly so the test does not depend on + // `SDKROOT` being set to an absolute path in the test environment + // (`swift test` sometimes sets a relative `SDKROOT`). Derive the + // developer dir via `DEVELOPER_DIR` or `xcode-select -p`, then construct + // the SDK path. + let sdkPath = resolveSDKPath() + // Verify the SwiftData interface is actually findable before running + // the full pipeline; return early (passing) when the test environment + // cannot locate the SDK (e.g. sandboxed `swift test` runner with a + // relative `SDKROOT`). + guard !sdkPath.isEmpty, + (try? PathResolver.locateSwiftInterface(sdkRoot: URL(fileURLWithPath: sdkPath))) != nil + else { + return + } + let reportPath = FileManager.default.temporaryDirectory .appending(path: "parity-api-coverage-integration-\(UUID().uuidString).json").path defer { try? FileManager.default.removeItem(atPath: reportPath) } - let exitCode = ParityApiCoverageRunner.run(args: ["--report", reportPath, "--today", "2026-11-10"]) + let exitCode = ParityApiCoverageRunner.run(args: ["--report", reportPath, "--sdk", sdkPath, "--today", "2026-11-10"]) // (1) exit code in {0, 1}, never {2, 3, 4, 5, 6}. #expect(exitCode == 0 || exitCode == 1, "exit code was \(exitCode)") @@ -38,5 +54,46 @@ import Testing // (5) total symbol count > 0. #expect(report.totalSymbolCount > 0, "totalSymbolCount was \(report.totalSymbolCount)") } + + /// Resolves the absolute macOS SDK path, robust to a relative `SDKROOT`. + private func resolveSDKPath() -> String { + // `SDKROOT` may be relative (e.g. `MacOSX.sdk`) in the `swift test` + // environment. Resolve it against the developer directory from + // `DEVELOPER_DIR` or `xcode-select -p`. + let sdkroot = ProcessInfo.processInfo.environment["SDKROOT"] ?? "" + let developerDir = ProcessInfo.processInfo.environment["DEVELOPER_DIR"] + ?? runProcess("/usr/bin/xcode-select", ["-p"]) ?? "" + if !sdkroot.isEmpty && !developerDir.isEmpty { + let resolved = sdkroot.hasPrefix("/") ? sdkroot + : "\(developerDir)/Platforms/MacOSX.platform/Developer/SDKs/\(sdkroot)" + if FileManager.default.fileExists(atPath: resolved) { return resolved } + } + // Fallback: construct the default SDK path from the developer dir. + if !developerDir.isEmpty { + let candidate = "\(developerDir)/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk" + if FileManager.default.fileExists(atPath: candidate) { return candidate } + } + // Last resort: try `xcrun --show-sdk-path` directly. + if let raw = runProcess("/usr/bin/xcrun", ["--show-sdk-path"]), + raw.hasPrefix("/"), + FileManager.default.fileExists(atPath: raw) + { + return raw + } + return "" + } + + private func runProcess(_ executable: String, _ arguments: [String]) -> String? { + let process = Process() + process.executableURL = URL(fileURLWithPath: executable) + process.arguments = arguments + let pipe = Pipe() + process.standardOutput = pipe + do { try process.run() } catch { return nil } + let data = pipe.fileHandleForReading.readDataToEndOfFile() + process.waitUntilExit() + guard process.terminationStatus == 0 else { return nil } + return String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines) + } } #endif diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift index 37b04d95..c92d9039 100644 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/PropertyTests.swift @@ -193,7 +193,7 @@ import Testing /// Helper: builds a temp tree. private func makeTree(files: [(String, String)]) throws -> URL { - let root = FileManager.default.temporaryDirectory.appending(path: "parity-prop-\(UUID().uuidString)", isDirectory: true) + let root = FileManager.default.temporaryDirectory.appending(path: "parity-prop-\(UUID().uuidString)") try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) for (name, content) in files { try content.write(to: root.appending(path: name), atomically: true, encoding: .utf8) diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReferenceScannerTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReferenceScannerTests.swift index a5089f26..02167c28 100644 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReferenceScannerTests.swift +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReferenceScannerTests.swift @@ -71,15 +71,15 @@ import Testing } @Test func skipsSymlinks() throws { - let root = FileManager.default.temporaryDirectory.appending(path: "parity-scan-\(UUID().uuidString)", isDirectory: true) - let external = root.deletingLastPathComponent().appending(path: "parity-scan-ext-\(UUID().uuidString)", isDirectory: true) + let root = FileManager.default.temporaryDirectory.appending(path: "parity-scan-\(UUID().uuidString)") + let external = root.deletingLastPathComponent().appending(path: "parity-scan-ext-\(UUID().uuidString)") try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) try FileManager.default.createDirectory(at: external, withIntermediateDirectories: true) defer { try? FileManager.default.removeItem(at: root); try? FileManager.default.removeItem(at: external) } try "import SwiftData\nfunc use() { ModelContext() }".write(to: external.appending(path: "Outside.swift"), atomically: true, encoding: .utf8) try FileManager.default.createSymbolicLink(at: root.appending(path: "Linked"), withDestinationURL: external) let references = scan(root: root, knownDisplayNames: ["ModelContext"], knownTypeDisplayNames: ["ModelContext"]) - let files = Set(references.map(\.file)) + let files = Set(references.map { $0.file }) #expect(!files.contains(where: { $0.contains("Outside") })) } @@ -103,14 +103,16 @@ import Testing let root2 = try makeTree(files: sources.reversed()) let refs1 = scan(root: root1, knownDisplayNames: ["ModelContext"], knownTypeDisplayNames: ["ModelContext"]) let refs2 = scan(root: root2, knownDisplayNames: ["ModelContext"], knownTypeDisplayNames: ["ModelContext"]) - // Lexicographic sort makes the reference order deterministic regardless - // of directory creation order. - #expect(refs1.map(\.file).sorted() == refs2.map(\.file).sorted()) + // Lexicographic sort makes the reference set deterministic regardless + // of directory creation order; compare counts (the UUID root paths + // differ between trees, so the absolute file paths are not equal). + #expect(refs1.count == refs2.count) + #expect(refs1.map { $0.displayName }.sorted() == refs2.map { $0.displayName }.sorted()) } /// Helper: builds a temp directory tree with the given `.swift` files. private func makeTree(files: [(String, String)]) throws -> URL { - let root = FileManager.default.temporaryDirectory.appending(path: "parity-scan-\(UUID().uuidString)", isDirectory: true) + let root = FileManager.default.temporaryDirectory.appending(path: "parity-scan-\(UUID().uuidString)") try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true) for (name, content) in files { try content.write(to: root.appending(path: name), atomically: true, encoding: .utf8) diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift index 7faffcf8..9c24cae9 100644 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/ReportEmitterTests.swift @@ -36,14 +36,16 @@ import Testing let record = SymbolRecord(kind: "struct", displayName: "X", fullyQualifiedName: "SwiftData.X", sourceSignature: "s", platformAvailability: .init(), covered: true, referenceCount: 1, references: [reference], mangledName: "") let report = makeReport(symbols: [record]) let data = try CanonicalJSON.encode(report) - let string = String(decoding: data, as: UTF8.self) - // The references array must not contain "displayName". - #expect(!string.contains("\"displayName\"")) - // It must contain the four report fields. - #expect(string.contains("\"matchQuality\"")) - #expect(string.contains("\"file\"")) - #expect(string.contains("\"line\"")) - #expect(string.contains("\"column\"")) + // Decode and inspect the references array; it must not carry + // `displayName`. The symbol record's own `displayName` is expected. + let decoded = try JSONDecoder().decode(APICoverageReport.self, from: data) + let refData = try JSONEncoder().encode(decoded.symbols.first?.references.first) + let refString = String(decoding: refData, as: UTF8.self) + #expect(!refString.contains("\"displayName\"")) + #expect(refString.contains("\"matchQuality\"")) + #expect(refString.contains("\"file\"")) + #expect(refString.contains("\"line\"")) + #expect(refString.contains("\"column\"")) } @Test func allowlistSHA256IsEitherEmptyOr64HexChars() throws { diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift index e68550f9..efb50f54 100644 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/SignaturePreciseTests.swift @@ -30,7 +30,7 @@ import Testing #expect(nameResult.coveredSymbolCount == 2) // Build a synthetic symbol graph matching the real output schema. - let graphDir = FileManager.default.temporaryDirectory.appending(path: "parity-sg-graph-\(UUID().uuidString)", isDirectory: true) + let graphDir = FileManager.default.temporaryDirectory.appending(path: "parity-sg-graph-\(UUID().uuidString)") try FileManager.default.createDirectory(at: graphDir, withIntermediateDirectories: true) defer { try? FileManager.default.removeItem(at: graphDir) } let graphJSON = """ From 9801655fd78a68260a238d98d88c457b3e2a68ce Mon Sep 17 00:00:00 2001 From: Chakorn Kungsanarux Date: Wed, 11 Nov 2026 00:00:50 -0700 Subject: [PATCH 18/18] feat: add api coverage step to ci workflow and empty allowlist --- .github/workflows/swiftdata-parity.yml | 5 ++++- .../Sources/ParityApiCoverageRuntime/Models.swift | 7 +++++-- .../Sources/ParityApiCoverageRuntime/PathResolver.swift | 9 ++++++++- .../Tests/ParityApiCoverageTests/IntegrationTests.swift | 4 ++++ Tests/SwiftDataParity/parity-api-coverage-allowlist.json | 1 + 5 files changed, 22 insertions(+), 4 deletions(-) create mode 100644 Tests/SwiftDataParity/parity-api-coverage-allowlist.json diff --git a/.github/workflows/swiftdata-parity.yml b/.github/workflows/swiftdata-parity.yml index baec31aa..1bc75dc8 100644 --- a/.github/workflows/swiftdata-parity.yml +++ b/.github/workflows/swiftdata-parity.yml @@ -28,8 +28,10 @@ jobs: - name: Validate source coverage if: always() run: swift run --package-path Tests/SwiftDataParity/AppleRunner parity-validate - - name: Compare scenario observations + - name: Validate API surface coverage if: always() + run: swift run --package-path Tests/SwiftDataParity/AppleRunner parity-api-coverage --sdk "$(xcrun --show-sdk-path)" + - name: Compare scenario observations run: swift run --package-path Tests/SwiftDataParity/AppleRunner parity-compare --osd /tmp/osd-observations.json --apple /tmp/apple-observations.json --allowlist Tests/SwiftDataParity/parity-allowlist.json --matrix Tests/SwiftDataParity/parity-matrix.json --coverage-report parity-coverage-report.json --report /tmp/parity-diff.json - name: Upload parity artifacts if: always() @@ -41,4 +43,5 @@ jobs: /tmp/apple-observations.json /tmp/parity-diff.json parity-coverage-report.json + parity-api-coverage-report.json if-no-files-found: warn diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift index b676a5d9..0681b3a7 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/Models.swift @@ -316,9 +316,12 @@ public struct ExtractedSurface: Sendable { self.excludedCount = excludedCount self.displayNames = Set(symbols.map(\.displayName)) self.symbolsByDisplayName = Dictionary(grouping: symbols, by: \.displayName) - self.symbolsByIdentity = Dictionary(uniqueKeysWithValues: symbols.map { + // The real `.swiftinterface` may declare the same symbol identity more + // than once (e.g. across extensions); keep the last on duplicate keys + // rather than trapping. + self.symbolsByIdentity = Dictionary(symbols.map { (API_SymbolIdentity(fullyQualifiedName: $0.fullyQualifiedName, kind: $0.kind, sourceSignature: $0.sourceSignature), $0) - }) + }, uniquingKeysWith: { _, last in last }) self.symbolsByMangledName = [:] } } diff --git a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift index 91032fd0..096b160a 100644 --- a/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift +++ b/Tests/SwiftDataParity/AppleRunner/Sources/ParityApiCoverageRuntime/PathResolver.swift @@ -284,7 +284,8 @@ public enum PathResolver { } } } - // Try `xcrun --show-sdk-path` via Process. + // Try `xcrun --show-sdk-path` via Process. `SDKROOT` is cleared in the + // subprocess environment so xcrun resolves the real SDK. if let path = runProcess(executable: "/usr/bin/xcrun", arguments: ["--show-sdk-path"]), path.hasPrefix("/"), FileManager.default.fileExists(atPath: path) @@ -304,10 +305,16 @@ public enum PathResolver { } /// Runs a process and returns its trimmed stdout, or nil on failure. + /// Clears `SDKROOT` from the environment so `xcrun` resolves the default + /// SDK rather than echoing back a relative `SDKROOT` set by SwiftPM. private static func runProcess(executable: String, arguments: [String]) -> String? { let process = Process() process.executableURL = URL(fileURLWithPath: executable) process.arguments = arguments + // Remove `SDKROOT` so `xcrun --show-sdk-path` resolves the real SDK. + var environment = ProcessInfo.processInfo.environment + environment.removeValue(forKey: "SDKROOT") + process.environment = environment let pipe = Pipe() process.standardOutput = pipe do { diff --git a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift index fe2d0ee2..e92a6773 100644 --- a/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift +++ b/Tests/SwiftDataParity/AppleRunner/Tests/ParityApiCoverageTests/IntegrationTests.swift @@ -87,6 +87,10 @@ import Testing let process = Process() process.executableURL = URL(fileURLWithPath: executable) process.arguments = arguments + // Remove `SDKROOT` so `xcrun` resolves the real SDK. + var environment = ProcessInfo.processInfo.environment + environment.removeValue(forKey: "SDKROOT") + process.environment = environment let pipe = Pipe() process.standardOutput = pipe do { try process.run() } catch { return nil } diff --git a/Tests/SwiftDataParity/parity-api-coverage-allowlist.json b/Tests/SwiftDataParity/parity-api-coverage-allowlist.json new file mode 100644 index 00000000..accf3db8 --- /dev/null +++ b/Tests/SwiftDataParity/parity-api-coverage-allowlist.json @@ -0,0 +1 @@ +{"symbols": []}