@aethervtt/shard-verify 0.0.0-stage → 0.2.0

package/dist/run.js

@@ -0,0 +1,19 @@
+import { ShardError } from "@aethervtt/shard-core";
+function addApproval(file, approval) {
+  if (!approval.reason.trim()) {
+    throw new ShardError(
+      "verify/approval-needs-reason",
+      `Approving "${approval.shot}" needs a reason`,
+      {
+        hint: 'Say why it looks the way it does: shard approve <shot> --reason "Shadows are softer since 0058".'
+      }
+    );
+  }
+  return {
+    version: 1,
+    approvals: [...file?.approvals ?? [], { ...approval, reason: approval.reason.trim() }]
+  };
+}
+export {
+  addApproval
+};

package/dist/stats.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Timestamped samples in a fixed ring: pushing never allocates, so a frame can record into it. The
+ * oldest samples fall off once it's full.
+ */
+export declare class SampleRing {
+    private readonly times;
+    private readonly values;
+    private next;
+    private count;
+    constructor(capacity: number);
+    get size(): number;
+    push(time: number, value: number): void;
+    clear(): void;
+    /** The values of samples at or after `since`, oldest first. Allocates: not for frames. */
+    since(since: number): Float64Array;
+}
+/** Nearest-rank percentile (`p` in 0..1) of `values`, which it sorts in place. 0 when empty. */
+export declare function percentile(values: Float64Array, p: number): number;
+/** p50, p95 and p99 of `values` (sorted in place). */
+export declare function distribution(values: Float64Array): {
+    p50: number;
+    p95: number;
+    p99: number;
+};
+/** Rounds to 0.01: records stay readable, and the rounding is far below any budget. */
+export declare function round(value: number): number;

package/dist/stats.js

@@ -0,0 +1,56 @@
+class SampleRing {
+  times;
+  values;
+  next = 0;
+  count = 0;
+  constructor(capacity) {
+    this.times = new Float64Array(capacity);
+    this.values = new Float64Array(capacity);
+  }
+  get size() {
+    return this.count;
+  }
+  push(time, value) {
+    this.times[this.next] = time;
+    this.values[this.next] = value;
+    this.next = (this.next + 1) % this.times.length;
+    if (this.count < this.times.length) this.count++;
+  }
+  clear() {
+    this.next = 0;
+    this.count = 0;
+  }
+  /** The values of samples at or after `since`, oldest first. Allocates: not for frames. */
+  since(since) {
+    const capacity = this.times.length;
+    const start = (this.next - this.count + capacity) % capacity;
+    const out = [];
+    for (let i = 0; i < this.count; i++) {
+      const at = (start + i) % capacity;
+      if (this.times[at] >= since) out.push(this.values[at]);
+    }
+    return Float64Array.from(out);
+  }
+}
+function percentile(values, p) {
+  if (values.length === 0) return 0;
+  values.sort();
+  const rank = Math.max(1, Math.ceil(p * values.length));
+  return values[rank - 1];
+}
+function distribution(values) {
+  return {
+    p50: percentile(values, 0.5),
+    p95: percentile(values, 0.95),
+    p99: percentile(values, 0.99)
+  };
+}
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+export {
+  SampleRing,
+  distribution,
+  percentile,
+  round
+};

package/dist/thresholds.d.ts

