@bfra.me/doc-sync 0.1.0

package/src/utils/sanitization.ts

@@ -0,0 +1,164 @@
+/**
+ * @bfra.me/doc-sync/utils/sanitization - Sanitization utilities for MDX content
+ * Provides comprehensive XSS prevention for user-generated content
+ */
+
+import {sanitizeInput} from '@bfra.me/es/validation'
+import escapeHtml from 'escape-html'
+
+/**
+ * Sanitize HTML content for MDX context
+ * Escapes all HTML entities and JSX curly braces to prevent XSS
+ *
+ * @param content - The content to sanitize
+ * @returns Sanitized content safe for MDX rendering
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeForMDX('<script>alert("xss")</script>')
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ * ```
+ */
+export function sanitizeForMDX(content: string): string {
+  // Use existing sanitizeInput from @bfra.me/es/validation
+  // This escapes: & < > " ' /
+  const escaped = sanitizeInput(content, {trim: false})
+
+  // Additionally escape JSX curly braces for MDX safety
+  return escaped.replaceAll('{', '&#123;').replaceAll('}', '&#125;')
+}
+
+/**
+ * Sanitize value for use in HTML/JSX attribute
+ * Uses escape-html library for proper attribute encoding
+ *
+ * @param value - The attribute value to sanitize
+ * @returns Sanitized value safe for attribute context
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeAttribute('value" onload="alert(1)')
+ * // Returns: 'value&quot; onload=&quot;alert(1)'
+ * ```
+ */
+export function sanitizeAttribute(value: string): string {
+  return escapeHtml(value)
+}
+
+/**
+ * JSX attribute parsed from a tag
+ */
+interface JSXAttribute {
+  readonly name: string
+  readonly value: string | null
+}
+
+/**
+ * Parse JSX tag attributes safely without using complex regex
+ * Uses a simple state machine approach to avoid ReDoS vulnerabilities
+ *
+ * @param tag - The complete JSX tag string (e.g., '<Badge text="hello" />')
+ * @returns Array of parsed attributes
+ *
+ * @example
+ * ```ts
+ * const attrs = parseJSXAttributes('<Card title="Hello" icon="star" />')
+ * // Returns: [{name: 'title', value: 'Hello'}, {name: 'icon', value: 'star'}]
+ * ```
+ */
+export function parseJSXAttributes(tag: string): readonly JSXAttribute[] {
+  const attrs: JSXAttribute[] = []
+
+  const spaceIndex = tag.indexOf(' ')
+  if (spaceIndex === -1) return attrs
+
+  const closeIndex = tag.lastIndexOf('>')
+  if (closeIndex === -1) return attrs
+
+  const attrRegion = tag.slice(spaceIndex + 1, closeIndex).trim()
+  let i = 0
+
+  while (i < attrRegion.length) {
+    while (i < attrRegion.length && /\s/.test(attrRegion.charAt(i))) i++
+    if (i >= attrRegion.length) break
+
+    let name = ''
+    while (i < attrRegion.length && /[\w-]/.test(attrRegion.charAt(i))) {
+      name += attrRegion[i]
+      i++
+    }
+
+    if (!name) break
+
+    while (i < attrRegion.length && /\s/.test(attrRegion.charAt(i))) i++
+
+    if (i >= attrRegion.length || attrRegion[i] !== '=') {
+      attrs.push({name, value: null})
+      continue
+    }
+
+    i++
+    while (i < attrRegion.length && /\s/.test(attrRegion.charAt(i))) i++
+
+    if (i >= attrRegion.length) {
+      attrs.push({name, value: ''})
+      break
+    }
+
+    let value = ''
+    const quote = attrRegion[i]
+    if (quote === '"' || quote === "'") {
+      i++
+      while (i < attrRegion.length && attrRegion[i] !== quote) {
+        value += attrRegion[i]
+        i++
+      }
+      if (i < attrRegion.length) i++
+    } else {
+      while (i < attrRegion.length && !/[\s/>]/.test(attrRegion.charAt(i))) {
+        value += attrRegion[i]
+        i++
+      }
+    }
+
+    attrs.push({name, value})
+  }
+
+  return attrs
+}
+
+/**
+ * Sanitize a complete JSX tag including all attributes
+ * Parses the tag and escapes all attribute values to prevent XSS
+ *
+ * @param tag - The complete JSX tag string
+ * @returns Sanitized JSX tag safe for rendering
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeJSXTag('<Badge text="v1.0.0" onclick="alert(1)" />')
+ * // Returns: '<Badge text="v1.0.0" onclick="alert(1)" />' (with escaped values)
+ * ```
+ */
+export function sanitizeJSXTag(tag: string): string {
+  // Extract tag name
+  const tagMatch = tag.match(/^<([A-Z][a-zA-Z0-9]*)/)
+  if (!tagMatch || typeof tagMatch[1] !== 'string' || tagMatch[1].length === 0) {
+    // Not a valid JSX tag, escape everything
+    return escapeHtml(tag)
+  }
+
+  const tagName = tagMatch[1]
+  const selfClosing = tag.endsWith('/>')
+  const attributes = parseJSXAttributes(tag)
+
+  // Sanitize each attribute value
+  const sanitizedAttrs = attributes.map(({name, value}) => {
+    if (value === null) return name
+    const escaped = escapeHtml(value)
+    return `${name}="${escaped}"`
+  })
+
+  const attrString = sanitizedAttrs.length > 0 ? ` ${sanitizedAttrs.join(' ')}` : ''
+  return `<${tagName}${attrString}${selfClosing ? ' />' : '>'}`
+}

