@codeyam/codeyam-cli 0.1.0-staging.dd216e0 → 0.1.0-staging.e090cb3

package/analyzer-template/packages/utils/dist/types/src/types/ScenariosDataStructure.d.ts

@@ -14,8 +14,158 @@ export interface ConditionalUsage {
     conditionType: 'truthiness' | 'comparison' | 'switch';
     /** For comparison conditions, the literal values being compared against */
     comparedValues?: string[];
-    /** Where this conditional usage occurs */
-    location: 'if' | 'ternary' | 'logical-and' | 'switch';
+    /** Where this conditional usage occurs. 'unconditional' is for always-rendered children with data props. */
+    location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
+    /** Source location information for this conditional usage */
+    sourceLocation?: {
+        /** Line number (1-based) */
+        lineNumber: number;
+        /** Column number (0-based) */
+        column: number;
+        /** The code snippet containing this conditional */
+        codeSnippet: string;
+    };
+    /** Unique ID for this compound conditional chain (shared by all conditions in same && chain) */
+    chainId?: string;
+    /** Position in the chain (0 = leftmost) */
+    chainPosition?: number;
+    /** Total number of conditions in this chain */
+    chainLength?: number;
+    /** The full original expression (e.g., "a && b && c") */
+    chainExpression?: string;
+    /** Whether this condition is negated (e.g., !foo) */
+    isNegated?: boolean;
+    /**
+     * Whether this conditional controls JSX rendering.
+     * True when the conditional appears in a JSX expression like {cond && <Component />}
+     * or {cond ? <A /> : <B />}. Used to identify high-impact execution flows.
+     */
+    controlsJsxRendering?: boolean;
+    /**
+     * Information about how this variable was derived from other variables.
+     * Used to trace derived boolean variables back to their data sources.
+     *
+     * Examples:
+     * - `const hasAnalysis = analysis !== null` → { sourcePath: 'analysis', operation: 'notNull' }
+     * - `const isLoading = status === 'loading'` → { sourcePath: 'status', operation: 'equals', comparedValue: 'loading' }
+     * - `const isBusy = isRunning || isQueued` → { operation: 'or', sourcePaths: ['isRunning', 'isQueued'] }
+     */
+    derivedFrom?: {
+        /** For single-source derivations (notNull, equals, etc.) */
+        sourcePath?: string;
+        /** For multi-source derivations (or, and) */
+        sourcePaths?: string[];
+        /** The operation that derived this variable */
+        operation: 'notNull' | 'isNull' | 'equals' | 'notEquals' | 'or' | 'and' | 'arrayIncludes' | 'arraySome' | 'arrayEvery' | 'arrayLength';
+        /** For comparison operations, the value being compared to */
+        comparedValue?: string;
+    };
+    /**
+     * The full original expression as a semantic constraint for LLM reasoning.
+     * Used when the path contains complex operations (filter, map, etc.) that
+     * can't be simply resolved to a mock value.
+     *
+     * Examples:
+     * - `scenarios.filter(s => s.active).length > 1`
+     * - `users.some(u => u.role === 'admin' && u.active)`
+     *
+     * The LLM can interpret this constraint to generate appropriate mock data.
+     */
+    constraintExpression?: string;
+}
+/**
+ * Represents a compound conditional (e.g., a && b && c) where all conditions
+ * must be satisfied together for a code path to execute.
+ */
+export interface CompoundConditional {
+    /** Unique identifier for this compound conditional */
+    chainId: string;
+    /** The full expression (e.g., "scenarios.length > 0 && !displayState.isQueued") */
+    expression: string;
+    /** Individual conditions in order */
+    conditions: {
+        path: string;
+        conditionType: 'truthiness' | 'comparison' | 'switch';
+        comparedValues?: string[];
+        isNegated: boolean;
+        /** Required value for this condition to be true */
+        requiredValue?: string | boolean;
+    }[];
+    /** Where this compound conditional occurs. 'unconditional' is for always-rendered children. */
+    location: 'if' | 'ternary' | 'logical-and' | 'switch' | 'unconditional';
+    /** Source location for the entire compound expression */
+    sourceLocation: {
+        lineNumber: number;
+        column: number;
+        codeSnippet: string;
+    };
+    /**
+     * Whether this compound conditional controls JSX rendering.
+     * True when the conditional appears in a JSX expression like {a && b && <Component />}
+     * Used to identify high-impact execution flows.
+     */
+    controlsJsxRendering?: boolean;
+}
+/**
+ * Represents the effect of a setter call within a conditional block.
+ * This tracks what state changes occur when specific conditions are met.
+ *
+ * Example: if (data.success) { setShowModal(true); }
+ * - condition: data.success = truthy
+ * - effect: setShowModal called with true
+ */
+export interface ConditionalEffect {
+    /**
+     * Single condition that controls this effect.
+     * Use this for simple if statements with a single condition.
+     */
+    condition?: {
+        /** The path being checked (e.g., "data.success") */
+        path: string;
+        /** Type of condition check */
+        conditionType: 'truthiness' | 'comparison' | 'switch';
+        /** Values being compared against (for comparison/switch) */
+        comparedValues?: string[];
+        /** The value required for this effect to occur */
+        requiredValue: string | boolean;
+    };
+    /**
+     * Multiple conditions that all must be true for this effect.
+     * Use this for compound conditions (a && b && c).
+     */
+    conditions?: Array<{
+        /** The path being checked */
+        path: string;
+        /** Type of condition check */
+        conditionType: 'truthiness' | 'comparison' | 'switch';
+        /** Values being compared against */
+        comparedValues?: string[];
+        /** The value required for this condition to be true */
+        requiredValue: string | boolean;
+    }>;
+    /**
+     * The effect that occurs when the condition(s) are met.
+     */
+    effect: {
+        /** Type of effect - currently only 'setter' for useState setters */
+        type: 'setter';
+        /** The state variable name (e.g., "showModal" from [showModal, setShowModal]) */
+        stateVariable: string;
+        /** The setter function name (e.g., "setShowModal") */
+        setterName: string;
+        /** The value being set (literal or expression text) */
+        value: string;
+        /** The type of value being set */
+        valueType: 'string' | 'number' | 'boolean' | 'null' | 'dynamic';
+    };
+    /**
+     * Source location for this conditional effect
+     */
+    sourceLocation?: {
+        lineNumber: number;
+        column: number;
+        codeSnippet: string;
+    };
 }
 export interface DataStructure {
     signatureSchema: {
@@ -25,7 +175,7 @@ export interface DataStructure {
         [key: string]: string;
     };
     equivalentSignatureVariables: {
-        [key: string]: string;
+        [key: string]: string | string[];
     };
     usageEquivalencies?: {
         [key: string]: {
@@ -68,7 +218,53 @@ export interface DataStructure {
     conditionalUsages?: {
         [attributePath: string]: ConditionalUsage[];
     };
+    /** Compound conditionals grouped by chain (all conditions must be true together) */
+    compoundConditionals?: CompoundConditional[];
+    /** Conditional effects - tracks what setter calls happen inside conditionals */
+    conditionalEffects?: ConditionalEffect[];
+    /** Gating conditions for child components - maps child component names to the conditions that must be true for them to render */
+    childBoundaryGatingConditions?: {
+        [childComponentName: string]: ConditionalUsage[];
+    };
+    /** JSX rendering usages - arrays rendered via .map() and strings interpolated in JSX */
+    jsxRenderingUsages?: JsxRenderingUsage[];
+    /** Derived variables - maps variable names to their derivation info (e.g., hasAnalysis -> { sourcePath: 'analysis', operation: 'notNull' }) */
+    derivedVariables?: {
+        [variableName: string]: {
+            sourcePath?: string;
+            sourcePaths?: string[];
+            operation: 'notNull' | 'isNull' | 'equals' | 'notEquals' | 'or' | 'and' | 'arrayIncludes' | 'arraySome' | 'arrayEvery' | 'arrayLength';
+            comparedValue?: string;
+        };
+    };
     structure?: any;
     mocksDataStructure?: any;
 }
+/**
+ * Represents a JSX rendering usage where arrays or strings are rendered directly.
+ * Used to generate execution flows for array sizes and text lengths
+ * even without explicit conditionals.
+ *
+ * Examples:
+ * - `{items.map(i => <Item {...i} />)}` → array-map usage for 'items'
+ * - `{user.name}` → text-interpolation usage for 'user.name'
+ */
+export interface JsxRenderingUsage {
+    /** The path to the rendered value (e.g., "items", "data.users", "user.name") */
+    path: string;
+    /**
+     * Type of rendering:
+     * - 'array-map': Array rendered via .map() method
+     * - 'text-interpolation': String rendered directly in JSX
+     */
+    renderingType: 'array-map' | 'text-interpolation';
+    /** The detected type of the value being rendered */
+    valueType?: 'array' | 'string' | 'unknown';
+    /** Source location information */
+    sourceLocation?: {
+        lineNumber: number;
+        column: number;
+        codeSnippet: string;
+    };
+}
 //# sourceMappingURL=ScenariosDataStructure.d.ts.map

package/analyzer-template/packages/utils/dist/types/src/types/ScenariosDataStructure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScenariosDataStructure.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/ScenariosDataStructure.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,aAAa,EAAE,YAAY,GAAG,YAAY,GAAG,QAAQ,CAAC;IACtD,2EAA2E;IAC3E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;CACvD;AAED,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC3C,iBAAiB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC7C,4BAA4B,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACxD,kBAAkB,CAAC,EAAE;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAChE,CAAC;IACF,mBAAmB,CAAC,EAAE;QACpB,CAAC,GAAG,EAAE,MAAM,GAAG;YAAE,aAAa,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KAChE,CAAC;IACF,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,iBAAiB,EAAE;QACjB,CAAC,kBAAkB,EAAE,MAAM,GAAG;YAC5B,CAAC,oBAAoB,EAAE,MAAM,GAAG;gBAC9B,eAAe,EAAE;oBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;iBAAE,CAAC;gBAC3C,iBAAiB,EAAE;oBAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;iBAAE,CAAC;gBAC7C,kBAAkB,CAAC,EAAE;oBACnB,CAAC,GAAG,EAAE,MAAM,GAAG;wBAAE,aAAa,EAAE,MAAM,CAAC;wBAAC,UAAU,EAAE,MAAM,CAAA;qBAAE,EAAE,CAAC;iBAChE,CAAC;gBACF,mBAAmB,CAAC,EAAE;oBACpB,CAAC,GAAG,EAAE,MAAM,GAAG;wBAAE,aAAa,EAAE,MAAM,CAAC;wBAAC,UAAU,EAAE,MAAM,CAAA;qBAAE,EAAE,CAAC;iBAChE,CAAC;aACH,CAAC;SACH,CAAC;KACH,CAAC;IACF,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE;QAAE,CAAC,aAAa,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAAA;KAAE,CAAC;IACpE,SAAS,CAAC,EAAE,GAAG,CAAC;IAChB,kBAAkB,CAAC,EAAE,GAAG,CAAC;CAC1B"}
+{"version":3,"file":"ScenariosDataStructure.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/ScenariosDataStructure.ts"],"names":[],"mappings":"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"}

package/analyzer-template/packages/utils/dist/types/src/types/ScopeAnalysis.d.ts

@@ -4,8 +4,13 @@ export interface ScopeAnalysis {
     isolatedStructure: {
         [key: string]: string;
     };
+    /**
+     * Maps variable names to their equivalent paths.
+     * Supports multiple equivalencies per key (e.g., for OR expressions like `x = a || b`
+     * where x is equivalent to both a and b).
+     */
     isolatedEquivalentVariables: {
-        [key: string]: string;
+        [key: string]: string | string[];
     };
     llmCalls: LlmCall[];
     environmentVariables: string[];

package/analyzer-template/packages/utils/dist/types/src/types/ScopeAnalysis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScopeAnalysis.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/ScopeAnalysis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC7C,2BAA2B,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvD,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC"}
+{"version":3,"file":"ScopeAnalysis.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/ScopeAnalysis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,WAAW,aAAa;IAC5B,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,iBAAiB,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC7C;;;;OAIG;IACH,2BAA2B,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,CAAA;KAAE,CAAC;IAClE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC"}

package/analyzer-template/packages/utils/dist/types/src/types/StatementInfo.d.ts

@@ -5,6 +5,8 @@ export interface StatementInfo {
     name?: string;
     childBoundaries: {
         name?: string;
+        /** The synthetic scope name (e.g., 'cyScope1') if JSX was extracted */
+        syntheticName?: string;
         start: number;
         end: number;
     }[];

package/analyzer-template/packages/utils/dist/types/src/types/StatementInfo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StatementInfo.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/StatementInfo.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,EAAE,CAAC;CACL"}
+{"version":3,"file":"StatementInfo.d.ts","sourceRoot":"","sources":["../../../../../types/src/types/StatementInfo.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,EAAE;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,uEAAuE;QACvE,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACb,EAAE,CAAC;CACL"}

package/analyzer-template/packages/utils/dist/utils/src/lib/safeFileName.d.ts

@@ -1,2 +1,10 @@
-export default function safeFileName(name: string): string;
+export interface SafeFileNameOptions {
+    /**
+     * Maximum length of the resulting filename.
+     * If the name exceeds this length, it will be truncated and a hash suffix added.
+     * macOS has a 255 byte filename limit. Default is undefined (no limit).
+     */
+    maxLength?: number;
+}
+export default function safeFileName(name: string, options?: SafeFileNameOptions): string;
 //# sourceMappingURL=safeFileName.d.ts.map

package/analyzer-template/packages/utils/dist/utils/src/lib/safeFileName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"safeFileName.d.ts","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,IAAI,EAAE,MAAM,UAShD"}
+{"version":3,"file":"safeFileName.d.ts","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA4BR"}

package/analyzer-template/packages/utils/dist/utils/src/lib/safeFileName.js

@@ -1,10 +1,36 @@
-export default function safeFileName(name) {
+/**
+ * Simple hash function for generating unique suffixes.
+ * Uses djb2 algorithm - fast and produces good distribution.
+ * Not cryptographically secure, but sufficient for filename uniqueness.
+ */
+function simpleHash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = (hash * 33) ^ str.charCodeAt(i);
+    }
+    // Convert to unsigned 32-bit and then to hex
+    return (hash >>> 0).toString(16).padStart(8, '0');
+}
+export default function safeFileName(name, options = {}) {
+    const { maxLength } = options;
     // Replace unsafe characters with underscores, preserving original casing
     // Then trim leading/trailing underscores to avoid malformed route segments
-    const safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+    let safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
     if (!safeSlug)
         return '';
     // Ensure it starts with a capital letter (for consistency with Remix routes)
-    return safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+    safeSlug = safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+    // If maxLength is specified and the slug exceeds it, truncate and add a hash
+    if (maxLength && safeSlug.length > maxLength) {
+        // Create an 8-character hash of the full name for uniqueness
+        const hash = simpleHash(name);
+        // Reserve space for underscore + hash (9 chars total)
+        const truncateLength = maxLength - 9;
+        const truncated = safeSlug.substring(0, truncateLength);
+        // Remove trailing underscore if present (from mid-word truncation)
+        const cleanTruncated = truncated.replace(/_+$/, '');
+        safeSlug = `${cleanTruncated}_${hash}`;
+    }
+    return safeSlug;
 }
 //# sourceMappingURL=safeFileName.js.map

package/analyzer-template/packages/utils/dist/utils/src/lib/safeFileName.js.map

@@ -1 +1 @@
-{"version":3,"file":"safeFileName.js","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,IAAY;IAC/C,yEAAyE;IACzE,2EAA2E;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE9E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,6EAA6E;IAC7E,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"safeFileName.js","sourceRoot":"","sources":["../../../../src/lib/safeFileName.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,IAAI,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACzC,CAAC;IACD,6CAA6C;IAC7C,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAWD,MAAM,CAAC,OAAO,UAAU,YAAY,CAClC,IAAY,EACZ,UAA+B,EAAE;IAEjC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IAE9B,yEAAyE;IACzE,2EAA2E;IAC3E,IAAI,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE5E,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,6EAA6E;IAC7E,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAElE,6EAA6E;IAC7E,IAAI,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QAC7C,6DAA6D;QAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;QAE9B,sDAAsD;QACtD,MAAM,cAAc,GAAG,SAAS,GAAG,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QAExD,mEAAmE;QACnE,MAAM,cAAc,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAEpD,QAAQ,GAAG,GAAG,cAAc,IAAI,IAAI,EAAE,CAAC;IACzC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

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

@@ -1,10 +1,55 @@
-export default function safeFileName(name: string) {
+/**
+ * Simple hash function for generating unique suffixes.
+ * Uses djb2 algorithm - fast and produces good distribution.
+ * Not cryptographically secure, but sufficient for filename uniqueness.
+ */
+function simpleHash(str: string): string {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash * 33) ^ str.charCodeAt(i);
+  }
+  // Convert to unsigned 32-bit and then to hex
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+export interface SafeFileNameOptions {
+  /**
+   * Maximum length of the resulting filename.
+   * If the name exceeds this length, it will be truncated and a hash suffix added.
+   * macOS has a 255 byte filename limit. Default is undefined (no limit).
+   */
+  maxLength?: number;
+}
+
+export default function safeFileName(
+  name: string,
+  options: SafeFileNameOptions = {},
+): string {
+  const { maxLength } = options;
+
   // Replace unsafe characters with underscores, preserving original casing
   // Then trim leading/trailing underscores to avoid malformed route segments
-  const safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+  let safeSlug = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
 
   if (!safeSlug) return '';
 
   // Ensure it starts with a capital letter (for consistency with Remix routes)
-  return safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+  safeSlug = safeSlug.slice(0, 1).toUpperCase() + safeSlug.slice(1);
+
+  // If maxLength is specified and the slug exceeds it, truncate and add a hash
+  if (maxLength && safeSlug.length > maxLength) {
+    // Create an 8-character hash of the full name for uniqueness
+    const hash = simpleHash(name);
+
+    // Reserve space for underscore + hash (9 chars total)
+    const truncateLength = maxLength - 9;
+    const truncated = safeSlug.substring(0, truncateLength);
+
+    // Remove trailing underscore if present (from mid-word truncation)
+    const cleanTruncated = truncated.replace(/_+$/, '');
+
+    safeSlug = `${cleanTruncated}_${hash}`;
+  }
+
+  return safeSlug;
 }

package/analyzer-template/playwright/capture.ts

@@ -161,10 +161,10 @@ export default async function capture({
   awsLogDebugLevel(1, 'Capture process initialized, waiting for controller...');
 
   // Resolve controller URL once before starting capture loop
-  // Read controller port from log file (for local dev) or use PROJECT_URL env var (for Docker)
+  // Priority: PROJECT_URL env var > log file (local dev) > default (Docker)
   let controllerUrl = process.env.PROJECT_URL;
 
-  if (!controllerUrl) {
+  if (!controllerUrl && process.env.CODEYAM_LOCAL_PROJECT_PATH) {
     // Local dev mode - poll log file until controller port is found
     awsLog('CodeYam: Waiting for controller port in log file...');
     let controllerPort: number | null = null;
@@ -182,10 +182,19 @@ export default async function capture({
       awsLog('CodeYam: Shutdown during controller port wait');
       return;
     }
+  } else if (!controllerUrl) {
+    // Docker mode - use fixed port 3000
+    controllerUrl = 'http://localhost:3000';
+    awsLog(`Using default controller URL: ${controllerUrl}`);
   }
 
   awsLogDebugLevel(1, 'Controller found, waiting for analysis...');
 
+  // Determine if we're in local CLI mode vs cloud mode
+  // In local mode, connection failures indicate server crash (should exit quickly)
+  // In cloud mode, connection failures are normal between work items (wait patiently)
+  const isLocalMode = !!process.env.CODEYAM_LOCAL_PROJECT_PATH;
+
   // Track if we've ever successfully captured an analysis
   // If connection fails after we've successfully worked, it means controller exited
   let hasEverCapturedAnalysis = false;
@@ -248,11 +257,11 @@ export default async function capture({
           analysisId: analysis.id,
           entityName: analysis.entityName,
         });
-        await updateFreshAnalysisStatus(
+        await updateFreshAnalysisStatusWithScenarios(
           analysis.id,
-          (freshStatus, inAnalysis) => {
+          (freshStatus, dbScenarios, inAnalysis) => {
             // Mark any incomplete scenarios as errored
-            for (const scenario of inAnalysis.scenarios || []) {
+            for (const scenario of dbScenarios) {
               const scenarioStatus = freshStatus.scenarios?.find(
                 (s) => s.name === scenario.name,
               );
@@ -272,17 +281,18 @@ export default async function capture({
             }
 
             // Mark the analysis as finished if all scenarios have been addressed
-            const allScenariosComplete = freshStatus.scenarios?.every(
-              (s) => s.finishedAt || s.error,
-            );
+            // Only set finishedAt - the loader will exclude based on scenario states
+            const allScenariosComplete =
+              freshStatus.scenarios?.length >= dbScenarios.length &&
+              freshStatus.scenarios?.every((s) => s.finishedAt || s.error);
             if (allScenariosComplete && !freshStatus.finishedAt) {
               freshStatus.finishedAt = new Date().toISOString();
-              freshStatus.readyToBeCaptured = false;
               awsLog('CodeYam: Marking analysis as complete on shutdown', {
                 analysisId: inAnalysis.id,
               });
             }
           },
+          'capture-shutdown',
         );
       }
 
@@ -334,7 +344,13 @@ export default async function capture({
 
   async function captureOneAnalysis() {
     // controllerUrl is already set in parent scope - just wait for server to be ready
-    const waitResult = await waitForServer(controllerUrl, () => isShuttingDown);
+    const waitResult = await waitForServer(
+      controllerUrl,
+      () => isShuttingDown,
+      {
+        isLocalMode,
+      },
+    );
 
     // Check if controller signaled completion during wait
     if (waitResult.shutdown) {
@@ -372,23 +388,27 @@ export default async function capture({
           break;
         }
 
-        // Check if connection failed (controller may have exited)
+        // Check if connection failed (controller may have exited or not started yet)
         if (result.connectionFailed) {
-          consecutiveConnectionFailures++;
-          awsLog(
-            `CodeYam: Connection failed (attempt ${consecutiveConnectionFailures}/${MAX_CONNECTION_FAILURES_FOR_SHUTDOWN}, hasEverCaptured=${hasEverCapturedAnalysis})`,
-          );
-          // If we've had many consecutive connection failures, the controller has likely exited
-          // This can happen even if hasEverCapturedAnalysis is false due to race conditions
-          // in how scenario completion is tracked
-          if (
-            consecutiveConnectionFailures >=
-            MAX_CONNECTION_FAILURES_FOR_SHUTDOWN
-          ) {
-            awsLog('CodeYam: Controller connection lost, treating as shutdown');
-            isShuttingDown = true;
-            break;
+          // Only treat connection failures as shutdown in local mode
+          // In cloud mode, connection failures are expected between work items
+          if (isLocalMode) {
+            consecutiveConnectionFailures++;
+            awsLog(
+              `CodeYam: Connection failed (attempt ${consecutiveConnectionFailures}/${MAX_CONNECTION_FAILURES_FOR_SHUTDOWN}, hasEverCaptured=${hasEverCapturedAnalysis})`,
+            );
+            if (
+              consecutiveConnectionFailures >=
+              MAX_CONNECTION_FAILURES_FOR_SHUTDOWN
+            ) {
+              awsLog(
+                'CodeYam: Controller connection lost, treating as shutdown',
+              );
+              isShuttingDown = true;
+              break;
+            }
           }
+          // In cloud mode, just continue waiting (don't count failures)
         } else {
           consecutiveConnectionFailures = 0;
         }
@@ -531,7 +551,7 @@ export default async function capture({
 
           await updateFreshAnalysisStatusWithScenarios(
             analysis.id,
-            (freshStatus, scenarios) => {
+            (freshStatus, dbScenarios) => {
               freshStatus.scenarios ||= [];
               const scenarioStatus = freshStatus.scenarios.find(
                 (s) => s.name === scenario.name,
@@ -550,6 +570,17 @@ export default async function capture({
                   error: fullErrorMessage,
                 });
               }
+
+              // Check if all scenarios are now complete (even if with errors)
+              // Only set finishedAt - the loader will exclude this analysis based on
+              // the scenario check (all have finishedAt || error), no need to also
+              // toggle readyToBeCaptured which has different semantics
+              if (
+                freshStatus.scenarios.length >= dbScenarios.length &&
+                freshStatus.scenarios.every((s) => s.finishedAt || s.error)
+              ) {
+                freshStatus.finishedAt = new Date().toISOString();
+              }
             },
             'capture-http-error',
           );

package/analyzer-template/playwright/captureStatic.ts

@@ -40,7 +40,7 @@ export default async function captureStatic({
       const now = new Date().toISOString();
       await updateCommitMetadata({
         commitId: analysis.commitId,
-        updateCallback: (metadata, commit) => {
+        updateCallback: (metadata) => {
           if (metadata.currentRun) {
             metadata.currentRun.firstCaptureAt ??= now;
             metadata.currentRun.lastCaptureAt = now;

package/analyzer-template/playwright/getCodeYamInfo.ts

@@ -1,5 +1,3 @@
-/* eslint-disable */
-
 import { ProjectFramework } from '~codeyam/types';
 
 export interface CodeYamInfo {
@@ -41,7 +39,9 @@ export default async function getCodeYamInfo(
 
       // if controller signals complete, tell capture to shut down
       if (phase === 'COMPLETE') {
-        console.log(`CodeYam DEBUG: getCodeYamInfo received COMPLETE phase, signaling shutdown`);
+        console.log(
+          `CodeYam DEBUG: getCodeYamInfo received COMPLETE phase, signaling shutdown`,
+        );
         if (options?.returnShutdown) {
           return { info: null, shutdown: true };
         }
@@ -57,7 +57,6 @@ export default async function getCodeYamInfo(
       }
 
       // all other cases mean 'keep waiting'
-      console.log(`CodeYam DEBUG: getCodeYamInfo phase=${phase}, info=${info ? 'present' : 'null'}, returning null`);
       if (options?.returnShutdown) {
         return { info: null, shutdown: false };
       }
@@ -74,7 +73,9 @@ export default async function getCodeYamInfo(
     const errorMessage = error.message || '';
     const causeMessage = error.cause?.message || '';
 
-    console.log(`CodeYam DEBUG: getCodeYamInfo caught error - code=${errorCode}, message=${errorMessage}, causeMessage=${causeMessage}`);
+    console.log(
+      `CodeYam DEBUG: getCodeYamInfo caught error - code=${errorCode}, message=${errorMessage}, causeMessage=${causeMessage}`,
+    );
 
     const isConnectionError =
       errorCode === 'ECONNREFUSED' ||
@@ -85,11 +86,15 @@ export default async function getCodeYamInfo(
       causeMessage.includes('ECONNREFUSED');
 
     if (!isConnectionError) {
-      console.log(`CodeYam DEBUG: getCodeYamInfo error is NOT a connection error, rethrowing`);
+      console.log(
+        `CodeYam DEBUG: getCodeYamInfo error is NOT a connection error, rethrowing`,
+      );
       throw error;
     }
     // let caller know the server just isn't up yet (or has shut down)
-    console.log(`CodeYam DEBUG: getCodeYamInfo connection error detected, returning connectionFailed=true`);
+    console.log(
+      `CodeYam DEBUG: getCodeYamInfo connection error detected, returning connectionFailed=true`,
+    );
     if (options?.returnShutdown) {
       return { info: null, shutdown: false, connectionFailed: true };
     }