@dot-agent/language-server 0.4.1 → 0.5.0-alpha.1

package/tests/formatting.test.js

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+import { describe, it, expect } from 'vitest'
+import { format } from '../features/formatting.js'
+
+// ── behavior formatting ───────────────────────────────────────────────────────
+
+describe('format — behavior', () => {
+    it('returns no edits for already-correct indentation', () => {
+        const text = [
+            'state init',
+            '  goal "hello"',
+            '  interact',
+            '  on intent "go" transition to next',
+            '  on offtopic transition to init',
+            '',
+            'state next',
+            '  guide "done"',
+        ].join('\n')
+        expect(format('behavior', text)).toHaveLength(0)
+    })
+
+    it('fixes over-indented state declaration', () => {
+        const text = '  state init\n  goal "hi"'
+        const edits = format('behavior', text)
+        const stateFix = edits.find(e => e.range.start.line === 0)
+        expect(stateFix).toBeDefined()
+        expect(stateFix.newText).toBe('')
+    })
+
+    it('fixes missing indentation inside state body', () => {
+        const text = 'state init\nguide "hello"'
+        const edits = format('behavior', text)
+        const guideFix = edits.find(e => e.range.start.line === 1)
+        expect(guideFix).toBeDefined()
+        expect(guideFix.newText).toBe('  ')
+    })
+
+    it('produces no edits for empty text', () => {
+        expect(format('behavior', '')).toHaveLength(0)
+    })
+
+    it('produces no edits for blank lines', () => {
+        expect(format('behavior', '\n\n\n')).toHaveLength(0)
+    })
+})
+
+// ── description formatting ────────────────────────────────────────────────────
+
+describe('format — description', () => {
+    it('returns no edits for already-correct indentation', () => {
+        const text = 'agent Doctor\n  domain example.com\n  license MIT'
+        expect(format('description', text)).toHaveLength(0)
+    })
+
+    it('fixes wrong indent on line starting with space (3→2)', () => {
+        // 3 spaces → starts with space → expectedIndent=2 → fix to 2
+        const text = '   agent Doctor\n  domain example.com'
+        const edits = format('description', text)
+        const fix = edits.find(e => e.range.start.line === 0)
+        expect(fix).toBeDefined()
+        expect(fix.newText).toBe('  ')
+    })
+
+    it('fixes wrong indent on nested property (4→2)', () => {
+        // 4 spaces → starts with space → expectedIndent=2 → fix to 2
+        const text = 'agent Doctor\n    domain example.com'
+        const edits = format('description', text)
+        const fix = edits.find(e => e.range.start.line === 1)
+        expect(fix).toBeDefined()
+        expect(fix.newText).toBe('  ')
+    })
+})
+
+// ── unknown langId ────────────────────────────────────────────────────────────
+
+describe('format — unknown langId', () => {
+    it('returns empty array', () => {
+        expect(format('unknown', 'anything')).toHaveLength(0)
+    })
+})

package/tests/hover.test.js

