@forgeax/engine-profiler 0.1.2

package/src/__tests__/compare.test.ts

@@ -0,0 +1,223 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { compareProfileCaptures } from '../compare.js';
+
+function readFixture(name: string): unknown {
+  return JSON.parse(
+    readFileSync(new URL(`./fixtures/cli/${name}`, import.meta.url), 'utf8'),
+  ) as unknown;
+}
+
+function capture(variant: 'left' | 'right'): Record<string, unknown> {
+  const right = variant === 'right';
+  return {
+    schemaVersion: '1.0',
+    captureId: right ? 'capture-0002' : 'capture-0001',
+    timeUnit: 'microseconds',
+    frameLimit: 4,
+    eventLimit: 16,
+    phaseCatalog: {
+      app: ['input', 'update'],
+      render: right ? ['submit', 'gpu'] : ['submit'],
+    },
+    records: right
+      ? [
+          {
+            kind: 'phase',
+            source: 'app',
+            frameId: 1,
+            phase: 'input',
+            startMicros: 1,
+            endMicros: 16,
+            durationMicros: 15,
+          },
+          {
+            kind: 'phase',
+            source: 'app',
+            frameId: 1,
+            phase: 'update',
+            parentSource: 'app',
+            parentPhase: 'input',
+            startMicros: 16,
+            endMicros: 41,
+            durationMicros: 25,
+          },
+          {
+            kind: 'phase',
+            source: 'render',
+            frameId: 1,
+            phase: 'submit',
+            startMicros: 41,
+            endMicros: 46,
+            durationMicros: 5,
+          },
+          {
+            kind: 'phase',
+            source: 'render',
+            frameId: 2,
+            phase: 'gpu',
+            startMicros: 50,
+            endMicros: 90,
+            durationMicros: 40,
+          },
+        ]
+      : [
+          {
+            kind: 'phase',
+            source: 'app',
+            frameId: 1,
+            phase: 'input',
+            startMicros: 1,
+            endMicros: 11,
+            durationMicros: 10,
+          },
+          {
+            kind: 'phase',
+            source: 'app',
+            frameId: 1,
+            phase: 'update',
+            parentSource: 'app',
+            parentPhase: 'input',
+            startMicros: 11,
+            endMicros: 31,
+            durationMicros: 20,
+          },
+          { kind: 'skip', source: 'render', frameId: 1, phase: 'submit', reason: 'not recorded' },
+        ],
+    completeness: right
+      ? {
+          status: 'overflow',
+          retainedEventCount: 4,
+          droppedEventCount: 2,
+          firstAffectedFrameId: 2,
+          lastAffectedFrameId: 2,
+        }
+      : { status: 'complete', retainedEventCount: 3, droppedEventCount: 0 },
+  };
+}
+
+describe('ProfileCapture comparison', () => {
+  it('preserves both summaries and compares a union of full phase identities', () => {
+    const result = compareProfileCaptures(capture('left'), capture('right'));
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(result.error.code);
+    expect(result.value.left).toMatchObject({
+      summary: {
+        captureId: 'capture-0001',
+        frameCount: 1,
+        recordCount: 3,
+        phaseCount: 2,
+        skipCount: 1,
+      },
+      completeness: { status: 'complete', retainedEventCount: 3, droppedEventCount: 0 },
+    });
+    expect(result.value.right).toMatchObject({
+      summary: { captureId: 'capture-0002' },
+      completeness: {
+        status: 'overflow',
+        retainedEventCount: 4,
+        droppedEventCount: 2,
+        firstAffectedFrameId: 2,
+        lastAffectedFrameId: 2,
+      },
+    });
+
+    const update = result.value.phases.find((phase) => phase.identity.phase === 'update');
+    expect(update).toEqual({
+      identity: { source: 'app', phase: 'update', parentSource: 'app', parentPhase: 'input' },
+      left: { count: 1, skipCount: 0, p95DurationMicros: 20 },
+      right: { count: 1, skipCount: 0, p95DurationMicros: 25 },
+      delta: { count: 0, skipCount: 0, p95DurationMicros: 5 },
+    });
+
+    const submit = result.value.phases.find(
+      (phase) => phase.identity.source === 'render' && phase.identity.phase === 'submit',
+    );
+    expect(submit).toEqual({
+      identity: { source: 'render', phase: 'submit' },
+      left: { count: 0, skipCount: 1, p95DurationMicros: null },
+      right: { count: 1, skipCount: 0, p95DurationMicros: 5 },
+      delta: { count: 1, skipCount: -1 },
+    });
+
+    const gpu = result.value.phases.find((phase) => phase.identity.phase === 'gpu');
+    expect(gpu).toEqual({
+      identity: { source: 'render', phase: 'gpu' },
+      right: { count: 1, skipCount: 0, p95DurationMicros: 40 },
+    });
+  });
+
+  it('keeps invalid input attributable to its side', () => {
+    const left = compareProfileCaptures({ schemaVersion: '9.0' }, capture('right'));
+    expect(left).toEqual({
+      ok: false,
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: {
+          path: '/schemaVersion',
+          message: expect.any(String),
+          side: 'left',
+        },
+      },
+    });
+
+    const right = compareProfileCaptures(capture('left'), { schemaVersion: '9.0' });
+    expect(right).toMatchObject({ ok: false, error: { detail: { side: 'right' } } });
+  });
+
+  it('does not mutate either artifact and produces stable ordering', () => {
+    const left = capture('left');
+    const right = capture('right');
+    const beforeLeft = JSON.stringify(left);
+    const beforeRight = JSON.stringify(right);
+    const first = compareProfileCaptures(left, right);
+    const second = compareProfileCaptures(left, right);
+
+    expect(first).toEqual(second);
+    expect(JSON.stringify(left)).toBe(beforeLeft);
+    expect(JSON.stringify(right)).toBe(beforeRight);
+  });
+
+  it('keeps an unavailable p95 unavailable instead of manufacturing a delta', () => {
+    const result = compareProfileCaptures(
+      readFixture('valid-capture.json'),
+      readFixture('partial-capture.json'),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(result.error.code);
+    const input = result.value.phases.find(
+      (phase) => phase.identity.source === 'app' && phase.identity.phase === 'input',
+    );
+    expect(input?.left?.p95DurationMicros).toBe(10);
+    expect(input?.right?.p95DurationMicros).toBe(15);
+    expect(input?.delta?.p95DurationMicros).toBe(5);
+    const update = result.value.phases.find(
+      (phase) => phase.identity.source === 'app' && phase.identity.phase === 'update',
+    );
+    expect(update?.left?.p95DurationMicros).toBe(30);
+    expect(update?.right).toBeUndefined();
+    expect(update?.delta).toBeUndefined();
+  });
+
+  it('does not merge equal phase names that have different parent identities', () => {
+    const right = capture('right');
+    const rootUpdate = (right.records as Array<Record<string, unknown>>).map((record) => {
+      if (record.phase !== 'update') return record;
+      const { parentSource: _parentSource, parentPhase: _parentPhase, ...withoutParent } = record;
+      return withoutParent;
+    });
+    const result = compareProfileCaptures(capture('left'), { ...right, records: rootUpdate });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(result.error.code);
+    const updates = result.value.phases.filter((phase) => phase.identity.phase === 'update');
+    expect(updates).toHaveLength(2);
+    expect(updates.map((phase) => phase.identity.parentPhase)).toEqual(['input', undefined]);
+    expect(updates[0]?.delta).toBeUndefined();
+    expect(updates[1]?.delta).toBeUndefined();
+  });
+});

