@matter/tools 0.12.2 → 0.12.3-alpha.0-20250205-ad3416ca3

package/src/ansi-text/tokenize.ts

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Chars } from "./chars.js";
+import { Producer } from "./producer.js";
+import { Style } from "./style.js";
+import { Token } from "./token.js";
+
+/**
+ * Convert ANSI text into a sequence of tokens.
+ */
+export function* tokenize(text: string): Producer {
+    for (let pos = 0; pos < text.length; ) {
+        const unit = text[pos];
+        switch (unit) {
+            case "\n":
+                yield { kind: "newline" };
+                pos++;
+                break;
+
+            case "\r":
+                if (text[pos + 1] === "\n") {
+                    yield { kind: "newline" };
+                    pos += 2;
+                } else {
+                    yield { kind: "carriage-return" };
+                    pos += 1;
+                }
+                break;
+
+            case "\t":
+                yield { kind: "tab" };
+                pos++;
+                break;
+
+            case "\x1b":
+                let valid = false;
+                let newColumn: number | undefined;
+                const escapeStart = pos;
+                pos++;
+                switch (text[pos]) {
+                    case "[":
+                        // Fe CSI
+                        pos++;
+
+                        // Valid sequence members
+                        while (text[pos] >= "\x30" && text[pos] <= "\x3f") {
+                            pos++;
+                        }
+
+                        // Valid sequence termination
+                        if (text[pos] >= "\0x40" && text[pos] <= "\x7e") {
+                            const param = text.slice(escapeStart + 2, pos);
+
+                            switch (text[pos]) {
+                                case "m": // SGR (select graphics rendition), the sequence that controls styling
+                                    yield {
+                                        kind: "style",
+                                        style: Style(param),
+                                    };
+                                    pos++;
+                                    continue;
+
+                                case "E": // Move up
+                                case "F": // Move down
+                                    newColumn = 0;
+                                    break;
+
+                                case "G": // Move to column
+                                    newColumn = Number.parseInt(param);
+                                    break;
+
+                                case "H": // Move to row and column
+                                    const [, column] = param.split(";");
+                                    newColumn = column ? Number.parseInt(column) : 0;
+                                    break;
+
+                                case "J": // Clear screen part
+                                    switch (param) {
+                                        case "2": // Entire screen
+                                        case "3": // Entire screen plus scrollback buffer
+                                            newColumn = 0;
+                                    }
+                                    break;
+                            }
+
+                            pos++;
+                            valid = true;
+                        }
+                        break;
+
+                    case "X":
+                    case "]":
+                    case "^":
+                    case "_":
+                        // Fe sequences that take a single string argument (<ESC X>, <ESC ]>, <ESC ^>, <ESC _>
+                        // terminated by "\")
+                        pos++;
+                        while (pos < text.length) {
+                            pos++;
+                            if (text[pos] === "\\") {
+                                valid = true;
+                                break;
+                            }
+                        }
+                        break;
+
+                    default:
+                        const code = text[pos];
+                        if (
+                            (code >= "\x40" && code <= "\x57") ||
+                            (code >= "\x59" && code <= "\x5a") ||
+                            (code >= "\x5c" && code <= "\x5d")
+                        ) {
+                            // Fe sequence not covered above
+                            pos++;
+                            valid = true;
+                        } else if (code >= "\x30" && code <= "0x3f") {
+                            // Fp sequence
+                            pos++;
+                            valid = true;
+                        } else if (code >= "\x60" && code <= "0x7e") {
+                            // Fs sequence
+                            pos++;
+                            valid = true;
+                        } else if (code >= "\x20" && code <= "0x2f") {
+                            pos++;
+                            const code2 = text[pos];
+                            if (code2 >= "\x30" && code2 <= "0x73") {
+                                pos++;
+                                valid = true;
+                            }
+                        }
+                        break;
+                }
+
+                if (valid) {
+                    const token: Token = {
+                        kind: "ansi",
+                        sequence: text.slice(escapeStart, pos),
+                    };
+                    if (newColumn !== undefined && !Number.isNaN(newColumn)) {
+                        token.newColumn = newColumn;
+                    }
+                    yield token;
+                }
+
+                break;
+
+            default:
+                const start = pos;
+
+                // Whitespace - no surrogates, zero-width space does not contribute to width
+                if (Chars.breakingSpace.has(unit)) {
+                    let width = 1;
+                    pos++;
+                    while (Chars.breakingSpace.has(text[pos])) {
+                        pos++;
+                        // No width for zero-width space
+                        if (unit !== "\u200b") {
+                            width++;
+                        }
+                    }
+                    yield {
+                        kind: "breaking",
+                        str: text.slice(start, pos),
+                        width,
+                    };
+                    break;
+                }
+
+                // Scan characters
+                let width = 0;
+                while (pos < text.length) {
+                    let cp = text[pos];
+
+                    // Combine proper surrogate pairs
+                    if (cp >= "\ud800" && cp < "\udc00") {
+                        const nextUnit = text[pos + 1];
+                        if (nextUnit !== undefined && nextUnit >= "\udc00" && nextUnit < "\ue000") {
+                            cp += nextUnit;
+                        }
+                    }
+
+                    if (!cp.match(Chars.nonbreakingText)) {
+                        break;
+                    }
+
+                    pos += cp.length;
+                    if (!cp.match(Chars.zeroWidth)) {
+                        width++;
+                    }
+                }
+
+                // If we detected no characters, the code unit is garbage and we skip it entirely
+                if (start === pos) {
+                    pos++;
+                    break;
+                }
+
+                // Yield the token and skip forward to the last character
+                yield {
+                    kind: "nonbreaking",
+                    str: text.slice(start, pos),
+                    width,
+                };
+        }
+    }
+}

