feat(lsp): JRL multi-line builder chains + enum value completion/hover

Problems fixed:
1. In real services.jrl the builder chain spans many lines — each setter on its
   own line. Hover on `.setJournalType(…)` at line 7 saw only the current line's
   receiver (`.`, whitespace) and returned null.
2. Typing `foam.dao.JournalType.` offered class IDs, not the enum's own values.
3. Hovering `SINGLE_JOURNAL` inside `foam.dao.JournalType.SINGLE_JOURNAL` showed
   the JournalType class doc instead of the value's label/ordinal.

Changes:
- resolveReceiverBefore_ now walks the full embedded content (not a single line).
  Whitespace is accepted only when it sits between chain elements — i.e. the
  next non-ws char backward is `.`, `)`, or `]`. This admits multi-line `.setX`
  continuations while rejecting `new foo.Bar` (ws between keyword + chain).
- serviceScriptCompletion_ uses absolute-offset prefix so member match crosses
  line boundaries.
- enumValueCompletions_: if the resolved receiver is an enum class, return
  its VALUES (CompletionItemKind.EnumMember, sorted by ordinal) BEFORE any
  member completions.
- buildEnumValueHover_: value-level hover with label + ordinal.
- resolveDottedClassUnderCursor_: when trimming trailing segments of a dotted
  identifier, if the stripped suffix is an enum value on the matching class,
  return the enum-value hover instead of the class doc.

Regression tests verified directly on ptv3/journals/services.jrl:
- hover on .setPm at line 9
- hover on .setOf at line 14
- hover on SINGLE_JOURNAL
Plus synthetic tests: multi-line chain hover on .setSeqNo, .setJournalType,
enum value completion ordering (first item is kind=20, not a class).

502 → 505 tests passing.

Author: abdelaziz-mahdy

tools/lsp/handlers/JrlHandler.js

