@nshipster/sosumi 1.0.6 → 1.0.8

package/src/lib/hig/render.ts

@@ -2,8 +2,19 @@
  * Human Interface Guidelines (HIG) rendering functionality
  */
 
-import { extractTitleFromIdentifier } from "../reference/render"
+import {
+  CONTENT_TOO_DEEP,
+  formatCallout,
+  formatCodeBlock,
+  formatList,
+  formatTable,
+  INLINE_CONTENT_TOO_DEEP,
+  MAX_CONTENT_DEPTH,
+  MAX_INLINE_DEPTH,
+  mapAsideStyleToCallout,
+} from "../markdown"
 import type { ContentItem, TextFragment } from "../types"
+import { extractTitleFromIdentifier } from "../url"
 import type {
   HIGExternalReference,
   HIGImageReference,
@@ -184,7 +195,14 @@ function generateHIGBreadcrumbs(sourceUrl: string): string {
 function renderHIGContent(
   content: ContentItem[],
   references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
 ): string {
+  // Prevent infinite recursion by limiting depth
+  if (depth > MAX_CONTENT_DEPTH) {
+    console.warn("Maximum recursion depth reached in renderHIGContent")
+    return CONTENT_TOO_DEEP
+  }
+
   let markdown = ""
 
   for (const item of content) {
@@ -212,7 +230,7 @@ function renderHIGContent(
       markdown += "\n"
     } else {
       // Handle other content types using the existing content renderer
-      markdown += renderContentItem(item, references)
+      markdown += renderContentItem(item, references, depth)
     }
   }
 
@@ -225,6 +243,7 @@ function renderHIGContent(
 function renderContentItem(
   item: ContentItem,
   references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
 ): string {
   let markdown = ""
 
@@ -234,36 +253,26 @@ function renderContentItem(
     markdown += `${hashes} ${item.text}\n\n`
   } else if (item.type === "paragraph") {
     if (item.inlineContent) {
+      // Inline nesting is counted separately from block nesting, so a
+      // paragraph's inline content starts a fresh depth budget.
       const text = renderHIGInlineContent(item.inlineContent, references)
       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 = item.syntax || "swift"
-    markdown += `\`\`\`${syntax}\n${code}\n\`\`\`\n\n`
-  } else if (item.type === "unorderedList" && item.items) {
-    for (const listItem of item.items) {
-      const itemText = renderHIGContent(listItem.content || [], references)
-      markdown += `- ${itemText.replace(/\n\n$/, "")}\n`
-    }
-    markdown += "\n"
-  } else if (item.type === "orderedList" && item.items) {
-    item.items.forEach((listItem: ContentItem, index: number) => {
-      const itemText = renderHIGContent(listItem.content || [], references)
-      markdown += `${index + 1}. ${itemText.replace(/\n\n$/, "")}\n`
-    })
-    markdown += "\n"
+    markdown += formatCodeBlock(item.code, item.syntax)
+  } else if ((item.type === "unorderedList" || item.type === "orderedList") && item.items) {
+    markdown += formatList(
+      item.items.map((listItem) => renderHIGContent(listItem.content || [], references, depth + 1)),
+      item.type === "orderedList",
+    )
   } else if (item.type === "table") {
-    markdown += renderHIGTable(item, references)
+    markdown += renderHIGTable(item, references, depth)
   } else if (item.type === "aside") {
-    markdown += renderHIGAside(item, references)
+    markdown += renderHIGAside(item, references, depth)
+  } else if (item.type === "tabNavigator") {
+    markdown += renderHIGTabNavigator(item, references, depth)
   } else if (item.type === "row") {
-    markdown += renderHIGRow(item, references)
+    markdown += renderHIGRow(item, references, depth)
   } else if (item.type === "video") {
     markdown += renderHIGVideo(item, references)
   }
@@ -278,34 +287,16 @@ function renderContentItem(
 function renderHIGTable(
   item: ContentItem,
   references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
 ): string {
   const table = item as ContentItem & {
     header?: string
     rows?: 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 text = renderHIGContent(items, references)
-    return escapeCell(text)
-  }
-
-  const firstRowIsHeader = table.header === "row"
-  let markdown = ""
-
-  rows.forEach((row, rowIndex) => {
-    const cells = row.map((cell) => renderCell(cell))
-    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) => renderHIGContent(Array.isArray(cell) ? cell : [cell], references, depth + 1)),
+  )
+  return formatTable(rows, table.header === "row")
 }
 
 /**
@@ -314,14 +305,49 @@ function renderHIGTable(
 function renderHIGAside(
   item: ContentItem,
   references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
 ): string {
   const aside = item as ContentItem & { style?: string; name?: string }
   const rawType = (aside.style || aside.name || "note").toLowerCase()
-  const calloutType = mapHIGAsideStyleToCallout(rawType)
-  const asideContent = item.content ? renderHIGContent(item.content, references) : ""
-  const cleanContent = asideContent.trim().replace(/\n/g, "\n> ")
-  if (!cleanContent) return ""
-  return `> [!${calloutType}]\n> ${cleanContent}\n\n`
+  const asideContent = item.content ? renderHIGContent(item.content, references, depth + 1) : ""
+  return formatCallout(mapAsideStyleToCallout(rawType), asideContent)
+}
+
+/**
+ * Render a HIG tabNavigator by flattening its tabs into a sequence.
+ * Only one tab is visible at a time on the web,
+ * so rendering them all keeps the content of every tab
+ * (such as the per-Dynamic Type size tables on the Typography page).
+ */
+function renderHIGTabNavigator(
+  item: ContentItem,
+  references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
+): string {
+  const tabs = item.tabs ?? []
+  if (tabs.length === 0) return ""
+
+  let markdown = ""
+  for (const tab of tabs) {
+    // Tabs usually repeat their title as a heading in their own content,
+    // so only add a label when the title would otherwise be lost.
+    // A leading heading only stands in for the label when it repeats the title,
+    // possibly with a qualifier, as in "Small" and "Small (default 38mm)".
+    const label = tab.title?.trim()
+    const first = tab.content?.[0]
+    const leadingHeading = first?.type === "heading" ? (first.text ?? "").trim() : undefined
+    const headingRepeatsTitle =
+      label !== undefined &&
+      leadingHeading !== undefined &&
+      leadingHeading.toLowerCase().startsWith(label.toLowerCase())
+    if (label && !headingRepeatsTitle) {
+      markdown += `**${label}**\n\n`
+    }
+    if (tab.content?.length) {
+      markdown += renderHIGContent(tab.content, references, depth + 1)
+    }
+  }
+  return markdown
 }
 
 /**
@@ -330,6 +356,7 @@ function renderHIGAside(
 function renderHIGRow(
   item: ContentItem,
   references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
 ): string {
   const row = item as ContentItem & {
     columns?: Array<{
@@ -341,7 +368,7 @@ function renderHIGRow(
   let markdown = ""
   for (const column of row.columns) {
     if (column.content && column.content.length > 0) {
-      markdown += renderHIGContent(column.content, references)
+      markdown += renderHIGContent(column.content, references, depth + 1)
     }
   }
   return markdown
@@ -389,7 +416,14 @@ function renderHIGVideo(
 function renderHIGInlineContent(
   inlineContent: ContentItem[],
   references: Record<string, HIGReference | HIGImageReference | HIGExternalReference>,
+  depth: number = 0,
 ): string {
+  // Prevent infinite recursion by limiting depth
+  if (depth > MAX_INLINE_DEPTH) {
+    console.warn("Maximum recursion depth reached in renderHIGInlineContent")
+    return INLINE_CONTENT_TOO_DEEP
+  }
+
   return inlineContent
     .map((item) => {
       if (item.type === "text") {
@@ -411,11 +445,15 @@ function renderHIGInlineContent(
         return `[${title}](${url})`
       } else if (item.type === "emphasis") {
         return `*${
-          item.inlineContent ? renderHIGInlineContent(item.inlineContent, references) : ""
+          item.inlineContent
+            ? renderHIGInlineContent(item.inlineContent, references, depth + 1)
+            : ""
         }*`
       } else if (item.type === "strong") {
         return `**${
-          item.inlineContent ? renderHIGInlineContent(item.inlineContent, references) : ""
+          item.inlineContent
+            ? renderHIGInlineContent(item.inlineContent, references, depth + 1)
+            : ""
         }**`
       } else if (item.type === "image" && item.identifier) {
         const reference = references[item.identifier]
@@ -471,23 +509,6 @@ function renderHIGTopicSections(
   return markdown
 }
 
-function mapHIGAsideStyleToCallout(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"
-  }
-}
-
 /**
  * Render HIG table of contents items
  */

package/src/lib/markdown.ts

@@ -0,0 +1,115 @@
+/**
+ * Markdown formatting and nesting limits shared by the reference and HIG
+ * renderers.
+ */
+
+/** Depth limit guarding against cyclic or pathologically nested block content. */
+export const MAX_CONTENT_DEPTH = 50
+
+/**
+ * Depth limit guarding against cyclic or pathologically nested inline content.
+ * Counted independently of block nesting, since inline content recurses on its
+ * own stack.
+ */
+export const MAX_INLINE_DEPTH = 20
+
+/** Emitted in place of block content that exceeds `MAX_CONTENT_DEPTH`. */
+export const CONTENT_TOO_DEEP = "[Content too deeply nested]"
+
+/** Emitted in place of inline content that exceeds `MAX_INLINE_DEPTH`. */
+export const INLINE_CONTENT_TOO_DEEP = "[Inline content too deeply nested]"
+
+/**
+ * Format rendered content as a Markdown list item, indenting continuation
+ * lines (including nested lists) under the marker.
+ */
+function formatListItem(marker: string, content: string): string {
+  const trimmed = content.replace(/\n+$/, "")
+  if (!trimmed) {
+    return `${marker.trimEnd()}\n`
+  }
+
+  // Collapse blank lines immediately before a nested list so it stays tight
+  // under its parent item; keep other paragraph breaks.
+  const tightened = trimmed.replace(/\n{2,}(?=(?:[-*]|\d+\.) )/g, "\n")
+  const indent = " ".repeat(marker.length)
+  const [first, ...rest] = tightened.split("\n")
+  const continuation = rest.map((line) => (line ? indent + line : ""))
+  return `${marker}${[first, ...continuation].join("\n")}\n`
+}
+
+/**
+ * Format pre-rendered item contents as a Markdown list, terminated by a blank
+ * line so following blocks aren't absorbed into the last item.
+ */
+export function formatList(itemContents: string[], ordered: boolean): string {
+  const items = itemContents.map((content, index) =>
+    formatListItem(ordered ? `${index + 1}. ` : "- ", content),
+  )
+  return `${items.join("")}\n`
+}
+
+/**
+ * Format a DocC code listing as a fenced code block, defaulting to Swift.
+ */
+export function formatCodeBlock(code?: string | string[], syntax?: string): string {
+  const body = Array.isArray(code) ? code.join("\n") : String(code || "")
+  // DocC uses `occ` for Objective-C internally, but highlighters expect `objc`.
+  const language = syntax === "occ" ? "objc" : syntax || "swift"
+  return `\`\`\`${language}\n${body}\n\`\`\`\n\n`
+}
+
+/**
+ * Format rendered cell contents as a Markdown table, escaping pipes and
+ * flattening newlines that would otherwise break a row.
+ */
+export function formatTable(rows: string[][], hasHeaderRow: boolean): string {
+  let markdown = ""
+  rows.forEach((row, index) => {
+    if (row.length === 0) return
+    const cells = row.map((cell) => cell.replace(/\|/g, "\\|").replace(/\n/g, " ").trim())
+    markdown += `| ${cells.join(" | ")} |\n`
+    if (hasHeaderRow && index === 0) {
+      markdown += `| ${cells.map(() => "---").join(" | ")} |\n`
+    }
+  })
+  return markdown ? `${markdown}\n` : ""
+}
+
+/**
+ * Format rendered content as a GitHub-style callout. An optional lead becomes
+ * the callout's first paragraph, ahead of the content.
+ */
+export function formatCallout(type: string, content: string, lead?: string): string {
+  const paragraphs = [lead, content.trim()].filter(Boolean)
+  if (paragraphs.length === 0) {
+    return ""
+  }
+
+  const quoted = paragraphs
+    .join("\n\n")
+    .split("\n")
+    .map((line) => (line ? `> ${line}` : ">"))
+    .join("\n")
+  return `> [!${type}]\n${quoted}\n\n`
+}
+
+/**
+ * Map a DocC aside style to a GitHub-style callout type.
+ */
+export 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"
+  }
+}