@mnemom/mnemom 0.17.38-next.0 → 0.17.38-next.2

package/dist/vendor/shared/org-scan-core/failure.js

@@ -0,0 +1,43 @@
+const EXACT = new Map([
+    ["github repo not visible", "not_installed"],
+    ["scan credential refused", "credential"],
+    ["scan credential not configured", "credential"],
+    ["invalid repo", "invalid_input"],
+    ["invalid cursor", "invalid_input"],
+    ["scan read not allowed", "invalid_input"],
+    ["unexpected list shape", "github"],
+]);
+export function classifyFailure(e) {
+    if (e instanceof Error) {
+        if (e.name === "TimeoutError" || e.name === "AbortError")
+            return "timeout";
+        const exact = EXACT.get(e.message);
+        if (exact)
+            return exact;
+        const gh = /^github read failed \((\d{3})\)$/.exec(e.message);
+        if (gh) {
+            if (gh[1] === "401" || gh[1] === "403")
+                return "forbidden";
+            if (gh[1] === "429")
+                return "rate_limited";
+            return "github";
+        }
+        if (e instanceof TypeError)
+            return "network";
+    }
+    return "github";
+}
+const TEXT = {
+    not_installed: "a repo is not visible to the credential (check your GitHub access to it)",
+    credential: "the GitHub credential was refused or is not configured",
+    timeout: "GitHub did not answer in time",
+    forbidden: "GitHub refused the credential (401/403)",
+    rate_limited: "GitHub rate limit reached",
+    github: "a GitHub read failed",
+    network: "GitHub was unreachable",
+    invalid_input: "an input to the scan was invalid",
+};
+/** Fixed sentence for a reason. */
+export function failureText(r) {
+    return TEXT[r];
+}

package/dist/vendor/shared/org-scan-core/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @mnemom/org-scan-core (MNE-9752): the org scan pipeline shared by the CLI and the Mnemom-side run.
+ * Runtime-neutral: GitHub reads go through an injected fetch and credential, time through an injected
+ * clock, cancellation through an injected AbortSignal. Nothing here stores or sends a report.
+ */
+export * from "./caps.js";
+export * from "./credential.js";
+export * from "./failure.js";
+export * from "./pr-source.js";
+export * from "./scan.js";
+export * from "./cost-per-pr.js";
+export * from "./report-build.js";
+export * from "./spend/ai-tool-detect.js";
+export * from "./spend/prices.js";
+export * from "./spend/token-rate.js";
+export * from "./spend/spend-estimate.js";
+export * from "./spend/spend-select.js";
+export * from "./spend/anthropic-usage.js";

package/dist/vendor/shared/org-scan-core/index.js

@@ -0,0 +1,19 @@
+// GENERATED from shared/org-scan-core/src/index.ts by cli/scripts/sync-org-scan-core.mjs; do not edit.
+/**
+ * @mnemom/org-scan-core (MNE-9752): the org scan pipeline shared by the CLI and the Mnemom-side run.
+ * Runtime-neutral: GitHub reads go through an injected fetch and credential, time through an injected
+ * clock, cancellation through an injected AbortSignal. Nothing here stores or sends a report.
+ */
+export * from "./caps.js";
+export * from "./credential.js";
+export * from "./failure.js";
+export * from "./pr-source.js";
+export * from "./scan.js";
+export * from "./cost-per-pr.js";
+export * from "./report-build.js";
+export * from "./spend/ai-tool-detect.js";
+export * from "./spend/prices.js";
+export * from "./spend/token-rate.js";
+export * from "./spend/spend-estimate.js";
+export * from "./spend/spend-select.js";
+export * from "./spend/anthropic-usage.js";

