docusaurus-plugin-glossary 3.1.0 → 3.2.0

package/dist/index.cjs

@@ -0,0 +1,659 @@
+"use strict";
+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 __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);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  GlossaryValidationError: () => GlossaryValidationError,
+  clearGlossaryCache: () => clearGlossaryCache,
+  default: () => glossaryPlugin,
+  formatValidationErrors: () => formatValidationErrors,
+  getRemarkPlugin: () => getRemarkPlugin,
+  remarkPlugin: () => remarkPlugin,
+  validateGlossaryData: () => validateGlossaryData
+});
+module.exports = __toCommonJS(src_exports);
+var import_path2 = __toESM(require("path"), 1);
+var import_url = require("url");
+var import_fs_extra = __toESM(require("fs-extra"), 1);
+var import_validate_peer_dependencies = __toESM(require("validate-peer-dependencies"), 1);
+
+// src/remark/glossary-terms.js
+var import_unist_util_visit = require("unist-util-visit");
+var import_path = __toESM(require("path"), 1);
+var import_fs = __toESM(require("fs"), 1);
+function validateGlossaryTerms(data, _filePath) {
+  const errors = [];
+  const validTerms = [];
+  if (data === null || data === void 0) {
+    errors.push(`Glossary data is null or undefined`);
+    return { terms: [], errors };
+  }
+  if (typeof data !== "object") {
+    errors.push(`Glossary data must be an object, got ${typeof data}`);
+    return { terms: [], errors };
+  }
+  if (!("terms" in data)) {
+    errors.push(`Glossary data must contain a "terms" array`);
+    return { terms: [], errors };
+  }
+  if (!Array.isArray(data.terms)) {
+    errors.push(`Field "terms" must be an array, got ${typeof data.terms}`);
+    return { terms: [], errors };
+  }
+  data.terms.forEach((term, index) => {
+    if (term === null || term === void 0 || typeof term !== "object") {
+      errors.push(`terms[${index}]: Term must be an object`);
+      return;
+    }
+    if (typeof term.term !== "string" || term.term.trim() === "") {
+      errors.push(`terms[${index}]: Missing or invalid "term" field`);
+      return;
+    }
+    if (typeof term.definition !== "string") {
+      errors.push(`terms[${index}]: Missing or invalid "definition" field`);
+      return;
+    }
+    validTerms.push(term);
+  });
+  return { terms: validTerms, errors };
+}
+var glossaryCache = /* @__PURE__ */ new Map();
+var CACHE_TTL = 5e3;
+function remarkGlossaryTerms({
+  terms = [],
+  glossaryPath = null,
+  routePath = "/glossary",
+  siteDir = null
+} = {}) {
+  let glossaryTerms = terms;
+  if (!glossaryTerms.length && glossaryPath && siteDir) {
+    try {
+      const glossaryFilePath = import_path.default.resolve(siteDir, glossaryPath);
+      const now = Date.now();
+      const cached = glossaryCache.get(glossaryFilePath);
+      if (cached && now - cached.loadedAt < CACHE_TTL) {
+        glossaryTerms = cached.terms;
+      } else {
+        if (import_fs.default.existsSync(glossaryFilePath)) {
+          const fileContent = import_fs.default.readFileSync(glossaryFilePath, "utf8");
+          let glossaryData;
+          try {
+            glossaryData = JSON.parse(fileContent);
+          } catch (parseError) {
+            console.error(
+              `[glossary-plugin] Failed to parse glossary JSON at ${glossaryPath}:`,
+              parseError.message
+            );
+            glossaryCache.set(glossaryFilePath, {
+              terms: [],
+              loadedAt: now
+            });
+            return (tree) => tree;
+          }
+          const { terms: validTerms, errors } = validateGlossaryTerms(glossaryData, glossaryPath);
+          if (errors.length > 0) {
+            console.warn(`[glossary-plugin] Glossary validation errors in ${glossaryPath}:`);
+            errors.forEach((err) => console.warn(`  - ${err}`));
+            if (validTerms.length > 0) {
+              console.warn(`[glossary-plugin] Proceeding with ${validTerms.length} valid term(s).`);
+            }
+          }
+          glossaryTerms = validTerms;
+          glossaryCache.set(glossaryFilePath, {
+            terms: glossaryTerms,
+            loadedAt: now
+          });
+          if (!cached && process.env.NODE_ENV !== "production") {
+            console.log(
+              `[glossary-plugin] Loaded ${glossaryTerms.length} terms from ${glossaryPath}`
+            );
+          }
+        } else {
+          glossaryCache.set(glossaryFilePath, {
+            terms: [],
+            loadedAt: now
+          });
+          if (process.env.NODE_ENV !== "production") {
+            console.warn(`[glossary-plugin] Glossary file not found: ${glossaryPath}`);
+          }
+        }
+      }
+    } catch (error) {
+      console.warn(
+        `[glossary-plugin] Failed to load glossary from ${glossaryPath}:`,
+        error.message
+      );
+      if (glossaryPath && siteDir) {
+        const glossaryFilePath = import_path.default.resolve(siteDir, glossaryPath);
+        glossaryCache.set(glossaryFilePath, {
+          terms: [],
+          loadedAt: Date.now()
+        });
+      }
+    }
+  }
+  const termMap = /* @__PURE__ */ new Map();
+  glossaryTerms.forEach((termObj) => {
+    if (termObj.term && termObj.autoLink !== false) {
+      termMap.set(termObj.term.toLowerCase(), termObj);
+    }
+  });
+  const sortedTerms = Array.from(termMap.entries()).sort((a, b) => b[0].length - a[0].length);
+  if (sortedTerms.length === 0) {
+    return (tree) => tree;
+  }
+  function replaceTermsInText(text) {
+    if (!text || !sortedTerms.length) {
+      return [{ type: "text", value: text }];
+    }
+    const result = [];
+    let lastIndex = 0;
+    const textLower = text.toLowerCase();
+    const matches = [];
+    for (const [lowerTerm, termObj] of sortedTerms) {
+      const term = termObj.term;
+      let searchIndex = 0;
+      while (searchIndex < textLower.length) {
+        const index = textLower.indexOf(lowerTerm, searchIndex);
+        if (index === -1) break;
+        const beforeChar = index > 0 ? textLower[index - 1] : " ";
+        const afterIndex = index + lowerTerm.length;
+        const afterChar = afterIndex < textLower.length ? textLower[afterIndex] : " ";
+        let matchLength = term.length;
+        let isWordBoundary = !/\w/.test(beforeChar) && !/\w/.test(afterChar);
+        if (!isWordBoundary && afterChar === "s") {
+          const nextChar = afterIndex + 1 < textLower.length ? textLower[afterIndex + 1] : " ";
+          if (!/\w/.test(nextChar)) {
+            isWordBoundary = true;
+            matchLength = term.length + 1;
+          }
+        }
+        if (!isWordBoundary && afterChar === "e" && afterIndex + 1 < textLower.length && textLower[afterIndex + 1] === "s") {
+          const nextChar = afterIndex + 2 < textLower.length ? textLower[afterIndex + 2] : " ";
+          if (!/\w/.test(nextChar)) {
+            isWordBoundary = true;
+            matchLength = term.length + 2;
+          }
+        }
+        if (isWordBoundary) {
+          matches.push({
+            index,
+            length: matchLength,
+            term,
+            termObj,
+            // Store original case from the text
+            originalText: text.substring(index, index + matchLength)
+          });
+        }
+        searchIndex = index + 1;
+      }
+    }
+    matches.sort((a, b) => a.index - b.index);
+    const nonOverlappingMatches = [];
+    let lastMatchEnd = 0;
+    for (const match of matches) {
+      if (match.index >= lastMatchEnd) {
+        nonOverlappingMatches.push(match);
+        lastMatchEnd = match.index + match.length;
+      }
+    }
+    for (const match of nonOverlappingMatches) {
+      if (match.index > lastIndex) {
+        result.push({
+          type: "text",
+          value: text.substring(lastIndex, match.index)
+        });
+      }
+      result.push({
+        type: "mdxJsxFlowElement",
+        name: "GlossaryTerm",
+        attributes: [
+          {
+            type: "mdxJsxAttribute",
+            name: "term",
+            value: match.termObj.term
+          },
+          {
+            type: "mdxJsxAttribute",
+            name: "definition",
+            value: match.termObj.definition || ""
+          },
+          {
+            type: "mdxJsxAttribute",
+            name: "routePath",
+            value: routePath
+          }
+        ],
+        children: [
+          {
+            type: "text",
+            value: match.originalText
+          }
+        ]
+      });
+      lastIndex = match.index + match.length;
+    }
+    if (lastIndex < text.length) {
+      result.push({
+        type: "text",
+        value: text.substring(lastIndex)
+      });
+    }
+    return result.length > 0 ? result : [{ type: "text", value: text }];
+  }
+  const transformer = (tree) => {
+    let usedGlossaryTerm = false;
+    (0, import_unist_util_visit.visit)(tree, "text", (node, index, parent) => {
+      if (parent.type === "code" || parent.type === "inlineCode" || parent.type === "link" || parent.type === "mdxJsxFlowElement" || parent.type === "mdxJsxTextElement") {
+        return;
+      }
+      const replacements = replaceTermsInText(node.value);
+      if (replacements.length > 1 || replacements.length === 1 && replacements[0].type !== "text") {
+        const newNodes = replacements.map((replacement) => {
+          if (replacement.type === "mdxJsxFlowElement") {
+            if (parent.type === "paragraph") {
+              usedGlossaryTerm = true;
+              return {
+                type: "mdxJsxTextElement",
+                name: replacement.name,
+                attributes: replacement.attributes,
+                children: replacement.children
+              };
+            }
+            usedGlossaryTerm = true;
+          }
+          return replacement;
+        });
+        parent.children.splice(index, 1, ...newNodes);
+        return index + newNodes.length - 1;
+      }
+    });
+    if (usedGlossaryTerm) {
+      const importNode = {
+        type: "mdxjsEsm",
+        value: 'import GlossaryTerm from "@theme/GlossaryTerm";',
+        data: {
+          estree: {
+            type: "Program",
+            sourceType: "module",
+            body: [
+              {
+                type: "ImportDeclaration",
+                specifiers: [
+                  {
+                    type: "ImportDefaultSpecifier",
+                    local: { type: "Identifier", name: "GlossaryTerm" }
+                  }
+                ],
+                source: {
+                  type: "Literal",
+                  value: "@theme/GlossaryTerm",
+                  raw: '"@theme/GlossaryTerm"'
+                }
+              }
+            ]
+          }
+        }
+      };
+      const hasImport = Array.isArray(tree.children) && tree.children.some(
+        (n) => n.type === "mdxjsEsm" && (n.value?.includes("@theme/GlossaryTerm") || n.data?.estree?.body?.some((s) => s.source?.value === "@theme/GlossaryTerm"))
+      );
+      if (!hasImport) {
+        if (!Array.isArray(tree.children)) tree.children = [];
+        let insertIndex = 0;
+        for (let i = 0; i < tree.children.length; i++) {
+          const node = tree.children[i];
+          if (node.type === "yaml" || node.type === "toml") {
+            insertIndex = i + 1;
+          } else {
+            break;
+          }
+        }
+        tree.children.splice(insertIndex, 0, importNode);
+      }
+    }
+  };
+  return transformer;
+}
+function clearGlossaryCache(filePath) {
+  if (filePath) {
+    glossaryCache.delete(filePath);
+  } else {
+    glossaryCache.clear();
+  }
+}
+
+// src/validation.ts
+function validateTerm(term, index) {
+  const errors = [];
+  const prefix = `terms[${index}]`;
+  if (term === null || term === void 0) {
+    errors.push({
+      field: prefix,
+      message: "Term cannot be null or undefined",
+      value: term
+    });
+    return errors;
+  }
+  if (typeof term !== "object") {
+    errors.push({
+      field: prefix,
+      message: `Term must be an object, got ${typeof term}`,
+      value: term
+    });
+    return errors;
+  }
+  const termObj = term;
+  if (!("term" in termObj)) {
+    errors.push({
+      field: `${prefix}.term`,
+      message: 'Missing required field "term"'
+    });
+  } else if (typeof termObj.term !== "string") {
+    errors.push({
+      field: `${prefix}.term`,
+      message: `Field "term" must be a string, got ${typeof termObj.term}`,
+      value: termObj.term
+    });
+  } else if (termObj.term.trim() === "") {
+    errors.push({
+      field: `${prefix}.term`,
+      message: 'Field "term" cannot be empty',
+      value: termObj.term
+    });
+  }
+  if (!("definition" in termObj)) {
+    errors.push({
+      field: `${prefix}.definition`,
+      message: 'Missing required field "definition"'
+    });
+  } else if (typeof termObj.definition !== "string") {
+    errors.push({
+      field: `${prefix}.definition`,
+      message: `Field "definition" must be a string, got ${typeof termObj.definition}`,
+      value: termObj.definition
+    });
+  }
+  if ("abbreviation" in termObj && termObj.abbreviation !== void 0) {
+    if (typeof termObj.abbreviation !== "string") {
+      errors.push({
+        field: `${prefix}.abbreviation`,
+        message: `Field "abbreviation" must be a string, got ${typeof termObj.abbreviation}`,
+        value: termObj.abbreviation
+      });
+    }
+  }
+  if ("relatedTerms" in termObj && termObj.relatedTerms !== void 0) {
+    if (!Array.isArray(termObj.relatedTerms)) {
+      errors.push({
+        field: `${prefix}.relatedTerms`,
+        message: `Field "relatedTerms" must be an array, got ${typeof termObj.relatedTerms}`,
+        value: termObj.relatedTerms
+      });
+    } else {
+      termObj.relatedTerms.forEach((relatedTerm, relatedIndex) => {
+        if (typeof relatedTerm !== "string") {
+          errors.push({
+            field: `${prefix}.relatedTerms[${relatedIndex}]`,
+            message: `Related term must be a string, got ${typeof relatedTerm}`,
+            value: relatedTerm
+          });
+        }
+      });
+    }
+  }
+  if ("id" in termObj && termObj.id !== void 0) {
+    if (typeof termObj.id !== "string") {
+      errors.push({
+        field: `${prefix}.id`,
+        message: `Field "id" must be a string, got ${typeof termObj.id}`,
+        value: termObj.id
+      });
+    }
+  }
+  if ("autoLink" in termObj && termObj.autoLink !== void 0) {
+    if (typeof termObj.autoLink !== "boolean") {
+      errors.push({
+        field: `${prefix}.autoLink`,
+        message: `Field "autoLink" must be a boolean, got ${typeof termObj.autoLink}`,
+        value: termObj.autoLink
+      });
+    }
+  }
+  return errors;
+}
+function validateGlossaryData(data, options = {}) {
+  const { throwOnError = true } = options;
+  const errors = [];
+  if (data === null || data === void 0) {
+    errors.push({
+      field: "root",
+      message: "Glossary data cannot be null or undefined",
+      value: data
+    });
+    if (throwOnError && errors.length > 0) {
+      throw new GlossaryValidationError(errors);
+    }
+    return { valid: false, errors, data: { terms: [] } };
+  }
+  if (typeof data !== "object") {
+    errors.push({
+      field: "root",
+      message: `Glossary data must be an object, got ${typeof data}`,
+      value: data
+    });
+    if (throwOnError && errors.length > 0) {
+      throw new GlossaryValidationError(errors);
+    }
+    return { valid: false, errors, data: { terms: [] } };
+  }
+  const glossaryData = data;
+  if (!("terms" in glossaryData)) {
+    errors.push({
+      field: "terms",
+      message: 'Glossary data must contain a "terms" array'
+    });
+    if (throwOnError && errors.length > 0) {
+      throw new GlossaryValidationError(errors);
+    }
+    return { valid: false, errors, data: { terms: [] } };
+  }
+  if (!Array.isArray(glossaryData.terms)) {
+    errors.push({
+      field: "terms",
+      message: `Field "terms" must be an array, got ${typeof glossaryData.terms}`,
+      value: glossaryData.terms
+    });
+    if (throwOnError && errors.length > 0) {
+      throw new GlossaryValidationError(errors);
+    }
+    return { valid: false, errors, data: { terms: [] } };
+  }
+  const validTerms = [];
+  glossaryData.terms.forEach((term, index) => {
+    const termErrors = validateTerm(term, index);
+    if (termErrors.length > 0) {
+      errors.push(...termErrors);
+    } else {
+      validTerms.push(term);
+    }
+  });
+  const termNames = /* @__PURE__ */ new Map();
+  validTerms.forEach((term, index) => {
+    const lowerName = term.term.toLowerCase();
+    if (termNames.has(lowerName)) {
+      errors.push({
+        field: `terms[${index}].term`,
+        message: `Duplicate term "${term.term}" (first occurrence at index ${termNames.get(lowerName)})`,
+        value: term.term
+      });
+    } else {
+      termNames.set(lowerName, index);
+    }
+  });
+  if (throwOnError && errors.length > 0) {
+    throw new GlossaryValidationError(errors);
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    data: { terms: validTerms }
+  };
+}
+var GlossaryValidationError = class _GlossaryValidationError extends Error {
+  constructor(errors) {
+    const message = formatValidationErrors(errors);
+    super(message);
+    this.name = "GlossaryValidationError";
+    this.errors = errors;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _GlossaryValidationError);
+    }
+  }
+};
+function formatValidationErrors(errors) {
+  if (errors.length === 0) {
+    return "No validation errors";
+  }
+  const header = `Glossary validation failed with ${errors.length} error${errors.length > 1 ? "s" : ""}:`;
+  const errorList = errors.map((err, index) => {
+    let msg = `  ${index + 1}. [${err.field}] ${err.message}`;
+    if (err.value !== void 0) {
+      const valueStr = typeof err.value === "object" ? JSON.stringify(err.value) : String(err.value);
+      const truncated = valueStr.length > 50 ? valueStr.substring(0, 50) + "..." : valueStr;
+      msg += ` (got: ${truncated})`;
+    }
+    return msg;
+  }).join("\n");
+  return `${header}
+${errorList}`;
+}
+
+// src/index.ts
+var import_meta = {};
+var currentFilePath = (0, import_url.fileURLToPath)(import_meta.url);
+var currentDir = import_path2.default.dirname(currentFilePath);
+(0, import_validate_peer_dependencies.default)(currentDir);
+function glossaryPlugin(context, options = {}) {
+  const { glossaryPath = "glossary/glossary.json", routePath = "/glossary" } = options;
+  return {
+    name: "docusaurus-plugin-glossary",
+    getClientModules() {
+      return [import_path2.default.resolve(currentDir, "./client/index.js")];
+    },
+    async loadContent() {
+      const glossaryFilePath = import_path2.default.resolve(context.siteDir, glossaryPath);
+      if (await import_fs_extra.default.pathExists(glossaryFilePath)) {
+        try {
+          const rawData = await import_fs_extra.default.readJson(glossaryFilePath);
+          const validationResult = validateGlossaryData(rawData, { throwOnError: false });
+          if (!validationResult.valid) {
+            console.warn(
+              `[glossary-plugin] Glossary file has validation errors at ${glossaryFilePath}:`
+            );
+            validationResult.errors.forEach((err) => {
+              console.warn(`  - [${err.field}] ${err.message}`);
+            });
+            console.warn("[glossary-plugin] Proceeding with valid terms only.");
+          }
+          return validationResult.data;
+        } catch (error) {
+          if (error instanceof GlossaryValidationError) {
+            throw error;
+          }
+          throw new Error(
+            `Failed to parse glossary file at ${glossaryFilePath}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      console.warn(`Glossary file not found at ${glossaryFilePath}. Using empty glossary.`);
+      return { terms: [] };
+    },
+    async contentLoaded({ content, actions }) {
+      const { createData, addRoute, setGlobalData } = actions;
+      const glossaryContent = content;
+      const glossaryDataPath = await createData(
+        "glossary-data.json",
+        JSON.stringify(glossaryContent)
+      );
+      await createData(
+        "remark-glossary-data.json",
+        JSON.stringify({
+          terms: glossaryContent.terms || [],
+          routePath
+        })
+      );
+      addRoute({
+        path: routePath,
+        component: import_path2.default.join(currentDir, "components/GlossaryPage.js"),
+        exact: true,
+        modules: {
+          glossaryData: glossaryDataPath
+        }
+      });
+      setGlobalData({
+        terms: glossaryContent.terms || [],
+        routePath
+      });
+    },
+    getThemePath() {
+      return import_path2.default.resolve(currentDir, "./theme");
+    },
+    getPathsToWatch() {
+      return [import_path2.default.resolve(context.siteDir, glossaryPath)];
+    },
+    async postBuild() {
+      console.log("Glossary plugin: Build completed");
+    }
+  };
+}
+var remarkPlugin = remarkGlossaryTerms;
+function getRemarkPlugin(pluginOptions, context) {
+  const { glossaryPath = "glossary/glossary.json", routePath = "/glossary" } = pluginOptions;
+  const siteDir = context?.siteDir;
+  return [
+    remarkGlossaryTerms,
+    {
+      glossaryPath,
+      routePath,
+      siteDir
+    }
+  ];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  GlossaryValidationError,
+  clearGlossaryCache,
+  formatValidationErrors,
+  getRemarkPlugin,
+  remarkPlugin,
+  validateGlossaryData
+});
+//# sourceMappingURL=index.cjs.map