@flink-app/flink 0.14.3 → 2.0.0-alpha.100

package/spec/AgentDescendantDetection.spec.ts

@@ -0,0 +1,335 @@
+import { Project } from "ts-morph";
+import path from "path";
+import fs from "fs";
+
+describe("Agent Descendant Detection", () => {
+    let project: Project;
+    let tempDir: string;
+
+    beforeEach(() => {
+        // Create a new ts-morph project for each test
+        project = new Project({
+            compilerOptions: {
+                target: 99, // ESNext
+                module: 99, // ESNext
+                experimentalDecorators: true,
+            },
+            useInMemoryFileSystem: true,
+        });
+
+        // Create temp directory path (virtual in-memory)
+        tempDir = "/test";
+    });
+
+    /**
+     * Helper to test if isFlinkAgentDescendant would return true for a class in source code
+     */
+    function testAgentDetection(sourceCode: string, expectedDetection: boolean): void {
+        const sourceFile = project.createSourceFile(path.join(tempDir, "TestAgent.ts"), sourceCode);
+
+        // Find the exported class (mimics what TypeScriptCompiler does)
+        const classes = sourceFile.getClasses();
+        expect(classes.length).toBeGreaterThan(0);
+
+        // Get the last class in the file (which is typically the agent we're testing)
+        const agentClass = classes[classes.length - 1];
+
+        // Call the same logic as isFlinkAgentDescendant (inline for testing)
+        const result = isFlinkAgentDescendant(agentClass as any);
+
+        expect(result).toBe(expectedDetection);
+    }
+
+    /**
+     * Inline version of TypeScriptCompiler.isFlinkAgentDescendant for testing
+     */
+    function isFlinkAgentDescendant(cls: any): boolean {
+        const extendsClause = cls.getExtends();
+        if (!extendsClause) return false;
+
+        let currentExtends = extendsClause;
+        let depth = 0;
+        const maxDepth = 10;
+
+        while (currentExtends && depth < maxDepth) {
+            depth++;
+
+            const extendsText = currentExtends.getText().trim();
+
+            if (extendsText.includes("FlinkAgent")) {
+                return true;
+            }
+
+            const baseClassExpression = currentExtends.getExpression();
+            const baseClassSymbol = baseClassExpression.getType().getSymbol();
+
+            if (!baseClassSymbol) {
+                return false;
+            }
+
+            const declarations = baseClassSymbol.getDeclarations();
+            if (declarations.length === 0) {
+                return false;
+            }
+
+            const baseClassDecl = declarations[0];
+
+            if (!baseClassDecl.getKindName().includes("Class")) {
+                return false;
+            }
+
+            const baseClass = baseClassDecl as any;
+            currentExtends = baseClass.getExtends?.();
+
+            if (!currentExtends) {
+                return false;
+            }
+        }
+
+        return false;
+    }
+
+    describe("Direct FlinkAgent subclasses", () => {
+        it("should detect direct FlinkAgent subclass without generics", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+
+                export default class MyAgent extends FlinkAgent {
+                    id = "my-agent";
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+
+        it("should detect direct FlinkAgent subclass with generics", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+
+                export default class MyAgent extends FlinkAgent<any> {
+                    id = "my-agent";
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+
+        it("should detect direct FlinkAgent subclass with complex generic type", () => {
+            const source = `
+                interface AppContext {}
+                class FlinkAgent<Ctx, ConvCtx> {}
+
+                export default class MyAgent extends FlinkAgent<AppContext, { userId: string }> {
+                    id = "my-agent";
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+    });
+
+    describe("ConversationAgent subclasses", () => {
+        it("should detect ConversationAgent subclass", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+                class ConversationAgent<Ctx> extends FlinkAgent<Ctx> {}
+
+                export default class MyAgent extends ConversationAgent<any> {
+                    id = "my-agent";
+                    async loadConversation(id: string) { return null; }
+                    async saveConversation(id: string, data: any) {}
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+
+        it("should detect ConversationAgent subclass with specific context type", () => {
+            const source = `
+                interface AppContext {}
+                class FlinkAgent<Ctx> {}
+                class ConversationAgent<Ctx> extends FlinkAgent<Ctx> {}
+
+                export default class MyAgent extends ConversationAgent<AppContext> {
+                    id = "my-agent";
+                    async loadConversation(id: string) { return null; }
+                    async saveConversation(id: string, data: any) {}
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+    });
+
+    describe("InMemoryConversationAgent subclasses", () => {
+        it("should detect InMemoryConversationAgent subclass (3-level inheritance)", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+                class ConversationAgent<Ctx> extends FlinkAgent<Ctx> {}
+                class InMemoryConversationAgent<Ctx> extends ConversationAgent<Ctx> {}
+
+                export default class MyAgent extends InMemoryConversationAgent<any> {
+                    id = "my-agent";
+                    description = "Test agent";
+                    instructions() { return "You are helpful"; }
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+
+        it("should detect InMemoryConversationAgent with complex generics", () => {
+            const source = `
+                interface AppContext { repos: any; }
+                class FlinkAgent<Ctx, ConvCtx> {}
+                class ConversationAgent<Ctx> extends FlinkAgent<Ctx, any> {}
+                class InMemoryConversationAgent<Ctx> extends ConversationAgent<Ctx> {}
+
+                export default class MyAgent extends InMemoryConversationAgent<AppContext> {
+                    id = "my-agent";
+                    description = "Test agent";
+                    instructions() { return "You are helpful"; }
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+    });
+
+    describe("Custom intermediate base classes", () => {
+        it("should detect agent extending custom base that extends FlinkAgent", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+
+                abstract class MyCustomBase<Ctx> extends FlinkAgent<Ctx> {
+                    // Custom shared logic
+                }
+
+                export default class MyAgent extends MyCustomBase<any> {
+                    id = "my-agent";
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+
+        it("should detect agent with 4-level custom inheritance chain", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+                abstract class BaseAgent<Ctx> extends FlinkAgent<Ctx> {}
+                abstract class IntermediateAgent<Ctx> extends BaseAgent<Ctx> {}
+                abstract class SpecializedAgent<Ctx> extends IntermediateAgent<Ctx> {}
+
+                export default class MyAgent extends SpecializedAgent<any> {
+                    id = "deep-agent";
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+
+        it("should detect agent extending custom base extending ConversationAgent", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+                class ConversationAgent<Ctx> extends FlinkAgent<Ctx> {}
+
+                abstract class MyConversationBase<Ctx> extends ConversationAgent<Ctx> {
+                    // Custom conversation logic
+                }
+
+                export default class MyAgent extends MyConversationBase<any> {
+                    id = "my-agent";
+                    async loadConversation(id: string) { return null; }
+                    async saveConversation(id: string, data: any) {}
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+    });
+
+    describe("Negative cases - Non-agent classes", () => {
+        it("should NOT detect class with no extends clause", () => {
+            const source = `
+                export default class NotAnAgent {
+                    id = "not-agent";
+                }
+            `;
+            testAgentDetection(source, false);
+        });
+
+        it("should NOT detect class extending unrelated base class", () => {
+            const source = `
+                class SomeOtherClass {}
+
+                export default class MyClass extends SomeOtherClass {
+                    id = "not-agent";
+                }
+            `;
+            testAgentDetection(source, false);
+        });
+
+        it("should NOT detect class with similar name but different inheritance", () => {
+            const source = `
+                class Agent {}
+
+                export default class MyAgent extends Agent {
+                    id = "not-flink-agent";
+                }
+            `;
+            testAgentDetection(source, false);
+        });
+
+        it("should NOT detect class extending EventEmitter", () => {
+            const source = `
+                class EventEmitter {}
+
+                export default class MyService extends EventEmitter {
+                    id = "service";
+                }
+            `;
+            testAgentDetection(source, false);
+        });
+    });
+
+    describe("Edge cases", () => {
+        it("should handle class extending external module (unresolvable)", () => {
+            const source = `
+                import { SomeExternalClass } from "external-package";
+
+                export default class MyClass extends SomeExternalClass {
+                    id = "external";
+                }
+            `;
+            // Should return false when type resolution fails
+            testAgentDetection(source, false);
+        });
+
+        it("should respect max depth limit to prevent infinite loops", () => {
+            // Create a chain at maxDepth (10): MyAgent → Level8 → ... → Level1 → FlinkAgent
+            // Total depth: 10 levels (MyAgent is level 1, FlinkAgent is level 10)
+            const source = `
+                class FlinkAgent<Ctx> {}
+                class Level1<Ctx> extends FlinkAgent<Ctx> {}
+                class Level2<Ctx> extends Level1<Ctx> {}
+                class Level3<Ctx> extends Level2<Ctx> {}
+                class Level4<Ctx> extends Level3<Ctx> {}
+                class Level5<Ctx> extends Level4<Ctx> {}
+                class Level6<Ctx> extends Level5<Ctx> {}
+                class Level7<Ctx> extends Level6<Ctx> {}
+                class Level8<Ctx> extends Level7<Ctx> {}
+
+                export default class MyAgent extends Level8<any> {
+                    id = "deep-agent";
+                }
+            `;
+            // Should still detect within maxDepth (10 levels)
+            testAgentDetection(source, true);
+        });
+
+        it("should handle abstract classes in inheritance chain", () => {
+            const source = `
+                class FlinkAgent<Ctx> {}
+                abstract class AbstractBase<Ctx> extends FlinkAgent<Ctx> {
+                    abstract doSomething(): void;
+                }
+
+                export default class MyAgent extends AbstractBase<any> {
+                    id = "my-agent";
+                    doSomething() {}
+                }
+            `;
+            testAgentDetection(source, true);
+        });
+    });
+});

package/spec/AgentDuplicateDetection.spec.ts

@@ -0,0 +1,112 @@
+import { toKebabCase } from "../src/utils";
+
+describe("Agent Duplicate Detection Logic", () => {
+    describe("Instance name collisions (camelCase)", () => {
+        // Instance names are derived by lowercasing first character
+        const getInstanceName = (className: string) => {
+            return className.charAt(0).toLowerCase() + className.substring(1);
+        };
+
+        it("should show CarAgent vs Caragent do NOT collide (different casing)", () => {
+            const instance1 = getInstanceName("CarAgent");
+            const instance2 = getInstanceName("Caragent");
+
+            // CarAgent → carAgent, Caragent → caragent (no collision)
+            expect(instance1).toBe("carAgent");
+            expect(instance2).toBe("caragent");
+            expect(instance1).not.toBe(instance2);
+        });
+
+        it("should detect collision example: CarAgent vs CARAgent", () => {
+            // This is a contrived example, but shows the logic
+            const instance1 = getInstanceName("CarAgent");
+            const instance2 = getInstanceName("CarAgent"); // Exact same name
+
+            // Both become "carAgent" - COLLISION!
+            expect(instance1).toBe("carAgent");
+            expect(instance2).toBe("carAgent");
+            expect(instance1).toBe(instance2);
+        });
+
+        it("should not collide for different class names", () => {
+            const instance1 = getInstanceName("CarAgent");
+            const instance2 = getInstanceName("BikeAgent");
+
+            expect(instance1).toBe("carAgent");
+            expect(instance2).toBe("bikeAgent");
+            expect(instance1).not.toBe(instance2);
+        });
+    });
+
+    describe("Agent ID collisions (kebab-case)", () => {
+        it("should detect APIAgent vs ApiAgent collision", () => {
+            const id1 = toKebabCase("APIAgent");
+            const id2 = toKebabCase("ApiAgent");
+
+            // Both become "api-agent" - COLLISION!
+            expect(id1).toBe("api-agent");
+            expect(id2).toBe("api-agent");
+            expect(id1).toBe(id2);
+        });
+
+        it("should detect HTMLParser vs HtmlParser collision", () => {
+            const id1 = toKebabCase("HTMLParser");
+            const id2 = toKebabCase("HtmlParser");
+
+            // Both become "html-parser" - COLLISION!
+            expect(id1).toBe("html-parser");
+            expect(id2).toBe("html-parser");
+            expect(id1).toBe(id2);
+        });
+
+        it("should detect XMLHttpRequest vs XmlHttpRequest collision", () => {
+            const id1 = toKebabCase("XMLHttpRequest");
+            const id2 = toKebabCase("XmlHttpRequest");
+
+            // Both become "xml-http-request" - COLLISION!
+            expect(id1).toBe("xml-http-request");
+            expect(id2).toBe("xml-http-request");
+            expect(id1).toBe(id2);
+        });
+
+        it("should not collide for different agent names", () => {
+            const id1 = toKebabCase("CarAgent");
+            const id2 = toKebabCase("BikeAgent");
+
+            expect(id1).toBe("car-agent");
+            expect(id2).toBe("bike-agent");
+            expect(id1).not.toBe(id2);
+        });
+
+        it("should not collide for similar but distinct names", () => {
+            const id1 = toKebabCase("CarAgent");
+            const id2 = toKebabCase("CarPricingAgent");
+
+            expect(id1).toBe("car-agent");
+            expect(id2).toBe("car-pricing-agent");
+            expect(id1).not.toBe(id2);
+        });
+    });
+
+    describe("Real-world collision scenarios", () => {
+        it("should show that explicit IDs prevent collisions", () => {
+            // Even if class names would collide, explicit IDs prevent issues
+            const explicitId1 = "api-agent-v1";
+            const explicitId2 = "api-agent-v2";
+
+            expect(explicitId1).not.toBe(explicitId2);
+        });
+
+        it("should demonstrate the collision resolution path", () => {
+            // Problem: Both APIAgent and ApiAgent → "api-agent"
+            const problematicId1 = toKebabCase("APIAgent");
+            const problematicId2 = toKebabCase("ApiAgent");
+            expect(problematicId1).toBe(problematicId2); // Collision!
+
+            // Solution: Use explicit IDs
+            const resolvedId1 = "api-agent-v1";
+            const resolvedId2 = "api-agent-v2";
+            expect(resolvedId1).not.toBe(resolvedId2); // No collision
+        });
+    });
+});