package/dist/vendor/shared/org-scan-core/pr-source.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Read-only GitHub PR source for the local scan. Port of mnemom-api src/org-scan/scan/github-pr-source.ts
+ * (window path, PRs #4208 / #4221 / #4223).
+ *
+ * METADATA only: size counts, a CI rollup, a revert boolean and the AI tools named in the PR body.
+ * Titles and bodies are inspected in memory and dropped; author logins, branch names, and code never
+ * leave this module (PrRecord has no such field). Every call goes through `guardedGet`, which only
+ * ever issues a GET to api.github.com on an allowlisted path. Failures throw fixed-text errors:
+ * never a GitHub body, a header, a URL or the token.
+ */
+import { type GitHubCredential } from "./credential.js";
+import type { AiTool } from "./spend/prices.js";
+export declare const GITHUB_API = "https://api.github.com";
+/** Merged PRs are listed 100 at a time; a list page is one read however many PRs it holds. */
+export declare const INDEX_PAGE_SIZE = 100;
+export type CiRollup = "none" | "pending" | "success" | "failure";
+export interface PrIndexItem {
+    number: number;
+    /** YYYY-MM-DD, UTC. */
+    mergedDay: string;
+    /** YYYY-MM-DD, UTC, last activity (the listing is newest-activity first). */
+    updatedDay: string;
+    reverted: boolean;
+}
+export interface PrIndexPage {
+    items: PrIndexItem[];
+    next: string | null;
+    reads: number;
+}
+export interface PrRecord {
+    additions: number;
+    deletions: number;
+    changed_files: number;
+    ci?: CiRollup;
+    reverted: boolean;
+    /** AI tools named in the PR body, detected here so the body never leaves this module. */
+    tools: AiTool[];
+}
+export interface PrSource {
+    indexMerged(repo: string, cursor: string | null, maxReads?: number): Promise<PrIndexPage>;
+    readPr(repo: string, item: PrIndexItem, maxReads?: number): Promise<{
+        pr: PrRecord | null;
+        reads: number;
+    }>;
+}
+export interface GithubPrSourceDeps {
+    credential: GitHubCredential;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /** Aborts every read (the caller's run deadline), on top of the per-read timeout. */
+    signal?: AbortSignal;
+    /** Sent as user-agent; defaults to the CLI's. */
+    userAgent?: string;
+}
+/** Pure: one word from check-run conclusions. No check names, logs or URLs are kept. */
+export declare function rollupCi(runs: Array<{
+    status?: unknown;
+    conclusion?: unknown;
+}>): CiRollup;
+export declare function isAllowedScanPath(path: string): boolean;
+export declare function createGithubPrSource(deps: GithubPrSourceDeps): PrSource;

package/dist/vendor/shared/org-scan-core/pr-source.js

@@ -0,0 +1,138 @@
+// GENERATED from shared/org-scan-core/src/pr-source.ts by cli/scripts/sync-org-scan-core.mjs; do not edit.
+/**
+ * Read-only GitHub PR source for the local scan. Port of mnemom-api src/org-scan/scan/github-pr-source.ts
+ * (window path, PRs #4208 / #4221 / #4223).
+ *
+ * METADATA only: size counts, a CI rollup, a revert boolean and the AI tools named in the PR body.
+ * Titles and bodies are inspected in memory and dropped; author logins, branch names, and code never
+ * leave this module (PrRecord has no such field). Every call goes through `guardedGet`, which only
+ * ever issues a GET to api.github.com on an allowlisted path. Failures throw fixed-text errors:
+ * never a GitHub body, a header, a URL or the token.
+ */
+import { isValidRepoSlug } from "./credential.js";
+import { detectAiTools } from "./spend/ai-tool-detect.js";
+export const GITHUB_API = "https://api.github.com";
+/** Merged PRs are listed 100 at a time; a list page is one read however many PRs it holds. */
+export const INDEX_PAGE_SIZE = 100;
+/** Pure: one word from check-run conclusions. No check names, logs or URLs are kept. */
+export function rollupCi(runs) {
+    if (runs.length === 0)
+        return "none";
+    if (runs.some((r) => r.status !== "completed"))
+        return "pending";
+    const ok = new Set(["success", "neutral", "skipped"]);
+    return runs.every((r) => typeof r.conclusion === "string" && ok.has(r.conclusion))
+        ? "success"
+        : "failure";
+}
+const isCount = (n) => typeof n === "number" && Number.isInteger(n) && n >= 0;
+const SLUG = "[A-Za-z0-9._-]{1,100}/[A-Za-z0-9._-]{1,100}";
+/** The only paths the scan may read. Anything else is refused before a request is made. */
+const ALLOWED_PATHS = [
+    new RegExp(`^/repos/${SLUG}/pulls\\?state=closed&sort=updated&direction=desc&per_page=\\d{1,3}&page=\\d{1,4}$`),
+    new RegExp(`^/repos/${SLUG}/pulls/\\d{1,9}$`),
+    new RegExp(`^/repos/${SLUG}/commits/[0-9a-f]{40}/check-runs\\?per_page=100$`),
+    // The repo picker's one list read (MNE-9643): the repos this login can read, newest push first.
+    /^\/user\/repos\?sort=pushed&direction=desc&per_page=\d{1,3}$/,
+];
+export function isAllowedScanPath(path) {
+    return ALLOWED_PATHS.some((re) => re.test(path));
+}
+/** The per-read timeout, joined with the caller's signal when there is one. */
+function readSignal(timeoutMs, outer) {
+    const t = AbortSignal.timeout(timeoutMs);
+    return outer ? AbortSignal.any([outer, t]) : t;
+}
+export function createGithubPrSource(deps) {
+    const doFetch = deps.fetchImpl ?? fetch;
+    const headers = {
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+        "user-agent": deps.userAgent ?? "mnemom-cli-scan/1",
+    };
+    /**
+     * `list` marks the PR list read, the first read of a repo. GitHub hides a repo the credential cannot
+     * see behind a 404, so only there is a 404 "repo not visible"; a 404 on a later detail or
+     * check-runs read is an ordinary upstream miss and keeps its numeric message (#4223).
+     */
+    async function guardedGet(path, repo, list = false) {
+        if (!isAllowedScanPath(path))
+            throw new Error("scan read not allowed");
+        const bearer = await deps.credential.tokenFor(repo);
+        const res = await doFetch(`${GITHUB_API}${path}`, {
+            method: "GET",
+            headers: { ...headers, authorization: `Bearer ${bearer}` },
+            redirect: "error",
+            signal: readSignal(deps.timeoutMs ?? 10_000, deps.signal),
+        });
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => { });
+            throw new Error(list && res.status === 404
+                ? "github repo not visible"
+                : `github read failed (${res.status})`);
+        }
+        return res.json();
+    }
+    const day = (v) => {
+        const t = typeof v === "string" ? Date.parse(v) : NaN;
+        return Number.isFinite(t) ? new Date(t).toISOString().slice(0, 10) : null;
+    };
+    return {
+        async indexMerged(repo, cursor) {
+            if (!isValidRepoSlug(repo))
+                throw new Error("invalid repo");
+            const page = cursor === null ? 1 : Number(cursor);
+            if (!Number.isInteger(page) || page < 1 || page > 1000)
+                throw new Error("invalid cursor");
+            const list = (await guardedGet(`/repos/${repo}/pulls?state=closed&sort=updated&direction=desc&per_page=${INDEX_PAGE_SIZE}&page=${page}`, repo, true));
+            if (!Array.isArray(list))
+                throw new Error("unexpected list shape");
+            const items = [];
+            for (const it of list) {
+                const mergedDay = day(it.merged_at);
+                const updatedDay = day(it.updated_at);
+                if (mergedDay === null || updatedDay === null || !isCount(it.number))
+                    continue;
+                // The title is read for the revert marker only and dropped here.
+                items.push({
+                    number: it.number,
+                    mergedDay,
+                    updatedDay,
+                    reverted: typeof it.title === "string" && /^revert\b/i.test(it.title),
+                });
+            }
+            return { items, next: list.length < INDEX_PAGE_SIZE ? null : String(page + 1), reads: 1 };
+        },
+        async readPr(repo, item, maxReads = Number.POSITIVE_INFINITY) {
+            if (!isValidRepoSlug(repo))
+                throw new Error("invalid repo");
+            if (!isCount(item.number) || maxReads < 2)
+                return { pr: null, reads: 0 };
+            const detail = (await guardedGet(`/repos/${repo}/pulls/${item.number}`, repo));
+            let reads = 1;
+            let ci;
+            const sha = detail.head?.sha;
+            if (typeof sha === "string" && /^[0-9a-f]{40}$/.test(sha)) {
+                const checks = (await guardedGet(`/repos/${repo}/commits/${sha}/check-runs?per_page=100`, repo));
+                reads += 1;
+                ci = rollupCi(Array.isArray(checks.check_runs) ? checks.check_runs : []);
+            }
+            if (!isCount(detail.additions) ||
+                !isCount(detail.deletions) ||
+                !isCount(detail.changed_files))
+                return { pr: null, reads };
+            const tools = detectAiTools(detail.body);
+            return {
+                pr: {
+                    additions: detail.additions,
+                    deletions: detail.deletions,
+                    changed_files: detail.changed_files,
+                    ci,
+                    reverted: item.reverted,
+                    tools,
+                },
+                reads,
+            };
+        },
+    };
+}

