team 0.0.1 → 0.1.0

package/dist/budgets/table.js

@@ -0,0 +1,90 @@
+import { verdict } from "./readings.js";
+const WINDOWS = ['session', 'daily', 'weekly'];
+/** Rows for the accounts the budgets in force name, and for any reading still in the state. */
+export function budgetTable(budgets, list, now) {
+    const staleAfterMs = budgets.staleAfter * 1000;
+    const groups = new Map();
+    for (const reading of list) {
+        const key = `${reading.account}\0${reading.window}`;
+        const group = groups.get(key) ?? [];
+        group.push(reading);
+        groups.set(key, group);
+    }
+    const rows = [];
+    const named = new Set();
+    for (const [key, group] of groups) {
+        const account = key.slice(0, key.indexOf('\0'));
+        const window = group[0]?.window ?? null;
+        named.add(account);
+        const reserve = reserveOf(budgets, account);
+        rows.push(rowOf(account, window, verdict(group, now, staleAfterMs, reserve), now, reserve));
+    }
+    for (const account of Object.keys(budgets.accounts)) {
+        if (!named.has(account))
+            rows.push(blank(account, reserveOf(budgets, account)));
+    }
+    return rows.sort(byAccount);
+}
+/** An account's reserve: a subscription's own, and none for anything else. */
+export function reserveOf(budgets, account) {
+    const entry = budgets.accounts[account];
+    return entry?.kind === 'subscription' ? entry.reserve : null;
+}
+export function budgetLine(row) {
+    if (row.state === 'unknown' || row.left === null || row.used === null) {
+        return [row.account, row.window, 'unknown'].filter((part) => part).join('  ');
+    }
+    const reset = row.resetsIn === null ? 'resets unknown' : `resets in ${row.resetsIn}`;
+    const from = row.source === 'status_line' ? 'status line' : 'unknown source';
+    const state = row.inside && row.reserve !== null ? `${row.state}, inside reserve ${row.reserve}%` : row.state;
+    return `${row.account}  ${row.window}  left ${row.left}%  used ${row.used}%  ${reset}  ${row.seat}  changed ${row.age} ago  ${from}  ${state}`;
+}
+function rowOf(account, window, result, now, reserve) {
+    if (result.kind === 'unknown')
+        return { ...blank(account, reserve), window };
+    const reading = result.reading;
+    return {
+        account,
+        window: reading.window,
+        left: reading.left,
+        used: reading.used,
+        resetsIn: reading.resetsAt === null ? null : span(reading.resetsAt - now),
+        seat: reading.seat,
+        age: span(now - reading.changedAt),
+        source: 'status_line',
+        state: result.kind,
+        inside: reserve !== null && reading.left <= reserve,
+        reserve,
+    };
+}
+function blank(account, reserve) {
+    return {
+        account,
+        window: null,
+        left: null,
+        used: null,
+        resetsIn: null,
+        seat: null,
+        age: null,
+        source: null,
+        state: 'unknown',
+        inside: false,
+        reserve,
+    };
+}
+function byAccount(a, b) {
+    if (a.account !== b.account)
+        return a.account < b.account ? -1 : 1;
+    const rank = (window) => (window === null ? WINDOWS.length : WINDOWS.indexOf(window));
+    return rank(a.window) - rank(b.window);
+}
+function span(ms) {
+    const minutes = Math.max(0, Math.floor(ms / 60_000));
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    if (hours && rest)
+        return `${hours}h${rest}m`;
+    if (hours)
+        return `${hours}h`;
+    return `${minutes}m`;
+}

package/dist/caller.d.ts

