sfcc-dev-mcp 1.0.15 → 1.0.19

package/src/clients/docs/documentation-scanner.ts

@@ -28,7 +28,7 @@ export class DocumentationScanner {
   /**
    * Check if a directory name represents an SFCC-specific directory
    * SFCC directories include dw_ prefixed namespaces and TopLevel
-   * Excludes best-practices and sfra directories
+    * Excludes sfra and isml directories
    */
   private isSFCCDirectory(directoryName: string): boolean {
     // Include dw_ prefixed directories (SFCC namespaces)
@@ -41,13 +41,13 @@ export class DocumentationScanner {
       return true;
     }
 
-    // Exclude best-practices directory (handled by best practices tools)
-    if (directoryName === 'best-practices') {
+    // Exclude sfra directory (handled by SFRA tools)
+    if (directoryName === 'sfra') {
       return false;
     }
 
-    // Exclude sfra directory (handled by SFRA tools)
-    if (directoryName === 'sfra') {
+    // Exclude the isml directory (ISML templates, not SFCC classes)
+    if (directoryName === 'isml') {
       return false;
     }
 
@@ -169,65 +169,81 @@ export class DocumentationScanner {
     }
   }
 
+  // Batch size for parallel file reads (avoid file descriptor exhaustion)
+  private static readonly PARALLEL_BATCH_SIZE = 50;
+
   /**
    * Scan a single package directory for documentation files
+   * Uses parallel batch processing for improved performance
    */
   private async scanPackageDirectory(
     packageName: string,
     packagePath: string,
     docsPath: string,
   ): Promise<SFCCClassInfo[]> {
-    const classInfos: SFCCClassInfo[] = [];
-
     try {
       const files = await fs.readdir(packagePath);
 
-      for (const file of files) {
-        // Validate file name type and basic content before processing
+      // Filter to only markdown files with valid names
+      const mdFiles = files.filter(file => {
         if (!file || typeof file !== 'string') {
           this.logger.warn(`Warning: Invalid file name type: ${file}`);
-          continue;
+          return false;
         }
-
-        if (file.endsWith('.md')) {
-          const classInfo = await this.readDocumentationFile(file, packagePath, packageName, docsPath);
-          if (classInfo) {
-            classInfos.push(classInfo);
+        return file.endsWith('.md');
+      });
+
+      // Process files in parallel batches to avoid fd exhaustion
+      const classInfos: SFCCClassInfo[] = [];
+      for (let i = 0; i < mdFiles.length; i += DocumentationScanner.PARALLEL_BATCH_SIZE) {
+        const batch = mdFiles.slice(i, i + DocumentationScanner.PARALLEL_BATCH_SIZE);
+        const results = await Promise.all(
+          batch.map(file => this.readDocumentationFile(file, packagePath, packageName, docsPath)),
+        );
+        // Filter out null results and add to classInfos
+        for (const result of results) {
+          if (result) {
+            classInfos.push(result);
           }
         }
       }
+
+      return classInfos;
     } catch (error) {
       this.logger.warn(`Warning: Could not read package ${packageName}: ${error}`);
+      return [];
     }
-
-    return classInfos;
   }
 
   /**
    * Scan the docs directory and index all SFCC classes
-   * Only scans SFCC-specific directories, excluding best-practices and sfra
+    * Only scans SFCC-specific directories, excluding sfra and isml
+   * Uses parallel processing for improved cold-start performance
    */
   async scanDocumentation(docsPath: string): Promise<Map<string, SFCCClassInfo>> {
     const classCache = new Map<string, SFCCClassInfo>();
     const packages = await fs.readdir(docsPath, { withFileTypes: true });
 
-    for (const packageDir of packages) {
+    // Filter to only SFCC directories
+    const sfccPackages = packages.filter(packageDir => {
       if (!packageDir.isDirectory()) {
-        continue;
+        return false;
       }
+      return this.isSFCCDirectory(packageDir.name);
+    });
 
+    // Scan all packages in parallel for faster initialization
+    const scanPromises = sfccPackages.map(async packageDir => {
       const packageName = packageDir.name;
-
-      // Only scan SFCC-specific directories (dw_ prefixed and TopLevel)
-      // Exclude best-practices and sfra directories which are handled by other tools
-      if (!this.isSFCCDirectory(packageName)) {
-        continue;
-      }
-
       const packagePath = path.join(docsPath, packageName);
       const classInfos = await this.scanPackageDirectory(packageName, packagePath, docsPath);
+      return { packageName, classInfos };
+    });
+
+    const results = await Promise.all(scanPromises);
 
-      // Add to cache with normalized keys
+    // Add all results to cache
+    for (const { packageName, classInfos } of results) {
       for (const classInfo of classInfos) {
         const cacheKey = `${packageName}.${classInfo.className}`;
         classCache.set(cacheKey, classInfo);

package/src/clients/docs-client.ts

@@ -15,13 +15,15 @@
 import { PathResolver } from '../utils/path-resolver.js';
 import { CacheManager } from '../utils/cache.js';
 import { Logger } from '../utils/logger.js';
-import { DocumentationScanner, SFCCClassInfo } from './docs/documentation-scanner.js';
-import { ClassContentParser, SFCCClassDetails, SFCCMethod } from './docs/class-content-parser.js';
+import { DocumentationScanner } from './docs/documentation-scanner.js';
+import { ClassContentParser } from './docs/class-content-parser.js';
+import type { SFCCClassInfo } from './docs/documentation-scanner.js';
+import type { SFCCClassDetails, SFCCMethod } from './docs/class-content-parser.js';
 import { ClassNameResolver } from './docs/class-name-resolver.js';
 import { ReferencedTypesExtractor } from './docs/referenced-types-extractor.js';
 
 // Re-export types for backward compatibility
-export { SFCCClassInfo, SFCCMethod, SFCCClassDetails };
+export type { SFCCClassInfo, SFCCMethod, SFCCClassDetails };
 export type { SFCCProperty, SFCCConstant } from './docs/class-content-parser.js';
 
 export interface ClassDetailsFilterOptions {
@@ -36,6 +38,7 @@ export interface ClassDetailsFilterOptions {
 export class SFCCDocumentationClient {
   private docsPath: string;
   private classCache: Map<string, SFCCClassInfo> = new Map();
+  private methodIndex: Map<string, Array<{ className: string; method: SFCCMethod }>> = new Map();
   private cacheManager: CacheManager;
   private initialized = false;
   private logger: Logger;
@@ -52,6 +55,7 @@ export class SFCCDocumentationClient {
 
   /**
    * Initialize the documentation client by scanning all available classes
+   * and building a precomputed method index for fast method searches
    */
   async initialize(): Promise<void> {
     if (this.initialized) {
@@ -59,13 +63,51 @@ export class SFCCDocumentationClient {
     }
 
     try {
+      const startTime = Date.now();
       this.classCache = await this.documentationScanner.scanDocumentation(this.docsPath);
+
+      // Build method index in parallel for O(1) method lookups
+      await this.buildMethodIndex();
+
       this.initialized = true;
+      this.logger.debug(`Documentation initialized in ${Date.now() - startTime}ms (${this.classCache.size} classes, ${this.methodIndex.size} unique methods)`);
     } catch (error) {
       throw new Error(`Failed to initialize SFCC documentation: ${error}`);
     }
   }
 
+  /**
+   * Build a precomputed index mapping method names to their containing classes
+   * This enables O(1) method lookups instead of O(n) iteration over all classes
+   */
+  private async buildMethodIndex(): Promise<void> {
+    this.methodIndex.clear();
+
+    // Process classes in parallel batches for faster index building
+    const BATCH_SIZE = 50;
+    const classEntries = Array.from(this.classCache.entries());
+
+    for (let i = 0; i < classEntries.length; i += BATCH_SIZE) {
+      const batch = classEntries.slice(i, i + BATCH_SIZE);
+
+      await Promise.all(batch.map(async ([className, classInfo]) => {
+        try {
+          const details = this.classContentParser.parseClassContent(classInfo.content);
+          for (const method of details.methods) {
+            const methodKey = method.name.toLowerCase();
+            if (!this.methodIndex.has(methodKey)) {
+              this.methodIndex.set(methodKey, []);
+            }
+            this.methodIndex.get(methodKey)!.push({ className, method });
+          }
+        } catch {
+          // Skip classes that fail to parse
+          this.logger.warn(`Failed to parse methods for class: ${className}`);
+        }
+      }));
+    }
+  }
+
   /**
    * Get a list of all available SFCC classes
    */
@@ -298,7 +340,9 @@ export class SFCCDocumentationClient {
   }
 
   /**
-   * Search for methods across all classes
+   * Search for methods across all classes using precomputed method index
+   * Performance: O(m) where m = number of indexed method names containing the search term
+   * Previously: O(n * p) where n = number of classes, p = avg methods per class
    */
   async searchMethods(methodName: string): Promise<{ className: string; method: SFCCMethod }[]> {
     await this.initialize();
@@ -310,18 +354,14 @@ export class SFCCDocumentationClient {
       return cachedResult;
     }
 
+    const searchTerm = methodName.toLowerCase();
     const results: { className: string; method: SFCCMethod }[] = [];
 
-    for (const [fullClassName] of this.classCache) {
-      const details = await this.getClassDetails(fullClassName);
-      const methods = details?.methods ?? [];
-      for (const method of methods) {
-        if (method.name.toLowerCase().includes(methodName.toLowerCase())) {
-          results.push({
-            className: fullClassName,
-            method,
-          });
-        }
+    // Use precomputed method index for fast lookups
+    // Search through index keys that contain the search term
+    for (const [indexedMethodName, methodEntries] of this.methodIndex) {
+      if (indexedMethodName.includes(searchTerm)) {
+        results.push(...methodEntries);
       }
     }
 

package/src/clients/isml-client.ts

@@ -0,0 +1,353 @@
+/**
+ * SFCC ISML Documentation Client
+ *
+ * Provides access to ISML (Internet Store Markup Language) element documentation including
+ * control flow elements, output formatting, includes, scripting, caching, and special elements.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { PathResolver } from '../utils/path-resolver.js';
+import {
+  AbstractDocumentationClient,
+  BaseDocument,
+  DocumentSummary,
+  SearchResult,
+  CategoryWithCount,
+  DocumentationClientConfig,
+} from './base/abstract-documentation-client.js';
+import {
+  extractDescriptionFromContent,
+  extractSections,
+} from '../utils/markdown-utils.js';
+
+// ==================== Types ====================
+
+export type ISMLCategory =
+  | 'control-flow'
+  | 'output'
+  | 'includes'
+  | 'scripting'
+  | 'cache'
+  | 'decorators'
+  | 'special'
+  | 'payment'
+  | 'analytics';
+
+export interface ISMLElement extends BaseDocument {
+  category: ISMLCategory;
+  attributes?: string[];
+  requiredAttributes?: string[];
+  optionalAttributes?: string[];
+}
+
+export interface ISMLElementSummary extends DocumentSummary {
+  category: string;
+}
+
+export interface ISMLSearchResult extends SearchResult<ISMLElementSummary> {}
+
+export interface ISMLCategoryInfo extends CategoryWithCount {}
+
+// ==================== Configuration ====================
+
+const ISML_CATEGORY_MAPPINGS: Record<string, ISMLCategory> = {
+  // Control flow elements
+  'isif': 'control-flow',
+  'isloop': 'control-flow',
+  'isbreak': 'control-flow',
+  'iscontinue': 'control-flow',
+  'isnext': 'control-flow',
+  'isselect': 'control-flow',
+
+  // Output elements
+  'isprint': 'output',
+
+  // Include/Component elements
+  'isinclude': 'includes',
+  'iscomponent': 'includes',
+  'iscontent': 'includes',
+  'isslot': 'includes',
+  'ismodule': 'includes',
+
+  // Scripting elements
+  'isscript': 'scripting',
+  'isobject': 'scripting',
+  'isset': 'scripting',
+
+  // Cache elements
+  'iscache': 'cache',
+
+  // Decorator elements
+  'isdecorate': 'decorators',
+
+  // Special elements
+  'isredirect': 'special',
+  'isstatus': 'special',
+  'iscookie': 'special',
+  'iscomment': 'special',
+  'isremove': 'special',
+  'isreplace': 'special',
+
+  // Payment elements
+  'ispayment': 'payment',
+  'ispaymentmessages': 'payment',
+  'isapplepay': 'payment',
+  'isbuynow': 'payment',
+
+  // Analytics elements
+  'isactivedatacontext': 'analytics',
+  'isactivedatahead': 'analytics',
+  'isanalyticsoff': 'analytics',
+};
+
+const ISML_CATEGORY_DESCRIPTIONS: Record<ISMLCategory, { displayName: string; description: string }> = {
+  'control-flow': {
+    displayName: 'Control Flow',
+    description: 'Conditional logic, loops, and flow control elements (isif, isloop, isbreak, etc.)',
+  },
+  'output': {
+    displayName: 'Output',
+    description: 'Elements for formatting and displaying data (isprint)',
+  },
+  'includes': {
+    displayName: 'Includes & Components',
+    description: 'Template inclusion and component rendering (isinclude, iscomponent, isslot, etc.)',
+  },
+  'scripting': {
+    displayName: 'Scripting',
+    description: 'Server-side scripting and variable management (isscript, isset, isobject)',
+  },
+  'cache': {
+    displayName: 'Cache',
+    description: 'Page and template caching control (iscache)',
+  },
+  'decorators': {
+    displayName: 'Decorators',
+    description: 'Template decoration and layout wrapping (isdecorate)',
+  },
+  'special': {
+    displayName: 'Special Elements',
+    description: 'Specialized functionality (isredirect, isstatus, iscookie, iscomment, etc.)',
+  },
+  'payment': {
+    displayName: 'Payment',
+    description: 'Payment-related elements (ispayment, isapplepay, isbuynow)',
+  },
+  'analytics': {
+    displayName: 'Analytics',
+    description: 'Analytics and tracking elements (isactivedatacontext, isactivedatahead)',
+  },
+};
+
+// ==================== Client Implementation ====================
+
+/**
+ * Client for accessing ISML element documentation
+ * Extends AbstractDocumentationClient for shared functionality
+ */
+export class ISMLClient extends AbstractDocumentationClient<ISMLElement, ISMLElementSummary, ISMLCategory> {
+  constructor() {
+    const config: DocumentationClientConfig<ISMLCategory> = {
+      clientName: 'ISMLClient',
+      docsPath: path.join(PathResolver.getDocsPath(), 'isml'),
+      categoryMappings: ISML_CATEGORY_MAPPINGS,
+      categoryDescriptions: ISML_CATEGORY_DESCRIPTIONS,
+      defaultCategory: 'special',
+      cachePrefix: 'isml',
+    };
+    super(config);
+  }
+
+  // ==================== Public API (preserves existing interface) ====================
+
+  /**
+   * Get list of all available ISML elements with summaries
+   */
+  async getAvailableElements(): Promise<ISMLElementSummary[]> {
+    return this.getAvailableDocuments();
+  }
+
+  /**
+   * Get detailed information about a specific ISML element
+   */
+  async getISMLElement(
+    elementName: string,
+    options?: {
+      includeContent?: boolean;
+      includeSections?: boolean;
+      includeAttributes?: boolean;
+    },
+  ): Promise<ISMLElement | null> {
+    const normalizedName = this.normalizeElementName(elementName);
+    const element = await this.getDocument(normalizedName);
+
+    if (!element) {
+      return null;
+    }
+
+    // Apply options to filter returned data
+    return this.applyElementOptions(element, options);
+  }
+
+  /**
+   * Search ISML documentation with relevance scoring
+   */
+  async searchISMLElements(
+    query: string,
+    options?: { category?: string; limit?: number },
+  ): Promise<ISMLSearchResult[]> {
+    return this.searchDocuments(query, options);
+  }
+
+  /**
+   * Get ISML elements filtered by category
+   */
+  async getElementsByCategory(category: string): Promise<ISMLElementSummary[]> {
+    return this.getDocumentsByCategory(category);
+  }
+
+  /**
+   * Get available ISML element categories with counts
+   */
+  async getAvailableCategories(): Promise<ISMLCategoryInfo[]> {
+    return super.getAvailableCategories();
+  }
+
+  // ==================== Protected overrides ====================
+
+  protected createDocument(baseData: BaseDocument): ISMLElement {
+    return {
+      ...baseData,
+      category: baseData.category as ISMLCategory,
+      attributes: [],
+      requiredAttributes: [],
+      optionalAttributes: [],
+    };
+  }
+
+  protected toSummary(element: ISMLElement): ISMLElementSummary {
+    return {
+      name: element.name,
+      title: element.title,
+      description: element.description,
+      category: element.category,
+      filename: element.filename,
+    };
+  }
+
+  protected async parseDocumentFile(filePath: string, filename: string): Promise<ISMLElement | null> {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const stats = await fs.stat(filePath);
+
+      const elementName = filename.replace('.md', '');
+      const normalizedName = this.normalizeDocumentName(elementName);
+
+      // Extract title from first heading
+      const titleMatch = content.match(/^#\s+(.+)$/m);
+      const title = titleMatch ? titleMatch[1].trim() : elementName;
+
+      // Extract attributes
+      const attributes = this.extractAttributes(content);
+
+      // Get category
+      const category = ISML_CATEGORY_MAPPINGS[normalizedName] ?? 'special';
+
+      return {
+        name: elementName,
+        title,
+        description: extractDescriptionFromContent(content),
+        sections: extractSections(content),
+        content,
+        category,
+        attributes: attributes.all,
+        requiredAttributes: attributes.required,
+        optionalAttributes: attributes.optional,
+        filename,
+        lastModified: stats.mtime,
+      };
+    } catch (error) {
+      this.logger.error(`Error parsing ISML file ${filename}: ${error}`);
+      return null;
+    }
+  }
+
+  // ==================== Private helpers ====================
+
+  /**
+   * Normalize element name (ensure 'is' prefix)
+   */
+  private normalizeElementName(name: string): string {
+    const lower = name.toLowerCase();
+    return lower.startsWith('is') ? lower : `is${lower}`;
+  }
+
+  /**
+   * Extract attributes from content
+   */
+  private extractAttributes(content: string): {
+    all: string[];
+    required: string[];
+    optional: string[];
+  } {
+    const all: string[] = [];
+    const required: string[] = [];
+    const optional: string[] = [];
+
+    const attrRegex = /###\s+(.+?)\n/g;
+    let match;
+
+    while ((match = attrRegex.exec(content)) !== null) {
+      const attrName = match[1].trim();
+
+      // Skip common headings that aren't attributes
+      const skipPatterns = ['overview', 'syntax', 'example', 'use case'];
+      if (skipPatterns.some(p => attrName.toLowerCase().includes(p))) {
+        continue;
+      }
+
+      all.push(attrName);
+
+      // Check if attribute is required/optional
+      const sectionContent = content.slice(match.index, match.index + 500);
+      if (sectionContent.toLowerCase().includes('required: yes')) {
+        required.push(attrName);
+      } else if (sectionContent.toLowerCase().includes('optional: yes')) {
+        optional.push(attrName);
+      }
+    }
+
+    return { all, required, optional };
+  }
+
+  /**
+   * Apply filtering options to element data
+   */
+  private applyElementOptions(
+    element: ISMLElement,
+    options?: {
+      includeContent?: boolean;
+      includeSections?: boolean;
+      includeAttributes?: boolean;
+    },
+  ): ISMLElement {
+    const filtered = { ...element };
+
+    if (options?.includeContent === false) {
+      filtered.content = '';
+    }
+
+    if (options?.includeSections === false) {
+      filtered.sections = [];
+    }
+
+    if (options?.includeAttributes === false) {
+      filtered.attributes = [];
+      filtered.requiredAttributes = [];
+      filtered.optionalAttributes = [];
+    }
+
+    return filtered;
+  }
+}

package/src/clients/ocapi/code-versions-client.ts

@@ -39,10 +39,16 @@ export class OCAPICodeVersionsClient extends OCAPIAuthClient {
   async activateCodeVersion(codeVersionId: string): Promise<any> {
     Validator.validateRequired({ codeVersionId }, ['codeVersionId']);
 
+    // Validate code version ID format to prevent URL injection
+    // Code version IDs should be alphanumeric with underscores, dashes, and dots
+    if (!/^[a-zA-Z0-9_.-]+$/.test(codeVersionId)) {
+      throw new Error('Invalid code version ID format. Must contain only alphanumeric characters, underscores, dashes, and dots.');
+    }
+
     const requestBody = {
       active: true,
     };
 
-    return this.patch(`/code_versions/${codeVersionId}`, requestBody);
+    return this.patch(`/code_versions/${encodeURIComponent(codeVersionId)}`, requestBody);
   }
 }