Add section/keyword outline tree view for navigation

Closes #41. Adds an explorer tree view that mirrors the deck structure
(section -> keyword), letting users jump to any keyword with a click.

- outline.ts: pure buildOutline() helper, unit-tested under jest. Reuses
  the column-1 keyword discipline from the folding provider (comments
  skipped, END closes a section, pre-section keywords attach to root).
- OpmFlowOutlineProvider: TreeDataProvider with section/keyword icons and
  index summaries as tooltips; tree selection follows the cursor.
- opm-flow.revealKeyword command jumps the editor to a keyword line.
- package.json: contributes the opm-flow.outlineView tree to the explorer.

Author: magnesj

vscode-extension/package.json

@@ -32,12 +32,19 @@
   "activationEvents": [
     "onLanguage:opm-flow",
     "onView:opm-flow.docsView",
+    "onView:opm-flow.outlineView",
     "onStartupFinished"
   ],
   "main": "./out/extension",
   "contributes": {
     "views": {
       "explorer": [
+        {
+          "type": "tree",
+          "id": "opm-flow.outlineView",
+          "name": "OPM Flow Outline",
+          "when": "resourceLangId == opm-flow"
+        },
         {
           "type": "webview",
           "id": "opm-flow.docsView",

vscode-extension/src/extension.ts

@@ -20,6 +20,7 @@ import {
   toggleLineComments,
 } from './formatting';
 import { computeDiagnostics } from './analysis';
+import { buildOutline, OutlineNode } from './outline';
 import { findFileReferences } from './links';
 import { parsePathsAliases, resolvePathAlias, prtCandidatePaths } from './paths';
 import { DEFAULT_DIAGNOSTICS_EXCLUDED_KEYWORDS } from './diagnostics-exclusions';
@@ -729,6 +730,81 @@ class OpmFlowFoldingRangeProvider implements vscode.FoldingRangeProvider {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Outline tree view — section -> keyword navigation
+// ---------------------------------------------------------------------------
+
+class OpmFlowOutlineProvider implements vscode.TreeDataProvider<OutlineNode> {
+  private readonly _onDidChangeTreeData = new vscode.EventEmitter<void>();
+  readonly onDidChangeTreeData = this._onDidChangeTreeData.event;
+
+  private roots: OutlineNode[] = [];
+  /** Source document of the current outline, for the reveal command. */
+  private docUri?: vscode.Uri;
+
+  constructor(private readonly index: KeywordIndex) {}
+
+  /** Rebuild the outline from `doc` (or clear it for non-opm-flow docs). */
+  refresh(doc?: vscode.TextDocument): void {
+    if (doc?.languageId === 'opm-flow') {
+      this.roots = buildOutline(doc.getText().split(/\r?\n/));
+      this.docUri = doc.uri;
+    } else {
+      this.roots = [];
+      this.docUri = undefined;
+    }
+    this._onDidChangeTreeData.fire();
+  }
+
+  getChildren(node?: OutlineNode): OutlineNode[] {
+    return node ? node.children : this.roots;
+  }
+
+  /** Required for `TreeView.reveal` to locate a node. Sections are roots;
+   *  a keyword's parent is the section that contains it (undefined for
+   *  pre-section keywords attached directly to the root). */
+  getParent(node: OutlineNode): OutlineNode | undefined {
+    if (node.kind === 'section') return undefined;
+    return this.roots.find(s => s.children.includes(node));
+  }
+
+  getTreeItem(node: OutlineNode): vscode.TreeItem {
+    const item = new vscode.TreeItem(
+      node.name,
+      node.kind === 'section'
+        ? vscode.TreeItemCollapsibleState.Expanded
+        : vscode.TreeItemCollapsibleState.None,
+    );
+    item.iconPath = new vscode.ThemeIcon(
+      node.kind === 'section' ? 'symbol-namespace' : 'symbol-keyword',
+    );
+    const summary = resolveKeyword(this.index, node.name)?.summary;
+    if (summary) item.tooltip = summary;
+    if (node.kind === 'keyword' && this.docUri) {
+      item.command = {
+        command: 'opm-flow.revealKeyword',
+        title: 'Go to keyword',
+        arguments: [this.docUri, node.line],
+      };
+    }
+    return item;
+  }
+
+  /** Find the deepest node whose declaration line is at or before `line`. */
+  nodeAtLine(line: number): OutlineNode | undefined {
+    let match: OutlineNode | undefined;
+    for (const section of this.roots) {
+      if (section.line > line) break;
+      match = section;
+      for (const kw of section.children) {
+        if (kw.line > line) break;
+        match = kw;
+      }
+    }
+    return match;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // File-reference link provider — INCLUDE / IMPORT / RESTART / GDFILE
 // ---------------------------------------------------------------------------
@@ -1258,6 +1334,57 @@ export function activate(context: vscode.ExtensionContext): void {
     new OpmFlowFoldingRangeProvider()
   );
 
+  // --- Outline tree view: section -> keyword navigation ---
+  const outlineProvider = new OpmFlowOutlineProvider(index);
+  const outlineView = vscode.window.createTreeView('opm-flow.outlineView', {
+    treeDataProvider: outlineProvider,
+  });
+  outlineProvider.refresh(vscode.window.activeTextEditor?.document);
+
+  const revealKeywordCommand = vscode.commands.registerCommand(
+    'opm-flow.revealKeyword',
+    async (uri: vscode.Uri, line: number) => {
+      const editor = await vscode.window.showTextDocument(uri);
+      const pos = new vscode.Position(line, 0);
+      editor.selection = new vscode.Selection(pos, pos);
+      editor.revealRange(
+        new vscode.Range(pos, pos),
+        vscode.TextEditorRevealType.InCenter,
+      );
+    },
+  );
+
+  const refreshOutline = debounce((doc: vscode.TextDocument) => {
+    outlineProvider.refresh(doc);
+  }, 250);
+
+  // Keep the tree's selection in sync with the cursor's active keyword.
+  let lastRevealedLine = -1;
+  const syncOutlineSelection = (editor: vscode.TextEditor): void => {
+    if (editor.document.languageId !== 'opm-flow' || !outlineView.visible) return;
+    const node = outlineProvider.nodeAtLine(editor.selection.active.line);
+    if (!node || node.line === lastRevealedLine) return;
+    lastRevealedLine = node.line;
+    void outlineView.reveal(node, { select: true, focus: false });
+  };
+
+  context.subscriptions.push(
+    outlineView,
+    revealKeywordCommand,
+    vscode.window.onDidChangeActiveTextEditor(editor => {
+      outlineProvider.refresh(editor?.document);
+      lastRevealedLine = -1;
+    }),
+    vscode.workspace.onDidChangeTextDocument(e => {
+      if (e.document === vscode.window.activeTextEditor?.document) {
+        refreshOutline(e.document);
+      }
+    }),
+    vscode.window.onDidChangeTextEditorSelection(e => {
+      syncOutlineSelection(e.textEditor);
+    }),
+  );
+
   // --- Diagnostics: over-arity records and wrong-section keywords ---
   const diagnostics = vscode.languages.createDiagnosticCollection('opm-flow');
   const refreshDiags = debounce((doc: vscode.TextDocument) => {

vscode-extension/src/outline.test.ts

@@ -0,0 +1,60 @@
+import { buildOutline } from './outline';
+
+const lines = (s: string): string[] => s.split('\n');
+
+describe('buildOutline', () => {
+  it('nests keywords under their section', () => {
+    const roots = buildOutline(lines(
+      'RUNSPEC\n' +
+      'DIMENS\n' +
+      '10 10 3 /\n' +
+      'OIL\n' +
+      'GRID\n' +
+      'PERMX\n' +
+      '300*100 /\n',
+    ));
+    expect(roots.map(r => r.name)).toEqual(['RUNSPEC', 'GRID']);
+    expect(roots[0].kind).toBe('section');
+    expect(roots[0].children.map(c => c.name)).toEqual(['DIMENS', 'OIL']);
+    expect(roots[1].children.map(c => c.name)).toEqual(['PERMX']);
+  });
+
+  it('records the zero-based line of each node', () => {
+    const roots = buildOutline(lines('RUNSPEC\nDIMENS\n10 10 3 /\n'));
+    expect(roots[0].line).toBe(0);
+    expect(roots[0].children[0].line).toBe(1);
+  });
+
+  it('skips comment lines and record/value lines', () => {
+    const roots = buildOutline(lines(
+      '-- a comment\n' +
+      'RUNSPEC\n' +
+      '-- another\n' +
+      'DIMENS\n' +
+      '10 10 3 /\n',
+    ));
+    expect(roots[0].children.map(c => c.name)).toEqual(['DIMENS']);
+  });
+
+  it('does not treat indented uppercase tokens as keywords', () => {
+    const roots = buildOutline(lines(
+      'RUNSPEC\n' +
+      'EQLOPTS\n' +
+      ' THPRES /\n',
+    ));
+    expect(roots[0].children.map(c => c.name)).toEqual(['EQLOPTS']);
+  });
+
+  it('attaches pre-section keywords to the root', () => {
+    const roots = buildOutline(lines('INCLUDE\n  \'grid.inc\' /\nGRID\nPERMX\n'));
+    expect(roots[0]).toMatchObject({ name: 'INCLUDE', kind: 'keyword' });
+    expect(roots[1].name).toBe('GRID');
+  });
+
+  it('closes the active section on END', () => {
+    const roots = buildOutline(lines('SCHEDULE\nTSTEP\n10 /\nEND\nFOO\n'));
+    expect(roots[0].children.map(c => c.name)).toEqual(['TSTEP']);
+    // FOO after END falls back to a root-level keyword node.
+    expect(roots.map(r => r.name)).toEqual(['SCHEDULE', 'FOO']);
+  });
+});

vscode-extension/src/outline.ts

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// Pure document-outline model for the keyword navigation tree.
+// Kept free of vscode imports so it can be unit-tested under jest, mirroring
+// the section -> keyword structure used by the folding range provider.
+// ---------------------------------------------------------------------------
+
+import { KEYWORD_LINE_COL1_RE, SECTION_KEYWORD_SET } from './formatting';
+
+export interface OutlineNode {
+  /** Keyword token as written in the deck (always column-1, uppercase). */
+  name: string;
+  /** Zero-based document line where the keyword starts — used for reveal. */
+  line: number;
+  kind: 'section' | 'keyword';
+  /** Populated for section nodes; always empty for keyword leaves. */
+  children: OutlineNode[];
+}
+
+/**
+ * Build a two-level outline from deck lines:
+ *
+ *   section (RUNSPEC, GRID, …) -> keyword leaves between section headers
+ *
+ * The walk mirrors `OpmFlowFoldingRangeProvider`: only column-1 declarations
+ * (`KEYWORD_LINE_COL1_RE`) count, comment lines are skipped, and `END` closes
+ * the current section so any trailing keywords fall back to the synthetic
+ * root. Keywords appearing before the first section header (e.g. in an
+ * include file with no section marker) are attached directly to the root so
+ * nothing is dropped.
+ */
+export function buildOutline(lines: string[]): OutlineNode[] {
+  const roots: OutlineNode[] = [];
+  let current: OutlineNode | null = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i];
+    if (text.trim().startsWith('--')) continue;
+
+    const m = text.match(KEYWORD_LINE_COL1_RE);
+    if (!m) continue;
+    const kw = m[1];
+
+    if (SECTION_KEYWORD_SET.has(kw)) {
+      current = { name: kw, line: i, kind: 'section', children: [] };
+      roots.push(current);
+    } else if (kw === 'END') {
+      current = null;
+    } else {
+      const node: OutlineNode = { name: kw, line: i, kind: 'keyword', children: [] };
+      if (current) current.children.push(node);
+      else roots.push(node);
+    }
+  }
+
+  return roots;
+}