@nshipster/sosumi 1.0.0

package/src/lib/external/fetch.ts

@@ -0,0 +1,133 @@
+import { renderFromJSON } from "../reference"
+import type { AppleDocJSON } from "../types"
+import {
+  assertExternalDocumentationAccess,
+  ExternalAccessError,
+  validateExternalDocumentationUrl,
+} from "./policy"
+import type { ExternalPolicyEnv, RobotsPolicyResult } from "./types"
+
+const RESTRICTIVE_X_ROBOTS_TAGS = ["none", "noindex", "noai", "noimageai"] as const
+
+export function extractExternalDocumentationBasePath(sourceUrl: URL): string {
+  const normalizedPath = sourceUrl.pathname.replace(/\/+$/, "")
+  const match = normalizedPath.match(/^(.*?)(\/documentation(?:\/.*)?)$/)
+  if (!match) {
+    throw new ExternalAccessError(
+      "External URL must point to a Swift-DocC documentation path.",
+      400,
+    )
+  }
+
+  return match[1]
+}
+
+export function buildExternalDocCJsonUrl(sourceUrl: URL): URL {
+  const hostBasePath = extractExternalDocumentationBasePath(sourceUrl)
+  const documentationPath = sourceUrl.pathname.replace(/\/+$/, "").slice(hostBasePath.length)
+  const jsonPath = documentationPath.endsWith(".json")
+    ? documentationPath
+    : `${documentationPath}.json`
+  return new URL(`${hostBasePath}/data${jsonPath}`, sourceUrl.origin)
+}
+
+export async function fetchExternalDocCJSON(
+  sourceUrl: URL,
+  externalPolicyEnv: ExternalPolicyEnv = {},
+): Promise<AppleDocJSON> {
+  const validatedUrl = validateExternalDocumentationUrl(sourceUrl.toString())
+  await assertExternalDocumentationAccess(validatedUrl, externalPolicyEnv)
+  const jsonUrl = buildExternalDocCJsonUrl(validatedUrl)
+  const response = await fetch(jsonUrl.toString(), {
+    headers: {
+      "User-Agent": EXTERNAL_DOC_USER_AGENT,
+      Accept: "application/json",
+    },
+  })
+
+  const xRobotsTag = response.headers.get("x-robots-tag")
+  if (containsRestrictiveXRobotsTag(xRobotsTag)) {
+    throw new ExternalAccessError(
+      "External host denied AI/doc access via X-Robots-Tag response header.",
+      403,
+    )
+  }
+
+  if (!response.ok) {
+    if (response.status === 404) {
+      throw new ExternalAccessError(
+        `External documentation page not found at ${jsonUrl.toString()}`,
+        404,
+      )
+    }
+
+    throw new Error(`Failed to fetch external DocC JSON: ${response.status} ${response.statusText}`)
+  }
+
+  return (await response.json()) as AppleDocJSON
+}
+
+export async function fetchExternalDocumentationMarkdown(
+  url: string,
+  externalPolicyEnv: ExternalPolicyEnv = {},
+): Promise<string> {
+  const targetUrl = validateExternalDocumentationUrl(url)
+  const jsonData = await fetchExternalDocCJSON(targetUrl, externalPolicyEnv)
+  const externalBasePath = extractExternalDocumentationBasePath(targetUrl)
+  return renderFromJSON(jsonData, targetUrl.toString(), {
+    externalOrigin: `${targetUrl.origin}${externalBasePath}`,
+  })
+}
+
+export async function fetchRobotsPolicy(
+  origin: string,
+  userAgent: string,
+): Promise<RobotsPolicyResult> {
+  const robotsUrl = new URL("/robots.txt", origin)
+  const response = await fetch(robotsUrl.toString(), {
+    headers: {
+      "User-Agent": userAgent,
+      Accept: "text/plain, text/*;q=0.9, */*;q=0.1",
+    },
+  })
+
+  // Missing or inaccessible robots.txt — caller may try root domain or allow.
+  if (response.status === 404 || response.status === 410 || response.status === 403) {
+    return { kind: "not-found" }
+  }
+
+  // Explicit access denial when robots cannot be read due to auth.
+  if (response.status === 401) {
+    return { kind: "deny-all" }
+  }
+
+  // Fail open for transient server/network issues.
+  if (!response.ok) {
+    return { kind: "allow-all" }
+  }
+
+  const robotsText = await response.text()
+  return { kind: "rules", robotsText }
+}
+
+function containsRestrictiveXRobotsTag(headerValue: string | null): boolean {
+  if (!headerValue) {
+    return false
+  }
+
+  const tokenSet = new Set(
+    headerValue
+      .toLowerCase()
+      .split(",")
+      .map((token) => token.trim())
+      .filter(Boolean),
+  )
+
+  for (const token of RESTRICTIVE_X_ROBOTS_TAGS) {
+    if (tokenSet.has(token)) {
+      return true
+    }
+  }
+  return false
+}
+export const EXTERNAL_DOC_USER_AGENT = "sosumi-ai/1.0 (+https://sosumi.ai/#bot)"

