Merge pull request #32 from ketupia/23-navigation-from-code-interface-to-action

feat: enhance navigation with cross-reference code lenses

Author: ketupia

.github/copilot-instructions.md

@@ -79,6 +79,17 @@
   - Function signatures should make the purpose and usage clear without requiring knowledge of
     internal algorithms or data structures.
 
+- **Favor pipeline-style processing with helper functions.**
+  - When implementing logic that involves filtering, mapping, or transforming collections, prefer a
+    pipeline of array methods (`filter`, `map`, `flatMap`, etc.) with small, well-named helper
+    functions for each transformation step.
+  - This style should resemble Elixir's `Enum` pipelines: break up complex logic into a series of
+    focused, composable steps.
+  - Avoid deeply nested loops or imperative code when a pipeline with helpers would be clearer.
+  - Use early returns and guard clauses in helpers to keep each step focused and readable.
+  - Example: Instead of a large nested loop, use chained array methods and extract the innermost
+    logic into a named function.
+
 ## Modularization & Interface-Driven Architecture
 
 - All logic should be organized into small, well-defined modules with clear responsibilities.

src/ashParserService.ts

@@ -52,7 +52,7 @@ export class AshParserService {
         `Parser ${result.parserName} succeeded`,
         {
           sectionsFound: result.sections.length,
-          codeLensesFound: result.codeLenses.length,
+          diagramCodeLensesFound: result.diagramCodeLenses.length,
         }
       );
     } catch (error) {
@@ -62,8 +62,9 @@ export class AshParserService {
       // Fallback to an empty result on error
       result = {
         sections: [],
-        parserName: "ErrorFallback",
-        codeLenses: [],
+        parserName: "",
+        diagramCodeLenses: [],
+        crossReferenceCodeLenses: [],
       };
     }
 
@@ -113,7 +114,8 @@ export class AshParserService {
       return {
         sections: [],
         parserName: "LanguageFilter",
-        codeLenses: [],
+        diagramCodeLenses: [],
+        crossReferenceCodeLenses: [],
       };
     }
 

src/configurations/Ash.Resource.config.ts

@@ -101,6 +101,9 @@ const Ash_Resource_Config: ModuleInterface = {
         {
           keyword: "define",
           namePattern: "(:\\w+|\\w+)",
+          crossReference: {
+            blockName: "actions",
+          },
         },
       ],
     },

src/extension.ts

@@ -9,9 +9,10 @@ import {
   generateDiagramWebviewContent,
   getOrCreateAshStudioWebview,
 } from "./features/ashStudioWebview";
-import { CodeLensEntry } from "./types/parser";
 import { getTheoreticalDiagramFilePath } from "./utils/diagramUtils";
 import { generateDiagramWithMix } from "./utils/diagramMixUtils";
+import { DiagramCodeLensEntry } from "./types/parser";
+import { GotoFileLocationEntry } from "./types/commands";
 
 // Debounce map for text change events to prevent excessive parsing
 const debounceTimers = new Map<string, NodeJS.Timeout>();
