@codeyam/codeyam-cli 0.1.0-staging.eb21b2f → 0.1.0-staging.f777668

package/analyzer-template/packages/analyze/src/lib/files/analyze/findOrCreateEntity.ts

@@ -138,6 +138,18 @@ export default async function findOrCreateEntity({
           break;
         }
       }
+
+      // Mark previous versions as superseded
+      const entitiesToSupersede = previousEntities.filter(
+        (e) => !e.metadata?.isSuperseded,
+      );
+      if (entitiesToSupersede.length > 0) {
+        for (const prev of entitiesToSupersede) {
+          prev.metadata = prev.metadata || {};
+          prev.metadata.isSuperseded = true;
+        }
+        await upsertEntities(entitiesToSupersede);
+      }
     }
 
     entity = {

package/analyzer-template/packages/analyze/src/lib/files/scenarios/TransformationTracer.ts

@@ -404,22 +404,15 @@ export class TransformationTracer {
   }
 
   /**
-   * Write the trace to the output file.
+   * Compute the summary data for the current traces.
    */
-  flush(): void {
-    if (!this.isEnabled()) return;
-    if (this.traces.size === 0) {
-      this.log('flush: no traces to write');
-      return;
-    }
-
-    const entities = Array.from(this.traces.keys());
-    const stageCounts = entities
-      .map((e) => `${e}(${this.traces.get(e)!.stages.length})`)
-      .join(', ');
-    this.log(`flush: writing ${entities.length} entities: ${stageCounts}`);
-
-    // Compute summary
+  private computeFlushSummary(): {
+    stageChangeCounts: Record<
+      string,
+      { added: number; removed: number; changed: number }
+    >;
+    entitiesWithMostChanges: string[];
+  } {
     const stageChangeCounts: Record<
       string,
       { added: number; removed: number; changed: number }
@@ -484,17 +477,39 @@ export class TransformationTracer {
       .slice(0, 10)
       .map(([name]) => name);
 
-    const traceFile: TraceFile = {
-      meta: {
-        timestamp: new Date().toISOString(),
-        projectSlug: this.projectSlug,
-        entityCount: this.traces.size,
-      },
-      summary: {
-        stageChangeCounts,
-        entitiesWithMostChanges,
-      },
-      entities: Object.fromEntries(this.traces),
+    return { stageChangeCounts, entitiesWithMostChanges };
+  }
+
+  /**
+   * Write the trace to the output file.
+   * Uses streaming per-entity writes to avoid exceeding V8's max string length
+   * on large projects.
+   */
+  flush(): void {
+    if (!this.isEnabled()) return;
+    if (this.traces.size === 0) {
+      this.log('flush: no traces to write');
+      return;
+    }
+
+    const entities = Array.from(this.traces.keys());
+    const stageCounts = entities
+      .map((e) => `${e}(${this.traces.get(e)!.stages.length})`)
+      .join(', ');
+    this.log(`flush: writing ${entities.length} entities: ${stageCounts}`);
+
+    const { stageChangeCounts, entitiesWithMostChanges } =
+      this.computeFlushSummary();
+
+    const meta = {
+      timestamp: new Date().toISOString(),
+      projectSlug: this.projectSlug,
+      entityCount: this.traces.size,
+    };
+
+    const summary = {
+      stageChangeCounts,
+      entitiesWithMostChanges,
     };
 
     // Ensure directory exists
@@ -503,8 +518,30 @@ export class TransformationTracer {
       fs.mkdirSync(dir, { recursive: true });
     }
 
-    fs.writeFileSync(this.outputPath, JSON.stringify(traceFile, null, 2));
-    this.log(`flush: wrote trace to ${this.outputPath}`);
+    // Stream JSON per-entity to avoid exceeding V8's max string length.
+    // Each entity is serialized individually so no single JSON.stringify
+    // call needs to produce the entire trace.
+    const fd = fs.openSync(this.outputPath, 'w');
+    try {
+      fs.writeSync(fd, '{\n  "meta": ');
+      fs.writeSync(fd, JSON.stringify(meta, null, 2));
+      fs.writeSync(fd, ',\n  "summary": ');
+      fs.writeSync(fd, JSON.stringify(summary, null, 2));
+      fs.writeSync(fd, ',\n  "entities": {');
+
+      let first = true;
+      for (const [entityName, entityTrace] of this.traces) {
+        if (!first) fs.writeSync(fd, ',');
+        fs.writeSync(fd, `\n    ${JSON.stringify(entityName)}: `);
+        fs.writeSync(fd, JSON.stringify(entityTrace, null, 2));
+        first = false;
+      }
+
+      fs.writeSync(fd, '\n  }\n}\n');
+      this.log(`flush: wrote trace to ${this.outputPath}`);
+    } finally {
+      fs.closeSync(fd);
+    }
   }
 
   /**

package/analyzer-template/packages/analyze/src/lib/files/scenarios/generateDataStructure.ts

@@ -461,6 +461,17 @@ export default function generateDataStructure({
 
     const { isolatedDataStructure } = entity.metadata;
 
+    if (!isolatedDataStructure) {
+      awsLog(
+        'CodeYam: Skipping data structure generation — isolatedDataStructure is undefined (scope analysis may have failed)',
+        {
+          entityName: entity.name,
+          filePath: entity.filePath,
+        },
+      );
+      return analysis;
+    }
+
     // Transformation tracing: start entity and capture isolated data structure
     transformationTracer.startEntity({
       name: entity.name,
@@ -643,6 +654,78 @@ export default function generateDataStructure({
           },
         );
 
+        // Infer function types from child component usage BEFORE fillInSchemaGapsAndUnknowns.
+        // When a hook returns a property with type 'unknown' that is passed to a child
+        // component which calls it as a function (e.g., isEntityPending(entity)),
+        // promote it to 'function'. Without this, name heuristics like isLikelyBoolean
+        // would mistype "isEntityPending" as boolean because of the "is" prefix.
+        //
+        // sourceEquivalencies are in isolatedDataStructure.dependencySchemas (not in
+        // mergedDataStructure.dependencySchemas — they're dropped during the merge).
+        // The child's signatureSchema (with function call evidence) IS in the merged schemas.
+        {
+          const isolatedDepSchemas =
+            entity.metadata.isolatedDataStructure?.dependencySchemas;
+          if (isolatedDepSchemas) {
+            for (const childFilePath in isolatedDepSchemas) {
+              const childIsolated = isolatedDepSchemas[childFilePath];
+              for (const childName in childIsolated) {
+                const sourceEq = childIsolated[childName]?.sourceEquivalencies;
+                if (!sourceEq) continue;
+
+                // Get the child's signatureSchema from the MERGED schemas (richer)
+                const mergedChildSchema =
+                  mergedDataStructure.dependencySchemas[childFilePath]?.[
+                    childName
+                  ];
+                const sigSchema = mergedChildSchema?.signatureSchema;
+                if (!sigSchema) continue;
+
+                for (const childPath in sourceEq) {
+                  for (const source of sourceEq[childPath]) {
+                    const fcrvSuffix = '.functionCallReturnValue.';
+                    const fcrvIndex = source.schemaPath.indexOf(fcrvSuffix);
+                    if (fcrvIndex === -1) continue;
+
+                    const propName = source.schemaPath.slice(
+                      fcrvIndex + fcrvSuffix.length,
+                    );
+
+                    // Find the corresponding child signature path
+                    const entityCallPrefix = childName + '().';
+                    const sigPathBase = childPath.startsWith(entityCallPrefix)
+                      ? childPath.slice(entityCallPrefix.length)
+                      : childPath;
+
+                    // Check if the child's signatureSchema has a function call version
+                    let isFunction = false;
+                    for (const sigKey in sigSchema) {
+                      if (
+                        sigKey.startsWith(sigPathBase + '(') &&
+                        sigSchema[sigKey] === 'function'
+                      ) {
+                        isFunction = true;
+                        break;
+                      }
+                    }
+
+                    if (isFunction) {
+                      for (const rvKey in depSchema.returnValueSchema) {
+                        if (
+                          rvKey.endsWith('.' + propName) &&
+                          depSchema.returnValueSchema[rvKey] === 'unknown'
+                        ) {
+                          depSchema.returnValueSchema[rvKey] = 'function';
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+
         // Fill in type gaps BEFORE clearing attributes, so evidence like .includes()
         // is used for type inference before being deleted
 

package/analyzer-template/packages/analyze/src/lib/files/scenarios/generateExecutionFlows.ts

@@ -65,10 +65,6 @@ export default async function generateExecutionFlows({
   }
 
   if (!analysis.metadata.executionFlows) {
-    console.log(
-      `[GenerateExecutionFlows] Starting for ${entity.name} (${entity.filePath})`,
-    );
-
     // Build childEntityMetadata from dependentAnalyses for child flow merging
     // This maps child component names to their metadata (specifically isolatedDataStructure)
     const childEntityMetadata = buildChildEntityMetadata(
@@ -77,15 +73,6 @@ export default async function generateExecutionFlows({
     );
 
     const childCount = Object.keys(childEntityMetadata).length;
-    console.log(
-      `[GenerateExecutionFlows] Built childEntityMetadata with ${childCount} children`,
-    );
-    if (childCount > 0) {
-      console.log(
-        `[GenerateExecutionFlows] Will merge flows from children: [${Object.keys(childEntityMetadata).join(', ')}]`,
-      );
-    }
-
     const {
       result: { executionFlows, llmCall: executionFlowsLLMCall },
     } = await measureAndReportExecutionTime(
@@ -100,18 +87,6 @@ export default async function generateExecutionFlows({
       updateProgress,
     );
 
-    console.log(
-      `[GenerateExecutionFlows] Generated ${executionFlows.length} execution flows for ${entity.name}`,
-    );
-    for (const flow of executionFlows) {
-      const reqValues = flow.requiredValues
-        .map((rv) => `${rv.attributePath}=${rv.value}`)
-        .join(', ');
-      console.log(
-        `[GenerateExecutionFlows]   - Flow '${flow.id}': ${flow.name} [${reqValues}]`,
-      );
-    }
-
     analysis.metadata.executionFlows = executionFlows;
 
     if (executionFlowsLLMCall) {
@@ -137,14 +112,7 @@ export function buildChildEntityMetadata(
 ): Record<string, Entity['metadata']> {
   const childEntityMetadata: Record<string, Entity['metadata']> = {};
 
-  console.log(
-    `[BuildChildMetadata] Starting for entity: ${entity.name} (${entity.filePath})`,
-  );
-
   if (!dependentAnalyses) {
-    console.log(
-      `[BuildChildMetadata] No dependentAnalyses provided, returning empty`,
-    );
     return childEntityMetadata;
   }
 
@@ -152,54 +120,19 @@ export function buildChildEntityMetadata(
     entity.metadata?.isolatedDataStructure?.childBoundaryGatingConditions;
 
   if (!childBoundaryGatingConditions) {
-    console.log(
-      `[BuildChildMetadata] No childBoundaryGatingConditions found in isolatedDataStructure`,
-    );
-    console.log(
-      `[BuildChildMetadata] isolatedDataStructure keys: ${Object.keys(entity.metadata?.isolatedDataStructure ?? {}).join(', ') || 'none'}`,
-    );
     return childEntityMetadata;
   }
 
   const childNames = Object.keys(childBoundaryGatingConditions);
-  console.log(
-    `[BuildChildMetadata] Found ${childNames.length} children in childBoundaryGatingConditions: [${childNames.join(', ')}]`,
-  );
-
-  // Log gating conditions for each child
-  for (const [childName, conditions] of Object.entries(
-    childBoundaryGatingConditions,
-  )) {
-    const isUnconditional = conditions.some(
-      (c) => c.location === 'unconditional',
-    );
-    console.log(
-      `[BuildChildMetadata] Child '${childName}': ${conditions.length} gating conditions, unconditional=${isUnconditional}`,
-    );
-    for (const condition of conditions) {
-      console.log(
-        `[BuildChildMetadata]   - path='${condition.path}' location='${condition.location}' isNegated=${condition.isNegated ?? false}`,
-      );
-    }
-  }
-
   const importedExports = entity.metadata?.importedExports ?? [];
-  console.log(
-    `[BuildChildMetadata] Entity has ${importedExports.length} importedExports`,
-  );
 
   for (const childName of childNames) {
-    console.log(`[BuildChildMetadata] Looking up child '${childName}'...`);
-
     // Find the child in importedExports to get its file path
     const importedExport = importedExports.find(
       (ie) => ie.name === childName || ie.resolvedName === childName,
     );
 
     if (!importedExport) {
-      console.log(
-        `[BuildChildMetadata] Child '${childName}' NOT FOUND in importedExports`,
-      );
       continue;
     }
 
@@ -208,27 +141,14 @@ export function buildChildEntityMetadata(
       importedExport.resolvedFilePath ?? importedExport.filePath;
     const lookupName = importedExport.resolvedName ?? importedExport.name;
 
-    console.log(
-      `[BuildChildMetadata] Child '${childName}' found in importedExports: lookupPath='${lookupPath}' lookupName='${lookupName}'`,
-    );
-
     // Look up the child's analysis in dependentAnalyses
     const childAnalysis = dependentAnalyses[lookupPath]?.[lookupName];
 
     if (!childAnalysis) {
-      console.log(
-        `[BuildChildMetadata] Child '${childName}' analysis NOT FOUND in dependentAnalyses[${lookupPath}][${lookupName}]`,
-      );
-      console.log(
-        `[BuildChildMetadata] Available paths in dependentAnalyses: [${Object.keys(dependentAnalyses).slice(0, 10).join(', ')}...]`,
-      );
       continue;
     }
 
     if (!childAnalysis.entity?.metadata) {
-      console.log(
-        `[BuildChildMetadata] Child '${childName}' analysis found but entity.metadata is missing`,
-      );
       continue;
     }
 
@@ -237,28 +157,10 @@ export function buildChildEntityMetadata(
     const childConditionalUsages = childIsolated?.conditionalUsages ?? {};
     const childConditionalCount = Object.keys(childConditionalUsages).length;
 
-    console.log(
-      `[BuildChildMetadata] Child '${childName}' FOUND with metadata:`,
-    );
-    console.log(
-      `[BuildChildMetadata]   - conditionalUsages: ${childConditionalCount} paths`,
-    );
-    if (childConditionalCount > 0) {
-      for (const [path, usages] of Object.entries(childConditionalUsages)) {
-        console.log(
-          `[BuildChildMetadata]     - '${path}': ${(usages as any[]).length} usages`,
-        );
-      }
-    }
-
     // Cast to mutable type - the metadata is only read, not modified
     childEntityMetadata[childName] = childAnalysis.entity
       .metadata as Entity['metadata'];
   }
 
-  console.log(
-    `[BuildChildMetadata] RESULT: Found metadata for ${Object.keys(childEntityMetadata).length} children: [${Object.keys(childEntityMetadata).join(', ')}]`,
-  );
-
   return childEntityMetadata;
 }

package/analyzer-template/packages/analyze/src/lib/files/scenarios/mergeInDependentDataStructure.ts

@@ -52,6 +52,7 @@ const PRIMITIVE_TYPES = new Set([
 
 // Check if a type string represents a primitive type
 // Handles union types like "string | undefined" or "number | null"
+// Also handles string literal unions like "'suggestion' | 'warning' | 'tip'"
 function isPrimitiveType(typeStr: string): boolean {
   if (PRIMITIVE_TYPES.has(typeStr)) {
     return true;
@@ -59,9 +60,15 @@ function isPrimitiveType(typeStr: string): boolean {
   // Check union types - if ALL parts of the union are primitives, it's primitive
   // e.g., "string | undefined" -> ["string", "undefined"] -> both are primitive -> true
   // e.g., "object | null" -> ["object", "null"] -> object is not primitive -> false
+  // e.g., "'suggestion' | 'warning'" -> string literal union -> true
   if (typeStr.includes('|')) {
     const parts = typeStr.split('|').map((p) => p.trim());
-    return parts.every((part) => PRIMITIVE_TYPES.has(part));
+    return parts.every(
+      (part) =>
+        PRIMITIVE_TYPES.has(part) ||
+        // String literal values like 'suggestion', 'warning' are primitives
+        (part.startsWith("'") && part.endsWith("'")),
+    );
   }
   return false;
 }
@@ -110,9 +117,21 @@ function pathPartMatches(pathPart: string, schemaPathPart: string): boolean {
 function bestValueFromOptions(options: Array<string | undefined>) {
   options = options.filter(Boolean) as string[];
 
-  const known = options.find((o) => !o.includes('unknown'));
-  if (known) {
-    return known;
+  const known = options.filter((o) => !o.includes('unknown'));
+  if (known.length > 0) {
+    // Among known values, prefer string literal unions over bare primitives.
+    // e.g., "'draft' | 'inProgress' | 'paused' | 'completed'" is more specific than "string".
+    // This handles cases where a dependency schema has a bare type like "string" but the
+    // child entity's analysis has the actual literal union from TypeScript type resolution.
+    if (known.length > 1 && known.some((o) => PRIMITIVE_TYPES.has(o))) {
+      const literalUnion = known.find(
+        (o) => !PRIMITIVE_TYPES.has(o) && o.includes("'"),
+      );
+      if (literalUnion) {
+        return literalUnion;
+      }
+    }
+    return known[0];
   }
 
   const notUnknown = options.find((o) => o !== 'unknown');

package/analyzer-template/packages/aws/package.json

@@ -11,15 +11,15 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@aws-sdk/client-codebuild": "^3.948.0",
-    "@aws-sdk/client-cloudwatch-logs": "^3.980.0",
-    "@aws-sdk/client-dynamodb": "^3.956.0",
-    "@aws-sdk/client-ecr": "^3.948.0",
-    "@aws-sdk/client-ecs": "^3.956.0",
-    "@aws-sdk/client-s3": "^3.940.0",
-    "@aws-sdk/client-sqs": "^3.956.0",
-    "@aws-sdk/lib-storage": "^3.975.0",
-    "@aws-sdk/s3-request-presigner": "^3.940.0",
-    "@aws-sdk/util-dynamodb": "^3.971.0"
+    "@aws-sdk/client-codebuild": "^3.1000.0",
+    "@aws-sdk/client-cloudwatch-logs": "^3.990.0",
+    "@aws-sdk/client-dynamodb": "^3.990.0",
+    "@aws-sdk/client-ecr": "^3.990.0",
+    "@aws-sdk/client-ecs": "^3.990.0",
+    "@aws-sdk/client-s3": "^3.990.0",
+    "@aws-sdk/client-sqs": "^3.990.0",
+    "@aws-sdk/lib-storage": "^3.990.0",
+    "@aws-sdk/s3-request-presigner": "^3.990.0",
+    "@aws-sdk/util-dynamodb": "^3.990.0"
   }
 }

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

@@ -75,6 +75,7 @@ export * from './src/lib/kysely/tables/backgroundJobsTable';
 export * from './src/lib/kysely/tables/branchesTable';
 export * from './src/lib/kysely/tables/commitBranchesTable';
 export * from './src/lib/kysely/tables/commitsTable';
+export * from './src/lib/kysely/tables/editorScenariosTable';
 export * from './src/lib/kysely/tables/entitiesTable';
 export * from './src/lib/kysely/tables/entityBranchesTable';
 export * from './src/lib/kysely/tables/entityStatementsTable';

package/analyzer-template/packages/database/package.json

@@ -13,10 +13,10 @@
   "license": "ISC",
   "dependencies": {
     "@supabase/supabase-js": "2.88.0",
-    "better-sqlite3": "^12.4.1",
+    "better-sqlite3": "^12.6.2",
     "fetch-retry": "^6.0.0",
     "kysely": "^0.28.11",
-    "pg": "^8.16.3"
+    "pg": "^8.19.0"
   },
   "jest": {
     "preset": "ts-jest",
@@ -25,7 +25,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/jest": "^30.0.0",
-    "@types/pg": "^8.15.5",
+    "@types/pg": "^8.18.0",
     "@types/ws": "^8.18.1"
   }
 }

package/analyzer-template/packages/database/src/lib/kysely/db.ts

@@ -62,6 +62,10 @@ import {
   createScenarioCommentsTable,
   ScenarioCommentsTable,
 } from './tables/scenarioCommentsTable';
+import {
+  createEditorScenariosTable,
+  EditorScenariosTable,
+} from './tables/editorScenariosTable';
 import { createScenariosTable, ScenariosTable } from './tables/scenariosTable';
 import {
   createStatementsTable,
@@ -106,6 +110,7 @@ const databaseSchema = {
   commit_branches: schemaField<CommitBranchesTable>(),
   commits: schemaField<CommitsTable>(),
   debug_reports: schemaField<DebugBundlesTable>(),
+  editor_scenarios: schemaField<EditorScenariosTable>(),
   entities: schemaField<EntitiesTable>(),
   entity_branches: schemaField<EntityBranchesTable>(),
   entity_statements: schemaField<EntityStatementsTable>(),
@@ -210,6 +215,7 @@ export function getSqliteDatabase(sqlitePath?: string) {
     fileMustExist: false,
   });
   sqlite.pragma('journal_mode = WAL');
+  sqlite.pragma('busy_timeout = 5000');
   sqlite.pragma('synchronous = FULL');
 
   // Verify the database has the expected schema
@@ -305,6 +311,7 @@ export async function getDatabaseForTesting(
     // Standard SQLite testing path
     const sqlite = new SQLiteDatabase(dbPath);
     sqlite.pragma('journal_mode = WAL');
+    sqlite.pragma('busy_timeout = 5000');
     sqlite.pragma('synchronous = FULL');
     const kyselyDb = new Kysely<Database>({
       dialect: new SqliteDialect({ database: sqlite }),
@@ -390,6 +397,7 @@ export async function createSqliteSchema(db: Kysely<Database>): Promise<void> {
   await createCommitBranchesTable(db);
   await createCommitsTable(db);
   await createDebugBundlesTable(db);
+  await createEditorScenariosTable(db);
   await createEntitiesTable(db);
   await createEntityBranchesTable(db);
   await createEntityStatementsTable(db);

package/analyzer-template/packages/database/src/lib/kysely/tables/editorScenariosTable.ts

@@ -0,0 +1,68 @@
+import { Kysely, ColumnDefinitionBuilder } from 'kysely';
+import type { Generated } from 'kysely';
+
+import { schemaField, defaultNow } from '../schemaHelpers';
+
+const editorScenariosSchema = {
+  id: schemaField<Generated<string>>(),
+  project_id: schemaField<string>(),
+  name: schemaField<string>(),
+  description: schemaField<string | null>(),
+  component_name: schemaField<string | null>(),
+  component_path: schemaField<string | null>(),
+  url: schemaField<string | null>(),
+  type: schemaField<string | null>(),
+  screenshot_path: schemaField<string | null>(),
+  created_at: schemaField<Generated<string>>(),
+  updated_at: schemaField<Generated<string>>(),
+} as const;
+
+export type EditorScenariosTable = {
+  [K in keyof typeof editorScenariosSchema]: (typeof editorScenariosSchema)[K];
+};
+
+export const EditorScenariosTableColumns = Object.keys(
+  editorScenariosSchema,
+) as (keyof EditorScenariosTable)[];
+
+export async function createEditorScenariosTable(
+  db: Kysely<any>,
+): Promise<void> {
+  await db.schema
+    .createTable('editor_scenarios')
+    .addColumn('id', 'uuid', (col: ColumnDefinitionBuilder) => col.primaryKey())
+    .addColumn('project_id', 'uuid', (col: ColumnDefinitionBuilder) =>
+      col.notNull(),
+    )
+    .addColumn('name', 'varchar', (col: ColumnDefinitionBuilder) =>
+      col.notNull(),
+    )
+    .addColumn('description', 'text')
+    .addColumn('component_name', 'varchar')
+    .addColumn('component_path', 'varchar')
+    .addColumn('url', 'varchar')
+    .addColumn('type', 'varchar')
+    .addColumn('screenshot_path', 'varchar')
+    .addColumn('created_at', 'datetime', defaultNow(true))
+    .addColumn('updated_at', 'datetime', defaultNow(true))
+    .ifNotExists()
+    .execute();
+
+  // Add columns to existing tables (ALTER TABLE has no IF NOT EXISTS in SQLite)
+  for (const col of [
+    'component_name',
+    'component_path',
+    'url',
+    'type',
+    'screenshot_path',
+  ] as const) {
+    try {
+      await db.schema
+        .alterTable('editor_scenarios')
+        .addColumn(col, 'varchar')
+        .execute();
+    } catch {
+      // Column already exists — expected for fresh databases
+    }
+  }
+}