@nshipster/sosumi 1.0.4 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nshipster/sosumi",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Making Apple docs AI-readable",
   "license": "MIT",
   "author": "NSHipster",

package/src/lib/reference/render.ts

@@ -5,7 +5,9 @@
 import type {
   AppleDocJSON,
   ContentItem,
+  Declaration,
   IndexContentItem,
+  Platform,
   PossibleValueItem,
   PropertyItem,
   TopicSection,
@@ -66,6 +68,8 @@ export async function renderFromJSON(
     }
   }
 
+  markdown += renderDeprecationNotice(jsonData, jsonData.references, options.externalOrigin)
+
   // Add declaration
   if (jsonData.primaryContentSections) {
     const declarationSection = jsonData.primaryContentSections.find(
@@ -192,6 +196,10 @@ function generateFrontMatterFromJSON(jsonData: AppleDocJSON, sourceUrl: string):
   frontMatter.source = sourceUrl
   frontMatter.timestamp = new Date().toISOString()
 
+  if (isSymbolDeprecated(jsonData)) {
+    frontMatter.deprecated = "true"
+  }
+
   // Convert to YAML format
   const yamlLines = Object.entries(frontMatter).map(([key, value]) => `${key}: ${value}`)
   return `---\n${yamlLines.join("\n")}\n---\n\n`
@@ -227,10 +235,25 @@ function generateBreadcrumbs(sourceUrl: string, externalOrigin?: string): string
   return `${breadcrumbs}\n\n`
 }
 
+/**
+ * Map a DocC language code to a Markdown code-fence identifier. DocC uses
+ * `occ` for Objective-C internally, but Markdown highlighters expect `objc`.
+ */
+function normalizeFenceLanguage(syntax: string): string {
+  return syntax === "occ" ? "objc" : syntax
+}
+
+/**
+ * Tab titles DocC uses for language-variant code examples. Used to detect
+ * whether a `tabNavigator` is a language switch (so we can default to Swift)
+ * versus some other tabbed content we should leave alone.
+ */
+const LANGUAGE_TAB_TITLES = new Set(["Swift", "Objective-C"])
+
 /**
  * Render declaration sections
  */
-function renderDeclarations(declarations: Array<{ tokens?: Array<{ text?: string }> }>): string {
+function renderDeclarations(declarations: Declaration[]): string {
   let markdown = ""
 
   for (const decl of declarations) {
@@ -242,7 +265,8 @@ function renderDeclarations(declarations: Array<{ tokens?: Array<{ text?: string
         .join("")
         .trim()
 
-      markdown += `\`\`\`swift\n${code}\n\`\`\`\n\n`
+      const fence = decl.languages?.includes("occ") ? "objc" : "swift"
+      markdown += `\`\`\`${fence}\n${code}\n\`\`\`\n\n`
     }
   }
 
@@ -399,7 +423,7 @@ function renderContentArray(
       } else {
         code = String(item.code || "")
       }
-      const syntax = item.syntax || "swift"
+      const syntax = normalizeFenceLanguage(item.syntax || "swift")
 
       markdown += `\`\`\`${syntax}\n${code}\n\`\`\`\n\n`
     } else if (item.type === "unorderedList") {
@@ -435,14 +459,29 @@ function renderContentArray(
         ? renderContentArray(item.content, references, depth + 1, externalOrigin)
         : ""
       const cleanContent = asideContent.trim().replace(/\n/g, "\n> ")
-      markdown += `> [!${calloutType}]\n> ${cleanContent}\n\n`
+      const deprecatedLabel = style.toLowerCase() === "deprecated" ? "**Deprecated**\n>\n> " : ""
+      markdown += `> [!${calloutType}]\n> ${deprecatedLabel}${cleanContent}\n\n`
     } else if (item.type === "table") {
       markdown += renderTable(item, references, depth, externalOrigin)
     } else if (item.type === "tabNavigator" && item.tabs?.length) {
-      for (const tab of item.tabs) {
-        const label = tab.title?.trim()
-        if (label) {
-          markdown += `**${label}**\n\n`
+      // Only filter when every tab is a known language tab — otherwise
+      // `tabNavigator` may carry non-language content (e.g. platform or
+      // theme variants) that we shouldn't drop.
+      const allLanguageTabs = item.tabs.every(
+        (tab) => tab.title != null && LANGUAGE_TAB_TITLES.has(tab.title.trim()),
+      )
+      let tabsToRender = item.tabs
+      if (allLanguageTabs) {
+        const swiftTabs = item.tabs.filter((tab) => tab.title?.trim() === "Swift")
+        tabsToRender = swiftTabs.length > 0 ? swiftTabs : item.tabs
+      }
+      const showLabel = tabsToRender.length > 1
+      for (const tab of tabsToRender) {
+        if (showLabel) {
+          const label = tab.title?.trim()
+          if (label) {
+            markdown += `**${label}**\n\n`
+          }
         }
         if (tab.content?.length) {
           markdown += renderContentArray(tab.content, references, depth + 1, externalOrigin)
@@ -594,7 +633,8 @@ function renderTopicSections(
                 ? reference.abstract.map((a: { text: string }) => a.text).join("")
                 : ""
 
-            markdown += `- [${title}](${url})`
+            const deprecatedLabel = reference?.deprecated ? " *(Deprecated)*" : ""
+            markdown += `- [${title}](${url})${deprecatedLabel}`
             if (abstract) {
               markdown += ` ${abstract}`
             }
@@ -694,6 +734,102 @@ function renderSeeAlso(
   return markdown
 }
 
+/**
+ * Whether the symbol page represents a deprecated API.
+ */
+function isSymbolDeprecated(jsonData: AppleDocJSON): boolean {
+  return getDeprecationNoticeBody(jsonData, jsonData.references) !== null
+}
+
+/**
+ * Collect a deprecation message from platform availability metadata.
+ */
+function getDeprecationMessageFromPlatforms(platforms?: Platform[]): string | null {
+  if (!platforms?.length) {
+    return null
+  }
+
+  const deprecatedPlatforms = platforms.filter(
+    (platform) => platform.deprecated === true || platform.deprecatedAt,
+  )
+  if (deprecatedPlatforms.length === 0) {
+    return null
+  }
+
+  const uniqueMessages = [
+    ...new Set(
+      deprecatedPlatforms
+        .map((platform) => platform.message?.trim())
+        .filter((message): message is string => Boolean(message)),
+    ),
+  ]
+
+  if (uniqueMessages.length === 1) {
+    return uniqueMessages[0]
+  }
+
+  if (uniqueMessages.length > 1) {
+    return deprecatedPlatforms
+      .filter((platform) => platform.message)
+      .map((platform) => `**${platform.name}:** ${platform.message}`)
+      .join("\n")
+  }
+
+  return DEFAULT_DEPRECATION_MESSAGE
+}
+
+const DEFAULT_DEPRECATION_MESSAGE = "This symbol is deprecated."
+
+/**
+ * Resolve deprecation notice text from DocC JSON (without rendering the callout).
+ */
+function getDeprecationNoticeBody(
+  jsonData: AppleDocJSON,
+  references?: Record<string, ContentItem>,
+  externalOrigin?: string,
+): string | null {
+  if (jsonData.deprecationSummary?.length) {
+    const summary = renderContentArray(
+      jsonData.deprecationSummary,
+      references,
+      0,
+      externalOrigin,
+    ).trim()
+    if (summary) {
+      return summary
+    }
+  }
+
+  const platformMessage = getDeprecationMessageFromPlatforms(jsonData.metadata?.platforms)
+  if (platformMessage) {
+    return platformMessage
+  }
+
+  const identifier = jsonData.identifier?.url
+  if (identifier && references?.[identifier]?.deprecated === true) {
+    return DEFAULT_DEPRECATION_MESSAGE
+  }
+
+  return null
+}
+
+/**
+ * Render a deprecation callout for deprecated symbol pages.
+ */
+function renderDeprecationNotice(
+  jsonData: AppleDocJSON,
+  references?: Record<string, ContentItem>,
+  externalOrigin?: string,
+): string {
+  const body = getDeprecationNoticeBody(jsonData, references, externalOrigin)
+  if (!body) {
+    return ""
+  }
+
+  const quotedBody = body.replace(/\n/g, "\n> ")
+  return `> [!WARNING]\n> **Deprecated**\n>\n> ${quotedBody}\n\n`
+}
+
 /**
  * Map aside style to GitHub-style callout
  */

package/src/lib/types.ts

@@ -75,6 +75,9 @@ export interface ContentItem {
 
   // Abstract content
   abstract?: TextFragment[]
+
+  /** Present on reference entries for deprecated symbols. */
+  deprecated?: boolean
 }
 
 // ============================================================================
@@ -86,6 +89,7 @@ export interface ContentItem {
  */
 export interface Declaration {
   tokens?: Token[]
+  languages?: string[]
 }
 
 /**
@@ -260,6 +264,10 @@ export interface Platform {
   name: string
   introducedAt: string
   beta?: boolean
+  deprecated?: boolean
+  deprecatedAt?: string
+  message?: string
+  unavailable?: boolean
 }
 
 /**
@@ -296,6 +304,8 @@ export interface AppleDocJSON {
 
   // Content
   abstract?: Array<{ text: string; type: string }>
+  /** DocC deprecation notice shown at the top of deprecated symbol pages. */
+  deprecationSummary?: ContentItem[]
   sections?: ContentItem[]
 
   // Primary content sections