@mnemom/mnemom 0.17.32 → 0.17.34-next.1

package/dist/lib/scan/record.js

@@ -0,0 +1,85 @@
+/**
+ * The org's Record totals for the scan preview: one read of
+ * `GET /v1/orgs/:org_id/record/totals?from=&to=` (window form, contract i2-totals-window v1.2).
+ * Read-only and local: the answer is held in memory to build the report and is never uploaded or
+ * stored (mnemom-api#4211: Mnemom stores no scan result).
+ *
+ * The window is always the last 30 days ending now (the contract's maximum). It is its own
+ * window, not the PR scan period, and the report labels it "last 30 days"; no other scan-window
+ * number is ever produced here.
+ *
+ * Outcomes are a closed set, and every one has fixed text. The thrown value, the response body
+ * and the credential never reach the terminal:
+ *   ok            totals read and shape-checked
+ *   not_in_cohort 404: the org is not in the Record cohort (or the org is unknown). Not an error.
+ *   unavailable   anything else (429 cap, 5xx, timeout, network, off-shape body). Scan continues.
+ *   auth          401/403 or a missing login: throws RecordAuthError (fail closed).
+ */
+import { getRecordWindowTotals, MnemomApiError } from "../api.js";
+export const RECORD_WINDOW_DAYS = 30;
+export const RECORD_WINDOW_LABEL = "last 30 days";
+export const RECORD_TIMEOUT_MS = 10_000;
+/** `to` may not be in the future; stay a minute behind so a fast local clock cannot trip it. */
+const CLOCK_SKEW_MS = 60_000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const ORG_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const MMU_RE = /^(0|[1-9][0-9]{0,18})$/;
+export const isOrgId = (v) => typeof v === "string" && ORG_ID_RE.test(v);
+export const RECORD_AUTH_MSG = "Record totals were refused for this org. Run `mnemom login` (or set MNEMOM_API_KEY) with an owner, admin or auditor of the org passed to --org, then retry.";
+export class RecordAuthError extends Error {
+    constructor() {
+        super(RECORD_AUTH_MSG);
+        this.name = "RecordAuthError";
+    }
+}
+export function recordWindow(nowMs) {
+    const to = nowMs - CLOCK_SKEW_MS;
+    return {
+        from: new Date(to - RECORD_WINDOW_DAYS * DAY_MS).toISOString(),
+        to: new Date(to).toISOString(),
+    };
+}
+const isMmu = (v) => typeof v === "string" && MMU_RE.test(v);
+/** Shape-check the body: a malformed answer is "unavailable", never rendered. */
+export function parseWindowTotals(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const o = v;
+    if (!isMmu(o.model_cost_mmu))
+        return null;
+    if (o.mu_charged_mmu !== null && !isMmu(o.mu_charged_mmu))
+        return null;
+    if (typeof o.row_count !== "number" || !Number.isInteger(o.row_count) || o.row_count < 0)
+        return null;
+    if (o.as_of !== null && typeof o.as_of !== "string")
+        return null;
+    return {
+        model_cost_mmu: o.model_cost_mmu,
+        mu_charged_mmu: o.mu_charged_mmu,
+        row_count: o.row_count,
+        as_of: o.as_of,
+    };
+}
+/** Never throws except RecordAuthError (401/403, fail closed). */
+export async function fetchRecordTotals(orgId, deps = {}) {
+    if (!isOrgId(orgId))
+        return { status: "unavailable" };
+    const window = recordWindow((deps.now ?? Date.now)());
+    const fetchTotals = deps.fetchTotals ?? getRecordWindowTotals;
+    const signal = AbortSignal.timeout(deps.timeoutMs ?? RECORD_TIMEOUT_MS);
+    try {
+        const body = await fetchTotals(orgId, window.from, window.to, signal);
+        const totals = parseWindowTotals(body);
+        return totals ? { status: "ok", totals, window } : { status: "unavailable" };
+    }
+    catch (e) {
+        if (e instanceof MnemomApiError) {
+            const s = e.effectiveStatus;
+            if (s === 401 || s === 403)
+                throw new RecordAuthError();
+            if (s === 404)
+                return { status: "not_in_cohort" };
+        }
+        return { status: "unavailable" };
+    }
+}

package/dist/lib/scan/report-email.d.ts

