@bfra.me/doc-sync 0.1.0 → 0.1.2

package/lib/utils/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @bfra.me/doc-sync/utils/safe-patterns - Safe regex patterns and utilities for MDX/HTML parsing
+ * All patterns are designed to prevent ReDoS attacks
+ */
+/**
+ * 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)
+ * ```
+ */
+declare function createHeadingPattern(level: number): RegExp;
+/**
+ * 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')
+ * ```
+ */
+declare function hasComponent(content: string, componentName: string): boolean;
+/**
+ * Extract code blocks and inline code 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 (fenced blocks with backticks, inline code with backticks)
+ *
+ * @example
+ * ```ts
+ * const blocks = extractCodeBlocks(content)
+ * for (const block of blocks) {
+ *   console.log(block)
+ * }
+ * ```
+ */
+declare function extractCodeBlocks(content: string): readonly string[];
+/**
+ * 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
+ */
+declare function parseJSXTags(content: string): readonly {
+    tag: string;
+    index: number;
+    isClosing: boolean;
+    isSelfClosing: boolean;
+}[];
+/**
+ * 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
+ */
+declare function findEmptyMarkdownLinks(content: string): readonly number[];
+
+/**
+ * @bfra.me/doc-sync/utils/sanitization - Sanitization utilities for MDX content
+ * Provides comprehensive XSS prevention for user-generated content
+ */
+/**
+ * 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;'
+ * ```
+ */
+declare function sanitizeForMDX(content: string): string;
+/**
+ * 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)'
+ * ```
+ */
+declare function sanitizeAttribute(value: string): string;
+/**
+ * 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'}]
+ * ```
+ */
+declare function parseJSXAttributes(tag: string): readonly JSXAttribute[];
+/**
+ * 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)
+ * ```
+ */
+declare function sanitizeJSXTag(tag: string): string;
+
+export { createHeadingPattern, extractCodeBlocks, findEmptyMarkdownLinks, hasComponent, parseJSXAttributes, parseJSXTags, sanitizeAttribute, sanitizeForMDX, sanitizeJSXTag };

package/lib/utils/index.js

@@ -0,0 +1,24 @@
+import "../chunk-DRBRT57F.js";
+import {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  hasComponent,
+  parseJSXAttributes,
+  parseJSXTags,
+  sanitizeAttribute,
+  sanitizeForMDX,
+  sanitizeJSXTag
+} from "../chunk-GZ2MP3VN.js";
+export {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  hasComponent,
+  parseJSXAttributes,
+  parseJSXTags,
+  sanitizeAttribute,
+  sanitizeForMDX,
+  sanitizeJSXTag
+};
+//# sourceMappingURL=index.js.map

package/lib/watcher/index.d.ts

@@ -0,0 +1,62 @@
+import { FileChangeEvent, PackageInfo } from '../types.js';
+import '@bfra.me/es/result';
+import 'zod';
+
+interface DocWatcherOptions {
+    readonly rootDir?: string;
+    readonly debounceMs?: number;
+    readonly additionalIgnore?: readonly string[];
+    readonly usePolling?: boolean;
+}
+type DocChangeHandler = (events: readonly FileChangeEvent[]) => void | Promise<void>;
+interface DocFileWatcher {
+    readonly start: () => Promise<void>;
+    readonly close: () => Promise<void>;
+    readonly onChanges: (handler: DocChangeHandler) => () => void;
+    readonly getWatchedPaths: () => readonly string[];
+}
+declare function createDocWatcher(options?: DocWatcherOptions): DocFileWatcher;
+type FileCategory = 'readme' | 'source' | 'package-json' | 'unknown';
+declare function categorizeFile(filePath: string): FileCategory;
+declare function groupChangesByPackage(events: readonly FileChangeEvent[]): Map<string, FileChangeEvent[]>;
+declare function filterDocumentationChanges(events: readonly FileChangeEvent[]): FileChangeEvent[];
+
+interface DocChangeDetectorOptions {
+    readonly algorithm?: 'sha256' | 'md5';
+}
+interface PackageChangeAnalysis {
+    readonly packageName: string;
+    readonly needsRegeneration: boolean;
+    readonly changedCategories: readonly FileCategory[];
+    readonly changedFiles: readonly string[];
+}
+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[]>;
+}
+declare function createDocChangeDetector(options?: DocChangeDetectorOptions): DocChangeDetector;
+type RegenerationScope = 'full' | 'api-only' | 'readme-only' | 'metadata-only' | 'none';
+declare function determineRegenerationScope(changedCategories: readonly FileCategory[]): RegenerationScope;
+declare function hasAnyFileChanged(detector: DocChangeDetector, files: readonly string[]): Promise<boolean>;
+
+interface DocDebouncerOptions {
+    readonly debounceMs?: number;
+    readonly maxWaitMs?: number;
+}
+type BatchChangeHandler = (events: readonly FileChangeEvent[]) => void | Promise<void>;
+interface DocDebouncer {
+    readonly add: (event: FileChangeEvent) => void;
+    readonly addAll: (events: readonly FileChangeEvent[]) => void;
+    readonly flush: () => void;
+    readonly cancel: () => void;
+    readonly getPendingCount: () => number;
+}
+declare function createDocDebouncer(handler: BatchChangeHandler, options?: DocDebouncerOptions): DocDebouncer;
+declare function deduplicateEvents(events: readonly FileChangeEvent[]): FileChangeEvent[];
+declare function consolidateEvents(events: readonly FileChangeEvent[]): FileChangeEvent[];
+
+export { type BatchChangeHandler, type DocChangeDetector, type DocChangeDetectorOptions, type DocChangeHandler, type DocDebouncer, type DocDebouncerOptions, type DocFileWatcher, type DocWatcherOptions, type FileCategory, type PackageChangeAnalysis, type RegenerationScope, categorizeFile, consolidateEvents, createDocChangeDetector, createDocDebouncer, createDocWatcher, deduplicateEvents, determineRegenerationScope, filterDocumentationChanges, groupChangesByPackage, hasAnyFileChanged };

