wotann 0.5.0

package/dist/ports/scrapling-adaptive.js

@@ -0,0 +1,254 @@
+/**
+ * Scrapling Adaptive Selectors — port of D4Vinci/Scrapling's
+ * "auto-match" selector self-healing pattern.
+ *
+ * WHAT
+ *   The killer feature of Scrapling that's missing from every other
+ *   scraping lib: when a CSS/XPath selector breaks (because the target
+ *   site refactored its DOM), Scrapling stores a STRUCTURAL FINGERPRINT
+ *   of each element (tag + classes + text + parent chain + sibling
+ *   index) at scrape time. Next run, if the original selector returns
+ *   nothing, it walks the new DOM and finds the element whose
+ *   fingerprint best matches the saved one. The scrape keeps working
+ *   even when the page changes.
+ *
+ *   This port is a pure-JS, dependency-free version that operates on
+ *   any DOM shape (cheerio, JSDOM, parse5 — caller passes a tiny
+ *   adapter). The fingerprint algorithm is the same: tag, classes,
+ *   text length bucket, parent-chain hash, sibling-index distance.
+ *
+ * WHY (leverage)
+ *   WOTANN has a /scrape skill (skills/scrape.md) and a markitdown bridge,
+ *   but no SELF-HEALING selector layer. Every WOTANN scraping flow that
+ *   uses CSS selectors breaks the moment a site refactors. This module
+ *   plus a 20-line adapter for whatever DOM library the caller uses
+ *   makes those flows resilient.
+ *
+ * QUALITY BARS
+ *   QB#3  honest stub — every fingerprint match returns a similarity
+ *         score; below threshold returns ok:false with a reason.
+ *   QB#7  zero module-globals. Adapter and store are passed in.
+ *   QB#10 errors surface verbatim.
+ *   QB#13 no env reads.
+ *   Vendor-agnostic — caller plugs in their own DOM library via DomAdapter.
+ *
+ * Future expansion (deferred):
+ *   - Persistent fingerprint store (currently in-memory; trivial to back
+ *     by SQLite via the existing storage/ helpers).
+ *   - Adaptive XPath (current support is CSS-shaped element queries).
+ *   - LLM-assisted re-locate when fingerprint score is below threshold.
+ */
+// In-memory store (default backend, QB#7 per-instance)
+export function createInMemoryFingerprintStore() {
+    const map = new Map();
+    return {
+        save(label, fp) {
+            map.set(label, fp);
+        },
+        load(label) {
+            return map.get(label) ?? null;
+        },
+        list() {
+            return Array.from(map.entries()).map(([label, fingerprint]) => ({
+                label,
+                fingerprint,
+            }));
+        },
+    };
+}
+// Fingerprint construction
+function bucketLength(len) {
+    if (len <= 0)
+        return 0;
+    return 1 << Math.floor(Math.log2(len + 1));
+}
+function rollingHash(items) {
+    // Simple deterministic 32-bit rolling hash. Not crypto — just a fast probe.
+    let h = 5381;
+    for (const it of items) {
+        for (let i = 0; i < it.tag.length; i++) {
+            h = ((h * 33) ^ it.tag.charCodeAt(i)) | 0;
+        }
+        h = (h * 33 + it.siblingIndex) | 0;
+    }
+    return h;
+}
+function buildParentChain(adapter, node, maxDepth = 6) {
+    const chain = [];
+    let current = node;
+    let depth = 0;
+    while (current !== null && depth < maxDepth) {
+        chain.push({
+            tag: adapter.getTag(current),
+            siblingIndex: adapter.getSiblingIndex(current),
+        });
+        current = adapter.getParent(current);
+        depth += 1;
+    }
+    return chain;
+}
+/**
+ * Build a fingerprint from a node. Pure function — no side effects.
+ */
+export function fingerprint(adapter, node, originalSelector) {
+    const tag = adapter.getTag(node);
+    const classes = [...adapter.getClasses(node)].sort();
+    const text = adapter.getText(node);
+    const textLengthBucket = bucketLength(text.length);
+    const parentChain = buildParentChain(adapter, node);
+    const parentChainHash = rollingHash(parentChain);
+    return {
+        originalSelector,
+        tag,
+        classes,
+        textLengthBucket,
+        parentChain,
+        parentChainHash,
+    };
+}
+// Similarity scoring
+function jaccard(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    const sa = new Set(a);
+    const sb = new Set(b);
+    let intersect = 0;
+    for (const x of sa)
+        if (sb.has(x))
+            intersect += 1;
+    const union = sa.size + sb.size - intersect;
+    return union === 0 ? 0 : intersect / union;
+}
+function chainSimilarity(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 1;
+    const minLen = Math.min(a.length, b.length);
+    if (minLen === 0)
+        return 0;
+    let tagMatches = 0;
+    let siblingPenalty = 0;
+    for (let i = 0; i < minLen; i++) {
+        const ai = a[i];
+        const bi = b[i];
+        if (!ai || !bi)
+            continue;
+        if (ai.tag === bi.tag)
+            tagMatches += 1;
+        siblingPenalty += Math.min(1, Math.abs(ai.siblingIndex - bi.siblingIndex) / 5);
+    }
+    const tagScore = tagMatches / minLen;
+    const siblingScore = 1 - siblingPenalty / minLen;
+    return tagScore * 0.7 + siblingScore * 0.3;
+}
+/**
+ * Compute similarity between two fingerprints in [0, 1]. Pure function.
+ */
+export function similarity(a, b) {
+    if (a.tag !== b.tag) {
+        // Different tag is a strong negative signal but not disqualifying
+        // (sites occasionally swap div<->section).
+        return 0.2 * jaccard(a.classes, b.classes);
+    }
+    const classScore = jaccard(a.classes, b.classes);
+    const textScore = a.textLengthBucket === b.textLengthBucket ? 1 : 0.5;
+    const chainScore = chainSimilarity(a.parentChain, b.parentChain);
+    return classScore * 0.4 + textScore * 0.2 + chainScore * 0.4;
+}
+// Relocate
+/**
+ * Try to relocate a node by label. Strategy:
+ *   1. Run the original selector. If it returns exactly one node, build
+ *      its fingerprint and compare to the saved one. If similarity is
+ *      high (≥0.9), return that node — fast path.
+ *   2. If the original selector returns nothing, walk every node and
+ *      pick the one with the highest fingerprint similarity above the
+ *      minScore threshold (default 0.6).
+ *
+ * Returns ok:false with a reason if no node clears the threshold (QB#3).
+ */
+export function relocate(adapter, store, label, options = {}) {
+    const saved = store.load(label);
+    if (!saved) {
+        return { ok: false, reason: `no fingerprint saved for label "${label}"` };
+    }
+    const minScore = options.minScore ?? 0.6;
+    // Fast path: try the original selector first.
+    try {
+        const candidates = adapter.query(saved.originalSelector);
+        if (candidates.length === 1) {
+            const c = candidates[0];
+            if (c) {
+                const fp = fingerprint(adapter, c, saved.originalSelector);
+                const score = similarity(saved, fp);
+                if (score >= 0.9) {
+                    return { ok: true, node: c, score, viaOriginalSelector: true };
+                }
+            }
+        }
+    }
+    catch (err) {
+        // Selector itself may now be invalid — fall through to the walk.
+        void err;
+    }
+    // Fallback: walk every node and pick the best match.
+    let best = null;
+    let walkResult;
+    try {
+        walkResult = adapter.walkAll();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `adapter walkAll threw: ${msg}` };
+    }
+    for (const n of walkResult) {
+        let candidateFp;
+        try {
+            candidateFp = fingerprint(adapter, n, saved.originalSelector);
+        }
+        catch {
+            continue;
+        }
+        const score = similarity(saved, candidateFp);
+        if (best === null || score > best.score) {
+            best = { node: n, score };
+        }
+    }
+    if (best === null) {
+        return { ok: false, reason: "no nodes available to walk" };
+    }
+    if (best.score < minScore) {
+        return {
+            ok: false,
+            reason: `best candidate score ${best.score.toFixed(3)} below minScore ${minScore}`,
+        };
+    }
+    return { ok: true, node: best.node, score: best.score, viaOriginalSelector: false };
+}
+/**
+ * High-level convenience: query by selector, save the first match's
+ * fingerprint, and return the node. If a fingerprint already exists
+ * under the label, returns the relocated node (which may or may not
+ * be reachable via the saved selector — that's the whole point).
+ */
+export function adaptiveLocate(adapter, store, label, selector, options = {}) {
+    const existing = store.load(label);
+    if (existing) {
+        return relocate(adapter, store, label, options);
+    }
+    let candidates;
+    try {
+        candidates = adapter.query(selector);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `selector threw: ${msg}` };
+    }
+    const first = candidates[0];
+    if (!first) {
+        return { ok: false, reason: `selector "${selector}" matched no nodes` };
+    }
+    const fp = fingerprint(adapter, first, selector);
+    store.save(label, fp);
+    return { ok: true, node: first, score: 1, viaOriginalSelector: true };
+}
+//# sourceMappingURL=scrapling-adaptive.js.map

