@forgeax/engine-profiler 0.1.2

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

@@ -0,0 +1,113 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const packageRoot = fileURLToPath(new URL('../../', import.meta.url));
+const cliPath = fileURLToPath(new URL('../../dist/cli.mjs', import.meta.url));
+const smokePath = fileURLToPath(new URL('../../scripts/consume-smoke.mjs', import.meta.url));
+const fixtureRoot = new URL('./fixtures/cli/', import.meta.url);
+
+function runCli(args: readonly string[], input = '') {
+  return spawnSync(process.execPath, [cliPath, ...args], {
+    cwd: packageRoot,
+    input,
+    encoding: 'utf8',
+  });
+}
+
+function readFixture(name: string): string {
+  return readFileSync(fileURLToPath(new URL(name, fixtureRoot)), 'utf8');
+}
+
+function runSummaryForFixture(name: string) {
+  const fixturePath = fileURLToPath(new URL(name, fixtureRoot));
+  return runCli(['summary', '--file', fixturePath]);
+}
+
+function parseObject(output: string): Record<string, unknown> {
+  return JSON.parse(output) as Record<string, unknown>;
+}
+
+describe('profiler CLI consumer smoke', () => {
+  it('preserves completeness states through the built public CLI', () => {
+    const complete = runSummaryForFixture('valid-capture.json');
+    const partial = runSummaryForFixture('partial-capture.json');
+    const overflow = runSummaryForFixture('../profile-capture/valid-overflow.json');
+    const empty = runCli(
+      ['summary'],
+      JSON.stringify({
+        schemaVersion: '1.0',
+        captureId: 'capture-0044',
+        timeUnit: 'microseconds',
+        frameLimit: 1,
+        eventLimit: 1,
+        phaseCatalog: { app: ['input'], render: ['submit'] },
+        records: [],
+        completeness: {
+          status: 'partial',
+          retainedEventCount: 0,
+          droppedEventCount: 0,
+          incompleteReason: 'stopped-before-frame',
+        },
+      }),
+    );
+
+    expect(complete.status).toBe(0);
+    expect(parseObject(complete.stdout).completeness).toMatchObject({ status: 'complete' });
+    expect(partial.status).toBe(0);
+    expect(parseObject(partial.stdout).completeness).toMatchObject({
+      status: 'partial',
+      incompleteReason: 'stopped-during-frame',
+    });
+    expect(overflow.status).toBe(0);
+    expect(parseObject(overflow.stdout).completeness).toMatchObject({
+      status: 'overflow',
+      droppedEventCount: 7,
+    });
+    expect(empty.status).toBe(0);
+    expect(parseObject(empty.stdout)).toMatchObject({
+      captureId: 'capture-0044',
+      frameCount: 0,
+      frameRange: null,
+      completeness: { status: 'partial' },
+    });
+  });
+
+  it('keeps incompatible artifacts on stderr and repeats deterministically', () => {
+    const input = readFixture('valid-capture.json');
+    const first = runCli(['summary'], input);
+    const second = runCli(['summary'], input);
+    const invalid = runSummaryForFixture('invalid-version.json');
+
+    expect(first.status).toBe(0);
+    expect(second.status).toBe(0);
+    expect(first.stdout).toBe(second.stdout);
+    expect(first.stderr).toBe('');
+    expect(invalid.status).not.toBe(0);
+    expect(invalid.stdout).toBe('');
+    expect(parseObject(invalid.stderr)).toEqual({
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: expect.any(Object),
+      },
+    });
+  });
+
+  it('runs the package consumer smoke through the public CLI entry', () => {
+    const result = spawnSync(process.execPath, [smokePath], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(parseObject(result.stdout)).toMatchObject({
+      query: 'summary',
+      captureId: 'capture-0010',
+      completeness: { status: 'overflow' },
+    });
+  });
+});

package/src/__tests__/cli-contract.test.ts