package/src/lib/external/index.ts

@@ -0,0 +1,8 @@
+/**
+ * External documentation functionality
+ * Re-exports all external-doc related functions and types
+ */
+
+export * from "./fetch"
+export * from "./policy"
+export type * from "./types"

package/src/lib/external/policy.ts

@@ -0,0 +1,308 @@
+import robotsParser from "robots-parser"
+
+import { EXTERNAL_DOC_USER_AGENT, fetchRobotsPolicy } from "./fetch"
+import type { ExternalPolicyEnv, RobotsPolicyResult } from "./types"
+
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"])
+const EXTERNAL_PATH_PREFIX = "/external/"
+const ROBOTS_CACHE_TTL_MS = 5 * 60 * 1000
+const ROBOTS_CACHE_MAX_ENTRIES = 1000
+const ROBOTS_INFLIGHT_MAX_ENTRIES = 1000
+const robotsPolicyCache = new Map<string, { expiresAt: number; policy: RobotsPolicyResult }>()
+const robotsPolicyInFlight = new Map<string, Promise<RobotsPolicyResult>>()
+
+export class ExternalAccessError extends Error {
+  status: number
+
+  constructor(message: string, status: number = 403) {
+    super(message)
+    this.name = "ExternalAccessError"
+    this.status = status
+  }
+}
+
+export function validateExternalDocumentationUrl(rawUrl: string): URL {
+  if (!rawUrl || hasControlOrWhitespace(rawUrl)) {
+    throw new ExternalAccessError("Invalid external URL.", 400)
+  }
+
+  let parsedUrl: URL
+
+  try {
+    parsedUrl = new URL(rawUrl)
+  } catch {
+    throw new ExternalAccessError("Invalid external URL.", 400)
+  }
+
+  if (parsedUrl.protocol !== "https:") {
+    throw new ExternalAccessError("Only https:// external URLs are supported.", 400)
+  }
+
+  if (parsedUrl.username || parsedUrl.password) {
+    throw new ExternalAccessError("Credentialed URLs are not supported.", 400)
+  }
+
+  if (parsedUrl.hash) {
+    throw new ExternalAccessError("URL fragments are not supported.", 400)
+  }
+
+  return parsedUrl
+}
+
+export function decodeExternalTargetPath(path: string): string {
+  if (!path.startsWith(EXTERNAL_PATH_PREFIX)) {
+    throw new ExternalAccessError("Invalid external URL.", 400)
+  }
+
+  const encodedTarget = path.slice(EXTERNAL_PATH_PREFIX.length)
+  if (!encodedTarget) {
+    throw new ExternalAccessError("Invalid external URL.", 400)
+  }
+
+  try {
+    const decodedTarget = decodeURIComponent(encodedTarget)
+    if (!decodedTarget || hasControlOrWhitespace(decodedTarget)) {
+      throw new ExternalAccessError("Invalid external URL.", 400)
+    }
+    return decodedTarget
+  } catch {
+    throw new ExternalAccessError("Invalid external URL.", 400)
+  }
+}
+
+export async function assertExternalDocumentationAccess(
+  targetUrl: URL,
+  env: ExternalPolicyEnv,
+): Promise<void> {
+  assertHostPolicy(targetUrl, env)
+  const robotsAllowed = await isAllowedByRobotsTxt(targetUrl)
+  if (!robotsAllowed) {
+    throw new ExternalAccessError("External host denied access for this path via robots.txt.", 403)
+  }
+}
+
+function assertHostPolicy(targetUrl: URL, env: ExternalPolicyEnv): void {
+  const hostname = targetUrl.hostname.toLowerCase()
+  const allowlist = parseHostList(env.EXTERNAL_DOC_HOST_ALLOWLIST)
+  const blocklist = parseHostList(env.EXTERNAL_DOC_HOST_BLOCKLIST)
+  const explicitlyAllowlisted = isHostListed(hostname, allowlist)
+
+  if (isHostListed(hostname, blocklist)) {
+    throw new ExternalAccessError("External host is blocked by configuration.", 403)
+  }
+
+  if (allowlist.size > 0 && !explicitlyAllowlisted) {
+    throw new ExternalAccessError("External host is not allowlisted.", 403)
+  }
+
+  if (isLocalOrPrivateHost(hostname) && !explicitlyAllowlisted) {
+    // This blocks obvious local/private hostnames, but DNS rebinding on public hostnames
+    // still requires explicit allowlists for strict SSRF protection in runtimes without DNS resolution APIs.
+    throw new ExternalAccessError(
+      "External URL points to a local or private host and is not allowlisted.",
+      403,
+    )
+  }
+}
+
+async function isAllowedByRobotsTxt(targetUrl: URL): Promise<boolean> {
+  const policy = await getRobotsPolicy(targetUrl.origin)
+  if (policy.kind === "allow-all") {
+    return true
+  }
+  if (policy.kind === "deny-all") {
+    return false
+  }
+  if (policy.kind === "rules") {
+    return evaluateRobotsPolicy(policy.robotsText, targetUrl, EXTERNAL_DOC_USER_AGENT)
+  }
+  return true
+}
+
+function evaluateRobotsPolicy(robotsText: string, targetUrl: URL, userAgent: string): boolean {
+  const robots = robotsParser(new URL("/robots.txt", targetUrl.origin).toString(), robotsText)
+  const isAllowed = robots.isAllowed(targetUrl.toString(), userAgent)
+  return isAllowed !== false
+}
+
+function parseHostList(rawList: string | undefined): Set<string> {
+  if (!rawList) {
+    return new Set()
+  }
+
+  return new Set(
+    rawList
+      .split(/\r?\n|,/)
+      .map((value) => value.trim().toLowerCase())
+      .filter(Boolean),
+  )
+}
+
+function getRootOrigin(origin: string): string | null {
+  try {
+    const url = new URL(origin)
+    const labels = url.hostname.toLowerCase().split(".")
+    if (labels.length < 3) {
+      return null
+    }
+    const rootHost = labels.slice(-2).join(".")
+    return `${url.protocol}//${rootHost}`
+  } catch {
+    return null
+  }
+}
+
+async function getRobotsPolicy(origin: string): Promise<RobotsPolicyResult> {
+  const now = Date.now()
+  pruneExpiredRobotsPolicyEntries(now)
+
+  const cached = robotsPolicyCache.get(origin)
+  if (cached && cached.expiresAt > now) {
+    return cached.policy
+  }
+
+  const inFlight = robotsPolicyInFlight.get(origin)
+  if (inFlight) {
+    return inFlight
+  }
+
+  const request = (async (): Promise<RobotsPolicyResult> => {
+    let policy = await fetchRobotsPolicy(origin, EXTERNAL_DOC_USER_AGENT)
+    if (policy.kind === "not-found") {
+      const rootOrigin = getRootOrigin(origin)
+      if (rootOrigin && rootOrigin !== origin) {
+        const rootPolicy = await fetchRobotsPolicy(rootOrigin, EXTERNAL_DOC_USER_AGENT)
+        if (rootPolicy.kind !== "not-found") {
+          policy = rootPolicy
+        } else {
+          policy = { kind: "allow-all" }
+        }
+      } else {
+        policy = { kind: "allow-all" }
+      }
+    }
+    return policy
+  })()
+    .then((policy) => {
+      robotsPolicyCache.set(origin, {
+        expiresAt: Date.now() + ROBOTS_CACHE_TTL_MS,
+        policy,
+      })
+      enforceMaxMapEntries(robotsPolicyCache, ROBOTS_CACHE_MAX_ENTRIES)
+      return policy
+    })
+    .finally(() => {
+      robotsPolicyInFlight.delete(origin)
+    })
+
+  enforceMaxMapEntries(robotsPolicyInFlight, ROBOTS_INFLIGHT_MAX_ENTRIES, origin)
+  robotsPolicyInFlight.set(origin, request)
+  return request
+}
+
+function isHostListed(hostname: string, list: Set<string>): boolean {
+  if (list.has(hostname)) {
+    return true
+  }
+
+  for (const candidate of list) {
+    if (candidate.startsWith(".")) {
+      if (hostname.endsWith(candidate)) {
+        return true
+      }
+      continue
+    }
+
+    if (hostname === candidate || hostname.endsWith(`.${candidate}`)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+function pruneExpiredRobotsPolicyEntries(now: number): void {
+  for (const [origin, entry] of robotsPolicyCache.entries()) {
+    if (entry.expiresAt <= now) {
+      robotsPolicyCache.delete(origin)
+    }
+  }
+}
+
+function enforceMaxMapEntries<K, V>(map: Map<K, V>, maxEntries: number, incomingKey?: K): void {
+  while (
+    map.size > maxEntries ||
+    (incomingKey !== undefined && map.size >= maxEntries && !map.has(incomingKey))
+  ) {
+    const oldestKey = map.keys().next().value
+    if (oldestKey === undefined) {
+      break
+    }
+    map.delete(oldestKey)
+  }
+}
+
+function isLocalOrPrivateHost(hostname: string): boolean {
+  if (LOCAL_HOSTNAMES.has(hostname)) {
+    return true
+  }
+
+  if (hostname.endsWith(".local")) {
+    return true
+  }
+
+  if (isPrivateIPv4(hostname)) {
+    return true
+  }
+
+  if (isPrivateIPv6(hostname)) {
+    return true
+  }
+
+  return false
+}
+
+function isPrivateIPv4(hostname: string): boolean {
+  const octets = hostname.split(".")
+  if (octets.length !== 4 || octets.some((octet) => !/^\d{1,3}$/.test(octet))) {
+    return false
+  }
+
+  const octetNumbers = octets.map((octet) => Number.parseInt(octet, 10))
+  if (octetNumbers.some((value) => value > 255)) {
+    return false
+  }
+  const [a, b] = octetNumbers
+
+  return (
+    a === 10 ||
+    a === 127 ||
+    a === 0 ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168)
+  )
+}
+
+function isPrivateIPv6(hostname: string): boolean {
+  const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, "")
+  return (
+    normalized === "::1" ||
+    normalized.startsWith("fc") ||
+    normalized.startsWith("fd") ||
+    normalized.startsWith("fe8") ||
+    normalized.startsWith("fe9") ||
+    normalized.startsWith("fea") ||
+    normalized.startsWith("feb")
+  )
+}
+
+function hasControlOrWhitespace(value: string): boolean {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index)
+    if (code <= 0x20 || code === 0x7f) {
+      return true
+    }
+  }
+  return false
+}

