@matter/tools 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/util/package.ts

@@ -0,0 +1,369 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { existsSync, readFileSync, statSync } from "fs";
+import { readdir, readFile, stat, writeFile } from "fs/promises";
+import { glob } from "glob";
+import { dirname, join, relative, resolve } from "path";
+import { maybeStatSync } from "../testing/files.js";
+import { ignoreError, ignoreErrorSync } from "./errors.js";
+import { Progress } from "./progress.js";
+import { toolsPath } from "./tools-path.cjs";
+
+export class JsonNotFoundError extends Error {}
+
+export const CONFIG_PATH = `src/build.config.ts`;
+export const CODEGEN_PATH = `codegen`;
+
+const packageForPath = {} as Record<string, Package | undefined | null>;
+
+function findJson(filename: string, path: string = ".", title?: string) {
+    path = resolve(path);
+    while (true) {
+        const json = ignoreErrorSync(["ENOENT", "ENOTDIR"], () =>
+            JSON.parse(readFileSync(resolve(path, filename)).toString()),
+        );
+        if (json) {
+            if (title === undefined || json.name === title) {
+                return { root: path, json };
+            }
+        }
+        const parent = dirname(path);
+        if (parent === path) {
+            throw new JsonNotFoundError(`Could not locate ${title ?? filename}`);
+        }
+        path = parent;
+    }
+}
+
+function isDirectory(path: string) {
+    return !!ignoreErrorSync("ENOENT", () => statSync(path).isDirectory());
+}
+
+export class Package {
+    path: string;
+    json: PackageJson;
+    supportsEsm: boolean;
+    supportsCjs: boolean;
+    hasSrc: boolean;
+    hasTests: boolean;
+    hasConfig: boolean;
+    isLibrary: boolean;
+    #aliases?: Record<string, string>;
+
+    constructor({
+        path = ".",
+        name,
+    }: {
+        path?: string;
+        name?: string;
+    } = {}) {
+        const { root, json } = findJson("package.json", path, name);
+        this.path = root;
+        this.json = json;
+
+        const { esm, cjs } = selectFormats(this.json);
+        this.supportsEsm = esm;
+        this.supportsCjs = cjs;
+
+        this.hasSrc = isDirectory(this.resolve("src"));
+        this.hasTests = isDirectory(this.resolve("test"));
+
+        this.isLibrary = !!(this.json.main || this.json.module || this.json.exports);
+
+        this.hasConfig = this.hasFile(this.resolve(CONFIG_PATH));
+    }
+
+    get name() {
+        return this.json.name;
+    }
+
+    get exports() {
+        return this.json.exports;
+    }
+
+    get hasCodegen() {
+        return this.hasDirectory(CODEGEN_PATH);
+    }
+
+    resolve(path: string) {
+        return resolve(this.path, path);
+    }
+
+    relative(path: string) {
+        return relative(this.path, path);
+    }
+
+    async glob(pattern: string) {
+        // Glob only understands forward-slash as separator because reasons
+        pattern = this.resolve(pattern).replace(/\\/g, "/");
+
+        return await glob(pattern);
+    }
+
+    start(what: string) {
+        const progress = new Progress();
+        progress.startup(what, this);
+        return progress;
+    }
+
+    async lastModified(...paths: string[]) {
+        return this.lastModifiedAbsolute(paths.map(p => this.resolve(p)));
+    }
+
+    private async lastModifiedAbsolute(paths: string[]) {
+        let mtime = 0;
+        await Promise.all(
+            paths.map(async p => {
+                const stats = await ignoreError("ENOENT", async () => await stat(p));
+                if (!stats) {
+                    return;
+                }
+
+                let thisMtime;
+                if (stats.isDirectory()) {
+                    const paths = (await readdir(p)).map(p2 => resolve(p, p2));
+                    thisMtime = await this.lastModifiedAbsolute(paths);
+                } else {
+                    thisMtime = stats.mtimeMs;
+                }
+                if (thisMtime > mtime) {
+                    mtime = thisMtime;
+                }
+            }),
+        );
+        return mtime;
+    }
+
+    get dependencies() {
+        let result = Array<string>();
+        for (const type of ["dependencies", "optionalDependencies", "devDependencies", "peerDependencies"]) {
+            if (typeof this.json[type] === "object" && this.json[type] !== null) {
+                result = [...result, ...Object.keys(this.json[type])];
+            }
+        }
+        return [...new Set(result)];
+    }
+
+    get workspace() {
+        return Package.workspaceFor(this.path);
+    }
+
+    static set workingDir(wd: string) {
+        workingDir = wd;
+    }
+
+    static get workspace() {
+        return this.workspaceFor(workingDir);
+    }
+
+    static workspaceFor(cwd: string) {
+        if (!workspace) {
+            workspace = find(cwd, pkg => Array.isArray(pkg.json.workspaces));
+        }
+        return workspace;
+    }
+
+    static get tools() {
+        if (!tools) {
+            tools = new Package({ path: toolsPath });
+        }
+        return tools;
+    }
+
+    static findExport(name: string, type: "cjs" | "esm" = "esm") {
+        return this.workspace.resolveImport(name, type);
+    }
+
+    resolveExport(name: string, type: "cjs" | "esm" = "esm") {
+        if (!name.startsWith(".")) {
+            name = `./${name}`;
+        }
+        const exportDetail = this.exports?.[name];
+
+        if (exportDetail) {
+            const exp = findExportCondition(exportDetail, type);
+            if (exp) {
+                return this.resolve(exp);
+            }
+        }
+
+        if (name === ".") {
+            if (type === "esm" && this.json.module) {
+                return this.resolve(this.json.module);
+            }
+            if (this.json.main) {
+                return this.resolve(this.json.main);
+            }
+        }
+
+        throw new Error(`Cannot resolve export ${name} in package ${this.name}`);
+    }
+
+    resolveImport(name: string, type: "cjs" | "esm" = "esm") {
+        const segments = name.split("/");
+        let subdir = segments.shift() as string;
+        if (subdir.startsWith("@") && segments.length) {
+            subdir = `${subdir}/${segments.shift()}`;
+        }
+
+        let resolveIn = this.path;
+        while (true) {
+            if (isDirectory(resolve(resolveIn, "node_modules", subdir))) {
+                break;
+            }
+            const nextResolveIn = dirname(resolveIn);
+            if (nextResolveIn === resolveIn) {
+                throw new Error(`Cannot find module ${subdir} from ${this.path}`);
+            }
+            resolveIn = nextResolveIn;
+        }
+
+        const pkg = Package.forPath(resolve(resolveIn, "node_modules", subdir));
+        return pkg.resolveExport(segments.length ? segments.join("/") : ".", type);
+    }
+
+    hasFile(path: string) {
+        return !!this.#maybeStat(path)?.isFile();
+    }
+
+    hasDirectory(path: string) {
+        return !!this.#maybeStat(path)?.isDirectory();
+    }
+
+    async readFile(path: string) {
+        return readFile(this.resolve(path), "utf-8");
+    }
+
+    readFileSync(path: string) {
+        return readFileSync(this.resolve(path), "utf-8");
+    }
+
+    async writeFile(path: string, contents: unknown) {
+        await writeFile(this.resolve(path), `${contents}`);
+    }
+
+    async save() {
+        await this.writeFile(join(this.path, "package.json"), JSON.stringify(this.json, undefined, 4));
+    }
+
+    async readJson(path: string) {
+        const text = await this.readFile(path);
+        try {
+            return JSON.parse(text);
+        } catch (e) {
+            if (!(e instanceof Error)) {
+                e = new Error(`${e}`);
+            }
+            (e as Error).message = `Error parsing "${this.resolve(path)}": ${(e as Error).message}`;
+        }
+        return JSON.parse(await this.readFile(path));
+    }
+
+    async writeJson(path: string, value: {}) {
+        await this.writeFile(path, JSON.stringify(value, undefined, 4));
+    }
+
+    static maybeForPath(path: string) {
+        function find(path: string): Package | null {
+            let result = packageForPath[path];
+            if (result === undefined) {
+                if (existsSync(join(path, "package.json"))) {
+                    result = new Package({ path });
+                } else {
+                    result = find(dirname(path));
+                }
+                packageForPath[path] = result;
+            }
+            return result;
+        }
+
+        const result = find(path);
+
+        return result ?? undefined;
+    }
+
+    static forPath(path: string) {
+        const result = this.maybeForPath(path);
+        if (result !== undefined) {
+            return result;
+        }
+        throw new Error(`Cannot find package.json for "${path}"`);
+    }
+
+    get aliases(): Record<string, string> {
+        if (this.#aliases !== undefined) {
+            return this.#aliases;
+        }
+
+        this.#aliases = {
+            ...Package.maybeForPath(dirname(this.path))?.aliases,
+            ...this.json.imports,
+        };
+
+        return this.#aliases;
+    }
+
+    #maybeStat(path: string) {
+        return maybeStatSync(this.resolve(path));
+    }
+}
+
+export type PackageJson = {
+    name: string;
+    version: string;
+    imports: Record<string, string>;
+    [key: string]: any;
+};
+
+let workingDir = ".";
+let workspace: Package | undefined;
+let tools: Package | undefined;
+
+function find(startDir: string, selector: (pkg: Package) => boolean): Package {
+    let pkg = new Package({ path: startDir });
+    while (!selector(pkg)) {
+        pkg = new Package({ path: dirname(pkg.path) });
+    }
+    return pkg;
+}
+
+function selectFormats(json: any) {
+    let esm: boolean, cjs: boolean;
+
+    if (json.type === "module") {
+        esm = true;
+        cjs =
+            (json.main !== undefined && json.module !== undefined) ||
+            !!Object.values(json.exports ?? {}).find((exp: any) => exp.require);
+    } else {
+        cjs = true;
+        esm = !!json.module || !!Object.values(json.exports ?? {}).find((exp: any) => exp.import);
+    }
+
+    return { esm, cjs };
+}
+
+function findExportCondition(detail: Record<string, any>, type: "esm" | "cjs"): string | undefined {
+    if (type === "esm" && detail.import) {
+        let exp = detail.import;
+        if (exp && typeof exp !== "string") {
+            exp = findExportCondition(exp, type);
+        }
+        if (exp) {
+            return exp;
+        }
+    }
+
+    let exp = detail.require ?? detail.node ?? detail.default;
+    if (exp && typeof exp !== "string") {
+        exp = findExportCondition(exp, type);
+    }
+
+    if (typeof exp === "string") {
+        return exp;
+    }
+}

