@bfra.me/doc-sync 0.1.0

package/src/generators/code-example-formatter.ts

@@ -0,0 +1,313 @@
+/**
+ * @bfra.me/doc-sync/generators/code-example-formatter - Syntax-highlighted code blocks from JSDoc examples
+ */
+
+import type {ExportedFunction, ExportedType, PackageAPI} from '../types'
+
+/**
+ * Options for code example formatting
+ */
+export interface CodeExampleOptions {
+  /** Default language for code blocks */
+  readonly defaultLanguage?: string
+  /** Whether to add function name as title */
+  readonly includeTitle?: boolean
+  /** Maximum number of examples per function */
+  readonly maxExamplesPerFunction?: number
+  /** Whether to wrap examples in collapsible sections */
+  readonly collapsible?: boolean
+}
+
+/**
+ * Default options for code example formatting
+ */
+const DEFAULT_OPTIONS: Required<CodeExampleOptions> = {
+  defaultLanguage: 'typescript',
+  includeTitle: true,
+  maxExamplesPerFunction: 3,
+  collapsible: false,
+}
+
+export function formatCodeExamples(api: PackageAPI, options: CodeExampleOptions = {}): string {
+  const mergedOptions = {...DEFAULT_OPTIONS, ...options}
+  const examples: string[] = []
+
+  for (const fn of api.functions) {
+    const fnExamples = formatFunctionExamples(fn, mergedOptions)
+    if (fnExamples.length > 0) {
+      examples.push(fnExamples)
+    }
+  }
+
+  for (const type of api.types) {
+    const typeExamples = formatTypeExamples(type, mergedOptions)
+    if (typeExamples.length > 0) {
+      examples.push(typeExamples)
+    }
+  }
+
+  return examples.join('\n\n')
+}
+
+export function formatFunctionExamples(
+  fn: ExportedFunction,
+  options: CodeExampleOptions = {},
+): string {
+  const mergedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  if (fn.jsdoc?.examples === undefined || fn.jsdoc.examples.length === 0) {
+    return ''
+  }
+
+  const exampleCount = Math.min(fn.jsdoc.examples.length, mergedOptions.maxExamplesPerFunction)
+  const examples = fn.jsdoc.examples.slice(0, exampleCount)
+
+  const sections: string[] = []
+
+  if (mergedOptions.includeTitle) {
+    sections.push(`### ${fn.name}`)
+    sections.push('')
+  }
+
+  for (const [index, example] of examples.entries()) {
+    const formattedExample = formatCodeBlock(example, mergedOptions.defaultLanguage)
+
+    if (mergedOptions.collapsible && examples.length > 1) {
+      sections.push(`<details>`)
+      sections.push(`<summary>Example ${index + 1}</summary>`)
+      sections.push('')
+      sections.push(formattedExample)
+      sections.push('')
+      sections.push(`</details>`)
+    } else {
+      sections.push(formattedExample)
+    }
+
+    if (index < examples.length - 1) {
+      sections.push('')
+    }
+  }
+
+  return sections.join('\n')
+}
+
+export function formatTypeExamples(type: ExportedType, options: CodeExampleOptions = {}): string {
+  const mergedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  if (type.jsdoc?.examples === undefined || type.jsdoc.examples.length === 0) {
+    return ''
+  }
+
+  const exampleCount = Math.min(type.jsdoc.examples.length, mergedOptions.maxExamplesPerFunction)
+  const examples = type.jsdoc.examples.slice(0, exampleCount)
+
+  const sections: string[] = []
+
+  if (mergedOptions.includeTitle) {
+    sections.push(`### ${type.name}`)
+    sections.push('')
+  }
+
+  for (const [index, example] of examples.entries()) {
+    const formattedExample = formatCodeBlock(example, mergedOptions.defaultLanguage)
+
+    if (mergedOptions.collapsible && examples.length > 1) {
+      sections.push(`<details>`)
+      sections.push(`<summary>Example ${index + 1}</summary>`)
+      sections.push('')
+      sections.push(formattedExample)
+      sections.push('')
+      sections.push(`</details>`)
+    } else {
+      sections.push(formattedExample)
+    }
+
+    if (index < examples.length - 1) {
+      sections.push('')
+    }
+  }
+
+  return sections.join('\n')
+}
+
+export function formatCodeBlock(code: string, language = 'typescript'): string {
+  const cleanedCode = cleanCodeExample(code)
+  const detectedLanguage = detectLanguage(cleanedCode) ?? language
+
+  return `\`\`\`${detectedLanguage}\n${cleanedCode}\n\`\`\``
+}
+
+export function cleanCodeExample(code: string): string {
+  let cleaned = code.trim()
+
+  if (cleaned.startsWith('```')) {
+    const lines = cleaned.split('\n')
+    lines.shift()
+    if (lines.at(-1)?.trim() === '```') {
+      lines.pop()
+    }
+    cleaned = lines.join('\n')
+  }
+
+  cleaned = cleaned
+    .split('\n')
+    .map(line => {
+      if (line.startsWith(' * ')) {
+        return line.slice(3)
+      }
+      if (line.startsWith('* ')) {
+        return line.slice(2)
+      }
+      return line
+    })
+    .join('\n')
+
+  const lines = cleaned.split('\n')
+  const nonEmptyLines = lines.filter(line => line.trim().length > 0)
+
+  if (nonEmptyLines.length === 0) {
+    return cleaned
+  }
+
+  const minIndent = Math.min(
+    ...nonEmptyLines.map(line => {
+      const match = /^(\s*)/.exec(line)
+      return match?.[1]?.length ?? 0
+    }),
+  )
+
+  if (minIndent > 0) {
+    cleaned = lines.map(line => line.slice(minIndent)).join('\n')
+  }
+
+  return cleaned.trim()
+}
+
+export function detectLanguage(code: string): string | undefined {
+  if (code.includes('import ') || code.includes('export ') || code.includes(': ')) {
+    if (code.includes('<') && code.includes('/>')) {
+      return 'tsx'
+    }
+    return 'typescript'
+  }
+
+  if (code.includes('const ') || code.includes('let ') || code.includes('function ')) {
+    if (code.includes('<') && code.includes('/>')) {
+      return 'jsx'
+    }
+    return 'javascript'
+  }
+
+  if (code.startsWith('{') || code.startsWith('[')) {
+    return 'json'
+  }
+
+  if (code.includes('$ ') || code.includes('npm ') || code.includes('pnpm ')) {
+    return 'bash'
+  }
+
+  return undefined
+}
+
+export function formatUsageExample(fn: ExportedFunction): string {
+  const params = fn.parameters.map(p => {
+    if (p.optional && p.defaultValue !== undefined) {
+      return `${p.name} = ${p.defaultValue}`
+    }
+    if (p.optional) {
+      return `${p.name}?`
+    }
+    return p.name
+  })
+
+  const call = `${fn.name}(${params.join(', ')})`
+
+  if (fn.isAsync) {
+    return `const result = await ${call}`
+  }
+
+  if (fn.returnType !== 'void') {
+    return `const result = ${call}`
+  }
+
+  return call
+}
+
+export function groupExamplesByCategory(
+  api: PackageAPI,
+): Map<string, {functions: ExportedFunction[]; types: ExportedType[]}> {
+  const categories = new Map<string, {functions: ExportedFunction[]; types: ExportedType[]}>()
+
+  for (const fn of api.functions) {
+    if (fn.jsdoc?.examples === undefined || fn.jsdoc.examples.length === 0) {
+      continue
+    }
+
+    const category = inferCategory(fn.name)
+    const existing = categories.get(category) ?? {functions: [], types: []}
+    existing.functions.push(fn)
+    categories.set(category, existing)
+  }
+
+  for (const type of api.types) {
+    if (type.jsdoc?.examples === undefined || type.jsdoc.examples.length === 0) {
+      continue
+    }
+
+    const category = inferCategory(type.name)
+    const existing = categories.get(category) ?? {functions: [], types: []}
+    existing.types.push(type)
+    categories.set(category, existing)
+  }
+
+  return categories
+}
+
+function inferCategory(name: string): string {
+  const prefixes = ['create', 'get', 'set', 'is', 'has', 'parse', 'format', 'validate', 'build']
+
+  for (const prefix of prefixes) {
+    if (name.toLowerCase().startsWith(prefix)) {
+      return capitalizeFirst(prefix)
+    }
+  }
+
+  return 'General'
+}
+
+function capitalizeFirst(str: string): string {
+  if (str.length === 0) return str
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+export function formatGroupedExamples(api: PackageAPI, options: CodeExampleOptions = {}): string {
+  const categories = groupExamplesByCategory(api)
+  const sections: string[] = []
+
+  for (const [category, items] of categories) {
+    sections.push(`### ${category}`)
+    sections.push('')
+
+    for (const fn of items.functions) {
+      const examples = formatFunctionExamples(fn, {...options, includeTitle: false})
+      if (examples.length > 0) {
+        sections.push(`#### \`${fn.name}\``)
+        sections.push('')
+        sections.push(examples)
+        sections.push('')
+      }
+    }
+
+    for (const type of items.types) {
+      const examples = formatTypeExamples(type, {...options, includeTitle: false})
+      if (examples.length > 0) {
+        sections.push(`#### \`${type.name}\``)
+        sections.push('')
+        sections.push(examples)
+        sections.push('')
+      }
+    }
+  }
+
+  return sections.join('\n').trim()
+}

package/src/generators/component-mapper.ts

@@ -0,0 +1,383 @@
+/**
+ * @bfra.me/doc-sync/generators/component-mapper - Map content sections to Starlight components
+ */
+
+import type {PackageInfo, ReadmeContent, ReadmeSection} from '../types'
+
+import {sanitizeAttribute} from '../utils/sanitization'
+
+/**
+ * Configuration for Starlight component mapping
+ */
+export interface ComponentMapperConfig {
+  /** Section titles that should use CardGrid for features */
+  readonly featureSections?: readonly string[]
+  /** Section titles that should use Tabs for installation */
+  readonly tabSections?: readonly string[]
+  /** Section titles to exclude from output */
+  readonly excludeSections?: readonly string[]
+  /** Custom component mappings by section title */
+  readonly customMappings?: Record<string, SectionMapper>
+}
+
+/**
+ * A function that maps section content to MDX output
+ */
+export type SectionMapper = (section: ReadmeSection, info: PackageInfo) => string
+
+/**
+ * Default configuration for component mapping
+ */
+const DEFAULT_CONFIG: Required<Omit<ComponentMapperConfig, 'customMappings'>> = {
+  featureSections: ['features', 'highlights', 'key features'],
+  tabSections: ['installation', 'getting started', 'setup'],
+  excludeSections: ['license', 'contributing', 'contributors', 'changelog'],
+}
+
+export function mapToStarlightComponents(
+  readme: ReadmeContent,
+  packageInfo: PackageInfo,
+  config: ComponentMapperConfig = {},
+): string {
+  const mergedConfig = {...DEFAULT_CONFIG, ...config}
+  const sections: string[] = []
+
+  if (readme.preamble !== undefined && readme.preamble.trim().length > 0) {
+    sections.push(readme.preamble)
+    sections.push('')
+  }
+
+  for (const section of readme.sections) {
+    const output = mapSection(section, packageInfo, mergedConfig)
+    if (output.length > 0) {
+      sections.push(output)
+      sections.push('')
+    }
+  }
+
+  return sections.join('\n').trim()
+}
+
+function mapSection(
+  section: ReadmeSection,
+  packageInfo: PackageInfo,
+  config: Required<Omit<ComponentMapperConfig, 'customMappings'>> &
+    Pick<ComponentMapperConfig, 'customMappings'>,
+): string {
+  const normalizedHeading = section.heading.toLowerCase().trim()
+
+  if (isExcludedSection(normalizedHeading, config.excludeSections, packageInfo)) {
+    return ''
+  }
+
+  if (config.customMappings?.[normalizedHeading] !== undefined) {
+    return config.customMappings[normalizedHeading](section, packageInfo)
+  }
+
+  if (isFeatureSection(normalizedHeading, config.featureSections)) {
+    return mapFeatureSection(section)
+  }
+
+  if (isInstallationSection(normalizedHeading, config.tabSections)) {
+    return mapInstallationSection(section, packageInfo)
+  }
+
+  return mapDefaultSection(section, packageInfo, config)
+}
+
+function isExcludedSection(
+  heading: string,
+  excludeSections: readonly string[],
+  packageInfo: PackageInfo,
+): boolean {
+  if (excludeSections.some(excluded => heading.includes(excluded.toLowerCase()))) {
+    return true
+  }
+
+  if (packageInfo.docsConfig?.excludeSections !== undefined) {
+    return packageInfo.docsConfig.excludeSections.some(excluded =>
+      heading.includes(excluded.toLowerCase()),
+    )
+  }
+
+  return false
+}
+
+function isFeatureSection(heading: string, featureSections: readonly string[]): boolean {
+  return featureSections.some(feature => heading.includes(feature.toLowerCase()))
+}
+
+function isInstallationSection(heading: string, tabSections: readonly string[]): boolean {
+  return tabSections.some(tab => heading.includes(tab.toLowerCase()))
+}
+
+function mapFeatureSection(section: ReadmeSection): string {
+  const lines: string[] = []
+
+  lines.push(`## ${section.heading}`)
+  lines.push('')
+
+  const features = extractFeatureItems(section.content)
+
+  if (features.length > 0) {
+    lines.push('<CardGrid>')
+    for (const feature of features) {
+      const icon = inferFeatureIcon(feature.title, feature.emoji)
+      lines.push(`  <Card title="${sanitizeAttribute(feature.title)}" icon="${icon}">`)
+      lines.push(`    ${feature.description}`)
+      lines.push('  </Card>')
+    }
+    lines.push('</CardGrid>')
+  } else {
+    lines.push(section.content)
+  }
+
+  return lines.join('\n')
+}
+
+interface FeatureItem {
+  readonly title: string
+  readonly description: string
+  readonly emoji?: string
+}
+
+const EMOJI_TO_ICON_MAP: Record<string, string> = {
+  '📝': 'document',
+  '📖': 'document',
+  '🔄': 'seti:refresh',
+  '👁️': 'eye-open',
+  '✨': 'star',
+  '🛡️': 'shield',
+  '🎨': 'seti:settings',
+  '🔒': 'lock',
+} as const
+
+function extractFeatureItems(content: string): FeatureItem[] {
+  const features: FeatureItem[] = []
+
+  // Uses specific character classes to prevent catastrophic backtracking
+  // Pattern breakdown:
+  // ^[-*] - list marker at start of line
+  // ([^*\r\n]*) - prefix (no asterisks or newlines)
+  // \*\*([^*\r\n]+)\*\* - bold text (must contain non-asterisk chars)
+  // [ ]?[:—–-][ ]? - separator with optional spaces
+  // ([^\r\n]+) - description (rest of line, no newlines)
+  const boldListPattern = /^[-*] ([^*\r\n]*)\*\*([^*\r\n]+)\*\* ?[:—–-] ?([^\r\n]+)$/gm
+
+  for (const match of content.matchAll(boldListPattern)) {
+    if (match[2] !== undefined && match[3] !== undefined) {
+      const prefix = match[1] ?? ''
+      const emoji = extractEmoji(prefix)
+
+      features.push({
+        title: match[2].trim(),
+        description: match[3].trim(),
+        emoji,
+      })
+    }
+  }
+
+  if (features.length === 0) {
+    const dashSeparatedPattern = /^[-*] ([^—–\n]+)[—–] (.+)$/gm
+
+    for (const match of content.matchAll(dashSeparatedPattern)) {
+      if (match[1] !== undefined && match[2] !== undefined) {
+        const rawTitle = match[1].trim()
+        const description = match[2].trim()
+        const emoji = extractEmoji(rawTitle)
+        const title = rawTitle.replace(
+          /^[\p{Emoji_Presentation}\p{Extended_Pictographic}]+\s*/u,
+          '',
+        )
+
+        if (title.length > 0 && description.length > 0 && description.length < 300) {
+          features.push({title, description, emoji})
+        }
+      }
+    }
+  }
+
+  // Tertiary fallback pattern: any bold text followed by description
+  if (features.length === 0) {
+    const boldPattern = /\*\*([^*]+)\*\*/g
+    const boldMatches = [...content.matchAll(boldPattern)]
+
+    for (const match of boldMatches) {
+      if (match[1] !== undefined) {
+        const title = match[1].trim()
+        const afterMatch = content.slice((match.index ?? 0) + match[0].length)
+        const description = afterMatch.split(/\n\n|\*\*/)[0]?.trim() ?? ''
+
+        if (description.length > 0 && description.length < 200) {
+          features.push({title, description})
+        }
+      }
+    }
+  }
+
+  return features
+}
+
+function extractEmoji(text: string): string | undefined {
+  const emojiMatch = text.match(/^[\p{Emoji_Presentation}\p{Extended_Pictographic}]+/u)
+  return emojiMatch?.[0]
+}
+
+function inferFeatureIcon(title: string, emoji?: string): string {
+  if (emoji !== undefined && EMOJI_TO_ICON_MAP[emoji] !== undefined) {
+    return EMOJI_TO_ICON_MAP[emoji]
+  }
+
+  const lowerTitle = title.toLowerCase()
+
+  const keywordIconMap: Record<string, string> = {
+    typescript: 'approve-check',
+    type: 'approve-check',
+    test: 'approve-check',
+    fast: 'rocket',
+    speed: 'rocket',
+    performance: 'rocket',
+    tree: 'seti:plan',
+    modular: 'puzzle',
+    plugin: 'puzzle',
+    extensible: 'puzzle',
+    document: 'document',
+    doc: 'document',
+    config: 'setting',
+    setting: 'setting',
+    star: 'star',
+    feature: 'star',
+    safe: 'approve-check',
+    secure: 'approve-check',
+    error: 'warning',
+    async: 'rocket',
+    result: 'approve-check',
+    function: 'puzzle',
+    watch: 'eye-open',
+    incremental: 'seti:refresh',
+    preservation: 'shield',
+    mdx: 'document',
+    parsing: 'document',
+  }
+
+  for (const [keyword, icon] of Object.entries(keywordIconMap)) {
+    if (lowerTitle.includes(keyword)) {
+      return icon
+    }
+  }
+
+  return 'star'
+}
+
+function mapInstallationSection(section: ReadmeSection, packageInfo: PackageInfo): string {
+  const lines: string[] = []
+
+  lines.push(`## ${section.heading}`)
+  lines.push('')
+
+  // Use word boundaries to avoid matching 'npm' within 'pnpm'
+  const hasPnpm = /\bpnpm\b/.test(section.content)
+  const hasNpm = /\bnpm\b/.test(section.content)
+  const hasYarn = /\byarn\b/.test(section.content)
+  const packageManagerCount = [hasPnpm, hasNpm, hasYarn].filter(Boolean).length
+
+  const hasExistingTabs = section.content.includes('```bash')
+  const hasMultiplePackageManagers = packageManagerCount >= 2
+
+  if (hasExistingTabs && hasMultiplePackageManagers) {
+    lines.push(section.content)
+  } else {
+    lines.push(generateInstallTabs(packageInfo.name))
+
+    const contentWithoutInstall = removeInstallCommand(section.content)
+    if (contentWithoutInstall.trim().length > 0) {
+      lines.push('')
+      lines.push(contentWithoutInstall)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+export function generateInstallTabs(packageName: string): string {
+  return `<Tabs>
+  <TabItem label="pnpm">
+    \`\`\`bash
+    pnpm add ${packageName}
+    \`\`\`
+  </TabItem>
+  <TabItem label="npm">
+    \`\`\`bash
+    npm install ${packageName}
+    \`\`\`
+  </TabItem>
+  <TabItem label="yarn">
+    \`\`\`bash
+    yarn add ${packageName}
+    \`\`\`
+  </TabItem>
+</Tabs>`
+}
+
+function removeInstallCommand(content: string): string {
+  return content
+    .replaceAll(/```(?:bash|sh)\n(?:npm|pnpm|yarn)\s+(?:install|add|i)\s+\S+\n```/g, '')
+    .trim()
+}
+
+function mapDefaultSection(
+  section: ReadmeSection,
+  packageInfo: PackageInfo,
+  config: Required<Omit<ComponentMapperConfig, 'customMappings'>> &
+    Pick<ComponentMapperConfig, 'customMappings'>,
+): string {
+  const lines: string[] = []
+
+  const headingLevel = '#'.repeat(Math.min(section.level + 1, 6))
+  lines.push(`${headingLevel} ${section.heading}`)
+  lines.push('')
+  lines.push(section.content)
+
+  for (const child of section.children) {
+    const childOutput = mapSection(child, packageInfo, config)
+    if (childOutput.length > 0) {
+      lines.push('')
+      lines.push(childOutput)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+export function createBadge(
+  text: string,
+  variant: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default' = 'note',
+): string {
+  return `<Badge text="${sanitizeAttribute(text)}" variant="${variant}" />`
+}
+
+export function createCard(title: string, content: string, icon?: string): string {
+  const iconAttr = icon === undefined ? '' : ` icon="${icon}"`
+  return `<Card title="${sanitizeAttribute(title)}"${iconAttr}>
+  ${content}
+</Card>`
+}
+
+export function createCardGrid(cards: {title: string; content: string; icon?: string}[]): string {
+  const cardElements = cards.map(card => createCard(card.title, card.content, card.icon))
+  return `<CardGrid>
+${cardElements.map(c => `  ${c}`).join('\n')}
+</CardGrid>`
+}
+
+export function createTabs(items: {label: string; content: string}[]): string {
+  const tabItems = items.map(
+    item => `  <TabItem label="${sanitizeAttribute(item.label)}">
+    ${item.content}
+  </TabItem>`,
+  )
+
+  return `<Tabs>
+${tabItems.join('\n')}
+</Tabs>`
+}