@@ -0,0 +1,92 @@
+import type { ScanResult } from "./scan.js";
+import type { ShareLevel } from "./share.js";
+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/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;
+    };
+}
+export interface ReportEmailBody {
+    report: EmailReport;
+    share_level: ShareLevel;
+    coverage: {
+        complete: boolean;
+    };
+    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;
+    period: {
+        start: string;
+        end: string;
+    };
+    now: () => number;
+    sendSpendRange: boolean;
+    scanId?: string;
+}): EmailReport;
+export declare function buildEmailBody(report: EmailReport, level: ShareLevel, complete: boolean, ctoEmail?: string): ReportEmailBody;
+/** Closed set of failure names; each has fixed text. */
+export type EmailFailure = "presend_check_failed" | "email_not_sent" | "not_signed_in" | "not_a_member" | "report_rejected" | "no_recipients" | "network_error" | "unexpected_response";
+export declare const failureMessage: (f: EmailFailure) => string;
+export declare const DRY_RUN_MSG = "Report email is in dry-run on this environment; nothing was sent.";
+export declare const UNAVAILABLE_MSG = "Report email is not available for this org yet; nothing was sent.";
+export declare class ReportEmailError extends Error {
+    readonly reason: EmailFailure;
+    constructor(reason: EmailFailure);
+}
+export type EmailOutcome = {
+    status: "sent";
+    recipients: number;
+} | {
+    status: "dry_run";
+} | {
+    status: "unavailable";
+} | {
+    status: "failed";
+    reason: EmailFailure;
+};
+export interface ReportEmailDeps {
+    post?: (endpoint: string, body: ReportEmailBody) => Promise<unknown>;
+}
+/** Never throws. The thrown value, the response body and the credential are never surfaced. */
+export declare function sendReportEmail(orgId: string, body: ReportEmailBody, deps?: ReportEmailDeps): Promise<EmailOutcome>;

package/dist/lib/scan/report-email.js

@@ -0,0 +1,136 @@
+/**
+ * The report email: after every successful scan the person who ran it is emailed the report, with no
+ * opt-out and at every share level. One call to `POST /v1/orgs/{org_id}/scan/report-email`
+ * (mnemom-api#4270). The server resolves the runner's address from the signed-in identity, so the
+ * request carries no runner address; `cto_email` is sent only when the user passed --cto-email.
+ *
+ * The body is exactly the route's contract and nothing else: `report` (org-scan-report/1: team totals
+ * and counts only), `share_level`, `coverage.complete` and the optional `cto_email`. No Record totals,
+ * no repo names, no author, title, branch or body text, no credential.
+ *
+ * Every failure has a fixed name and fixed text. The server's body, the thrown value and the
+ * credential never reach the terminal.
+ */
+import { randomUUID } from "node:crypto";
+import { MnemomApiError, postApi } from "../api.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/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 }))
+        : [];
+    return {
+        schema_version: REPORT_SCHEMA_VERSION,
+        org_id: o.orgId,
+        scan_id: o.scanId ?? randomUUID(),
+        period: o.period,
+        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 },
+    };
+}
+export function buildEmailBody(report, level, complete, ctoEmail) {
+    return {
+        report,
+        share_level: level,
+        coverage: { complete },
+        ...(ctoEmail !== undefined ? { cto_email: ctoEmail } : {}),
+    };
+}
+const FAILURE_TEXT = {
+    presend_check_failed: "the report failed Mnemom's pre-send checks, so no email was sent.",
+    email_not_sent: "Mnemom could not send the email.",
+    not_signed_in: "you are not signed in. Run `mnemom login` and re-run the scan.",
+    not_a_member: "your account is not a member of the org passed to --org.",
+    report_rejected: "Mnemom rejected the report as malformed.",
+    no_recipients: "the server accepted the report but reported zero recipients.",
+    network_error: "Mnemom could not be reached.",
+    unexpected_response: "Mnemom answered in an unexpected way.",
+};
+export const failureMessage = (f) => `Your report was NOT emailed: ${f}. ${FAILURE_TEXT[f]}`;
+export const DRY_RUN_MSG = "Report email is in dry-run on this environment; nothing was sent.";
+export const UNAVAILABLE_MSG = "Report email is not available for this org yet; nothing was sent.";
+export class ReportEmailError extends Error {
+    reason;
+    constructor(reason) {
+        super(failureMessage(reason));
+        this.reason = reason;
+        this.name = "ReportEmailError";
+    }
+}
+const defaultPost = (endpoint, body) => postApi(endpoint, body);
+function classifyStatus(status) {
+    if (status === 401)
+        return "not_signed_in";
+    if (status === 403)
+        return "not_a_member";
+    if (status === 422)
+        return "presend_check_failed";
+    if (status === 502)
+        return "email_not_sent";
+    if (status === 400 || status === 413)
+        return "report_rejected";
+    return "unexpected_response";
+}
+/** Never throws. The thrown value, the response body and the credential are never surfaced. */
+export async function sendReportEmail(orgId, body, deps = {}) {
+    const post = deps.post ?? defaultPost;
+    let res;
+    try {
+        res = await post(`/v1/orgs/${encodeURIComponent(orgId)}/scan/report-email`, body);
+    }
+    catch (e) {
+        if (e instanceof MnemomApiError && e.effectiveStatus === 404)
+            return { status: "unavailable" };
+        if (e instanceof MnemomApiError)
+            return { status: "failed", reason: classifyStatus(e.effectiveStatus) };
+        return { status: "failed", reason: "network_error" };
+    }
+    const o = typeof res === "object" && res !== null ? res : null;
+    const recipients = o?.recipients;
+    if (o === null || (o.status !== "sent" && o.status !== "dry_run"))
+        return { status: "failed", reason: "unexpected_response" };
+    if (typeof recipients !== "number" || !Number.isInteger(recipients) || recipients < 0)
+        return { status: "failed", reason: "unexpected_response" };
+    if (recipients === 0)
+        return { status: "failed", reason: "no_recipients" };
+    return o.status === "dry_run" ? { status: "dry_run" } : { status: "sent", recipients };
+}