package/dist/vendor/shared/org-scan-core/report-build.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The org-scan report (org-scan-report/1) built from a scan result: the exact body the report email
+ * carries. Shared by the CLI (`POST /v1/orgs/{org_id}/scan/report-email`) and the Mnemom-side run
+ * (MNE-9752), so both send the same numbers. Pure and in memory: no network, no Node or Worker API.
+ *
+ * The body is exactly the route's contract and nothing else: `report` (team totals, counts, and the
+ * per-repo counts `by_repo`), `share_level`, `coverage.complete` and the optional `emails`. No author,
+ * title, branch or body text, no credential.
+ */
+import { type CostPerPr, type CostSpend } from "./cost-per-pr.js";
+import type { ScanResult } from "./scan.js";
+import type { SpendSelection } from "./spend/spend-select.js";
+/** How much of the report Mnemom may keep on file (MNE-9634). The email is always the full report. */
+export type ShareLevel = "full" | "analytics" | "none";
+export declare const REPORT_SCHEMA_VERSION = "org-scan-report/1";
+export declare const ESTIMATE_NAME = "automatable_work_share";
+export declare const METHOD_URL = "https://www.mnemom.ai/org-scan-method";
+export interface EmailReport {
+    schema_version: typeof REPORT_SCHEMA_VERSION;
+    org_id: string;
+    scan_id: string;
+    period: {
+        start: string;
+        end: string;
+    };
+    generated_at: string;
+    measured: {
+        teams: [];
+        summary: {
+            pr_count: number;
+            revert_count: number;
+            automatable_count: number;
+            examined_count: number;
+            tokens_total: 0;
+        };
+        spend: {
+            source: "pr_estimate";
+            figure?: {
+                low_cents: number;
+                high_cents: number;
+            };
+            ai_prs_by_tool?: Array<{
+                tool: string;
+                count: number;
+            }>;
+        };
+    };
+    estimate: {
+        name: string;
+        value: number;
+        unit: string;
+        method_url: string;
+    };
+    /**
+     * Optional, added after org-scan-report/1 shipped; absent whenever it cannot be computed (no spend,
+     * no merged PR in the period, an incomplete scan, an empty bucket). See cost-per-pr.ts.
+     *   cost_per_merged_pr  average cost of one merged PR in the period
+     *   cost_by_pr_size     { small | medium | large }: average cost of ONE PR of that size, per-bucket
+     *                       keys absent when the bucket is empty. small < 50 lines changed, medium 50..500, large > 500.
+     * A figure is { label: "estimate", spend_source, pr_scope, pr_count } (+ spend_scope: "whole_org" on
+     * anthropic_usage) plus { value_cents } (anthropic_usage) or { low_cents, high_cents } (modelled_range). Integer cents.
+     * pr_scope is "ai_assisted" for modelled_range (spend and size buckets split across AI-assisted PRs only;
+     * absent if none) and "all_merged" otherwise; pr_count counts PRs in that scope.
+     * Always attached when present. The API's report validator (mnemom-api src/org-scan/report-schema.ts) is
+     * closed, so an API that does not yet list these keys answers 400 invalid_report; sendReportEmail then
+     * retries once without them so the report email still goes out.
+     */
+    cost_per_merged_pr?: CostPerPr["cost_per_merged_pr"];
+    cost_by_pr_size?: CostPerPr["cost_by_pr_size"];
+    /**
+     * The per-repo counts, by name (MNE-9634). Always sent, at every share level: the emailed report is the full
+     * report. Optional on the wire so an API that predates it can be retried without it. Capped at 500 repos
+     * (busiest first), valid names only, each name once.
+     */
+    by_repo?: Array<{
+        repo: string;
+        pr_count: number;
+        revert_count: number;
+        automatable_count: number;
+        examined_count: number;
+    }>;
+}
+export interface ReportEmailBody {
+    report: EmailReport;
+    share_level: ShareLevel;
+    coverage: {
+        complete: boolean;
+    };
+    /** The extra recipients the runner added. Absent when none. */
+    emails?: string[];
+    /** Only set on the retry to an API that predates `emails`: it reads one extra address under this name. */
+    cto_email?: string;
+}
+/**
+ * Maps the local scan onto the route's closed report shape. Team totals stay empty (they come only from
+ * Anthropic usage, which the local scan does not carry). The estimate is the share of examined merged
+ * PRs that finished with every CI check passing. `figure` (tier 3 range) is included only when the CLI
+ * itself would let that line leave the machine (`sendSpendRange`).
+ */
+export declare function buildEmailReport(result: ScanResult, o: {
+    orgId: string;
+    now: () => number;
+    sendSpendRange: boolean;
+    scanId?: string;
+    /** The requested scan period (the one the spend covers), not the examined window. */
+    period?: {
+        start: string;
+        end: string;
+    };
+    /** The one spend source the cost figures are split from; null/absent leaves them out. */
+    costSpend?: CostSpend | null;
+}): EmailReport;
+export declare function buildEmailBody(report: EmailReport, level: ShareLevel, complete: boolean, extraEmails?: string[]): ReportEmailBody;
+/**
+ * The one spend source the cost-per-PR figures are split from, given the spend line selected (null when
+ * the spend tiers are off) and the measured Anthropic usage in dollars, if any.
+ */
+export declare function costSpendFor(result: ScanResult, spend: SpendSelection | null, measuredUsd: number | undefined): CostSpend | null;
+/** May the tier 3 range leave the machine in the report? Only when it is the tier shown (or tiers are off). */
+export declare const sendsSpendRange: (spend: SpendSelection | null) => boolean;