package/src/__tests__/comparison-side-owner.test-d.ts

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ProfileComparisonError } from '../index.js';
+
+type ComparisonErrorSide = ProfileComparisonError['detail']['side'];
+type ExpectedComparisonErrorSide = 'left' | 'right';
+
+const compareSource = readFileSync(new URL('../compare.ts', import.meta.url), 'utf8');
+
+describe('profile comparison side owner', () => {
+  it('keeps the public side vocabulary bilaterally exact', () => {
+    expectTypeOf<ComparisonErrorSide>().toEqualTypeOf<ExpectedComparisonErrorSide>();
+    expectTypeOf<ExpectedComparisonErrorSide>().toEqualTypeOf<ComparisonErrorSide>();
+
+    const acceptsSide = (side: ComparisonErrorSide): void => void side;
+    acceptsSide('left');
+    acceptsSide('right');
+    // @ts-expect-error Unknown sides remain outside the public comparison vocabulary.
+    acceptsSide('comparison-side-not-real');
+  });
+
+  it('derives withSide from the public error detail owner', () => {
+    expect(compareSource).toContain("side: ProfileComparisonError['detail']['side'],");
+    expect(compareSource).not.toContain("side: 'left' | 'right'");
+    expect(compareSource).toContain("withSide('left', leftModel.error)");
+    expect(compareSource).toContain("withSide('right', rightModel.error)");
+  });
+});

