brass-runtime 1.16.0 → 1.17.0

package/dist/perf/cli.cjs

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+"use strict"; function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+var _chunk7ZPEZ57Lcjs = require('../chunk-7ZPEZ57L.cjs');
+require('../chunk-PD4EJTQC.cjs');
+require('../chunk-KQLYONSE.cjs');
+require('../chunk-5EC274J5.cjs');
+require('../chunk-L6VB5N7Q.cjs');
+require('../chunk-KZJQ723N.cjs');
+require('../chunk-SA6HUJVI.cjs');
+require('../chunk-AGR5B2BC.cjs');
+require('../chunk-JF5WGYJJ.cjs');
+require('../chunk-F6XWZQY4.cjs');
+require('../chunk-WBGRHGBP.cjs');
+require('../chunk-52PPNNI4.cjs');
+require('../chunk-3LOYJFRR.cjs');
+require('../chunk-GLE2WY7Z.cjs');
+require('../chunk-MVGUEJ5Z.cjs');
+require('../chunk-CZIVE6NT.cjs');
+require('../chunk-OBGZSXTJ.cjs');
+
+// src/perf/cli.ts
+async function main(argv) {
+  const cli = parseArgs(argv);
+  if (cli.profile === "runtime-ab") {
+    const report2 = await _chunk7ZPEZ57Lcjs.profileRuntimeAb.call(void 0, cli.runtimeAb);
+    await printReport(cli, report2, _chunk7ZPEZ57Lcjs.formatRuntimeAbReport.call(void 0, report2));
+    return;
+  }
+  if (cli.profile === "runtime-soak") {
+    const report2 = await _chunk7ZPEZ57Lcjs.profileRuntimeSoak.call(void 0, cli.runtimeSoak);
+    await printReport(cli, report2, _chunk7ZPEZ57Lcjs.formatRuntimeSoakReport.call(void 0, report2));
+    return;
+  }
+  if (cli.profile === "http-memory") {
+    const report2 = await _chunk7ZPEZ57Lcjs.profileHttpMemoryLab.call(void 0, cli.httpMemory);
+    await printReport(cli, report2, _chunk7ZPEZ57Lcjs.formatHttpMemoryLabReport.call(void 0, report2));
+    return;
+  }
+  const report = await _chunk7ZPEZ57Lcjs.runBrassPerformanceProfile.call(void 0, cli.options);
+  await printReport(cli, report, _chunk7ZPEZ57Lcjs.formatPerformanceReport.call(void 0, report));
+}
+function parseArgs(argv) {
+  let json = envBool("BRASS_PERF_JSON", false);
+  let profile = envProfile("BRASS_PERF_PROFILE", "all");
+  let calls = envInt("BRASS_PERF_CALLS", void 0);
+  let concurrency = envInt("BRASS_PERF_CONCURRENCY", void 0);
+  let delayMs = envInt("BRASS_PERF_DELAY_MS", void 0);
+  let warmupCalls = envInt("BRASS_PERF_WARMUP_CALLS", void 0);
+  let timeoutMs = envInt("BRASS_PERF_TIMEOUT_MS", void 0);
+  let statsSampleMs = envInt("BRASS_PERF_STATS_SAMPLE_MS", void 0);
+  let runtimeIterations = envInt("BRASS_PERF_RUNTIME_ITERATIONS", void 0);
+  let runtimeChainDepth = envInt("BRASS_PERF_RUNTIME_CHAIN_DEPTH", void 0);
+  let runtimeVariant = envRuntimeVariant("BRASS_PERF_RUNTIME_VARIANT");
+  let baseline = envRuntimeVariant("BRASS_PERF_BASELINE");
+  let candidate = envRuntimeVariant("BRASS_PERF_CANDIDATE");
+  let rounds = envInt("BRASS_PERF_ROUNDS", void 0);
+  let forceGc = envBool("BRASS_PERF_FORCE_GC", false);
+  let variants = envVariants("BRASS_PERF_VARIANTS");
+  let recordHistory = envBool("BRASS_PERF_RECORD_HISTORY", false);
+  let historyDir = envString("BRASS_PERF_HISTORY_DIR");
+  let historyMaxEntries = envInt("BRASS_PERF_HISTORY_MAX_ENTRIES", void 0);
+  let saveBaseline = envString("BRASS_PERF_SAVE_BASELINE");
+  let compareBaseline = envString("BRASS_PERF_COMPARE_BASELINE");
+  let failOnBaselineRegression = envBool("BRASS_PERF_FAIL_ON_BASELINE_REGRESSION", false);
+  let baselineMaxRegressionPercent = envNumber("BRASS_PERF_BASELINE_MAX_REGRESSION_PERCENT");
+  let baselineMaxHeapRegressionPercent = envNumber("BRASS_PERF_BASELINE_MAX_HEAP_REGRESSION_PERCENT");
+  let baselineWarnAtRatio = envNumber("BRASS_PERF_BASELINE_WARN_AT_RATIO");
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--json":
+        json = true;
+        break;
+      case "--profile":
+        profile = parseProfile(readValue(argv, ++i, arg));
+        break;
+      case "--calls":
+        calls = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--concurrency":
+        concurrency = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--delay-ms":
+        delayMs = parseNonNegative(readValue(argv, ++i, arg), arg);
+        break;
+      case "--warmup":
+      case "--warmup-calls":
+        warmupCalls = parseNonNegative(readValue(argv, ++i, arg), arg);
+        break;
+      case "--timeout-ms":
+        timeoutMs = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--stats-sample-ms":
+        statsSampleMs = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--runtime-iterations":
+        runtimeIterations = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--runtime-chain-depth":
+        runtimeChainDepth = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--runtime-variant":
+        runtimeVariant = parseRuntimeVariant(readValue(argv, ++i, arg));
+        break;
+      case "--baseline":
+        baseline = parseRuntimeVariant(readValue(argv, ++i, arg));
+        break;
+      case "--candidate":
+        candidate = parseRuntimeVariant(readValue(argv, ++i, arg));
+        break;
+      case "--rounds":
+        rounds = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--variants":
+        variants = parseVariants(readValue(argv, ++i, arg));
+        break;
+      case "--force-gc":
+        forceGc = true;
+        break;
+      case "--no-gc":
+        forceGc = false;
+        break;
+      case "--no-http":
+        profile = "runtime";
+        break;
+      case "--no-runtime":
+        profile = "http";
+        break;
+      case "--record-history":
+        recordHistory = true;
+        break;
+      case "--history-dir":
+        historyDir = readValue(argv, ++i, arg);
+        break;
+      case "--history-max-entries":
+        historyMaxEntries = parsePositive(readValue(argv, ++i, arg), arg);
+        break;
+      case "--save-baseline":
+        saveBaseline = readValue(argv, ++i, arg);
+        break;
+      case "--compare-baseline":
+        compareBaseline = readValue(argv, ++i, arg);
+        break;
+      case "--fail-on-baseline-regression":
+        failOnBaselineRegression = true;
+        break;
+      case "--baseline-max-regression-percent":
+        baselineMaxRegressionPercent = parseNonNegativeNumber(readValue(argv, ++i, arg), arg);
+        break;
+      case "--baseline-max-heap-regression-percent":
+        baselineMaxHeapRegressionPercent = parseNonNegativeNumber(readValue(argv, ++i, arg), arg);
+        break;
+      case "--baseline-warn-at-ratio":
+        baselineWarnAtRatio = parseNonNegativeNumber(readValue(argv, ++i, arg), arg);
+        break;
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return {
+    json,
+    profile,
+    options: {
+      runtime: profile === "http" ? false : {
+        ...runtimeIterations !== void 0 ? { iterations: runtimeIterations } : {},
+        ...runtimeChainDepth !== void 0 ? { chainDepth: runtimeChainDepth } : {},
+        ...runtimeVariant !== void 0 ? { variant: runtimeVariant } : {}
+      },
+      http: profile === "runtime" ? false : {
+        ...calls !== void 0 ? { calls } : {},
+        ...concurrency !== void 0 ? { concurrency } : {},
+        ...delayMs !== void 0 ? { delayMs } : {},
+        ...warmupCalls !== void 0 ? { warmupCalls } : {},
+        ...timeoutMs !== void 0 ? { timeoutMs } : {},
+        ...statsSampleMs !== void 0 ? { statsSampleMs } : {},
+        ...variants !== void 0 ? { variants } : {},
+        forceGc
+      },
+      memory: { forceGc }
+    },
+    runtimeAb: {
+      baseline,
+      candidate,
+      runtime: {
+        ...runtimeIterations !== void 0 ? { iterations: runtimeIterations } : {},
+        ...runtimeChainDepth !== void 0 ? { chainDepth: runtimeChainDepth } : {}
+      },
+      forceGc
+    },
+    runtimeSoak: {
+      rounds,
+      variant: runtimeVariant,
+      runtime: {
+        ...runtimeIterations !== void 0 ? { iterations: runtimeIterations } : {},
+        ...runtimeChainDepth !== void 0 ? { chainDepth: runtimeChainDepth } : {}
+      },
+      forceGc
+    },
+    httpMemory: {
+      ...calls !== void 0 ? { calls } : {},
+      ...concurrency !== void 0 ? { concurrency } : {},
+      ...delayMs !== void 0 ? { delayMs } : {},
+      ...warmupCalls !== void 0 ? { warmupCalls } : {},
+      ...timeoutMs !== void 0 ? { timeoutMs } : {},
+      ...statsSampleMs !== void 0 ? { statsSampleMs } : {},
+      ...variants !== void 0 ? { variants } : {},
+      rounds,
+      forceGc
+    },
+    history: {
+      recordHistory,
+      ...historyDir !== void 0 ? { historyDir } : {},
+      ...historyMaxEntries !== void 0 ? { maxEntries: historyMaxEntries } : {},
+      ...saveBaseline !== void 0 ? { saveBaseline } : {},
+      ...compareBaseline !== void 0 ? { compareBaseline } : {},
+      failOnBaselineRegression,
+      thresholds: {
+        ...baselineMaxRegressionPercent !== void 0 ? { maxRegressionPercent: baselineMaxRegressionPercent } : {},
+        ...baselineMaxHeapRegressionPercent !== void 0 ? { maxHeapRegressionPercent: baselineMaxHeapRegressionPercent } : {},
+        ...baselineWarnAtRatio !== void 0 ? { warnAtRatio: baselineWarnAtRatio } : {}
+      }
+    }
+  };
+}
+function printHelp() {
+  console.log([
+    "Usage: npm run perf -- [options]",
+    "",
+    "Options:",
+    "  --profile all|runtime|http|runtime-ab|runtime-soak|http-memory",
+    "  --json",
+    "  --calls N",
+    "  --concurrency N",
+    "  --delay-ms N",
+    "  --warmup N",
+    "  --variants node-http-text,default-json,default-json-observed",
+    "  --runtime-iterations N",
+    "  --runtime-chain-depth N",
+    "  --runtime-variant default|fiber-only|active-hooks|recorder|wide-scheduler",
+    "  --baseline default|fiber-only|active-hooks|recorder|wide-scheduler",
+    "  --candidate default|fiber-only|active-hooks|recorder|wide-scheduler",
+    "  --rounds N",
+    "  --force-gc",
+    "  --no-gc",
+    "  --record-history",
+    "  --history-dir PATH",
+    "  --history-max-entries N",
+    "  --save-baseline NAME",
+    "  --compare-baseline NAME",
+    "  --baseline-max-regression-percent N",
+    "  --baseline-max-heap-regression-percent N",
+    "  --baseline-warn-at-ratio N",
+    "  --fail-on-baseline-regression"
+  ].join("\n"));
+}
+async function printReport(cli, report, textReport) {
+  const history = await maybeHandleHistory(cli, report);
+  if (cli.json) {
+    console.log(JSON.stringify(history ? { report, history } : report, null, 2));
+  } else {
+    console.log(history ? `${textReport}
+
+${formatCliHistory(history)}` : textReport);
+  }
+  if (_optionalChain([history, 'optionalAccess', _ => _.comparison]) && !history.comparison.passed && cli.history.failOnBaselineRegression) {
+    process.exitCode = 1;
+  }
+}
+async function maybeHandleHistory(cli, report) {
+  const config = cli.history;
+  if (!config.recordHistory && !config.saveBaseline && !config.compareBaseline) return void 0;
+  const storeOptions = {
+    ...config.historyDir !== void 0 ? { directory: config.historyDir } : {},
+    ...config.maxEntries !== void 0 ? { maxEntries: config.maxEntries } : {},
+    metadata: {
+      cliProfile: cli.profile
+    }
+  };
+  const entry = _chunk7ZPEZ57Lcjs.createPerfHistoryEntry.call(void 0, cli.profile, report, storeOptions);
+  const historyPath = config.recordHistory ? await _chunk7ZPEZ57Lcjs.writePerfHistoryEntry.call(void 0, entry, storeOptions) : void 0;
+  const savedBaseline = config.saveBaseline ? await _chunk7ZPEZ57Lcjs.savePerfBaseline.call(void 0, config.saveBaseline, entry, storeOptions) : void 0;
+  const loadedBaseline = config.compareBaseline ? await _chunk7ZPEZ57Lcjs.loadPerfBaseline.call(void 0, config.compareBaseline, storeOptions) : void 0;
+  if (config.compareBaseline && !loadedBaseline) {
+    throw new Error(`Perf baseline '${config.compareBaseline}' was not found`);
+  }
+  const comparison = loadedBaseline ? _chunk7ZPEZ57Lcjs.comparePerfToBaseline.call(void 0, entry, loadedBaseline, config.thresholds) : void 0;
+  return Object.freeze({
+    entry,
+    ...historyPath !== void 0 ? { historyPath } : {},
+    ...savedBaseline !== void 0 ? { savedBaselinePath: savedBaseline.path } : {},
+    ...comparison !== void 0 ? { comparison } : {}
+  });
+}
+function formatCliHistory(history) {
+  const lines = [];
+  lines.push("Performance history");
+  if (history.historyPath) lines.push(`- recorded: ${history.historyPath}`);
+  if (history.savedBaselinePath) lines.push(`- baseline saved: ${history.savedBaselinePath}`);
+  if (history.comparison) {
+    lines.push("");
+    lines.push(_chunk7ZPEZ57Lcjs.formatPerfBaselineComparison.call(void 0, history.comparison));
+  }
+  return lines.join("\n");
+}
+function readValue(argv, index, flag) {
+  const value = argv[index];
+  if (!value || value.startsWith("--")) throw new Error(`Missing value for ${flag}`);
+  return value;
+}
+function parseProfile(value) {
+  if (value === "all" || value === "runtime" || value === "http" || value === "runtime-ab" || value === "runtime-soak" || value === "http-memory") return value;
+  throw new Error(`Invalid --profile value: ${value}`);
+}
+function parseRuntimeVariant(value) {
+  if (value === "default" || value === "fiber-only" || value === "active-hooks" || value === "recorder" || value === "wide-scheduler") return value;
+  throw new Error(`Invalid runtime variant: ${value}`);
+}
+function parseVariants(value) {
+  const allowed = new Set(_chunk7ZPEZ57Lcjs.HTTP_PROFILE_VARIANTS);
+  return Object.freeze(value.split(",").map((item) => item.trim()).filter(Boolean).map((item) => {
+    if (!allowed.has(item)) {
+      throw new Error(`Invalid HTTP profile variant: ${item}`);
+    }
+    return item;
+  }));
+}
+function parsePositive(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`${flag} must be a positive number`);
+  return Math.floor(parsed);
+}
+function parseNonNegative(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative number`);
+  return Math.floor(parsed);
+}
+function parseNonNegativeNumber(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) throw new Error(`${flag} must be a non-negative number`);
+  return parsed;
+}
+function envInt(name, fallback) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? Math.floor(parsed) : fallback;
+}
+function envNumber(name) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function envString(name) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  return raw.trim();
+}
+function envBool(name, fallback) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  return raw === "1" || raw.toLowerCase() === "true" || raw.toLowerCase() === "yes";
+}
+function envProfile(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  return parseProfile(raw.trim());
+}
+function envRuntimeVariant(name) {
+  const raw = process.env[name];
+  if (!raw || raw.trim() === "") return void 0;
+  return parseRuntimeVariant(raw.trim());
+}
+function envVariants(name) {
+  const raw = process.env[name];
+  if (!raw || raw.trim() === "") return void 0;
+  return parseVariants(raw);
+}
+main(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/dist/perf/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node