@matter/tools 0.12.2 → 0.12.3-alpha.0-20250203-34ba45cae

package/src/building/project-builder.ts

@@ -0,0 +1,230 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { createHash } from "crypto";
+import { Progress } from "../util/progress.js";
+import { BuildError } from "./error.js";
+import { Graph } from "./graph.js";
+import { BuildInformation, Project } from "./project.js";
+import { createTypescriptContext } from "./typescript.js";
+import { TypescriptContext } from "./typescript/context.js";
+
+export enum Target {
+    clean = "clean",
+    types = "types",
+    esm = "esm",
+    cjs = "cjs",
+}
+
+export interface Options {
+    targets?: Target[];
+    clean?: boolean;
+    graph?: Graph;
+}
+
+/**
+ * High-level build coordination.
+ *
+ * Warning: This class is intended for command line use and will process.exit if things go wrong.
+ */
+export class ProjectBuilder {
+    unconditional: boolean;
+    tsContext?: TypescriptContext;
+    graph?: Graph;
+
+    constructor(private options: Options = {}) {
+        this.graph = options.graph;
+        this.unconditional =
+            options.clean || (options.targets !== undefined && options.targets?.indexOf(Target.clean) !== -1);
+    }
+
+    get hasClean() {
+        return this.options.clean;
+    }
+
+    clearClean() {
+        delete this.options.clean;
+    }
+
+    hasTargets() {
+        return this.options.targets && this.options.targets.length > 0;
+    }
+
+    public async configure(project: Project) {
+        if (!project.pkg.hasConfig) {
+            return;
+        }
+
+        await project.configure();
+    }
+
+    public async build(project: Project) {
+        const progress = project.pkg.start("Building");
+
+        try {
+            await this.#doBuild(project, progress);
+        } catch (e: any) {
+            progress.shutdown();
+            process.stderr.write(`${e.stack ?? e.message}\n\n`);
+            process.exit(1);
+        }
+
+        progress.shutdown();
+    }
+
+    async #doBuild(project: Project, progress: Progress) {
+        const targets = this.#selectTargets(project);
+
+        if (targets.has(Target.clean) || this.options.clean) {
+            await progress.run("Clean", () => project.clean());
+        }
+
+        if (!targets.has(Target.types) && !targets.has(Target.esm) && !targets.has(Target.cjs)) {
+            return;
+        }
+
+        const info: BuildInformation = {};
+
+        const config = await project.configure();
+
+        await config?.before?.({ project });
+
+        // If available we use graph to access dependency API shas
+        const graph = this.graph ?? (await Graph.forProject(project.pkg.path));
+        let node: Graph.Node | undefined;
+        if (graph) {
+            node = graph.get(project.pkg.name);
+            for (const dep of node.dependencies) {
+                if (dep.info.apiSha !== undefined) {
+                    if (info.dependencyApiShas === undefined) {
+                        info.dependencyApiShas = {};
+                    }
+                    info.dependencyApiShas[dep.pkg.name] = dep.info.apiSha;
+                }
+            }
+        }
+
+        if (targets.has(Target.types)) {
+            try {
+                // Obtain or initialize typescript solution builder
+                let context = this.tsContext;
+                if (context === undefined) {
+                    context = this.tsContext = await createTypescriptContext(project.pkg.workspace, graph);
+                }
+
+                const refreshCallback = progress.refresh.bind(progress);
+
+                if (project.pkg.isLibrary) {
+                    const apiSha = createHash("sha1");
+
+                    // Our API SHA changes if that of any dependency changes
+                    if (node) {
+                        for (const dep of node.dependencies) {
+                            if (dep.info.apiSha !== undefined) {
+                                apiSha.update(dep.info.apiSha);
+                            }
+                        }
+                    }
+
+                    await progress.run(`Generate ${progress.emphasize("type declarations")}`, async () => {
+                        await context.build(project.pkg, "src", refreshCallback);
+                        await project.hashDeclarations(apiSha);
+                    });
+
+                    // Work-in-progress alternative doc generation implementation
+                    // await progress.run(`Extract ${progress.emphasize("api docs")}`, () =>
+                    //     emitApiDoc(project.pkg, program, progress),
+                    // );
+
+                    info.apiSha = apiSha.digest("hex");
+                } else {
+                    await progress.run(`Validate ${progress.emphasize("types")}`, () =>
+                        context.build(project.pkg, "src", refreshCallback, false),
+                    );
+                }
+                if (project.pkg.hasTests) {
+                    await progress.run(`Validate ${progress.emphasize("test types")}`, () =>
+                        context.build(project.pkg, "test", refreshCallback),
+                    );
+                }
+            } catch (e) {
+                if (e instanceof BuildError) {
+                    progress.failure("Terminating due to type errors");
+                    process.stderr.write(`${e.diagnostics}\n`);
+                    process.exit(1);
+                }
+                throw e;
+            }
+        }
+
+        const formats = Array<"esm" | "cjs">();
+        if (targets.has(Target.esm)) {
+            formats.push("esm");
+        }
+        if (targets.has(Target.cjs)) {
+            formats.push("cjs");
+        }
+
+        if (formats.length) {
+            const groups = [project.pkg.isLibrary ? "library" : "app"];
+            if (project.pkg.hasTests) {
+                groups.push("tests");
+            }
+
+            const formatDesc = formats.map(progress.emphasize).join("+");
+            const groupDesc = groups.map(progress.emphasize).join("+");
+
+            await progress.run(`Transpile ${groupDesc} to ${formatDesc}`, async () => {
+                for (const format of formats) {
+                    await this.#transpile(project, format);
+                }
+            });
+        }
+
+        await config?.after?.({ project });
+
+        // Only update build information when there are no explicit targets so we know it's a full build
+        if (!this.options.targets?.length) {
+            await project.recordBuildInfo(info);
+            if (node) {
+                node.info = info;
+            }
+        }
+    }
+
+    async #transpile(project: Project, format: "esm" | "cjs") {
+        await project.buildSource(format);
+        if (project.pkg.hasTests) {
+            await project.buildTests(format);
+        }
+    }
+
+    #selectTargets(project: Project) {
+        const targets = new Set<string>(this.options.targets);
+
+        if (!targets.size) {
+            targets.add(Target.types);
+
+            if (project.pkg.supportsEsm) {
+                targets.add(Target.esm);
+            }
+
+            if (project.pkg.supportsCjs) {
+                targets.add(Target.cjs);
+            }
+        } else {
+            if (!project.pkg.supportsEsm) {
+                targets.delete(Target.esm);
+            }
+
+            if (!project.pkg.supportsCjs) {
+                targets.delete(Target.cjs);
+            }
+        }
+
+        return targets;
+    }
+}