@@ -0,0 +1,87 @@
+// Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+import { describe, it, expect } from 'vitest'
+import { provideHover } from '../features/hover.js'
+
+// ── behavior keywords ─────────────────────────────────────────────────────────
+
+describe('provideHover — behavior', () => {
+    it('returns docs for "state" keyword', () => {
+        const result = provideHover('behavior', 'state init', { line: 0, character: 2 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/state/)
+    })
+
+    it('returns docs for "goal" keyword', () => {
+        const result = provideHover('behavior', '  goal "help"', { line: 0, character: 4 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/goal/)
+    })
+
+    it('returns docs for "interact" keyword', () => {
+        const result = provideHover('behavior', '  interact', { line: 0, character: 4 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/interact/)
+    })
+
+    it('returns docs for "transition" keyword', () => {
+        const result = provideHover('behavior', '  transition to next', { line: 0, character: 5 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/transition/)
+    })
+
+    it('returns docs for "merge" keyword', () => {
+        const result = provideHover('behavior', 'merge "base.behavior"', { line: 0, character: 2 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/merge/)
+    })
+
+    it('returns docs for "teach" keyword', () => {
+        const result = provideHover('behavior', '  teach "file.md"', { line: 0, character: 3 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/teach/)
+    })
+
+    it('returns null for unknown word', () => {
+        const result = provideHover('behavior', '  unknownkeyword', { line: 0, character: 5 })
+        expect(result).toBeNull()
+    })
+
+    it('returns null for empty position', () => {
+        const result = provideHover('behavior', '  ', { line: 0, character: 0 })
+        expect(result).toBeNull()
+    })
+})
+
+// ── description keywords ──────────────────────────────────────────────────────
+
+describe('provideHover — description', () => {
+    it('returns docs for "agent" keyword', () => {
+        const result = provideHover('description', 'agent Doctor', { line: 0, character: 2 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/agent/)
+    })
+
+    it('returns docs for "domain" keyword', () => {
+        const result = provideHover('description', '  domain example.com', { line: 0, character: 4 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/domain/)
+    })
+
+    it('returns docs for "type" keyword', () => {
+        const result = provideHover('description', 'type Patient', { line: 0, character: 2 })
+        expect(result).not.toBeNull()
+        expect(result.contents.value).toMatch(/type/)
+    })
+
+    it('returns null for behavior-only keyword in description mode', () => {
+        const result = provideHover('description', 'state init', { line: 0, character: 2 })
+        expect(result).toBeNull()
+    })
+})

package/tests/parser.test.js

@@ -0,0 +1,215 @@
+// Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+import { describe, it, expect, beforeAll } from 'vitest'
+import {
+    initParsers,
+    parse,
+    evict,
+    nodesOfType,
+    nodeAtOffset,
+    nodeToRange,
+    positionToOffset,
+    wordAtPosition,
+    getContextNode,
+} from '../parser.js'
+
+// transition-only state bodies are the safest valid fixture
+const BEHAVIOR_TEXT = `\
+state init
+  transition to next
+
+state next
+  transition to init
+`
+
+const DESCRIPTION_TEXT = `\
+agent Doctor
+  domain health.example.com
+  license MIT
+
+description
+  Clinical diagnostic agent.
+
+input Patient
+output Prescription
+`
+
+beforeAll(async () => {
+    await initParsers()
+})
+
+// ── parse + cache ─────────────────────────────────────────────────────────────
+
+describe('parse', () => {
+    it('parses behavior text and returns a tree', () => {
+        const tree = parse('uri:test.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        expect(tree).not.toBeNull()
+        expect(tree.rootNode.type).toBe('behavior_file')
+    })
+
+    it('returns the cached tree for the same version', () => {
+        const t1 = parse('uri:cached.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const t2 = parse('uri:cached.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        expect(t1).toBe(t2)
+    })
+
+    it('reparses when version changes', () => {
+        const t1 = parse('uri:versioned.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const t2 = parse('uri:versioned.behavior', 'behavior', BEHAVIOR_TEXT + '\n', 2)
+        expect(t1).not.toBe(t2)
+    })
+
+    it('parses description text', () => {
+        const tree = parse('uri:test.description', 'description', DESCRIPTION_TEXT, 1)
+        expect(tree).not.toBeNull()
+        expect(tree.rootNode.type).toBe('manifest')
+    })
+
+    it('returns no parse errors for valid behavior', () => {
+        const tree = parse('uri:valid.behavior', 'behavior', BEHAVIOR_TEXT, 2)
+        expect(tree.rootNode.hasError).toBe(false)
+    })
+
+    // Regression: parse() used to hand the previous version's tree to
+    // tree-sitter as an incremental-reuse hint without ever calling
+    // tree.edit() first, which tree-sitter requires to keep node byte ranges
+    // valid. Without it, node.text silently returns garbled/truncated
+    // strings after an edit shifts content — surfaced as "name must not be
+    // falsy" when the language server converted a corrupted state name to a
+    // DocumentSymbol.
+    it('does not corrupt node text across an edit at the same uri', () => {
+        const uri = 'uri:edited.behavior'
+        parse(uri, 'behavior', BEHAVIOR_TEXT, 1)
+        const editedText = 'state prepended\n  transition to init\n\n' + BEHAVIOR_TEXT
+        const tree = parse(uri, 'behavior', editedText, 2)
+        const names = nodesOfType(tree, 'state_decl').map(n => n.childForFieldName('name')?.text)
+        expect(names).toEqual(['prepended', 'init', 'next'])
+        expect(names.every(n => n && n.length > 0)).toBe(true)
+    })
+})
+
+// ── evict ─────────────────────────────────────────────────────────────────────
+
+describe('evict', () => {
+    it('removes cached tree so next parse re-builds', () => {
+        const uri = 'uri:evict-test.behavior'
+        const t1 = parse(uri, 'behavior', BEHAVIOR_TEXT, 1)
+        evict(uri)
+        const t2 = parse(uri, 'behavior', BEHAVIOR_TEXT, 1)
+        // After evict, same version → new tree object
+        expect(t1).not.toBe(t2)
+    })
+})
+
+// ── nodesOfType ───────────────────────────────────────────────────────────────
+
+describe('nodesOfType', () => {
+    it('returns all state_decl nodes from a behavior tree', () => {
+        const tree = parse('uri:nodes.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const states = nodesOfType(tree, 'state_decl')
+        expect(states.length).toBe(2)
+        expect(states.map(n => n.childForFieldName('name')?.text)).toEqual(['init', 'next'])
+    })
+
+    it('returns empty array for unknown node type', () => {
+        const tree = parse('uri:nodes2.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        expect(nodesOfType(tree, 'nonexistent_node')).toHaveLength(0)
+    })
+
+    it('returns empty array for null tree', () => {
+        expect(nodesOfType(null, 'state_decl')).toHaveLength(0)
+    })
+
+    it('returns agent_decl from description tree', () => {
+        const tree = parse('uri:desc-nodes.description', 'description', DESCRIPTION_TEXT, 1)
+        const agents = nodesOfType(tree, 'agent_decl')
+        expect(agents.length).toBe(1)
+        expect(agents[0].childForFieldName('name')?.text).toBe('Doctor')
+    })
+})
+
+// ── nodeToRange ───────────────────────────────────────────────────────────────
+
+describe('nodeToRange', () => {
+    it('converts a node to an LSP range', () => {
+        const tree = parse('uri:range.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const [firstState] = nodesOfType(tree, 'state_decl')
+        const range = nodeToRange(firstState)
+        expect(range.start.line).toBe(0)
+        expect(range.start.character).toBe(0)
+        expect(range.end.line).toBeGreaterThanOrEqual(1)
+    })
+})
+
+// ── positionToOffset ──────────────────────────────────────────────────────────
+
+describe('positionToOffset', () => {
+    it('returns 0 for line 0 character 0', () => {
+        expect(positionToOffset('hello\nworld', 0, 0)).toBe(0)
+    })
+
+    it('returns correct offset for line 1', () => {
+        expect(positionToOffset('hello\nworld', 1, 0)).toBe(6)
+    })
+
+    it('returns correct offset for mid-line character', () => {
+        expect(positionToOffset('hello\nworld', 0, 3)).toBe(3)
+    })
+})
+
+// ── wordAtPosition ────────────────────────────────────────────────────────────
+
+describe('wordAtPosition', () => {
+    it('extracts identifier at cursor inside word', () => {
+        const { word } = wordAtPosition('  transition to init', 0, 5)
+        expect(word).toBe('transition')
+    })
+
+    it('extracts dotted identifier', () => {
+        const { word } = wordAtPosition('set context.name', 0, 6)
+        expect(word).toBe('context.name')
+    })
+
+    it('extracts word when cursor is at a boundary between word and space', () => {
+        // At "state init", ch=5 (the space) — walks back into "state"
+        const { word } = wordAtPosition('state init', 0, 5)
+        expect(word).toBe('state')
+    })
+
+    it('returns empty string when cursor is before any word character', () => {
+        const { word } = wordAtPosition('  state init', 0, 0)
+        expect(word).toBe('')
+    })
+})
+
+// ── nodeAtOffset ──────────────────────────────────────────────────────────────
+
+describe('nodeAtOffset', () => {
+    it('returns a node at the given byte offset', () => {
+        const tree = parse('uri:offset.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const node = nodeAtOffset(tree, 0)
+        expect(node).not.toBeNull()
+    })
+
+    it('returns null for null tree', () => {
+        expect(nodeAtOffset(null, 0)).toBeNull()
+    })
+})
+
+// ── getContextNode ────────────────────────────────────────────────────────────
+
+describe('getContextNode', () => {
+    it('returns a non-error node for valid position', () => {
+        const tree = parse('uri:ctx.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const offset = positionToOffset(BEHAVIOR_TEXT, 0, 6)
+        const node = getContextNode(tree, offset)
+        expect(node).not.toBeNull()
+        expect(node.isError).toBeFalsy()
+    })
+})

package/tests/references.test.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+import { describe, it, expect, beforeAll } from 'vitest'
+import { initParsers, parse } from '../parser.js'
+import { provideReferences } from '../features/references.js'
+
+const BEHAVIOR_TEXT = `\
+state init
+  transition to next
+  transition to next
+
+state next
+  transition to init
+`
+
+beforeAll(async () => { await initParsers() })
+
+describe('provideReferences — behavior states', () => {
+    const uri = 'file:///test.behavior'
+
+    it('finds declaration + all transition targets for "next"', () => {
+        const tree = parse(uri, 'behavior', BEHAVIOR_TEXT, 1)
+        // "next" is at line 4, char 6
+        const refs = provideReferences('behavior', tree, BEHAVIOR_TEXT, uri, { line: 4, character: 6 })
+        // 1 declaration + 2 transition targets
+        expect(refs.length).toBe(3)
+    })
+
+    it('finds declaration + one transition for "init"', () => {
+        const tree = parse(uri + '2', 'behavior', BEHAVIOR_TEXT, 1)
+        // "init" is at line 0, char 6
+        const refs = provideReferences('behavior', tree, BEHAVIOR_TEXT, uri + '2', { line: 0, character: 6 })
+        // 1 declaration + 1 transition target
+        expect(refs.length).toBe(2)
+    })
+
+    it('returns empty array for null tree', () => {
+        expect(provideReferences('behavior', null, '', uri, { line: 0, character: 0 })).toHaveLength(0)
+    })
+
+    it('returns empty array when word not found', () => {
+        const tree = parse(uri + '3', 'behavior', BEHAVIOR_TEXT, 1)
+        const refs = provideReferences('behavior', tree, BEHAVIOR_TEXT, uri + '3', { line: 1, character: 0 })
+        expect(refs).toHaveLength(0)
+    })
+})

package/tests/rename.test.js

@@ -0,0 +1,47 @@
+// Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+import { describe, it, expect, beforeAll } from 'vitest'
+import { initParsers, parse } from '../parser.js'
+import { provideRenameEdits } from '../features/rename.js'
+
+const BEHAVIOR_TEXT = `\
+state init
+  transition to next
+
+state next
+  transition to init
+`
+
+beforeAll(async () => { await initParsers() })
+
+describe('provideRenameEdits — behavior', () => {
+    const uri = 'file:///test.behavior'
+
+    it('renames state declaration and all transition targets', () => {
+        const tree = parse(uri, 'behavior', BEHAVIOR_TEXT, 1)
+        // "next" is at line 3, char 6
+        const result = provideRenameEdits('behavior', tree, BEHAVIOR_TEXT, uri, { line: 3, character: 6 }, 'renamed')
+        expect(result).not.toBeNull()
+        const edits = result.changes[uri]
+        // 1 declaration + 1 transition target
+        expect(edits).toHaveLength(2)
+        expect(edits.every(e => e.newText === 'renamed')).toBe(true)
+    })
+
+    it('returns null when word is not a declared state', () => {
+        const tree = parse(uri + '2', 'behavior', BEHAVIOR_TEXT, 1)
+        // cursor on "transition" keyword — not a state name
+        const result = provideRenameEdits('behavior', tree, BEHAVIOR_TEXT, uri + '2', { line: 1, character: 2 }, 'x')
+        expect(result).toBeNull()
+    })
+
+    it('returns null for null tree', () => {
+        expect(provideRenameEdits('behavior', null, '', uri, { line: 0, character: 0 }, 'x')).toBeNull()
+    })
+})

package/tests/symbols.test.js

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+import { describe, it, expect, beforeAll } from 'vitest'
+import { initParsers, parse } from '../parser.js'
+import { provideDocumentSymbols } from '../features/symbols.js'
+
+const BEHAVIOR_TEXT = `\
+on event "start"
+  transition to init
+
+state init
+  transition to next
+
+state next
+  transition to init
+`
+
+const DESCRIPTION_TEXT = `\
+agent Doctor
+  domain health.example.com
+  license MIT
+
+description
+  Clinical diagnostic agent.
+`
+
+beforeAll(async () => { await initParsers() })
+
+describe('provideDocumentSymbols — behavior', () => {
+    it('returns all state_decl as Class symbols', () => {
+        const tree = parse('uri:sym.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const symbols = provideDocumentSymbols('behavior', tree)
+        const states = symbols.filter(s => s.kind === 5) // Class
+        expect(states.map(s => s.name)).toEqual(['init', 'next'])
+    })
+
+    it('returns trigger_decl as Event symbol', () => {
+        const tree = parse('uri:sym2.behavior', 'behavior', BEHAVIOR_TEXT, 1)
+        const symbols = provideDocumentSymbols('behavior', tree)
+        const events = symbols.filter(s => s.kind === 24) // Event
+        expect(events).toHaveLength(1)
+        expect(events[0].name).toMatch(/start/)
+    })
+
+    it('returns empty array for null tree', () => {
+        expect(provideDocumentSymbols('behavior', null)).toHaveLength(0)
+    })
+})
+
+describe('provideDocumentSymbols — description', () => {
+    it('returns agent_decl as Class symbol', () => {
+        const tree = parse('uri:sym.description', 'description', DESCRIPTION_TEXT, 1)
+        const symbols = provideDocumentSymbols('description', tree)
+        const agents = symbols.filter(s => s.kind === 5)
+        expect(agents).toHaveLength(1)
+        expect(agents[0].name).toBe('Doctor')
+    })
+
+    it('returns empty array for null tree', () => {
+        expect(provideDocumentSymbols('description', null)).toHaveLength(0)
+    })
+})

package/.github/workflows/publish.yml

@@ -1,28 +0,0 @@
-name: Publish to npm
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  id-token: write
-  contents: read
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '24.x'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Publish package to npm
-        run: npm publish

package/features/graph.js

@@ -1,53 +0,0 @@
-/*
- * Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-'use strict';
-
-const { nodesOfType } = require('../parser');
-
-function extractBehaviorGraph(tree) {
-    const states = nodesOfType(tree, 'state_decl')
-        .map(n => n.childForFieldName('name')?.text)
-        .filter(Boolean);
-
-    const transitions = [];
-    const seen = new Set();
-    for (const stateNode of nodesOfType(tree, 'state_decl')) {
-        const from = stateNode.childForFieldName('name')?.text;
-        if (!from) continue;
-        for (const t of stateNode.descendantsOfType('transition_stmt')) {
-            const to = t.childForFieldName('state')?.text;
-            if (to) {
-                const key = `${from}→${to}`;
-                if (!seen.has(key)) { seen.add(key); transitions.push({ from, to }); }
-            }
-        }
-    }
-
-    const entryPoints = [];
-    for (const triggerNode of nodesOfType(tree, 'trigger_decl')) {
-        // event field is a quoted_string WITHOUT surrounding quotes (quotes are literals in the grammar rule)
-        const eventText = triggerNode.childForFieldName('event')?.text;
-        for (const t of triggerNode.descendantsOfType('transition_stmt')) {
-            const to = t.childForFieldName('state')?.text;
-            if (eventText && to) entryPoints.push({ event: eventText, to });
-        }
-    }
-
-    return { states, transitions, entryPoints };
-}
-
-module.exports = { extractBehaviorGraph };