@staticbolt/lsp 1.0.0-beta.30 → 1.0.0-beta.32

package/src/index.ts

@@ -1,15 +1,45 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
 import { format, stripVTControlCharacters } from "node:util";
-import * as vs from "vscode-languageserver/node";
+import { createConnection, createServer, createTypeScriptProject, loadTsdkByPath } from "@volar/language-server/node.js";
 
-import { startServer } from "./html-server.ts";
-import { getNodeFileFS } from "./utils/node-fs.ts";
-import { formatError } from "./utils/runner.ts";
+import { useModuleScripts } from "./helpers/inferred-project.ts";
+import { createLanguagePlugin } from "./language-plugin.ts";
+import { findProjectRoots, Projects } from "./projects.ts";
+import { createStaticboltService } from "./services/staticbolt-service.ts";
+import { createSyntaxTokensService } from "./services/syntax-tokens-service.ts";
+import { createTypeScriptServices } from "./services/typescript-service.ts";
 
-import type { RuntimeEnvironment } from "./html-server.ts";
-import type { Connection, Disposable } from "vscode-languageserver/node";
+import type { InitializeParams, WorkspaceFolder } from "@volar/language-server/node.js";
 
-// Create a connection for the server.
-const connection: Connection = vs.createConnection();
+/** What an editor may pass as `initializationOptions`. */
+interface InitializationOptions {
+  /** Where TypeScript is. */
+  typescript?: {
+    /** The directory holding `typescript.js`, `node_modules/typescript/lib` say. */
+    tsdk?: string;
+  };
+
+  /** Whether the editor maps the scoped token types to grammar scopes, so the keywords are sent as those. */
+  scopedTokens?: boolean;
+}
+
+/** The initialization options, with anything that is not an object read as none. */
+function initializationOptionsOf(parameters: InitializeParams): InitializationOptions {
+  const options: unknown = parameters.initializationOptions;
+
+  if (typeof options !== "object" || options === null) {
+    return {};
+  }
+
+  return options;
+}
+
+/** The LSP connection to the editor, over stdio. */
+const connection = createConnection();
+
+/** Volar's server on top of the connection: documents, projects and the language features. */
+const server = createServer(connection);
 
 /**
  * `RemoteConsole` takes a single string, but the shared logger calls `console` with several arguments and colours them with
@@ -17,7 +47,11 @@ const connection: Connection = vs.createConnection();
  * so format the arguments the way `console` would, then strip the escapes.
  */
 function forward(write: (message: string) => void) {
-  return (...messages: unknown[]) => write(stripVTControlCharacters(format(...messages)));
+  return (...messages: unknown[]) => {
+    const text = stripVTControlCharacters(format(...messages));
+
+    write(text);
+  };
 }
 
 console.log = forward(connection.console.log.bind(connection.console));
@@ -26,24 +60,123 @@ console.warn = forward(connection.console.warn.bind(connection.console));
 console.error = forward(connection.console.error.bind(connection.console));
 
 process.on("unhandledRejection", (error: unknown) => {
-  connection.console.error(formatError(`Unhandled exception`, error));
+  console.error("[staticbolt] unhandled rejection:", error);
 });
 
