@statorjs/language-server 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@statorjs/language-server",
+  "version": "0.1.0",
+  "description": "Volar-based language server for .stator files.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statorjs/stator.git",
+    "directory": "packages/language-server"
+  },
+  "homepage": "https://github.com/statorjs/stator#readme",
+  "bin": {
+    "stator-language-server": "./bin/stator-language-server.js"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./src/language-plugin.ts",
+    "./server": "./dist/server.cjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@volar/language-core": "~2.4.0",
+    "@volar/language-server": "~2.4.0",
+    "@volar/typescript": "~2.4.0",
+    "volar-service-css": "0.0.71",
+    "volar-service-typescript": "0.0.71",
+    "vscode-css-languageservice": "^6.3.0",
+    "vscode-uri": "^3.0.8",
+    "@statorjs/stator": "1.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=cjs --outfile=dist/server.cjs --external:typescript --external:vscode-css-languageservice"
+  }
+}

package/src/diagnostics.ts

@@ -0,0 +1,75 @@
+/**
+ * Stator semantic diagnostics: run the REAL compiler over the `.stator`
+ * source and surface its `CompileError`s as editor squiggles — so the editor
+ * and the Vite build can never disagree about what's valid. (The TS and CSS
+ * services cover their regions; this covers Stator's own rules: directive
+ * misuse, client-component name matching, frontmatter capabilities, spread,
+ * malformed templates.)
+ *
+ * The service runs against the ROOT virtual code (languageId `stator`, full
+ * source text, identity-mapped back to the file — see language-plugin.ts),
+ * so positions pass through 1:1.
+ */
+
+import { CompileError, compile } from '@statorjs/stator/compiler'
+import type { Diagnostic, LanguageServicePlugin } from '@volar/language-server'
+import { URI } from 'vscode-uri'
+
+const ROUTE_PATH_RE = /[\\/]routes[\\/].*\.stator$/
+
+/** Pure core, unit-tested directly: compile and translate the failure. */
+export function statorDiagnostics(text: string, filePath: string): Diagnostic[] {
+  const kind = ROUTE_PATH_RE.test(filePath) ? 'route' : 'component'
+  try {
+    compile(text, { id: filePath, kind })
+    return []
+  } catch (err) {
+    if (err instanceof CompileError) {
+      // CompileError carries a 1-based line/column into the original source;
+      // LSP positions are 0-based. Errors without a location anchor at 0:0.
+      const line = (err.loc?.line ?? 1) - 1
+      const character = (err.loc?.column ?? 1) - 1
+      return [
+        {
+          range: { start: { line, character }, end: { line, character: character + 1 } },
+          message: err.message,
+          severity: 1, // Error
+          source: 'stator',
+        },
+      ]
+    }
+    // Non-CompileError throws are compiler bugs — still show them rather
+    // than swallowing, anchored at the top of the file.
+    return [
+      {
+        range: { start: { line: 0, character: 0 }, end: { line: 0, character: 1 } },
+        message: `stator: internal compiler error — ${String(err)}`,
+        severity: 1,
+        source: 'stator',
+      },
+    ]
+  }
+}
+
+export function createStatorDiagnosticsService(): LanguageServicePlugin {
+  return {
+    name: 'stator-diagnostics',
+    capabilities: {
+      diagnosticProvider: {
+        interFileDependencies: false,
+        workspaceDiagnostics: false,
+      },
+    },
+    create(context) {
+      return {
+        provideDiagnostics(document) {
+          if (document.languageId !== 'stator') return
+          const uri = URI.parse(document.uri)
+          const decoded = context.decodeEmbeddedDocumentUri(uri)
+          const path = decoded ? decoded[0].fsPath : uri.fsPath
+          return statorDiagnostics(document.getText(), path)
+        },
+      }
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * The `.stator` language server — a standard Volar node server.
+ *
+ * Editor-agnostic: any LSP client launches this over stdio (the VSCode extension
+ * is one client; nvim/emacs/helix/zed configure the same binary). It federates
+ * the TypeScript and CSS language services over the virtual code produced by the
+ * Stator language plugin.
+ */
+
+import {
+  createConnection,
+  createServer,
+  createTypeScriptProject,
+  loadTsdkByPath,
+} from '@volar/language-server/node'
+import { create as createCssService } from 'volar-service-css'
+import { create as createTypeScriptServices } from 'volar-service-typescript'
+import { createStatorDiagnosticsService } from './diagnostics.ts'
+import { statorLanguagePlugin } from './language-plugin.ts'
+
+const connection = createConnection()
+const server = createServer(connection)
+
+connection.onInitialize((params) => {
+  const options = params.initializationOptions as { typescript?: { tsdk?: string } } | undefined
+  const tsdkPath = options?.typescript?.tsdk
+  if (!tsdkPath) {
+    throw new Error(
+      'stator language server: initializationOptions.typescript.tsdk (path to the TS lib dir) is required.',
+    )
+  }
+  const tsdk = loadTsdkByPath(tsdkPath, params.locale)
+  return server.initialize(
+    params,
+    createTypeScriptProject(tsdk.typescript, tsdk.diagnosticMessages, () => ({
+      languagePlugins: [statorLanguagePlugin],
+    })),
+    [
+      ...createTypeScriptServices(tsdk.typescript),
+      createCssService(),
+      createStatorDiagnosticsService(),
+    ],
+  )
+})
+
+connection.onInitialized(() => server.initialized())
+connection.listen()

package/src/language-plugin.ts

@@ -0,0 +1,136 @@
+/**
+ * The Volar language plugin for `.stator` files. It adapts the compiler's
+ * framework-neutral virtual-code emit (`toVirtualCode`) into Volar's virtual
+ * codes + `CodeMapping`s, so Volar can federate the TypeScript and CSS language
+ * services over the right regions with correct source mapping.
+ *
+ * All `.stator` syntax knowledge lives in the compiler; this file is purely the
+ * Volar adapter (mapping-shape translation + which embedded code is the TS
+ * script). Keeping the split means the language server and the runtime compiler
+ * never disagree about the file.
+ */
+
+import { toVirtualCode, type VirtualMapping } from '@statorjs/stator/compiler'
+import type { CodeMapping, LanguagePlugin, VirtualCode } from '@volar/language-core'
+import { forEachEmbeddedCode } from '@volar/language-core'
+// Activates the `typescript` field on LanguagePlugin (module augmentation).
+import type {} from '@volar/typescript'
+import type { IScriptSnapshot } from 'typescript'
+import type { URI } from 'vscode-uri'
+
+const TSX_SCRIPT_KIND = 4 // ts.ScriptKind.TSX
+const DEFERRED_SCRIPT_KIND = 7 // ts.ScriptKind.Deferred
+
+/** Feature flags for a fully-serviced region. */
+const FULL: CodeMapping['data'] = {
+  verification: true,
+  completion: true,
+  semantic: true,
+  navigation: true,
+  structure: true,
+  format: false,
+}
+
+export const statorLanguagePlugin: LanguagePlugin<URI, StatorVirtualCode> = {
+  getLanguageId(uri) {
+    if (uri.path.endsWith('.stator')) return 'stator'
+    return undefined
+  },
+  createVirtualCode(_uri, languageId, snapshot) {
+    if (languageId !== 'stator') return undefined
+    return new StatorVirtualCode(snapshot)
+  },
+  updateVirtualCode(_uri, code, snapshot) {
+    code.update(snapshot)
+    return code
+  },
+  typescript: {
+    extraFileExtensions: [
+      {
+        extension: 'stator',
+        isMixedContent: true,
+        scriptKind: DEFERRED_SCRIPT_KIND,
+      },
+    ],
+    getServiceScript(root) {
+      for (const code of forEachEmbeddedCode(root)) {
+        if (code.id === 'tsx') {
+          return { code, extension: '.tsx', scriptKind: TSX_SCRIPT_KIND }
+        }
+      }
+      return undefined
+    },
+  },
+}
+
+export class StatorVirtualCode implements VirtualCode {
+  id = 'root'
+  languageId = 'stator'
+  snapshot: IScriptSnapshot
+  // TS/CSS features are served by the embedded codes' mappings. The root
+  // itself carries one identity mapping with `verification` only, which makes
+  // it visible to the stator diagnostics service (full source, positions
+  // passing through 1:1) without inviting TS/CSS features onto it.
+  mappings: CodeMapping[] = []
+  embeddedCodes: VirtualCode[] = []
+
+  constructor(snapshot: IScriptSnapshot) {
+    this.snapshot = snapshot
+    this.update(snapshot)
+  }
+
+  update(snapshot: IScriptSnapshot): void {
+    this.snapshot = snapshot
+    const text = snapshot.getText(0, snapshot.getLength())
+    this.mappings = [
+      {
+        sourceOffsets: [0],
+        generatedOffsets: [0],
+        lengths: [text.length],
+        data: {
+          verification: true,
+          completion: false,
+          semantic: false,
+          navigation: false,
+          structure: false,
+          format: false,
+        },
+      },
+    ]
+    const vc = toVirtualCode(text)
+    this.embeddedCodes = [
+      embed('tsx', 'typescriptreact', vc.tsx.code, vc.tsx.mappings),
+      ...vc.styles.map((s, i) => embed(`css_${i}`, 'css', s.code, s.mappings)),
+    ]
+  }
+}
+
+function embed(
+  id: string,
+  languageId: string,
+  code: string,
+  mappings: VirtualMapping[],
+): VirtualCode {
+  return {
+    id,
+    languageId,
+    snapshot: stringSnapshot(code),
+    mappings: [
+      {
+        sourceOffsets: mappings.map((m) => m.sourceOffset),
+        generatedOffsets: mappings.map((m) => m.generatedOffset),
+        lengths: mappings.map((m) => m.length),
+        data: FULL,
+      },
+    ],
+    embeddedCodes: [],
+  }
+}
+
+function stringSnapshot(text: string): IScriptSnapshot {
+  return {
+    getText: (start, end) => text.slice(start, end),
+    getLength: () => text.length,
+    getChangeRange: () => undefined,
+  }
+}