@lullabot/playwright-testing 0.1.0

package/lib/github/failure-summary.js

@@ -0,0 +1,567 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLAKE_MARKER_PREFIX = exports.FAILURE_MARKER_PREFIX = void 0;
+exports.defuseMaskTriggers = defuseMaskTriggers;
+exports.parseFailures = parseFailures;
+exports.resolveImagePaths = resolveImagePaths;
+exports.uploadImages = uploadImages;
+exports.generateSummary = generateSummary;
+exports.generateComment = generateComment;
+exports.uploaderFromEnvironment = uploaderFromEnvironment;
+exports.main = main;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const attachments_1 = require("./attachments");
+const report_paths_1 = require("./report-paths");
+/**
+ * Turn a Playwright JSON report into a job summary — and optionally a PR
+ * comment body — with the failure screenshots embedded inline.
+ *
+ * Playwright already captures everything worth looking at: `toHaveScreenshot`
+ * attaches `-expected`/`-actual`/`-diff` images when a comparison fails, and
+ * checkAccessibility() attaches a full-page screenshot with the violating
+ * elements outlined. Both normally end up zipped inside an artifact nobody
+ * downloads. Given an upload token they can be embedded where the failure is
+ * actually read.
+ *
+ * Without a token this still produces a useful text summary, so the feature
+ * degrades rather than disappearing.
+ */
+/** Attachment names Playwright gives the three snapshot comparison images. */
+const SNAPSHOT_SUFFIXES = [
+    { suffix: '-diff', kind: 'diff' },
+    { suffix: '-actual', kind: 'actual' },
+    { suffix: '-expected', kind: 'expected' },
+    { suffix: '-previous', kind: 'previous' },
+];
+/** Attachment name used by checkAccessibility() for its highlighted screenshot. */
+const A11Y_SCREENSHOT = 'a11y-violation-screenshot';
+/**
+ * Prefix of the HTML comment carrying the failure count in a generated comment
+ * body. Invisible when rendered, and greppable by a workflow that has to decide
+ * whether the run is worth commenting on.
+ */
+exports.FAILURE_MARKER_PREFIX = '<!-- playwright-testing-failures: ';
+/** Machine-readable flaky-test count used by the comment assembly action. */
+exports.FLAKE_MARKER_PREFIX = '<!-- playwright-testing-flakes: ';
+/**
+ * Neutralise text that the Actions runner would redact.
+ *
+ * Job summaries pass through the runner's secret masking (comments posted over
+ * the API do not). The masker replaces `Bearer <value>` with `***` and takes
+ * the following characters with it, so a test name or error containing the
+ * word can silently swallow the Markdown that follows it. A zero-width space
+ * inside the word reads identically and no longer matches.
+ */
+function defuseMaskTriggers(text) {
+    return text.replace(/Bearer(?=\s)/g, 'Bear\u200Ber');
+}
+/** Strip ANSI colour codes Playwright puts in error messages. */
+function stripAnsi(text) {
+    return text.replace(/\u001b\[[0-9;]*m/g, '');
+}
+function classifyAttachment(name, contentType) {
+    if (!contentType.startsWith('image/'))
+        return null;
+    if (name === A11Y_SCREENSHOT)
+        return 'a11y';
+    const withoutExtension = name.replace(/\.[^.]+$/, '');
+    for (const { suffix, kind } of SNAPSHOT_SUFFIXES) {
+        if (withoutExtension.endsWith(suffix))
+            return kind;
+    }
+    return 'screenshot';
+}
+/**
+ * Collect the images worth showing for one test result.
+ *
+ * Accessibility screenshots are kept even when the test passed, because a
+ * baselined violation still passes and its screenshot is still the thing you
+ * want to look at.
+ */
+function collectImages(attachments, include) {
+    const images = [];
+    for (const attachment of attachments) {
+        const name = String(attachment?.name ?? '');
+        const contentType = String(attachment?.contentType ?? '');
+        const kind = classifyAttachment(name, contentType);
+        if (!kind)
+            continue;
+        // Uploading three near-identical images per failure is rarely worth it;
+        // the diff is the one that shows what changed.
+        if (include === 'diff' && (kind === 'expected' || kind === 'actual' || kind === 'previous')) {
+            continue;
+        }
+        images.push({
+            name,
+            filePath: attachment?.path ? String(attachment.path) : undefined,
+            body: attachment?.body ? String(attachment.body) : undefined,
+            contentType,
+            kind,
+        });
+    }
+    return images;
+}
+function firstError(result) {
+    const message = result?.error?.message ?? result?.errors?.[0]?.message;
+    if (typeof message !== 'string' || !message.trim())
+        return undefined;
+    const cleaned = stripAnsi(message).trim().split('\n')[0];
+    return cleaned.length > 300 ? `${cleaned.slice(0, 300)}…` : cleaned;
+}
+function walkSuites(suites, parentFile, include, out) {
+    for (const suite of suites ?? []) {
+        const file = suite.file || parentFile;
+        for (const spec of suite.specs ?? []) {
+            for (const test of spec.tests ?? []) {
+                const results = test.results ?? [];
+                const result = results[results.length - 1];
+                if (!result)
+                    continue;
+                // Playwright reports each retry as another result. A passing final
+                // attempt therefore hides the failed attempt unless we deliberately
+                // retain it and give the test its Playwright outcome: flaky.
+                const failedAttempts = results.slice(0, -1).filter((attempt) => (attempt?.status !== 'passed' && attempt?.status !== 'skipped'));
+                // JSON reports expose Playwright's computed outcome on the test. Keep
+                // the attempt-based fallback for older or hand-written reports that do
+                // not carry it.
+                const flaky = test.status === 'flaky' || (test.status === undefined && result.status === 'passed' && failedAttempts.length > 0);
+                const reportedResult = flaky ? failedAttempts[failedAttempts.length - 1] : result;
+                const images = collectImages(reportedResult.attachments ?? [], include);
+                const failed = result.status !== 'passed' && result.status !== 'skipped';
+                const hasA11yImage = images.some(image => image.kind === 'a11y');
+                if (!failed && !flaky && !hasA11yImage)
+                    continue;
+                out.push({
+                    title: spec.title,
+                    file,
+                    line: spec.line ?? 1,
+                    status: flaky ? 'flaky' : String(result.status ?? 'unknown'),
+                    error: firstError(reportedResult),
+                    images,
+                });
+            }
+        }
+        walkSuites(suite.suites ?? [], file, include, out);
+    }
+}
+/**
+ * Parse a Playwright JSON report into the failures worth reporting.
+ */
+function parseFailures(reportPath, include = 'diff') {
+    const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+    const tests = [];
+    walkSuites(report.suites ?? [], '', include, tests);
+    const totalFailed = tests.filter(test => (test.status !== 'passed' && test.status !== 'skipped' && test.status !== 'flaky')).length;
+    const totalFlaky = tests.filter(test => test.status === 'flaky').length;
+    const totalImages = tests.reduce((sum, test) => sum + test.images.length, 0);
+    return { tests, totalFailed, totalFlaky, totalImages };
+}
+/**
+ * Point every image at a file this process can open, and note the ones where
+ * that was not possible.
+ *
+ * Runs whether or not uploads are switched on: an unreachable attachment is
+ * worth reporting even on a fork build that was never going to upload it,
+ * because it is the same misconfiguration either way.
+ */
+function resolveImagePaths(report, resolve) {
+    const summary = { remapped: 0, used: [], unreadable: [] };
+    for (const test of report.tests) {
+        for (const image of test.images) {
+            if (!image.filePath)
+                continue;
+            const resolution = resolve(image.filePath);
+            if (!resolution.found) {
+                image.unreadable = true;
+                summary.unreadable.push(image.filePath);
+                continue;
+            }
+            if (resolution.path === image.filePath)
+                continue;
+            summary.remapped++;
+            image.filePath = resolution.path;
+            const prefix = resolution.prefix;
+            if (prefix && !summary.used.some(used => used.from === prefix.from && used.to === prefix.to)) {
+                summary.used.push(prefix);
+            }
+        }
+    }
+    return summary;
+}
+/**
+ * Upload every collected image, annotating each one with its URL. Images the
+ * uploader declines are simply left without a URL, which the renderers treat
+ * as "link to the artifact instead".
+ */
+async function uploadImages(report, uploader) {
+    for (const test of report.tests) {
+        for (const image of test.images) {
+            let url = null;
+            if (image.filePath) {
+                url = await uploader.upload(image.filePath, path.basename(image.filePath));
+            }
+            else if (image.body) {
+                url = await uploader.uploadBuffer(Buffer.from(image.body, 'base64'), `${image.name}${extensionFor(image.contentType)}`, image.contentType);
+            }
+            if (url) {
+                image.url = url;
+                continue;
+            }
+            // Every one of these is a null, and they need different things said
+            // about them. resolveImagePaths() has already checked the file is there,
+            // so 'unreadable' here means the read itself failed; the size reasons
+            // are the uploader declining this one image rather than stopping.
+            switch (uploader.lastSkipReason) {
+                case 'unreadable':
+                    image.unreadable = true;
+                    break;
+                case 'too-large':
+                case 'budget':
+                    image.oversize = true;
+                    break;
+            }
+        }
+    }
+}
+/** Inlined attachments carry no file name, so derive one from the content type. */
+function extensionFor(contentType) {
+    if (contentType === 'image/png')
+        return '.png';
+    if (contentType === 'image/jpeg')
+        return '.jpg';
+    if (contentType === 'image/gif')
+        return '.gif';
+    if (contentType === 'image/webp')
+        return '.webp';
+    return '';
+}
+function headline(report) {
+    if (report.tests.length === 0)
+        return ':white_check_mark: No failing tests or flaky tests with screenshots.';
+    // Nothing failed, but an accessibility check still captured something worth
+    // seeing — a baselined violation passes and is still screenshotted.
+    const parts = report.totalFailed === 0
+        ? [':white_check_mark: No failing tests']
+        : [`**${report.totalFailed}** failing test(s)`];
+    if (report.totalFlaky > 0)
+        parts.push(`:warning: **${report.totalFlaky}** flaky test(s)`);
+    if (report.totalImages > 0)
+        parts.push(`**${report.totalImages}** screenshot(s)`);
+    return parts.join(' · ');
+}
+/** Every image across every test, which is what the diagnostics count. */
+function allImages(report) {
+    return report.tests.flatMap(test => test.images);
+}
+/**
+ * Say why a set of images was not uploaded, or nothing when they were.
+ *
+ * "No token" and "the files were not where the report said" are different
+ * problems with different fixes, and until they are named apart a reader has
+ * no way to tell which one they have. An absent token is the dominant reason
+ * when it applies: nothing was going to be uploaded regardless.
+ */
+function missingImageReason(images, uploadReason) {
+    if (uploadReason)
+        return uploadReason;
+    const reasons = [];
+    const unreadable = images.filter(image => image.unreadable).length;
+    if (unreadable > 0) {
+        reasons.push(`${unreadable} could not be read from the path recorded in the report`);
+    }
+    const oversize = images.filter(image => image.oversize).length;
+    if (oversize > 0) {
+        reasons.push(`${oversize} too large to upload`);
+    }
+    return reasons.length > 0 ? reasons.join('; ') : undefined;
+}
+/**
+ * Render the job summary: a heading, a headline, and one collapsed block per
+ * test holding its images.
+ *
+ * Deliberately table-free. Test titles and error messages are arbitrary text,
+ * and the runner's masking can eat a cell delimiter and corrupt a whole row.
+ */
+function generateSummary(report, options = {}) {
+    // A baselined accessibility violation is screenshotted without failing
+    // anything, so a green run can still have something to show here.
+    const heading = report.totalFailed > 0
+        ? '## Test Failures'
+        : report.totalFlaky > 0 ? '## Test Flakes' : '## Test Screenshots';
+    const lines = [`${heading}\n`, `${headline(report)}\n`];
+    if (report.tests.length === 0)
+        return lines.join('\n');
+    // Name the path boundary where it will be read, rather than leaving the
+    // reader to conclude they forgot the token.
+    const unreadable = allImages(report).filter(image => image.unreadable);
+    if (unreadable.length > 0) {
+        const example = defuseMaskTriggers(unreadable[0].filePath ?? '');
+        lines.push(`> :warning: **${unreadable.length} screenshot(s) could not be read.** The report records them ` +
+            `under \`${example}\`, which does not exist where this step ran. Playwright ran somewhere else — ` +
+            'a container, most likely — so run this command there too, or pass ' +
+            '`--path-prefix=CONTAINER_PATH:LOCAL_PATH` to map one onto the other.\n');
+    }
+    for (const test of report.tests) {
+        const title = defuseMaskTriggers(test.title);
+        lines.push(`### ${title}\n`);
+        lines.push(`\`${test.file}:${test.line}\` — ${test.status}\n`);
+        if (test.error) {
+            lines.push(`> ${defuseMaskTriggers(test.error)}\n`);
+        }
+        if (test.images.length === 0)
+            continue;
+        // The images go in the pull request comment, not here. A job summary is
+        // rendered once, when the job finishes, and an attachment uploaded seconds
+        // earlier is not resolvable yet — so it renders as a dead link and the
+        // cached result never improves, however often the page is reloaded.
+        const embedded = test.images.filter(image => image.url).length;
+        if (embedded > 0) {
+            lines.push(`${embedded} screenshot(s) uploaded — see the pull request comment.\n`);
+        }
+        else {
+            const hint = options.artifactHint ?? 'the Playwright report artifact';
+            const reason = missingImageReason(test.images, options.uploadReason);
+            const because = reason ? ` (${reason})` : '';
+            lines.push(`${test.images.length} screenshot(s) captured, not uploaded${because} — download ${hint}.\n`);
+        }
+    }
+    return lines.join('\n');
+}
+/** A collapsed block of images for one test, used in the comment. */
+function renderImageBlock(test) {
+    const embedded = test.images.filter(image => image.url);
+    if (embedded.length === 0)
+        return [];
+    const title = defuseMaskTriggers(test.title);
+    const lines = ['<details>', `<summary>Screenshots (${embedded.length})</summary>\n`];
+    for (const image of embedded) {
+        lines.push(`**${image.kind}**\n`);
+        const src = escapeAttribute(image.url ?? '');
+        lines.push(`<img src="${src}" alt="${image.kind} for ${escapeAttribute(title)}" width="640">\n`);
+    }
+    lines.push('</details>\n');
+    return lines;
+}
+function generateComment(report, options = {}) {
+    const heading = options.title ?? 'Playwright results';
+    const lines = [`### ${heading}\n`, `${headline(report)}\n`];
+    if (report.tests.length > 0) {
+        for (const test of report.tests.slice(0, 10)) {
+            const title = defuseMaskTriggers(test.title);
+            const images = test.images.length > 0 ? ` — ${test.images.length} screenshot(s)` : '';
+            lines.push(`- \`${test.status}\` ${title}${images}`);
+        }
+        if (report.tests.length > 10) {
+            lines.push(`- …and ${report.tests.length - 10} more`);
+        }
+        lines.push('');
+        for (const test of report.tests) {
+            const block = renderImageBlock(test);
+            if (block.length === 0)
+                continue;
+            lines.push(`**${defuseMaskTriggers(test.title)}**\n`);
+            lines.push(...block);
+        }
+        // An empty comment where images were expected reads as a broken feature.
+        // Whatever the reason, it belongs where the images would have been.
+        const missing = allImages(report).filter(image => !image.url);
+        const reason = missingImageReason(missing, options.uploadReason);
+        if (missing.length > 0 && reason) {
+            lines.push(`_${missing.length} screenshot(s) not shown — ${reason}._\n`);
+        }
+    }
+    if (options.summaryUrl) {
+        lines.push(`[Full run](${options.summaryUrl})\n`);
+    }
+    // A machine-readable count, so a workflow assembling several of these can
+    // decide whether to post at all without grepping prose — the empty-state
+    // sentence contains the words "failing test" too.
+    lines.push(`${options.failureMarkerPrefix ?? exports.FAILURE_MARKER_PREFIX}${report.totalFailed} -->\n`);
+    lines.push(`${options.flakeMarkerPrefix ?? exports.FLAKE_MARKER_PREFIX}${report.totalFlaky} -->\n`);
+    return lines.join('\n');
+}
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+function parseArgs(args) {
+    const options = {
+        reportPath: 'test-results/results.json',
+        include: 'diff',
+        pathPrefixes: [],
+    };
+    for (const arg of args) {
+        // Repeatable: a project can have more than one mount to translate.
+        if (arg.startsWith('--path-prefix=')) {
+            const prefix = (0, report_paths_1.parsePathPrefix)(arg.slice('--path-prefix='.length));
+            if (prefix) {
+                options.pathPrefixes.push(prefix);
+            }
+            else {
+                console.error(`Ignoring --path-prefix: expected FROM:TO, got ${arg.slice('--path-prefix='.length)}`);
+            }
+        }
+        if (arg.startsWith('--report-path='))
+            options.reportPath = arg.slice('--report-path='.length);
+        if (arg.startsWith('--comment-path='))
+            options.commentPath = arg.slice('--comment-path='.length);
+        if (arg.startsWith('--title='))
+            options.title = arg.slice('--title='.length);
+        if (arg.startsWith('--include=')) {
+            const value = arg.slice('--include='.length);
+            options.include = value === 'all' ? 'all' : 'diff';
+        }
+        if (arg.startsWith('--max-uploads=')) {
+            const value = Number.parseInt(arg.slice('--max-uploads='.length), 10);
+            if (Number.isFinite(value) && value >= 0)
+                options.maxUploads = value;
+        }
+    }
+    return options;
+}
+/**
+ * Raise a warning where someone will see it.
+ *
+ * A `::warning::` command has to go to stdout for the runner to pick it up,
+ * which is only safe once the summary itself is going to a file — otherwise it
+ * would land in the middle of the Markdown. Outside Actions, or when the
+ * summary is on stdout, stderr is the only sensible place.
+ */
+function warn(message) {
+    const inActions = process.env.GITHUB_ACTIONS === 'true' && !!process.env.GITHUB_STEP_SUMMARY;
+    if (inActions) {
+        process.stdout.write(`::warning title=Playwright screenshots::${escapeAnnotation(message)}\n`);
+    }
+    else {
+        console.error(`Warning: ${message}`);
+    }
+}
+/** Workflow commands are line-based, so anything that ends a line is encoded. */
+function escapeAnnotation(message) {
+    return message.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+}
+/** Build the run's job summary URL, which is the best anchor a comment can link to. */
+function summaryUrl() {
+    const { GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID } = process.env;
+    if (!GITHUB_SERVER_URL || !GITHUB_REPOSITORY || !GITHUB_RUN_ID)
+        return undefined;
+    return `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}`;
+}
+function uploaderFromEnvironment(overrides = {}) {
+    return new attachments_1.AttachmentUploader({
+        token: process.env.SCREENSHOT_GITHUB_TOKEN,
+        repositoryId: process.env.GITHUB_REPOSITORY_ID,
+        log: message => console.error(message),
+        ...overrides,
+    });
+}
+async function main(args = process.argv.slice(2), adapter = {}) {
+    if (args.includes('--help') || args.includes('-h')) {
+        process.stdout.write(`Usage: ${adapter.commandName ?? 'playwright-testing-failure-summary'} [options]\n\n` +
+            'Options:\n' +
+            '  --report-path=PATH       Playwright JSON report (default: test-results/results.json)\n' +
+            '  --comment-path=PATH      Write a pull request comment body\n' +
+            '  --include=diff|all       Select comparison images (default: diff)\n' +
+            '  --path-prefix=FROM:TO    Remap attachment paths; repeatable\n' +
+            '  --max-uploads=COUNT      Limit uploaded screenshots\n' +
+            '  --title=TEXT             Set the comment heading\n' +
+            '  -h, --help               Show this help\n');
+        return;
+    }
+    const options = parseArgs(args);
+    const resolvedPath = path.resolve(options.reportPath);
+    // A missing report is not an error: the suite may not have run at all.
+    if (!fs.existsSync(resolvedPath)) {
+        console.error(`Playwright JSON report not found at ${resolvedPath} — skipping failure summary.`);
+        return;
+    }
+    const report = parseFailures(resolvedPath, options.include);
+    // The report records where the run wrote its attachments, which is not
+    // necessarily anywhere this process can reach. Settle that before uploading,
+    // so an unreachable file is reported as one rather than as a silent skip.
+    const paths = resolveImagePaths(report, (0, report_paths_1.createPathResolver)({ reportPath: resolvedPath, prefixes: options.pathPrefixes }));
+    if (paths.remapped > 0) {
+        const mappings = paths.used.map(prefix => `${prefix.from} → ${prefix.to}`).join(', ');
+        console.error(`Remapped ${paths.remapped} attachment path(s): ${mappings || 'no mapping recorded'}`);
+    }
+    if (paths.unreadable.length > 0) {
+        warn(`${paths.unreadable.length} screenshot(s) could not be read, starting with ${paths.unreadable[0]}. ` +
+            'Playwright ran somewhere this command cannot reach — a container, most likely. Run it there too, ' +
+            'or pass --path-prefix=CONTAINER_PATH:LOCAL_PATH.');
+    }
+    const uploader = uploaderFromEnvironment(options.maxUploads === undefined ? {} : { maxUploads: options.maxUploads });
+    if (uploader.enabled) {
+        await uploadImages(report, uploader);
+        const stats = uploader.getStats();
+        console.error(`Uploaded ${stats.uploaded} screenshot(s), skipped ${stats.skipped}.`);
+        if (uploader.disabledReason) {
+            // Reaching an undocumented endpoint that no longer answers is a real
+            // fault, unlike an absent token on a fork build.
+            warn(`Screenshot uploads stopped early — ${uploader.disabledReason}.`);
+        }
+    }
+    else {
+        console.error(`Screenshot uploads are off — ${uploader.disabledReason}.`);
+    }
+    const uploadReason = uploader.disabledReason ?? undefined;
+    const summary = generateSummary(report, { uploadReason });
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile) {
+        fs.appendFileSync(summaryFile, summary);
+        console.error('Failure summary written to $GITHUB_STEP_SUMMARY');
+    }
+    else {
+        process.stdout.write(summary);
+    }
+    if (options.commentPath) {
+        const comment = generateComment(report, {
+            summaryUrl: summaryUrl(),
+            title: options.title,
+            uploadReason,
+            failureMarkerPrefix: adapter.failureMarkerPrefix,
+            flakeMarkerPrefix: adapter.flakeMarkerPrefix,
+        });
+        fs.writeFileSync(path.resolve(options.commentPath), comment);
+        console.error(`Comment body written to ${options.commentPath}`);
+    }
+}
+// Auto-invoke when run directly (node lib/github/failure-summary.js).
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
+}

