@bfra.me/doc-sync 0.1.0

package/src/types.ts

@@ -0,0 +1,423 @@
+/**
+ * @bfra.me/doc-sync/types - Core type definitions for documentation synchronization
+ */
+
+import type {Result} from '@bfra.me/es/result'
+import type {z} from 'zod'
+
+/**
+ * Metadata extracted from a package.json file
+ */
+export interface PackageInfo {
+  /** Package name from package.json */
+  readonly name: string
+  /** Package version from package.json */
+  readonly version: string
+  /** Package description from package.json */
+  readonly description?: string
+  /** Keywords for categorization */
+  readonly keywords?: readonly string[]
+  /** Path to the package directory */
+  readonly packagePath: string
+  /** Path to the package's source directory */
+  readonly srcPath: string
+  /** Path to the package's README file if it exists */
+  readonly readmePath?: string
+  /** Custom documentation config from package.json "docs" field */
+  readonly docsConfig?: DocConfigSource
+}
+
+/**
+ * Source configuration for documentation, from package.json or docs.config.json
+ */
+export interface DocConfigSource {
+  /** Custom title override for the documentation page */
+  readonly title?: string
+  /** Custom description override */
+  readonly description?: string
+  /** Sidebar configuration */
+  readonly sidebar?: {
+    /** Label shown in sidebar navigation */
+    readonly label?: string
+    /** Sort order in sidebar */
+    readonly order?: number
+    /** Whether to hide from sidebar */
+    readonly hidden?: boolean
+  }
+  /** Sections to exclude from auto-generation */
+  readonly excludeSections?: readonly string[]
+  /** Custom frontmatter fields to include */
+  readonly frontmatter?: Record<string, unknown>
+}
+
+/**
+ * Configuration for documentation generation
+ */
+export interface DocConfig {
+  /** Root directory of the monorepo */
+  readonly rootDir: string
+  /** Output directory for generated documentation */
+  readonly outputDir: string
+  /** Glob patterns for packages to include */
+  readonly includePatterns: readonly string[]
+  /** Glob patterns for packages to exclude */
+  readonly excludePatterns?: readonly string[]
+  /** Whether to watch for changes */
+  readonly watch?: boolean
+  /** Debounce delay in milliseconds for watch mode */
+  readonly debounceMs?: number
+}
+
+/**
+ * Error types for parse operations
+ */
+export type ParseErrorCode =
+  | 'INVALID_SYNTAX'
+  | 'FILE_NOT_FOUND'
+  | 'READ_ERROR'
+  | 'MALFORMED_JSON'
+  | 'UNSUPPORTED_FORMAT'
+
+/**
+ * Structured error for parse operations
+ */
+export interface ParseError {
+  /** Error classification code */
+  readonly code: ParseErrorCode
+  /** Human-readable error message */
+  readonly message: string
+  /** File path that caused the error */
+  readonly filePath?: string
+  /** Line number where error occurred (1-indexed) */
+  readonly line?: number
+  /** Column number where error occurred (1-indexed) */
+  readonly column?: number
+  /** Original error if wrapping */
+  readonly cause?: unknown
+}
+
+/**
+ * Result type for parse operations
+ */
+export type ParseResult<T> = Result<T, ParseError>
+
+/**
+ * Error types for sync operations
+ */
+export type SyncErrorCode =
+  | 'WRITE_ERROR'
+  | 'VALIDATION_ERROR'
+  | 'GENERATION_ERROR'
+  | 'PACKAGE_NOT_FOUND'
+  | 'CONFIG_ERROR'
+
+/**
+ * Structured error for sync operations
+ */
+export interface SyncError {
+  /** Error classification code */
+  readonly code: SyncErrorCode
+  /** Human-readable error message */
+  readonly message: string
+  /** Package name that caused the error */
+  readonly packageName?: string
+  /** File path that caused the error */
+  readonly filePath?: string
+  /** Original error if wrapping */
+  readonly cause?: unknown
+}
+
+/**
+ * Result type for sync operations
+ */
+export type SyncResult<T> = Result<T, SyncError>
+
+/**
+ * Information about a single sync operation
+ */
+export interface SyncInfo {
+  /** Package name that was synced */
+  readonly packageName: string
+  /** Output file path */
+  readonly outputPath: string
+  /** Whether the file was created or updated */
+  readonly action: 'created' | 'updated' | 'unchanged'
+  /** Timestamp of the sync operation */
+  readonly timestamp: Date
+}
+
+/**
+ * Summary of a complete sync run
+ */
+export interface SyncSummary {
+  /** Total number of packages processed */
+  readonly totalPackages: number
+  /** Number of successful syncs */
+  readonly successCount: number
+  /** Number of failed syncs */
+  readonly failureCount: number
+  /** Number of unchanged packages */
+  readonly unchangedCount: number
+  /** Details of each sync operation */
+  readonly details: readonly SyncInfo[]
+  /** Errors encountered during sync */
+  readonly errors: readonly SyncError[]
+  /** Duration of the sync run in milliseconds */
+  readonly durationMs: number
+}
+
+/**
+ * Extracted JSDoc information
+ */
+export interface JSDocInfo {
+  /** Main description from JSDoc */
+  readonly description?: string
+  /** @param tags with name and description */
+  readonly params?: readonly JSDocParam[]
+  /** @returns description */
+  readonly returns?: string
+  /** @example code blocks */
+  readonly examples?: readonly string[]
+  /** @deprecated message if present */
+  readonly deprecated?: string
+  /** @since version if present */
+  readonly since?: string
+  /** @see references */
+  readonly see?: readonly string[]
+  /** Custom tags not in standard set */
+  readonly customTags?: readonly JSDocTag[]
+}
+
+/**
+ * A single JSDoc @param entry
+ */
+export interface JSDocParam {
+  /** Parameter name */
+  readonly name: string
+  /** Parameter type (from JSDoc or inferred) */
+  readonly type?: string
+  /** Parameter description */
+  readonly description?: string
+  /** Whether the parameter is optional */
+  readonly optional?: boolean
+  /** Default value if specified */
+  readonly defaultValue?: string
+}
+
+/**
+ * A custom JSDoc tag
+ */
+export interface JSDocTag {
+  /** Tag name without @ symbol */
+  readonly name: string
+  /** Tag value/content */
+  readonly value?: string
+}
+
+/**
+ * Information about an exported function
+ */
+export interface ExportedFunction {
+  /** Function name */
+  readonly name: string
+  /** JSDoc documentation */
+  readonly jsdoc?: JSDocInfo
+  /** Function signature as string */
+  readonly signature: string
+  /** Whether it's async */
+  readonly isAsync: boolean
+  /** Whether it's a generator */
+  readonly isGenerator: boolean
+  /** Parameter information */
+  readonly parameters: readonly FunctionParameter[]
+  /** Return type as string */
+  readonly returnType: string
+  /** Whether it's the default export */
+  readonly isDefault: boolean
+}
+
+/**
+ * Function parameter information
+ */
+export interface FunctionParameter {
+  /** Parameter name */
+  readonly name: string
+  /** TypeScript type */
+  readonly type: string
+  /** Whether optional */
+  readonly optional: boolean
+  /** Default value if provided */
+  readonly defaultValue?: string
+}
+
+/**
+ * Information about an exported type or interface
+ */
+export interface ExportedType {
+  /** Type name */
+  readonly name: string
+  /** JSDoc documentation */
+  readonly jsdoc?: JSDocInfo
+  /** Full type definition as string */
+  readonly definition: string
+  /** Kind of type declaration */
+  readonly kind: 'interface' | 'type' | 'enum' | 'class'
+  /** Whether it's the default export */
+  readonly isDefault: boolean
+  /** Type parameters (generics) */
+  readonly typeParameters?: readonly string[]
+}
+
+/**
+ * Complete API surface extracted from a package
+ */
+export interface PackageAPI {
+  /** Exported functions */
+  readonly functions: readonly ExportedFunction[]
+  /** Exported types/interfaces */
+  readonly types: readonly ExportedType[]
+  /** Re-exported modules */
+  readonly reExports: readonly ReExport[]
+}
+
+/**
+ * Information about a re-export statement
+ */
+export interface ReExport {
+  /** Module path being re-exported from */
+  readonly from: string
+  /** Named exports being re-exported, or '*' for all */
+  readonly exports: readonly string[] | '*'
+  /** Alias if renamed during re-export */
+  readonly alias?: string
+}
+
+/**
+ * Parsed README content with sections
+ */
+export interface ReadmeContent {
+  /** Main title (first H1) */
+  readonly title?: string
+  /** Content before first heading */
+  readonly preamble?: string
+  /** Structured sections by heading */
+  readonly sections: readonly ReadmeSection[]
+  /** Raw markdown content */
+  readonly raw: string
+}
+
+/**
+ * A section in the README
+ */
+export interface ReadmeSection {
+  /** Section heading text */
+  readonly heading: string
+  /** Heading level (1-6) */
+  readonly level: number
+  /** Section content (markdown) */
+  readonly content: string
+  /** Nested subsections */
+  readonly children: readonly ReadmeSection[]
+}
+
+/**
+ * MDX frontmatter for Starlight
+ */
+export interface MDXFrontmatter {
+  /** Page title */
+  readonly title: string
+  /** Page description for SEO */
+  readonly description?: string
+  /** Sidebar configuration */
+  readonly sidebar?: {
+    readonly label?: string
+    readonly order?: number
+    readonly hidden?: boolean
+    readonly badge?:
+      | string
+      | {
+          readonly text: string
+          readonly variant?: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default'
+        }
+  }
+  /** Table of contents configuration */
+  readonly tableOfContents?:
+    | boolean
+    | {
+        readonly minHeadingLevel?: number
+        readonly maxHeadingLevel?: number
+      }
+  /** Template to use */
+  readonly template?: 'doc' | 'splash'
+  /** Hero configuration for splash template */
+  readonly hero?: {
+    readonly title?: string
+    readonly tagline?: string
+    readonly image?: {readonly src: string; readonly alt: string}
+    readonly actions?: readonly {
+      readonly text: string
+      readonly link: string
+      readonly icon?: string
+      readonly variant?: 'primary' | 'secondary' | 'minimal'
+    }[]
+  }
+}
+
+/**
+ * Generated MDX document
+ */
+export interface MDXDocument {
+  /** Frontmatter configuration */
+  readonly frontmatter: MDXFrontmatter
+  /** Document body content */
+  readonly content: string
+  /** Full rendered document */
+  readonly rendered: string
+}
+
+/**
+ * Sentinel markers for content preservation
+ */
+export const SENTINEL_MARKERS = {
+  AUTO_START: '{/* AUTO-GENERATED-START */}',
+  AUTO_END: '{/* AUTO-GENERATED-END */}',
+  MANUAL_START: '{/* MANUAL-CONTENT-START */}',
+  MANUAL_END: '{/* MANUAL-CONTENT-END */}',
+} as const
+
+/**
+ * File change event from watcher
+ */
+export interface FileChangeEvent {
+  /** Type of change */
+  readonly type: 'add' | 'change' | 'unlink'
+  /** Absolute path to the changed file */
+  readonly path: string
+  /** Package name if determinable */
+  readonly packageName?: string
+  /** Timestamp of the change */
+  readonly timestamp: Date
+}
+
+/**
+ * Options for the CLI
+ */
+export interface CLIOptions {
+  /** Root directory to operate from */
+  readonly root?: string
+  /** Specific packages to sync */
+  readonly packages?: readonly string[]
+  /** Run in watch mode */
+  readonly watch?: boolean
+  /** Dry run without writing files */
+  readonly dryRun?: boolean
+  /** Verbose logging */
+  readonly verbose?: boolean
+  /** Quiet mode (minimal output) */
+  readonly quiet?: boolean
+}
+
+/**
+ * Zod schema type helper for runtime validation
+ */
+export type InferSchema<T extends z.ZodTypeAny> = z.infer<T>

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @bfra.me/doc-sync/utils - Security utilities for MDX generation
+ */
+
+export {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  hasComponent,
+  parseJSXTags,
+} from './safe-patterns'
+
+export {parseJSXAttributes, sanitizeAttribute, sanitizeForMDX, sanitizeJSXTag} from './sanitization'

