@spyglassmc/core 0.4.43 → 0.4.45

package/lib/common/UriStore.d.ts

@@ -0,0 +1,43 @@
+import type { RootUriString } from '../service/index.js';
+/**
+ * Stores a collection of URIs in a trie. Each file URI can optionally have a metadata associated
+ * with it. No actual file system I/O is performed by this class.
+ */
+export declare class UriStore {
+    #private;
+    /**
+     * Adds a file URI or a directory URI to the store.
+     * Directory URIs must end with a slash (`/`), otherwise it will be treated as a file URI.
+     */
+    add(uri: string): void;
+    /**
+     * Returns true if the specified URI exists in the store and is of the expected type.
+     * Directory URIs must end with a slash (`/`), otherwise it will be treated as a file URI.
+     */
+    has(uri: string): boolean;
+    /**
+     * Deletes a URI from the store if it exists.
+     * For directories, all sub URIs under them will be recursively removed.
+     */
+    delete(uri: string): void;
+    /**
+     * Returns names of all direct children of the URI.
+     * An empty result is generated if the directory URI does not exist.
+     */
+    getChildrenNames(uri: RootUriString): Generator<string>;
+    /**
+     * Returns URIs of all files under a directory and its subdirectories.
+     * An empty result is generated if the directory URI does not exist.
+     */
+    getSubFiles(uri: RootUriString): Generator<string>;
+    /**
+     * Removes all URIs from the store.
+     */
+    clear(): void;
+    /**
+     * Creates a deep copy of this store.
+     */
+    clone(): UriStore;
+    [Symbol.iterator](): Generator<string, any, any>;
+}
+//# sourceMappingURL=UriStore.d.ts.map

package/lib/common/UriStore.js