package/dist/lib/scan/report.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Renders the scan preview report from values already in memory: the local PR scan plus the org's
+ * Record totals. Pure (returns lines, prints nothing) and never persists anything. Totals are
+ * labelled "last 30 days"; no other window number is invented. Money is integer millimu
+ * (1 MU = 1000 mmu), formatted with BigInt so values above 2^53 stay exact.
+ */
+import { type RecordOutcome } from "./record.js";
+export declare const RECORD_NOT_AVAILABLE_NOTE = "Records not available for this org.";
+export declare const RECORD_UNAVAILABLE_NOTE = "Records could not be read right now; continuing without them.";
+export declare const RECORD_NO_ORG_NOTE = "Records skipped: pass --org <org_id> to include the org's Record totals.";
+/** "12.5 MU" from "12500". Caller guarantees a canonical mmu string. */
+export declare function formatMu(mmu: string): string;
+export declare function renderRecordSection(outcome: RecordOutcome): string[];

package/dist/lib/scan/report.js

@@ -0,0 +1,30 @@
+/**
+ * Renders the scan preview report from values already in memory: the local PR scan plus the org's
+ * Record totals. Pure (returns lines, prints nothing) and never persists anything. Totals are
+ * labelled "last 30 days"; no other window number is invented. Money is integer millimu
+ * (1 MU = 1000 mmu), formatted with BigInt so values above 2^53 stay exact.
+ */
+import { RECORD_WINDOW_LABEL } from "./record.js";
+export const RECORD_NOT_AVAILABLE_NOTE = "Records not available for this org.";
+export const RECORD_UNAVAILABLE_NOTE = "Records could not be read right now; continuing without them.";
+export const RECORD_NO_ORG_NOTE = "Records skipped: pass --org <org_id> to include the org's Record totals.";
+/** "12.5 MU" from "12500". Caller guarantees a canonical mmu string. */
+export function formatMu(mmu) {
+    const n = BigInt(mmu);
+    const whole = (n / 1000n).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    const frac = (n % 1000n).toString().padStart(3, "0").replace(/0+$/, "");
+    return `${whole}${frac ? `.${frac}` : ""} MU`;
+}
+export function renderRecordSection(outcome) {
+    if (outcome.status === "not_in_cohort")
+        return [RECORD_NOT_AVAILABLE_NOTE];
+    if (outcome.status === "unavailable")
+        return [RECORD_UNAVAILABLE_NOTE];
+    const t = outcome.totals;
+    return [
+        `Org Record (${RECORD_WINDOW_LABEL}, read from Mnemom; not stored):`,
+        `  Model cost: ${formatMu(t.model_cost_mmu)}`,
+        `  Charged: ${t.mu_charged_mmu === null ? "not charged" : formatMu(t.mu_charged_mmu)}`,
+        `  Requests recorded: ${t.row_count}`,
+    ];
+}

package/dist/lib/scan/scan.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Local capped scan core. 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 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>;
+}
+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;
+}
+export interface ScanResult {
+    coverage: Coverage;
+    totals: {
+        prs: number;
+        reverts: number;
+        ciGreen: number;
+        examined: number;
+    };
+    byRepo: RepoTotals[];
+    spend: SpendEstimate;
+}
+export type ScanOutcome = {
+    status: "done";
+    result: ScanResult;
+} | {
+    status: "withheld";
+    reason: FailureReason;
+};
+export declare function runLocalScan(deps: ScanDeps, input: ScanInput): Promise<ScanOutcome>;

