@sdods/integrations 0.2.0

package/dist/store.js

@@ -0,0 +1,75 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { newId } from '@sdods/contracts';
+/**
+ * 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 class FileIssueLinkStore {
+    file;
+    links = null;
+    constructor(file) {
+        this.file = file;
+    }
+    load() {
+        if (this.links)
+            return this.links;
+        if (!this.file || !existsSync(this.file)) {
+            this.links = [];
+            return this.links;
+        }
+        try {
+            const parsed = JSON.parse(readFileSync(this.file, 'utf8'));
+            this.links = Array.isArray(parsed.links) ? parsed.links : [];
+        }
+        catch {
+            this.links = [];
+        }
+        return this.links;
+    }
+    persist() {
+        if (!this.file)
+            return;
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileSync(this.file, JSON.stringify({ version: 1, links: this.load() }, null, 2));
+    }
+    async findOpen(projectSlug, provider, fingerprint) {
+        return this.load().find((l) => l.projectSlug === projectSlug &&
+            l.provider === provider &&
+            l.fingerprint === fingerprint &&
+            l.status !== 'closed');
+    }
+    async findByKey(projectSlug, provider, externalKey) {
+        return this.load().find((l) => l.projectSlug === projectSlug && l.provider === provider && l.externalKey === externalKey);
+    }
+    async save(input) {
+        const links = this.load();
+        const now = new Date().toISOString();
+        const existing = links.find((l) => (input.id !== undefined && l.id === input.id) ||
+            (l.projectSlug === input.projectSlug &&
+                l.provider === input.provider &&
+                l.fingerprint === input.fingerprint &&
+                l.externalKey === input.externalKey));
+        if (existing) {
+            Object.assign(existing, input, { updatedAt: now });
+            this.persist();
+            return existing;
+        }
+        const link = {
+            ...input,
+            id: input.id ?? newId(),
+            createdAt: input.createdAt ?? now,
+            updatedAt: now,
+        };
+        links.push(link);
+        this.persist();
+        return link;
+    }
+    async list(projectSlug, provider) {
+        return this.load().filter((l) => l.projectSlug === projectSlug && (provider ? l.provider === provider : true));
+    }
+}
+export function createMemoryStore() {
+    return new FileIssueLinkStore(null);
+}
+//# sourceMappingURL=store.js.map

package/dist/summary.d.ts

@@ -0,0 +1,15 @@
+import type { RunSummaryInput, ScenarioSummary } from './types.js';
+/**
+ * Build a RunSummaryInput from the files in a run directory (`.sdods/runs/<runId>`), so
+ * `sdods integrations notify --from-files` works without a database.
+ * Reads run.json (manifest), summary.json (optional totals) and messages*.ndjson (cucumber messages).
+ */
+export declare function buildRunSummaryFromFiles(runDir: string, opts?: {
+    projectSlug?: string;
+    reportUrl?: string;
+}): RunSummaryInput;
+export declare function parseMessages(text: string, opts: {
+    runDir?: string;
+    projectSlug: string;
+}): ScenarioSummary[];
+//# sourceMappingURL=summary.d.ts.map

package/dist/summary.js

