add DocC documentation comments across the codebase, standardize on grouped parameter form (uai-w96)

Author: Jason-Abbott

.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
     - uses: actions/checkout@v4
 
     - name: Select Xcode version
-      run: sudo xcode-select -s /Applications/Xcode_16.2.app/Contents/Developer
+      run: sudo xcode-select -s /Applications/Xcode_26.3.app/Contents/Developer
 
     - name: Build release binary
       run: swift build -c release --disable-sandbox

.issues/c/cms-fc6--extend-xcode-source-editor-extension-with-swiftfor.md

@@ -0,0 +1,65 @@
+---
+# cms-fc6
+title: Extend Xcode Source Editor Extension with SwiftFormat-inspired features
+status: in-progress
+type: feature
+priority: normal
+created_at: 2026-03-01T17:48:45Z
+updated_at: 2026-03-01T18:03:11Z
+sync:
+    github:
+        issue_number: "123"
+        synced_at: "2026-03-01T18:21:06Z"
+---
+
+## Context
+
+The Swiftiomatic Xcode Source Editor Extension (under `Xcode/`) currently has minimal stub implementations. SwiftFormat's [EditorExtension](https://github.com/nicklockwood/SwiftFormat/tree/main/EditorExtension) provides a mature reference with features we should adopt, adapted to Swiftiomatic's AST-based rule engine and modernized for Swift 6.2.
+
+### Current State
+
+- **SourceEditorExtension.swift** — empty principal class
+- **FormatFileCommand.swift** — basic format-entire-buffer, no content-type validation, no selection preservation, no early-exit on unchanged content
+- **FormatSelectionCommand.swift** — basic range formatting, no content-type validation, naive line splitting
+- **AppDelegate.swift** — empty LSUIElement host app
+- **PublicAPI.swift** — single \`SwiftiomaticLib.format(_:)\` entry point
+
+### What SwiftFormat Does Well (to adopt)
+
+1. **Content-type validation** — checks \`SupportedContentUTIs\` before processing (Swift source, playgrounds, package manifests)
+2. **Typed command errors** — \`FormatCommandError\` enum with \`LocalizedError\` + \`CustomNSError\` conformance for user-facing messages
+3. **Selection preservation** — removes selections before buffer mutation to prevent Xcode crashes, restores at new positions using token-based offset calculation
+4. **Lint File command** — surfaces lint warnings directly in the extension
+5. **Buffer helper extension** — \`XCSourceTextBuffer+\` for indentation detection and position/offset conversion
+6. **App group UserDefaults** — shared storage between host app and extension for rules/options
+7. **Host app UI** — rules browser, options editor with table views for toggling rules on/off
+
+## Tasks
+
+- [ ] Add \`SupportedContentUTIs\` — array of UTIs the extension should handle (\`public.swift-source\`, \`com.apple.dt.playground\`, \`com.apple.dt.playgroundpage\`, \`com.apple.dt.swiftpm-package-manifest\`)
+- [ ] Add \`FormatCommandError\` enum — \`.notSwiftLanguage\`, \`.noSelection\`, \`.invalidSelection\`, \`.lintWarnings([Diagnostic])\` with \`LocalizedError\` conformance. Use Swift 6.2 typed throws where applicable
+- [ ] Add \`XCSourceTextBuffer+Swiftiomatic\` extension — content-type validation helper, indentation string detection, position/offset conversion
+- [ ] Rewrite \`FormatFileCommand\` — validate content type, preserve/restore selections around buffer mutation, early-exit on no changes, proper error handling with \`FormatCommandError\`
+- [ ] Rewrite \`FormatSelectionCommand\` — validate content type + selection exists, selection-aware formatting, restore selection at new positions
+- [ ] Add \`LintFileCommand\` — new command that runs lint-scope rules and reports findings as a user-facing error summary. Register in Info.plist
+- [ ] Expand \`PublicAPI.swift\` — add \`SwiftiomaticLib.lint(_:)\` returning diagnostics, so the extension can use it
+- [ ] Update \`Info.plist\` — register \`LintFileCommand\` as third command (\`com.toba.swiftiomatic.extension.lint-file\`, "Lint File")
+- [ ] Update \`SourceEditorExtension\` — implement \`extensionDidFinishLaunching()\` if needed for initialization
+- [ ] Add App Group entitlements — shared \`UserDefaults\` suite for future settings sync between host app and extension
+- [ ] All new code must be Swift 6.2 strict concurrency, \`Sendable\` where needed, no warnings
+
+## Modernization Requirements (Swift 6.2 / swift-review)
+
+- Use typed throws (\`throws(FormatCommandError)\`) where the error type is known
+- Mark types \`@Sendable\` or conform to \`Sendable\` as needed for XPC extension context
+- Prefer \`sending\` parameter annotations if passing data across isolation boundaries
+- Use \`nonisolated(unsafe)\` only as a last resort — prefer proper sendability
+- No \`@objc\` unless required by XcodeKit protocol conformance
+- Use \`if let\`/\`guard let\` shorthand (no redundant \`= variable\`)
+- Prefer \`for-in\` with indices over manual counter loops
+
+## Non-Goals (for now)
+
+- Host app UI for toggling rules/options (future task)
+- App group UserDefaults stores (future task — depends on host app UI)
+- Storyboard / SwiftUI settings interface

.issues/u/uai-w96--add-docc-documentation-comments-across-the-codebas.md

@@ -0,0 +1,62 @@
+---
+# uai-w96
+title: Add DocC documentation comments across the codebase
+status: completed
+type: task
+priority: normal
+created_at: 2026-03-01T18:02:49Z
+updated_at: 2026-03-01T18:20:48Z
+sync:
+    github:
+        issue_number: "124"
+        synced_at: "2026-03-01T18:21:07Z"
+---
+
+Add documentation comments to all public and internal types throughout the Swiftiomatic codebase. Standardize on short-form parameter documentation. Work section-by-section starting with foundational layers.
+
+## Plan
+
+Work through layers bottom-up so each layer's docs can reference already-documented types:
+
+### Phase 1: Extensions (foundation utilities)
+- [x] Extensions/ — String, Collection, SwiftSyntax helpers
+
+### Phase 2: SourceKit layer
+- [x] SourceKit/ — C bindings, type system enums, resolvers
+
+### Phase 3: Support infrastructure  
+- [x] Support/ root — Console, file discovery, glob, diagnostics
+- [x] Support/Detectors/ — Pattern detectors
+- [x] Support/Visitors/ — AST visitors
+
+### Phase 4: Format engine
+- [x] Format/ — Token, Tokenizer, Formatter, FormatOptions, FormatRule
+
+### Phase 5: Rules infrastructure
+- [x] Rules/ base protocols — Rule, ASTRule, CollectingRule
+- [x] Rules/ category directories — top-level category docs
+
+### Phase 6: Analysis & Public API
+- [x] Suggest/ — Analyzer, TextFormatter (no changes needed)
+- [x] PublicAPI.swift (no changes needed)
+
+## Style Guide
+- Use grouped parameter form: `- Parameters:` with `  - name: Description.`
+- Summary line is a single sentence fragment (no period)
+- Add `## Discussion` only when non-obvious
+- Link related types with ```TypeName``` syntax
+- Do NOT add docs to trivial computed properties or obvious enum cases
+
+
+## Summary of Changes
+
+Documented ~130 files across all layers of the codebase:
+- **Extensions/** (35 files): Added DocC comments to all utility extensions, converted parameter style
+- **SourceKit/** (31 files): Documented all SourceKit bindings, types, and resolvers
+- **Support/** (29 files): Documented root utilities, detectors, and visitors
+- **Format/** (19 files): Documented formatter, tokenizer, options, and rules infrastructure
+- **Rules/** (14 root files) + **Configuration/** (8 files): Converted parameter style, added docs to undocumented types
+- **Models/** (16 files): Converted all parameter docs to grouped form
+- **Suggest/** + **PublicAPI.swift**: Already properly documented, no changes needed
+
+All parameters now use the grouped `- Parameters:` form. Summaries are sentence fragments without trailing periods. Discussion sections added only where non-obvious.

Sources/Swiftiomatic/Configuration/ConfigValue.swift

@@ -1,16 +1,25 @@
-/// A `Sendable` wrapper for untyped YAML configuration values.
+/// A `Sendable` wrapper for untyped YAML configuration values
 ///
 /// Replaces `[String: Any]` in configuration properties where `Sendable` conformance
 /// is required. Converts to/from `Any` at system boundaries (YAML parsing, rule init).
-package enum ConfigValue: Sendable, Equatable {
+public enum ConfigValue: Sendable, Equatable {
+    /// A string value
     case string(String)
+    /// An integer value
     case int(Int)
+    /// A double-precision floating-point value
     case double(Double)
+    /// A boolean value
     case bool(Bool)
+    /// An ordered list of ``ConfigValue`` elements
     case array([ConfigValue])
+    /// A keyed dictionary of ``ConfigValue`` entries
     case dictionary([String: ConfigValue])
 
-    /// Creates a `ConfigValue` from an untyped value, returning `nil` if the type isn't representable.
+    /// Create a ``ConfigValue`` from an untyped value, returning `nil` if the type isn't representable
+    ///
+    /// - Parameters:
+    ///   - any: The untyped value to wrap.
     init?(_ any: Any) {
         switch any {
             case let value as String: self = .string(value)
@@ -25,7 +34,7 @@ package enum ConfigValue: Sendable, Equatable {
         }
     }
 
-    /// Converts back to an untyped value for passing to `Rule.init(configuration:)`.
+    /// Convert back to an untyped value for passing to ``Rule/init(configuration:)``
     var asAny: Any {
         switch self {
             case let .string(v): v

Sources/Swiftiomatic/Configuration/Configuration+Cache.swift

@@ -3,7 +3,7 @@ import Foundation
 extension Configuration {
     // MARK: On-Disk Cache
 
-    /// A SHA-256 fingerprint of this configuration's root directory and rule settings.
+    /// A SHA-256 fingerprint of this configuration's root directory and rule settings
     ///
     /// ``LinterCache`` uses this as a cache key: lint results for a file are only valid
     /// when produced under the same configuration fingerprint. Changing any rule or its
@@ -19,7 +19,7 @@ extension Configuration {
         return data.sha256().hexString
     }
 
-    /// The directory where ``LinterCache`` stores its per-file violation caches.
+    /// The directory where ``LinterCache`` stores its per-file violation caches
     ///
     /// Resolves to `<cachePath>/Swiftiomatic/<version>/<buildID>/`, falling back to
     /// `~/Library/Caches/` when no custom ``cachePath`` is set.
@@ -40,7 +40,7 @@ extension Configuration {
         return baseURL.appendingPathComponent(versionedDirectory)
     }
 
-    /// Creates the cache directory at ``cacheURL`` if it doesn't already exist.
+    /// Create the cache directory at ``cacheURL`` if it doesn't already exist
     func prepareCacheDirectory() {
         do {
             try FileManager.default.createDirectory(

Sources/Swiftiomatic/Configuration/Configuration+IndentationStyle.swift

@@ -1,17 +1,18 @@
 extension Configuration {
-    /// The style of indentation used in a Swift project.
+    /// The style of indentation used in a Swift project
     package enum IndentationStyle: Hashable, Sendable {
-        /// Swift source code should be indented using tabs.
+        /// Indent using tabs
         case tabs
-        /// Swift source code should be indented using spaces with `count` spaces per indentation level.
+        /// Indent using spaces with `count` spaces per indentation level
         case spaces(count: Int)
 
-        /// The default indentation style if none is explicitly provided.
+        /// The default indentation style if none is explicitly provided
         static let `default` = spaces(count: 4)
 
-        /// Creates an indentation style based on an untyped configuration value.
+        /// Create an indentation style based on an untyped configuration value
         ///
-        /// - parameter object: The configuration value.
+        /// - Parameters:
+        ///   - object: The configuration value (an `Int` for spaces or the string `"tabs"`).
         init?(_ object: Any?) {
             switch object {
                 case let value as Int: self = .spaces(count: value)

Sources/Swiftiomatic/Configuration/Configuration+Parsing.swift

@@ -19,14 +19,14 @@ extension Configuration {
 
     // MARK: - Initializers
 
-    /// Creates a Configuration value based on the specified parameters.
+    /// Create a ``Configuration`` value from a parsed YAML dictionary
     ///
-    /// - parameter dict:                   The untyped dictionary to serve as the input for this typed configuration.
-    ///                                     Typically generated from a YAML-formatted file.
-    /// - parameter ruleList:               The list of rules to be available to this configuration.
-    /// - parameter enableAllRules:         Whether all rules from `ruleList` should be enabled, regardless of the
-    ///                                     settings in `dict`.
-    /// - parameter cachePath:              The location of the persisted cache on disk.
+    /// - Parameters:
+    ///   - dict: The untyped dictionary to serve as the input, typically generated from a YAML file.
+    ///   - ruleList: The list of rules to be available to this configuration.
+    ///   - enableAllRules: Whether all rules from `ruleList` should be enabled regardless of `dict`.
+    ///   - onlyRule: Rules to restrict the run to.
+    ///   - cachePath: The location of the persisted cache on disk.
     init(
         dict: [String: Any],
         ruleList: RuleList = RuleRegistry.shared.list,

Sources/Swiftiomatic/Configuration/Configuration+RuleSelection.swift

@@ -2,7 +2,7 @@ import Foundation
 import Synchronization
 
 extension Configuration {
-    /// Manages which rules are active based on the configured `RulesMode`.
+    /// Manages which rules are active based on the configured ``RulesMode``
     ///
     /// All mutable state is protected by `Mutex`, making concurrent access safe.
     package final class RuleSelection: @unchecked Sendable {
@@ -16,8 +16,7 @@ extension Configuration {
         private let invalidRuleIdsWarnedAbout = Mutex<Set<String>>([])
         private let cachedResultingRules = Mutex<[any Rule]?>(nil)
 
-        /// All rules enabled in this configuration,
-        /// derived from rule mode (only / optIn - disabled) & existing rules
+        /// All rules enabled in this configuration, derived from the ``RulesMode``
         var resultingRules: [any Rule] {
             cachedResultingRules.withLock { cached in
                 if let rules = cached { return rules }

Sources/Swiftiomatic/Configuration/Configuration+RulesMode.swift

@@ -1,30 +1,27 @@
 extension Configuration {
-    /// Returns the rule for the specified ID, if configured in this configuration.
+    /// Return the rule for the specified ID, if configured in this configuration
     ///
-    /// - parameter ruleID: The identifier for the rule to look up.
-    ///
-    /// - returns: The rule for the specified ID, if configured in this configuration.
+    /// - Parameters:
+    ///   - ruleID: The identifier for the rule to look up.
+    /// - Returns: The rule for the specified ID, if configured in this configuration.
     func configuredRule(forID ruleID: String) -> (any Rule)? {
         rules.first { rule in
             type(of: rule).identifier == ruleID
         }
     }
 
-    /// Represents how a Configuration object can be configured with regards to rules.
+    /// Represents how a ``Configuration`` selects which rules are active
     package enum RulesMode: Equatable, Sendable {
-        /// The default rules mode, which will enable all rules that aren't defined as being opt-in
-        /// (conforming to the `OptInRule` protocol), minus the rules listed in `disabled`, plus the rules listed in
-        /// `optIn`.
+        /// Enable all non-``OptInRule`` rules minus `disabled`, plus `optIn`
         case defaultConfiguration(disabled: Set<String>, optIn: Set<String>)
 
-        /// Only enable the rules explicitly listed in the configuration files.
+        /// Only enable the rules explicitly listed in the configuration files
         case onlyConfiguration(Set<String>)
 
-        /// Only enable the rule(s) explicitly listed on the command line (and their aliases). `--only-rule` can be
-        /// specified multiple times to enable multiple rules.
+        /// Only enable the rule(s) explicitly listed on the command line (and their aliases)
         case onlyCommandLine(Set<String>)
 
-        /// Enable all available rules.
+        /// Enable all available rules
         case allCommandLine
 
         init(
@@ -98,6 +95,11 @@ extension Configuration {
             }
         }
 
+        /// Return a copy with all rule identifiers resolved through the alias resolver
+        ///
+        /// - Parameters:
+        ///   - aliasResolver: A closure that maps deprecated aliases to canonical identifiers.
+        /// - Returns: A new ``RulesMode`` with all identifiers resolved.
         func applied(aliasResolver: (String) -> String) -> Self {
             switch self {
                 case let .defaultConfiguration(disabled, optIn):