package/dist/ports/scrapling-adaptive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapling-adaptive.js","sourceRoot":"","sources":["../../src/ports/scrapling-adaptive.ts"],"names":[],"mappings":"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"}

package/dist/pr-checks/check-emitter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * GitHub Check Run emitter — POSTs Check Run payloads to the GitHub Checks API.
+ *
+ * V9 T12.5: each PR-check result becomes a separate Check Run entry under
+ * the PR (so reviewers see them listed individually). Uses the `application/vnd.github+json`
+ * media type and the v2022-11-28 API contract.
+ *
+ * QB #6 (honest stubs): bad input fails with explicit error; transient API
+ * failures retry per the spec (3 attempts, exponential backoff). No silent OK.
+ *
+ * SECURITY: token is read from `GITHUB_TOKEN` env var by default; tests inject
+ * their own. Never log the token or the request body (PR diffs may contain
+ * secrets that the no-hardcoded-secrets check is itself trying to flag).
+ */
+import type { GitHubCheckConclusion, PrCheckResult, PrCheckRunSummary } from "./pr-types.js";
+export interface EmitConfig {
+    /** repo slug `<owner>/<repo>` */
+    readonly repo: string;
+    /** head SHA the checks are anchored to */
+    readonly headSha: string;
+    /** GitHub token (Actions: secrets.GITHUB_TOKEN) */
+    readonly token: string;
+    /** Optional fetch shim — injectable for tests. */
+    readonly fetchFn?: typeof fetch;
+    /** Number of retries on transient (5xx) failures. Default 3. */
+    readonly retries?: number;
+    /** Optional sleep shim — injectable for tests. */
+    readonly sleepFn?: (ms: number) => Promise<void>;
+    /** Base URL for GitHub API. Default `https://api.github.com`. */
+    readonly apiBase?: string;
+}
+export interface EmitResult {
+    readonly ok: boolean;
+    readonly checkRunId?: number;
+    readonly statusCode?: number;
+    readonly error?: string;
+    readonly attempts: number;
+}
+/**
+ * Emit a single Check Run for one check result.
+ *
+ * Returns `{ok: false, error: ...}` on failure (after retries) — never throws.
+ *
+ * Status codes treated as transient (retried): 502, 503, 504, 408, 429.
+ * All other non-2xx codes return immediately with the status code surfaced.
+ */
+export declare function emitCheckRun(result: PrCheckResult, config: EmitConfig): Promise<EmitResult>;
+/**
+ * Emit all results in a summary. Continues on failure — returns array of
+ * EmitResult in same order as `summary.results` so callers can correlate.
+ *
+ * Per-call state (QB #7): does NOT mutate config; each emit gets its own
+ * retry counter independent of siblings.
+ */
+export declare function emitAllChecks(summary: PrCheckRunSummary, config: EmitConfig): Promise<readonly EmitResult[]>;
+/**
+ * Build the GitHub Check Run JSON payload from a single result.
+ *
+ * Mapping:
+ *   pass     → conclusion=success
+ *   fail+blocking → conclusion=failure
+ *   fail+advisory → conclusion=neutral
+ *   neutral  → conclusion=neutral
+ *   error    → conclusion=neutral (with explicit summary text)
+ *
+ * Every Check Run is `status=completed` — we don't emit progress checkpoints.
+ */
+export declare function buildCheckRunPayload(result: PrCheckResult, headSha: string): Readonly<Record<string, unknown>>;
+export declare function mapConclusion(result: PrCheckResult): GitHubCheckConclusion;
+/**
+ * Compute aggregate conclusion across all results. Used by the workflow
+ * summary step to decide whether to set the overall PR commit status.
+ */
+export declare function computeOverallConclusion(results: readonly PrCheckResult[]): GitHubCheckConclusion;
+//# sourceMappingURL=check-emitter.d.ts.map

