docusaurus-plugin-llms 0.2.0 → 0.3.0

package/lib/utils.js

@@ -39,6 +39,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.LogLevel = exports.ValidationError = void 0;
+exports.isDefined = isDefined;
+exports.isNonEmptyString = isNonEmptyString;
+exports.isNonEmptyArray = isNonEmptyArray;
+exports.getErrorMessage = getErrorMessage;
+exports.getErrorStack = getErrorStack;
+exports.validateRequired = validateRequired;
+exports.validateString = validateString;
+exports.validateArray = validateArray;
+exports.setLogLevel = setLogLevel;
+exports.normalizePath = normalizePath;
+exports.validatePathLength = validatePathLength;
+exports.shortenPathIfNeeded = shortenPathIfNeeded;
 exports.writeFile = writeFile;
 exports.readFile = readFile;
 exports.shouldIgnoreFile = shouldIgnoreFile;
@@ -47,10 +60,240 @@ exports.extractTitle = extractTitle;
 exports.resolvePartialImports = resolvePartialImports;
 exports.cleanMarkdownContent = cleanMarkdownContent;
 exports.applyPathTransformations = applyPathTransformations;
+exports.sanitizeForFilename = sanitizeForFilename;
+exports.ensureUniqueIdentifier = ensureUniqueIdentifier;
+exports.createMarkdownContent = createMarkdownContent;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
 const minimatch_1 = require("minimatch");
 const gray_matter_1 = __importDefault(require("gray-matter"));