@@ -0,0 +1,115 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { runProfilerCli } from '../cli.js';
+
+type CliResponse = Record<string, unknown>;
+
+function readFixture(name: string): string {
+  return readFileSync(new URL(`./fixtures/profile-capture/${name}`, import.meta.url), 'utf8');
+}
+
+function readCliFixture(name: string): string {
+  return readFileSync(new URL(`./fixtures/cli/${name}`, import.meta.url), 'utf8');
+}
+
+function parseOutput(output: string): CliResponse {
+  return JSON.parse(output) as CliResponse;
+}
+
+function expectJsonObject(output: string): CliResponse {
+  const parsed = parseOutput(output);
+  expect(parsed).toEqual(expect.any(Object));
+  return parsed;
+}
+
+describe('profiler CLI structured output contract', () => {
+  it('prints one machine-readable summary object by default', () => {
+    const result = runProfilerCli([], readFixture('valid-complete.json'));
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output).toMatchObject({
+      query: 'summary',
+      schemaVersion: '1.0',
+      captureId: 'capture-0001',
+      frameRange: { first: 1, last: 2 },
+      completeness: { status: 'complete' },
+    });
+    expect(output.phases).toEqual(expect.any(Array));
+  });
+
+  it('returns a frame projection selected by frameId', () => {
+    const result = runProfilerCli(['frame', '--frame-id', '2'], readFixture('valid-overflow.json'));
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output).toMatchObject({
+      query: 'frame',
+      captureId: 'capture-0002',
+      frameId: 2,
+      completeness: {
+        status: 'overflow',
+        droppedEventCount: 7,
+        firstAffectedFrameId: 2,
+        lastAffectedFrameId: 4,
+      },
+      frame: null,
+    });
+  });
+
+  it('returns a phase projection selected by source and phase', () => {
+    const result = runProfilerCli(
+      ['phase', '--source', 'render', '--phase', 'submit'],
+      readFixture('valid-complete.json'),
+    );
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output).toMatchObject({
+      query: 'phase',
+      captureId: 'capture-0001',
+      source: 'render',
+      phase: 'submit',
+      phaseSummary: {
+        source: 'render',
+        phase: 'submit',
+        skipCount: 1,
+      },
+    });
+  });
+
+  it('accepts file input and preserves an empty capture status', () => {
+    const result = runProfilerCli(
+      [
+        'summary',
+        '--file',
+        new URL('./fixtures/profile-capture/valid-complete.json', import.meta.url).pathname,
+      ],
+      '',
+    );
+    const output = expectJsonObject(result.stdout);
+
+    expect(result.exitCode).toBe(0);
+    expect(result.stderr).toBe('');
+    expect(output.completeness).toMatchObject({ status: 'complete' });
+  });
+
+  it('writes one structured error object for an incompatible artifact', () => {
+    const result = runProfilerCli(['summary'], readCliFixture('invalid-version.json'));
+    const error = expectJsonObject(result.stderr);
+
+    expect(result.exitCode).not.toBe(0);
+    expect(result.stdout).toBe('');
+    expect(error).toMatchObject({
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: expect.any(Object),
+      },
+    });
+  });
+});

package/src/__tests__/cli-input-errors.test.ts

