vouchington-tooling 0.0.13 → 0.0.14

package/dist/transient-retry/types.d.mts

@@ -0,0 +1,39 @@
+/** Provider-neutral context supplied to a transient-retry rule. */
+export interface RetryContext {
+    /** The provider's current run attempt, starting at one. */
+    runAttempt: number;
+    /** A normalized attempt count shared by rules when provider attempts are sparse. */
+    retryAttempt?: number;
+    /** A normalized next-occurrence count for individual rules. */
+    retryAttempts?: ReadonlyMap<string, number>;
+    /** Targets that the provider resolved for this run. */
+    targetNames?: ReadonlySet<string>;
+}
+export type RetryDecision = 'rerun' | 'ignore' | 'fresh-plan' | 'reap-lock';
+export type RetryTarget = {
+    targetName: string;
+    targetFamily?: never;
+    resolveTargetName?: never;
+} | {
+    targetName?: never;
+    /** Static prefix shared by every dynamically named target in the family. */
+    targetFamily: string;
+    /** Resolves the exact target for this run, or null when it cannot be determined. */
+    resolveTargetName: (context: RetryContext) => string | null;
+};
+interface RetryRuleBase {
+    /** Stable identifier for logs and telemetry. */
+    id: string;
+    /** Maximum normalized attempts at which this rule may match. */
+    maxAttempts: number;
+    match: (context: RetryContext) => boolean | Promise<boolean>;
+}
+export type RetryRule = (RetryRuleBase & {
+    decision?: 'rerun';
+    /** Reruns must name a resolved target; full-provider reruns stay private. */
+    retryTarget: RetryTarget;
+}) | (RetryRuleBase & {
+    decision: Exclude<RetryDecision, 'rerun'>;
+    retryTarget?: never;
+});
+export {};

package/dist/transient-retry/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/vitest-blob-manifest/constants.d.mts

@@ -0,0 +1 @@
+export declare const VITEST_SUITE_PATTERN: RegExp;

package/dist/vitest-blob-manifest/constants.mjs

@@ -0,0 +1 @@
+export const VITEST_SUITE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

package/dist/vitest-blob-manifest/index.d.mts

@@ -1,6 +1,7 @@
+export * from './report-attempt.mts';
+export { VITEST_SUITE_PATTERN } from './constants.mts';
 export declare const VITEST_BLOB_MANIFEST_FILENAME = "vitest-blob-manifest.json";
 export declare const VITEST_BLOB_MANIFEST_VERSION = "vitest-blob-manifest:v1";