package/dist/lib/scan/scan.js

@@ -0,0 +1,182 @@
+/**
+ * Local capped scan core. 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 { assertReadOnlyCredential, isValidRepoSlug } from "./credential.js";
+import { Budget, COVERAGE_MONTHS, evenSample, monthsBefore, sanitiseCaps, } from "./caps.js";
+import { classifyFailure } from "./failure.js";
+import { createGithubPrSource } from "./pr-source.js";
+import { estimateSpend } from "./spend/spend-estimate.js";
+const validDay = (d) => typeof d === "string" &&
+    /^\d{4}-\d{2}-\d{2}$/.test(d) &&
+    !Number.isNaN(Date.parse(`${d}T00:00:00Z`));
+export async function runLocalScan(deps, input) {
+    if (!validDay(input.period.start) ||
+        !validDay(input.period.end) ||
+        input.repos.length === 0 ||
+        !input.repos.every(isValidRepoSlug)) {
+        return { status: "withheld", reason: "invalid_input" };
+    }
+    try {
+        await assertReadOnlyCredential(deps.credential);
+    }
+    catch (e) {
+        return { status: "withheld", reason: classifyFailure(e) };
+    }
+    const prs = deps.prs ?? createGithubPrSource({ credential: deps.credential, fetchImpl: deps.fetchImpl });
+    const now = deps.now ?? Date.now;
+    const caps = sanitiseCaps(deps.caps ?? {});
+    const budget = new Budget(caps, now, now());
+    let stoppedBy = null;
+    const stop = (r) => {
+        if (r && !stoppedBy)
+            stoppedBy = r;
+        return stoppedBy !== null;
+    };
+    const periodStart = input.period.start;
+    const windowStart = periodStart < monthsBefore(input.period.end, COVERAGE_MONTHS)
+        ? periodStart
+        : monthsBefore(input.period.end, COVERAGE_MONTHS);
+    const endDay = input.period.end;
+    const pool = [];
+    let reposRead = 0;
+    let listingCut = false;
+    try {
+        for (const repo of input.repos) {
+            if (stoppedBy !== null || stop(budget.block()))
+                break;
+            reposRead += 1;
+            let cursor = null;
+            const days = [];
+            let oldestUpdated = "9999-99-99";
+            do {
+                if (stop(budget.block()))
+                    break;
+                // Listing may use at most half the read budget, so it never starves the reads of the PRs it found.
+                if (budget.reads * 2 > caps.maxReads) {
+                    listingCut = true;
+                    break;
+                }
+                budget.charge(1);
+                const page = await prs.indexMerged(repo, cursor, budget.room() + 1);
+                budget.charge((Number.isFinite(page.reads) && page.reads >= 1 ? page.reads : 1) - 1);
+                const overrun = budget.overrun();
+                if (overrun) {
+                    stop(overrun);
+                    break;
+                }
+                for (const item of page.items) {
+                    pool.push({ repo, item });
+                    days.push(item.mergedDay);
+                    if (item.updatedDay < oldestUpdated)
+                        oldestUpdated = item.updatedDay;
+                }
+                cursor = page.next;
+                // Newest-activity first: once a seen PR was last touched before D, no later page holds a PR
+                // merged on or after D. Stop when D is both the window start and the merge day of this repo's
+                // maxPrs-th newest merged PR.
+                const kth = days.length >= caps.maxPrs ? [...days].sort().reverse()[caps.maxPrs - 1] : null;
+                if (kth !== null && oldestUpdated < (kth < windowStart ? kth : windowStart))
+                    break;
+            } while (cursor !== null && stoppedBy === null);
+            if (listingCut) {
+                if (cursor === null && days.length === 0)
+                    reposRead -= 1;
+                break;
+            }
+        }
+        // Newest first, ties by repo then number: the same pool always gives the same sample.
+        for (let i = pool.length - 1; i >= 0; i--)
+            if (pool[i].item.mergedDay > endDay)
+                pool.splice(i, 1);
+        pool.sort((a, b) => (a.item.mergedDay === b.item.mergedDay
+            ? 0
+            : a.item.mergedDay < b.item.mergedDay
+                ? 1
+                : -1) ||
+            (a.repo < b.repo ? -1 : a.repo > b.repo ? 1 : 0) ||
+            b.item.number - a.item.number);
+        const inWindow = pool.filter((p) => p.item.mergedDay >= windowStart);
+        const sampled = inWindow.length > caps.maxPrs;
+        const chosen = sampled ? evenSample(inWindow, caps.maxPrs) : pool.slice(0, caps.maxPrs);
+        const byRepo = new Map();
+        const bucket = (repo) => {
+            let b = byRepo.get(repo);
+            if (!b)
+                byRepo.set(repo, (b = { repo, prs: 0, reverts: 0, ciGreen: 0 }));
+            return b;
+        };
+        const totals = { prs: 0, reverts: 0, ciGreen: 0, examined: 0 };
+        const spendInputs = [];
+        let skippedLarge = 0;
+        let unreadable = 0;
+        for (const { repo, item } of chosen) {
+            // A revert PR is never a candidate: counted from the listing, never read.
+            if (item.reverted) {
+                totals.prs += 1;
+                totals.reverts += 1;
+                bucket(repo).prs += 1;
+                bucket(repo).reverts += 1;
+                continue;
+            }
+            if (stop(budget.block(2)))
+                break;
+            budget.charge(1);
+            const res = await prs.readPr(repo, item, budget.room() + 1);
+            budget.charge((Number.isFinite(res.reads) && res.reads >= 1 ? res.reads : 1) - 1);
+            const overrun = budget.overrun();
+            if (overrun) {
+                stop(overrun);
+                break;
+            }
+            const rec = res.pr;
+            if (!rec) {
+                unreadable += 1;
+                continue;
+            }
+            if (rec.additions + rec.deletions > caps.maxPrSizeLines) {
+                skippedLarge += 1;
+                continue;
+            }
+            totals.prs += 1;
+            totals.examined += 1;
+            bucket(repo).prs += 1;
+            if (rec.ci === "success") {
+                totals.ciGreen += 1;
+                bucket(repo).ciGreen += 1;
+            }
+            spendInputs.push({
+                additions: rec.additions,
+                deletions: rec.deletions,
+                markText: "",
+                tools: rec.tools,
+            });
+        }
+        const coverage = {
+            complete: stoppedBy === null &&
+                !listingCut &&
+                unreadable === 0 &&
+                reposRead === input.repos.length &&
+                !sampled,
+            stoppedBy: stoppedBy ?? (listingCut ? "read-cap" : null),
+            prsExamined: totals.examined,
+            prsSkippedLarge: skippedLarge,
+            prsUnreadable: unreadable,
+            reposRead,
+            reposTotal: input.repos.length,
+            reads: budget.reads,
+            windowStart,
+            windowEnd: endDay,
+            ...(sampled ? { windowSampledFrom: inWindow.length } : {}),
+        };
+        return {
+            status: "done",
+            result: { coverage, totals, byRepo: [...byRepo.values()], spend: estimateSpend(spendInputs) },
+        };
+    }
+    catch (e) {
+        // Reads only; the raw error is dropped and a fixed reason returned.
+        return { status: "withheld", reason: classifyFailure(e) };
+    }
+}

package/dist/lib/scan/share.d.ts

@@ -0,0 +1,38 @@
+import type { ScanResult } from "./scan.js";
+export type ShareLevel = "summary" | "full" | "none";
+export declare const SHARE_OPTIONS: ReadonlyArray<{
+    level: ShareLevel;
+    label: string;
+}>;
+/** Asks the user. Anything but a recognised answer (cancel, EOF, noise) is "none": fail closed. */
+export declare function promptShareLevel(): Promise<ShareLevel>;
+export declare function parseShareLevel(v: string | undefined): ShareLevel | null;
+/** Who receives the report. Sent only with a non-"none" share level. */
+export interface ReportRecipients {
+    runner_email: string;
+    cto_email: string;
+}
+export interface SharePayload {
+    recipients: ReportRecipients;
+    level: Exclude<ShareLevel, "none">;
+    period: {
+        start: string;
+        end: string;
+    };
+    prs: number;
+    reverts: number;
+    ci_green: number;
+    examined: number;
+    coverage_complete: boolean;
+    /** Absent when no spend line may be shown. */
+    spend_line?: string;
+    repos?: Array<{
+        repo: string;
+        prs: number;
+        reverts: number;
+        ci_green: number;
+    }>;
+}
+/** Builds only what the level allows. Never includes authors, titles, branches, bodies or tokens. The only person data is the two report recipients. */
+export declare function buildSharePayload(level: Exclude<ShareLevel, "none">, r: ScanResult, recipients: ReportRecipients, spendLine?: string | null): SharePayload;
+export declare function buildSharePayload(level: ShareLevel, r: ScanResult, recipients: ReportRecipients, spendLine?: string | null): SharePayload | null;