@@ -0,0 +1,210 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { readCliInput, runProfilerCli } from '../cli.js';
+
+function expectStructuredError(
+  result: { stdout: string; stderr: string; exitCode: number },
+  code: string,
+): void {
+  expect(result.exitCode).not.toBe(0);
+  expect(result.stdout).toBe('');
+  const parsed = JSON.parse(result.stderr) as {
+    error?: { code?: string; expected?: string; hint?: string; detail?: unknown };
+  };
+  expect(parsed).toEqual({
+    error: {
+      code,
+      expected: expect.any(String),
+      hint: expect.any(String),
+      detail: expect.anything(),
+    },
+  });
+}
+
+function expectStructuredErrorWithSide(
+  result: { stdout: string; stderr: string; exitCode: number },
+  code: string,
+  side: 'left' | 'right',
+): void {
+  expect(result.exitCode).not.toBe(0);
+  expect(result.stdout).toBe('');
+  expect(JSON.parse(result.stderr)).toEqual({
+    error: {
+      code,
+      expected: expect.any(String),
+      hint: expect.any(String),
+      detail: {
+        side,
+        ...(code === 'cli-input-file-read-failed' ? { path: expect.any(String) } : {}),
+        message: expect.any(String),
+      },
+    },
+  });
+}
+
+describe('profiler CLI input error contract', () => {
+  it('does not read stdin when a file input is selected', () => {
+    expect(
+      readCliInput(['summary', '--file', 'capture.json'], () => {
+        throw new Error('stdin read');
+      }),
+    ).toBe('');
+  });
+
+  it('reads stdin when no file input is selected', () => {
+    expect(readCliInput(['summary'], () => 'capture')).toBe('capture');
+  });
+
+  it('returns a structured reader failure and retries the same reader deterministically', () => {
+    const input = readFileSync(
+      new URL('./fixtures/cli/valid-capture.json', import.meta.url),
+      'utf8',
+    );
+    let refuse = true;
+    const readStdin = (): string => {
+      if (refuse) {
+        refuse = false;
+        throw new Error('EISDIR: illegal operation on a directory, read');
+      }
+      return input;
+    };
+
+    const first = runProfilerCli(['summary'], readCliInput(['summary'], readStdin));
+    expectStructuredError(first, 'cli-input-stdin-read-failed');
+    expect(JSON.parse(first.stderr)).toEqual({
+      error: {
+        code: 'cli-input-stdin-read-failed',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: {
+          message: 'EISDIR: illegal operation on a directory, read',
+        },
+      },
+    });
+
+    const second = runProfilerCli(['summary'], readCliInput(['summary'], readStdin));
+    const repeat = runProfilerCli(['summary'], readCliInput(['summary'], readStdin));
+    expect(second.exitCode).toBe(0);
+    expect(second.stderr).toBe('');
+    expect(second.stdout).toBe(repeat.stdout);
+    expect(JSON.parse(second.stdout)).toMatchObject({
+      query: 'summary',
+      captureId: 'capture-0042',
+    });
+  });
+
+  it('rejects empty stdin without producing a summary', () => {
+    expectStructuredError(runProfilerCli(['summary'], ''), 'cli-input-empty');
+  });
+
+  it('rejects malformed JSON from stdin', () => {
+    expectStructuredError(
+      runProfilerCli(['summary'], '{"schemaVersion":'),
+      'cli-input-invalid-json',
+    );
+  });
+
+  it('rejects a missing file before model analysis', () => {
+    expectStructuredError(
+      runProfilerCli(['summary', '--file', '/tmp/forgeax-profiler-missing-capture.json'], ''),
+      'cli-input-file-read-failed',
+    );
+  });
+
+  it('rejects schema-invalid JSON as a structured artifact error', () => {
+    expectStructuredError(
+      runProfilerCli(['summary'], '{"schemaVersion":"1.0"}'),
+      'profile-artifact-invalid',
+    );
+  });
+
+  it('rejects unsupported artifact versions without guessing fields', () => {
+    expectStructuredError(
+      runProfilerCli(
+        ['summary'],
+        JSON.stringify({
+          schemaVersion: '9.0',
+          captureId: 'capture-0001',
+          timeUnit: 'microseconds',
+          frameLimit: 1,
+          eventLimit: 1,
+          phaseCatalog: { app: [], render: [] },
+          records: [],
+          completeness: { status: 'partial', retainedEventCount: 0, droppedEventCount: 0 },
+        }),
+      ),
+      'profile-artifact-incompatible',
+    );
+  });
+
+  it('rejects non-positive and unsafe frame identifiers', () => {
+    const input = JSON.stringify({
+      schemaVersion: '1.0',
+      captureId: 'capture-0001',
+      timeUnit: 'microseconds',
+      frameLimit: 1,
+      eventLimit: 1,
+      phaseCatalog: { app: ['input'], render: [] },
+      records: [],
+      completeness: { status: 'partial', retainedEventCount: 0, droppedEventCount: 0 },
+    });
+
+    expectStructuredError(runProfilerCli(['frame', '--frame-id', '0'], input), 'cli-query-invalid');
+    expectStructuredError(
+      runProfilerCli(['frame', '--frame-id', '9007199254740992'], input),
+      'cli-query-invalid',
+    );
+  });
+
+  it('rejects unknown flags and missing phase selectors', () => {
+    const input = JSON.stringify({
+      schemaVersion: '1.0',
+      captureId: 'capture-0001',
+      timeUnit: 'microseconds',
+      frameLimit: 1,
+      eventLimit: 1,
+      phaseCatalog: { app: ['input'], render: [] },
+      records: [],
+      completeness: { status: 'partial', retainedEventCount: 0, droppedEventCount: 0 },
+    });
+
+    expectStructuredError(runProfilerCli(['summary', '--unknown'], input), 'cli-arguments-invalid');
+    expectStructuredError(
+      runProfilerCli(['phase', '--source', 'app'], input),
+      'cli-arguments-invalid',
+    );
+  });
+
+  it('requires two file inputs for compare and does not consume stdin', () => {
+    expect(
+      readCliInput(['compare', '--left-file', 'left.json', '--right-file', 'right.json'], () => {
+        throw new Error('stdin read');
+      }),
+    ).toBe('');
+    expectStructuredError(
+      runProfilerCli(['compare', '--left-file', 'left.json'], ''),
+      'cli-arguments-invalid',
+    );
+    expectStructuredError(
+      runProfilerCli(['summary', '--left-file', 'left.json', '--right-file', 'right.json'], '{}'),
+      'cli-arguments-invalid',
+    );
+  });
+
+  it('attributes unreadable compare files independently', () => {
+    const validPath = fileURLToPath(new URL('./fixtures/cli/valid-capture.json', import.meta.url));
+    const missingLeftPath = '/tmp/forgeax-profiler-missing-left-capture.json';
+    const missingRightPath = '/tmp/forgeax-profiler-missing-right-capture.json';
+    expectStructuredErrorWithSide(
+      runProfilerCli(['compare', '--left-file', missingLeftPath, '--right-file', validPath], ''),
+      'cli-input-file-read-failed',
+      'left',
+    );
+    expectStructuredErrorWithSide(
+      runProfilerCli(['compare', '--left-file', validPath, '--right-file', missingRightPath], ''),
+      'cli-input-file-read-failed',
+      'right',
+    );
+  });
+});