package/src/building/tsconfig.ts

@@ -50,10 +50,8 @@ async function syncSubproject(node: Graph.Node, path: string, ...extraRefs: stri
 
     const tsconfig = await node.pkg.readJson(tsconfigPath);
 
-    const deps = node.dependencies
-        .filter(dep => dep.pkg.isLibrary)
-        .map(dep => dep.pkg.resolve("src"))
-        .filter(p => !p.match(/packages[\\/]tools/));
+    const deps = node.dependencies.filter(dep => dep.pkg.isLibrary).map(dep => dep.pkg.resolve("src"));
+    //.filter(p => !p.match(/packages[\\/]tools/));
 
     const desired = [...new Set([...deps, ...extraRefs])];
 

package/src/index.ts

@@ -4,12 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export * from "./building/builder.js";
+export * from "./ansi-text/index.js";
+export * from "./ansi-text/std.js";
 export * from "./building/graph.js";
+export * from "./building/project-builder.js";
 export * from "./building/project.js";
 export * from "./running/ensure-compiled.js";
-export * from "./util/commander.js";
-export * from "./util/file.js";
-export * from "./util/glob.js";
-export * from "./util/package.js";
-export * from "./util/progress.js";
+export * from "./util/index.js";

package/src/running/ensure-compiled.ts

@@ -6,8 +6,8 @@
 
 import { exit } from "process";
 import { fileURLToPath } from "url";
-import { Builder } from "../building/builder.js";
 import { Graph } from "../building/graph.js";
+import { ProjectBuilder } from "../building/project-builder.js";
 import { Project } from "../building/project.js";
 import { Package } from "../util/package.js";
 
@@ -39,7 +39,7 @@ export async function ensureCompiled(path: string) {
     // In development we currently build package and dependencies unconditionally before running
     const isDevelopment = !path.match(/[\\/]node_modules[\\/]/);
     if (isDevelopment && format !== "none") {
-        const builder = new Builder();
+        const builder = new ProjectBuilder();
         const dependencies = await Graph.forProject(path);
         if (dependencies) {
             // Project is in a workspace; build along with dependencies from the same workspace

package/src/util/commander.ts

@@ -4,11 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import colors from "ansi-colors";
 import { Command } from "commander";
 import process from "process";
-
-colors.enabled = process.stdout.isTTY;
+import { ansi } from "../ansi-text/text-builder.js";
 
 export function commander(name: string, description: string) {
     return new Command(name)
@@ -16,7 +14,7 @@ export function commander(name: string, description: string) {
         .allowExcessArguments(false)
         .configureOutput({
             writeOut: str => process.stdout.write(`\n${formatHelp(str)}\n`),
-            writeErr: str => process.stderr.write(`\n${colors.red(str)}\n`),
+            writeErr: str => process.stderr.write(`\n${ansi.red(str)}\n`),
         });
 }
 function formatHelp(help: string) {
@@ -24,11 +22,11 @@ function formatHelp(help: string) {
         return help;
     }
 
-    help = help.replace(/^Usage: (\S+)/, (_match, name) => `Usage: ${colors.bold(name)}`);
+    help = help.replace(/^Usage: (\S+)/, (_match, name) => `Usage: ${ansi.bold(name)}`);
     help = help.replace(/^( {2}.+ {2})/gm, (_match, input: string) =>
         input
             .split(",")
-            .map(item => item.replace(/(-*\w+)/, (_match, word) => colors.blue(word)))
+            .map(item => item.replace(/(-*\w+)/, (_match, word) => ansi.blue(word).toString()))
             .join(","),
     );
     return help;

package/src/util/index.ts

@@ -9,3 +9,4 @@ export * from "./errors.js";
 export * from "./file.js";
 export * from "./glob.js";
 export * from "./package.js";
+export * from "./progress.js";

package/src/util/progress.ts

@@ -4,16 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import colors from "ansi-colors";
 import { stderr, stdout } from "process";
+import { screen } from "../ansi-text/screen.js";
+import { std } from "../ansi-text/std.js";
+import { ansi } from "../ansi-text/text-builder.js";
 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);
+    let identity = ansi.bold(pkg.json.name).toString();
     if (pkg.json.version) {
         identity = `${identity}@${pkg.json.version}`;
     }
@@ -50,24 +51,20 @@ const writeStatus = (() => {
     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";
+        text += willOverwrite ? `${screen.erase.toEol}\r` : `${screen.erase.toEol}\n`;
         if (text === lastStatus) {
             return;
         }
 
-        if (lastStatus) {
-            lastStatus = undefined;
-            stdout.write(CLEAR);
-        } else if (needNewline && !text.startsWith("\n")) {
-            stdout.write("\n");
-        }
+        std.out.state({ buffer: true }, () => {
+            if (lastStatus) {
+                lastStatus = undefined;
+            } else if (needNewline && !text.startsWith("\n")) {
+                std.out("\n");
+            }
 
-        stdout.write(text);
+            std.out.writeTruncated(text);
+        });
 
         lastStatus = text;
     };
@@ -86,15 +83,15 @@ export class Progress {
     constructor() {}
 
     emphasize(text: unknown) {
-        return colors.bold(`${text}`);
+        return ansi.bold(`${text}`);
     }
 
     deemphasize(text: unknown) {
-        return colors.dim(`${text}`);
+        return ansi.dim(`${text}`);
     }
 
     skip(why: string, pkg: Package) {
-        stdout.write(colors.dim(`Skip ${packageIdentity(pkg)}: ${why}\n\n`));
+        std.out.write(ansi.dim(`Skip ${packageIdentity(pkg)}: ${why}\n\n`));
     }
 
     startup(what: string, pkgOrOverwrite?: Package | boolean) {
@@ -130,34 +127,32 @@ export class Progress {
             return;
         }
 
-        const subtask = this.#subtasks.length
-            ? colors.dim(` (${colors.dim(this.#subtasks[this.#subtasks.length - 1])})`)
-            : "";
+        const subtask = this.#subtasks.length ? ansi.dim(` (${this.#subtasks[this.#subtasks.length - 1]})`) : "";
 
-        writeStatus(`  ${colors.yellow(this.#spinner)} ${this.#ongoingText}${subtask}`, true);
+        writeStatus(`  ${ansi.yellow(this.#spinner)} ${this.#ongoingText}${subtask}`, true);
     }
 
     success(text: string) {
         this.status = Progress.Status.Success;
-        writeStatus(`  ${colors.green("✓")} ${text} ${this.#duration}`);
+        writeStatus(`  ${ansi.green("✓")} ${text} ${this.#duration}`);
         this.#start = this.#ongoingText = undefined;
     }
 
     failure(text: string) {
         this.status = Progress.Status.Failure;
-        writeStatus(`  ${colors.redBright("✗")} ${text} ${this.#duration}`);
+        writeStatus(`  ${ansi.bright.red("✗")} ${text} ${this.#duration}`);
         this.#start = this.#ongoingText = undefined;
     }
 
     info(label: string, value?: any) {
         if (value) {
-            label = `${colors.dim(label)} ${value}`;
+            label = `${ansi.dim(label)} ${value}`;
         }
-        writeStatus(`  ${colors.dim("‣")} ${label}`);
+        writeStatus(`  ${ansi.dim("‣")} ${label}`);
     }
 
     warn(text: string) {
-        stdout.write(`    ${colors.yellow("Warning:")} ${text}\n`);
+        std.out.write(`    ${ansi.yellow("Warning:")} ${text}\n`);
     }
 
     shutdown() {
@@ -223,7 +218,7 @@ export class Progress {
         } else {
             ms = Math.trunc(ms / 1000);
         }
-        return colors.dim.yellow(`(${ms}s)`);
+        return `${ansi.dim.yellow}(${ms}s)${ansi.not.dim.not.yellow}`;
     }
 }
 
@@ -235,35 +230,3 @@ export namespace Progress {
         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/versioning/versioner.ts

@@ -4,9 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import colors from "ansi-colors";
 import { existsSync, readFileSync } from "fs";
 import { cp, writeFile } from "fs/promises";
+import { ansi } from "../ansi-text/text-builder.js";
 import { Graph } from "../building/graph.js";
 import { execute } from "../running/execute.js";
 import { Package } from "../util/package.js";
@@ -54,7 +54,7 @@ export class Versioner {
         this.#members = new Set(graph.nodes.map(node => node.pkg.name));
 
         for (const node of graph.nodes) {
-            const what = `Apply ${colors.bold(this.#definiteVersion)} to ${colors.bold(node.pkg.name)}`;
+            const what = `Apply ${ansi.bold(this.#definiteVersion)} to ${ansi.bold(node.pkg.name)}`;
             progress?.update(what);
             if (this.#applyOne(node.pkg)) {
                 progress?.success(what);