feat(cdk-explorer): three-way linked navigation and source-to-template double-click

- Add source→template navigation: double-click a line in the source pane
  to jump to the resource it produces in the template pane
- Fix template highlight coordinates: TemplateViewer now resolves highlights
  from logicalId using its own display-format resources (JSON or YAML),
  eliminating the JSON-line-in-YAML-view mismatch
- Replace js-yaml + regex-based YAML remapping with the `yaml` package's
  AST parser (parseDocument + LineCounter) for robust resource range resolution
- Remove per-property line ranges from the API (block-level highlight only)
- Add source-nav.ts: builds a per-file anchor index from the construct tree
  for efficient source-line-to-construct lookups

Author: megha-narayanan

.projenrc.ts

@@ -1736,6 +1736,7 @@ const cdkExplorer = configureProject(
       'supertest@^6',
       '@types/supertest@^6',
       '@types/convert-source-map@^2',
+      'yaml@^2',
     ],
     tsconfig: {
       compilerOptions: {

packages/@aws-cdk/cdk-explorer/frontend/App.tsx

@@ -5,7 +5,8 @@ import Header from '@cloudscape-design/components/header';
 import SpaceBetween from '@cloudscape-design/components/space-between';
 import Spinner from '@cloudscape-design/components/spinner';
 import * as React from 'react';
-import { api, type DirEntry, type LineRange, type TemplateResponse, type TreeResponse, type ViolationsResponse } from './api';
+import { buildSourceAnchorIndex, findConstructAtLine } from '../lib/web/source-nav';
+import { api, type DirEntry, type TemplateResponse, type TreeResponse, type ViolationsResponse } from './api';
 import { CodeViewer, type Diagnostic } from './components/CodeViewer';
 import { ConstructTree } from './components/ConstructTree';
 import { TemplateViewer } from './components/TemplateViewer';
@@ -16,7 +17,7 @@ export type { NavigateHandler } from './nav-types';
 /** Navigation target describing what both panes should show. */
 export interface NavTarget {
   readonly source?: { file: string; startLine: number; endLine: number };
-  readonly template?: { file: string; logicalId: string; startLine: number; endLine: number; propertyLines?: LineRange };
+  readonly template?: { file: string; logicalId: string };
   readonly color: string;
   readonly navCounter: number;
 }
@@ -83,39 +84,19 @@ export function App(): JSX.Element {
 
     let templateTarget: NavTarget['template'];
     if (opts.templateFile && opts.logicalId) {
-      let data = templateDataRef.current;
       if (templateFileRef.current !== opts.templateFile) {
         try {
-          data = await api.getTemplate(opts.templateFile);
+          const data = await api.getTemplate(opts.templateFile);
           setTemplateFile(opts.templateFile);
           setTemplateData(data);
         } catch {
           setTemplateFile(opts.templateFile);
           setTemplateData(undefined);
-          data = undefined;
-        }
-      }
-      if (data) {
-        const resource = data.resources[opts.logicalId];
-        if (resource) {
-          let propertyLines: LineRange | undefined;
-          if (opts.propertyPaths?.length) {
-            const firstPath = opts.propertyPaths[0];
-            const segments = firstPath.split('.');
-            const propName = segments[0] === 'Properties' ? segments[1] : segments[0];
-            if (propName && resource.properties?.[propName]) {
-              propertyLines = resource.properties[propName];
-            }
-          }
-          templateTarget = {
-            file: opts.templateFile,
-            logicalId: opts.logicalId,
-            startLine: propertyLines?.startLine ?? resource.block.startLine,
-            endLine: propertyLines?.endLine ?? resource.block.endLine,
-            propertyLines,
-          };
         }
       }
+      // Carry identity only; TemplateViewer resolves the highlight line from the
+      // rendered format (JSON or YAML), which is the sole coordinate authority.
+      templateTarget = { file: opts.templateFile, logicalId: opts.logicalId };
     }
 
     setNav({ source: sourceTarget, template: templateTarget, color, navCounter: counter });
@@ -143,17 +124,25 @@ export function App(): JSX.Element {
     });
   }, []);
 
