@electron-stagewright/plugin-budget 0.0.0-stage → 0.2.0

package/dist/check-api.js

@@ -0,0 +1,11 @@
+/**
+ * `@electron-stagewright/plugin-budget/check`: the budget and run formats and the check, without
+ * core, the plugin, or anything that launches Electron.
+ *
+ * @module
+ */
+export { BUDGET_PLATFORMS, BudgetFileError, MEMORY_METRICS, PHASES, PROCESS_TYPES, budgetSchema, loadBudget, parseBudget, } from './budget.js';
+export { checkRun } from './check.js';
+export { compareRuns, renderCheckReport, renderComparison } from './render.js';
+export { RUN_FORMAT, RUN_SCHEMA_VERSION, RunFileError, createRun, loadRun, memoryByType, mergeRuns, runSchema, summarizeLatencies, summarizeRun, } from './run.js';
+//# sourceMappingURL=check-api.js.map

package/dist/check-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-api.js","sourceRoot":"","sources":["../src/check-api.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,MAAM,EACN,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,GACZ,MAAM,aAAa,CAAA;AAUpB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAErC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE9E,OAAO,EACL,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,OAAO,EACP,YAAY,EACZ,SAAS,EACT,SAAS,EACT,kBAAkB,EAClB,YAAY,GACb,MAAM,UAAU,CAAA"}

package/dist/check.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Compare a run to a budget. Pure: no I/O, no Electron.
+ *
+ * @module
+ */
+import { type Budget, type Phase } from './budget.js';
+import { type BudgetRun, type SummaryRow } from './run.js';
+export type CheckStatus = 'pass' | 'fail' | 'unmeasured';
+export interface CheckResult {
+    readonly id: string;
+    readonly status: CheckStatus;
+    readonly unit: SummaryRow['unit'];
+    readonly limit: number;
+    /** `limit` plus the tolerance; the value that actually gates. */
+    readonly allowed: number;
+    readonly actual?: number;
+    readonly phase?: Phase;
+    readonly metric?: string;
+    /** Why it is unmeasured. */
+    readonly detail?: string;
+}
+export interface CheckReport {
+    /** False on any failure, and always false when nothing at all was measured. */
+    readonly passed: boolean;
+    readonly reason?: 'NO_EXPECTATIONS' | 'NO_MEASUREMENTS' | 'UNMEASURED' | 'OVER_BUDGET';
+    readonly summary: {
+        readonly pass: number;
+        readonly fail: number;
+        readonly unmeasured: number;
+    };
+    readonly results: readonly CheckResult[];
+}
+export interface CheckOptions {
+    /** Ignore every `thresholdPercent`: the limit itself gates. */
+    readonly ignoreThreshold?: boolean;
+    /** @deprecated Same as `ignoreThreshold`; it never meant "fail instead of warn". */
+    readonly strict?: boolean;
+    /** Treat a budgeted metric the run did not measure as a failure. */
+    readonly requireMeasurement?: boolean;
+    /** Read every metric from this phase instead of the budget's own phases. */
+    readonly phase?: Phase;
+    /**
+     * Rounds a runtime metric needs before its median counts; fewer leaves it `unmeasured`. Use it
+     * with `--rounds N` so that a median never rests on one launch. Bundle entries are exempt.
+     */
+    readonly minSamples?: number;
+}
+/** Compare `run` to `budget` for the platform the run was measured on. */
+export declare function checkRun(run: BudgetRun, budget: Budget, options?: CheckOptions): CheckReport;
+//# sourceMappingURL=check.d.ts.map

package/dist/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiB,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAgB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAA;AAExE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAA;AAExD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,YAAY,GAAG,aAAa,CAAA;IACtF,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/F,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;CACzC;AAED,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,oEAAoE;IACpE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAuKD,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAuDhG"}

package/dist/check.js

