@nshipster/sosumi 1.0.5 → 1.0.7

package/src/lib/reference/render.ts

@@ -2,11 +2,24 @@
  * Apple Developer Reference documentation rendering functionality
  */
 
+import {
+  CONTENT_TOO_DEEP,
+  formatCallout,
+  formatCodeBlock,
+  formatList,
+  formatTable,
+  INLINE_CONTENT_TOO_DEEP,
+  MAX_CONTENT_DEPTH,
+  MAX_INLINE_DEPTH,
+  mapAsideStyleToCallout,
+} from "../markdown"
+import { extractTitleFromIdentifier } from "../url"
 import type {
   AppleDocJSON,
   ContentItem,
   Declaration,
   IndexContentItem,
+  Platform,
   PossibleValueItem,
   PropertyItem,
   TopicSection,
@@ -67,6 +80,8 @@ export async function renderFromJSON(
     }
   }
 
+  markdown += renderDeprecationNotice(jsonData, jsonData.references, options.externalOrigin)
+
   // Add declaration
   if (jsonData.primaryContentSections) {
     const declarationSection = jsonData.primaryContentSections.find(
@@ -193,6 +208,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`
@@ -228,14 +247,6 @@ 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)
@@ -392,9 +403,9 @@ function renderContentArray(
   externalOrigin?: string,
 ): string {
   // Prevent infinite recursion by limiting depth
-  if (depth > 50) {
+  if (depth > MAX_CONTENT_DEPTH) {
     console.warn("Maximum recursion depth reached in renderContentArray")
-    return "[Content too deeply nested]"
+    return CONTENT_TOO_DEEP
   }
 
   let markdown = ""
@@ -406,53 +417,29 @@ function renderContentArray(
       markdown += `${hashes} ${item.text}\n\n`
     } else if (item.type === "paragraph") {
       if (item.inlineContent) {
-        const text = renderInlineContent(item.inlineContent, references, depth, externalOrigin)
+        // Inline nesting is counted separately from block nesting, so a
+        // paragraph's inline content starts a fresh depth budget.
+        const text = renderInlineContent(item.inlineContent, references, 0, externalOrigin)
         markdown += `${text}\n\n`
       }
     } else if (item.type === "codeListing") {
-      let code = ""
-      if (Array.isArray(item.code)) {
-        code = item.code.join("\n")
-      } else {
-        code = String(item.code || "")
-      }
-      const syntax = normalizeFenceLanguage(item.syntax || "swift")
-
-      markdown += `\`\`\`${syntax}\n${code}\n\`\`\`\n\n`
-    } else if (item.type === "unorderedList") {
+      markdown += formatCodeBlock(item.code, item.syntax)
+    } else if (item.type === "unorderedList" || item.type === "orderedList") {
       if (item.items) {
-        for (const listItem of item.items) {
-          const itemText = renderContentArray(
-            listItem.content || [],
-            references,
-            depth + 1,
-            externalOrigin,
-          )
-          markdown += `- ${itemText.replace(/\n\n$/, "")}\n`
-        }
-        markdown += "\n"
-      }
-    } else if (item.type === "orderedList") {
-      if (item.items) {
-        item.items.forEach((listItem: ContentItem, index: number) => {
-          const itemText = renderContentArray(
-            listItem.content || [],
-            references,
-            depth + 1,
-            externalOrigin,
-          )
-          markdown += `${index + 1}. ${itemText.replace(/\n\n$/, "")}\n`
-        })
-        markdown += "\n"
+        markdown += formatList(
+          item.items.map((listItem) =>
+            renderContentArray(listItem.content || [], references, depth + 1, externalOrigin),
+          ),
+          item.type === "orderedList",
+        )
       }
     } else if (item.type === "aside") {
       const style = item.style || "note"
-      const calloutType = mapAsideStyleToCallout(style)
       const asideContent = item.content
         ? renderContentArray(item.content, references, depth + 1, externalOrigin)
         : ""
-      const cleanContent = asideContent.trim().replace(/\n/g, "\n> ")
-      markdown += `> [!${calloutType}]\n> ${cleanContent}\n\n`
+      const lead = style.toLowerCase() === "deprecated" ? DEPRECATED_LEAD : undefined
+      markdown += formatCallout(mapAsideStyleToCallout(style), asideContent, lead)
     } else if (item.type === "table") {
       markdown += renderTable(item, references, depth, externalOrigin)
     } else if (item.type === "tabNavigator" && item.tabs?.length) {
@@ -499,27 +486,17 @@ function renderTable(
     header?: string
     rows?: ContentItem[][][] // rows[rowIndex][cellIndex] = ContentItem[]
   }
-  const rows = table.rows ?? []
-  if (rows.length === 0) return ""
-
-  const escapeCell = (s: string) => s.replace(/\|/g, "\\|").replace(/\n/g, " ").trim()
-  const renderCell = (cell: ContentItem | ContentItem[]) => {
-    const items = Array.isArray(cell) ? cell : [cell]
-    const s = renderContentArray(items, references, depth + 1, externalOrigin)
-    return escapeCell(s)
-  }
-
-  const firstRowIsHeader = table.header === "row"
-  let markdown = ""
-  rows.forEach((row, rowIndex) => {
-    const cells = row.map((c) => renderCell(c))
-    if (cells.length === 0) return
-    markdown += `| ${cells.join(" | ")} |\n`
-    if (firstRowIsHeader && rowIndex === 0) {
-      markdown += `| ${cells.map(() => "---").join(" | ")} |\n`
-    }
-  })
-  return markdown ? `${markdown}\n` : ""
+  const rows = (table.rows ?? []).map((row) =>
+    row.map((cell) =>
+      renderContentArray(
+        Array.isArray(cell) ? cell : [cell],
+        references,
+        depth + 1,
+        externalOrigin,
+      ),
+    ),
+  )
+  return formatTable(rows, table.header === "row")
 }
 
 /**
@@ -532,9 +509,9 @@ function renderInlineContent(
   externalOrigin?: string,
 ): string {
   // Prevent infinite recursion by limiting depth
-  if (depth > 20) {
+  if (depth > MAX_INLINE_DEPTH) {
     console.warn("Maximum recursion depth reached in renderInlineContent")
-    return "[Inline content too deeply nested]"
+    return INLINE_CONTENT_TOO_DEEP
   }
 
   return inlineContent
@@ -544,9 +521,11 @@ function renderInlineContent(
       } else if (item.type === "codeVoice") {
         return `\`${item.code}\``
       } else if (item.type === "reference") {
+        const reference = item.identifier ? references?.[item.identifier] : undefined
         const title =
           item.title ||
           item.text ||
+          resolveReferenceTitle(reference, references, depth, externalOrigin) ||
           (item.identifier ? extractTitleFromIdentifier(item.identifier) : "")
         const url = item.identifier
           ? convertIdentifierToURL(item.identifier, references, externalOrigin)
@@ -569,6 +548,56 @@ function renderInlineContent(
     .join("")
 }
 
+/**
+ * Resolve the display title for a reference, preferring its rich
+ * `titleInlineContent` (which preserves code spans) over the flat `title`.
+ * When there is no rich title, wrap symbol titles in backticks so older DocC
+ * pages that omit `titleInlineContent` still render code spans in link text.
+ */
+function resolveReferenceTitle(
+  reference: ContentItem | undefined,
+  references?: Record<string, ContentItem>,
+  depth: number = 0,
+  externalOrigin?: string,
+): string | undefined {
+  if (reference?.titleInlineContent) {
+    return renderInlineContent(reference.titleInlineContent, references, depth + 1, externalOrigin)
+  }
+  if (reference?.title && reference.role === "symbol") {
+    return `\`${reference.title}\``
+  }
+  return reference?.title
+}
+
+interface ResolvedLink {
+  title: string
+  url: string
+  abstract: string
+  deprecated: boolean
+}
+
+/**
+ * Resolve an identifier to a Markdown link, drawing the title and abstract from
+ * the page's variants first, then the shared references map, and finally the
+ * identifier itself.
+ */
+function resolveLink(
+  id: string,
+  variants?: Variant[],
+  references?: Record<string, ContentItem>,
+  externalOrigin?: string,
+): ResolvedLink {
+  const info = variants?.find((v) => v.identifier === id)
+  const reference = references?.[id]
+  const title =
+    info?.title ||
+    resolveReferenceTitle(reference, references, 0, externalOrigin) ||
+    extractTitleFromIdentifier(id)
+  const url = convertIdentifierToURL(id, references, externalOrigin)
+  const abstract = (info?.abstract ?? reference?.abstract)?.map((a) => a.text).join("") ?? ""
+  return { title, url, abstract, deprecated: reference?.deprecated === true }
+}
+
 /**
  * Render relationship sections
  */
@@ -584,10 +613,7 @@ function renderRelationships(
     if (rel.title && rel.identifiers) {
       markdown += `## ${rel.title}\n\n`
       for (const id of rel.identifiers) {
-        const info = variants?.find((v: Variant) => v.identifier === id)
-        const reference = references?.[id]
-        const title = info?.title || reference?.title || extractTitleFromIdentifier(id)
-        const url = convertIdentifierToURL(id, references, externalOrigin)
+        const { title, url } = resolveLink(id, variants, references, externalOrigin)
         markdown += `- [${title}](${url})\n`
       }
       markdown += "\n"
@@ -611,33 +637,24 @@ function renderTopicSections(
   for (const topic of topics) {
     if (topic.title) {
       markdown += `## ${topic.title}\n\n`
+    }
 
-      if (topic.identifiers) {
-        for (const id of topic.identifiers) {
-          const info = variants?.find((v: Variant) => v.identifier === id)
-          const reference = references?.[id]
-          if (info || reference) {
-            const title = info?.title || reference?.title || extractTitleFromIdentifier(id)
-            const url = convertIdentifierToURL(id, references, externalOrigin)
-            const abstract = info?.abstract
-              ? info.abstract.map((a: { text: string }) => a.text).join("")
-              : reference?.abstract
-                ? reference.abstract.map((a: { text: string }) => a.text).join("")
-                : ""
-
-            markdown += `- [${title}](${url})`
-            if (abstract) {
-              markdown += ` ${abstract}`
-            }
-            markdown += "\n"
-          } else {
-            const title = extractTitleFromIdentifier(id)
-            const url = convertIdentifierToURL(id, references, externalOrigin)
-            markdown += `- [${title}](${url})\n`
-          }
+    if (topic.identifiers) {
+      for (const id of topic.identifiers) {
+        const { title, url, abstract, deprecated } = resolveLink(
+          id,
+          variants,
+          references,
+          externalOrigin,
+        )
+        const deprecatedLabel = deprecated ? " *(Deprecated)*" : ""
+        markdown += `- [${title}](${url})${deprecatedLabel}`
+        if (abstract) {
+          markdown += ` ${abstract}`
         }
         markdown += "\n"
       }
+      markdown += "\n"
     }
   }
 
@@ -712,10 +729,7 @@ function renderSeeAlso(
     if (section.title && section.identifiers) {
       markdown += `## ${section.title}\n\n`
       for (const id of section.identifiers) {
-        const info = variants?.find((v: Variant) => v.identifier === id)
-        const reference = references?.[id]
-        const title = info?.title || reference?.title || extractTitleFromIdentifier(id)
-        const url = convertIdentifierToURL(id, references, externalOrigin)
+        const { title, url } = resolveLink(id, variants, references, externalOrigin)
         markdown += `- [${title}](${url})\n`
       }
       markdown += "\n"
@@ -726,23 +740,101 @@ function renderSeeAlso(
 }
 
 /**
- * Map aside style to GitHub-style callout
+ * 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."
+
+/** Leading paragraph for callouts that flag deprecated APIs. */
+const DEPRECATED_LEAD = "**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 mapAsideStyleToCallout(style: string): string {
-  switch (style.toLowerCase()) {
-    case "warning":
-      return "WARNING"
-    case "important":
-      return "IMPORTANT"
-    case "caution":
-      return "CAUTION"
-    case "tip":
-      return "TIP"
-    case "deprecated":
-      return "WARNING"
-    default:
-      return "NOTE"
+function renderDeprecationNotice(
+  jsonData: AppleDocJSON,
+  references?: Record<string, ContentItem>,
+  externalOrigin?: string,
+): string {
+  const body = getDeprecationNoticeBody(jsonData, references, externalOrigin)
+  if (!body) {
+    return ""
   }
+
+  return formatCallout("WARNING", body, DEPRECATED_LEAD)
 }
 
 /**
@@ -788,34 +880,3 @@ function rewriteDocumentationPath(path: string | undefined, externalOrigin?: str
 
   return `/external/${externalOrigin}${path}`
 }
-
-/**
- * Extract title from identifier
- */
-export function extractTitleFromIdentifier(identifier: string): string {
-  const parts = identifier.split("/")
-  const lastPart = parts[parts.length - 1]
-
-  // Handle disambiguation suffixes (e.g., "body-8kl5o" -> "body", "init(exactly:)-63925" -> "init(exactly:)")
-  const disambiguationMatch = lastPart.match(/^(.+?)(?:-\w+)?$/)
-  if (disambiguationMatch) {
-    const baseName = disambiguationMatch[1]
-
-    // If it looks like a method signature (contains parentheses), preserve it
-    if (baseName.includes("(") && baseName.includes(")")) {
-      return baseName
-    }
-
-    // For simple identifiers, convert camelCase to readable format
-    return baseName
-      .replace(/([a-z])([A-Z])/g, "$1 $2")
-      .replace(/\s+/g, " ")
-      .trim()
-  }
-
-  // Fallback: convert camelCase to readable format
-  return lastPart
-    .replace(/([a-z])([A-Z])/g, "$1 $2")
-    .replace(/\s+/g, " ")
-    .trim()
-}