@friggframework/devtools 2.0.0--canary.461.849e166.0 → 2.0.0--canary.474.aa465e4.0

package/infrastructure/domains/shared/base-resolver.js

@@ -0,0 +1,186 @@
+/**
+ * Base Resource Resolver
+ *
+ * Abstract base class for resource ownership resolution.
+ * Each builder has its own resolver (VpcResolver, AuroraResolver, etc.)
+ * that extends this base class.
+ *
+ * Resolver Layer - Hexagonal Architecture
+ */
+
+const {
+    ResourceOwnership,
+    resolveOwnership,
+    findStackResource,
+    findExternalResource,
+    findAllExternalResources,
+    isResourceInStack
+} = require('./types');
+
+class BaseResourceResolver {
+    /**
+     * Find resource in CloudFormation stack
+     * @protected
+     * @param {string} logicalId - Logical resource ID
+     * @param {Object} discovery - Discovery result
+     * @returns {Object|null} Stack resource or null
+     */
+    findInStack(logicalId, discovery) {
+        return findStackResource(discovery, logicalId);
+    }
+
+    /**
+     * Find external resource by type
+     * @protected
+     * @param {string} resourceType - CloudFormation resource type
+     * @param {Object} discovery - Discovery result
+     * @returns {Object|null} External resource or null
+     */
+    findExternal(resourceType, discovery) {
+        return findExternalResource(discovery, resourceType);
+    }
+
+    /**
+     * Find all external resources by type
+     * @protected
+     * @param {Object} discovery - Discovery result
+     * @param {string} resourceType - CloudFormation resource type
+     * @returns {Object[]} Array of external resources
+     */
+    findAllExternalResources(discovery, resourceType) {
+        return findAllExternalResources(discovery, resourceType);
+    }
+
+    /**
+     * Check if resource is in stack
+     * @protected
+     * @param {string} logicalId - Logical resource ID
+     * @param {Object} discovery - Discovery result
+     * @returns {boolean}
+     */
+    isInStack(logicalId, discovery) {
+        return isResourceInStack(discovery, logicalId);
+    }
+
+    /**
+     * Validate that external resource IDs are provided when required
+     * @protected
+     * @param {*} resourceIds - Resource IDs to validate
+     * @param {string} resourceName - Name for error message
+     * @throws {Error} If resourceIds is not provided
+     */
+    requireExternalIds(resourceIds, resourceName) {
+        if (!resourceIds || (Array.isArray(resourceIds) && resourceIds.length === 0)) {
+            throw new Error(
+                `ownership='external' for ${resourceName} requires external.${resourceName} to be provided in app definition`
+            );
+        }
+    }
+
+    /**
+     * Resolve ownership for a resource
+     * @protected
+     * @param {string} userIntent - User's ownership intent ('stack' | 'external' | 'auto')
+     * @param {string} logicalId - CloudFormation logical ID
+     * @param {string} resourceType - CloudFormation resource type
+     * @param {Object} discovery - Discovery result
+     * @returns {Object} Resource decision
+     */
+    resolveResourceOwnership(userIntent, logicalId, resourceType, discovery) {
+        // Use helper to work with both old flat structure and new structured
+        const structured = discovery._structured || discovery;
+
+        const inStack = this.isInStack(logicalId, structured);
+        const externalResource = this.findExternal(resourceType, structured);
+
+        const ownership = resolveOwnership(
+            userIntent || ResourceOwnership.AUTO,
+            inStack,
+            externalResource !== null
+        );
+
+        const stackResource = inStack ? this.findInStack(logicalId, structured) : null;
+
+        return {
+            ownership,
+            physicalId: stackResource?.physicalId || externalResource?.physicalId,
+            reason: this._buildReasonString(ownership, inStack, externalResource, userIntent),
+            metadata: {
+                logicalId,
+                resourceType,
+                userIntent: userIntent || 'auto',
+                inStack,
+                foundExternal: externalResource !== null
+            }
+        };
+    }
+
+    /**
+     * Build human-readable reason string
+     * @private
+     */
+    _buildReasonString(ownership, inStack, externalResource, userIntent) {
+        if (userIntent === 'stack') {
+            return 'User explicitly specified ownership=stack';
+        }
+
+        if (userIntent === 'external') {
+            return 'User explicitly specified ownership=external';
+        }
+
+        // Auto-decided
+        if (ownership === ResourceOwnership.STACK) {
+            if (inStack) {
+                return 'Found in CloudFormation stack (must keep in template to avoid deletion)';
+            }
+            return 'No existing resource found - will create in stack';
+        }
+
+        if (ownership === ResourceOwnership.EXTERNAL) {
+            return 'Found external resource via discovery';
+        }
+
+        return 'Ownership resolved via auto-detection';
+    }
+
+    /**
+     * Create a resource decision for explicit external reference
+     * @protected
+     * @param {string|string[]} physicalIds - Physical resource ID(s)
+     * @param {string} reason - Reason string
+     * @returns {Object} Resource decision
+     */
+    createExternalDecision(physicalIds, reason = 'Using external resource reference') {
+        const ids = Array.isArray(physicalIds) ? physicalIds : [physicalIds];
+
+        return {
+            ownership: ResourceOwnership.EXTERNAL,
+            physicalId: ids[0],
+            physicalIds: ids,
+            reason,
+            metadata: {
+                source: 'user-provided'
+            }
+        };
+    }
+
+    /**
+     * Create a resource decision for stack-managed resource
+     * @protected
+     * @param {string} [physicalId] - Physical ID if resource already exists
+     * @param {string} reason - Reason string
+     * @returns {Object} Resource decision
+     */
+    createStackDecision(physicalId = null, reason = 'Managed by CloudFormation stack') {
+        return {
+            ownership: ResourceOwnership.STACK,
+            physicalId,
+            reason,
+            metadata: {
+                source: physicalId ? 'discovered' : 'new'
+            }
+        };
+    }
+}
+
+module.exports = BaseResourceResolver;