@@ -0,0 +1,166 @@
+import { normalizeUriPathname, Uri } from './util.js';
+/**
+ * Stores a collection of URIs in a trie. Each file URI can optionally have a metadata associated
+ * with it. No actual file system I/O is performed by this class.
+ */
+export class UriStore {
+    #trie = new Map();
+    /**
+     * Adds a file URI or a directory URI to the store.
+     * Directory URIs must end with a slash (`/`), otherwise it will be treated as a file URI.
+     */
+    add(uri) {
+        const [parts, isDir] = this.#dissectUri(uri);
+        let node = this.#trie;
+        for (const [i, part] of parts.entries()) {
+            const isLast = i === parts.length - 1;
+            const shouldAddDir = !isLast || isDir;
+            if (!node.has(part)) {
+                node.set(part, shouldAddDir ? new Map() : {});
+            }
+            if (!isLast) {
+                const next = node.get(part);
+                if (next instanceof Map) {
+                    node = next;
+                }
+                else {
+                    throw new Error(`Cannot add '${uri}' because ${parts.slice(0, i + 1).join('/')} is a file`);
+                }
+            }
+        }
+    }
+    /**
+     * Returns true if the specified URI exists in the store and is of the expected type.
+     * Directory URIs must end with a slash (`/`), otherwise it will be treated as a file URI.
+     */
+    has(uri) {
+        const [parts, isDir] = this.#dissectUri(uri);
+        let node = this.#trie;
+        for (const part of parts) {
+            if (!(node instanceof Map)) {
+                return false;
+            }
+            node = node.get(part);
+        }
+        return isDir
+            ? node instanceof Map
+            : !!node && typeof node === 'object' && !(node instanceof Map);
+    }
+    /**
+     * Deletes a URI from the store if it exists.
+     * For directories, all sub URIs under them will be recursively removed.
+     */
+    delete(uri) {
+        const [parts, _isDir] = this.#dissectUri(uri);
+        let node = this.#trie;
+        for (const [i, part] of parts.entries()) {
+            if (!(node instanceof Map)) {
+                return;
+            }
+            if (i === parts.length - 1) {
+                node.delete(part);
+            }
+            else {
+                node = node.get(part);
+            }
+        }
+    }
+    /**
+     * Returns names of all direct children of the URI.
+     * An empty result is generated if the directory URI does not exist.
+     */
+    *getChildrenNames(uri) {
+        const [parts, _isDir] = this.#dissectUri(uri);
+        let node = this.#trie;
+        for (const part of parts) {
+            if (!(node instanceof Map)) {
+                return;
+            }
+            node = node.get(part);
+        }
+        if (!(node instanceof Map)) {
+            return;
+        }
+        yield* node.keys();
+    }
+    /**
+     * Returns URIs of all files under a directory and its subdirectories.
+     * An empty result is generated if the directory URI does not exist.
+     */
+    *getSubFiles(uri) {
+        const [parts, _isDir] = this.#dissectUri(uri);
+        let node = this.#trie;
+        for (const part of parts) {
+            if (!(node instanceof Map)) {
+                return;
+            }
+            node = node.get(part);
+        }
+        if (!(node instanceof Map)) {
+            return;
+        }
+        yield* this.#collect(node, parts);
+    }
+    /**
+     * Removes all URIs from the store.
+     */
+    clear() {
+        this.#trie.clear();
+    }
+    /**
+     * Creates a deep copy of this store.
+     */
+    clone() {
+        const clonedStore = new UriStore();
+        clonedStore.#trie = structuredClone(this.#trie);
+        return clonedStore;
+    }
+    [Symbol.iterator]() {
+        return this.#collect(this.#trie, []);
+    }
+    /**
+     * Dissects a URI string into parts that can be used as edges in the trie.
+     */
+    #dissectUri(uriString) {
+        const uri = new Uri(uriString);
+        const isDir = uriString.endsWith('/');
+        const parts = [
+            uri.protocol,
+            uri.host || 'localhost',
+            ...normalizeUriPathname(uri.pathname).split('/')
+                // Filter out empty segments
+                .filter((p) => p)
+                .map(decodeURIComponent),
+        ];
+        return [parts, isDir];
+    }
+    /**
+     * Reconstructs a URI string from its parts.
+     *
+     * This is the inverse of `#dissectUri`.
+     * It handles special cases like omitting the host when it's 'localhost' and adding a trailing
+     * slash for directory URIs.
+     */
+    #buildUri(parts, isDir) {
+        const [protocol, host, ...segments] = parts;
+        const pathname = normalizeUriPathname(`/${segments.map(encodeURIComponent).join('/')}`);
+        const trailingSlash = isDir && segments.length ? '/' : '';
+        return `${protocol}//${host === 'localhost' ? '' : host}${pathname}${trailingSlash}`;
+    }
+    /**
+     * Returns a generator that yields all URIs under a DirectoryNode recursively.
+     * @param currentParts Parts corresponding to the URI of the DirectoryNode.
+     */
+    *#collect(node, currentParts) {
+        for (const [key, value] of node) {
+            const nextParts = [...currentParts, key];
+            if (value instanceof Map) {
+                yield* this.#collect(value, nextParts);
+            }
+            else {
+                yield this.#buildUri(nextParts, false);
+            }
+        }
+    }
+}
+//# sourceMappingURL=UriStore.js.map

package/lib/common/externals/BrowserExternals.js

@@ -35,21 +35,7 @@ export class BrowserEventEmitter {
         return this;
     }
 }
-class BrowserFsWatcher {
-    on(event, listener) {
-        if (event === 'ready') {
-            listener();
-        }
-        return this;
-    }
-    once(event, listener) {
-        if (event === 'ready') {
-            listener();
-        }
-        return this;
-    }
-    async close() { }
-}
+// TODO: Use Origin Private File System (OPFS) instead
 class BrowserFileSystem {
     static LocalStorageKey = 'spyglassmc-browser-fs';
     states;
@@ -85,6 +71,9 @@ class BrowserFileSystem {
         }
         return new Uint8Array(arrayBufferFromBase64(entry.content));
     }
+    async rm(_location, _options) {
+        throw new Error('Not implemented');
+    }
     async showFile(_path) {
         throw new Error('showFile not supported on browser');
     }