package/lib/github/index.d.ts

@@ -0,0 +1,6 @@
+export { generateAnnotations as generateA11yAnnotations, generateSummary as generateA11ySummary, main as runA11ySummary, parseA11yResults, } from './a11y-summary';
+export type { A11yReport, A11yTestResult } from './a11y-summary';
+export * from './attachments';
+export { FAILURE_MARKER_PREFIX, FLAKE_MARKER_PREFIX, defuseMaskTriggers, generateComment as generateFailureComment, generateSummary as generateFailureSummary, main as runFailureSummary, parseFailures, resolveImagePaths, uploaderFromEnvironment, uploadImages, } from './failure-summary';
+export type { FailedTest, FailureImage, FailureReport, FailureCommentOptions, FailureSummaryMainOptions, ImageKind, IncludeMode, PathResolutionSummary, SummaryOptions, } from './failure-summary';
+export * from './report-paths';

package/lib/github/index.js

@@ -0,0 +1,35 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadImages = exports.uploaderFromEnvironment = exports.resolveImagePaths = exports.parseFailures = exports.runFailureSummary = exports.generateFailureSummary = exports.generateFailureComment = exports.defuseMaskTriggers = exports.FLAKE_MARKER_PREFIX = exports.FAILURE_MARKER_PREFIX = exports.parseA11yResults = exports.runA11ySummary = exports.generateA11ySummary = exports.generateA11yAnnotations = void 0;
+var a11y_summary_1 = require("./a11y-summary");
+Object.defineProperty(exports, "generateA11yAnnotations", { enumerable: true, get: function () { return a11y_summary_1.generateAnnotations; } });
+Object.defineProperty(exports, "generateA11ySummary", { enumerable: true, get: function () { return a11y_summary_1.generateSummary; } });
+Object.defineProperty(exports, "runA11ySummary", { enumerable: true, get: function () { return a11y_summary_1.main; } });
+Object.defineProperty(exports, "parseA11yResults", { enumerable: true, get: function () { return a11y_summary_1.parseA11yResults; } });
+__exportStar(require("./attachments"), exports);
+var failure_summary_1 = require("./failure-summary");
+Object.defineProperty(exports, "FAILURE_MARKER_PREFIX", { enumerable: true, get: function () { return failure_summary_1.FAILURE_MARKER_PREFIX; } });
+Object.defineProperty(exports, "FLAKE_MARKER_PREFIX", { enumerable: true, get: function () { return failure_summary_1.FLAKE_MARKER_PREFIX; } });
+Object.defineProperty(exports, "defuseMaskTriggers", { enumerable: true, get: function () { return failure_summary_1.defuseMaskTriggers; } });
+Object.defineProperty(exports, "generateFailureComment", { enumerable: true, get: function () { return failure_summary_1.generateComment; } });
+Object.defineProperty(exports, "generateFailureSummary", { enumerable: true, get: function () { return failure_summary_1.generateSummary; } });
+Object.defineProperty(exports, "runFailureSummary", { enumerable: true, get: function () { return failure_summary_1.main; } });
+Object.defineProperty(exports, "parseFailures", { enumerable: true, get: function () { return failure_summary_1.parseFailures; } });
+Object.defineProperty(exports, "resolveImagePaths", { enumerable: true, get: function () { return failure_summary_1.resolveImagePaths; } });
+Object.defineProperty(exports, "uploaderFromEnvironment", { enumerable: true, get: function () { return failure_summary_1.uploaderFromEnvironment; } });
+Object.defineProperty(exports, "uploadImages", { enumerable: true, get: function () { return failure_summary_1.uploadImages; } });
+__exportStar(require("./report-paths"), exports);

