@sdods/integrations 0.2.0

package/dist/jira.js

@@ -0,0 +1,420 @@
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+import { gherkinBlock, selectIssueScreenshots, truncate } from './context.js';
+import { IssueDedupe, fingerprintMarker, issueTitle } from './dedupe.js';
+export class JiraProvider {
+    name = 'jira';
+    config;
+    authHeader = '';
+    base = '';
+    fetchImpl;
+    constructor(options = {}) {
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    async init(config, secrets) {
+        this.config = config;
+        if (!config.baseUrl)
+            throw new Error('Jira integration needs baseUrl.');
+        if (!config.projectKey)
+            throw new Error('Jira integration needs projectKey.');
+        if (!secrets.token)
+            throw new Error(`Jira integration needs a token in $${config.tokenEnv}.`);
+        this.base = config.baseUrl.replace(/\/+$/, '');
+        if (config.authMode === 'bearer') {
+            this.authHeader = `Bearer ${secrets.token}`;
+        }
+        else {
+            if (!secrets.email)
+                throw new Error(`Jira basic auth needs an email in $${config.emailEnv}.`);
+            this.authHeader = `Basic ${Buffer.from(`${secrets.email}:${secrets.token}`).toString('base64')}`;
+        }
+    }
+    async request(method, path, body, extraHeaders = {}) {
+        const isForm = typeof FormData !== 'undefined' && body instanceof FormData;
+        const res = await this.fetchImpl(`${this.base}${path}`, {
+            method,
+            headers: {
+                Authorization: this.authHeader,
+                Accept: 'application/json',
+                ...(isForm ? {} : body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                ...extraHeaders,
+            },
+            body: isForm ? body : body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Jira ${method} ${path} → ${res.status} ${res.statusText}${text ? `: ${text.slice(0, 300)}` : ''}`);
+        }
+        if (res.status === 204)
+            return undefined;
+        const ct = res.headers.get('content-type') ?? '';
+        return (ct.includes('json') ? await res.json() : await res.text());
+    }
+    async test() {
+        try {
+            const me = await this.request('GET', '/rest/api/3/myself');
+            const project = await this.request('GET', `/rest/api/3/project/${this.config.projectKey}`);
+            return {
+                ok: true,
+                detail: `authenticated as ${me.displayName ?? me.emailAddress ?? 'user'}; project ${project.key} (${project.name}) reachable`,
+            };
+        }
+        catch (e) {
+            return { ok: false, detail: e.message };
+        }
+    }
+    async onRunFinished(summary, ctx) {
+        const actions = [];
+        const { run } = summary;
+        const dedupe = new IssueDedupe(ctx.store);
+        for (const scenario of this.failuresToReport(summary)) {
+            let decision = await dedupe.decide(run.projectSlug, this.name, scenario.fingerprint);
+            if (decision.action === 'create' && !ctx.dryRun) {
+                // JQL fallback: an issue may exist that the local store does not know about.
+                const found = await this.findByFingerprint(scenario.fingerprint).catch(() => null);
+                if (found) {
+                    const link = await ctx.store.save({
+                        projectSlug: run.projectSlug,
+                        provider: this.name,
+                        fingerprint: scenario.fingerprint,
+                        scenarioName: scenario.scenarioName,
+                        externalKey: found.key,
+                        externalUrl: found.url,
+                        status: found.status,
+                        source: 'auto',
+                        lastRunId: run.id,
+                    });
+                    decision = { action: 'comment', link, reason: `found ${found.key} via JQL` };
+                }
+            }
+            if (decision.action === 'create') {
+                if (ctx.dryRun) {
+                    actions.push({
+                        provider: this.name,
+                        kind: 'issue-created',
+                        fingerprint: scenario.fingerprint,
+                        detail: `[dry-run] would create "${issueTitle(scenario.featureName, scenario.scenarioName, scenario.browser)}"`,
+                    });
+                    continue;
+                }
+                const ref = await this.createIssue({
+                    projectSlug: run.projectSlug,
+                    run,
+                    scenario,
+                    screenshots: selectIssueScreenshots(scenario),
+                    reportUrl: summary.reportUrl,
+                }, ctx);
+                actions.push({
+                    provider: this.name,
+                    kind: 'issue-created',
+                    target: ref.key,
+                    url: ref.url,
+                    fingerprint: scenario.fingerprint,
+                });
+            }
+            else if (decision.action === 'comment' && decision.link) {
+                const link = decision.link;
+                if (ctx.dryRun) {
+                    actions.push({
+                        provider: this.name,
+                        kind: 'issue-commented',
+                        target: link.externalKey,
+                        fingerprint: scenario.fingerprint,
+                        detail: '[dry-run] would comment "failed again"',
+                    });
+                    continue;
+                }
+                await this.comment(link.externalKey, [
+                    paragraph(`Failed again in run ${run.id}${ctx.ci.runUrl ? ` (${ctx.ci.runUrl})` : ''}.`),
+                    codeBlock(truncate(scenario.errorMessage ?? '', 1500) || 'no error message'),
+                ]);
+                await ctx.store.save({ ...link, lastRunId: run.id });
+                actions.push({
+                    provider: this.name,
+                    kind: 'issue-commented',
+                    target: link.externalKey,
+                    url: link.externalUrl,
+                    fingerprint: scenario.fingerprint,
+                });
+            }
+            else {
+                actions.push({
+                    provider: this.name,
+                    kind: 'skipped',
+                    fingerprint: scenario.fingerprint,
+                    detail: decision.reason,
+                });
+            }
+        }
+        if (this.config.linkTaggedScenarios) {
+            for (const scenario of summary.scenarios) {
+                for (const key of scenario.jiraKeys) {
+                    const existing = await ctx.store.findByKey(run.projectSlug, this.name, key);
+                    if (existing)
+                        continue;
+                    if (ctx.dryRun) {
+                        actions.push({
+                            provider: this.name,
+                            kind: 'skipped',
+                            target: key,
+                            detail: '[dry-run] would link tagged issue',
+                        });
+                        continue;
+                    }
+                    try {
+                        const ref = await this.linkIssue(scenario.fingerprint, key);
+                        await ctx.store.save({
+                            projectSlug: run.projectSlug,
+                            provider: this.name,
+                            fingerprint: scenario.fingerprint,
+                            scenarioName: scenario.scenarioName,
+                            externalKey: ref.key,
+                            externalUrl: ref.url,
+                            status: ref.status,
+                            source: 'tag',
+                            lastRunId: run.id,
+                            lastSyncedAt: new Date().toISOString(),
+                        });
+                    }
+                    catch (e) {
+                        ctx.logger.warn(`Cannot link ${key}: ${e.message}`);
+                    }
+                }
+            }
+        }
+        for (const scenario of summary.passed) {
+            const link = await ctx.store.findOpen(run.projectSlug, this.name, scenario.fingerprint);
+            if (!link)
+                continue;
+            const action = await this.onScenarioPassed(link, run, ctx);
+            if (action)
+                actions.push(action);
+        }
+        return { provider: this.name, actions };
+    }
+    failuresToReport(summary) {
+        const mode = this.config.createIssueOnFailure;
+        if (mode === 'never')
+            return [];
+        const seen = new Set();
+        return summary.failed.filter((s) => {
+            if (seen.has(s.fingerprint))
+                return false;
+            seen.add(s.fingerprint);
+            return mode === 'always' || s.suiteTag === '@smoke';
+        });
+    }
+    async findByFingerprint(fingerprint) {
+        const jql = `project = ${this.config.projectKey} AND labels = sdods AND text ~ "${fingerprintMarker(fingerprint)}" AND statusCategory != Done ORDER BY created DESC`;
+        const data = await this.request('POST', '/rest/api/3/search/jql', { jql, maxResults: 1, fields: ['status'] });
+        const issue = data.issues?.[0];
+        if (!issue)
+            return null;
+        return {
+            provider: this.name,
+            key: issue.key,
+            url: this.browseUrl(issue.key),
+            status: statusFromCategory(issue.fields?.status?.statusCategory?.key),
+        };
+    }
+    async createIssue(input, ctx) {
+        const { scenario, run } = input;
+        const content = [
+            heading(`Scenario`, 3),
+            codeBlock(gherkinBlock(scenario), 'gherkin'),
+            heading('Error', 3),
+            codeBlock(truncate(scenario.errorMessage ?? 'no error message', 3000)),
+            heading('Context', 3),
+            bullets([
+                `Project: ${run.projectSlug} · Environment: ${run.env} · Browser: ${scenario.browser ?? scenario.layer}`,
+                `Run: ${run.id}${run.gitSha ? ` · Commit ${run.gitSha.slice(0, 10)}` : ''}`,
+                ...(input.reportUrl ? [`Report: ${input.reportUrl}`] : []),
+                ...(ctx.ci.runUrl ? [`CI run: ${ctx.ci.runUrl}`] : []),
+            ]),
+            paragraph(fingerprintMarker(scenario.fingerprint)),
+        ];
+        const created = await this.request('POST', '/rest/api/3/issue', {
+            fields: {
+                project: { key: this.config.projectKey },
+                issuetype: { name: this.config.issueType },
+                summary: issueTitle(scenario.featureName, scenario.scenarioName, scenario.browser),
+                labels: this.config.labels,
+                description: { type: 'doc', version: 1, content },
+            },
+        });
+        await this.attachScreenshots(created.key, input, ctx);
+        const ref = {
+            provider: this.name,
+            key: created.key,
+            url: this.browseUrl(created.key),
+            status: 'open',
+        };
+        await ctx.store.save({
+            projectSlug: input.projectSlug,
+            provider: this.name,
+            fingerprint: scenario.fingerprint,
+            scenarioName: scenario.scenarioName,
+            externalKey: ref.key,
+            externalUrl: ref.url,
+            status: 'open',
+            source: 'auto',
+            lastRunId: run.id,
+            lastSyncedAt: new Date().toISOString(),
+        });
+        return ref;
+    }
+    async attachScreenshots(key, input, ctx) {
+        const capBytes = this.config.maxAttachmentMb * 1024 * 1024;
+        let used = 0;
+        const files = [];
+        for (const shot of input.screenshots) {
+            const file = ctx.artifactPath(shot, input.run);
+            if (!file)
+                continue;
+            const size = statSync(file).size;
+            if (used + size > capBytes)
+                break;
+            used += size;
+            files.push({
+                path: file,
+                name: `${shot.phase ?? 'shot'}${shot.stepIndex != null ? `-step${shot.stepIndex}` : ''}-${basename(file)}`,
+            });
+        }
+        if (input.scenario.tracePath) {
+            const file = ctx.artifactPath({ relPath: input.scenario.tracePath }, input.run);
+            if (file && used + statSync(file).size <= capBytes)
+                files.push({ path: file, name: `trace-${basename(file)}` });
+        }
+        if (!files.length)
+            return;
+        const form = new FormData();
+        for (const f of files) {
+            form.append('file', new Blob([readFileSync(f.path)], {
+                type: f.name.endsWith('.zip') ? 'application/zip' : 'image/png',
+            }), f.name);
+        }
+        await this.request('POST', `/rest/api/3/issue/${key}/attachments`, form, {
+            'X-Atlassian-Token': 'no-check',
+        });
+    }
+    async comment(key, content) {
+        await this.request('POST', `/rest/api/3/issue/${key}/comment`, {
+            body: { type: 'doc', version: 1, content },
+        });
+    }
+    async linkIssue(_fingerprint, key) {
+        const data = await this.request('GET', `/rest/api/3/issue/${encodeURIComponent(key)}?fields=status,summary`);
+        return {
+            provider: this.name,
+            key: data.key,
+            url: this.browseUrl(data.key),
+            status: statusFromCategory(data.fields?.status?.statusCategory?.key),
+        };
+    }
+    async syncStatuses(links) {
+        const out = [];
+        for (let i = 0; i < links.length; i += 50) {
+            const batch = links.slice(i, i + 50);
+            try {
+                const data = await this.request('POST', '/rest/api/3/search/jql', {
+                    jql: `key in (${batch.map((l) => l.externalKey).join(',')})`,
+                    maxResults: batch.length,
+                    fields: ['status'],
+                });
+                const byKey = new Map((data.issues ?? []).map((i) => [i.key, i]));
+                for (const l of batch) {
+                    const issue = byKey.get(l.externalKey);
+                    out.push({
+                        provider: this.name,
+                        key: l.externalKey,
+                        url: l.externalUrl,
+                        status: issue
+                            ? statusFromCategory(issue.fields?.status?.statusCategory?.key)
+                            : 'unknown',
+                    });
+                }
+            }
+            catch {
+                for (const l of batch)
+                    out.push({
+                        provider: this.name,
+                        key: l.externalKey,
+                        url: l.externalUrl,
+                        status: 'unknown',
+                    });
+            }
+        }
+        return out;
+    }
+    async onScenarioPassed(link, run, ctx) {
+        if (ctx.dryRun)
+            return {
+                provider: this.name,
+                kind: this.config.transitionOnPass ? 'transition' : 'issue-commented',
+                target: link.externalKey,
+                detail: '[dry-run]',
+            };
+        await this.comment(link.externalKey, [
+            paragraph(`Passing again in run ${run.id}${ctx.ci.runUrl ? ` (${ctx.ci.runUrl})` : ''}.`),
+        ]);
+        if (this.config.transitionOnPass) {
+            const data = await this.request('GET', `/rest/api/3/issue/${link.externalKey}/transitions`);
+            const target = data.transitions?.find((t) => t.name.toLowerCase() === this.config.transitionOnPass.toLowerCase());
+            if (target) {
+                await this.request('POST', `/rest/api/3/issue/${link.externalKey}/transitions`, {
+                    transition: { id: target.id },
+                });
+                await ctx.store.save({
+                    ...link,
+                    status: 'closed',
+                    closedAt: new Date().toISOString(),
+                    lastRunId: run.id,
+                });
+                return {
+                    provider: this.name,
+                    kind: 'transition',
+                    target: link.externalKey,
+                    url: link.externalUrl,
+                    detail: `→ ${target.name}`,
+                };
+            }
+            ctx.logger.warn(`Transition "${this.config.transitionOnPass}" not available on ${link.externalKey}`);
+        }
+        await ctx.store.save({ ...link, lastRunId: run.id });
+        return {
+            provider: this.name,
+            kind: 'issue-commented',
+            target: link.externalKey,
+            url: link.externalUrl,
+            detail: 'passing again',
+        };
+    }
+    browseUrl(key) {
+        return `${this.base}/browse/${key}`;
+    }
+}
+function statusFromCategory(key) {
+    if (!key)
+        return 'unknown';
+    return key === 'done' ? 'closed' : 'open';
+}
+function paragraph(text) {
+    return { type: 'paragraph', content: [{ type: 'text', text }] };
+}
+function heading(text, level) {
+    return { type: 'heading', attrs: { level }, content: [{ type: 'text', text }] };
+}
+function codeBlock(text, language) {
+    return {
+        type: 'codeBlock',
+        attrs: language ? { language } : {},
+        content: [{ type: 'text', text: text || ' ' }],
+    };
+}
+function bullets(items) {
+    return {
+        type: 'bulletList',
+        content: items.map((t) => ({ type: 'listItem', content: [paragraph(t)] })),
+    };
+}
+//# sourceMappingURL=jira.js.map

package/dist/registry.d.ts

@@ -0,0 +1,20 @@
+import type { ProjectConfig } from '@sdods/contracts';
+import type { IntegrationProvider, ProviderName } from './types.js';
+export interface ProviderEntry {
+    name: ProviderName;
+    provider: IntegrationProvider;
+    enabled: boolean;
+    /** env var name → present? (values are never exposed) */
+    secrets: Record<string, boolean>;
+    initError?: string;
+}
+export interface GetProvidersOptions {
+    env?: NodeJS.ProcessEnv;
+    only?: ProviderName[];
+    projectRoot?: string;
+    /** initialise providers (needs secrets); false = list only */
+    init?: boolean;
+}
+/** Build providers from a project's `integrations` section. Missing secrets become `initError`, not throws. */
+export declare function getProviders(project: Pick<ProjectConfig, 'integrations'>, opts?: GetProvidersOptions): Promise<ProviderEntry[]>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,90 @@
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { GitHubProvider } from './github.js';
+import { JiraProvider } from './jira.js';
+import { readSecrets, secretPresence } from './secrets.js';
+/** Build providers from a project's `integrations` section. Missing secrets become `initError`, not throws. */
+export async function getProviders(project, opts = {}) {
+    const env = opts.env ?? process.env;
+    const entries = [];
+    const want = (name) => !opts.only || opts.only.includes(name);
+    const gh = project.integrations.github;
+    if (gh && want('github')) {
+        const provider = new GitHubProvider();
+        const entry = {
+            name: 'github',
+            provider,
+            enabled: gh.enabled,
+            secrets: secretPresence({ tokenEnv: gh.tokenEnv }, env),
+        };
+        if (gh.enabled && opts.init !== false) {
+            try {
+                await provider.init(gh, readSecrets({ tokenEnv: gh.tokenEnv }, env));
+            }
+            catch (e) {
+                entry.initError = e.message;
+            }
+        }
+        entries.push(entry);
+    }
+    const jira = project.integrations.jira;
+    if (jira && want('jira')) {
+        const provider = new JiraProvider();
+        const entry = {
+            name: 'jira',
+            provider,
+            enabled: jira.enabled,
+            secrets: secretPresence({
+                tokenEnv: jira.tokenEnv,
+                emailEnv: jira.authMode === 'basic' ? jira.emailEnv : undefined,
+            }, env),
+        };
+        if (jira.enabled && opts.init !== false) {
+            try {
+                await provider.init(jira, readSecrets({ tokenEnv: jira.tokenEnv, emailEnv: jira.emailEnv }, env));
+            }
+            catch (e) {
+                entry.initError = e.message;
+            }
+        }
+        entries.push(entry);
+    }
+    for (const custom of project.integrations.custom) {
+        const specifier = custom.module.startsWith('.')
+            ? pathToFileURL(resolve(opts.projectRoot ?? process.cwd(), custom.module)).href
+            : custom.module;
+        try {
+            const mod = (await import(specifier));
+            const provider = mod.createProvider
+                ? mod.createProvider(custom.options)
+                : mod.default
+                    ? new mod.default(custom.options)
+                    : null;
+            if (!provider)
+                throw new Error(`module ${custom.module} exports neither createProvider nor a default class`);
+            if (!want(provider.name))
+                continue;
+            const entry = { name: provider.name, provider, enabled: true, secrets: {} };
+            if (opts.init !== false) {
+                try {
+                    await provider.init(custom.options ?? {}, {});
+                }
+                catch (e) {
+                    entry.initError = e.message;
+                }
+            }
+            entries.push(entry);
+        }
+        catch (e) {
+            entries.push({
+                name: custom.module,
+                provider: null,
+                enabled: true,
+                secrets: {},
+                initError: e.message,
+            });
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=registry.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,13 @@
+import type { CiInfo, IntegrationSecrets } from './types.js';
+/** Read secrets by env var NAME from the given environment; values are never logged. */
+export declare function readSecrets(names: {
+    tokenEnv?: string;
+    emailEnv?: string;
+}, env?: NodeJS.ProcessEnv): IntegrationSecrets;
+export declare function secretPresence(names: {
+    tokenEnv?: string;
+    emailEnv?: 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;
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,50 @@
+/** Read secrets by env var NAME from the given environment; values are never logged. */
+export function readSecrets(names, env = process.env) {
+    return {
+        token: names.tokenEnv ? env[names.tokenEnv] : undefined,
+        email: names.emailEnv ? env[names.emailEnv] : undefined,
+    };
+}
+export function secretPresence(names, env = process.env) {
+    const out = {};
+    if (names.tokenEnv)
+        out[names.tokenEnv] = Boolean(env[names.tokenEnv]);
+    if (names.emailEnv)
+        out[names.emailEnv] = Boolean(env[names.emailEnv]);
+    return out;
+}
+/** Detect CI context (GitHub Actions and GitLab CI; everything else is "other"). */
+export function detectCi(env = process.env) {
+    if (env.GITHUB_ACTIONS === 'true') {
+        const ref = env.GITHUB_REF ?? '';
+        const prMatch = /^refs\/pull\/(\d+)\//.exec(ref);
+        const server = env.GITHUB_SERVER_URL ?? 'https://github.com';
+        const repo = env.GITHUB_REPOSITORY;
+        const runId = env.GITHUB_RUN_ID;
+        return {
+            provider: 'github',
+            isPullRequest: env.GITHUB_EVENT_NAME === 'pull_request' || Boolean(prMatch),
+            prNumber: prMatch ? Number(prMatch[1]) : undefined,
+            sha: env.GITHUB_SHA,
+            branch: env.GITHUB_HEAD_REF || env.GITHUB_REF_NAME,
+            runUrl: repo && runId ? `${server}/${repo}/actions/runs/${runId}` : undefined,
+            artifactUrl: repo && runId ? `${server}/${repo}/actions/runs/${runId}#artifacts` : undefined,
+            eventName: env.GITHUB_EVENT_NAME,
+            repository: repo,
+        };
+    }
+    if (env.GITLAB_CI === 'true') {
+        return {
+            provider: 'gitlab',
+            isPullRequest: Boolean(env.CI_MERGE_REQUEST_IID),
+            prNumber: env.CI_MERGE_REQUEST_IID ? Number(env.CI_MERGE_REQUEST_IID) : undefined,
+            sha: env.CI_COMMIT_SHA,
+            branch: env.CI_COMMIT_REF_NAME,
+            runUrl: env.CI_JOB_URL,
+            artifactUrl: env.CI_JOB_URL ? `${env.CI_JOB_URL}/artifacts/browse` : undefined,
+            repository: env.CI_PROJECT_PATH,
+        };
+    }
+    return { provider: env.CI ? 'other' : undefined, isPullRequest: false };
+}
+//# sourceMappingURL=secrets.js.map

package/dist/store.d.ts

@@ -0,0 +1,18 @@
+import type { IssueLink, IssueLinkStore, ProviderName } from './types.js';
+/**
+ * JSON-file store so the CLI works without a database (`.sdods/issue-links.json`).
+ * Pass `null` as the file for an in-memory store (tests). Not safe for concurrent writers across machines.
+ */
+export declare class FileIssueLinkStore implements IssueLinkStore {
+    private readonly file;
+    private links;
+    constructor(file: string | null);
+    private load;
+    private persist;
+    findOpen(projectSlug: string, provider: ProviderName, fingerprint: string): Promise<IssueLink | undefined>;
+    findByKey(projectSlug: string, provider: ProviderName, externalKey: string): Promise<IssueLink | undefined>;
+    save(input: Parameters<IssueLinkStore['save']>[0]): Promise<IssueLink>;
+    list(projectSlug: string, provider?: ProviderName): Promise<IssueLink[]>;
+}
+export declare function createMemoryStore(): IssueLinkStore;
+//# sourceMappingURL=store.d.ts.map