@crewhaus/tool-buildperf 0.7.0

package/dist/lib/size.js

@@ -0,0 +1,339 @@
+/**
+ * Artifact size, and the single condition that makes two sizes comparable.
+ *
+ * Compressing bytes is the easy half. The half that costs a team a morning is
+ * comparability: a gzip size is not a property of a file, it is a property of
+ * a file AND the compressor settings. Level 6 against level 9 on the same
+ * bundle differs by several percent — the same order as the regression anyone
+ * is looking for — so a baseline produced at one level and a head measured at
+ * another produce a confident, entirely fabricated "+4.1%". Every number this
+ * module produces therefore travels with the parameters that produced it, and
+ * `parametersMismatch` exists so the caller can refuse rather than subtract.
+ *
+ * Nothing here is statistical. Compression at fixed parameters is
+ * deterministic, so a one-byte difference is a real one-byte difference and
+ * there is no noise floor to declare. That is the whole reason size gating is
+ * a different shape of problem from benchmark gating, which is next door in
+ * `./bench`.
+ */
+import { constants as zlib, brotliCompressSync, gzipSync } from "node:zlib";
+export const COMPRESSION_ALGORITHMS = ["none", "gzip", "brotli"];
+export class SizeError extends Error {
+    name = "SizeError";
+}
+/** zlib's own default is 6; bundler size reporters quote level 9, so that is the default here. */
+const GZIP_DEFAULT_LEVEL = 9;
+/** Brotli's maximum quality, which is what every published "brotli size" means. */
+const BROTLI_DEFAULT_LEVEL = 11;
+/**
+ * Fill in and validate the parameters for a run.
+ *
+ * A level outside the algorithm's range is a refusal, not a clamp: gzip
+ * silently accepting 11 (a brotli quality) and compressing at 9 would produce
+ * a report claiming a level it did not use, which is the exact failure this
+ * module exists to prevent.
+ */
+export function compressionParameters(algorithm, level) {
+    if (algorithm === "none") {
+        if (level !== undefined) {
+            throw new SizeError(`algorithm "none" does not compress, so it has no level (got ${level})`);
+        }
+        return { algorithm, level: null, tuning: {} };
+    }
+    const max = algorithm === "gzip" ? 9 : 11;
+    const chosen = level ?? (algorithm === "gzip" ? GZIP_DEFAULT_LEVEL : BROTLI_DEFAULT_LEVEL);
+    if (!Number.isInteger(chosen) || chosen < 0 || chosen > max) {
+        throw new SizeError(`${algorithm} levels run 0-${max}, got ${chosen}${algorithm === "gzip" && chosen > 9
+            ? " — 10 and 11 are brotli qualities, not gzip levels"
+            : ""}`);
+    }
+    return algorithm === "gzip"
+        ? {
+            algorithm,
+            level: chosen,
+            // memLevel and strategy move the output too; pinned so the recorded
+            // pair (algorithm, level) really does determine the byte count.
+            tuning: { memLevel: 8, strategy: zlib.Z_DEFAULT_STRATEGY, windowBits: 15 },
+        }
+        : {
+            algorithm,
+            level: chosen,
+            tuning: { lgwin: 22, mode: zlib.BROTLI_MODE_GENERIC },
+        };
+}
+/**
+ * The string two parameter sets must agree on for a comparison to mean
+ * anything. Sorted, so key order in a stored baseline cannot change it.
+ */
+export function comparabilityKey(p) {
+    const tuning = Object.keys(p.tuning)
+        .sort()
+        .map((k) => `${k}=${p.tuning[k]}`)
+        .join(",");
+    return `${p.algorithm}/level=${p.level ?? "n/a"}${tuning === "" ? "" : `/${tuning}`}`;
+}
+/**
+ * Why these two sets of parameters cannot be compared, or `null` when they
+ * can. The message names the fields that differ, because "incomparable" on
+ * its own sends the reader to the source.
+ */
+export function parametersMismatch(baseline, head) {
+    if (baseline.algorithm !== head.algorithm) {
+        return `the baseline was measured with ${baseline.algorithm} and this run used ${head.algorithm}; compressed sizes from two algorithms are different measurements, not a change`;
+    }
+    if (baseline.level !== head.level) {
+        return `the baseline was measured at ${baseline.algorithm} level ${baseline.level} and this run at level ${head.level}; the difference between two levels is several percent on typical bundles, which would read as a regression that did not happen`;
+    }
+    const differing = [...new Set([...Object.keys(baseline.tuning), ...Object.keys(head.tuning)])]
+        .filter((k) => baseline.tuning[k] !== head.tuning[k])
+        .sort();
+    if (differing.length > 0) {
+        return `the baseline and this run disagree on ${differing
+            .map((k) => `${k} (${baseline.tuning[k] ?? "unset"} vs ${head.tuning[k] ?? "unset"})`)
+            .join(", ")}; those settings change the compressed size, so the two are not comparable`;
+    }
+    return null;
+}
+/**
+ * Why this baseline's ENTRIES cannot be differenced against a run measured
+ * under `algorithm`, or `null` when they can.
+ *
+ * `parametersMismatch` guards the compressor settings. This guards the
+ * column. Every entry carries two numbers — a raw size and a compressed one —
+ * and which of them a delta is taken on is decided by the algorithm, so a
+ * baseline that declares gzip but stores no `compressedBytes` makes the
+ * obvious `compressed ?? raw` fallback subtract a gzip size from a raw one.
+ * That lands near -70% on real bundles: not a number a reader distrusts, a
+ * number a reader celebrates, and it hides whatever the change actually did.
+ * The reverse — a compressed column under algorithm "none" — fabricates a
+ * regression the same way, so both directions are refused rather than
+ * silently filled in.
+ */
+export function baselineBasisMismatch(algorithm, entries) {
+    if (entries.length === 0)
+        return null;
+    const compresses = algorithm !== "none";
+    const offenders = entries
+        .filter((e) => ((e.compressedBytes ?? null) === null) === compresses)
+        .map((e) => e.path);
+    if (offenders.length === 0)
+        return null;
+    const named = offenders.slice(0, 5).join(", ");
+    const more = offenders.length > 5 ? `, and ${offenders.length - 5} more` : "";
+    return compresses
+        ? `the baseline declares ${algorithm} but has no compressedBytes on ${offenders.length} of its ${entries.length} entries (${named}${more}); this run's sizes are compressed, so pairing them would subtract a compressed size from a raw one and report a saving of roughly the compression ratio. Re-record it from a report of this tool`
+        : `the baseline declares algorithm "none" but carries a compressedBytes on ${offenders.length} of its ${entries.length} entries (${named}${more}), and this run measured raw bytes; the two columns are different measurements, not a change`;
+}
+/** Compressed byte count under `parameters`; the raw length for `none`. */
+export function compressedSize(bytes, parameters) {
+    if (parameters.algorithm === "none")
+        return bytes.byteLength;
+    if (parameters.algorithm === "gzip") {
+        return gzipSync(bytes, {
+            level: parameters.level ?? GZIP_DEFAULT_LEVEL,
+            memLevel: parameters.tuning["memLevel"] ?? 8,
+            strategy: parameters.tuning["strategy"] ?? zlib.Z_DEFAULT_STRATEGY,
+            windowBits: parameters.tuning["windowBits"] ?? 15,
+        }).byteLength;
+    }
+    return brotliCompressSync(bytes, {
+        params: {
+            [zlib.BROTLI_PARAM_QUALITY]: parameters.level ?? BROTLI_DEFAULT_LEVEL,
+            [zlib.BROTLI_PARAM_LGWIN]: parameters.tuning["lgwin"] ?? 22,
+            [zlib.BROTLI_PARAM_MODE]: parameters.tuning["mode"] ?? zlib.BROTLI_MODE_GENERIC,
+            // SIZE_HINT is deliberately not set. It improves the ratio and is what a
+            // bundler passes, but it makes the output depend on a value the caller
+            // never sees, so two tools measuring "the brotli size" would disagree.
+        },
+    }).byteLength;
+}
+// --- joining a hashed build against a baseline ------------------------------
+export const JOIN_MODES = ["exact", "auto", "custom"];
+/**
+ * Whether a filename segment looks like a content hash rather than a name.
+ *
+ * Deliberately conservative in one direction only: `chunk`, `min`, `esm` and
+ * `vendor` must never be eaten, because normalizing a real name merges two
+ * different artifacts into one row. Pure hex needs 6 characters (webpack's
+ * shortest common `[contenthash:6]`); a mixed alphabet needs 8 AND both a
+ * digit and a letter (Vite's base64url ids, e.g. `BXaGz2Qm`). A lowercase
+ * word of 6+ letters that happens to be all hex — `decade`, `defaced` — is
+ * the known false positive, which is why every entry reports the key it was
+ * joined on rather than just the delta.
+ */
+export function looksLikeHash(segment) {
+    if (!/^[0-9a-zA-Z_]+$/.test(segment))
+        return false;
+    if (/^[0-9a-f]{6,}$/i.test(segment))
+        return true;
+    return segment.length >= 8 && /[0-9]/.test(segment) && /[a-zA-Z]/.test(segment);
+}
+/**
+ * The key an entry joins on.
+ *
+ * `exact` is the default and joins on the path as written. It is the right
+ * choice for a build with stable filenames and the wrong one for a hashed
+ * build, where it matches NOTHING on every run — which reads as "every file
+ * is new", not as "the join is broken". `auto` strips hash-shaped segments
+ * from the basename; `custom` applies the caller's own pattern, which is the
+ * escape hatch for a bundler whose scheme the heuristic does not recognise.
+ */
+export function joinKey(path, mode, custom) {
+    if (mode === "exact")
+        return { key: path, normalized: false };
+    if (mode === "custom") {
+        if (custom === undefined)
+            throw new SizeError('join mode "custom" needs a pattern');
+        const key = path.replace(custom, "[hash]");
+        return { key, normalized: key !== path };
+    }
+    const cut = path.lastIndexOf("/");
+    const dir = cut === -1 ? "" : path.slice(0, cut + 1);
+    const base = path.slice(cut + 1);
+    // Split on both separators at once: `app-4f2a1c.js` (Vite, Rollup) and
+    // `app.4f2a1c.js` (webpack) are the same idea with a different delimiter,
+    // and a build can contain both.
+    const parts = base.split(/([.-])/);
+    let normalized = false;
+    const rebuilt = parts.map((part, i) => {
+        // Odd indices are the captured separators; index 0 is the stem, which is
+        // never a hash on its own — `4f2a1c.js` as a whole filename carries no
+        // other identity, and blanking it would merge every such file.
+        if (i === 0 || i % 2 === 1)
+            return part;
+        if (!looksLikeHash(part))
+            return part;
+        normalized = true;
+        return "[hash]";
+    });
+    return { key: `${dir}${rebuilt.join("")}`, normalized };
+}
+/**
+ * Long enough for any real budget, short enough that the matcher's recursion
+ * depth (one frame per token) cannot reach the stack limit.
+ */
+export const MAX_GLOB_LENGTH = 512;
+function tokenizeGlob(pattern) {
+    if (pattern.length > MAX_GLOB_LENGTH) {
+        throw new SizeError(`glob pattern is ${pattern.length} characters, over the ${MAX_GLOB_LENGTH}-character limit; a budget pattern that long is not a path shape`);
+    }
+    const tokens = [];
+    let literal = "";
+    const flush = () => {
+        if (literal !== "") {
+            tokens.push({ kind: "literal", text: literal });
+            literal = "";
+        }
+    };
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            flush();
+            if (pattern[i + 1] === "*") {
+                if (pattern[i + 2] === "/") {
+                    tokens.push({ kind: "anyDir" });
+                    i += 2;
+                    continue;
+                }
+                tokens.push({ kind: "any" });
+                i += 1;
+                continue;
+            }
+            tokens.push({ kind: "segment" });
+            continue;
+        }
+        if (ch === "?") {
+            flush();
+            tokens.push({ kind: "one" });
+            continue;
+        }
+        literal += ch;
+    }
+    flush();
+    return tokens;
+}
+/**
+ * Compile a pattern once, match many paths with it.
+ *
+ * This deliberately does NOT compile to a regular expression. `*` and `**`
+ * become `[^/]*` and `.*`, and a backtracking engine handed several of those
+ * separated by literals explores every way of splitting the string between
+ * them: `*a*a*a…*b` — a 49-character pattern — against sixty `a`s does not
+ * finish, and a budget pattern is caller-supplied. The state here is only
+ * (token index, offset in the path), so memoising it bounds the search at
+ * tokens x length cells no matter how the wildcards are arranged.
+ *
+ * Callers with many paths should hold the matcher: recompiling per path
+ * multiplies the tokenizer by the size of the build.
+ */
+export function compileGlob(pattern) {
+    const tokens = tokenizeGlob(pattern);
+    const width = tokens.length;
+    return (path) => {
+        const n = path.length;
+        const stride = n + 1;
+        // 0 = not yet answered, 1 = no, 2 = yes. `match` only ever descends to a
+        // higher token index, so a cell can never be re-entered while it is being
+        // computed and there is no need for an "in progress" state.
+        const memo = new Uint8Array((width + 1) * stride);
+        const match = (j, i) => {
+            const cell = j * stride + i;
+            const cached = memo[cell];
+            if (cached !== 0)
+                return cached === 2;
+            let answer;
+            if (j === width) {
+                answer = i === n;
+            }
+            else {
+                const token = tokens[j];
+                switch (token.kind) {
+                    case "literal":
+                        answer = path.startsWith(token.text, i) && match(j + 1, i + token.text.length);
+                        break;
+                    case "one":
+                        answer = i < n && path[i] !== "/" && match(j + 1, i + 1);
+                        break;
+                    case "segment": {
+                        answer = false;
+                        for (let k = i;; k++) {
+                            if (match(j + 1, k)) {
+                                answer = true;
+                                break;
+                            }
+                            // A segment wildcard stops at the separator it is not allowed to
+                            // cross, which is what makes `*.js` miss `dist/app.js`.
+                            if (k >= n || path[k] === "/")
+                                break;
+                        }
+                        break;
+                    }
+                    case "any": {
+                        answer = false;
+                        for (let k = i; k <= n; k++) {
+                            if (match(j + 1, k)) {
+                                answer = true;
+                                break;
+                            }
+                        }
+                        break;
+                    }
+                    case "anyDir": {
+                        answer = match(j + 1, i);
+                        for (let k = i; !answer && k < n; k++) {
+                            if (path[k] === "/")
+                                answer = match(j + 1, k + 1);
+                        }
+                        break;
+                    }
+                }
+            }
+            memo[cell] = answer ? 2 : 1;
+            return answer;
+        };
+        return match(0, 0);
+    };
+}
+export function globMatch(pattern, path) {
+    return compileGlob(pattern)(path);
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@crewhaus/tool-buildperf",
+  "version": "0.7.0",
+  "type": "module",
+  "description": "Deterministic build-performance gates: bundle size, benchmark comparison and flaky-test detection against a baseline",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.7.0",
+    "@crewhaus/tool-builder": "0.7.0",
+    "@crewhaus/tool-catalog": "0.7.0",
+    "@crewhaus/tool-math": "0.7.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/tool-executor": "workspace:*"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@crewhaus.ai",
+    "url": "https://crewhaus.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/tool-buildperf"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-buildperf#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
+}