package/src/watcher/change-detector.ts

@@ -0,0 +1,138 @@
+import type {ChangeDetector} from '@bfra.me/es/watcher'
+import type {FileChangeEvent, PackageInfo} from '../types'
+
+import {createChangeDetector as createBaseDetector} from '@bfra.me/es/watcher'
+
+import {categorizeFile, type FileCategory} from './file-watcher'
+
+export interface DocChangeDetectorOptions {
+  readonly algorithm?: 'sha256' | 'md5'
+}
+
+export interface PackageChangeAnalysis {
+  readonly packageName: string
+  readonly needsRegeneration: boolean
+  readonly changedCategories: readonly FileCategory[]
+  readonly changedFiles: readonly string[]
+}
+
+export interface DocChangeDetector {
+  readonly hasChanged: (filePath: string) => Promise<boolean>
+  readonly record: (filePath: string) => Promise<void>
+  readonly recordPackage: (pkg: PackageInfo, files: readonly string[]) => Promise<void>
+  readonly clear: (filePath: string) => void
+  readonly clearAll: () => void
+  readonly analyzeChanges: (events: readonly FileChangeEvent[]) => Promise<PackageChangeAnalysis[]>
+}
+
+export function createDocChangeDetector(options: DocChangeDetectorOptions = {}): DocChangeDetector {
+  const baseDetector: ChangeDetector = createBaseDetector({algorithm: options.algorithm})
+  const packageFiles = new Map<string, Set<string>>()
+
+  return {
+    async hasChanged(filePath: string): Promise<boolean> {
+      return baseDetector.hasChanged(filePath)
+    },
+
+    async record(filePath: string): Promise<void> {
+      await baseDetector.record(filePath)
+    },
+
+    async recordPackage(pkg: PackageInfo, files: readonly string[]): Promise<void> {
+      const fileSet = new Set(files)
+      packageFiles.set(pkg.name, fileSet)
+
+      await Promise.all(files.map(async file => baseDetector.record(file)))
+    },
+
+    clear(filePath: string): void {
+      baseDetector.clear(filePath)
+
+      for (const fileSet of packageFiles.values()) {
+        fileSet.delete(filePath)
+      }
+    },
+
+    clearAll(): void {
+      baseDetector.clearAll()
+      packageFiles.clear()
+    },
+
+    async analyzeChanges(events: readonly FileChangeEvent[]): Promise<PackageChangeAnalysis[]> {
+      const packageChanges = new Map<string, {categories: Set<FileCategory>; files: string[]}>()
+
+      for (const event of events) {
+        const packageName = event.packageName ?? '__unknown__'
+        const category = categorizeFile(event.path)
+
+        let analysis = packageChanges.get(packageName)
+        if (analysis === undefined) {
+          analysis = {categories: new Set(), files: []}
+          packageChanges.set(packageName, analysis)
+        }
+
+        if (category !== 'unknown') {
+          analysis.categories.add(category)
+        }
+        analysis.files.push(event.path)
+      }
+
+      const results: PackageChangeAnalysis[] = []
+
+      for (const [packageName, analysis] of packageChanges) {
+        const changedCategories = [...analysis.categories]
+
+        // Package needs regeneration if any documentation-relevant files changed
+        const needsRegeneration =
+          changedCategories.includes('readme') ||
+          changedCategories.includes('package-json') ||
+          changedCategories.includes('source')
+
+        results.push({
+          packageName,
+          needsRegeneration,
+          changedCategories,
+          changedFiles: analysis.files,
+        })
+      }
+
+      return results
+    },
+  }
+}
+
+export type RegenerationScope = 'full' | 'api-only' | 'readme-only' | 'metadata-only' | 'none'
+
+export function determineRegenerationScope(
+  changedCategories: readonly FileCategory[],
+): RegenerationScope {
+  const hasReadme = changedCategories.includes('readme')
+  const hasSource = changedCategories.includes('source')
+  const hasPackageJson = changedCategories.includes('package-json')
+
+  if (hasReadme && hasSource) {
+    return 'full'
+  }
+
+  if (hasSource) {
+    return 'api-only'
+  }
+
+  if (hasReadme) {
+    return 'readme-only'
+  }
+
+  if (hasPackageJson) {
+    return 'metadata-only'
+  }
+
+  return 'none'
+}
+
+export async function hasAnyFileChanged(
+  detector: DocChangeDetector,
+  files: readonly string[],
+): Promise<boolean> {
+  const results = await Promise.all(files.map(async file => detector.hasChanged(file)))
+  return results.some(changed => changed)
+}