@@ -0,0 +1,349 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { fingerprint as makeFingerprint, parseAttachmentName, parseRunnerProjectName, runFiles, scenarioFiles, } from '@sdods/contracts';
+/**
+ * Build a RunSummaryInput from the files in a run directory (`.sdods/runs/<runId>`), so
+ * `sdods integrations notify --from-files` works without a database.
+ * Reads run.json (manifest), summary.json (optional totals) and messages*.ndjson (cucumber messages).
+ */
+export function buildRunSummaryFromFiles(runDir, opts = {}) {
+    const manifest = readJson(join(runDir, runFiles.manifest));
+    const runId = manifest?.runId ?? basename(runDir);
+    const projectSlug = opts.projectSlug ?? manifest?.projectSlug ?? 'unknown';
+    const ndjsonFiles = listNdjson(runDir);
+    const scenarios = ndjsonFiles.flatMap((f) => parseMessages(readFileSync(f, 'utf8'), { runDir, projectSlug }));
+    const totals = computeTotals(scenarios, manifest);
+    const run = {
+        id: runId,
+        projectSlug,
+        env: manifest?.env ?? 'unknown',
+        trigger: manifest?.trigger ?? 'cli',
+        status: totals.failed > 0 ? 'failed' : manifest?.exitCode === 130 ? 'cancelled' : 'passed',
+        suiteTag: manifest?.suiteTag,
+        tagsExpr: manifest?.tagsExpr,
+        layers: manifest?.layers ?? [],
+        browsers: manifest?.browsers ?? [],
+        gitSha: manifest?.git?.sha,
+        gitBranch: manifest?.git?.branch,
+        ciProvider: manifest?.ci?.provider,
+        ciRunId: manifest?.ci?.runId,
+        ciUrl: manifest?.ci?.url,
+        startedAt: manifest?.startedAt,
+        finishedAt: manifest?.finishedAt,
+        durationMs: totals.durationMs,
+        totals,
+        artifactsDir: runDir,
+        exitCode: manifest?.exitCode,
+    };
+    const failed = scenarios.filter((s) => s.status === 'failed' || s.status === 'timedOut');
+    const flaky = scenarios.filter((s) => s.flaky);
+    const passed = scenarios.filter((s) => s.status === 'passed');
+    return { run, totals, scenarios, failed, flaky, passed, runDir, reportUrl: opts.reportUrl };
+}
+function listNdjson(runDir) {
+    const out = [];
+    const main = join(runDir, runFiles.messages);
+    if (existsSync(main))
+        out.push(main);
+    for (let i = 1; i <= 64; i++) {
+        const f = join(runDir, runFiles.messagesShard(i));
+        if (existsSync(f))
+            out.push(f);
+    }
+    return out;
+}
+function readJson(file) {
+    if (!existsSync(file))
+        return undefined;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function computeTotals(scenarios, manifest) {
+    const totals = {
+        total: scenarios.length,
+        passed: 0,
+        failed: 0,
+        skipped: 0,
+        timedOut: 0,
+        flaky: 0,
+        healed: 0,
+        durationMs: 0,
+    };
+    for (const s of scenarios) {
+        if (s.status === 'passed')
+            totals.passed++;
+        else if (s.status === 'failed')
+            totals.failed++;
+        else if (s.status === 'timedOut')
+            totals.timedOut++;
+        else if (s.status === 'skipped')
+            totals.skipped++;
+        if (s.flaky)
+            totals.flaky++;
+    }
+    if (manifest?.startedAt && manifest.finishedAt) {
+        totals.durationMs = Math.max(0, Date.parse(manifest.finishedAt) - Date.parse(manifest.startedAt));
+    }
+    else {
+        totals.durationMs = scenarios.reduce((acc, s) => acc + (s.durationMs ?? 0), 0);
+    }
+    return totals;
+}
+export function parseMessages(text, opts) {
+    const docs = new Map();
+    const pickles = new Map();
+    const testCases = new Map();
+    const attempts = new Map();
+    const scenarios = new Map();
+    const stepStarts = new Map();
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let env;
+        try {
+            env = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (env.gherkinDocument?.uri) {
+            const lines = new Map();
+            const examplesIndex = new Map();
+            const walk = (children) => {
+                for (const c of children ?? []) {
+                    const node = c.scenario ?? c.background;
+                    if (node?.id)
+                        lines.set(node.id, node.location?.line ?? 0);
+                    if (c.scenario?.examples) {
+                        let idx = 0;
+                        for (const ex of c.scenario.examples)
+                            for (const row of ex.tableBody ?? [])
+                                examplesIndex.set(row.id, idx++);
+                    }
+                    if (c.rule)
+                        walk(c.rule.children);
+                }
+            };
+            walk(env.gherkinDocument.feature?.children);
+            docs.set(splitUri(env.gherkinDocument.uri).uri, {
+                name: env.gherkinDocument.feature?.name ?? '',
+                lines,
+                examplesIndex,
+            });
+        }
+        else if (env.pickle) {
+            pickles.set(env.pickle.id, env.pickle);
+        }
+        else if (env.testCase) {
+            testCases.set(env.testCase.id, env.testCase);
+        }
+        else if (env.testCaseStarted) {
+            const tc = testCases.get(env.testCaseStarted.testCaseId);
+            const pickle = tc && pickles.get(tc.pickleId);
+            if (!tc || !pickle)
+                continue;
+            const { runnerProject, uri } = splitUri(pickle.uri);
+            const key = `${runnerProject}:${pickle.id}`;
+            const state = {
+                scenarioKey: key,
+                attempt: env.testCaseStarted.attempt ?? 0,
+                steps: [],
+                status: 'passed',
+                startedAt: tsMs(env.testCaseStarted.timestamp),
+                screenshots: [],
+            };
+            attempts.set(env.testCaseStarted.id, state);
+            const entry = scenarios.get(key) ?? {
+                pickle: { ...pickle, uri },
+                runnerProject,
+                attempts: [],
+            };
+            entry.attempts.push(state);
+            scenarios.set(key, entry);
+        }
+        else if (env.testStepStarted) {
+            stepStarts.set(`${env.testStepStarted.testCaseStartedId}:${env.testStepStarted.testStepId}`, tsMs(env.testStepStarted.timestamp) ?? 0);
+        }
+        else if (env.testStepFinished) {
+            const state = attempts.get(env.testStepFinished.testCaseStartedId);
+            if (!state)
+                continue;
+            const entry = scenarios.get(state.scenarioKey);
+            const tc = entry && [...testCases.values()].find((t) => t.pickleId === entry.pickle.id);
+            const ts = tc?.testSteps?.find((s) => s.id === env.testStepFinished.testStepId);
+            const result = env.testStepFinished.testStepResult ?? {};
+            const status = mapStatus(result.status);
+            if (ts?.pickleStepId) {
+                const idx = entry.pickle.steps?.findIndex((s) => s.id === ts.pickleStepId) ?? -1;
+                const pstep = entry.pickle.steps?.[idx];
+                state.steps.push({
+                    index: idx,
+                    keyword: keywordFromType(pstep?.type),
+                    text: pstep?.text ?? '',
+                    status,
+                    errorMessage: result.exception?.message ?? result.message,
+                    durationMs: durMs(result.duration),
+                });
+            }
+            if ((status === 'failed' || status === 'timedOut') && state.status === 'passed') {
+                state.status = status;
+                state.error = result.exception?.message ?? result.message;
+                state.stack = result.exception?.stackTrace;
+            }
+            else if (status === 'skipped' && state.status === 'passed' && ts?.pickleStepId) {
+                state.status = 'skipped';
+            }
+        }
+        else if (env.attachment?.testCaseStartedId) {
+            const state = attempts.get(env.attachment.testCaseStartedId);
+            if (!state || !env.attachment.fileName)
+                continue;
+            const parsed = parseAttachmentName(env.attachment.fileName);
+            const entry = scenarios.get(state.scenarioKey);
+            const rel = (p) => relPathFor(opts.projectSlug, entry, state, p);
+            if (parsed.kind === 'shot-scenario')
+                state.screenshots.push({
+                    relPath: rel(scenarioFiles.scenarioShot(parsed.phase)),
+                    phase: parsed.phase === 'start'
+                        ? 'scenario-start'
+                        : parsed.phase === 'end'
+                            ? 'scenario-end'
+                            : 'failure',
+                });
+            else if (parsed.kind === 'shot-step')
+                state.screenshots.push({
+                    relPath: rel(scenarioFiles.stepShot(parsed.stepIndex, parsed.phase)),
+                    phase: parsed.phase,
+                    stepIndex: parsed.stepIndex,
+                });
+            else if (parsed.kind === 'visual-baseline')
+                state.screenshots.push({
+                    relPath: env.attachment.url ?? `${parsed.name}-${parsed.phase}.png`,
+                    phase: parsed.phase,
+                    name: parsed.name,
+                });
+            else if (parsed.kind === 'runner-builtin' && parsed.name === 'screenshot')
+                state.screenshots.push({
+                    relPath: env.attachment.url ?? 'screenshot.png',
+                    phase: 'failure',
+                });
+            else if (parsed.kind === 'runner-builtin' && parsed.name === 'trace')
+                state.tracePath = env.attachment.url ?? 'trace.zip';
+        }
+        else if (env.testCaseFinished) {
+            const state = attempts.get(env.testCaseFinished.testCaseStartedId);
+            if (!state)
+                continue;
+            state.finishedAt = tsMs(env.testCaseFinished.timestamp);
+            state.willBeRetried = env.testCaseFinished.willBeRetried;
+        }
+    }
+    const out = [];
+    for (const { pickle, runnerProject, attempts: atts } of scenarios.values()) {
+        const sorted = atts.sort((a, b) => a.attempt - b.attempt);
+        const final = sorted[sorted.length - 1];
+        const doc = docs.get(pickle.uri);
+        const parts = parseRunnerProjectName(runnerProject);
+        const layer = parts?.layer ?? 'ui';
+        const scenarioAst = pickle.astNodeIds?.[0];
+        const exampleRow = pickle.astNodeIds?.[1];
+        const exampleIndex = exampleRow && doc ? (doc.examplesIndex.get(exampleRow) ?? null) : null;
+        const tags = (pickle.tags ?? []).map((t) => t.name);
+        const fp = makeFingerprint({
+            project: opts.projectSlug,
+            featureUri: pickle.uri,
+            scenarioName: pickle.name,
+            exampleIndex,
+            layer,
+        });
+        out.push({
+            fingerprint: fp,
+            featureUri: pickle.uri,
+            featureName: doc?.name ?? pickle.uri,
+            scenarioName: pickle.name,
+            line: scenarioAst && doc ? doc.lines.get(scenarioAst) : undefined,
+            exampleIndex,
+            runnerProject,
+            layer,
+            browser: parts?.browser,
+            suiteTag: tags.find((t) => ['@smoke', '@regression', '@sanity'].includes(t)),
+            tags,
+            status: final.status,
+            flaky: sorted.length > 1 && final.status === 'passed',
+            attemptsCount: sorted.length,
+            durationMs: final.startedAt !== undefined && final.finishedAt !== undefined
+                ? final.finishedAt - final.startedAt
+                : undefined,
+            errorMessage: final.error,
+            errorStack: final.stack,
+            steps: final.steps,
+            screenshots: final.screenshots,
+            jiraKeys: tags
+                .filter((t) => /^@jira:[A-Z][A-Z0-9]+-\d+$/i.test(t))
+                .map((t) => t.slice('@jira:'.length).toUpperCase()),
+            githubIssues: tags
+                .filter((t) => /^@github:\d+$/.test(t))
+                .map((t) => t.slice('@github:'.length)),
+            tracePath: final.tracePath,
+        });
+    }
+    return out;
+}
+function relPathFor(projectSlug, entry, state, file) {
+    const parts = parseRunnerProjectName(entry.runnerProject);
+    const fp = makeFingerprint({
+        project: projectSlug,
+        featureUri: entry.pickle.uri,
+        scenarioName: entry.pickle.name,
+        exampleIndex: null,
+        layer: parts?.layer ?? 'ui',
+    });
+    return `${projectSlug}/${fp}/r${state.attempt}/${file}`;
+}
+function splitUri(uri) {
+    const m = /^\[([^\]]+)\]:(.*)$/.exec(uri);
+    return m ? { runnerProject: m[1], uri: m[2] } : { runnerProject: 'unknown', uri };
+}
+function mapStatus(s) {
+    switch ((s ?? '').toUpperCase()) {
+        case 'PASSED':
+            return 'passed';
+        case 'FAILED':
+            return 'failed';
+        case 'SKIPPED':
+        case 'PENDING':
+        case 'UNDEFINED':
+        case 'AMBIGUOUS':
+            return 'skipped';
+        default:
+            return 'unknown';
+    }
+}
+function keywordFromType(type) {
+    switch (type) {
+        case 'Context':
+            return 'Given';
+        case 'Action':
+            return 'When';
+        case 'Outcome':
+            return 'Then';
+        default:
+            return undefined;
+    }
+}
+function tsMs(ts) {
+    if (!ts)
+        return undefined;
+    return (ts.seconds ?? 0) * 1000 + Math.floor((ts.nanos ?? 0) / 1e6);
+}
+function durMs(d) {
+    if (!d)
+        return undefined;
+    return (d.seconds ?? 0) * 1000 + Math.floor((d.nanos ?? 0) / 1e6);
+}
+//# sourceMappingURL=summary.js.map

