Add a virtual document abstraction to the language service

Most relevant requests are document related in some manner and this will serve a few purposes:
- It centralizes logic common to all providers
- It can help simplify the implementation of providers
- It reduces duplication by moving common actions into the document creation layer (e.g. loading settings)

Author: thecrypticace

packages/tailwindcss-language-service/src/documents/document.ts

@@ -0,0 +1,190 @@
+import type { Position, TextDocument } from 'vscode-languageserver-textdocument'
+import type {
+  DocumentClassList,
+  DocumentClassName,
+  DocumentHelperFunction,
+  Settings,
+  State,
+} from '../util/state'
+import type { ServiceOptions } from '../service'
+import { isWithinRange } from '../util/isWithinRange'
+import { getDocumentBlocks, type LanguageBlock } from '../util/language-blocks'
+import {
+  findClassListsInCssRange,
+  findClassListsInHtmlRange,
+  findCustomClassLists,
+  findHelperFunctionsInDocument,
+  findHelperFunctionsInRange,
+  getClassNamesInClassList,
+} from '../util/find'
+import { dedupeBySpan } from '../util/array'
+
+export interface Document {
+  readonly state: State
+  readonly version: number
+  readonly uri: string
+  readonly settings: Settings
+  readonly storage: TextDocument
+
+  /**
+   * Find the language block that contains the cursor
+   */
+  blockAt(cursor: Position): LanguageBlock | null
+
+  /**
+   * Find all class lists in the document
+   */
+  classLists(): Iterable<DocumentClassList>
+
+  /**
+   * Find all class lists at a given cursor position
+   */
+  classListsAt(cursor: Position): Iterable<DocumentClassList>
+
+  /**
+   * Find all class names in the document
+   */
+  classNames(): Iterable<DocumentClassName>
+
+  /**
+   * Find all class names at a given cursor position
+   *
+   * Theoretically, this function should only ever contain one entry
+   * but the presence of custom regexes may produce multiple entries
+   */
+  classNamesAt(cursor: Position): Iterable<DocumentClassName>
+
+  /**
+   * Find all helper functions in the document
+   *
+   * This only applies to CSS contexts. Other document types will produce
+   * zero entries.
+   */
+  helperFns(): Iterable<DocumentHelperFunction>
+
+  /**
+   * Find all helper functions at a given cursor position
+   */
+  helperFnsAt(cursor: Position): Iterable<DocumentHelperFunction>
+}
+
+export async function createVirtualDocument(
+  opts: ServiceOptions,
+  storage: TextDocument,
+): Promise<Document> {
+  /**
+   * The state of the server at the time of creation
+   */
+  let state = opts.state()
+
+  /**
+   * The current settings for this document
+   */
+  let settings = await state.editor.getConfiguration(storage.uri)
+
+  /**
+   * Conceptual boundaries of the document where different languages are used
+   *
+   * This is used to determine how the document is structured and what parts
+   * are relevant to the current operation.
+   */
+  let blocks = getDocumentBlocks(state, storage)
+
+  /**
+   * All class lists in the document
+   */
+  let classLists: DocumentClassList[] = []
+
+  for (let block of blocks) {
+    if (block.context === 'css') {
+      classLists.push(...findClassListsInCssRange(state, storage, block.range, block.lang))
+    } else if (block.context === 'html') {
+      classLists.push(...(await findClassListsInHtmlRange(state, storage, 'html', block.range)))
+    } else if (block.context === 'js') {
+      classLists.push(...(await findClassListsInHtmlRange(state, storage, 'jsx', block.range)))
+    }
+  }
+
+  classLists.push(...(await findCustomClassLists(state, storage)))
+
+  classLists.sort((a, b) => a.span[0] - b.span[0] || b.span[1] - a.span[1])
+  classLists = dedupeBySpan(classLists)
+
+  /**
+   * All class names in the document
+   */
+  let classNames: DocumentClassName[] = []
+
+  for (let classList of classLists) {
+    classNames.push(...getClassNamesInClassList(classList, state.blocklist ?? []))
+  }
+
+  classNames.sort((a, b) => a.span[0] - b.span[0] || b.span[1] - a.span[1])
+  classNames = dedupeBySpan(classNames)
+
+  /**
+   * Helper functions in CSS
+   */
+  let helperFns: DocumentHelperFunction[] = []
+
+  for (let block of blocks) {
+    if (block.context === 'css') {
+      helperFns.push(...findHelperFunctionsInRange(storage, block.range))
+    }
+  }
+
+  function blockAt(cursor: Position): LanguageBlock | null {
+    for (let block of blocks) {
+      if (isWithinRange(cursor, block.range)) {
+        return block
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Find all class lists at a given cursor position
+   */
+  function classListsAt(cursor: Position): DocumentClassList[] {
+    return classLists.filter((classList) => isWithinRange(cursor, classList.range))
+  }
+
+  /**
+   * Find all class names at a given cursor position
+   */
+  function classNamesAt(cursor: Position): DocumentClassName[] {
+    return classNames.filter((className) => isWithinRange(cursor, className.range))
+  }
+
+  /**
+   * Find all class names at a given cursor position
+   */
+  function helperFnsAt(cursor: Position): DocumentHelperFunction[] {
+    return helperFns.filter((fn) => isWithinRange(cursor, fn.ranges.full))
+  }
+
+  return {
+    settings,
+    storage,
+    uri: storage.uri,
+
+    get version() {
+      return storage.version
+    },
+
+    get state() {
+      return opts.state()
+    },
+
+    blockAt,
+
+    classLists: () => classLists.slice(),
+    classListsAt,
+    classNames: () => classNames.slice(),
+    classNamesAt,
+
+    helperFns: () => helperFns.slice(),
+    helperFnsAt,
+  }
+}

packages/tailwindcss-language-service/src/documents/store.ts

@@ -0,0 +1,25 @@
+import type { TextDocument } from 'vscode-languageserver-textdocument'
+import type { ServiceOptions } from '../service'
+import { createVirtualDocument, type Document } from './document'
+
+export function createDocumentStore(opts: ServiceOptions) {
+  let documents = new Map<string, [version: number, doc: Document]>()
+
+  return {
+    clear: () => documents.clear(),
+
+    async parse(uri: string | TextDocument) {
+      let textDoc = typeof uri === 'string' ? await opts.fs.document(uri) : uri
+
+      // Return from the cache if the document has not changed
+      let found = documents.get(textDoc.uri)
+      if (found && found[0] === textDoc.version) return found[1]
+
+      let doc = await createVirtualDocument(opts, textDoc)
+
+      documents.set(textDoc.uri, [textDoc.version, doc])
+
+      return doc
+    },
+  }
+}

packages/tailwindcss-language-service/src/service.ts

@@ -28,6 +28,8 @@ import { doCodeActions } from './codeActions/codeActionProvider'
 import { provideColorPresentation } from './colorPresentationProvider'
 import { getColor, KeywordColor } from './util/color'
 import * as culori from 'culori'
+import { Document } from './documents/document'
+import { createDocumentStore } from './documents/store'
 
 export interface ServiceOptions {
   fs: FileSystem
@@ -58,12 +60,10 @@ export interface LanguageService {
 }
 
 export function createLanguageService(opts: ServiceOptions): LanguageService {
-  async function open(doc: TextDocument | string) {
-    if (typeof doc === 'string') {
-      doc = await opts.fs.document(doc)
-    }
+  let store = createDocumentStore(opts)
 
-    return createLanguageDocument(opts, doc)
+  async function open(doc: TextDocument | string) {
+    return createLanguageDocument(opts, await store.parse(doc))
   }
 
   return {
@@ -91,7 +91,7 @@ export function createLanguageService(opts: ServiceOptions): LanguageService {
 
 async function createLanguageDocument(
   opts: ServiceOptions,
-  doc: TextDocument,
+  doc: Document,
 ): Promise<LanguageDocument | null> {
   let state = opts.state()
   if (!state.enabled) return null
@@ -120,33 +120,33 @@ async function createLanguageDocument(
     async hover(position: Position) {
       if (!state.enabled || !settings.tailwindCSS.hovers) return null
 
-      return doHover(state, doc, position)
+      return doHover(state, doc.storage, position)
     },
 
     async documentLinks() {
       if (!state.enabled) return []
 
-      return getDocumentLinks(state, doc, (path) => {
-        return opts.fs.resolve(doc, path)
+      return getDocumentLinks(state, doc.storage, (path) => {
+        return opts.fs.resolve(doc.storage, path)
       })
     },
 
     async documentColors() {
       if (!state.enabled || !settings.tailwindCSS.colorDecorators) return []
 
-      return getDocumentColors(state, doc)
+      return getDocumentColors(state, doc.storage)
     },
 
     async colorPresentation(color: Color, range: Range) {
       if (!state.enabled || !settings.tailwindCSS.colorDecorators) return []
 
-      return provideColorPresentation(state, doc, color, range)
+      return provideColorPresentation(state, doc.storage, color, range)
     },
 
     async codeLenses() {
       if (!state.enabled || !settings.tailwindCSS.codeLens) return []
 
-      return getCodeLens(state, doc)
+      return getCodeLens(state, doc.storage)
     },
 
     async diagnostics(kinds?: DiagnosticKind[]) {
@@ -157,7 +157,7 @@ async function createLanguageDocument(
         }
       }
 
-      return doValidate(state, doc, kinds)
+      return doValidate(state, doc.storage, kinds)
     },
 
     async codeActions(range: Range, context: CodeActionContext) {
@@ -169,14 +169,14 @@ async function createLanguageDocument(
         context,
       }
 
-      return doCodeActions(state, params, doc)
+      return doCodeActions(state, params, doc.storage)
     },
 
     async completions(position: Position, ctx?: CompletionContext) {
       if (!state.enabled || !settings.tailwindCSS.suggestions) return null
 
       state.completionItemData.uri = doc.uri
-      return doComplete(state, doc, position, ctx)
+      return doComplete(state, doc.storage, position, ctx)
     },
 
     async resolveCompletion(item: CompletionItem) {

packages/tailwindcss-language-service/src/util/find.ts

@@ -138,7 +138,7 @@ export function findClassListsInCssRange(
   })
 }
 
-async function findCustomClassLists(
+export async function findCustomClassLists(
   state: State,
   doc: TextDocument,
   range?: Range,