aontu 0.52.1 → 0.54.0

package/src/lsp.ts

@@ -18,8 +18,12 @@
 
 import type { Val } from './type'
 
-import { Aontu } from './aontu'
+import { Aontu, VERSION } from './aontu'
 import { getHint } from './err'
+import { collectNils } from './walk'
+import { collectDeprecations, deprecationMessage } from './utility'
+import { why } from './query'
+import type { WhyConjunct } from './provenance'
 
 
 // LSP DiagnosticSeverity subset.
@@ -28,8 +32,12 @@ const SEVERITY_WARNING = 2
 const SEVERITY_INFORMATION = 3
 const SEVERITY_HINT = 4
 
-// Reported to the client in the initialize response.
-const LSP_VERSION = '0.1.0'
+// Reported to the client in the initialize response. It is the
+// ENGINE's version, not a number of the server's own: a separately
+// maintained one drifts, and had -- the server answered 0.1.0 against
+// a package at 0.52.1, so a client could not tell which engine it was
+// talking to (status-2026-08-21.md section 10).
+const LSP_VERSION = VERSION
 
 
 // Zero-based line / UTF-16 character offset (LSP Position).
@@ -45,6 +53,9 @@ type Diagnostic = {
   code?: string
   source: string
   message: string
+  // LSP DiagnosticTag values; [1] is Unnecessary, [2] is Deprecated —
+  // the native tag editors strike through (G3 phase 4).
+  tags?: number[]
 }
 
 