package/dist/pr-checks/check-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-emitter.d.ts","sourceRoot":"","sources":["../../src/pr-checks/check-emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7F,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CA0FjG;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAOhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,MAAM,GACd,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAwBnC;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,qBAAqB,CAY1E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,qBAAqB,CAQjG"}

package/dist/pr-checks/check-emitter.js

@@ -0,0 +1,198 @@
+/**
+ * GitHub Check Run emitter — POSTs Check Run payloads to the GitHub Checks API.
+ *
+ * V9 T12.5: each PR-check result becomes a separate Check Run entry under
+ * the PR (so reviewers see them listed individually). Uses the `application/vnd.github+json`
+ * media type and the v2022-11-28 API contract.
+ *
+ * QB #6 (honest stubs): bad input fails with explicit error; transient API
+ * failures retry per the spec (3 attempts, exponential backoff). No silent OK.
+ *
+ * SECURITY: token is read from `GITHUB_TOKEN` env var by default; tests inject
+ * their own. Never log the token or the request body (PR diffs may contain
+ * secrets that the no-hardcoded-secrets check is itself trying to flag).
+ */
+/**
+ * Emit a single Check Run for one check result.
+ *
+ * Returns `{ok: false, error: ...}` on failure (after retries) — never throws.
+ *
+ * Status codes treated as transient (retried): 502, 503, 504, 408, 429.
+ * All other non-2xx codes return immediately with the status code surfaced.
+ */
+export async function emitCheckRun(result, config) {
+    if (!config.repo.includes("/")) {
+        return { ok: false, error: "config.repo must be 'owner/name'", attempts: 0 };
+    }
+    if (!config.headSha) {
+        return { ok: false, error: "config.headSha is required", attempts: 0 };
+    }
+    if (!config.token) {
+        return { ok: false, error: "config.token is required", attempts: 0 };
+    }
+    const fetchFn = config.fetchFn ?? fetch;
+    const sleepFn = config.sleepFn ?? defaultSleep;
+    const retries = config.retries ?? 3;
+    const apiBase = config.apiBase ?? "https://api.github.com";
+    const url = `${apiBase}/repos/${config.repo}/check-runs`;
+    const body = JSON.stringify(buildCheckRunPayload(result, config.headSha));
+    let attempt = 0;
+    let lastStatusCode;
+    let lastError;
+    while (attempt < retries) {
+        attempt++;
+        let response;
+        try {
+            response = await fetchFn(url, {
+                method: "POST",
+                headers: {
+                    Accept: "application/vnd.github+json",
+                    Authorization: `Bearer ${config.token}`,
+                    "Content-Type": "application/json",
+                    "X-GitHub-Api-Version": "2022-11-28",
+                },
+                body,
+            });
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+            if (attempt >= retries) {
+                return { ok: false, error: lastError, attempts: attempt };
+            }
+            await sleepFn(backoffMs(attempt));
+            continue;
+        }
+        lastStatusCode = response.status;
+        if (response.status >= 200 && response.status < 300) {
+            let id;
+            try {
+                const parsed = (await response.json());
+                if (typeof parsed.id === "number")
+                    id = parsed.id;
+            }
+            catch {
+                // Body unparseable but status was 2xx — still success, just no id.
+            }
+            return { ok: true, checkRunId: id, statusCode: response.status, attempts: attempt };
+        }
+        if (!isTransient(response.status)) {
+            let errBody = "";
+            try {
+                errBody = (await response.text()).slice(0, 256);
+            }
+            catch {
+                /* ignore */
+            }
+            return {
+                ok: false,
+                statusCode: response.status,
+                error: `GitHub API non-transient ${response.status}: ${errBody || "no body"}`,
+                attempts: attempt,
+            };
+        }
+        if (attempt >= retries) {
+            return {
+                ok: false,
+                statusCode: response.status,
+                error: `GitHub API transient ${response.status} after ${attempt} attempts`,
+                attempts: attempt,
+            };
+        }
+        await sleepFn(backoffMs(attempt));
+    }
+    return {
+        ok: false,
+        statusCode: lastStatusCode,
+        error: lastError ?? "unknown emit failure",
+        attempts: attempt,
+    };
+}
+/**
+ * Emit all results in a summary. Continues on failure — returns array of
+ * EmitResult in same order as `summary.results` so callers can correlate.
+ *
+ * Per-call state (QB #7): does NOT mutate config; each emit gets its own
+ * retry counter independent of siblings.
+ */
+export async function emitAllChecks(summary, config) {
+    const out = [];
+    for (const result of summary.results) {
+        const r = await emitCheckRun(result, config);
+        out.push(r);
+    }
+    return out;
+}
+/**
+ * Build the GitHub Check Run JSON payload from a single result.
+ *
+ * Mapping:
+ *   pass     → conclusion=success
+ *   fail+blocking → conclusion=failure
+ *   fail+advisory → conclusion=neutral
+ *   neutral  → conclusion=neutral
+ *   error    → conclusion=neutral (with explicit summary text)
+ *
+ * Every Check Run is `status=completed` — we don't emit progress checkpoints.
+ */
+export function buildCheckRunPayload(result, headSha) {
+    const conclusion = mapConclusion(result);
+    const title = result.status === "pass"
+        ? `${result.id}: PASS`
+        : result.status === "fail"
+            ? `${result.id}: FAIL`
+            : result.status === "neutral"
+                ? `${result.id}: NEUTRAL`
+                : `${result.id}: ERROR`;
+    return {
+        name: `wotann/${result.id}`,
+        head_sha: headSha,
+        status: "completed",
+        conclusion,
+        started_at: new Date(Date.now() - result.durationMs).toISOString(),
+        completed_at: new Date().toISOString(),
+        output: {
+            title,
+            summary: result.message.slice(0, 65535),
+            text: `Check: ${result.id}\nSeverity: ${result.severity}\nStatus: ${result.status}\nDuration: ${result.durationMs}ms`,
+        },
+    };
+}
+export function mapConclusion(result) {
+    switch (result.status) {
+        case "pass":
+            return "success";
+        case "fail":
+            return result.severity === "blocking" ? "failure" : "neutral";
+        case "neutral":
+        case "error":
+            return "neutral";
+        default:
+            return "neutral";
+    }
+}
+/**
+ * Compute aggregate conclusion across all results. Used by the workflow
+ * summary step to decide whether to set the overall PR commit status.
+ */
+export function computeOverallConclusion(results) {
+    let hasNeutral = false;
+    for (const r of results) {
+        const c = mapConclusion(r);
+        if (c === "failure")
+            return "failure";
+        if (c === "neutral")
+            hasNeutral = true;
+    }
+    return hasNeutral ? "neutral" : "success";
+}
+function backoffMs(attempt) {
+    // 1s, 2s, 4s — bounded so a flaky GH API doesn't stretch CI runs > 30s.
+    return Math.min(1000 * 2 ** (attempt - 1), 4000);
+}
+function isTransient(status) {
+    return status === 408 || status === 429 || (status >= 500 && status < 600);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=check-emitter.js.map

package/dist/pr-checks/check-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-emitter.js","sourceRoot":"","sources":["../../src/pr-checks/check-emitter.ts"],"names":[],"mappings":"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"}

package/dist/pr-checks/diff-loader.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Diff loader — produces a unified-diff string for a PR.
+ *
+ * Three modes:
+ *   - `gh-cli`: shells out to `gh pr diff <num>` via execFileNoThrow (argv-pass)
+ *   - `inline`: caller already has the diff text and just wants validation
+ *   - `file`:   caller has the diff in a file on disk
+ *
+ * QB #6 (honest stubs): no silent success — every failure path returns
+ * a Result with a precise reason, never throws ambiguous noise.
+ *
+ * SECURITY: gh shell-out uses execFileNoThrow (no shell, argv only) so a
+ * caller-supplied repo string can't inject shell metacharacters.
+ */
+/**
+ * Loader result — discriminated union, never throws on bad input.
+ */
+export type LoadResult = {
+    readonly ok: true;
+    readonly diff: string;
+    readonly source: DiffSource;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type DiffSource = "gh-cli" | "inline" | "file";
+/**
+ * Argv-style runner injected for tests; production uses execFileNoThrow.
+ */
+export interface ExecRunner {
+    (file: string, args: readonly string[]): Promise<{
+        readonly exitCode: number;
+        readonly stdout: string;
+        readonly stderr: string;
+    }>;
+}
+export interface LoadDiffOptions {
+    /** PR number (required for gh-cli mode). */
+    readonly prNumber?: number;
+    /** Inline diff text (required for inline mode). */
+    readonly inlineDiff?: string;
+    /** File path on disk (required for file mode). */
+    readonly filePath?: string;
+    /** Mode selector — auto-detected if omitted. */
+    readonly mode?: DiffSource;
+    /** Repository slug `<owner>/<repo>` for gh-cli (optional). */
+    readonly repo?: string;
+    /** Path to gh executable (default: `gh`). Injectable for tests. */
+    readonly ghBinary?: string;
+    /** ExecRunner shim — injectable for tests. */
+    readonly execFn?: ExecRunner;
+    /** ReadFile shim — injectable for tests. */
+    readonly readFileFn?: (path: string) => Promise<string>;
+    /** Max diff size accepted (default 1 MiB). */
+    readonly maxBytes?: number;
+}
+/**
+ * Load a PR diff. Returns Result, never throws.
+ *
+ * Validates that the returned text actually looks like a unified diff
+ * (starts with `diff --git ` or `--- ` or `Index:`). An empty PR returns
+ * `{ok: true, diff: ""}` — checks should treat empty diff as PASS by default.
+ */
+export declare function loadPrDiff(opts: LoadDiffOptions): Promise<LoadResult>;
+//# sourceMappingURL=diff-loader.d.ts.map

package/dist/pr-checks/diff-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-loader.d.ts","sourceRoot":"","sources":["../../src/pr-checks/diff-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,CACE,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,OAAO,CAAC;QACT,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAID;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CA4C3E"}