-  /** Double-click a line in the template pane to jump to source. */
-  const handleTemplateDoubleClick = React.useCallback((line: number) => {
-    const data = templateDataRef.current;
-    if (!data) return;
-    for (const [logicalId, resource] of Object.entries(data.resources)) {
-      if (line >= resource.block.startLine && line <= resource.block.endLine && resource.source) {
-        void jumpToSource(logicalId);
-        return;
-      }
-    }
-  }, [jumpToSource]);
+  // Per-file index of constructs navigable from source to template, built from
+  // the construct tree the app already loads. Rebuilt only when the tree changes.
+  const sourceAnchors = React.useMemo(
+    () => (tree?.status === 'ok' ? buildSourceAnchorIndex(tree.tree) : undefined),
+    [tree],
+  );
+
+  /** Double-click a line in the source pane to jump to its resource in the template. */
+  const handleSourceDoubleClick = React.useCallback((line: number) => {
+    const file = sourceFileRef.current;
+    if (!file) return;
+    const node = findConstructAtLine(sourceAnchors?.get(file), line);
+    if (!node) return;
+    void navigate({
+      sourceLocation: node.sourceLocation,
+      templateFile: node.templateFile,
+      logicalId: node.logicalId,
+    });
+  }, [sourceAnchors, navigate]);
 
   // File picker state.
   const [showFilePicker, setShowFilePicker] = React.useState<false | 'source' | 'template'>(false);