@@ -0,0 +1,198 @@
+/**
+ * Compare a run to a budget. Pure: no I/O, no Electron.
+ *
+ * @module
+ */
+import { PROCESS_TYPES } from './budget.js';
+import { summarizeRun } from './run.js';
+const ANY_PHASE_ORDER = ['warm', 'live', 'cold'];
+function expectations(budget, run, options) {
+    const platform = run.platform;
+    const list = [];
+    const tolerance = (own) => options.ignoreThreshold === true || options.strict === true
+        ? 0
+        : (own ?? budget.thresholdPercent ?? 0);
+    if (budget.startup !== undefined) {
+        list.push({
+            id: 'startup.firstWindowMs',
+            section: 'startup',
+            unit: 'ms',
+            limit: budget.startup.maxFirstWindowMs,
+            thresholdPercent: tolerance(budget.startup.thresholdPercent),
+            phase: options.phase ?? budget.startup.phase ?? 'cold',
+        });
+    }
+    const memory = budget.memory?.[platform];
+    if (memory !== undefined) {
+        const prefix = memory.aggregate === 'peak' ? 'memoryPeak' : 'memory';
+        // Unset: the first of warm, live, cold whose rounds measured memory, else that has rounds.
+        const roundsOf = (measured) => ANY_PHASE_ORDER.find((phase) => run.rounds.some((round) => round.phase === phase && (!measured || round.measurement[prefix] !== undefined)));
+        const memoryPhase = options.phase ?? memory.phase ?? roundsOf(true) ?? roundsOf(false);
+        const base = {
+            section: 'memory',
+            unit: 'MB',
+            thresholdPercent: tolerance(memory.thresholdPercent),
+            ...(memoryPhase === undefined ? {} : { phase: memoryPhase }),
+            metric: memory.metric,
+        };
+        for (const type of PROCESS_TYPES) {
+            const max = memory.perTypeMb?.[type];
+            if (max !== undefined)
+                list.push({ ...base, id: `${prefix}.${type}`, limit: max });
+        }
+        if (memory.totalWithoutGpuMb !== undefined) {
+            list.push({ ...base, id: `${prefix}.totalWithoutGpu`, limit: memory.totalWithoutGpuMb });
+        }
+        if (memory.totalMb !== undefined) {
+            list.push({ ...base, id: `${prefix}.total`, limit: memory.totalMb });
+        }
+    }
+    const mainThread = budget.mainThread;
+    if (mainThread !== undefined) {
+        const base = {
+            section: 'mainThread',
+            thresholdPercent: tolerance(mainThread.thresholdPercent),
+            ...(options.phase === undefined ? {} : { phase: options.phase }),
+        };
+        if (mainThread.maxBlockedPercent !== undefined) {
+            list.push({
+                ...base,
+                id: 'mainThread.blockedPercent',
+                unit: '%',
+                limit: mainThread.maxBlockedPercent,
+            });
+        }
+        if (mainThread.maxStallMs !== undefined) {
+            list.push({ ...base, id: 'mainThread.maxStallMs', unit: 'ms', limit: mainThread.maxStallMs });
+        }
+    }
+    const ipc = budget.ipc;
+    if (ipc !== undefined) {
+        const base = {
+            section: 'ipc',
+            unit: 'ms',
+            thresholdPercent: tolerance(ipc.thresholdPercent),
+            ...(options.phase === undefined ? {} : { phase: options.phase }),
+        };
+        if (ipc.maxP95Ms !== undefined)
+            list.push({ ...base, id: 'ipc.p95Ms', limit: ipc.maxP95Ms });
+        if (ipc.maxP99Ms !== undefined)
+            list.push({ ...base, id: 'ipc.p99Ms', limit: ipc.maxP99Ms });
+    }
+    for (const entry of budget.bundle?.entries ?? []) {
+        list.push({
+            id: `bundle.${entry.name ?? entry.path}`,
+            section: 'bundle',
+            unit: 'KB',
+            limit: entry.maxKb,
+            thresholdPercent: tolerance(budget.bundle?.thresholdPercent),
+        });
+    }
+    return list;
+}
+function findRow(rows, expectation) {
+    const candidates = rows.filter((row) => row.id === expectation.id &&
+        (expectation.metric === undefined || row.metric === expectation.metric));
+    if (expectation.section === 'bundle')
+        return candidates[0];
+    if (expectation.phase !== undefined) {
+        return candidates.find((row) => row.phase === expectation.phase);
+    }
+    for (const phase of ANY_PHASE_ORDER) {
+        const row = candidates.find((candidate) => candidate.phase === phase);
+        if (row !== undefined)
+            return row;
+    }
+    return undefined;
+}
+function unmeasuredDetail(run, expectation) {
+    if (expectation.section === 'bundle') {
+        const id = expectation.id.slice('bundle.'.length);
+        const entry = run.bundle?.entries.find((candidate) => candidate.id === id);
+        return entry?.unavailable ?? 'the run has no measurement for this bundle entry';
+    }
+    const rounds = run.rounds.filter((round) => expectation.phase === undefined || round.phase === expectation.phase);
+    if (rounds.length === 0) {
+        return expectation.phase === undefined
+            ? 'the run has no rounds'
+            : `the run has no ${expectation.phase} round`;
+    }
+    if (expectation.section === 'memory' &&
+        expectation.id.startsWith('memoryPeak.') &&
+        rounds.every((round) => round.measurement.memoryPeak === undefined) &&
+        rounds.some((round) => round.measurement.memory !== undefined)) {
+        const failed = rounds
+            .map((round) => round.measurement.unavailable?.['memoryPeak'])
+            .find((value) => value !== undefined);
+        return failed ?? 'the run has no peak sample; measure with --memory-sample-ms';
+    }
+    if (expectation.section === 'memory') {
+        const measured = rounds.map((round) => round.measurement.memory?.metric).find(Boolean);
+        // Megabytes in another metric are a different quantity, never a comparable one.
+        if (measured !== undefined && measured !== expectation.metric) {
+            return `the run measured ${measured}, the budget names ${expectation.metric}`;
+        }
+    }
+    if (expectation.section === 'ipc' && rounds.some((r) => r.measurement.ipc?.count === 0)) {
+        return 'the IPC probe completed no round trip';
+    }
+    const reason = rounds
+        .map((round) => round.measurement.unavailable?.[expectation.section])
+        .find((value) => value !== undefined);
+    return reason ?? `the run did not measure ${expectation.id}`;
+}
+/** Compare `run` to `budget` for the platform the run was measured on. */
+export function checkRun(run, budget, options = {}) {
+    const rows = summarizeRun(run);
+    const results = expectations(budget, run, options).map((expectation) => {
+        // Divide last: 200 * (1 + 15 / 100) is 229.99999999999997, which would fail a 230.
+        const exactAllowed = (expectation.limit * (100 + expectation.thresholdPercent)) / 100;
+        const allowed = Math.round(exactAllowed * 10) / 10;
+        const base = {
+            id: expectation.id,
+            unit: expectation.unit,
+            limit: expectation.limit,
+            allowed,
+            ...(expectation.phase === undefined ? {} : { phase: expectation.phase }),
+            ...(expectation.metric === undefined ? {} : { metric: expectation.metric }),
+        };
+        const row = findRow(rows, expectation);
+        if (row === undefined) {
+            return { ...base, status: 'unmeasured', detail: unmeasuredDetail(run, expectation) };
+        }
+        const needed = options.minSamples ?? 1;
+        if (expectation.section !== 'bundle' && row.samples < needed) {
+            return {
+                ...base,
+                ...(row.phase === undefined ? {} : { phase: row.phase }),
+                status: 'unmeasured',
+                actual: row.value,
+                detail: `${row.samples} of the ${needed} rounds needed measured ${expectation.id}`,
+            };
+        }
+        return {
+            ...base,
+            ...(row.phase === undefined ? {} : { phase: row.phase }),
+            status: row.exact <= exactAllowed ? 'pass' : 'fail',
+            actual: row.value,
+        };
+    });
+    const count = (status) => results.filter((result) => result.status === status).length;
+    const summary = { pass: count('pass'), fail: count('fail'), unmeasured: count('unmeasured') };
+    const reason = results.length === 0
+        ? 'NO_EXPECTATIONS'
+        : summary.fail > 0
+            ? 'OVER_BUDGET'
+            : summary.pass === 0
+                ? 'NO_MEASUREMENTS'
+                : options.requireMeasurement === true && summary.unmeasured > 0
+                    ? 'UNMEASURED'
+                    : undefined;
+    return {
+        passed: reason === undefined,
+        ...(reason === undefined ? {} : { reason }),
+        summary,
+        results,
+    };
+}
+//# sourceMappingURL=check.js.map

