@bfra.me/doc-sync 0.1.0

package/src/cli/commands/validate.ts

@@ -0,0 +1,151 @@
+import type {GlobalOptions, ValidationStatus} from '../types.js'
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import process from 'node:process'
+
+import {generateMDXDocument, mergeContent} from '../../generators/index.js'
+import {createPackageScanner} from '../../orchestrator/package-scanner.js'
+import {createValidationPipeline} from '../../orchestrator/validation-pipeline.js'
+import {getUnscopedName} from '../../parsers/index.js'
+import {createLogger, createSpinner, formatDuration, showIntro, showOutro} from '../ui.js'
+
+export async function runValidate(packages: string[], options: GlobalOptions): Promise<void> {
+  const logger = createLogger(options)
+  const rootDir = path.resolve(options.root)
+  const outputDir = path.join(rootDir, 'docs', 'src', 'content', 'docs', 'packages')
+
+  if (options.quiet !== true) {
+    showIntro('🔍 doc-sync validate')
+  }
+
+  const startTime = Date.now()
+  const spinner = options.quiet === true ? undefined : createSpinner()
+  const validationResults: ValidationStatus[] = []
+
+  spinner?.start('Scanning packages...')
+
+  const scanner = createPackageScanner({
+    rootDir,
+    parseSourceFiles: true,
+    parseReadme: true,
+  })
+
+  const validationPipeline = createValidationPipeline()
+  const scanResult = await scanner.scan()
+
+  spinner?.stop(`Found ${scanResult.packages.length} packages`)
+
+  const packagesToValidate =
+    packages.length > 0
+      ? scanResult.packages.filter(pkg => packages.includes(pkg.info.name))
+      : scanResult.packages
+
+  spinner?.start(`Validating ${packagesToValidate.length} packages...`)
+
+  for (const pkg of packagesToValidate) {
+    const issues: string[] = []
+    let isValid = true
+
+    const docPath = buildDocPath(pkg.info.name, outputDir)
+
+    try {
+      await fs.access(docPath)
+
+      const existingContent = await fs.readFile(docPath, 'utf-8')
+      const contentValidation = validationPipeline.validateContent(existingContent)
+
+      if (!contentValidation.valid) {
+        isValid = false
+        for (const error of contentValidation.errors) {
+          issues.push(`MDX error: ${error.message}`)
+        }
+      }
+
+      const docResult = generateMDXDocument(pkg.info, pkg.readme, pkg.api)
+
+      if (docResult.success) {
+        const generatedContent = docResult.data.rendered
+        const mergedResult = mergeContent(existingContent, generatedContent)
+
+        // Use mergeContent to respect manual edits between sentinel markers
+        // This ensures validation matches sync behavior
+        if (mergedResult.success) {
+          if (normalizeContent(existingContent) !== normalizeContent(mergedResult.data.content)) {
+            isValid = false
+            issues.push('Documentation is out of date with source')
+          }
+        } else if (normalizeContent(existingContent) !== normalizeContent(generatedContent)) {
+          isValid = false
+          issues.push('Documentation is out of date with source')
+        }
+      } else {
+        issues.push(`Generation failed: ${docResult.error.message}`)
+      }
+    } catch {
+      isValid = false
+      issues.push('Documentation file does not exist')
+    }
+
+    validationResults.push({
+      packageName: pkg.info.name,
+      isValid,
+      issues,
+    })
+
+    if (options.verbose === true) {
+      if (isValid) {
+        logger.success(`✓ ${pkg.info.name}`)
+      } else {
+        logger.warn(`✗ ${pkg.info.name}: ${issues.join(', ')}`)
+      }
+    }
+  }
+
+  spinner?.stop('Validation complete')
+
+  const validCount = validationResults.filter(r => r.isValid).length
+  const invalidCount = validationResults.filter(r => !r.isValid).length
+  const durationMs = Date.now() - startTime
+
+  if (invalidCount > 0) {
+    logger.warn(`Found ${invalidCount} package${invalidCount === 1 ? '' : 's'} with issues:`)
+
+    for (const result of validationResults) {
+      if (!result.isValid) {
+        logger.error(`  ${result.packageName}:`)
+        for (const issue of result.issues) {
+          logger.error(`    - ${issue}`)
+        }
+      }
+    }
+  }
+
+  logger.info(`${validCount} valid, ${invalidCount} invalid in ${formatDuration(durationMs)}`)
+
+  if (options.quiet !== true) {
+    if (invalidCount > 0) {
+      showOutro(
+        `⚠️  ${invalidCount} package${invalidCount === 1 ? '' : 's'} need${invalidCount === 1 ? 's' : ''} attention`,
+      )
+    } else {
+      showOutro('✨ All documentation is up to date!')
+    }
+  }
+
+  if (invalidCount > 0) {
+    process.exit(1)
+  }
+}
+
+function buildDocPath(packageName: string, outputDir: string): string {
+  const slug = getUnscopedName(packageName)
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9-]/g, '-')
+
+  return path.join(outputDir, `${slug}.mdx`)
+}
+
+function normalizeContent(content: string): string {
+  return content.replaceAll('\r\n', '\n').replaceAll(/\s+$/gm, '').trim()
+}

