docusaurus-plugin-llms 0.2.2 → 0.3.0

package/src/index.ts

@@ -10,13 +10,190 @@
 
 import * as path from 'path';
 import type { LoadContext, Plugin, Props, RouteConfig } from '@docusaurus/types';
-import { PluginOptions, PluginContext } from './types';
+import { PluginOptions, PluginContext, CustomLLMFile } from './types';
 import { collectDocFiles, generateStandardLLMFiles, generateCustomLLMFiles } from './generator';
+import { setLogLevel, LogLevel, logger, getErrorMessage, isDefined, isNonEmptyString, isNonEmptyArray } from './utils';
+
+/**
+ * Validates plugin options to ensure they conform to expected types and constraints
+ * @param options - Plugin options to validate
+ * @throws Error if any option is invalid
+ */
+function validatePluginOptions(options: PluginOptions): void {
+  // Validate includeOrder
+  if (options.includeOrder !== undefined) {
+    if (!Array.isArray(options.includeOrder)) {
+      throw new Error('includeOrder must be an array');
+    }
+    if (!options.includeOrder.every(item => typeof item === 'string')) {
+      throw new Error('includeOrder must contain only strings');
+    }
+  }
+
+  // Validate ignoreFiles
+  if (options.ignoreFiles !== undefined) {
+    if (!Array.isArray(options.ignoreFiles)) {
+      throw new Error('ignoreFiles must be an array');
+    }
+    if (!options.ignoreFiles.every(item => typeof item === 'string')) {
+      throw new Error('ignoreFiles must contain only strings');
+    }
+  }
+
+  // Validate pathTransformation
+  if (isDefined(options.pathTransformation)) {
+    if (typeof options.pathTransformation !== 'object') {
+      throw new Error('pathTransformation must be an object');
+    }
+
+    const { ignorePaths, addPaths } = options.pathTransformation;
+
+    if (ignorePaths !== undefined) {
+      if (!Array.isArray(ignorePaths)) {
+        throw new Error('pathTransformation.ignorePaths must be an array');
+      }
+      if (!ignorePaths.every(item => typeof item === 'string')) {
+        throw new Error('pathTransformation.ignorePaths must contain only strings');
+      }
+    }
+
+    if (addPaths !== undefined) {
+      if (!Array.isArray(addPaths)) {
+        throw new Error('pathTransformation.addPaths must be an array');
+      }
+      if (!addPaths.every(item => typeof item === 'string')) {
+        throw new Error('pathTransformation.addPaths must contain only strings');
+      }
+    }
+  }
+
+  // Validate boolean options
+  const booleanOptions = [
+    'generateLLMsTxt',
+    'generateLLMsFullTxt',
+    'includeBlog',
+    'includeUnmatchedLast',
+    'excludeImports',
+    'removeDuplicateHeadings',
+    'generateMarkdownFiles',
+    'preserveDirectoryStructure'
+  ] as const;
+
+  for (const option of booleanOptions) {
+    if (options[option] !== undefined && typeof options[option] !== 'boolean') {
+      throw new Error(`${option} must be a boolean`);
+    }
+  }
+
+  // Validate string options
+  const stringOptions = [
+    'docsDir',
+    'title',
+    'description',
+    'llmsTxtFilename',
+    'llmsFullTxtFilename',
+    'version',
+    'rootContent',
+    'fullRootContent'
+  ] as const;
+
+  for (const option of stringOptions) {
+    if (options[option] !== undefined && typeof options[option] !== 'string') {
+      throw new Error(`${option} must be a string`);
+    }
+  }
+
+  // Validate keepFrontMatter
+  if (options.keepFrontMatter !== undefined) {
+    if (!Array.isArray(options.keepFrontMatter)) {
+      throw new Error('keepFrontMatter must be an array');
+    }
+    if (!options.keepFrontMatter.every(item => typeof item === 'string')) {
+      throw new Error('keepFrontMatter must contain only strings');
+    }
+  }
+
+  // Validate logLevel
+  if (options.logLevel !== undefined) {
+    const validLogLevels = ['quiet', 'normal', 'verbose'];
+    if (!validLogLevels.includes(options.logLevel)) {
+      throw new Error(`logLevel must be one of: ${validLogLevels.join(', ')}`);
+    }
+  }
+
+  // Validate customLLMFiles
+  if (options.customLLMFiles !== undefined) {
+    if (!Array.isArray(options.customLLMFiles)) {
+      throw new Error('customLLMFiles must be an array');
+    }
+
+    options.customLLMFiles.forEach((file, index) => {
+      if (!isDefined(file) || typeof file !== 'object') {
+        throw new Error(`customLLMFiles[${index}] must be an object`);
+      }
+
+      // Required fields
+      if (!isNonEmptyString(file.filename)) {
+        throw new Error(`customLLMFiles[${index}].filename must be a non-empty string`);
+      }
+
+      if (!isNonEmptyArray(file.includePatterns)) {
+        throw new Error(`customLLMFiles[${index}].includePatterns must be a non-empty array`);
+      }
+      if (!file.includePatterns.every(item => typeof item === 'string')) {
+        throw new Error(`customLLMFiles[${index}].includePatterns must contain only strings`);
+      }
+
+      if (typeof file.fullContent !== 'boolean') {
+        throw new Error(`customLLMFiles[${index}].fullContent must be a boolean`);
+      }
+
+      // Optional fields
+      if (isDefined(file.title) && !isNonEmptyString(file.title)) {
+        throw new Error(`customLLMFiles[${index}].title must be a non-empty string`);
+      }
+
+      if (isDefined(file.description) && !isNonEmptyString(file.description)) {
+        throw new Error(`customLLMFiles[${index}].description must be a non-empty string`);
+      }
+
+      if (file.ignorePatterns !== undefined) {
+        if (!Array.isArray(file.ignorePatterns)) {
+          throw new Error(`customLLMFiles[${index}].ignorePatterns must be an array`);
+        }
+        if (!file.ignorePatterns.every(item => typeof item === 'string')) {
+          throw new Error(`customLLMFiles[${index}].ignorePatterns must contain only strings`);
+        }
+      }
+
+      if (file.orderPatterns !== undefined) {
+        if (!Array.isArray(file.orderPatterns)) {
+          throw new Error(`customLLMFiles[${index}].orderPatterns must be an array`);
+        }
+        if (!file.orderPatterns.every(item => typeof item === 'string')) {
+          throw new Error(`customLLMFiles[${index}].orderPatterns must contain only strings`);
+        }
+      }
+
+      if (file.includeUnmatchedLast !== undefined && typeof file.includeUnmatchedLast !== 'boolean') {
+        throw new Error(`customLLMFiles[${index}].includeUnmatchedLast must be a boolean`);
+      }
+
+      if (isDefined(file.version) && !isNonEmptyString(file.version)) {
+        throw new Error(`customLLMFiles[${index}].version must be a non-empty string`);
+      }
+
+      if (isDefined(file.rootContent) && !isNonEmptyString(file.rootContent)) {
+        throw new Error(`customLLMFiles[${index}].rootContent must be a non-empty string`);
+      }
+    });
+  }
+}
 
 /**
  * A Docusaurus plugin to generate LLM-friendly documentation following
  * the llmstxt.org standard
- * 
+ *
  * @param context - Docusaurus context
  * @param options - Plugin options
  * @returns Plugin object
@@ -25,6 +202,8 @@ export default function docusaurusPluginLLMs(
   context: LoadContext,
   options: PluginOptions = {}
 ): Plugin<void> {
+  // Validate options before processing
+  validatePluginOptions(options);
   // Set default options
   const {
     generateLLMsTxt = true,
@@ -46,20 +225,29 @@ export default function docusaurusPluginLLMs(
     keepFrontMatter = [],
     rootContent,
     fullRootContent,
+    logLevel = 'normal',
   } = options;
 
+  // Initialize logging level
+  const logLevelMap = {
+    quiet: LogLevel.QUIET,
+    normal: LogLevel.NORMAL,
+    verbose: LogLevel.VERBOSE,
+  };
+  setLogLevel(logLevelMap[logLevel] || LogLevel.NORMAL);
+
   const {
     siteDir,
     siteConfig,
     outDir,
   } = context;
   
-  // Build the site URL with proper trailing slash
-  const siteUrl = siteConfig.url + (
-    siteConfig.baseUrl.endsWith('/') 
-      ? siteConfig.baseUrl.slice(0, -1) 
-      : siteConfig.baseUrl || ''
-  );
+  // Normalize baseUrl: remove trailing slash unless it's root '/'
+  let normalizedBaseUrl = siteConfig.baseUrl || '/';
+  if (normalizedBaseUrl !== '/' && normalizedBaseUrl.endsWith('/')) {
+    normalizedBaseUrl = normalizedBaseUrl.slice(0, -1);
+  }
+  const siteUrl = siteConfig.url + normalizedBaseUrl;
   
   // Create a plugin context object with processed options
   const pluginContext: PluginContext = {
@@ -99,7 +287,7 @@ export default function docusaurusPluginLLMs(
      * Generates LLM-friendly documentation files after the build is complete
      */
     async postBuild(props?: Props & { content: unknown }): Promise<void> {
-      console.log('Generating LLM-friendly documentation...');
+      logger.info('Generating LLM-friendly documentation...');
      
       try {
         let enhancedContext = pluginContext;
@@ -140,8 +328,8 @@ export default function docusaurusPluginLLMs(
         const allDocFiles = await collectDocFiles(enhancedContext);
         
         // Skip further processing if no documents were found
-        if (allDocFiles.length === 0) {
-          console.warn('No documents found to process.');
+        if (!isNonEmptyArray(allDocFiles)) {
+          logger.warn('No documents found to process. Skipping.');
           return;
         }
         
@@ -152,9 +340,9 @@ export default function docusaurusPluginLLMs(
         await generateCustomLLMFiles(enhancedContext, allDocFiles);
         
         // Output overall statistics
-        console.log(`Stats: ${allDocFiles.length} total available documents processed`);
-      } catch (err: any) {
-        console.error('Error generating LLM documentation:', err);
+        logger.info(`Stats: ${allDocFiles.length} total available documents processed`);
+      } catch (err: unknown) {
+        logger.error(`Error generating LLM documentation: ${getErrorMessage(err)}`);
       }
     },
   };

package/src/null-handling-guide.ts

@@ -0,0 +1,321 @@
+/**
+ * NULL AND UNDEFINED HANDLING GUIDE
+ *
+ * This file documents the standardized patterns for null/undefined handling
+ * across the docusaurus-plugin-llms codebase.
+ *
+ * PRINCIPLES:
+ * 1. Be explicit about null/undefined checks - avoid loose truthy checks
+ * 2. Use optional chaining for safe property access on optional values
+ * 3. Validate required parameters early with explicit checks
+ * 4. Distinguish between "missing" (undefined/null) and "falsy" (0, '', false)
+ *
+ * PATTERNS:
+ */
+
+// ============================================================================
+// PATTERN 1: Checking for null OR undefined (most common)
+// ============================================================================
+
+/**
+ * Use when you need to check if a value exists (not null and not undefined).
+ * This is the most common check for optional parameters or properties.
+ */
+function checkIfDefined_GOOD(value: string | undefined | null): void {
+  if (value !== undefined && value !== null) {
+    // Value is defined and not null
+    console.log(value.toUpperCase());
+  }
+}
+
+/**
+ * AVOID: Loose truthy check - this catches 0, '', false, NaN
+ */
+function checkIfDefined_BAD(value: string | undefined | null): void {
+  if (value) {
+    // PROBLEM: This rejects empty strings, 0, false, etc.
+    console.log(value.toUpperCase());
+  }
+}
+
+// ============================================================================
+// PATTERN 2: Optional chaining for safe property access
+// ============================================================================
+
+/**
+ * Use optional chaining when accessing properties on values that might be
+ * null or undefined. This avoids TypeError exceptions.
+ */
+function safePropertyAccess_GOOD(obj: { prop?: string } | undefined): void {
+  const value = obj?.prop;
+  if (value !== undefined && value !== null) {
+    console.log(value);
+  }
+}
+
+/**
+ * AVOID: Manual null checks before property access (verbose)
+ */
+function safePropertyAccess_BAD(obj: { prop?: string } | undefined): void {
+  if (obj && obj.prop) {
+    // Verbose and misses the case where prop is explicitly false/0
+    console.log(obj.prop);
+  }
+}
+
+// ============================================================================
+// PATTERN 3: Type-specific validation with explicit null checks
+// ============================================================================
+
+/**
+ * Use when validating optional parameters that must be a specific type if provided.
+ * Check both that the value is defined AND that it has the correct type.
+ */
+function validateOptionalString_GOOD(value: unknown): void {
+  if (value !== undefined && value !== null) {
+    if (typeof value !== 'string') {
+      throw new Error('Value must be a string if provided');
+    }
+    // Now we know value is a string
+    console.log(value.trim());
+  }
+}
+
+/**
+ * Can be combined into a single check when appropriate
+ */
+function validateOptionalString_GOOD_COMPACT(value: unknown): void {
+  if (value !== undefined && typeof value !== 'string') {
+    throw new Error('Value must be a string if provided');
+  }
+}
+
+// ============================================================================
+// PATTERN 4: Non-empty string validation
+// ============================================================================
+
+/**
+ * Use when you need a string that is not only defined but also not empty.
+ * This is common for required fields that have been parsed from user input.
+ */
+function validateNonEmptyString_GOOD(value: string | undefined | null): void {
+  if (typeof value === 'string' && value.trim() !== '') {
+    // Value is a non-empty string
+    console.log(value);
+  } else {
+    throw new Error('Value must be a non-empty string');
+  }
+}
+
+/**
+ * AVOID: Loose check that doesn't validate the type
+ */
+function validateNonEmptyString_BAD(value: string | undefined | null): void {
+  if (value && value.trim()) {
+    // PROBLEM: Assumes value has .trim() method
+    console.log(value);
+  }
+}
+
+// ============================================================================
+// PATTERN 5: Array validation
+// ============================================================================
+
+/**
+ * Use explicit checks for arrays, checking both existence and array type.
+ */
+function validateOptionalArray_GOOD(value: unknown): void {
+  if (value !== undefined && value !== null) {
+    if (!Array.isArray(value)) {
+      throw new Error('Value must be an array if provided');
+    }
+    // Now we know value is an array
+    console.log(value.length);
+  }
+}
+
+/**
+ * Check for non-empty arrays using optional chaining and length check
+ */
+function checkNonEmptyArray_GOOD(value: string[] | undefined): void {
+  if (value?.length) {
+    // Array exists and has at least one element
+    console.log(value[0]);
+  }
+}
+
+/**
+ * AVOID: Loose truthy check on arrays - empty arrays are truthy!
+ */
+function checkNonEmptyArray_BAD(value: string[] | undefined): void {
+  if (value && value.length > 0) {
+    // Works but is verbose compared to optional chaining
+    console.log(value[0]);
+  }
+}
+
+// ============================================================================
+// PATTERN 6: Object validation
+// ============================================================================
+
+/**
+ * Use explicit null check for objects since typeof null === 'object'
+ */
+function validateOptionalObject_GOOD(value: unknown): void {
+  if (value !== undefined && value !== null) {
+    if (typeof value !== 'object') {
+      throw new Error('Value must be an object if provided');
+    }
+    // Now we know value is an object (not null)
+  }
+}
+
+/**
+ * CRITICAL: Always check for null when using typeof to validate objects
+ */
+function validateOptionalObject_BAD(value: unknown): void {
+  if (value !== undefined) {
+    if (typeof value !== 'object') {
+      // PROBLEM: typeof null === 'object', so null passes this check!
+      throw new Error('Value must be an object if provided');
+    }
+  }
+}
+
+// ============================================================================
+// PATTERN 7: Boolean validation
+// ============================================================================
+
+/**
+ * Use explicit type check for booleans, not truthiness.
+ * This distinguishes between missing (undefined) and false.
+ */
+function validateOptionalBoolean_GOOD(value: unknown): void {
+  if (value !== undefined && value !== null && typeof value !== 'boolean') {
+    throw new Error('Value must be a boolean if provided');
+  }
+  // Can safely use value as boolean | undefined | null
+}
+
+/**
+ * When you need to treat undefined as a specific boolean value
+ */
+function withDefaultBoolean_GOOD(value: boolean | undefined): boolean {
+  // Explicit: undefined becomes true, false stays false
+  return value !== false;
+}
+
+/**
+ * AVOID: Coercing to boolean implicitly
+ */
+function withDefaultBoolean_BAD(value: boolean | undefined): boolean {
+  // PROBLEM: value = 0 or '' would also become false
+  return !!value;
+}
+
+// ============================================================================
+// PATTERN 8: Default values with nullish coalescing
+// ============================================================================
+
+/**
+ * Use nullish coalescing (??) for default values.
+ * This only replaces null/undefined, not other falsy values.
+ */
+function withDefault_GOOD(value: string | undefined | null): string {
+  return value ?? 'default';
+}
+
+/**
+ * AVOID: Logical OR for defaults - it replaces ALL falsy values
+ */
+function withDefault_BAD(value: string | undefined | null): string {
+  // PROBLEM: value = '' or 0 would also use the default
+  return value || 'default';
+}
+
+// ============================================================================
+// PATTERN 9: Early validation for required parameters
+// ============================================================================
+
+/**
+ * Validate required parameters at function entry with explicit checks.
+ */
+function requireParameter_GOOD(value: string | undefined | null): void {
+  if (value === undefined || value === null) {
+    throw new Error('Parameter is required');
+  }
+  // Now TypeScript knows value is string
+  console.log(value.toUpperCase());
+}
+
+/**
+ * AVOID: Loose validation that doesn't distinguish null/undefined from falsy
+ */
+function requireParameter_BAD(value: string | undefined | null): void {
+  if (!value) {
+    // PROBLEM: Also throws for empty string, 0, false
+    throw new Error('Parameter is required');
+  }
+  console.log(value.toUpperCase());
+}
+
+// ============================================================================
+// PATTERN 10: Converting truthy checks to explicit checks
+// ============================================================================
+
+/**
+ * When checking if a value should be used (but preserving falsy values)
+ */
+function explicitCheck_GOOD(value: string | number | boolean | undefined | null): void {
+  if (value !== undefined && value !== null) {
+    // Now can use value = 0, '', false safely
+    console.log(value);
+  }
+}
+
+/**
+ * AVOID: Truthy check when falsy values are valid
+ */
+function explicitCheck_BAD(value: string | number | boolean | undefined | null): void {
+  if (value) {
+    // PROBLEM: Rejects value = 0, '', false
+    console.log(value);
+  }
+}
+
+// ============================================================================
+// SUMMARY
+// ============================================================================
+
+/**
+ * QUICK REFERENCE:
+ *
+ * 1. Optional parameter check:
+ *    if (value !== undefined && value !== null) { ... }
+ *
+ * 2. Safe property access:
+ *    const prop = obj?.property
+ *
+ * 3. Type validation with null check:
+ *    if (typeof value !== 'object' || value === null) { throw ... }
+ *
+ * 4. Non-empty string:
+ *    if (typeof value === 'string' && value.trim() !== '') { ... }
+ *
+ * 5. Non-empty array:
+ *    if (value?.length) { ... }
+ *
+ * 6. Default values:
+ *    const result = value ?? defaultValue
+ *
+ * 7. Boolean with default:
+ *    const enabled = value !== false  // undefined and null become true
+ *
+ * 8. Required parameter:
+ *    if (value === undefined || value === null) { throw ... }
+ *
+ * AVOID:
+ * - if (value) { ... }  // Too loose, catches falsy values
+ * - value || defaultValue  // Replaces ALL falsy values, not just null/undefined
+ * - !value  // Too loose for validation
+ */