@hustle-together/api-dev-tools 2.0.7 → 3.1.0

package/scripts/extract-parameters.ts

@@ -0,0 +1,483 @@
+#!/usr/bin/env npx tsx
+/**
+ * Extract Parameters Script
+ *
+ * Programmatically extracts ALL parameters from:
+ * 1. Zod schemas (request/response validation)
+ * 2. Route files (query params, headers)
+ * 3. Test files (parameter usage in tests)
+ *
+ * Generates a parameter matrix for each endpoint showing:
+ * - Name, type, required/optional
+ * - Valid values, defaults, constraints
+ * - Test coverage (which params are tested)
+ *
+ * IMPORTANT: This is 100% programmatic - NO LLM involvement.
+ *
+ * @generated by @hustle-together/api-dev-tools v3.0
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ============================================
+// Types
+// ============================================
+
+interface ParameterDefinition {
+  name: string;
+  location: 'query' | 'body' | 'header' | 'path';
+  type: string;
+  required: boolean;
+  description?: string;
+  default?: unknown;
+  enum?: string[];
+  min?: number;
+  max?: number;
+  pattern?: string;
+  example?: unknown;
+}
+
+interface EndpointParameters {
+  endpoint: string;
+  method: string;
+  parameters: ParameterDefinition[];
+  sourceFiles: string[];
+  testedParameters: string[];
+  untestedParameters: string[];
+}
+
+interface ParameterMatrix {
+  version: string;
+  generatedAt: string;
+  endpoints: EndpointParameters[];
+  coverage: {
+    totalParameters: number;
+    testedParameters: number;
+    coveragePercent: number;
+  };
+}
+
+// ============================================
+// File Discovery
+// ============================================
+
+function findFiles(baseDir: string, pattern: RegExp, exclude: string[] = ['node_modules', '.git', 'dist']): string[] {
+  const files: string[] = [];
+
+  function walk(dir: string) {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (exclude.includes(entry.name)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else if (entry.isFile() && pattern.test(entry.name)) {
+          files.push(fullPath);
+        }
+      }
+    } catch {
+      // Skip unreadable directories
+    }
+  }
+
+  walk(baseDir);
+  return files;
+}
+
+// ============================================
+// Zod Schema Extractor
+// ============================================
+
+function extractFromZodSchema(content: string): ParameterDefinition[] {
+  const params: ParameterDefinition[] = [];
+
+  // Match z.object definitions with their field names
+  // This handles nested objects and various Zod types
+  const zodObjectRegex = /z\.object\s*\(\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/gs;
+
+  let objectMatch;
+  while ((objectMatch = zodObjectRegex.exec(content)) !== null) {
+    const objectBody = objectMatch[1];
+
+    // Parse individual fields
+    // Pattern handles: fieldName: z.type().chain().chain()
+    const fieldRegex = /(\w+)\s*:\s*(z\.(?:[^,\n]+(?:\([^)]*\))?)+)/g;
+
+    let fieldMatch;
+    while ((fieldMatch = fieldRegex.exec(objectBody)) !== null) {
+      const [, name, zodChain] = fieldMatch;
+
+      const param = parseZodChain(name, zodChain);
+      if (param) {
+        params.push(param);
+      }
+    }
+  }
+
+  return params;
+}
+
+function parseZodChain(name: string, chain: string): ParameterDefinition | null {
+  // Determine base type
+  const typeMatch = chain.match(/z\.(\w+)/);
+  if (!typeMatch) return null;
+
+  const baseType = typeMatch[1];
+
+  const param: ParameterDefinition = {
+    name,
+    location: 'body', // Default, will be refined based on context
+    type: mapZodType(baseType),
+    required: true
+  };
+
+  // Check for optional
+  if (chain.includes('.optional()') || chain.includes('.nullable()')) {
+    param.required = false;
+  }
+
+  // Extract description
+  const descMatch = chain.match(/\.describe\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+  if (descMatch) {
+    param.description = descMatch[1];
+  }
+
+  // Extract default value
+  const defaultMatch = chain.match(/\.default\s*\(\s*([^)]+)\s*\)/);
+  if (defaultMatch) {
+    try {
+      param.default = JSON.parse(defaultMatch[1].replace(/'/g, '"'));
+    } catch {
+      param.default = defaultMatch[1].replace(/['"]/g, '');
+    }
+    param.required = false; // Has default = not required
+  }
+
+  // Extract enum values
+  if (baseType === 'enum') {
+    const enumMatch = chain.match(/z\.enum\s*\(\s*\[([^\]]+)\]/);
+    if (enumMatch) {
+      param.enum = enumMatch[1]
+        .split(',')
+        .map(s => s.trim().replace(/['"`]/g, ''));
+    }
+  }
+
+  // Extract min/max for numbers
+  const minMatch = chain.match(/\.min\s*\(\s*(\d+)\s*\)/);
+  if (minMatch) param.min = parseInt(minMatch[1]);
+
+  const maxMatch = chain.match(/\.max\s*\(\s*(\d+)\s*\)/);
+  if (maxMatch) param.max = parseInt(maxMatch[1]);
+
+  // Extract pattern for strings
+  const regexMatch = chain.match(/\.regex\s*\(\s*\/([^/]+)\//);
+  if (regexMatch) param.pattern = regexMatch[1];
+
+  return param;
+}
+
+function mapZodType(zodType: string): string {
+  const typeMap: Record<string, string> = {
+    'string': 'string',
+    'number': 'number',
+    'boolean': 'boolean',
+    'array': 'array',
+    'object': 'object',
+    'enum': 'enum',
+    'literal': 'literal',
+    'union': 'union',
+    'date': 'string (ISO date)',
+    'coerce': 'coerced'
+  };
+  return typeMap[zodType] || zodType;
+}
+
+// ============================================
+// Route File Extractor
+// ============================================
+
+function extractFromRouteFile(content: string, existingParams: ParameterDefinition[]): ParameterDefinition[] {
+  const params: ParameterDefinition[] = [];
+
+  // Extract query parameters from searchParams usage
+  // Pattern: searchParams.get('paramName')
+  const queryParamRegex = /searchParams\.get\s*\(\s*['"`](\w+)['"`]\s*\)/g;
+  let match;
+  while ((match = queryParamRegex.exec(content)) !== null) {
+    const name = match[1];
+    if (!existingParams.some(p => p.name === name) && !params.some(p => p.name === name)) {
+      params.push({
+        name,
+        location: 'query',
+        type: 'string',
+        required: false // Query params are typically optional
+      });
+    }
+  }
+
+  // Extract header access
+  // Pattern: request.headers.get('X-Header-Name')
+  const headerRegex = /headers\.get\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
+  while ((match = headerRegex.exec(content)) !== null) {
+    const name = match[1];
+    if (!existingParams.some(p => p.name === name) && !params.some(p => p.name === name)) {
+      params.push({
+        name,
+        location: 'header',
+        type: 'string',
+        required: false
+      });
+    }
+  }
+
+  // Extract path parameters from dynamic routes
+  // Pattern: params.paramName or { paramName } = params
+  const pathParamRegex = /params\.(\w+)|{\s*(\w+)\s*}\s*=\s*params/g;
+  while ((match = pathParamRegex.exec(content)) !== null) {
+    const name = match[1] || match[2];
+    if (!existingParams.some(p => p.name === name) && !params.some(p => p.name === name)) {
+      params.push({
+        name,
+        location: 'path',
+        type: 'string',
+        required: true // Path params are always required
+      });
+    }
+  }
+
+  return params;
+}
+
+// ============================================
+// Test File Analyzer
+// ============================================
+
+function extractTestedParams(content: string): string[] {
+  const testedParams: Set<string> = new Set();
+
+  // Find parameters in fetch/request calls
+  // Pattern: body: { param: value } or ?param=value
+  const bodyParamRegex = /body\s*:\s*(?:JSON\.stringify\s*\()?\s*\{([^}]+)\}/g;
+  let match;
+
+  while ((match = bodyParamRegex.exec(content)) !== null) {
+    const bodyContent = match[1];
+    const paramNames = bodyContent.match(/(\w+)\s*:/g);
+    if (paramNames) {
+      paramNames.forEach(p => testedParams.add(p.replace(':', '').trim()));
+    }
+  }
+
+  // Find query params in URLs
+  const queryRegex = /[?&](\w+)=/g;
+  while ((match = queryRegex.exec(content)) !== null) {
+    testedParams.add(match[1]);
+  }
+
+  // Find header params
+  const headerRegex = /['"`](X-[\w-]+|Authorization|Content-Type)['"`]\s*:/gi;
+  while ((match = headerRegex.exec(content)) !== null) {
+    testedParams.add(match[1]);
+  }
+
+  return Array.from(testedParams);
+}
+
+// ============================================
+// Main Extractor
+// ============================================
+
+function extractAllParameters(baseDir: string): ParameterMatrix {
+  console.log('🔍 Scanning for parameter sources...');
+
+  // Find files
+  const schemaFiles = findFiles(baseDir, /schema.*\.ts$|schemas?\/.*\.ts$/);
+  const routeFiles = findFiles(baseDir, /route\.(ts|tsx)$/);
+  const testFiles = findFiles(baseDir, /\.(test|spec)\.(ts|tsx)$/);
+
+  console.log(`   Found ${schemaFiles.length} schema files`);
+  console.log(`   Found ${routeFiles.length} route files`);
+  console.log(`   Found ${testFiles.length} test files`);
+
+  const endpointsMap = new Map<string, EndpointParameters>();
+
+  // Process schema files
+  for (const schemaFile of schemaFiles) {
+    const content = fs.readFileSync(schemaFile, 'utf-8');
+    const params = extractFromZodSchema(content);
+
+    if (params.length > 0) {
+      const relativePath = path.relative(baseDir, schemaFile);
+
+      // Determine endpoint from file path
+      const pathParts = relativePath.split(path.sep);
+      const apiIndex = pathParts.findIndex(p => p === 'api');
+      let endpoint = '/api/unknown';
+
+      if (apiIndex >= 0) {
+        endpoint = '/' + pathParts.slice(apiIndex).join('/').replace(/\/schema.*\.ts$/, '');
+      }
+
+      const existing = endpointsMap.get(endpoint) || {
+        endpoint,
+        method: 'POST',
+        parameters: [],
+        sourceFiles: [],
+        testedParameters: [],
+        untestedParameters: []
+      };
+
+      existing.parameters.push(...params);
+      existing.sourceFiles.push(relativePath);
+      endpointsMap.set(endpoint, existing);
+
+      console.log(`\n📄 Schema: ${relativePath}`);
+      console.log(`   Extracted ${params.length} parameters for ${endpoint}`);
+    }
+  }
+
+  // Process route files
+  for (const routeFile of routeFiles) {
+    const content = fs.readFileSync(routeFile, 'utf-8');
+    const relativePath = path.relative(baseDir, routeFile);
+
+    // Determine endpoint
+    const pathParts = relativePath.split(path.sep);
+    const apiIndex = pathParts.findIndex(p => p === 'api');
+    let endpoint = '/api/unknown';
+
+    if (apiIndex >= 0) {
+      endpoint = '/' + pathParts.slice(apiIndex, -1).join('/');
+    }
+
+    const existing = endpointsMap.get(endpoint) || {
+      endpoint,
+      method: 'GET',
+      parameters: [],
+      sourceFiles: [],
+      testedParameters: [],
+      untestedParameters: []
+    };
+
+    // Determine method
+    if (content.includes('export async function POST') || content.includes('export const POST')) {
+      existing.method = 'POST';
+    }
+
+    const routeParams = extractFromRouteFile(content, existing.parameters);
+    existing.parameters.push(...routeParams);
+    if (!existing.sourceFiles.includes(relativePath)) {
+      existing.sourceFiles.push(relativePath);
+    }
+
+    endpointsMap.set(endpoint, existing);
+
+    if (routeParams.length > 0) {
+      console.log(`\n📄 Route: ${relativePath}`);
+      console.log(`   Extracted ${routeParams.length} additional parameters`);
+    }
+  }
+
+  // Process test files to find tested parameters
+  for (const testFile of testFiles) {
+    const content = fs.readFileSync(testFile, 'utf-8');
+    const relativePath = path.relative(baseDir, testFile);
+
+    // Determine endpoint from test file
+    const endpointMatch = content.match(/(?:\/api\/[\w\/-]+)/);
+    if (!endpointMatch) continue;
+
+    const endpoint = endpointMatch[0];
+    const existing = endpointsMap.get(endpoint);
+
+    if (existing) {
+      const testedParams = extractTestedParams(content);
+      existing.testedParameters = [...new Set([...existing.testedParameters, ...testedParams])];
+
+      console.log(`\n🧪 Test: ${relativePath}`);
+      console.log(`   Found ${testedParams.length} tested parameters`);
+    }
+  }
+
+  // Calculate untested parameters and coverage
+  let totalParams = 0;
+  let testedParams = 0;
+
+  const endpoints = Array.from(endpointsMap.values()).map(ep => {
+    const allParamNames = ep.parameters.map(p => p.name);
+    ep.untestedParameters = allParamNames.filter(p => !ep.testedParameters.includes(p));
+
+    totalParams += ep.parameters.length;
+    testedParams += ep.testedParameters.length;
+
+    return ep;
+  });
+
+  return {
+    version: '3.0.0',
+    generatedAt: new Date().toISOString(),
+    endpoints,
+    coverage: {
+      totalParameters: totalParams,
+      testedParameters: testedParams,
+      coveragePercent: totalParams > 0 ? Math.round((testedParams / totalParams) * 100) : 0
+    }
+  };
+}
+
+// ============================================
+// CLI Entry Point
+// ============================================
+
+function main() {
+  const args = process.argv.slice(2);
+  const baseDir = args[0] || process.cwd();
+  const outputPath = args[1] || path.join(baseDir, 'src', 'app', 'api-test', 'parameter-matrix.json');
+
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('  📊 Parameter Matrix Extractor');
+  console.log('  @hustle-together/api-dev-tools v3.0');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log(`\n📁 Base directory: ${baseDir}`);
+  console.log(`📄 Output file: ${outputPath}\n`);
+
+  const matrix = extractAllParameters(baseDir);
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write matrix
+  fs.writeFileSync(outputPath, JSON.stringify(matrix, null, 2));
+
+  console.log('\n═══════════════════════════════════════════════════════════════');
+  console.log('  ✅ Parameter matrix generated successfully!');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log(`\n📊 Coverage Summary:`);
+  console.log(`   • Total parameters: ${matrix.coverage.totalParameters}`);
+  console.log(`   • Tested parameters: ${matrix.coverage.testedParameters}`);
+  console.log(`   • Coverage: ${matrix.coverage.coveragePercent}%`);
+
+  // List untested parameters
+  const untested = matrix.endpoints.flatMap(ep =>
+    ep.untestedParameters.map(p => `${ep.endpoint}: ${p}`)
+  );
+
+  if (untested.length > 0) {
+    console.log(`\n⚠️  Untested parameters (${untested.length}):`);
+    untested.slice(0, 10).forEach(p => console.log(`   • ${p}`));
+    if (untested.length > 10) {
+      console.log(`   ... and ${untested.length - 10} more`);
+    }
+  }
+
+  console.log(`\n📄 Output: ${outputPath}\n`);
+}
+
+main();