@patronage/factory-ci 1.0.0-alpha.7 → 1.0.0-alpha.9

package/src/vitest-profile-reader.test.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+
+import { readVitestProfileDocument } from "./vitest-profile-reader.ts";
+import type { VitestProfile } from "./vitest-profile.ts";
+
+const durations = {
+  maximum: 16_200,
+  mean: 15_800,
+  median: 15_700,
+  minimum: 15_300,
+};
+
+/** A document shaped exactly as `runVitestProfile` writes it. */
+const validProfile = (): VitestProfile => ({
+  command: ["vitest", "run", "--reporter=json", "--maxWorkers=2"],
+  endedAt: "2026-08-06T12:01:00.000Z",
+  environment: {
+    arch: "x64",
+    availableParallelism: 4,
+    cpuCount: 4,
+    cpuModel: "AMD EPYC 9R45",
+    gitDirty: false,
+    gitHead: "0123456789abcdef0123456789abcdef01234567",
+    node: "v24.0.0",
+    osRelease: "6.8.0",
+    platform: "linux",
+    totalMemoryBytes: 16_000_000_000,
+    vitest: "3.0.0",
+  },
+  options: { maxWorkers: 2, samples: 3, slowLimit: 20 },
+  rawReportDirectory: "/tmp/profile.raw/abc",
+  runs: [
+    {
+      counts: {
+        failed: 0,
+        passed: 900,
+        pending: 0,
+        suites: 80,
+        tests: 900,
+        todo: 0,
+      },
+      durationMs: 15_300,
+      endedAt: "2026-08-06T12:00:20.000Z",
+      exitCode: 0,
+      failure: null,
+      files: [{ durationMs: 900, path: "src/slow.test.ts", status: "passed" }],
+      reportAvailable: true,
+      sample: 1,
+      startedAt: "2026-08-06T12:00:00.000Z",
+      tests: [
+        {
+          durationMs: 450,
+          file: "src/slow.test.ts",
+          name: "slow case",
+          status: "passed",
+        },
+      ],
+    },
+  ],
+  schemaVersion: 1,
+  startedAt: "2026-08-06T12:00:00.000Z",
+  summary: {
+    durationMs: { ...durations },
+    slowFiles: [
+      { durationMs: { ...durations }, path: "src/slow.test.ts", samples: 3 },
+    ],
+    slowTests: [
+      {
+        durationMs: { ...durations },
+        file: "src/slow.test.ts",
+        name: "slow case",
+        samples: 3,
+      },
+    ],
+  },
+  tool: "factory-ci-vitest-profile",
+});
+
+describe("readVitestProfileDocument", () => {
+  it("accepts a document the writer emitted", () => {
+    const result = readVitestProfileDocument(validProfile());
+
+    expect(result.kind).toBe("profile");
+    if (result.kind === "profile") {
+      expect(result.profile.environment.cpuModel).toBe("AMD EPYC 9R45");
+      expect(result.profile.summary.durationMs.median).toBe(15_700);
+    }
+  });
+
+  it("names the tool mismatch instead of guessing", () => {
+    const result = readVitestProfileDocument({
+      ...validProfile(),
+      tool: "someone-elses-artifact",
+    });
+
+    expect(result).toEqual({
+      kind: "unrecognized",
+      reason:
+        'tool is "someone-elses-artifact" rather than "factory-ci-vitest-profile"',
+    });
+  });
+
+  it("refuses a future schema version rather than misreading it", () => {
+    const result = readVitestProfileDocument({
+      ...validProfile(),
+      schemaVersion: 2,
+    });
+
+    expect(result).toEqual({
+      kind: "unrecognized",
+      reason: "schemaVersion is 2 rather than 1",
+    });
+  });
+
+  it("refuses a document whose environment lost the cpuModel field", () => {
+    const document = validProfile() as unknown as {
+      environment: Record<string, unknown>;
+    };
+    delete document.environment.cpuModel;
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "environment.cpuModel is neither a string nor null",
+    });
+  });
+
+  it("refuses a run without a finite duration", () => {
+    const document = validProfile();
+    (document.runs[0] as unknown as Record<string, unknown>).durationMs =
+      "fast";
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "runs[0].durationMs is not a finite number",
+    });
+  });
+
+  it("refuses a summary without duration statistics", () => {
+    const document = validProfile() as unknown as {
+      summary: { durationMs: Record<string, unknown> };
+    };
+    delete document.summary.durationMs.median;
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.durationMs.median is not a finite number",
+    });
+  });
+
+  it("refuses empty counts rather than serving undefined fields", () => {
+    const document = validProfile();
+    (document.runs[0] as unknown as Record<string, unknown>).counts = {};
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "runs[0].counts.failed is not a finite number",
+    });
+  });
+
+  it("refuses a null slowFiles entry rather than crashing projection", () => {
+    const document = validProfile() as unknown as {
+      summary: { slowFiles: unknown[] };
+    };
+    document.summary.slowFiles = [null];
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.slowFiles[0] is not an object",
+    });
+  });
+
+  it("refuses a slow test whose duration summary is incomplete", () => {
+    const document = validProfile() as unknown as {
+      summary: { slowTests: { durationMs: Record<string, unknown> }[] };
+    };
+    const [slowTest] = document.summary.slowTests;
+    if (slowTest) {
+      delete slowTest.durationMs.median;
+    }
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.slowTests[0].durationMs.median is not a finite number",
+    });
+  });
+
+  it("refuses a slow file without a path string", () => {
+    const document = validProfile() as unknown as {
+      summary: { slowFiles: Record<string, unknown>[] };
+    };
+    const [slowFile] = document.summary.slowFiles;
+    if (slowFile) {
+      delete slowFile.path;
+    }
+
+    expect(readVitestProfileDocument(document)).toEqual({
+      kind: "unrecognized",
+      reason: "summary.slowFiles[0].path is not a string",
+    });
+  });
+
+  it("refuses non-object input", () => {
+    expect(readVitestProfileDocument(null)).toEqual({
+      kind: "unrecognized",
+      reason: "the document is not an object",
+    });
+  });
+});