package/src/ansi-text/truncator.ts

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Consumer } from "./consumer.js";
+import { ContiguousOutputSegment } from "./contiguous-output-segment.js";
+import { Producer } from "./producer.js";
+
+/**
+ * Writes lines truncated to a specific width.
+ */
+export class Truncator implements Consumer {
+    #target: Consumer;
+    #addNewline: boolean;
+
+    constructor(target: Consumer, options: { addNewline?: boolean } = {}) {
+        const { addNewline } = options;
+        this.#target = target;
+        this.#addNewline = addNewline === undefined ? true : false;
+    }
+
+    get state() {
+        return this.#target.state;
+    }
+
+    write(...text: Producer.Sequence) {
+        const width = this.#target.state.remainingWidth;
+
+        if (width === undefined) {
+            this.#write(...text);
+            return;
+        }
+
+        const segment = new ContiguousOutputSegment(...text);
+        if (segment.width <= width) {
+            this.#write(...segment.tokens);
+        } else {
+            const scanner = segment.scan();
+
+            this.#write(...scanner.take(width - 1), { kind: "nonbreaking", str: "…", width: 1 });
+            for (const token of scanner) {
+                if (token.kind === "breaking" || token.kind === "nonbreaking") {
+                    continue;
+                }
+                this.#write(token);
+            }
+        }
+    }
+
+    close() {
+        this.#target.close();
+    }
+
+    #write(...text: Producer.Sequence) {
+        if (this.#addNewline) {
+            this.#target.write(...text, { kind: "newline" });
+        } else {
+            this.#target.write(...text);
+        }
+    }
+}

package/src/ansi-text/visible-width-of.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Returns visible width of a space or visible text segment.
+ */
+export function visibleWidthOf(str: string) {
+    let width = 0;
+
+    for (let i = 0; i < str.length; i++) {
+        const charCode = str.charCodeAt(i);
+
+        // Skip zero width characters
+        switch (charCode) {
+            case 0x200b: // zwsp
+            case 0x200c: // zero width non-joiner
+            case 0x200d: // zero width joiner
+            case 0x2060: // word joiner
+            case 0xfeff: // bom
+                continue;
+        }
+
+        // Extend width
+        width++;
+
+        // Skip low surrogate if it properly follows a high surrogate
+        if (charCode >= 0xd800 && charCode < 0xdc00) {
+            const charCode2 = str.charCodeAt(i + 1);
+            if (charCode2 !== undefined && charCode2 >= 0xdc00 && charCode2 < 0xe000) {
+                i++;
+            }
+        }
+    }
+
+    return width;
+}

package/src/ansi-text/wrapper.ts

