Merge pull request #6 from 10up/fix/5

Fix issues with multiple types for parameter and duplicate hooks

Author: iamdharmesh

src/cli.ts

@@ -11,7 +11,7 @@ const program = new Command();
 const defaultConfig: WPHooksDocConfig = {
   input: '.',
   outputDir: './wp-hooks-docs',
-  ignoreFiles: [],
+  ignoreFiles: ['/tests/', '/vendor/', '/node_modules/'],
   ignoreHooks: [],
   title: 'Plugin Hooks Documentation',
   tagline: 'Documentation for the plugin hooks',

src/collectors/hook-collector.ts

@@ -60,24 +60,58 @@ export class HookCollector {
   }
 
   private transformHooks(rawData: RawHookCollection): HookCollection {
-    // Deduplicate hooks based on name
+    // Helper function to merge hooks with the same name and transform them.
+    const prepareHooks = (hooks: RawHookData['hooks']): Hook[] => {
+      const hookMap = new Map<string, RawHookData['hooks'][0][]>();
+
+      // Group hooks by name
+      hooks.forEach((hook) => {
+        const hookId = this.getHookId(this.escapeHookName(hook.name));
+        if (!hookMap.has(hookId)) {
+          hookMap.set(hookId, []);
+        }
+        hookMap.get(hookId)?.push(hook);
+      });
+
+      // Merge and transform hooks
+      return Array.from(hookMap.entries()).map(([_, hooks]) => {
+        if (hooks.length === 1) {
+          return this.transformHook(hooks[0]);
+        }
+
+        // Merge multiple hooks with the same name
+        const mergedHook = { ...hooks[0] };
+
+        // Collect sources of all hooks.
+        mergedHook.files = [];
+        hooks.forEach((h) => {
+          const file = {
+            file: h.file || '',
+            line: h.line || 0,
+          };
+          mergedHook.files?.push(file);
+        });
+
+        return this.transformHook(mergedHook);
+      });
+    };
+
     return {
-      actions: rawData.actions.hooks.map(this.transformHook.bind(this)),
-      filters: rawData.filters.hooks.map(this.transformHook.bind(this)),
+      actions: prepareHooks(rawData.actions.hooks),
+      filters: prepareHooks(rawData.filters.hooks),
     };
   }
 
-  private transformHook(hook: RawHookData['hooks'][0]): Hook {
-    let hookName = hook.name;
-
+  private escapeHookName(hookName: string): string {
+    let escapedHookName = hookName;
     /**
      * Replace PHP-style interpolations with {$var}_suffix
      * Example:
      * 'woocommerce_analytics_' . $field . '_' . $context
      * becomes
      * 'woocommerce_analytics_{$field}_$context'
      */
-    hookName = hookName.replace(
+    escapedHookName = hookName.replace(
       /['"]\s*\.\s*(\$(?:[a-zA-Z_]\w*)(?:->\w+|\[[^\]]+\]|\(\))*((?:->\w+|\[[^\]]+\]|\(\)))*)\s*\.\s*['"]?_?([a-zA-Z0-9_]*)/g,
       (_, variable, rest, suffix) => `{${variable}${rest || ''}}${suffix ? `_${suffix}` : ''}`
     );
@@ -89,26 +123,36 @@ export class HookCollector {
      * becomes
      * 'woocommerce_analytics_{$field}'
      */
-    hookName = hookName.replace(
+    escapedHookName = hookName.replace(
       /['"]\s*\.\s*(\$(?:[a-zA-Z_]\w*)(?:->\w+|\[[^\]]+\]|\(\))*((?:->\w+|\[[^\]]+\]|\(\)))*)/g,
       (_, variable, rest) => `{${variable}${rest || ''}}`
     );
 
     /**
      * Remove quotes from hook name
      */
-    hookName = hookName.replace(/['"]/g, '');
+    escapedHookName = hookName.replace(/['"]/g, '');
+
+    return escapedHookName;
+  }
 
-    const hookId = hookName
+  private getHookId(hookName: string): string {
+    return hookName
       .replace(/[^a-zA-Z0-9\-_.~]/g, '')
       .replace(/^__/, '')
       .replace(/^_/, '');
+  }
+
+  private transformHook(hook: RawHookData['hooks'][0]): Hook {
+    const hookName = this.escapeHookName(hook.name);
+    const hookId = this.getHookId(hookName);
 
     return {
       id: hookId,
       name: hookName,
       type: hook.type,
       file: hook.file,
+      files: hook.files || [],
       line: hook.line || 0,
       doc: {
         description: hook.doc?.description || '',

src/generators/markdown-generator.ts

@@ -96,7 +96,7 @@ export class MarkdownGenerator {
       content.push('|------|------|-------------|');
       hook.doc.params.forEach((param) => {
         content.push(
-          `| ${param.name} | \`${param.type}\` | ${this.sanitizeContent(param.description, true)} |`
+          `| ${this.sanitizeContent(param.name)} | \`${this.sanitizeContent(param.type)}\` | ${this.sanitizeContent(param.description, true)} |`
         );
       });
       content.push('');
@@ -114,7 +114,20 @@ export class MarkdownGenerator {
       });
     }
 
-    if (hook.file) {
+    if (hook.files && hook.files.length > 0) {
+      content.push('### Source\n');
+      hook.files.forEach((file) => {
+        if (file.line && file.line > 0 && this.config.githubSourceCodeUrl) {
+          content.push(
+            `- Defined in [\`${file.file}\` at line ${file.line}](${this.config.githubSourceCodeUrl}/${file.file}#L${file.line})`
+          );
+        } else if (file.line && file.line > 0) {
+          content.push(`- Defined in \`${file.file}\` at line ${file.line}`);
+        } else {
+          content.push(`- Defined in \`${file.file}\``);
+        }
+      });
+    } else if (hook.file) {
       content.push('### Source\n');
       if (hook.line && hook.line > 0 && this.config.githubSourceCodeUrl) {
         content.push(
@@ -216,7 +229,7 @@ export class MarkdownGenerator {
       sanitized = sanitized.replace(/\n/g, '');
     }
 
-    return sanitized.replace(/[{}]/g, (match) => `\\${match}`);
+    return sanitized.replace(/[{}|]/g, (match) => `\\${match}`);
   }
 
   private sanitizeHookName(hookName: string): string {

src/utils/types.ts

@@ -1,8 +1,14 @@
+export interface HookFile {
+  file: string;
+  line: number;
+}
+
 export interface Hook {
   id: string;
   name: string;
   type: string;
   file: string;
+  files?: HookFile[];
   line?: number;
   doc: {
     description?: string;
@@ -55,6 +61,7 @@ export interface RawHookData {
     name: string;
     type: string;
     file: string;
+    files?: HookFile[];
     line?: number;
     doc?: {
       description?: string;