@staticbolt/lsp 1.0.0-beta.29 → 1.0.0-beta.31

package/src/helpers/document-elements.ts

@@ -0,0 +1,119 @@
+import vscodeHtml from "vscode-html-languageservice";
+
+import type { AttributeInfo, ElementInfo, TextRange } from "@staticbolt/core";
+import type { HTMLDocument, LanguageService, Node } from "vscode-html-languageservice";
+
+/** The token kinds the HTML scanner reports. */
+const TokenType = vscodeHtml.TokenType;
+
+/**
+ * Every element of a parsed document in document order, with the attribute offsets the parser leaves out: each start tag is
+ * scanned again for them.
+ */
+export function parseElements(languageService: LanguageService, text: string, htmlDocument: HTMLDocument): ElementInfo[] {
+  const elements: ElementInfo[] = [];
+
+  for (const root of htmlDocument.roots) {
+    collectElements(languageService, text, root, undefined, elements);
+  }
+
+  return elements;
+}
+
+/** The element for a node and, after it, the ones for its children; the tree only ever holds elements. */
+function collectElements(
+  languageService: LanguageService,
+  text: string,
+  node: Node,
+  parent: ElementInfo | undefined,
+  elements: ElementInfo[]
+): void {
+  const element = createElement(languageService, text, node, parent);
+
+  elements.push(element);
+  parent?.children.push(element);
+
+  for (const child of node.children) {
+    collectElements(languageService, text, child, element, elements);
+  }
+}
+
+/** The element for a node, with its attributes scanned from its start tag. */
+function createElement(languageService: LanguageService, text: string, node: Node, parent: ElementInfo | undefined): ElementInfo {
+  const tag = node.tag ?? "";
+  const startTagEnd = node.startTagEnd ?? node.end;
+  const attributes: AttributeInfo[] = [];
+
+  const findAttribute = (name: string) => {
+    const wanted = name.toLowerCase();
+
+    return attributes.find(attribute => attribute.name.toLowerCase() === wanted);
+  };
+
+  const element: ElementInfo = {
+    name: tag.toLowerCase(),
+    attributes,
+    parent,
+    children: [],
+    range: { start: node.start, end: node.end },
+    nameRange: { start: node.start + 1, end: node.start + 1 + tag.length },
+    contentRange: contentRangeOf(node, startTagEnd),
+    attribute: findAttribute,
+    has: name => findAttribute(name) !== undefined,
+  };
+
+  attributes.push(...scanAttributes(languageService, text, element, node.start, startTagEnd));
+
+  return element;
+}
+
+/**
+ * From the end of the start tag to the end tag, or to wherever the parser closed an element missing its end tag; nothing for an
+ * element that is over with its start tag, void or self-closing.
+ */
+function contentRangeOf(node: Node, startTagEnd: number): TextRange | undefined {
+  const end = node.endTagStart ?? node.end;
+
+  if (end <= startTagEnd) {
+    return undefined;
+  }
+
+  return { start: startTagEnd, end };
+}
+
+/** The attributes in a start tag, with where their names and values sit. */
+function scanAttributes(
+  languageService: LanguageService,
+  text: string,
+  element: ElementInfo,
+  start: number,
+  end: number
+): AttributeInfo[] {
+  const attributes: AttributeInfo[] = [];
+  const scanner = languageService.createScanner(text.slice(start, end));
+  let pending: AttributeInfo | undefined;
+
+  for (let token = scanner.scan(); token !== TokenType.EOS; token = scanner.scan()) {
+    const range: TextRange = { start: start + scanner.getTokenOffset(), end: start + scanner.getTokenEnd() };
+
+    if (token === TokenType.AttributeName) {
+      pending = { name: scanner.getTokenText(), value: undefined, element, nameRange: range, valueRange: undefined };
+      attributes.push(pending);
+      continue;
+    }
+
+    if (token !== TokenType.AttributeValue || !pending) {
+      continue;
+    }
+
+    const raw = scanner.getTokenText();
+    const isQuoted = raw.startsWith('"') || raw.startsWith("'");
+    const quote = isQuoted ? 1 : 0;
+
+    pending.value = raw.slice(quote, raw.length - quote);
+    pending.valueRange = { start: range.start + quote, end: range.end - quote };
+    pending = undefined;
+  }
+
+  return attributes;
+}

package/src/helpers/document-info.ts

