@spyglassmc/core 0.1.0

package/lib/service/FileService.d.ts

@@ -0,0 +1,96 @@
+/// <reference types="node" />
+import type { Dependency } from './Dependency';
+import type { RootUriString } from './fileUtil';
+import type { Logger } from './Logger';
+export interface UriProtocolSupporter {
+    /**
+     * @throws
+     *
+     * @returns A hash created from the content of the item at `uri`. This hash is used by the cache invalidation
+     * mechanism to check if an item has been modified, therefore it doesn't need to use a super duper secure hash
+     * algorithm. Algorithms like SHA-1 or MD5 should be good enough.
+     */
+    hash(uri: string): Promise<string>;
+    /**
+     * @param uri A file URI.
+     * @returns The content of the file at `uri`.
+     * @throws If the URI doesn't exist in the file system.
+     */
+    readFile(uri: string): Promise<Buffer>;
+    listFiles(): Iterable<string>;
+    /**
+     * Each URI in this array must end with a slash (`/`).
+     */
+    listRoots(): Iterable<RootUriString>;
+}
+declare type Protocol = `${string}:`;
+export interface FileService extends UriProtocolSupporter {
+    /**
+     * @param protocol A protocol of URI, including the colon. e.g. `file:`.
+     * @param supporter The supporter for that `protocol`.
+     * @param force If the protocol is already supported, whether to override it or not.
+     *
+     * @throws If `protocol` is already registered, unless `force` is set to `true`.
+     */
+    register(protocol: Protocol, supporter: UriProtocolSupporter, force?: boolean): void;
+    /**
+     * Unregister the supported associated with `protocol`. Nothing happens if the `protocol` isn't supported.
+     */
+    unregister(protocol: Protocol): void;
+}
+export declare namespace FileService {
+    function create(): FileService;
+}
+export declare class FileServiceImpl implements FileService {
+    private readonly supporters;
+    register(protocol: Protocol, supporter: UriProtocolSupporter, force?: boolean): void;
+    unregister(protocol: Protocol): void;
+    /**
+     * @throws If the protocol of `uri` isn't supported.
+     *
+     * @returns The protocol if it's supported.
+     */
+    private getSupportedProtocol;
+    /**
+     * @throws
+     */
+    hash(uri: string): Promise<string>;
+    /**
+     * @throws
+     */
+    readFile(uri: string): Promise<Buffer>;
+    listFiles(): Generator<string, void, undefined>;
+    listRoots(): Generator<`${string}/`, void, undefined>;
+}
+export declare class FileUriSupporter implements UriProtocolSupporter {
+    private readonly roots;
+    private readonly files;
+    readonly protocol = "file:";
+    private constructor();
+    hash(uri: string): Promise<string>;
+    readFile(uri: string): Promise<Buffer>;
+    listFiles(): Generator<string, void, undefined>;
+    listRoots(): `${string}/`[];
+    private static rootUriToGlob;
+    static create(dependencies: readonly Dependency[], logger: Logger): Promise<FileUriSupporter>;
+}
+export declare class SpyglassUriSupporter implements UriProtocolSupporter {
+    private readonly entries;
+    readonly protocol = "spyglassmc:";
+    private static readonly SupportedArchiveExtnames;
+    /**
+     * @param entries A map from archive URIs to unzipped entries.
+     */
+    private constructor();
+    hash(uri: string): Promise<string>;
+    readFile(uri: string): Promise<Buffer>;
+    /**
+     * @throws
+     */
+    private getDataInArchive;
+    listFiles(): Generator<string, void, unknown>;
+    listRoots(): Generator<`${string}/`, void, unknown>;
+    static create(dependencies: readonly Dependency[], logger: Logger, checksums: Record<RootUriString, string>): Promise<SpyglassUriSupporter>;
+}
+export {};
+//# sourceMappingURL=FileService.d.ts.map

package/lib/service/FileService.js

@@ -0,0 +1,224 @@
+"use strict";
+/* istanbul ignore file */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpyglassUriSupporter = exports.FileUriSupporter = exports.FileServiceImpl = exports.FileService = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const decompress_1 = __importDefault(require("decompress"));
+const fs_1 = __importStar(require("fs"));
+const globby_1 = __importDefault(require("globby"));
+const common_1 = require("../common");
+const fileUtil_1 = require("./fileUtil");
+const HashAlgorithm = 'sha1';
+var FileService;
+(function (FileService) {
+    let instance;
+    function create() {
+        return instance ?? (instance = new FileServiceImpl());
+    }
+    FileService.create = create;
+})(FileService = exports.FileService || (exports.FileService = {}));
+class FileServiceImpl {
+    constructor() {
+        this.supporters = new Map();
+    }
+    register(protocol, supporter, force = false) {
+        if (!force && this.supporters.has(protocol)) {
+            throw new Error(`The protocol “${protocol}” is already associated with another supporter.`);
+        }
+        this.supporters.set(protocol, supporter);
+    }
+    unregister(protocol) {
+        this.supporters.delete(protocol);
+    }
+    /**
+     * @throws If the protocol of `uri` isn't supported.
+     *
+     * @returns The protocol if it's supported.
+     */
+    getSupportedProtocol(uri) {
+        const protocol = new common_1.Uri(uri).protocol;
+        if (!this.supporters.has(protocol)) {
+            throw new Error(`The protocol “${protocol}” is unsupported.`);
+        }
+        return protocol;
+    }
+    /**
+     * @throws
+     */
+    async hash(uri) {
+        const protocol = this.getSupportedProtocol(uri);
+        return this.supporters.get(protocol).hash(uri);
+    }
+    /**
+     * @throws
+     */
+    readFile(uri) {
+        const protocol = this.getSupportedProtocol(uri);
+        return this.supporters.get(protocol).readFile(uri);
+    }
+    *listFiles() {
+        for (const supporter of this.supporters.values()) {
+            yield* supporter.listFiles();
+        }
+    }
+    *listRoots() {
+        for (const supporter of this.supporters.values()) {
+            yield* supporter.listRoots();
+        }
+    }
+}
+exports.FileServiceImpl = FileServiceImpl;
+class FileUriSupporter {
+    constructor(roots, files) {
+        this.roots = roots;
+        this.files = files;
+        this.protocol = 'file:';
+    }
+    async hash(uri) {
+        return hashFile(uri);
+    }
+    readFile(uri) {
+        return fs_1.promises.readFile(new common_1.Uri(uri));
+    }
+    *listFiles() {
+        for (const files of this.files.values()) {
+            yield* files;
+        }
+    }
+    listRoots() {
+        return this.roots;
+    }
+    static rootUriToGlob(root) {
+        return fileUtil_1.fileUtil.fileUriToPath(root) + '**/*';
+    }
+    static async create(dependencies, logger) {
+        const roots = [];
+        const files = new Map();
+        for (let { uri } of dependencies) {
+            try {
+                if (fileUtil_1.fileUtil.isFileUri(uri) && (await fs_1.promises.stat(new common_1.Uri(uri))).isDirectory()) {
+                    uri = fileUtil_1.fileUtil.ensureEndingSlash(uri);
+                    roots.push(uri);
+                    files.set(uri, (await (0, globby_1.default)(this.rootUriToGlob(uri), { absolute: true, dot: true })).map(fileUtil_1.fileUtil.pathToFileUri));
+                }
+            }
+            catch (e) {
+                logger.error(`[FileUriSupporter#create] Bad dependency “${uri}”`, e);
+            }
+        }
+        return new FileUriSupporter(roots, files);
+    }
+}
+exports.FileUriSupporter = FileUriSupporter;
+class SpyglassUriSupporter {
+    /**
+     * @param entries A map from archive URIs to unzipped entries.
+     */
+    constructor(entries) {
+        this.entries = entries;
+        this.protocol = common_1.SpyglassUri.Protocol;
+    }
+    async hash(uri) {
+        const { archiveUri, pathInArchive } = common_1.SpyglassUri.Archive.decode(new common_1.Uri(uri));
+        if (!pathInArchive) {
+            // Hash the archive itself.
+            return hashFile(archiveUri);
+        }
+        else {
+            // Hash the corresponding file.
+            return (0, common_1.getSha1)(await this.getDataInArchive(archiveUri, pathInArchive));
+        }
+    }
+    async readFile(uri) {
+        const { archiveUri, pathInArchive } = common_1.SpyglassUri.Archive.decode(new common_1.Uri(uri));
+        return this.getDataInArchive(archiveUri, pathInArchive);
+    }
+    /**
+     * @throws
+     */
+    async getDataInArchive(archiveUri, pathInArchive) {
+        const entries = this.entries.get(archiveUri);
+        if (!entries) {
+            throw new Error(`Archive “${archiveUri}” has not been loaded into the memory`);
+        }
+        const entry = entries.get(pathInArchive);
+        if (!entry) {
+            throw new Error(`Path “${pathInArchive}” does not exist in archive “${archiveUri}”`);
+        }
+        if (entry.type !== 'file') {
+            throw new Error(`Path “${pathInArchive}” in archive “${archiveUri}” is not a file`);
+        }
+        return entry.data;
+    }
+    *listFiles() {
+        for (const [archiveUri, files] of this.entries.entries()) {
+            for (const file of files.values()) {
+                yield common_1.SpyglassUri.Archive.get(archiveUri, file.path);
+            }
+        }
+    }
+    *listRoots() {
+        for (const archiveUri of this.entries.keys()) {
+            yield common_1.SpyglassUri.Archive.get(archiveUri);
+        }
+    }
+    static async create(dependencies, logger, checksums) {
+        const entries = new Map();
+        for (const { uri, info } of dependencies) {
+            try {
+                if (uri.startsWith('file:') && SpyglassUriSupporter.SupportedArchiveExtnames.some(ext => uri.endsWith(ext)) && (await fs_1.promises.stat(new common_1.Uri(uri))).isFile()) {
+                    const rootUri = common_1.SpyglassUri.Archive.get(uri);
+                    const cachedChecksum = checksums[rootUri];
+                    if (cachedChecksum !== undefined) {
+                        const checksum = await hashFile(uri);
+                        if (cachedChecksum === checksum) {
+                            // The dependency has not changed since last cache.
+                            logger.info(`[SpyglassUriSupporter#create] Skipped decompressing “${uri}” thanks to cache ${checksum}`);
+                            continue;
+                        }
+                    }
+                    const files = await (0, decompress_1.default)(fileUtil_1.fileUtil.fileUriToPath(uri), { strip: typeof info?.startDepth === 'number' ? info.startDepth : 0 });
+                    entries.set(uri, new Map(files.map(f => [f.path.replace(/\\/g, '/'), f])));
+                }
+            }
+            catch (e) {
+                logger.error(`[SpyglassUriSupporter#create] Bad dependency “${uri}”`, e);
+            }
+        }
+        return new SpyglassUriSupporter(entries);
+    }
+}
+exports.SpyglassUriSupporter = SpyglassUriSupporter;
+SpyglassUriSupporter.SupportedArchiveExtnames = ['.tar', '.tar.bz2', '.tar.gz', '.zip'];
+async function hashFile(uri) {
+    return new Promise((resolve, reject) => {
+        const hash = crypto_1.default.createHash(HashAlgorithm);
+        fs_1.default.createReadStream(new common_1.Uri(uri))
+            .on('data', chunk => hash.update(chunk))
+            .on('end', () => resolve(hash.digest('hex')))
+            .on('error', reject);
+    });
+}
+//# sourceMappingURL=FileService.js.map

