@bfra.me/doc-sync 0.1.0

package/lib/chunk-DR6UG237.js

@@ -0,0 +1,1027 @@
+import {
+  createHeadingPattern,
+  extractCodeBlocks,
+  findEmptyMarkdownLinks,
+  generateMDXDocument,
+  hasComponent,
+  mergeContent,
+  validateMDXSyntax
+} from "./chunk-G5KKGJYO.js";
+import {
+  analyzePublicAPI,
+  parsePackageComplete,
+  parseReadmeFile
+} from "./chunk-6NKAJT2M.js";
+
+// src/orchestrator/package-scanner.ts
+import fs from "fs/promises";
+import path from "path";
+import { err, ok } from "@bfra.me/es/result";
+var DEFAULT_OPTIONS = {
+  includePatterns: ["packages/*"],
+  parseSourceFiles: true,
+  parseReadme: true
+};
+function createPackageScanner(options) {
+  const {
+    rootDir,
+    includePatterns = DEFAULT_OPTIONS.includePatterns,
+    excludePackages = [],
+    parseSourceFiles = DEFAULT_OPTIONS.parseSourceFiles,
+    parseReadme = DEFAULT_OPTIONS.parseReadme
+  } = options;
+  const docsOutputDir = path.join(rootDir, "docs", "src", "content", "docs", "packages");
+  async function discoverPackages() {
+    const packagePaths = [];
+    for (const pattern of includePatterns) {
+      const baseDir = path.join(rootDir, pattern.replace("/*", ""));
+      try {
+        const entries = await fs.readdir(baseDir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) {
+            continue;
+          }
+          const packagePath = path.join(baseDir, entry.name);
+          const packageJsonPath = path.join(packagePath, "package.json");
+          try {
+            await fs.access(packageJsonPath);
+            packagePaths.push(packagePath);
+          } catch {
+          }
+        }
+      } catch {
+      }
+    }
+    return packagePaths;
+  }
+  async function findSourceFiles(srcDir) {
+    const sourceFiles = [];
+    try {
+      await collectSourceFiles(srcDir, sourceFiles);
+    } catch {
+    }
+    return sourceFiles;
+  }
+  async function collectSourceFiles(dir, files) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === "__tests__" || entry.name === "__mocks__") {
+          continue;
+        }
+        await collectSourceFiles(fullPath, files);
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if ((ext === ".ts" || ext === ".tsx") && !entry.name.includes(".test.") && !entry.name.includes(".spec.")) {
+          files.push(fullPath);
+        }
+      }
+    }
+  }
+  async function scanPackage(packagePath) {
+    const packageResult = await parsePackageComplete(packagePath);
+    if (!packageResult.success) {
+      return err({
+        code: "PACKAGE_NOT_FOUND",
+        message: `Failed to parse package at ${packagePath}: ${packageResult.error.message}`,
+        filePath: packagePath,
+        cause: packageResult.error
+      });
+    }
+    const info = packageResult.data;
+    const sourceFiles = await findSourceFiles(info.srcPath);
+    let readme;
+    if (parseReadme && info.readmePath !== void 0) {
+      const readmeResult = await parseReadmeFile(info.readmePath);
+      if (readmeResult.success) {
+        readme = readmeResult.data;
+      }
+    }
+    let api;
+    if (parseSourceFiles && sourceFiles.length > 0) {
+      const entryFile = findEntryFile(sourceFiles, info.srcPath);
+      if (entryFile !== void 0) {
+        const analysisResult = analyzePublicAPI(entryFile);
+        if (analysisResult.success) {
+          api = analysisResult.data.api;
+        }
+      }
+    }
+    const docSlug = buildDocSlug(info.name);
+    const existingDocPath = path.join(docsOutputDir, `${docSlug}.mdx`);
+    let hasExistingDoc = false;
+    try {
+      await fs.access(existingDocPath);
+      hasExistingDoc = true;
+    } catch {
+    }
+    return ok({
+      info,
+      readme,
+      api,
+      sourceFiles,
+      needsDocumentation: true,
+      existingDocPath: hasExistingDoc ? existingDocPath : void 0
+    });
+  }
+  return {
+    async scan() {
+      const startTime = Date.now();
+      const packagePaths = await discoverPackages();
+      const packages = [];
+      const errors = [];
+      for (const packagePath of packagePaths) {
+        const result = await scanPackage(packagePath);
+        if (result.success) {
+          const scanned = result.data;
+          if (excludePackages.includes(scanned.info.name)) {
+            continue;
+          }
+          packages.push(scanned);
+        } else {
+          errors.push(result.error);
+        }
+      }
+      const packagesNeedingDocs = packages.filter((pkg) => pkg.needsDocumentation);
+      return {
+        packages,
+        packagesNeedingDocs,
+        errors,
+        durationMs: Date.now() - startTime
+      };
+    },
+    scanPackage
+  };
+}
+function findEntryFile(sourceFiles, srcDir) {
+  const indexPath = path.join(srcDir, "index.ts");
+  return sourceFiles.find((file) => file === indexPath) ?? sourceFiles[0];
+}
+function buildDocSlug(packageName) {
+  return getUnscopedName(packageName).toLowerCase().replaceAll(/[^a-z0-9-]/g, "-");
+}
+function getUnscopedName(packageName) {
+  if (packageName.startsWith("@")) {
+    const slashIndex = packageName.indexOf("/");
+    if (slashIndex > 0) {
+      return packageName.slice(slashIndex + 1);
+    }
+  }
+  return packageName;
+}
+function filterPackagesByPattern(packages, pattern) {
+  const regex = new RegExp(pattern.replaceAll("*", ".*"), "i");
+  return packages.filter((pkg) => regex.test(pkg.info.name));
+}
+function groupPackagesByScope(packages) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const pkg of packages) {
+    const scope = getPackageScope(pkg.info.name) ?? "__unscoped__";
+    const existing = grouped.get(scope);
+    if (existing === void 0) {
+      grouped.set(scope, [pkg]);
+    } else {
+      existing.push(pkg);
+    }
+  }
+  return grouped;
+}
+function getPackageScope(packageName) {
+  if (packageName.startsWith("@")) {
+    const slashIndex = packageName.indexOf("/");
+    if (slashIndex > 0) {
+      return packageName.slice(0, slashIndex);
+    }
+  }
+  return void 0;
+}
+
+// src/watcher/file-watcher.ts
+import path2 from "path";
+import process from "process";
+import { createFileWatcher as createBaseWatcher } from "@bfra.me/es/watcher";
+var DEFAULT_WATCH_PATTERNS = [
+  "packages/*/README.md",
+  "packages/*/readme.md",
+  "packages/*/package.json",
+  "packages/*/src/**/*.ts",
+  "packages/*/src/**/*.tsx"
+];
+var DEFAULT_IGNORE_PATTERNS = [
+  "**/node_modules/**",
+  "**/lib/**",
+  "**/dist/**",
+  "**/.git/**",
+  "**/coverage/**",
+  "**/*.test.ts",
+  "**/*.spec.ts",
+  "**/__tests__/**",
+  "**/__mocks__/**"
+];
+function extractPackageName(filePath, root) {
+  const relativePath = path2.relative(root, filePath);
+  const parts = relativePath.split(path2.sep);
+  if (parts[0] === "packages" && parts.length > 1) {
+    return parts[1];
+  }
+  return void 0;
+}
+function createDocWatcher(options = {}) {
+  const {
+    rootDir = process.cwd(),
+    debounceMs = 300,
+    additionalIgnore = [],
+    usePolling = false
+  } = options;
+  const watchPaths = DEFAULT_WATCH_PATTERNS.map((pattern) => path2.join(rootDir, pattern));
+  const ignoredPatterns = [...DEFAULT_IGNORE_PATTERNS, ...additionalIgnore];
+  const watcherOptions = {
+    debounceMs,
+    ignored: ignoredPatterns,
+    usePolling
+  };
+  const baseWatcher = createBaseWatcher(watchPaths, watcherOptions);
+  const handlers = /* @__PURE__ */ new Set();
+  function transformToDocEvents(changes) {
+    return changes.map((change) => ({
+      type: change.type,
+      path: change.path,
+      packageName: extractPackageName(change.path, rootDir),
+      timestamp: new Date(change.timestamp)
+    }));
+  }
+  return {
+    async start() {
+      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() {
+      await baseWatcher.close();
+      handlers.clear();
+    },
+    onChanges(handler) {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    },
+    getWatchedPaths() {
+      return watchPaths;
+    }
+  };
+}
+function categorizeFile(filePath) {
+  const basename = path2.basename(filePath).toLowerCase();
+  if (basename === "readme.md" || basename === "readme") {
+    return "readme";
+  }
+  if (basename === "package.json") {
+    return "package-json";
+  }
+  const ext = path2.extname(filePath).toLowerCase();
+  if (ext === ".ts" || ext === ".tsx") {
+    return "source";
+  }
+  return "unknown";
+}
+function groupChangesByPackage(events) {
+  const grouped = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const pkg = event.packageName ?? "__unknown__";
+    const existing = grouped.get(pkg);
+    if (existing === void 0) {
+      grouped.set(pkg, [event]);
+    } else {
+      existing.push(event);
+    }
+  }
+  return grouped;
+}
+function filterDocumentationChanges(events) {
+  return events.filter((event) => {
+    const category = categorizeFile(event.path);
+    return category !== "unknown";
+  });
+}
+
+// src/watcher/change-detector.ts
+import { createChangeDetector as createBaseDetector } from "@bfra.me/es/watcher";
+function createDocChangeDetector(options = {}) {
+  const baseDetector = createBaseDetector({ algorithm: options.algorithm });
+  const packageFiles = /* @__PURE__ */ new Map();
+  return {
+    async hasChanged(filePath) {
+      return baseDetector.hasChanged(filePath);
+    },
+    async record(filePath) {
+      await baseDetector.record(filePath);
+    },
+    async recordPackage(pkg, files) {
+      const fileSet = new Set(files);
+      packageFiles.set(pkg.name, fileSet);
+      await Promise.all(files.map(async (file) => baseDetector.record(file)));
+    },
+    clear(filePath) {
+      baseDetector.clear(filePath);
+      for (const fileSet of packageFiles.values()) {
+        fileSet.delete(filePath);
+      }
+    },
+    clearAll() {
+      baseDetector.clearAll();
+      packageFiles.clear();
+    },
+    async analyzeChanges(events) {
+      const packageChanges = /* @__PURE__ */ new Map();
+      for (const event of events) {
+        const packageName = event.packageName ?? "__unknown__";
+        const category = categorizeFile(event.path);
+        let analysis = packageChanges.get(packageName);
+        if (analysis === void 0) {
+          analysis = { categories: /* @__PURE__ */ new Set(), files: [] };
+          packageChanges.set(packageName, analysis);
+        }
+        if (category !== "unknown") {
+          analysis.categories.add(category);
+        }
+        analysis.files.push(event.path);
+      }
+      const results = [];
+      for (const [packageName, analysis] of packageChanges) {
+        const changedCategories = [...analysis.categories];
+        const needsRegeneration = changedCategories.includes("readme") || changedCategories.includes("package-json") || changedCategories.includes("source");
+        results.push({
+          packageName,
+          needsRegeneration,
+          changedCategories,
+          changedFiles: analysis.files
+        });
+      }
+      return results;
+    }
+  };
+}
+function determineRegenerationScope(changedCategories) {
+  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";
+}
+async function hasAnyFileChanged(detector, files) {
+  const results = await Promise.all(files.map(async (file) => detector.hasChanged(file)));
+  return results.some((changed) => changed);
+}
+
+// src/watcher/debouncer.ts
+import { createDebouncer as createBaseDebouncer } from "@bfra.me/es/watcher";
+function createDocDebouncer(handler, options = {}) {
+  const { debounceMs = 300, maxWaitMs = 5e3 } = options;
+  let pendingEvents = [];
+  let maxWaitTimeout;
+  function processEvents(events) {
+    if (maxWaitTimeout !== void 0) {
+      clearTimeout(maxWaitTimeout);
+      maxWaitTimeout = void 0;
+    }
+    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 = createBaseDebouncer((events) => {
+    processEvents(events);
+    pendingEvents = [];
+  }, debounceMs);
+  function startMaxWaitTimer() {
+    if (maxWaitTimeout === void 0) {
+      maxWaitTimeout = setTimeout(() => {
+        baseDebouncer.flush();
+      }, maxWaitMs);
+    }
+  }
+  return {
+    add(event) {
+      pendingEvents.push(event);
+      startMaxWaitTimer();
+      baseDebouncer.add(event);
+    },
+    addAll(events) {
+      for (const event of events) {
+        pendingEvents.push(event);
+        baseDebouncer.add(event);
+      }
+      if (events.length > 0) {
+        startMaxWaitTimer();
+      }
+    },
+    flush() {
+      if (maxWaitTimeout !== void 0) {
+        clearTimeout(maxWaitTimeout);
+        maxWaitTimeout = void 0;
+      }
+      baseDebouncer.flush();
+    },
+    cancel() {
+      if (maxWaitTimeout !== void 0) {
+        clearTimeout(maxWaitTimeout);
+        maxWaitTimeout = void 0;
+      }
+      pendingEvents = [];
+      baseDebouncer.cancel();
+    },
+    getPendingCount() {
+      return pendingEvents.length;
+    }
+  };
+}
+function deduplicateEvents(events) {
+  const latestByPath = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const existing = latestByPath.get(event.path);
+    if (existing === void 0 || event.timestamp > existing.timestamp) {
+      latestByPath.set(event.path, event);
+    }
+  }
+  return [...latestByPath.values()];
+}
+function consolidateEvents(events) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    const existing = byPath.get(event.path);
+    if (existing === void 0) {
+      byPath.set(event.path, [event]);
+    } else {
+      existing.push(event);
+    }
+  }
+  const consolidated = [];
+  for (const [, pathEvents] of byPath) {
+    const firstEvent = pathEvents[0];
+    if (firstEvent === void 0) {
+      continue;
+    }
+    if (pathEvents.length === 1) {
+      consolidated.push(firstEvent);
+      continue;
+    }
+    pathEvents.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    const first = pathEvents[0];
+    const last = pathEvents.at(-1);
+    if (first === void 0 || last === void 0) {
+      continue;
+    }
+    if (first.type === "add" && last.type === "unlink") {
+      continue;
+    }
+    if (first.type === "unlink" && last.type === "add") {
+      consolidated.push({
+        type: "change",
+        path: last.path,
+        packageName: last.packageName,
+        timestamp: last.timestamp
+      });
+      continue;
+    }
+    consolidated.push(last);
+  }
+  return consolidated;
+}
+
+// src/orchestrator/validation-pipeline.ts
+import { err as err2, ok as ok2 } from "@bfra.me/es/result";
+var DEFAULT_OPTIONS2 = {
+  validateFrontmatter: true,
+  validateComponents: true,
+  validateContent: true,
+  strict: false
+};
+function createValidationPipeline(options = {}) {
+  const mergedOptions = { ...DEFAULT_OPTIONS2, ...options };
+  function validate(doc) {
+    const errors = [];
+    const warnings = [];
+    if (mergedOptions.validateFrontmatter) {
+      const frontmatterResult = validateFrontmatter(doc.frontmatter);
+      errors.push(...frontmatterResult.errors);
+      warnings.push(...frontmatterResult.warnings);
+    }
+    const syntaxResult = validateSyntax(doc.rendered);
+    errors.push(...syntaxResult.errors);
+    warnings.push(...syntaxResult.warnings);
+    if (mergedOptions.validateComponents) {
+      const componentResult = validateStarlightComponents(doc.rendered);
+      errors.push(...componentResult.errors);
+      warnings.push(...componentResult.warnings);
+    }
+    if (mergedOptions.validateContent) {
+      const contentResult = validateContentQuality(doc.rendered);
+      errors.push(...contentResult.errors);
+      warnings.push(...contentResult.warnings);
+    }
+    const valid = mergedOptions.strict ? errors.length === 0 && warnings.length === 0 : errors.length === 0;
+    return { valid, errors, warnings };
+  }
+  function validateContent(content) {
+    const errors = [];
+    const warnings = [];
+    const syntaxResult = validateSyntax(content);
+    errors.push(...syntaxResult.errors);
+    warnings.push(...syntaxResult.warnings);
+    if (mergedOptions.validateComponents) {
+      const componentResult = validateStarlightComponents(content);
+      errors.push(...componentResult.errors);
+      warnings.push(...componentResult.warnings);
+    }
+    const valid = mergedOptions.strict ? errors.length === 0 && warnings.length === 0 : errors.length === 0;
+    return { valid, errors, warnings };
+  }
+  function validateMultiple(docs) {
+    const results = /* @__PURE__ */ new Map();
+    const seen = /* @__PURE__ */ new Set();
+    for (const doc of docs) {
+      const key = doc.frontmatter.title;
+      if (seen.has(key)) {
+        return err2({
+          code: "VALIDATION_ERROR",
+          message: `Duplicate document title detected: "${key}". Each document must have a unique title.`
+        });
+      }
+      seen.add(key);
+      results.set(key, validate(doc));
+    }
+    return ok2(results);
+  }
+  return { validate, validateContent, validateMultiple };
+}
+function validateFrontmatter(frontmatter) {
+  const errors = [];
+  const warnings = [];
+  if (frontmatter.title.trim().length === 0) {
+    errors.push({
+      type: "frontmatter",
+      message: "Frontmatter title is required and cannot be empty"
+    });
+  }
+  if (frontmatter.title.length > 100) {
+    warnings.push({
+      type: "recommendation",
+      message: `Title is ${frontmatter.title.length} characters, consider keeping under 100 for better readability`
+    });
+  }
+  if (frontmatter.description !== void 0 && frontmatter.description.length > 200) {
+    warnings.push({
+      type: "recommendation",
+      message: "Description is quite long, consider keeping under 200 characters for SEO"
+    });
+  }
+  return { errors, warnings };
+}
+function validateSyntax(content) {
+  const errors = [];
+  const warnings = [];
+  const result = validateMDXSyntax(content);
+  if (!result.success) {
+    errors.push({
+      type: "syntax",
+      message: result.error.message
+    });
+  }
+  return { errors, warnings };
+}
+var STARLIGHT_COMPONENTS = ["Badge", "Card", "CardGrid", "Tabs", "TabItem"];
+function validateStarlightComponents(content) {
+  const errors = [];
+  const warnings = [];
+  for (const component of STARLIGHT_COMPONENTS) {
+    const openPattern = new RegExp(String.raw`<${component}(?:\s[^>]*)?>`, "g");
+    const closePattern = new RegExp(`</${component}>`, "g");
+    const selfClosePattern = new RegExp(String.raw`<${component}(?:\s[^>]*)?/>`, "g");
+    const opens = content.match(openPattern)?.length ?? 0;
+    const closes = content.match(closePattern)?.length ?? 0;
+    const selfCloses = content.match(selfClosePattern)?.length ?? 0;
+    const nonSelfClosingOpens = opens - selfCloses;
+    if (nonSelfClosingOpens > closes) {
+      errors.push({
+        type: "component",
+        message: `Unclosed <${component}> tag detected (${nonSelfClosingOpens} opens, ${closes} closes)`
+      });
+    }
+  }
+  const hasTabItem = content.includes("<TabItem");
+  const hasTabs = content.includes("<Tabs");
+  if (hasTabItem && !hasTabs) {
+    errors.push({
+      type: "component",
+      message: "<TabItem> must be used inside <Tabs>"
+    });
+  }
+  const hasCard = hasComponent(content, "Card");
+  const hasCardGrid = hasComponent(content, "CardGrid");
+  if (hasCard && !hasCardGrid) {
+    warnings.push({
+      type: "recommendation",
+      message: "Consider wrapping <Card> components in <CardGrid> for better layout"
+    });
+  }
+  return { errors, warnings };
+}
+function validateContentQuality(content) {
+  const errors = [];
+  const warnings = [];
+  const emptyLinkPositions = findEmptyMarkdownLinks(content);
+  if (emptyLinkPositions.length > 0) {
+    errors.push({
+      type: "content",
+      message: `Found ${emptyLinkPositions.length} empty link(s)`
+    });
+  }
+  const codeBlockMarkers = content.match(/```/g)?.length ?? 0;
+  if (codeBlockMarkers % 2 !== 0) {
+    errors.push({
+      type: "content",
+      message: "Unclosed code block detected (odd number of ``` markers)"
+    });
+  }
+  const h2Pattern = createHeadingPattern(2);
+  const h2Headings = [];
+  const h2Matches = content.matchAll(h2Pattern);
+  for (const match of h2Matches) {
+    const heading = match[1];
+    if (heading === void 0) {
+      continue;
+    }
+    if (h2Headings.includes(heading)) {
+      warnings.push({
+        type: "recommendation",
+        message: `Duplicate H2 heading: "${heading}"`
+      });
+    }
+    h2Headings.push(heading);
+  }
+  const codeBlocks = extractCodeBlocks(content);
+  for (const block of codeBlocks) {
+    const lines = block.split("\n");
+    for (const line of lines) {
+      if (line.length > 120 && !line.startsWith("```")) {
+        warnings.push({
+          type: "recommendation",
+          message: `Code line exceeds 120 characters, may require horizontal scrolling`
+        });
+        break;
+      }
+    }
+  }
+  return { errors, warnings };
+}
+function validateDocument(doc, options) {
+  const pipeline = createValidationPipeline(options);
+  const result = pipeline.validate(doc);
+  if (!result.valid) {
+    const errorMessages = result.errors.map((e) => e.message).join("; ");
+    return err2({
+      code: "VALIDATION_ERROR",
+      message: `MDX validation failed: ${errorMessages}`
+    });
+  }
+  return ok2(doc);
+}
+function validateContentString(content, options) {
+  const pipeline = createValidationPipeline(options);
+  const result = pipeline.validateContent(content);
+  if (!result.valid) {
+    const errorMessages = result.errors.map((e) => e.message).join("; ");
+    return err2({
+      code: "VALIDATION_ERROR",
+      message: `MDX validation failed: ${errorMessages}`
+    });
+  }
+  return ok2(content);
+}
+
+// src/orchestrator/sync-orchestrator.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+import { err as err3, ok as ok3 } from "@bfra.me/es/result";
+function createSyncOrchestrator(options) {
+  const { config, dryRun = false, verbose = false, onProgress, onError } = options;
+  const scanner = createPackageScanner({
+    rootDir: config.rootDir,
+    includePatterns: config.includePatterns,
+    excludePackages: config.excludePatterns
+  });
+  const validationPipeline = createValidationPipeline();
+  let watcher;
+  let debouncer;
+  let watching = false;
+  function log(message) {
+    if (verbose && onProgress != null) {
+      onProgress(message);
+    }
+  }
+  function reportError(error) {
+    if (onError != null) {
+      onError(error);
+    }
+  }
+  async function syncPackage(pkg) {
+    log(`Syncing documentation for ${pkg.info.name}...`);
+    const docResult = generateMDXDocument(pkg.info, pkg.readme, pkg.api);
+    if (!docResult.success) {
+      return docResult;
+    }
+    const doc = docResult.data;
+    const validationResult = validationPipeline.validate(doc);
+    if (!validationResult.valid) {
+      const errorMessages = validationResult.errors.map((e) => e.message).join("; ");
+      return err3({
+        code: "VALIDATION_ERROR",
+        message: `Validation failed for ${pkg.info.name}: ${errorMessages}`,
+        packageName: pkg.info.name
+      });
+    }
+    const outputPath = getOutputPath(pkg.info.name, config.outputDir);
+    let action = "created";
+    let contentToWrite = doc.rendered;
+    try {
+      if (pkg.existingDocPath == null) {
+        if (!dryRun) {
+          await writeFile(outputPath, contentToWrite);
+        }
+      } else {
+        try {
+          const existingContent = await fs2.readFile(pkg.existingDocPath, "utf-8");
+          const mergedResult = mergeContent(existingContent, doc.rendered);
+          if (!mergedResult.success) {
+            if (!dryRun) {
+              await writeFile(outputPath, contentToWrite);
+            }
+            action = "updated";
+          } else if (mergedResult.data.content === existingContent) {
+            return ok3({
+              packageName: pkg.info.name,
+              outputPath,
+              action: "unchanged",
+              timestamp: /* @__PURE__ */ new Date()
+            });
+          } else {
+            contentToWrite = mergedResult.data.content;
+            action = "updated";
+            if (!dryRun) {
+              await writeFile(outputPath, contentToWrite);
+            }
+          }
+        } catch {
+          if (!dryRun) {
+            await writeFile(outputPath, contentToWrite);
+          }
+        }
+      }
+    } catch (error) {
+      return err3(createWriteError(error, outputPath, pkg.info.name));
+    }
+    log(`${dryRun ? "[DRY RUN] Would write" : "Wrote"} ${outputPath}`);
+    return ok3({
+      packageName: pkg.info.name,
+      outputPath,
+      action,
+      timestamp: /* @__PURE__ */ new Date()
+    });
+  }
+  async function syncAll() {
+    const startTime = Date.now();
+    log("Starting full documentation sync...");
+    const scanResult = await scanner.scan();
+    const details = [];
+    const errors = [...scanResult.errors];
+    for (const pkg of scanResult.packagesNeedingDocs) {
+      const result = await syncPackage(pkg);
+      if (result.success) {
+        details.push(result.data);
+      } else {
+        errors.push(result.error);
+        reportError(result.error);
+      }
+    }
+    const successCount = details.filter((d) => d.action !== "unchanged").length;
+    const unchangedCount = details.filter((d) => d.action === "unchanged").length;
+    log(
+      `Sync complete: ${successCount} updated, ${unchangedCount} unchanged, ${errors.length} errors`
+    );
+    return {
+      totalPackages: scanResult.packages.length,
+      successCount,
+      failureCount: errors.length,
+      unchangedCount,
+      details,
+      errors,
+      durationMs: Date.now() - startTime
+    };
+  }
+  async function syncPackages(packageNames) {
+    const startTime = Date.now();
+    log(`Syncing specific packages: ${packageNames.join(", ")}...`);
+    const scanResult = await scanner.scan();
+    const packagesToSync = scanResult.packages.filter((pkg) => packageNames.includes(pkg.info.name));
+    const details = [];
+    const errors = [];
+    for (const pkg of packagesToSync) {
+      const result = await syncPackage(pkg);
+      if (result.success) {
+        details.push(result.data);
+      } else {
+        errors.push(result.error);
+        reportError(result.error);
+      }
+    }
+    const successCount = details.filter((d) => d.action !== "unchanged").length;
+    const unchangedCount = details.filter((d) => d.action === "unchanged").length;
+    return {
+      totalPackages: packagesToSync.length,
+      successCount,
+      failureCount: errors.length,
+      unchangedCount,
+      details,
+      errors,
+      durationMs: Date.now() - startTime
+    };
+  }
+  async function handleChanges(events) {
+    const startTime = Date.now();
+    const groupedChanges = groupChangesByPackage(events);
+    const packageNames = [];
+    for (const [packageName, packageEvents] of groupedChanges) {
+      if (packageName === "__unknown__") {
+        continue;
+      }
+      const categories = packageEvents.map((e) => categorizeFileChange(e.path));
+      const scope = determineRegenerationScope(categories);
+      if (scope !== "none") {
+        packageNames.push(packageName);
+        log(`Package ${packageName} needs ${scope} regeneration`);
+      }
+    }
+    if (packageNames.length === 0) {
+      return {
+        totalPackages: 0,
+        successCount: 0,
+        failureCount: 0,
+        unchangedCount: 0,
+        details: [],
+        errors: [],
+        durationMs: Date.now() - startTime
+      };
+    }
+    return syncPackages(packageNames);
+  }
+  async function startWatching() {
+    if (watching) {
+      return;
+    }
+    log("Starting watch mode...");
+    watcher = createDocWatcher({
+      rootDir: config.rootDir,
+      debounceMs: config.debounceMs ?? 300
+    });
+    debouncer = createDocDebouncer(
+      async (events) => {
+        const result = await handleChanges(events);
+        log(`Watch mode sync: ${result.successCount} updated, ${result.failureCount} errors`);
+      },
+      { debounceMs: config.debounceMs ?? 300 }
+    );
+    watcher.onChanges((events) => {
+      for (const event of events) {
+        debouncer?.add(event);
+      }
+    });
+    await watcher.start();
+    watching = true;
+    log("Watch mode started");
+  }
+  async function stopWatching() {
+    if (!watching) {
+      return;
+    }
+    log("Stopping watch mode...");
+    debouncer?.cancel();
+    await watcher?.close();
+    watcher = void 0;
+    debouncer = void 0;
+    watching = false;
+    log("Watch mode stopped");
+  }
+  return {
+    syncAll,
+    syncPackages,
+    handleChanges,
+    startWatching,
+    stopWatching,
+    isWatching: () => watching
+  };
+}
+function getOutputPath(packageName, outputDir) {
+  const slug = createSlug(getUnscopedName2(packageName));
+  return path3.join(outputDir, `${slug}.mdx`);
+}
+function createSlug(name) {
+  return name.toLowerCase().replaceAll(/[^a-z0-9-]/g, "-");
+}
+function getUnscopedName2(packageName) {
+  if (packageName.startsWith("@")) {
+    const slashIndex = packageName.indexOf("/");
+    if (slashIndex > 0) {
+      return packageName.slice(slashIndex + 1);
+    }
+  }
+  return packageName;
+}
+async function writeFile(filePath, content) {
+  const dir = path3.dirname(filePath);
+  await fs2.mkdir(dir, { recursive: true });
+  await fs2.writeFile(filePath, content, "utf-8");
+}
+function createWriteError(error, filePath, packageName) {
+  const message = formatWriteErrorMessage(error, filePath);
+  return {
+    code: "WRITE_ERROR",
+    message,
+    packageName,
+    filePath,
+    cause: error
+  };
+}
+function formatWriteErrorMessage(error, filePath) {
+  const errorCode = isNodeError(error) ? error.code : void 0;
+  switch (errorCode) {
+    case "EACCES":
+      return `Permission denied writing to ${filePath}`;
+    case "ENOENT":
+      return `Directory not found for ${filePath}`;
+    case "EISDIR":
+      return `Cannot write to directory ${filePath}`;
+    case void 0:
+    default: {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      return `Failed to write ${filePath}: ${errorMessage}`;
+    }
+  }
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+function categorizeFileChange(filePath) {
+  const basename = path3.basename(filePath).toLowerCase();
+  if (basename === "readme.md" || basename === "readme") return "readme";
+  if (basename === "package.json") return "package-json";
+  if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) return "source";
+  return "unknown";
+}
+function isValidFilePath(filePath, rootDir) {
+  const resolvedPath = path3.resolve(filePath);
+  const resolvedRoot = path3.resolve(rootDir);
+  return resolvedPath.startsWith(resolvedRoot);
+}
+
+export {
+  createPackageScanner,
+  filterPackagesByPattern,
+  groupPackagesByScope,
+  createDocWatcher,
+  categorizeFile,
+  groupChangesByPackage,
+  filterDocumentationChanges,
+  createDocChangeDetector,
+  determineRegenerationScope,
+  hasAnyFileChanged,
+  createDocDebouncer,
+  deduplicateEvents,
+  consolidateEvents,
+  createValidationPipeline,
+  validateDocument,
+  validateContentString,
+  createSyncOrchestrator,
+  isValidFilePath
+};
+//# sourceMappingURL=chunk-DR6UG237.js.map