package/dist/types.d.ts

@@ -0,0 +1,154 @@
+import type { GitHubIntegrationConfig, JiraIntegrationConfig, RunRecord, RunTotals, SuiteStatus } from '@sdods/contracts';
+export type ProviderName = 'github' | 'jira' | (string & {});
+export interface IssueRef {
+    provider: ProviderName;
+    key: string;
+    url: string;
+    status: 'open' | 'closed' | 'unknown';
+}
+export interface IssueLink {
+    id: string;
+    projectSlug: string;
+    provider: ProviderName;
+    fingerprint: string;
+    scenarioName: string;
+    externalKey: string;
+    externalUrl: string;
+    status: 'open' | 'closed' | 'unknown';
+    source: 'auto' | 'tag' | 'manual';
+    lastRunId?: string;
+    lastSyncedAt?: string;
+    closedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Narrow persistence contract; the CLI uses a JSON file, the server can plug the DB. */
+export interface IssueLinkStore {
+    findOpen(projectSlug: string, provider: ProviderName, fingerprint: string): Promise<IssueLink | undefined>;
+    findByKey(projectSlug: string, provider: ProviderName, externalKey: string): Promise<IssueLink | undefined>;
+    save(link: Omit<IssueLink, 'id' | 'createdAt' | 'updatedAt'> & Partial<Pick<IssueLink, 'id' | 'createdAt'>>): Promise<IssueLink>;
+    list(projectSlug: string, provider?: ProviderName): Promise<IssueLink[]>;
+}
+export interface StepSummary {
+    index: number;
+    keyword?: string;
+    text: string;
+    status: SuiteStatus;
+    errorMessage?: string;
+    durationMs?: number;
+}
+export interface ScreenshotRef {
+    /** path relative to the run directory */
+    relPath: string;
+    absPath?: string;
+    phase?: string;
+    stepIndex?: number | null;
+    name?: string;
+}
+export interface ScenarioSummary {
+    fingerprint: string;
+    featureUri: string;
+    featureName: string;
+    scenarioName: string;
+    line?: number;
+    exampleIndex?: number | null;
+    runnerProject: string;
+    layer: string;
+    browser?: string;
+    suiteTag?: string;
+    tags: string[];
+    status: SuiteStatus;
+    flaky: boolean;
+    attemptsCount: number;
+    durationMs?: number;
+    errorMessage?: string;
+    errorStack?: string;
+    steps: StepSummary[];
+    screenshots: ScreenshotRef[];
+    jiraKeys: string[];
+    githubIssues: string[];
+    tracePath?: string;
+}
+export interface RunSummaryInput {
+    run: RunRecord;
+    totals: RunTotals;
+    scenarios: ScenarioSummary[];
+    failed: ScenarioSummary[];
+    flaky: ScenarioSummary[];
+    passed: ScenarioSummary[];
+    runDir?: string;
+    reportUrl?: string;
+}
+export interface CiInfo {
+    provider?: 'github' | 'gitlab' | 'other';
+    isPullRequest: boolean;
+    prNumber?: number;
+    sha?: string;
+    branch?: string;
+    runUrl?: string;
+    artifactUrl?: string;
+    eventName?: string;
+    repository?: string;
+}
+export interface IntegrationLogger {
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+}
+export interface IntegrationContext {
+    store: IssueLinkStore;
+    logger: IntegrationLogger;
+    publicUrl?: string;
+    ci: CiInfo;
+    dryRun?: boolean;
+    /** Resolve a screenshot to a URL viewers can open (public server first, then CI artifact page). */
+    artifactUrl(artifact: ScreenshotRef, run: RunRecord): string | null;
+    /** Resolve a screenshot to a local file for upload. */
+    artifactPath(artifact: ScreenshotRef, run: RunRecord): string | null;
+}
+export interface CreateIssueInput {
+    projectSlug: string;
+    run: RunRecord;
+    scenario: ScenarioSummary;
+    screenshots: ScreenshotRef[];
+    diffUrl?: string;
+    reportUrl?: string;
+}
+export interface NotifyAction {
+    provider: ProviderName;
+    kind: 'check-run' | 'pr-comment' | 'issue-created' | 'issue-commented' | 'issue-closed' | 'transition' | 'skipped';
+    target?: string;
+    url?: string;
+    detail?: string;
+    fingerprint?: string;
+}
+export interface NotifyResult {
+    provider: ProviderName;
+    actions: NotifyAction[];
+}
+export interface ProviderTestResult {
+    ok: boolean;
+    detail: string;
+}
+export interface IntegrationSecrets {
+    token?: string;
+    email?: string;
+}
+export interface IntegrationProvider<C = unknown> {
+    readonly name: ProviderName;
+    init(config: C, secrets: IntegrationSecrets): Promise<void>;
+    test(): Promise<ProviderTestResult>;
+    onRunFinished(summary: RunSummaryInput, ctx: IntegrationContext): Promise<NotifyResult>;
+    createIssue(input: CreateIssueInput, ctx: IntegrationContext): Promise<IssueRef>;
+    linkIssue(fingerprint: string, key: string): Promise<IssueRef>;
+    syncStatuses(links: IssueLink[]): Promise<IssueRef[]>;
+    onScenarioPassed?(link: IssueLink, run: RunRecord, ctx: IntegrationContext): Promise<NotifyAction | null>;
+}
+export type GitHubConfig = GitHubIntegrationConfig;
+export type JiraConfig = JiraIntegrationConfig;
+export interface CustomProviderModule {
+    default?: new (options?: Record<string, unknown>) => IntegrationProvider;
+    createProvider?: (options?: Record<string, unknown>) => IntegrationProvider;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@sdods/integrations",
+  "version": "0.2.0",
+  "description": "SDODS integrations: GitHub checks and issues, Jira issues and links.",
+  "license": "Apache-2.0",
+  "author": "SDODS <admin@sdods.com>",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@sdods/contracts": "0.2.0",
+    "@octokit/rest": "^22.0.1",
+    "zod": "^4.5.4"
+  },
+  "homepage": "https://sdods.com",
+  "bugs": {
+    "url": "https://github.com/siri1410/SDODS/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/siri1410/SDODS.git",
+    "directory": "packages/integrations"
+  },
+  "keywords": [
+    "sdods",
+    "automation",
+    "orchestration",
+    "testing",
+    "bdd",
+    "ai-agents",
+    "mcp"
+  ]
+}