@@ -235,6 +224,7 @@ export function App(): JSX.Element {
                     highlightColor={nav?.color}
                     navCounter={nav?.navCounter}
                     scrollToLine={nav?.source?.startLine}
+                    onLineDoubleClick={handleSourceDoubleClick}
                     diagnostics={buildDiagnostics(sourceFile, violations)}
                   />
                 ) : (
@@ -257,12 +247,10 @@ export function App(): JSX.Element {
                   <TemplateViewer
                     jsonContent={templateData.content}
                     resources={templateData.resources}
-                    highlightStart={nav?.template?.startLine}
-                    highlightEnd={nav?.template?.endLine}
+                    highlightLogicalId={nav?.template?.logicalId}
                     highlightColor={nav?.color}
                     navCounter={nav?.navCounter}
-                    scrollToLine={nav?.template?.startLine}
-                    onLineDoubleClick={handleTemplateDoubleClick}
+                    onResourceDoubleClick={jumpToSource}
                   />
                 ) : templateFile ? (
                   <Box color="text-status-error">Could not load {templateFile}</Box>

packages/@aws-cdk/cdk-explorer/frontend/components/TemplateViewer.tsx

@@ -1,17 +1,15 @@
-import * as yaml from 'js-yaml';
+import { isNode, isScalar, isMap, LineCounter, parseDocument, stringify } from 'yaml';
 import * as React from 'react';
-import type { LineRange, TemplateResource } from '../api';
+import type { TemplateResource } from '../api';
 import { CodeViewer } from './CodeViewer';
 
 export interface TemplateViewerProps {
   readonly jsonContent: string;
   readonly resources: Record<string, TemplateResource>;
-  readonly highlightStart?: number;
-  readonly highlightEnd?: number;
+  readonly highlightLogicalId?: string;
   readonly highlightColor?: string;
   readonly navCounter?: number;
-  readonly scrollToLine?: number;
-  readonly onLineDoubleClick?: (line: number) => void;
+  readonly onResourceDoubleClick?: (logicalId: string) => void;
 }
 
 type Format = 'yaml' | 'json';
@@ -25,12 +23,10 @@ interface ResourceSection {
 export function TemplateViewer({
   jsonContent,
   resources,
-  highlightStart,
-  highlightEnd,
+  highlightLogicalId,
   highlightColor,
   navCounter,
-  scrollToLine,
-  onLineDoubleClick,
+  onResourceDoubleClick,
 }: TemplateViewerProps): JSX.Element {
   const [format, setFormat] = React.useState<Format>('yaml');
   const [collapsedResources, setCollapsedResources] = React.useState<Set<string>>(new Set());
@@ -43,25 +39,23 @@ export function TemplateViewer({
         sections: buildSections(resources),
       };
     }
-    return jsonToYaml(jsonContent, resources);
+    return jsonToYaml(jsonContent);
   }, [jsonContent, resources, format]);
 
   const filteredContent = React.useMemo(() => {
     if (collapsedResources.size === 0) return displayContent;
     return collapseContent(displayContent, sections, collapsedResources);
   }, [displayContent, sections, collapsedResources]);
 
+  // Resolve the highlight from the rendered format's own ranges (JSON block in
+  // JSON view, YAML block in YAML view), so the highlight is always in the
+  // coordinate system actually on screen. Derived, so toggling format re-resolves.
   const adjustedHighlight = React.useMemo(() => {
-    if (highlightStart === undefined || highlightEnd === undefined) return undefined;
-    if (collapsedResources.size === 0) return { start: highlightStart, end: highlightEnd };
-    return adjustLineNumbers(highlightStart, highlightEnd, sections, collapsedResources);
-  }, [highlightStart, highlightEnd, sections, collapsedResources]);
-
-  const adjustedScroll = React.useMemo(() => {
-    if (scrollToLine === undefined) return undefined;
-    if (collapsedResources.size === 0) return scrollToLine;
-    return adjustSingleLine(scrollToLine, sections, collapsedResources);
-  }, [scrollToLine, sections, collapsedResources]);
+    const block = highlightLogicalId ? displayResources[highlightLogicalId]?.block : undefined;
+    if (!block) return undefined;
+    if (collapsedResources.size === 0) return { start: block.startLine, end: block.endLine };
+    return adjustLineNumbers(block.startLine, block.endLine, sections, collapsedResources);
+  }, [highlightLogicalId, displayResources, sections, collapsedResources]);
 
   const toggleResource = React.useCallback((logicalId: string) => {
     setCollapsedResources((prev) => {
@@ -91,10 +85,15 @@ export function TemplateViewer({
       }
     }
 
-    if (onLineDoubleClick) {
-      onLineDoubleClick(originalLine);
+    if (onResourceDoubleClick) {
+      // Map the clicked line back to the resource that owns it (display-coordinate
+      // sections), so the reverse jump is identity-based like the forward one.
+      const section = sections.find((s) => originalLine >= s.startLine && originalLine <= s.endLine);
+      if (section) {
+        onResourceDoubleClick(section.logicalId);
+      }
     }
-  }, [filteredContent, sections, collapsedResources, onLineDoubleClick, toggleResource]);
+  }, [filteredContent, sections, collapsedResources, onResourceDoubleClick, toggleResource]);
 
   const gutterDecorations = React.useMemo(() => {
     const decorations = new Map<number, { icon: string; logicalId: string }>();
@@ -141,7 +140,7 @@ export function TemplateViewer({
         highlightEnd={adjustedHighlight?.end}
         highlightColor={highlightColor}
         navCounter={navCounter}
-        scrollToLine={adjustedScroll}
+        scrollToLine={adjustedHighlight?.start}
         onLineDoubleClick={handleDoubleClick}
       />
     </div>
@@ -160,77 +159,40 @@ interface YamlResult {
   sections: ResourceSection[];
 }
 
-function jsonToYaml(jsonContent: string, jsonResources: Record<string, TemplateResource>): YamlResult {
+function jsonToYaml(jsonContent: string): YamlResult {
   let parsed: unknown;
   try {
     parsed = JSON.parse(jsonContent);
   } catch {
-    return { displayContent: jsonContent, displayResources: jsonResources, sections: buildSections(jsonResources) };
+    return { displayContent: jsonContent, displayResources: {}, sections: [] };
   }
 
-  const yamlContent = yaml.dump(parsed, { indent: 2, lineWidth: -1, noRefs: true, sortKeys: false });
-  const yamlResources = remapResources(parsed as Record<string, unknown>, yamlContent);
-
-  return {
-    displayContent: yamlContent,
-    displayResources: yamlResources,
-    sections: buildSections(yamlResources),
-  };
-}
-
-function remapResources(template: Record<string, unknown>, yamlText: string): Record<string, TemplateResource> {
-  const resources = (template as { Resources?: Record<string, unknown> }).Resources;
-  if (!resources) return {};
-
-  const lines = yamlText.split('\n');
-  const result: Record<string, TemplateResource> = {};
-
-  for (const logicalId of Object.keys(resources)) {
-    const pattern = new RegExp(`^  ${escapeRegex(logicalId)}:`);
-    const startIdx = lines.findIndex((l) => pattern.test(l));
-    if (startIdx === -1) continue;
-
-    let endIdx = startIdx + 1;
-    while (endIdx < lines.length) {
-      const line = lines[endIdx];
-      if (line.length > 0 && !line.startsWith('    ') && !line.startsWith('  ') === false) {
-        if (/^  \S/.test(line) && !line.startsWith('    ')) break;
+  // Render and measure with the same parser so the text and the ranges always
+  // agree. lineWidth:0 disables wrapping (keeps one CFN value per line, like the
+  // old serializer); aliasDuplicateObjects:false keeps CloudFormation's repeated
+  // objects inline instead of emitting &anchor/*alias.
+  const displayContent = stringify(parsed, { indent: 2, lineWidth: 0, aliasDuplicateObjects: false });
+  const lineCounter = new LineCounter();
+  const doc = parseDocument(displayContent, { lineCounter });
+
+  const displayResources: Record<string, TemplateResource> = {};
+  const resources = doc.get('Resources');
+  if (isMap(resources)) {
+    for (const pair of resources.items) {
+      const key = pair.key;
+      const value = pair.value;
+      if (!isScalar(key) || !isNode(value) || key.range == null || value.range == null) {
+        continue;
       }
-      if (endIdx > startIdx && /^  [^\s]/.test(line)) break;
-      endIdx++;
+      // range is [valueStart, valueEnd, nodeEnd]; a resource block spans from its
+      // logical-id key line through the end of its value.
+      const startLine = lineCounter.linePos(key.range[0]).line;
+      const endLine = lineCounter.linePos(value.range[1]).line;
+      displayResources[String(key.value)] = { block: { startLine, endLine } };
     }
-
-    const block: LineRange = { startLine: startIdx + 1, endLine: endIdx };
-
-    const properties: Record<string, LineRange> = {};
-    const resourceObj = resources[logicalId] as Record<string, unknown> | undefined;
-    if (resourceObj?.Properties && typeof resourceObj.Properties === 'object') {
-      for (const propName of Object.keys(resourceObj.Properties as Record<string, unknown>)) {
-        const propPattern = new RegExp(`^      ${escapeRegex(propName)}:`);
-        for (let pi = startIdx; pi < endIdx; pi++) {
-          if (propPattern.test(lines[pi])) {
-            let propEnd = pi + 1;
-            while (propEnd < endIdx && lines[propEnd]?.startsWith('        ')) {
-              propEnd++;
-            }
-            properties[propName] = { startLine: pi + 1, endLine: propEnd };
-            break;
-          }
-        }
-      }
-    }
-
-    result[logicalId] = {
-      block,
-      ...(Object.keys(properties).length > 0 && { properties }),
-    };
   }
 
-  return result;
-}
-
-function escapeRegex(s: string): string {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return { displayContent, displayResources, sections: buildSections(displayResources) };
 }
 
 function collapseContent(content: string, sections: ResourceSection[], collapsed: Set<string>): string {

packages/@aws-cdk/cdk-explorer/lib/web/protocol.ts

@@ -78,8 +78,6 @@ export interface LineRange {
 export interface TemplateResource {
   /** Line range of the resource's value block `{ ... }`. */
   readonly block: LineRange;
-  /** Line range per top-level CFN property (PascalCase key). */
-  readonly properties?: Record<string, LineRange>;
   /** User source location for the construct that owns this resource. */
   readonly source?: WebSourceLocation;
 }

packages/@aws-cdk/cdk-explorer/lib/web/routes.ts

@@ -326,8 +326,7 @@ function toOccurrence(
 
 /**
  * Build the resource metadata map for a template file. Each resource gets its
- * block line range, per-property line ranges (if it has Properties), and the
- * source location of the construct that owns it.
+ * block line range and the source location of the construct that owns it.
  */
 function buildTemplateResources(
   content: string,
@@ -344,13 +343,6 @@ function buildTemplateResources(
 
   for (const [logicalId, ranges] of Object.entries(allRanges)) {
     const block = offsetRangeToLineRange(ranges.block, lineOffsets);
-    let properties: Record<string, LineRange> | undefined;
-    if (Object.keys(ranges.properties).length > 0) {
-      properties = {};
-      for (const [prop, offsetRange] of Object.entries(ranges.properties)) {
-        properties[prop] = offsetRangeToLineRange(offsetRange, lineOffsets);
-      }
-    }
 
     let source: WebSourceLocation | undefined;
     if (index) {
@@ -360,7 +352,7 @@ function buildTemplateResources(
       }
     }
 
-    resources[logicalId] = { block, ...(properties && { properties }), ...(source && { source }) };
+    resources[logicalId] = { block, ...(source && { source }) };
   }
   return resources;
 }