vouchington-tooling 0.0.4 → 0.0.6

package/dist/shared-context/fake-git.test-helpers.mjs

@@ -0,0 +1,59 @@
+import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const FAKE_GIT_INSIDE = 'FAKE_GIT_INSIDE';
+const FAKE_GIT_ROOT = 'FAKE_GIT_ROOT';
+const FAKE_GIT_FILES = 'FAKE_GIT_FILES';
+const FAKE_GIT_LS_FILES_EXIT_CODE = 'FAKE_GIT_LS_FILES_EXIT_CODE';
+const FAKE_GIT_LS_FILES_STDERR = 'FAKE_GIT_LS_FILES_STDERR';
+export function installFakeGit({ binDir, isInsideWorkTree = true, lsFilesExitCode = 0, lsFilesStderr = '', pathPrefix = process.env.PATH, repoRoot, trackedFiles = [], }) {
+    mkdirSync(binDir, { recursive: true });
+    writeFileSync(join(binDir, 'git'), fakeGitScript());
+    chmodSync(join(binDir, 'git'), 0o755);
+    process.env.PATH = [binDir, pathPrefix].filter(Boolean).join(':');
+    process.env[FAKE_GIT_INSIDE] = String(isInsideWorkTree);
+    process.env[FAKE_GIT_LS_FILES_EXIT_CODE] = String(lsFilesExitCode);
+    process.env[FAKE_GIT_LS_FILES_STDERR] = lsFilesStderr;
+    if (repoRoot !== undefined)
+        process.env[FAKE_GIT_ROOT] = repoRoot;
+    process.env[FAKE_GIT_FILES] = [...trackedFiles].toSorted().join('\n');
+}
+export function clearFakeGitEnv() {
+    process.env.FAKE_GIT_INSIDE = 'false';
+    process.env.FAKE_GIT_ROOT = '';
+    process.env.FAKE_GIT_FILES = '';
+    process.env.FAKE_GIT_LS_FILES_EXIT_CODE = '';
+    process.env.FAKE_GIT_LS_FILES_STDERR = '';
+}
+function fakeGitScript() {
+    return [
+        '#!/usr/bin/env bash',
+        'set -euo pipefail',
+        'if [ "${1:-}" = "-C" ]; then',
+        '  shift 2',
+        'fi',
+        'case "${1:-} ${2:-}" in',
+        '  "rev-parse --is-inside-work-tree")',
+        '    [ "${FAKE_GIT_INSIDE:-false}" = "true" ]',
+        '    ;;',
+        '  "rev-parse --show-toplevel")',
+        '    printf \'%s\\n\' "${FAKE_GIT_ROOT:?}"',
+        '    ;;',
+        '  "ls-files -z"|"ls-files " )',
+        '    if [ "${FAKE_GIT_LS_FILES_EXIT_CODE:-0}" -ne 0 ]; then',
+        '      printf \'%s\' "${FAKE_GIT_LS_FILES_STDERR:-}" >&2',
+        '      exit "${FAKE_GIT_LS_FILES_EXIT_CODE}"',
+        '    fi',
+        '    printf \'%s\\n\' "${FAKE_GIT_FILES:-}" | while IFS= read -r file; do',
+        '      if [ -n "$file" ]; then',
+        String.raw `        printf '%s\0' "$file"`,
+        '      fi',
+        '    done',
+        '    ;;',
+        '  *)',
+        String.raw `    printf 'unexpected fake git invocation: %s\n' "$*" >&2`,
+        '    exit 2',
+        '    ;;',
+        'esac',
+        '',
+    ].join('\n');
+}

package/dist/shared-context/index.d.mts

@@ -0,0 +1,26 @@
+export declare function gitEnv(): NodeJS.ProcessEnv;
+export interface SharedContext {
+    repoRoot: string;
+    isInsideGitRepo: boolean;
+    trackedFiles: readonly string[];
+    trackedFileSet: ReadonlySet<string>;
+    /** Lazily reads tracked files and shares the result across policy visitors. */
+    readTrackedFile?: (file: string) => string | null;
+}
+export declare function buildContextFromTrackedFiles(repoRoot: string, trackedFiles: readonly string[]): SharedContext;
+export type NamedCheck = {
+    name: string;
+    run: (ctx: SharedContext) => Promise<{
+        errors: string[];
+        fixes?: string[];
+    }> | {
+        errors: string[];
+        fixes?: string[];
+    };
+};
+export declare function runNamedChecks(repoRoot: string, checks: readonly NamedCheck[]): Promise<Array<{
+    name: string;
+    errors: string[];
+    fixes?: string[];
+}>>;
+export declare function buildSharedContext(inputRoot: string): Promise<SharedContext>;