package/src/cli/commands/watch.ts

@@ -0,0 +1,74 @@
+import type {GlobalOptions} from '../types.js'
+
+import path from 'node:path'
+import process from 'node:process'
+
+import {createSyncOrchestrator} from '../../orchestrator/sync-orchestrator.js'
+import {createLogger, createProgressCallback, createSpinner, showIntro, showOutro} from '../ui.js'
+
+export async function runWatch(packages: string[], options: GlobalOptions): Promise<void> {
+  const logger = createLogger(options)
+  const rootDir = path.resolve(options.root)
+  const outputDir = path.join(rootDir, 'docs', 'src', 'content', 'docs', 'packages')
+
+  if (options.quiet !== true) {
+    showIntro('👁️  doc-sync watch')
+  }
+
+  const spinner = options.quiet === true ? undefined : createSpinner()
+
+  const orchestrator = createSyncOrchestrator({
+    config: {
+      rootDir,
+      outputDir,
+      includePatterns: ['packages/*'],
+      excludePatterns: [],
+      watch: true,
+      debounceMs: 300,
+    },
+    dryRun: options.dryRun ?? false,
+    verbose: options.verbose ?? false,
+    onProgress: createProgressCallback(options),
+    onError(error): void {
+      logger.error(`Error: ${error.message}`)
+    },
+  })
+
+  if (packages.length > 0) {
+    logger.info(`Watching packages: ${packages.join(', ')}`)
+    spinner?.start('Performing initial sync...')
+    await orchestrator.syncPackages(packages)
+    spinner?.stop('Initial sync complete')
+  } else {
+    spinner?.start('Performing initial sync of all packages...')
+    await orchestrator.syncAll()
+    spinner?.stop('Initial sync complete')
+  }
+
+  logger.info('Starting watch mode...')
+  spinner?.start('Watching for changes... (Ctrl+C to stop)')
+
+  await orchestrator.startWatching()
+
+  const shutdown = async (): Promise<void> => {
+    spinner?.stop('Stopping watch mode...')
+    await orchestrator.stopWatching()
+
+    if (options.quiet !== true) {
+      showOutro('👋 Watch mode stopped')
+    }
+
+    process.exit(0)
+  }
+
+  process.on('SIGINT', () => {
+    shutdown().catch(() => process.exit(1))
+  })
+
+  process.on('SIGTERM', () => {
+    shutdown().catch(() => process.exit(1))
+  })
+
+  // Keep the process running until interrupted
+  setInterval(() => {}, 1 << 30)
+}

