@spyglassmc/core 0.1.1 → 0.3.0

package/lib/service/Profiler.js

@@ -1,76 +1,112 @@
-"use strict";
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _ProfilerImpl_finalized, _ProfilerImpl_startTime, _ProfilerImpl_lastTime, _ProfilerImpl_tasks, _ProfilerImpl_longestTaskNameLength, _ProfilerFactory_enabledProfilers;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ProfilerFactory = void 0;
-const perf_hooks_1 = require("perf_hooks");
-const Logger_1 = require("./Logger");
+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;
+    #startTime;
+    #lastTime;
+    #tasks = [];
+    #longestTaskNameLength = 0;
     constructor(id, logger) {
         this.id = id;
         this.logger = logger;
-        _ProfilerImpl_finalized.set(this, false);
-        _ProfilerImpl_startTime.set(this, void 0);
-        _ProfilerImpl_lastTime.set(this, void 0);
-        _ProfilerImpl_tasks.set(this, []);
-        _ProfilerImpl_longestTaskNameLength.set(this, 0);
-        __classPrivateFieldSet(this, _ProfilerImpl_startTime, __classPrivateFieldSet(this, _ProfilerImpl_lastTime, perf_hooks_1.performance.now(), "f"), "f");
+        this.#startTime = this.#lastTime = performance.now();
     }
     task(name) {
-        if (__classPrivateFieldGet(this, _ProfilerImpl_finalized, "f")) {
+        if (this.#finalized) {
             throw new Error('The profiler is finalized.');
         }
-        const time = perf_hooks_1.performance.now();
-        __classPrivateFieldGet(this, _ProfilerImpl_tasks, "f").push([name, time - __classPrivateFieldGet(this, _ProfilerImpl_lastTime, "f")]);
-        __classPrivateFieldSet(this, _ProfilerImpl_lastTime, time, "f");
-        __classPrivateFieldSet(this, _ProfilerImpl_longestTaskNameLength, Math.max(__classPrivateFieldGet(this, _ProfilerImpl_longestTaskNameLength, "f"), name.length), "f");
-        this.logger.info(`[Profiler: ${this.id}] Done: ${name}`);
+        const time = performance.now();
+        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} in ${duration} ms`);
         return this;
     }
     finalize() {
-        __classPrivateFieldSet(this, _ProfilerImpl_finalized, true, "f");
-        __classPrivateFieldGet(this, _ProfilerImpl_tasks, "f").push([TotalTaskName, __classPrivateFieldGet(this, _ProfilerImpl_lastTime, "f") - __classPrivateFieldGet(this, _ProfilerImpl_startTime, "f")]);
-        __classPrivateFieldSet(this, _ProfilerImpl_longestTaskNameLength, Math.max(__classPrivateFieldGet(this, _ProfilerImpl_longestTaskNameLength, "f"), TotalTaskName.length), "f");
+        this.#finalized = true;
+        this.#tasks.push([TotalTaskName, this.#lastTime - this.#startTime]);
+        this.#longestTaskNameLength = Math.max(this.#longestTaskNameLength, TotalTaskName.length);
         this.logger.info(`[Profiler: ${this.id}] == Summary ==`);
-        for (const [name, time] of __classPrivateFieldGet(this, _ProfilerImpl_tasks, "f")) {
-            this.logger.info(`[Profiler: ${this.id}] ${name}${' '.repeat(__classPrivateFieldGet(this, _ProfilerImpl_longestTaskNameLength, "f") - name.length)} - ${time} ms`);
+        for (const [name, time] of this.#tasks) {
+            this.logger.info(`[Profiler: ${this.id}] ${name}${' '.repeat(this.#longestTaskNameLength - name.length)} - ${time} ms`);
         }
     }
 }
-_ProfilerImpl_finalized = new WeakMap(), _ProfilerImpl_startTime = new WeakMap(), _ProfilerImpl_lastTime = new WeakMap(), _ProfilerImpl_tasks = new WeakMap(), _ProfilerImpl_longestTaskNameLength = new WeakMap();
 class NoopImpl {
     task() { return this; }
     finalize() { }
 }
-class ProfilerFactory {
+export class ProfilerFactory {
+    logger;
+    #enabledProfilers;
     constructor(logger, enabledProfilers) {
         this.logger = logger;
-        _ProfilerFactory_enabledProfilers.set(this, void 0);
-        __classPrivateFieldSet(this, _ProfilerFactory_enabledProfilers, new Set(enabledProfilers), "f");
+        this.#enabledProfilers = new Set(enabledProfilers);
     }
-    get(id) {
-        if (__classPrivateFieldGet(this, _ProfilerFactory_enabledProfilers, "f").has(id)) {
-            return new ProfilerImpl(id, this.logger);
+    get(id, style = 'total', n) {
+        if (this.#enabledProfilers.has(id)) {
+            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();
         }
     }
     static noop() {
-        return new ProfilerFactory(Logger_1.Logger.noop(), []);
+        return new ProfilerFactory(Logger.noop(), []);
     }
 }
-exports.ProfilerFactory = ProfilerFactory;
-_ProfilerFactory_enabledProfilers = new WeakMap();
 //# sourceMappingURL=Profiler.js.map

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 { LanguageError } 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 {
@@ -50,48 +53,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 +120,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: '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;
     /**
      * Get all files that are tracked and supported.
      *
@@ -120,10 +152,16 @@ 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.
@@ -131,41 +169,31 @@ export declare class Project extends EventEmitter {
     close(): Promise<void>;
     restart(): Promise<void>;
     resetCache(): void;
-    /**
-     * @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;
+    normalizeUri(uri: string): string;
+    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;