package/infrastructure/domains/shared/base-resolver.test.js

@@ -0,0 +1,305 @@
+const BaseResourceResolver = require('./base-resolver');
+const { ResourceOwnership } = require('./types');
+
+describe('BaseResourceResolver', () => {
+    let resolver;
+
+    beforeEach(() => {
+        resolver = new BaseResourceResolver();
+    });
+
+    describe('helper methods', () => {
+        const mockDiscovery = {
+            stackManaged: [
+                { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' },
+                { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-456', resourceType: 'AWS::EC2::SecurityGroup' }
+            ],
+            external: [
+                { physicalId: 'vpc-external', resourceType: 'AWS::EC2::VPC', source: 'tag-search' }
+            ],
+            fromCloudFormation: true
+        };
+
+        describe('findInStack', () => {
+            it('should find resource in stack', () => {
+                const resource = resolver.findInStack('FriggVPC', mockDiscovery);
+
+                expect(resource).toEqual({
+                    logicalId: 'FriggVPC',
+                    physicalId: 'vpc-123',
+                    resourceType: 'AWS::EC2::VPC'
+                });
+            });
+
+            it('should return null if not found', () => {
+                const resource = resolver.findInStack('NonExistent', mockDiscovery);
+                expect(resource).toBeNull();
+            });
+        });
+
+        describe('findExternal', () => {
+            it('should find external resource by type', () => {
+                const resource = resolver.findExternal('AWS::EC2::VPC', mockDiscovery);
+
+                expect(resource).toEqual({
+                    physicalId: 'vpc-external',
+                    resourceType: 'AWS::EC2::VPC',
+                    source: 'tag-search'
+                });
+            });
+
+            it('should return null if not found', () => {
+                const resource = resolver.findExternal('AWS::RDS::DBCluster', mockDiscovery);
+                expect(resource).toBeNull();
+            });
+        });
+
+        describe('isInStack', () => {
+            it('should return true if resource is in stack', () => {
+                expect(resolver.isInStack('FriggVPC', mockDiscovery)).toBe(true);
+                expect(resolver.isInStack('FriggLambdaSecurityGroup', mockDiscovery)).toBe(true);
+            });
+
+            it('should return false if resource is not in stack', () => {
+                expect(resolver.isInStack('NonExistent', mockDiscovery)).toBe(false);
+            });
+        });
+
+        describe('requireExternalIds', () => {
+            it('should not throw if IDs are provided', () => {
+                expect(() => resolver.requireExternalIds('vpc-123', 'vpcId')).not.toThrow();
+                expect(() => resolver.requireExternalIds(['sg-1', 'sg-2'], 'securityGroupIds')).not.toThrow();
+            });
+
+            it('should throw if IDs are missing', () => {
+                expect(() => resolver.requireExternalIds(undefined, 'vpcId')).toThrow(
+                    "ownership='external' for vpcId requires external.vpcId"
+                );
+                expect(() => resolver.requireExternalIds(null, 'vpcId')).toThrow();
+                expect(() => resolver.requireExternalIds([], 'securityGroupIds')).toThrow();
+            });
+        });
+    });
+
+    describe('resolveResourceOwnership', () => {
+        describe('with explicit stack intent', () => {
+            it('should return STACK ownership', () => {
+                const discovery = {
+                    stackManaged: [],
+                    external: [{ physicalId: 'vpc-ext', resourceType: 'AWS::EC2::VPC', source: 'tag-search' }],
+                    fromCloudFormation: false
+                };
+
+                const decision = resolver.resolveResourceOwnership(
+                    'stack',
+                    'FriggVPC',
+                    'AWS::EC2::VPC',
+                    discovery
+                );
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.reason).toContain('User explicitly specified ownership=stack');
+            });
+        });
+
+        describe('with explicit external intent', () => {
+            it('should return EXTERNAL ownership', () => {
+                const discovery = {
+                    stackManaged: [
+                        { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' }
+                    ],
+                    external: [],
+                    fromCloudFormation: true
+                };
+
+                const decision = resolver.resolveResourceOwnership(
+                    'external',
+                    'FriggVPC',
+                    'AWS::EC2::VPC',
+                    discovery
+                );
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.reason).toContain('User explicitly specified ownership=external');
+            });
+        });
+
+        describe('with auto intent', () => {
+            it('should return STACK if resource is in stack (CRITICAL)', () => {
+                const discovery = {
+                    stackManaged: [
+                        { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-069629001ade41c9a', resourceType: 'AWS::EC2::SecurityGroup' }
+                    ],
+                    external: [],
+                    fromCloudFormation: true
+                };
+
+                const decision = resolver.resolveResourceOwnership(
+                    'auto',
+                    'FriggLambdaSecurityGroup',
+                    'AWS::EC2::SecurityGroup',
+                    discovery
+                );
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBe('sg-069629001ade41c9a');
+                expect(decision.reason).toContain('Found in CloudFormation stack');
+                expect(decision.reason).toContain('must keep in template to avoid deletion');
+            });
+
+            it('should return EXTERNAL if found externally but not in stack', () => {
+                const discovery = {
+                    stackManaged: [],
+                    external: [
+                        { physicalId: 'vpc-external', resourceType: 'AWS::EC2::VPC', source: 'tag-search' }
+                    ],
+                    fromCloudFormation: false
+                };
+
+                const decision = resolver.resolveResourceOwnership(
+                    'auto',
+                    'FriggVPC',
+                    'AWS::EC2::VPC',
+                    discovery
+                );
+
+                expect(decision.ownership).toBe(ResourceOwnership.EXTERNAL);
+                expect(decision.physicalId).toBe('vpc-external');
+                expect(decision.reason).toContain('Found external resource via discovery');
+            });
+
+            it('should return STACK if not found anywhere (create new)', () => {
+                const discovery = {
+                    stackManaged: [],
+                    external: [],
+                    fromCloudFormation: false
+                };
+
+                const decision = resolver.resolveResourceOwnership(
+                    'auto',
+                    'FriggVPC',
+                    'AWS::EC2::VPC',
+                    discovery
+                );
+
+                expect(decision.ownership).toBe(ResourceOwnership.STACK);
+                expect(decision.physicalId).toBeUndefined();
+                expect(decision.reason).toContain('No existing resource found - will create in stack');
+            });
+        });
+
+        describe('metadata', () => {
+            it('should include complete metadata', () => {
+                const discovery = {
+                    stackManaged: [
+                        { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' }
+                    ],
+                    external: [],
+                    fromCloudFormation: true
+                };
+
+                const decision = resolver.resolveResourceOwnership(
+                    'auto',
+                    'FriggVPC',
+                    'AWS::EC2::VPC',
+                    discovery
+                );
+
+                expect(decision.metadata).toEqual({
+                    logicalId: 'FriggVPC',
+                    resourceType: 'AWS::EC2::VPC',
+                    userIntent: 'auto',
+                    inStack: true,
+                    foundExternal: false
+                });
+            });
+        });
+    });
+
+    describe('createExternalDecision', () => {
+        it('should create external decision with single ID', () => {
+            const decision = resolver.createExternalDecision('vpc-external');
+
+            expect(decision).toEqual({
+                ownership: ResourceOwnership.EXTERNAL,
+                physicalId: 'vpc-external',
+                physicalIds: ['vpc-external'],
+                reason: 'Using external resource reference',
+                metadata: {
+                    source: 'user-provided'
+                }
+            });
+        });
+
+        it('should create external decision with multiple IDs', () => {
+            const decision = resolver.createExternalDecision(['sg-1', 'sg-2'], 'Custom reason');
+
+            expect(decision).toEqual({
+                ownership: ResourceOwnership.EXTERNAL,
+                physicalId: 'sg-1',
+                physicalIds: ['sg-1', 'sg-2'],
+                reason: 'Custom reason',
+                metadata: {
+                    source: 'user-provided'
+                }
+            });
+        });
+    });
+
+    describe('createStackDecision', () => {
+        it('should create stack decision for new resource', () => {
+            const decision = resolver.createStackDecision();
+
+            expect(decision).toEqual({
+                ownership: ResourceOwnership.STACK,
+                physicalId: null,
+                reason: 'Managed by CloudFormation stack',
+                metadata: {
+                    source: 'new'
+                }
+            });
+        });
+
+        it('should create stack decision for existing resource', () => {
+            const decision = resolver.createStackDecision('vpc-123', 'Found in stack');
+
+            expect(decision).toEqual({
+                ownership: ResourceOwnership.STACK,
+                physicalId: 'vpc-123',
+                reason: 'Found in stack',
+                metadata: {
+                    source: 'discovered'
+                }
+            });
+        });
+    });
+
+    describe('backwards compatibility with flat discovery', () => {
+        it('should work with old flat discovery structure', () => {
+            const flatDiscovery = {
+                fromCloudFormationStack: true,
+                existingLogicalIds: ['FriggVPC', 'FriggLambdaSecurityGroup'],
+                defaultVpcId: 'vpc-123',
+                securityGroupId: 'sg-456',
+                _structured: {
+                    stackManaged: [
+                        { logicalId: 'FriggVPC', physicalId: 'vpc-123', resourceType: 'AWS::EC2::VPC' },
+                        { logicalId: 'FriggLambdaSecurityGroup', physicalId: 'sg-456', resourceType: 'AWS::EC2::SecurityGroup' }
+                    ],
+                    external: [],
+                    fromCloudFormation: true
+                }
+            };
+
+            const decision = resolver.resolveResourceOwnership(
+                'auto',
+                'FriggLambdaSecurityGroup',
+                'AWS::EC2::SecurityGroup',
+                flatDiscovery
+            );
+
+            expect(decision.ownership).toBe(ResourceOwnership.STACK);
+            expect(decision.physicalId).toBe('sg-456');
+        });
+    });
+});