@nshipster/sosumi 1.0.5 → 1.0.6

package/package.json

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

package/src/lib/reference/render.ts

@@ -7,6 +7,7 @@ import type {
   ContentItem,
   Declaration,
   IndexContentItem,
+  Platform,
   PossibleValueItem,
   PropertyItem,
   TopicSection,
@@ -67,6 +68,8 @@ export async function renderFromJSON(
     }
   }
 
+  markdown += renderDeprecationNotice(jsonData, jsonData.references, options.externalOrigin)
+
   // Add declaration
   if (jsonData.primaryContentSections) {
     const declarationSection = jsonData.primaryContentSections.find(
@@ -193,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`
@@ -452,7 +459,8 @@ 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) {
@@ -625,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}`
             }
@@ -725,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
 }
 
 // ============================================================================
@@ -261,6 +264,10 @@ export interface Platform {
   name: string
   introducedAt: string
   beta?: boolean
+  deprecated?: boolean
+  deprecatedAt?: string
+  message?: string
+  unavailable?: boolean
 }
 
 /**
@@ -297,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