package/src/__tests__/cli-process.integration.test.ts

@@ -0,0 +1,154 @@
+import { spawnSync } from 'node:child_process';
+import { closeSync, openSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const cliPath = fileURLToPath(new URL('../../dist/cli.mjs', import.meta.url));
+const fixturePath = fileURLToPath(new URL('./fixtures/cli/valid-capture.json', import.meta.url));
+const partialFixturePath = fileURLToPath(
+  new URL('./fixtures/cli/partial-capture.json', import.meta.url),
+);
+const invalidFixturePath = fileURLToPath(
+  new URL('./fixtures/cli/invalid-version.json', import.meta.url),
+);
+
+function readFixture(): string {
+  return readFileSync(fixturePath, 'utf8');
+}
+
+function runCli(args: readonly string[], input: string) {
+  return spawnSync(process.execPath, [cliPath, ...args], {
+    input,
+    encoding: 'utf8',
+  });
+}
+
+function runCliWithDirectoryStdin(args: readonly string[]) {
+  const stdin = openSync(fileURLToPath(new URL('./', import.meta.url)), 'r');
+  try {
+    return spawnSync(process.execPath, [cliPath, ...args], {
+      stdio: [stdin, 'pipe', 'pipe'],
+      encoding: 'utf8',
+    });
+  } finally {
+    closeSync(stdin);
+  }
+}
+
+function parseObject(output: string): Record<string, unknown> {
+  return JSON.parse(output) as Record<string, unknown>;
+}
+
+describe('profiler CLI public process contract', () => {
+  it('prints deterministic summary, frame, and phase JSON through the built entry', () => {
+    const input = readFixture();
+    const summary = runCli(['summary'], input);
+    const summaryRepeat = runCli(['summary'], input);
+    const frame = runCli(['frame', '--frame-id', '2'], input);
+    const phase = runCli(['phase', '--source', 'render', '--phase', 'submit'], input);
+
+    expect(summary.status).toBe(0);
+    expect(summary.stderr).toBe('');
+    expect(parseObject(summary.stdout)).toEqual(parseObject(summaryRepeat.stdout));
+    expect(parseObject(summary.stdout)).toMatchObject({
+      query: 'summary',
+      captureId: 'capture-0042',
+      completeness: { status: 'complete' },
+    });
+    expect(frame.status).toBe(0);
+    expect(parseObject(frame.stdout)).toMatchObject({ query: 'frame', frameId: 2 });
+    expect(phase.status).toBe(0);
+    expect(parseObject(phase.stdout)).toMatchObject({
+      query: 'phase',
+      source: 'render',
+      phase: 'submit',
+    });
+  });
+
+  it('accepts file input and keeps invalid input on stderr as one error object', () => {
+    const fromFile = runCli(['summary', '--file', fixturePath], '');
+    const invalid = runCli(['summary'], '{"schemaVersion":');
+
+    expect(fromFile.status).toBe(0);
+    expect(fromFile.stderr).toBe('');
+    expect(parseObject(fromFile.stdout)).toMatchObject({ captureId: 'capture-0042' });
+    expect(invalid.status).not.toBe(0);
+    expect(invalid.stdout).toBe('');
+    expect(parseObject(invalid.stderr)).toEqual({
+      error: {
+        code: 'cli-input-invalid-json',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: expect.any(Object),
+      },
+    });
+  });
+
+  it('returns one structured stdin reader error through the built entry', () => {
+    const refusal = runCliWithDirectoryStdin(['summary']);
+
+    expect(refusal.status).toBe(2);
+    expect(refusal.stdout).toBe('');
+    expect(parseObject(refusal.stderr)).toEqual({
+      error: {
+        code: 'cli-input-stdin-read-failed',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: { message: expect.stringContaining('EISDIR') },
+      },
+    });
+  });
+
+  it('compares two file artifacts deterministically through the built entry', () => {
+    const args = ['compare', '--left-file', fixturePath, '--right-file', partialFixturePath];
+    const first = runCli(args, 'stdin must not be read');
+    const second = runCli(args, 'different stdin must not be read');
+    const output = parseObject(first.stdout);
+
+    expect(first.status).toBe(0);
+    expect(first.stderr).toBe('');
+    expect(first.stdout).toBe(second.stdout);
+    expect(output).toMatchObject({
+      query: 'compare',
+      left: {
+        summary: { captureId: 'capture-0042' },
+        completeness: { status: 'complete' },
+      },
+      right: {
+        summary: { captureId: 'capture-0043' },
+        completeness: { status: 'partial' },
+      },
+      phases: expect.any(Array),
+    });
+  });
+
+  it('attributes an invalid compare artifact to its input side', () => {
+    const leftInvalid = runCli(
+      ['compare', '--left-file', invalidFixturePath, '--right-file', fixturePath],
+      '',
+    );
+    const rightInvalid = runCli(
+      ['compare', '--left-file', fixturePath, '--right-file', invalidFixturePath],
+      '',
+    );
+
+    expect(leftInvalid.status).not.toBe(0);
+    expect(parseObject(leftInvalid.stderr)).toEqual({
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: { path: '/schemaVersion', message: expect.any(String), side: 'left' },
+      },
+    });
+    expect(rightInvalid.status).not.toBe(0);
+    expect(parseObject(rightInvalid.stderr)).toEqual({
+      error: {
+        code: 'profile-artifact-incompatible',
+        expected: expect.any(String),
+        hint: expect.any(String),
+        detail: { path: '/schemaVersion', message: expect.any(String), side: 'right' },
+      },
+    });
+  });
+});