fix all build errors and test failures for CLI and Xcode app (ivk-5u2, vfk-vlj, 4si-g2g)

- promote package → public on ~80 declarations for cross-target visibility
- add Sendable conformance to RuleViolation, LinterCache, FormatRuleCatalog
- exclude .format/.suggest scope rules from default lint configuration
- fix PeriodSpacingRule regex for Swift Regex engine compatibility
- add SwiftSyntax-based comment exclusion fallback when SourceKit is disabled
- fix two-pass collect-then-validate in test helpers for CollectingRule
- restore BridgeExtensions.swift, fix Command \r\n handling

Author: Jason-Abbott

.claude/settings.local.json

@@ -65,7 +65,12 @@
       "mcp__xc-project__remove_target",
       "mcp__xc-build__clean",
       "mcp__xc-build__list_schemes",
-      "mcp__xc-swift__swift_diagnostics"
+      "mcp__xc-swift__swift_diagnostics",
+      "mcp__xc-build__set_session_defaults",
+      "mcp__xc-build__test_macos",
+      "mcp__xc-build__list_test_plan_targets",
+      "WebFetch(domain:www.swift.org)",
+      "WebFetch(domain:wwdcnotes.com)"
     ]
   },
   "enableAllProjectMcpServers": true,

.claude/skills/docc/SKILL.md

