Merge pull request #123 from mihaelamj/feat/81-swiftsyntax-ast-indexing

  Summary

  - AST Indexing: SwiftSyntax-based extraction of symbols, property wrappers, conformances from sample code
  - Unified Search: Single search across all 8 sources with hierarchical result numbering (1.1, 1.2, 2.1...)
  - Doctor Command Enhanced: Package diagnostics with orphan detection
  - Code Quality: Consolidated constants, fixed race conditions in tests, SwiftLint compliance

  Changes

  Added

  - ASTIndexer package with SwiftSourceExtractor for semantic code analysis
  - StringFormatterTests - 34 unit tests for display formatting
  - Hierarchical result numbering and source counts in search output

  Fixed

  - Display formatting bugs (double spaces, title-casing)
  - Race condition in PriorityPackagesCatalog tests
  - SwiftLint violations (line length, identifier names)
  - Package-docs fetch now reads user selections (#107)

  Changed

  - 698 tests across 73 suites (up from 93/7)
  - Renamed md → output in formatters for clarity

  Test plan

  - All 698 tests pass
  - swift build succeeds
  - cupertino search "swiftui navigation" produces correct output
  - SwiftLint passes on modified files

  Related Issues

  Closes #81, #107

Author: mihaelamj

CHANGELOG.md

@@ -1,3 +1,58 @@
+## 0.8.0 (2025-12-20)
+
+### Added
+- **Doctor Command Enhanced** - Package diagnostics (#81)
+  - Shows user selections file status and package count
+  - Shows downloaded README count
+  - Warns about orphaned READMEs (packages no longer selected)
+  - Displays priority package breakdown (Apple vs ecosystem)
+- **String Formatter Tests** - 34 unit tests for display formatting (#81)
+  - `StringFormatterTests.swift` covers truncation, markdown escaping, camelCase splitting
+
+### Changed
+- **Code Quality Improvements** (#81)
+  - Consolidated magic numbers into `Shared.Constants` (timeouts, delays, limits, intervals)
+  - Added `Timeout`, `Delay`, `Limit`, `Interval` namespaces for better organization
+  - Replaced hardcoded values across WKWebCrawler, HIGCrawler, and other modules
+- **PriorityPackagesCatalog** - Made fields optional for TUI compatibility
+  - `appleOfficial` tier now optional (TUI only saves ecosystem tier)
+  - Stats fields `totalCriticalApplePackages` and `totalEcosystemPackages` now optional
+- **Search Result Formatting** (#81)
+  - Hierarchical result numbering (1.1, 1.2, 2.1, etc.)
+  - Source counts in headers: `## 1. Apple Documentation (20) 📚`
+  - Renamed `md` variable to `output` in formatters for clarity
+
+### Fixed
+- **Package-docs fetch now reads user selections** (#107)
+  - `cupertino fetch --type package-docs` now loads from `~/.cupertino/selected-packages.json`
+  - Falls back to bundled `priority-packages.json` if user file doesn't exist
+  - TUI package selections are now respected by fetch command
+- **Display Formatting Bugs** (#81)
+  - Double space artifacts ("Tab  bars" → "Tab bars")
+  - Smart title-casing (only lowercase first letters get uppercased)
+  - SwiftLint violations (line length, identifier names)
+
+### Related Issues
+- Closes #81, #107
+
+---
+
+## 0.7.0 (2025-12-15)
+
+### Added
+- **Unified Search with Source Parameter**
+  - New `--source` parameter: `apple-docs`, `samples`, `hig`, `apple-archive`, `swift-evolution`, `swift-org`, `swift-book`, `packages`, `all`
+  - Teasers show results from alternate sources in every search response
+  - Source-aware messaging tells AI exactly what was searched
+- **Documentation Database Expanded** - 302,424 docs across 307 frameworks (up from 234k/287)
+
+### Changed
+- Consolidated multiple search tools into one unified search tool
+- Shared formatters between MCP and CLI for consistent output
+- Shared TeaserFormatter and constants eliminate hardcoding
+
+---
+
 ## 0.6.0 (2025-12-12)
 
 ### Added
@@ -30,17 +85,6 @@
 
 ---
 
-## 0.7.0 (2025-12-15)
-
-### Added
--
-
-### Changed
--
-
-### Fixed
--
-
 ## 0.5.0 (2025-12-11)
 
 **Why minor bump?** The `cupertino release` command was removed from the public CLI. Users who had scripts calling `cupertino release` will need to update them. This is a breaking change for maintainer workflows.

Packages/Package.resolved

@@ -25,6 +25,7 @@ let macOSOnlyProducts: [Product] = [
     .singleTargetLibrary("Services"),
     .singleTargetLibrary("Resources"),
     .singleTargetLibrary("Availability"),
+    .singleTargetLibrary("ASTIndexer"),
     .singleTargetLibrary("MCPSupport"),
     .singleTargetLibrary("SearchToolProvider"),
     .singleTargetLibrary("MCPClient"),
@@ -49,6 +50,8 @@ let allProducts = baseProducts + macOSOnlyProducts
 let deps: [Package.Dependency] = [
     // Swift Argument Parser (cross-platform CLI tool)
     .package(url: "https://github.com/apple/swift-argument-parser", from: "1.5.0"),
+    // SwiftSyntax for AST parsing (#81)
+    .package(url: "https://github.com/swiftlang/swift-syntax", from: "600.0.0"),
 ]
 
 // -------------------------------------------------------------
@@ -118,7 +121,7 @@ let targets: [Target] = {
 
     let searchTarget = Target.target(
         name: "Search",
-        dependencies: ["Shared", "Logging", "Core"]
+        dependencies: ["Shared", "Logging", "Core", "ASTIndexer"]
     )
     let searchTestsTarget = Target.testTarget(
         name: "SearchTests",
@@ -127,7 +130,7 @@ let targets: [Target] = {
 
     let sampleIndexTarget = Target.target(
         name: "SampleIndex",
-        dependencies: ["Shared", "Logging"]
+        dependencies: ["Shared", "Logging", "ASTIndexer"]
     )
     let sampleIndexTestsTarget = Target.testTarget(
         name: "SampleIndexTests",
@@ -188,6 +191,20 @@ let targets: [Target] = {
         dependencies: ["Availability", "TestSupport"]
     )
 
+    let astIndexerTarget = Target.target(
+        name: "ASTIndexer",
+        dependencies: [
+            "Shared",
+            "Logging",
+            .product(name: "SwiftSyntax", package: "swift-syntax"),
+            .product(name: "SwiftParser", package: "swift-syntax"),
+        ]
+    )
+    let astIndexerTestsTarget = Target.testTarget(
+        name: "ASTIndexerTests",
+        dependencies: ["ASTIndexer", "Search", "SampleIndex", "TestSupport"]
+    )
+
     let cliTarget = Target.executableTarget(
         name: "CLI",
         dependencies: [
@@ -309,6 +326,8 @@ let targets: [Target] = {
         remoteSyncTestsTarget,
         availabilityTarget,
         availabilityTestsTarget,
+        astIndexerTarget,
+        astIndexerTestsTarget,
         testSupportTarget,
         cliTarget,
         tuiTarget,

Packages/Package.swift

@@ -0,0 +1,10 @@
+// ASTIndexer.swift
+// SwiftSyntax-based AST parsing for semantic code indexing (#81)
+
+import Foundation
+
+/// Namespace for AST indexing types
+public enum ASTIndexer {
+    /// Current schema version for AST index tables
+    public static let schemaVersion: Int = 1
+}

Packages/Sources/ASTIndexer/ASTIndexer.swift

@@ -0,0 +1,141 @@
+// ExtractedSymbol.swift
+// Data models for extracted AST symbols (#81)
+
+import Foundation
+
+extension ASTIndexer {
+    /// Kind of Swift symbol
+    public enum SymbolKind: String, Codable, Sendable, CaseIterable {
+        case `class`
+        case `struct`
+        case `enum`
+        case `actor`
+        case `protocol`
+        case `extension`
+        case function
+        case method
+        case initializer
+        case property
+        case `subscript`
+        case `typealias`
+        case `associatedtype`
+        case `case` // enum case
+        case `operator`
+        case macro
+    }
+
+    /// A symbol extracted from Swift source code
+    public struct ExtractedSymbol: Codable, Sendable, Hashable {
+        /// Symbol name (e.g., "AppState", "fetchItems", "count")
+        public let name: String
+
+        /// Kind of symbol
+        public let kind: SymbolKind
+
+        /// Line number in source (1-indexed)
+        public let line: Int
+
+        /// Column number in source (1-indexed)
+        public let column: Int
+
+        /// Full signature for functions/methods (e.g., "func fetchItems() async throws -> [Item]")
+        public let signature: String?
+
+        /// Whether the symbol is async
+        public let isAsync: Bool
+
+        /// Whether the symbol throws
+        public let isThrows: Bool
+
+        /// Whether the symbol is public
+        public let isPublic: Bool
+
+        /// Whether the symbol is static
+        public let isStatic: Bool
+
+        /// Attributes applied to the symbol (e.g., ["@MainActor", "@Observable"])
+        public let attributes: [String]
+
+        /// Protocol conformances (for types)
+        public let conformances: [String]
+
+        /// Generic parameters (e.g., ["T", "U: Hashable"])
+        public let genericParameters: [String]
+
+        public init(
+            name: String,
+            kind: SymbolKind,
+            line: Int,
+            column: Int,
+            signature: String? = nil,
+            isAsync: Bool = false,
+            isThrows: Bool = false,
+            isPublic: Bool = false,
+            isStatic: Bool = false,
+            attributes: [String] = [],
+            conformances: [String] = [],
+            genericParameters: [String] = []
+        ) {
+            self.name = name
+            self.kind = kind
+            self.line = line
+            self.column = column
+            self.signature = signature
+            self.isAsync = isAsync
+            self.isThrows = isThrows
+            self.isPublic = isPublic
+            self.isStatic = isStatic
+            self.attributes = attributes
+            self.conformances = conformances
+            self.genericParameters = genericParameters
+        }
+    }
+
+    /// An import statement extracted from Swift source
+    public struct ExtractedImport: Codable, Sendable, Hashable {
+        /// Module name (e.g., "SwiftUI", "Foundation")
+        public let moduleName: String
+
+        /// Line number in source
+        public let line: Int
+
+        /// Whether this is an @_exported import
+        public let isExported: Bool
+
+        public init(moduleName: String, line: Int, isExported: Bool = false) {
+            self.moduleName = moduleName
+            self.line = line
+            self.isExported = isExported
+        }
+    }
+
+    /// Result of parsing a Swift source file
+    public struct ExtractionResult: Codable, Sendable {
+        /// All symbols found in the source
+        public let symbols: [ExtractedSymbol]
+
+        /// All imports found in the source
+        public let imports: [ExtractedImport]
+
+        /// Whether the source had syntax errors
+        public let hasErrors: Bool
+
+        /// Error message if parsing failed completely
+        public let errorMessage: String?
+
+        public init(
+            symbols: [ExtractedSymbol],
+            imports: [ExtractedImport],
+            hasErrors: Bool = false,
+            errorMessage: String? = nil
+        ) {
+            self.symbols = symbols
+            self.imports = imports
+            self.hasErrors = hasErrors
+            self.errorMessage = errorMessage
+        }
+
+        /// Empty result (for failed parsing)
+        public static let empty = ExtractionResult(symbols: [], imports: [], hasErrors: true)
+    }
+}