@bfra.me/doc-sync 0.1.0 → 0.1.1

package/lib/index.js

@@ -1,23 +1,14 @@
+import "./chunk-SQSYXPIF.js";
 import {
-  categorizeFile,
-  consolidateEvents,
-  createDocChangeDetector,
-  createDocDebouncer,
-  createDocWatcher,
   createPackageScanner,
   createSyncOrchestrator,
   createValidationPipeline,
-  deduplicateEvents,
-  determineRegenerationScope,
-  filterDocumentationChanges,
   filterPackagesByPattern,
-  groupChangesByPackage,
   groupPackagesByScope,
-  hasAnyFileChanged,
   isValidFilePath,
   validateContentString,
   validateDocument
-} from "./chunk-DR6UG237.js";
+} from "./chunk-NC7YTZAL.js";
 import {
   cleanCodeExample,
   createBadge,
@@ -54,13 +45,99 @@ import {
   validateMarkerPairing,
   wrapAutoSection,
   wrapManualSection
-} from "./chunk-G5KKGJYO.js";
+} from "./chunk-LOB73H77.js";
 import {
   SENTINEL_MARKERS
 } from "./chunk-ROLA7SBB.js";
-import "./chunk-6NKAJT2M.js";
+import {
+  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,
+  isReExport,
+  isReadmeContent,
+  isReadmeSection,
+  isSafeContent,
+  isSafeFilePath,
+  isSymbolExported,
+  isSyncError,
+  isValidHeadingLevel,
+  isValidPackageName,
+  isValidSemver,
+  parseJSDoc,
+  parsePackageComplete,
+  parsePackageJson,
+  parsePackageJsonContent,
+  parseReadme,
+  parseReadmeFile,
+  parseSourceContent,
+  parseSourceFile
+} from "./chunk-6NKAJT2M.js";
+import "./chunk-DRBRT57F.js";
+import {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  hasComponent,
+  parseJSXAttributes,
+  parseJSXTags,
+  sanitizeAttribute,
+  sanitizeForMDX,
+  sanitizeJSXTag
+} from "./chunk-GZ2MP3VN.js";
+import {
+  categorizeFile,
+  consolidateEvents,
+  createDocChangeDetector,
+  createDocDebouncer,
+  createDocWatcher,
+  deduplicateEvents,
+  determineRegenerationScope,
+  filterDocumentationChanges,
+  groupChangesByPackage,
+  hasAnyFileChanged
+} from "./chunk-45NROJIG.js";
 export {
   SENTINEL_MARKERS,
+  analyzePublicAPI,
+  analyzeTypeScriptContent,
+  analyzeTypeScriptFile,
+  assertPackageAPI,
+  assertPackageInfo,
+  assertParseError,
+  buildDocSlug,
   categorizeFile,
   cleanCodeExample,
   consolidateEvents,
@@ -71,7 +148,9 @@ export {
   createDocChangeDetector,
   createDocDebouncer,
   createDocWatcher,
+  createHeadingPattern,
   createPackageScanner,
+  createProject,
   createSyncOrchestrator,
   createTabs,
   createValidationPipeline,
@@ -79,9 +158,22 @@ export {
   detectLanguage,
   determineRegenerationScope,
   extractAutoSections,
+  extractCodeBlocks,
+  extractDocsConfig,
+  extractExportedFunctions,
+  extractExportedTypes,
+  extractJSDocInfo,
   extractManualSections,
+  extractPackageAPI,
+  extractReExports,
   filterDocumentationChanges,
   filterPackagesByPattern,
+  findEmptyMarkdownLinks,
+  findEntryPoint,
+  findExportedSymbols,
+  findReadmePath,
+  findSection,
+  flattenSections,
   formatCodeBlock,
   formatCodeExamples,
   formatFunctionExamples,
@@ -94,17 +186,58 @@ export {
   generateFrontmatter,
   generateInstallTabs,
   generateMDXDocument,
+  getExportedSymbolInfo,
+  getExportsByKind,
+  getPackageScope,
+  getSectionsByLevel,
+  getTableOfContents,
+  getUnscopedName,
   groupChangesByPackage,
   groupExamplesByCategory,
   groupPackagesByScope,
   hasAnyFileChanged,
   hasAutoContent,
+  hasComponent,
+  hasJSDoc,
   hasManualContent,
+  isDocConfigSource,
+  isExportedFunction,
+  isExportedType,
+  isJSDocInfo,
+  isJSDocParam,
+  isJSDocTag,
+  isMDXFrontmatter,
+  isPackageAPI,
+  isPackageInfo,
+  isParseError,
+  isReExport,
+  isReadmeContent,
+  isReadmeSection,
+  isSafeContent,
+  isSafeFilePath,
+  isSymbolExported,
+  isSyncError,
   isValidFilePath,
+  isValidHeadingLevel,
+  isValidPackageName,
+  isValidSemver,
   mapToStarlightComponents,
   mergeContent,
   parseFrontmatter,
+  parseJSDoc,
+  parseJSXAttributes,
+  parseJSXTags,
+  parsePackageComplete,
+  parsePackageJson,
+  parsePackageJsonContent,
+  parseReadme,
+  parseReadmeFile,
+  parseSourceContent,
+  parseSourceFile,
+  sanitizeAttribute,
   sanitizeContent,
+  sanitizeForMDX,
+  sanitizeJSXTag,
   sanitizeTextContent,
   stringifyFrontmatter,
   stripSentinelMarkers,

package/lib/orchestrator/index.d.ts

@@ -0,0 +1,82 @@
+import { Result } from '@bfra.me/es/result';
+import { PackageInfo, ReadmeContent, PackageAPI, SyncError, DocConfig, SyncSummary, FileChangeEvent, MDXDocument } from '../types.js';
+import 'zod';
+
+interface PackageScannerOptions {
+    readonly rootDir: string;
+    readonly includePatterns?: readonly string[];
+    readonly excludePackages?: readonly string[];
+    readonly parseSourceFiles?: boolean;
+    readonly parseReadme?: boolean;
+}
+interface ScannedPackage {
+    readonly info: PackageInfo;
+    readonly readme?: ReadmeContent;
+    readonly api?: PackageAPI;
+    readonly sourceFiles: readonly string[];
+    readonly needsDocumentation: boolean;
+    readonly existingDocPath?: string;
+}
+interface ScanResult {
+    readonly packages: readonly ScannedPackage[];
+    readonly packagesNeedingDocs: readonly ScannedPackage[];
+    readonly errors: readonly SyncError[];
+    readonly durationMs: number;
+}
+declare function createPackageScanner(options: PackageScannerOptions): {
+    readonly scan: () => Promise<ScanResult>;
+    readonly scanPackage: (packagePath: string) => Promise<Result<ScannedPackage, SyncError>>;
+};
+declare function filterPackagesByPattern(packages: readonly ScannedPackage[], pattern: string): ScannedPackage[];
+declare function groupPackagesByScope(packages: readonly ScannedPackage[]): Map<string, ScannedPackage[]>;
+
+interface SyncOrchestratorOptions {
+    readonly config: DocConfig;
+    readonly dryRun?: boolean;
+    readonly verbose?: boolean;
+    readonly onProgress?: (message: string) => void;
+    readonly onError?: (error: SyncError) => void;
+}
+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;
+}
+declare function createSyncOrchestrator(options: SyncOrchestratorOptions): SyncOrchestrator;
+/** Prevents directory traversal attacks (SEC-002) */
+declare function isValidFilePath(filePath: string, rootDir: string): boolean;
+
+interface ValidationResult {
+    readonly valid: boolean;
+    readonly errors: readonly ValidationError[];
+    readonly warnings: readonly ValidationWarning[];
+}
+interface ValidationError {
+    readonly type: 'syntax' | 'frontmatter' | 'component' | 'content';
+    readonly message: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+interface ValidationWarning {
+    readonly type: 'deprecation' | 'recommendation' | 'compatibility';
+    readonly message: string;
+    readonly line?: number;
+}
+interface ValidationPipelineOptions {
+    readonly validateFrontmatter?: boolean;
+    readonly validateComponents?: boolean;
+    readonly validateContent?: boolean;
+    readonly strict?: boolean;
+}
+declare function createValidationPipeline(options?: ValidationPipelineOptions): {
+    readonly validate: (doc: MDXDocument) => ValidationResult;
+    readonly validateContent: (content: string) => ValidationResult;
+    readonly validateMultiple: (docs: readonly MDXDocument[]) => Result<Map<string, ValidationResult>, SyncError>;
+};
+declare function validateDocument(doc: MDXDocument, options?: ValidationPipelineOptions): Result<MDXDocument, SyncError>;
+declare function validateContentString(content: string, options?: ValidationPipelineOptions): Result<string, SyncError>;
+
+export { type PackageScannerOptions, type ScanResult, type ScannedPackage, type SyncOrchestrator, type SyncOrchestratorOptions, type ValidationError, type ValidationPipelineOptions, type ValidationResult, type ValidationWarning, createPackageScanner, createSyncOrchestrator, createValidationPipeline, filterPackagesByPattern, groupPackagesByScope, isValidFilePath, validateContentString, validateDocument };

package/lib/orchestrator/index.js

@@ -0,0 +1,27 @@
+import "../chunk-SQSYXPIF.js";
+import {
+  createPackageScanner,
+  createSyncOrchestrator,
+  createValidationPipeline,
+  filterPackagesByPattern,
+  groupPackagesByScope,
+  isValidFilePath,
+  validateContentString,
+  validateDocument
+} from "../chunk-NC7YTZAL.js";
+import "../chunk-LOB73H77.js";
+import "../chunk-ROLA7SBB.js";
+import "../chunk-6NKAJT2M.js";
+import "../chunk-GZ2MP3VN.js";
+import "../chunk-45NROJIG.js";
+export {
+  createPackageScanner,
+  createSyncOrchestrator,
+  createValidationPipeline,
+  filterPackagesByPattern,
+  groupPackagesByScope,
+  isValidFilePath,
+  validateContentString,
+  validateDocument
+};
+//# sourceMappingURL=index.js.map

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.1",
   "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"