+const YAML = __importStar(require("yaml"));
+/**
+ * Null/Undefined Handling Guidelines:
+ *
+ * 1. For required parameters: Throw early if null/undefined
+ * 2. For optional parameters: Use optional chaining `value?.property`
+ * 3. For explicit null checks: Use `!== null` and `!== undefined` or the isDefined type guard
+ * 4. For string validation: Use isNonEmptyString() type guard
+ * 5. For truthy checks on booleans: Use explicit comparison or Boolean(value)
+ *
+ * Avoid: `if (value)` when value could be 0, '', or false legitimately
+ * Use: Type guards for consistent, type-safe checks
+ */
+/**
+ * Type guard to check if a value is defined (not null or undefined)
+ * @param value - Value to check
+ * @returns True if value is not null or undefined
+ */
+function isDefined(value) {
+    return value !== null && value !== undefined;
+}
+/**
+ * Type guard to check if a value is a non-empty string
+ * @param value - Value to check
+ * @returns True if value is a string with at least one non-whitespace character
+ */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Type guard to check if a value is a non-empty array
+ * @param value - Value to check
+ * @returns True if value is an array with at least one element
+ */
+function isNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+/**
+ * Safely extract an error message from an unknown error value
+ * @param error - The error value (can be Error, string, or any other type)
+ * @returns A string representation of the error
+ */
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    try {
+        const stringified = JSON.stringify(error);
+        // JSON.stringify returns undefined for undefined values, handle that case
+        return stringified !== undefined ? stringified : 'Unknown error';
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
+/**
+ * Extract stack trace from unknown error types
+ * @param error - The error value (can be Error or any other type)
+ * @returns Stack trace if available, undefined otherwise
+ */
+function getErrorStack(error) {
+    if (error instanceof Error) {
+        return error.stack;
+    }
+    return undefined;
+}
+/**
+ * Custom error class for validation errors
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Validates that a value is not null or undefined
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @returns The validated value
+ * @throws ValidationError if the value is null or undefined
+ */
+function validateRequired(value, paramName) {
+    if (value === null || value === undefined) {
+        throw new ValidationError(`Required parameter '${paramName}' is null or undefined`);
+    }
+    return value;
+}
+/**
+ * Validates that a value is a string and optionally checks its properties
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param options - Validation options for min/max length and pattern
+ * @returns The validated string
+ * @throws ValidationError if validation fails
+ */
+function validateString(value, paramName, options = {}) {
+    if (typeof value !== 'string') {
+        throw new ValidationError(`Parameter '${paramName}' must be a string, got ${typeof value}`);
+    }
+    if (options.minLength !== undefined && value.length < options.minLength) {
+        throw new ValidationError(`Parameter '${paramName}' must be at least ${options.minLength} characters`);
+    }
+    if (options.maxLength !== undefined && value.length > options.maxLength) {
+        throw new ValidationError(`Parameter '${paramName}' exceeds maximum length of ${options.maxLength}`);
+    }
+    if (options.pattern && !options.pattern.test(value)) {
+        throw new ValidationError(`Parameter '${paramName}' does not match required pattern`);
+    }
+    return value;
+}
+/**
+ * Validates that a value is an array and optionally validates elements
+ * @param value - The value to validate
+ * @param paramName - The parameter name for error messages
+ * @param elementValidator - Optional function to validate each element
+ * @returns The validated array
+ * @throws ValidationError if validation fails
+ */
+function validateArray(value, paramName, elementValidator) {
+    if (!Array.isArray(value)) {
+        throw new ValidationError(`Parameter '${paramName}' must be an array`);
+    }
+    if (elementValidator) {
+        value.forEach((item, index) => {
+            if (!elementValidator(item)) {
+                throw new ValidationError(`Element at index ${index} in '${paramName}' failed validation`);
+            }
+        });
+    }
+    return value;
+}
+/**
+ * Logging level enumeration
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["QUIET"] = 0] = "QUIET";
+    LogLevel[LogLevel["NORMAL"] = 1] = "NORMAL";
+    LogLevel[LogLevel["VERBOSE"] = 2] = "VERBOSE";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+let currentLogLevel = LogLevel.NORMAL;
+/**
+ * Set the logging level for the plugin
+ * @param level - The logging level to use
+ */
+function setLogLevel(level) {
+    currentLogLevel = level;
+}
+/**
+ * Logger utility for consistent logging across the plugin
+ */
+exports.logger = {
+    error: (message) => {
+        console.error(`[docusaurus-plugin-llms] ERROR: ${message}`);
+    },
+    warn: (message) => {
+        if (currentLogLevel >= LogLevel.NORMAL) {
+            console.warn(`[docusaurus-plugin-llms] ${message}`);
+        }
+    },
+    info: (message) => {
+        if (currentLogLevel >= LogLevel.NORMAL) {
+            console.log(`[docusaurus-plugin-llms] ${message}`);
+        }
+    },
+    verbose: (message) => {
+        if (currentLogLevel >= LogLevel.VERBOSE) {
+            console.log(`[docusaurus-plugin-llms] ${message}`);
+        }
+    }
+};
+/**
+ * Constants for path length limits
+ */
+const MAX_PATH_LENGTH_WINDOWS = 260;
+const MAX_PATH_LENGTH_UNIX = 4096;
+/**
+ * Normalizes a file path by converting all backslashes to forward slashes.
+ * This ensures consistent path handling across Windows and Unix systems.
+ *
+ * @param filePath - The file path to normalize
+ * @returns The normalized path with forward slashes
+ * @throws ValidationError if filePath is not a string
+ */
+function normalizePath(filePath) {
+    validateString(filePath, 'filePath');
+    return filePath.replace(/\\/g, '/');
+}
+/**
+ * Validates that a file path does not exceed the platform-specific maximum length
+ * @param filePath - The file path to validate
+ * @returns True if the path is within limits, false otherwise
+ */
+function validatePathLength(filePath) {
+    const maxLength = process.platform === 'win32'
+        ? MAX_PATH_LENGTH_WINDOWS
+        : MAX_PATH_LENGTH_UNIX;
+    if (filePath.length > maxLength) {
+        exports.logger.error(`Path exceeds maximum length (${maxLength}): ${filePath}`);
+        return false;
+    }
+    return true;
+}
+/**
+ * Shortens a file path by creating a hash-based filename if the path is too long
+ * @param fullPath - The full file path that may be too long
+ * @param outputDir - The output directory base path
+ * @param relativePath - The relative path from the output directory
+ * @returns A shortened path if necessary, or the original path if it's within limits
+ */
+function shortenPathIfNeeded(fullPath, outputDir, relativePath) {
+    if (validatePathLength(fullPath)) {
+        return fullPath;
+    }
+    // Create a hash of the relative path to ensure uniqueness
+    const hash = crypto.createHash('md5').update(relativePath).digest('hex').substring(0, 8);
+    const shortenedPath = path.join(outputDir, `${hash}.md`);
+    exports.logger.warn(`Path too long, using shortened path: ${shortenedPath}`);
+    exports.logger.verbose(`Original path: ${fullPath}`);
+    return shortenedPath;
+}
 /**
  * Write content to a file
  * @param filePath - Path to write the file to
@@ -62,50 +305,121 @@ async function writeFile(filePath, data) {
 /**
  * Read content from a file
  * @param filePath - Path of the file to read
- * @returns Content of the file
+ * @returns Content of the file with BOM removed if present
  */
 async function readFile(filePath) {
-    return fs.readFile(filePath, 'utf8');
+    let content = await fs.readFile(filePath, 'utf8');
+    // Remove UTF-8 BOM if present
+    // UTF-8 BOM is the character U+FEFF at the start of the file
+    if (content.charCodeAt(0) === 0xFEFF) {
+        content = content.slice(1);
+    }
+    return content;
 }
 /**
  * Check if a file should be ignored based on glob patterns
+ * Matches against both site-relative and docs-relative paths
  * @param filePath - Path to the file
- * @param baseDir - Base directory for relative paths
+ * @param baseDir - Base directory (site root) for relative paths
  * @param ignorePatterns - Glob patterns for files to ignore
+ * @param docsDir - Docs directory name (e.g., 'docs')
  * @returns Whether the file should be ignored
  */
-function shouldIgnoreFile(filePath, baseDir, ignorePatterns) {
-    if (ignorePatterns.length === 0) {
+function shouldIgnoreFile(filePath, baseDir, ignorePatterns, docsDir = 'docs') {
+    if (!isNonEmptyArray(ignorePatterns)) {
         return false;
     }
-    const relativePath = path.relative(baseDir, filePath);
-    return ignorePatterns.some(pattern => (0, minimatch_1.minimatch)(relativePath, pattern, { matchBase: true }));
+    const minimatchOptions = { matchBase: true };
+    // Get site-relative path (e.g., "docs/quickstart/file.md")
+    const siteRelativePath = normalizePath(path.relative(baseDir, filePath));
+    // Get docs-relative path (e.g., "quickstart/file.md")
+    const docsBaseDir = path.resolve(path.join(baseDir, docsDir));
+    const resolvedFile = path.resolve(filePath);
+    const docsRelativePath = resolvedFile.startsWith(docsBaseDir)
+        ? normalizePath(path.relative(docsBaseDir, resolvedFile))
+        : null;
+    return ignorePatterns.some(pattern => {
+        // Try matching against site-relative path
+        if ((0, minimatch_1.minimatch)(siteRelativePath, pattern, minimatchOptions)) {
+            return true;
+        }
+        // Try matching against docs-relative path if available
+        if (docsRelativePath && (0, minimatch_1.minimatch)(docsRelativePath, pattern, minimatchOptions)) {
+            return true;
+        }
+        return false;
+    });
 }
 /**
  * Recursively reads all Markdown files in a directory
  * @param dir - Directory to scan
- * @param baseDir - Base directory for relative paths
+ * @param baseDir - Base directory (site root) for relative paths
  * @param ignorePatterns - Glob patterns for files to ignore
+ * @param docsDir - Docs directory name (e.g., 'docs')
+ * @param warnOnIgnoredFiles - Whether to warn about ignored files
+ * @param visitedPaths - Set of already visited real paths to detect symlink loops (internal use)
  * @returns Array of file paths
  */
-async function readMarkdownFiles(dir, baseDir, ignorePatterns = []) {
+async function readMarkdownFiles(dir, baseDir, ignorePatterns = [], docsDir = 'docs', warnOnIgnoredFiles = false, visitedPaths = new Set()) {
+    // Get real path to detect symlink loops
+    let realPath;
+    try {
+        realPath = await fs.realpath(dir);
+    }
+    catch (error) {
+        exports.logger.warn(`Failed to resolve real path for ${dir}: ${getErrorMessage(error)}`);
+        return [];
+    }
+    // Check if we've already visited this path (symlink loop detection)
+    if (visitedPaths.has(realPath)) {
+        exports.logger.warn(`Skipping already visited path (possible symlink loop): ${dir}`);
+        return [];
+    }
+    // Add to visited paths
+    visitedPaths.add(realPath);
     const files = [];
     const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
         const fullPath = path.join(dir, entry.name);
-        if (shouldIgnoreFile(fullPath, baseDir, ignorePatterns)) {
+        if (shouldIgnoreFile(fullPath, baseDir, ignorePatterns, docsDir)) {
             continue;
         }
-        if (entry.isDirectory()) {
-            const subDirFiles = await readMarkdownFiles(fullPath, baseDir, ignorePatterns);
+        // Handle both regular directories and symlinked directories
+        let isDir = entry.isDirectory();
+        if (!isDir && entry.isSymbolicLink()) {
+            // Check if symlink points to a directory
+            try {
+                const stats = await fs.stat(fullPath);
+                isDir = stats.isDirectory();
+            }
+            catch (error) {
+                // Broken symlink, warn and skip it
+                exports.logger.warn(`Skipping broken symlink: ${fullPath}`);
+                continue;
+            }
+        }
+        if (isDir) {
+            const subDirFiles = await readMarkdownFiles(fullPath, baseDir, ignorePatterns, docsDir, warnOnIgnoredFiles, visitedPaths);
             files.push(...subDirFiles);
         }
+        else if (!entry.name.includes('.')) {
+            // File without extension
+            if (warnOnIgnoredFiles) {
+                exports.logger.warn(`Ignoring file without extension: ${fullPath}`);
+            }
+        }
         else if (entry.name.endsWith('.md') || entry.name.endsWith('.mdx')) {
             // Skip partial files (those starting with underscore)
             if (!entry.name.startsWith('_')) {
                 files.push(fullPath);
             }
         }
+        else {
+            // Other extension
+            if (warnOnIgnoredFiles) {
+                exports.logger.warn(`Ignoring file with unsupported extension: ${fullPath}`);
+            }
+        }
     }
     return files;
 }
@@ -117,35 +431,46 @@ async function readMarkdownFiles(dir, baseDir, ignorePatterns = []) {
  * @returns Extracted title
  */
 function extractTitle(data, content, filePath) {
-    // First try frontmatter
-    if (data.title) {
+    // First try frontmatter (check for valid non-empty string)
+    if (isNonEmptyString(data.title)) {
         return data.title;
     }
     // Then try first heading
     const headingMatch = content.match(/^#\s+(.*)/m);
-    if (headingMatch) {
+    if (isNonEmptyString(headingMatch?.[1])) {
         return headingMatch[1].trim();
     }
     // Finally use filename
     return path.basename(filePath, path.extname(filePath))
         .replace(/-/g, ' ')
-        .replace(/\b\w/g, c => c.toUpperCase());
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+/**
+ * Escape special regex characters in a string
+ * @param str - String to escape
+ * @returns Escaped string safe for use in regex
+ */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /**
  * Resolve and inline partial imports in markdown content
  * @param content - The markdown content with import statements
  * @param filePath - The path of the file containing the imports
+ * @param importChain - Set of file paths in the current import chain (for circular dependency detection)
  * @returns Content with partials resolved
  */
-async function resolvePartialImports(content, filePath) {
+async function resolvePartialImports(content, filePath, importChain = new Set()) {
     let resolved = content;
     // Match import statements for partials and JSX usage
     // Pattern 1: import PartialName from './_partial.mdx'
     // Pattern 2: import { PartialName } from './_partial.mdx'
-    const importRegex = /^\s*import\s+(?:(\w+)|{\s*(\w+)\s*})\s+from\s+['"]([^'"]+_[^'"]+\.mdx?)['"];?\s*$/gm;
+    // Create a fresh regex for each invocation to avoid lastIndex state leakage
+    const createImportRegex = () => /^\s*import\s+(?:(\w+)|{\s*(\w+)\s*})\s+from\s+['"]([^'"]+_[^'"]+\.mdx?)['"];?\s*$/gm;
     const imports = new Map();
     // First pass: collect all imports
     let match;
+    const importRegex = createImportRegex();
     while ((match = importRegex.exec(content)) !== null) {
         const componentName = match[1] || match[2];
         const importPath = match[3];
@@ -160,20 +485,52 @@ async function resolvePartialImports(content, filePath) {
             // Resolve the partial file path relative to the current file
             const dir = path.dirname(filePath);
             const partialPath = path.resolve(dir, importPath);
+            // Check for circular import
+            if (importChain.has(partialPath)) {
+                const chain = Array.from(importChain).join(' -> ');
+                exports.logger.error(`Circular import detected: ${chain} -> ${partialPath}`);
+                // Escape special regex characters in component name and import path
+                const escapedComponentName = escapeRegex(componentName);
+                const escapedImportPath = escapeRegex(importPath);
+                // Remove the import statement to prevent infinite recursion
+                resolved = resolved.replace(new RegExp(`^\\s*import\\s+(?:${escapedComponentName}|{\\s*${escapedComponentName}\\s*})\\s+from\\s+['"]${escapedImportPath}['"];?\\s*$`, 'gm'), '');
+                // Remove JSX usage of this component
+                const jsxRegex = new RegExp(`<${escapedComponentName}(?:\\s+[^>]*)?\\s*\\/?>(?:[\\s\\S]*?<\\/${escapedComponentName}>)?`, 'gm');
+                resolved = resolved.replace(jsxRegex, '');
+                continue;
+            }
+            // Add to chain before recursive call
+            const newChain = new Set(importChain);
+            newChain.add(partialPath);
             // Read the partial file
-            const partialContent = await readFile(partialPath);
+            let partialContent = await readFile(partialPath);
             const { content: partialMarkdown } = (0, gray_matter_1.default)(partialContent);
+            // Recursively resolve imports in the partial with the updated chain
+            const resolvedPartial = await resolvePartialImports(partialMarkdown, partialPath, newChain);
+            // Escape special regex characters in component name and import path
+            const escapedComponentName = escapeRegex(componentName);
+            const escapedImportPath = escapeRegex(importPath);
             // Remove the import statement
-            resolved = resolved.replace(new RegExp(`^\\s*import\\s+(?:${componentName}|{\\s*${componentName}\\s*})\\s+from\\s+['"]${importPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"];?\\s*$`, 'gm'), '');
+            resolved = resolved.replace(new RegExp(`^\\s*import\\s+(?:${escapedComponentName}|{\\s*${escapedComponentName}\\s*})\\s+from\\s+['"]${escapedImportPath}['"];?\\s*$`, 'gm'), '');
             // Replace JSX usage with the partial content
             // Handle both self-closing tags and tags with content
             // <PartialName /> or <PartialName></PartialName> or <PartialName>...</PartialName>
-            const jsxRegex = new RegExp(`<${componentName}\\s*(?:[^>]*?)(?:/>|>[^<]*</${componentName}>)`, 'g');
-            resolved = resolved.replace(jsxRegex, partialMarkdown.trim());
+            const jsxRegex = new RegExp(`<${escapedComponentName}\\s*(?:[^>]*?)(?:/>|>[^<]*</${escapedComponentName}>)`, 'g');
+            resolved = resolved.replace(jsxRegex, resolvedPartial.trim());
         }
         catch (error) {
-            console.warn(`Failed to resolve partial import "${importPath}" in ${filePath}: ${error}`);
-            // Leave the import and usage as-is if we can't resolve it
+            exports.logger.warn(`Failed to resolve partial import from ${importPath}: ${getErrorMessage(error)}`);
+            // Remove both the import statement AND the JSX usage even if partial can't be resolved
+            // This prevents leaving broken references in the output
+            // Escape special regex characters in component name and import path
+            const escapedComponentName = escapeRegex(componentName);
+            const escapedImportPath = escapeRegex(importPath);
+            // Remove the import statement
+            resolved = resolved.replace(new RegExp(`^\\s*import\\s+(?:${escapedComponentName}|{\\s*${escapedComponentName}\\s*})\\s+from\\s+['"]${escapedImportPath}['"];?\\s*$`, 'gm'), '');
+            // Remove JSX usage of this component
+            // Handle both self-closing tags (<Component />) and regular tags with content (<Component>...</Component>)
+            const jsxRegex = new RegExp(`<${escapedComponentName}(?:\\s+[^>]*)?\\s*\\/?>(?:[\\s\\S]*?<\\/${escapedComponentName}>)?`, 'gm');
+            resolved = resolved.replace(jsxRegex, '');
         }
     }
     return resolved;
@@ -255,16 +612,18 @@ function cleanMarkdownContent(content, excludeImports = false, removeDuplicateHe
  * @returns Transformed URL path
  */
 function applyPathTransformations(urlPath, pathTransformation) {
-    if (!pathTransformation) {
+    if (!isDefined(pathTransformation)) {
         return urlPath;
     }
     let transformedPath = urlPath;
     // Remove ignored path segments
-    if (pathTransformation.ignorePaths?.length) {
+    if (isNonEmptyArray(pathTransformation.ignorePaths)) {
         for (const ignorePath of pathTransformation.ignorePaths) {
             // Create a regex that matches the ignore path at the beginning, middle, or end of the path
             // We use word boundaries to ensure we match complete path segments
-            const ignoreRegex = new RegExp(`(^|/)(${ignorePath})(/|$)`, 'g');
+            // Escape special regex characters in ignorePath to prevent regex injection
+            const escapedIgnorePath = ignorePath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const ignoreRegex = new RegExp(`(^|/)(${escapedIgnorePath})(/|$)`, 'g');
             transformedPath = transformedPath.replace(ignoreRegex, '$1$3');
         }
         // Clean up any double slashes that might have been created
@@ -273,7 +632,7 @@ function applyPathTransformations(urlPath, pathTransformation) {
         transformedPath = transformedPath.replace(/^\//, '');
     }
     // Add path segments if they're not already present
-    if (pathTransformation.addPaths?.length) {
+    if (isNonEmptyArray(pathTransformation.addPaths)) {
         // Process in reverse order to maintain the specified order in the final path
         // This is because each path is prepended to the front
         const pathsToAdd = [...pathTransformation.addPaths].reverse();
@@ -286,3 +645,97 @@ function applyPathTransformations(urlPath, pathTransformation) {
     }
     return transformedPath;
 }
+/**
+ * Sanitize a string to create a safe filename
+ * @param input - Input string (typically a title)
+ * @param fallback - Fallback string if input becomes empty after sanitization
+ * @returns Sanitized filename (without extension)
+ * @throws ValidationError if input or fallback are not strings
+ */
+function sanitizeForFilename(input, fallback = 'untitled', options = {}) {
+    // Validate input parameters
+    validateString(input, 'input');
+    validateString(fallback, 'fallback', { minLength: 1 });
+    if (!isNonEmptyString(input))
+        return fallback;
+    const { preserveUnicode = true, preserveCase = false } = options;
+    let sanitized = preserveCase ? input : input.toLowerCase();
+    if (preserveUnicode) {
+        // Only remove filesystem-unsafe characters: / \ : * ? " < > |
+        // Keep underscores, dots (except at start), hyphens, and unicode
+        // Also replace spaces with dashes for better filesystem compatibility
+        sanitized = sanitized.replace(/[/\\:*?"<>|\s]+/g, '-');
+    }
+    else {
+        // Allow alphanumeric, underscores, hyphens, dots
+        sanitized = sanitized.replace(/[^a-z0-9_.-]+/g, '-');
+    }
+    // Remove leading dots (hidden files on Unix)
+    sanitized = sanitized.replace(/^\.+/, '');
+    // Clean up multiple dashes and trim
+    sanitized = sanitized
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return sanitized || fallback;
+}
+/**
+ * Ensure a unique identifier from a set of used identifiers
+ * @param baseIdentifier - Base identifier to make unique
+ * @param usedIdentifiers - Set of already used identifiers
+ * @param suffix - Suffix pattern (default: number in parentheses)
+ * @returns Unique identifier
+ * @throws ValidationError if baseIdentifier is not a string or usedIdentifiers is not a Set
+ */
+function ensureUniqueIdentifier(baseIdentifier, usedIdentifiers, suffix = (counter) => `(${counter})`) {
+    // Validate input parameters
+    validateString(baseIdentifier, 'baseIdentifier', { minLength: 1 });
+    validateRequired(usedIdentifiers, 'usedIdentifiers');
+    if (!(usedIdentifiers instanceof Set)) {
+        throw new ValidationError(`Parameter 'usedIdentifiers' must be a Set`);
+    }
+    const MAX_ITERATIONS = 10000;
+    let uniqueIdentifier = baseIdentifier;
+    let counter = 1;
+    let iterations = 0;
+    while (usedIdentifiers.has(uniqueIdentifier.toLowerCase())) {
+        counter++;
+        uniqueIdentifier = `${baseIdentifier}${suffix(counter, baseIdentifier)}`;
+        iterations++;
+        if (iterations >= MAX_ITERATIONS) {
+            // Fallback to timestamp-based unique identifier
+            const timestamp = Date.now().toString(36);
+            const random = Math.random().toString(36).substring(2, 8);
+            uniqueIdentifier = `${baseIdentifier}-${timestamp}-${random}`;
+            exports.logger.warn(`Maximum iterations reached for unique identifier. Using fallback: ${uniqueIdentifier}`);
+            break;
+        }
+    }
+    usedIdentifiers.add(uniqueIdentifier.toLowerCase());
+    return uniqueIdentifier;
+}
+/**
+ * Create standardized markdown content template
+ * @param title - Document title
+ * @param description - Document description
+ * @param content - Document content
+ * @param includeMetadata - Whether to include description metadata
+ * @param frontMatter - Optional frontmatter to include at the top
+ * @returns Formatted markdown content
+ */
+function createMarkdownContent(title, description = '', content = '', includeMetadata = true, frontMatter) {
+    let result = '';
+    // Add frontmatter if provided
+    if (isDefined(frontMatter) && Object.keys(frontMatter).length > 0) {
+        result += '---\n';
+        result += YAML.stringify(frontMatter, {
+            lineWidth: 0,
+            defaultStringType: 'QUOTE_DOUBLE',
+            defaultKeyType: 'PLAIN'
+        });
+        result += '---\n\n';
+    }
+    const descriptionLine = includeMetadata && description ? `\n\n> ${description}\n` : '\n';
+    result += `# ${title}${descriptionLine}
+${content}`.trim() + '\n';
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-llms",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Docusaurus plugin for generating LLM-friendly documentation following the llmstxt.org standard",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -9,7 +9,7 @@
     "watch": "tsc --watch",
     "cleanup": "node cleanup.js",
     "prepublishOnly": "npm run build && npm run cleanup",
-    "test:unit": "node tests/test-path-transforms.js && node tests/test-header-deduplication.js && node tests/test-import-removal.js && node tests/test-partials.js && node tests/test-root-content.js",
+    "test:unit": "node tests/test-plugin-options-validation.js && node tests/test-plugin-validation-integration.js && node tests/test-regex-escaping.js && node tests/test-baseurl-handling.js && node tests/test-path-transforms.js && node tests/test-header-deduplication.js && node tests/test-import-removal.js && node tests/test-partials.js && node tests/test-missing-partials.js && node tests/test-circular-imports.js && node tests/test-root-content.js && node tests/test-filenames.js && node tests/test-url-encoding.js && node tests/test-nested-paths.js && node tests/test-filename-sanitization.js && node tests/test-yaml-encoding.js && node tests/test-url-error-handling.js && node tests/test-regex-lastindex.js && node tests/test-whitespace-paths.js && node tests/test-unique-identifier-iteration-limit.js && node tests/test-error-handling.js && node tests/test-file-io-error-handling.js && node tests/test-parallel-processing.js && node tests/test-path-length-validation.js && node tests/test-bom-handling.js && node tests/test-batch-processing.js && node tests/test-input-validation.js",
     "test:integration": "node tests/test-path-transformation.js",
     "test": "npm run build && npm run test:unit && npm run test:integration"
   },
@@ -38,13 +38,15 @@
   "license": "MIT",
   "dependencies": {
     "gray-matter": "^4.0.3",
-    "minimatch": "^9.0.3"
+    "minimatch": "^9.0.3",
+    "yaml": "^2.8.1"
   },
   "peerDependencies": {
     "@docusaurus/core": "^3.0.0"
   },
   "devDependencies": {
     "@docusaurus/types": "^3.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/minimatch": "^5.1.2",
     "@types/node": "^20.6.0",
     "typescript": "^5.2.2"