@@ -0,0 +1,48 @@
+import type { TeamFile } from './file/types.ts';
+import type { HerdrAgent } from './herdr.ts';
+import type { Io } from './io.ts';
+export type Caller = {
+    kind: 'owner';
+} | {
+    kind: 'seat';
+    name: string;
+    pane: string;
+} | {
+    kind: 'unplaced';
+    reason: string;
+};
+export type Process = {
+    pid: number;
+    name: string;
+};
+export type CallerSources = {
+    ancestors(): Process[] | null;
+    agents(): HerdrAgent[] | null;
+    paneRootPid(pane: string): number | null;
+    env: Record<string, string | undefined>;
+    stdinIsTTY: boolean;
+};
+export declare function placeCaller(sources: CallerSources): Caller;
+export declare function isOwner(caller: Caller): boolean;
+export declare function mayChangeTeam(caller: Caller, team: Pick<TeamFile, 'coordinator' | 'operator'>): boolean;
+export declare function describeCaller(caller: Caller): string;
+export type ReadProcess = (pid: number) => {
+    ppid: number;
+    name: string;
+} | null;
+export declare const readWithPs: ReadProcess;
+export declare function parseStat(text: string): {
+    ppid: number;
+    name: string;
+} | null;
+export declare function readWithProc(pid: number, proc?: string): {
+    ppid: number;
+    name: string;
+} | null;
+export declare function processReader(platform?: string): ReadProcess;
+export declare function readAncestors(pid?: number, read?: ReadProcess): Process[] | null;
+export declare function callerOf(io: Pick<Io, 'env' | 'stdinIsTTY' | 'caller'>, session?: string): Caller;
+export declare function currentCaller(io: {
+    env: Record<string, string | undefined>;
+    stdinIsTTY: boolean;
+}, session?: string): Caller;

package/dist/caller.js