package/dist/shared-context/index.mjs

@@ -0,0 +1,89 @@
+import { execFile, spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export function gitEnv() {
+    return Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
+}
+async function listTrackedFiles(repoRoot) {
+    const lsOutput = await new Promise((resolve, reject) => {
+        const proc = spawn('git', ['-C', repoRoot, 'ls-files', '-z'], { env: gitEnv(), stdio: 'pipe' });
+        const chunks = [];
+        const errChunks = [];
+        proc.stdout.on('data', (d) => chunks.push(d));
+        proc.stderr.on('data', (d) => errChunks.push(d));
+        proc.on('error', reject);
+        proc.on('close', (code) => {
+            if (code !== 0) {
+                reject(new Error(`git ls-files failed (exit ${code}): ${Buffer.concat(errChunks).toString()}`));
+                return;
+            }
+            resolve(Buffer.concat(chunks).toString());
+        });
+    });
+    return lsOutput.split('\0').filter(Boolean);
+}
+// Builds the caches/helpers around an already-known tracked-file list, without spawning `git
+// ls-files` again. Split out from buildSharedContext() so a caller that already has the list
+// (e.g. a worker_threads worker whose parent already paid the spawn cost — worker_threads doesn't
+// share module-level JS state across threads, so the cache above can't be shared directly) can
+// reuse it instead of re-spawning `git ls-files` in its own process.
+export function buildContextFromTrackedFiles(repoRoot, trackedFiles) {
+    const trackedFileSet = new Set(trackedFiles);
+    const contents = new Map();
+    const readTrackedFile = (file) => {
+        if (!trackedFileSet.has(file))
+            return null;
+        const cached = contents.get(file);
+        if (cached !== undefined)
+            return cached;
+        try {
+            const content = readFileSync(join(repoRoot, file), 'utf8');
+            contents.set(file, content);
+            return content;
+        }
+        catch {
+            contents.set(file, null);
+            return null;
+        }
+    };
+    return {
+        repoRoot,
+        isInsideGitRepo: true,
+        trackedFiles,
+        trackedFileSet,
+        readTrackedFile,
+    };
+}
+export async function runNamedChecks(repoRoot, checks) {
+    const ctx = await buildSharedContext(repoRoot);
+    return Promise.all(checks.map(async (check) => {
+        const result = await check.run(ctx);
+        return { name: check.name, ...result };
+    }));
+}
+export async function buildSharedContext(inputRoot) {
+    // Run rev-parse checks first
+    try {
+        await execFileAsync('git', ['-C', inputRoot, 'rev-parse', '--is-inside-work-tree'], {
+            env: gitEnv(),
+        });
+    }
+    catch {
+        return {
+            repoRoot: inputRoot,
+            isInsideGitRepo: false,
+            trackedFiles: [],
+            trackedFileSet: new Set(),
+        };
+    }
+    // Get resolved root first, then use it to list files (so paths are always relative to repo root)
+    const rootResult = await execFileAsync('git', ['-C', inputRoot, 'rev-parse', '--show-toplevel'], {
+        encoding: 'utf8',
+        env: gitEnv(),
+    });
+    const repoRoot = rootResult.stdout.trim();
+    const trackedFiles = await listTrackedFiles(repoRoot);
+    return buildContextFromTrackedFiles(repoRoot, trackedFiles);
+}

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runVitestBlobManifestCli(args: readonly string[], env?: NodeJS.ProcessEnv, revision?: string): void;

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

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { writeVitestBlobManifest } from './index.mjs';
+function failRepository() {
+    throw new Error('GITHUB_REPOSITORY is required');
+}
+export function runVitestBlobManifestCli(args, env = process.env, revision = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+}).trim()) {
+    const [suite, directory = '.vitest-reports', ...extra] = args;
+    const runId = env.GITHUB_RUN_ID;
+    const rawAttempt = env.GITHUB_RUN_ATTEMPT;
+    if (!suite || extra.length > 0 || !runId || !rawAttempt) {
+        throw new Error('Usage: vouchington vitest-blob-manifest <suite> [reports-directory]');
+    }
+    const runAttempt = Number(rawAttempt);
+    if (!Number.isSafeInteger(runAttempt) || runAttempt < 1) {
+        throw new Error('GITHUB_RUN_ATTEMPT must be a positive integer');
+    }
+    writeVitestBlobManifest(directory, {
+        suite,
+        repository: env.GITHUB_REPOSITORY || failRepository(),
+        revision,
+        runId,
+        runAttempt,
+    });
+}
+/* v8 ignore next 3 -- exercised as an executable by the composite action contract */
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    runVitestBlobManifestCli(process.argv.slice(2));
+}

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