package/src/util/progress.ts

@@ -0,0 +1,252 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import colors from "ansi-colors";
+import { stderr, stdout } from "process";
+import { Package } from "./package.js";
+
+const CLEAR = "\x1b[K";
+const SPINNER = "◐◓◑◒"; //"⡜⠔⠢⢣"; //["⚫︎", "⚪︎"]; "⡈⠔⠢⢁";
+const SPINNER_INTERVAL = 100;
+
+function packageIdentity(pkg: Package) {
+    let identity = colors.bold(pkg.json.name);
+    if (pkg.json.version) {
+        identity = `${identity}@${pkg.json.version}`;
+    }
+    return identity;
+}
+
+/**
+ * Intercept writes to stderr and stdout so we can ensure our updates appear on different lines from other output.
+ */
+const writeStatus = (() => {
+    let lastStatus: undefined | string;
+    let needNewline = false;
+
+    function intercept(stream: NodeJS.WriteStream) {
+        const actualWrite = stream.write;
+        stream.write = (payload: Uint8Array | string, ...params: any[]) => {
+            if (lastStatus) {
+                actualWrite.call(stream, "\n");
+                lastStatus = undefined;
+            }
+
+            if (!payload.length) {
+                return true;
+            }
+
+            // Require a newline for status updates any time the cursor does not end at the beginning of a line
+            needNewline =
+                // Update ends in newline
+                payload[payload.length - 1] === "\n" &&
+                // Update ends in carriage return
+                payload[payload.length - 1] !== "\r";
+
+            return actualWrite.call(stream, payload, ...params);
+        };
+    }
+
+    intercept(stdout);
+    intercept(stderr);
+
+    return function writeStatus(text: string, willOverwrite = false) {
+        const columns = process.stdout.columns;
+        if (willOverwrite && columns !== undefined && text.length > columns - 2) {
+            text = filterAnsi(text, columns - 2) + "…";
+        }
+
+        text += willOverwrite ? "\r" : "\n";
+        if (text === lastStatus) {
+            return;
+        }
+
+        if (lastStatus) {
+            lastStatus = undefined;
+            stdout.write(CLEAR);
+        } else if (needNewline && !text.startsWith("\n")) {
+            stdout.write("\n");
+        }
+
+        stdout.write(text);
+
+        lastStatus = text;
+    };
+})();
+
+export class Progress {
+    status = Progress.Status.Startup;
+    #ongoingText?: string;
+    #start?: number;
+    #spinner = "⧗";
+    #refreshInterval?: ReturnType<typeof setInterval>;
+    #spinnerPosition = 0;
+    #spinnerWindow?: number;
+
+    constructor() {}
+
+    emphasize(text: unknown) {
+        return colors.bold(`${text}`);
+    }
+
+    deemphasize(text: unknown) {
+        return colors.dim(`${text}`);
+    }
+
+    skip(why: string, pkg: Package) {
+        stdout.write(colors.dim(`Skip ${packageIdentity(pkg)}: ${why}\n\n`));
+    }
+
+    startup(what: string, pkgOrOverwrite?: Package | boolean) {
+        if (process.stdout.isTTY) {
+            this.#updateSpinner();
+            this.#refreshInterval = setInterval(this.refresh.bind(this), SPINNER_INTERVAL);
+        }
+
+        this.status = Progress.Status.Startup;
+        if (pkgOrOverwrite === undefined || typeof pkgOrOverwrite === "boolean") {
+            writeStatus(what, pkgOrOverwrite ?? true);
+        } else {
+            writeStatus(`${what} ${packageIdentity(pkgOrOverwrite)}`);
+        }
+    }
+
+    update(text: string, extra?: string) {
+        this.status = Progress.Status.Ongoing;
+        let duration;
+        if (this.#start === undefined) {
+            this.#start = new Date().getTime();
+            duration = "";
+        } else {
+            duration = this.#duration;
+        }
+        extra = extra === undefined ? "" : ` ${extra}`;
+        this.#ongoingText = `${text} ${duration}${extra}`;
+        this.#writeOngoing();
+    }
+
+    #writeOngoing() {
+        if (!this.#ongoingText) {
+            return;
+        }
+
+        writeStatus(`  ${colors.yellow(this.#spinner)} ${this.#ongoingText}`, true);
+    }
+
+    success(text: string) {
+        this.status = Progress.Status.Success;
+        writeStatus(`  ${colors.green("✓")} ${text} ${this.#duration}`);
+        this.#start = this.#ongoingText = undefined;
+    }
+
+    failure(text: string) {
+        this.status = Progress.Status.Failure;
+        writeStatus(`  ${colors.redBright("✗")} ${text} ${this.#duration}`);
+        this.#start = this.#ongoingText = undefined;
+    }
+
+    info(label: string, value?: any) {
+        if (value) {
+            label = `${colors.dim(label)} ${value}`;
+        }
+        writeStatus(`  ${colors.dim("‣")} ${label}`);
+    }
+
+    shutdown() {
+        if (this.#refreshInterval) {
+            clearInterval(this.#refreshInterval);
+            this.#refreshInterval = undefined;
+        }
+        writeStatus("");
+    }
+
+    refresh() {
+        if (this.#updateSpinner()) {
+            this.#writeOngoing();
+        }
+    }
+
+    #updateSpinner() {
+        if (!stdout.isTTY) {
+            return false;
+        }
+
+        const window = Math.floor(new Date().getTime() / SPINNER_INTERVAL);
+        if (this.#spinnerWindow === window) {
+            return false;
+        }
+        this.#spinnerWindow = window;
+
+        this.#spinnerPosition = (this.#spinnerPosition + 1) % SPINNER.length;
+        this.#spinner = SPINNER[this.#spinnerPosition];
+
+        return true;
+    }
+
+    async run(what: string, fn: () => void | Promise<void>) {
+        this.update(what);
+        try {
+            await fn();
+        } catch (e) {
+            this.failure(what);
+            throw e;
+        }
+        this.success(what);
+    }
+
+    get #duration() {
+        let ms = this.#start ? new Date().getTime() - this.#start : 0;
+        if (ms < 1000) {
+            ms = Math.round(ms / 10) / 100;
+        } else if (ms < 10000) {
+            ms = Math.round(ms / 100) / 10;
+        } else {
+            ms = Math.trunc(ms / 1000);
+        }
+        return colors.dim.yellow(`(${ms}s)`);
+    }
+}
+
+export namespace Progress {
+    export enum Status {
+        Startup = "startup",
+        Ongoing = "ongoing",
+        Success = "success",
+        Failure = "failure",
+    }
+}
+
+// See https://stackoverflow.com/questions/26238553/how-can-i-truncate-a-string-to-a-maximum-length-without-breaking-ansi-escape-cod
+// TODO - this function doesn't seem entirely correct, still seems to truncate too much
+// Crop the length of lines, ANSI escape code aware
+// Always outputs every escape char, regardless of length (so we always end up with a sane state)
+// Visible characters are filtered out once length is exceeded
+function filterAnsi(str: string, len: number) {
+    if (!len || len < 10) return str; // probably not a valid console -- send back the whole line
+    let count = 0, // number of visible chars on line so far
+        esc = false, // in an escape sequence
+        longesc = false; // in a multi-character escape sequence
+    let outp = true; // should output this character
+    return str
+        .split("")
+        .filter(function (c) {
+            // filter characters...
+            if (esc && !longesc && c == "[") longesc = true; // have seen an escape, now '[', start multi-char escape
+            if (c == "\x1b") esc = true; // start of escape sequence
+
+            outp = count < len || esc; // if length exceeded, don't output non-escape chars
+            if (!esc && !longesc) count++; // if not in escape, count visible char
+
+            if (esc && !longesc && c != "\x1b") esc = false; // out of single char escape
+            if (longesc && c != "[" && c >= "@" && c <= "~") {
+                esc = false;
+                longesc = false;
+            } // end of multi-char escape
+
+            return outp; // result for filter
+        })
+        .join(""); // glue chars back into string
+}

