@bfra.me/doc-sync 0.1.0

package/src/generators/content-merger.ts

@@ -0,0 +1,295 @@
+/**
+ * @bfra.me/doc-sync/generators/content-merger - Preserve manual sections using sentinel markers
+ */
+
+import type {Result} from '@bfra.me/es/result'
+import type {SyncError} from '../types'
+
+import {err, ok} from '@bfra.me/es/result'
+import {SENTINEL_MARKERS} from '../types'
+
+/**
+ * A section of content extracted from MDX
+ */
+export interface ContentSection {
+  /** Section type */
+  readonly type: 'auto' | 'manual' | 'unchanged'
+  /** Section content */
+  readonly content: string
+  /** Start position in source */
+  readonly startIndex: number
+  /** End position in source */
+  readonly endIndex: number
+}
+
+/**
+ * Merge options
+ */
+export interface MergeOptions {
+  /** Strategy for handling conflicts */
+  readonly conflictStrategy?: 'keep-manual' | 'keep-auto' | 'merge'
+  /** Preserve empty manual sections */
+  readonly preserveEmptyManual?: boolean
+}
+
+/**
+ * Result of a merge operation
+ */
+export interface MergeResult {
+  /** Merged content */
+  readonly content: string
+  /** Number of manual sections preserved */
+  readonly preservedCount: number
+  /** Number of auto-generated sections updated */
+  readonly updatedCount: number
+  /** Whether content changed */
+  readonly hasChanges: boolean
+}
+
+export function mergeContent(
+  existingContent: string,
+  newContent: string,
+  options: MergeOptions = {},
+): Result<MergeResult, SyncError> {
+  const {conflictStrategy = 'keep-manual', preserveEmptyManual = true} = options
+
+  try {
+    const existingManualSections = extractManualSections(existingContent)
+    const newAutoSections = extractAutoSections(newContent)
+
+    if (existingManualSections.length === 0 && newAutoSections.length === 0) {
+      const hasChanges = existingContent.trim() !== newContent.trim()
+      return ok({
+        content: newContent,
+        preservedCount: 0,
+        updatedCount: hasChanges ? 1 : 0,
+        hasChanges,
+      })
+    }
+
+    let merged = newContent
+    let preservedCount = 0
+
+    for (const manual of existingManualSections) {
+      if (!preserveEmptyManual && manual.content.trim().length === 0) {
+        continue
+      }
+
+      const manualMarker = `${SENTINEL_MARKERS.MANUAL_START}\n${manual.content}\n${SENTINEL_MARKERS.MANUAL_END}`
+
+      if (!merged.includes(SENTINEL_MARKERS.MANUAL_START)) {
+        const autoEndIndex = merged.indexOf(SENTINEL_MARKERS.AUTO_END)
+        if (autoEndIndex === -1) {
+          merged = `${merged}\n\n${manualMarker}`
+        } else {
+          merged = `${merged.slice(0, autoEndIndex + SENTINEL_MARKERS.AUTO_END.length)}\n\n${manualMarker}\n${merged.slice(autoEndIndex + SENTINEL_MARKERS.AUTO_END.length)}`
+        }
+      } else if (conflictStrategy === 'keep-manual') {
+        const existingManualInNew = extractManualSections(merged)
+        if (existingManualInNew.length > 0) {
+          const firstManualInNew = existingManualInNew[0]
+          if (firstManualInNew !== undefined) {
+            merged = replaceSection(merged, firstManualInNew, manual.content)
+          }
+        }
+      }
+
+      preservedCount++
+    }
+
+    const hasChanges = existingContent.trim() !== merged.trim()
+
+    return ok({
+      content: merged,
+      preservedCount,
+      updatedCount: newAutoSections.length,
+      hasChanges,
+    })
+  } catch (error) {
+    return err({
+      code: 'GENERATION_ERROR',
+      message: `Failed to merge content: ${error instanceof Error ? error.message : String(error)}`,
+      cause: error,
+    })
+  }
+}
+
+export function extractManualSections(content: string): ContentSection[] {
+  const sections: ContentSection[] = []
+  let searchStart = 0
+
+  while (searchStart < content.length) {
+    const startIndex = content.indexOf(SENTINEL_MARKERS.MANUAL_START, searchStart)
+    if (startIndex === -1) break
+
+    const endIndex = content.indexOf(SENTINEL_MARKERS.MANUAL_END, startIndex)
+    if (endIndex === -1) break
+
+    const contentStart = startIndex + SENTINEL_MARKERS.MANUAL_START.length
+    const sectionContent = content.slice(contentStart, endIndex).trim()
+
+    sections.push({
+      type: 'manual',
+      content: sectionContent,
+      startIndex,
+      endIndex: endIndex + SENTINEL_MARKERS.MANUAL_END.length,
+    })
+
+    searchStart = endIndex + SENTINEL_MARKERS.MANUAL_END.length
+  }
+
+  return sections
+}
+
+export function extractAutoSections(content: string): ContentSection[] {
+  const sections: ContentSection[] = []
+  let searchStart = 0
+
+  while (searchStart < content.length) {
+    const startIndex = content.indexOf(SENTINEL_MARKERS.AUTO_START, searchStart)
+    if (startIndex === -1) break
+
+    const endIndex = content.indexOf(SENTINEL_MARKERS.AUTO_END, startIndex)
+    if (endIndex === -1) break
+
+    const contentStart = startIndex + SENTINEL_MARKERS.AUTO_START.length
+    const sectionContent = content.slice(contentStart, endIndex).trim()
+
+    sections.push({
+      type: 'auto',
+      content: sectionContent,
+      startIndex,
+      endIndex: endIndex + SENTINEL_MARKERS.AUTO_END.length,
+    })
+
+    searchStart = endIndex + SENTINEL_MARKERS.AUTO_END.length
+  }
+
+  return sections
+}
+
+function replaceSection(content: string, section: ContentSection, newContent: string): string {
+  const marker =
+    section.type === 'manual' ? SENTINEL_MARKERS.MANUAL_START : SENTINEL_MARKERS.AUTO_START
+  const endMarker =
+    section.type === 'manual' ? SENTINEL_MARKERS.MANUAL_END : SENTINEL_MARKERS.AUTO_END
+
+  const before = content.slice(0, section.startIndex)
+  const after = content.slice(section.endIndex)
+
+  return `${before}${marker}\n${newContent}\n${endMarker}${after}`
+}
+
+export function hasManualContent(content: string): boolean {
+  return content.includes(SENTINEL_MARKERS.MANUAL_START)
+}
+
+export function hasAutoContent(content: string): boolean {
+  return content.includes(SENTINEL_MARKERS.AUTO_START)
+}
+
+export function wrapManualSection(content: string): string {
+  return `${SENTINEL_MARKERS.MANUAL_START}\n${content}\n${SENTINEL_MARKERS.MANUAL_END}`
+}
+
+export function wrapAutoSection(content: string): string {
+  return `${SENTINEL_MARKERS.AUTO_START}\n${content}\n${SENTINEL_MARKERS.AUTO_END}`
+}
+
+export function stripSentinelMarkers(content: string): string {
+  return content
+    .replaceAll(SENTINEL_MARKERS.AUTO_START, '')
+    .replaceAll(SENTINEL_MARKERS.AUTO_END, '')
+    .replaceAll(SENTINEL_MARKERS.MANUAL_START, '')
+    .replaceAll(SENTINEL_MARKERS.MANUAL_END, '')
+    .replaceAll(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+export function validateMarkerPairing(content: string): Result<true, SyncError> {
+  const autoStartCount = countOccurrences(content, SENTINEL_MARKERS.AUTO_START)
+  const autoEndCount = countOccurrences(content, SENTINEL_MARKERS.AUTO_END)
+  const manualStartCount = countOccurrences(content, SENTINEL_MARKERS.MANUAL_START)
+  const manualEndCount = countOccurrences(content, SENTINEL_MARKERS.MANUAL_END)
+
+  if (autoStartCount !== autoEndCount) {
+    return err({
+      code: 'VALIDATION_ERROR',
+      message: `Mismatched AUTO-GENERATED markers: ${autoStartCount} starts, ${autoEndCount} ends`,
+    })
+  }
+
+  if (manualStartCount !== manualEndCount) {
+    return err({
+      code: 'VALIDATION_ERROR',
+      message: `Mismatched MANUAL-CONTENT markers: ${manualStartCount} starts, ${manualEndCount} ends`,
+    })
+  }
+
+  const autoNesting = checkNesting(content, SENTINEL_MARKERS.AUTO_START, SENTINEL_MARKERS.AUTO_END)
+  if (!autoNesting) {
+    return err({
+      code: 'VALIDATION_ERROR',
+      message: 'AUTO-GENERATED markers are improperly nested',
+    })
+  }
+
+  const manualNesting = checkNesting(
+    content,
+    SENTINEL_MARKERS.MANUAL_START,
+    SENTINEL_MARKERS.MANUAL_END,
+  )
+  if (!manualNesting) {
+    return err({
+      code: 'VALIDATION_ERROR',
+      message: 'MANUAL-CONTENT markers are improperly nested',
+    })
+  }
+
+  return ok(true)
+}
+
+function countOccurrences(content: string, substring: string): number {
+  let count = 0
+  let position = content.indexOf(substring, 0)
+
+  while (position !== -1) {
+    count++
+    position = content.indexOf(substring, position + substring.length)
+  }
+
+  return count
+}
+
+function checkNesting(content: string, startMarker: string, endMarker: string): boolean {
+  let depth = 0
+  let position = 0
+
+  while (position < content.length) {
+    const startPos = content.indexOf(startMarker, position)
+    const endPos = content.indexOf(endMarker, position)
+
+    if (startPos === -1 && endPos === -1) break
+
+    if (startPos !== -1 && (endPos === -1 || startPos < endPos)) {
+      depth++
+      position = startPos + startMarker.length
+    } else {
+      depth--
+      if (depth < 0) return false
+      position = endPos + endMarker.length
+    }
+  }
+
+  return depth === 0
+}
+
+export function createDiffSummary(oldContent: string, newContent: string): string {
+  const oldLines = oldContent.split('\n')
+  const newLines = newContent.split('\n')
+
+  const added = newLines.filter(line => !oldLines.includes(line)).length
+  const removed = oldLines.filter(line => !newLines.includes(line)).length
+
+  return `${added} lines added, ${removed} lines removed`
+}

package/src/generators/frontmatter-generator.ts

@@ -0,0 +1,277 @@
+/**
+ * @bfra.me/doc-sync/generators/frontmatter-generator - Starlight-compatible frontmatter generation
+ */
+
+import type {MDXFrontmatter, PackageInfo, ReadmeContent} from '../types'
+
+/**
+ * Mutable frontmatter for internal construction before freezing
+ */
+interface MutableFrontmatter {
+  title: string
+  description?: string
+  sidebar?: MDXFrontmatter['sidebar']
+  tableOfContents?: MDXFrontmatter['tableOfContents']
+  template?: MDXFrontmatter['template']
+  hero?: MDXFrontmatter['hero']
+}
+
+export function generateFrontmatter(
+  packageInfo: PackageInfo,
+  readme: ReadmeContent | undefined,
+  overrides?: Partial<MDXFrontmatter>,
+): MDXFrontmatter {
+  const title = resolveTitle(packageInfo, readme, overrides?.title)
+  const description = resolveDescription(packageInfo, readme, overrides?.description)
+
+  const frontmatter: MutableFrontmatter = {
+    title,
+    ...(description !== undefined && {description}),
+    ...(overrides?.sidebar !== undefined && {sidebar: overrides.sidebar}),
+    ...(overrides?.tableOfContents !== undefined && {tableOfContents: overrides.tableOfContents}),
+    ...(overrides?.template !== undefined && {template: overrides.template}),
+    ...(overrides?.hero !== undefined && {hero: overrides.hero}),
+  }
+
+  if (packageInfo.docsConfig?.sidebar !== undefined) {
+    frontmatter.sidebar = {
+      ...packageInfo.docsConfig.sidebar,
+      ...frontmatter.sidebar,
+    }
+  }
+
+  if (packageInfo.docsConfig?.frontmatter !== undefined) {
+    const customFrontmatter = packageInfo.docsConfig.frontmatter
+    return {...customFrontmatter, ...frontmatter} as MDXFrontmatter
+  }
+
+  return frontmatter as MDXFrontmatter
+}
+
+function resolveTitle(
+  packageInfo: PackageInfo,
+  readme: ReadmeContent | undefined,
+  override?: string,
+): string {
+  if (override !== undefined) {
+    return override
+  }
+
+  if (packageInfo.docsConfig?.title !== undefined) {
+    return packageInfo.docsConfig.title
+  }
+
+  if (readme?.title !== undefined) {
+    return readme.title
+  }
+
+  return packageInfo.name
+}
+
+function resolveDescription(
+  packageInfo: PackageInfo,
+  readme: ReadmeContent | undefined,
+  override?: string,
+): string | undefined {
+  if (override !== undefined) {
+    return override
+  }
+
+  if (packageInfo.docsConfig?.description !== undefined) {
+    return packageInfo.docsConfig.description
+  }
+
+  if (packageInfo.description !== undefined) {
+    return packageInfo.description
+  }
+
+  if (readme?.preamble !== undefined) {
+    return extractFirstSentence(readme.preamble)
+  }
+
+  return undefined
+}
+
+function extractFirstSentence(text: string): string {
+  const cleaned = text.trim().replaceAll(/\s+/g, ' ')
+
+  const sentenceEnd = cleaned.search(/[.!?](?:\s|$)/)
+  if (sentenceEnd > 0) {
+    return cleaned.slice(0, sentenceEnd + 1)
+  }
+
+  if (cleaned.length > 160) {
+    const truncated = cleaned.slice(0, 157)
+    const lastSpace = truncated.lastIndexOf(' ')
+    if (lastSpace > 100) {
+      return `${truncated.slice(0, lastSpace)}...`
+    }
+    return `${truncated}...`
+  }
+
+  return cleaned
+}
+
+export function stringifyFrontmatter(frontmatter: MDXFrontmatter): string {
+  const lines: string[] = []
+
+  lines.push(`title: ${yamlString(frontmatter.title)}`)
+
+  if (frontmatter.description !== undefined) {
+    lines.push(`description: ${yamlString(frontmatter.description)}`)
+  }
+
+  if (frontmatter.sidebar !== undefined) {
+    lines.push('sidebar:')
+    const sidebar = frontmatter.sidebar
+
+    if (sidebar.label !== undefined) {
+      lines.push(`  label: ${yamlString(sidebar.label)}`)
+    }
+
+    if (sidebar.order !== undefined) {
+      lines.push(`  order: ${sidebar.order}`)
+    }
+
+    if (sidebar.hidden !== undefined) {
+      lines.push(`  hidden: ${sidebar.hidden}`)
+    }
+
+    if (sidebar.badge !== undefined) {
+      if (typeof sidebar.badge === 'string') {
+        lines.push(`  badge: ${yamlString(sidebar.badge)}`)
+      } else {
+        lines.push('  badge:')
+        lines.push(`    text: ${yamlString(sidebar.badge.text)}`)
+        if (sidebar.badge.variant !== undefined) {
+          lines.push(`    variant: ${sidebar.badge.variant}`)
+        }
+      }
+    }
+  }
+
+  if (frontmatter.tableOfContents !== undefined) {
+    if (typeof frontmatter.tableOfContents === 'boolean') {
+      lines.push(`tableOfContents: ${frontmatter.tableOfContents}`)
+    } else {
+      lines.push('tableOfContents:')
+      if (frontmatter.tableOfContents.minHeadingLevel !== undefined) {
+        lines.push(`  minHeadingLevel: ${frontmatter.tableOfContents.minHeadingLevel}`)
+      }
+      if (frontmatter.tableOfContents.maxHeadingLevel !== undefined) {
+        lines.push(`  maxHeadingLevel: ${frontmatter.tableOfContents.maxHeadingLevel}`)
+      }
+    }
+  }
+
+  if (frontmatter.template !== undefined) {
+    lines.push(`template: ${frontmatter.template}`)
+  }
+
+  if (frontmatter.hero !== undefined) {
+    lines.push('hero:')
+    const hero = frontmatter.hero
+
+    if (hero.title !== undefined) {
+      lines.push(`  title: ${yamlString(hero.title)}`)
+    }
+
+    if (hero.tagline !== undefined) {
+      lines.push(`  tagline: ${yamlString(hero.tagline)}`)
+    }
+
+    if (hero.image !== undefined) {
+      lines.push('  image:')
+      lines.push(`    src: ${yamlString(hero.image.src)}`)
+      lines.push(`    alt: ${yamlString(hero.image.alt)}`)
+    }
+
+    if (hero.actions !== undefined && hero.actions.length > 0) {
+      lines.push('  actions:')
+      for (const action of hero.actions) {
+        lines.push(`    - text: ${yamlString(action.text)}`)
+        lines.push(`      link: ${yamlString(action.link)}`)
+        if (action.icon !== undefined) {
+          lines.push(`      icon: ${yamlString(action.icon)}`)
+        }
+        if (action.variant !== undefined) {
+          lines.push(`      variant: ${action.variant}`)
+        }
+      }
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function yamlString(value: string): string {
+  if (needsQuoting(value)) {
+    return `'${value.replaceAll("'", "''")}'`
+  }
+  return value
+}
+
+function needsQuoting(value: string): boolean {
+  if (value.length === 0) {
+    return true
+  }
+
+  if (value.startsWith(' ') || value.endsWith(' ')) {
+    return true
+  }
+
+  const specialChars = /[:#{}[\]&*?|<>=!%@`"',]/
+  if (specialChars.test(value)) {
+    return true
+  }
+
+  const reserved = ['true', 'false', 'null', 'yes', 'no', 'on', 'off']
+  if (reserved.includes(value.toLowerCase())) {
+    return true
+  }
+
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Mutable frontmatter for internal parsing
+ */
+interface MutableParsedFrontmatter {
+  title?: string
+  description?: string
+}
+
+export function parseFrontmatter(yaml: string): Partial<MDXFrontmatter> {
+  const result: MutableParsedFrontmatter = {}
+  const lines = yaml.split('\n')
+
+  for (const line of lines) {
+    const trimmedLine = line.trim()
+
+    if (trimmedLine.startsWith('title:')) {
+      const value = trimmedLine.slice(6).trim()
+      result.title = stripQuotes(value)
+    }
+
+    if (trimmedLine.startsWith('description:')) {
+      const value = trimmedLine.slice(12).trim()
+      result.description = stripQuotes(value)
+    }
+  }
+
+  return result as Partial<MDXFrontmatter>
+}
+
+function stripQuotes(value: string): string {
+  if (
+    (value.startsWith("'") && value.endsWith("'")) ||
+    (value.startsWith('"') && value.endsWith('"'))
+  ) {
+    return value.slice(1, -1)
+  }
+  return value
+}

package/src/generators/index.ts

@@ -0,0 +1,56 @@
+/**
+ * @bfra.me/doc-sync/generators - Unified export of all generator modules
+ */
+
+export {
+  generateAPICompact,
+  generateAPIReference,
+  generateCategoryReference,
+} from './api-reference-generator'
+
+export {
+  cleanCodeExample,
+  detectLanguage,
+  formatCodeBlock,
+  formatCodeExamples,
+  formatFunctionExamples,
+  formatGroupedExamples,
+  formatTypeExamples,
+  formatUsageExample,
+  groupExamplesByCategory,
+} from './code-example-formatter'
+export type {CodeExampleOptions} from './code-example-formatter'
+
+export {
+  createBadge,
+  createCard,
+  createCardGrid,
+  createTabs,
+  generateInstallTabs,
+  mapToStarlightComponents,
+} from './component-mapper'
+export type {ComponentMapperConfig, SectionMapper} from './component-mapper'
+
+export {
+  createDiffSummary,
+  extractAutoSections,
+  extractManualSections,
+  hasAutoContent,
+  hasManualContent,
+  mergeContent,
+  stripSentinelMarkers,
+  validateMarkerPairing,
+  wrapAutoSection,
+  wrapManualSection,
+} from './content-merger'
+export type {ContentSection, MergeOptions, MergeResult} from './content-merger'
+
+export {generateFrontmatter, parseFrontmatter, stringifyFrontmatter} from './frontmatter-generator'
+
+export {
+  generateMDXDocument,
+  sanitizeContent,
+  sanitizeTextContent,
+  validateMDXSyntax,
+} from './mdx-generator'
+export type {MDXGeneratorOptions} from './mdx-generator'