@@ -0,0 +1,37 @@
+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;
+    readonly repository: string;
+    readonly revision: string;
+    readonly run: {
+        readonly id: string;
+        readonly attempt: number;
+    };
+    readonly report: {
+        readonly filename: string;
+        readonly byteLength: number;
+        readonly sha256: string;
+    };
+}
+export interface VitestBlobIdentity {
+    readonly suite: string;
+    readonly repository: string;
+    readonly revision: string;
+    readonly runId: string;
+    readonly runAttempt: number;
+}
+export interface InspectedVitestBlobBundle {
+    readonly directory: string;
+    readonly manifest: VitestBlobManifest;
+    readonly manifestBytes: Buffer;
+    readonly reportBytes: Buffer;
+}
+export declare function parseVitestBlobManifest(raw: unknown): VitestBlobManifest;
+export declare function createVitestBlobManifest(identity: VitestBlobIdentity, reportBytes: Buffer): VitestBlobManifest;
+export declare function serializeVitestBlobManifest(manifest: VitestBlobManifest): Buffer;
+export declare function writeVitestBlobManifest(directory: string, identity: VitestBlobIdentity): string;
+export declare function vitestBlobBundlePaths(directory: string, suite: string): readonly [string, string];
+export declare function inspectVitestBlobBundle(directory: string): InspectedVitestBlobBundle;

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