-export declare const VITEST_SUITE_PATTERN: RegExp;
 export interface VitestBlobManifest {
     readonly version: typeof VITEST_BLOB_MANIFEST_VERSION;
     readonly suite: string;

package/dist/vitest-blob-manifest/index.mjs

@@ -1,9 +1,11 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { lstatSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, join } from 'node:path';
+import { VITEST_SUITE_PATTERN } from './constants.mjs';
+export * from './report-attempt.mjs';
+export { VITEST_SUITE_PATTERN } from './constants.mjs';
 export const VITEST_BLOB_MANIFEST_FILENAME = 'vitest-blob-manifest.json';
 export const VITEST_BLOB_MANIFEST_VERSION = 'vitest-blob-manifest:v1';
-export const VITEST_SUITE_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/vitest-blob-manifest/report-attempt.d.mts

@@ -0,0 +1,24 @@
+export declare const VITEST_REPORT_ATTEMPT_VERSION = "vitest-report-attempt:v1";
+export declare const VITEST_REPORT_ATTEMPT_PREFIX = "vitest-report-attempt-";
+export interface VitestReportAttemptIdentity {
+    readonly repository: string;
+    readonly revision: string;
+    readonly runId: string;
+    readonly attempt: number;
+}
+export interface VitestReportAttempt {
+    readonly version: typeof VITEST_REPORT_ATTEMPT_VERSION;
+    readonly suite: string;
+    readonly repository: string;
+    readonly revision: string;
+    readonly run: {
+        readonly id: string;
+        readonly attempt: number;
+    };
+}
+export declare function parseVitestReportAttempt(raw: unknown): VitestReportAttempt;
+export declare function createVitestReportAttempt(suite: string, identity: VitestReportAttemptIdentity): VitestReportAttempt;
+export declare function serializeVitestReportAttempt(marker: VitestReportAttempt): Buffer;
+export declare function writeVitestReportAttempt(directory: string, suite: string, identity: VitestReportAttemptIdentity): string;
+/** Reads only exact flattened or per-suite marker artifacts, rejecting all other layouts. */
+export declare function readVitestReportAttempts(root: string, identity: VitestReportAttemptIdentity): Readonly<Record<string, number>>;

package/dist/vitest-blob-manifest/report-attempt.mjs

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, join } from 'node:path';
+import { VITEST_SUITE_PATTERN } from './constants.mjs';
+export const VITEST_REPORT_ATTEMPT_VERSION = 'vitest-report-attempt:v1';
+export const VITEST_REPORT_ATTEMPT_PREFIX = 'vitest-report-attempt-';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasExactKeys(value, keys) {
+    return Object.keys(value).toSorted().join('\0') === keys.toSorted().join('\0');
+}
+function isPositiveInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) > 0;
+}
+function assertIdentity(identity) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(identity.repository) ||
+        !/^[0-9a-f]{40}$/.test(identity.revision) ||
+        !/^[1-9][0-9]*$/.test(identity.runId) ||
+        !isPositiveInteger(identity.attempt)) {
+        throw new Error('Vitest report attempt identity has an invalid schema');
+    }
+}
+export function parseVitestReportAttempt(raw) {
+    if (!isRecord(raw) ||
+        !hasExactKeys(raw, ['version', 'suite', 'repository', 'revision', 'run']) ||
+        raw.version !== VITEST_REPORT_ATTEMPT_VERSION ||
+        typeof raw.suite !== 'string' ||
+        !VITEST_SUITE_PATTERN.test(raw.suite) ||
+        typeof raw.repository !== 'string' ||
+        !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(raw.repository) ||
+        typeof raw.revision !== 'string' ||
+        !/^[0-9a-f]{40}$/.test(raw.revision) ||
+        !isRecord(raw.run) ||
+        !hasExactKeys(raw.run, ['id', 'attempt']) ||
+        typeof raw.run.id !== 'string' ||
+        !/^[1-9][0-9]*$/.test(raw.run.id) ||
+        !isPositiveInteger(raw.run.attempt)) {
+        throw new Error('Vitest report attempt marker has an invalid schema');
+    }
+    return raw;
+}
+export function createVitestReportAttempt(suite, identity) {
+    assertIdentity(identity);
+    return parseVitestReportAttempt({
+        version: VITEST_REPORT_ATTEMPT_VERSION,
+        suite,
+        repository: identity.repository,
+        revision: identity.revision,
+        run: { id: identity.runId, attempt: identity.attempt },
+    });
+}
+export function serializeVitestReportAttempt(marker) {
+    return Buffer.from(`${JSON.stringify(parseVitestReportAttempt(marker), null, 2)}\n`);
+}
+function assertDirectory(path, label) {
+    if (!lstatSync(path).isDirectory())
+        throw new Error(`${label} must be a directory`);
+}
+function writeAtomically(path, bytes) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch {
+            // A successful rename consumes the temporary name.
+        }
+    }
+}
+export function writeVitestReportAttempt(directory, suite, identity) {
+    const marker = createVitestReportAttempt(suite, identity);
+    mkdirSync(directory, { recursive: true });
+    assertDirectory(directory, 'Vitest report attempt directory');
+    const path = join(directory, `${suite}.json`);
+    writeAtomically(path, serializeVitestReportAttempt(marker));
+    return path;
+}
+function readAttempt(path, suite, identity) {
+    const marker = parseVitestReportAttempt(JSON.parse(readFileSync(path, 'utf8')));
+    if (marker.suite !== suite ||
+        marker.repository !== identity.repository ||
+        marker.revision !== identity.revision ||
+        marker.run.id !== identity.runId ||
+        marker.run.attempt > identity.attempt) {
+        throw new Error(`Vitest report attempt identity does not match this run for ${suite}`);
+    }
+    return marker.run.attempt;
+}
+/** Reads only exact flattened or per-suite marker artifacts, rejecting all other layouts. */
+export function readVitestReportAttempts(root, identity) {
+    assertIdentity(identity);
+    if (!existsSync(root))
+        return {};
+    assertDirectory(root, 'Vitest report attempt root');
+    const attempts = {};
+    const rootEntries = readdirSync(root, { withFileTypes: true });
+    const flattened = rootEntries.length === 1 && rootEntries[0].isFile();
+    for (const artifact of rootEntries) {
+        if (flattened) {
+            const suite = artifact.name.endsWith('.json') ? artifact.name.slice(0, -'.json'.length) : '';
+            if (!VITEST_SUITE_PATTERN.test(suite)) {
+                throw new Error('Vitest report attempt root has an unexpected entry');
+            }
+            attempts[suite] = readAttempt(join(root, artifact.name), suite, identity);
+            continue;
+        }
+        if (!artifact.isDirectory() || !artifact.name.startsWith(VITEST_REPORT_ATTEMPT_PREFIX)) {
+            throw new Error('Vitest report attempt root has an unexpected entry');
+        }
+        const suite = artifact.name.slice(VITEST_REPORT_ATTEMPT_PREFIX.length);
+        if (!VITEST_SUITE_PATTERN.test(suite))
+            throw new Error('Invalid Vitest suite attempt artifact');
+        const directory = join(root, artifact.name);
+        assertDirectory(directory, `Vitest report attempt artifact ${basename(directory)}`);
+        const entries = readdirSync(directory, { withFileTypes: true });
+        if (entries.length !== 1 || entries[0].name !== `${suite}.json` || !entries[0].isFile()) {
+            throw new Error(`Vitest report attempt artifact ${basename(directory)} is invalid`);
+        }
+        attempts[suite] = readAttempt(join(directory, entries[0].name), suite, identity);
+    }
+    return Object.fromEntries(Object.entries(attempts).toSorted(([left], [right]) => left.localeCompare(right)));
+}

