@zenithbuild/language-server 0.5.0-beta.2.20 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.0] - 2026-02-28
+
+### Added
+
+- `zenith.strictDomLints` setting: when `true`, ZEN-DOM-* diagnostics are errors; when `false`, hints
+- Diagnostics from compiler JSON warnings (schemaVersion=1 contract)
+- Debounce and cancellation for compile requests
+- On-save validation
+- Code actions for ZEN-DOM-* (querySelector → ref, addEventListener → zenOn)
+- Code actions for window/document → zenWindow/zenDocument
+- Completions for canonical primitives (ref, signal, state, zenOn, zenMount, etc.)
+
+### Changed
+
+- Requires @zenithbuild/compiler ^0.6.0 (schemaVersion + warnings contract)
+
 ## [0.2.8] - 2026-01-26
 
 ### 📝 Other Changes

package/RELEASE_NOTES_v0.6.0.md

@@ -0,0 +1,39 @@
+# @zenithbuild/language-server v0.6.0
+
+## Summary
+
+- ZEN-DOM-* diagnostics from compiler JSON; severity flips with `strictDomLints`
+- Debounced diagnostics (150ms) + on-save validation; last edit wins
+- Code actions for ZEN-DOM-QUERY, ZEN-DOM-LISTENER, ZEN-DOM-WRAPPER + window/document convenience
+
+## Breaking Changes
+
+None.
+
+## Key Changes
+
+- **Diagnostics:** Surface compiler `warnings` as LSP diagnostics; `strictDomLints` setting (warning → error)
+- **Debounce:** 150ms idle before validation; immediate validation on save
+- **Cancellation:** Only latest validation sends diagnostics
+- **Code actions:** Suppress/ref for ZEN-DOM-QUERY; zenOn template for ZEN-DOM-LISTENER; zenWindow/zenDocument for ZEN-DOM-WRAPPER
+- **Convenience:** "Replace with zenWindow()" / "Replace with zenDocument()" on identifier selection (no diagnostic required)
+- **Completions:** zenMount, zenWindow, zenDocument, zenOn, zenResize, collectRefs, signal, ref; soft suggestions for window/document
+
+## Diagnostics / UX Highlights
+
+| Code | Default | strictDomLints: true |
+|------|---------|---------------------|
+| ZEN-DOM-QUERY | Warning | Error |
+| ZEN-DOM-LISTENER | Warning | Error |
+| ZEN-DOM-WRAPPER | Warning | Error |
+
+## Upgrade Notes
+
+Requires `@zenithbuild/compiler` with JSON `schemaVersion` and `warnings` (v0.6.0+).
+
+## Verification Checklist
+
+- [ ] Type `document.querySelector(` → ZEN-DOM-QUERY warning + quick fixes
+- [ ] Toggle `zenith.strictDomLints` → severity flips to error
+- [ ] Select `window` → "Replace with zenWindow()" code action
+- [ ] Rapid typing does not spawn excessive compiler processes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenithbuild/language-server",
-  "version": "0.5.0-beta.2.20",
+  "version": "0.6.1",
   "description": "Language Server for Zenith Framework",
   "main": "./dist/server.js",
   "types": "./dist/server.d.ts",
@@ -16,7 +16,7 @@
     "release:major": "bun run scripts/release.ts --bump=major"
   },
   "dependencies": {
-    "@zenithbuild/compiler": "^1.3.0",
+    "@zenithbuild/compiler": "^0.6.5",
     "vscode-languageserver": "^9.0.1",
     "vscode-languageserver-textdocument": "^1.0.11"
   },

package/src/code-actions.ts