@@ -794,57 +794,86 @@ foam.CLASS({
        * back once the grammar path is stable and covered by tests.
        */
       var cpos = this.embedCursorToPosition_(ctx);
-      var clines = ctx.content.split('\n');
-      var line = clines[cpos.line] || '';
+      var content = ctx.content;
+      var cursorAbs = this.positionToOffset_(content, cpos);
+
       var wordRe = /[\w.$]/;
-      var start = cpos.character;
-      var end = cpos.character;
-      while ( start > 0 && wordRe.test(line.charAt(start - 1)) ) start--;
-      while ( end < line.length && wordRe.test(line.charAt(end)) ) end++;
-      var dotted = line.substring(start, end).replace(/^\.+|\.+$/g, '');
+      var start = cursorAbs;
+      var end = cursorAbs;
+      while ( start > 0 && wordRe.test(content.charAt(start - 1)) ) start--;
+      while ( end < content.length && wordRe.test(content.charAt(end)) ) end++;
+      var dotted = content.substring(start, end).replace(/^\.+|\.+$/g, '');
 
       if ( dotted && this.index.classExists(dotted) ) {
         return this.index.getClassDoc(dotted);
       }
       if ( dotted && dotted.indexOf('.') !== -1 ) {
         for ( var cand = dotted ; cand.indexOf('.') !== -1 ; ) {
-          if ( this.index.classExists(cand) ) return this.index.getClassDoc(cand);
+          if ( this.index.classExists(cand) ) {
+            // If the trimmed suffix is an enum value on this class, show
+            // the value hover rather than the class doc.
+            var suffix = dotted.substring(cand.length + 1);
+            if ( suffix && suffix.indexOf('.') === -1 ) {
+              var enumHit = this.buildEnumValueHover_(cand, suffix);
+              if ( enumHit ) return enumHit;
+            }
+            return this.index.getClassDoc(cand);
+          }
           cand = cand.substring(0, cand.lastIndexOf('.'));
         }
       }
       if ( dotted && dotted.indexOf('.') === -1 ) {
         // Effective word start: first non-dot char in the matched region.
         var effectiveStart = start;
-        while ( effectiveStart < line.length && line.charAt(effectiveStart) === '.' ) {
+        while ( effectiveStart < content.length && content.charAt(effectiveStart) === '.' ) {
           effectiveStart++;
         }
-        var receiverType = this.resolveReceiverBefore_(line, effectiveStart);
-        if ( receiverType ) return this.buildMemberHover_(receiverType, dotted);
+        var receiverType = this.resolveReceiverBefore_(content, effectiveStart);
+        if ( receiverType ) {
+          // Check enum first — hovering on ENUM_VALUE inside enum class scope.
+          var enumHover = this.buildEnumValueHover_(receiverType, dotted);
+          if ( enumHover ) return enumHover;
+          return this.buildMemberHover_(receiverType, dotted);
+        }
       }
       return null;
     },
 
-    function resolveReceiverBefore_(line, wordStart) {
+    function positionToOffset_(content, pos) {
+      /** Map {line, character} to absolute offset in content. */
+      var off = 0, line = 0;
+      for ( var i = 0 ; i < content.length ; i++ ) {
+        if ( line === pos.line ) return i + pos.character;
+        if ( content.charCodeAt(i) === 10 ) line++;
+      }
+      return content.length;
+    },
+
+    function resolveReceiverBefore_(content, wordStart) {
       /**
        * Return the FOAM class id of the receiver expression that precedes
-       * `line[wordStart]`. Handles arbitrarily long chains:
-       *   • `foo.X.something.`
-       *   • `foo.X.Builder(x).`
-       *   • `foo.X.Builder(x).setA(true).setB(y).`   ← chained builder
+       * `content[wordStart]`. Operates on the FULL embedded content so
+       * multi-line builder chains work:
+       *
+       *   return new foo.X.Builder(x)
+       *     .setA(true)
+       *     .setB(y)
+       *     .setC(…)   ← cursor on setC resolves receiver across lines
        *
-       * Walks backward peeling alternating `word/dot` runs and balanced
-       * `(…)` groups. Stops on whitespace, operators, or line start.
+       * Walks backward peeling alternating word/dot runs and balanced
+       * `(…)` groups; treats whitespace (including newlines) as part of
+       * the chain if it's between a dot and the next token.
        */
-      if ( wordStart === 0 || line.charAt(wordStart - 1) !== '.' ) return null;
+      if ( wordStart === 0 || content.charAt(wordStart - 1) !== '.' ) return null;
       var pos = wordStart - 2; // start before the trailing dot
       while ( pos >= 0 ) {
-        var ch = line.charAt(pos);
+        var ch = content.charAt(pos);
         if ( /[\w.$]/.test(ch) ) { pos--; continue; }
         if ( ch === ')' ) {
           var depth = 1;
           pos--;
           while ( pos >= 0 && depth > 0 ) {
-            var c = line.charAt(pos);
+            var c = content.charAt(pos);
             if ( c === ')' ) depth++;
             else if ( c === '(' ) depth--;
             if ( depth === 0 ) break;
@@ -854,15 +883,52 @@ foam.CLASS({
           pos--; // consume the '('
           continue;
         }
+        if ( /\s/.test(ch) ) {
+          // Whitespace (including newlines) is part of the chain only if it
+          // sits between two chain elements — i.e. the next non-ws char
+          // going backward is `.`, `)`, or `]`. This rejects `new foo.Bar`
+          // (whitespace between `new` and the chain) while accepting
+          //    foo.Builder(x)
+          //      .setA(…)           (ws before `.`)
+          // and foo
+          //      .bar                (ws before `.`)
+          var skip = pos;
+          while ( skip >= 0 && /\s/.test(content.charAt(skip)) ) skip--;
+          if ( skip < 0 ) break;
+          var prev = content.charAt(skip);
+          if ( prev !== '.' && prev !== ')' && prev !== ']' ) break;
+          pos = skip;
+          continue;
+        }
         break;
       }
-      var start = pos + 1;
-      while ( start < wordStart - 1 && line.charAt(start) === '.' ) start++;
-      var receiverExpr = line.substring(start, wordStart - 1);
+      var segStart = pos + 1;
+      // Skip leading whitespace and leading dots.
+      while ( segStart < wordStart - 1 && /[\s.]/.test(content.charAt(segStart)) ) segStart++;
+      var receiverExpr = content.substring(segStart, wordStart - 1).replace(/\s+/g, '');
       if ( ! receiverExpr ) return null;
       return this.resolveReceiverType_(receiverExpr);
     },
 
+    function buildEnumValueHover_(classId, valueName) {
+      /**
+       * If classId is an enum and valueName is one of its values, build a
+       * hover showing the value's label and ordinal.
+       */
+      var values = this.index.getEnumValues(classId);
+      if ( ! values || ! values.length ) return null;
+      for ( var i = 0 ; i < values.length ; i++ ) {
+        if ( values[i].name !== valueName ) continue;
+        var v = values[i];
+        var md = '```java\n' + classId + '.' + v.name + '\n```\n';
+        md += '*enum value on `' + classId + '`*';
+        if ( v.label ) md += '\n\nLabel: **' + v.label + '**';
+        if ( v.ordinal != null ) md += '\n\nOrdinal: ' + v.ordinal;
+        return md;
+      }
+      return null;
+    },
+
     function buildMemberHover_(classId, memberName) {
       /**
        * Build hover markdown for a member access on a known class. Matches
@@ -996,24 +1062,34 @@ foam.CLASS({
        *      or the builder's own type) this surfaces EVERY real setter
        *      the class actually declares, no hardcoded list.
        */
-      var lines = text.split('\n');
-      var line = lines[position.line] || '';
-      var prefix = line.substring(0, position.character);
-
-      // Member access: `<receiver>.<partial>` — try registry-driven resolution.
-      var memberMatch = prefix.match(/([\w.$]+)\s*(?:\([^)]*\)\s*(?:\.\w+\s*\([^)]*\)\s*)*)?\.(\w*)$/);
-      if ( memberMatch ) {
-        var receiverExpr = memberMatch[1];
-        var partialName  = memberMatch[2] || '';
-        var receiverType = this.resolveReceiverType_(receiverExpr);
+      // Operate on the FULL content up to the cursor so multi-line
+       // builder chains resolve correctly (each setter on its own line).
+      var cursorAbs = this.positionToOffset_(text, position);
+      var prefix = text.substring(0, cursorAbs);
+
+      // Partial word at cursor: letters only — we match an optional leading
+      // dot explicitly below.
+      var partialMatch = prefix.match(/\.(\w*)$/);
+      if ( partialMatch ) {
+        var partialName = partialMatch[1] || '';
+        var dotPos = cursorAbs - partialName.length - 1;
+        var receiverType = this.resolveReceiverBefore_(text, dotPos + 1);
         if ( receiverType ) {
+          // Enum values take precedence — they're what you actually want
+          // when the receiver is an enum class.
+          var enumItems = this.enumValueCompletions_(receiverType, partialName);
+          if ( enumItems.length > 0 ) return { isIncomplete: false, items: enumItems };
+
           var items = this.memberCompletions_(receiverType, partialName);
           if ( items.length > 0 ) return { isIncomplete: false, items: items };
         }
       }
 
       // Otherwise: dotted class-id prefix search.
-      var dotted = prefix.match(/([\w.$]+)$/);
+      var lines = text.split('\n');
+      var line = lines[position.line] || '';
+      var linePrefix = line.substring(0, position.character);
+      var dotted = linePrefix.match(/([\w.$]+)$/);
       var partial = dotted ? dotted[1] : '';
       var ids = this.index.getAllClassIds();
       var out = [];
@@ -1054,6 +1130,29 @@ foam.CLASS({
       return null;
     },
 
+    function enumValueCompletions_(classId, partial) {
+      /**
+       * If classId is a FOAM enum, offer its VALUES as completions.
+       * Returns empty array for non-enums.
+       */
+      var values = this.index.getEnumValues(classId);
+      if ( ! values || ! values.length ) return [];
+      var items = [];
+      var lower = partial ? partial.toLowerCase() : '';
+      for ( var i = 0 ; i < values.length ; i++ ) {
+        var v = values[i];
+        if ( lower && v.name.toLowerCase().indexOf(lower) === -1 ) continue;
+        items.push({
+          label: v.name,
+          kind: 20, // CompletionItemKind.EnumMember
+          detail: classId + (v.label ? ' — ' + v.label : ''),
+          insertText: v.name,
+          sortText: '!' + String(v.ordinal != null ? v.ordinal : i).padStart(5, '0')
+        });
+      }
+      return items;
+    },
+
     function memberCompletions_(classId, partial) {
       /**
        * Build completion items for members of a FOAM class's Java surface:

tools/tests/testFoamLSP.js

@@ -2799,6 +2799,71 @@ var vscodeJrl = JSON.parse(fs_.readFileSync(path_.join(__dirname, '../lsp/editor
 test(!! vscodeJrl.repository['json-block-triple'] && !! vscodeJrl.repository['json-block-backtick'],
   'VS Code foam-jrl grammar has JSON injections for client triple/backtick');
 
+// === MULTI-LINE BUILDER CHAIN (real-world services.jrl shape) ===
+section('Multi-line builder chain — hover + enum completion');
+var mlsrc = [
+  'p({',
+  '  "class":"foam.core.boot.CSpec",',
+  '  "name":"transactionDAO",',
+  '  "serviceScript": """',
+  '    return new foam.dao.EasyDAO.Builder(x)',
+  '      .setPm(true)',
+  '      .setSeqNo(true)',
+  '      .setJournalType(foam.dao.JournalType.SINGLE_JOURNAL)',
+  '      .setOf(foam.lang.FObject.getOwnClassInfo())',
+  '      .build();',
+  '  """',
+  '})'
+].join('\n');
+
+// Hover on .setSeqNo — receiver is on line 4 (the return new ... Builder(x)),
+// but .setSeqNo is on line 6. Walk-back must cross line boundaries.
+var linesMl = mlsrc.split('\n');
+var seqLine = 6; // .setSeqNo
+var seqCol = linesMl[seqLine].indexOf('setSeqNo') + 2;
+var seqH = jrlH3.handleHover(mlsrc, { line: seqLine, character: seqCol });
+test(seqH && seqH.contents && seqH.contents.value && /setSeqNo|property|seqNo/i.test(seqH.contents.value),
+  'Multi-line: hover on .setSeqNo resolves to EasyDAO setter (receiver on prior line)');
+
+// Hover on .setJournalType (line 7, two chained setters + Builder above)
+var jtLine = 7;
+var jtCol = linesMl[jtLine].indexOf('setJournalType') + 2;
+var jtH = jrlH3.handleHover(mlsrc, { line: jtLine, character: jtCol });
+test(jtH && jtH.contents && jtH.contents.value && /setJournalType|journalType|property/i.test(jtH.contents.value),
+  'Multi-line: hover on .setJournalType resolves to EasyDAO setter (chain with multiple prior setters)');
+
+// Hover on SINGLE_JOURNAL — should be enum value hover.
+var enumLine = 7;
+var enumCol = linesMl[enumLine].indexOf('SINGLE_JOURNAL') + 2;
+var enumH = jrlH3.handleHover(mlsrc, { line: enumLine, character: enumCol });
+if ( index.classExists('foam.dao.JournalType') ) {
+  test(enumH && enumH.contents && enumH.contents.value && /JournalType\.SINGLE_JOURNAL|enum value/i.test(enumH.contents.value),
+    'Hover on foam.dao.JournalType.SINGLE_JOURNAL shows enum value info');
+}
+
+// Completion at `foam.dao.JournalType.` — must surface enum values FIRST,
+// not all classes starting with foam.dao.JournalType.
+if ( index.classExists('foam.dao.JournalType') ) {
+  var enumCompSrc = [
+    'p({',
+    '  "serviceScript": """',
+    '    return new foam.dao.EasyDAO.Builder(x).setJournalType(foam.dao.JournalType.',
+    '  """',
+    '})'
+  ].join('\n');
+  var enumCompLine = 2;
+  var enumCompCol = enumCompSrc.split('\n')[enumCompLine].length;
+  var enumComp = jrlH3.handleCompletion(enumCompSrc, { line: enumCompLine, character: enumCompCol });
+  var hasSingleJournal = enumComp.items.some(function(it) { return it.label === 'SINGLE_JOURNAL'; });
+  test(hasSingleJournal,
+    'Completion after `foam.dao.JournalType.` offers enum values (SINGLE_JOURNAL found: ' +
+    enumComp.items.slice(0, 4).map(function(i) { return i.label; }).join(',') + ')');
+  // First item must be an enum value (kind 20), not a class
+  var firstIsEnum = enumComp.items.length > 0 && enumComp.items[0].kind === 20;
+  test(firstIsEnum,
+    'First completion item is an enum value (kind=20), not a class');
+}
+
 // === CHAINED BUILDER SETTER HOVERS ===
 section('Chained builder setter hovers — walk back through .a(x).b(y) chains');
 var chained = [
@@ -2821,6 +2886,46 @@ var chainedLine = chained.split('\n')[4];
     'Hover on .' + name + '( in chained builder — resolves to EasyDAO setter');
 });
 
+// === REAL services.jrl sanity check ===
+section('Real services.jrl hover sanity');
+var realJrlPath = require('path').resolve(__dirname, '../../../journals/services.jrl');
+if ( require('fs').existsSync(realJrlPath) ) {
+  var realText = require('fs').readFileSync(realJrlPath, 'utf8');
+  var realLines = realText.split('\n');
+
+  // Find the first .setPm( occurrence and hover on it.
+  for ( var rl = 0 ; rl < realLines.length ; rl++ ) {
+    var m = realLines[rl].indexOf('.setPm(');
+    if ( m === -1 ) continue;
+    var h = jrlH3.handleHover(realText, { line: rl, character: m + 3 });
+    test(h && h.contents && h.contents.value && /setPm|pm/i.test(h.contents.value),
+      'Real services.jrl: hover on .setPm at line ' + rl + ' resolves (setPm or pm in output)');
+    break;
+  }
+
+  // First .setOf( across the entire file.
+  for ( var rl2 = 0 ; rl2 < realLines.length ; rl2++ ) {
+    var m2 = realLines[rl2].indexOf('.setOf(');
+    if ( m2 === -1 ) continue;
+    var h2 = jrlH3.handleHover(realText, { line: rl2, character: m2 + 3 });
+    test(h2 && h2.contents && h2.contents.value && /setOf|of /i.test(h2.contents.value),
+      'Real services.jrl: hover on .setOf at line ' + rl2 + ' resolves');
+    break;
+  }
+
+  // First `foam.dao.JournalType.SINGLE_JOURNAL` reference.
+  for ( var rl3 = 0 ; rl3 < realLines.length ; rl3++ ) {
+    var m3 = realLines[rl3].indexOf('JournalType.SINGLE_JOURNAL');
+    if ( m3 === -1 ) continue;
+    // Hover on SINGLE_JOURNAL
+    var sj = realLines[rl3].indexOf('SINGLE_JOURNAL');
+    var h3 = jrlH3.handleHover(realText, { line: rl3, character: sj + 2 });
+    test(h3 && h3.contents && h3.contents.value && /SINGLE_JOURNAL|enum value|ordinal/i.test(h3.contents.value),
+      'Real services.jrl: hover on SINGLE_JOURNAL enum value resolves');
+    break;
+  }
+}
+
 // === SUMMARY ===
 
 section('SUMMARY');