package/src/__tests__/consumer-smoke.integration.test.ts

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { buildProfileModel } from '@forgeax/engine-profiler';
+import { describe, expect, it } from 'vitest';
+
+// @perf-budget-skip: intentional public-entry subprocess smoke gate.
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+const scriptPath = fileURLToPath(new URL('../../scripts/consume-smoke.mjs', import.meta.url));
+const fixturePath = fileURLToPath(
+  new URL('./fixtures/profile-capture/model-input.json', import.meta.url),
+);
+
+describe('consumer smoke', () => {
+  it('consumes a fixture through the public package entry', () => {
+    const result = spawnSync(process.execPath, [scriptPath], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(result.stdout.trim().split('\n')).toHaveLength(1);
+
+    const output = JSON.parse(result.stdout) as Record<string, unknown>;
+    const fixture = JSON.parse(readFileSync(fixturePath, 'utf8')) as unknown;
+    const model = buildProfileModel(fixture);
+    expect(model.ok).toBe(true);
+    if (!model.ok) throw new Error(model.error.code);
+    expect(output).toEqual({
+      query: 'summary',
+      ...model.value.summary,
+      phases: model.value.phases,
+    });
+  });
+});

package/src/__tests__/fixtures/cli/invalid-version.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "2.0",
+  "captureId": "capture-0001",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [],
+  "completeness": {
+    "status": "partial",
+    "retainedEventCount": 0,
+    "droppedEventCount": 0,
+    "incompleteReason": "unsupported-version"
+  }
+}

package/src/__tests__/fixtures/cli/partial-capture.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0043",
+  "timeUnit": "microseconds",
+  "frameLimit": 4,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1015,
+      "durationMicros": 15
+    }
+  ],
+  "completeness": {
+    "status": "partial",
+    "retainedEventCount": 1,
+    "droppedEventCount": 0,
+    "incompleteReason": "stopped-during-frame"
+  }
+}

package/src/__tests__/fixtures/cli/valid-capture.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0042",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1010,
+      "durationMicros": 10
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 2,
+      "phase": "update",
+      "startMicros": 2000,
+      "endMicros": 2030,
+      "durationMicros": 30
+    },
+    {
+      "kind": "skip",
+      "source": "render",
+      "frameId": 2,
+      "phase": "submit",
+      "reason": "no-render"
+    }
+  ],
+  "completeness": {
+    "status": "complete",
+    "retainedEventCount": 3,
+    "droppedEventCount": 0
+  }
+}

package/src/__tests__/fixtures/profile-capture/invalid-boundary.json

