overview documentation of the extension

apps/lsp/src/custom.ts

@@ -31,7 +31,8 @@ import { Hover, Position, TextDocuments } from "vscode-languageserver";
 import { CodeViewCellContext, CodeViewCompletionContext, kCodeViewAssist, kCodeViewGetDiagnostics, kCodeViewGetCompletions, LintItem } from "editor-types";
 import { yamlCompletions } from "./service/providers/completion/completion-yaml";
 import { yamlHover } from "./service/providers/hover/hover-yaml";
-import { EditorContext, Quarto, codeEditorContext } from "./service/quarto";
+import { EditorContext, codeEditorContext } from "./service/quarto";
+import { Quarto } from "./quarto";
 
 export function registerCustomMethods(
   quarto: Quarto,

apps/lsp/src/index.ts

@@ -257,6 +257,7 @@ connection.onInitialized(async () => {
   const parser = markdownitParser();
 
   // create language service
+  // note that `mdLs` is referenced in `connection.onInitialize` above
   mdLs = createLanguageService({
     config,
     quarto,

apps/lsp/src/quarto.ts

@@ -31,7 +31,6 @@ import {
 import { QuartoContext } from "quarto-core";
 
 import {
-  Quarto,
   CompletionResult,
   EditorContext,
   HoverResult,
@@ -42,6 +41,16 @@ import {
 } from "./service/quarto";
 import { LintItem } from "editor-types";
 
+export interface Quarto extends QuartoContext {
+  getYamlCompletions(context: EditorContext): Promise<CompletionResult>;
+  getAttrCompletions(
+    token: AttrToken,
+    context: EditorContext
+  ): Promise<CompletionItem[]>;
+  getYamlDiagnostics(context: EditorContext): Promise<LintItem[]>;
+  getHover?: (context: EditorContext) => Promise<HoverResult | null>;
+}
+
 export async function initializeQuarto(context: QuartoContext): Promise<Quarto> {
   const quartoModule = await initializeQuartoYamlModule(context.resourcePath) as QuartoYamlModule;
   return {

apps/lsp/src/service/index.ts

@@ -17,7 +17,7 @@
 import type { CancellationToken, CompletionContext, TextDocuments } from 'vscode-languageserver';
 import * as lsp from 'vscode-languageserver-types';
 import { URI } from 'vscode-uri';
-import { Document, Parser } from "quarto-core"
+import { Document, Parser } from "quarto-core";
 import { LsConfiguration } from './config';
 import { MdDefinitionProvider } from './providers/definitions';
 import { DiagnosticComputer, DiagnosticOnSaveComputer, DiagnosticOptions, DiagnosticsManager, IPullDiagnosticsManager } from './providers/diagnostics';
@@ -33,7 +33,7 @@ import { MdTableOfContentsProvider } from './toc';
 import { isWorkspaceWithFileWatching, IWorkspace } from './workspace';
 import { MdHoverProvider } from './providers/hover/hover';
 import { MdCompletionProvider } from './providers/completion/completion';
-import { Quarto } from './quarto';
+import { Quarto } from '../quarto';
 
 export { IncludeWorkspaceHeaderCompletions } from './providers/completion/completion';
 export type { MdCompletionProvider } from './providers/completion/completion';
@@ -44,7 +44,7 @@ export { DiagnosticCode, DiagnosticLevel } from './providers/diagnostics';
 export type { ResolvedDocumentLinkTarget } from './providers/document-links';
 export type { ILogger } from './logging';
 export { LogLevel } from './logging';
-export type { ISlugifier } from './slugify'
+export type { ISlugifier } from './slugify';
 export { Slug, pandocSlugifier } from './slugify';
 export type { ContainingDocumentContext, FileStat, FileWatcherOptions, IFileSystemWatcher, IWorkspace, IWorkspaceWithWatching } from './workspace';
 
@@ -84,7 +84,7 @@ export interface IMdLanguageService {
    *
    * @returns The headers and optionally also the link definitions in the file
    */
-  getDocumentSymbols(document: Document, options: { readonly includeLinkDefinitions?: boolean }, token: CancellationToken): Promise<lsp.DocumentSymbol[]>;
+  getDocumentSymbols(document: Document, options: { readonly includeLinkDefinitions?: boolean; }, token: CancellationToken): Promise<lsp.DocumentSymbol[]>;
 
   /**
    * Get the folding ranges of a markdown file.
@@ -238,7 +238,7 @@ export function createLanguageService(init: LanguageServiceInitialization): IMdL
       return documentHighlightProvider.getDocumentHighlights(document, position, token);
     },
     computeOnSaveDiagnostics: async (doc: Document) => {
-      return (await diagnosticOnSaveComputer.compute(doc))
+      return (await diagnosticOnSaveComputer.compute(doc));
     },
     computeDiagnostics: async (doc: Document, options: DiagnosticOptions, token: CancellationToken): Promise<lsp.Diagnostic[]> => {
       return (await diagnosticsComputer.compute(doc, options, token))?.diagnostics;

apps/lsp/src/service/providers/completion/completion-attrs.ts

@@ -13,7 +13,8 @@
  *
  */
 
-import { AttrContext, AttrToken, EditorContext, Quarto } from "../../quarto";
+import { AttrContext, AttrToken, EditorContext } from "../../quarto";
+import { Quarto } from "../../../quarto";
 
 export async function attrCompletions(quarto: Quarto, context: EditorContext) {
 

apps/lsp/src/service/providers/completion/completion-yaml.ts

@@ -25,7 +25,8 @@ import {
 } from "vscode-languageserver-types";
 
 
-import { EditorContext, Quarto } from "../../quarto";
+import { EditorContext } from "../../quarto";
+import { Quarto } from "../../../quarto";
 
 export async function yamlCompletions(quarto: Quarto, context: EditorContext, stripPadding: boolean) {
 
@@ -67,7 +68,7 @@ export async function yamlCompletions(quarto: Quarto, context: EditorContext, st
               .replace(/(<([^>]+)>)/gi, "")
               .replace(/\n/g, " ")
           )
-        }
+        };
       }
 
       // strip padding if requested (vscode doesn't seem to need indentation padding)

apps/lsp/src/service/providers/completion/completion.ts

@@ -23,7 +23,7 @@ import {
   CompletionTriggerKind,
   TextDocuments
 } from "vscode-languageserver";
-import { Quarto } from "../../quarto";
+import { Quarto } from "../../../quarto";
 import { attrCompletions } from "./completion-attrs";
 import { latexCompletions } from "./completion-latex";
 import { yamlCompletions } from "./completion-yaml";

apps/lsp/src/service/providers/completion/refs/completion-biblio.ts

@@ -21,7 +21,7 @@ import {
 import { cslRefs } from "editor-server";
 
 import { Document, Parser, filePathForDoc, documentFrontMatter } from "quarto-core";
-import { Quarto } from "../../../quarto";
+import { Quarto } from "../../../../quarto";
 
 export async function biblioCompletions(
   quarto: Quarto,

apps/lsp/src/service/providers/completion/refs/completion-crossref.ts

@@ -23,7 +23,7 @@ import {
 import { XRef } from "editor-types";
 
 import { EditorServerDocuments, xrefsForFile } from "editor-server";
-import { Quarto } from "../../../quarto";
+import { Quarto } from "../../../../quarto";
 
 export async function crossrefCompletions(
   quarto: Quarto,

apps/lsp/src/service/providers/completion/refs/completion-refs.ts

@@ -18,7 +18,8 @@ import { Range, Position } from "vscode-languageserver-types";
 import { CompletionItem, TextDocuments } from "vscode-languageserver";
 import { bypassRefIntelligence } from "../../../util/refs";
 
-import { EditorContext, Quarto } from "../../../quarto";
+import { EditorContext } from "../../../quarto";
+import { Quarto } from "../../../../quarto";
 import { projectDirForDocument, filePathForDoc, Document, Parser } from "quarto-core";
 import { biblioCompletions } from "./completion-biblio";
 import { crossrefCompletions } from "./completion-crossref";

apps/lsp/src/service/providers/diagnostics-yaml.ts

@@ -24,9 +24,9 @@ import {
 import { Document } from "quarto-core";
 
 import {
-  Quarto,
   docEditorContext
 } from "../quarto";
+import { Quarto } from "../../quarto";
 import { kEndColumn, kEndRow, kStartColumn, kStartRow, LintItem } from "editor-types";
 
 export async function provideYamlDiagnostics(

apps/lsp/src/service/providers/diagnostics.ts

@@ -31,7 +31,7 @@ import { ResourceMap } from '../util/resource-maps';
 import { FileStat, IWorkspace, IWorkspaceWithWatching, statLinkToMarkdownFile } from '../workspace';
 import { HrefKind, InternalHref, LinkDefinitionSet, MdLink, MdLinkDefinition, MdLinkKind, MdLinkProvider, MdLinkSource, parseLocationInfoFromFragment, ReferenceLinkMap } from './document-links';
 import { ILogger, LogLevel } from '../logging';
-import { Quarto } from '../quarto';
+import { Quarto } from '../../quarto';
 import { provideYamlDiagnostics } from './diagnostics-yaml';
 
 /**
@@ -208,12 +208,12 @@ export class DiagnosticComputer {
   ): Promise<{
     readonly diagnostics: lsp.Diagnostic[];
     readonly links: readonly MdLink[];
-    readonly statCache: ResourceMap<{ readonly exists: boolean }>;
+    readonly statCache: ResourceMap<{ readonly exists: boolean; }>;
   }> {
     this.#logger.logDebug('DiagnosticComputer.compute', { document: doc.uri, version: doc.version });
 
     const { links, definitions } = await this.#linkProvider.getLinks(doc);
-    const statCache = new ResourceMap<{ readonly exists: boolean }>();
+    const statCache = new ResourceMap<{ readonly exists: boolean; }>();
     if (token.isCancellationRequested) {
       return { links, diagnostics: [], statCache };
     }
@@ -381,7 +381,7 @@ export class DiagnosticComputer {
   async #validateFileLinks(
     options: DiagnosticOptions,
     links: readonly MdLink[],
-    statCache: ResourceMap<{ readonly exists: boolean }>,
+    statCache: ResourceMap<{ readonly exists: boolean; }>,
     token: CancellationToken,
   ): Promise<lsp.Diagnostic[]> {
     const pathErrorSeverity = toSeverity(options.validateFileLinks);
@@ -551,8 +551,8 @@ class FileLinkState extends Disposable {
   /**
    * Set the known links in a markdown document, adding and removing file watchers as needed
    */
-  updateLinksForDocument(document: URI, links: readonly MdLink[], statCache: ResourceMap<{ readonly exists: boolean }>) {
-    const linkedToResource = new Set<{ path: URI; exists: boolean }>(
+  updateLinksForDocument(document: URI, links: readonly MdLink[], statCache: ResourceMap<{ readonly exists: boolean; }>) {
+    const linkedToResource = new Set<{ path: URI; exists: boolean; }>(
       links
         .filter(link => link.href.kind === HrefKind.Internal)
         .map(link => ({ path: (link.href as InternalHref).path, exists: !!(statCache.get((link.href as InternalHref).path)?.exists) })));
@@ -590,7 +590,7 @@ class FileLinkState extends Disposable {
     this.updateLinksForDocument(resource, [], new ResourceMap());
   }
 
-  public tryStatFileLink(link: URI): { exists: boolean } | undefined {
+  public tryStatFileLink(link: URI): { exists: boolean; } | undefined {
     const entry = this.#linkedToFile.get(link);
     if (!entry) {
       return undefined;

apps/lsp/src/service/providers/hover/hover-ref.ts

@@ -19,7 +19,7 @@ import { cslRefs, CslRef } from "editor-server";
 import { bypassRefIntelligence } from "../../util/refs";
 
 import { Document, Parser, filePathForDoc, documentFrontMatter } from "quarto-core";
-import { Quarto } from "../../quarto";
+import { Quarto } from "../../../quarto";
 
 
 // cache the last ref lookup

apps/lsp/src/service/providers/hover/hover-yaml.ts

@@ -15,7 +15,8 @@
 
 import { Hover, MarkupKind } from "vscode-languageserver";
 
-import { EditorContext, Quarto } from "../../quarto";
+import { EditorContext } from "../../quarto";
+import { Quarto } from "../../../quarto";
 
 export async function yamlHover(quarto: Quarto, context: EditorContext): Promise<Hover | null> {
   // bail if no quarto connection

apps/lsp/src/service/providers/hover/hover.ts

@@ -21,7 +21,7 @@ import { mathHover } from "./hover-math";
 import { refHover } from "./hover-ref";
 import { Document, Parser } from "quarto-core";
 import { LsConfiguration } from "../../config";
-import { Quarto } from "../../quarto";
+import { Quarto } from "../../../quarto";
 import { docEditorContext } from "../../quarto";
 import { IWorkspace } from "../../workspace";
 

apps/lsp/src/service/quarto.ts

@@ -13,12 +13,11 @@
  *
  */
 
-import { CompletionItem, Position } from "vscode-languageserver-types";
+import { Position } from "vscode-languageserver-types";
 
-import { QuartoContext, Document, filePathForDoc, isQuartoDoc, isQuartoRevealDoc, isQuartoYaml, isQuartoDashboardDoc } from "quarto-core";
+import { Document, filePathForDoc, isQuartoDoc, isQuartoRevealDoc, isQuartoYaml, isQuartoDashboardDoc } from "quarto-core";
 
 import { lines } from "core";
-import { LintItem } from "editor-types";
 
 export interface CompletionResult {
   token: string;
@@ -28,7 +27,7 @@ export interface CompletionResult {
 
 export interface HoverResult {
   content: string;
-  range: { start: Position; end: Position };
+  range: { start: Position; end: Position; };
 }
 
 export interface Completion {
@@ -78,17 +77,6 @@ export interface AttrToken {
   token: string;
 }
 
-export interface Quarto extends QuartoContext {
-  getYamlCompletions(context: EditorContext): Promise<CompletionResult>;
-  getAttrCompletions(
-    token: AttrToken,
-    context: EditorContext
-  ): Promise<CompletionItem[]>;
-  getYamlDiagnostics(context: EditorContext): Promise<LintItem[]>;
-  getHover?: (context: EditorContext) => Promise<HoverResult | null>;
-}
-
-
 export function codeEditorContext(
   path: string,
   filetype: string,
@@ -149,5 +137,5 @@ export function docEditorContext(
     false,
     explicit,
     trigger
-  )
+  );
 }