@@ -0,0 +1,51 @@
+import type { Thresholds } from './plan.js';
+import { type PerfRecord } from './record.js';
+/** One broken budget: the metric, the value, the budget, and the baseline it came from. */
+export interface Breach {
+    scenario: string;
+    metric: string;
+    renderer: string;
+    fixture: string;
+    /** Undefined when the record has no such metric. */
+    value: number | undefined;
+    /** The limit that was broken, e.g. `max 16.7` or `max 1.0 × three (12.1) = 12.1`. */
+    budget: string;
+    baseline?: {
+        renderer: string;
+        value: number | undefined;
+    };
+    message: string;
+    /** A span budget's span (0074). */
+    span?: string;
+    /**
+     * Against a baseline: the spans whose p95 grew the most from its record to this one (0074), when
+     * both records have a breakdown.
+     */
+    grew?: {
+        span: string;
+        p95: number;
+        baselineP95: number;
+    }[];
+}
+export interface PerfCheck {
+    pass: boolean;
+    /** Rules applied, over every record they applied to. */
+    checked: number;
+    breaches: Breach[];
+}
+/**
+ * Applies a plan's thresholds to the records of one run (0062). Absolute rules apply to every
+ * record of the scenario whose renderer isn't a ratio baseline there. A ratio rule compares with
+ * the baseline renderer's record of the same scenario and fixture, on the same device where the
+ * run has one; with no baseline record, the rule fails.
+ */
+export declare function checkThresholds(records: readonly PerfRecord[], thresholds: Thresholds): PerfCheck;
+/**
+ * The spans whose p95 grew the most from `baseline` to `record` (0074), largest growth first: a
+ * span missing from the baseline's breakdown counts from 0. Empty unless both have a breakdown.
+ */
+export declare function spansThatGrew(record: PerfRecord, baseline: PerfRecord, limit?: number): {
+    span: string;
+    p95: number;
+    baselineP95: number;
+}[];

package/dist/thresholds.js

