Add verify-config-schema command to sourcekit-lsp-dev-utils

Author: kateinoigakukun

SourceKitLSPDevUtils/Sources/ConfigSchemaGen/ConfigSchemaGen.swift

@@ -19,6 +19,16 @@ import SwiftSyntax
 /// (`.sourcekit-lsp/config.json`) from the Swift type definitions in
 /// `SKOptions` Swift module.
 public struct ConfigSchemaGen {
+  public struct WritePlan {
+    public let category: String
+    public let path: URL
+    public let contents: () throws -> Data
+
+    public func write() throws {
+      try contents().write(to: path)
+    }
+  }
+
   static let projectRoot = URL(fileURLWithPath: #filePath)
     .deletingLastPathComponent()
     .deletingLastPathComponent()
@@ -37,6 +47,14 @@ public struct ConfigSchemaGen {
     .appendingPathComponent("Configuration File.md")
 
   public static func generate() throws {
+    let plans = try plan()
+    for plan in plans {
+      print("Writing \(plan.category) to \"\(plan.path.path)\"")
+      try plan.write()
+    }
+  }
+
+  public static func plan() throws -> [WritePlan] {
     let sourceFiles = FileManager.default.enumerator(at: sourceDir, includingPropertiesForKeys: nil)!
     let typeNameResolver = TypeDeclResolver()
 
@@ -71,15 +89,20 @@ public struct ConfigSchemaGen {
       )
     )
 
-    print("Writing schema to \(configSchemaJSONPath.path)")
-    try generateJSONSchema(from: schema, context: context).write(to: configSchemaJSONPath)
+    var plans: [WritePlan] = []
 
-    print("Writing schema documentation to \(configSchemaDocPath.path)")
-    try generateDocumentation(from: schema, context: context).write(
-      to: configSchemaDocPath,
-      atomically: true,
-      encoding: .utf8
-    )
+    plans.append(WritePlan(
+      category: "JSON Schema",
+      path: configSchemaJSONPath,
+      contents: { try generateJSONSchema(from: schema, context: context) }
+    ))
+
+    plans.append(WritePlan(
+      category: "Schema Documentation",
+      path: configSchemaDocPath,
+      contents: { try generateDocumentation(from: schema, context: context) }
+    ))
+    return plans
   }
 
   static func generateJSONSchema(from schema: OptionTypeSchama, context: OptionSchemaContext) throws -> Data {
@@ -92,8 +115,22 @@ public struct ConfigSchemaGen {
     return try encoder.encode(jsonSchema)
   }
 
-  static func generateDocumentation(from schema: OptionTypeSchama, context: OptionSchemaContext) throws -> String {
+  static func generateDocumentation(from schema: OptionTypeSchama, context: OptionSchemaContext) throws -> Data {
     let docBuilder = OptionDocumentBuilder(context: context)
-    return try docBuilder.build(from: schema)
+    guard let data = try docBuilder.build(from: schema).data(using: .utf8) else {
+      throw ConfigSchemaGenError.documentationEncodingFailed
+    }
+    return data
+  }
+}
+
+enum ConfigSchemaGenError: Error, CustomStringConvertible {
+  case documentationEncodingFailed
+
+  var description: String {
+    switch self {
+    case .documentationEncodingFailed:
+      return "Failed to encode documentation as UTF-8"
+    }
   }
 }

SourceKitLSPDevUtils/Sources/SourceKitLSPDevUtils/Commands/GenerateConfigSchema.swift

@@ -15,7 +15,6 @@ import ConfigSchemaGen
 
 struct GenerateConfigSchema: ParsableCommand {
     static let configuration = CommandConfiguration(
-        commandName: "generate-config-schema",
         abstract: "Generate a JSON schema and documentation for the SourceKit-LSP configuration file"
     )
 

SourceKitLSPDevUtils/Sources/SourceKitLSPDevUtils/Commands/VerifyConfigSchema.swift

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+import ConfigSchemaGen
+import Foundation
+
+struct VerifyConfigSchema: ParsableCommand {
+    static let configuration = CommandConfiguration(
+        abstract: "Verify that the generated JSON schema and documentation for the SourceKit-LSP configuration file are up-to-date"
+    )
+
+    func run() throws {
+        let plans = try ConfigSchemaGen.plan()
+        for plan in plans {
+            print("Verifying \(plan.category) at \"\(plan.path.path)\"")
+            let expectedContents = try plan.contents()
+            let actualContents = try Data(contentsOf: plan.path)
+            guard expectedContents == actualContents else {
+                print("FATAL: \(plan.category) is out-of-date!")
+                print("Please run `./sourcekit-lsp-dev-utils generate-config-schema` to update it.")
+                throw ExitCode.failure
+            }
+        }
+        print("All schemas are up-to-date!")
+    }
+}

SourceKitLSPDevUtils/Sources/SourceKitLSPDevUtils/SourceKitLSPDevUtils.swift

@@ -19,6 +19,7 @@ struct SourceKitLSPDevUtils: ParsableCommand {
         abstract: "Utilities for developing SourceKit-LSP",
         subcommands: [
             GenerateConfigSchema.self,
+            VerifyConfigSchema.self,
         ]
     )
 }