package/src/utils/safe-patterns.ts

@@ -0,0 +1,280 @@
+/**
+ * @bfra.me/doc-sync/utils/safe-patterns - Safe regex patterns and utilities for MDX/HTML parsing
+ * All patterns are designed to prevent ReDoS attacks
+ */
+
+import remarkParse from 'remark-parse'
+import {unified} from 'unified'
+
+/**
+ * Create safe heading pattern for specific level
+ * Uses explicit character class instead of greedy `.+` to prevent ReDoS
+ *
+ * @param level - Heading level (1-6)
+ * @returns Safe regex pattern for the heading level
+ *
+ * @example
+ * ```ts
+ * const h2Pattern = createHeadingPattern(2)
+ * const matches = content.match(h2Pattern)
+ * ```
+ */
+export function createHeadingPattern(level: number): RegExp {
+  if (level < 1 || level > 6) {
+    throw new Error('Heading level must be between 1 and 6')
+  }
+  const hashes = '#'.repeat(level)
+  // Use [^\r\n]+ instead of .+ to prevent ReDoS
+  return new RegExp(`^${hashes} ([^\r\n]+)$`, 'gm')
+}
+
+/**
+ * Check if content contains a specific JSX component
+ * Uses a safe pattern that avoids catastrophic backtracking
+ *
+ * @param content - The MDX/HTML content to search
+ * @param componentName - Name of the component to find (e.g., 'Card', 'Badge')
+ * @returns True if the component is found
+ *
+ * @example
+ * ```ts
+ * const hasCard = hasComponent(content, 'Card')
+ * const hasCardGrid = hasComponent(content, 'CardGrid')
+ * ```
+ */
+export function hasComponent(content: string, componentName: string): boolean {
+  // Escape special regex characters in component name
+  const escaped = componentName.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`)
+  // Match opening tag or self-closing tag with word boundary
+  const pattern = new RegExp(String.raw`<${escaped}(?:\s[^>]*)?(?:>|\/>)`)
+  return pattern.test(content)
+}
+
+/**
+ * Extract code blocks from markdown content using unified/remark (safe, no regex)
+ * This approach uses AST parsing instead of regex to avoid ReDoS vulnerabilities
+ *
+ * @param content - The markdown content to parse
+ * @returns Array of code block strings with their language identifiers
+ *
+ * @example
+ * ```ts
+ * const blocks = extractCodeBlocks(content)
+ * for (const block of blocks) {
+ *   console.log(block)
+ * }
+ * ```
+ */
+export function extractCodeBlocks(content: string): readonly string[] {
+  const processor = unified().use(remarkParse)
+  let tree
+
+  try {
+    tree = processor.parse(content)
+  } catch {
+    // If parsing fails, return empty array instead of throwing
+    return []
+  }
+
+  const blocks: string[] = []
+
+  interface MarkdownNode {
+    type?: string
+    lang?: string | null
+    value?: string
+    children?: MarkdownNode[]
+  }
+
+  function visit(node: MarkdownNode): void {
+    if (node.type === 'code') {
+      const lang = node.lang ?? ''
+      const value = node.value ?? ''
+      blocks.push(`\`\`\`${lang}\n${value}\n\`\`\``)
+    }
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) {
+        visit(child)
+      }
+    }
+  }
+
+  visit(tree as MarkdownNode)
+  return blocks
+}
+
+/**
+ * Parse JSX tags from content using a safe, non-backtracking approach.
+ * Uses a state machine instead of regex to prevent ReDoS.
+ *
+ * @param content - The MDX/HTML content to parse
+ * @returns Array of matched JSX tags with their positions
+ */
+export function parseJSXTags(
+  content: string,
+): readonly {tag: string; index: number; isClosing: boolean; isSelfClosing: boolean}[] {
+  const results: {tag: string; index: number; isClosing: boolean; isSelfClosing: boolean}[] = []
+  let i = 0
+
+  while (i < content.length) {
+    if (content[i] !== '<') {
+      i++
+      continue
+    }
+
+    const startIndex = i
+    i++
+
+    if (i >= content.length) break
+
+    const isClosing = content[i] === '/'
+    if (isClosing) {
+      i++
+      if (i >= content.length) break
+    }
+
+    // JSX components must start with uppercase (React convention)
+    if (!/^[A-Z]/.test(content[i] ?? '')) {
+      continue
+    }
+
+    let tagName = ''
+    while (i < content.length && /^[a-z0-9]/i.test(content[i] ?? '')) {
+      tagName += content[i]
+      i++
+    }
+
+    if (tagName.length === 0) {
+      continue
+    }
+
+    if (isClosing) {
+      if (i < content.length && content[i] === '>') {
+        results.push({
+          tag: `</${tagName}>`,
+          index: startIndex,
+          isClosing: true,
+          isSelfClosing: false,
+        })
+        i++
+      }
+      continue
+    }
+
+    // Skip attributes while tracking nested structures
+    let depth = 0
+    let foundEnd = false
+    let isSelfClosing = false
+
+    while (i < content.length && !foundEnd) {
+      const char = content[i]
+
+      // Skip quoted string contents to avoid misinterpreting > inside strings
+      if ((char === '"' || char === "'") && depth === 0) {
+        const quote = char
+        i++
+        while (i < content.length && content[i] !== quote) {
+          if (content[i] === '\\' && i + 1 < content.length) {
+            i += 2
+          } else {
+            i++
+          }
+        }
+        if (i < content.length) i++
+        continue
+      }
+
+      // Track brace depth for JSX expressions like {value}
+      if (char === '{') {
+        depth++
+        i++
+        continue
+      }
+      if (char === '}') {
+        depth = Math.max(0, depth - 1)
+        i++
+        continue
+      }
+
+      // Only match tag end when not inside a JSX expression
+      if (depth === 0) {
+        if (char === '/' && i + 1 < content.length && content[i + 1] === '>') {
+          isSelfClosing = true
+          foundEnd = true
+          i += 2
+          continue
+        }
+        if (char === '>') {
+          foundEnd = true
+          i++
+          continue
+        }
+      }
+
+      i++
+    }
+
+    if (foundEnd) {
+      const fullTag = content.slice(startIndex, i)
+      results.push({tag: fullTag, index: startIndex, isClosing: false, isSelfClosing})
+    }
+  }
+
+  return results
+}
+
+/**
+ * Find empty markdown links in content using safe parsing.
+ * Uses indexOf-based scanning instead of regex to prevent ReDoS.
+ *
+ * @param content - The markdown content to check
+ * @returns Array of positions where empty links were found
+ */
+export function findEmptyMarkdownLinks(content: string): readonly number[] {
+  const positions: number[] = []
+  let pos = 0
+
+  while (pos < content.length) {
+    const openBracket = content.indexOf('[', pos)
+    if (openBracket === -1) break
+
+    // Handle nested brackets
+    let bracketDepth = 1
+    let closeBracket = openBracket + 1
+    while (closeBracket < content.length && bracketDepth > 0) {
+      if (content[closeBracket] === '[') {
+        bracketDepth++
+      } else if (content[closeBracket] === ']') {
+        bracketDepth--
+      }
+      closeBracket++
+    }
+
+    if (bracketDepth !== 0) {
+      pos = openBracket + 1
+      continue
+    }
+
+    closeBracket--
+
+    if (closeBracket + 1 < content.length && content[closeBracket + 1] === '(') {
+      let parenPos = closeBracket + 2
+      let isEmptyOrWhitespace = true
+
+      while (parenPos < content.length && content[parenPos] !== ')') {
+        if (!/^\s/.test(content[parenPos] ?? '')) {
+          isEmptyOrWhitespace = false
+          break
+        }
+        parenPos++
+      }
+
+      if (isEmptyOrWhitespace && parenPos < content.length && content[parenPos] === ')') {
+        positions.push(openBracket)
+      }
+    }
+
+    pos = closeBracket + 1
+  }
+
+  return positions
+}