@nshipster/sosumi 1.0.0

package/src/lib/reference/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Apple Developer Reference documentation specific types
+ */
+
+// Most types used by reference docs are already in the shared types.ts
+// This file is for reference-specific types only, if any are needed in the future
+
+// Re-export commonly used types from shared types for convenience
+export type {
+  AppleDocJSON,
+  ContentItem,
+  Declaration,
+  DocumentationIdentifier,
+  DocumentationMetadata,
+  ImageVariant,
+  IndexContentItem,
+  isImageVariant,
+  isLanguageVariant,
+  isSymbolVariant,
+  LanguageVariant,
+  Parameter,
+  Platform,
+  PrimaryContentSection,
+  PropertyItem,
+  SeeAlsoSection,
+  SwiftInterfaceItem,
+  SymbolVariant,
+  TextFragment,
+  TopicSection,
+  Variant,
+} from "../types"

package/src/lib/search.ts

@@ -0,0 +1,221 @@
+import { getRandomUserAgent } from "./fetch"
+
+export interface SearchResult {
+  title: string
+  url: string
+  description: string
+  breadcrumbs: string[]
+  tags: string[]
+  type: string // 'documentation' | 'general' etc.
+}
+
+export interface SearchResponse {
+  query: string
+  results: SearchResult[]
+}
+
+class SearchResultParser {
+  private results: SearchResult[] = []
+  private currentResult: Partial<SearchResult> = {}
+  private currentBreadcrumbs: string[] = []
+  private currentTags: string[] = []
+  private isInResultTitle = false
+  private isInResultDescription = false
+  private isInBreadcrumb = false
+  private isInTag = false
+
+  getResults(): SearchResult[] {
+    return this.results
+  }
+
+  private resetCurrentResult() {
+    this.currentResult = {}
+    this.currentBreadcrumbs = []
+    this.currentTags = []
+    this.isInResultTitle = false
+    this.isInResultDescription = false
+    this.isInBreadcrumb = false
+    this.isInTag = false
+  }
+
+  private finalizeCurrentResult() {
+    if (this.currentResult.title && this.currentResult.url) {
+      this.results.push({
+        title: this.currentResult.title,
+        url: this.currentResult.url,
+        description: this.currentResult.description || "",
+        breadcrumbs: [...this.currentBreadcrumbs],
+        tags: [...this.currentTags],
+        type: this.currentResult.type || "unknown",
+      })
+    }
+    this.resetCurrentResult()
+  }
+
+  element(element: Element) {
+    // Start of a search result
+    if (element.tagName === "li" && element.getAttribute("class")?.includes("search-result")) {
+      this.finalizeCurrentResult() // Finalize previous result if any
+
+      // Extract result type from class
+      const className = element.getAttribute("class") || ""
+      if (className.includes("documentation")) {
+        this.currentResult.type = "documentation"
+      } else if (className.includes("general")) {
+        this.currentResult.type = "general"
+      } else {
+        this.currentResult.type = "other"
+      }
+    }
+
+    // Result title link
+    if (
+      element.tagName === "a" &&
+      element.getAttribute("class")?.includes("click-analytics-result")
+    ) {
+      const href = element.getAttribute("href")
+      if (href) {
+        this.currentResult.url = href.startsWith("/") ? `https://developer.apple.com${href}` : href
+      }
+      this.isInResultTitle = true
+    }
+
+    // Result description
+    if (element.tagName === "p" && element.getAttribute("class")?.includes("result-description")) {
+      this.isInResultDescription = true
+    }
+
+    // Breadcrumb items
+    if (
+      element.tagName === "li" &&
+      element.getAttribute("class")?.includes("breadcrumb-list-item")
+    ) {
+      this.isInBreadcrumb = true
+    }
+
+    // Tag spans
+    if (
+      element.tagName === "span" &&
+      element.parentElement?.getAttribute("class")?.includes("result-tag")
+    ) {
+      this.isInTag = true
+    }
+
+    // Tag list items (for languages like "Swift", "Objective-C")
+    if (
+      element.tagName === "li" &&
+      element.getAttribute("class")?.includes("result-tag language")
+    ) {
+      this.isInTag = true
+    }
+  }
+
+  text(text: Text) {
+    const content = text.text.trim()
+    if (!content) return
+
+    if (this.isInResultTitle && this.currentResult.url) {
+      this.currentResult.title = content
+      this.isInResultTitle = false
+    } else if (this.isInResultDescription) {
+      this.currentResult.description = content
+      this.isInResultDescription = false
+    } else if (this.isInBreadcrumb) {
+      this.currentBreadcrumbs.push(content)
+      this.isInBreadcrumb = false
+    } else if (this.isInTag) {
+      this.currentTags.push(content)
+      this.isInTag = false
+    }
+  }
+
+  end() {
+    this.finalizeCurrentResult() // Finalize the last result
+  }
+}
+
+export async function searchAppleDeveloperDocs(query: string): Promise<SearchResponse> {
+  const searchUrl = `https://developer.apple.com/search/?q=${encodeURIComponent(query)}`
+  const response = await fetch(searchUrl, {
+    headers: {
+      "User-Agent": getRandomUserAgent(),
+    },
+  })
+
+  if (!response.ok) {
+    throw new Error(`Search request failed: ${response.status}`)
+  }
+
+  const html = await response.text()
+  let results: SearchResult[] = []
+  if (typeof HTMLRewriter !== "undefined") {
+    const parser = new SearchResultParser()
+    const rewriter = new HTMLRewriter()
+      .on("li.search-result", parser)
+      .on("li.search-result a.click-analytics-result", parser)
+      .on("li.search-result p.result-description", parser)
+      .on("li.search-result li.breadcrumb-list-item", parser)
+      .on("li.search-result li.result-tag", parser)
+      .on("li.search-result li.result-tag span", parser)
+
+    // We need to consume the transformed response to trigger parsing callbacks.
+    await rewriter.transform(new Response(html)).text()
+    parser.end()
+    results = parser.getResults()
+  } else {
+    results = await parseSearchResultsWithCheerio(html)
+  }
+
+  return {
+    query,
+    results,
+  }
+}
+
+async function parseSearchResultsWithCheerio(html: string): Promise<SearchResult[]> {
+  const { load } = await import("cheerio")
+  const $ = load(html)
+  const results: SearchResult[] = []
+
+  $("li.search-result").each((_, element) => {
+    const item = $(element)
+    const link = item.find("a.click-analytics-result").first()
+    const rawHref = link.attr("href")
+    const title = link.text().trim()
+
+    if (!rawHref || !title) {
+      return
+    }
+
+    const description = item.find("p.result-description").first().text().trim()
+    const breadcrumbs = item
+      .find("li.breadcrumb-list-item")
+      .toArray()
+      .map((breadcrumb) => $(breadcrumb).text().trim())
+      .filter(Boolean)
+
+    const tags = item
+      .find("li.result-tag span, li.result-tag.language")
+      .toArray()
+      .map((tag) => $(tag).text().trim())
+      .filter(Boolean)
+
+    const className = item.attr("class") ?? ""
+    const type = className.includes("documentation")
+      ? "documentation"
+      : className.includes("general")
+        ? "general"
+        : "other"
+
+    results.push({
+      title,
+      url: rawHref.startsWith("/") ? `https://developer.apple.com${rawHref}` : rawHref,
+      description,
+      breadcrumbs,
+      tags,
+      type,
+    })
+  })
+
+  return results
+}