package/src/watcher/debouncer.ts

@@ -0,0 +1,168 @@
+import type {Debouncer} from '@bfra.me/es/watcher'
+import type {FileChangeEvent} from '../types'
+
+import {createDebouncer as createBaseDebouncer} from '@bfra.me/es/watcher'
+
+export interface DocDebouncerOptions {
+  readonly debounceMs?: number
+  readonly maxWaitMs?: number
+}
+
+export type BatchChangeHandler = (events: readonly FileChangeEvent[]) => void | Promise<void>
+
+export interface DocDebouncer {
+  readonly add: (event: FileChangeEvent) => void
+  readonly addAll: (events: readonly FileChangeEvent[]) => void
+  readonly flush: () => void
+  readonly cancel: () => void
+  readonly getPendingCount: () => number
+}
+
+export function createDocDebouncer(
+  handler: BatchChangeHandler,
+  options: DocDebouncerOptions = {},
+): DocDebouncer {
+  const {debounceMs = 300, maxWaitMs = 5000} = options
+
+  let pendingEvents: FileChangeEvent[] = []
+  let maxWaitTimeout: ReturnType<typeof setTimeout> | undefined
+
+  function processEvents(events: FileChangeEvent[]): void {
+    if (maxWaitTimeout !== undefined) {
+      clearTimeout(maxWaitTimeout)
+      maxWaitTimeout = undefined
+    }
+
+    const deduplicated = deduplicateEvents(events)
+    if (deduplicated.length > 0) {
+      Promise.resolve(handler(deduplicated)).catch(error => {
+        console.error('[doc-sync] Error in batch handler:', error)
+      })
+    }
+  }
+
+  const baseDebouncer: Debouncer<FileChangeEvent> = createBaseDebouncer(events => {
+    processEvents(events)
+    pendingEvents = []
+  }, debounceMs)
+
+  function startMaxWaitTimer(): void {
+    if (maxWaitTimeout === undefined) {
+      maxWaitTimeout = setTimeout(() => {
+        baseDebouncer.flush()
+      }, maxWaitMs)
+    }
+  }
+
+  return {
+    add(event: FileChangeEvent): void {
+      pendingEvents.push(event)
+      startMaxWaitTimer()
+      baseDebouncer.add(event)
+    },
+
+    addAll(events: readonly FileChangeEvent[]): void {
+      for (const event of events) {
+        pendingEvents.push(event)
+        baseDebouncer.add(event)
+      }
+      if (events.length > 0) {
+        startMaxWaitTimer()
+      }
+    },
+
+    flush(): void {
+      if (maxWaitTimeout !== undefined) {
+        clearTimeout(maxWaitTimeout)
+        maxWaitTimeout = undefined
+      }
+      baseDebouncer.flush()
+    },
+
+    cancel(): void {
+      if (maxWaitTimeout !== undefined) {
+        clearTimeout(maxWaitTimeout)
+        maxWaitTimeout = undefined
+      }
+      pendingEvents = []
+      baseDebouncer.cancel()
+    },
+
+    getPendingCount(): number {
+      return pendingEvents.length
+    },
+  }
+}
+
+export function deduplicateEvents(events: readonly FileChangeEvent[]): FileChangeEvent[] {
+  const latestByPath = new Map<string, FileChangeEvent>()
+
+  for (const event of events) {
+    const existing = latestByPath.get(event.path)
+
+    // Keep the most recent event for each path
+    if (existing === undefined || event.timestamp > existing.timestamp) {
+      latestByPath.set(event.path, event)
+    }
+  }
+
+  return [...latestByPath.values()]
+}
+
+export function consolidateEvents(events: readonly FileChangeEvent[]): FileChangeEvent[] {
+  const byPath = new Map<string, FileChangeEvent[]>()
+
+  for (const event of events) {
+    const existing = byPath.get(event.path)
+    if (existing === undefined) {
+      byPath.set(event.path, [event])
+    } else {
+      existing.push(event)
+    }
+  }
+
+  const consolidated: FileChangeEvent[] = []
+
+  for (const [, pathEvents] of byPath) {
+    const firstEvent = pathEvents[0]
+    if (firstEvent === undefined) {
+      continue
+    }
+
+    if (pathEvents.length === 1) {
+      consolidated.push(firstEvent)
+      continue
+    }
+
+    // Sort by timestamp to get event sequence
+    pathEvents.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime())
+
+    const first = pathEvents[0]
+    const last = pathEvents.at(-1)
+
+    if (first === undefined || last === undefined) {
+      continue
+    }
+
+    // If file was added then removed, skip entirely
+    if (first.type === 'add' && last.type === 'unlink') {
+      continue
+    }
+
+    // If file was removed then added, treat as change
+    if (first.type === 'unlink' && last.type === 'add') {
+      consolidated.push({
+        type: 'change',
+        path: last.path,
+        packageName: last.packageName,
+        timestamp: last.timestamp,
+      })
+      continue
+    }
+
+    // Otherwise use the latest event
+    consolidated.push(last)
+  }
+
+  return consolidated
+}