@@ -5,6 +5,10 @@ import {
 
 export const EVENT_BINDING_DIAGNOSTIC_CODE = 'zenith.event.binding.syntax';
 
+export const ZEN_DOM_QUERY = 'ZEN-DOM-QUERY';
+export const ZEN_DOM_LISTENER = 'ZEN-DOM-LISTENER';
+export const ZEN_DOM_WRAPPER = 'ZEN-DOM-WRAPPER';
+
 export interface EventBindingCodeActionData {
     replacement: string;
     title: string;
@@ -22,6 +26,9 @@ export interface ZenithCodeAction {
 
 interface ZenithTextDocumentLike {
     uri: string;
+    getText(): string;
+    positionAt(offset: number): { line: number; character: number };
+    offsetAt(position: { line: number; character: number }): number;
 }
 
 export function buildEventBindingCodeActions(
@@ -58,3 +65,155 @@ export function buildEventBindingCodeActions(
 
     return actions;
 }
+
+export function buildDomLintCodeActions(
+    document: ZenithTextDocumentLike,
+    diagnostics: ZenithDiagnostic[]
+): ZenithCodeAction[] {
+    const actions: ZenithCodeAction[] = [];
+    const text = document.getText();
+
+    for (const diagnostic of diagnostics) {
+        const code = diagnostic.code;
+        if (code !== ZEN_DOM_QUERY && code !== ZEN_DOM_LISTENER && code !== ZEN_DOM_WRAPPER) {
+            continue;
+        }
+
+        const startOffset = document.offsetAt(diagnostic.range.start);
+        const endOffset = document.offsetAt(diagnostic.range.end);
+        const lineStart = text.lastIndexOf('\n', startOffset) + 1;
+        const lineEnd = text.indexOf('\n', endOffset);
+        const lineEndOffset = lineEnd === -1 ? text.length : lineEnd;
+        const lineContent = text.substring(lineStart, lineEndOffset);
+
+        if (code === ZEN_DOM_QUERY) {
+            const insertPos = { line: diagnostic.range.start.line, character: 0 };
+            actions.push({
+                title: 'Suppress with // zen-allow:dom-query <reason>',
+                kind: 'quickfix',
+                diagnostics: [diagnostic],
+                edit: {
+                    changes: {
+                        [document.uri]: [{
+                            range: { start: insertPos, end: insertPos },
+                            newText: '// zen-allow:dom-query <reason>\n'
+                        }]
+                    }
+                }
+            });
+            actions.push({
+                title: 'Convert to ref() (partial / TODO)',
+                kind: 'quickfix',
+                diagnostics: [diagnostic],
+                edit: {
+                    changes: {
+                        [document.uri]: [{
+                            range: { start: insertPos, end: insertPos },
+                            newText: '// TODO: use ref<T>() + zenMount instead\nconst elRef = ref<HTMLElement>();\n'
+                        }]
+                    }
+                }
+            });
+        } else if (code === ZEN_DOM_LISTENER) {
+            const insertPos = { line: diagnostic.range.start.line, character: 0 };
+            const lineRange = {
+                start: document.positionAt(lineStart),
+                end: document.positionAt(lineEndOffset)
+            };
+            const commentedLine = lineContent.replace(/^(\s*)/, '$1// ');
+            actions.push({
+                title: 'Replace with zenOn template',
+                kind: 'quickfix',
+                diagnostics: [diagnostic],
+                edit: {
+                    changes: {
+                        [document.uri]: [
+                            {
+                                range: { start: insertPos, end: insertPos },
+                                newText: '// zenOn(target, eventName, handler) - register disposer via ctx.cleanup\n// const off = zenOn(doc, \'keydown\', handler); ctx.cleanup(off);\n'
+                            },
+                            {
+                                range: lineRange,
+                                newText: commentedLine
+                            }
+                        ]
+                    }
+                }
+            });
+        } else if (code === ZEN_DOM_WRAPPER) {
+            let newText = lineContent;
+            if (lineContent.includes('window') && !lineContent.includes('zenWindow')) {
+                newText = newText.replace(/\bwindow\b/g, 'zenWindow()');
+            }
+            if (lineContent.includes('document') && !lineContent.includes('zenDocument')) {
+                newText = newText.replace(/\bdocument\b/g, 'zenDocument()');
+            }
+            if (lineContent.includes('globalThis.window')) {
+                newText = newText.replace(/globalThis\.window/g, 'zenWindow()');
+            }
+            if (lineContent.includes('globalThis.document')) {
+                newText = newText.replace(/globalThis\.document/g, 'zenDocument()');
+            }
+            if (newText !== lineContent) {
+                actions.push({
+                    title: 'Replace with zenWindow() / zenDocument()',
+                    kind: 'quickfix',
+                    diagnostics: [diagnostic],
+                    edit: {
+                        changes: {
+                            [document.uri]: [{
+                                range: {
+                                    start: document.positionAt(lineStart),
+                                    end: document.positionAt(lineEndOffset)
+                                },
+                                newText
+                            }]
+                        }
+                    }
+                });
+            }
+        }
+    }
+
+    return actions;
+}
+
+/**
+ * Convenience code actions: Replace window/document with zenWindow()/zenDocument()
+ * even when there is no ZEN-DOM-WRAPPER diagnostic.
+ */
+export function buildWindowDocumentCodeActions(
+    document: ZenithTextDocumentLike,
+    range: ZenithRange
+): ZenithCodeAction[] {
+    const text = document.getText();
+    const startOffset = document.offsetAt(range.start);
+    const endOffset = document.offsetAt(range.end);
+    const selected = text.substring(startOffset, endOffset);
+
+    if (selected === 'window') {
+        return [{
+            title: 'Replace with zenWindow()',
+            kind: 'refactor',
+            diagnostics: [],
+            edit: {
+                changes: {
+                    [document.uri]: [{ range, newText: 'zenWindow()' }]
+                }
+            }
+        }];
+    }
+    if (selected === 'document') {
+        return [{
+            title: 'Replace with zenDocument()',
+            kind: 'refactor',
+            diagnostics: [],
+            edit: {
+                changes: {
+                    [document.uri]: [{ range, newText: 'zenDocument()' }]
+                }
+            }
+        }];
+    }
+    return [];
+}

package/src/diagnostics.ts

@@ -155,7 +155,33 @@ export async function collectDiagnostics(
     try {
         process.env.ZENITH_CACHE = '1';
         const { compile } = await import('@zenithbuild/compiler');
-        await compile(text, filePath);
+        const result = await compile(text, filePath);
+
+        // 2) Surface ZEN-DOM-* warnings from compiler JSON as LSP diagnostics.
+        interface CompilerWarning {
+            code?: string;
+            message?: string;
+            range?: { start?: { line?: number; column?: number }; end?: { line?: number; column?: number } };
+        }
+        const warnings: CompilerWarning[] = (result as { warnings?: CompilerWarning[] }).warnings ?? [];
+        const domLintSeverity = settings.strictDomLints ? DiagnosticSeverity.Error : DiagnosticSeverity.Warning;
+        for (const w of warnings) {
+            const range = w.range;
+            const startLine = (range?.start?.line ?? 1) - 1;
+            const startChar = (range?.start?.column ?? 1) - 1;
+            const endLine = (range?.end?.line ?? range?.start?.line ?? 1) - 1;
+            const endChar = (range?.end?.column ?? range?.start?.column ?? 1);
+            diagnostics.push({
+                severity: domLintSeverity,
+                range: {
+                    start: { line: startLine, character: startChar },
+                    end: { line: endLine, character: endChar }
+                },
+                message: w.message ?? 'DOM lint',
+                source: 'zenith-compiler',
+                code: w.code
+            });
+        }
     } catch (error: any) {
         const message = String(error?.message || 'Unknown compiler error');
         const isContractViolation = message.includes(COMPONENT_SCRIPT_CONTRACT_MESSAGE);

package/src/server.ts

@@ -66,7 +66,7 @@ import {
 } from './router';
 
 import { collectDiagnostics } from './diagnostics';
-import { buildEventBindingCodeActions } from './code-actions';
+import { buildEventBindingCodeActions, buildDomLintCodeActions, buildWindowDocumentCodeActions } from './code-actions';
 import { DEFAULT_SETTINGS, normalizeSettings, ZenithServerSettings } from './settings';
 
 // Create connection and document manager
@@ -78,9 +78,10 @@ let projectGraphs: Map<string, ProjectGraph> = new Map();
 let workspaceFolders: string[] = [];
 let globalSettings: ZenithServerSettings = DEFAULT_SETTINGS;
 
-// Lifecycle hooks with documentation
+// Lifecycle hooks and platform primitives with documentation
 const LIFECYCLE_HOOKS = [
     { name: 'state', doc: 'Declare a reactive state variable', snippet: 'state ${1:name} = ${2:value}', kind: CompletionItemKind.Keyword },
+    { name: 'zenMount', doc: 'Mount callback with ctx.cleanup for disposers', snippet: 'zenMount((ctx) => {\n\t$0\n})', kind: CompletionItemKind.Function },
     { name: 'zenOnMount', doc: 'Called when component is mounted to the DOM', snippet: 'zenOnMount(() => {\n\t$0\n})', kind: CompletionItemKind.Function },
     { name: 'zenOnDestroy', doc: 'Called when component is removed from the DOM', snippet: 'zenOnDestroy(() => {\n\t$0\n})', kind: CompletionItemKind.Function },
     { name: 'zenOnUpdate', doc: 'Called after any state update causes a re-render', snippet: 'zenOnUpdate(() => {\n\t$0\n})', kind: CompletionItemKind.Function },
@@ -88,6 +89,16 @@ const LIFECYCLE_HOOKS = [
     { name: 'useFetch', doc: 'Fetch data with caching and SSG support', snippet: 'useFetch("${1:url}")', kind: CompletionItemKind.Function }
 ];
 
+const PLATFORM_PRIMITIVES = [
+    { name: 'zenWindow', doc: 'SSR-safe window access (returns null when not in browser)', snippet: 'zenWindow()', kind: CompletionItemKind.Function },
+    { name: 'zenDocument', doc: 'SSR-safe document access (returns null when not in browser)', snippet: 'zenDocument()', kind: CompletionItemKind.Function },
+    { name: 'zenOn', doc: 'Event subscription with disposer; register via ctx.cleanup', snippet: 'zenOn(${1:target}, \'${2:event}\', ${3:handler})', kind: CompletionItemKind.Function },
+    { name: 'zenResize', doc: 'Window resize handler; returns disposer for ctx.cleanup', snippet: 'zenResize(({ w, h }) => {\n\t$0\n})', kind: CompletionItemKind.Function },
+    { name: 'collectRefs', doc: 'Collect multiple refs into a deterministic node list', snippet: 'collectRefs(${1:refA}, ${2:refB})', kind: CompletionItemKind.Function },
+    { name: 'signal', doc: 'Create a signal for explicit get/set', snippet: 'signal(${1:0})', kind: CompletionItemKind.Function },
+    { name: 'ref', doc: 'Create a ref for DOM node or value', snippet: 'ref<${1:HTMLElement}>()', kind: CompletionItemKind.Function }
+];
+
 // Common HTML elements
 const HTML_ELEMENTS = [
     { tag: 'div', doc: 'Generic container element' },
@@ -360,6 +371,44 @@ connection.onCompletion((params: TextDocumentPositionParams): CompletionItem[] =
             }
         }
 
+        // Platform primitives (zenWindow, zenDocument, zenOn, zenResize, collectRefs, signal, ref)
+        for (const prim of PLATFORM_PRIMITIVES) {
+            if (!ctx.currentWord || prim.name.toLowerCase().startsWith(ctx.currentWord.toLowerCase())) {
+                completions.push({
+                    label: prim.name,
+                    kind: prim.kind,
+                    detail: 'Zenith Platform',
+                    documentation: { kind: MarkupKind.Markdown, value: prim.doc },
+                    insertText: prim.snippet,
+                    insertTextFormat: InsertTextFormat.Snippet,
+                    sortText: `0_${prim.name}`
+                });
+            }
+        }
+
+        // Soft suggestions: window -> zenWindow, document -> zenDocument (do not block normal JS)
+        const lc = ctx.currentWord.toLowerCase();
+        if (lc === 'window' || lc.startsWith('wind')) {
+            completions.push({
+                label: 'zenWindow',
+                kind: CompletionItemKind.Function,
+                detail: 'Zenith (SSR-safe)',
+                documentation: { kind: MarkupKind.Markdown, value: 'Use zenWindow() instead of window for SSR-safe access.' },
+                insertText: 'zenWindow()',
+                sortText: '0_zenWindow'
+            });
+        }
+        if (lc === 'document' || lc.startsWith('doc')) {
+            completions.push({
+                label: 'zenDocument',
+                kind: CompletionItemKind.Function,
+                detail: 'Zenith (SSR-safe)',
+                documentation: { kind: MarkupKind.Markdown, value: 'Use zenDocument() instead of document for SSR-safe access.' },
+                insertText: 'zenDocument()',
+                sortText: '0_zenDocument'
+            });
+        }
+
         // Router hooks when router is imported
         if (routerEnabled) {
             for (const hook of Object.values(ROUTER_HOOKS)) {
@@ -674,8 +723,10 @@ connection.onCodeAction((params: CodeActionParams): CodeAction[] => {
     if (!document) {
         return [];
     }
-
-    return buildEventBindingCodeActions(document, params.context.diagnostics);
+    const eventActions = buildEventBindingCodeActions(document, params.context.diagnostics);
+    const domLintActions = buildDomLintCodeActions(document, params.context.diagnostics);
+    const windowDocActions = buildWindowDocumentCodeActions(document, params.range);
+    return [...eventActions, ...domLintActions, ...windowDocActions];
 });
 
 connection.onHover((params: TextDocumentPositionParams): Hover | null => {
@@ -822,9 +873,26 @@ connection.onHover((params: TextDocumentPositionParams): Hover | null => {
     return null;
 });
 
-// Validate documents and provide diagnostics
+// Debounce + cancellation for diagnostics (prevents editor lag from rapid typing)
+const DEBOUNCE_MS = 150;
+const validationTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+const validationIds = new Map<string, number>();
+
 documents.onDidChangeContent(change => {
-    validateDocument(change.document);
+    const uri = change.document.uri;
+    const existing = validationTimeouts.get(uri);
+    if (existing) clearTimeout(existing);
+    validationTimeouts.set(
+        uri,
+        setTimeout(() => {
+            validationTimeouts.delete(uri);
+            validateDocument(change.document);
+        }, DEBOUNCE_MS)
+    );
+});
+
+documents.onDidSave(event => {
+    validateDocument(event.document);
 });
 
 documents.onDidOpen(event => {
@@ -832,11 +900,17 @@ documents.onDidOpen(event => {
 });
 
 async function validateDocument(document: TextDocument) {
-    const graph = getProjectGraph(document.uri);
-    const filePath = document.uri.replace('file://', '');
+    const uri = document.uri;
+    const id = (validationIds.get(uri) ?? 0) + 1;
+    validationIds.set(uri, id);
+
+    const graph = getProjectGraph(uri);
+    const filePath = uri.replace('file://', '');
     const projectRoot = detectProjectRoot(path.dirname(filePath), workspaceFolders);
     const diagnostics = await collectDiagnostics(document, graph, globalSettings, projectRoot);
-    connection.sendDiagnostics({ uri: document.uri, diagnostics });
+
+    if (validationIds.get(uri) !== id) return;
+    connection.sendDiagnostics({ uri, diagnostics });
 }
 
 connection.onDidChangeConfiguration((change) => {

package/src/settings.ts

@@ -2,14 +2,17 @@ export type ComponentScriptsMode = 'forbid' | 'allow';
 
 export interface ZenithServerSettings {
     componentScripts: ComponentScriptsMode;
+    strictDomLints: boolean;
 }
 
 export const DEFAULT_SETTINGS: ZenithServerSettings = Object.freeze({
-    componentScripts: 'forbid'
+    componentScripts: 'forbid',
+    strictDomLints: false
 });
 
 export function normalizeSettings(input: unknown): ZenithServerSettings {
-    const maybe = (input || {}) as { componentScripts?: unknown };
+    const maybe = (input || {}) as { componentScripts?: unknown; strictDomLints?: unknown };
     const mode = maybe.componentScripts === 'allow' ? 'allow' : 'forbid';
-    return { componentScripts: mode };
+    const strictDomLints = maybe.strictDomLints === true;
+    return { componentScripts: mode, strictDomLints };
 }

package/test/diagnostics.spec.ts

@@ -1,9 +1,9 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 
-import { collectContractDiagnostics, CONTRACT_MESSAGES } from '../src/diagnostics';
+import { collectDiagnostics, collectContractDiagnostics, CONTRACT_MESSAGES } from '../src/diagnostics';
 import { buildEventBindingCodeActions } from '../src/code-actions';
-import { DEFAULT_SETTINGS } from '../src/settings';
+import { DEFAULT_SETTINGS, normalizeSettings } from '../src/settings';
 
 const PROJECT_ROOT = '/tmp/zenith-site';
 
@@ -99,3 +99,22 @@ test('css import contract allows local precompiled css with suffixes', () => {
     assert.ok(!messages.includes(CONTRACT_MESSAGES.cssBareImport));
     assert.ok(!messages.includes(CONTRACT_MESSAGES.cssEscape));
 });
+
+test('ZEN-DOM-QUERY diagnostic appears for querySelector and severity maps with strictDomLints', async () => {
+    const document = doc(
+        'file:///tmp/zenith-site/src/pages/index.zen',
+        '<script lang="ts">\nconst el = document.querySelector(".foo");\n</script>\n<div class="foo">hi</div>'
+    );
+
+    const settingsDefault = normalizeSettings({ strictDomLints: false });
+    const diagnosticsDefault = await collectDiagnostics(document, null, settingsDefault, PROJECT_ROOT);
+    const queryDefault = diagnosticsDefault.filter((d) => d.code === 'ZEN-DOM-QUERY');
+    assert.ok(queryDefault.length >= 1, `expected ZEN-DOM-QUERY diagnostic, got: ${JSON.stringify(diagnosticsDefault.map((d) => d.code))}`);
+    assert.equal(queryDefault[0]?.severity, 2, 'ZEN-DOM-QUERY should be Warning (2) when strictDomLints=false');
+
+    const settingsStrict = normalizeSettings({ strictDomLints: true });
+    const diagnosticsStrict = await collectDiagnostics(document, null, settingsStrict, PROJECT_ROOT);
+    const queryStrict = diagnosticsStrict.filter((d) => d.code === 'ZEN-DOM-QUERY');
+    assert.ok(queryStrict.length >= 1, `expected ZEN-DOM-QUERY diagnostic in strict mode, got: ${JSON.stringify(diagnosticsStrict.map((d) => d.code))}`);
+    assert.equal(queryStrict[0]?.severity, 1, 'ZEN-DOM-QUERY should be Error (1) when strictDomLints=true');
+});