package/lib/service/Hover.d.ts

@@ -0,0 +1,10 @@
+import type { RangeLike } from '../source';
+import { Range } from '../source';
+export interface Hover {
+    range: Range;
+    markdown: string;
+}
+export declare namespace Hover {
+    function create(range: RangeLike, markdown: string): Hover;
+}
+//# sourceMappingURL=Hover.d.ts.map

package/lib/service/Hover.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hover = void 0;
+const source_1 = require("../source");
+var Hover;
+(function (Hover) {
+    /* istanbul ignore next */
+    function create(range, markdown) {
+        return {
+            range: source_1.Range.get(range),
+            markdown,
+        };
+    }
+    Hover.create = create;
+})(Hover = exports.Hover || (exports.Hover = {}));
+//# sourceMappingURL=Hover.js.map

package/lib/service/Logger.d.ts

@@ -0,0 +1,31 @@
+export interface Logger {
+    /**
+     * Output an error message.
+     */
+    error(data: any, ...args: any[]): void;
+    /**
+     * Log an information.
+     */
+    info(data: any, ...args: any[]): void;
+    /**
+     * Log a message.
+     */
+    log(data: any, ...args: any[]): void;
+    /**
+     * Output a warning message.
+     */
+    warn(data: any, ...args: any[]): void;
+}
+export declare namespace Logger {
+    /**
+     * @returns The built-in `console`.
+     * Do **not** use this implementation in language servers, as some clients cannot handle
+     * non-LSP stdout. (https://github.com/SpyglassMC/Spyglass/issues/845)
+     */
+    function create(): Logger;
+    /**
+     * @returns A logger that does nothing.
+     */
+    function noop(): Logger;
+}
+//# sourceMappingURL=Logger.d.ts.map

