@codeyam/codeyam-cli 0.1.0-staging.1 → 0.1.0-staging.28f73cf

package/analyzer-template/packages/utils/index.ts

@@ -1,3 +1,4 @@
+export { default as Semaphore } from './src/lib/Semaphore';
 export { default as isRemixRoute } from './src/lib/frameworks/isRemixRoute';
 export { default as isNextRoute } from './src/lib/frameworks/isNextRoute';
 export { default as isFrameworkRoute } from './src/lib/frameworks/isFrameworkRoute';
@@ -7,6 +8,7 @@ export { default as frameworkRouteFileNameToRoute } from './src/lib/frameworks/f
 export { default as getRemixRoutePath } from './src/lib/frameworks/getRemixRoutePath';
 export { default as getNextRoutePath } from './src/lib/frameworks/getNextRoutePath';
 export { default as getFrameworkRoutePath } from './src/lib/frameworks/getFrameworkRoutePath';
+export { default as sanitizeNextRouteSegments } from './src/lib/frameworks/sanitizeNextRouteSegments';
 export { default as safeFileName } from './src/lib/safeFileName';
 export { default as normalizeKey } from './src/lib/normalizeKey';
 export {

package/analyzer-template/packages/utils/src/lib/Semaphore.ts

@@ -0,0 +1,42 @@
+/**
+ * An async semaphore for limiting concurrent access to a resource.
+ *
+ * Useful for controlling parallelism when some operations are CPU-bound
+ * and shouldn't all run simultaneously, while allowing I/O-bound operations
+ * to proceed freely.
+ */
+export default class Semaphore {
+  private count: number;
+  private waiting: Array<() => void> = [];
+
+  constructor(count: number) {
+    this.count = count;
+  }
+
+  /**
+   * Acquire a permit from the semaphore.
+   * If a permit is available, returns immediately.
+   * Otherwise, blocks until a permit becomes available.
+   */
+  async acquire(): Promise<void> {
+    if (this.count > 0) {
+      this.count--;
+      return;
+    }
+    await new Promise<void>((resolve) => this.waiting.push(resolve));
+  }
+
+  /**
+   * Release a permit back to the semaphore.
+   * If there are waiters, the first one in line gets the permit.
+   * Otherwise, increments the available count.
+   */
+  release(): void {
+    const next = this.waiting.shift();
+    if (next) {
+      next();
+    } else {
+      this.count++;
+    }
+  }
+}

package/analyzer-template/packages/utils/src/lib/frameworks/getNextRoutePath.ts

@@ -1,4 +1,4 @@
-import { safeFileName } from '~codeyam/utils';
+import { getAppDirectoryForFile, safeFileName } from '~codeyam/utils';
 import {
   Analysis,
   ReadonlyEntity,
@@ -7,6 +7,7 @@ import {
   ProjectFramework,
 } from '~codeyam/types';
 import { PROJECT_RELATIVE_PATH } from '~codeyam/utils';
+import sanitizeNextRouteSegments from './sanitizeNextRouteSegments';
 
 export default function getNextRoutePath({
   file,
@@ -24,11 +25,15 @@ export default function getNextRoutePath({
   framework: ProjectFramework;
   scenario?: { name: string };
 }) {
-  const routePath = file.path.split('/').slice(1);
+  const routePath = sanitizeNextRouteSegments(file.path.split('/').slice(1));
   const scenarioSlug = scenario ? safeFileName(scenario.name) : undefined;
+  const appDirectory = getAppDirectoryForFile(
+    file.path,
+    project.metadata?.webapps,
+  );
   const pathComponents = [
     PROJECT_RELATIVE_PATH,
-    'app',
+    appDirectory,
     'static',
     project.slug,
     rootAnalysis.id,

package/analyzer-template/packages/utils/src/lib/frameworks/getRemixRoutePath.ts

@@ -31,7 +31,8 @@ export default function getRemixRoutePath({
   const route = file.path.slice(routesIndex);
   const cleanRoute = route
     .replace(/\//g, '.')
-    .replace('$', '')
+    .replace(/\$(\w+)/g, '$1') // $slug -> slug (named params)
+    .replace(/\$/g, 'splat') // bare $ -> splat (catch-all)
     .replace(/_/g, 'x');
 
   const scenarioSlug = scenario ? `.${safeFileName(scenario.name)}` : '';

package/analyzer-template/packages/utils/src/lib/frameworks/nextRouteFileNameToRoute.ts

@@ -1,5 +1,6 @@
 import { Analysis, File } from '~codeyam/types';
 import safeFileName from '../safeFileName';
+import sanitizeNextRouteSegments from './sanitizeNextRouteSegments';
 
 export default function nextRouteFileNameToRoute(
   projectSlug: string,
@@ -7,7 +8,7 @@ export default function nextRouteFileNameToRoute(
   analysis: Analysis,
   scenarioName?: string,
 ) {
-  const route = file.path.split('/').slice(1, -1);
+  const route = sanitizeNextRouteSegments(file.path.split('/').slice(1, -1));
   const pathComponents = [
     'static',
     projectSlug,

package/analyzer-template/packages/utils/src/lib/frameworks/remixRouteFileNameToRoute.ts

@@ -20,6 +20,7 @@ export default function remixRouteFileNameToRoute(
       .replace(/\(\$(\w+)\)/g, '$1')
       .replace(/\$(\w+)/g, '$1')
       .replace(/\((\w+)\)/g, '$1')
+      .replace(/\$/g, 'splat')
       .replace(/_/g, 'x'),
     'default',
   ].filter(Boolean);

package/analyzer-template/packages/utils/src/lib/frameworks/sanitizeNextRouteSegments.ts

@@ -0,0 +1,33 @@
+/**
+ * Sanitize Next.js route path segments to remove special syntax.
+ * - Route groups (folder) become folder (strip parens, keep name)
+ * - Dynamic segments [param] become param0 (suffix avoids Next.js private folder convention)
+ * - Catch-all [...slug] becomes slug0
+ * - Optional catch-all [[...slug]] becomes slug0
+ *
+ * Note: We use suffix "0" instead of prefix "_" because Next.js treats folders
+ * starting with underscore as private segments that are excluded from routing.
+ */
+export default function sanitizeNextRouteSegments(
+  segments: string[],
+): string[] {
+  return segments.map((segment) => {
+    // Handle route groups (folder) - strip parens, keep name
+    const routeGroup = segment.match(/^\(([^)]+)\)$/);
+    if (routeGroup) return routeGroup[1];
+
+    // Handle optional catch-all [[...param]]
+    const optionalCatchAll = segment.match(/^\[\[\.\.\.([\w]+)\]\]$/);
+    if (optionalCatchAll) return `${optionalCatchAll[1]}0`;
+
+    // Handle catch-all [...param]
+    const catchAll = segment.match(/^\[\.\.\.([\w]+)\]$/);
+    if (catchAll) return `${catchAll[1]}0`;
+
+    // Handle dynamic [param]
+    const dynamic = segment.match(/^\[([\w]+)\]$/);
+    if (dynamic) return `${dynamic[1]}0`;
+
+    return segment;
+  });
+}

package/analyzer-template/project/constructMockCode.ts

@@ -18,6 +18,7 @@ interface ReturnValuePart {
   nested?: ReturnValuePart[];
   isAsyncFunction?: boolean;
   isStructural?: boolean;
+  hasNoReturnData?: boolean; // true when function has only signature entries, no functionCallReturnValue
   // Maps literal argument values to their specific nested structures for conditional dispatch
   argVariants?: Map<string, ReturnValuePart[]>;
 }
@@ -273,7 +274,15 @@ export default function constructMockCode(
       }
 
       const addReturnValueFunctionAccessor = (dataPath: string) => {
-        if (returnValue.returnsFunctionArgs) {
+        // Add function call accessor if:
+        // - There are actual arguments, OR
+        // - This is a callable (not a method that returns an array directly)
+        // For methods like getAll() that return arrays, the data is at ["getAll()"] not ["getAll()"]["()"]
+        if (
+          returnValue.returnsFunctionArgs &&
+          (returnValue.returnsFunctionArgs.length > 0 ||
+            !returnValue.returnsFunctionArray)
+        ) {
           if (returnValue.isArray) {
             dataPath = `${dataPath}${optionalAccess('[0]')}`;
           }
@@ -313,6 +322,7 @@ export default function constructMockCode(
         returnsFunctionArgs,
         returnsFunctionArray,
         isAsyncFunction,
+        hasNoReturnData,
       } = returnValue;
 
       const nestedContent: (string | undefined)[] = (nested ?? []).map(
@@ -325,9 +335,53 @@ export default function constructMockCode(
         },
       );
 
+      // Array prototype methods that should be ignored when building mocks
+      // (these work on any array - we don't need to mock them)
+      const ARRAY_PROTOTYPE_METHODS = new Set([
+        'at',
+        'concat',
+        'copyWithin',
+        'entries',
+        'every',
+        'fill',
+        'filter',
+        'find',
+        'findIndex',
+        'findLast',
+        'findLastIndex',
+        'flat',
+        'flatMap',
+        'forEach',
+        'includes',
+        'indexOf',
+        'join',
+        'keys',
+        'lastIndexOf',
+        'map',
+        'pop',
+        'push',
+        'reduce',
+        'reduceRight',
+        'reverse',
+        'shift',
+        'slice',
+        'some',
+        'sort',
+        'splice',
+        'toLocaleString',
+        'toReversed',
+        'toSorted',
+        'toSpliced',
+        'toString',
+        'unshift',
+        'values',
+        'with',
+        'length',
+      ]);
+
       const levelContentItems = [];
       // Add spread for data paths when:
-      // - Not a function returning an array
+      // - Not a function returning an array, OR function returns array with custom methods
       // - Has function args OR not an array
       // - Not structural, OR is a structural [0] element with nested content
       //   (array elements with nested functions need their other properties spread)
@@ -336,8 +390,20 @@ export default function constructMockCode(
         returnValue.name === '[0]' &&
         nested &&
         nested.length > 0;
+      // Check if function returns array but has custom methods (not just array prototype methods)
+      // Excludes array indices like [0], [1], [] which are not methods
+      const hasCustomMethodsOnArrayReturn =
+        returnsFunctionArray &&
+        nested &&
+        nested.length > 0 &&
+        nested.some((n) => {
+          // Skip array indices - they're not methods
+          if (n.name.match(/^\[\d*\]$/)) return false;
+          const methodName = n.name.replace(/[<(].*$/, '');
+          return !ARRAY_PROTOTYPE_METHODS.has(methodName);
+        });
       if (
-        !returnsFunctionArray &&
+        (!returnsFunctionArray || hasCustomMethodsOnArrayReturn) &&
         (returnsFunctionArgs || !isArray) &&
         (!returnValue.isStructural || isStructuralArrayElementWithNested)
       ) {
@@ -352,14 +418,35 @@ export default function constructMockCode(
           .join(', ');
         let funcContents = '';
         if (returnsFunctionArray) {
-          if (levelContents.length === 0) {
+          if (hasNoReturnData) {
+            // Function has no return data (only signatures) - return empty array
+            funcContents = 'return []';
+          } else if (levelContents.length === 0 && dataPaths.length === 1) {
+            // When returning an array with no nested content, return the data path directly
+            // (the data path points to the array in scenario data)
+            funcContents = `return ${dataPaths[0]}`;
+          } else if (levelContents.length === 0) {
             funcContents = 'return []';
           } else {
             funcContents = `return [\n${indent(levelContents)}\n]`;
           }
         } else {
+          // Check if function has no actual return data (only signatures)
+          const hasNestedItems = nested && nested.length > 0;
+          const hasActualNestedContent =
+            nestedContent.filter(Boolean).length > 0;
+
           if (levelContentItems.length === 1 && dataPaths.length === 1) {
-            funcContents = `return ${dataPaths[0]}`;
+            if (
+              hasNoReturnData ||
+              (hasNestedItems && !hasActualNestedContent)
+            ) {
+              // Function has no return data (only signatures) - return empty array
+              funcContents = 'return []';
+            } else {
+              // Has return data - return data path
+              funcContents = `return ${dataPaths[0]}`;
+            }
           } else {
             funcContents = `return {\n${indent(levelContents)}\n}`;
           }
@@ -372,6 +459,17 @@ export default function constructMockCode(
         }
       }
 
+      // Check if all nested items are array prototype methods
+      const hasOnlyArrayPrototypeMethods =
+        returnsFunctionArray &&
+        nested &&
+        nested.length > 0 &&
+        nested.every((n) => {
+          // Extract method name before type params and args (e.g., "reduce<...>(...)" -> "reduce")
+          const methodName = n.name.replace(/[<(].*$/, '');
+          return ARRAY_PROTOTYPE_METHODS.has(methodName);
+        });
+
       let returnValueContents = '';
       if (
         !returnsFunctionArgs &&
@@ -379,6 +477,16 @@ export default function constructMockCode(
         dataPaths.length === 1
       ) {
         returnValueContents = dataPaths[0];
+      } else if (
+        returnsFunctionArray &&
+        dataPaths.length === 1 &&
+        !root &&
+        (!nested || nested.length === 0 || hasOnlyArrayPrototypeMethods)
+      ) {
+        // Nested method returns an array - return the data path directly
+        // Only if nested content is empty or only contains array prototype methods
+        // (like .reduce() which work on any array - we don't need to mock them)
+        returnValueContents = dataPaths[0];
       } else {
         if (isArray) {
           // When GENERIC array (using []) has nested content (like functions that need wrapping),
@@ -687,6 +795,25 @@ export default function constructMockCode(
           if (returnValueSection.returnsFunctionArgs && value === 'array') {
             returnValueSection.returnsFunctionArray = true;
           }
+
+          // Check if this function call has actual return data in the schema
+          // If the path only has .signature entries (no .functionCallReturnValue), mark as no return data
+          // Use parts[i] (original part) instead of modified 'part' to include array indices like [1]
+          const functionCallPath = joinParenthesesAndArrays([
+            ...parts.slice(0, i),
+            parts[i], // Use original part which may include [1](args) together
+          ]);
+          // Check if there's a .functionCallReturnValue AFTER this function call path
+          const hasFunctionCallReturnValue = Object.keys(
+            relevantReturnValueSchema,
+          ).some((k) => {
+            if (!k.startsWith(functionCallPath)) return false;
+            const afterPath = k.slice(functionCallPath.length);
+            return afterPath.startsWith('.functionCallReturnValue');
+          });
+          if (!hasFunctionCallReturnValue) {
+            returnValueSection.hasNoReturnData = true;
+          }
         }
 
         if (nextIsDifferentiatedArray || hasNestedFunction) {
@@ -841,6 +968,26 @@ export default function constructMockCode(
       }
 
       if (!hasNestedFunction) {
+        // Before breaking, check if this function returns an array
+        // by looking for a functionCallReturnValue: 'array' entry in the schema
+        if (relevantPart && part.endsWith(')')) {
+          const functionReturnPath = joinParenthesesAndArrays([
+            ...parts.slice(0, i + 1),
+            RETURN_VALUE,
+          ]);
+          const returnType = relevantReturnValueSchema[functionReturnPath];
+          if (returnType === 'array') {
+            // Only set returnsFunctionArray if the array contains plain data,
+            // NOT if it contains functions (which need wrapping)
+            const arrayElementPath = `${functionReturnPath}[]`;
+            const arrayElementType =
+              relevantReturnValueSchema[arrayElementPath];
+            // If array element is a function, we need to wrap it - don't set returnsFunctionArray
+            if (arrayElementType !== 'function') {
+              relevantPart.returnsFunctionArray = true;
+            }
+          }
+        }
         break;
       }
 
@@ -884,7 +1031,24 @@ export default function constructMockCode(
 
     return `const ${mockNameParts[0]} = {\n${indent(returnParts.join(',\n'))}\n};`;
   } else if (isFunction) {
-    return `const ${mockName}ReturnValue = ${contents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
+    // For headers() and cookies() from next/headers, add common iterator methods
+    // These are needed when the mock is passed to functions that use .entries(), .keys(), etc.
+    // (e.g., Object.fromEntries(headers.entries()) in buildLegacyHeaders)
+    const needsIteratorMethods =
+      mockName === 'headers' || mockName === 'cookies';
+    let enhancedContents = contents;
+    if (needsIteratorMethods && contents.trim().startsWith('{')) {
+      // Add iterator methods that operate on the scenario data
+      const iteratorMethods = `,
+  entries: () => Object.entries(scenarios().data()?.["${mockName}()"] || {}),
+  keys: () => Object.keys(scenarios().data()?.["${mockName}()"] || {}),
+  values: () => Object.values(scenarios().data()?.["${mockName}()"] || {}),
+  forEach: (fn) => Object.entries(scenarios().data()?.["${mockName}()"] || {}).forEach(([k, v]) => fn(v, k)),
+  has: (key) => Object.prototype.hasOwnProperty.call(scenarios().data()?.["${mockName}()"] || {}, key)`;
+      // Insert before the closing brace (handle trailing whitespace)
+      enhancedContents = contents.replace(/\}\s*$/, iteratorMethods + '\n}');
+    }
+    return `const ${mockName}ReturnValue = ${enhancedContents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
   } else {
     return `const ${mockName} = ${contents}`;
   }

package/analyzer-template/project/reconcileMockDataKeys.ts

@@ -46,8 +46,10 @@ export function reconcileMockDataKeys(
  * - Extract function name and first argument(s)
  * - Ignore the last argument value (could be literal or variable)
  * - Match based on the common prefix
+ * - If key has no parentheses, try matching with "()" appended
  *
  * e.g., "eq('user_id', 'user-12345')" matches "eq('user_id', user.id)"
+ * e.g., "getAll" matches "getAll()"
  */
 function findClosestKey(key: string, expectedKeys: string[]): string | null {
   const keyBase = extractKeyBase(key);
@@ -60,6 +62,17 @@ function findClosestKey(key: string, expectedKeys: string[]): string | null {
     }
   }
 
+  // If no match found and key has no parentheses, try matching with "()" appended
+  // This handles the case where LLM generates "getAll" but expected key is "getAll()"
+  if (!key.includes('(')) {
+    const keyWithParens = key + '()';
+    for (const expected of expectedKeys) {
+      if (expected === keyWithParens) {
+        return expected;
+      }
+    }
+  }
+
   return null;
 }
 

package/analyzer-template/project/start.ts

@@ -378,17 +378,7 @@ async function main({
       });
       updateBackgroundJobProgress(backgroundJob, {
         initiated: backgroundJob.progress.initiated,
-        steps: [
-          {
-            name: 'build-project',
-            initiated:
-              backgroundJob.progress.steps.find(
-                (s) => s.name === 'build-project',
-              )?.initiated ?? new Date().toISOString(),
-            error: error.message,
-            completed: new Date().toISOString(),
-          },
-        ],
+        steps: [],
         completed: new Date().toISOString(),
       }).catch(() => {});
     }

package/analyzer-template/project/startScenarioCapture.ts

@@ -24,6 +24,11 @@ import {
 } from '~codeyam/utils';
 import getAppPath from './getAppPath';
 import { restoreAllBackups, restoreFromBackup } from './backupFiles';
+import {
+  readTrackingFile,
+  writeTrackingFile,
+  clearTrackingFile,
+} from './trackGeneratedFiles';
 import captureLibraryFunctionDirect from './captureLibraryFunctionDirect';
 import {
   getFrameworkForComponent,
@@ -79,6 +84,21 @@ export async function startScenarioCapture({
     restoreAllBackups(fullPath);
   }
 
+  // Clean up any leftover generated files from previous debug sessions
+  const previouslyTracked = readTrackingFile();
+  if (previouslyTracked) {
+    awsLog('CodeYam: Cleaning up files from previous session', {
+      generatedCount: previouslyTracked.generatedFiles.length,
+      backupCount: previouslyTracked.backupFiles.length,
+      timestamp: previouslyTracked.timestamp,
+    });
+    removeScenario(previouslyTracked.generatedFiles);
+    for (const backupPath of previouslyTracked.backupFiles) {
+      restoreFromBackup(backupPath);
+    }
+    clearTrackingFile();
+  }
+
   const sortedReadyToBeCaptured = readyToBeCaptured.sort((a, b) => {
     if (a.indirect !== b.indirect) {
       return a.indirect ? 1 : -1;
@@ -446,6 +466,9 @@ export async function startScenarioCapture({
         controller?.port,
       );
       allGeneratedFiles.push(codeyamPagePath);
+
+      // Persist file tracking for crash/debug recovery
+      writeTrackingFile(allGeneratedFiles, backupFiles);
     }
 
     // Skip if no scenarios to capture
@@ -565,6 +588,7 @@ export async function startScenarioCapture({
         for (const backupPath of backupsToRestore) {
           restoreFromBackup(backupPath);
         }
+        clearTrackingFile();
       }
     };
 

package/analyzer-template/project/trackGeneratedFiles.ts

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs';
+
+const TRACKING_FILE_PATH = '../project/.codeyam-generated-files.json';
+
+export interface TrackedFiles {
+  generatedFiles: string[];
+  backupFiles: string[];
+  timestamp: string;
+}
+
+export function getTrackingFilePath(): string {
+  return TRACKING_FILE_PATH;
+}
+
+export function writeTrackingFile(
+  generatedFiles: string[],
+  backupFiles: string[],
+): void {
+  const data: TrackedFiles = {
+    generatedFiles,
+    backupFiles,
+    timestamp: new Date().toISOString(),
+  };
+  writeFileSync(TRACKING_FILE_PATH, JSON.stringify(data, null, 2), 'utf8');
+}
+
+export function readTrackingFile(): TrackedFiles | null {
+  if (!existsSync(TRACKING_FILE_PATH)) return null;
+  try {
+    const content = readFileSync(TRACKING_FILE_PATH, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+export function clearTrackingFile(): void {
+  if (existsSync(TRACKING_FILE_PATH)) {
+    unlinkSync(TRACKING_FILE_PATH);
+  }
+}