@@ -0,0 +1,144 @@
+{
+  "cases": [
+    {
+      "name": "unsupported schema version",
+      "capture": { "schemaVersion": "2.0" }
+    },
+    {
+      "name": "zero frame limit",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0003",
+        "timeUnit": "microseconds",
+        "frameLimit": 0,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 0,
+          "droppedEventCount": 0,
+          "incompleteReason": "stopped-before-frame"
+        }
+      }
+    },
+    {
+      "name": "fractional event limit",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0004",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1.5,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 0,
+          "droppedEventCount": 0,
+          "incompleteReason": "stopped-before-frame"
+        }
+      }
+    },
+    {
+      "name": "negative duration",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0005",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": ["input"], "render": [] },
+        "records": [
+          {
+            "kind": "phase",
+            "source": "app",
+            "frameId": 1,
+            "phase": "input",
+            "startMicros": 20,
+            "endMicros": 10,
+            "durationMicros": -10
+          }
+        ],
+        "completeness": { "status": "complete", "retainedEventCount": 1, "droppedEventCount": 0 }
+      }
+    },
+    {
+      "name": "unknown phase",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0006",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": ["input"], "render": [] },
+        "records": [
+          {
+            "kind": "skip",
+            "source": "app",
+            "frameId": 1,
+            "phase": "unknown",
+            "reason": "not-declared"
+          }
+        ],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 1,
+          "droppedEventCount": 0,
+          "incompleteReason": "phase-not-declared"
+        }
+      }
+    },
+    {
+      "name": "complete with incomplete reason",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0007",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": {
+          "status": "complete",
+          "retainedEventCount": 0,
+          "droppedEventCount": 0,
+          "incompleteReason": "source-failed"
+        }
+      }
+    },
+    {
+      "name": "frame id is not positive safe integer",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0008",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": ["input"], "render": [] },
+        "records": [
+          { "kind": "skip", "source": "app", "frameId": -1, "phase": "input", "reason": "not-run" }
+        ],
+        "completeness": {
+          "status": "partial",
+          "retainedEventCount": 1,
+          "droppedEventCount": 0,
+          "incompleteReason": "source-failed"
+        }
+      }
+    },
+    {
+      "name": "overflow without affected frame range",
+      "capture": {
+        "schemaVersion": "1.0",
+        "captureId": "capture-0009",
+        "timeUnit": "microseconds",
+        "frameLimit": 1,
+        "eventLimit": 1,
+        "phaseCatalog": { "app": [], "render": [] },
+        "records": [],
+        "completeness": { "status": "overflow", "retainedEventCount": 0, "droppedEventCount": 1 }
+      }
+    }
+  ]
+}

package/src/__tests__/fixtures/profile-capture/model-input.json

@@ -0,0 +1,54 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0010",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1030,
+      "durationMicros": 30
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "update",
+      "startMicros": 1100,
+      "endMicros": 1120,
+      "durationMicros": 20
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 2,
+      "phase": "input",
+      "startMicros": 2000,
+      "endMicros": 2010,
+      "durationMicros": 10
+    },
+    {
+      "kind": "skip",
+      "source": "render",
+      "frameId": 2,
+      "phase": "submit",
+      "reason": "no-render"
+    }
+  ],
+  "completeness": {
+    "status": "overflow",
+    "retainedEventCount": 4,
+    "droppedEventCount": 2,
+    "firstAffectedFrameId": 2,
+    "lastAffectedFrameId": 2
+  }
+}

package/src/__tests__/fixtures/profile-capture/sink-failure.json

@@ -0,0 +1,30 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0004",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 4,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1100,
+      "durationMicros": 100
+    }
+  ],
+  "completeness": {
+    "status": "partial",
+    "retainedEventCount": 1,
+    "droppedEventCount": 0,
+    "incompleteReason": "profile-sink-failed",
+    "firstAffectedFrameId": 1,
+    "lastAffectedFrameId": 1
+  }
+}

package/src/__tests__/fixtures/profile-capture/valid-complete.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": "1.0",
+  "captureId": "capture-0001",
+  "timeUnit": "microseconds",
+  "frameLimit": 2,
+  "eventLimit": 8,
+  "phaseCatalog": {
+    "app": ["input", "update"],
+    "render": ["prepare", "submit"]
+  },
+  "records": [
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 1,
+      "phase": "input",
+      "startMicros": 1000,
+      "endMicros": 1100,
+      "durationMicros": 100
+    },
+    {
+      "kind": "skip",
+      "source": "render",
+      "frameId": 1,
+      "phase": "submit",
+      "reason": "no-render"
+    },
+    {
+      "kind": "phase",
+      "source": "app",
+      "frameId": 2,
+      "phase": "update",
+      "startMicros": 2000,
+      "endMicros": 2200,
+      "durationMicros": 200
+    }
+  ],
+  "completeness": {
+    "status": "complete",
+    "retainedEventCount": 3,
+    "droppedEventCount": 0
+  }
+}