-const runtime: RuntimeEnvironment = {
-  timer: {
-    setImmediate(callback: (...arguments_: unknown[]) => void, ...arguments_: unknown[]): Disposable {
-      const handle = setImmediate(callback, ...arguments_);
-      return { dispose: () => clearImmediate(handle) };
-    },
+/** Whether a directory holds TypeScript with its API, which the native builds do not ship. */
+function hasTypeScriptApi(tsdk: string): boolean {
+  return existsSync(path.join(tsdk, "typescript.js"));
+}
+
+/**
+ * The directory of the TypeScript to run: the editor's choice from the initialization options, the `--tsdk` argument, or the
+ * nearest `typescript` package with an API installed above the working directory.
+ */
+function findTsdk(parameters: InitializeParams): string | undefined {
+  const options = initializationOptionsOf(parameters);
+  if (options.typescript?.tsdk) {
+    return options.typescript.tsdk;
+  }
+
+  const argument = process.argv.find(value => value.startsWith("--tsdk="));
+  if (argument) {
+    return argument.slice("--tsdk=".length);
+  }
+
+  let directory = process.cwd();
 
-    setTimeout(callback: (...arguments_: unknown[]) => void, ms: number, ...arguments_: unknown[]): Disposable {
-      const handle = setTimeout(callback, ms, ...arguments_);
-      return { dispose: () => clearTimeout(handle) };
-    },
-  },
+  while (true) {
+    const tsdk = path.join(directory, "node_modules", "typescript", "lib");
+    if (hasTypeScriptApi(tsdk)) {
+      return tsdk;
+    }
 
-  fileFs: getNodeFileFS(),
-};
+    const parent = path.dirname(directory);
+    if (parent === directory) {
+      return undefined;
+    }
 
-connection.console.log("[staticbolt] starting server");
-startServer(connection, runtime);
+    directory = parent;
+  }
+}
+
+/** The workspace folders, or the root uri of an editor that has no folders. */
+function foldersOf(parameters: InitializeParams): WorkspaceFolder[] {
+  if (parameters.workspaceFolders) {
+    return parameters.workspaceFolders;
+  }
+
+  if (parameters.rootUri) {
+    return [{ name: "", uri: parameters.rootUri }];
+  }
+
+  return [];
+}
+
+/** The staticbolt projects of the workspace, from initialization on. */
+let projects: Projects | undefined;
+
+connection.listen();
+
+connection.onInitialize(async parameters => {
+  const tsdk = findTsdk(parameters);
+  if (tsdk === undefined || !hasTypeScriptApi(tsdk)) {
+    throw new Error(
+      `[staticbolt] no TypeScript with an API ${tsdk ? `at ${tsdk}` : "found"}; point typescript.tsdk or --tsdk at one, 6.x say`
+    );
+  }
+
+  const { typescript, diagnosticMessages } = loadTsdkByPath(tsdk, parameters.locale);
+  console.log(`[staticbolt] TypeScript ${typescript.version} from ${tsdk}`);
+
+  // Every project's plugins are asked what they contribute before the first document is served
+  let isInitialized = false;
+  const workspace = new Projects(connection.console, () => {
+    if (!isInitialized) return;
+
+    server.project.reload();
+  });
+
+  projects = workspace;
+
+  const roots = findProjectRoots(foldersOf(parameters));
+  console.log(`[staticbolt] discovered projects:\n${roots.map(root => `  - ${root}`).join("\n")}`);
+  await Promise.all(roots.map(root => workspace.get(root)));
+  isInitialized = true;
+
+  const languagePlugin = createLanguagePlugin(typescript, workspace);
+  const project = createTypeScriptProject(typescript, diagnosticMessages, ({ configFileName, projectHost }) => {
+    if (configFileName === undefined) {
+      useModuleScripts(typescript, projectHost);
+    }
+
+    return { languagePlugins: [languagePlugin] };
+  });
+  const services = [
+    createStaticboltService(),
+    createSyntaxTokensService(typescript, initializationOptionsOf(parameters).scopedTokens === true),
+    ...createTypeScriptServices(typescript),
+  ];
+
+  return server.initialize(parameters, project, services);
+});
+
+/** A TypeScript config, or one of those a config extends. */
+const TS_CONFIG = /\/(?:tsconfig|jsconfig)[^/]*\.json$/;
+
+connection.onInitialized(() => {
+  server.initialized();
+
+  // The editor reports the changes; Volar follows the source files itself, a config is reloaded whole since it may be extended
+  void server.fileWatcher.watchFiles(["**/*.{ts,mts,cts,js,mjs,cjs}", "**/{tsconfig,jsconfig}*.json"]);
+
+  server.fileWatcher.onDidChangeWatchedFiles(({ changes }) => {
+    if (changes.every(change => !TS_CONFIG.test(change.uri))) return;
+
+    server.project.reload();
+  });
+});
+connection.onShutdown(async () => {
+  await projects?.dispose();
+  server.shutdown();
+});

package/src/language-plugin.ts