package/lib/watcher/index.js

@@ -0,0 +1,25 @@
+import {
+  categorizeFile,
+  consolidateEvents,
+  createDocChangeDetector,
+  createDocDebouncer,
+  createDocWatcher,
+  deduplicateEvents,
+  determineRegenerationScope,
+  filterDocumentationChanges,
+  groupChangesByPackage,
+  hasAnyFileChanged
+} from "../chunk-45NROJIG.js";
+export {
+  categorizeFile,
+  consolidateEvents,
+  createDocChangeDetector,
+  createDocDebouncer,
+  createDocWatcher,
+  deduplicateEvents,
+  determineRegenerationScope,
+  filterDocumentationChanges,
+  groupChangesByPackage,
+  hasAnyFileChanged
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bfra.me/doc-sync",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Intelligent documentation synchronization engine for automatic Astro Starlight site updates",
   "keywords": [
     "astro",
@@ -35,6 +35,11 @@
       "source": "./src/generators/index.ts",
       "import": "./lib/generators/index.js"
     },
+    "./orchestrator": {
+      "types": "./lib/orchestrator/index.d.ts",
+      "source": "./src/orchestrator/index.ts",
+      "import": "./lib/orchestrator/index.js"
+    },
     "./parsers": {
       "types": "./lib/parsers/index.d.ts",
       "source": "./src/parsers/index.ts",
@@ -45,6 +50,16 @@
       "source": "./src/types.ts",
       "import": "./lib/types.js"
     },
+    "./utils": {
+      "types": "./lib/utils/index.d.ts",
+      "source": "./src/utils/index.ts",
+      "import": "./lib/utils/index.js"
+    },
+    "./watcher": {
+      "types": "./lib/watcher/index.d.ts",
+      "source": "./src/watcher/index.ts",
+      "import": "./lib/watcher/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./lib/index.js",
@@ -65,7 +80,7 @@
     "fast-glob": "3.3.3",
     "remark-mdx": "3.1.1",
     "remark-parse": "11.0.0",
-    "ts-morph": "26.0.0",
+    "ts-morph": "27.0.2",
     "unified": "11.0.5",
     "zod": "4.1.13",
     "@bfra.me/es": "0.1.0"

package/src/generators/component-mapper.ts

@@ -111,6 +111,16 @@ function isInstallationSection(heading: string, tabSections: readonly string[]):
   return tabSections.some(tab => heading.includes(tab.toLowerCase()))
 }
 
+/**
+ * Escape angle brackets in text to prevent MDX JSX tag misinterpretation
+ * This is applied to section content to prevent TypeScript generics like Result<T, E>
+ * from being interpreted as unclosed JSX tags
+ */
+function escapeAngleBrackets(text: string): string {
+  // Escape all < and > to HTML entities
+  return text.replaceAll('<', '&lt;').replaceAll('>', '&gt;')
+}
+
 function mapFeatureSection(section: ReadmeSection): string {
   const lines: string[] = []
 
@@ -124,7 +134,7 @@ function mapFeatureSection(section: ReadmeSection): string {
     for (const feature of features) {
       const icon = inferFeatureIcon(feature.title, feature.emoji)
       lines.push(`  <Card title="${sanitizeAttribute(feature.title)}" icon="${icon}">`)
-      lines.push(`    ${feature.description}`)
+      lines.push(`    ${escapeAngleBrackets(feature.description)}`)
       lines.push('  </Card>')
     }
     lines.push('</CardGrid>')

package/src/generators/mdx-generator.ts

@@ -169,15 +169,12 @@ function renderMDXDocument(frontmatter: MDXFrontmatter, content: string): string
  * Prevents XSS by escaping potentially dangerous content
  */
 export function sanitizeContent(content: string): string {
-  // Use comprehensive sanitization from utils
   return sanitizeForMDX(content)
 }
 
 /**
  * Sanitizes content within MDX while preserving JSX components
- * Only escapes content that appears to be user-provided text
- * Now includes sanitization of JSX component attributes to prevent XSS
- * Uses safe, non-backtracking parsing to prevent ReDoS
+ * Sanitizes JSX component attributes to prevent XSS while leaving closing tags unchanged
  */
 export function sanitizeTextContent(content: string): string {
   const jsxTags = parseJSXTags(content)
@@ -189,12 +186,7 @@ export function sanitizeTextContent(content: string): string {
       parts.push(sanitizeContent(content.slice(lastIndex, index)))
     }
 
-    if (isClosing) {
-      parts.push(tag)
-    } else {
-      parts.push(sanitizeJSXTag(tag))
-    }
-
+    parts.push(isClosing ? tag : sanitizeJSXTag(tag))
     lastIndex = index + tag.length
   }
 
@@ -225,23 +217,32 @@ export function validateMDXSyntax(mdx: string): Result<true, SyncError> {
   return ok(true)
 }
 
+/**
+ * Checks if a tag name is likely a TypeScript generic parameter rather than a JSX component
+ * Single uppercase letters (T, E, K, V, etc.) are common generic type parameters
+ */
+function isTypeScriptGeneric(tag: string): boolean {
+  const tagNameMatch = tag.match(/<\/?([A-Z][a-zA-Z0-9]*)/)
+  const tagName = tagNameMatch?.[1]
+  return tagName !== undefined && tagName.length === 1
+}
+
 function checkForUnclosedTags(mdx: string): string[] {
   const unclosed: string[] = []
   const tagStack: string[] = []
 
-  // Remove code blocks from content before checking for JSX tags
-  // This prevents TypeScript generics like Result<T, E> from being
-  // misinterpreted as unclosed JSX tags
+  // Remove code blocks and inline code to prevent TypeScript generics like Result<T, E>
+  // from being misinterpreted as JSX tags
   const codeBlocks = extractCodeBlocks(mdx)
-  let contentWithoutCodeBlocks = mdx
+  let contentWithoutCode = mdx
   for (const block of codeBlocks) {
-    // Replace code block with empty lines to preserve line numbers
     const lineCount = block.split('\n').length
     const placeholder = '\n'.repeat(lineCount)
-    contentWithoutCodeBlocks = contentWithoutCodeBlocks.replace(block, placeholder)
+    contentWithoutCode = contentWithoutCode.replace(block, placeholder)
   }
 
-  const jsxTags = parseJSXTags(contentWithoutCodeBlocks)
+  const allJSXTags = parseJSXTags(contentWithoutCode)
+  const jsxTags = allJSXTags.filter(({tag}) => !isTypeScriptGeneric(tag))
 
   for (const {tag, isClosing, isSelfClosing} of jsxTags) {
     const tagNameMatch = isClosing

package/src/index.ts

@@ -71,6 +71,75 @@ export type {
   ValidationWarning,
 } from './orchestrator'
 
+// Re-export parsers
+export {
+  analyzePublicAPI,
+  analyzeTypeScriptContent,
+  analyzeTypeScriptFile,
+  assertPackageAPI,
+  assertPackageInfo,
+  assertParseError,
+  buildDocSlug,
+  createProject,
+  extractDocsConfig,
+  extractExportedFunctions,
+  extractExportedTypes,
+  extractJSDocInfo,
+  extractPackageAPI,
+  extractReExports,
+  findEntryPoint,
+  findExportedSymbols,
+  findReadmePath,
+  findSection,
+  flattenSections,
+  getExportedSymbolInfo,
+  getExportsByKind,
+  getPackageScope,
+  getSectionsByLevel,
+  getTableOfContents,
+  getUnscopedName,
+  hasJSDoc,
+  isDocConfigSource,
+  isExportedFunction,
+  isExportedType,
+  isJSDocInfo,
+  isJSDocParam,
+  isJSDocTag,
+  isMDXFrontmatter,
+  isPackageAPI,
+  isPackageInfo,
+  isParseError,
+  isReadmeContent,
+  isReadmeSection,
+  isReExport,
+  isSafeContent,
+  isSafeFilePath,
+  isSymbolExported,
+  isSyncError,
+  isValidHeadingLevel,
+  isValidPackageName,
+  isValidSemver,
+  parseJSDoc,
+  parsePackageComplete,
+  parsePackageJson,
+  parsePackageJsonContent,
+  parseReadme,
+  parseReadmeFile,
+  parseSourceContent,
+  parseSourceFile,
+} from './parsers'
+
+export type {
+  ExportAnalyzerOptions,
+  JSDocableDeclaration,
+  PackageInfoOptions,
+  PackageJsonSchema,
+  PublicAPIAnalysis,
+  ReadmeParserOptions,
+  ResolvedExport,
+  TypeScriptParserOptions,
+} from './parsers'
+
 export type {
   CLIOptions,
   DocConfig,
@@ -102,6 +171,19 @@ export type {
 
 export {SENTINEL_MARKERS} from './types'
 
+// Re-export utils
+export {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  hasComponent,
+  parseJSXAttributes,
+  parseJSXTags,
+  sanitizeAttribute,
+  sanitizeForMDX,
+  sanitizeJSXTag,
+} from './utils'
+
 // Re-export watcher
 export {
   categorizeFile,

package/src/parsers/readme-parser.ts

@@ -183,12 +183,12 @@ function extractTextFromNode(node: RootContent): string {
 
 function serializeNode(node: RootContent): string {
   if (node.type === 'paragraph') {
-    return extractTextFromNode(node)
+    return serializeInlineContent(node)
   }
 
   if (node.type === 'heading') {
     const prefix = '#'.repeat(node.depth)
-    return `${prefix} ${extractTextFromNode(node)}`
+    return `${prefix} ${serializeInlineContent(node)}`
   }
 
   if (node.type === 'code') {
@@ -227,6 +227,59 @@ function serializeNode(node: RootContent): string {
   return extractTextFromNode(node)
 }
 
+/**
+ * Serialize inline content preserving markdown formatting like **bold**, *italic*, `code`, etc.
+ */
+function serializeInlineContent(node: RootContent): string {
+  if ('value' in node && typeof node.value === 'string') {
+    return node.value
+  }
+
+  if (!('children' in node) || !Array.isArray(node.children)) {
+    return ''
+  }
+
+  return (node.children as RootContent[])
+    .map(child => {
+      // Handle strong (bold) text
+      if (child.type === 'strong') {
+        return `**${serializeInlineContent(child)}**`
+      }
+
+      // Handle emphasis (italic) text
+      if (child.type === 'emphasis') {
+        return `*${serializeInlineContent(child)}*`
+      }
+
+      // Handle inline code
+      if (child.type === 'inlineCode') {
+        return `\`${'value' in child ? child.value : ''}\``
+      }
+
+      // Handle links
+      if (child.type === 'link') {
+        const text = serializeInlineContent(child)
+        return `[${text}](${'url' in child ? child.url : ''})`
+      }
+
+      // Handle images
+      if (child.type === 'image') {
+        const alt = 'alt' in child ? child.alt : ''
+        const url = 'url' in child ? child.url : ''
+        return `![${alt}](${url})`
+      }
+
+      // Handle plain text
+      if ('value' in child && typeof child.value === 'string') {
+        return child.value
+      }
+
+      // Recursively handle other inline elements
+      return serializeInlineContent(child)
+    })
+    .join('')
+}
+
 function serializeTable(node: RootContent): string {
   if (node.type !== 'table' || !('children' in node)) {
     return ''

package/src/utils/safe-patterns.ts

@@ -51,11 +51,11 @@ export function hasComponent(content: string, componentName: string): boolean {
 }
 
 /**
- * Extract code blocks from markdown content using unified/remark (safe, no regex)
+ * Extract code blocks and inline code 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
+ * @returns Array of code block strings (fenced blocks with backticks, inline code with backticks)
  *
  * @example
  * ```ts
@@ -91,6 +91,10 @@ export function extractCodeBlocks(content: string): readonly string[] {
       const value = node.value ?? ''
       blocks.push(`\`\`\`${lang}\n${value}\n\`\`\``)
     }
+    if (node.type === 'inlineCode') {
+      const value = node.value ?? ''
+      blocks.push(`\`${value}\``)
+    }
     if (Array.isArray(node.children)) {
       for (const child of node.children) {
         visit(child)