@nocobase/server 2.0.0-beta.9 → 2.0.0

package/lib/ai/create-docs-index.js

@@ -0,0 +1,892 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var create_docs_index_exports = {};
+__export(create_docs_index_exports, {
+  createDocsIndex: () => createDocsIndex
+});
+module.exports = __toCommonJS(create_docs_index_exports);
+var import_fast_glob = __toESM(require("fast-glob"));
+var import_fs_extra = __toESM(require("fs-extra"));
+var import_path = __toESM(require("path"));
+var import_ai = require("@nocobase/ai");
+var import_findPackageNames = require("../plugin-manager/findPackageNames");
+var import_plugin_manager = require("../plugin-manager");
+const DOCS_STORAGE_DIR = import_path.default.resolve(process.cwd(), "storage/ai/docs");
+const REFERENCE_START = "<!-- docs:references:start -->";
+const REFERENCE_END = "<!-- docs:references:end -->";
+const SPLIT_REFERENCE_START = "<!-- docs:splits:start -->";
+const SPLIT_REFERENCE_END = "<!-- docs:splits:end -->";
+const SPLIT_MAX_LENGTH = 5e3;
+const SPLIT_MAX_CODE_BLOCKS = 3;
+const CREATE_INDEX_RETRY_MAX = 3;
+const CREATE_INDEX_RETRY_DELAY_MS = 200;
+function normalizeMetaEntries(meta, fallbackModule) {
+  if (Array.isArray(meta)) {
+    return meta.filter((item) => item && typeof item.module === "string").map((item) => ({
+      module: item.module.trim(),
+      description: typeof item.description === "string" ? item.description.trim() : "",
+      source: typeof item.source === "string" ? item.source.trim() : ""
+    })).filter((item) => item.module);
+  }
+  if (meta && typeof meta.module === "string") {
+    return [
+      {
+        module: meta.module.trim() || fallbackModule,
+        description: typeof meta.description === "string" ? meta.description.trim() : "",
+        source: typeof meta.source === "string" ? meta.source.trim() : ""
+      }
+    ];
+  }
+  return [
+    {
+      module: fallbackModule,
+      description: "",
+      source: ""
+    }
+  ];
+}
+__name(normalizeMetaEntries, "normalizeMetaEntries");
+async function resolvePkgs(pkg) {
+  if (!pkg) {
+    return await (0, import_findPackageNames.findAllPlugins)();
+  }
+  const scopes = (Array.isArray(pkg) ? pkg : pkg.split(",")).map((item) => item.trim()).filter(Boolean);
+  return Array.from(new Set(scopes));
+}
+__name(resolvePkgs, "resolvePkgs");
+function buildDirectoryChildren(files, docsDir) {
+  const map = /* @__PURE__ */ new Map();
+  const ensureDir = /* @__PURE__ */ __name((dir) => {
+    if (!map.has(dir)) {
+      map.set(dir, { files: [], directories: [] });
+    }
+  }, "ensureDir");
+  ensureDir(docsDir);
+  files.forEach((file) => {
+    var _a;
+    const dir = import_path.default.dirname(file);
+    ensureDir(dir);
+    (_a = map.get(dir)) == null ? void 0 : _a.files.push(file);
+  });
+  files.forEach((file) => {
+    let current = import_path.default.dirname(file);
+    while (current && current.startsWith(docsDir)) {
+      const parent = import_path.default.dirname(current);
+      if (parent && parent.startsWith(docsDir)) {
+        ensureDir(parent);
+        const list = map.get(parent);
+        if (list && !list.directories.includes(current)) {
+          list.directories.push(current);
+        }
+      }
+      if (current === docsDir) break;
+      current = import_path.default.dirname(current);
+    }
+  });
+  return map;
+}
+__name(buildDirectoryChildren, "buildDirectoryChildren");
+async function resolveSourcePath(source, metaFile) {
+  if (!source) return "";
+  if (import_path.default.isAbsolute(source)) {
+    return await import_fs_extra.default.pathExists(source) ? source : "";
+  }
+  const fromRepo = import_path.default.resolve(process.cwd(), source);
+  if (await import_fs_extra.default.pathExists(fromRepo)) {
+    return fromRepo;
+  }
+  const fromMeta = import_path.default.resolve(import_path.default.dirname(metaFile), source);
+  if (await import_fs_extra.default.pathExists(fromMeta)) {
+    return fromMeta;
+  }
+  return "";
+}
+__name(resolveSourcePath, "resolveSourcePath");
+function errorToString(error) {
+  if (error instanceof Error) {
+    return error.stack || error.message;
+  }
+  return String(error);
+}
+__name(errorToString, "errorToString");
+async function collectModuleGroups(packageName) {
+  const packageJsonPath = require.resolve(`${packageName}/package.json`);
+  const packageDir = import_path.default.dirname(packageJsonPath);
+  const distDocsDir = import_path.default.join(packageDir, "dist", "ai", "docs");
+  const srcDocsDir = import_path.default.join(packageDir, "src", "ai", "docs");
+  const preferSrc = process.env.APP_ENV !== "production";
+  const preferredDocsDir = preferSrc ? srcDocsDir : distDocsDir;
+  const fallbackDocsDir = preferSrc ? distDocsDir : srcDocsDir;
+  const docsDir = await import_fs_extra.default.pathExists(preferredDocsDir) ? preferredDocsDir : fallbackDocsDir;
+  if (!await import_fs_extra.default.pathExists(docsDir)) {
+    return [];
+  }
+  const rootMetaPath = import_path.default.join(docsDir, "meta.json");
+  let metaEntries = [];
+  if (await import_fs_extra.default.pathExists(rootMetaPath)) {
+    try {
+      const rootMeta = await import_fs_extra.default.readJson(rootMetaPath);
+      metaEntries = normalizeMetaEntries(rootMeta, import_path.default.basename(docsDir));
+    } catch {
+      metaEntries = [];
+    }
+  }
+  const moduleMetaFiles = metaEntries.length === 0 ? await (0, import_fast_glob.default)(["*/meta.json"], {
+    cwd: docsDir,
+    onlyFiles: true,
+    absolute: true
+  }) : [];
+  if (!metaEntries.length && !moduleMetaFiles.length) {
+    return [];
+  }
+  moduleMetaFiles.sort();
+  const moduleRoots = moduleMetaFiles.map((metaPath) => import_path.default.dirname(metaPath));
+  const groups = [];
+  const entriesToProcess = metaEntries.length > 0 ? metaEntries.map((entry) => ({ metaFile: rootMetaPath, entry })) : moduleMetaFiles.map((metaFile) => ({ metaFile, entry: void 0 }));
+  for (const item of entriesToProcess) {
+    const metaFile = item.metaFile;
+    const moduleRoot = import_path.default.dirname(metaFile);
+    const moduleDirName = import_path.default.basename(moduleRoot);
+    let perFileEntries = [];
+    if (item.entry) {
+      perFileEntries = [item.entry];
+    } else {
+      try {
+        const meta = await import_fs_extra.default.readJson(metaFile);
+        perFileEntries = normalizeMetaEntries(meta, moduleDirName);
+      } catch {
+        perFileEntries = normalizeMetaEntries(null, moduleDirName);
+      }
+    }
+    for (const metaEntry of perFileEntries) {
+      const moduleName = metaEntry.module || moduleDirName;
+      const description = metaEntry.description || "";
+      const source = metaEntry.source || "";
+      const defaultModuleRoot = import_path.default.join(docsDir, moduleName);
+      let effectiveModuleRoot = defaultModuleRoot;
+      if (source && preferSrc) {
+        const resolvedSource = await resolveSourcePath(source, metaFile);
+        if (resolvedSource) {
+          effectiveModuleRoot = resolvedSource;
+        }
+      }
+      if (!await import_fs_extra.default.pathExists(effectiveModuleRoot)) {
+        continue;
+      }
+      const ignore = [];
+      if (moduleRoot === docsDir && effectiveModuleRoot === moduleRoot) {
+        for (const otherRoot of moduleRoots) {
+          if (otherRoot === moduleRoot) continue;
+          const rel = import_path.default.relative(moduleRoot, otherRoot).split(import_path.default.sep).join("/");
+          if (rel && !rel.startsWith("..")) {
+            ignore.push(`${rel}/**`);
+          }
+        }
+      }
+      const files = await (0, import_fast_glob.default)(["**/*.{md,mdx}"], {
+        cwd: effectiveModuleRoot,
+        onlyFiles: true,
+        absolute: true,
+        ignore
+      });
+      if (!files.length) {
+        continue;
+      }
+      files.sort();
+      const directoryChildren = buildDirectoryChildren(files, effectiveModuleRoot);
+      const docEntries = await Promise.all(
+        files.map(async (file) => {
+          const relativePath = import_path.default.relative(effectiveModuleRoot, file);
+          const normalizedRelativePath = relativePath.split(import_path.default.sep).join("/");
+          const canonicalPath = import_path.default.posix.join(moduleName, normalizedRelativePath);
+          const content = await import_fs_extra.default.readFile(file, "utf8");
+          const meta = extractDocMetadata(content, file);
+          return {
+            absolutePath: file,
+            relativePath,
+            canonicalPath,
+            content,
+            moduleName,
+            moduleRoot,
+            packageName,
+            ...meta
+          };
+        })
+      );
+      const docMap = new Map(docEntries.map((entry) => [entry.absolutePath, entry]));
+      groups.push({
+        moduleName,
+        description,
+        moduleRoot,
+        packageName,
+        entries: docEntries,
+        directoryChildren,
+        docMap
+      });
+    }
+  }
+  return groups;
+}
+__name(collectModuleGroups, "collectModuleGroups");
+async function buildDocsIndexForPackages(packageNames) {
+  const moduleGroups = /* @__PURE__ */ new Map();
+  const moduleDescriptions = /* @__PURE__ */ new Map();
+  const conflicts = /* @__PURE__ */ new Map();
+  for (const packageName of packageNames) {
+    const groups = await collectModuleGroups(packageName);
+    for (const group of groups) {
+      const existing = moduleGroups.get(group.moduleName);
+      if (existing) {
+        existing.push(group);
+      } else {
+        moduleGroups.set(group.moduleName, [group]);
+      }
+      if (group.description) {
+        const existingDesc = moduleDescriptions.get(group.moduleName);
+        if (existingDesc && existingDesc !== group.description) {
+          const list = conflicts.get(group.moduleName) || [];
+          list.push(
+            `${group.packageName}: description mismatch (existing="${existingDesc}", new="${group.description}")`
+          );
+          conflicts.set(group.moduleName, list);
+        } else if (!existingDesc) {
+          moduleDescriptions.set(group.moduleName, group.description);
+        }
+      }
+    }
+  }
+  const results = /* @__PURE__ */ new Map();
+  for (const [moduleName, groups] of moduleGroups.entries()) {
+    const outputDir = import_path.default.join(DOCS_STORAGE_DIR, moduleName);
+    if (!groups.length) {
+      results.set(moduleName, { created: false, reason: "no doc files found" });
+      continue;
+    }
+    const docsOutputDir = outputDir;
+    const index = new import_ai.FlexSearchIndex();
+    const fileMap = {};
+    let currentId = 1;
+    let indexedDocs = 0;
+    const markdownExt = /* @__PURE__ */ new Set([".md", ".mdx"]);
+    const storagePathMap = /* @__PURE__ */ new Map();
+    const moduleConflicts = [];
+    await import_fs_extra.default.remove(outputDir);
+    await import_fs_extra.default.ensureDir(docsOutputDir);
+    const sortedGroups = groups.slice().sort((a, b) => {
+      if (a.packageName !== b.packageName) {
+        return a.packageName.localeCompare(b.packageName);
+      }
+      return a.moduleRoot.localeCompare(b.moduleRoot);
+    });
+    for (const group of sortedGroups) {
+      for (const entry of group.entries) {
+        const storageDocPath = import_path.default.join(docsOutputDir, entry.relativePath);
+        const existing = storagePathMap.get(storageDocPath);
+        if (existing) {
+          moduleConflicts.push(
+            `Duplicate path "${entry.relativePath}" from ${entry.packageName} and ${existing.packageName}`
+          );
+          continue;
+        }
+        storagePathMap.set(storageDocPath, entry);
+        await import_fs_extra.default.ensureDir(import_path.default.dirname(storageDocPath));
+        let processedContent = rewriteRelativeLinks(entry.content, entry);
+        const splitResult = splitMarkdownIfNeeded(processedContent, entry);
+        const splitRefs = splitResult.splits.map((split, index2) => {
+          const splitRelativePath = entry.relativePath.replace(/\.mdx?$/i, "") + split.suffix;
+          const splitCanonicalPath = import_path.default.posix.join(entry.moduleName, splitRelativePath.split(import_path.default.sep).join("/"));
+          return {
+            index: index2,
+            splitRelativePath,
+            splitCanonicalPath,
+            ...split
+          };
+        });
+        processedContent = splitResult.content;
+        if (entry.isIndex) {
+          processedContent = applyReferencesToIndex(
+            processedContent,
+            entry.absolutePath,
+            group.directoryChildren,
+            group.docMap
+          );
+        }
+        if (splitRefs.length) {
+          processedContent = applySplitReferences(
+            processedContent,
+            splitRefs.map((split) => ({
+              pathRef: split.splitCanonicalPath,
+              title: split.title,
+              description: split.description
+            }))
+          );
+        }
+        if (!entry.hasFrontMatter) {
+          processedContent = injectFrontMatter(processedContent, entry);
+        }
+        await import_fs_extra.default.writeFile(storageDocPath, processedContent, "utf8");
+        for (const split of splitRefs) {
+          const splitStoragePath = import_path.default.join(docsOutputDir, split.splitRelativePath);
+          if (storagePathMap.has(splitStoragePath)) {
+            moduleConflicts.push(`Duplicate split path "${split.splitRelativePath}" in ${entry.packageName}`);
+            continue;
+          }
+          storagePathMap.set(splitStoragePath, entry);
+          await import_fs_extra.default.ensureDir(import_path.default.dirname(splitStoragePath));
+          let splitContent = split.content;
+          splitContent = injectFrontMatter(splitContent, {
+            title: split.title,
+            description: split.description
+          });
+          await import_fs_extra.default.writeFile(splitStoragePath, splitContent, "utf8");
+        }
+        const ext = import_path.default.extname(entry.absolutePath).toLowerCase();
+        if (!markdownExt.has(ext)) {
+          continue;
+        }
+        const content = processedContent.trim();
+        if (!content) {
+          continue;
+        }
+        const docId = currentId++;
+        await index.addAsync(docId, processedContent);
+        fileMap[docId] = entry.canonicalPath;
+        indexedDocs++;
+      }
+    }
+    if (!indexedDocs) {
+      await import_fs_extra.default.remove(outputDir);
+      results.set(moduleName, { created: false, reason: "no markdown doc content to index" });
+      continue;
+    }
+    const indexData = {};
+    index.export((key, data) => {
+      indexData[key] = data;
+    });
+    await import_fs_extra.default.ensureDir(outputDir);
+    await import_fs_extra.default.writeJSON(import_path.default.join(outputDir, "index.json"), indexData, { spaces: 2 });
+    await import_fs_extra.default.writeJSON(import_path.default.join(outputDir, "files.json"), fileMap, { spaces: 2 });
+    const allConflicts = [...conflicts.get(moduleName) || [], ...moduleConflicts];
+    if (allConflicts.length) {
+      results.set(moduleName, { created: true, conflicts: allConflicts });
+    } else {
+      results.set(moduleName, { created: true });
+    }
+  }
+  if (moduleGroups.size) {
+    const metaOutput = {};
+    for (const moduleName of moduleGroups.keys()) {
+      metaOutput[moduleName] = {
+        description: moduleDescriptions.get(moduleName) || ""
+      };
+    }
+    await import_fs_extra.default.ensureDir(DOCS_STORAGE_DIR);
+    await import_fs_extra.default.writeJSON(import_path.default.join(DOCS_STORAGE_DIR, "meta.json"), metaOutput, { spaces: 2 });
+  }
+  return results;
+}
+__name(buildDocsIndexForPackages, "buildDocsIndexForPackages");
+function extractDocMetadata(content, filePath) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  const hasFrontMatter = normalized.startsWith("---\n") && normalized.indexOf("\n---", 4) !== -1;
+  let searchStart = 0;
+  if (hasFrontMatter) {
+    const closingIndex = normalized.indexOf("\n---", 4);
+    if (closingIndex !== -1) {
+      const closingLineEnd = normalized.indexOf("\n", closingIndex + 4);
+      searchStart = closingLineEnd === -1 ? normalized.length : closingLineEnd + 1;
+    }
+  }
+  let title = "";
+  let description = "";
+  const lines = normalized.slice(searchStart).split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.startsWith("# ")) {
+      title = line.replace(/^#\s+/, "").trim();
+      let j = i + 1;
+      const descParts = [];
+      while (j < lines.length) {
+        const descLine = lines[j].trim();
+        if (!descLine) {
+          if (descParts.length) break;
+          j++;
+          continue;
+        }
+        if (descLine.startsWith("#")) break;
+        descParts.push(descLine);
+        if (descParts.join(" ").length > 160) break;
+        j++;
+      }
+      description = descParts.join(" ");
+      break;
+    }
+  }
+  if (!title) {
+    const base = import_path.default.basename(filePath, import_path.default.extname(filePath));
+    title = base.split(/[-_]/).map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1)).join(" ");
+  }
+  if (!description) {
+    description = `Reference snippet for ${title}`;
+  }
+  return {
+    title,
+    description,
+    hasFrontMatter,
+    isIndex: import_path.default.basename(filePath).toLowerCase() === "index.md"
+  };
+}
+__name(extractDocMetadata, "extractDocMetadata");
+function injectFrontMatter(content, meta) {
+  const trimmed = content.replace(/^\uFEFF/, "");
+  const fmLines = [
+    "---",
+    `title: ${JSON.stringify(meta.title)}`,
+    `description: ${JSON.stringify(meta.description)}`,
+    "---"
+  ];
+  const frontMatter = `${fmLines.join("\n")}
+`;
+  const separator = trimmed.startsWith("\n") ? "" : "\n";
+  return `${frontMatter}${separator}${trimmed}`;
+}
+__name(injectFrontMatter, "injectFrontMatter");
+function splitFrontMatter(content) {
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return { frontMatter: "", body: normalized, hasFrontMatter: false };
+  }
+  const closingIndex = normalized.indexOf("\n---", 4);
+  if (closingIndex === -1) {
+    return { frontMatter: "", body: normalized, hasFrontMatter: false };
+  }
+  const closingLineEnd = normalized.indexOf("\n", closingIndex + 4);
+  const bodyStart = closingLineEnd === -1 ? normalized.length : closingLineEnd + 1;
+  return {
+    frontMatter: normalized.slice(0, bodyStart),
+    body: normalized.slice(bodyStart),
+    hasFrontMatter: true
+  };
+}
+__name(splitFrontMatter, "splitFrontMatter");
+function getPrimaryHeading(body) {
+  var _a;
+  const match = body.match(/^#\s+(.+)$/m);
+  return ((_a = match == null ? void 0 : match[1]) == null ? void 0 : _a.trim()) || "";
+}
+__name(getPrimaryHeading, "getPrimaryHeading");
+function countCodeBlocks(content) {
+  return (content.match(/```[\s\S]*?```/g) || []).length;
+}
+__name(countCodeBlocks, "countCodeBlocks");
+function normalizeHeadingText(text) {
+  return text.replace(/^#+\s+/, "").trim();
+}
+__name(normalizeHeadingText, "normalizeHeadingText");
+function splitByHeadings(body) {
+  const lines = body.split("\n");
+  const sections = [];
+  let current = null;
+  for (const line of lines) {
+    const headingMatch = line.match(/^(#{2,3})\s+(.+)$/);
+    if (headingMatch) {
+      if (current) {
+        sections.push(current);
+      }
+      current = {
+        level: headingMatch[1].length,
+        heading: normalizeHeadingText(headingMatch[0]),
+        content: []
+      };
+      continue;
+    }
+    if (current) {
+      current.content.push(line);
+    }
+  }
+  if (current) {
+    sections.push(current);
+  }
+  return sections.filter((section) => section.content.join("\n").trim().length > 0);
+}
+__name(splitByHeadings, "splitByHeadings");
+function splitExamples(body) {
+  var _a;
+  const codeRegex = /```[\s\S]*?```/g;
+  const headingRegex = /^(#{2,3})\s+(.+)$/gm;
+  const headings = [];
+  for (const match of body.matchAll(headingRegex)) {
+    const raw = normalizeHeadingText(match[0]);
+    const key = raw.toLowerCase();
+    headings.push({
+      index: match.index ?? 0,
+      level: match[1].length,
+      text: raw,
+      key
+    });
+  }
+  const examples = [];
+  const excludeKeys = /* @__PURE__ */ new Set([
+    "type definition",
+    "type definition (simplified)",
+    "parameters",
+    "return value",
+    "\u7C7B\u578B\u5B9A\u4E49",
+    "\u53C2\u6570",
+    "\u8FD4\u56DE\u503C"
+  ]);
+  const codeMatches = Array.from(body.matchAll(codeRegex));
+  const exampleCodeRanges = [];
+  const exampleSectionRanges = [];
+  for (const match of codeMatches) {
+    const code = match[0];
+    const index = match.index ?? 0;
+    const priorHeadings = headings.filter((item) => item.index < index);
+    const currentH2 = priorHeadings.filter((item) => item.level === 2).slice(-1)[0];
+    const currentH3 = priorHeadings.filter((item) => item.level === 3).slice(-1)[0];
+    const h2Key = (currentH2 == null ? void 0 : currentH2.key) || "";
+    const h3Key = (currentH3 == null ? void 0 : currentH3.key) || "";
+    if (excludeKeys.has(h2Key) || excludeKeys.has(h3Key)) {
+      continue;
+    }
+    const heading = (currentH3 == null ? void 0 : currentH3.text) || (currentH2 == null ? void 0 : currentH2.text) || "";
+    examples.push({ heading, content: code });
+    exampleCodeRanges.push({ start: index, end: index + code.length });
+    if (currentH3 || currentH2) {
+      const anchor = currentH3 || currentH2;
+      const nextHeadingIndex = ((_a = headings.filter((item) => item.index > anchor.index && item.level <= anchor.level).slice(0, 1)[0]) == null ? void 0 : _a.index) ?? body.length;
+      exampleSectionRanges.push({ start: anchor.index, end: nextHeadingIndex });
+    }
+  }
+  let cleanedBody = body;
+  if (exampleSectionRanges.length) {
+    const ranges = exampleSectionRanges.sort((a, b) => a.start - b.start).filter((range, index, list) => index === 0 || range.start >= list[index - 1].end);
+    let result = "";
+    let last = 0;
+    for (const range of ranges) {
+      result += body.slice(last, range.start);
+      last = range.end;
+    }
+    result += body.slice(last);
+    cleanedBody = result;
+  } else if (exampleCodeRanges.length) {
+    const ranges = exampleCodeRanges.sort((a, b) => a.start - b.start).filter((range, index, list) => index === 0 || range.start >= list[index - 1].end);
+    let result = "";
+    let last = 0;
+    for (const range of ranges) {
+      result += body.slice(last, range.start);
+      last = range.end;
+    }
+    result += body.slice(last);
+    cleanedBody = result;
+  }
+  return { examples, cleanedBody };
+}
+__name(splitExamples, "splitExamples");
+function splitMarkdownIfNeeded(content, entry) {
+  const { body, frontMatter, hasFrontMatter } = splitFrontMatter(content);
+  const bodyLength = body.trim().length;
+  const codeBlocks = countCodeBlocks(body);
+  const shouldSplitByLength = bodyLength > SPLIT_MAX_LENGTH;
+  const shouldSplitByExamples = codeBlocks > SPLIT_MAX_CODE_BLOCKS;
+  if (!shouldSplitByLength && !shouldSplitByExamples) {
+    return {
+      splits: [],
+      content
+    };
+  }
+  const h1 = getPrimaryHeading(body) || entry.title;
+  const splits = [];
+  let nextBody = body;
+  let didSplitByExamples = false;
+  if (shouldSplitByExamples) {
+    const { examples, cleanedBody } = splitExamples(body);
+    if (examples.length) {
+      didSplitByExamples = true;
+      nextBody = cleanedBody;
+      examples.forEach((example, index) => {
+        const headingLine = example.heading ? `## ${example.heading}
+
+` : "";
+        const exampleContent = `# ${h1}
+
+${headingLine}${example.content}
+`;
+        const title = example.heading ? `${example.heading} Example` : `${h1} Example ${index + 1}`;
+        splits.push({
+          suffix: `__example-${index + 1}.md`,
+          title,
+          description: `Extracted example from ${entry.title}`,
+          content: exampleContent
+        });
+      });
+    }
+  }
+  if (shouldSplitByLength && !didSplitByExamples) {
+    const sections = splitByHeadings(body);
+    sections.forEach((section, index) => {
+      const headingLine = `${"#".repeat(section.level)} ${section.heading}`;
+      const sectionBody = section.content.join("\n").trim();
+      const chunkContent = `# ${h1}
+
+${headingLine}
+${sectionBody}
+`;
+      const title = section.heading || `${h1} Chunk ${index + 1}`;
+      splits.push({
+        suffix: `__chunk-${index + 1}.md`,
+        title,
+        description: `Extracted section from ${entry.title}`,
+        content: chunkContent
+      });
+    });
+  }
+  const rebuilt = hasFrontMatter ? `${frontMatter}${nextBody}` : nextBody;
+  return { splits, content: rebuilt };
+}
+__name(splitMarkdownIfNeeded, "splitMarkdownIfNeeded");
+function applySplitReferences(content, splits) {
+  if (!splits.length) return content;
+  const refLines = splits.map((split) => referenceLine(split.title, split.description, split.pathRef));
+  const baseContent = stripSplitReferenceBlock(content).trimEnd();
+  const block = `${SPLIT_REFERENCE_START}
+
+## Extracted references
+
+${refLines.join(
+    "\n"
+  )}
+
+${SPLIT_REFERENCE_END}`;
+  if (!baseContent) {
+    return `${block}
+`;
+  }
+  return `${baseContent}
+
+${block}
+`;
+}
+__name(applySplitReferences, "applySplitReferences");
+function stripSplitReferenceBlock(content) {
+  const start = content.indexOf(SPLIT_REFERENCE_START);
+  if (start === -1) return content;
+  const end = content.indexOf(SPLIT_REFERENCE_END, start + SPLIT_REFERENCE_START.length);
+  if (end === -1) return content;
+  const before = content.slice(0, start).trimEnd();
+  const after = content.slice(end + SPLIT_REFERENCE_END.length).trimStart();
+  if (!before) return after;
+  if (!after) return `${before}
+`;
+  return `${before}
+
+${after}`;
+}
+__name(stripSplitReferenceBlock, "stripSplitReferenceBlock");
+function rewriteRelativeLinks(content, entry) {
+  const { body, frontMatter, hasFrontMatter } = splitFrontMatter(content);
+  const segments = [];
+  const codeRegex = /```[\s\S]*?```/g;
+  let lastIndex = 0;
+  for (const match of body.matchAll(codeRegex)) {
+    const index = match.index ?? 0;
+    if (index > lastIndex) {
+      segments.push({ type: "text", content: body.slice(lastIndex, index) });
+    }
+    segments.push({ type: "code", content: match[0] });
+    lastIndex = index + match[0].length;
+  }
+  if (lastIndex < body.length) {
+    segments.push({ type: "text", content: body.slice(lastIndex) });
+  }
+  const dir = import_path.default.posix.dirname(entry.relativePath.split(import_path.default.sep).join("/"));
+  const rewritten = segments.map((segment) => {
+    if (segment.type === "code") return segment.content;
+    return segment.content.replace(/(!?)\[[^\]]+]\(([^)]+)\)/g, (match, bang, link) => {
+      if (bang) return match;
+      const trimmed = link.trim();
+      if (trimmed.startsWith("http://") || trimmed.startsWith("https://") || trimmed.startsWith("/") || trimmed.startsWith("#") || trimmed.startsWith("mailto:") || trimmed.startsWith("tel:")) {
+        return match;
+      }
+      const hashIndex = trimmed.indexOf("#");
+      const hash = hashIndex >= 0 ? trimmed.slice(hashIndex) : "";
+      const beforeHash = hashIndex >= 0 ? trimmed.slice(0, hashIndex) : trimmed;
+      const queryIndex = beforeHash.indexOf("?");
+      const query = queryIndex >= 0 ? beforeHash.slice(queryIndex) : "";
+      const pathPart = queryIndex >= 0 ? beforeHash.slice(0, queryIndex) : beforeHash;
+      const resolved = import_path.default.posix.normalize(import_path.default.posix.join(dir, pathPart));
+      const normalized = resolved.startsWith(".") ? resolved.replace(/^(\.\.\/?)+/, "") : resolved;
+      const absolutePath = import_path.default.posix.join("/", entry.moduleName, normalized);
+      const nextLink = `${absolutePath}${query}${hash}`;
+      return match.replace(link, nextLink);
+    });
+  }).join("");
+  if (!hasFrontMatter) {
+    return rewritten;
+  }
+  return `${frontMatter}${rewritten}`;
+}
+__name(rewriteRelativeLinks, "rewriteRelativeLinks");
+function applyReferencesToIndex(content, filePath, directoryChildren, docMap) {
+  const dir = import_path.default.dirname(filePath);
+  const entry = directoryChildren.get(dir);
+  if (!entry) {
+    return stripExistingReferenceBlock(content);
+  }
+  const refLines = [];
+  const refs = /* @__PURE__ */ new Set();
+  const childFiles = entry.files.filter((file) => file !== import_path.default.join(dir, "index.md"));
+  for (const child of childFiles.sort()) {
+    const meta = docMap.get(child);
+    if (!meta) continue;
+    const refPath = meta.canonicalPath;
+    if (refs.has(refPath)) continue;
+    refs.add(refPath);
+    refLines.push(referenceLine(meta.title, meta.description, refPath));
+  }
+  for (const subDir of entry.directories.sort()) {
+    const indexFile = import_path.default.join(subDir, "index.md");
+    const meta = docMap.get(indexFile);
+    if (!meta) continue;
+    const refPath = meta.canonicalPath;
+    if (refs.has(refPath)) continue;
+    refs.add(refPath);
+    refLines.push(referenceLine(meta.title, meta.description, refPath));
+  }
+  if (!refLines.length) {
+    return stripExistingReferenceBlock(content);
+  }
+  const baseContent = stripExistingReferenceBlock(content).trimEnd();
+  const block = `${REFERENCE_START}
+
+## References
+
+${refLines.join("\n")}
+
+${REFERENCE_END}`;
+  if (!baseContent) {
+    return `${block}
+`;
+  }
+  return `${baseContent}
+
+${block}
+`;
+}
+__name(applyReferencesToIndex, "applyReferencesToIndex");
+function referenceLine(title, description, pathRef) {
+  const summary = description.length > 200 ? `${description.slice(0, 197)}...` : description;
+  const descText = summary ? ` - ${summary}` : "";
+  return `- **${title}** (\`${pathRef}\`)${descText}`;
+}
+__name(referenceLine, "referenceLine");
+function stripExistingReferenceBlock(content) {
+  const start = content.indexOf(REFERENCE_START);
+  if (start === -1) return content;
+  const end = content.indexOf(REFERENCE_END, start + REFERENCE_START.length);
+  if (end === -1) return content;
+  const before = content.slice(0, start).trimEnd();
+  const after = content.slice(end + REFERENCE_END.length).trimStart();
+  if (!before) return after;
+  if (!after) return `${before}
+`;
+  return `${before}
+
+${after}`;
+}
+__name(stripExistingReferenceBlock, "stripExistingReferenceBlock");
+async function createDocsIndex(app, options = {}) {
+  var _a;
+  const pkgs = await resolvePkgs(options.pkg);
+  if (!pkgs.length) {
+    app.log.info("No plugin packages detected for docs index generation");
+    return;
+  }
+  const packageNames = [];
+  for (const pkg of pkgs) {
+    try {
+      const { packageName } = await import_plugin_manager.PluginManager.parseName(pkg);
+      packageNames.push(packageName);
+    } catch (error) {
+      app.log.error(error, { pkg });
+    }
+  }
+  if (!packageNames.length) {
+    app.log.info("No plugin packages resolved for docs index generation");
+    return;
+  }
+  let results = null;
+  let lastError;
+  for (let attempt = 0; attempt < CREATE_INDEX_RETRY_MAX; attempt++) {
+    try {
+      results = await buildDocsIndexForPackages(packageNames);
+      break;
+    } catch (error) {
+      lastError = error;
+      if (attempt === CREATE_INDEX_RETRY_MAX - 1) {
+        break;
+      }
+      app.log.warn(`Docs index build failed, retrying (${attempt + 1}/${CREATE_INDEX_RETRY_MAX})`);
+      await new Promise((resolve) => setTimeout(resolve, CREATE_INDEX_RETRY_DELAY_MS * (attempt + 1)));
+    }
+  }
+  if (!results) {
+    const message = lastError ? errorToString(lastError) : "Docs index build failed";
+    app.log.error(message);
+    return;
+  }
+  if (!results.size) {
+    app.log.info("No module docs found to index");
+    return;
+  }
+  for (const [moduleName, result] of results.entries()) {
+    if (result.created) {
+      app.log.info(`Docs index generated for module "${moduleName}"`);
+      if ((_a = result.conflicts) == null ? void 0 : _a.length) {
+        app.log.warn(`Module "${moduleName}" has conflicts: ${result.conflicts.join("; ")}`);
+      }
+    } else {
+      app.log.info(`Skipped docs index for module "${moduleName}": ${result.reason}`);
+    }
+  }
+}
+__name(createDocsIndex, "createDocsIndex");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDocsIndex
+});