@@ -0,0 +1,67 @@
+import path from "node:path";
+import { forEachEmbeddedCode } from "@volar/language-core";
+
+import { embeddedFileName, StaticboltCode } from "./virtual-code.ts";
+
+import type { Projects } from "./projects.ts";
+import type { LanguagePlugin } from "@volar/language-core";
+import type * as ts from "typescript";
+import type { URI } from "vscode-uri";
+
+/** The language ids by file extension. */
+const LANGUAGE_IDS: Record<string, string | undefined> = {
+  ".html": "html",
+  ".md": "markdown",
+};
+
+/**
+ * Tells Volar what an HTML or markdown document is: the document itself, and a TypeScript file per plugin language, named after
+ * the document and the language and served by the project's TypeScript next to it.
+ */
+export function createLanguagePlugin(typescript: typeof ts, projects: Projects): LanguagePlugin<URI, StaticboltCode> {
+  return {
+    getLanguageId(uri) {
+      return LANGUAGE_IDS[path.extname(uri.path).toLowerCase()];
+    },
+
+    createVirtualCode(uri, languageId, snapshot) {
+      if (uri.scheme !== "file") {
+        return;
+      }
+
+      if (languageId !== "html" && languageId !== "markdown") {
+        return;
+      }
+
+      return new StaticboltCode(typescript, uri, languageId, snapshot, projects.of(uri.toString()));
+    },
+
+    typescript: {
+      extraFileExtensions: [
+        { extension: "html", isMixedContent: true, scriptKind: typescript.ScriptKind.Deferred },
+        { extension: "md", isMixedContent: true, scriptKind: typescript.ScriptKind.Deferred },
+      ],
+
+      getServiceScript() {
+        return;
+      },
+
+      getExtraServiceScripts(fileName, root) {
+        const scripts = [];
+
+        for (const code of forEachEmbeddedCode(root)) {
+          if (code.languageId !== "typescript") continue;
+
+          scripts.push({
+            fileName: embeddedFileName(fileName, code.id),
+            code,
+            extension: ".ts",
+            scriptKind: typescript.ScriptKind.TS,
+          });
+        }
+
+        return scripts;
+      },
+    },
+  };
+}

package/src/projects.ts