package/dist/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../src/check.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * `electron-stagewright-budget`: the CI face of the budget plugin.
+ *
+ * Exit codes: 0 within budget, 1 over budget or nothing measured, 2 usage, unreadable input, or any
+ * other error.
+ *
+ * @module
+ */
+import { type Phase } from './budget.js';
+import { measureApp, type LaunchPhase } from './measure.js';
+export declare const BUDGET_EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly OVER_BUDGET: 1;
+    readonly USAGE: 2;
+};
+export type BudgetExitCode = (typeof BUDGET_EXIT_CODES)[keyof typeof BUDGET_EXIT_CODES];
+export interface BudgetCliIo {
+    readonly stdout: (text: string) => void;
+    readonly stderr: (text: string) => void;
+}
+export type BudgetCliOptions = {
+    readonly command: 'help';
+} | {
+    readonly command: 'check';
+    readonly runPaths: readonly string[];
+    readonly budgetPath: string;
+    readonly noTolerance: boolean;
+    readonly minSamples?: number;
+    readonly requireMeasurement: boolean;
+    readonly phase?: Phase;
+    readonly json: boolean;
+    readonly deprecatedStrict?: true;
+} | {
+    readonly command: 'compare';
+    readonly beforePath: string;
+    readonly afterPath: string;
+    readonly json: boolean;
+} | {
+    readonly command: 'bundle';
+    readonly budgetPath: string;
+    readonly root?: string;
+    readonly outPath?: string;
+    readonly noTolerance: boolean;
+    readonly json: boolean;
+    readonly deprecatedStrict?: true;
+} | MeasureCliOptions;
+export interface MeasureCliOptions {
+    readonly command: 'measure';
+    readonly main?: string;
+    readonly executablePath?: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly budgetPath?: string;
+    readonly rounds: number;
+    readonly phases: readonly LaunchPhase[];
+    readonly settleMs?: number;
+    readonly windowMs?: number;
+    readonly workloadPath?: string;
+    readonly workloadTimeoutMs?: number;
+    readonly beforeRoundPath?: string;
+    readonly memorySampleMs?: number;
+    readonly skipFailedRounds: boolean;
+    readonly minSamples?: number;
+    readonly phase?: Phase;
+    readonly label?: string;
+    readonly outPath?: string;
+    readonly check: boolean;
+    readonly noTolerance: boolean;
+    readonly requireMeasurement: boolean;
+    readonly json: boolean;
+    readonly deprecatedStrict?: true;
+}
+/** Seam for tests: the launch-and-measure step. */
+export interface BudgetCliDependencies {
+    readonly measureApp: typeof measureApp;
+}
+export declare function formatBudgetCliHelp(): string;
+/** Strict parser: an unknown flag or a missing value is a usage error. */
+export declare function parseBudgetCliArgs(argv: readonly string[]): BudgetCliOptions;
+/** Execute already-parsed options. Throws the typed file errors; the caller maps them to exit 2. */
+export declare function runBudgetCli(options: BudgetCliOptions, io?: BudgetCliIo, deps?: BudgetCliDependencies): Promise<BudgetExitCode>;
+/** Parse and execute; never throws. */
+export declare function runBudgetCliCommand(argv: readonly string[], io?: BudgetCliIo, deps?: BudgetCliDependencies): Promise<BudgetExitCode>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}