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

package/src/services/staticbolt-service.ts

@@ -0,0 +1,257 @@
+import path from "node:path";
+import vscodeHtml from "vscode-html-languageservice";
+import { CompletionItemKind, SemanticTokenTypes, TextEdit } from "vscode-languageserver-protocol";
+import * as vscodeUri from "vscode-uri";
+
+import { createMergedHtmlDataProvider } from "../helpers/merge-html-data.ts";
+import { isInRegions } from "../helpers/regions.ts";
+import { validateDocument } from "../helpers/validation.ts";
+import { getDocumentContext } from "../helpers/document-context.ts";
+import { StaticboltCode } from "../virtual-code.ts";
+
+import type { Project } from "../projects.ts";
+import type { LanguageServiceContext, LanguageServicePlugin, SemanticToken } from "@volar/language-service";
+import type { FileStat, FileSystemProvider, HTMLDataV1, LanguageService } from "vscode-html-languageservice";
+import type { CompletionItem, Position } from "vscode-languageserver-protocol";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+
+/** The id the merged data provider registers under with the language service. */
+const DATA_PROVIDER_ID = "staticbolt";
+
+/** The cursor inside a `src` or `href` value before any slash, capturing what is typed of its first segment. */
+const PATH_VALUE_START = /(?:src|href)\s*=\s*["']([^"'/\s]*)$/;
+
+/** Has the editor open the completions again, right after an item is taken. */
+const SUGGEST = { title: "Suggest", command: "editor.action.triggerSuggest" };
+
+/** A document of a loaded project, with the HTML language service that knows the project's tags and attributes. */
+interface Found {
+  /** The document's root code, holding its HTML and regions. */
+  code: StaticboltCode;
+
+  /** The project the document belongs to. */
+  project: Project;
+
+  /** The project's HTML language service. */
+  languageService: LanguageService;
+}
+
+/**
+ * What the plugins add to HTML: their tags and attributes for completion and hover, path completion that knows the project's
+ * aliases, links resolved the way the build resolves them, and the problems the plugins find. The editor's own HTML support
+ * covers the standard elements, and stays out of the regions the plugins embed.
+ */
+export function createStaticboltService(): LanguageServicePlugin {
+  return {
+    name: "staticbolt",
+
+    capabilities: {
+      completionProvider: { triggerCharacters: [".", ":", "<", '"', "=", "/"] },
+      hoverProvider: true,
+      documentLinkProvider: {},
+      diagnosticProvider: { interFileDependencies: false, workspaceDiagnostics: false },
+      semanticTokensProvider: { legend: { tokenTypes: [SemanticTokenTypes.operator], tokenModifiers: [] } },
+    },
+
+    create(context) {
+      // One language service per project's data, which is a new array whenever its config is loaded again
+      const languageServices = new WeakMap<HTMLDataV1[], LanguageService>();
+
+      /** The HTML language service that knows a project's tags and attributes. */
+      function languageServiceOf(project: Project): LanguageService {
+        let languageService = languageServices.get(project.htmlData);
+
+        if (!languageService) {
+          languageService = vscodeHtml.getLanguageService({
+            clientCapabilities: context.env.clientCapabilities,
+            fileSystemProvider: fileSystemOf(context),
+            useDefaultDataProvider: false,
+            customDataProviders: [createMergedHtmlDataProvider(DATA_PROVIDER_ID, project.htmlData)],
+          });
+
+          languageServices.set(project.htmlData, languageService);
+        }
+
+        return languageService;
+      }
+
+      /** The document's code and project, or nothing when the document is no HTML of a loaded project. */
+      function find(document: TextDocument): Found | undefined {
+        if (document.languageId !== "html") {
+          return undefined;
+        }
+
+        const code = codeOf(context, document);
+        if (!code?.project) {
+          return undefined;
+        }
+
+        return { code, project: code.project, languageService: languageServiceOf(code.project) };
+      }
+
+      return {
+        async provideCompletionItems(document, position) {
+          const found = find(document);
+          if (!found) {
+            return;
+          }
+
+          // Inside a plugin's region the code is the plugin language's, served through TypeScript
+          if (isInRegions(found.code.regions, document.offsetAt(position))) {
+            return;
+          }
+
+          const { code, project, languageService } = found;
+          const documentContext = getDocumentContext(code.uri.toString(), project.resolver);
+          const list = await languageService.doComplete2(document, position, code.htmlDocument, documentContext);
+
+          list.items.push(...aliasCompletions(document, position, project.resolver.aliases));
+
+          // Ahead of whatever the editor's own HTML support offers
+          for (const item of list.items) {
+            item.sortText = "0_" + item.label;
+          }
+
+          return list;
+        },
+
+        provideHover(document, position) {
+          const found = find(document);
+          if (!found) {
+            return;
+          }
+
+          if (isInRegions(found.code.regions, document.offsetAt(position))) {
+            return;
+          }
+
+          return found.languageService.doHover(document, position, found.code.htmlDocument);
+        },
+
+        provideDocumentLinks(document) {
+          const found = find(document);
+          if (!found) {
+            return;
+          }
+
+          const { code, project, languageService } = found;
+          const documentPath = code.uri.fsPath;
+          const documentContext = getDocumentContext(code.uri.toString(), project.resolver);
+          const links = languageService.findDocumentLinks(document, documentContext);
+
+          // Resolved the way the build resolves sources: aliases, extensionless paths and directories with an index file
+          for (const link of links) {
+            if (!link.target) continue;
+
+            const source = path.relative(path.dirname(documentPath), vscodeUri.URI.parse(link.target).fsPath);
+            const resolved = project.resolver.resolve(source, code.file);
+            if (!resolved) continue;
+
+            link.target = vscodeUri.URI.file(resolved.path).toString();
+          }
+
+          return links;
+        },
+
+        /**
+         * Colours the delimiters of the plugins' regions, the `{{` and `}}` of a placeholder: they are outside the code, so
+         * nothing else colours them, and they would take the colour of whatever they sit in, an attribute's string say.
+         */
+        provideDocumentSemanticTokens(document, _range, legend) {
+          const found = find(document);
+          if (!found) {
+            return;
+          }
+
+          const type = legend.tokenTypes.indexOf(SemanticTokenTypes.operator);
+          const tokens: SemanticToken[] = [];
+
+          for (const region of found.code.regions) {
+            if (!region.extent) continue;
+
+            for (const [start, end] of [
+              [region.extent.start, region.start],
+              [region.end, region.extent.end],
+            ]) {
+              if (end <= start) continue;
+
+              const { line, character } = document.positionAt(start);
+
+              tokens.push([line, character, end - start, type, 0]);
+            }
+          }
+
+          return tokens;
+        },
+
+        provideDiagnostics(document) {
+          const found = find(document);
+          if (!found) {
+            return;
+          }
+
+          return validateDocument({
+            document,
+            info: found.code.info,
+            project: found.project,
+            console: context.env.console ?? console,
+          });
+        },
+      };
+    },
+  };
+}
+
+/** The editor's file system, as the HTML language service reads it for path completions; nothing is there without one. */
+function fileSystemOf(context: LanguageServiceContext): FileSystemProvider {
+  const missing: FileStat = { type: vscodeHtml.FileType.Unknown, ctime: -1, mtime: -1, size: -1 };
+
+  return {
+    async stat(uri) {
+      return (await context.env.fs?.stat(vscodeUri.URI.parse(uri))) ?? missing;
+    },
+
+    async readDirectory(uri) {
+      return (await context.env.fs?.readDirectory(vscodeUri.URI.parse(uri))) ?? [];
+    },
+  };
+}
+
+/** The root code of the document a service is asked about, whether it is the document itself or its embedded HTML copy. */
+function codeOf(context: LanguageServiceContext, document: TextDocument): StaticboltCode | undefined {
+  const uri = vscodeUri.URI.parse(document.uri);
+  const [sourceUri] = context.decodeEmbeddedDocumentUri(uri) ?? [uri];
+  const root = context.language.scripts.get(sourceUri)?.generated?.root;
+
+  if (!(root instanceof StaticboltCode)) {
+    return undefined;
+  }
+
+  return root;
+}
+
+/**
+ * The path aliases, offered at the start of a `src` or `href` value: a partly typed one completes, and a directory alias opens
+ * its listing right away.
+ */
+function aliasCompletions(document: TextDocument, position: Position, aliases: Record<string, string>): CompletionItem[] {
+  const lineBeforeCursor = document.getText({ start: { line: position.line, character: 0 }, end: position });
+  const typed = PATH_VALUE_START.exec(lineBeforeCursor)?.[1];
+
+  if (typed === undefined) {
+    return [];
+  }
+
+  const range = { start: { line: position.line, character: position.character - typed.length }, end: position };
+
+  return Object.keys(aliases).map(alias => {
+    const textEdit = TextEdit.replace(range, alias);
+
+    // A directory alias goes on to list its files
+    if (alias.endsWith("/")) {
+      return { label: alias, kind: CompletionItemKind.Folder, textEdit, command: SUGGEST };
+    }
+
+    return { label: alias, kind: CompletionItemKind.File, textEdit };
+  });
+}

package/src/services/syntax-tokens-service.ts

@@ -0,0 +1,127 @@
+import { SemanticTokenModifiers, SemanticTokenTypes } from "vscode-languageserver-protocol";
+import { URI } from "vscode-uri";
+
+import { isInRegions } from "../helpers/regions.ts";
+import { createSyntaxTokenizer, SCOPED_TYPES } from "../helpers/syntax-tokens.ts";
+import { embeddedFileName, StaticboltCode } from "../virtual-code.ts";
+
+import type { LanguageRegions } from "../helpers/regions.ts";
+import type { LanguageServiceContext, LanguageServicePlugin, SemanticToken } from "@volar/language-service";
+import type * as ts from "typescript";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+
+/** What the TypeScript service shares with the other services. */
+interface TypeScriptProvide {
+  /** The language service over the project's files, the embedded codes among them. */
+  "typescript/languageService": () => ts.LanguageService;
+}
+
+/** An embedded document with the plugin language it belongs to, as TypeScript knows the document. */
+interface Embedded {
+  /** The plugin language, with its regions and holes. */
+  group: LanguageRegions;
+
+  /** The embedded document as a TypeScript file. */
+  fileName: string;
+}
+
+/**
+ * Colours what TypeScript's own tokens leave out of the embedded code the editor's grammar cannot see, a placeholder say:
+ * keywords, literals, operators and comments, named from TypeScript's parse of it. TypeScript names the identifiers; together
+ * they colour the code the way a TypeScript file is coloured. The languages the editor colours itself get only the identifiers.
+ * With `isScoped`, the keywords are sent as the scoped types an editor maps to grammar scopes, see `SCOPED_TYPES`; otherwise as
+ * the nearest standard types.
+ */
+export function createSyntaxTokensService(typescript: typeof ts, isScoped: boolean): LanguageServicePlugin {
+  const tokenize = createSyntaxTokenizer(typescript, isScoped);
+
+  return {
+    name: "staticbolt-syntax-tokens",
+
+    capabilities: {
+      semanticTokensProvider: {
+        legend: {
+          tokenTypes: [...Object.values(SemanticTokenTypes), ...Object.keys(SCOPED_TYPES)],
+          tokenModifiers: Object.values(SemanticTokenModifiers),
+        },
+      },
+    },
+
+    create(context) {
+      /**
+       * The parsed file of an embedded document as the project's TypeScript holds it, with the checker that knows its symbols, or
+       * a fresh parse alone when the project has none.
+       */
+      function parse(document: TextDocument, fileName: string): [ts.SourceFile, ts.TypeChecker | undefined] {
+        const program = context.inject<TypeScriptProvide>("typescript/languageService")?.getProgram();
+        const parsed = program?.getSourceFile(fileName);
+        if (program && parsed && parsed.text === document.getText()) {
+          return [parsed, program.getTypeChecker()];
+        }
+
+        return [typescript.createSourceFile(fileName, document.getText(), typescript.ScriptTarget.Latest, true), undefined];
+      }
+
+      return {
+        provideDocumentSemanticTokens(document, _range, legend) {
+          if (document.languageId !== "typescript") {
+            return;
+          }
+
+          const embedded = embeddedOf(context, document);
+          if (!embedded || embedded.group.language.isColouredByEditor) {
+            return;
+          }
+
+          const [sourceFile, checker] = parse(document, embedded.fileName);
+          const tokens: SemanticToken[] = [];
+
+          for (const token of tokenize(sourceFile, document, checker)) {
+            const type = legend.tokenTypes.indexOf(token.type);
+            if (type === -1) continue;
+
+            // The masks standing in for other languages' code are not code to colour
+            const offset = document.offsetAt({ line: token.line, character: token.character });
+            if (isInRegions(embedded.group.holes, offset)) continue;
+
+            let modifiers = 0;
+
+            for (const modifier of token.modifiers) {
+              const bit = legend.tokenModifiers.indexOf(modifier);
+              if (bit === -1) continue;
+
+              modifiers |= 1 << bit;
+            }
+
+            tokens.push([token.line, token.character, token.length, type, modifiers]);
+          }
+
+          return tokens;
+        },
+      };
+    },
+  };
+}
+
+/** The plugin language an embedded document belongs to and its TypeScript file name, as `getExtraServiceScripts` names it. */
+function embeddedOf(context: LanguageServiceContext, document: TextDocument): Embedded | undefined {
+  const decoded = context.decodeEmbeddedDocumentUri(URI.parse(document.uri));
+  if (!decoded) {
+    return undefined;
+  }
+
+  const [sourceUri, codeId] = decoded;
+  const root = context.language.scripts.get(sourceUri)?.generated?.root;
+  if (!(root instanceof StaticboltCode)) {
+    return undefined;
+  }
+
+  const group = root.languages.find(candidate => candidate.id === codeId);
+  if (!group) {
+    return undefined;
+  }
+
+  const documentFileName = context.project.typescript?.uriConverter.asFileName(sourceUri) ?? sourceUri.fsPath;
+
+  return { group, fileName: embeddedFileName(documentFileName, codeId) };
+}

package/src/services/typescript-service.ts

@@ -0,0 +1,20 @@
+import { create } from "volar-service-typescript";
+
+import type { LanguageServicePlugin } from "@volar/language-service";
+import type * as ts from "typescript";
+
+/**
+ * TypeScript's features for the embedded codes, through Volar's TypeScript service: completion, hover, diagnostics, semantic
+ * tokens, definitions, references, rename, folding and the rest. Formatting is left out: a document is HTML to the editor, and
+ * its own formatter takes care of the whole of it.
+ */
+export function createTypeScriptServices(typescript: typeof ts): LanguageServicePlugin[] {
+  return create(typescript).map(plugin => ({
+    ...plugin,
+    capabilities: {
+      ...plugin.capabilities,
+      documentFormattingProvider: undefined,
+      documentOnTypeFormattingProvider: undefined,
+    },
+  }));
+}

package/src/virtual-code.ts

@@ -0,0 +1,196 @@
+import path from "node:path";
+import { Resolver } from "@staticbolt/core";
+import vscodeHtml from "vscode-html-languageservice";
+import { TextDocument } from "vscode-languageserver-textdocument";
+
+import { parseElements } from "./helpers/document-elements.ts";
+import { describeDocument } from "./helpers/document-info.ts";
+import { findMarkdownNonHtmlRegions } from "./helpers/markdown-regions.ts";
+import { findPluginRegions, groupByFile } from "./helpers/regions.ts";
+import { blankAround, blankRegions, mask } from "./helpers/virtual-document.ts";
+
+import type { LanguageRegions, PluginRegion } from "./helpers/regions.ts";
+import type { Project } from "./projects.ts";
+import type { CodeMapping, IScriptSnapshot, VirtualCode } from "@volar/language-core";
+import type { DocumentInfo, EmbeddedRegion } from "@staticbolt/core";
+import type * as ts from "typescript";
+import type { HTMLDocument, LanguageService } from "vscode-html-languageservice";
+import type { URI } from "vscode-uri";
+
+/** The id of the root code, and of the HTML copy a markdown document is served through. */
+const ROOT_ID = "root";
+
+/** The id of the embedded code holding the HTML of a document that is not HTML itself. */
+const HTML_ID = "html";
+
+/** The TypeScript file name an embedded code of a document is served under. */
+export function embeddedFileName(documentFileName: string, codeId: string): string {
+  return `${documentFileName}.${codeId}.ts`;
+}
+
+/** What every feature is allowed to do on a mapped stretch of code. */
+const ALL_FEATURES: CodeMapping["data"] = {
+  verification: true,
+  completion: true,
+  semantic: true,
+  navigation: true,
+  structure: true,
+  format: false,
+};
+
+/** The HTML language service the codes parse with; no data provider, only the tree is wanted here. */
+const htmlLanguageService: LanguageService = vscodeHtml.getLanguageService({ useDefaultDataProvider: false });
+
+/**
+ * A document as the server sees it: the HTML (a markdown document's with everything that cannot be HTML blanked out), the regions
+ * plugins embed in it, and an embedded TypeScript code per plugin language, served through the project's TypeScript.
+ */
+export class StaticboltCode implements VirtualCode {
+  /** The root is the document. */
+  readonly id = ROOT_ID;
+
+  /** `html` or `markdown`. */
+  readonly languageId: string;
+
+  /** The document's text. */
+  readonly snapshot: IScriptSnapshot;
+
+  /** The whole document maps onto itself. */
+  readonly mappings: CodeMapping[];
+
+  /** The HTML copy of a markdown document, then the TypeScript code of every plugin language with regions. */
+  readonly embeddedCodes: VirtualCode[];
+
+  /** The document's uri. */
+  readonly uri: URI;
+
+  /** The project the document belongs to, or nothing when it is outside every loaded one. */
+  readonly project: Project | undefined;
+
+  /** The document's path relative to its project, or its whole path outside one. */
+  readonly file: string;
+
+  /** The document as HTML: the text itself, or for markdown the blanked copy. */
+  readonly html: string;
+
+  /** The regions the plugins embed, in text order. */
+  readonly regions: PluginRegion[];
+
+  /** The regions by plugin language. */
+  readonly languages: LanguageRegions[];
+
+  /** The parsed HTML, on first use. */
+  #htmlDocument: HTMLDocument | undefined;
+
+  /** The document as the plugins see it, on first use. */
+  #info: DocumentInfo | undefined;
+
+  constructor(typescript: typeof ts, uri: URI, languageId: string, snapshot: IScriptSnapshot, project: Project | undefined) {
+    const text = snapshot.getText(0, snapshot.getLength());
+
+    this.uri = uri;
+    this.languageId = languageId;
+    this.snapshot = snapshot;
+    this.project = project;
+    this.file = project ? path.relative(project.root, uri.fsPath) : uri.fsPath;
+    this.mappings = [identityMapping(text.length)];
+    this.html = languageId === "markdown" ? blankRegions(text, findMarkdownNonHtmlRegions(text)) : text;
+    this.regions = project ? findPluginRegions(this.info, project.embeddedLanguages) : [];
+    this.languages = groupByFile(this.regions);
+    this.embeddedCodes = this.languages.map(group => createTypeScriptCode(typescript, this.info, group));
+
+    if (languageId === "markdown") {
+      this.embeddedCodes.unshift(createHtmlCode(typescript, this.html));
+    }
+  }
+
+  /** The parsed HTML. */
+  get htmlDocument(): HTMLDocument {
+    this.#htmlDocument ??= htmlLanguageService.parseHTMLDocument(TextDocument.create(this.uri.toString(), "html", 0, this.html));
+
+    return this.#htmlDocument;
+  }
+
+  /**
+   * The document as the plugins see it: its elements with their attributes and where everything sits, and the project's resolver.
+   * Outside a project, a resolver of the document's own directory.
+   */
+  get info(): DocumentInfo {
+    this.#info ??= describeDocument(
+      this.html,
+      this.file,
+      parseElements(htmlLanguageService, this.html, this.htmlDocument),
+      this.project?.resolver ?? new Resolver(path.dirname(this.uri.fsPath), false, {}, false)
+    );
+
+    return this.#info;
+  }
+}
+
+/** A mapping of a whole text onto itself. */
+function identityMapping(length: number): CodeMapping {
+  return { sourceOffsets: [0], generatedOffsets: [0], lengths: [length], data: ALL_FEATURES };
+}
+
+/** A markdown document's HTML copy, at the same offsets. */
+function createHtmlCode(typescript: typeof ts, html: string): VirtualCode {
+  return {
+    id: HTML_ID,
+    languageId: "html",
+    snapshot: typescript.ScriptSnapshot.fromString(html),
+    mappings: [identityMapping(html.length)],
+  };
+}
+
+/**
+ * The TypeScript code of one file of a plugin language: the document with everything outside the file's regions blanked, so every
+ * offset means the same thing in both, the regions of other languages masked, and the language's prelude appended at the end. A
+ * module is made one with an `export {}`, so its top level is its own; a script's top level is the global scope, as it is in the
+ * browser. The regions map back to the document; what lies before the first and after the last maps onto their edges, so what
+ * TypeScript puts at the top or the bottom of the file, an import or a declaration it adds say, lands in the code.
+ */
+function createTypeScriptCode(typescript: typeof ts, info: DocumentInfo, group: LanguageRegions): VirtualCode {
+  const { id, language, isModule, regions, holes } = group;
+  const prelude = typeof language.prelude === "function" ? language.prelude(info) : language.prelude;
+  const suffix = [isModule ? "export {};" : "", prelude ?? ""].filter(Boolean).join("\n");
+  const text = `${mask(typescript, blankAround(info.text, regions), holes)}\n${suffix}\n`;
+  const first = regions[0];
+  const last = regions.at(-1) ?? first;
+
+  return {
+    id,
+    languageId: "typescript",
+    snapshot: typescript.ScriptSnapshot.fromString(text),
+    mappings: [
+      {
+        sourceOffsets: regions.map(region => region.start),
+        generatedOffsets: regions.map(region => region.start),
+        lengths: regions.map(region => region.end - region.start),
+        data: ALL_FEATURES,
+      },
+      edgeMapping(topOf(info.text, first), 0, first.start),
+      edgeMapping(last.end, last.end, text.length - last.end),
+    ],
+  };
+}
+
+/**
+ * A stretch of the generated text outside the regions mapped onto one spot of the document, for the edits of completions and code
+ * actions only: nothing there is verified, coloured or folded.
+ */
+function edgeMapping(sourceOffset: number, generatedOffset: number, generatedLength: number): CodeMapping {
+  return {
+    sourceOffsets: [sourceOffset],
+    generatedOffsets: [generatedOffset],
+    lengths: [0],
+    generatedLengths: [generatedLength],
+    data: { completion: true, navigation: true, verification: false, semantic: false, structure: false, format: false },
+  };
+}
+
+/** Where the top of a file's code is in the document: the first region's start, past the line break a script body opens with. */
+function topOf(text: string, first: EmbeddedRegion): number {
+  const lineBreak = /^\r?\n/.exec(text.slice(first.start, first.end));
+
+  return first.start + (lineBreak?.[0].length ?? 0);
+}