package/lib/service/Logger.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+var Logger;
+(function (Logger) {
+    /* istanbul ignore next */
+    /**
+     * @returns The built-in `console`.
+     * Do **not** use this implementation in language servers, as some clients cannot handle
+     * non-LSP stdout. (https://github.com/SpyglassMC/Spyglass/issues/845)
+     */
+    function create() {
+        return console;
+    }
+    Logger.create = create;
+    /**
+     * @returns A logger that does nothing.
+     */
+    function noop() {
+        return new NoopLogger();
+    }
+    Logger.noop = noop;
+})(Logger = exports.Logger || (exports.Logger = {}));
+class NoopLogger {
+    error() { }
+    info() { }
+    log() { }
+    warn() { }
+}
+//# sourceMappingURL=Logger.js.map

package/lib/service/MetaRegistry.d.ts

@@ -0,0 +1,106 @@
+import { Lazy } from '../common';
+import type { AstNode } from '../node';
+import type { Parser } from '../parser';
+import type { Checker, Colorizer, Completer, InlayHintProvider } from '../processor';
+import type { Formatter } from '../processor/formatter';
+import type { Linter } from '../processor/linter/Linter';
+import type { SignatureHelpProvider } from '../processor/SignatureHelpProvider';
+import type { UriBinder } from '../symbol';
+import type { DependencyKey, DependencyProvider } from './Dependency';
+import type { FileExtension } from './fileUtil';
+import type { Logger } from './Logger';
+import type { SymbolRegistrar } from './SymbolRegistrar';
+export interface LanguageOptions {
+    /**
+     * An array of extensions of files corresponding to the language. Each extension should include the leading dot (`.`).
+     */
+    extensions: FileExtension[];
+    triggerCharacters?: string[];
+    parser: Parser<AstNode>;
+    completer?: Completer<any>;
+}
+interface LinterRegistration {
+    configValidator: (ruleName: string, ruleValue: unknown, logger: Logger) => unknown;
+    linter: Linter<AstNode>;
+    nodePredicate: (node: AstNode) => unknown;
+}
+interface SymbolRegistrarRegistration {
+    registrar: SymbolRegistrar;
+    checksum: string | undefined;
+}
+/**
+ * The meta registry of Spyglass. You can register new parsers, processors, and languages here.
+ */
+export declare class MetaRegistry {
+    #private;
+    constructor();
+    /**
+     * Registers a new language.
+     * @param languageID The language ID. e.g. `"mcfunction"`
+     * @param options The language options for this language.
+     */
+    registerLanguage(languageID: string, options: LanguageOptions): void;
+    /**
+     * An array of all registered language IDs.
+     */
+    getLanguages(): string[];
+    isSupportedLanguage(language: string): boolean;
+    /**
+     * An array of file extensions (including the leading dot (`.`)) that are supported.
+     */
+    getSupportedFileExtensions(): FileExtension[];
+    /**
+     * An array of characters that trigger a completion request.
+     */
+    getTriggerCharacters(): string[];
+    /**
+     * @param fileExtension The file extension including the leading dot. e.g. `".mcfunction"`.
+     * @returns The language ID registered for the file extension, or `undefined`.
+     */
+    getLanguageID(fileExtension: FileExtension): string | undefined;
+    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;
+    hasColorizer<N extends AstNode>(type: N['type']): boolean;
+    getColorizer<N extends AstNode>(type: N['type']): Colorizer<N>;
+    registerColorizer<N extends AstNode>(type: N['type'], colorizer: Colorizer<N>): void;
+    hasCompleter<N extends AstNode>(type: N['type']): boolean;
+    getCompleter<N extends AstNode>(type: N['type']): Completer<N>;
+    registerCompleter<N extends AstNode>(type: N['type'], completer: Completer<N>): void;
+    registerCompleter(type: string, completer: Completer<any>): void;
+    shouldComplete(languageID: string, triggerCharacter?: string): boolean;
+    getCompleterForLanguageID(languageID: string): Completer<any>;
+    getDependencyProvider(key: DependencyKey): DependencyProvider | undefined;
+    registerDependencyProvider(key: DependencyKey, provider: DependencyProvider): void;
+    hasFormatter<N extends AstNode>(type: N['type']): boolean;
+    getFormatter<N extends AstNode>(type: N['type']): Formatter<N>;
+    registerFormatter<N extends AstNode>(type: N['type'], formatter: Formatter<N>): void;
+    registerInlayHintProvider(provider: InlayHintProvider<any>): void;
+    get inlayHintProviders(): Set<InlayHintProvider<any>>;
+    getLinter(ruleName: string): LinterRegistration;
+    registerLinter(ruleName: string, options: LinterRegistration): void;
+    hasParser<N extends AstNode>(id: N['type']): boolean;
+    hasParser(id: string): boolean;
+    /**
+     * @throws When no parser is registered for the node type.
+     */
+    getParser<N extends AstNode>(id: N['type']): Parser<N>;
+    getParser<N extends AstNode>(id: string): Parser<N>;
+    getParserLazily<N extends AstNode>(id: N['type']): Lazy.UnresolvedLazy<Parser<N>>;
+    getParserLazily<N extends AstNode>(id: string): Lazy.UnresolvedLazy<Parser<N>>;
+    registerParser<N extends AstNode>(id: N['type'], parser: Parser<N>): void;
+    registerParser(id: string, parser: Parser): void;
+    /**
+     * @returns The corresponding `Parser` for the language ID.
+     * @throws If there's no such language in the registry.
+     */
+    getParserForLanguageId<N extends AstNode>(languageID: string): Parser<N>;
+    registerSignatureHelpProvider(provider: SignatureHelpProvider<any>): void;
+    get signatureHelpProviders(): Set<SignatureHelpProvider<any>>;
+    registerSymbolRegistrar(id: string, registrar: SymbolRegistrarRegistration): void;
+    get symbolRegistrars(): Map<string, SymbolRegistrarRegistration>;
+    registerUriBinder(uriBinder: UriBinder): void;
+    get uriBinders(): Set<UriBinder>;
+}
+export {};
+//# sourceMappingURL=MetaRegistry.d.ts.map