@@ -109,6 +109,133 @@ This project follows specific DocC patterns. See [references/swiftiomatic-conven
 - How to document rules and analysis categories
 - Cross-referencing between rule types and configuration
 
+## Metadata Directives
+
+Use `@Metadata` at the top of an article (after the title) to control page behavior and appearance:
+
+```markdown
+# My Sample Project
+
+@Metadata {
+    @PageKind(sampleCode)
+    @CallToAction(url: "https://github.com/org/repo", purpose: link)
+    @PageImage(purpose: card, source: "project-card", alt: "Screenshot of the project")
+    @PageColor(green)
+}
+
+Summary sentence.
+```
+
+### @PageKind
+
+Sets the page type and navigator icon. Values: `article` (default for `.md` files), `sampleCode`.
+
+Sample code pages display "Sample Code" as the role heading (eyebrow text above the title) and get a distinct sidebar icon.
+
+### @CallToAction
+
+Adds a prominent button in the page header. Use with sample code pages to link to the source repo or download.
+
+| Parameter | Description |
+|-----------|-------------|
+| `url` | External URL (use for repo links) |
+| `file` | Local file path relative to the `.docc` bundle (use for downloads) |
+| `purpose` | Default label: `link` → "Visit", `download` → "Download" |
+| `label` | Custom button text (overrides `purpose` label) |
+
+One of `url` or `file` required. One of `purpose` or `label` required. Only one `@CallToAction` per page.
+
+```markdown
+@Metadata {
+    @CallToAction(url: "https://github.com/org/repo", label: "View on GitHub")
+}
+```
+
+### @PageImage
+
+Sets the card image shown when the page appears in a `@Links` grid. Also used as the page's icon.
+
+```markdown
+@PageImage(purpose: card, source: "my-image", alt: "Description")
+```
+
+The `source` references an image file in the `Resources/` directory (without extension). Supports `@2x` and `~dark` variants.
+
+### @PageColor
+
+Sets the accent color for the page. Built-in colors: `blue` (default), `green`, `yellow`, `orange`, `purple`, `red`.
+
+```markdown
+@PageColor(green)
+```
+
+## @Links Directive
+
+Feature documentation pages with styled link collections anywhere on a page — outside the `## Topics` section.
+
+```markdown
+@Links(visualStyle: detailedGrid) {
+    - <doc:SampleProject1>
+    - <doc:SampleProject2>
+    - <doc:GettingStartedGuide>
+}
+```
+
+### visualStyle Options
+
+| Style | Shows | Best for |
+|-------|-------|----------|
+| `list` | Title + abstract (matches Topics style) | General link lists |
+| `compactGrid` | Card image + title only | Visual galleries, sample code collections |
+| `detailedGrid` | Card image + title + abstract | Featured content with descriptions |
+
+Card images come from `@PageImage(purpose: card, ...)` on the linked page. Pages without a card image still work but show a placeholder.
+
+The directive can only contain `<doc:>` links — no headings or prose inside the block.
+
+## Sample Code Page Template
+
+A complete sample code page combining these directives:
+
+```markdown
+# Building a Custom Linter
+
+@Metadata {
+    @PageKind(sampleCode)
+    @CallToAction(url: "https://github.com/org/custom-linter", purpose: link)
+    @PageImage(purpose: card, source: "custom-linter-card", alt: "Custom linter running in Xcode")
+    @PageColor(purple)
+}
+
+Learn how to build a custom Swift linter using Swiftiomatic's rule API.
+
+## Overview
+
+This sample project demonstrates creating rules, configuring severity,
+and integrating with Xcode's build system.
+
+## Topics
+
+### Essentials
+- <doc:CreatingYourFirstRule>
+- ``Rule``
+- ``RuleConfiguration``
+```
+
+### Featuring Sample Code from a Landing Page
+
+On Main.md or a category page, use `@Links` to showcase sample projects:
+
+```markdown
+## Featured Sample Code
+
+@Links(visualStyle: compactGrid) {
+    - <doc:BuildingACustomLinter>
+    - <doc:IntegratingWithXcode>
+    - <doc:WritingFormatRules>
+}
+```
+
 ## Layout Directives
 
 For rich layouts beyond standard Markdown:
@@ -135,6 +262,20 @@ For rich layouts beyond standard Markdown:
 }
 ```
 
+## What NOT to Use DocC For
+
+**Rule documentation** (examples, triggering/non-triggering code, corrections) must stay in the Swift type system — not DocC. The `RuleDescription` and `FormatRule` types carry structured data that DocC cannot express:
+
+- `nonTriggeringExamples` / `triggeringExamples` arrays of `Example` with per-example configuration overrides and test metadata (`shouldTestMultiByteOffsets`, `shouldTestWrappingInComment`, etc.)
+- `corrections` dictionary mapping before→after code for auto-fix validation
+- FormatRule `examples` closures with string interpolation of runtime values (e.g. `VisibilityCategory.defaultOrdering(...)`)
+- `options` / `sharedOptions` arrays consumed by `generate-docs` and CLI `--help`
+
+This data is consumed programmatically at runtime (CLI help, `generate-docs` markdown output, test harnesses). DocC is a compile-time documentation system that produces HTML — it cannot serve these use cases.
+
+**Use DocC for:** module-level overviews, conceptual articles, API symbol documentation, guides.
+**Use RuleDescription/FormatRule for:** per-rule examples, configuration docs, triggering/non-triggering code.
+
 ## Common Issues
 
 | Problem | Solution |

.issues/3/3eb-r8b--remove-bridge-calls-use-idiomatic-swift-casts.md

@@ -0,0 +1,29 @@
+---
+# 3eb-r8b
+title: Remove .bridge() calls — use idiomatic Swift casts
+status: completed
+type: task
+priority: normal
+created_at: 2026-03-01T18:45:33Z
+updated_at: 2026-03-01T18:48:35Z
+sync:
+    github:
+        issue_number: "129"
+        synced_at: "2026-03-01T21:06:29Z"
+---
+
+Replace all .bridge() call sites with idiomatic Swift: drop where String extensions exist, use `as NSString` for path ops, explicit casts for NSRange loops, .utf8.count for byte lengths.
+
+
+## Summary of Changes
+
+Replaced all 17 compiled `.bridge()` call sites across 11 files with idiomatic Swift:
+
+- **Drop `.bridge()`** where String extensions already exist: `absolutePathStandardized()`, `fullNSRange` (3 sites)
+- **`as NSString` casts** for path operations: `lastPathComponent`, `deletingPathExtension`, `appendingPathComponent` (7 sites)
+- **Explicit `as NSString`/`as String` casts** in NSRange replacement loops: ExplicitSelfRule, UnusedImportRule (5 sites)
+- **`.utf8.count`** replacing `.bridge().lengthOfBytes(using: .utf8)` (1 site)
+- **`(x as NSString).replacingCharacters(in:with:)`** in SyntacticSugarRule (1 site)
+- **Skipped** 2 occurrences in UnavailableFunctionRule — inside `Example("""...""")` string literals, not compiled code
+
+All changes are zero-cost toll-free bridging. No functional behavior change.

.issues/4/4si-g2g--fix-build-warnings-after-violationseverityseverity.md

@@ -0,0 +1,20 @@
+---
+# 4si-g2g
+title: Fix build warnings after ViolationSeverity→Severity rename
+status: in-progress
+type: bug
+priority: normal
+created_at: 2026-03-01T19:53:36Z
+updated_at: 2026-03-01T19:53:36Z
+sync:
+    github:
+        issue_number: "127"
+        synced_at: "2026-03-01T21:06:26Z"
+---
+
+Build warnings/errors after ViolationSeverity→Severity rename and BridgeExtensions.swift deletion.
+
+## Tasks
+- [ ] Build to capture all warnings/errors
+- [ ] Fix each warning
+- [ ] Rebuild to verify clean build

.issues/7/7y2-kma--evaluate-consistent-use-of-ruledescription-across.md

@@ -0,0 +1,32 @@
+---
+# 7y2-kma
+title: Evaluate consistent use of RuleDescription across SwiftLint and SwiftFormat-derived rules
+status: in-progress
+type: task
+priority: normal
+created_at: 2026-03-01T20:20:03Z
+updated_at: 2026-03-01T20:26:02Z
+sync:
+    github:
+        issue_number: "128"
+        synced_at: "2026-03-01T21:06:26Z"
+---
+
+Audit the two rule systems (Rule protocol with RuleDescription vs FormatRule class) for consistency in how rule metadata is described, documented, and consumed. Identify gaps and recommend whether/how to unify.
+
+- [x] Map the two metadata models
+- [x] Identify field coverage gaps
+- [x] Evaluate generate-docs coverage
+- [x] Assess RuleCatalog bridge completeness
+- [x] Write findings and recommendations
+
+## Summary of Changes
+
+Evaluation only — no code changes. Findings:
+
+1. **Two separate metadata systems**: Rule uses RuleDescription struct (11 fields); FormatRule uses inline stored properties (help, examples, options). They don't share a type.
+2. **RuleCatalog bridges them** at the query layer via Entry, but loses rich metadata.
+3. **generate-docs excludes FormatRules** entirely — 130 rules get no documentation output.
+4. **Naming mismatch**: Rules use snake_case identifiers, FormatRules use camelCase names.
+5. **rationale field adopted by only 14/323 rules** — dead API surface.
+6. **Recommendation**: Don't unify the types (different execution models). Instead: (a) extend generate-docs for FormatRules, (b) add a RuleMetadata protocol for the common interface, (c) normalize naming, (d) audit rationale adoption.

.issues/a/ay9-7gx--unify-violationseverity-and-diagnosticseverity-int.md

@@ -1,17 +1,30 @@
 ---
 # ay9-7gx
 title: Unify ViolationSeverity and DiagnosticSeverity into one enum
-status: ready
+status: completed
 type: task
 priority: normal
 created_at: 2026-03-01T07:58:51Z
-updated_at: 2026-03-01T07:58:51Z
+updated_at: 2026-03-01T18:37:30Z
 sync:
     github:
         issue_number: "122"
-        synced_at: "2026-03-01T08:00:21Z"
+        synced_at: "2026-03-01T21:06:26Z"
 ---
 
 These two severity enums serve overlapping purposes but are deeply entangled throughout the codebase. Unifying them requires careful migration of all call sites.
 
 Deferred from vu5-l8x because of the scope of changes required.
+
+
+
+## Summary of Changes
+
+Unified `ViolationSeverity` (package, internal) and `DiagnosticSeverity` (public, output) into a single `public enum Severity` with all necessary conformances.
+
+- **Renamed** `ViolationSeverity.swift` → `Severity.swift` via `git mv` (preserves history)
+- **Promoted** access level from `package` to `public`; added `public` to `<` operator (fixes missing `Comparable` impl bug on old `DiagnosticSeverity`)
+- **Deleted** `DiagnosticSeverity` enum from `Diagnostic.swift`
+- **Simplified** `RuleViolation.toDiagnostic()` — severity passes through directly instead of manual conversion
+- **Renamed** `typealias Severity` in `NestingRule+Configuration` and `NameConfiguration` to avoid shadowing the new module-level `Severity` enum
+- **Mechanical rename** across 20+ files in Sources/ and Tests/