package/dist/vitest-blob-manifest/reports.d.mts

@@ -0,0 +1,28 @@
+export interface PrepareVitestReportsOptions {
+    readonly primaryDir: string;
+    readonly fallbackDir: string;
+    readonly outputDir: string;
+    readonly expectedSuites: readonly VitestReportExpectation[];
+    readonly repository: string;
+    readonly revision: string;
+    readonly run: {
+        readonly id: string;
+        readonly currentAttempt: number;
+    };
+}
+export type VitestReportExpectation = {
+    readonly suite: string;
+    readonly minimumAttempt: number;
+};
+export interface SelectedVitestReport {
+    readonly suite: string;
+    readonly attempt: number;
+    readonly sources: readonly ('primary' | 'fallback')[];
+}
+/**
+ * Validates untrusted blob bundles and atomically publishes one newest report per expected suite.
+ * The caller owns artifact transport; this function deliberately has no network or CI-provider API.
+ */
+export declare function prepareVitestReports(options: PrepareVitestReportsOptions): {
+    readonly selected: readonly SelectedVitestReport[];
+};

package/dist/vitest-blob-manifest/reports.mjs

@@ -0,0 +1,160 @@
+/* eslint-disable max-lines -- untrusted artifact discovery and publication form one security boundary. */
+import { randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { inspectVitestBlobBundle, VITEST_BLOB_MANIFEST_FILENAME, VITEST_SUITE_PATTERN, } from './index.mjs';
+function inspectSource(root, source) {
+    if (!existsSync(root))
+        return [];
+    if (!lstatSync(root).isDirectory())
+        throw new Error(`Vitest ${source} root must be a directory`);
+    const entries = readdirSync(root, { withFileTypes: true });
+    if (entries.length === 0)
+        return [];
+    const isFlattened = entries.some((entry) => entry.name === VITEST_BLOB_MANIFEST_FILENAME);
+    if (isFlattened)
+        return [{ ...inspectVitestBlobBundle(root), source }];
+    const invalid = entries.find((entry) => {
+        const suite = entry.name.startsWith('.invalid-') ? entry.name.slice('.invalid-'.length) : '';
+        return entry.isFile() && VITEST_SUITE_PATTERN.test(suite);
+    });
+    if (invalid)
+        throw new Error(`Vitest ${source} root contains an invalid archive marker`);
+    const unexpected = entries.find((entry) => !entry.isDirectory());
+    if (unexpected)
+        throw new Error(`Vitest ${source} root has an unexpected entry`);
+    return entries
+        .toSorted((left, right) => left.name.localeCompare(right.name))
+        .map((entry) => ({ ...inspectVitestBlobBundle(join(root, entry.name)), source }));
+}
+function validateOptions(options) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(options.repository)) {
+        throw new Error('Invalid Vitest repository');
+    }
+    if (!/^[0-9a-f]{40}$/.test(options.revision))
+        throw new Error('Invalid Vitest revision');
+    if (!/^[1-9][0-9]*$/.test(options.run.id) || !Number.isSafeInteger(options.run.currentAttempt)) {
+        throw new Error('Invalid Vitest run');
+    }
+    if (options.run.currentAttempt < 1)
+        throw new Error('Invalid Vitest run');
+    for (const expectation of options.expectedSuites) {
+        if (!VITEST_SUITE_PATTERN.test(expectation.suite) ||
+            !Number.isSafeInteger(expectation.minimumAttempt)) {
+            throw new Error('Invalid expected Vitest suite');
+        }
+        if (expectation.minimumAttempt < 1 || expectation.minimumAttempt > options.run.currentAttempt) {
+            throw new Error('Invalid expected Vitest suite attempt');
+        }
+    }
+}
+function validateIdentity(candidate, options) {
+    const { manifest } = candidate;
+    if (manifest.repository !== options.repository ||
+        manifest.revision !== options.revision ||
+        manifest.run.id !== options.run.id) {
+        throw new Error(`Vitest blob identity does not match this run for ${manifest.suite}`);
+    }
+    if (manifest.run.attempt > options.run.currentAttempt) {
+        throw new Error(`Vitest blob attempt is from the future for ${manifest.suite}`);
+    }
+}
+function identical(left, right) {
+    return (left.manifestBytes.equals(right.manifestBytes) && left.reportBytes.equals(right.reportBytes));
+}
+function rejectConflictingCopies(candidates) {
+    const firstByIdentity = new Map();
+    for (const candidate of candidates) {
+        const key = `${candidate.manifest.suite}\0${candidate.manifest.run.attempt}`;
+        const first = firstByIdentity.get(key);
+        if (first && !identical(first, candidate)) {
+            throw new Error(`Conflicting Vitest blobs for ${candidate.manifest.suite} attempt ${candidate.manifest.run.attempt}`);
+        }
+        firstByIdentity.set(key, first ?? candidate);
+    }
+}
+function selectCandidates(candidates, options) {
+    const expected = new Map(options.expectedSuites.map((expectation) => [expectation.suite, expectation.minimumAttempt]));
+    if (expected.size !== options.expectedSuites.length)
+        throw new Error('Expected Vitest suites must be unique');
+    for (const candidate of candidates)
+        validateIdentity(candidate, options);
+    rejectConflictingCopies(candidates);
+    for (const candidate of candidates) {
+        if (!expected.has(candidate.manifest.suite) &&
+            candidate.manifest.run.attempt === options.run.currentAttempt) {
+            throw new Error(`Unexpected current-attempt Vitest suite: ${candidate.manifest.suite}`);
+        }
+    }
+    return options.expectedSuites
+        .toSorted((left, right) => left.suite.localeCompare(right.suite))
+        .map((expectation) => {
+        const matches = candidates.filter((candidate) => candidate.manifest.suite === expectation.suite &&
+            candidate.manifest.run.attempt >= expectation.minimumAttempt);
+        if (matches.length === 0)
+            throw new Error(`Missing expected Vitest suite: ${expectation.suite}`);
+        const latestAttempt = Math.max(...matches.map((candidate) => candidate.manifest.run.attempt));
+        const latest = matches.filter((candidate) => candidate.manifest.run.attempt === latestAttempt);
+        return {
+            candidate: latest[0],
+            sources: [...new Set(latest.map((candidate) => candidate.source))].toSorted(),
+        };
+    });
+}
+function replaceOutput(outputDir, selected) {
+    const parent = dirname(outputDir);
+    mkdirSync(parent, { recursive: true });
+    const temporary = mkdtempSync(join(parent, `.${basename(outputDir)}-`));
+    const backup = join(parent, `.${basename(outputDir)}-backup-${randomUUID()}`);
+    let backedUp = false;
+    try {
+        for (const { candidate } of selected) {
+            writeFileSync(join(temporary, `${candidate.manifest.suite}.json`), candidate.reportBytes, {
+                flag: 'wx',
+                mode: 0o600,
+            });
+        }
+        if (existsSync(outputDir)) {
+            if (!lstatSync(outputDir).isDirectory())
+                throw new Error('Vitest report output must be a directory');
+            renameSync(outputDir, backup);
+            backedUp = true;
+        }
+        try {
+            renameSync(temporary, outputDir);
+        }
+        catch (error) {
+            /* v8 ignore start -- an OS-level rename failure restores the already-tested backup path */
+            if (backedUp)
+                renameSync(backup, outputDir);
+            backedUp = false;
+            throw error;
+            /* v8 ignore stop */
+        }
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+        if (backedUp)
+            rmSync(backup, { recursive: true, force: true });
+    }
+}
+/**
+ * Validates untrusted blob bundles and atomically publishes one newest report per expected suite.
+ * The caller owns artifact transport; this function deliberately has no network or CI-provider API.
+ */
+export function prepareVitestReports(options) {
+    validateOptions(options);
+    const candidates = [
+        ...inspectSource(options.primaryDir, 'primary'),
+        ...inspectSource(options.fallbackDir, 'fallback'),
+    ];
+    const selected = selectCandidates(candidates, options);
+    replaceOutput(options.outputDir, selected);
+    return {
+        selected: selected.map(({ candidate, sources }) => ({
+            suite: candidate.manifest.suite,
+            attempt: candidate.manifest.run.attempt,
+            sources,
+        })),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -55,6 +55,11 @@
       "import": "./dist/vitest-blob-manifest/index.mjs",
       "default": "./dist/vitest-blob-manifest/index.mjs"
     },
+    "./vitest-reports": {
+      "types": "./dist/vitest-blob-manifest/reports.d.mts",
+      "import": "./dist/vitest-blob-manifest/reports.mjs",
+      "default": "./dist/vitest-blob-manifest/reports.mjs"
+    },
     "./pnpm-install": {
       "types": "./dist/pnpm-install/index.d.mts",
       "import": "./dist/pnpm-install/index.mjs",
@@ -95,6 +100,36 @@
       "import": "./dist/openapi-document/index.mjs",
       "default": "./dist/openapi-document/index.mjs"
     },
+    "./transient-retry": {
+      "types": "./dist/transient-retry/index.d.mts",
+      "import": "./dist/transient-retry/index.mjs",
+      "default": "./dist/transient-retry/index.mjs"
+    },
+    "./csv": {
+      "types": "./dist/csv/index.d.mts",
+      "import": "./dist/csv/index.mjs",
+      "default": "./dist/csv/index.mjs"
+    },
+    "./http-body": {
+      "types": "./dist/http-body/index.d.mts",
+      "import": "./dist/http-body/index.mjs",
+      "default": "./dist/http-body/index.mjs"
+    },
+    "./ast-grep-rule": {
+      "types": "./dist/ast-grep-rule/index.d.mts",
+      "import": "./dist/ast-grep-rule/index.mjs",
+      "default": "./dist/ast-grep-rule/index.mjs"
+    },
+    "./gha-review-payload": {
+      "types": "./dist/gha-review-payload/index.d.mts",
+      "import": "./dist/gha-review-payload/index.mjs",
+      "default": "./dist/gha-review-payload/index.mjs"
+    },
+    "./http-link-pagination": {
+      "types": "./dist/http-link-pagination/index.d.mts",
+      "import": "./dist/http-link-pagination/index.mjs",
+      "default": "./dist/http-link-pagination/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -106,6 +141,8 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
+    "csv-parse": "7.0.2",
+    "csv-stringify": "6.8.2",
     "picomatch": "4.0.5"
   },
   "devDependencies": {