package/src/lib/external/types.ts

@@ -0,0 +1,10 @@
+export type RobotsPolicyResult =
+  | { kind: "allow-all" }
+  | { kind: "deny-all" }
+  | { kind: "not-found" }
+  | { kind: "rules"; robotsText: string }
+
+export interface ExternalPolicyEnv {
+  EXTERNAL_DOC_HOST_ALLOWLIST?: string
+  EXTERNAL_DOC_HOST_BLOCKLIST?: string
+}

package/src/lib/fetch.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared fetching utilities for Apple Developer documentation
+ * Contains common utilities used by both HIG and reference documentation
+ */
+
+export class NotFoundError extends Error {}
+
+const USER_AGENTS = [
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.2.20",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.3 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3.1 Safari/605.7.24",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1.2 Safari/605.1.15 Reeder/5.4",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.3.1 Safari/605.1.1",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.1 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.6.1 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_3_9; en) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1.6 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.7.24",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.4.24",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.7.23",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_3) AppleWebKit/537.75.14 (KHTML, like Gecko) Version/7.0.3 Safari/7046A194A",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.2 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_16) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/17618.1.15.111.8",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_3) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Safari/605.1.15",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.6.24",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/618.2.7 (KHTML, like Gecko) Version/17.5 Safari/618.2.7",
+  "Mozilla/5.0 (iPhone; U; CPU iPhone OS 4_3 like Mac OS X; de-de) AppleWebKit/533.17.9 (KHTML, like Gecko) Mobile/8F190",
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1",
+  "Mozilla/5.0 (iPad; CPU OS 8_4_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12H321 Safari/600.1.4",
+  "Mozilla/5.0 (iPhone; CPU iPhone OS 11_0_3 like Mac OS X) AppleWebKit/604.1.38 (KHTML, like Gecko) Version/10.1 Mobile/15A432 Safari/602.1",
+] as const
+
+/**
+ * Get a random Safari user agent
+ */
+export function getRandomUserAgent(): string {
+  const randomIndex = Math.floor(Math.random() * USER_AGENTS.length)
+  return USER_AGENTS[randomIndex]
+}

package/src/lib/hig/fetch.ts

@@ -0,0 +1,186 @@
+/**
+ * Human Interface Guidelines (HIG) fetching functionality
+ */
+
+import { getRandomUserAgent, NotFoundError } from "../fetch"
+import type { HIGPageJSON, HIGTableOfContents } from "./types"
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+/**
+ * Base URL for HIG JSON API
+ */
+const HIG_BASE_URL = "https://developer.apple.com/tutorials/data"
+
+// ============================================================================
+// FETCHING FUNCTIONS
+// ============================================================================
+
+/**
+ * Fetch the complete HIG table of contents
+ */
+export async function fetchHIGTableOfContents(): Promise<HIGTableOfContents> {
+  const tocUrl = `${HIG_BASE_URL}/index/design--human-interface-guidelines`
+
+  const userAgent = getRandomUserAgent()
+
+  const response = await fetch(tocUrl, {
+    headers: {
+      "User-Agent": userAgent,
+      Accept: "application/json",
+      "Cache-Control": "no-cache",
+    },
+  })
+
+  if (!response.ok) {
+    console.error(`Failed to fetch HIG ToC: ${response.status} ${response.statusText}`)
+    if (response.status === 404) {
+      throw new NotFoundError(`HIG table of contents not found at ${tocUrl}`)
+    }
+    throw new Error(`Failed to fetch HIG ToC: ${response.status} ${response.statusText}`)
+  }
+
+  const data = (await response.json()) as HIGTableOfContents
+  return data
+}
+
+/**
+ * Fetch HIG page content by path
+ *
+ * @param path - The HIG path (e.g., "getting-started", "foundations/color")
+ * @returns HIG page JSON data
+ */
+export async function fetchHIGPageData(path: string): Promise<HIGPageJSON> {
+  // Normalize the path - remove leading/trailing slashes
+  const normalizedPath = path.replace(/^\/+|\/+$/g, "")
+
+  // Construct the full JSON URL
+  const jsonUrl = `${HIG_BASE_URL}/design/human-interface-guidelines/${normalizedPath}.json`
+
+  const userAgent = getRandomUserAgent()
+
+  const response = await fetch(jsonUrl, {
+    headers: {
+      "User-Agent": userAgent,
+      Accept: "application/json",
+      "Cache-Control": "no-cache",
+    },
+  })
+
+  if (!response.ok) {
+    console.error(`Failed to fetch HIG page: ${response.status} ${response.statusText}`)
+    if (response.status === 404) {
+      throw new NotFoundError(`HIG page not found at ${jsonUrl}`)
+    }
+    throw new Error(`Failed to fetch HIG page: ${response.status} ${response.statusText}`)
+  }
+
+  const data = (await response.json()) as HIGPageJSON
+  return data
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Extract all available HIG paths from the table of contents
+ *
+ * @param toc - The HIG table of contents
+ * @returns Array of all available paths
+ */
+export function extractHIGPaths(toc: HIGTableOfContents): string[] {
+  const paths: string[] = []
+
+  function extractFromItems(items: typeof toc.interfaceLanguages.swift) {
+    for (const item of items) {
+      if (item.path) {
+        // Remove the leading "/design/human-interface-guidelines/" prefix
+        const normalizedPath = item.path.replace(/^\/design\/human-interface-guidelines\//, "")
+        if (normalizedPath) {
+          paths.push(normalizedPath)
+        }
+      }
+
+      if (item.children) {
+        extractFromItems(item.children)
+      }
+    }
+  }
+
+  extractFromItems(toc.interfaceLanguages.swift)
+  return paths
+}
+
+/**
+ * Find a specific HIG item in the table of contents by path
+ *
+ * @param toc - The HIG table of contents
+ * @param targetPath - The path to search for
+ * @returns The HIG item if found, undefined otherwise
+ */
+export function findHIGItemByPath(
+  toc: HIGTableOfContents,
+  targetPath: string,
+): (typeof toc.interfaceLanguages.swift)[0] | undefined {
+  const normalizedTarget = targetPath.replace(/^\/+|\/+$/g, "")
+
+  function searchInItems(
+    items: typeof toc.interfaceLanguages.swift,
+  ): (typeof items)[0] | undefined {
+    for (const item of items) {
+      const normalizedItemPath = item.path
+        .replace(/^\/design\/human-interface-guidelines\//, "")
+        .replace(/^\/+|\/+$/g, "")
+
+      if (normalizedItemPath === normalizedTarget) {
+        return item
+      }
+
+      if (item.children) {
+        const found = searchInItems(item.children)
+        if (found) return found
+      }
+    }
+    return undefined
+  }
+
+  return searchInItems(toc.interfaceLanguages.swift)
+}
+
+/**
+ * Get breadcrumb path for a HIG item
+ *
+ * @param toc - The HIG table of contents
+ * @param targetPath - The path to get breadcrumbs for
+ * @returns Array of titles representing the breadcrumb path
+ */
+export function getHIGBreadcrumbs(toc: HIGTableOfContents, targetPath: string): string[] {
+  const normalizedTarget = targetPath.replace(/^\/+|\/+$/g, "")
+
+  function findBreadcrumbs(
+    items: typeof toc.interfaceLanguages.swift,
+    currentPath: string[] = [],
+  ): string[] | null {
+    for (const item of items) {
+      const normalizedItemPath = item.path
+        .replace(/^\/design\/human-interface-guidelines\//, "")
+        .replace(/^\/+|\/+$/g, "")
+      const newPath = [...currentPath, item.title]
+
+      if (normalizedItemPath === normalizedTarget) {
+        return newPath
+      }
+
+      if (item.children) {
+        const found = findBreadcrumbs(item.children, newPath)
+        if (found) return found
+      }
+    }
+    return null
+  }
+
+  return findBreadcrumbs(toc.interfaceLanguages.swift) || []
+}

package/src/lib/hig/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Human Interface Guidelines (HIG) functionality
+ * Re-exports all HIG-related functions and types
+ */
+
+export * from "./fetch"
+export * from "./render"
+export type * from "./types"
+export { hasChildren, isHIGImageReference, isHIGTopicReference } from "./util"