package/src/lib/types.ts

@@ -0,0 +1,334 @@
+/**
+ * Type definitions for Apple Developer documentation JSON API
+ *
+ * This module consolidates all types used across the codebase for processing
+ * Apple documentation. Types are organized by category and complexity.
+ */
+
+// ============================================================================
+// CORE CONTENT TYPES
+// ============================================================================
+
+/**
+ * Represents a text fragment with optional styling information
+ */
+export interface TextFragment {
+  text: string
+  type?: string
+}
+
+/**
+ * Represents a code fragment with syntax highlighting
+ */
+export interface CodeFragment {
+  code: string | string[]
+  syntax?: string
+}
+
+/**
+ * Represents a tokenized piece of content
+ */
+export interface Token {
+  text?: string
+}
+
+/**
+ * The main content item type used throughout the documentation structure.
+ * Can represent text, code, lists, headings, and other content elements.
+ */
+export interface ContentItem {
+  // Basic content properties
+  text?: string
+  type?: string
+  title?: string
+  name?: string
+
+  // Tokenized content
+  tokens?: Token[]
+
+  // Nested content
+  content?: ContentItem[]
+  inlineContent?: ContentItem[]
+  items?: ContentItem[]
+
+  // Code content
+  code?: string | string[]
+  syntax?: string
+
+  // Structural properties
+  level?: number
+  style?: string
+  identifier?: string
+  identifiers?: string[]
+  url?: string
+
+  // Abstract content
+  abstract?: TextFragment[]
+}
+
+// ============================================================================
+// DECLARATION & PARAMETER TYPES
+// ============================================================================
+
+/**
+ * Represents a code declaration with tokenized content
+ */
+export interface Declaration {
+  tokens?: Token[]
+}
+
+/**
+ * Represents a function or method parameter
+ */
+export interface Parameter {
+  name: string
+  content?: ContentItem[]
+}
+
+// ============================================================================
+// SECTION TYPES
+// ============================================================================
+
+/**
+ * Represents a topic section in the documentation
+ */
+export interface TopicSection {
+  title: string
+  identifiers?: string[]
+  children?: TopicSection[]
+  abstract?: ContentItem[]
+  anchor?: string
+}
+
+/**
+ * Represents a "see also" section with related identifiers
+ */
+export interface SeeAlsoSection {
+  title: string
+  identifiers?: string[]
+}
+
+/**
+ * Represents a primary content section with specific kind and content
+ */
+export interface PrimaryContentSection {
+  kind: string
+  content?: ContentItem[]
+  declarations?: Declaration[]
+  parameters?: Parameter[]
+  items?: PropertyItem[]
+}
+
+/**
+ * Represents a property item used in data dictionary pages.
+ */
+export interface PropertyItem {
+  name: string
+  required?: boolean
+  content?: ContentItem[]
+  type?: Array<{
+    text?: string
+    kind?: string
+    identifier?: string
+  }>
+  attributes?: Array<{
+    kind?: string
+    values?: string[]
+  }>
+}
+
+// ============================================================================
+// VARIANT TYPES
+// ============================================================================
+
+/**
+ * Common properties shared across all variant types
+ */
+interface BaseVariant {
+  title?: string
+  abstract?: TextFragment[]
+  identifier?: string
+  type?: string
+  role?: string
+  kind?: string
+}
+
+/**
+ * Represents a language-specific variant of documentation
+ */
+export interface LanguageVariant extends BaseVariant {
+  traits: Array<{ interfaceLanguage: string }>
+  paths: string[]
+}
+
+/**
+ * Represents an image variant with URL and traits
+ */
+export interface ImageVariant extends BaseVariant {
+  url: string
+  traits: string[]
+}
+
+/**
+ * Represents a symbol variant with detailed metadata
+ */
+export interface SymbolVariant extends BaseVariant {
+  url?: string
+  fragments?: Array<{
+    kind: string
+    text?: string
+    preciseIdentifier?: string
+  }>
+  conformance?: {
+    constraints?: Array<{
+      code?: string
+      type: string
+      text?: string
+    }>
+    conformancePrefix?: Array<{
+      text: string
+      type: string
+    }>
+    availabilityPrefix?: Array<{
+      type: string
+      text: string
+    }>
+  }
+}
+
+/**
+ * Union type representing any variant type
+ */
+export type Variant = LanguageVariant | ImageVariant | SymbolVariant
+
+// ============================================================================
+// INTERFACE & INDEX TYPES
+// ============================================================================
+
+/**
+ * Represents a Swift interface item in the documentation index
+ */
+export interface SwiftInterfaceItem {
+  path: string
+  title: string
+  type: string
+  children?: SwiftInterfaceItem[]
+  external?: boolean
+  beta?: boolean
+}
+
+/**
+ * Represents an item in the documentation index
+ */
+export interface IndexContentItem {
+  type?: string
+  title?: string
+  path?: string
+  beta?: boolean
+  children?: IndexContentItem[]
+}
+
+// ============================================================================
+// METADATA TYPES
+// ============================================================================
+
+/**
+ * Platform information for documentation
+ */
+export interface Platform {
+  name: string
+  introducedAt: string
+  beta?: boolean
+}
+
+/**
+ * Documentation metadata
+ */
+export interface DocumentationMetadata {
+  title?: string
+  platforms?: Platform[]
+  roleHeading?: string
+  symbolKind?: string
+}
+
+/**
+ * Documentation identifier with URL and language
+ */
+export interface DocumentationIdentifier {
+  url: string
+  interfaceLanguage?: string
+}
+
+// ============================================================================
+// MAIN DOCUMENTATION STRUCTURE
+// ============================================================================
+
+/**
+ * The main Apple documentation JSON structure.
+ * This is the root type for all Apple documentation responses.
+ */
+export interface AppleDocJSON {
+  // Metadata
+  metadata?: DocumentationMetadata
+  kind?: string
+  identifier?: DocumentationIdentifier
+
+  // Content
+  abstract?: Array<{ text: string; type: string }>
+  sections?: ContentItem[]
+
+  // Primary content sections
+  primaryContentSections?: PrimaryContentSection[]
+
+  // Topic sections
+  topicSections?: TopicSection[]
+  seeAlsoSections?: SeeAlsoSection[]
+
+  // Variants and relationships
+  variants?: Variant[]
+  relationshipsSections?: ContentItem[]
+
+  // References
+  references?: Record<string, ContentItem>
+
+  // Index-specific fields
+  interfaceLanguages?: {
+    swift?: SwiftInterfaceItem[]
+  }
+}
+
+// ============================================================================
+// UTILITY TYPES
+// ============================================================================
+
+/**
+ * Type guard to check if a variant is a language variant
+ */
+export function isLanguageVariant(variant: Variant): variant is LanguageVariant {
+  return (
+    "traits" in variant &&
+    Array.isArray(variant.traits) &&
+    variant.traits.length > 0 &&
+    typeof variant.traits[0] === "object" &&
+    "interfaceLanguage" in variant.traits[0]
+  )
+}
+
+/**
+ * Type guard to check if a variant is an image variant
+ */
+export function isImageVariant(variant: Variant): variant is ImageVariant {
+  return (
+    "url" in variant &&
+    "traits" in variant &&
+    Array.isArray(variant.traits) &&
+    typeof variant.traits[0] === "string"
+  )
+}
+
+/**
+ * Type guard to check if a variant is a symbol variant
+ */
+export function isSymbolVariant(variant: Variant): variant is SymbolVariant {
+  return "fragments" in variant || "conformance" in variant
+}