@@ -0,0 +1,305 @@
+import { existsSync, globSync, watch } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Resolver } from "@staticbolt/core";
+import * as vscodeUri from "vscode-uri";
+
+import type { FSWatcher } from "node:fs";
+import type { AppConfig, EmbeddedLanguage, Plugin } from "@staticbolt/core";
+import type { HTMLDataV1, IAttributeData, MarkupContent } from "vscode-html-languageservice";
+import type { WorkspaceFolder } from "vscode-languageserver-protocol";
+
+/** Where the projects log. */
+type RemoteConsole = Pick<Console, "log" | "error">;
+
+/** In order, so the first one that exists wins. */
+const CONFIG_NAMES = [".staticbolt.ts", ".staticbolt.js"];
+
+/** A save may come as several writes; the config is loaded once they have stopped. */
+const RELOAD_DELAY_MS = 150;
+
+/** A plugin's document check, with the plugin's name to label what it reports. */
+export interface Validator {
+  /** The plugin's name. */
+  name: string;
+
+  /** The plugin's `lspValidate` hook. */
+  validate: NonNullable<Plugin["lspValidate"]>;
+
+  /** Whether the hook threw already, so it is logged once; the next config load starts over. */
+  hasFailed: boolean;
+}
+
+/** The directory of the nearest config file above a directory, which is the project it belongs to. */
+function findProjectRoot(directory: string): string | undefined {
+  while (true) {
+    const hasConfig = CONFIG_NAMES.some(name => existsSync(path.join(directory, name)));
+    if (hasConfig) {
+      return directory;
+    }
+
+    const parent = path.dirname(directory);
+    if (parent === directory) return;
+
+    directory = parent;
+  }
+}
+
+/** A resolver for a root that does not log missing files, with the config's aliases on top of the tsconfig's. */
+function createResolver(root: string, aliases?: Record<string, string>): Resolver {
+  return new Resolver(root, false, aliases, false);
+}
+
+/** Every project under the workspace folders, for the startup log. */
+export function findProjectRoots(folders: WorkspaceFolder[]): string[] {
+  return folders.flatMap(folder => {
+    const cwd = vscodeUri.URI.parse(folder.uri).fsPath;
+    const configs = globSync(`**/{${CONFIG_NAMES.join(",")}}`, { cwd, exclude: ["**/node_modules/**", "**/.git/**"] });
+
+    return configs.map(config => path.join(cwd, path.dirname(config)));
+  });
+}
+
+/**
+ * A staticbolt project as the server sees it: its config, kept current while the config file changes, and what its plugins
+ * contribute to the editor.
+ */
+export class Project {
+  /** The directory holding the config file. */
+  readonly root: string;
+
+  /** The last config that loaded, or nothing when none did yet. */
+  config: AppConfig | undefined;
+
+  /** The tags and attributes the plugins contribute to HTML. A new array on every load, so consumers may cache on its identity. */
+  htmlData: HTMLDataV1[] = [];
+
+  /** The languages the plugins embed in HTML. */
+  embeddedLanguages: EmbeddedLanguage[] = [];
+
+  /** The plugins that check documents, by name. */
+  validators: Validator[] = [];
+
+  /** Resolves paths the way the project's build does: its tsconfig paths and config aliases. New on every load. */
+  resolver: Resolver;
+
+  /** Where to log. */
+  readonly #console: RemoteConsole;
+
+  /** Follows the root directory for saves of the config file. */
+  #watcher: FSWatcher | undefined;
+
+  /** The reload waiting for the save to finish. */
+  #reload: NodeJS.Timeout | undefined;
+
+  /** Told whenever the config loaded. */
+  readonly #onLoad: () => void;
+
+  /** Nothing is loaded until `start` is called. */
+  constructor(root: string, console: RemoteConsole, onLoad: () => void) {
+    this.root = root;
+    this.resolver = createResolver(root);
+    this.#console = console;
+    this.#onLoad = onLoad;
+  }
+
+  /** Loads the config and starts following the config file. */
+  async start(): Promise<void> {
+    // The directory rather than the file: editors save through a temporary file and a rename, which a watch on the file misses
+    this.#watcher = watch(this.root, { persistent: false }, (_event, filename) => {
+      if (typeof filename !== "string") return;
+      if (!CONFIG_NAMES.includes(filename)) return;
+      this.#scheduleReload();
+    });
+
+    this.#watcher.on("error", error => this.#console.error(`[staticbolt] watching ${this.root}: ${error.message}`));
+
+    await this.#load();
+  }
+
+  /** Stops following the config file. */
+  dispose(): void {
+    clearTimeout(this.#reload);
+    this.#watcher?.close();
+  }
+
+  /** Loads the config again once the save has stopped writing. */
+  #scheduleReload(): void {
+    clearTimeout(this.#reload);
+    this.#reload = setTimeout(() => void this.#load(), RELOAD_DELAY_MS);
+  }
+
+  /** Loads the config file and takes what its plugins contribute; a failure is logged and leaves the last config in place. */
+  async #load(): Promise<void> {
+    const configPath = CONFIG_NAMES.map(name => path.join(this.root, name)).find(candidate => existsSync(candidate));
+
+    if (!configPath) {
+      this.#console.error(`[staticbolt] the config file of ${this.root} is gone`);
+      return;
+    }
+
+    try {
+      // A fresh URL each time, since a module is only ever evaluated once
+      const module = (await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`)) as { default?: AppConfig };
+      if (!module.default) {
+        throw new Error("it has no default export, use `export default { … }`");
+      }
+
+      await this.#collectPluginData(module.default);
+      this.config = module.default;
+      this.resolver = createResolver(this.root, module.default.aliases);
+      this.#onLoad();
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+
+      this.#console.error(`[staticbolt] failed to load ${configPath}: ${reason}`);
+    }
+  }
+
+  /** Asks every plugin of the config what it contributes to the editor. */
+  async #collectPluginData(config: AppConfig): Promise<void> {
+    const plugins = (config.plugins ?? []).flat();
+    const embeddedLanguages: EmbeddedLanguage[] = [];
+    const validators: Validator[] = [];
+    const htmlData: HTMLDataV1[] = [];
+
+    for (const plugin of plugins) {
+      embeddedLanguages.push(...(plugin.lspEmbeddedLanguages?.() ?? []));
+
+      if (plugin.lspValidate) {
+        validators.push({ name: plugin.name, validate: plugin.lspValidate, hasFailed: false });
+      }
+
+      const data = await plugin.lspHtmlData?.();
+      if (data) {
+        htmlData.push(creditPlugin(data, plugin.name));
+      }
+    }
+
+    this.embeddedLanguages = embeddedLanguages;
+    this.validators = validators;
+    this.htmlData = htmlData;
+  }
+}
+
+/** The projects the server has been asked about, each started on first request. */
+export class Projects {
+  /** Where to log. */
+  readonly #console: RemoteConsole;
+
+  /** By root, from the moment a project was asked for. */
+  readonly #starting = new Map<string, Promise<Project>>();
+
+  /** By root, once the project's config loaded. */
+  readonly #loaded = new Map<string, Project>();
+
+  /** The project root of every directory a document was served from. */
+  readonly #roots = new Map<string, string>();
+
+  /** Told whenever any project's config loaded. */
+  readonly #onLoad: () => void;
+
+  /** Starts with no projects; each is started the first time `get` asks for it. */
+  constructor(console: RemoteConsole, onLoad: () => void) {
+    this.#console = console;
+    this.#onLoad = onLoad;
+  }
+
+  /**
+   * The project at a root, or nothing while its config cannot be loaded. The project keeps following its config file either way,
+   * so a fixed config loads on its own.
+   */
+  async get(root: string): Promise<Project | undefined> {
+    let project = this.#starting.get(root);
+
+    if (!project) {
+      project = this.#start(root);
+      this.#starting.set(root, project);
+    }
+
+    const started = await project;
+
+    return started.config ? started : undefined;
+  }
+
+  /**
+   * The project a document belongs to, if it has loaded already. One that has not is started, and the document is served again
+   * once it loads; a document outside any project gets nothing.
+   */
+  of(documentUri: string): Project | undefined {
+    const directory = path.dirname(vscodeUri.URI.parse(documentUri).fsPath);
+    const root = this.#roots.get(directory) ?? findProjectRoot(directory);
+    if (root === undefined) {
+      return undefined;
+    }
+
+    this.#roots.set(directory, root);
+
+    const loaded = this.#loaded.get(root);
+    if (!loaded) {
+      void this.get(root);
+    }
+
+    return loaded;
+  }
+
+  /** Stops following every project. */
+  async dispose(): Promise<void> {
+    const projects = await Promise.all(this.#starting.values());
+
+    for (const project of projects) {
+      project.dispose();
+    }
+
+    this.#starting.clear();
+    this.#loaded.clear();
+    this.#roots.clear();
+  }
+
+  /** A project at a root, counted as loaded from the first time its config loads. */
+  async #start(root: string): Promise<Project> {
+    const project = new Project(root, this.#console, () => {
+      this.#loaded.set(root, project);
+      this.#onLoad();
+    });
+
+    await project.start();
+
+    return project;
+  }
+}
+
+/** The data with every description saying which plugin it comes from. */
+function creditPlugin(htmlData: HTMLDataV1, pluginName: string): HTMLDataV1 {
+  const credit = `_Provided by **staticbolt** \`${pluginName}\` plugin._`;
+
+  const withCredit = (description: string | MarkupContent | undefined): string | MarkupContent => {
+    if (!description) {
+      return credit;
+    }
+
+    const text = typeof description === "string" ? description : description.value;
+    if (text.includes(credit)) {
+      return description;
+    }
+
+    const credited = `${text}\n\n${credit}`;
+    if (typeof description === "string") {
+      return credited;
+    }
+
+    return { ...description, value: credited };
+  };
+
+  const creditAttributes = (attributes: IAttributeData[]): IAttributeData[] => {
+    return attributes.map(attribute => ({ ...attribute, description: withCredit(attribute.description) }));
+  };
+
+  const tags = htmlData.tags?.map(tag => {
+    return { ...tag, description: withCredit(tag.description), attributes: creditAttributes(tag.attributes) };
+  });
+
+  const globalAttributes = htmlData.globalAttributes ? creditAttributes(htmlData.globalAttributes) : undefined;
+
+  return { ...htmlData, tags, globalAttributes };
+}