Fn::ForEach Hover Support (#159)

Author: deepfuriya

src/context/semantic/EntityBuilder.ts

@@ -66,18 +66,20 @@ export function createEntityFromObject(logicalId: string, entityObject: any, sec
                 const collection = Array.isArray(entityObject) ? entityObject[1] : undefined;
                 const outputMap = Array.isArray(entityObject) ? entityObject[2] : {};
                 const [key, value]: [string, any] = Object.entries(outputMap ?? {})[0] || [undefined, {}];
-                const resourceInsideForEach = new Resource(
-                    key,
-                    value?.Type,
-                    value?.Properties,
-                    value?.DependsOn,
-                    value?.Condition,
-                    value?.Metadata,
-                    value?.CreationPolicy,
-                    value?.DeletionPolicy,
-                    value?.UpdatePolicy,
-                    value?.UpdateReplacePolicy,
-                );
+                const resourceInsideForEach = key
+                    ? new Resource(
+                          key,
+                          value?.Type,
+                          value?.Properties,
+                          value?.DependsOn,
+                          value?.Condition,
+                          value?.Metadata,
+                          value?.CreationPolicy,
+                          value?.DeletionPolicy,
+                          value?.UpdatePolicy,
+                          value?.UpdateReplacePolicy,
+                      )
+                    : undefined;
                 return new ForEachResource(loopName, identifier, collection, resourceInsideForEach);
             }
             return new Resource(

src/hover/ResourceSectionHoverProvider.ts

@@ -4,8 +4,9 @@ import { deletionPolicyValueDocsMap } from '../artifacts/resourceAttributes/Dele
 import { updatePolicyPropertyDocsMap } from '../artifacts/resourceAttributes/UpdatePolicyPropertyDocs';
 import { updateReplacePolicyValueDocsMap } from '../artifacts/resourceAttributes/UpdateReplacePolicyPropertyDocs-1';
 import { Context } from '../context/Context';
-import { ResourceAttribute, TopLevelSection } from '../context/ContextType';
+import { ResourceAttribute } from '../context/ContextType';
 import { Resource } from '../context/semantic/Entity';
+import { EntityType } from '../context/semantic/SemanticTypes';
 import { ResourceSchema } from '../schema/ResourceSchema';
 import { SchemaRetriever } from '../schema/SchemaRetriever';
 import { Measure } from '../telemetry/TelemetryDecorator';
@@ -18,7 +19,10 @@ export class ResourceSectionHoverProvider implements HoverProvider {
 
     @Measure({ name: 'getInformation' })
     getInformation(context: Context) {
-        const resource = context.entity as Resource;
+        const resource = context.getResourceEntity();
+        if (!resource) {
+            return;
+        }
 
         if (context.text === context.logicalId) {
             return formatResourceHover(resource);
@@ -44,11 +48,12 @@ export class ResourceSectionHoverProvider implements HoverProvider {
         if (context.isResourceAttribute && resource[context.text] !== undefined) {
             return this.getResourceAttributeDoc(context.text);
         }
-        if (
-            context.matchPathWithLogicalId(TopLevelSection.Resources, 'Properties') &&
-            context.propertyPath.length >= 3
-        ) {
-            return this.getPropertyDefinitionDoc(schema, context);
+
+        // Find 'Properties' starting after the resource structure
+        const startIndex = context.getEntityType() === EntityType.ForEachResource ? 4 : 2;
+        const propertiesIndex = context.propertyPath.indexOf('Properties', startIndex);
+        if (propertiesIndex !== -1 && context.propertyPath.length >= propertiesIndex + 1) {
+            return this.getPropertyDefinitionDoc(schema, context, propertiesIndex);
         }
     }
 
@@ -75,14 +80,18 @@ export class ResourceSectionHoverProvider implements HoverProvider {
         return doc.join('\n');
     }
 
-    private getPropertyDefinitionDoc(schema: ResourceSchema, context: Context): string | undefined {
+    private getPropertyDefinitionDoc(
+        schema: ResourceSchema,
+        context: Context,
+        propertiesIndex: number,
+    ): string | undefined {
         if (!context.isKey()) {
             return undefined;
         }
 
         // Extract the property path from the context, starting after "Properties"
-        // Expected path: ['Resources', 'LogicalId', 'Properties', ...propertySegments]
-        const propertyPathSegments = context.propertyPath.slice(3);
+        // Expected path: ['Resources', 'LogicalId', 'Properties', ...propertySegments] OR ['Resources', 'Fn::ForEach::LogicalName', 2, 'S3Bucket${BucketName}', 'Properties', ...propertySegments]
+        const propertyPathSegments = context.propertyPath.slice(propertiesIndex + 1);
 
         // Convert template path to JSON Pointer path and resolve schema
         const jsonPointerPath = templatePathToJsonPointerPath(propertyPathSegments);

tst/unit/hover/ResourceSectionHoverProvider.test.ts

@@ -13,10 +13,11 @@ import {
     UpdatePolicyProperty,
     AutoScalingRollingUpdateProperty,
 } from '../../../src/context/ContextType';
+import { ForEachResource, Resource } from '../../../src/context/semantic/Entity';
 import { SyntaxTreeManager } from '../../../src/context/syntaxtree/SyntaxTreeManager';
 import { ResourceSectionHoverProvider } from '../../../src/hover/ResourceSectionHoverProvider';
 import { ResourceSchema } from '../../../src/schema/ResourceSchema';
-import { createResourceContext } from '../../utils/MockContext';
+import { createMockContext, createResourceContext } from '../../utils/MockContext';
 import { createMockSchemaRetriever } from '../../utils/MockServerComponents';
 import { combinedSchemas, combineSchema, Schemas } from '../../utils/SchemaUtils';
 import { docPosition, Templates } from '../../utils/TemplateUtils';
@@ -963,4 +964,89 @@ describe('ResourceSectionHoverProvider', () => {
             });
         });
     });
+
+    describe('ForEach Resource Hover', () => {
+        function createForEachResourceContext(
+            text: string,
+            resourceType: string,
+            properties?: Record<string, any>,
+            propertyPath?: any[],
+        ): Context {
+            const nestedResource = new Resource('S3Bucket${BucketName}', resourceType, properties);
+
+            const forEachEntity = new ForEachResource('Buckets', 'BucketName', { Ref: 'BucketNames' }, nestedResource);
+
+            return createMockContext(TopLevelSection.Resources, 'Fn::ForEach::Buckets', {
+                text,
+                entity: forEachEntity,
+                propertyPath: propertyPath ?? ['Resources', 'Fn::ForEach::Buckets', 2, 'S3Bucket${BucketName}'],
+            });
+        }
+
+        it('should return documentation for resource type in ForEach', () => {
+            const mockContext = createForEachResourceContext('AWS::S3::Bucket', 'AWS::S3::Bucket', undefined, [
+                'Resources',
+                'Fn::ForEach::Buckets',
+                2,
+                'S3Bucket${BucketName}',
+                'Type',
+            ]);
+
+            const result = hoverProvider.getInformation(mockContext);
+
+            expect(result).toContain('### AWS::S3::Bucket');
+            expect(result).toContain('The ``AWS::S3::Bucket`` resource creates an Amazon S3 bucket');
+        });
+
+        it('should return property documentation for ForEach resource property', () => {
+            const properties = { BucketName: 'my-bucket' };
+            const mockContext = createForEachResourceContext('BucketName', 'AWS::S3::Bucket', properties, [
+                'Resources',
+                'Fn::ForEach::Buckets',
+                2,
+                'S3Bucket${BucketName}',
+                'Properties',
+                'BucketName',
+            ]);
+
+            const result = hoverProvider.getInformation(mockContext);
+
+            expect(result).toContain('```typescript');
+            expect(result).toContain('string');
+            expect(result).toContain('A name for the bucket');
+        });
+
+        it('should return nested property documentation for ForEach resource', () => {
+            const properties = {
+                VersioningConfiguration: { Status: 'Enabled' },
+            };
+            const mockContext = createForEachResourceContext('Status', 'AWS::S3::Bucket', properties, [
+                'Resources',
+                'Fn::ForEach::Buckets',
+                2,
+                'S3Bucket${BucketName}',
+                'Properties',
+                'VersioningConfiguration',
+                'Status',
+            ]);
+
+            const result = hoverProvider.getInformation(mockContext);
+
+            expect(result).toBeDefined();
+            expect(result).toContain('Status');
+        });
+
+        it('should return undefined when ForEach resource has no nested resource', () => {
+            const forEachEntity = new ForEachResource('Buckets', 'BucketName', { Ref: 'BucketNames' }, undefined);
+
+            const mockContext = createMockContext(TopLevelSection.Resources, 'Fn::ForEach::Buckets', {
+                text: 'AWS::S3::Bucket',
+                entity: forEachEntity,
+            });
+
+            const result = hoverProvider.getInformation(mockContext);
+
+            expect(result).toBeUndefined();
+        });
+    });
 });