team 0.0.1 → 0.1.1

package/dist/budgets/run.js

@@ -0,0 +1,119 @@
+// A `check` command's run and its output contract (RFC 0003 § 5). The raw output
+// lives only here: it is parsed and dropped, and never returned, logged or shown.
+// A check reads a vendor home; its bytes could carry anything the owner's tools know.
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { budgetsInForce } from "../approve/approval.js";
+import { readApproval, storePath } from "../store/store.js";
+import { checkCommands, checkReadings } from "./checks.js";
+import { resetsFrom } from "./readings.js";
+// § 5: one line, an amount with at most four decimals, an uppercase currency.
+const SPEND = /^([0-9]+(?:\.[0-9]{1,4})?) ([A-Z]{3})$/;
+// § 5: one to three lines, each a window, each figure whole and at most 100. The
+// printed reset is a duration; the printed measurement time is unix seconds.
+const LINE = /^(session|daily|weekly) (100|[0-9]{1,2})% (used|left)(?: resets ([0-9]+h(?:[0-9]+m)?|[0-9]+m))?(?: at ([0-9]{10}))?$/;
+/** An output's lines: one trailing newline allowed, and nothing else. */
+function linesOf(text) {
+    const body = text.endsWith('\n') ? text.slice(0, -1) : text;
+    return body === '' ? null : body.split('\n');
+}
+/**
+ * A subscription output against § 5. Any line off the contract, a figure over
+ * 100, or a window twice reads unknown — the whole output, not just the line.
+ * `at`, when printed, is the line's own time; a time later than the run is the run's.
+ */
+export function parseSubscription(text, now) {
+    const lines = linesOf(text);
+    if (!lines || lines.length > 3)
+        return null;
+    const windows = [];
+    for (const line of lines) {
+        const match = LINE.exec(line);
+        if (!match)
+            return null;
+        const window = match[1];
+        if (windows.some((one) => one.window === window))
+            return null;
+        const value = Number(match[2]);
+        const used = match[3] === 'used' ? value : 100 - value;
+        const at = match[5] === undefined ? now : Math.min(Number(match[5]) * 1000, now);
+        windows.push({ window, left: 100 - used, used, at, resetsAt: match[4] === undefined ? null : resetsFrom(match[4], at) });
+    }
+    return windows.length ? { kind: 'subscription', windows } : null;
+}
+/** A spend output against § 5: exactly one line, and in the floor's currency. */
+export function parseSpend(text, currency, now) {
+    const lines = linesOf(text);
+    if (!lines || lines.length !== 1)
+        return null;
+    const match = SPEND.exec(lines[0] ?? '');
+    if (!match || match[2] !== currency)
+        return null;
+    return { kind: 'spend', amount: Number(match[1]), currency: match[2], at: now };
+}
+/** One output against its account's contract. Null reads unknown for that account. */
+export function parseOutput(account, text, now) {
+    if (account.kind === 'spend')
+        return account.floor === null ? null : parseSpend(text, account.floor.currency, now);
+    return parseSubscription(text, now);
+}
+/**
+ * Runs one approved command and returns its output, or null: § 5 gives it an
+ * empty environment with PATH and HOME, a timeout, and exit 0; stderr is dropped.
+ * The timeout kills (SIGKILL: a command that traps TERM would otherwise run on,
+ * and `spawnSync` blocks the whole watch loop while it does). The command's bytes
+ * are the owner's, so they are returned to the parser only.
+ */
+export function runCommand(path, timeoutMs = 10_000) {
+    try {
+        const result = spawnSync(path, [], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: timeoutMs,
+            killSignal: 'SIGKILL',
+            env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '' },
+        });
+        if (result.error || result.status !== 0)
+            return null;
+        return result.stdout;
+    }
+    catch {
+        return null;
+    }
+}
+/** One account's reading this pass: null when the command fails, times out, or breaks its contract. */
+export function readCheck(account, path, now, timeoutMs = 10_000) {
+    const text = runCommand(path, timeoutMs);
+    return text === null ? null : parseOutput(account, text, now);
+}
+/**
+ * What each checked account reads this pass: its reading, or that it has none
+ * and why. `budgets` is the section in force: an account an unapproved edit
+ * took out is not checked, and one it changed reads under the approved entry.
+ * An account whose check is changed, missing or unapproved is not run at all
+ * (§ 5, #45). The path handed to `run` is the approved one, hashed again
+ * against the approval: the file's command is never run directly.
+ */
+export function checkOutcomes(budgets, approved, run, now) {
+    const may = new Map(checkReadings(budgets, approved).map((one) => [one.account, one.state === 'approved']));
+    const outcomes = [];
+    for (const { account } of checkCommands(budgets)) {
+        const entry = budgets.accounts[account];
+        const known = approved?.[account];
+        if (entry === undefined || known === undefined || may.get(account) !== true) {
+            outcomes.push({ account, state: 'unapproved' });
+            continue;
+        }
+        const reading = run(entry, known.path, now);
+        outcomes.push(reading === null ? { account, state: 'unreadable' } : { account, state: 'read', reading });
+    }
+    return outcomes;
+}
+/**
+ * What every checked account reads this pass, with the approval of this machine. The accounts are
+ * the ones the budgets in force name, never the file's unapproved edit of them.
+ */
+export function runChecks(team, root, now, home = homedir(), run = readCheck) {
+    const approved = readApproval(storePath(team.project, root, home))?.approval.checks;
+    return checkOutcomes(budgetsInForce(team, root, home), approved, run, now);
+}

package/dist/budgets/table.d.ts

@@ -0,0 +1,24 @@
+import type { TeamFile } from '../file/types.ts';
+import type { WindowName } from '../profiles/quota.ts';
+import { type Seen } from './readings.ts';
+export type BudgetState = 'fresh' | 'unconfirmed' | 'stale' | 'refusing' | 'unknown';
+export type BudgetRow = {
+    account: string;
+    window: WindowName | null;
+    left: number | null;
+    used: number | null;
+    resetsIn: string | null;
+    seat: string | null;
+    age: string | null;
+    source: 'status_line' | null;
+    state: BudgetState;
+    /** True when a subscription's left figure is at or inside its reserve. */
+    inside: boolean;
+    /** The reserve the row was read against, or null: the line and the JSON can't disagree. */
+    reserve: number | null;
+};
+/** Rows for the accounts the budgets in force name, and for any reading still in the state. */
+export declare function budgetTable(budgets: TeamFile['budgets'], list: readonly Seen[], now: number): BudgetRow[];
+/** An account's reserve: a subscription's own, and none for anything else. */
+export declare function reserveOf(budgets: TeamFile['budgets'], account: string): number | null;
+export declare function budgetLine(row: BudgetRow): string;

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[];