@@ -0,0 +1,29 @@
+import type { DocumentInfo, ElementInfo, Resolver } from "@staticbolt/core";
+
+/** The document as a plugin sees it: its text and elements, with lookups over them and the project's resolver. */
+export function describeDocument(text: string, file: string, elements: ElementInfo[], resolver: Resolver): DocumentInfo {
+  return {
+    file,
+    text,
+    elements,
+
+    select(...names) {
+      const wanted = new Set(names.map(name => name.toLowerCase()));
+
+      return elements.filter(element => wanted.has(element.name));
+    },
+
+    textOf(range) {
+      return text.slice(range.start, range.end);
+    },
+
+    resolve(source) {
+      const resolved = resolver.resolve(source, file);
+      if (!resolved) {
+        return;
+      }
+
+      return { path: resolved.path, exists: resolved.exists };
+    },
+  };
+}

package/src/{modes → helpers}/markdown-regions.ts

@@ -5,18 +5,14 @@
  */
 import { markdownToMdast } from "satteri";
 
+import type { TextRange } from "@staticbolt/core";
 import type { MdastNode } from "satteri";
 
-export interface TextRegion {
-  start: number;
-  end: number;
-}
-
 /** None of these nest, so the regions they produce never overlap. */
 const NON_HTML_NODES = new Set(["code", "inlineCode", "yaml", "toml"]);
 
 /** The regions of a markdown document that must not be treated as HTML, sorted by start offset. */