@@ -0,0 +1,156 @@
+import { valueAt } from "./expect.js";
+import { rendererName } from "./record.js";
+function checkThresholds(records, thresholds) {
+  const breaches = [];
+  let checked = 0;
+  for (const [scenario, rules] of Object.entries(thresholds)) {
+    const metrics = [];
+    for (const [metric, rule] of Object.entries(rules)) {
+      if (metric !== "spans" && rule && !Array.isArray(rule))
+        metrics.push([metric, rule]);
+    }
+    const baselines = new Set(
+      metrics.map(([, r]) => r.maxRatioTo).filter((r) => r !== void 0)
+    );
+    const subjects = records.filter(
+      (r) => r.scenario === scenario && !baselines.has(rendererName(r))
+    );
+    for (const record of subjects) {
+      for (const [metric, rule] of metrics) {
+        checked++;
+        const breach = apply(record, metric, rule, records);
+        if (breach) breaches.push(breach);
+      }
+      for (const rule of rules.spans ?? []) {
+        checked++;
+        const breach = applySpan(record, rule);
+        if (breach) breaches.push(breach);
+      }
+    }
+  }
+  return { pass: breaches.length === 0, checked, breaches };
+}
+function metricOf(record, metric) {
+  const value = valueAt(record, metric);
+  return typeof value === "number" ? value : void 0;
+}
+function apply(record, metric, rule, records) {
+  const value = metricOf(record, metric);
+  const base = {
+    scenario: record.scenario,
+    metric,
+    renderer: record.renderer,
+    fixture: record.fixture,
+    value
+  };
+  const where = `${record.scenario} ${metric} (${record.renderer})`;
+  if (value === void 0) {
+    return { ...base, budget: describe(rule), message: `${where}: the record has no ${metric}` };
+  }
+  if (rule.max !== void 0 && value > rule.max) {
+    return {
+      ...base,
+      budget: `max ${rule.max}`,
+      message: `${where}: ${value} is over the max of ${rule.max}`
+    };
+  }
+  if (rule.min !== void 0 && value < rule.min) {
+    return {
+      ...base,
+      budget: `min ${rule.min}`,
+      message: `${where}: ${value} is under the min of ${rule.min}`
+    };
+  }
+  if (rule.maxRatioTo === void 0) return void 0;
+  const ratio = rule.ratio ?? 1;
+  const baseline = findBaseline(record, rule.maxRatioTo, records);
+  if (!baseline) {
+    return {
+      ...base,
+      budget: `max ${ratio} \xD7 ${rule.maxRatioTo}`,
+      message: `${where}: no ${rule.maxRatioTo} record of ${record.scenario} on ${record.fixture} to compare with`
+    };
+  }
+  const baseValue = metricOf(baseline, metric);
+  const limit = baseValue === void 0 ? void 0 : baseValue * ratio;
+  if (limit !== void 0 && value <= limit) return void 0;
+  const grew = spansThatGrew(record, baseline);
+  const breach = {
+    ...base,
+    budget: `max ${ratio} \xD7 ${baseline.renderer} (${baseValue ?? "none"})${limit === void 0 ? "" : ` = ${round(limit)}`}`,
+    baseline: { renderer: baseline.renderer, value: baseValue },
+    message: limit === void 0 ? `${where}: ${baseline.renderer}'s record has no ${metric}` : `${where}: ${value} is over ${ratio} \xD7 ${baseline.renderer}'s ${baseValue} (${round(limit)})${grew.length > 0 ? `; grew most: ${grew.map((g) => `${g.span} ${g.baselineP95} \u2192 ${g.p95} ms`).join(", ")}` : ""}`
+  };
+  if (grew.length > 0) breach.grew = grew;
+  return breach;
+}
+function spansOf(record) {
+  return record.breakdown ? [...record.breakdown.cpu, ...record.breakdown.gpu] : [];
+}
+function spansThatGrew(record, baseline, limit = 3) {
+  if (!record.breakdown || !baseline.breakdown) return [];
+  const before = new Map(spansOf(baseline).map((s) => [s.span, s.p95]));
+  return spansOf(record).map((s) => ({ span: s.span, p95: s.p95, baselineP95: before.get(s.span) ?? 0 })).filter((g) => g.p95 > g.baselineP95).sort((a, b) => b.p95 - b.baselineP95 - (a.p95 - a.baselineP95) || (a.span < b.span ? -1 : 1)).slice(0, limit);
+}
+function applySpan(record, rule) {
+  const stats = spansOf(record).find((s) => s.span === rule.span);
+  const where = `${record.scenario} span ${rule.span} (${record.renderer})`;
+  const base = {
+    scenario: record.scenario,
+    renderer: record.renderer,
+    fixture: record.fixture,
+    span: rule.span
+  };
+  if (!stats) {
+    const metric = `span:${rule.span}`;
+    return {
+      ...base,
+      metric,
+      value: void 0,
+      budget: describeSpan(rule),
+      message: record.breakdown ? `${where}: the record's breakdown has no ${rule.span}` : `${where}: the record has no breakdown (version 1)`
+    };
+  }
+  for (const key of ["p50", "p95", "max"]) {
+    const limit = rule[key];
+    if (limit === void 0 || stats[key] <= limit) continue;
+    return {
+      ...base,
+      metric: `span:${rule.span}.${key}`,
+      value: stats[key],
+      budget: `${key} ${limit}`,
+      message: `${where}: ${key} ${stats[key]} ms is over ${limit} ms`
+    };
+  }
+  return void 0;
+}
+function describeSpan(rule) {
+  const parts = [];
+  for (const key of ["p50", "p95", "max"]) {
+    if (rule[key] !== void 0) parts.push(`${key} ${rule[key]}`);
+  }
+  return parts.join(", ");
+}
+function findBaseline(record, renderer, records) {
+  const candidates = records.filter(
+    (r) => rendererName(r) === renderer && r.scenario === record.scenario && r.fixture === record.fixture
+  );
+  const sameDevice = candidates.find(
+    (r) => r.device.ua === record.device.ua && r.device.dpr === record.device.dpr && r.device.viewport[0] === record.device.viewport[0] && r.device.viewport[1] === record.device.viewport[1]
+  );
+  return sameDevice ?? candidates[0];
+}
+function describe(rule) {
+  const parts = [];
+  if (rule.max !== void 0) parts.push(`max ${rule.max}`);
+  if (rule.min !== void 0) parts.push(`min ${rule.min}`);
+  if (rule.maxRatioTo !== void 0) parts.push(`max ${rule.ratio ?? 1} \xD7 ${rule.maxRatioTo}`);
+  return parts.join(", ");
+}
+function round(value) {
+  return Math.round(value * 100) / 100;
+}
+export {
+  checkThresholds,
+  spansThatGrew
+};

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@aethervtt/shard-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./metrics": {
+      "types": "./dist/metrics/index.d.ts",
+      "default": "./dist/metrics/index.js"
+    },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "default": "./dist/page.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-gpu": "0.2.0",
+    "@aethervtt/shard-platform": "0.2.0",
+    "@aethervtt/shard-render": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-texture": "0.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/verify"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
+  }
+}