@sdods/integrations 0.7.2 → 0.8.0

package/dist/github.d.ts

@@ -1,10 +1,20 @@
 import { Octokit } from '@octokit/rest';
 import type { RunRecord } from '@sdods/contracts';
+import { type PruneResult } from './evidence.js';
+import { type CommandRunner } from './gif.js';
 import type { CreateIssueInput, GitHubConfig, IntegrationContext, IntegrationProvider, IntegrationSecrets, IssueLink, IssueRef, NotifyAction, NotifyResult, ProviderTestOptions, ProviderTestResult, RunSummaryInput } from './types.js';
 export declare const PR_COMMENT_MARKER = "<!-- sdods:run-summary -->";
 export interface GitHubProviderOptions {
     baseUrl?: string;
     octokit?: Octokit;
+    /** Octokit for the evidence repository (default: one built from `evidence.tokenEnv`, else `octokit`) */
+    evidenceOctokit?: Octokit;
+    /** web origin for evidence links (default `GITHUB_SERVER_URL`, then https://github.com) */
+    serverUrl?: string;
+    /** runs ffmpeg for GIF previews; injected by tests */
+    runCommand?: CommandRunner;
+    /** backoff between evidence ref-update attempts; injected by tests */
+    sleep?: (ms: number) => Promise<void>;
 }
 export declare class GitHubProvider implements IntegrationProvider<GitHubConfig> {
     private readonly options;
@@ -13,15 +23,33 @@ export declare class GitHubProvider implements IntegrationProvider<GitHubConfig>
     private octokit;
     private owner;
     private repo;
+    private evidence?;
+    private evidenceError?;
+    private gif?;
     constructor(options?: GitHubProviderOptions);
     init(config: GitHubConfig, secrets: IntegrationSecrets): Promise<void>;
+    /** `integrations.github.evidence.host: branch` — off unless configured. */
+    private initEvidence;
     test(opts?: ProviderTestOptions): Promise<ProviderTestResult>;
+    /**
+     * Rewrite the evidence branch without the runs uploaded more than `olderThan` ago
+     * (default `evidence.retainDays`). Used by `sdods integrations evidence prune`.
+     */
+    pruneEvidence(opts?: {
+        olderThan?: string;
+        dryRun?: boolean;
+    }): Promise<PruneResult>;
     /**
      * Issues are created with `labels`; a label the repository lacks is a configuration error that
      * nothing reported. Missing labels fail the test, and `createMissingLabels` creates them.
      */
     private checkLabels;
     onRunFinished(summary: RunSummaryInput, ctx: IntegrationContext): Promise<NotifyResult>;
+    /**
+     * Commit the screenshots, video and GIF preview of the scenarios about to get an issue to the
+     * evidence branch. Any failure is a warning: the issues then use the links they had before.
+     */
+    private publishEvidence;
     /**
      * Search the repository for an open issue whose body carries this scenario's fingerprint marker
      * and record it as the scenario's link. A failed search falls back to the local links.

package/dist/github.js

@@ -1,12 +1,17 @@
-import { readFileSync } from 'node:fs';
-import { basename, extname } from 'node:path';
+import { mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, extname, join } from 'node:path';
 import { Octokit } from '@octokit/rest';
 import { TRACE_CREDENTIALS_WARNING, artifactDisplayPath, gherkinBlock, selectIssueScreenshots, truncate, } from './context.js';
 import { IssueDedupe, fingerprintMarker, issueTitle } from './dedupe.js';
+import { GitHubBranchEvidence, evidenceKey, formatBytes, parseAge, scenarioSlug, } from './evidence.js';
+import { GifPreviewer } from './gif.js';
 export const PR_COMMENT_MARKER = '<!-- sdods:run-summary -->';
 const ANNOTATION_BATCH = 50;
 /** colour for labels created by `sdods integrations test --create-labels` */
 const LABEL_COLOR = 'd93f0b';
+/** evidence key of a scenario's GIF preview */
+const PREVIEW_REL = '#preview.gif';
 export class GitHubProvider {
     options;
     name = 'github';
@@ -14,6 +19,9 @@ export class GitHubProvider {
     octokit;
     owner = '';
     repo = '';
+    evidence;
+    evidenceError;
+    gif;
     constructor(options = {}) {
         this.options = options;
     }
@@ -34,17 +42,76 @@ export class GitHubProvider {
                     baseUrl: this.options.baseUrl ?? process.env.GITHUB_API_URL,
                     userAgent: 'sdods',
                 });
+        this.initEvidence(config, secrets);
+    }
+    /** `integrations.github.evidence.host: branch` — off unless configured. */
+    initEvidence(config, secrets) {
+        const ev = config.evidence;
+        if (ev?.host !== 'branch')
+            return;
+        const [owner, repo] = ev.repo ? ev.repo.split('/') : [this.owner, this.repo];
+        let octokit = this.options.evidenceOctokit;
+        if (!octokit && ev.tokenEnv && !this.options.octokit) {
+            if (!secrets.evidenceToken) {
+                // issues are still created, with the links used without an evidence host
+                this.evidenceError = `evidence host needs a token in $${ev.tokenEnv}`;
+                return;
+            }
+            octokit = new Octokit({
+                auth: secrets.evidenceToken,
+                baseUrl: this.options.baseUrl ?? process.env.GITHUB_API_URL,
+                userAgent: 'sdods',
+            });
+        }
+        this.evidence = new GitHubBranchEvidence({
+            octokit: octokit ?? this.octokit,
+            owner: owner,
+            repo: repo,
+            branch: ev.branch,
+            serverUrl: this.options.serverUrl ?? process.env.GITHUB_SERVER_URL,
+            retainDays: ev.retainDays,
+            sleep: this.options.sleep,
+        });
+        if (ev.gifPreview)
+            this.gif = new GifPreviewer(this.options.runCommand);
     }
     async test(opts = {}) {
         let detail;
+        let isPrivate;
         try {
             const { data } = await this.octokit.rest.repos.get({ owner: this.owner, repo: this.repo });
             detail = `repo ${data.full_name} reachable (${data.private ? 'private' : 'public'})`;
+            isPrivate = data.private;
         }
         catch (e) {
             return { ok: false, detail: e.message };
         }
-        return this.checkLabels(detail, opts);
+        const result = await this.checkLabels(detail, opts);
+        if (this.config.evidence?.host !== 'branch')
+            return result;
+        const evidence = this.evidence
+            ? await this.evidence.check(isPrivate)
+            : { ok: false, detail: this.evidenceError ?? 'evidence host not initialised' };
+        return {
+            ...result,
+            ok: result.ok && evidence.ok,
+            detail: `${result.detail}; ${evidence.detail}`,
+            evidence,
+        };
+    }
+    /**
+     * Rewrite the evidence branch without the runs uploaded more than `olderThan` ago
+     * (default `evidence.retainDays`). Used by `sdods integrations evidence prune`.
+     */
+    async pruneEvidence(opts = {}) {
+        if (this.config.evidence?.host !== 'branch')
+            throw new Error('integrations.github.evidence.host is not "branch" for this project.');
+        if (!this.evidence)
+            throw new Error(`GitHub ${this.evidenceError ?? 'evidence host not initialised'}.`);
+        const olderThanMs = opts.olderThan
+            ? parseAge(opts.olderThan)
+            : this.config.evidence.retainDays * 86_400_000;
+        return this.evidence.prune({ olderThanMs, dryRun: opts.dryRun });
     }
     /**
      * Issues are created with `labels`; a label the repository lacks is a configuration error that
@@ -115,8 +182,8 @@ export class GitHubProvider {
         if (this.config.prComment && ctx.ci.isPullRequest && ctx.ci.prNumber) {
             actions.push(await this.upsertPrComment(summary, ctx));
         }
-        const candidates = this.failuresToReport(summary);
-        for (const scenario of candidates) {
+        const decided = [];
+        for (const scenario of this.failuresToReport(summary)) {
             // The local link file does not survive a fresh CI runner, so an open issue carrying the
             // fingerprint marker is looked up in the repository before creating another one.
             const dedupe = new IssueDedupe(ctx.store, {
@@ -124,7 +191,15 @@ export class GitHubProvider {
                     ? undefined
                     : () => this.findOpenIssueByFingerprint(scenario, run, ctx),
             });
-            const decision = await dedupe.decide(run.projectSlug, this.name, scenario.fingerprint);
+            decided.push({
+                scenario,
+                decision: await dedupe.decide(run.projectSlug, this.name, scenario.fingerprint),
+            });
+        }
+        // every new issue's evidence goes up in one commit, before the issues are created
+        const toCreate = decided.filter((d) => d.decision.action === 'create').map((d) => d.scenario);
+        const evidence = ctx.dryRun || !toCreate.length ? undefined : await this.publishEvidence(toCreate, run, ctx);
+        for (const { scenario, decision } of decided) {
             if (decision.action === 'create') {
                 if (ctx.dryRun) {
                     actions.push({
@@ -141,6 +216,7 @@ export class GitHubProvider {
                     scenario,
                     screenshots: selectIssueScreenshots(scenario),
                     reportUrl: summary.reportUrl,
+                    evidence,
                 }, ctx);
                 actions.push({
                     provider: this.name,
@@ -209,6 +285,74 @@ export class GitHubProvider {
         }
         return { provider: this.name, actions };
     }
+    /**
+     * Commit the screenshots, video and GIF preview of the scenarios about to get an issue to the
+     * evidence branch. Any failure is a warning: the issues then use the links they had before.
+     */
+    async publishEvidence(scenarios, run, ctx) {
+        if (this.evidenceError) {
+            ctx.logger.warn(`github: ${this.evidenceError}; issues link evidence without it`);
+            return undefined;
+        }
+        const host = this.evidence;
+        const ev = this.config.evidence;
+        if (!host || !ev)
+            return undefined;
+        host.logger = ctx.logger;
+        const files = [];
+        let tmp;
+        const add = (scenario, key, localPath, kind, taken, wanted = basename(localPath)) => {
+            let name = wanted;
+            for (let i = 2; taken.has(name); i++)
+                name = `${i}-${wanted}`;
+            taken.add(name);
+            files.push({
+                key: evidenceKey(scenario.fingerprint, key),
+                fingerprint: scenario.fingerprint,
+                scenarioDir: scenarioSlug(scenario.scenarioName, scenario.fingerprint),
+                name,
+                localPath,
+                kind,
+                bytes: statSync(localPath).size,
+            });
+        };
+        try {
+            for (const scenario of scenarios) {
+                const taken = new Set();
+                for (const shot of selectIssueScreenshots(scenario)) {
+                    const local = ctx.artifactPath(shot, run);
+                    if (local)
+                        add(scenario, shot.relPath, local, 'screenshot', taken);
+                }
+                // the trace is never offered: it carries credentials (#101)
+                const video = scenario.videoPath
+                    ? ctx.artifactPath({ relPath: scenario.videoPath }, run)
+                    : null;
+                if (!video)
+                    continue;
+                if (this.gif) {
+                    tmp ??= mkdtempSync(join(tmpdir(), 'sdods-gif-'));
+                    const gif = await this.gif.make(video, join(tmp, `${files.length}.gif`), ctx.logger);
+                    if (gif)
+                        add(scenario, PREVIEW_REL, gif, 'preview', taken, 'preview.gif');
+                }
+                add(scenario, scenario.videoPath, video, 'video', taken);
+            }
+            if (!files.length)
+                return undefined;
+            const published = await host.publishRun({ id: run.id, projectSlug: run.projectSlug }, files, ev);
+            ctx.logger.info(`github evidence: ${published.urls.size} file(s) on ${host.fullName}@${host.branch}${published.skipped.length ? `, ${published.skipped.length} skipped by the size caps` : ''}`);
+            return published;
+        }
+        catch (e) {
+            ctx.logger.warn(`github: evidence upload to ${host.fullName}@${host.branch} failed, issues link evidence without it: ${e.message}`);
+            return undefined;
+        }
+        finally {
+            if (tmp)
+                rmSync(tmp, { recursive: true, force: true });
+        }
+    }
     /**
      * Search the repository for an open issue whose body carries this scenario's fingerprint marker
      * and record it as the scenario's link. A failed search falls back to the local links.
@@ -420,15 +564,17 @@ export class GitHubProvider {
         const { scenario, run } = input;
         const title = issueTitle(scenario.featureName, scenario.scenarioName, scenario.browser);
         const shotLines = [];
+        const hosted = (relPath) => input.evidence?.urls.get(evidenceKey(scenario.fingerprint, relPath));
         for (const shot of input.screenshots) {
-            let url = ctx.artifactUrl(shot, run);
-            if (this.config.uploadToRelease) {
+            // precedence: evidence branch, then release asset, then SDODS_PUBLIC_URL, then CI artifacts
+            let url = hosted(shot.relPath) ?? ctx.artifactUrl(shot, run);
+            if (this.config.uploadToRelease && !hosted(shot.relPath)) {
                 const uploaded = await this.uploadReleaseAsset(shot, run, ctx).catch(() => null);
                 if (uploaded)
                     url = uploaded;
             }
             if (url)
-                shotLines.push(`- ${shot.phase ?? 'screenshot'}${shot.stepIndex != null ? ` (step ${shot.stepIndex})` : ''}: ${url.endsWith('.png') ? `![${shot.phase}](${url})` : url}`);
+                shotLines.push(`- ${shot.phase ?? 'screenshot'}${shot.stepIndex != null ? ` (step ${shot.stepIndex})` : ''}: ${/\.png(\?raw=true)?$/.test(url) ? `![${shot.phase}](${url})` : url}`);
         }
         const body = [
             `**Project** \`${run.projectSlug}\` · **Environment** \`${run.env}\` · **Browser** \`${scenario.browser ?? scenario.layer}\` · **Run** \`${run.id}\``,
@@ -447,7 +593,8 @@ export class GitHubProvider {
             '```',
             '',
             ...(shotLines.length ? ['### Screenshots', ...shotLines, ''] : []),
-            ...(await this.mediaLines(scenario, run, ctx)),
+            ...(await this.mediaLines(scenario, run, ctx, input.evidence)),
+            ...skippedEvidenceLines(scenario, input.evidence),
             ...(input.reportUrl || ctx.ci.runUrl
                 ? [
                     '### Links',
@@ -502,13 +649,17 @@ export class GitHubProvider {
      * render masked, but anything the application prints on screen (an OTP, a token in a URL bar
      * shown in a page) is visible in it, so projects with such screens should set `evidence.video: off`.
      */
-    async mediaLines(scenario, run, ctx) {
+    async mediaLines(scenario, run, ctx, evidence) {
         const lines = [];
+        const preview = evidence?.urls.get(evidenceKey(scenario.fingerprint, PREVIEW_REL));
+        if (preview)
+            lines.push(`- Preview (last ${this.gif?.seconds ?? 5} s): ![video preview](${preview})`);
         if (scenario.videoPath) {
             const relPath = scenario.videoPath;
             const local = artifactDisplayPath(relPath, run);
-            let url = ctx.artifactUrl({ relPath }, run);
-            if (this.config.uploadToRelease) {
+            const hostedVideo = evidence?.urls.get(evidenceKey(scenario.fingerprint, relPath));
+            let url = hostedVideo ?? ctx.artifactUrl({ relPath }, run);
+            if (this.config.uploadToRelease && !hostedVideo) {
                 const uploaded = await this.uploadReleaseAsset({ relPath }, run, ctx).catch(() => null);
                 if (uploaded)
                     url = uploaded;
@@ -627,6 +778,17 @@ export class GitHubProvider {
         };
     }
 }
+/** Files the evidence host did not take, so a reader knows why they are only linked. */
+function skippedEvidenceLines(scenario, evidence) {
+    const mine = evidence?.skipped.filter((s) => s.fingerprint === scenario.fingerprint) ?? [];
+    if (!mine.length)
+        return [];
+    return [
+        '### Evidence not uploaded',
+        ...mine.map((s) => `- \`${s.name}\` (${formatBytes(s.bytes)}): ${s.reason}`),
+        '',
+    ];
+}
 export function issueNumber(key) {
     const m = /#?(\d+)$/.exec(key.trim());
     if (!m)

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export * from './dedupe.js';
 export * from './secrets.js';
 export * from './context.js';
 export * from './github.js';
+export * from './evidence.js';
+export * from './gif.js';
 export * from './jira.js';
 export * from './registry.js';
 export * from './summary.js';

package/dist/index.js

@@ -4,6 +4,8 @@ export * from './dedupe.js';
 export * from './secrets.js';
 export * from './context.js';
 export * from './github.js';
+export * from './evidence.js';
+export * from './gif.js';
 export * from './jira.js';
 export * from './registry.js';
 export * from './summary.js';

package/dist/registry.js

@@ -11,15 +11,19 @@ export async function getProviders(project, opts = {}) {
     const gh = project.integrations.github;
     if (gh && want('github')) {
         const provider = new GitHubProvider();
+        const names = {
+            tokenEnv: gh.tokenEnv,
+            evidenceTokenEnv: gh.evidence?.host === 'branch' ? gh.evidence.tokenEnv : undefined,
+        };
         const entry = {
             name: 'github',
             provider,
             enabled: gh.enabled,
-            secrets: secretPresence({ tokenEnv: gh.tokenEnv }, env),
+            secrets: secretPresence(names, env),
         };
         if (gh.enabled && opts.init !== false) {
             try {
-                await provider.init(gh, readSecrets({ tokenEnv: gh.tokenEnv }, env));
+                await provider.init(gh, readSecrets(names, env));
             }
             catch (e) {
                 entry.initError = e.message;

package/dist/secrets.d.ts

@@ -3,10 +3,12 @@ import type { CiInfo, IntegrationSecrets } from './types.js';
 export declare function readSecrets(names: {
     tokenEnv?: string;
     emailEnv?: string;
+    evidenceTokenEnv?: string;
 }, env?: NodeJS.ProcessEnv): IntegrationSecrets;
 export declare function secretPresence(names: {
     tokenEnv?: string;
     emailEnv?: string;
+    evidenceTokenEnv?: string;
 }, env?: NodeJS.ProcessEnv): Record<string, boolean>;
 /** Detect CI context (GitHub Actions and GitLab CI; everything else is "other"). */
 export declare function detectCi(env?: NodeJS.ProcessEnv): CiInfo;

package/dist/secrets.js

@@ -3,6 +3,7 @@ export function readSecrets(names, env = process.env) {
     return {
         token: names.tokenEnv ? env[names.tokenEnv] : undefined,
         email: names.emailEnv ? env[names.emailEnv] : undefined,
+        ...(names.evidenceTokenEnv ? { evidenceToken: env[names.evidenceTokenEnv] } : {}),
     };
 }
 export function secretPresence(names, env = process.env) {
@@ -11,6 +12,8 @@ export function secretPresence(names, env = process.env) {
         out[names.tokenEnv] = Boolean(env[names.tokenEnv]);
     if (names.emailEnv)
         out[names.emailEnv] = Boolean(env[names.emailEnv]);
+    if (names.evidenceTokenEnv)
+        out[names.evidenceTokenEnv] = Boolean(env[names.evidenceTokenEnv]);
     return out;
 }
 /** Detect CI context (GitHub Actions and GitLab CI; everything else is "other"). */

package/dist/types.d.ts

@@ -117,6 +117,33 @@ export interface CreateIssueInput {
     screenshots: ScreenshotRef[];
     diffUrl?: string;
     reportUrl?: string;
+    /** files already committed to the evidence branch for this run (`integrations.github.evidence`) */
+    evidence?: PublishedEvidence;
+}
+/** One local file offered to an evidence host. */
+export interface EvidenceFile {
+    /** lookup key for the issue body: `evidenceKey(fingerprint, relPath)` */
+    key: string;
+    fingerprint: string;
+    /** directory under `runs/<runId>/` */
+    scenarioDir: string;
+    name: string;
+    localPath: string;
+    kind: 'screenshot' | 'preview' | 'video';
+    bytes: number;
+}
+export interface SkippedEvidence {
+    key: string;
+    fingerprint: string;
+    name: string;
+    bytes: number;
+    reason: string;
+}
+export interface PublishedEvidence {
+    /** evidence key → link that renders inline for readers of the evidence repository */
+    urls: Map<string, string>;
+    skipped: SkippedEvidence[];
+    commitSha?: string;
 }
 export interface NotifyAction {
     provider: ProviderName;
@@ -138,6 +165,11 @@ export interface ProviderTestResult {
         missing: string[];
         created: string[];
     };
+    /** the evidence host, when `integrations.github.evidence.host` is `branch` */
+    evidence?: {
+        ok: boolean;
+        detail: string;
+    };
 }
 export interface ProviderTestOptions {
     /** create configured labels the target is missing (GitHub) */
@@ -146,6 +178,8 @@ export interface ProviderTestOptions {
 export interface IntegrationSecrets {
     token?: string;
     email?: string;
+    /** token for `integrations.github.evidence.tokenEnv`, when set */
+    evidenceToken?: string;
 }
 export interface IntegrationProvider<C = unknown> {
     readonly name: ProviderName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/integrations",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "SDODS integrations: GitHub checks and issues, Jira issues and links.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -18,7 +18,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.7.2",
+    "@sdods/contracts": "0.8.0",
     "@octokit/rest": "^22.0.1",
     "zod": "^4.5.4"
   },