package/src/cli/index.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * @bfra.me/doc-sync CLI entry point
+ *
+ * Modern TUI for documentation synchronization using @clack/prompts.
+ */
+
+import type {GlobalOptions} from './types.js'
+
+import process from 'node:process'
+
+import {cac} from 'cac'
+import {runSync} from './commands/sync.js'
+import {runValidate} from './commands/validate.js'
+import {runWatch} from './commands/watch.js'
+
+const cli = cac('doc-sync')
+
+cli
+  .command(
+    'sync [...packages]',
+    'Sync documentation for specified packages (or all if none specified)',
+  )
+  .option('-r, --root <dir>', 'Root directory of the monorepo', {default: process.cwd()})
+  .option('-d, --dry-run', 'Preview changes without writing files')
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .option('-i, --interactive', 'Use interactive package selection')
+  .action(async (packages: string[], options: GlobalOptions) => {
+    await runSync(packages, options)
+  })
+
+cli
+  .command('watch [...packages]', 'Watch for changes and sync automatically')
+  .option('-r, --root <dir>', 'Root directory of the monorepo', {default: process.cwd()})
+  .option('-d, --dry-run', 'Preview changes without writing files')
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .action(async (packages: string[], options: GlobalOptions) => {
+    await runWatch(packages, options)
+  })
+
+cli
+  .command('validate [...packages]', 'Check documentation freshness and validate MDX syntax')
+  .option('-r, --root <dir>', 'Root directory of the monorepo', {default: process.cwd()})
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .action(async (packages: string[], options: GlobalOptions) => {
+    await runValidate(packages, options)
+  })
+
+cli
+  .command('[...packages]', 'Sync documentation (default command)')
+  .option('-r, --root <dir>', 'Root directory of the monorepo', {default: process.cwd()})
+  .option('-w, --watch', 'Watch for changes and sync automatically')
+  .option('-d, --dry-run', 'Preview changes without writing files')
+  .option('-v, --verbose', 'Enable verbose output')
+  .option('-q, --quiet', 'Suppress non-error output')
+  .option('-i, --interactive', 'Use interactive package selection')
+  .action(async (packages: string[], options: GlobalOptions & {watch?: boolean}) => {
+    if (options.watch === true) {
+      await runWatch(packages, options)
+    } else {
+      await runSync(packages, options)
+    }
+  })
+
+cli.help()
+cli.version('0.0.1')
+
+cli.parse()

package/src/cli/types.ts

@@ -0,0 +1,19 @@
+export interface GlobalOptions {
+  readonly root: string
+  readonly dryRun?: boolean
+  readonly verbose?: boolean
+  readonly quiet?: boolean
+  readonly interactive?: boolean
+}
+
+export interface PackageSelectionOption {
+  readonly value: string
+  readonly label: string
+  readonly hint?: string
+}
+
+export interface ValidationStatus {
+  readonly packageName: string
+  readonly isValid: boolean
+  readonly issues: readonly string[]
+}

package/src/cli/ui.ts