package/src/lib/url.ts

@@ -0,0 +1,55 @@
+// Constants for Apple Developer documentation URLs
+const APPLE_DOC_BASE_URL = "https://developer.apple.com/documentation/"
+
+/**
+ * Normalizes documentation paths by removing leading slashes, whitespace, and documentation prefixes.
+ *
+ * This function handles various input formats:
+ * - `/swift/array` → `swift/array`
+ * - `documentation/swift/array` → `swift/array`
+ * - `  swift/array  ` → `swift/array`
+ * - `/documentation/swift/array` → `swift/array`
+ *
+ * @param path - The documentation path to normalize
+ * @returns The normalized path without leading slashes or documentation prefixes
+ */
+export function normalizeDocumentationPath(path: string): string {
+  if (!path || typeof path !== "string") {
+    return ""
+  }
+
+  return (
+    path
+      .trim()
+      // Remove leading slashes and documentation prefixes
+      .replace(/^\/?(?:documentation\/?)?/, "")
+  )
+}
+
+/**
+ * Generates a complete Apple Developer documentation URL from a normalized path.
+ *
+ * @param normalizedPath - The normalized documentation path (e.g., "swift/array")
+ * @returns The complete Apple Developer documentation URL
+ */
+export function generateAppleDocUrl(normalizedPath: string): string {
+  if (!normalizedPath || typeof normalizedPath !== "string") {
+    return APPLE_DOC_BASE_URL
+  }
+
+  return `${APPLE_DOC_BASE_URL}${normalizedPath}`
+}
+
+/**
+ * Validates if a URL is a proper Apple Developer documentation URL.
+ *
+ * @param url - The URL to validate
+ * @returns True if the URL is a valid Apple Developer documentation URL
+ */
+export function isValidAppleDocUrl(url: string): boolean {
+  if (!url || typeof url !== "string") {
+    return false
+  }
+
+  return url.startsWith(APPLE_DOC_BASE_URL)
+}