package/lib/github/report-paths.d.ts

@@ -0,0 +1,38 @@
+export interface PathPrefix {
+    /** Absolute path as recorded in the report — typically a container path. */
+    from: string;
+    /** The same directory as seen from here. */
+    to: string;
+}
+export interface PathResolution {
+    /** The path to read. Unchanged when the recorded one was already fine. */
+    path: string;
+    /** Whether a readable file was found. */
+    found: boolean;
+    /** The mapping that made it readable, when one was needed. */
+    prefix?: PathPrefix;
+}
+export interface PathResolverOptions {
+    /** Where the JSON report was read from, on this side of the boundary. */
+    reportPath: string;
+    /** Explicit mappings. Tried before anything is worked out. */
+    prefixes?: PathPrefix[];
+    /** Existence check, injectable for tests. */
+    exists?: (filePath: string) => boolean;
+}
+/**
+ * Parse a `FROM:TO` pair, as `--path-prefix` takes it.
+ *
+ * Split on the first colon: `TO` is a local absolute path and may itself
+ * contain one on Windows, whereas `FROM` comes from a container and will not.
+ */
+export declare function parsePathPrefix(value: string): PathPrefix | null;
+/**
+ * Build the function that turns a recorded path into a readable one.
+ *
+ * A path that already resolves is left alone, so this costs one `stat` per
+ * attachment when the report and the files are on the same side. A mapping
+ * worked out for one attachment is kept and tried first for the rest, so the
+ * search runs once per run rather than once per image.
+ */
+export declare function createPathResolver(options: PathResolverOptions): (filePath: string) => PathResolution;