@@ -0,0 +1,134 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, join } from 'node:path';
+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);
+}
+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 assertRegularFile(path, label) {
+    if (!lstatSync(path).isFile())
+        throw new Error(`${label} must be a regular file`);
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function parseVitestBlobManifest(raw) {
+    if (!isRecord(raw) ||
+        !hasExactKeys(raw, ['version', 'suite', 'repository', 'revision', 'run', 'report']) ||
+        raw.version !== VITEST_BLOB_MANIFEST_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) ||
+        !isRecord(raw.report) ||
+        !hasExactKeys(raw.report, ['filename', 'byteLength', 'sha256']) ||
+        raw.report.filename !== `${raw.suite}.json` ||
+        !Number.isSafeInteger(raw.report.byteLength) ||
+        Number(raw.report.byteLength) < 0 ||
+        typeof raw.report.sha256 !== 'string' ||
+        !/^[0-9a-f]{64}$/.test(raw.report.sha256)) {
+        throw new Error('Vitest blob manifest has an invalid schema');
+    }
+    return raw;
+}
+export function createVitestBlobManifest(identity, reportBytes) {
+    return parseVitestBlobManifest({
+        version: VITEST_BLOB_MANIFEST_VERSION,
+        suite: identity.suite,
+        repository: identity.repository,
+        revision: identity.revision,
+        run: { id: identity.runId, attempt: identity.runAttempt },
+        report: {
+            filename: `${identity.suite}.json`,
+            byteLength: reportBytes.byteLength,
+            sha256: sha256(reportBytes),
+        },
+    });
+}
+export function serializeVitestBlobManifest(manifest) {
+    return Buffer.from(`${JSON.stringify(parseVitestBlobManifest(manifest), null, 2)}\n`);
+}
+export function writeVitestBlobManifest(directory, identity) {
+    if (!VITEST_SUITE_PATTERN.test(identity.suite))
+        throw new Error('Invalid Vitest suite');
+    const reportEntries = readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.name.endsWith('.json') && entry.name !== VITEST_BLOB_MANIFEST_FILENAME);
+    const reportEntry = reportEntries[0];
+    if (reportEntries.length !== 1 ||
+        reportEntry === undefined ||
+        reportEntry.name !== `${identity.suite}.json` ||
+        !reportEntry.isFile()) {
+        throw new Error(`Expected exactly one ${identity.suite}.json Vitest blob report`);
+    }
+    const reportPath = join(directory, `${identity.suite}.json`);
+    assertRegularFile(reportPath, 'Vitest blob report');
+    const bytes = serializeVitestBlobManifest(createVitestBlobManifest(identity, readFileSync(reportPath)));
+    const manifestPath = join(directory, VITEST_BLOB_MANIFEST_FILENAME);
+    const temporaryPath = join(directory, `.${VITEST_BLOB_MANIFEST_FILENAME}.${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporaryPath, bytes, { flag: 'wx', mode: 0o600 });
+        renameSync(temporaryPath, manifestPath);
+    }
+    finally {
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Successful rename removes the temporary path.
+        }
+    }
+    return manifestPath;
+}
+export function vitestBlobBundlePaths(directory, suite) {
+    if (!VITEST_SUITE_PATTERN.test(suite))
+        throw new Error('Invalid Vitest suite');
+    const manifestPath = join(directory, VITEST_BLOB_MANIFEST_FILENAME);
+    const reportPath = join(directory, `${suite}.json`);
+    assertRegularFile(manifestPath, 'Vitest blob manifest');
+    assertRegularFile(reportPath, 'Vitest blob report');
+    return [manifestPath, reportPath];
+}
+export function inspectVitestBlobBundle(directory) {
+    const entries = readdirSync(directory, { withFileTypes: true });
+    if (entries.length !== 2 || entries.some((entry) => !entry.isFile())) {
+        throw new Error(`Vitest blob bundle ${basename(directory)} must contain exactly two files`);
+    }
+    const manifestPath = join(directory, VITEST_BLOB_MANIFEST_FILENAME);
+    assertRegularFile(manifestPath, 'Vitest blob manifest');
+    const manifestBytes = readFileSync(manifestPath);
+    let manifest;
+    try {
+        manifest = parseVitestBlobManifest(JSON.parse(manifestBytes.toString('utf8')));
+    }
+    catch (error) {
+        throw new Error(`Invalid Vitest blob bundle ${basename(directory)}`, { cause: error });
+    }
+    const reportPath = join(directory, manifest.report.filename);
+    assertRegularFile(reportPath, 'Vitest blob report');
+    const reportBytes = readFileSync(reportPath);
+    if (reportBytes.byteLength !== manifest.report.byteLength ||
+        sha256(reportBytes) !== manifest.report.sha256) {
+        throw new Error(`Vitest blob report integrity check failed for ${manifest.suite}`);
+    }
+    try {
+        JSON.parse(reportBytes.toString('utf8'));
+    }
+    catch (error) {
+        throw new Error(`Vitest blob report is not valid JSON for ${manifest.suite}`, { cause: error });
+    }
+    return { directory, manifest, manifestBytes, reportBytes };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -50,6 +50,21 @@
       "import": "./dist/gha-runtime-audit/index.mjs",
       "default": "./dist/gha-runtime-audit/index.mjs"
     },
+    "./vitest-blob-manifest": {
+      "types": "./dist/vitest-blob-manifest/index.d.mts",
+      "import": "./dist/vitest-blob-manifest/index.mjs",
+      "default": "./dist/vitest-blob-manifest/index.mjs"
+    },
+    "./pnpm-install": {
+      "types": "./dist/pnpm-install/index.d.mts",
+      "import": "./dist/pnpm-install/index.mjs",
+      "default": "./dist/pnpm-install/index.mjs"
+    },
+    "./shared-context": {
+      "types": "./dist/shared-context/index.d.mts",
+      "import": "./dist/shared-context/index.mjs",
+      "default": "./dist/shared-context/index.mjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {