@pattern-stack/frontend-patterns 0.2.0-alpha.0 → 0.2.0-alpha.3

package/cli/commands/generate-hooks.ts

@@ -8,11 +8,15 @@
 
 import { promises as fs } from 'fs'
 import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
 import { loadOpenAPISpec, parseOpenAPI } from '../../src/codegen/openapi/parser.js'
 import { generateTypes } from '../../src/codegen/openapi/type-generator.js'
 import { generateAPIClient } from '../../src/codegen/openapi/client-generator.js'
 import { generateHooks } from '../../src/codegen/openapi/hook-generator.js'
 
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
 interface GenerateHooksOptions {
   output: string
   prefix?: string
@@ -121,6 +125,11 @@ export async function generateHooksCommand(source: string, options: GenerateHook
     await writeFile(join(options.output, 'hooks', 'keys.ts'), hooks.keys)
     await writeFile(join(options.output, 'hooks', 'types.ts'), hooks.types)
     await writeFile(join(options.output, 'hooks', 'index.ts'), hooks.index)
+
+    // Copy bulk-types.ts to output directory (referenced by hooks/types.ts)
+    const bulkTypesPath = join(__dirname, '../../src/codegen/openapi/bulk-types.ts')
+    const bulkTypesContent = await fs.readFile(bulkTypesPath, 'utf8')
+    await writeFile(join(options.output, 'bulk-types.ts'), bulkTypesContent)
     
     // Write confidence report if available
     if (hooks.report) {
@@ -154,10 +163,10 @@ export { queryKeys } from './hooks'`
     
     await writeFile(join(options.output, 'index.ts'), mainIndex)
     
-    // Generate usage example
+    // Generate usage example (as .tsx since it contains JSX)
     const usageExample = generateUsageExample(spec.info.title, options)
-    await writeFile(join(options.output, 'example.ts'), usageExample)
-    
+    await writeFile(join(options.output, 'example.tsx'), usageExample)
+
     console.log()
     console.log('✅ Generation complete!')
     console.log(`📦 Generated files in: ${options.output}`)
@@ -165,7 +174,7 @@ export { queryKeys } from './hooks'`
     console.log('🚀 Quick start:')
     console.log(`import { createAPIClient, useGetUsers } from './${options.output}'`)
     console.log()
-    console.log('💡 See example.ts for detailed usage instructions')
+    console.log('💡 See example.tsx for detailed usage instructions')
     
   } catch (error) {
     console.error('❌ Generation failed:')

package/cli/src/codegen/openapi/__tests__/naming-utils.test.js

@@ -0,0 +1,367 @@
+import { singularize, pluralize, isPlural } from '../naming-utils.js';
+
+describe('singularize()', () => {
+  describe('regular plurals', () => {
+    it('should convert cats to cat', () => {
+      expect(singularize('cats')).toBe('cat');
+    });
+
+    it('should convert dogs to dog', () => {
+      expect(singularize('dogs')).toBe('dog');
+    });
+
+    it('should convert users to user', () => {
+      expect(singularize('users')).toBe('user');
+    });
+
+    it('should convert accounts to account', () => {
+      expect(singularize('accounts')).toBe('account');
+    });
+  });
+
+  describe('-ies plurals', () => {
+    it('should convert activities to activity', () => {
+      expect(singularize('activities')).toBe('activity');
+    });
+
+    it('should convert categories to category', () => {
+      expect(singularize('categories')).toBe('category');
+    });
+
+    it('should convert companies to company', () => {
+      expect(singularize('companies')).toBe('company');
+    });
+
+    it('should convert opportunities to opportunity', () => {
+      expect(singularize('opportunities')).toBe('opportunity');
+    });
+  });
+
+  describe('-es plurals', () => {
+    it('should convert boxes to box', () => {
+      expect(singularize('boxes')).toBe('box');
+    });
+
+    it('should convert watches to watch', () => {
+      expect(singularize('watches')).toBe('watch');
+    });
+
+    it('should convert dishes to dish', () => {
+      expect(singularize('dishes')).toBe('dish');
+    });
+
+    it('should convert benches to bench', () => {
+      expect(singularize('benches')).toBe('bench');
+    });
+  });
+
+  describe('-ses plurals (tricky cases)', () => {
+    it('should convert addresses to address', () => {
+      expect(singularize('addresses')).toBe('address');
+    });
+
+    it('should convert businesses to business', () => {
+      expect(singularize('businesses')).toBe('business');
+    });
+
+    it('should convert processes to process', () => {
+      expect(singularize('processes')).toBe('process');
+    });
+  });
+
+  describe('irregular plurals', () => {
+    it('should convert people to person', () => {
+      expect(singularize('people')).toBe('person');
+    });
+
+    it('should convert children to child', () => {
+      expect(singularize('children')).toBe('child');
+    });
+
+    it('should convert men to man', () => {
+      expect(singularize('men')).toBe('man');
+    });
+
+    it('should convert women to woman', () => {
+      expect(singularize('women')).toBe('woman');
+    });
+  });
+
+  describe('already singular', () => {
+    it('should keep data as data', () => {
+      expect(singularize('data')).toBe('data');
+    });
+
+    it('should keep metadata as metadata', () => {
+      expect(singularize('metadata')).toBe('metadata');
+    });
+
+    it('should keep user as user', () => {
+      expect(singularize('user')).toBe('user');
+    });
+
+    it('should keep account as account', () => {
+      expect(singularize('account')).toBe('account');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should keep status as status', () => {
+      expect(singularize('status')).toBe('status');
+    });
+
+    it('should keep class as class', () => {
+      expect(singularize('class')).toBe('class');
+    });
+
+    it('should keep bus as bus', () => {
+      expect(singularize('bus')).toBe('bus');
+    });
+
+    it('should convert pass to pass (not pas)', () => {
+      expect(singularize('pass')).toBe('pass');
+    });
+
+    it('should handle empty string', () => {
+      expect(singularize('')).toBe('');
+    });
+
+    it('should handle single character', () => {
+      expect(singularize('a')).toBe('a');
+    });
+  });
+});
+
+describe('pluralize()', () => {
+  describe('regular plurals', () => {
+    it('should convert cat to cats', () => {
+      expect(pluralize('cat')).toBe('cats');
+    });
+
+    it('should convert dog to dogs', () => {
+      expect(pluralize('dog')).toBe('dogs');
+    });
+
+    it('should convert user to users', () => {
+      expect(pluralize('user')).toBe('users');
+    });
+
+    it('should convert account to accounts', () => {
+      expect(pluralize('account')).toBe('accounts');
+    });
+  });
+
+  describe('-y endings (consonant + y)', () => {
+    it('should convert activity to activities', () => {
+      expect(pluralize('activity')).toBe('activities');
+    });
+
+    it('should convert category to categories', () => {
+      expect(pluralize('category')).toBe('categories');
+    });
+
+    it('should convert company to companies', () => {
+      expect(pluralize('company')).toBe('companies');
+    });
+
+    it('should convert opportunity to opportunities', () => {
+      expect(pluralize('opportunity')).toBe('opportunities');
+    });
+  });
+
+  describe('vowel + y endings', () => {
+    it('should convert day to days', () => {
+      expect(pluralize('day')).toBe('days');
+    });
+
+    it('should convert key to keys', () => {
+      expect(pluralize('key')).toBe('keys');
+    });
+
+    it('should convert boy to boys', () => {
+      expect(pluralize('boy')).toBe('boys');
+    });
+
+    it('should convert array to arrays', () => {
+      expect(pluralize('array')).toBe('arrays');
+    });
+  });
+
+  describe('-x, -ch, -sh, -s, -ss endings', () => {
+    it('should convert box to boxes', () => {
+      expect(pluralize('box')).toBe('boxes');
+    });
+
+    it('should convert watch to watches', () => {
+      expect(pluralize('watch')).toBe('watches');
+    });
+
+    it('should convert dish to dishes', () => {
+      expect(pluralize('dish')).toBe('dishes');
+    });
+
+    it('should convert bench to benches', () => {
+      expect(pluralize('bench')).toBe('benches');
+    });
+
+    it('should convert address to addresses', () => {
+      expect(pluralize('address')).toBe('addresses');
+    });
+
+    it('should convert business to businesses', () => {
+      expect(pluralize('business')).toBe('businesses');
+    });
+
+    it('should convert class to classes', () => {
+      expect(pluralize('class')).toBe('classes');
+    });
+  });
+
+  describe('irregular plurals', () => {
+    it('should convert person to people', () => {
+      expect(pluralize('person')).toBe('people');
+    });
+
+    it('should convert child to children', () => {
+      expect(pluralize('child')).toBe('children');
+    });
+
+    it('should convert man to men', () => {
+      expect(pluralize('man')).toBe('men');
+    });
+
+    it('should convert woman to women', () => {
+      expect(pluralize('woman')).toBe('women');
+    });
+  });
+
+  describe('already plural (no double-pluralize)', () => {
+    it('should keep accounts as accounts', () => {
+      expect(pluralize('accounts')).toBe('accounts');
+    });
+
+    it('should keep users as users', () => {
+      expect(pluralize('users')).toBe('users');
+    });
+
+    it('should keep activities as activities', () => {
+      expect(pluralize('activities')).toBe('activities');
+    });
+
+    it('should keep boxes as boxes', () => {
+      expect(pluralize('boxes')).toBe('boxes');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty string', () => {
+      expect(pluralize('')).toBe('');
+    });
+
+    it('should handle single character', () => {
+      expect(pluralize('a')).toBe('as');
+    });
+
+    it('should keep status as status (special case)', () => {
+      expect(pluralize('status')).toBe('status');
+    });
+  });
+});
+
+describe('isPlural()', () => {
+  describe('should return true for plural words', () => {
+    it('should identify cats as plural', () => {
+      expect(isPlural('cats')).toBe(true);
+    });
+
+    it('should identify activities as plural', () => {
+      expect(isPlural('activities')).toBe(true);
+    });
+
+    it('should identify boxes as plural', () => {
+      expect(isPlural('boxes')).toBe(true);
+    });
+
+    it('should identify watches as plural', () => {
+      expect(isPlural('watches')).toBe(true);
+    });
+
+    it('should identify addresses as plural', () => {
+      expect(isPlural('addresses')).toBe(true);
+    });
+
+    it('should identify people as plural', () => {
+      expect(isPlural('people')).toBe(true);
+    });
+
+    it('should identify children as plural', () => {
+      expect(isPlural('children')).toBe(true);
+    });
+
+    it('should identify users as plural', () => {
+      expect(isPlural('users')).toBe(true);
+    });
+
+    it('should identify accounts as plural', () => {
+      expect(isPlural('accounts')).toBe(true);
+    });
+  });
+
+  describe('should return false for singular words', () => {
+    it('should identify cat as singular', () => {
+      expect(isPlural('cat')).toBe(false);
+    });
+
+    it('should identify activity as singular', () => {
+      expect(isPlural('activity')).toBe(false);
+    });
+
+    it('should identify box as singular', () => {
+      expect(isPlural('box')).toBe(false);
+    });
+
+    it('should identify user as singular', () => {
+      expect(isPlural('user')).toBe(false);
+    });
+
+    it('should identify account as singular', () => {
+      expect(isPlural('account')).toBe(false);
+    });
+  });
+
+  describe('should return false for edge cases', () => {
+    it('should identify status as singular', () => {
+      expect(isPlural('status')).toBe(false);
+    });
+
+    it('should identify class as singular', () => {
+      expect(isPlural('class')).toBe(false);
+    });
+
+    it('should identify bus as singular', () => {
+      expect(isPlural('bus')).toBe(false);
+    });
+
+    it('should identify process as singular', () => {
+      expect(isPlural('process')).toBe(false);
+    });
+
+    it('should identify data as singular', () => {
+      expect(isPlural('data')).toBe(false);
+    });
+
+    it('should identify metadata as singular', () => {
+      expect(isPlural('metadata')).toBe(false);
+    });
+  });
+
+  describe('should handle empty/minimal input', () => {
+    it('should return false for empty string', () => {
+      expect(isPlural('')).toBe(false);
+    });
+
+    it('should return false for single character', () => {
+      expect(isPlural('a')).toBe(false);
+    });
+  });
+});

package/cli/src/codegen/openapi/client-generator.js

@@ -6,6 +6,9 @@
  *
  * Part of FRO-12: API Client Generator
  */
+import { singularize, pluralize, isPlural } from './naming-utils.js';
+import { AUTH_ACTIONS, HEALTH_ENDPOINTS, USER_PROFILE_ENDPOINTS, SINGLETON_RESOURCES, COLLECTION_ACTIONS } from './naming-constants.js';
+
 export class APIClientGenerator {
     options;
     constructor(options = {}) {
@@ -39,7 +42,7 @@ export class APIClientGenerator {
     generateAxiosClient() {
         return `/**
  * Axios API Client
- * 
+ *
  * Auto-generated API client with interceptors and error handling
  */
 
@@ -146,7 +149,7 @@ export class APIClient {
     generateFetchClient() {
         return `/**
  * Fetch API Client
- * 
+ *
  * Auto-generated API client using native fetch with error handling
  */
 
@@ -166,7 +169,7 @@ export class APIClient {
   ): Promise<T> {
     try {
       const fullUrl = this.buildUrl(url, options.params)
-      
+
       const fetchOptions: RequestInit = {
         method,
         headers: {
@@ -205,7 +208,7 @@ export class APIClient {
 
   private buildUrl(path: string, params?: Record<string, any>): string {
     const url = new URL(path, this.config.baseUrl)
-    
+
     if (params) {
       Object.entries(params).forEach(([key, value]) => {
         if (value !== undefined && value !== null) {
@@ -325,7 +328,7 @@ export class APIClient {
   private shouldRetry(error: AxiosError): boolean {
     const retryCount = (error.config as any)?._retryCount || 0
     const maxRetries = this.config.retries || ${this.options.retries}
-    
+
     return (
       retryCount < maxRetries &&
       (!error.response || error.response.status >= 500) &&
@@ -335,11 +338,11 @@ export class APIClient {
 
   private async retryRequest(config: any): Promise<any> {
     config._retryCount = (config._retryCount || 0) + 1
-    
+
     // Exponential backoff
     const delay = Math.pow(2, config._retryCount) * 1000
     await new Promise(resolve => setTimeout(resolve, delay))
-    
+
     return this.client.request(config)
   }`;
     }
@@ -500,7 +503,7 @@ export class APIClient {
         const authTypes = this.generateAuthTypes();
         return `/**
  * API Client Types
- * 
+ *
  * Configuration and utility types for the generated API client
  */
 
@@ -556,7 +559,7 @@ export interface APIError {
     generateConfiguration() {
         return `/**
  * API Client Configuration
- * 
+ *
  * Default configuration and factory functions
  */
 
@@ -580,7 +583,7 @@ export const defaultConfig: Partial<APIClientConfig> = {
     generateIndexFile() {
         return `/**
  * Generated API Client
- * 
+ *
  * Auto-generated from OpenAPI specification
  */
 
@@ -593,20 +596,85 @@ export { createAPIClient, defaultConfig } from './config'`;
     generateFileHeader(title) {
         return `/**
  * ${title}
- * 
+ *
  * Auto-generated from OpenAPI specification
  * Do not edit manually
  */`;
     }
     getMethodName(endpoint) {
-        if (endpoint.operationId) {
-            return this.camelCase(endpoint.operationId);
-        }
-        const pathParts = endpoint.path
-            .split('/')
-            .filter(part => part && !part.startsWith('{'))
-            .map(part => this.capitalize(part));
-        return this.camelCase(`${endpoint.method}_${pathParts.join('_')}`);
+        // Use semantic naming instead of raw operationId
+        return this.generateSemanticMethodName(endpoint);
+    }
+    generateSemanticMethodName(endpoint) {
+        // Extract resource from path
+        const pathSegments = endpoint.path.split('/').filter(s => s && !s.startsWith('{') && !['api', 'v1', 'v2'].includes(s));
+        const urlSegments = endpoint.path.split('/');
+        const hasPathParam = endpoint.path.includes('{');
+        const lastSegment = pathSegments[pathSegments.length - 1]?.replace(/-/g, '_') || 'resource';
+        const prevSegment = pathSegments[pathSegments.length - 2]?.replace(/-/g, '_');
+
+        // Auth endpoints - use action name directly
+        if (AUTH_ACTIONS.includes(lastSegment.toLowerCase())) {
+            return this.camelCase(lastSegment);
+        }
+
+        // Health/status singletons
+        if (HEALTH_ENDPOINTS.includes(lastSegment.toLowerCase())) {
+            return this.camelCase(lastSegment);
+        }
+
+        // User profile singletons
+        if (USER_PROFILE_ENDPOINTS.includes(lastSegment.toLowerCase())) {
+            return this.camelCase(`get_current_user`);
+        }
+
+        // Metadata endpoints - include parent resource to avoid collision
+        if (lastSegment.toLowerCase() === 'metadata' && prevSegment) {
+            return hasPathParam
+                ? this.camelCase(`get_${singularize(prevSegment)}_metadata`)
+                : this.camelCase(`get_${prevSegment}_metadata`);
+        }
+
+        // Collection actions (e.g., /activities/search)
+        if (COLLECTION_ACTIONS.includes(lastSegment.toLowerCase()) && prevSegment) {
+            return this.camelCase(`${lastSegment}_${prevSegment}`);
+        }
+
+        // Determine resource name - for nested paths, include context
+        let resource = lastSegment;
+        if (pathSegments.length > 2 && hasPathParam) {
+            // e.g., /accounts/{id}/stages/allowed → get_account_allowed_stages
+            const parentResource = pathSegments.find((s, i) => {
+                const nextSeg = urlSegments[urlSegments.findIndex(u => u === s) + 1];
+                return nextSeg?.startsWith('{');
+            });
+            if (parentResource && parentResource !== lastSegment) {
+                resource = `${singularize(parentResource)}_${lastSegment}`;
+            }
+        }
+
+        // Generate name based on HTTP method
+        switch (endpoint.method) {
+            case 'get':
+                return hasPathParam
+                    ? this.camelCase(`get_${singularize(resource)}`)
+                    : this.camelCase(`list_${resource}`);
+            case 'post':
+                // Check for custom actions like /accounts/{id}/stage
+                const lastUrl = urlSegments[urlSegments.length - 1];
+                const prevUrl = urlSegments[urlSegments.length - 2];
+                if (!lastUrl.startsWith('{') && prevUrl?.startsWith('{')) {
+                    return this.camelCase(`${lastUrl}_${singularize(prevSegment || resource)}`);
+                }
+                return this.camelCase(`create_${singularize(resource)}`);
+            case 'put':
+            case 'patch':
+                return this.camelCase(`update_${singularize(resource)}`);
+            case 'delete':
+                return this.camelCase(`delete_${singularize(resource)}`);
+            default:
+                return this.camelCase(`${endpoint.method}_${resource}`);
+        }
     }
     generatePathWithParams(endpoint) {
         return endpoint.path.replace(/{([^}]+)}/g, '${$1}');

package/cli/src/codegen/openapi/confidence-scorer.js

@@ -0,0 +1,93 @@
+/**
+ * Confidence Scorer (Stub)
+ *
+ * Scores generated hook names for quality/confidence.
+ * This is a minimal stub that returns high confidence for all names.
+ */
+
+export class ConfidenceScorer {
+  constructor() {
+    this.scoringRules = [];
+  }
+
+  /**
+   * Score a generated hook name
+   * @returns {{ hookName: string, operationId: string, confidence: string, score: number, suggestions: string[] }}
+   */
+  scoreHookName(hookName, operationId, path, method) {
+    // Simple heuristic: shorter names are better
+    const lengthScore = Math.max(0, 100 - hookName.length);
+
+    // Check for common anti-patterns
+    const hasApiV1 = hookName.toLowerCase().includes('apiv1');
+    const hasUnderscore = hookName.includes('_');
+    const isVeryLong = hookName.length > 40;
+
+    let score = lengthScore;
+    if (hasApiV1) score -= 30;
+    if (hasUnderscore) score -= 10;
+    if (isVeryLong) score -= 20;
+
+    // Normalize to 0-100
+    score = Math.max(0, Math.min(100, score));
+
+    // Determine confidence level
+    let confidence;
+    if (score >= 70) confidence = 'high';
+    else if (score >= 40) confidence = 'medium';
+    else confidence = 'low';
+
+    return {
+      hookName,
+      operationId,
+      path,
+      method,
+      confidence,
+      score,
+      suggestions: confidence === 'low' ? [this.suggestBetterName(path, method)] : []
+    };
+  }
+
+  suggestBetterName(path, method) {
+    // Extract resource from path
+    const segments = path.split('/').filter(s => s && !s.startsWith('{') && !['api', 'v1'].includes(s));
+    const resource = segments[segments.length - 1]?.replace(/-/g, '') || 'resource';
+
+    // Capitalize first letter
+    const capitalizedResource = resource.charAt(0).toUpperCase() + resource.slice(1);
+
+    switch (method) {
+      case 'get':
+        return path.includes('{') ? `useGet${capitalizedResource}` : `use${capitalizedResource}`;
+      case 'post':
+        return `useCreate${capitalizedResource}`;
+      case 'put':
+      case 'patch':
+        return `useUpdate${capitalizedResource}`;
+      case 'delete':
+        return `useDelete${capitalizedResource}`;
+      default:
+        return `use${capitalizedResource}`;
+    }
+  }
+
+  generateReport(scoredNames) {
+    const high = scoredNames.filter(s => s.confidence === 'high').length;
+    const medium = scoredNames.filter(s => s.confidence === 'medium').length;
+    const low = scoredNames.filter(s => s.confidence === 'low').length;
+
+    return `
+Hook Name Quality Report
+========================
+Total hooks: ${scoredNames.length}
+High confidence: ${high} (${Math.round(high/scoredNames.length*100)}%)
+Medium confidence: ${medium} (${Math.round(medium/scoredNames.length*100)}%)
+Low confidence: ${low} (${Math.round(low/scoredNames.length*100)}%)
+
+${low > 0 ? 'Low confidence hooks that may need review:\n' +
+  scoredNames.filter(s => s.confidence === 'low')
+    .map(s => `  - ${s.hookName} → suggested: ${s.suggestions[0]}`)
+    .join('\n') : 'All hooks have acceptable names!'}
+`;
+  }
+}