@@ -73,9 +84,13 @@ type OutMessage = {
 // functions, syntax errors) produce diagnostics.
 function computeDiagnostics(
   src: string,
-  opts?: { vars?: Record<string, Val> }
+  opts?: { vars?: Record<string, Val>, trust?: any }
 ): Diagnostic[] {
-  const aontu = new Aontu()
+  // The trust profile (G5, docs/trust.md): the LSP is the
+  // highest-exposure surface — merely OPENING a hostile .aon file in an
+  // editor performs its reads — so the handler confines evaluation to
+  // the workspace root and threads the profile through here.
+  const aontu = new Aontu(null == opts?.trust ? {} : { trust: opts.trust })
 
   let root: any
   let ac: any
@@ -92,9 +107,10 @@ function computeDiagnostics(
     return [parseErrorDiagnostic(err)]
   }
 
-  const nils: any[] = []
+  // The walk's `seen` set is reused below to dedup context errors
+  // against the nils already found in the tree.
   const seen = new Set()
-  walkNils(root, nils, seen)
+  const nils: any[] = collectNils(root, seen)
 
   // Errors recorded on the context but not present in the tree — e.g. a
   // budget_passes exhaustion nil, which is about the whole evaluation
@@ -109,34 +125,35 @@ function computeDiagnostics(
     }
   }
 
-  return nils.map(nilToDiagnostic)
-}
-
-
-// Walk a unified Val tree collecting every NilVal exactly once. A NilVal
-// in the result always represents an error; valid non-concrete values
-// (scalar kinds, refs, conjuncts) are never NilVals.
-function walkNils(v: any, out: any[], seen: Set<any>) {
-  if (null == v || 'object' !== typeof v || true !== v.isVal) return
-  if (seen.has(v)) return
-  seen.add(v)
-
-  if (v.isNil) {
-    out.push(v)
-    return
-  }
-
-  const peg = v.peg
-  if (Array.isArray(peg)) {
-    for (const c of peg) walkNils(c, out, seen)
-  }
-  else if (null != peg && 'object' === typeof peg) {
-    for (const k in peg) walkNils(peg[k], out, seen)
+  const out = nils.map(nilToDiagnostic)
+
+  // Deprecation tags (G3 phase 4): every sited value carrying the
+  // deprecate() record — the declaration and, because the record rides
+  // meets and reference clones, every use resolving through it — gets
+  // the native Deprecated tag (2) at Hint severity, so editors strike
+  // it through without shouting.
+  for (const { val } of collectDeprecations(root)) {
+    const v: any = val
+    if (1 > (v.site?.row ?? -1) || 1 > (v.site?.col ?? -1)) {
+      continue
+    }
+    out.push({
+      range: {
+        start: { line: v.site.row - 1, character: v.site.col - 1 },
+        end: {
+          line: v.site.row - 1,
+          character: v.site.col - 1 + siteExtent(v),
+        },
+      },
+      severity: 4,
+      code: 'deprecated',
+      source: 'aontu',
+      message: deprecationMessage(v.deprecation),
+      tags: [2],
+    })
   }
 
-  // Spread constraints live off-peg on Map/List Vals.
-  const spreadCj = v.spread?.cj
-  if (spreadCj) walkNils(spreadCj, out, seen)
+  return out
 }
 
 
@@ -169,9 +186,39 @@ function nilToDiagnostic(nil: any): Diagnostic {
 
 
 // Length (UTF-16 units, like LSP characters) of the offending value's
-// canonical form, used to size the diagnostic range (minimum 1).
+// SOURCE TEXT, used to size the diagnostic range (minimum 1).
 function labelLength(nil: any): number {
-  const c = nil.primary?.canon
+  return null == nil.primary ? 1 : siteExtent(nil.primary)
+}
+
+
+// The extent to underline for a value: its SOURCE TEXT's length, with
+// the canon as the fallback and 1 as the floor.
+//
+// CANON IS NOT SOURCE TEXT, which is the whole point of Site.len:
+// `0x1F` has canon `31`, so sizing by canon underlines two characters
+// of a four-character literal — hovering `0x1F` highlighted `0x` and
+// hovering `1F` answered nothing. The Go twin is the same fallback in
+// go/check.go (Problem.Len, ValueSpan.Len), in bytes there because it
+// is added to a byte offset before conversion.
+//
+// The fallback is for a value carrying no stamped span — one propagated
+// onto a result rather than written by a document — where canon is all
+// there is and an approximate underline beats none. A REPORT never
+// guesses this way: vet and why emit len only when it is known, because
+// there a wrong length is a corrupted document rather than a wonky
+// highlight.
+function siteExtent(v: any): number {
+  const len = v?.site?.len
+  if ('number' === typeof len && len > 0) {
+    return len
+  }
+  // CANON IS READ DEFENSIVELY, as every other reader here does: it is a
+  // getter that unifies, and a host-supplied value can throw from it
+  // (hover-refuses-bad-input). A hover that cannot measure a value
+  // still has to answer for the rest of the document.
+  let c = ''
+  try { c = v?.canon } catch { c = '' }
   return 'string' === typeof c && c.length > 0 ? c.length : 1
 }
 
@@ -223,6 +270,7 @@ function initializeResult() {
       textDocumentSync: 1,
       hoverProvider: true,
       completionProvider: {},
+      signatureHelpProvider: { triggerCharacters: ['(', ','] },
     },
     serverInfo: {
       name: 'aontu-lsp',
@@ -232,6 +280,59 @@ function initializeResult() {
 }
 
 
+// signatureHelp: the declared signature of the ENCLOSING call, served
+// from the registry (docs/design/SIGNATURES.0.md). The enclosing call
+// is found lexically -- scan back from the cursor for the nearest
+// unclosed '(' and read the word before it; commas at that depth
+// count the active parameter, capped at the last slot so a rest tail
+// stays active for every excess argument. Strings are skipped so a
+// paren or comma inside one does not miscount, and the scan stops at
+// the line start, a call being one line in practice.
+function computeSignatureHelp(text: string, pos: any): any {
+  // Position to offset, under the full-sync model: lines are exactly
+  // the text's newlines.
+  const lines = text.split('\n')
+  const line = Math.max(0, Math.min(Number(pos.line) || 0, lines.length - 1))
+  let offset = 0
+  for (let li = 0; li < line; li++) {
+    offset += lines[li].length + 1
+  }
+  offset += Math.max(0, Math.min(Number(pos.character) || 0, lines[line].length))
+  let depth = 0
+  let commas = 0
+  let open = -1
+  for (let i = offset - 1; 0 <= i; i--) {
+    const c = text[i]
+    if ('"' === c || "'" === c) {
+      for (i--; 0 <= i && text[i] !== c; i--) { }
+      continue
+    }
+    if (')' === c) { depth++ }
+    else if ('(' === c) {
+      if (0 === depth) { open = i; break }
+      depth--
+    }
+    else if (',' === c && 0 === depth) { commas++ }
+    else if ('\n' === c && 0 === depth) { break }
+  }
+  if (0 > open) { return null }
+  let start = open
+  while (0 < start && /[a-zA-Z0-9_]/.test(text[start - 1])) { start-- }
+  const name = text.slice(start, open)
+  const sig = funcSig[name]
+  if (undefined === sig) { return null }
+  const last = sig.args.length - 1
+  return {
+    signatures: [{
+      label: renderSig(sig),
+      parameters: sig.args.map((a) => ({ label: renderSigArg(a) })),
+    }],
+    activeSignature: 0,
+    activeParameter: Math.min(commas, 0 <= last ? last : 0),
+  }
+}
+
+
 function publishDiagnosticsMsg(uri: string, diagnostics: Diagnostic[]): OutMessage {
   return {
     jsonrpc: '2.0',
@@ -251,10 +352,52 @@ type Hover = { contents: MarkupContent, range?: Range }
 // the position is not over a value with a known source location. Because
 // hover reads the *unified* tree, a literal shows its resolved value and
 // kind (e.g. a reference target resolves to the value it points at).
-function computeHover(src: string, position: Position): Hover | null {
+// HOVER PROVENANCE (G7 phase 7) is CONFIG-GATED and off by default:
+// the contributions that met at the hovered path, appended to the
+// value's own hover. Hover already re-unifies the whole document per
+// request, so an editor that asks for this pays a second instrumented
+// evaluation knowingly, and one that does not pays nothing.
+function provenanceMarkdown(
+  src: string, path: string[], trust?: any): string {
+  if (0 === path.length) {
+    return ''
+  }
+  // A document with an error ELSEWHERE still hovers — the tree the
+  // hover walked is there — while `why` refuses it, so the record may
+  // be absent for a value the cursor is sitting on.
+  const report = why(src, '$.' + path.join('.'), { trust } as any)
+  return contributionsMarkdown(report.record?.conjuncts ?? [])
+}
+
+
+// The contributions as hover markdown. Exported for the direct test
+// (ADR-002): a siteless contribution and a named file are both shapes
+// the record allows and no hover produces, hover evaluating one
+// unnamed document.
+export function contributionsMarkdown(conjuncts: WhyConjunct[]): string {
+  if (0 === conjuncts.length) {
+    return ''
+  }
+  return '\n\n---\n\nContributions:\n' + conjuncts.map((c) =>
+    '- `' + c.canon + '` — ' + c.role +
+    (0 > c.site.row ? '' : ' (' +
+      ('' === c.site.file ? '' : c.site.file + ':') +
+      c.site.row + ':' + c.site.col + ')')).join('\n')
+}
+
+
+// HOVER RUNS UNDER THE SAME CAPABILITY AS DIAGNOSTICS. It used to
+// evaluate through `new Aontu()` -- the full system resolver -- BESIDE
+// confined diagnostics in the same server, so a workspace-confined
+// session still resolved an escaping include the moment a cursor rested
+// on it (use-cases/REVIEW.md finding G). One document, two postures, is
+// not a confinement.
+function computeHover(
+  src: string, position: Position, provenance?: boolean,
+  trust?: any): Hover | null {
   let root: any
   try {
-    root = new Aontu().unify(src, { collect: true })
+    root = new Aontu(null == trust ? {} : { trust }).unify(src, { collect: true })
   }
   catch {
     return null
@@ -274,7 +417,12 @@ function computeHover(src: string, position: Position): Hover | null {
   if (null == best) return null
 
   return {
-    contents: { kind: 'markdown', value: hoverMarkdown(best.val) },
+    contents: {
+      kind: 'markdown',
+      value: hoverMarkdown(best.val) +
+        (true === provenance
+          ? provenanceMarkdown(src, best.val.path, trust) : ''),
+    },
     range: {
       start: { line: best.line, character: best.start },
       end: { line: best.line, character: best.end },
@@ -296,15 +444,24 @@ function collectHoverCandidates(
   const col = v.site.col
   let canon = ''
   try { canon = v.canon } catch { canon = '' }
+  // The span to highlight: the value's own source text where it has
+  // one, canon otherwise. See siteExtent.
+  const span = siteExtent(v)
+  const spanSrc = 'string' === typeof v.site?.src ? v.site.src : ''
   // Hover targets concrete values (scalars, kinds, refs, …), not
   // containers: a map/list source span is not reliably reconstructable
   // from a single site, and the same restriction in the Go port keeps
   // hover behaviour identical across implementations. The walk still
   // recurses into containers below to reach their leaf values. Canon is
   // single-line, so its length approximates the on-line source span.
-  if (row >= 1 && col >= 1 && canon.length > 0 && !canon.includes('\n') &&
+  // Single-line is decided by the SOURCE TEXT when there is one: a
+  // multi-line token cannot be described by one line's start and end,
+  // and canon's newlines are not the token's. Falling back to canon
+  // keeps the old test for a value with no stamped span.
+  const multiline = '' === spanSrc ? canon.includes('\n') : spanSrc.includes('\n')
+  if (row >= 1 && col >= 1 && canon.length > 0 && !multiline &&
     !v.isMap && !v.isList) {
-    out.push({ val: v, line: row - 1, start: col - 1, end: col - 1 + canon.length })
+    out.push({ val: v, line: row - 1, start: col - 1, end: col - 1 + span })
   }
 
   const peg = v.peg
@@ -354,16 +511,27 @@ type CompletionItem = {
   detail?: string
 }
 
+import { funcSig, renderSig, renderSigArg } from './sig'
+
 // LSP CompletionItemKind subset.
 const COMPLETION_FUNCTION = 3
 const COMPLETION_KEYWORD = 14
 
-// The twenty-one built-in functions. Kept in sync with the engine by
+// The built-in functions. Kept in sync with the engine by
 // `lsp.test.ts`, which asserts each is recognised and no others are.
+// The Go port derives its list from the engine's own name set
+// (`BuiltinFuncNames`, go/func.go), which is why a name added there
+// and forgotten here diverges silently — as `id` and `refer` did
+// between G4 phases 1/2 and G8 phase 1.
 const BUILTIN_FUNCS = [
-  'above', 'below', 'close', 'copy', 'hide', 'key', 'length', 'lower',
-  'max', 'min', 'move', 'must', 'neq', 'open', 'path', 'pref', 're',
-  'super', 'type', 'unique', 'upper',
+  'above', 'acyclic', 'add', 'below', 'close', 'copy', 'deprecate', 'div',
+  'each',
+  'filter', 'greatest',
+  'hide', 'inverse', 'join', 'key', 'least', 'length', 'list', 'lower',
+  'map', 'match', 'max', 'min', 'mod', 'move', 'mul', 'must', 'neq', 'open',
+  'pack', 'path', 'pick',
+  'pref', 're', 'refer', 'rel', 'rem', 'sub', 'sum', 'super', 'type', 'unique',
+  'upper',
 ]
 
 // Scalar-kind and literal keywords.
@@ -372,7 +540,9 @@ const BUILTIN_FUNCS = [
 const KIND_KEYWORDS = [
   'string', 'number', 'integer', 'float', 'biginteger', 'bigdecimal', 'boolean',
 ]
-const LITERAL_KEYWORDS = ['true', 'false', 'null', 'top']
+// `_` joins these as of G8 phase 3: it is a literal of the language
+// now, not text.
+const LITERAL_KEYWORDS = ['_', 'true', 'false', 'null', 'top']
 
 
 // Context-free completion: the built-in functions, scalar-kind keywords
@@ -380,7 +550,10 @@ const LITERAL_KEYWORDS = ['true', 'false', 'null', 'top']
 function computeCompletions(): CompletionItem[] {
   const out: CompletionItem[] = []
   for (const f of BUILTIN_FUNCS) {
-    out.push({ label: f, kind: COMPLETION_FUNCTION, detail: 'Aontu built-in function' })
+    // The detail is the rendered SIGNATURE (docs/design/SIGNATURES.0.md)
+    // -- the same renderer the hints and the docs table use, so the
+    // completion list cannot drift from the declaration.
+    out.push({ label: f, kind: COMPLETION_FUNCTION, detail: renderSig(funcSig[f]) })
   }
   for (const k of KIND_KEYWORDS) {
     out.push({ label: k, kind: COMPLETION_KEYWORD, detail: 'scalar kind' })
@@ -396,11 +569,103 @@ function computeCompletions(): CompletionItem[] {
 // messages and returns the messages to send back, tracking open document
 // text and recomputing diagnostics on open/change/close. Not safe for
 // concurrent use; drive it from a single loop (as the stdio server does).
+// A file:// uri's filesystem path, for the workspace-root confinement.
+// Percent-decoded; a non-file uri (or none) yields undefined.
+//
+// EXPORTED, inline as contributionsMarkdown is: part of the reusable
+// LSP library surface, and the twin of the package-visible uriToPath in
+// go/lsp/handler.go. Anything driving this module with its own
+// transport has to turn a client's uri into a path the same way the
+// confinement does, and the rules below are not guessable from outside.
+//
+// THE DRIVE-LETTER SLASH. A file uri names an absolute path after the
+// authority, so on Windows the standard spelling every editor sends is
+// file:///C:/Users/me/project — three slashes, and the third belongs to
+// the PATH. Stripping only `file://` leaves `/C:/Users/me/project`,
+// which is not a Windows path at all, so the workspace-root
+// confinement below compared real paths against nonsense and an editor
+// on Windows got no confinement it could rely on. Both ports carried
+// the defect identically (go/lsp/handler.go uriToPath), and no test
+// caught it because both ports' tests built the uri as `'file://' +
+// path` — two slashes, which is not what a client sends and which
+// accidentally produced a usable path.
+//
+// The leading slash is dropped only before a DRIVE LETTER, so a POSIX
+// path keeps the root it needs: file:///tmp/x stays /tmp/x.
+export function uriToPath(uri: unknown): string | undefined {
+  if ('string' !== typeof uri || !uri.startsWith('file://')) {
+    return undefined
+  }
+  const path = percentDecode(uri.slice('file://'.length))
+  // AN EMPTY PATH IS NOT A ROOT. `file://` on its own yields '', and
+  // '' is not nullish — so it won the `??` chain below and arrived as
+  // `{ include: { root: '' } }`, a confinement root that then resolves
+  // against the process working directory: the same client params made
+  // the server allow or deny an include depending on where it was
+  // started from. The Go twin never had it, because its chain tests
+  // `"" != folder` explicitly (go/lsp/handler.go). Answering undefined
+  // is what makes the two chains agree.
+  if ('' === path) {
+    return undefined
+  }
+  return driveLetterPath(path) ? path.slice(1) : path
+}
+
+
+// Percent-decoding that CANNOT THROW. `decodeURIComponent` raises a
+// URIError on a malformed escape (`%ZZ`), and this runs on a uri a
+// CLIENT sent — so a stray percent in a workspace path took the
+// exception straight out of the initialize handler, where the Go twin
+// swallowed the same failure and used the raw text
+// (go/lsp/handler.go). Two ports, two behaviours, for an input neither
+// of them controls.
+//
+// The agreement runs the other way for the SECOND way an escape can
+// fail to decode. `%FF` is well-formed and names a raw byte — a
+// perfectly good Linux filename — which Go produced and a JavaScript
+// string cannot hold at all, so the ports derived different workspace
+// roots for a uri a byte-oriented client really sends. Only one
+// direction is reachable from both languages, so Go now declines to
+// unescape a result that is not valid UTF-8 and both ports keep the
+// raw text. An undecodable path is still a path, and refusing to serve
+// a session over it helps nobody.
+function percentDecode(text: string): string {
+  try {
+    return decodeURIComponent(text)
+  }
+  catch {
+    return text
+  }
+}
+
+
+// Whether p is `/X:…` for a drive letter X — the one shape whose
+// leading slash is uri syntax rather than path. Mirrors the same
+// predicate in go/lsp/handler.go.
+function driveLetterPath(p: string): boolean {
+  return 3 <= p.length && '/' === p[0] && ':' === p[2] &&
+    /[A-Za-z]/.test(p[1])
+}
+
+
 class LspHandler {
   private docs = new Map<string, string>()
   private shutdownOK = false
   private exited = false
 
+  // The trust profile evaluation runs under (G5, docs/trust.md):
+  // workspace-root confinement by default, set from the initialize
+  // params. An `initializationOptions.aontu.trust.include` of 'system',
+  // 'none' or { root } widens or narrows it explicitly. Undefined —
+  // no workspace root and no explicit option — falls back to today's
+  // unconfined behaviour, which single-file sessions rely on.
+  private trust: any = undefined
+
+  // Hover provenance (G7 phase 7): off unless an editor asks for it
+  // with `initializationOptions.aontu.provenance`. It costs a second,
+  // instrumented evaluation per hover, which is a cost to opt into.
+  private provenance = false
+
   // True once an `exit` notification has been received.
   get shouldExit(): boolean { return this.exited }
 
@@ -414,8 +679,34 @@ class LspHandler {
   // Process one incoming message, returning zero or more to send.
   handle(msg: Message): OutMessage[] {
     switch (msg.method) {
-      case 'initialize':
+      case 'initialize': {
+        const params = msg.params ?? {}
+        this.provenance =
+          true === params.initializationOptions?.aontu?.provenance
+        const explicit = params.initializationOptions?.aontu?.trust?.include
+        if (null != explicit) {
+          // An explicit setting wins — validated, and an unrecognised
+          // value confines to NOTHING rather than silently widening:
+          // deny is the safe reading of a setting the server does not
+          // understand. The same rule as the Go handler.
+          this.trust =
+            'system' === explicit ? undefined :
+              'none' === explicit ? { include: 'none' } :
+                ('string' === typeof explicit?.root && '' !== explicit.root)
+                  ? { include: { root: explicit.root } } :
+                  (null != explicit?.mem && 'object' === typeof explicit.mem)
+                    ? { include: { mem: explicit.mem } } :
+                    { include: 'none' }
+        }
+        else {
+          const root = uriToPath(params.workspaceFolders?.[0]?.uri)
+            ?? uriToPath(params.rootUri)
+            ?? (('string' === typeof params.rootPath && '' !== params.rootPath)
+              ? params.rootPath : undefined)
+          this.trust = null != root ? { include: { root } } : undefined
+        }
         return [{ jsonrpc: '2.0', id: msg.id, result: initializeResult() }]
+      }
 
       case 'initialized':
         return []
@@ -456,13 +747,23 @@ class LspHandler {
         const uri = msg.params?.textDocument?.uri
         const pos = msg.params?.position
         const text = null != uri ? this.docs.get(uri) : undefined
-        const hover = (null != text && null != pos) ? computeHover(text, pos) : null
+        const hover = (null != text && null != pos)
+          ? computeHover(text, pos, this.provenance, this.trust) : null
         return [{ jsonrpc: '2.0', id: msg.id, result: hover }]
       }
 
       case 'textDocument/completion':
         return [{ jsonrpc: '2.0', id: msg.id, result: computeCompletions() }]
 
+      case 'textDocument/signatureHelp': {
+        const uri = msg.params?.textDocument?.uri
+        const pos = msg.params?.position
+        const text = null != uri ? this.docs.get(uri) : undefined
+        const help = (null != text && null != pos)
+          ? computeSignatureHelp(text, pos) : null
+        return [{ jsonrpc: '2.0', id: msg.id, result: help }]
+      }
+
       default:
         // Unknown request (has an id): reply method-not-found. Unknown
         // notification: ignore.
@@ -478,7 +779,8 @@ class LspHandler {
   }
 
   private publish(uri: string): OutMessage {
-    return publishDiagnosticsMsg(uri, computeDiagnostics(this.docs.get(uri) ?? ''))
+    return publishDiagnosticsMsg(uri,
+      computeDiagnostics(this.docs.get(uri) ?? '', { trust: this.trust }))
   }
 } /* node:coverage ignore next 28 */