package/dist/vendor/shared/org-scan-core/report-build.js

@@ -0,0 +1,119 @@
+// GENERATED from shared/org-scan-core/src/report-build.ts by cli/scripts/sync-org-scan-core.mjs; do not edit.
+/**
+ * The org-scan report (org-scan-report/1) built from a scan result: the exact body the report email
+ * carries. Shared by the CLI (`POST /v1/orgs/{org_id}/scan/report-email`) and the Mnemom-side run
+ * (MNE-9752), so both send the same numbers. Pure and in memory: no network, no Node or Worker API.
+ *
+ * The body is exactly the route's contract and nothing else: `report` (team totals, counts, and the
+ * per-repo counts `by_repo`), `share_level`, `coverage.complete` and the optional `emails`. No author,
+ * title, branch or body text, no credential.
+ */
+import { buildCostPerPr, modelledSpend } from "./cost-per-pr.js";
+export const REPORT_SCHEMA_VERSION = "org-scan-report/1";
+export const ESTIMATE_NAME = "automatable_work_share";
+export const METHOD_URL = "https://www.mnemom.ai/org-scan-method";
+const cents = (usd) => Math.max(0, Math.round(usd * 100));
+/**
+ * Maps the local scan onto the route's closed report shape. Team totals stay empty (they come only from
+ * Anthropic usage, which the local scan does not carry). The estimate is the share of examined merged
+ * PRs that finished with every CI check passing. `figure` (tier 3 range) is included only when the CLI
+ * itself would let that line leave the machine (`sendSpendRange`).
+ */
+export function buildEmailReport(result, o) {
+    const { totals, coverage } = result;
+    const value = totals.examined > 0 ? Math.round((totals.ciGreen / totals.examined) * 1000) / 10 : 0;
+    const scope = coverage.complete
+        ? "every merged pull request in the period"
+        : "a capped sample (not every merged pull request in the period)";
+    const unit = `percent of merged pull requests examined (${totals.examined} of ${totals.prs}, ${scope}) ` +
+        `that finished with all CI checks passing; an estimate from pull request metadata, not a measured share`;
+    const byTool = result.spend.kind === "range"
+        ? Object.entries(result.spend.byTool)
+            .filter(([, n]) => typeof n === "number" && n > 0)
+            .map(([tool, count]) => ({ tool, count: count }))
+        : [];
+    // Only a scan that read every merged PR in the period gives an average that means anything.
+    const exhaustive = coverage.complete && coverage.prsSkippedLarge === 0 && coverage.prsUnreadable === 0;
+    const cost = buildCostPerPr(result.prSizes, o.period ?? { start: coverage.windowStart, end: coverage.windowEnd }, o.costSpend ?? null, exhaustive);
+    const byRepo = repoRows(result);
+    return {
+        schema_version: REPORT_SCHEMA_VERSION,
+        org_id: o.orgId,
+        scan_id: o.scanId ?? crypto.randomUUID(),
+        // The span the scan actually examined (coverage), never the requested period: with no --period
+        // that defaults to today..today, which is not what was read.
+        period: { start: coverage.windowStart, end: coverage.windowEnd },
+        generated_at: new Date(o.now()).toISOString(),
+        measured: {
+            teams: [],
+            summary: {
+                pr_count: totals.prs,
+                revert_count: totals.reverts,
+                automatable_count: totals.ciGreen,
+                examined_count: totals.examined,
+                tokens_total: 0,
+            },
+            spend: {
+                source: "pr_estimate",
+                ...(o.sendSpendRange && result.spend.kind === "range"
+                    ? {
+                        figure: {
+                            low_cents: cents(result.spend.lowUsd),
+                            high_cents: cents(result.spend.highUsd),
+                        },
+                    }
+                    : {}),
+                ...(o.sendSpendRange && byTool.length > 0 ? { ai_prs_by_tool: byTool } : {}),
+            },
+        },
+        estimate: { name: ESTIMATE_NAME, value, unit, method_url: METHOD_URL },
+        ...cost,
+        ...(byRepo.length > 0 ? { by_repo: byRepo } : {}),
+    };
+}
+const MAX_REPOS = 500;
+const REPO_NAME = /^[A-Za-z0-9._-]{1,100}\/[A-Za-z0-9._-]{1,100}$/;
+/** The per-repo rows for the report: valid names only, each once (any case), busiest first, at most 500. */
+function repoRows(result) {
+    const seen = new Set();
+    return [...result.byRepo]
+        .sort((a, b) => b.prs - a.prs || a.repo.localeCompare(b.repo))
+        .filter((r) => {
+        const k = r.repo.toLowerCase();
+        if (!REPO_NAME.test(r.repo) || seen.has(k))
+            return false;
+        seen.add(k);
+        return true;
+    })
+        .slice(0, MAX_REPOS)
+        .map((r) => ({
+        repo: r.repo,
+        pr_count: r.prs,
+        revert_count: r.reverts,
+        automatable_count: r.ciGreen,
+        examined_count: r.examined,
+    }));
+}
+export function buildEmailBody(report, level, complete, extraEmails = []) {
+    return {
+        report,
+        share_level: level,
+        coverage: { complete },
+        ...(extraEmails.length > 0 ? { emails: extraEmails } : {}),
+    };
+}
+/**
+ * The one spend source the cost-per-PR figures are split from, given the spend line selected (null when
+ * the spend tiers are off) and the measured Anthropic usage in dollars, if any.
+ */
+export function costSpendFor(result, spend, measuredUsd) {
+    if (spend === null)
+        return modelledSpend(result.spend);
+    if (spend.tier === 1)
+        return typeof measuredUsd === "number" ? { source: "anthropic_usage", usd: measuredUsd } : null;
+    if (spend.tier === 2)
+        return null;
+    return spend.tier === 3 ? modelledSpend(result.spend) : null;
+}
+/** May the tier 3 range leave the machine in the report? Only when it is the tier shown (or tiers are off). */
+export const sendsSpendRange = (spend) => spend ? spend.shareable && spend.tier === 3 : true;

