@auto-engineer/information-architect 0.13.3 → 0.15.0

package/package.json

@@ -14,23 +14,19 @@
   },
   "dependencies": {
     "fast-glob": "^3.3.2",
-    "@auto-engineer/ai-gateway": "0.13.3",
-    "@auto-engineer/message-bus": "0.13.3",
-    "@auto-engineer/narrative": "0.13.3"
+    "@auto-engineer/narrative": "0.15.0",
+    "@auto-engineer/ai-gateway": "0.15.0",
+    "@auto-engineer/message-bus": "0.15.0"
   },
   "devDependencies": {
-    "@auto-engineer/cli": "0.13.3"
+    "@auto-engineer/cli": "0.15.0"
   },
-  "version": "0.13.3",
+  "version": "0.15.0",
   "scripts": {
     "build": "tsc && tsx ../../scripts/fix-esm-imports.ts && cp src/auto-ux-schema.json dist/",
     "test": "vitest run --reporter=dot",
-    "lint": "eslint 'src/**/*.ts' --max-warnings 0 --config ../../eslint.config.ts",
     "type-check": "tsc --noEmit",
     "generate-ia-schema": "tsx src/generate-ia-schema.ts",
-    "format": "prettier --write \"**/*.{js,ts,json,md,yml,yaml}\" --ignore-path ../../.prettierignore --log-level warn",
-    "lint:fix": "eslint 'src/**/*.ts' --fix --config ../../eslint.config.ts",
-    "format:fix": "prettier --write \"**/*.{js,ts,json,md,yml,yaml}\" --ignore-path ../../.prettierignore --log-level warn",
     "link:dev": "pnpm build && pnpm link --global",
     "unlink:dev": "pnpm unlink --global"
   }

package/src/commands/generate-ia.ts

@@ -1,12 +1,12 @@
-import { type Command, type Event, defineCommandHandler } from '@auto-engineer/message-bus';
-import { promises as fs } from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-import { processFlowsWithAI } from '../index';
-import { type UXSchema } from '../types';
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { type Command, defineCommandHandler, type Event } from '@auto-engineer/message-bus';
+import type { Model } from '@auto-engineer/narrative';
 import createDebug from 'debug';
-import { Model } from '@auto-engineer/narrative';
+import { processFlowsWithAI, type ValidationError, validateCompositionReferences } from '../index';
 import { flattenClientSpecs } from '../spec-utils';
+import type { UXSchema } from '../types';
 
 const debug = createDebug('auto:information-architect:generate-command');
 const debugSchema = createDebug('auto:information-architect:generate-command:schema');
@@ -22,6 +22,7 @@ export type GenerateIACommand = Command<
   {
     modelPath: string;
     outputDir: string;
+    previousErrors?: string;
   }
 >;
 
@@ -41,18 +42,32 @@ export type IAGenerationFailedEvent = Event<
   }
 >;
 
-export type GenerateIAEvents = IAGeneratedEvent | IAGenerationFailedEvent;
+export type IAValidationFailedEvent = Event<
+  'IAValidationFailed',
+  {
+    errors: ValidationError[];
+    outputDir: string;
+    modelPath: string;
+  }
+>;
+
+export type GenerateIAEvents = IAGeneratedEvent | IAGenerationFailedEvent | IAValidationFailedEvent;
 
 export const commandHandler = defineCommandHandler<
   GenerateIACommand,