package/src/util/tools-path.cjs

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+const { resolve } = require("path");
+
+// Node makes it impossible to obtain the path of the current file in a matter that transpiles cleanly to both ESM and
+// CJS.  __dirname is not available in ESM but you can't reference import.meta.url in CJS even conditionally because it
+// is a compile-time error.  So instead we locate the root of the tools package in this file which always runs as CJS
+// and is thus importable into both ESM and CJS.
+exports.toolsPath = resolve(__dirname, "../..");

package/src/util/tools-path.d.cts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export declare const toolsPath: string;

package/src/util/trace-unhandled.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const traceUnhandled = {
+    async initialize() {
+        // We process args and environment manually so we don't need dependencies and can install as early as possible
+        if (!process.argv.includes("--trace-unhandled") && !process.env.MATTER_TRACE_UNHANDLED) {
+            return;
+        }
+
+        const { register } = await import("trace-unhandled");
+        register();
+    },
+};

package/src/util/wtf.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const wtf = {
+    async initialize() {
+        // This will only work under actual Node.js
+        if (typeof process !== "object" || process?.release?.name !== "node") {
+            return;
+        }
+
+        // We process args and environment manually so we don't need dependencies and can install wtfnode as early as
+        // possible
+        if (!process.argv.includes("--wtf") && !process.env.MATTER_WTF) {
+            return;
+        }
+
+        const { dump } = await import("wtfnode");
+        this.dump = () => dump();
+    },
+
+    dump() {},
+};