package/dist/vendor/shared/org-scan-core/scan.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Capped scan core, shared by the CLI and the Mnemom-side run (MNE-9752). Port of the window path of runCappedScan (mnemom-api capped-scan.ts, PR #4208)
+ * plus the spend estimate (#4222). Everything outside is injected (credential, PR source, clock), so the
+ * core touches no network or disk, and the report exists only in memory.
+ */
+import { type GitHubCredential } from "./credential.js";
+import { type ScanCaps, type StopReason } from "./caps.js";
+import { type FailureReason } from "./failure.js";
+import { type PrSource } from "./pr-source.js";
+import type { PrSize } from "./cost-per-pr.js";
+import { type SpendEstimate } from "./spend/spend-estimate.js";
+export interface ScanInput {
+    repos: string[];
+    /** Inclusive dates, YYYY-MM-DD. */
+    period: {
+        start: string;
+        end: string;
+    };
+}
+export interface ScanDeps {
+    credential: GitHubCredential;
+    prs?: PrSource;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    caps?: Partial<ScanCaps>;
+    /** The exact read-only permission set the credential must hold. Defaults to the CLI's set. */
+    permissions?: Readonly<Record<string, "read">>;
+    /** Aborts every GitHub read (the caller's run deadline). */
+    signal?: AbortSignal;
+    /** user-agent for the GitHub reads; defaults to the CLI's. */
+    userAgent?: string;
+}
+export interface Coverage {
+    complete: boolean;
+    stoppedBy: StopReason | null;
+    prsExamined: number;
+    prsSkippedLarge: number;
+    prsUnreadable: number;
+    reposRead: number;
+    reposTotal: number;
+    reads: number;
+    windowStart: string;
+    windowEnd: string;
+    /** Set only when the window held more merged PRs than the quota and an even sample was taken. */
+    windowSampledFrom?: number;
+}
+export interface RepoTotals {
+    repo: string;
+    prs: number;
+    reverts: number;
+    ciGreen: number;
+    /** PRs read and counted (not reverts, not skipped); the per-repo base of the CI-green share. */
+    examined: number;
+}
+export interface ScanResult {
+    coverage: Coverage;
+    totals: {
+        prs: number;
+        reverts: number;
+        ciGreen: number;
+        examined: number;
+    };
+    byRepo: RepoTotals[];
+    spend: SpendEstimate;
+    /** Every merged PR read in full (reverts and unreadable/oversize PRs excluded): merge day and size. In memory only. */
+    prSizes: PrSize[];
+}
+export type ScanOutcome = {
+    status: "done";
+    result: ScanResult;
+} | {
+    status: "withheld";
+    reason: FailureReason;
+};
+export declare function runLocalScan(deps: ScanDeps, input: ScanInput): Promise<ScanOutcome>;