@@ -0,0 +1,244 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Consumer } from "./consumer.js";
+import { ContiguousOutputSegment } from "./contiguous-output-segment.js";
+import { Producer } from "./producer.js";
+import { Style } from "./style.js";
+import { type TextWriter } from "./text-writer.js";
+import { Token } from "./token.js";
+import { tokenize } from "./tokenize.js";
+
+const NEWLINE: Token = { kind: "newline" };
+const SPACE: Token = { kind: "nonbreaking", str: " ", width: 1 };
+
+/**
+ * Writes to a {@link TextWriter} with support for smart wrapping of text.
+ */
+export class Wrapper implements Consumer {
+    #target: Consumer;
+    #wrapPrefix?: ContiguousOutputSegment;
+    #preserveIndent: boolean;
+    #splitStyling: boolean;
+    #inputState: "newline" | "prefix" | "indent" | "word" | "space" = "newline";
+    #outputState: "newline" | "newwrap" | "inline" = "newline";
+    #indent?: ContiguousOutputSegment;
+    #output?: ContiguousOutputSegment;
+    #onRevert = () => {
+        // When state reverts we may have buffered output we have yet to emit.  Do so now to ensure it receives proper
+        // styling
+        this.#emit();
+    };
+
+    constructor(target: Consumer, options: Wrapper.Options) {
+        const { wrapPrefix, preserveIndent, splitStyling } = options;
+
+        this.#target = target;
+        if (wrapPrefix !== undefined) {
+            this.#wrapPrefix = new ContiguousOutputSegment(...tokenize(wrapPrefix));
+        }
+        this.#preserveIndent = preserveIndent ?? true;
+        this.#splitStyling =
+            splitStyling ?? !!(this.#preserveIndent || this.#wrapPrefix || !this.#target.state.linePrefix);
+
+        this.#target.state.onRevert(this.#onRevert);
+    }
+
+    get state() {
+        return this.#target.state;
+    }
+
+    write(...text: Producer.Sequence) {
+        if (this.#target.state.terminalWidth === undefined) {
+            this.#target.write(...text);
+            return;
+        }
+
+        for (const token of Producer.of(text)) {
+            this.#addToken(token);
+        }
+    }
+
+    close() {
+        this.#emit();
+        this.#target.state.offRevert(this.#onRevert);
+        this.#target.close();
+    }
+
+    [Symbol.dispose]() {
+        this.close();
+    }
+
+    #addToken(token: Token) {
+        switch (token.kind) {
+            case "newline":
+            case "carriage-return":
+                this.#emit();
+                this.#target.write(token);
+                this.#indent = undefined;
+                this.#outputState = this.#inputState = "newline";
+                break;
+
+            case "ansi":
+                this.#enqueue(token);
+
+                switch (token.sequence) {
+                    case Wrapper.prefixStart:
+                        this.#inputState = "prefix";
+                        break;
+
+                    case Wrapper.prefixStop:
+                        this.#inputState = "indent";
+                        break;
+                }
+                break;
+
+            case "style":
+                this.#enqueue(token);
+                break;
+
+            case "nonbreaking":
+                if (this.#inputState === "prefix") {
+                    this.#enqueue(token);
+                    break;
+                }
+                if (this.#inputState === "indent") {
+                    this.#indent = this.#output;
+                    this.#output = undefined;
+                }
+                this.#inputState = "word";
+                this.#enqueue(token);
+                break;
+
+            case "tab":
+            case "breaking":
+                switch (this.#inputState) {
+                    case "newline":
+                        if (this.#preserveIndent) {
+                            this.#enqueue(token);
+                        }
+                        this.#inputState = "indent";
+                        break;
+
+                    case "prefix":
+                    case "indent":
+                        this.#enqueue(token);
+                        break;
+
+                    case "word":
+                        this.#emit();
+                        this.#inputState = "space";
+                        break;
+                }
+                break;
+        }
+    }
+
+    #emit() {
+        if (this.#output === undefined) {
+            return;
+        }
+
+        const outputState = this.#outputState;
+        if (outputState === "newline") {
+            this.#emitPrefix();
+        }
+        this.#outputState = "inline";
+
+        const output = this.#output;
+        this.#output = undefined;
+
+        let remainingWidth = this.#target.state.remainingWidth!;
+
+        // Leave room for a space except at the beginning of the line
+        if (remainingWidth !== undefined && outputState === "inline") {
+            remainingWidth--;
+        }
+
+        // Ideal case - not wrapping or segment fits on current line
+        if (remainingWidth === undefined || output.width <= remainingWidth) {
+            if (outputState === "inline") {
+                this.#target.write(SPACE);
+            }
+            this.#target.write(...output.tokens);
+            return;
+        }
+
+        // Least ideal case - the first- or tertiary- prefix fills up the line by itself.  Give up on wrapping
+        const wrapPrefixWidth = (this.#wrapPrefix?.width ?? 0) + (this.#indent?.width ?? 0);
+        const availableWrappedWidth = this.#target.state.availableWidth! - wrapPrefixWidth;
+        if ((outputState === "newline" && remainingWidth <= 0) || availableWrappedWidth < 0) {
+            this.#target.write(...output.tokens);
+            return;
+        }
+
+        // Second best case - the segment fits on a new line
+        if (output.width < availableWrappedWidth) {
+            this.#wrap();
+            this.#target.write(...output.tokens);
+            return;
+        }
+
+        // Third best case - we need to wrap the segment itself
+        const scanner = output.scan();
+        if (outputState === "inline") {
+            this.#target.write(SPACE);
+        }
+        this.#target.write(...scanner.take(remainingWidth));
+        while (!scanner.done) {
+            this.#wrap();
+            this.#target.write(...scanner.take(availableWrappedWidth));
+        }
+    }
+
+    #emitPrefix(extra?: ContiguousOutputSegment) {
+        if (this.#indent !== undefined) {
+            this.#target.write(...this.#indent.tokens);
+        }
+        if (extra !== undefined) {
+            this.#target.write(...extra.tokens);
+        }
+    }
+
+    #wrap() {
+        let style: Style | undefined;
+        if (this.#splitStyling) {
+            style = this.#target.state.style;
+            this.#target.write({ kind: "style", style: Style.None });
+        }
+        this.#target.write(NEWLINE);
+        this.#emitPrefix(this.#wrapPrefix);
+        if (style) {
+            this.#target.write({ kind: "style", style });
+        }
+    }
+
+    #enqueue(token: Token) {
+        if (this.#output) {
+            this.#output.push(token);
+        } else {
+            this.#output = new ContiguousOutputSegment(token);
+        }
+    }
+}
+
+export namespace Wrapper {
+    export interface Options {
+        wrapPrefix?: string;
+        preserveIndent?: boolean;
+        splitStyling?: boolean;
+    }
+
+    /**
+     * Private - begin demarcation of line prefix.
+     */
+    export const prefixStart = "\x1b[<<~";
+
+    /**
+     * Private - end demarcation of line prefix.
+     */
+    export const prefixStop = "\x1b[>>~";
+}

