Add override comment command

ileitch · ileitch · commit 8c99cf30d5c0 · 2025-04-22T13:37:08.000+02:00
diff --git a/Sources/PeripheryKit/Results/CodeClimateFormatter.swift b/Sources/PeripheryKit/Results/CodeClimateFormatter.swift
@@ -14,35 +14,27 @@ final class CodeClimateFormatter: OutputFormatter {
         var jsonObject: [Any] = []
 
         for result in results {
+            let location = declarationLocation(from: result.declaration)
+
             let lines: [AnyHashable: Any] = [
-                "begin": result.declaration.location.line,
+                "begin": location.line,
             ]
 
-            let location: [AnyHashable: Any] = [
-                "path": outputPath(result.declaration.location).url.relativePath,
+            let locationDict: [AnyHashable: Any] = [
+                "path": outputPath(location).url.relativePath,
                 "lines": lines,
             ]
 
             let description = describe(result, colored: colored)
                 .map(\.1)
                 .joined(separator: ", ")
-
-            let fingerprint: String = if result.declaration.kind == .varParameter,
-                                         let parentFingerprint = result.declaration.parent?.usrs.sorted().joined(separator: "."),
-                                         let argumentName = result.declaration.name
-            {
-                // As function parameters do not have a mangled name that can be used for the fingerprint
-                // we take the mangled name of the function and append the position
-                "\(parentFingerprint)-\(argumentName)"
-            } else {
-                result.declaration.usrs.sorted().joined(separator: ".")
-            }
+            let fingerprint = result.declaration.usrs.sorted().joined(separator: ".")
 
             let object: [AnyHashable: Any] = [
                 "description": description,
                 "fingerprint": fingerprint,
                 "severity": "major",
-                "location": location,
+                "location": locationDict,
             ]
 
             jsonObject.append(object)
diff --git a/Sources/PeripheryKit/Results/CsvFormatter.swift b/Sources/PeripheryKit/Results/CsvFormatter.swift
@@ -16,13 +16,13 @@ final class CsvFormatter: OutputFormatter {
 
         for result in results {
             let line = format(
-                kind: result.declaration.kind.rawValue,
+                kind: declarationKind(from: result.declaration),
                 name: result.declaration.name,
                 modifiers: result.declaration.modifiers,
                 attributes: result.declaration.attributes,
                 accessibility: result.declaration.accessibility.value.rawValue,
                 usrs: result.declaration.usrs,
-                location: result.declaration.location,
+                location: declarationLocation(from: result.declaration),
                 hint: describe(result.annotation)
             )
             lines.append(line)
diff --git a/Sources/PeripheryKit/Results/JsonFormatter.swift b/Sources/PeripheryKit/Results/JsonFormatter.swift
@@ -14,16 +14,17 @@ final class JsonFormatter: OutputFormatter {
         var jsonObject: [Any] = []
 
         for result in results {
+            let location = declarationLocation(from: result.declaration)
             let object: [AnyHashable: Any] = [
-                "kind": result.declaration.kind.rawValue,
-                "modules": result.declaration.location.file.modules.sorted(),
+                "kind": declarationKind(from: result.declaration),
+                "modules": location.file.modules.sorted(),
                 "name": result.declaration.name ?? "",
                 "modifiers": result.declaration.modifiers.sorted(),
                 "attributes": result.declaration.attributes.sorted(),
                 "accessibility": result.declaration.accessibility.value.rawValue,
                 "ids": result.declaration.usrs.sorted(),
                 "hints": [describe(result.annotation)],
-                "location": locationDescription(result.declaration.location),
+                "location": locationDescription(location),
             ]
             jsonObject.append(object)
 
diff --git a/Sources/PeripheryKit/Results/OutputDeclarationFilter.swift b/Sources/PeripheryKit/Results/OutputDeclarationFilter.swift
@@ -43,19 +43,36 @@ public final class OutputDeclarationFilter {
 
         return declarations
             .filter { [contextualLogger] in
-                let path = $0.declaration.location.file.path
+                var path = $0.declaration.location.file.path
+
+                // If the declaration has a location override, use it as the path for filtering.
+                for command in $0.declaration.commentCommands {
+                    switch command {
+                    case let .override(overrides):
+                        for override in overrides {
+                            switch override {
+                            case let .location(location):
+                                path = location.file.path
+                            default:
+                                break
+                            }
+                        }
+                    default:
+                        break
+                    }
+                }
 
                 if configuration.reportIncludeMatchers.isEmpty {
                     if configuration.reportExcludeMatchers.anyMatch(filename: path.string) {
-                        contextualLogger.debug("Excluding \(path.string)")
+                        contextualLogger.debug("Excluding \(path)")
                         return false
                     }
 
                     return true
                 }
 
                 if configuration.reportIncludeMatchers.anyMatch(filename: path.string) {
-                    contextualLogger.debug("Including \(path.string)")
+                    contextualLogger.debug("Including \(path)")
                     return true
                 }
 
diff --git a/Sources/PeripheryKit/Results/OutputFormatter.swift b/Sources/PeripheryKit/Results/OutputFormatter.swift
@@ -38,13 +38,11 @@ extension OutputFormatter {
     func describe(_ result: ScanResult, colored: Bool) -> [(Location, String)] {
         var description = ""
         var secondaryResults: [(Location, String)] = []
+        let location = declarationLocation(from: result.declaration)
+        let kindDisplayName = declarationKindDisplayName(from: result.declaration)
 
         if var name = result.declaration.name {
-            if let kind = result.declaration.kind.displayName, let first_ = kind.first {
-                let first = String(first_)
-                description += "\(first.uppercased())\(kind.dropFirst()) "
-            }
-
+            description += "\(kindDisplayName.first?.uppercased() ?? "")\(kindDisplayName.dropFirst()) "
             name = colored ? Logger.colorize(name, .lightBlue) : name
             description += "'\(name)'"
 
@@ -72,14 +70,14 @@ extension OutputFormatter {
             description += "unused"
         }
 
-        return [(result.declaration.location, description)] + secondaryResults
+        return [(location, description)] + secondaryResults
     }
 
     func outputPath(_ location: Location) -> FilePath {
         var path = location.file.path.lexicallyNormalized()
 
-        if configuration.relativeResults {
-            path = path.relativeTo(currentFilePath)
+        if configuration.relativeResults, path.isAbsolute {
+            path = path.relativeTo(currentFilePath).removingRoot()
         }
 
         return path
@@ -93,6 +91,72 @@ extension OutputFormatter {
         ]
         .joined(separator: ":")
     }
+
+    func declarationKind(from declaration: Declaration) -> String {
+        var kind = declaration.kind.rawValue
+
+        for command in declaration.commentCommands {
+            switch command {
+            case let .override(overrides):
+                for override in overrides {
+                    switch override {
+                    case let .kind(overrideKind):
+                        kind = overrideKind
+                    default:
+                        break
+                    }
+                }
+            default:
+                break
+            }
+        }
+
+        return kind
+    }
+
+    func declarationKindDisplayName(from declaration: Declaration) -> String {
+        var kind = declaration.kind.displayName
+
+        for command in declaration.commentCommands {
+            switch command {
+            case let .override(overrides):
+                for override in overrides {
+                    switch override {
+                    case let .kind(overrideKind):
+                        kind = overrideKind
+                    default:
+                        break
+                    }
+                }
+            default:
+                break
+            }
+        }
+
+        return kind
+    }
+
+    func declarationLocation(from declaration: Declaration) -> Location {
+        var location = declaration.location
+
+        for command in declaration.commentCommands {
+            switch command {
+            case let .override(overrides):
+                for override in overrides {
+                    switch override {
+                    case let .location(overrideLocation):
+                        location = overrideLocation
+                    default:
+                        break
+                    }
+                }
+            default:
+                break
+            }
+        }
+
+        return location
+    }
 }
 
 public extension OutputFormat {
diff --git a/Sources/PeripheryKit/Results/XcodeFormatter.swift b/Sources/PeripheryKit/Results/XcodeFormatter.swift
@@ -29,14 +29,19 @@ final class XcodeFormatter: OutputFormatter {
 
     private func prefix(for location: Location, colored: Bool) -> String {
         let path = outputPath(location)
-        let dir = path.removingLastComponent()
+        var dir = path.removingLastComponent().string
+
+        if !dir.isEmpty {
+            dir += "/"
+        }
+
         let file = colorize(path.lastComponent?.stem ?? "", .bold, colored: colored)
         let ext = path.extension ?? "swift"
         let lineNum = colorize(String(location.line), .bold, colored: colored)
         let column = location.column
         let warning = colorize("warning:", .boldYellow, colored: colored)
 
-        return "\(dir)/\(file).\(ext):\(lineNum):\(column): \(warning) "
+        return "\(dir)\(file).\(ext):\(lineNum):\(column): \(warning) "
     }
 
     private func colorize(_ text: String, _ color: ANSIColor, colored: Bool) -> String {
diff --git a/Sources/SourceGraph/Elements/CommentCommand.swift b/Sources/SourceGraph/Elements/CommentCommand.swift
@@ -1,9 +1,24 @@
 import Foundation
 
 public enum CommentCommand: CustomStringConvertible, Hashable {
+    public enum Override: CustomStringConvertible, Hashable {
+        case location(Location)
+        case kind(String)
+
+        public var description: String {
+            switch self {
+            case let .location(location):
+                "location=\"\(location.file.path):\(location.line):\(location.column)\""
+            case let .kind(kind):
+                "kind=\"\(kind)\""
+            }
+        }
+    }
+
     case ignore
     case ignoreAll
     case ignoreParameters([String])
+    case override([Override])
 
     public var description: String {
         switch self {
@@ -14,6 +29,9 @@ public enum CommentCommand: CustomStringConvertible, Hashable {
         case let .ignoreParameters(params):
             let formattedParams = params.sorted().joined(separator: ",")
             return "ignore:parameters \(formattedParams)"
+        case let .override(overrides):
+            let formattedOverrides = overrides.map(\.description).joined(separator: " ")
+            return "override \(formattedOverrides)"
         }
     }
 }
diff --git a/Sources/SourceGraph/Elements/Declaration.swift b/Sources/SourceGraph/Elements/Declaration.swift
@@ -176,7 +176,7 @@ public final class Declaration {
             [.class, .struct, .enum]
         }
 
-        public var displayName: String? {
+        public var displayName: String {
             switch self {
             case .module:
                 "imported module"
@@ -198,16 +198,18 @@ public final class Declaration {
                 "initializer"
             case .extension, .extensionEnum, .extensionClass, .extensionStruct, .extensionProtocol:
                 "extension"
-            case .functionMethodClass, .functionMethodStatic, .functionMethodInstance, .functionFree, .functionOperator, .functionOperatorInfix, .functionOperatorPostfix, .functionOperatorPrefix, .functionSubscript:
+            case .functionMethodClass, .functionMethodStatic, .functionMethodInstance, .functionFree, .functionOperator, .functionOperatorInfix, .functionOperatorPostfix, .functionOperatorPrefix, .functionSubscript, .functionAccessorAddress, .functionAccessorMutableaddress, .functionAccessorDidset, .functionAccessorGetter, .functionAccessorSetter, .functionAccessorWillset, .functionAccessorRead, .functionAccessorModify, .functionAccessorInit, .functionDestructor:
                 "function"
             case .varStatic, .varInstance, .varClass, .varGlobal, .varLocal:
                 "property"
             case .varParameter:
                 "parameter"
             case .genericTypeParam:
                 "generic type parameter"
-            default:
-                nil
+            case .precedenceGroup:
+                "precedence group"
+            case .macro:
+                "macro"
             }
         }
     }
diff --git a/Sources/SyntaxAnalysis/CommentCommand.swift b/Sources/SyntaxAnalysis/CommentCommand.swift
@@ -1,5 +1,6 @@
 import SourceGraph
 import SwiftSyntax
+import SystemPackage
 
 extension CommentCommand {
     static func parseCommands(in trivia: Trivia?) -> [CommentCommand] {
@@ -33,6 +34,38 @@ extension CommentCommand {
         } else if rawCommand.hasPrefix("ignore:parameters") {
             guard let params = rawCommand.split(separator: " ").last?.split(separator: ",").map({ String($0).trimmed }) else { return nil }
             return .ignoreParameters(params)
+        } else if rawCommand.hasPrefix("override") {
+            let pattern = #/(?<key>\w+)="(?<value>[^"]*)"/#
+            var params: [String: String] = [:]
+
+            for match in rawCommand.matches(of: pattern) {
+                let key = String(match.output.key)
+                let value = String(match.output.value)
+                params[key] = value
+            }
+
+            var overrides = [Override]()
+
+            for (key, value) in params {
+                switch key {
+                case "location":
+                    let parts = value.split(separator: ":")
+                    guard let file = parts[safe: 0] else { break }
+
+                    let line = Int(parts[safe: 1] ?? "1") ?? 1
+                    let column = Int(parts[safe: 2] ?? "1") ?? 1
+                    let sourceFile = SourceFile(path: FilePath(String(file)), modules: [])
+                    let location = Location(file: sourceFile, line: line, column: column)
+
+                    overrides.append(.location(location))
+                case "kind":
+                    overrides.append(.kind(value))
+                default:
+                    break
+                }
+            }
+
+            return .override(overrides)
         }
 
         return nil
