@aplaytest/core 0.1.0

package/dist/evidence/store.js

@@ -0,0 +1,148 @@
+/**
+ * The evidence store: plain JSON on disk, one directory per run.
+ *
+ *   <dir>/<runId>/<evidenceId>.json
+ *
+ * Deliberately not a binary format and not a database. A human with `jq` must
+ * be able to read a bundle, and a CI job must be able to upload the directory
+ * as an artifact with no export step. Every bundle carries `schemaVersion` so
+ * a reader can refuse politely rather than mis-parse.
+ */
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { redact } from './redact.js';
+import { EVIDENCE_SCHEMA_VERSION } from './types.js';
+const JSON_EXTENSION = '.json';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function isEvidenceBundle(value) {
+    if (!isRecord(value))
+        return false;
+    if (value['schemaVersion'] !== EVIDENCE_SCHEMA_VERSION)
+        return false;
+    if (typeof value['id'] !== 'string')
+        return false;
+    if (!isRecord(value['test']) || typeof value['test']['title'] !== 'string')
+        return false;
+    if (!isRecord(value['failure']) || typeof value['failure']['kind'] !== 'string')
+        return false;
+    return true;
+}
+export function parseEvidenceBundle(value) {
+    return isEvidenceBundle(value) ? value : null;
+}
+function schemaVersionOf(value) {
+    return isRecord(value) ? value['schemaVersion'] : undefined;
+}
+async function latestRunDirectory(evidenceDir) {
+    const entries = await readdir(evidenceDir, { withFileTypes: true }).catch(() => []);
+    const dirs = entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort();
+    return dirs[dirs.length - 1] ?? null;
+}
+export async function loadRunBundles(evidenceDir, runId) {
+    const resolvedRunId = runId ?? (await latestRunDirectory(evidenceDir));
+    if (resolvedRunId === null)
+        return { runId: null, bundles: [], skipped: [] };
+    const dir = join(evidenceDir, resolvedRunId);
+    const files = (await readdir(dir).catch(() => [])).filter(file => file.endsWith(JSON_EXTENSION));
+    const bundles = [];
+    const skipped = [];
+    for (const file of files) {
+        const raw = await readFile(join(dir, file), 'utf8').catch(() => null);
+        if (raw === null) {
+            skipped.push({ file, reason: 'unreadable' });
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            skipped.push({ file, reason: 'unreadable' });
+            continue;
+        }
+        const bundle = parseEvidenceBundle(parsed);
+        if (bundle === null) {
+            const version = schemaVersionOf(parsed);
+            skipped.push({
+                file,
+                reason: typeof version === 'number'
+                    ? `schemaVersion ${version}, this build reads ${EVIDENCE_SCHEMA_VERSION}`
+                    : 'malformed',
+            });
+            continue;
+        }
+        bundles.push(bundle);
+    }
+    return { runId: resolvedRunId, bundles, skipped };
+}
+export class SchemaVersionError extends Error {
+    found;
+    expected;
+    path;
+    constructor(found, expected, path) {
+        super(`Evidence bundle at ${path} is schemaVersion ${found}, this build reads ${expected}. ` +
+            `Re-run the suite to regenerate, or use a matching atest version.`);
+        this.found = found;
+        this.expected = expected;
+        this.path = path;
+        this.name = 'SchemaVersionError';
+    }
+}
+export class EvidenceStore {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    bundlePath(runId, id) {
+        return join(this.options.dir, runId, `${id}.json`);
+    }
+    /**
+     * Redaction happens HERE, on the write path, so there is exactly one place
+     * that can forget to do it.
+     */
+    async write(bundle) {
+        const safe = redact(bundle, this.options.redactKeys);
+        const path = this.bundlePath(bundle.runId, bundle.id);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(safe, null, 2)}\n`, 'utf8');
+        return path;
+    }
+    async read(runId, id) {
+        const path = this.bundlePath(runId, id);
+        const raw = await readFile(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        const bundle = parseEvidenceBundle(parsed);
+        if (bundle === null) {
+            throw new SchemaVersionError(Number(schemaVersionOf(parsed)), EVIDENCE_SCHEMA_VERSION, path);
+        }
+        return bundle;
+    }
+    /** Run ids, newest first by directory mtime. */
+    async listRuns() {
+        const entries = await readdir(this.options.dir, { withFileTypes: true }).catch(() => []);
+        const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+        const withTime = await Promise.all(dirs.map(async (name) => ({
+            name,
+            mtime: await stat(join(this.options.dir, name))
+                .then(s => s.mtimeMs)
+                .catch(() => 0),
+        })));
+        return withTime.sort((a, b) => b.mtime - a.mtime).map(e => e.name);
+    }
+    async listBundles(runId) {
+        const entries = await readdir(join(this.options.dir, runId)).catch(() => []);
+        return entries
+            .filter(file => file.endsWith(JSON_EXTENSION))
+            .map(file => file.slice(0, -JSON_EXTENSION.length));
+    }
+    /** Drop the oldest runs beyond the retention limit. Returns what it removed. */
+    async prune() {
+        const runs = await this.listRuns();
+        const doomed = runs.slice(this.options.retainRuns);
+        await Promise.all(doomed.map(r => rm(join(this.options.dir, r), { recursive: true, force: true })));
+        return doomed;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/evidence/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/evidence/store.ts"],"names":[],"mappings":"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"}

package/dist/evidence/types.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The Evidence Bundle — the central data structure of the system.
+ *
+ * Everything downstream (healing, flaky classification, MCP resources, report
+ * insights) consumes this and only this. Engines never re-open a browser to
+ * "go look"; if a field is missing, the fix is to capture it at source, not to
+ * re-run the test.
+ *
+ * DESIGN NOTE — nullable, not optional. Fields that may be absent are typed
+ * `T | null` rather than `field?: T`. Bundles are written to disk as JSON and
+ * read back by other processes (and by humans with `jq`); `undefined`
+ * disappears on serialisation, `null` round-trips. Every bundle therefore has
+ * the same key set regardless of what was captured.
+ */
+import type { FailureKind } from '../taxonomy/kinds.js';
+import type { LocatorStrategy } from '../locator/stability.js';
+/** sha256(runId, testId, project, retry) — stable and reproducible. */
+export type EvidenceId = string & {
+    readonly __brand: 'EvidenceId';
+};
+export declare const EVIDENCE_SCHEMA_VERSION: 1;
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** One page-object call, captured by the bindPage wrapper. */
+export interface StepRecord {
+    /** e.g. "gymsPage" */
+    readonly pageObject: string;
+    /** e.g. "expectCardData" */
+    readonly method: string;
+    /** Domain arguments, JSON-safe and redacted. */
+    readonly args: readonly unknown[];
+    readonly startedAt: string;
+    readonly durationMs: number;
+    readonly failed: boolean;
+}
+export declare function formatFailingStep(step: StepRecord | null): string | null;
+/** Where a selector literal lives in source — the target of a heal patch. */
+export interface SelectorSource {
+    readonly file: string;
+    readonly line: number;
+    /** e.g. "TEST_IDS.cardName" */
+    readonly constantPath: string;
+    /** Other constants in the same file holding the identical literal. */
+    readonly aliases: readonly string[];
+}
+export interface LocatorCandidate {
+    readonly strategy: LocatorStrategy;
+    /** e.g. "getByRole('option', { name: 'Cork' })" */
+    readonly expression: string;
+    /** Must be exactly 1 to be eligible — ambiguity is disqualifying. */
+    readonly matchCount: number;
+    readonly visible: boolean;
+    readonly enabled: boolean;
+    readonly accessibleName: string | null;
+    readonly boundingBox: Rect | null;
+    /** 0 = means the same thing, 1 = unrelated. Tier-0 heuristic. */
+    readonly semanticDistance: number;
+    /** 0 = testid … 6 = xpath. See locator/stability. */
+    readonly stabilityRank: number;
+}
+export interface RequestRecord {
+    readonly url: string;
+    readonly method: string;
+    readonly status: number | null;
+    readonly durationMs: number;
+    readonly failureText: string | null;
+    /** Set when the body was parsed against a wire schema and failed. */
+    readonly schemaError: string | null;
+}
+export interface AppSpanRecord {
+    readonly spanId: string;
+    readonly name: string;
+    readonly durationMs: number;
+    readonly status: 'ok' | 'error' | 'unset';
+}
+export interface EvidenceBundle {
+    readonly schemaVersion: typeof EVIDENCE_SCHEMA_VERSION;
+    readonly id: EvidenceId;
+    readonly runId: string;
+    /** Joins to OpenTelemetry / Tempo. Derived, not random. */
+    readonly traceId: string;
+    readonly capturedAt: string;
+    readonly test: {
+        /** Playwright's stable test id — survives a title rename. */
+        readonly id: string;
+        readonly title: string;
+        readonly titlePath: readonly string[];
+        readonly file: string;
+        readonly line: number;
+        readonly project: string;
+        readonly tags: readonly string[];
+        readonly retry: number;
+        readonly workerIndex: number;
+        readonly shard: {
+            readonly current: number;
+            readonly total: number;
+        } | null;
+    };
+    readonly failure: {
+        readonly kind: FailureKind;
+        readonly message: string;
+        readonly stack: string;
+        /** e.g. "toBeVisible" | "toHaveText" */
+        readonly matcher: string | null;
+        readonly expected: string | null;
+        readonly actual: string | null;
+        readonly timedOut: boolean;
+    };
+    /** What the test was trying to do, in domain terms. */
+    readonly intent: {
+        readonly steps: readonly StepRecord[];
+        readonly failingStep: StepRecord | null;
+        readonly selector: string | null;
+        readonly selectorSource: SelectorSource | null;
+    };
+    /** Primary model-facing page representation. ARIA first: cheap and semantic. */
+    readonly page: {
+        readonly url: string;
+        readonly title: string;
+        readonly ariaSnapshot: string;
+        readonly candidates: readonly LocatorCandidate[];
+        /** Structural skeleton only, sent when ARIA is insufficient. */
+        readonly htmlDigest: string | null;
+        /** Every data-testid present. The cheapest answer to "was it renamed?" */
+        readonly testIdsPresent: readonly string[];
+    };
+    readonly visual: {
+        readonly screenshotPath: string | null;
+        readonly diffPath: string | null;
+        readonly diffPixelRatio: number | null;
+    };
+    readonly network: {
+        readonly failed: readonly RequestRecord[];
+        readonly slow: readonly RequestRecord[];
+        readonly statusCounts: Readonly<Record<string, number>>;
+    };
+    readonly console: {
+        readonly errors: readonly string[];
+        readonly warnings: readonly string[];
+    };
+    readonly timing: {
+        readonly testMs: number;
+        readonly failingActionMs: number | null;
+        readonly navigationMs: number | null;
+        /** testMs / configured timeout. Near 1.0 implies a timing failure. */
+        readonly budgetUsedRatio: number;
+    };
+    readonly env: {
+        readonly appEnv: string;
+        readonly baseUrl: string;
+        readonly browser: string;
+        readonly platform: string;
+        readonly workers: number;
+        readonly commit: string;
+        readonly changedPaths: readonly string[];
+    };
+    /** Populated when an OTel backend is reachable; joined on traceId. */
+    readonly appSpans: readonly AppSpanRecord[] | null;
+    readonly artifacts: {
+        readonly tracePath: string | null;
+        readonly videoPath: string | null;
+    };
+}
+/**
+ * The subset of a bundle the classifier needs. Keeping this narrow means
+ * classification can be unit-tested against small fixtures instead of
+ * requiring a full bundle, and makes the classifier reusable at capture time
+ * before the rest of the bundle is assembled.
+ */
+export interface ClassifiableFailure {
+    readonly message: string;
+    readonly stack: string;
+    readonly matcher: string | null;
+    readonly timedOut: boolean;
+    readonly consoleErrors: readonly string[];
+    readonly failedRequests: readonly RequestRecord[];
+    readonly budgetUsedRatio: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/evidence/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/evidence/types.ts"],"names":[],"mappings":"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"}

package/dist/evidence/types.js

@@ -0,0 +1,21 @@
+/**
+ * The Evidence Bundle — the central data structure of the system.
+ *
+ * Everything downstream (healing, flaky classification, MCP resources, report
+ * insights) consumes this and only this. Engines never re-open a browser to
+ * "go look"; if a field is missing, the fix is to capture it at source, not to
+ * re-run the test.
+ *
+ * DESIGN NOTE — nullable, not optional. Fields that may be absent are typed
+ * `T | null` rather than `field?: T`. Bundles are written to disk as JSON and
+ * read back by other processes (and by humans with `jq`); `undefined`
+ * disappears on serialisation, `null` round-trips. Every bundle therefore has
+ * the same key set regardless of what was captured.
+ */
+export const EVIDENCE_SCHEMA_VERSION = 1;
+export function formatFailingStep(step) {
+    if (step === null)
+        return null;
+    return `${step.pageObject}.${step.method}(${step.args.join(', ')})`;
+}
+//# sourceMappingURL=types.js.map

package/dist/evidence/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/evidence/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAU,CAAC;AAsBlD,MAAM,UAAU,iBAAiB,CAAC,IAAuB;IACvD,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,GAAG,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AACtE,CAAC"}

package/dist/history/ingest-playwright.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Ingest a Playwright JSON report into the history store.
+ *
+ * The I/O half of the adapter: read, parse, hand to `mapPlaywrightReport`,
+ * store. All of the mapping decisions — identity, timestamps, classification —
+ * live in `playwright-report.ts` and are unit-tested without a database.
+ *
+ * Like `ingestDirectory`, this NEVER throws. A bad report is reported through
+ * `IngestResult.skipped` so that one unreadable artifact among many cannot cost
+ * the others, and so a CI analyze job degrades to "nothing ingested" rather
+ * than to a red build.
+ */
+import { type RunIdentity } from './playwright-report.js';
+import type { HistoryStore } from './store.js';
+import type { IngestResult } from './ingest.js';
+export interface IngestPlaywrightJsonOptions {
+    /**
+     * Run-level facts the report may not carry. Defaults read the GitHub Actions
+     * environment, matching the reporter's own convention so both paths label a
+     * run the same way. The report still wins wherever it has an answer.
+     */
+    readonly identity?: Partial<RunIdentity>;
+    readonly now?: () => number;
+}
+export declare function ingestPlaywrightJson(store: HistoryStore, path: string, options?: IngestPlaywrightJsonOptions): Promise<IngestResult>;
+//# sourceMappingURL=ingest-playwright.d.ts.map

package/dist/history/ingest-playwright.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-playwright.d.ts","sourceRoot":"","sources":["../../src/history/ingest-playwright.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAwC,KAAK,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AA0BD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,YAAY,CAAC,CAyCvB"}

package/dist/history/ingest-playwright.js

@@ -0,0 +1,73 @@
+/**
+ * Ingest a Playwright JSON report into the history store.
+ *
+ * The I/O half of the adapter: read, parse, hand to `mapPlaywrightReport`,
+ * store. All of the mapping decisions — identity, timestamps, classification —
+ * live in `playwright-report.ts` and are unit-tested without a database.
+ *
+ * Like `ingestDirectory`, this NEVER throws. A bad report is reported through
+ * `IngestResult.skipped` so that one unreadable artifact among many cannot cost
+ * the others, and so a CI analyze job degrades to "nothing ingested" rather
+ * than to a red build.
+ */
+import { readFile } from 'node:fs/promises';
+import { mapPlaywrightReport } from './playwright-report.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * The same environment variables the reporter reads. Kept identical on purpose:
+ * a run ingested through the JSON path and one written by the reporter should
+ * be labelled by the same rules, or comparing them later means comparing the
+ * conventions of two different code paths.
+ */
+function identityFromEnv(overrides) {
+    const env = process.env;
+    return {
+        commit: overrides?.commit ?? env['GITHUB_SHA'] ?? null,
+        branch: overrides?.branch ?? env['GITHUB_REF_NAME'] ?? null,
+        appEnv: overrides?.appEnv ?? env['APP_ENV'] ?? null,
+        ci: overrides?.ci ?? (env['CI'] === 'true' || env['CI'] === '1'),
+    };
+}
+function failed(path, reason) {
+    return { filesRead: 1, runsIngested: 0, attemptsIngested: 0, skipped: [{ file: path, reason }] };
+}
+export async function ingestPlaywrightJson(store, path, options = {}) {
+    const raw = await readFile(path, 'utf8').catch(() => null);
+    if (raw === null) {
+        return { filesRead: 0, runsIngested: 0, attemptsIngested: 0, skipped: [{ file: path, reason: 'unreadable' }] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return failed(path, 'not valid JSON');
+    }
+    if (!isRecord(parsed))
+        return failed(path, 'not a Playwright JSON report');
+    const { run, collapsed } = mapPlaywrightReport(parsed, {
+        identity: identityFromEnv(options.identity),
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    try {
+        await store.ingest(run);
+    }
+    catch (error) {
+        return failed(path, `could not be stored: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return {
+        filesRead: 1,
+        runsIngested: 1,
+        attemptsIngested: run.attempts.length,
+        // Surfaced through the channel the CLI already prints as warnings. A
+        // collapsed duplicate is a real loss of an attempt and has to be visible;
+        // it is not a reason to reject the other hundred-odd rows.
+        skipped: collapsed.map(what => ({
+            file: path,
+            reason: `duplicate attempt collapsed: ${what}`,
+        })),
+    };
+}
+//# sourceMappingURL=ingest-playwright.js.map

