@spyglassmc/core 0.2.0 → 0.3.0

package/lib/service/FileService.d.ts

@@ -1,7 +1,6 @@
-import type { Externals } from '../common/index.js';
+import type { Externals, Logger } from '../common/index.js';
 import type { Dependency } from './Dependency.js';
 import type { RootUriString } from './fileUtil.js';
-import type { Logger } from './Logger.js';
 export interface UriProtocolSupporter {
     /**
      * @throws

package/lib/service/MetaRegistry.d.ts

@@ -1,15 +1,15 @@
+import type { Logger } from '../common/index.js';
 import { Lazy } from '../common/index.js';
 import type { AstNode } from '../node/index.js';
 import type { Parser } from '../parser/index.js';
 import type { Formatter } from '../processor/formatter/index.js';
-import type { Checker, Colorizer, Completer, InlayHintProvider } from '../processor/index.js';
+import type { Binder, Checker, Colorizer, Completer, InlayHintProvider } from '../processor/index.js';
 import type { Linter } from '../processor/linter/Linter.js';
 import type { SignatureHelpProvider } from '../processor/SignatureHelpProvider.js';
-import type { UriBinder } from '../symbol/index.js';
 import type { DependencyKey, DependencyProvider } from './Dependency.js';
 import type { FileExtension } from './fileUtil.js';
-import type { Logger } from './Logger.js';
 import type { SymbolRegistrar } from './SymbolRegistrar.js';
+import type { UriBinder, UriSorter, UriSorterRegistration } from './UriProcessor.js';
 export interface LanguageOptions {
     /**
      * An array of extensions of files corresponding to the language. Each extension should include the leading dot (`.`).
@@ -58,6 +58,9 @@ export declare class MetaRegistry {
      * @returns The language ID registered for the file extension, or `undefined`.
      */
     getLanguageID(fileExtension: FileExtension): string | undefined;
+    hasBinder<N extends AstNode>(type: N['type']): boolean;
+    getBinder<N extends AstNode>(type: N['type']): Binder<N>;
+    registerBinder<N extends AstNode>(type: N['type'], binder: Binder<N>): void;
     hasChecker<N extends AstNode>(type: N['type']): boolean;
     getChecker<N extends AstNode>(type: N['type']): Checker<N>;
     registerChecker<N extends AstNode>(type: N['type'], checker: Checker<N>): void;
@@ -101,6 +104,8 @@ export declare class MetaRegistry {
     get symbolRegistrars(): Map<string, SymbolRegistrarRegistration>;
     registerUriBinder(uriBinder: UriBinder): void;
     get uriBinders(): Set<UriBinder>;
+    setUriSorter(uriSorter: UriSorterRegistration): void;
+    get uriSorter(): UriSorter;
 }
 export {};
 //# sourceMappingURL=MetaRegistry.d.ts.map

package/lib/service/MetaRegistry.js

@@ -1,5 +1,5 @@
 import { Lazy } from '../common/index.js';
-import { checker, colorizer, completer, formatter, linter } from '../processor/index.js';
+import { binder, checker, colorizer, completer, formatter, linter } from '../processor/index.js';
 /* istanbul ignore next */
 /**
  * The meta registry of Spyglass. You can register new parsers, processors, and languages here.
@@ -9,6 +9,7 @@ export class MetaRegistry {
      * A map from language IDs to language options.
      */
     #languages = new Map();
+    #binders = new Map();
     #checkers = new Map();
     #colorizers = new Map();
     #completers = new Map();
@@ -20,7 +21,9 @@ export class MetaRegistry {
     #signatureHelpProviders = new Set();
     #symbolRegistrars = new Map();
     #uriBinders = new Set();
+    #uriSorter = () => 0;
     constructor() {
+        binder.registerBinders(this);
         checker.registerCheckers(this);
         colorizer.registerColorizers(this);
         completer.registerCompleters(this);
@@ -68,6 +71,15 @@ export class MetaRegistry {
         }
         return undefined;
     }
+    hasBinder(type) {
+        return this.#binders.has(type);
+    }
+    getBinder(type) {
+        return this.#binders.get(type) ?? binder.fallback;
+    }
+    registerBinder(type, binder) {
+        this.#binders.set(type, binder);
+    }
     hasChecker(type) {
         return this.#checkers.has(type);
     }
@@ -177,5 +189,12 @@ export class MetaRegistry {
     get uriBinders() {
         return this.#uriBinders;
     }
+    setUriSorter(uriSorter) {
+        const nextSorter = this.#uriSorter;
+        this.#uriSorter = (a, b) => uriSorter(a, b, nextSorter);
+    }
+    get uriSorter() {
+        return this.#uriSorter;
+    }
 }
 //# sourceMappingURL=MetaRegistry.js.map

package/lib/service/Profiler.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from './Logger.js';
+import { Logger } from '../common/index.js';
 /**
  * @example
  * ```typescript
@@ -27,7 +27,8 @@ export declare class ProfilerFactory {
     #private;
     private readonly logger;
     constructor(logger: Logger, enabledProfilers: string[]);
-    get(id: string): Profiler;
+    get(id: string, style: 'top-n', n: number): Profiler;
+    get(id: string, style?: 'total'): Profiler;
     static noop(): ProfilerFactory;
 }
 //# sourceMappingURL=Profiler.d.ts.map

package/lib/service/Profiler.js

@@ -1,6 +1,53 @@
-import { Logger } from './Logger.js';
+import { Dev, Logger } from '../common/index.js';
+class TopNImpl {
+    id;
+    logger;
+    n;
+    #finalized = false;
+    #startTime;
+    #lastTime;
+    #taskCount = 0;
+    #topTasks = [];
+    #minTime = Infinity;
+    #maxTime = 0;
+    constructor(id, logger, n) {
+        this.id = id;
+        this.logger = logger;
+        this.n = n;
+        this.#startTime = this.#lastTime = performance.now();
+    }
+    task(name) {
+        if (this.#finalized) {
+            throw new Error('The profiler has already been finalized');
+        }
+        this.#taskCount++;
+        const time = performance.now();
+        const duration = time - this.#lastTime;
+        this.#lastTime = time;
+        this.#minTime = Math.min(this.#minTime, duration);
+        this.#maxTime = Math.max(this.#maxTime, duration);
+        this.#topTasks.push([name, duration]);
+        this.#topTasks.sort((a, b) => b[1] - a[1]);
+        if (this.#topTasks.length > this.n) {
+            this.#topTasks = this.#topTasks.slice(0, -1);
+        }
+        return this;
+    }
+    finalize() {
+        this.#finalized = true;
+        const longestTaskNameLength = this.#topTasks.reduce((length, [name]) => Math.max(length, name.length), 0);
+        const totalDuration = this.#lastTime - this.#startTime;
+        this.logger.info(`[Profiler: ${this.id}] == Summary ==`);
+        this.logger.info(`[Profiler: ${this.id}] Total tasks: ${this.#taskCount} done in ${totalDuration} ms`);
+        this.logger.info(`[Profiler: ${this.id}] Min/Avg/Max: ${this.#minTime} / ${totalDuration / this.#taskCount} / ${this.#maxTime} ms`);
+        this.logger.info(`[Profiler: ${this.id}] Top ${Math.min(this.n, this.#topTasks.length)} task(s):`);
+        for (const [name, time] of this.#topTasks) {
+            this.logger.info(`[Profiler: ${this.id}] ${name}${' '.repeat(longestTaskNameLength - name.length)} - ${time} ms (${time / totalDuration * 100}%)`);
+        }
+    }
+}
 const TotalTaskName = 'Total';
-class ProfilerImpl {
+class TotalImpl {
     id;
     logger;
     #finalized = false;
@@ -18,10 +65,11 @@ class ProfilerImpl {
             throw new Error('The profiler is finalized.');
         }
         const time = performance.now();
-        this.#tasks.push([name, time - this.#lastTime]);
+        const duration = time - this.#lastTime;
         this.#lastTime = time;
+        this.#tasks.push([name, duration]);
         this.#longestTaskNameLength = Math.max(this.#longestTaskNameLength, name.length);
-        this.logger.info(`[Profiler: ${this.id}] Done: ${name}`);
+        this.logger.info(`[Profiler: ${this.id}] Done: ${name} in ${duration} ms`);
         return this;
     }
     finalize() {
@@ -45,9 +93,13 @@ export class ProfilerFactory {
         this.logger = logger;
         this.#enabledProfilers = new Set(enabledProfilers);
     }
-    get(id) {
+    get(id, style = 'total', n) {
         if (this.#enabledProfilers.has(id)) {
-            return new ProfilerImpl(id, this.logger);
+            switch (style) {
+                case 'top-n': return new TopNImpl(id, this.logger, n);
+                case 'total': return new TotalImpl(id, this.logger);
+                default: return Dev.assertNever(style);
+            }
         }
         else {
             return new NoopImpl();

package/lib/service/Project.d.ts

@@ -1,6 +1,7 @@
 import type { TextDocumentContentChangeEvent } from 'vscode-languageserver-textdocument';
 import { TextDocument } from 'vscode-languageserver-textdocument';
 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 { LanguageError } from '../source/index.js';
@@ -10,11 +11,12 @@ import type { Config } from './Config.js';
 import { Downloader } from './Downloader.js';
 import { FileService } from './FileService.js';
 import type { RootUriString } from './fileUtil.js';
-import { Logger } from './Logger.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 ProjectInitializer = (this: void, ctx: ProjectInitializerContext) => PromiseLike<Record<string, string> | void> | Record<string, string> | void;
+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;
@@ -51,9 +53,43 @@ interface SymbolRegistrarEvent {
     id: string;
     checksum: string | undefined;
 }
-export declare type ProjectData = Pick<Project, 'cacheRoot' | 'config' | 'downloader' | 'ensureParsedAndChecked' | 'externals' | 'fs' | 'get' | 'logger' | 'meta' | 'profilers' | 'projectRoot' | 'roots' | 'symbols' | 'ctx'>;
+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 implements ExternalEventEmitter {
     #private;
@@ -119,7 +155,13 @@ export declare class Project implements ExternalEventEmitter {
     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.
@@ -128,41 +170,30 @@ export declare class Project implements ExternalEventEmitter {
     restart(): Promise<void>;
     resetCache(): 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;