@@ -105,22 +106,6 @@ export function activate(context: vscode.ExtensionContext) {
     registerAshSectionNavigation(context, parserService);
     registerAshCodeLensProvider(context, parserService);
 
-    // Register the reveal command that the sidebar uses
-    context.subscriptions.push(
-      vscode.commands.registerCommand(
-        "ash-studio.revealSectionOrSubBlock",
-        (line: number) => {
-          const editor = vscode.window.activeTextEditor;
-          if (editor && typeof line === "number") {
-            const position = new vscode.Position(line, 0);
-            editor.selection = new vscode.Selection(position, position);
-            editor.revealRange(new vscode.Range(position, position));
-            vscode.window.showTextDocument(editor.document);
-          }
-        }
-      )
-    );
-
     // Register diagram commands
     context.subscriptions.push(
       vscode.commands.registerCommand(
@@ -133,7 +118,7 @@ export function activate(context: vscode.ExtensionContext) {
          * @param entry - The CodeLensEntry containing diagram metadata and resource info
          */
         "ash-studio.showDiagram",
-        async (filePath: string, entry: CodeLensEntry) => {
+        async (filePath: string, entry: DiagramCodeLensEntry) => {
           const diagramFilePath = getTheoreticalDiagramFilePath(
             entry.target,
             entry.diagramSpec
@@ -168,6 +153,33 @@ export function activate(context: vscode.ExtensionContext) {
       )
     );
 
+    // Register generic file location navigation command
+    context.subscriptions.push(
+      vscode.commands.registerCommand(
+        /**
+         * Registers the ash-studio.gotoFileLocation command to reveal a file and line in the editor.
+         * Used by all navigation features (code lenses, QuickPick, sidebar, etc.) for unified navigation.
+         *
+         * @param filePath - The file path to open
+         * @param entry - An object containing targetLine or line (1-based)
+         */
+        "ash-studio.gotoFileLocation",
+        async (filePath: string, entry: GotoFileLocationEntry) => {
+          const doc = await vscode.workspace.openTextDocument(filePath);
+          const editor = await vscode.window.showTextDocument(doc, {
+            preview: false,
+          });
+          const line = Math.max(0, (entry.targetLine ?? entry.line ?? 1) - 1); // 0-based
+          const pos = new vscode.Position(line, 0);
+          editor.selection = new vscode.Selection(pos, pos);
+          editor.revealRange(
+            new vscode.Range(pos, pos),
+            vscode.TextEditorRevealType.InCenter
+          );
+        }
+      )
+    );
+
     logger.info("Extension", "...complete");
   } catch (error) {
     logger.error("Extension", "Extension activation failed", error);

src/features/ashCodeLensProvider.ts

@@ -1,6 +1,5 @@
 import * as vscode from "vscode";
 import { AshParserService } from "../ashParserService";
-import { Logger } from "../utils/logger";
 import { ConfigurationManager } from "../utils/config";
 
 /**
@@ -38,30 +37,20 @@ export class AshCodeLensProvider implements vscode.CodeLensProvider {
       parseResult = this.parserService.parseElixirDocument(document);
     }
 
-    if (!parseResult || parseResult.codeLenses.length === 0) {
+    if (!parseResult) {
       return [];
     }
 
     // Convert parser results to VS Code CodeLens objects
     const codeLenses: vscode.CodeLens[] = [];
-    for (const entry of parseResult.codeLenses) {
-      // Create a range for the CodeLens
+    // Handle diagram code lenses
+    for (const entry of parseResult.diagramCodeLenses || []) {
       const line = Math.max(0, entry.line - 1); // Convert to 0-based line number
       const range = new vscode.Range(
         new vscode.Position(line, entry.character),
         new vscode.Position(line, entry.character + 1)
       );
-
-      // Create the CodeLens with a command that opens the diagram
       const lens = new vscode.CodeLens(range);
-
-      // Debug logging
-      Logger.getInstance().debug(
-        "AshCodeLensProvider",
-        `Creating code lens: ${entry.title} -> ${entry.target}`
-      );
-
-      // Assign command directly from entry
       if (entry.command === "ash-studio.showDiagram") {
         lens.command = {
           title: entry.title,
@@ -70,14 +59,26 @@ export class AshCodeLensProvider implements vscode.CodeLensProvider {
           tooltip: `View diagram for ${entry.source}`,
         };
       } else {
-        const logger = Logger.getInstance();
-        logger.error("Code Lens Provider", `Unknown Command ${entry.command}`);
         vscode.window.showErrorMessage(`Unknown Command ${entry.command}`);
       }
-
       codeLenses.push(lens);
     }
-
+    // Handle cross-reference code lenses
+    for (const entry of parseResult.crossReferenceCodeLenses || []) {
+      const line = Math.max(0, entry.line - 1); // Convert to 0-based line number
+      const range = new vscode.Range(
+        new vscode.Position(line, entry.character),
+        new vscode.Position(line, entry.character + 1)
+      );
+      const lens = new vscode.CodeLens(range);
+      lens.command = {
+        title: "➡️ " + entry.title,
+        command: "ash-studio.gotoFileLocation",
+        arguments: [document.uri.fsPath, entry],
+        tooltip: `Go to referenced section/detail (line ${entry.targetLine})`,
+      };
+      codeLenses.push(lens);
+    }
     return codeLenses;
   }
 

src/features/ashQuickPick.ts

@@ -46,12 +46,11 @@ export function registerAshQuickPick(
       });
 
       if (pick && pick.section) {
-        const position = new vscode.Position(pick.section.startLine - 1, 0);
-        activeEditor.revealRange(
-          new vscode.Range(position, position),
-          vscode.TextEditorRevealType.InCenter
+        await vscode.commands.executeCommand(
+          "ash-studio.gotoFileLocation",
+          activeEditor.document.uri.fsPath,
+          { line: pick.section.startLine }
         );
-        activeEditor.selection = new vscode.Selection(position, position);
       }
     }
   );

src/features/ashSidebarProvider.ts

@@ -36,6 +36,7 @@ export class AshSidebarProvider
       );
       return [];
     }
+    const filePath = activeEditor.document.uri.fsPath;
 
     // Get parse result for the active document
     let parseResult = this.parserService.getCachedResult(activeEditor.document);
@@ -65,9 +66,9 @@ export class AshSidebarProvider
             section.startLine, // Use startLine instead of line
             undefined,
             {
-              command: "ash-studio.revealSectionOrSubBlock",
+              command: "ash-studio.gotoFileLocation",
               title: "Go to Section",
-              arguments: [section.startLine],
+              arguments: [filePath, { targetLine: section.startLine }],
             },
             undefined,
             true // Mark as section
@@ -82,7 +83,7 @@ export class AshSidebarProvider
         return [];
 
       return section.details.map((detail: ParsedDetail) =>
-        this.createDetailTreeItem(detail)
+        this.createDetailTreeItem(detail, filePath)
       );
     } else if (
       element.detail &&
@@ -91,7 +92,7 @@ export class AshSidebarProvider
     ) {
       // Level 2+: Show nested details (recursive handling)
       return element.detail.childDetails.map((childDetail: ParsedDetail) =>
-        this.createDetailTreeItem(childDetail)
+        this.createDetailTreeItem(childDetail, filePath)
       );
     }
 
@@ -101,7 +102,10 @@ export class AshSidebarProvider
   /**
    * Helper method to create a tree item for a detail, handling nested details recursively
    */
-  private createDetailTreeItem(detail: ParsedDetail): AshSidebarItem {
+  private createDetailTreeItem(
+    detail: ParsedDetail,
+    filePath?: string
+  ): AshSidebarItem {
     const hasChildren = detail.childDetails && detail.childDetails.length > 0;
 
     // Create a label that shows both block type and name (if available)
@@ -117,11 +121,13 @@ export class AshSidebarProvider
         : vscode.TreeItemCollapsibleState.None,
       detail.line,
       undefined, // Remove parent section display
-      {
-        command: "ash-studio.revealSectionOrSubBlock",
-        title: "Go to Detail",
-        arguments: [detail.line],
-      },
+      filePath
+        ? {
+            command: "ash-studio.gotoFileLocation",
+            title: "Go to Detail",
+            arguments: [filePath, { targetLine: detail.line }],
+          }
+        : undefined,
       detail, // Pass the detail for recursive nesting
       false // Not a section
     );
@@ -148,13 +154,7 @@ class AshSidebarItem extends vscode.TreeItem {
     isSection: boolean = false
   ) {
     super(label, collapsibleState);
-    if (sectionLine !== undefined) {
-      this.command = {
-        command: "ash-studio.revealSectionOrSubBlock",
-        title: "Go to block",
-        arguments: [sectionLine],
-      };
-    }
+    // Remove legacy command assignment here; now passed in explicitly
     if (parentSection) {
       this.description = parentSection;
     }