-  (command: GenerateIACommand) => Promise<IAGeneratedEvent | IAGenerationFailedEvent>
+  (command: GenerateIACommand) => Promise<IAGeneratedEvent | IAGenerationFailedEvent | IAValidationFailedEvent>
 >({
   name: 'GenerateIA',
+  displayName: 'Generate IA',
   alias: 'generate:ia',
   description: 'Generate Information Architecture',
   category: 'generate',
   icon: 'building',
-  events: ['IAGenerated', 'IAGenerationFailed'],
+  events: [
+    { name: 'IAGenerated', displayName: 'IA Generated' },
+    { name: 'IAGenerationFailed', displayName: 'IA Generation Failed' },
+    { name: 'IAValidationFailed', displayName: 'IA Validation Failed' },
+  ],
   fields: {
     outputDir: {
       description: 'Context directory',
@@ -64,10 +79,14 @@ export const commandHandler = defineCommandHandler<
     },
   },
   examples: ['$ auto generate:ia --output-dir=./.context --model-path=./.context/schema.json'],
-  handle: async (command: GenerateIACommand): Promise<IAGeneratedEvent | IAGenerationFailedEvent> => {
+  handle: async (
+    command: GenerateIACommand,
+  ): Promise<IAGeneratedEvent | IAGenerationFailedEvent | IAValidationFailedEvent> => {
     const result = await handleGenerateIACommandInternal(command);
     if (result.type === 'IAGenerated') {
       debug('IA schema generated successfully');
+    } else if (result.type === 'IAValidationFailed') {
+      debug('Validation failed with %d errors', result.data.errors.length);
     } else {
       debug('Failed: %s', result.data.error);
     }
@@ -154,8 +173,8 @@ async function getUniqueSchemaPath(
 
 async function handleGenerateIACommandInternal(
   command: GenerateIACommand,
-): Promise<IAGeneratedEvent | IAGenerationFailedEvent> {
-  const { outputDir, modelPath } = command.data;
+): Promise<IAGeneratedEvent | IAGenerationFailedEvent | IAValidationFailedEvent> {
+  const { outputDir, modelPath, previousErrors } = command.data;
 
   debug('Handling GenerateIA command');
   debug('  Output directory: %s', outputDir);
@@ -190,9 +209,31 @@ async function handleGenerateIACommandInternal(
     debug('  Existing schema: %s', existingSchema ? 'yes' : 'no');
     debug('  Atom count: %d', atoms.length);
 
-    const iaSchema = await processFlowsWithAI(processedModel, uxSchema, existingSchema, atoms);
+    const iaSchema = await processFlowsWithAI(processedModel, uxSchema, existingSchema, atoms, previousErrors);
     debug('AI processing complete');
 
+    const validationErrors = validateCompositionReferences(iaSchema, atomNames);
+    if (validationErrors.length > 0) {
+      debug('Validation failed with %d errors', validationErrors.length);
+      for (const err of validationErrors) {
+        debug('  - %s', err.message);
+      }
+
+      const validationFailedEvent: IAValidationFailedEvent = {
+        type: 'IAValidationFailed',
+        data: {
+          errors: validationErrors,
+          outputDir,
+          modelPath,
+        },
+        timestamp: new Date(),
+        requestId: command.requestId,
+        correlationId: command.correlationId,
+      };
+
+      return validationFailedEvent;
+    }
+
     // Write the schema to file
     debugResult('Writing IA schema to: %s', filePath);
     const schemaJson = JSON.stringify(iaSchema, null, 2);

package/src/generate-ia-schema.ts

@@ -1,8 +1,8 @@
-import { processFlowsWithAI } from './index';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { Model } from '@auto-engineer/narrative';
 import uxSchema from './auto-ux-schema.json';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { type Model } from '@auto-engineer/narrative';
+import { processFlowsWithAI } from './index';
 
 interface DesignSystemItem {
   name: string;
@@ -101,7 +101,7 @@ async function getUniqueSchemaPath(
   await fs.mkdir(outputDir, { recursive: true });
   const baseFileName = 'auto-ia-scheme';
   const basePath = path.join(outputDir, baseFileName);
-  let existingSchema: object | undefined = undefined;
+  let existingSchema: object | undefined;
 
   try {
     existingSchema = JSON.parse(await fs.readFile(`${basePath}.json`, 'utf-8')) as object;

package/src/ia-agent.ts

@@ -1,6 +1,6 @@
-import { generateTextWithAI, AIProvider } from '@auto-engineer/ai-gateway';
-import { type UXSchema, type AIAgentOutput } from './types.js';
-import { type Model } from '@auto-engineer/narrative';
+import { type AIProvider, generateTextWithAI } from '@auto-engineer/ai-gateway';
+import type { Model } from '@auto-engineer/narrative';
+import type { AIAgentOutput, UXSchema } from './types.js';
 
 function extractJsonFromMarkdown(text: string): string {
   return text.replace(/```(?:json)?\s*([\s\S]*?)\s*```/, '$1').trim();
@@ -15,6 +15,91 @@ function isJsonString(str: string): boolean {
   }
 }
 
+interface CompositionSection {
+  atoms?: string[];
+  molecules?: string[];
+  organisms?: string[];
+}
+
+interface ComponentDefinition {
+  composition?: CompositionSection;
+}
+
+interface ItemsContainer {
+  items?: Record<string, ComponentDefinition>;
+}
+
+interface IASchema {
+  atoms?: ItemsContainer;
+  molecules?: ItemsContainer;
+  organisms?: ItemsContainer;
+  pages?: Record<string, unknown>;
+}
+
+export interface ValidationError {
+  component: string;
+  type: 'molecule' | 'organism';
+  field: string;
+  invalidReferences: string[];
+  message: string;
+}
+
+export function validateCompositionReferences(schema: unknown, designSystemAtoms: string[] = []): ValidationError[] {
+  const s = schema as IASchema;
+  const errors: ValidationError[] = [];
+
+  const schemaAtoms = Object.keys(s.atoms?.items ?? {});
+  const atomNames = new Set([...schemaAtoms, ...designSystemAtoms]);
+  const moleculeNames = new Set(Object.keys(s.molecules?.items ?? {}));
+  const organismNames = new Set(Object.keys(s.organisms?.items ?? {}));
+
+  for (const [name, def] of Object.entries(s.molecules?.items ?? {})) {
+    const referencedAtoms = def.composition?.atoms ?? [];
+    const invalidAtoms = referencedAtoms.filter((atom: string) => !atomNames.has(atom));
+    if (invalidAtoms.length > 0) {
+      errors.push({
+        component: name,
+        type: 'molecule',
+        field: 'composition.atoms',
+        invalidReferences: invalidAtoms,
+        message: `Molecule "${name}" references non-existent atoms: ${invalidAtoms.join(', ')}`,
+      });
+    }
+  }
+
+  for (const [name, def] of Object.entries(s.organisms?.items ?? {})) {
+    const referencedMolecules = def.composition?.molecules ?? [];
+
+    const nonExistentMolecules = referencedMolecules.filter(
+      (mol: string) => !moleculeNames.has(mol) && !organismNames.has(mol),
+    );
+    if (nonExistentMolecules.length > 0) {
+      errors.push({
+        component: name,
+        type: 'organism',
+        field: 'composition.molecules',
+        invalidReferences: nonExistentMolecules,
+        message: `Organism "${name}" references non-existent molecules: ${nonExistentMolecules.join(', ')}`,
+      });
+    }
+
+    const organismsAsMolecules = referencedMolecules.filter(
+      (mol: string) => organismNames.has(mol) && !moleculeNames.has(mol),
+    );
+    if (organismsAsMolecules.length > 0) {
+      errors.push({
+        component: name,
+        type: 'organism',
+        field: 'composition.molecules',
+        invalidReferences: organismsAsMolecules,
+        message: `Organism "${name}" incorrectly references organisms as molecules: ${organismsAsMolecules.join(', ')}. These should be in molecules.items, not organisms.items.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
 export class InformationArchitectAgent {
   private provider?: AIProvider;
 
@@ -27,8 +112,9 @@ export class InformationArchitectAgent {
     uxSchema: UXSchema,
     existingSchema?: object,
     atoms?: { name: string; props: { name: string; type: string }[] }[],
+    previousErrors?: string,
   ): Promise<AIAgentOutput> {
-    const prompt = this.constructPrompt(model, uxSchema, existingSchema, atoms);
+    const prompt = this.constructPrompt(model, uxSchema, existingSchema, atoms, previousErrors);
     try {
       const response = await generateTextWithAI(prompt, {
         provider: this.provider,
@@ -40,7 +126,7 @@ export class InformationArchitectAgent {
       }
       const clean = extractJsonFromMarkdown(response);
       if (!isJsonString(clean)) {
-        throw new Error('AI did not return valid JSON. Got: ' + clean.slice(0, 100));
+        throw new Error(`AI did not return valid JSON. Got: ${clean.slice(0, 100)}`);
       }
       return JSON.parse(clean) as AIAgentOutput;
     } catch (error) {
@@ -54,13 +140,35 @@ export class InformationArchitectAgent {
     uxSchema: UXSchema,
     existingSchema?: object,
     atoms?: { name: string; props: { name: string; type: string }[] }[],
+    previousErrors?: string,
   ): string {
+    const errorContext = previousErrors
+      ? `
+PREVIOUS ATTEMPT FAILED VALIDATION. You MUST fix these errors:
+${previousErrors}
+
+The schema was rejected because of the composition errors above. Please regenerate the schema with these issues corrected.
+`
+      : '';
+
     return `
 You are an expert UI architect and product designer. Given the following model (containing flows, messages, and integrations) and UX schema, generate a detailed JSON specification for the application's UI components and pages.
-
+${errorContext}
 IMPORTANT: Only generate pages and components that are directly referenced in the provided model's flows. Do NOT add any extra pages or components, and do NOT make assumptions outside the flows. If something is not mentioned in the flows, it should NOT appear in the output.
 IMPORTANT: try your best to reuse the existing atoms, and try not to generate atoms with context: like Submit Button, because the submit part is mainly irrelevant, instead just use the Button atom if provided.
 
+CRITICAL COMPOSITION RULES - THESE ARE STRICT AND MUST BE FOLLOWED:
+1. Atoms: Basic UI primitives (Button, Text, Input, Icon, etc.). Atoms do NOT compose other atoms.
+2. Molecules: Composed ONLY of atoms. A molecule's "composition.atoms" array must ONLY reference items that exist in "atoms.items".
+3. Organisms: Composed of atoms AND molecules. An organism's "composition.molecules" array must ONLY reference items that exist in "molecules.items". An organism MUST NOT reference other organisms.
+4. Pages: Can reference organisms, molecules, and atoms.
+
+VALIDATION CHECKLIST (the schema will be rejected if these rules are violated):
+- Every item in a molecule's "composition.atoms" MUST exist in "atoms.items"
+- Every item in an organism's "composition.molecules" MUST exist in "molecules.items"
+- An organism's "composition.molecules" MUST NOT contain names that only exist in "organisms.items"
+- Cross-check all composition references before finalizing the output
+
 $${atoms ? `Here is a list of available atomic components (atoms) from the design system. Use these atoms and their props as much as possible. Only create new atoms if absolutely necessary. And only put the new atoms created into the schema. \n\nAtoms:\n${JSON.stringify(atoms, null, 2)}\n` : ''}
 System Model (flows, messages, integrations):
 ${JSON.stringify(model, null, 2)}
@@ -152,7 +260,8 @@ export async function processFlowsWithAI(
   uxSchema: UXSchema,
   existingSchema?: object,
   atoms?: { name: string; props: { name: string; type: string }[] }[],
+  previousErrors?: string,
 ): Promise<AIAgentOutput> {
   const agent = new InformationArchitectAgent();
-  return agent.generateUXComponents(model, uxSchema, existingSchema, atoms);
+  return agent.generateUXComponents(model, uxSchema, existingSchema, atoms, previousErrors);
 }

package/src/index.ts

@@ -1,6 +1,11 @@
 // Barrel exports
-export { InformationArchitectAgent, processFlowsWithAI } from './ia-agent.js';
-export type { UXSchema, AIAgentOutput } from './types.js';
+export {
+  InformationArchitectAgent,
+  processFlowsWithAI,
+  type ValidationError,
+  validateCompositionReferences,
+} from './ia-agent.js';
+export type { AIAgentOutput, UXSchema } from './types.js';
 
 import { commandHandler as generateIAHandler } from './commands/generate-ia';
 export const COMMANDS = [generateIAHandler];
@@ -9,4 +14,5 @@ export type {
   GenerateIAEvents,
   IAGeneratedEvent,
   IAGenerationFailedEvent,
+  IAValidationFailedEvent,
 } from './commands/generate-ia';