@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/ports/learning.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The records the Learning port passes, and the answers it gives: core's
+ * declaration of the six types `packages/rafa/src/ports/index.ts` names for it.
+ *
+ * The learning library declares the same six in `src/learning/types.ts`
+ * and keeps them there. `src/learning/` imports nothing from the rest of
+ * `src/`, and core imports nothing above it, so neither side can take
+ * the other's declaration: each declares its own, and
+ * `src/tests/learning-contract.test.ts` holds every pair mutually
+ * assignable, so a field added, dropped or retyped on one side alone
+ * fails to compile there.
+ *
+ * Types only, as `index.ts` and `log-level.ts` beside it are: the module
+ * holds no runtime value, so importing it runs nothing. The fields are
+ * snake case, as the distributed-learning spec spells the record a sync
+ * payload carries.
+ */
+/**
+ * One instinct: a trigger, the action to take on it, and how far to
+ * trust that action.
+ */
+export interface InstinctRecord {
+    id: string;
+    trigger: string;
+    action: string;
+    /** `sha256(trim(lower(action)))`: two records share an action by it. */
+    action_hash: string;
+    /** From 0.3 to 0.9. */
+    confidence: number;
+    /**
+     * The weight a merge gives the confidence. Once a record carries
+     * {@link InstinctRecord.sources}, it equals that list's length.
+     */
+    usage_count: number;
+    /**
+     * The distinct `source_id`s that confirmed the record. A merge takes
+     * the union, which is what makes a source pushing one record twice
+     * count once. Left out by a record written before sources were kept.
+     */
+    sources?: string[];
+    /** The recurrence key; phase 2's field. */
+    artifact?: string;
+    signal: 'loud' | 'silent';
+    /** A `flagged` record is excluded from every blessed bundle. */
+    status: 'active' | 'flagged';
+    /**
+     * The path of the page the wrap-up wrote the record into. A promoted
+     * record leaves every blessed bundle, because the page now carries it.
+     */
+    promoted_to?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * What one source pushes. Under the `local` adapter the source is the
+ * task's session id, so two tasks of one plan are two sources.
+ */
+export interface SyncPayload {
+    source_id: string;
+    instincts: InstinctRecord[];
+}
+/** What a pull answers: the instincts blessed for injection. */
+export interface BlessedBundle {
+    version: string;
+    instincts: InstinctRecord[];
+}
+/**
+ * The rule a merge applied to one incoming record, one per row of the
+ * spec's merge table plus the record whose trigger nothing shares:
+ *
+ *   - `new-trigger`: no held record shares the trigger, so it is kept.
+ *   - `same-action`: the same `action_hash`, so the confidences are
+ *     weighted by usage and the sources joined.
+ *   - `higher-confidence`: a different action, confidences more than
+ *     0.10 apart, so the higher one wins.
+ *   - `flagged`: a different action, confidences within 0.10, so both
+ *     are kept and flagged.
+ */
+export type MergeRule = 'new-trigger' | 'same-action' | 'higher-confidence' | 'flagged';
+/** Which rule applied to one incoming record, and what it produced. */
+export interface MergeDecision {
+    incoming: InstinctRecord;
+    rule: MergeRule;
+    /** The records the trigger is held as once the rule has applied. */
+    produced: InstinctRecord[];
+}
+/**
+ * What a merge did, so a consumer can log each decision.
+ *
+ * The spec names `discarded` and describes the rest, a list saying which
+ * rule applied to each incoming record and what it produced, without
+ * naming it; `decisions`, {@link MergeDecision} and the
+ * {@link MergeRule} names are the learning library's, and this module
+ * spells them as the library does.
+ */
+export interface MergeResult {
+    /** One per incoming record, in the payload's order. */
+    decisions: MergeDecision[];
+    /** The records a higher-confidence action displaced; none is deleted. */
+    discarded: InstinctRecord[];
+}

package/dist/ports/log-level.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The logger's level, in a leaf of its own so a module that needs only
+ * the level (the logger's settings, the config section that reads them)
+ * imports it without reaching the rest of `./ports`. `packages/rafa/src/ports/index.ts`
+ * re-exports it, so the `./ports` subpath names it unchanged.
+ */
+/**
+ * How loud a log entry is, or `api` for the metadata of one request and
+ * its response. `error`, `warn` and `debug` are ordered, quietest first;
+ * `api` sits outside that order and is turned on by itself. There is no
+ * `info`: that is a command's own text, which goes through `Output`.
+ */
+export type LogLevel = 'error' | 'warn' | 'debug' | 'api';

package/dist/ports/spec-review.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The shapes a spec review is read into: the verdicts and readings a
+ * `rafa:spec-review` block answers, the gaps it names and the issues it
+ * reports. Core's `Planner` port names {@link SpecReviewReading}, so they
+ * sit here, below the board; `src/board/spec-review.ts` reads the block
+ * into them, re-exports them under the same names, and keeps the parser,
+ * the headings and the two fallback gaps.
+ */
+import type { RafaBlock } from '../core/plan/block-reader.js';
+/** The two words the block's `verdict` is spelled with. */
+export declare const SPEC_REVIEW_VERDICTS: readonly ["ready", "not-ready"];
+/** One of the two verdicts a session can write. */
+export type SpecReviewVerdict = (typeof SPEC_REVIEW_VERDICTS)[number];
+/**
+ * The four readings a session output answers. The first two are the
+ * verdicts as written; the last two are a block that could not be read,
+ * and are not-ready all the same.
+ */
+export declare const SPEC_REVIEW_ANSWERS: readonly ["ready", "not-ready", "absent", "malformed"];
+/** One of the four readings; see {@link SPEC_REVIEW_ANSWERS}. */
+export type SpecReviewAnswer = (typeof SPEC_REVIEW_ANSWERS)[number];
+/** One thing the planner found keeping a spec from being planned from. */
+export interface SpecReviewGap {
+    /** The spec heading it sits under, as the comment names it. */
+    readonly heading: string;
+    /** What is wrong under that heading, as the session wrote it. */
+    readonly what: string;
+    /**
+     * True when guessing wrong here changes what ships or what is safe,
+     * so nothing can be planned until the spec answers it. True for
+     * every gap whose `blocking` was unreadable and for every
+     * non-blocking one that named no assumption; see the module note.
+     */
+    readonly blocking: boolean;
+    /**
+     * What the planner would plan under, as the session wrote it. Never
+     * null for a gap that is not blocking; null for a blocking gap that
+     * named none.
+     */
+    readonly assumption: string | null;
+}
+/** One thing the block said that this reading does not hold as written. */
+export interface SpecReviewIssue {
+    /** Where, in the block's own key names: `gaps[2].what`. */
+    readonly field: string;
+    /** One sentence for an operator to read. */
+    readonly text: string;
+}
+/** A session output, read for its `rafa:spec-review` block. */
+export interface SpecReviewReading {
+    /** Which of the four readings this is. */
+    readonly answer: SpecReviewAnswer;
+    /** True for `ready` alone; what the gate acts on. */
+    readonly ready: boolean;
+    /**
+     * Every gap to post. Empty only for a ready reading; see the module
+     * note for what fills it when the session named none.
+     */
+    readonly gaps: readonly SpecReviewGap[];
+    /** The last `rafa:spec-review` block, or null when there is none. */
+    readonly block: RafaBlock | null;
+    /** One sentence for an operator to read. */
+    readonly text: string;
+    /** What was not read as written. Empty for a clean block. */
+    readonly issues: readonly SpecReviewIssue[];
+}

package/dist/pr/checks.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The check-row readers of a pull request: raw `gh pr checks` output in,
+ * one verdict out.
+ *
+ * A PR is not finished until CI has spoken about it, and two failure
+ * shapes made that worth automating rather than leaving to the session's
+ * judgement:
+ *
+ *  - A CONFLICTING PR schedules no workflow run at all, because GitHub
+ *    cannot build `refs/pull/<n>/merge` for a branch that does not merge
+ *    cleanly. The loop would report a finished plan whose code had never
+ *    been through CI once.
+ *  - A resolved conflict can still red the whole battery at its first
+ *    step (a lockfile out of step with the merged manifests fails
+ *    `bun install --frozen-lockfile`, and nothing downstream runs).
+ *
+ * Both are invisible from inside the session that pushed.
+ *
+ * ## Zero rows is two readings, and the head's age tells them apart
+ *
+ * GitHub registers a push's runs some seconds after the push, so a poll
+ * in that gap reads zero rows off a pull request whose checks are about
+ * to appear. Zero rows on an OLD head is the settled reading above: no
+ * run is coming. So a caller that knows when the head was committed
+ * hands that time over ({@link WaitOptions.headCommittedAtMs}), and zero
+ * rows on a head younger than {@link FIRST_CHECK_GRACE_MS} is polled
+ * again like a pending reading. A caller that hands over no time gets
+ * `none` on the first poll, as every caller did before the grace
+ * existed: the loop's CI gate and `pr triage --resolve` hand over none.
+ *
+ * The time is the head commit's COMMITTED date, which is not the push
+ * time: a commit made an hour ago and pushed just now reads as old and
+ * gets no grace. A provider answers a committed date and no push time,
+ * and the wrong direction of that error is the cheap one, since it is
+ * the behaviour there was before.
+ *
+ * Everything here is pure: the only effect {@link waitForChecks} has is
+ * the `probe` handed to it, and its clock and its wait are injected too,
+ * so the polling logic is testable without a network or a timer. The
+ * `gh` invocations that feed it live with the rest of the port, not
+ * here, which is what keeps `checks.test.ts` free of a process spawn.
+ *
+ * {@link waitForChecks} polls ROWS rather than stdout, so the poll runs
+ * over `PullRequests.checks` (`./types.ts`) without either side naming
+ * the CLI. {@link parseChecks} is what turns one provider's stdout into
+ * those rows, and the `gh` adapter is its only caller.
+ *
+ * The row type, the verdict type, {@link verdictOf} and `failingRows`
+ * are core's (`packages/rafa/src/effort/store/check-rows.ts`), where the store's plan
+ * CI writer reads them; this file re-exports them under the same names.
+ */
+import type { CheckOutcome, CheckRow, ChecksVerdict } from '@open-tomato/rafa/store/check-rows';
+export type { CheckOutcome, CheckRow, ChecksVerdict } from '@open-tomato/rafa/store/check-rows';
+export { failingRows, verdictOf } from '@open-tomato/rafa/store/check-rows';
+/**
+ * Maps a GitHub check state onto an outcome.
+ *
+ * An UNRECOGNISED state counts as pending on purpose: the alternative is
+ * declaring a run green on a state nobody classified, and a wrong green
+ * here lands a plan whose CI never agreed. Waiting is recoverable — the
+ * deadline ends it and the raw state is printed in the summary.
+ */
+export declare function classifyState(state: string): CheckOutcome;
+/**
+ * Parses `gh pr checks --json name,state,link` output into rows.
+ *
+ * Returns an empty list for anything that is not a JSON array — `gh`
+ * writes a plain `no checks reported` message and exits non-zero when a
+ * PR has none, and that is a verdict here rather than an error.
+ */
+export declare function parseChecks(stdout: string): CheckRow[];
+/** One line per check, for the console and for a repair prompt. */
+export declare function formatRows(rows: readonly CheckRow[]): string;
+/**
+ * How long after a head commit zero rows still reads as "no check has
+ * registered yet" rather than "no check is coming": two minutes.
+ *
+ * Measured from the head commit's committed date, by the clock
+ * {@link waitForChecks} was handed. It is a ceiling on one wait as well:
+ * a head dated ahead of that clock is held no longer than this from the
+ * wait's own first poll.
+ */
+export declare const FIRST_CHECK_GRACE_MS = 120000;
+export interface WaitOptions {
+    /**
+     * The rows of one poll. A caller on the port hands
+     * `PullRequests.checks` here, and a caller holding raw
+     * `gh pr checks --json ...` stdout hands {@link parseChecks} of it.
+     */
+    probe: () => Promise<readonly CheckRow[]>;
+    timeoutMs: number;
+    intervalMs: number;
+    /** Injected for tests; defaults to the real clock. */
+    now?: () => number;
+    /** Injected for tests; defaults to a real timer. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Called after every poll, for progress output. The verdict is the one
+     * the wait acts on, so a poll of zero rows the grace holds is reported
+     * `pending`, which is why it is polled again.
+     */
+    onPoll?: (rows: readonly CheckRow[], verdict: ChecksVerdict, elapsedMs: number) => void;
+    /**
+     * When the pull request's head was committed, in the milliseconds
+     * `now` answers in. Handed over, zero rows on a head younger than
+     * {@link FIRST_CHECK_GRACE_MS} is polled again; left out, or a value
+     * that is no finite number, zero rows ends `none` on the first poll.
+     */
+    headCommittedAtMs?: number;
+}
+export interface WaitResult {
+    /** `timeout` means the deadline passed while checks were still running. */
+    verdict: ChecksVerdict | 'timeout';
+    rows: readonly CheckRow[];
+    elapsedMs: number;
+    polls: number;
+}
+/**
+ * Polls a PR's checks until they settle, the deadline passes, or the PR
+ * reports no checks at all.
+ *
+ * `none` returns rather than waiting out the deadline: a PR with no
+ * checks is conflicting, has no workflow matching its changed paths, or
+ * was pushed so recently that none has registered. Only the last
+ * resolves by waiting, and only for {@link FIRST_CHECK_GRACE_MS}, so
+ * zero rows is polled again while {@link WaitOptions.headCommittedAtMs}
+ * says the head is that young and ends `none` otherwise. The caller
+ * tells the first two apart, since only it knows the merge state.
+ *
+ * A deadline that passes inside the grace ends `timeout`, with no rows,
+ * as it does for any reading that was still being polled.
+ */
+export declare function waitForChecks(options: WaitOptions): Promise<WaitResult>;