package/dist/history/ingest-playwright.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest-playwright.js","sourceRoot":"","sources":["../../src/history/ingest-playwright.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,OAAO,EAAE,mBAAmB,EAAqC,MAAM,wBAAwB,CAAC;AAchG,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,SAA2C;IAClE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IACxB,OAAO;QACL,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,IAAI;QACtD,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,CAAC,iBAAiB,CAAC,IAAI,IAAI;QAC3D,MAAM,EAAE,SAAS,EAAE,MAAM,IAAI,GAAG,CAAC,SAAS,CAAC,IAAI,IAAI;QACnD,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,IAAY,EAAE,MAAc;IAC1C,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AACnG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAmB,EACnB,IAAY,EACZ,UAAuC,EAAE;IAEzC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAC3D,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;IACjH,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;IAE3E,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,mBAAmB,CAAC,MAAoB,EAAE;QACnE,QAAQ,EAAE,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC3C,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KAC3D,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,MAAM,CACX,IAAI,EACJ,wBAAwB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACjF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,CAAC;QACf,gBAAgB,EAAE,GAAG,CAAC,QAAQ,CAAC,MAAM;QACrC,qEAAqE;QACrE,0EAA0E;QAC1E,2DAA2D;QAC3D,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,EAAE,IAAI;YACV,MAAM,EAAE,gCAAgC,IAAI,EAAE;SAC/C,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/history/ingest.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Ingest run records written by the reporter into the history store.
+ *
+ * The reporter writes plain JSON; this is the seam where those files become
+ * queryable history. Keeping it separate means a CI job can download shard
+ * artifacts from anywhere and ingest them in one pass, and a developer can
+ * replay months of archived runs to seed history without waiting for it to
+ * accumulate.
+ */
+import type { HistoryStore } from './store.js';
+export interface IngestResult {
+    readonly filesRead: number;
+    readonly runsIngested: number;
+    readonly attemptsIngested: number;
+    /** Files that could not be ingested, with the reason. Never thrown. */
+    readonly skipped: readonly {
+        readonly file: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * Ingest every `*.json` in a directory.
+ *
+ * A malformed or version-mismatched file is SKIPPED and reported, never
+ * thrown: one bad artifact among fifty shards must not cost you the other
+ * forty-nine, and a partial history is far more useful than none.
+ */
+export declare function ingestDirectory(store: HistoryStore, dir: string): Promise<IngestResult>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/history/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/history/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjF;AAuBD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,YAAY,CAAC,CA4CvB"}

package/dist/history/ingest.js

@@ -0,0 +1,86 @@
+/**
+ * Ingest run records written by the reporter into the history store.
+ *
+ * The reporter writes plain JSON; this is the seam where those files become
+ * queryable history. Keeping it separate means a CI job can download shard
+ * artifacts from anywhere and ingest them in one pass, and a developer can
+ * replay months of archived runs to seed history without waiting for it to
+ * accumulate.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RUN_SCHEMA_VERSION } from './types.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isRunRecord(value) {
+    if (!isRecord(value))
+        return false;
+    if (value['schemaVersion'] !== RUN_SCHEMA_VERSION)
+        return false;
+    if (typeof value['runId'] !== 'string' || value['runId'] === '')
+        return false;
+    return Array.isArray(value['attempts']);
+}
+function validate(parsed) {
+    if (!isRecord(parsed))
+        return 'not an object';
+    if (parsed['schemaVersion'] !== RUN_SCHEMA_VERSION) {
+        return `schemaVersion ${String(parsed['schemaVersion'])} — this build reads ${RUN_SCHEMA_VERSION}`;
+    }
+    if (typeof parsed['runId'] !== 'string' || parsed['runId'] === '')
+        return 'missing runId';
+    if (!Array.isArray(parsed['attempts']))
+        return 'missing attempts';
+    return isRunRecord(parsed) ? parsed : 'not an object';
+}
+/**
+ * Ingest every `*.json` in a directory.
+ *
+ * A malformed or version-mismatched file is SKIPPED and reported, never
+ * thrown: one bad artifact among fifty shards must not cost you the other
+ * forty-nine, and a partial history is far more useful than none.
+ */
+export async function ingestDirectory(store, dir) {
+    const entries = await readdir(dir).catch(() => []);
+    const files = entries.filter(name => name.endsWith('.json'));
+    const skipped = [];
+    let runsIngested = 0;
+    let attemptsIngested = 0;
+    for (const name of files) {
+        const path = join(dir, name);
+        let parsed;
+        try {
+            parsed = JSON.parse(await readFile(path, 'utf8'));
+        }
+        catch (error) {
+            skipped.push({ file: name, reason: error instanceof Error ? error.message : 'unreadable' });
+            continue;
+        }
+        const validated = validate(parsed);
+        if (typeof validated === 'string') {
+            skipped.push({ file: name, reason: validated });
+            continue;
+        }
+        // The doc comment above promises a bad file is skipped, never thrown —
+        // but only the JSON parse and the shape check were guarded. A record that
+        // passes both and then fails at the database (an unbindable value, a
+        // constraint) threw straight out of here and rolled back the transaction,
+        // costing every other file in the batch. In CI that reads as history
+        // simply never accumulating.
+        try {
+            await store.ingest(validated);
+        }
+        catch (error) {
+            skipped.push({
+                file: name,
+                reason: `could not be stored: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            continue;
+        }
+        runsIngested += 1;
+        attemptsIngested += validated.attempts.length;
+    }
+    return { filesRead: files.length, runsIngested, attemptsIngested, skipped };
+}
+//# sourceMappingURL=ingest.js.map

package/dist/history/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../src/history/ingest.ts"],"names":[],"mappings":"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"}