@patronage/factory-ci 0.2.1 → 1.0.0-alpha.13

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 };
+};