@matter/cli-tool 0.11.0-alpha.0-20241013-d38e934bb

package/src/location.ts

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NotADirectoryError, NotFoundError } from "#errors.js";
+import { decamelize, MaybePromise } from "#general";
+import { Stat } from "#stat.js";
+
+/**
+ * We support a quick-and-dirty virtual "filesystem" for navigation of our object model.
+ *
+ * This is the interface to this filesystem.
+ */
+export interface Location {
+    kind: "directory" | "command" | "file";
+    basename: string;
+    path: string;
+    tag: string;
+    id?: string | number;
+    name?: string;
+    summary?: string;
+    parent?: Location;
+    definition: unknown;
+    paths: MaybePromise<string[]>;
+    at(path: string, searchedAs?: string): MaybePromise<Location>;
+    maybeAt(path: string, searchedAs?: string): MaybePromise<Location | undefined>;
+}
+
+function isClass(fn: {}) {
+    return !Object.getOwnPropertyDescriptor(fn, "prototype")?.writable;
+}
+
+export function Location(basename: string, definition: unknown, stat: Stat, parent: undefined | Location): Location {
+    let { tag } = stat;
+
+    if (tag === undefined) {
+        if (definition === undefined) {
+            tag = "undefined";
+        } else if (typeof definition === "object") {
+            if (definition === null) {
+                tag = "null";
+            } else if (Symbol.toStringTag in definition) {
+                tag = `${definition[Symbol.toStringTag]}`;
+            } else if (Array.isArray(definition)) {
+                tag = "array";
+            } else if (ArrayBuffer.isView(definition)) {
+                tag = "bytes";
+            } else if (definition.constructor.name !== "Object") {
+                tag = definition.constructor.name;
+            } else {
+                tag = "object";
+            }
+        } else if (typeof definition === "function") {
+            if (isClass(definition)) {
+                tag = "constructor";
+            } else {
+                tag = "function";
+            }
+        } else {
+            tag = typeof definition;
+        }
+    }
+
+    tag = decamelize(tag);
+
+    return {
+        kind: typeof definition === "function" && !isClass(definition) ? "command" : stat.kind,
+        basename,
+        name: stat.name,
+        summary: stat.summary,
+        id: stat.id,
+        tag,
+        parent,
+        definition,
+
+        get path() {
+            if (!this.parent) {
+                return "/";
+            }
+
+            let path = "";
+            let location = this;
+            while (location.parent) {
+                path = `/${location.basename}${path}`;
+                location = location.parent;
+            }
+            return path;
+        },
+
+        get paths() {
+            if (stat.kind !== "directory") {
+                throw new NotADirectoryError(this.path);
+            }
+            return stat.paths;
+        },
+
+        at(path, searchedAs): MaybePromise<Location> {
+            const location = this.maybeAt(path);
+
+            if (MaybePromise.is(location)) {
+                return location.then(accept);
+            }
+
+            return accept(location);
+
+            function accept(location: Location | undefined) {
+                if (location === undefined) {
+                    throw new NotFoundError(searchedAs ?? path);
+                }
+
+                return location;
+            }
+        },
+
+        maybeAt(path, searchedAs): MaybePromise<Location | undefined> {
+            if (stat.kind !== "directory") {
+                throw new NotADirectoryError(searchedAs ?? path);
+            }
+
+            if (path === undefined || path === "") {
+                return this;
+            }
+
+            const segments = path.split("/");
+
+            // Handle absolute path.  Does not happen on recursion
+            if (segments[0] === "") {
+                let location = this;
+                while (location.parent) {
+                    location = location.parent;
+                }
+                return location.maybeAt(segments.slice(1).join("/"), "/");
+            }
+
+            while (segments[0] === "" || segments[0] === ".") {
+                searchedAs += `${segments.shift()}/`;
+            }
+
+            if (segments[0] === "..") {
+                return (this.parent ?? this).maybeAt(
+                    segments.slice(1).join("/"),
+                    searchedAs ? Location.join(searchedAs, "..") : "..",
+                );
+            }
+
+            if (!segments.length) {
+                return this;
+            }
+
+            const subsearchedAs = searchedAs ? Location.join(searchedAs, segments[0]) : segments[0];
+            const definition = stat.definitionAt(decodeURIComponent(segments[0]));
+
+            const accept = (definition: unknown) => {
+                if (definition === undefined || definition === null) {
+                    if (segments.length > 1) {
+                        throw new NotFoundError(subsearchedAs);
+                    }
+                    return;
+                }
+
+                const sublocation = Location(segments[0], definition, Stat.of(definition), this);
+                if (segments.length === 1) {
+                    return sublocation;
+                }
+
+                return sublocation.at(segments.slice(1).join("/"), subsearchedAs);
+            };
+
+            if (MaybePromise.is(definition)) {
+                return definition.then(accept);
+            }
+
+            return accept(definition);
+        },
+    };
+}
+
+export namespace Location {
+    export function join(path: string, ...paths: string[]) {
+        for (const other of paths) {
+            if (other.startsWith("/")) {
+                path = other;
+            } else if (path.endsWith("/")) {
+                path = `${path}${other}`;
+            } else {
+                path = `${path}/${other}`;
+            }
+        }
+        return path;
+    }
+}

