@spyglassmc/core 0.1.2 → 0.4.0

package/lib/service/Project.d.ts

@@ -1,32 +1,35 @@
-/// <reference types="node" />
-import EventEmitter from 'events';
 import type { TextDocumentContentChangeEvent } from 'vscode-languageserver-textdocument';
 import { TextDocument } from 'vscode-languageserver-textdocument';
-import type { AstNode } from '../node';
-import { FileNode } from '../node';
-import type { LanguageError } from '../source';
-import { SymbolUtil } from '../symbol';
-import { CacheService } from './CacheService';
-import type { Config } from './Config';
-import { Downloader } from './Downloader';
-import { FileService } from './FileService';
-import type { RootUriString } from './fileUtil';
-import { Logger } from './Logger';
-import { MetaRegistry } from './MetaRegistry';
-import { ProfilerFactory } from './Profiler';
-export declare type ProjectInitializerContext = Pick<Project, 'cacheRoot' | 'config' | 'downloader' | 'logger' | 'meta' | 'projectRoot'>;
-export declare type ProjectInitializer = (this: void, ctx: ProjectInitializerContext) => PromiseLike<Record<string, string> | void> | Record<string, string> | void;
-interface Options {
-    cacheRoot: string;
+import type { ExternalEventEmitter, Externals } from '../common/index.js';
+import { Logger } from '../common/index.js';
+import type { AstNode } from '../node/index.js';
+import { FileNode } from '../node/index.js';
+import type { PosRangeLanguageError } from '../source/index.js';
+import { SymbolUtil } from '../symbol/index.js';
+import { CacheService } from './CacheService.js';
+import type { Config } from './Config.js';
+import { Downloader } from './Downloader.js';
+import { FileService } from './FileService.js';
+import type { RootUriString } from './fileUtil.js';
+import { MetaRegistry } from './MetaRegistry.js';
+import { ProfilerFactory } from './Profiler.js';
+export declare type ProjectInitializerContext = Pick<Project, 'cacheRoot' | 'config' | 'downloader' | 'externals' | 'logger' | 'meta' | 'projectRoot'>;
+export declare type SyncProjectInitializer = (this: void, ctx: ProjectInitializerContext) => Record<string, string> | void;
+export declare type AsyncProjectInitializer = (this: void, ctx: ProjectInitializerContext) => PromiseLike<Record<string, string> | void>;
+export declare type ProjectInitializer = SyncProjectInitializer | AsyncProjectInitializer;
+export interface ProjectOptions {
+    cacheRoot: RootUriString;
+    defaultConfig?: Config;
     downloader?: Downloader;
+    externals: Externals;
     fs?: FileService;
     initializers?: readonly ProjectInitializer[];
     logger?: Logger;
     profilers?: ProfilerFactory;
     /**
-     * A file path to the root of this project.
+     * A file URI to the root of this project.
      */
-    projectPath: string;
+    projectRoot: RootUriString;
     symbols?: SymbolUtil;
 }
 export interface DocAndNode {
@@ -35,8 +38,10 @@ export interface DocAndNode {
 }
 interface DocumentEvent extends DocAndNode {
 }
-interface DocumentErrorEvent extends DocumentEvent {
-    errors: LanguageError[];
+interface DocumentErrorEvent {
+    errors: readonly PosRangeLanguageError[];
+    uri: string;
+    version?: number;
 }
 interface FileEvent {
     uri: string;
@@ -50,48 +55,56 @@ interface SymbolRegistrarEvent {
     id: string;
     checksum: string | undefined;
 }
-export declare type ProjectData = Pick<Project, 'cacheRoot' | 'config' | 'downloader' | 'ensureParsedAndChecked' | 'fs' | 'get' | 'logger' | 'meta' | 'profilers' | 'projectRoot' | 'roots' | 'symbols' | 'ctx'>;
-export declare namespace ProjectData {
-    function mock(data?: Partial<ProjectData>): ProjectData;
-}
-export interface Project extends EventEmitter {
-    on(event: 'documentErrorred', callbackFn: (data: DocumentErrorEvent) => void): this;
-    on(event: 'documentUpdated', callbackFn: (data: DocumentEvent) => void): this;
-    on(event: 'documentRemoved', callbackFn: (data: FileEvent) => void): this;
-    on(event: `file${'Created' | 'Modified' | 'Deleted'}`, callbackFn: (data: FileEvent) => void): this;
-    on(event: 'ready', callbackFn: (data: EmptyEvent) => void): this;
-    on(event: 'rootsUpdated', callbackFn: (data: RootsEvent) => void): this;
-    on(event: 'symbolRegistrarExecuted', callbackFn: (data: SymbolRegistrarEvent) => void): this;
-    once(event: 'documentErrorred', callbackFn: (data: DocumentErrorEvent) => void): this;
-    once(event: 'documentUpdated', callbackFn: (data: DocumentEvent) => void): this;
-    once(event: 'documentRemoved', callbackFn: (data: FileEvent) => void): this;
-    once(event: `file${'Created' | 'Modified' | 'Deleted'}`, callbackFn: (data: FileEvent) => void): this;
-    once(event: 'ready', callbackFn: (data: EmptyEvent) => void): this;
-    once(event: 'rootsUpdated', callbackFn: (data: RootsEvent) => void): this;
-    once(event: 'symbolRegistrarExecuted', callbackFn: (data: SymbolRegistrarEvent) => void): this;
-    emit(event: 'documentErrorred', data: DocumentErrorEvent): boolean;
-    emit(event: 'documentUpdated', data: DocumentEvent): boolean;
-    emit(event: 'documentRemoved', data: FileEvent): boolean;
-    emit(event: `file${'Created' | 'Modified' | 'Deleted'}`, data: FileEvent): boolean;
-    emit(event: 'ready', data: EmptyEvent): boolean;
-    emit(event: 'rootsUpdated', data: RootsEvent): boolean;
-    emit(event: 'symbolRegistrarExecuted', data: SymbolRegistrarEvent): boolean;
-}
+export declare type ProjectData = Pick<Project, 'cacheRoot' | 'config' | 'downloader' | 'ensureBindingStarted' | 'externals' | 'fs' | 'logger' | 'meta' | 'profilers' | 'projectRoot' | 'roots' | 'symbols' | 'ctx'>;
 /**
  * Manage all tracked documents and errors.
+ *
+ * The four stages of processing a document:
+ * 1. `read` - read the file from the external file system as a `TextDocument`.
+ * 2. `parse` - Parse the `TextDocument` into an `AstNode`.
+ * 3. `bind` - Bind the `AstNode` and populate both the global symbol table and the local symbol tables on the nodes.
+ * 4. `check` (includes `lint`) - Check the `AstNode` with information from the symbol tables.
+ *
+ * **Caching**
+ *
+ * The global symbol table along with a list of file URIs and checksums is cached in memory and is periodically saved to disk.
+ *
+ * The `TextDocument`s and file `AstNode`s (including their local symbol tables) managed by the client are stored in memory until the client sends a `didClose` notification.
+ *
+ * Some `TextDocument`s may be cached to avoid excessive reading from the file system.
+ *
+ * **INIT and READY**
+ *
+ * When a new instance of the {@link Project} class is constructed, its INIT and READY processes are immediately started in serial.
+ *
+ * During the INIT process of the project, the config and language feature initialization are processed.
+ * The Promise returned by the {@link init} function resolves when the INIT process is complete.
+ *
+ * During the READY process of the project, the whole project is analyzed mainly to populate the global symbol table.
+ * The Promise returned by the {@link ready} function resolves when the READY process is complete.
+ *
+ * The following generally happens during the READY process:
+ * 1. A list of file URIs under the project is obtained.
+ * 2. The global symbol cache, if available, is loaded and validated against the know list of files.
+ *    A list of files that need to be (re)processed is returned in this step.
+ * 3. For each files in the new list, the file is read, parsed, bound, and checked.
+ *
+ * **EDITING**
+ *
+ * After the READY process is complete, editing text documents as signaled by the client or the file watcher results in the file being re-processed.
  */
-export declare class Project extends EventEmitter {
+export declare class Project implements ExternalEventEmitter {
     #private;
     private static readonly RootSuffix;
     readonly cacheService: CacheService;
     get isReady(): boolean;
     config: Config;
     readonly downloader: Downloader;
+    readonly externals: Externals;
     readonly fs: FileService;
     readonly logger: Logger;
     readonly meta: MetaRegistry;
     readonly profilers: ProfilerFactory;
-    readonly projectPath: string;
     readonly projectRoot: RootUriString;
     symbols: SymbolUtil;
     /**
@@ -109,10 +122,31 @@ export declare class Project extends EventEmitter {
      */
     get ctx(): Record<string, string>;
     /**
-     * File path to a directory where all cache files of Spyglass should be stored.
+     * File URI to a directory where all cache files of Spyglass should be stored.
      */
-    get cacheRoot(): string;
+    get cacheRoot(): RootUriString;
     private updateRoots;
+    on(event: 'documentErrored', callbackFn: (data: DocumentErrorEvent) => void): this;
+    on(event: 'documentUpdated', callbackFn: (data: DocumentEvent) => void): this;
+    on(event: 'documentRemoved', callbackFn: (data: FileEvent) => void): this;
+    on(event: `file${'Created' | 'Modified' | 'Deleted'}`, callbackFn: (data: FileEvent) => void): this;
+    on(event: 'ready', callbackFn: (data: EmptyEvent) => void): this;
+    on(event: 'rootsUpdated', callbackFn: (data: RootsEvent) => void): this;
+    on(event: 'symbolRegistrarExecuted', callbackFn: (data: SymbolRegistrarEvent) => void): this;
+    once(event: 'documentErrored', callbackFn: (data: DocumentErrorEvent) => void): this;
+    once(event: 'documentUpdated', callbackFn: (data: DocumentEvent) => void): this;
+    once(event: 'documentRemoved', callbackFn: (data: FileEvent) => void): this;
+    once(event: `file${'Created' | 'Modified' | 'Deleted'}`, callbackFn: (data: FileEvent) => void): this;
+    once(event: 'ready', callbackFn: (data: EmptyEvent) => void): this;
+    once(event: 'rootsUpdated', callbackFn: (data: RootsEvent) => void): this;
+    once(event: 'symbolRegistrarExecuted', callbackFn: (data: SymbolRegistrarEvent) => void): this;
+    emit(event: 'documentErrored', data: DocumentErrorEvent): boolean;
+    emit(event: 'documentUpdated', data: DocumentEvent): boolean;
+    emit(event: 'documentRemoved', data: FileEvent): boolean;
+    emit(event: `file${'Created' | 'Modified' | 'Deleted'}`, data: FileEvent): boolean;
+    emit(event: 'ready', data: EmptyEvent): boolean;
+    emit(event: 'rootsUpdated', data: RootsEvent): boolean;
+    emit(event: 'symbolRegistrarExecuted', data: SymbolRegistrarEvent): boolean;
     /**
      * Get all files that are tracked and supported.
      *
@@ -120,53 +154,48 @@ export declare class Project extends EventEmitter {
      * are not loaded into the memory.
      */
     getTrackedFiles(): string[];
-    constructor({ cacheRoot, downloader, fs, initializers, logger, profilers, projectPath, }: Options);
+    constructor({ cacheRoot, defaultConfig, downloader, externals, fs, initializers, logger, profilers, projectRoot, }: ProjectOptions);
     private setInitPromise;
     private setReadyPromise;
+    /**
+     * Load the config file and initialize parsers and processors.
+     */
     init(): Promise<this>;
+    /**
+     * Finish the initial run of parsing, binding, and checking the entire project.
+     */
     ready(): Promise<this>;
     /**
      * Behavior of the `Project` instance is undefined after this function has settled.
      */
     close(): Promise<void>;
     restart(): Promise<void>;
-    resetCache(): void;
+    resetCache(): Promise<void>;
     normalizeUri(uri: string): string;
-    /**
-     * @returns The language ID of the file, or the file extension without the leading dot.
-     */
-    private getLanguageID;
-    /**
-     * @returns The cached `TextDocument` and `AstNode` for the URI, or `undefined` when such data isn't available in cache.
-     */
-    get(uri: string): DocAndNode | undefined;
-    /**
-     * @throws FS-related errors
-     */
-    ensureParsed(uri: string): Promise<DocAndNode | undefined>;
-    private parseAndCache;
+    private static readonly TextDocumentCacheMaxLength;
+    private removeCachedTextDocument;
+    private read;
     private parse;
-    private cache;
+    private bind;
     private check;
-    ensureChecked(doc: TextDocument, node: FileNode<AstNode>): Promise<void>;
     private lint;
-    ensureLinted(doc: TextDocument, node: FileNode<AstNode>): void;
-    ensureParsedAndChecked(uri: string): Promise<DocAndNode | undefined>;
-    ensureParsedAndCheckedOnlyWhenReady(uri: string): Promise<DocAndNode | undefined>;
-    private bind;
+    ensureBindingStarted(uri: string): Promise<void>;
+    private bindUri;
     /**
      * Notify that a new document was opened in the editor.
      */
-    onDidOpen(uri: string, languageID: string, version: number, content: string): void;
+    onDidOpen(uri: string, languageID: string, version: number, content: string): Promise<void>;
     /**
      * Notify that an existing document was changed in the editor.
      * @throws If there is no `TextDocument` corresponding to the URI.
      */
-    onDidChange(uri: string, changes: TextDocumentContentChangeEvent[], version: number): void;
+    onDidChange(uri: string, changes: TextDocumentContentChangeEvent[], version: number): Promise<void>;
     /**
      * Notify that an existing document was closed in the editor.
      */
     onDidClose(uri: string): void;
+    ensureClientManagedChecked(uri: string): Promise<DocAndNode | undefined>;
+    getClientManaged(uri: string): DocAndNode | undefined;
     showCacheRoot(): Promise<void>;
     private tryClearingCache;
     private shouldRemove;