package/src/vitest-profile-reader.ts

@@ -0,0 +1,220 @@
+/**
+ * Read back a Vitest profile artifact (#647).
+ *
+ * `vitest-profile.ts` owns the writer; this module owns the matching
+ * schema-checked reader, so a consumer analyzing profile artifacts collected
+ * from CI (for example `psf ci:analyze`) never re-types the document shape.
+ * The reader is deliberately strict about the fields an analysis is built on —
+ * tool discriminator, schema version, environment capture, per-run durations,
+ * and the duration summary — and deliberately silent about everything else, so
+ * additive writer changes never invalidate old artifacts.
+ *
+ * Pure: no I/O, no dependencies. The caller decides where the bytes come from.
+ */
+
+import type {
+  VitestProfile,
+  VitestProfileDurationSummary,
+} from "./vitest-profile.ts";
+import {
+  VITEST_PROFILE_SCHEMA_VERSION,
+  VITEST_PROFILE_TOOL,
+} from "./vitest-profile.ts";
+
+/**
+ * Outcome of reading one candidate document. `unrecognized` carries the first
+ * reason the document failed — an analyzer reports it verbatim rather than
+ * treating an unreadable profile as an empty one.
+ */
+export type VitestProfileReadResult =
+  | { kind: "profile"; profile: VitestProfile }
+  | { kind: "unrecognized"; reason: string };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+const durationSummaryFailure = (
+  value: unknown,
+  where: string
+): string | undefined => {
+  if (!isRecord(value)) {
+    return `${where} is not an object`;
+  }
+  const fields: (keyof VitestProfileDurationSummary)[] = [
+    "maximum",
+    "mean",
+    "median",
+    "minimum",
+  ];
+  const missing = fields.find((field) => !isFiniteNumber(value[field]));
+  return missing === undefined
+    ? undefined
+    : `${where}.${missing} is not a finite number`;
+};
+
+const environmentFailure = (value: unknown): string | undefined => {
+  if (!isRecord(value)) {
+    return "environment is not an object";
+  }
+  if (!(typeof value.cpuModel === "string" || value.cpuModel === null)) {
+    return "environment.cpuModel is neither a string nor null";
+  }
+  if (!isFiniteNumber(value.cpuCount)) {
+    return "environment.cpuCount is not a finite number";
+  }
+  return undefined;
+};
+
+/** The count fields the writer emits; every one must be a finite number. */
+const COUNT_FIELDS = [
+  "failed",
+  "passed",
+  "pending",
+  "suites",
+  "tests",
+  "todo",
+] as const;
+
+const runFailure = (value: unknown, index: number): string | undefined => {
+  if (!isRecord(value)) {
+    return `runs[${index}] is not an object`;
+  }
+  if (!isFiniteNumber(value.durationMs)) {
+    return `runs[${index}].durationMs is not a finite number`;
+  }
+  if (value.counts === null) {
+    return undefined;
+  }
+  if (!isRecord(value.counts)) {
+    return `runs[${index}].counts is neither an object nor null`;
+  }
+  const { counts } = value;
+  const missing = COUNT_FIELDS.find((field) => !isFiniteNumber(counts[field]));
+  return missing === undefined
+    ? undefined
+    : `runs[${index}].counts.${missing} is not a finite number`;
+};
+
+const slowEntryFailure = (
+  value: unknown,
+  where: string,
+  labelField: "name" | "path"
+): string | undefined => {
+  if (!isRecord(value)) {
+    return `${where} is not an object`;
+  }
+  if (typeof value[labelField] !== "string") {
+    return `${where}.${labelField} is not a string`;
+  }
+  if (labelField === "name" && typeof value.file !== "string") {
+    return `${where}.file is not a string`;
+  }
+  return durationSummaryFailure(value.durationMs, `${where}.durationMs`);
+};
+
+const summaryFailure = (value: unknown): string | undefined => {
+  if (!isRecord(value)) {
+    return "summary is not an object";
+  }
+  const durations = durationSummaryFailure(
+    value.durationMs,
+    "summary.durationMs"
+  );
+  if (durations !== undefined) {
+    return durations;
+  }
+  if (!Array.isArray(value.slowFiles)) {
+    return "summary.slowFiles is not an array";
+  }
+  for (const [index, entry] of value.slowFiles.entries()) {
+    const failure = slowEntryFailure(
+      entry,
+      `summary.slowFiles[${index}]`,
+      "path"
+    );
+    if (failure !== undefined) {
+      return failure;
+    }
+  }
+  if (!Array.isArray(value.slowTests)) {
+    return "summary.slowTests is not an array";
+  }
+  for (const [index, entry] of value.slowTests.entries()) {
+    const failure = slowEntryFailure(
+      entry,
+      `summary.slowTests[${index}]`,
+      "name"
+    );
+    if (failure !== undefined) {
+      return failure;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Check one parsed JSON document against the profile contract the writer
+ * emits. Returns the typed profile on success and the first mismatch reason
+ * otherwise — never a partially-usable value.
+ */
+export const readVitestProfileDocument = (
+  value: unknown
+): VitestProfileReadResult => {
+  if (!isRecord(value)) {
+    return { kind: "unrecognized", reason: "the document is not an object" };
+  }
+  if (value.tool !== VITEST_PROFILE_TOOL) {
+    return {
+      kind: "unrecognized",
+      reason: `tool is ${JSON.stringify(value.tool)} rather than "${VITEST_PROFILE_TOOL}"`,
+    };
+  }
+  if (value.schemaVersion !== VITEST_PROFILE_SCHEMA_VERSION) {
+    return {
+      kind: "unrecognized",
+      reason: `schemaVersion is ${JSON.stringify(value.schemaVersion)} rather than ${VITEST_PROFILE_SCHEMA_VERSION}`,
+    };
+  }
+  if (
+    !(
+      Array.isArray(value.command) &&
+      value.command.every((part) => typeof part === "string")
+    )
+  ) {
+    return {
+      kind: "unrecognized",
+      reason: "command is not an array of strings",
+    };
+  }
+  const environment = environmentFailure(value.environment);
+  if (environment !== undefined) {
+    return { kind: "unrecognized", reason: environment };
+  }
+  if (!isRecord(value.options)) {
+    return { kind: "unrecognized", reason: "options is not an object" };
+  }
+  if (!isFiniteNumber(value.options.maxWorkers)) {
+    return {
+      kind: "unrecognized",
+      reason: "options.maxWorkers is not a finite number",
+    };
+  }
+  if (!Array.isArray(value.runs)) {
+    return { kind: "unrecognized", reason: "runs is not an array" };
+  }
+  for (const [index, run] of value.runs.entries()) {
+    const failure = runFailure(run, index);
+    if (failure !== undefined) {
+      return { kind: "unrecognized", reason: failure };
+    }
+  }
+  const summary = summaryFailure(value.summary);
+  if (summary !== undefined) {
+    return { kind: "unrecognized", reason: summary };
+  }
+
+  return { kind: "profile", profile: value as unknown as VitestProfile };
+};