package/src/parser.ts

@@ -0,0 +1,254 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { getLineInfo, Options, parse, parseExpressionAt } from "acorn";
+import { generate } from "escodegen";
+
+/**
+ * The result of parsing our command dialect.
+ *
+ * We support an expanded JS dialect that allows function invocation with the syntax "command [...text|expr]*".  This
+ * allows us to support both JS less verbose "shell command" syntax that nonetheless supports full JS semantics.
+ *
+ * Differentiating between "shell commands" and JS is a bit fiddly but from a high level:
+ *
+ *   - If it starts with a keyword that starts a JS statement or assignment then it is a statement
+ *   - If it starts with a path (e.g. "foo", "foo/bar", "./foo/bar", etc.) it is a command
+ *   - Otherwise it is a JS statement
+ */
+export type Input = EmptyInput | CommandInput | StatementInput | IncompleteInput;
+
+export interface EmptyInput {
+    kind: "empty";
+}
+
+export interface CommandArg {
+    line: number;
+    column: number;
+    js: string;
+}
+
+export interface CommandInput {
+    kind: "command";
+    name: string;
+    args: CommandArg[];
+}
+
+export interface StatementInput {
+    kind: "statement";
+    js: string;
+}
+
+export interface IncompleteInput {
+    kind: "incomplete";
+    error: SyntaxError;
+}
+
+const ACORN_PARSE_OPTIONS: Options = {
+    ecmaVersion: "latest",
+    allowAwaitOutsideFunction: true,
+};
+
+/**
+ * Translate user input into a {@link Input}.
+ */
+export function parseInput(input: string): Input {
+    const inputIsCommand = isCommand(input);
+    try {
+        if (inputIsCommand) {
+            return parseCommand(input);
+        }
+
+        // Only parse so we can detect incomplete statements; otherwise let node do the work
+        parse(input, ACORN_PARSE_OPTIONS);
+        return { kind: "statement", js: input };
+    } catch (e) {
+        if (errorIndicatesIncomplete(e, input)) {
+            return { kind: "incomplete", error: e };
+        }
+        if (!inputIsCommand) {
+            // Let node throw its own error
+            return { kind: "statement", js: input };
+        }
+        throw e;
+    }
+}
+
+function errorIndicatesIncomplete(e: any, input: string): e is SyntaxError {
+    if (e instanceof SyntaxError) {
+        if (e.message.startsWith("Unexpected token") && (e as unknown as { pos: number }).pos === input.length) {
+            return true;
+        }
+        if (e.message.match(/^Unterminated (?:template literal|group|comment|regular expression|template)/)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function parseCommand(command: string): Input {
+    // Find beginning of name
+    let start = 0;
+    while (start < command.length && command[start].match(/\s/)) {
+        start++;
+    }
+
+    if (start === command.length) {
+        return { kind: "empty" };
+    }
+
+    // Find end of name.  We identified command with regexp so this can be simplistic
+    const nameStart = start;
+    while (start < command.length && !command[start].match(/\s/)) {
+        start++;
+    }
+
+    // We now know the command name
+    const name = command.slice(nameStart, start);
+
+    // Extract arguments.  These are either unadorned text
+    const args = Array<CommandArg>();
+    while (command.trim().length) {
+        while (start < command.length && command[start].match(/^\s/)) {
+            start++;
+        }
+
+        if (start === command.length) {
+            break;
+        }
+
+        let isExpression;
+        switch (command[start]) {
+            case "(":
+            case "[":
+            case "{":
+            case '"':
+            case "`":
+            case "'":
+                isExpression = true;
+                break;
+
+            default:
+                isExpression = false;
+                break;
+        }
+
+        const { line, column } = getLineInfo(command, start);
+
+        if (isExpression) {
+            try {
+                const ast = parseExpressionAt(command, start, ACORN_PARSE_OPTIONS);
+                args.push({ js: generate(ast), line, column });
+                start = ast.end;
+            } catch (e) {
+                // acorn sticks error onto end of message; move it into the stack like Node would
+                if (e instanceof SyntaxError) {
+                    let message = e.message;
+                    const match = message.match(/(.*) \(\d+:\d+\)$/);
+                    let location;
+                    if (match) {
+                        message = match[1];
+                        location = message[2];
+                    } else {
+                        const loc = getLineInfo(command, start);
+                        location = `${loc.line}:${loc.column}`;
+                    }
+                    const error = new SyntaxError(message);
+                    error.stack = `SyntaxError: ${message}\n    at matter-cli-input:${location}`;
+                    throw error;
+                }
+            }
+        } else {
+            let end = start;
+
+            while (end < command.length) {
+                if (command[end].match(/\s/)) {
+                    break;
+                }
+                end++;
+            }
+
+            const str = command.slice(start, end);
+            start = end;
+
+            let js;
+            if (str === "true" || str === "false" || str === "NaN" || str === "Infinity" || isNumeric(str)) {
+                js = str;
+            } else {
+                js = JSON.stringify(str);
+            }
+
+            args.push({ js, line, column });
+        }
+    }
+
+    return { kind: "command", name, args };
+}
+
+export function isCommand(input: string) {
+    if (input.match(isCommand.STATEMENT_DETECTOR)) {
+        return false;
+    }
+
+    if (input.match(isCommand.COMMAND_DETECTOR)) {
+        return true;
+    }
+
+    return false;
+}
+
+export namespace isCommand {
+    const STATEMENT_KEYWORDS = [
+        "async",
+        "break",
+        "class",
+        "const",
+        "debugger",
+        "delete",
+        "do",
+        "for",
+        "function",
+        "if",
+        "new",
+        "return",
+        "switch",
+        "throw",
+        "try",
+        "let",
+        "while",
+        "with",
+        "export",
+        "import",
+        "var",
+        "void",
+        "true",
+        "false",
+    ];
+
+    const IDENTIFIER = "[\\p{L}$_][\\p{L}$_0-9]*";
+    const EOW = "(?:\\s|$)";
+
+    const statementStarts = [...STATEMENT_KEYWORDS.map(kw => `${kw}${EOW}`), `${IDENTIFIER}\\s*=`];
+
+    // If this regexp matches, input is NOT a command
+    export const STATEMENT_DETECTOR = new RegExp(`^\\s*(?:${statementStarts.join("|")})`, "u");
+
+    // If above regexp does not match but this one does then input IS a command
+    export const COMMAND_DETECTOR = new RegExp(
+        `^\\s*(?:\\.?/)?${IDENTIFIER}(?:\\/(?:\\.?\\.|${IDENTIFIER}))*${EOW}`,
+        "u",
+    );
+}
+
+/**
+ * {@see https://stackoverflow.com/questions/175739/how-can-i-check-if-a-string-is-a-valid-number}
+ */
+function isNumeric(str: string) {
+    return (
+        !isNaN(str as unknown as number) && // use type coercion to parse the _entirety_ of the string (`parseFloat` alone does not do this)...
+        !isNaN(parseFloat(str))
+    ); // ...and ensure strings of whitespace fail
+}

package/src/providers/endpoint.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Endpoint } from "#node";
+import { Directory, Stat } from "#stat.js";
+
+Stat.provide(endpoint => {
+    if (!isEndpoint(endpoint)) {
+        return;
+    }
+
+    return Directory({
+        definitionAt(path) {
+            const part = endpoint.parts.get(path);
+
+            if (part) {
+                if (!part.lifecycle.isReady) {
+                    return part.construction.then(() => Stat.of(part));
+                }
+                return Stat.of(part);
+            }
+        },
+
+        paths() {
+            if (!endpoint.lifecycle.isPartsReady) {
+                return endpoint.construction.then(() => endpoint.parts.map(part => part.id));
+            }
+            return endpoint.parts.map(part => part.id);
+        },
+    });
+});
+
+function isEndpoint(item: unknown): item is Endpoint {
+    return item instanceof Endpoint;
+}

package/src/providers/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./endpoint.js";
+export * from "./model.js";
+export * from "./module.js";

package/src/providers/model.ts

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Model } from "#model";
+import { Directory, Stat } from "#stat.js";
+
+Stat.provide(model => {
+    if (!isModel(model)) {
+        return;
+    }
+
+    const details: Stat.Base = {
+        name: model.description,
+        summary: model.details,
+        id: model.id,
+        tag: model.tag,
+    };
+
+    if (!model.children.length) {
+        return {
+            kind: "file",
+            ...details,
+        };
+    }
+
+    return Directory({
+        ...details,
+        paths() {
+            return model.children.map(child => child.name);
+        },
+        definitionAt(name: string) {
+            return model.children.find(model => model.name === name);
+        },
+    });
+});
+
+function isModel(model: unknown): model is Model {
+    if (model instanceof Model) {
+        return true;
+    }
+    return false;
+}

package/src/providers/module.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Directory, Stat } from "#stat.js";
+
+Stat.provide(definition => {
+    if (!isModule(definition)) {
+        return;
+    }
+
+    return Directory({
+        paths() {
+            return Object.keys(definition);
+        },
+
+        definitionAt(path: string) {
+            return definition[path];
+        },
+    });
+});
+
+function isModule(definition: unknown): definition is Record<string, unknown> {
+    if (typeof definition !== "object" || definition === null) {
+        return false;
+    }
+    return (definition as any)[Symbol.toStringTag] === "Module";
+}