package/src/watcher/file-watcher.ts

@@ -0,0 +1,164 @@
+import type {WatcherOptions} from '@bfra.me/es/watcher'
+import type {FileChangeEvent} from '../types'
+
+import path from 'node:path'
+import process from 'node:process'
+
+import {createFileWatcher as createBaseWatcher} from '@bfra.me/es/watcher'
+
+export interface DocWatcherOptions {
+  readonly rootDir?: string
+  readonly debounceMs?: number
+  readonly additionalIgnore?: readonly string[]
+  readonly usePolling?: boolean
+}
+
+const DEFAULT_WATCH_PATTERNS = [
+  'packages/*/README.md',
+  'packages/*/readme.md',
+  'packages/*/package.json',
+  'packages/*/src/**/*.ts',
+  'packages/*/src/**/*.tsx',
+] as const
+
+const DEFAULT_IGNORE_PATTERNS = [
+  '**/node_modules/**',
+  '**/lib/**',
+  '**/dist/**',
+  '**/.git/**',
+  '**/coverage/**',
+  '**/*.test.ts',
+  '**/*.spec.ts',
+  '**/__tests__/**',
+  '**/__mocks__/**',
+] as const
+
+export type DocChangeHandler = (events: readonly FileChangeEvent[]) => void | Promise<void>
+
+export interface DocFileWatcher {
+  readonly start: () => Promise<void>
+  readonly close: () => Promise<void>
+  readonly onChanges: (handler: DocChangeHandler) => () => void
+  readonly getWatchedPaths: () => readonly string[]
+}
+
+function extractPackageName(filePath: string, root: string): string | undefined {
+  const relativePath = path.relative(root, filePath)
+  const parts = relativePath.split(path.sep)
+
+  if (parts[0] === 'packages' && parts.length > 1) {
+    return parts[1]
+  }
+
+  return undefined
+}
+
+export function createDocWatcher(options: DocWatcherOptions = {}): DocFileWatcher {
+  const {
+    rootDir = process.cwd(),
+    debounceMs = 300,
+    additionalIgnore = [],
+    usePolling = false,
+  } = options
+
+  const watchPaths = DEFAULT_WATCH_PATTERNS.map(pattern => path.join(rootDir, pattern))
+  const ignoredPatterns: string[] = [...DEFAULT_IGNORE_PATTERNS, ...additionalIgnore]
+
+  const watcherOptions: WatcherOptions = {
+    debounceMs,
+    ignored: ignoredPatterns,
+    usePolling,
+  }
+
+  const baseWatcher = createBaseWatcher(watchPaths, watcherOptions)
+  const handlers = new Set<DocChangeHandler>()
+
+  function transformToDocEvents(
+    changes: readonly {path: string; type: 'add' | 'change' | 'unlink'; timestamp: number}[],
+  ): FileChangeEvent[] {
+    return changes.map(change => ({
+      type: change.type,
+      path: change.path,
+      packageName: extractPackageName(change.path, rootDir),
+      timestamp: new Date(change.timestamp),
+    }))
+  }
+
+  return {
+    async start(): Promise<void> {
+      baseWatcher.on('change', event => {
+        const docEvents = transformToDocEvents(event.changes)
+        for (const handler of handlers) {
+          Promise.resolve(handler(docEvents)).catch(error => {
+            console.error('[doc-sync] Error in change handler:', error)
+          })
+        }
+      })
+
+      await baseWatcher.start()
+    },
+
+    async close(): Promise<void> {
+      await baseWatcher.close()
+      handlers.clear()
+    },
+
+    onChanges(handler: DocChangeHandler): () => void {
+      handlers.add(handler)
+      return () => {
+        handlers.delete(handler)
+      }
+    },
+
+    getWatchedPaths(): readonly string[] {
+      return watchPaths
+    },
+  }
+}
+
+export type FileCategory = 'readme' | 'source' | 'package-json' | 'unknown'
+
+export function categorizeFile(filePath: string): FileCategory {
+  const basename = path.basename(filePath).toLowerCase()
+
+  if (basename === 'readme.md' || basename === 'readme') {
+    return 'readme'
+  }
+
+  if (basename === 'package.json') {
+    return 'package-json'
+  }
+
+  const ext = path.extname(filePath).toLowerCase()
+  if (ext === '.ts' || ext === '.tsx') {
+    return 'source'
+  }
+
+  return 'unknown'
+}
+
+export function groupChangesByPackage(
+  events: readonly FileChangeEvent[],
+): Map<string, FileChangeEvent[]> {
+  const grouped = new Map<string, FileChangeEvent[]>()
+
+  for (const event of events) {
+    const pkg = event.packageName ?? '__unknown__'
+    const existing = grouped.get(pkg)
+
+    if (existing === undefined) {
+      grouped.set(pkg, [event])
+    } else {
+      existing.push(event)
+    }
+  }
+
+  return grouped
+}
+
+export function filterDocumentationChanges(events: readonly FileChangeEvent[]): FileChangeEvent[] {
+  return events.filter(event => {
+    const category = categorizeFile(event.path)
+    return category !== 'unknown'
+  })
+}

package/src/watcher/index.ts

@@ -0,0 +1,27 @@
+export {
+  createDocChangeDetector,
+  determineRegenerationScope,
+  hasAnyFileChanged,
+} from './change-detector'
+export type {
+  DocChangeDetector,
+  DocChangeDetectorOptions,
+  PackageChangeAnalysis,
+  RegenerationScope,
+} from './change-detector'
+
+export {consolidateEvents, createDocDebouncer, deduplicateEvents} from './debouncer'
+export type {BatchChangeHandler, DocDebouncer, DocDebouncerOptions} from './debouncer'
+
+export {
+  categorizeFile,
+  createDocWatcher,
+  filterDocumentationChanges,
+  groupChangesByPackage,
+} from './file-watcher'
+export type {
+  DocChangeHandler,
+  DocFileWatcher,
+  DocWatcherOptions,
+  FileCategory,
+} from './file-watcher'