@bfra.me/doc-sync 0.1.0

package/src/orchestrator/sync-orchestrator.ts

@@ -0,0 +1,382 @@
+import type {Result} from '@bfra.me/es/result'
+import type {DocConfig, FileChangeEvent, SyncError, SyncInfo, SyncSummary} from '../types'
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {err, ok} from '@bfra.me/es/result'
+
+import {generateMDXDocument, mergeContent} from '../generators'
+import {
+  createDocChangeDetector,
+  createDocDebouncer,
+  createDocWatcher,
+  determineRegenerationScope,
+  groupChangesByPackage,
+  type DocDebouncer,
+  type DocFileWatcher,
+} from '../watcher'
+
+import {createPackageScanner, type ScannedPackage} from './package-scanner'
+import {createValidationPipeline} from './validation-pipeline'
+
+export interface SyncOrchestratorOptions {
+  readonly config: DocConfig
+  readonly dryRun?: boolean
+  readonly verbose?: boolean
+  readonly onProgress?: (message: string) => void
+  readonly onError?: (error: SyncError) => void
+}
+
+export interface SyncOrchestrator {
+  readonly syncAll: () => Promise<SyncSummary>
+  readonly syncPackages: (packageNames: readonly string[]) => Promise<SyncSummary>
+  readonly handleChanges: (events: readonly FileChangeEvent[]) => Promise<SyncSummary>
+  readonly startWatching: () => Promise<void>
+  readonly stopWatching: () => Promise<void>
+  readonly isWatching: () => boolean
+}
+
+export function createSyncOrchestrator(options: SyncOrchestratorOptions): SyncOrchestrator {
+  const {config, dryRun = false, verbose = false, onProgress, onError} = options
+
+  const scanner = createPackageScanner({
+    rootDir: config.rootDir,
+    includePatterns: config.includePatterns,
+    excludePackages: config.excludePatterns as string[] | undefined,
+  })
+
+  const validationPipeline = createValidationPipeline()
+
+  let watcher: DocFileWatcher | undefined
+  let debouncer: DocDebouncer | undefined
+  let watching = false
+
+  function log(message: string): void {
+    if (verbose && onProgress != null) {
+      onProgress(message)
+    }
+  }
+
+  function reportError(error: SyncError): void {
+    if (onError != null) {
+      onError(error)
+    }
+  }
+
+  async function syncPackage(pkg: ScannedPackage): Promise<Result<SyncInfo, SyncError>> {
+    log(`Syncing documentation for ${pkg.info.name}...`)
+
+    const docResult = generateMDXDocument(pkg.info, pkg.readme, pkg.api)
+
+    if (!docResult.success) {
+      return docResult
+    }
+
+    const doc = docResult.data
+    const validationResult = validationPipeline.validate(doc)
+
+    if (!validationResult.valid) {
+      const errorMessages = validationResult.errors.map(e => e.message).join('; ')
+      return err({
+        code: 'VALIDATION_ERROR',
+        message: `Validation failed for ${pkg.info.name}: ${errorMessages}`,
+        packageName: pkg.info.name,
+      })
+    }
+
+    const outputPath = getOutputPath(pkg.info.name, config.outputDir)
+    let action: SyncInfo['action'] = 'created'
+    let contentToWrite = doc.rendered
+
+    try {
+      if (pkg.existingDocPath == null) {
+        if (!dryRun) {
+          await writeFile(outputPath, contentToWrite)
+        }
+      } else {
+        try {
+          const existingContent = await fs.readFile(pkg.existingDocPath, 'utf-8')
+          const mergedResult = mergeContent(existingContent, doc.rendered)
+
+          if (!mergedResult.success) {
+            if (!dryRun) {
+              await writeFile(outputPath, contentToWrite)
+            }
+            action = 'updated'
+          } else if (mergedResult.data.content === existingContent) {
+            return ok({
+              packageName: pkg.info.name,
+              outputPath,
+              action: 'unchanged',
+              timestamp: new Date(),
+            })
+          } else {
+            contentToWrite = mergedResult.data.content
+            action = 'updated'
+
+            if (!dryRun) {
+              await writeFile(outputPath, contentToWrite)
+            }
+          }
+        } catch {
+          if (!dryRun) {
+            await writeFile(outputPath, contentToWrite)
+          }
+        }
+      }
+    } catch (error) {
+      return err(createWriteError(error, outputPath, pkg.info.name))
+    }
+
+    log(`${dryRun ? '[DRY RUN] Would write' : 'Wrote'} ${outputPath}`)
+
+    return ok({
+      packageName: pkg.info.name,
+      outputPath,
+      action,
+      timestamp: new Date(),
+    })
+  }
+
+  async function syncAll(): Promise<SyncSummary> {
+    const startTime = Date.now()
+    log('Starting full documentation sync...')
+
+    const scanResult = await scanner.scan()
+    const details: SyncInfo[] = []
+    const errors: SyncError[] = [...scanResult.errors]
+
+    for (const pkg of scanResult.packagesNeedingDocs) {
+      const result = await syncPackage(pkg)
+
+      if (result.success) {
+        details.push(result.data)
+      } else {
+        errors.push(result.error)
+        reportError(result.error)
+      }
+    }
+
+    const successCount = details.filter(d => d.action !== 'unchanged').length
+    const unchangedCount = details.filter(d => d.action === 'unchanged').length
+
+    log(
+      `Sync complete: ${successCount} updated, ${unchangedCount} unchanged, ${errors.length} errors`,
+    )
+
+    return {
+      totalPackages: scanResult.packages.length,
+      successCount,
+      failureCount: errors.length,
+      unchangedCount,
+      details,
+      errors,
+      durationMs: Date.now() - startTime,
+    }
+  }
+
+  async function syncPackages(packageNames: readonly string[]): Promise<SyncSummary> {
+    const startTime = Date.now()
+    log(`Syncing specific packages: ${packageNames.join(', ')}...`)
+
+    const scanResult = await scanner.scan()
+    const packagesToSync = scanResult.packages.filter(pkg => packageNames.includes(pkg.info.name))
+
+    const details: SyncInfo[] = []
+    const errors: SyncError[] = []
+
+    for (const pkg of packagesToSync) {
+      const result = await syncPackage(pkg)
+
+      if (result.success) {
+        details.push(result.data)
+      } else {
+        errors.push(result.error)
+        reportError(result.error)
+      }
+    }
+
+    const successCount = details.filter(d => d.action !== 'unchanged').length
+    const unchangedCount = details.filter(d => d.action === 'unchanged').length
+
+    return {
+      totalPackages: packagesToSync.length,
+      successCount,
+      failureCount: errors.length,
+      unchangedCount,
+      details,
+      errors,
+      durationMs: Date.now() - startTime,
+    }
+  }
+
+  async function handleChanges(events: readonly FileChangeEvent[]): Promise<SyncSummary> {
+    const startTime = Date.now()
+    const groupedChanges = groupChangesByPackage(events)
+    const packageNames: string[] = []
+
+    for (const [packageName, packageEvents] of groupedChanges) {
+      if (packageName === '__unknown__') {
+        continue
+      }
+
+      const categories = packageEvents.map(e => categorizeFileChange(e.path))
+
+      const scope = determineRegenerationScope(categories)
+      if (scope !== 'none') {
+        packageNames.push(packageName)
+        log(`Package ${packageName} needs ${scope} regeneration`)
+      }
+    }
+
+    if (packageNames.length === 0) {
+      return {
+        totalPackages: 0,
+        successCount: 0,
+        failureCount: 0,
+        unchangedCount: 0,
+        details: [],
+        errors: [],
+        durationMs: Date.now() - startTime,
+      }
+    }
+
+    return syncPackages(packageNames)
+  }
+
+  async function startWatching(): Promise<void> {
+    if (watching) {
+      return
+    }
+
+    log('Starting watch mode...')
+
+    watcher = createDocWatcher({
+      rootDir: config.rootDir,
+      debounceMs: config.debounceMs ?? 300,
+    })
+
+    debouncer = createDocDebouncer(
+      async events => {
+        const result = await handleChanges(events)
+        log(`Watch mode sync: ${result.successCount} updated, ${result.failureCount} errors`)
+      },
+      {debounceMs: config.debounceMs ?? 300},
+    )
+
+    watcher.onChanges(events => {
+      for (const event of events) {
+        debouncer?.add(event)
+      }
+    })
+
+    await watcher.start()
+    watching = true
+    log('Watch mode started')
+  }
+
+  async function stopWatching(): Promise<void> {
+    if (!watching) {
+      return
+    }
+
+    log('Stopping watch mode...')
+
+    debouncer?.cancel()
+    await watcher?.close()
+
+    watcher = undefined
+    debouncer = undefined
+    watching = false
+
+    log('Watch mode stopped')
+  }
+
+  return {
+    syncAll,
+    syncPackages,
+    handleChanges,
+    startWatching,
+    stopWatching,
+    isWatching: () => watching,
+  }
+}
+
+function getOutputPath(packageName: string, outputDir: string): string {
+  const slug = createSlug(getUnscopedName(packageName))
+  return path.join(outputDir, `${slug}.mdx`)
+}
+
+function createSlug(name: string): string {
+  return name.toLowerCase().replaceAll(/[^a-z0-9-]/g, '-')
+}
+
+function getUnscopedName(packageName: string): string {
+  if (packageName.startsWith('@')) {
+    const slashIndex = packageName.indexOf('/')
+    if (slashIndex > 0) {
+      return packageName.slice(slashIndex + 1)
+    }
+  }
+  return packageName
+}
+
+async function writeFile(filePath: string, content: string): Promise<void> {
+  const dir = path.dirname(filePath)
+  await fs.mkdir(dir, {recursive: true})
+  await fs.writeFile(filePath, content, 'utf-8')
+}
+
+function createWriteError(error: unknown, filePath: string, packageName: string): SyncError {
+  const message = formatWriteErrorMessage(error, filePath)
+  return {
+    code: 'WRITE_ERROR',
+    message,
+    packageName,
+    filePath,
+    cause: error,
+  }
+}
+
+function formatWriteErrorMessage(error: unknown, filePath: string): string {
+  const errorCode = isNodeError(error) ? error.code : undefined
+
+  switch (errorCode) {
+    case 'EACCES':
+      return `Permission denied writing to ${filePath}`
+    case 'ENOENT':
+      return `Directory not found for ${filePath}`
+    case 'EISDIR':
+      return `Cannot write to directory ${filePath}`
+    case undefined:
+    default: {
+      const errorMessage = error instanceof Error ? error.message : String(error)
+      return `Failed to write ${filePath}: ${errorMessage}`
+    }
+  }
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error
+}
+
+function categorizeFileChange(filePath: string): 'readme' | 'package-json' | 'source' | 'unknown' {
+  const basename = path.basename(filePath).toLowerCase()
+
+  if (basename === 'readme.md' || basename === 'readme') return 'readme'
+  if (basename === 'package.json') return 'package-json'
+  if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) return 'source'
+  return 'unknown'
+}
+
+/** Prevents directory traversal attacks (SEC-002) */
+export function isValidFilePath(filePath: string, rootDir: string): boolean {
+  const resolvedPath = path.resolve(filePath)
+  const resolvedRoot = path.resolve(rootDir)
+
+  return resolvedPath.startsWith(resolvedRoot)
+}
+
+// Export changeDetector factory for external use
+export {createDocChangeDetector}