@@ -94,7 +83,11 @@ class BrowserFileSystem {
         if (!entry) {
             throw new Error(`ENOENT: ${location}`);
         }
-        return { isDirectory: () => entry.type === 'directory', isFile: () => entry.type === 'file' };
+        return {
+            isDirectory: () => entry.type === 'directory',
+            isFile: () => entry.type === 'file',
+            isSymbolicLink: () => false,
+        };
     }
     async unlink(location) {
         location = location.toString();
@@ -105,9 +98,6 @@ class BrowserFileSystem {
         delete this.states[location];
         this.saveStates();
     }
-    watch(_locations) {
-        return new BrowserFsWatcher();
-    }
     async writeFile(location, data, _options) {
         location = location.toString();
         if (typeof data === 'string') {

package/lib/common/externals/NodeJsExternals.d.ts

@@ -1,10 +1,10 @@
-import chokidar from 'chokidar';
 import { EventEmitter } from 'node:events';
-import fs from 'node:fs';
+import fs, { promises as fsp } from 'node:fs';
 import type { DecompressedFile, RootUriString } from '../../index.js';
-import type { FsLocation, FsWatcher } from './index.js';
-export declare function getNodeJsExternals({ cacheRoot }?: {
+import type { FsLocation } from './index.js';
+export declare function getNodeJsExternals({ cacheRoot, nodeFsp }?: {
     cacheRoot?: RootUriString;
+    nodeFsp?: typeof fsp;
 }): Readonly<{
     archive: {
         decompressBall(buffer: Uint8Array<ArrayBuffer>, options: {
@@ -31,12 +31,12 @@ export declare function getNodeJsExternals({ cacheRoot }?: {
         } | undefined): Promise<undefined>;
         readdir(location: FsLocation): Promise<fs.Dirent<string>[]>;
         readFile(location: FsLocation): Promise<NonSharedBuffer>;
+        rm(location: FsLocation, options: {
+            recursive?: boolean;
+        } | undefined): Promise<void>;
         showFile(location: FsLocation): Promise<void>;
         stat(location: FsLocation): Promise<fs.Stats>;
         unlink(location: FsLocation): Promise<void>;
-        watch(locations: FsLocation[], { usePolling }?: {
-            usePolling?: boolean;
-        }): ChokidarWatcherWrapper;
         writeFile(location: FsLocation, data: string | Uint8Array<ArrayBuffer>, options: {
             mode: number;
         } | undefined): Promise<void>;
@@ -72,12 +72,12 @@ export declare const NodeJsExternals: Readonly<{
         } | undefined): Promise<undefined>;
         readdir(location: FsLocation): Promise<fs.Dirent<string>[]>;
         readFile(location: FsLocation): Promise<NonSharedBuffer>;
+        rm(location: FsLocation, options: {
+            recursive?: boolean;
+        } | undefined): Promise<void>;
         showFile(location: FsLocation): Promise<void>;
         stat(location: FsLocation): Promise<fs.Stats>;
         unlink(location: FsLocation): Promise<void>;
-        watch(locations: FsLocation[], { usePolling }?: {
-            usePolling?: boolean;
-        }): ChokidarWatcherWrapper;
         writeFile(location: FsLocation, data: string | Uint8Array<ArrayBuffer>, options: {
             mode: number;
         } | undefined): Promise<void>;
@@ -87,11 +87,6 @@ export declare const NodeJsExternals: Readonly<{
         getCache: () => Promise<HttpCache>;
     };
 }>;
-declare class ChokidarWatcherWrapper extends EventEmitter implements FsWatcher {
-    #private;
-    constructor(watcher: chokidar.FSWatcher);
-    close(): Promise<void>;
-}
 /**
  * A non-spec-compliant, non-complete implementation of the Cache Web API for use in Spyglass.
  * This class stores the cached response on the file system under the cache root.

package/lib/common/externals/NodeJsExternals.js

@@ -1,5 +1,3 @@
-// https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/60592
-import chokidar from 'chokidar';
 import decompress from 'decompress';
 import { Buffer } from 'node:buffer';
 import cp from 'node:child_process';
@@ -12,10 +10,9 @@ import stream from 'node:stream';
 import url from 'node:url';
 import { promisify } from 'node:util';
 import zlib from 'node:zlib';
-import { Uri } from '../util.js';
 const gunzip = promisify(zlib.gunzip);
 const gzip = promisify(zlib.gzip);
-export function getNodeJsExternals({ cacheRoot } = {}) {
+export function getNodeJsExternals({ cacheRoot, nodeFsp = fsp } = {}) {
     return Object.freeze({
         archive: {
             decompressBall(buffer, options) {
@@ -51,19 +48,22 @@ export function getNodeJsExternals({ cacheRoot } = {}) {
         event: { EventEmitter },
         fs: {
             chmod(location, mode) {
-                return fsp.chmod(toFsPathLike(location), mode);
+                return nodeFsp.chmod(toFsPathLike(location), mode);
             },
             async mkdir(location, options) {
-                return void (await fsp.mkdir(toFsPathLike(location), options));
+                return void (await nodeFsp.mkdir(toFsPathLike(location), options));
             },
             readdir(location) {
-                return fsp.readdir(toFsPathLike(location), {
+                return nodeFsp.readdir(toFsPathLike(location), {
                     encoding: 'utf-8',
                     withFileTypes: true,
                 });
             },
             readFile(location) {
-                return fsp.readFile(toFsPathLike(location));
+                return nodeFsp.readFile(toFsPathLike(location));
+            },
+            rm(location, options) {
+                return nodeFsp.rm(toFsPathLike(location), options);
             },
             async showFile(location) {
                 const execFile = promisify(cp.execFile);
@@ -82,19 +82,13 @@ export function getNodeJsExternals({ cacheRoot } = {}) {
                 return void (await execFile(command, [toPath(location)]));
             },
             stat(location) {
-                return fsp.stat(toFsPathLike(location));
+                return nodeFsp.stat(toFsPathLike(location));
             },
             unlink(location) {
-                return fsp.unlink(toFsPathLike(location));
-            },
-            watch(locations, { usePolling = false } = {}) {
-                return new ChokidarWatcherWrapper(chokidar.watch(locations.map(toPath), {
-                    usePolling,
-                    disableGlobbing: true,
-                }));
+                return nodeFsp.unlink(toFsPathLike(location));
             },
             writeFile(location, data, options) {
-                return fsp.writeFile(toFsPathLike(location), data, options);
+                return nodeFsp.writeFile(toFsPathLike(location), data, options);
             },
         },
         web: {
@@ -110,11 +104,6 @@ export const NodeJsExternals = getNodeJsExternals();
  * @returns A {@link fs.PathLike}.
  */
 function toFsPathLike(path) {
-    if (path instanceof Uri) {
-        // Convert WHATWG URL to string so that it will be converted
-        // to Node.js URL by the next if-block.
-        path = path.toString();
-    }
     if (typeof path === 'string' && path.startsWith('file:')) {
         return new url.URL(path);
     }
@@ -126,23 +115,7 @@ function toPath(path) {
     }
     return uriToPath(path);
 }
-const uriToPath = (uri) => url.fileURLToPath(uri instanceof Uri ? new url.URL(uri.toString()) : uri);
-const uriFromPath = (path) => url.pathToFileURL(path).toString();
-class ChokidarWatcherWrapper extends EventEmitter {
-    #watcher;
-    constructor(watcher) {
-        super();
-        this.#watcher = watcher
-            .on('ready', () => this.emit('ready'))
-            .on('add', (path) => this.emit('add', uriFromPath(path)))
-            .on('change', (path) => this.emit('change', uriFromPath(path)))
-            .on('unlink', (path) => this.emit('unlink', uriFromPath(path)))
-            .on('error', (e) => this.emit('error', e));
-    }
-    close() {
-        return this.#watcher.close();
-    }
-}
+const uriToPath = (uri) => url.fileURLToPath(uri);
 /**
  * A non-spec-compliant, non-complete implementation of the Cache Web API for use in Spyglass.
  * This class stores the cached response on the file system under the cache root.

package/lib/common/externals/index.d.ts

@@ -57,27 +57,22 @@ export interface ExternalFileSystem {
         mode?: number;
         recursive?: boolean;
     }): Promise<void>;
-    readdir(location: FsLocation): Promise<{
-        name: string;
-        isDirectory(): boolean;
-        isFile(): boolean;
-        isSymbolicLink(): boolean;
-    }[]>;
+    readdir(location: FsLocation): Promise<ExternalDirEntry[]>;
     readFile(location: FsLocation): Promise<Uint8Array<ArrayBuffer>>;
+    rm(location: FsLocation, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
     /**
      * Show the file/directory in the platform-specific explorer program.
      *
      * Should not be called with unsanitized user-input path due to the possibility of arbitrary code execution.
      */
     showFile(path: FsLocation): Promise<void>;
-    stat(location: FsLocation): Promise<{
-        isDirectory(): boolean;
-        isFile(): boolean;
-    }>;
+    stat(location: FsLocation): Promise<ExternalStats>;
+    /**
+     * @deprecated Use `rm` instead
+     */
     unlink(location: FsLocation): Promise<void>;
-    watch(locations: FsLocation[], options: {
-        usePolling?: boolean;
-    }): FsWatcher;
     /**
      * @param options `mode` - File mode bit mask (e.g. `0o775`).
      */
@@ -85,21 +80,17 @@ export interface ExternalFileSystem {
         mode: number;
     }): Promise<void>;
 }
+export interface ExternalStats {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isSymbolicLink(): boolean;
+}
+interface ExternalDirEntry extends ExternalStats {
+    name: string;
+}
 /**
  * A file URI string or a URI object.
  */
 export type FsLocation = string | Uri;
-export interface FsWatcher {
-    on(eventName: 'ready', listener: () => unknown): this;
-    once(eventName: 'ready', listener: () => unknown): this;
-    on(eventName: 'add', listener: (uri: string) => unknown): this;
-    once(eventName: 'add', listener: (uri: string) => unknown): this;
-    on(eventName: 'change', listener: (uri: string) => unknown): this;
-    once(eventName: 'change', listener: (uri: string) => unknown): this;
-    on(eventName: 'unlink', listener: (uri: string) => unknown): this;
-    once(eventName: 'unlink', listener: (uri: string) => unknown): this;
-    on(eventName: 'error', listener: (error: Error) => unknown): this;
-    once(eventName: 'error', listener: (error: Error) => unknown): this;
-    close(): Promise<void>;
-}
+export {};
 //# sourceMappingURL=index.d.ts.map

package/lib/common/index.d.ts

@@ -5,5 +5,6 @@ export * from './Operations.js';
 export * from './ReadonlyProxy.js';
 export * from './StateProxy.js';
 export * from './TwoWayMap.js';
+export * from './UriStore.js';
 export * from './util.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/common/index.js

@@ -5,5 +5,6 @@ export * from './Operations.js';
 export * from './ReadonlyProxy.js';
 export * from './StateProxy.js';
 export * from './TwoWayMap.js';
+export * from './UriStore.js';
 export * from './util.js';
 //# sourceMappingURL=index.js.map

package/lib/common/util.d.ts

@@ -1,15 +1,24 @@
 import externalBinarySearch from 'binary-search';
-import { URL } from 'whatwg-url';
 import type { AstNode } from '../node/index.js';
 import type { ProcessorContext } from '../service/index.js';
 import type { Externals } from './externals/index.js';
 import type { DeepReadonly, ReadWrite } from './ReadonlyProxy.js';
-export declare const Uri: typeof URL;
+export declare const Uri: {
+    new (url: string | URL, base?: string | URL): URL;
+    prototype: URL;
+    canParse(url: string | URL, base?: string | URL): boolean;
+    createObjectURL(obj: Blob | MediaSource): string;
+    parse(url: string | URL, base?: string | URL): URL | null;
+    revokeObjectURL(url: string): void;
+};
 export type Uri = URL;
 /**
  * `NodeJS.Timeout` on Node.js and `number` on browser.
  */
 export type IntervalId = any;
+export type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
 /**
  * @param getKey A function that takes the actual arguments being passed into the decorated method, and returns anything.
  * The result of this function will be used as the key to identify the `Promise`. By default the first element in the argument
@@ -110,6 +119,7 @@ export declare function emplaceMap<K, V>(map: Map<K, V>, key: K, handler: {
  * @returns If `val` is an non-null object or a callable object (i.e. function).
  */
 export declare function isObject(val: unknown): val is object;
+export declare function normalizeUriPathname(pathname: string): string;
 export declare function normalizeUri(uri: string): string;
 /**
  * Return a read-write TARGET type if the INPUT type is read-write, and a

package/lib/common/util.js

@@ -1,17 +1,20 @@
 import externalBinarySearch from 'binary-search';
 import rfdc from 'rfdc';
-import { URL } from 'whatwg-url';
-// Spyglass uses the URL class provided by the
-// [spec](https://url.spec.whatwg.org/)-compliant `whatwg-url` package instead
-// of the broken one shipped with browsers that do not parse non-special scheme
-// URLs with hosts properly.
+import { URL as WhatwgURL } from 'whatwg-url';
+// We try to use the `URL` class built-in to the JavaScript runtime if possible, but falls back to
+// use the `URL` class from the `whatwg-url` package if a certain bug exists.
+// See more at https://github.com/SpyglassMC/Spyglass/issues/1763.
 //
-// * [Chromium bug](https://issues.chromium.org/issues/40587286)
-// * [FireFox bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1374505)
-//
-// We use the name "URI" instead of "URL" when possible, since it is what
-// LSP has chosen to use for the string that uniquely identifies a file.
-export const Uri = URL;
+// The name "URI" instead of "URL" is used to align with LSP terminology.
+export const Uri = isBuiltInURLGood() ? URL : WhatwgURL;
+function isBuiltInURLGood() {
+    try {
+        return new URL('archive://mcdoc.tar.gz/foo.mcdoc').host === 'mcdoc.tar.gz';
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * @param getKey A function that takes the actual arguments being passed into the decorated method, and returns anything.
  * The result of this function will be used as the key to identify the `Promise`. By default the first element in the argument
@@ -243,9 +246,25 @@ export function emplaceMap(map, key, handler) {
 export function isObject(val) {
     return typeof val === 'function' || (!!val && typeof val === 'object');
 }
+export function normalizeUriPathname(pathname) {
+    // Normalize drive letters on Windows to use lowercase letters, and ensure all colons are not encoded.
+    // See also LSP spec text, quoted below.
+    //
+    // > Care should be taken to handle encoding in URIs. For example, some clients (such as VS Code) may
+    // > encode colons in drive letters while others do not. The URIs below are both valid, but clients and
+    // > servers should be consistent with the form they use themselves to ensure the other party doesn’t
+    // > interpret them as distinct URIs. Clients and servers should not assume that each other are encoding
+    // > the same way (for example a client encoding colons in drive letters cannot assume server responses
+    // > will have encoded colons). The same applies to casing of drive letters - one party should not assume
+    // > the other party will return paths with drive letters cased the same as itself.
+    // > -- https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#uri
+    return pathname
+        .replace(/%3A/gi, ':')
+        .replace(/^\/[A-Z]:\//, (match) => match.toLowerCase());
+}
 export function normalizeUri(uri) {
     const obj = new Uri(uri);
-    obj.pathname = obj.pathname.replace(/%3A/gi, ':');
+    obj.pathname = normalizeUriPathname(obj.pathname);
     return obj.toString();
 }
 //# sourceMappingURL=util.js.map