@@ -0,0 +1,123 @@
+import type {GlobalOptions, PackageSelectionOption} from './types.js'
+
+import * as p from '@clack/prompts'
+import {consola} from 'consola'
+
+export interface Logger {
+  readonly info: (message: string) => void
+  readonly success: (message: string) => void
+  readonly warn: (message: string) => void
+  readonly error: (message: string) => void
+  readonly debug: (message: string) => void
+}
+
+export interface LoggerOptions {
+  readonly verbose?: boolean
+  readonly quiet?: boolean
+}
+
+export function createLogger(options: LoggerOptions): Logger {
+  const {verbose = false, quiet = false} = options
+
+  return {
+    info(message: string): void {
+      if (!quiet) {
+        p.log.info(message)
+      }
+    },
+    success(message: string): void {
+      if (!quiet) {
+        p.log.success(message)
+      }
+    },
+    warn(message: string): void {
+      p.log.warn(message)
+    },
+    error(message: string): void {
+      p.log.error(message)
+    },
+    debug(message: string): void {
+      if (verbose) {
+        consola.debug(message)
+      }
+    },
+  }
+}
+
+export function showIntro(title: string): void {
+  p.intro(title)
+}
+
+export function showOutro(message: string): void {
+  p.outro(message)
+}
+
+export function createSpinner(): ReturnType<typeof p.spinner> {
+  return p.spinner()
+}
+
+export async function selectPackages(
+  availablePackages: readonly PackageSelectionOption[],
+): Promise<readonly string[] | symbol> {
+  if (availablePackages.length === 0) {
+    return []
+  }
+
+  const options = availablePackages.map(pkg => ({
+    value: pkg.value,
+    label: pkg.label,
+    hint: pkg.hint,
+  }))
+
+  const selected = await p.multiselect({
+    message: 'Select packages to sync',
+    options,
+    required: false,
+  })
+
+  return selected
+}
+
+export async function confirmAction(message: string): Promise<boolean | symbol> {
+  return p.confirm({message})
+}
+
+export function handleCancel(value: unknown): value is symbol {
+  return p.isCancel(value)
+}
+
+export function showCancel(message = 'Operation cancelled.'): void {
+  p.cancel(message)
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms}ms`
+  }
+  if (ms < 60000) {
+    return `${(ms / 1000).toFixed(1)}s`
+  }
+  const minutes = Math.floor(ms / 60000)
+  const seconds = Math.round((ms % 60000) / 1000)
+  return `${minutes}m ${seconds}s`
+}
+
+export function formatPackageList(packages: readonly string[]): string {
+  if (packages.length === 0) {
+    return 'no packages'
+  }
+  if (packages.length === 1) {
+    return packages[0] ?? 'unknown'
+  }
+  if (packages.length <= 3) {
+    return packages.join(', ')
+  }
+  return `${packages.slice(0, 3).join(', ')} and ${packages.length - 3} more`
+}
+
+export function createProgressCallback(options: GlobalOptions): (message: string) => void {
+  const logger = createLogger(options)
+  return (message: string) => {
+    logger.debug(message)
+  }
+}

package/src/generators/api-reference-generator.ts

@@ -0,0 +1,268 @@
+/**
+ * @bfra.me/doc-sync/generators/api-reference-generator - API documentation table generation
+ */
+
+import type {ExportedFunction, ExportedType, PackageAPI} from '../types'
+
+export function generateAPIReference(api: PackageAPI): string {
+  const sections: string[] = []
+
+  if (api.functions.length > 0) {
+    sections.push('### Functions')
+    sections.push('')
+    sections.push(generateFunctionsTable(api.functions))
+    sections.push('')
+    sections.push(generateFunctionDetails(api.functions))
+  }
+
+  if (api.types.length > 0) {
+    sections.push('### Types')
+    sections.push('')
+    sections.push(generateTypesTable(api.types))
+    sections.push('')
+    sections.push(generateTypeDetails(api.types))
+  }
+
+  return sections.join('\n')
+}
+
+function generateFunctionsTable(functions: readonly ExportedFunction[]): string {
+  const lines: string[] = []
+
+  lines.push('| Function | Description |')
+  lines.push('| -------- | ----------- |')
+
+  for (const fn of functions) {
+    const name = formatFunctionName(fn)
+    const description = fn.jsdoc?.description ?? ''
+    const firstLine = getFirstLine(description)
+    lines.push(`| ${name} | ${escapeTableCell(firstLine)} |`)
+  }
+
+  return lines.join('\n')
+}
+
+function generateFunctionDetails(functions: readonly ExportedFunction[]): string {
+  const sections: string[] = []
+
+  for (const fn of functions) {
+    sections.push(generateFunctionDetail(fn))
+  }
+
+  return sections.join('\n\n')
+}
+
+function generateFunctionDetail(fn: ExportedFunction): string {
+  const lines: string[] = []
+
+  lines.push(`#### \`${fn.name}\``)
+  lines.push('')
+
+  if (fn.jsdoc?.description !== undefined) {
+    lines.push(fn.jsdoc.description)
+    lines.push('')
+  }
+
+  lines.push('```typescript')
+  lines.push(fn.signature)
+  lines.push('```')
+
+  if (fn.parameters.length > 0) {
+    lines.push('')
+    lines.push('**Parameters:**')
+    lines.push('')
+    lines.push('| Name | Type | Description |')
+    lines.push('| ---- | ---- | ----------- |')
+
+    for (const param of fn.parameters) {
+      const paramDoc = fn.jsdoc?.params?.find(p => p.name === param.name)
+      const description = paramDoc?.description ?? ''
+      const optional = param.optional ? ' (optional)' : ''
+      lines.push(
+        `| \`${param.name}\`${optional} | \`${escapeCode(param.type)}\` | ${escapeTableCell(description)} |`,
+      )
+    }
+  }
+
+  if (fn.returnType !== 'void') {
+    lines.push('')
+    lines.push(`**Returns:** \`${escapeCode(fn.returnType)}\``)
+
+    if (fn.jsdoc?.returns !== undefined) {
+      lines.push('')
+      lines.push(fn.jsdoc.returns)
+    }
+  }
+
+  if (fn.jsdoc?.deprecated !== undefined) {
+    lines.push('')
+    lines.push(`:::caution[Deprecated]`)
+    lines.push(fn.jsdoc.deprecated)
+    lines.push(':::')
+  }
+
+  if (fn.jsdoc?.since !== undefined) {
+    lines.push('')
+    lines.push(`*Since: ${fn.jsdoc.since}*`)
+  }
+
+  return lines.join('\n')
+}
+
+function generateTypesTable(types: readonly ExportedType[]): string {
+  const lines: string[] = []
+
+  lines.push('| Type | Kind | Description |')
+  lines.push('| ---- | ---- | ----------- |')
+
+  for (const type of types) {
+    const name = `[\`${type.name}\`](#${type.name.toLowerCase()})`
+    const kind = type.kind
+    const description = type.jsdoc?.description ?? ''
+    const firstLine = getFirstLine(description)
+    lines.push(`| ${name} | ${kind} | ${escapeTableCell(firstLine)} |`)
+  }
+
+  return lines.join('\n')
+}
+
+function generateTypeDetails(types: readonly ExportedType[]): string {
+  const sections: string[] = []
+
+  for (const type of types) {
+    sections.push(generateTypeDetail(type))
+  }
+
+  return sections.join('\n\n')
+}
+
+function generateTypeDetail(type: ExportedType): string {
+  const lines: string[] = []
+
+  lines.push(`#### \`${type.name}\``)
+  lines.push('')
+
+  if (type.jsdoc?.description !== undefined) {
+    lines.push(type.jsdoc.description)
+    lines.push('')
+  }
+
+  lines.push('```typescript')
+  lines.push(type.definition)
+  lines.push('```')
+
+  if (type.typeParameters !== undefined && type.typeParameters.length > 0) {
+    lines.push('')
+    lines.push(`**Type Parameters:** ${type.typeParameters.map(t => `\`${t}\``).join(', ')}`)
+  }
+
+  if (type.jsdoc?.deprecated !== undefined) {
+    lines.push('')
+    lines.push(`:::caution[Deprecated]`)
+    lines.push(type.jsdoc.deprecated)
+    lines.push(':::')
+  }
+
+  if (type.jsdoc?.since !== undefined) {
+    lines.push('')
+    lines.push(`*Since: ${type.jsdoc.since}*`)
+  }
+
+  return lines.join('\n')
+}
+
+function formatFunctionName(fn: ExportedFunction): string {
+  const name = `[\`${fn.name}\`](#${fn.name.toLowerCase()})`
+  const badges: string[] = []
+
+  if (fn.isAsync) {
+    badges.push('<Badge text="async" variant="note" size="small" />')
+  }
+
+  if (fn.isGenerator) {
+    badges.push('<Badge text="generator" variant="tip" size="small" />')
+  }
+
+  if (fn.isDefault) {
+    badges.push('<Badge text="default" variant="caution" size="small" />')
+  }
+
+  return badges.length > 0 ? `${name} ${badges.join(' ')}` : name
+}
+
+function getFirstLine(text: string): string {
+  const firstLine = text.split('\n')[0]?.trim() ?? ''
+
+  if (firstLine.length > 100) {
+    const truncated = firstLine.slice(0, 97)
+    const lastSpace = truncated.lastIndexOf(' ')
+    if (lastSpace > 50) {
+      return `${truncated.slice(0, lastSpace)}...`
+    }
+    return `${truncated}...`
+  }
+
+  return firstLine
+}
+
+function escapeTableCell(content: string): string {
+  return content.replaceAll('|', String.raw`\|`).replaceAll('\n', ' ')
+}
+
+function escapeCode(code: string): string {
+  return code.replaceAll('`', '\\`')
+}
+
+export function generateAPICompact(api: PackageAPI): string {
+  const lines: string[] = []
+
+  if (api.functions.length > 0) {
+    lines.push('**Functions:**')
+    for (const fn of api.functions) {
+      lines.push(`- \`${fn.name}(${formatParameterList(fn)})\` → \`${fn.returnType}\``)
+    }
+  }
+
+  if (api.types.length > 0) {
+    if (lines.length > 0) lines.push('')
+    lines.push('**Types:**')
+    for (const type of api.types) {
+      lines.push(`- \`${type.name}\` (${type.kind})`)
+    }
+  }
+
+  return lines.join('\n')
+}
+
+function formatParameterList(fn: ExportedFunction): string {
+  return fn.parameters.map(p => (p.optional ? `${p.name}?` : p.name)).join(', ')
+}
+
+export function generateCategoryReference(
+  functions: readonly ExportedFunction[],
+  types: readonly ExportedType[],
+  categoryName: string,
+): string {
+  const sections: string[] = []
+
+  sections.push(`### ${categoryName}`)
+  sections.push('')
+
+  if (functions.length > 0) {
+    sections.push('#### Functions')
+    sections.push('')
+    sections.push(generateFunctionsTable(functions))
+    sections.push('')
+    sections.push(generateFunctionDetails(functions))
+  }
+
+  if (types.length > 0) {
+    sections.push('#### Types')
+    sections.push('')
+    sections.push(generateTypesTable(types))
+    sections.push('')
+    sections.push(generateTypeDetails(types))
+  }
+
+  return sections.join('\n')
+}