-export function findMarkdownNonHtmlRegions(text: string): TextRegion[] {
+export function findMarkdownNonHtmlRegions(text: string): TextRange[] {
   let tree: MdastNode;
 
   try {
@@ -26,26 +22,26 @@ export function findMarkdownNonHtmlRegions(text: string): TextRegion[] {
     return [];
   }
 
-  const regions: TextRegion[] = [];
+  const regions: TextRange[] = [];
   const pending: MdastNode[] = [tree];
 
   while (pending.length > 0) {
     const node = pending.pop()!;
 
-    if (NON_HTML_NODES.has(node.type)) {
-      const start = node.position?.start.offset;
-      const end = node.position?.end.offset;
-
-      if (start !== undefined && end !== undefined) {
-        regions.push({ start, end });
-      }
-
-      continue;
-    }
-
+    // The nodes looked for are leaves, so a node with children is never one of them
     if ("children" in node) {
       pending.push(...node.children);
+      continue;
     }
+
+    if (!NON_HTML_NODES.has(node.type)) continue;
+
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+
+    if (start === undefined || end === undefined) continue;
+
+    regions.push({ start, end });
   }
 
   const sorted = regions.toSorted((a, b) => a.start - b.start);
@@ -57,8 +53,12 @@ export function findMarkdownNonHtmlRegions(text: string): TextRegion[] {
  * The parser counts code points, the editor counts UTF-16 code units. The two only drift apart once a character outside the basic
  * plane, an emoji most of the time, sits before a region.
  */
-function toUtf16Offsets(text: string, regions: TextRegion[]): TextRegion[] {
-  if (!/[\uD800-\uDBFF]/.test(text)) return regions;
+function toUtf16Offsets(text: string, regions: TextRange[]): TextRange[] {
+  const hasAstral = /[\uD800-\uDBFF]/.test(text);
+
+  if (!hasAstral) {
+    return regions;
+  }
 
   const astral: number[] = [];
   let codePoint = 0;
@@ -71,22 +71,12 @@ function toUtf16Offsets(text: string, regions: TextRegion[]): TextRegion[] {
     codePoint++;
   }
 
-  const toUtf16 = (offset: number) => offset + astral.filter(position => position < offset).length;
-
-  return regions.map(region => ({ start: toUtf16(region.start), end: toUtf16(region.end) }));
-}
-
-/** Replaces every region with spaces, keeping the length of the text and its line breaks. Regions must be sorted and disjoint. */
-export function blankRegions(text: string, regions: readonly TextRegion[]): string {
-  if (regions.length === 0) return text;
+  /** Shifts a code point offset by the number of astral characters before it. */
+  function toUtf16(offset: number): number {
+    const astralBefore = astral.filter(position => position < offset).length;
 
-  let result = "";
-  let cursor = 0;
-
-  for (const region of regions) {
-    result += text.slice(cursor, region.start) + text.slice(region.start, region.end).replaceAll(/[^\n\r]/g, " ");
-    cursor = region.end;
+    return offset + astralBefore;
   }
 
-  return result + text.slice(cursor);
+  return regions.map(region => ({ start: toUtf16(region.start), end: toUtf16(region.end) }));
 }

package/src/helpers/merge-html-data.ts

@@ -8,33 +8,37 @@ import type {
   MarkupContent,
 } from "vscode-html-languageservice";
 
+/** A description as the data format allows it: plain, marked up, or absent. */
 type Description = string | MarkupContent | undefined;
+
+/** Plain text or markdown. */
 type DescriptionKind = MarkupContent["kind"];
+
+/** The value sets by name. */
 type ValueSets = Map<string, IValueData[]>;
 
-/** Separates the documentation of two contributors. Rendered as a horizontal rule, unless the description is plain text. */
+/** The `valueSet` the HTML language service reads as "a boolean attribute". */
+const BOOLEAN_VALUE_SET = "v";
+
+/** Separates the documentation of two contributors, rendered as a horizontal rule. */
 const MARKDOWN_SEPARATOR = "\n\n---\n\n";
+
+/** The same, for descriptions that are plain text. */
 const PLAINTEXT_SEPARATOR = "\n\n";
 
 /** Groups entries by key, preserving the order of first appearance. */
 function groupBy<T>(items: T[], toKey: (item: T) => string): T[][] {
   const groups = new Map<string, T[]>();
-  const ordered: T[][] = [];
 
   for (const item of items) {
     const key = toKey(item);
-
-    let group = groups.get(key);
-    if (!group) {
-      group = [];
-      groups.set(key, group);
-      ordered.push(group);
-    }
+    const group = groups.get(key) ?? [];
 
     group.push(item);
+    groups.set(key, group);
   }
 
-  return ordered;
+  return groups.values().toArray();
 }
 
 /** Markdown wins over plain text, so a contributor asking for rich text still gets it. Plain strings imply no preference. */
@@ -42,39 +46,59 @@ function mergeDescriptionKind(descriptions: Exclude<Description, undefined>[]):
   let kind: DescriptionKind | undefined;
 
   for (const description of descriptions) {
-    if (typeof description === "string" || kind === "markdown") continue;
+    if (typeof description === "string") continue;
+    if (kind === "markdown") break;
+
     kind = description.kind;
   }
 
   return kind;
 }
 
+/** The text of a description, whichever shape it has. */
+function textOf(description: Exclude<Description, undefined>): string {
+  if (typeof description === "string") {
+    return description;
+  }
+
+  return description.value;
+}
+
 /** Concatenates every distinct description, so no contributor's documentation gets lost. */
 function mergeDescriptions(descriptions: Description[]): Description {
   const defined = descriptions.filter(description => description !== undefined);
 
-  // nothing to merge, keep the original as-is
-  if (defined.length <= 1) return defined[0];
+  if (defined.length <= 1) {
+    return defined[0];
+  }
 
   const parts: string[] = [];
   const seen = new Set<string>();
 
   for (const description of defined) {
-    const text = (typeof description === "string" ? description : description.value).trim();
+    const text = textOf(description).trim();
     if (!text || seen.has(text)) continue;
 
     seen.add(text);
     parts.push(text);
   }
 
-  if (parts.length === 0) return undefined;
+  if (parts.length === 0) {
+    return undefined;
+  }
 
   const kind = mergeDescriptionKind(defined);
-  const value = parts.join(kind === "plaintext" ? PLAINTEXT_SEPARATOR : MARKDOWN_SEPARATOR);
+  const separator = kind === "plaintext" ? PLAINTEXT_SEPARATOR : MARKDOWN_SEPARATOR;
+  const value = parts.join(separator);
 
-  return kind ? { kind, value } : value;
+  if (!kind) {
+    return value;
+  }
+
+  return { kind, value };
 }
 
+/** Every distinct reference, a reference being the same as another when both name and url match. */
 function mergeReferences(references: (IReference[] | undefined)[]): IReference[] | undefined {
   const merged: IReference[] = [];
   const seen = new Set<string>();
@@ -91,9 +115,14 @@ function mergeReferences(references: (IReference[] | undefined)[]): IReference[]
     }
   }
 
-  return merged.length > 0 ? merged : undefined;
+  if (merged.length === 0) {
+    return undefined;
+  }
+
+  return merged;
 }
 
+/** Every distinct browser. */
 function mergeBrowsers(browsers: (string[] | undefined)[]): string[] | undefined {
   const merged = new Set<string>();
 
@@ -105,13 +134,20 @@ function mergeBrowsers(browsers: (string[] | undefined)[]): string[] | undefined
     }
   }
 
-  return merged.size > 0 ? [...merged] : undefined;
+  if (merged.size === 0) {
+    return undefined;
+  }
+
+  return [...merged];
 }
 
 /** The values an attribute contributes, with its `valueSet` reference expanded. */
 function resolveValues(attribute: IAttributeData, valueSets: ValueSets): IValueData[] {
   const values = attribute.values ?? [];
-  if (!attribute.valueSet) return values;
+
+  if (!attribute.valueSet) {
+    return values;
+  }
 
   return [...(valueSets.get(attribute.valueSet) ?? []), ...values];
 }
@@ -119,7 +155,9 @@ function resolveValues(attribute: IAttributeData, valueSets: ValueSets): IValueD
 /** Merges entries sharing the same value name into one. Unlike tags and attributes, value names are case-sensitive. */
 function mergeValues(values: IValueData[]): IValueData[] {
   return groupBy(values, value => value.name).map(group => {
-    if (group.length === 1) return group[0];
+    if (group.length === 1) {
+      return group[0];
+    }
 
     return {
       name: group[0].name,
@@ -139,15 +177,17 @@ function mergeValues(values: IValueData[]): IValueData[] {
  */
 function mergeAttributes(attributes: IAttributeData[], valueSets: ValueSets): IAttributeData[] {
   return groupBy(attributes, attribute => attribute.name.toLowerCase()).map(group => {
-    // nothing to merge and no value set to expand, keep the original as-is
-    if (group.length === 1 && !group[0].valueSet) return group[0];
+    if (group.length === 1 && !group[0].valueSet) {
+      return group[0];
+    }
 
     const values = mergeValues(group.flatMap(attribute => resolveValues(attribute, valueSets)));
+    const isBoolean = group.some(attribute => attribute.valueSet === BOOLEAN_VALUE_SET);
 
     return {
       name: group[0].name,
       description: mergeDescriptions(group.map(attribute => attribute.description)),
-      // `valueSet` is dropped on purpose: every referenced set is now expanded into `values`
+      valueSet: isBoolean ? BOOLEAN_VALUE_SET : undefined,
       values: values.length > 0 ? values : undefined,
       references: mergeReferences(group.map(attribute => attribute.references)),
       browsers: mergeBrowsers(group.map(attribute => attribute.browsers)),
@@ -164,7 +204,9 @@ function mergeTags(tags: ITagData[], valueSets: ValueSets): ITagData[] {
       valueSets
     );
 
-    if (group.length === 1) return { ...group[0], attributes };
+    if (group.length === 1) {
+      return { ...group[0], attributes };
+    }
 
     return {
       name: group[0].name,
@@ -184,8 +226,9 @@ function collectValueSets(htmlData: HTMLDataV1[]): ValueSets {
   const collected = htmlData.flatMap(data => data.valueSets ?? []);
 
   for (const valueSet of collected) {
-    const existing = valueSets.get(valueSet.name);
-    valueSets.set(valueSet.name, existing ? mergeValues([...existing, ...valueSet.values]) : valueSet.values);
+    const existing = valueSets.get(valueSet.name) ?? [];
+
+    valueSets.set(valueSet.name, mergeValues([...existing, ...valueSet.values]));
   }
 
   return valueSets;
@@ -198,7 +241,6 @@ function collectValueSets(htmlData: HTMLDataV1[]): ValueSets {
 export function createMergedHtmlDataProvider(id: string, htmlData: HTMLDataV1[]): IHTMLDataProvider {
   const valueSets = collectValueSets(htmlData);
 
-  // the language service asks for tags on every parse, and for attributes on every completion/hover, so merging happens once here
   const tags = mergeTags(
     htmlData.flatMap(data => data.tags ?? []),
     valueSets
@@ -216,11 +258,15 @@ export function createMergedHtmlDataProvider(id: string, htmlData: HTMLDataV1[])
     const key = tag.toLowerCase();
 
     const cached = attributesByTag.get(key);
-    if (cached) return cached;
+    if (cached) {
+      return cached;
+    }
 
-    // an unknown tag only sees the global attributes, which are merged already
+    // An unknown tag only sees the global attributes, which are merged already
     const tagAttributes = tagsByName.get(key)?.attributes;
-    if (!tagAttributes || tagAttributes.length === 0) return globalAttributes;
+    if (!tagAttributes || tagAttributes.length === 0) {
+      return globalAttributes;
+    }
 
     const attributes = mergeAttributes([...globalAttributes, ...tagAttributes], valueSets);
     attributesByTag.set(key, attributes);
@@ -245,9 +291,9 @@ export function createMergedHtmlDataProvider(id: string, htmlData: HTMLDataV1[])
 
     provideValues(tag, attribute) {
       const name = attribute.toLowerCase();
+      const match = provideAttributes(tag).find(candidate => candidate.name.toLowerCase() === name);
 
-      // merged attributes already carry their expanded value sets
-      return provideAttributes(tag).find(a => a.name.toLowerCase() === name)?.values ?? [];
+      return match?.values ?? [];
     },
   };
 }

package/src/helpers/regions.ts

@@ -0,0 +1,101 @@
+import type { DocumentInfo, EmbeddedLanguage, EmbeddedRegion, TextRange } from "@staticbolt/core";
+
+/** A region of a plugin language in a document. */
+export interface PluginRegion extends EmbeddedRegion {
+  /** The plugin language. */
+  language: EmbeddedLanguage;
+}
+
+/** The regions of one plugin language that share a file: the classic ones together, a module on its own. */
+export interface LanguageRegions {
+  /** The file's id: the language's name, with the module's number for a module. */
+  id: string;
+
+  /** The plugin language. */
+  language: EmbeddedLanguage;
+
+  /** Whether the file is a module of one region, with a top level of its own, rather than a script whose top level is global. */
+  isModule: boolean;
+
+  /** Its regions, in text order. */
+  regions: EmbeddedRegion[];
+
+  /** The regions of other plugin languages inside its own, in text order: those languages serve them, this one sees them masked. */
+  holes: TextRange[];
+}
+
+/** Regions in text order. */
+const byStart = (a: TextRange, b: TextRange) => a.start - b.start;
+
+/**
+ * The regions of every plugin language that claims the document, in text order. A region inside one a language earlier in the
+ * config claimed already is left to that language: a plugin that runs a script elsewhere claims it before the core plugin, last
+ * in the config, sees the browser in it. A region of another language inside this one is a hole, not a claim.
+ */
+export function findPluginRegions(document: DocumentInfo, languages: readonly EmbeddedLanguage[]): PluginRegion[] {
+  const regions: PluginRegion[] = [];
+
+  for (const language of languages) {
+    if (!language.filter(document.file)) continue;
+
+    for (const region of language.findRegions(document)) {
+      if (regions.some(claimed => isInside(region, claimed))) continue;
+
+      regions.push({ ...region, language });
+    }
+  }
+
+  return regions.toSorted(byStart);
+}
+
+/** Whether a range lies within another. */
+function isInside(range: TextRange, outer: TextRange): boolean {
+  return outer.start <= range.start && range.end <= outer.end;
+}
+
+/**
+ * The plugin regions by the file they share: the classic regions of a language together, each module on its own. Every group is
+ * in text order, with the regions of other languages inside its own as its holes: a placeholder inside a build-time script is
+ * the placeholder language's.
+ */
+export function groupByFile(regions: readonly PluginRegion[]): LanguageRegions[] {
+  const groups = new Map<string, LanguageRegions>();
+  let modules = 0;
+
+  for (const region of regions) {
+    const id = region.isModule ? `${region.language.name}.module${modules++}` : region.language.name;
+    const group = groups.get(id) ?? { id, language: region.language, isModule: region.isModule === true, regions: [], holes: [] };
+
+    group.regions.push({ start: region.start, end: region.end });
+    group.holes.push(...holesOf(region, regions));
+    groups.set(id, group);
+  }
+
+  return groups.values().toArray();
+}
+
+/** The whole construct a region sits in, delimiters included, or the region itself when it has no more. */
+function extentOf(region: EmbeddedRegion): TextRange {
+  return region.extent ?? { start: region.start, end: region.end };
+}
+
+/** Whether an offset falls in any of the regions, their ends included. */
+export function isInRegions(regions: readonly TextRange[], offset: number): boolean {
+  return regions.some(region => region.start <= offset && offset <= region.end);
+}
+
+/** The regions of other languages lying inside a region, as their whole constructs. */
+function holesOf(region: PluginRegion, regions: readonly PluginRegion[]): TextRange[] {
+  const holes: TextRange[] = [];
+
+  for (const other of regions) {
+    if (other.language === region.language) continue;
+
+    const hole = extentOf(other);
+    if (hole.start < region.start || hole.end > region.end) continue;
+
+    holes.push(hole);
+  }
+
+  return holes;
+}