package/src/building/cli.ts

@@ -6,9 +6,9 @@
 
 import { commander } from "../util/commander.js";
 import { Package } from "../util/package.js";
-import { Builder, Target } from "./builder.js";
 import { buildDocs, mergeDocs } from "./docs.js";
 import { Graph } from "./graph.js";
+import { ProjectBuilder, Target } from "./project-builder.js";
 import { Project } from "./project.js";
 import { syncAllTsconfigs } from "./tsconfig.js";
 
@@ -105,7 +105,7 @@ export async function main(argv = process.argv) {
     }
 
     function builder(graph?: Graph) {
-        return new Builder({ ...args, targets: [...targets], graph });
+        return new ProjectBuilder({ ...args, targets: [...targets], graph });
     }
 
     switch (mode as Mode) {

package/src/building/graph.ts

@@ -7,8 +7,8 @@
 import colors from "ansi-colors";
 import { JsonNotFoundError, Package } from "../util/package.js";
 import { Progress } from "../util/progress.js";
-import { Builder } from "./builder.js";
 import { InternalBuildError } from "./error.js";
+import { ProjectBuilder } from "./project-builder.js";
 import { BUILD_INFO_LOCATION, BuildInformation, Project } from "./project.js";
 
 /**
@@ -72,7 +72,7 @@ export class Graph {
 
     // TODO - parallelization will be trivial except need to update Progress to support display of multiple simultaneous
     // tasks
-    async build(builder: Builder, showSkipped = true) {
+    async build(builder: ProjectBuilder, showSkipped = true) {
         const toBuild = new Set(this.nodes);
 
         const needsConfig = this.nodes.find(node => node.pkg.hasConfig);