@adaas/a-frame 0.0.23 → 0.1.2

package/tests/integration/A-FrameDynamicFeature.integration.test.ts

@@ -0,0 +1,337 @@
+import { A_Component, A_Concept, A_Container, A_Error, A_Fragment } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { A_FrameIndex } from '@adaas/a-frame/index';
+import { config } from 'dotenv';
+import { A_FrameDynamicFeature, A_FrameDynamicFeatureMapResult } from '@adaas/a-frame/dynamic-feature';
+import { A_FRAME_MODELS } from '@adaas/a-frame/models';
+
+config();
+
+jest.setTimeout(60 * 60 * 1000);
+
+// ─── Test domain: User management + task workflow ─────────────────────────────
+//
+// Service components with methods decorated via @A_Frame.Define so they are
+// embedded and indexed.  The DynamicFeature mapper resolves each workflow step
+// to a concrete class + method using cosine-similarity lookup.
+
+// ── Components ────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'A service component that manages user accounts: registers new users, fetches user profiles, updates contact information, and handles account deactivation.',
+})
+class UserService extends A_Component {
+
+    @A_Frame.Define({
+        description: 'Creates a new user account from the provided registration details: validates uniqueness of email, hashes the password, persists the UserEntity, and returns the created user.',
+    })
+    createUser(): void {}
+
+    @A_Frame.Define({
+        description: 'Retrieves an existing user account by its unique identifier. Returns the full UserEntity including profile data, or throws if the user is not found.',
+    })
+    getUser(): void {}
+
+    @A_Frame.Define({
+        description: 'Updates mutable profile fields (displayName, email) for the given user account. Validates uniqueness of the new email before persisting changes.',
+    })
+    updateUser(): void {}
+}
+
+@A_Frame.Define({
+    description: 'A service component responsible for authenticating users: validates credentials, issues JWT tokens, refreshes expired tokens, and invalidates sessions on logout.',
+})
+class AuthService extends A_Component {
+
+    @A_Frame.Define({
+        description: 'Authenticates a user with email and password. Verifies the password hash, issues a signed JWT access token and a refresh token, and records the login timestamp.',
+    })
+    login(): void {}
+
+    @A_Frame.Define({
+        description: 'Validates a JWT access token and returns the decoded user identity. Throws an authentication error if the token is expired or tampered.',
+    })
+    verifyToken(): void {}
+}
+
+@A_Frame.Define({
+    description: 'A service component that manages tasks inside projects: creates tasks, assigns them to team members, updates their status, and lists tasks filtered by project or assignee.',
+})
+class TaskService extends A_Component {
+
+    @A_Frame.Define({
+        description: 'Creates a new task inside the specified project. Sets the title, description, deadline, and initial status. Associates the task with the requesting user as creator.',
+    })
+    createTask(): void {}
+
+    @A_Frame.Define({
+        description: 'Assigns an existing task to a team member. Updates the assignee reference on the TaskEntity and dispatches an assignment notification event.',
+    })
+    assignTask(): void {}
+
+    @A_Frame.Define({
+        description: 'Updates the current status of a task (e.g. from "open" to "in-progress" or "done"). Records the state transition timestamp and triggers downstream side-effects.',
+    })
+    updateTaskStatus(): void {}
+}
+
+@A_Frame.Define({
+    description: 'A service component that sends email notifications: task assignment alerts, deadline reminders, and status-change summaries to the relevant team members.',
+})
+class NotificationService extends A_Component {
+
+    @A_Frame.Define({
+        description: 'Sends an email notification to a user about a newly assigned task, including the task title, deadline, and a link to the task details page.',
+    })
+    sendAssignmentEmail(): void {}
+}
+
+// ── Fragments ─────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'A fragment that carries the authenticated user identity, current session token, and request-scoped metadata across all service calls within a single HTTP request lifecycle.',
+})
+class RequestContext extends A_Fragment {}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const TEST_COMPONENTS = [
+    UserService, AuthService, TaskService, NotificationService,
+];
+
+async function buildConcept() {
+    const container = new A_Container({ name: 'DynamicFeature Test Container', components: TEST_COMPONENTS });
+    const concept = new A_Concept({
+        name: 'DynamicFeature Test Concept',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+
+    // Embed all definitions that don't have a vector yet.
+    // (A_FRAME_SYNC=false in jest.setup.ts suppresses automatic sync.)
+    const allDefs = A_FrameIndex.listDefinitions({});
+    const unembedded = allDefs.filter(d => !d.isEmbed);
+    console.log(`\n[Index] definitions: ${allDefs.length}, need embedding: ${unembedded.length}`);
+
+    if (unembedded.length > 0) {
+        await Promise.all(unembedded.map(d => d.embed()));
+        const embeddedNow = allDefs.filter(d => d.isEmbed).length;
+        console.log(`[Index] embedded after explicit embed: ${embeddedNow}`);
+    }
+
+    return { concept, container };
+}
+
+function logMapResult(label: string, feature: A_FrameDynamicFeature) {
+    const mapResult = feature.mapResult;
+    if (!mapResult) {
+        console.log(`\n=== ${label} === (no map result yet)\n`);
+        return;
+    }
+
+    const matchedSteps   = mapResult.steps.filter(s => s.matchedMethod !== null);
+    const unmatchedSteps = mapResult.steps.filter(s => s.matchedMethod === null);
+    const allElements    = [...mapResult.components, ...mapResult.fragments, ...mapResult.entities];
+    const matchedEls     = allElements.filter(e => e.matchedClass !== null);
+
+    console.log(`\n=== ${label} ===`);
+    console.log(`  Steps    : ${matchedSteps.length} matched / ${mapResult.steps.length} total`);
+    if (matchedSteps.length) {
+        console.log('  Methods  :',
+            matchedSteps.map(s => `${s.matchedClass}.${s.matchedMethod} (${s.matchScore.toFixed(3)})`).join(', '));
+    }
+    if (unmatchedSteps.length) {
+        console.log('  Unmatched:',
+            unmatchedSteps.map(s => `"${s.prompt.slice(0, 60)}…"`).join('\n             '));
+    }
+    console.log(`  Elements : ${matchedEls.length} matched / ${allElements.length} total`);
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame DynamicFeature Tests', () => {
+
+    // ── 1. Generate + verify step matching ────────────────────────────────────
+
+    describe('Integration — generate and match steps to methods', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('generates a feature workflow and matches steps to registered methods', async () => {
+            try {
+                const feature = new A_FrameDynamicFeature({
+                    prompt: 'Implement a "create task and notify assignee" workflow: a user logs in, a task is created in the project, the task is assigned to a team member, and an email notification is sent to the assignee.',
+                });
+
+                expect(feature.modelName).toBe(A_FRAME_MODELS.PULSAR);
+                expect(feature.definition).toBeNull();
+                expect(feature.mapResult).toBeNull();
+                expect(feature.version).toBe(0);
+                expect(feature.history.length).toBe(0);
+
+                container.scope.register(feature);
+                await feature.generate();
+
+                expect(feature.definition).not.toBeNull();
+                expect(feature.definition!.steps.length).toBeGreaterThan(0);
+                expect(feature.mapResult).toBeNull();   // not mapped yet
+                expect(feature.version).toBe(0);
+                expect(feature.history.length).toBe(1); // generate recorded
+
+                const def = feature.definition!;
+                console.log(`\n[Definition] title: "${def.title}"`);
+                console.log(`[Definition] steps: ${def.steps.length}`);
+                console.log(`[Definition] components: ${def.components.length}, fragments: ${def.fragments.length}, entities: ${def.entities.length}`);
+
+                // Map steps to real methods
+                await feature.map();
+                logMapResult('After generate + map', feature);
+
+                expect(feature.mapResult).not.toBeNull();
+                const mapResult = feature.mapResult!;
+
+                // Every step entry must be typed correctly
+                for (const step of mapResult.steps) {
+                    expect(typeof step.matchedClass === 'string' || step.matchedClass === null).toBe(true);
+                    expect(typeof step.matchedMethod === 'string' || step.matchedMethod === null).toBe(true);
+                    expect(typeof step.matchScore).toBe('number');
+                }
+
+                // At least one step must be matched to a known method
+                const matchedSteps = mapResult.steps.filter(s => s.matchedMethod !== null);
+                console.log(`  → Matched ${matchedSteps.length} of ${mapResult.steps.length} steps to methods`);
+                expect(matchedSteps.length).toBeGreaterThan(0);
+
+                // Matched classes must come from our registered service set
+                const knownClasses = new Set([
+                    'UserService', 'AuthService', 'TaskService', 'NotificationService', 'RequestContext',
+                ]);
+                for (const step of mapResult.steps) {
+                    if (step.matchedClass !== null) {
+                        expect(knownClasses.has(step.matchedClass)).toBe(true);
+                    }
+                }
+
+                // No containers — workflows are cross-cutting
+                expect((mapResult as any).containers).toBeUndefined();
+
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+    // ── 2. Generate + sequential patches ──────────────────────────────────────
+
+    describe('Integration — generate and sequential patches', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('patches update the workflow definition and track version/history', async () => {
+            try {
+                const feature = new A_FrameDynamicFeature({
+                    prompt: 'Implement a user registration workflow: validate the registration payload, create the user account, and return the created user profile.',
+                });
+
+                container.scope.register(feature);
+
+                // ── generate ──────────────────────────────────────────────────
+                await feature.generate();
+                await feature.map();
+                logMapResult('After generate + map', feature);
+
+                expect(feature.definition).not.toBeNull();
+                expect(feature.mapResult).not.toBeNull();
+                expect(feature.version).toBe(0);
+                expect(feature.history.length).toBe(1);
+
+                const workflowAfterGenerate = feature.workflow;
+
+                // ── patch: add a step ──────────────────────────────────────────
+                await feature.patch('Add a step to send a welcome email to the newly registered user after their account is created.');
+                await feature.map();
+                logMapResult('After patch — add welcome email step', feature);
+
+                expect(feature.version).toBe(1);
+                expect(feature.history.length).toBe(2);
+                expect(feature.workflow).not.toBe(workflowAfterGenerate);
+
+                // ── patch: remove a step ───────────────────────────────────────
+                const workflowAfterPatch1 = feature.workflow;
+                await feature.patch('Remove the welcome email step that was just added.');
+                await feature.map();
+                logMapResult('After patch — remove welcome email step', feature);
+
+                expect(feature.version).toBe(2);
+                expect(feature.history.length).toBe(3);
+                expect(feature.workflow).not.toBe(workflowAfterPatch1);
+
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+    // ── 3. `workflow` getter serialises without embeddings ────────────────────
+
+    describe('Unit-style — workflow serialisation', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('workflow getter returns valid JSON and strips embedding arrays', async () => {
+            try {
+                const feature = new A_FrameDynamicFeature({
+                    prompt: 'Implement a simple user login and token verification workflow.',
+                });
+
+                // Before generate: returns an empty-shell JSON
+                expect(() => JSON.parse(feature.workflow)).not.toThrow();
+                const empty = JSON.parse(feature.workflow);
+                expect(empty.steps).toEqual([]);
+
+                container.scope.register(feature);
+                await feature.generate();
+
+                // After generate: valid JSON with no embedding arrays
+                expect(() => JSON.parse(feature.workflow)).not.toThrow();
+                const parsed = JSON.parse(feature.workflow);
+                expect(parsed.title).toBeTruthy();
+                expect(Array.isArray(parsed.steps)).toBe(true);
+
+                // Assert no step carries an embedding
+                for (const step of parsed.steps) {
+                    expect(step.embedding).toBeUndefined();
+                }
+                for (const el of [...(parsed.components ?? []), ...(parsed.fragments ?? []), ...(parsed.entities ?? [])]) {
+                    expect(el.embedding).toBeUndefined();
+                }
+
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+});

package/tests/integration/A-FrameDynamicStructure.integration.test.ts

@@ -0,0 +1,264 @@
+import { A_Component, A_Concept, A_Container, A_Entity, A_Error, A_Fragment } from '@adaas/a-concept';
+import { A_Frame } from '@adaas/a-frame/core';
+import { A_FrameIndex } from '@adaas/a-frame/index';
+import { config } from 'dotenv';
+import { A_FrameDynamicStructure, A_FrameComponentMapResult } from '@adaas/a-frame/dynamic-structure';
+import { A_FRAME_MODELS } from '@adaas/a-frame/models';
+
+config();
+
+jest.setTimeout(60 * 60 * 1000);
+
+// ─── Test domain: Task-management backend ─────────────────────────────────────
+//
+// These classes are decorated with @A_Frame.Define so they get added to the
+// A-Frame index and embedded during concept.load(). The DynamicStructure
+// matching loop then uses cosine-similarity to resolve generated element prompts
+// back to these registered class names.
+
+// ── Components ────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'A service component that creates, updates, and deletes tasks, tracks deadline and status changes, and links each task to a project and an assigned team member.',
+})
+class TaskService extends A_Component {}
+
+@A_Frame.Define({
+    description: 'A service component that manages project creation and ownership, adds and removes team members from projects, and retrieves projects scoped by owner or member.',
+})
+class ProjectService extends A_Component {}
+
+@A_Frame.Define({
+    description: 'A service component that authenticates users with email and password, issues JWT access tokens, validates tokens on incoming requests, and handles session expiry and refresh.',
+})
+class AuthService extends A_Component {}
+
+@A_Frame.Define({
+    description: 'A service component that sends email notifications to assigned team members when a task deadline approaches, a task is newly assigned, or a task status changes.',
+})
+class EmailNotificationService extends A_Component {}
+
+// ── Containers ────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'A container module that bootstraps the HTTP REST API server, registers route handlers for project and task endpoints, and applies JWT authentication middleware to incoming requests.',
+})
+class ApiServerContainer extends A_Component {}
+
+@A_Frame.Define({
+    description: 'A container module that runs background worker processes, polls the database for upcoming task deadlines, and triggers email notifications without blocking the main API server.',
+})
+class BackgroundWorkerContainer extends A_Component {}
+
+// ── Fragments ─────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'A fragment that carries the authenticated user identity, active project scope reference, and per-request metadata across all service calls within a single HTTP request lifecycle.',
+})
+class RequestContext extends A_Fragment {}
+
+// ── Entities ──────────────────────────────────────────────────────────────────
+
+@A_Frame.Define({
+    description: 'An entity representing a task with a unique ID, title, description, deadline date, current status, a reference to the assigned team member, and a reference to the parent project.',
+})
+class TaskEntity extends A_Entity {}
+
+@A_Frame.Define({
+    description: 'An entity representing a project with a unique ID, owner reference, name, description, and a list of team member references.',
+})
+class ProjectEntity extends A_Entity {}
+
+@A_Frame.Define({
+    description: 'An entity representing a registered user account with a unique ID, email address, display name, and a hashed password.',
+})
+class UserEntity extends A_Entity {}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const TEST_COMPONENTS = [
+    // Components
+    TaskService, ProjectService, AuthService, EmailNotificationService,
+    // Containers (registered as components so the concept embeds their definitions)
+    ApiServerContainer, BackgroundWorkerContainer,
+];
+
+async function buildConcept() {
+    const container = new A_Container({ name: 'DynamicStructure Test Container', components: TEST_COMPONENTS });
+    const concept = new A_Concept({
+        name: 'Test Concept',
+        components: [A_Frame],
+        containers: [container],
+    });
+    await concept.load();
+
+    // Sync is disabled globally in jest.setup.ts (A_FRAME_SYNC=false) to keep
+    // unit and other integration tests fast. For this test we need the component
+    // definitions to be embedded so the matching loop can do cosine similarity.
+    // Embed only the definitions that don't have a vector yet.
+    const allDefs = A_FrameIndex.listDefinitions({});
+    const unembedded = allDefs.filter(d => !d.isEmbed);
+    console.log(`\n[Index] definitions: ${allDefs.length}, need embedding: ${unembedded.length}`);
+
+    if (unembedded.length > 0) {
+        await Promise.all(unembedded.map(d => d.embed()));
+        const embeddedNow = allDefs.filter(d => d.isEmbed).length;
+        console.log(`[Index] embedded after explicit embed: ${embeddedNow}`);
+    }
+
+    return { concept, container };
+}
+
+function logDefinition(label: string, structure: A_FrameDynamicStructure) {
+    const mapResult = structure.mapResult;
+    if (!mapResult) {
+        console.log(`\n=== ${label} === (no map result yet)\n`);
+        return;
+    }
+    const allElements = [
+        ...mapResult.containers,
+        ...mapResult.components,
+        ...mapResult.fragments,
+        ...mapResult.entities,
+    ];
+    const matched   = allElements.filter((e: any) => e.matchedClass !== null);
+    const unmatched = allElements.filter((e: any) => e.matchedClass === null);
+
+    console.log(`\n=== ${label} ===`);
+    console.log(`  Matched  : ${matched.length} / ${allElements.length}`);
+    if (matched.length)   console.log('  Classes  :', matched.map((e: any) => e.matchedClass).join(', '));
+    if (unmatched.length) console.log('  Unmatched:', unmatched.map((e: any) => `"${e.prompt.slice(0, 60)}…"`).join('\n             '));
+    console.log();
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('A-Frame DynamicStructure Tests', () => {
+
+    // ── 1. Generate + verify component matching ───────────────────────────────
+
+    describe('Integration — generate and match components', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('generates a structure and matches known components', async () => {
+            try {
+                const structure = new A_FrameDynamicStructure({
+                    prompt: 'Design a backend for a task-management app. Users create projects, add tasks with deadlines, assign tasks to team members, and receive email notifications when deadlines approach.',
+                });
+
+                expect(structure.modelName).toBe(A_FRAME_MODELS.PULSAR);
+
+                container.scope.register(structure);
+                await structure.generate();
+                await structure.map();
+
+                logDefinition('Generated + mapped structure', structure);
+
+                expect(structure.definition).not.toBeNull();
+                expect(structure.mapResult).not.toBeNull();
+                expect(structure.version).toBe(0);
+                expect(structure.history.length).toBe(1);
+
+                const mapResult = structure.mapResult!;
+                const allElements = [
+                    ...mapResult.containers,
+                    ...mapResult.components,
+                    ...mapResult.fragments,
+                    ...mapResult.entities,
+                ];
+
+                // Every element must have matchedClass typed correctly (string or null)
+                for (const el of allElements) {
+                    expect(typeof el.matchedClass === 'string' || el.matchedClass === null).toBe(true);
+                }
+
+                // At least one element should have been matched to a registered component
+                const matchedCount = allElements.filter((e: any) => e.matchedClass !== null).length;
+                console.log(`  → Matched ${matchedCount} of ${allElements.length} elements`);
+                expect(matchedCount).toBeGreaterThan(0);
+
+                // The matched class names should come from our registered set
+                const knownNames = new Set([
+                    'TaskService', 'ProjectService', 'AuthService', 'EmailNotificationService',
+                    'ApiServerContainer', 'BackgroundWorkerContainer',
+                    'RequestContext',
+                    'TaskEntity', 'ProjectEntity', 'UserEntity',
+                ]);
+                for (const el of allElements) {
+                    if (el.matchedClass !== null) {
+                        expect(knownNames.has(el.matchedClass)).toBe(true);
+                    }
+                }
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+    // ── 2. Generate + sequential patches ─────────────────────────────────────
+
+    describe('Integration — generate and sequential patches', () => {
+
+        let container: A_Container;
+
+        beforeEach(async () => {
+            ({ container } = await buildConcept());
+        });
+
+        it('patches update the structure and track history/version', async () => {
+            try {
+                const structure = new A_FrameDynamicStructure({
+                    prompt: 'Design a backend for a task-management app. Users create projects, add tasks with deadlines, assign tasks to team members, and receive email notifications when deadlines approach.',
+                });
+
+                container.scope.register(structure);
+
+                // ── generate ──────────────────────────────────────────────
+                await structure.generate();
+                await structure.map();
+                logDefinition('After generate + map', structure);
+
+                expect(structure.definition).not.toBeNull();
+                expect(structure.mapResult).not.toBeNull();
+                expect(structure.version).toBe(0);
+                expect(structure.history.length).toBe(1);
+
+                const structureAfterGenerate = structure.structure;
+
+                // ── patch: add ────────────────────────────────────────────
+                await structure.patch('Add a dedicated component for handling file attachment uploads linked to tasks.');
+                await structure.map();
+                logDefinition('After patch — add file upload component', structure);
+
+                expect(structure.version).toBe(1);
+                expect(structure.history.length).toBe(2);
+                expect(structure.structure).not.toBe(structureAfterGenerate);
+
+                // ── patch: remove ─────────────────────────────────────────
+                const structureAfterPatch1 = structure.structure;
+                await structure.patch('Remove the file attachment upload component that was just added.');
+                await structure.map();
+                logDefinition('After patch — remove file upload component', structure);
+
+                expect(structure.version).toBe(2);
+                expect(structure.history.length).toBe(3);
+                expect(structure.structure).not.toBe(structureAfterPatch1);
+
+            } catch (error) {
+                if (error instanceof A_Error) console.error('A_Error:', error.toJSON());
+                else console.error('Unexpected error:', error);
+                throw error;
+            }
+        });
+
+    });
+
+});