package/src/orchestrator/validation-pipeline.ts

@@ -0,0 +1,328 @@
+import type {Result} from '@bfra.me/es/result'
+import type {MDXDocument, SyncError} from '../types'
+
+import {err, ok} from '@bfra.me/es/result'
+
+import {validateMDXSyntax} from '../generators'
+import {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  hasComponent,
+} from '../utils/safe-patterns'
+
+export interface ValidationResult {
+  readonly valid: boolean
+  readonly errors: readonly ValidationError[]
+  readonly warnings: readonly ValidationWarning[]
+}
+
+export interface ValidationError {
+  readonly type: 'syntax' | 'frontmatter' | 'component' | 'content'
+  readonly message: string
+  readonly line?: number
+  readonly column?: number
+}
+
+export interface ValidationWarning {
+  readonly type: 'deprecation' | 'recommendation' | 'compatibility'
+  readonly message: string
+  readonly line?: number
+}
+
+export interface ValidationPipelineOptions {
+  readonly validateFrontmatter?: boolean
+  readonly validateComponents?: boolean
+  readonly validateContent?: boolean
+  readonly strict?: boolean
+}
+
+const DEFAULT_OPTIONS: Required<ValidationPipelineOptions> = {
+  validateFrontmatter: true,
+  validateComponents: true,
+  validateContent: true,
+  strict: false,
+}
+
+export function createValidationPipeline(options: ValidationPipelineOptions = {}): {
+  readonly validate: (doc: MDXDocument) => ValidationResult
+  readonly validateContent: (content: string) => ValidationResult
+  readonly validateMultiple: (
+    docs: readonly MDXDocument[],
+  ) => Result<Map<string, ValidationResult>, SyncError>
+} {
+  const mergedOptions = {...DEFAULT_OPTIONS, ...options}
+
+  function validate(doc: MDXDocument): ValidationResult {
+    const errors: ValidationError[] = []
+    const warnings: ValidationWarning[] = []
+
+    if (mergedOptions.validateFrontmatter) {
+      const frontmatterResult = validateFrontmatter(doc.frontmatter)
+      errors.push(...frontmatterResult.errors)
+      warnings.push(...frontmatterResult.warnings)
+    }
+
+    const syntaxResult = validateSyntax(doc.rendered)
+    errors.push(...syntaxResult.errors)
+    warnings.push(...syntaxResult.warnings)
+
+    if (mergedOptions.validateComponents) {
+      const componentResult = validateStarlightComponents(doc.rendered)
+      errors.push(...componentResult.errors)
+      warnings.push(...componentResult.warnings)
+    }
+
+    if (mergedOptions.validateContent) {
+      const contentResult = validateContentQuality(doc.rendered)
+      errors.push(...contentResult.errors)
+      warnings.push(...contentResult.warnings)
+    }
+
+    const valid = mergedOptions.strict
+      ? errors.length === 0 && warnings.length === 0
+      : errors.length === 0
+
+    return {valid, errors, warnings}
+  }
+
+  function validateContent(content: string): ValidationResult {
+    const errors: ValidationError[] = []
+    const warnings: ValidationWarning[] = []
+
+    const syntaxResult = validateSyntax(content)
+    errors.push(...syntaxResult.errors)
+    warnings.push(...syntaxResult.warnings)
+
+    if (mergedOptions.validateComponents) {
+      const componentResult = validateStarlightComponents(content)
+      errors.push(...componentResult.errors)
+      warnings.push(...componentResult.warnings)
+    }
+
+    const valid = mergedOptions.strict
+      ? errors.length === 0 && warnings.length === 0
+      : errors.length === 0
+
+    return {valid, errors, warnings}
+  }
+
+  function validateMultiple(
+    docs: readonly MDXDocument[],
+  ): Result<Map<string, ValidationResult>, SyncError> {
+    const results = new Map<string, ValidationResult>()
+    const seen = new Set<string>()
+
+    for (const doc of docs) {
+      const key = doc.frontmatter.title
+
+      // Fixed: Return error on duplicate titles instead of silent overwrite
+      if (seen.has(key)) {
+        return err({
+          code: 'VALIDATION_ERROR',
+          message: `Duplicate document title detected: "${key}". Each document must have a unique title.`,
+        })
+      }
+
+      seen.add(key)
+      results.set(key, validate(doc))
+    }
+
+    return ok(results)
+  }
+
+  return {validate, validateContent, validateMultiple}
+}
+
+function validateFrontmatter(frontmatter: MDXDocument['frontmatter']): {
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+} {
+  const errors: ValidationError[] = []
+  const warnings: ValidationWarning[] = []
+
+  if (frontmatter.title.trim().length === 0) {
+    errors.push({
+      type: 'frontmatter',
+      message: 'Frontmatter title is required and cannot be empty',
+    })
+  }
+
+  if (frontmatter.title.length > 100) {
+    warnings.push({
+      type: 'recommendation',
+      message: `Title is ${frontmatter.title.length} characters, consider keeping under 100 for better readability`,
+    })
+  }
+
+  if (frontmatter.description !== undefined && frontmatter.description.length > 200) {
+    warnings.push({
+      type: 'recommendation',
+      message: 'Description is quite long, consider keeping under 200 characters for SEO',
+    })
+  }
+
+  return {errors, warnings}
+}
+
+function validateSyntax(content: string): {
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+} {
+  const errors: ValidationError[] = []
+  const warnings: ValidationWarning[] = []
+
+  const result = validateMDXSyntax(content)
+
+  if (!result.success) {
+    errors.push({
+      type: 'syntax',
+      message: result.error.message,
+    })
+  }
+
+  return {errors, warnings}
+}
+
+const STARLIGHT_COMPONENTS = ['Badge', 'Card', 'CardGrid', 'Tabs', 'TabItem'] as const
+
+function validateStarlightComponents(content: string): {
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+} {
+  const errors: ValidationError[] = []
+  const warnings: ValidationWarning[] = []
+
+  for (const component of STARLIGHT_COMPONENTS) {
+    const openPattern = new RegExp(String.raw`<${component}(?:\s[^>]*)?>`, 'g')
+    const closePattern = new RegExp(`</${component}>`, 'g')
+    const selfClosePattern = new RegExp(String.raw`<${component}(?:\s[^>]*)?/>`, 'g')
+
+    const opens = content.match(openPattern)?.length ?? 0
+    const closes = content.match(closePattern)?.length ?? 0
+    const selfCloses = content.match(selfClosePattern)?.length ?? 0
+
+    const nonSelfClosingOpens = opens - selfCloses
+    if (nonSelfClosingOpens > closes) {
+      errors.push({
+        type: 'component',
+        message: `Unclosed <${component}> tag detected (${nonSelfClosingOpens} opens, ${closes} closes)`,
+      })
+    }
+  }
+
+  const hasTabItem = content.includes('<TabItem')
+  const hasTabs = content.includes('<Tabs')
+  if (hasTabItem && !hasTabs) {
+    errors.push({
+      type: 'component',
+      message: '<TabItem> must be used inside <Tabs>',
+    })
+  }
+
+  // Ensures hasCard detects 'Card' but not 'CardGrid'
+  const hasCard = hasComponent(content, 'Card')
+  const hasCardGrid = hasComponent(content, 'CardGrid')
+  if (hasCard && !hasCardGrid) {
+    warnings.push({
+      type: 'recommendation',
+      message: 'Consider wrapping <Card> components in <CardGrid> for better layout',
+    })
+  }
+
+  return {errors, warnings}
+}
+
+function validateContentQuality(content: string): {
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+} {
+  const errors: ValidationError[] = []
+  const warnings: ValidationWarning[] = []
+
+  const emptyLinkPositions = findEmptyMarkdownLinks(content)
+  if (emptyLinkPositions.length > 0) {
+    errors.push({
+      type: 'content',
+      message: `Found ${emptyLinkPositions.length} empty link(s)`,
+    })
+  }
+
+  const codeBlockMarkers = content.match(/```/g)?.length ?? 0
+  if (codeBlockMarkers % 2 !== 0) {
+    errors.push({
+      type: 'content',
+      message: 'Unclosed code block detected (odd number of ``` markers)',
+    })
+  }
+
+  // Duplicate headings can confuse readers and break anchor links
+  const h2Pattern = createHeadingPattern(2)
+  const h2Headings: string[] = []
+  const h2Matches = content.matchAll(h2Pattern)
+  for (const match of h2Matches) {
+    const heading = match[1]
+    if (heading === undefined) {
+      continue
+    }
+    if (h2Headings.includes(heading)) {
+      warnings.push({
+        type: 'recommendation',
+        message: `Duplicate H2 heading: "${heading}"`,
+      })
+    }
+    h2Headings.push(heading)
+  }
+
+  const codeBlocks = extractCodeBlocks(content)
+  for (const block of codeBlocks) {
+    const lines = block.split('\n')
+    for (const line of lines) {
+      if (line.length > 120 && !line.startsWith('```')) {
+        warnings.push({
+          type: 'recommendation',
+          message: `Code line exceeds 120 characters, may require horizontal scrolling`,
+        })
+        break
+      }
+    }
+  }
+
+  return {errors, warnings}
+}
+
+export function validateDocument(
+  doc: MDXDocument,
+  options?: ValidationPipelineOptions,
+): Result<MDXDocument, SyncError> {
+  const pipeline = createValidationPipeline(options)
+  const result = pipeline.validate(doc)
+
+  if (!result.valid) {
+    const errorMessages = result.errors.map(e => e.message).join('; ')
+    return err({
+      code: 'VALIDATION_ERROR',
+      message: `MDX validation failed: ${errorMessages}`,
+    })
+  }
+
+  return ok(doc)
+}
+
+export function validateContentString(
+  content: string,
+  options?: ValidationPipelineOptions,
+): Result<string, SyncError> {
+  const pipeline = createValidationPipeline(options)
+  const result = pipeline.validateContent(content)
+
+  if (!result.valid) {
+    const errorMessages = result.errors.map(e => e.message).join('; ')
+    return err({
+      code: 'VALIDATION_ERROR',
+      message: `MDX validation failed: ${errorMessages}`,
+    })
+  }
+
+  return ok(content)
+}