@kiwa-test/perf-harness 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cardene777
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -27,6 +37,11 @@ __export(index_exports, {
   evaluatePerfGate: () => evaluatePerfGate,
   loadBaseline: () => loadBaseline,
   measure: () => measure,
+  measureConcurrent: () => measureConcurrent,
+  measureMemory: () => measureMemory,
+  resolveKiwaRepoRoot: () => resolveKiwaRepoRoot,
+  runPerf3Layer: () => runPerf3Layer,
+  runPerf3LayerLive: () => runPerf3LayerLive,
   saveBaseline: () => saveBaseline
 });
 module.exports = __toCommonJS(index_exports);
@@ -81,6 +96,66 @@ function percentile(sorted, ratio) {
   return sorted[rank] ?? sorted[sorted.length - 1] ?? 0;
 }
 
+// src/concurrent.ts
+async function measureConcurrent(input) {
+  if (input.concurrency < 1) {
+    throw new Error(`measureConcurrent: concurrency must be >= 1, got ${input.concurrency}`);
+  }
+  if (input.iterationsPerWorker < 1) {
+    throw new Error(
+      `measureConcurrent: iterationsPerWorker must be >= 1, got ${input.iterationsPerWorker}`
+    );
+  }
+  const warmup = input.warmup ?? 0;
+  if (warmup < 0) {
+    throw new Error(`measureConcurrent: warmup must be >= 0, got ${warmup}`);
+  }
+  const worker = async () => {
+    for (let index = 0; index < warmup; index += 1) {
+      await input.fn();
+    }
+    const local = [];
+    for (let index = 0; index < input.iterationsPerWorker; index += 1) {
+      const start = process.hrtime.bigint();
+      await input.fn();
+      const end = process.hrtime.bigint();
+      local.push(Number(end - start) / 1e6);
+    }
+    return local;
+  };
+  const workers = Array.from({ length: input.concurrency }, () => worker());
+  const perWorkerSamples = await Promise.all(workers);
+  const samples = perWorkerSamples.flat();
+  const totalIterations = input.concurrency * input.iterationsPerWorker;
+  return buildMeasureResult(input.name, totalIterations, warmup * input.concurrency, samples);
+}
+
+// src/memory.ts
+async function measureMemory(input) {
+  if (input.iterations < 1) {
+    throw new Error(`measureMemory: iterations must be >= 1, got ${input.iterations}`);
+  }
+  const gcRef = globalThis.gc;
+  const gcExposed = typeof gcRef === "function";
+  if (gcExposed) gcRef();
+  const before = process.memoryUsage();
+  for (let index = 0; index < input.iterations; index += 1) {
+    await input.fn();
+  }
+  if (gcExposed) gcRef();
+  const after = process.memoryUsage();
+  const heapUsedDelta = after.heapUsed - before.heapUsed;
+  return {
+    iterationCount: input.iterations,
+    heapUsedDeltaBytes: heapUsedDelta,
+    heapUsedDeltaPerIterationBytes: heapUsedDelta / input.iterations,
+    rssDeltaBytes: after.rss - before.rss,
+    externalDeltaBytes: after.external - before.external,
+    arrayBuffersDeltaBytes: after.arrayBuffers - before.arrayBuffers,
+    gcExposed
+  };
+}
+
 // src/regression.ts
 function detectRegression(input) {
   const threshold = input.threshold ?? 0.2;
@@ -136,9 +211,9 @@ function sampleStats(samples) {
 // src/baseline.ts
 var import_promises = require("fs/promises");
 var import_node_path = require("path");
-async function loadBaseline(path) {
+async function loadBaseline(path3) {
   try {
-    const body = await (0, import_promises.readFile)(path, "utf8");
+    const body = await (0, import_promises.readFile)(path3, "utf8");
     return JSON.parse(body);
   } catch (error) {
     if (isMissingFile(error)) {
@@ -147,9 +222,9 @@ async function loadBaseline(path) {
     throw error;
   }
 }
-async function saveBaseline(path, result) {
-  await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
-  await (0, import_promises.writeFile)(path, `${JSON.stringify(result, null, 2)}
+async function saveBaseline(path3, result) {
+  await (0, import_promises.mkdir)((0, import_node_path.dirname)(path3), { recursive: true });
+  await (0, import_promises.writeFile)(path3, `${JSON.stringify(result, null, 2)}
 `, "utf8");
 }
 function defaultBaselinePath(moduleName) {
@@ -373,6 +448,343 @@ function formatSignedPct(value) {
   const sign = value > 0 ? "+" : "";
   return `${sign}${value.toFixed(2)}%`;
 }
+
+// src/three-layer.ts
+var import_node_fs = require("fs");
+var import_node_path2 = __toESM(require("path"), 1);
+async function runPerf3Layer(input) {
+  const serialIterations = input.serialIterations ?? 200;
+  const serialWarmup = input.serialWarmup ?? 5;
+  const concurrency = input.concurrency ?? 10;
+  const iterationsPerWorker = input.iterationsPerWorker ?? 50;
+  const memoryIterations = input.memoryIterations ?? 200;
+  const memoryCapDefault = 100 * 1024;
+  const baselinePath = input.baselinePath ?? defaultBaselinePath(input.moduleName);
+  const thresholdDocLink = input.thresholdDocLink ?? "../../quality/perf-thresholds";
+  const priorBaseline = await loadBaseline(baselinePath);
+  const combinedForBaseline = {};
+  const outcomes = [];
+  for (const op of input.ops) {
+    const serial = await measure({
+      name: `${op.name}.serial`,
+      iterations: serialIterations,
+      warmup: serialWarmup,
+      fn: async () => {
+        await op.fn();
+      }
+    });
+    const concurrent = await measureConcurrent({
+      name: `${op.name}.concurrent`,
+      concurrency,
+      iterationsPerWorker,
+      warmup: 2,
+      fn: async () => {
+        await op.fn();
+      }
+    });
+    const memory = await measureMemory({
+      fn: async () => {
+        await op.fn();
+      },
+      iterations: memoryIterations
+    });
+    const concurrentCap = op.concurrentP95CapMs ?? op.serialP95CapMs * 2;
+    const memoryCap = op.memoryArrayBuffersCapBytes ?? memoryCapDefault;
+    const serialGate = evaluatePerfGate({
+      result: serial,
+      thresholds: { p95Ms: op.serialP95CapMs }
+    });
+    const concurrentGate = evaluatePerfGate({
+      result: concurrent,
+      thresholds: { p95Ms: concurrentCap }
+    });
+    const memoryGatePassed = memory.arrayBuffersDeltaBytes < memoryCap;
+    const priorSerial = priorBaseline?.[`${op.name}.serial`];
+    const regression = priorSerial ? detectRegression({ current: serial, baseline: priorSerial, threshold: 0.2 }) : null;
+    combinedForBaseline[`${op.name}.serial`] = serial;
+    combinedForBaseline[`${op.name}.concurrent`] = concurrent;
+    outcomes.push({
+      name: op.name,
+      serial,
+      concurrent,
+      memory,
+      serialGatePassed: serialGate.verdict.passed,
+      concurrentGatePassed: concurrentGate.verdict.passed,
+      memoryGatePassed,
+      regressionVerdict: regression ? regression.verdict : "n/a (baseline seeded)"
+    });
+  }
+  const baselineSeeded = priorBaseline === null;
+  if (baselineSeeded) {
+    await saveBaseline(
+      baselinePath,
+      combinedForBaseline
+    );
+  }
+  const allPassed = outcomes.every(
+    (o) => o.serialGatePassed && o.concurrentGatePassed && o.memoryGatePassed
+  );
+  writeReport({
+    reportPath: input.reportPath,
+    moduleName: input.moduleName,
+    outcomes,
+    ops: input.ops,
+    thresholdDocLink,
+    priorBaseline,
+    concurrency,
+    iterationsPerWorker,
+    memoryIterations,
+    memoryCapDefault
+  });
+  return { outcomes, allPassed, baselineSeeded };
+}
+function writeReport(input) {
+  const lines = [
+    `# Perf Suite \u2014 ${input.moduleName}`,
+    "",
+    `Threshold source: [docs/quality/perf-thresholds.md](${input.thresholdDocLink})`,
+    "",
+    "## Serial p95 (concurrency = 1)",
+    "",
+    "| op | p95 | cap | gate | regression |",
+    "|---|---|---|---|---|"
+  ];
+  input.ops.forEach((op, idx) => {
+    const out = input.outcomes[idx];
+    lines.push(
+      `| ${op.name} | ${out.serial.p95.toFixed(2)}ms | ${op.serialP95CapMs}ms | ${out.serialGatePassed ? "PASS" : "FAIL"} | ${out.regressionVerdict} |`
+    );
+  });
+  lines.push(
+    "",
+    `## Concurrent p95 (concurrency = ${input.concurrency}, ${input.iterationsPerWorker} iter each)`,
+    "",
+    "| op | p95 | cap | gate |",
+    "|---|---|---|---|"
+  );
+  input.ops.forEach((op, idx) => {
+    const out = input.outcomes[idx];
+    const cap = op.concurrentP95CapMs ?? op.serialP95CapMs * 2;
+    lines.push(
+      `| ${op.name} | ${out.concurrent.p95.toFixed(2)}ms | ${cap}ms | ${out.concurrentGatePassed ? "PASS" : "FAIL"} |`
+    );
+  });
+  lines.push(
+    "",
+    `## Memory retention (${input.memoryIterations} iter, arrayBuffers axis is the gate; heap is informational)`,
+    "",
+    "| op | heapUsed \u0394 | arrayBuffers \u0394 | cap | verdict |",
+    "|---|---|---|---|---|"
+  );
+  input.ops.forEach((op, idx) => {
+    const out = input.outcomes[idx];
+    const cap = op.memoryArrayBuffersCapBytes ?? input.memoryCapDefault;
+    lines.push(
+      `| ${op.name} | ${out.memory.heapUsedDeltaBytes} B | ${out.memory.arrayBuffersDeltaBytes} B | ${cap} B | ${out.memoryGatePassed ? "PASS" : "FAIL"} |`
+    );
+  });
+  lines.push("", "## Detailed serial reports", "");
+  input.ops.forEach((op, idx) => {
+    const out = input.outcomes[idx];
+    lines.push(`### ${op.name}`);
+    lines.push("");
+    const priorSerial = input.priorBaseline?.[`${op.name}.serial`];
+    lines.push(
+      emitPerfReport(out.serial, {
+        includeSamples: false,
+        ...priorSerial !== void 0 ? { baseline: priorSerial } : {}
+      })
+    );
+  });
+  (0, import_node_fs.mkdirSync)(import_node_path2.default.dirname(input.reportPath), { recursive: true });
+  (0, import_node_fs.writeFileSync)(input.reportPath, `${lines.join("\n")}
+`, "utf8");
+}
+function resolveKiwaRepoRoot(start) {
+  let current = start;
+  while (true) {
+    const pkgPath = import_node_path2.default.join(current, "package.json");
+    if ((0, import_node_fs.existsSync)(pkgPath)) {
+      const m = JSON.parse((0, import_node_fs.readFileSync)(pkgPath, "utf8"));
+      if (m.name === "kiwa-monorepo") return current;
+    }
+    const parent = import_node_path2.default.dirname(current);
+    if (parent === current) throw new Error(`Could not resolve repo root from ${start}`);
+    current = parent;
+  }
+}
+
+// src/live.ts
+var import_node_fs2 = require("fs");
+var import_node_path3 = __toESM(require("path"), 1);
+async function runPerf3LayerLive(input) {
+  const serialIterations = input.serialIterations ?? 10;
+  const serialWarmup = input.serialWarmup ?? 1;
+  const concurrency = input.concurrency ?? 3;
+  const iterationsPerWorker = input.iterationsPerWorker ?? 3;
+  const memoryIterations = input.memoryIterations ?? 20;
+  const memoryCapDefault = 100 * 1024;
+  const baselinePath = input.baselinePath ?? defaultBaselinePath(`${input.moduleName}.live`);
+  const thresholdDocLink = input.thresholdDocLink ?? "../../quality/perf-thresholds";
+  const priorBaseline = await loadBaseline(baselinePath);
+  const combinedForBaseline = {};
+  const outcomes = [];
+  let baselineSeeded = false;
+  let anySkipped = false;
+  for (const op of input.ops) {
+    const missing = op.requiredEnv.filter((key) => !process.env[key]);
+    if (missing.length > 0) {
+      anySkipped = true;
+      outcomes.push({
+        name: op.name,
+        skipped: true,
+        skipReason: `LIVE_ENV_MISSING: ${missing.join(", ")}`
+      });
+      continue;
+    }
+    const serial = await measure({
+      name: `${op.name}.live.serial`,
+      iterations: serialIterations,
+      warmup: serialWarmup,
+      fn: async () => {
+        await op.fn();
+      }
+    });
+    const concurrent = await measureConcurrent({
+      name: `${op.name}.live.concurrent`,
+      concurrency,
+      iterationsPerWorker,
+      warmup: 1,
+      fn: async () => {
+        await op.fn();
+      }
+    });
+    const memory = await measureMemory({
+      fn: async () => {
+        await op.fn();
+      },
+      iterations: memoryIterations
+    });
+    const concurrentCap = op.concurrentP95CapMs ?? op.serialP95CapMs * 2;
+    const memoryCap = op.memoryArrayBuffersCapBytes ?? memoryCapDefault;
+    const serialGate = evaluatePerfGate({
+      result: serial,
+      thresholds: { p95Ms: op.serialP95CapMs }
+    });
+    const concurrentGate = evaluatePerfGate({
+      result: concurrent,
+      thresholds: { p95Ms: concurrentCap }
+    });
+    const memoryGatePassed = memory.arrayBuffersDeltaBytes < memoryCap;
+    const priorSerial = priorBaseline?.[`${op.name}.live.serial`];
+    const regression = priorSerial ? detectRegression({ current: serial, baseline: priorSerial, threshold: 0.2 }) : null;
+    combinedForBaseline[`${op.name}.live.serial`] = serial;
+    combinedForBaseline[`${op.name}.live.concurrent`] = concurrent;
+    outcomes.push({
+      name: op.name,
+      skipped: false,
+      skipReason: null,
+      serial,
+      concurrent,
+      memory,
+      serialGatePassed: serialGate.verdict.passed,
+      concurrentGatePassed: concurrentGate.verdict.passed,
+      memoryGatePassed,
+      regressionVerdict: regression ? regression.verdict : "n/a (baseline seeded)"
+    });
+  }
+  const anyMeasured = outcomes.some((o) => !o.skipped);
+  if (anyMeasured && priorBaseline === null) {
+    await saveBaseline(baselinePath, combinedForBaseline);
+    baselineSeeded = true;
+  }
+  const allPassed = outcomes.filter((o) => !o.skipped).every((o) => o.serialGatePassed && o.concurrentGatePassed && o.memoryGatePassed);
+  writeLiveReport({
+    reportPath: input.reportPath,
+    moduleName: input.moduleName,
+    outcomes,
+    ops: input.ops,
+    thresholdDocLink,
+    priorBaseline,
+    concurrency,
+    iterationsPerWorker,
+    memoryIterations,
+    memoryCapDefault
+  });
+  return { outcomes, allPassed, anySkipped, baselineSeeded };
+}
+function writeLiveReport(input) {
+  const lines = [
+    `# Perf Suite \u2014 ${input.moduleName} (LIVE)`,
+    "",
+    `Threshold source: [docs/quality/perf-thresholds.md \xA7 Real-API measurement mode](${input.thresholdDocLink})`,
+    ""
+  ];
+  const skippedOps = input.outcomes.filter((o) => o.skipped);
+  const measuredOps = input.outcomes.filter((o) => !o.skipped);
+  if (skippedOps.length > 0) {
+    lines.push("## Skipped ops (missing env)", "", "| op | reason |", "|---|---|");
+    for (const o of skippedOps) lines.push(`| ${o.name} | ${o.skipReason} |`);
+    lines.push("");
+  }
+  if (measuredOps.length === 0) {
+    lines.push("_No live ops ran this pass. Set the required env vars to enable._");
+  } else {
+    lines.push("## Serial p95 (LIVE)", "");
+    lines.push("| op | p95 | cap | gate | regression |");
+    lines.push("|---|---|---|---|---|");
+    input.ops.forEach((op) => {
+      const out = input.outcomes.find((o) => o.name === op.name);
+      if (!out || out.skipped || !out.serial) return;
+      lines.push(
+        `| ${op.name} | ${out.serial.p95.toFixed(2)}ms | ${op.serialP95CapMs}ms | ${out.serialGatePassed ? "PASS" : "FAIL"} | ${out.regressionVerdict} |`
+      );
+    });
+    lines.push(
+      "",
+      `## Concurrent p95 (LIVE, concurrency = ${input.concurrency})`,
+      "",
+      "| op | p95 | cap | gate |",
+      "|---|---|---|---|"
+    );
+    input.ops.forEach((op) => {
+      const out = input.outcomes.find((o) => o.name === op.name);
+      if (!out || out.skipped || !out.concurrent) return;
+      const cap = op.concurrentP95CapMs ?? op.serialP95CapMs * 2;
+      lines.push(
+        `| ${op.name} | ${out.concurrent.p95.toFixed(2)}ms | ${cap}ms | ${out.concurrentGatePassed ? "PASS" : "FAIL"} |`
+      );
+    });
+    lines.push("", "## Memory retention (LIVE)", "");
+    lines.push("| op | heapUsed \u0394 | arrayBuffers \u0394 | cap | verdict |");
+    lines.push("|---|---|---|---|---|");
+    input.ops.forEach((op) => {
+      const out = input.outcomes.find((o) => o.name === op.name);
+      if (!out || out.skipped || !out.memory) return;
+      const cap = op.memoryArrayBuffersCapBytes ?? input.memoryCapDefault;
+      lines.push(
+        `| ${op.name} | ${out.memory.heapUsedDeltaBytes} B | ${out.memory.arrayBuffersDeltaBytes} B | ${cap} B | ${out.memoryGatePassed ? "PASS" : "FAIL"} |`
+      );
+    });
+    lines.push("", "## Detailed serial reports", "");
+    input.ops.forEach((op) => {
+      const out = input.outcomes.find((o) => o.name === op.name);
+      if (!out || out.skipped || !out.serial) return;
+      lines.push(`### ${op.name}`);
+      lines.push("");
+      const priorSerial = input.priorBaseline?.[`${op.name}.live.serial`];
+      lines.push(
+        emitPerfReport(out.serial, {
+          includeSamples: false,
+          ...priorSerial !== void 0 ? { baseline: priorSerial } : {}
+        })
+      );
+    });
+  }
+  (0, import_node_fs2.mkdirSync)(import_node_path3.default.dirname(input.reportPath), { recursive: true });
+  (0, import_node_fs2.writeFileSync)(input.reportPath, `${lines.join("\n")}
+`, "utf8");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   buildMeasureResult,
@@ -382,6 +794,11 @@ function formatSignedPct(value) {
   evaluatePerfGate,
   loadBaseline,
   measure,
+  measureConcurrent,
+  measureMemory,
+  resolveKiwaRepoRoot,
+  runPerf3Layer,
+  runPerf3LayerLive,
   saveBaseline
 });
 //# sourceMappingURL=index.cjs.map