@@ -0,0 +1,126 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { agentList, paneRootPid } from "./herdr.js";
+import { CLI_PROCESSES } from "./clis.js";
+export function placeCaller(sources) {
+    const ancestors = sources.ancestors();
+    // A walk that stopped early may have stopped below a herdr server: it places nobody.
+    if (!ancestors?.length)
+        return { kind: 'unplaced', reason: 'its parent processes can\'t be read to the top' };
+    const pids = new Set(ancestors.map((process) => process.pid));
+    if (ancestors.some((process) => process.name === 'herdr')) {
+        const agents = sources.agents();
+        if (!agents)
+            return { kind: 'unplaced', reason: 'it runs under herdr, and herdr doesn\'t answer' };
+        // The variable only says which pane to read first; the pids decide.
+        const hint = sources.env.HERDR_PANE_ID;
+        const ordered = [...agents].sort((a, b) => Number(b.pane === hint) - Number(a.pane === hint));
+        for (const agent of ordered) {
+            const root = sources.paneRootPid(agent.pane);
+            if (root === null || !pids.has(root))
+                continue;
+            if (agent.name)
+                return { kind: 'seat', name: agent.name, pane: agent.pane };
+            return { kind: 'unplaced', reason: `it runs in pane ${agent.pane}, whose agent has no herdr name` };
+        }
+        return { kind: 'unplaced', reason: 'it runs in a herdr pane without an agent' };
+    }
+    const cli = ancestors.find((process) => CLI_PROCESSES.includes(process.name));
+    if (cli)
+        return { kind: 'unplaced', reason: `it is run by an agent (${cli.name}) outside herdr` };
+    if (sources.env.AGENT_UNATTENDED)
+        return { kind: 'unplaced', reason: 'AGENT_UNATTENDED is set' };
+    if (!sources.stdinIsTTY)
+        return { kind: 'unplaced', reason: 'it doesn\'t run on a terminal' };
+    return { kind: 'owner' };
+}
+export function isOwner(caller) {
+    return caller.kind === 'owner';
+}
+// The owner, or the coordinator's or the operator's seat: who may change a running team.
+export function mayChangeTeam(caller, team) {
+    if (caller.kind === 'owner')
+        return true;
+    return caller.kind === 'seat' && (caller.name === team.coordinator || caller.name === team.operator);
+}
+export function describeCaller(caller) {
+    if (caller.kind === 'owner')
+        return 'owner';
+    if (caller.kind === 'seat')
+        return caller.name;
+    return `unplaced (${caller.reason})`;
+}
+// A process's name, however the platform spells it: ps prints a path, /proc a bare name, and a
+// login shell leads with a dash.
+function processName(raw) {
+    return basename(raw).replace(/^-/, '');
+}
+export const readWithPs = (pid) => {
+    try {
+        const line = execFileSync('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        const match = /^(\d+)\s+(.+)$/.exec(line);
+        return match ? { ppid: Number(match[1]), name: processName(match[2]) } : null;
+    }
+    catch {
+        return null;
+    }
+};
+// "10 (herdr) S 1 10 …", one line of /proc/<pid>/stat: the name in parentheses — it can hold
+// spaces and parentheses, so the last of them closes it — then the state, then the parent.
+export function parseStat(text) {
+    const open = text.indexOf('(');
+    const close = text.lastIndexOf(')');
+    if (open < 0 || close < open)
+        return null;
+    const after = text.slice(close + 1).trim().split(/\s+/);
+    const ppid = Number(after[1]);
+    if (!Number.isInteger(ppid) || ppid < 0)
+        return null;
+    const name = processName(text.slice(open + 1, close));
+    return name ? { ppid, name } : null;
+}
+// One process, from Linux's own table. `proc` is the /proc root, a parameter so a test can walk a
+// captured one.
+export function readWithProc(pid, proc = '/proc') {
+    try {
+        return parseStat(readFileSync(`${proc}/${pid}/stat`, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// The table this platform keeps: Linux answers from /proc, every other system through ps.
+export function processReader(platform = process.platform) {
+    return platform === 'linux' ? readWithProc : readWithPs;
+}
+// The parent processes of `pid`, nearest first, up to the system's first process. Null when a
+// process on the way can't be read, or the chain is longer than any real one: a partial list
+// could hide the herdr server above it.
+export function readAncestors(pid = process.ppid, read = processReader()) {
+    const out = [];
+    let at = pid;
+    for (let depth = 0; depth < 64; depth++) {
+        if (at <= 1)
+            return out;
+        const found = read(at);
+        if (!found)
+            return null;
+        out.push({ pid: at, name: found.name });
+        at = found.ppid;
+    }
+    return null;
+}
+// The caller of a command: the one a test handed in, or the one the processes show.
+export function callerOf(io, session) {
+    return io.caller ?? currentCaller(io, session);
+}
+export function currentCaller(io, session) {
+    return placeCaller({
+        ancestors: () => readAncestors(),
+        agents: () => agentList(session),
+        paneRootPid: (pane) => paneRootPid(pane, session),
+        env: io.env,
+        stdinIsTTY: io.stdinIsTTY,
+    });
+}

package/dist/check/config.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What `check` needs from a validated team file: the `identity` section with
+ * its defaults applied, and the seats whose signatures are accepted.
+ */
+import type { Position, TeamFile } from '../file/types.ts';
+/** One `display` and `role` the team has had, with the fields a template may use. */
+export interface SeatIdentity {
+    display: string;
+    role: string;
+    model: string;
+    version: string;
+}
+export interface SignatureRule {
+    template: string;
+    position: Position;
+}
+export interface CheckConfig {
+    /** Whether `forbiddenPublic` applies. */
+    public: boolean;
+    commits: SignatureRule & {
+        exemptMerge: boolean;
+    };
+    pullRequests: SignatureRule;
+    /** Author emails whose commits need no signature. */
+    humans: string[];
+    /** A commit: it and everything reachable from it are skipped. */
+    since?: string;
+    /** The file's patterns; the defaults are added by `forbiddenPatterns`. */
+    forbidden: string[];
+    forbiddenPublic: string[];
+    /** Every seat whose signature is accepted. */
+    ledger: SeatIdentity[];
+}
+/**
+ * What `check` reads of a validated file. The accepted signatures are those
+ * of the file's seats and of the ledger: every seat the team has had, so the
+ * commits of a removed or temporary seat, or of a seat before a version
+ * change, still pass.
+ */
+export declare function fromTeamFile(team: TeamFile, ledger?: readonly SeatIdentity[]): CheckConfig;
+export interface ForbiddenPattern {
+    source: string;
+    regex: RegExp;
+}
+/**
+ * The patterns that apply to this project: the defaults (a validated file
+ * already lists them; they are never left out), the file's, and the public
+ * ones when the project is public. Throws on a pattern that isn't a
+ * regular expression.
+ */
+export declare function forbiddenPatterns(config: CheckConfig): ForbiddenPattern[];

package/dist/check/config.js

@@ -0,0 +1,50 @@
+/**
+ * What `check` needs from a validated team file: the `identity` section with
+ * its defaults applied, and the seats whose signatures are accepted.
+ */
+import { DEFAULT_FORBIDDEN } from "../file/signature.js";
+import { mergeLedger } from "../store/store.js";
+/**
+ * What `check` reads of a validated file. The accepted signatures are those
+ * of the file's seats and of the ledger: every seat the team has had, so the
+ * commits of a removed or temporary seat, or of a seat before a version
+ * change, still pass.
+ */
+export function fromTeamFile(team, ledger = []) {
+    const { identity } = team;
+    return {
+        public: team.visibility === 'public',
+        commits: {
+            template: identity.signature.commits.template,
+            position: identity.signature.commits.position,
+            exemptMerge: identity.signature.commits.exempt.includes('merge'),
+        },
+        pullRequests: identity.signature.pullRequests,
+        humans: identity.humans,
+        since: identity.since ?? undefined,
+        forbidden: identity.forbidden,
+        forbiddenPublic: identity.forbiddenPublic,
+        ledger: mergeLedger(ledger, team.seats),
+    };
+}
+/**
+ * The patterns that apply to this project: the defaults (a validated file
+ * already lists them; they are never left out), the file's, and the public
+ * ones when the project is public. Throws on a pattern that isn't a
+ * regular expression.
+ */
+export function forbiddenPatterns(config) {
+    const sources = [...DEFAULT_FORBIDDEN, ...config.forbidden, ...(config.public ? config.forbiddenPublic : [])];
+    const patterns = [];
+    for (const source of new Set(sources)) {
+        let regex;
+        try {
+            regex = new RegExp(source);
+        }
+        catch (error) {
+            throw new Error(`forbidden pattern ${JSON.stringify(source)} is not a regular expression: ${error.message}`);
+        }
+        patterns.push({ source, regex });
+    }
+    return patterns;
+}

package/dist/check/git.d.ts

@@ -0,0 +1,27 @@
+/** A git command that failed, or a ref that can't be used. */
+export declare class GitError extends Error {
+}
+export interface Commit {
+    hash: string;
+    parents: string[];
+    authorEmail: string;
+    subject: string;
+    message: string;
+    /** The lines of the final trailer block as git reads it; empty when it sees none. */
+    trailers: string[];
+}
+export interface Selection {
+    /** The commits to check, newest first. */
+    commits: Commit[];
+    /** Commits of the range that `since` leaves out. */
+    skipped: number;
+    /** `since` as a commit hash, when one applies. */
+    since?: string;
+}
+/**
+ * The commits `check` reads for `<ref>`: the range as given when it holds
+ * `..`, else that one commit, without what is reachable from `since`.
+ * An empty or unresolvable range is an error, and so is a `since` that isn't
+ * reachable from the range.
+ */
+export declare function selectCommits(cwd: string, ref: string, since?: string): Selection;

package/dist/check/git.js

@@ -0,0 +1,97 @@
+import { spawnSync } from 'node:child_process';
+/** A git command that failed, or a ref that can't be used. */
+export class GitError extends Error {
+}
+/** Set for every call, so the machine's git configuration can't change what is read. */
+const CONFIGURATION = ['log.showSignature=false', 'i18n.logOutputEncoding=UTF-8', 'trailer.separators=:'].flatMap((setting) => ['-c', setting]);
+function run(cwd, args) {
+    const result = spawnSync('git', [...CONFIGURATION, ...args], {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024 * 1024,
+    });
+    if (result.error)
+        throw new GitError(`can't run git: ${result.error.message}`);
+    return { status: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+}
+function git(cwd, args) {
+    const result = run(cwd, args);
+    if (result.status !== 0) {
+        throw new GitError(result.stderr.trim() || `git ${args[0]} exited ${result.status}`);
+    }
+    return result.stdout;
+}
+function refuseOption(ref, what) {
+    if (ref === '' || ref.startsWith('-'))
+        throw new GitError(`${what} ${JSON.stringify(ref)} is not a ref`);
+}
+/** The revision arguments for `<ref>`: a range as given, or that one commit. */
+function revision(cwd, ref) {
+    refuseOption(ref, 'the ref');
+    if (ref.includes('..'))
+        return ref;
+    const result = run(cwd, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`]);
+    if (result.status !== 0)
+        throw new GitError(`${JSON.stringify(ref)} doesn't name a commit`);
+    return `${result.stdout.trim()}^!`;
+}
+/** The commits a range starts from: what `rev-parse` gives without a `^`. */
+function tips(cwd, range) {
+    const result = run(cwd, ['rev-parse', '--revs-only', '--end-of-options', range]);
+    if (result.status !== 0 || result.stdout.trim() === '') {
+        throw new GitError(`the range ${JSON.stringify(range)} can't be resolved`);
+    }
+    return result.stdout.split('\n').filter((line) => line !== '' && !line.startsWith('^'));
+}
+const FIELDS = 6;
+const FORMAT = ['%H', '%P', '%ae', '%s', '%B', '%(trailers)'].map((field) => `${field}%x00`).join('');
+function parseLog(output) {
+    const fields = output.split('\0');
+    const commits = [];
+    for (let index = 0; index + FIELDS <= fields.length; index += FIELDS) {
+        const [hash, parents, authorEmail, subject, message, trailers] = fields.slice(index, index + FIELDS);
+        commits.push({
+            // Each record ends with a newline, which lands before the next hash.
+            hash: hash.trim(),
+            parents: parents.split(' ').filter(Boolean),
+            authorEmail,
+            subject,
+            message,
+            trailers: trailers.split('\n').filter((line) => line.trim() !== ''),
+        });
+    }
+    return commits;
+}
+/**
+ * The commits `check` reads for `<ref>`: the range as given when it holds
+ * `..`, else that one commit, without what is reachable from `since`.
+ * An empty or unresolvable range is an error, and so is a `since` that isn't
+ * reachable from the range.
+ */
+export function selectCommits(cwd, ref, since) {
+    const inside = run(cwd, ['rev-parse', '--git-dir']);
+    if (inside.status !== 0)
+        throw new GitError('not in a git repository');
+    const range = revision(cwd, ref);
+    const from = tips(cwd, range);
+    const total = Number(git(cwd, ['rev-list', '--count', '--end-of-options', range]).trim());
+    if (total === 0)
+        throw new GitError(`the range ${JSON.stringify(ref)} holds no commit`);
+    const revisions = [range];
+    let sinceHash;
+    if (since !== undefined) {
+        refuseOption(since, 'since');
+        const resolved = run(cwd, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${since}^{commit}`]);
+        if (resolved.status !== 0) {
+            throw new GitError(`since ${JSON.stringify(since)} doesn't name a commit here (a shallow clone doesn't hold the history it needs)`);
+        }
+        sinceHash = resolved.stdout.trim();
+        const reachable = from.some((tip) => run(cwd, ['merge-base', '--is-ancestor', sinceHash, tip]).status === 0);
+        if (!reachable) {
+            throw new GitError(`since ${JSON.stringify(since)} is not reachable from ${JSON.stringify(ref)}`);
+        }
+        revisions.push(`^${sinceHash}`);
+    }
+    const commits = parseLog(git(cwd, ['log', '--no-color', `--format=tformat:${FORMAT}`, '--end-of-options', ...revisions]));
+    return { commits, skipped: total - commits.length, since: sinceHash };
+}

package/dist/check/message.d.ts

@@ -0,0 +1,27 @@
+import type { ForbiddenPattern, SeatIdentity, SignatureRule } from './config.ts';
+export type FindingKind = 'forbidden' | 'signature-missing' | 'signature-misplaced' | 'signature-in-prose' | 'signature-unknown';
+export interface Finding {
+    kind: FindingKind;
+    message: string;
+    /** 1-based line of the commit message or PR body, when the finding has one. */
+    line?: number;
+    /** The offending line. */
+    text?: string;
+}
+/** The text's lines, trailing spaces trimmed. */
+export declare function splitLines(text: string): string[];
+/** Every line that matches a forbidden pattern. */
+export declare function findForbidden(lines: readonly string[], patterns: readonly ForbiddenPattern[]): Finding[];
+export interface SignatureInput {
+    lines: readonly string[];
+    rule: SignatureRule;
+    ledger: readonly SeatIdentity[];
+    /**
+     * For a commit: the lines of the final trailer block as git reads it, empty
+     * when git sees none. Absent for a PR body, where `trailer` means the last
+     * paragraph.
+     */
+    trailers?: readonly string[];
+}
+/** Empty when the text carries a signature of the team's at the position the rule says. */
+export declare function checkSignature(input: SignatureInput): Finding[];

package/dist/check/message.js

@@ -0,0 +1,101 @@
+import { renderings, shape } from "./signature.js";
+/** The text's lines, trailing spaces trimmed. */
+export function splitLines(text) {
+    return text.split(/\r?\n/).map((line) => line.trimEnd());
+}
+/** Every line that matches a forbidden pattern. */
+export function findForbidden(lines, patterns) {
+    const findings = [];
+    lines.forEach((text, index) => {
+        for (const pattern of patterns) {
+            if (pattern.regex.test(text)) {
+                findings.push({
+                    kind: 'forbidden',
+                    message: `forbidden pattern ${pattern.source}`,
+                    line: index + 1,
+                    text,
+                });
+            }
+        }
+    });
+    return findings;
+}
+/** The indexes of the last run of non-empty lines: [start, end). */
+function lastParagraph(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1] === '')
+        end--;
+    let start = end;
+    while (start > 0 && lines[start - 1] !== '')
+        start--;
+    return [start, end];
+}
+const TRAILER_LINE = /^[A-Za-z0-9-]+\s*:\s*\S/;
+const WHERE = {
+    'last-line': { commit: 'the last line', pr: 'the last line' },
+    trailer: { commit: 'the final trailer block', pr: 'the last paragraph' },
+    anywhere: { commit: 'a line of its own', pr: 'a line of its own' },
+};
+/** Empty when the text carries a signature of the team's at the position the rule says. */
+export function checkSignature(input) {
+    const { lines, rule, ledger, trailers } = input;
+    const accepted = renderings(rule.template, ledger);
+    const [start, end] = lastParagraph(lines);
+    const where = WHERE[rule.position][trailers ? 'commit' : 'pr'];
+    let candidates;
+    if (rule.position === 'last-line')
+        candidates = lines.slice(Math.max(end - 1, 0), end);
+    else if (rule.position === 'anywhere')
+        candidates = lines;
+    else
+        candidates = trailers ? trailers.map((line) => line.trimEnd()) : lines.slice(start, end);
+    if (candidates.some((line) => accepted.has(line)))
+        return [];
+    const signed = lines.findIndex((line) => accepted.has(line));
+    if (signed !== -1) {
+        const text = lines[signed];
+        const inLastParagraph = signed >= start && signed < end;
+        if (trailers && rule.position === 'trailer' && inLastParagraph) {
+            const prose = lines.slice(start, end).filter((line) => !TRAILER_LINE.test(line));
+            if (prose.length > 0) {
+                return [
+                    {
+                        kind: 'signature-in-prose',
+                        message: `the signature shares its paragraph with prose (${prose.map((line) => JSON.stringify(line)).join(', ')}), ` +
+                            'so git reads no trailer block: put it in a paragraph of its own, with trailers only',
+                        line: signed + 1,
+                        text,
+                    },
+                ];
+            }
+        }
+        return [
+            {
+                kind: 'signature-misplaced',
+                message: `the signature is not in ${where}`,
+                line: signed + 1,
+                text,
+            },
+        ];
+    }
+    const form = shape(rule.template);
+    const unknown = [];
+    lines.forEach((text, index) => {
+        if (form.test(text)) {
+            unknown.push({
+                kind: 'signature-unknown',
+                message: 'a signature no seat of this team has had (the model, the version and the role must all match one seat)',
+                line: index + 1,
+                text,
+            });
+        }
+    });
+    if (unknown.length > 0)
+        return unknown;
+    return [
+        {
+            kind: 'signature-missing',
+            message: `no signature: expected ${JSON.stringify(rule.template)} in ${where}`,
+        },
+    ];
+}

package/dist/check/run.d.ts

@@ -0,0 +1,31 @@
+import { type CheckConfig } from './config.ts';
+import { type Finding } from './message.ts';
+export interface CheckOptions {
+    /** A folder of the repository to read. */
+    cwd: string;
+    /** A range when it holds `..`, else one commit. */
+    ref: string;
+    /** Overrides the file's `identity.since` for this run. */
+    since?: string;
+    /** A pull request's body, to check as well. */
+    pullRequestBody?: string;
+}
+export interface CommitReport {
+    hash: string;
+    subject: string;
+    /** Why the commit needs no signature; its forbidden patterns are still checked. */
+    exempt?: 'merge' | 'human';
+    findings: Finding[];
+}
+export interface CheckReport {
+    commits: CommitReport[];
+    skipped: number;
+    since?: string;
+    /** Present when a PR body was checked. */
+    pullRequest?: Finding[];
+    ok: boolean;
+}
+/** Checks the commits of `ref`, and a PR body when one is given. Read only. */
+export declare function runCheck(config: CheckConfig, options: CheckOptions): CheckReport;
+/** The report as `check` prints it: each offending commit and line, then a summary. */
+export declare function formatReport(report: CheckReport): string;