toolroll 0.9.94 → 0.9.96

package/dist/findings.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Findings sent to the task that owns the code (docs/plans/fleet-follow-through.md, part 1).
+ *
+ * A finding asks the owner for an answer: accepted, with what changed, or rejected, with a reason against the code.
+ * Reading one closes nothing. It stays open, and visible, until an answer counts or a person closes it, and a reviewer
+ * and an implementer get FINDING_ROUND_LIMIT rounds before it goes to a person.
+ *
+ * Trust: summary, action, excerpt and every answer can hold model output or repository text. They are data wherever
+ * they are read: quoted with `fence` for an agent, and they decide nothing. An answer ends this finding and touches no
+ * proof, check or approval, and only a signed-in person (the caller proves it) closes one.
+ */
+import { z } from "zod";
+import type { BuildFinding } from "./contracts/review-findings.js";
+import type { Store } from "./store.js";
+/** A first send and one more: then a person decides. */
+export declare const FINDING_ROUND_LIMIT = 2;
+export declare const FINDING_TEXT_LIMIT = 1000;
+export declare const FINDING_ACTION_LIMIT = 300;
+export declare const FINDING_EXCERPT_LIMIT = 2000;
+export declare const ANSWER_TEXT_LIMIT = 1000;
+export declare const ANSWER_FILE_BYTES: number;
+export declare const REVIEW_ACTION = "Check this against the code. Fix it and say what changed, or reject it with a reason that names the file.";
+export declare const CHECK_ACTION = "Find the cause of this failed check. Fix it and say what changed, or reject it with a reason that names the file.";
+/** `lead`: words the lead (a model) drafted, sent only once a person confirmed them; `sent_by` is that person. They are
+ * never recorded as the person's own words. */
+export type FindingSource = "build-review" | "person" | "lead" | "check-failure";
+export type FindingState = "open" | "accepted" | "rejected" | "with-person" | "closed";
+export type FindingAnswer = {
+    round: number;
+    run: number;
+    answer: "accepted" | "rejected";
+    detail: string;
+    file: string | null;
+    line: number | null;
+    revision: string | null;
+    state: "saved" | "counted" | "refused";
+    problem: string | null;
+    at: string;
+};
+export type Finding = {
+    id: number;
+    familyRoot: string;
+    taskId: string;
+    repo: string | null;
+    source: FindingSource;
+    sourceRun: number | null;
+    severity: "HIGH" | "MEDIUM" | "LOW" | null;
+    file: string | null;
+    line: number | null;
+    summary: string;
+    action: string;
+    excerpt: string | null;
+    revision: string | null;
+    state: FindingState;
+    rounds: number;
+    sentBy: string;
+    sentAt: string;
+    deliveredRun: number | null;
+    deliveredHow: "mailbox" | "brief" | null;
+    readAt: string | null;
+    closedBy: string | null;
+    closedNote: string | null;
+    closedAt: string | null;
+    /** The newest answer of any standing, or null. */
+    answer: FindingAnswer | null;
+};
+export declare const findingSourceWords: (source: FindingSource) => string;
+/** Who a finding's words are from, naming the person who confirmed the lead's draft: never the person as its author. */
+export declare const findingFromWords: (finding: Pick<Finding, "source" | "sentBy">) => string;
+/** The family a task belongs to: a broken history keeps the finding on the task it named. */
+export declare function familyRootOf(store: Store, taskId: string): string;
+/** One line of quotable text: controls gone, secrets gone, inside its limit. */
+export declare function cleanFindingText(text: string, limit: number): string;
+export declare function getFinding(store: Store, id: number): Finding | null;
+/** Every finding of a task's family, newest first. */
+export declare function findingsOfTask(store: Store, taskId: string): Finding[];
+/** How many of this task's family's findings used their rounds and wait on a person; none on a database not yet migrated. */
+export declare const heldFindingCount: (store: Store, taskId: string) => number;
+/** The findings still waiting on someone, across a project or everywhere. */
+export declare function waitingFindings(store: Store, repos: readonly string[] | null): Finding[];
+/** Who is reading or sending: the projects this chat reaches, and the person they must reach them as. */
+export type FindingReader = {
+    name: string;
+    repos: readonly string[];
+};
+/** Every project a task's family reaches, or null unless this person reaches all of them: one gate for every chat road to
+ * a family's findings and handover. A task with no project is out of reach. */
+export declare function familyInReach(store: Store, who: FindingReader, task: string): readonly string[] | null;
+/** The findings this person may see: a task's, only if its whole family is in reach, else those waiting in `repos`. Null
+ * for a task out of reach. A finding with no project, or one out of reach, is left out. */
+export declare function findingsInReach(store: Store, who: FindingReader, query: {
+    task?: string;
+    repos: readonly string[];
+}): Finding[] | null;
+/** The same finding, in another reviewer's words: the same file, and the same opening words or nearly the same line. */
+export declare function sameFinding(a: {
+    file: string | null;
+    line: number | null;
+    summary: string;
+}, b: {
+    file: string | null;
+    line: number | null;
+    summary: string;
+}): boolean;
+export type SendInput = {
+    taskId: string;
+    source: FindingSource;
+    by: string;
+    summary: string;
+    action?: string;
+    file?: string | null;
+    line?: number | null;
+    severity?: Finding["severity"];
+    run?: number | null;
+    excerpt?: string | null;
+    revision?: string | null;
+    /** The source's own identity: a repeat of the same key is the same finding. */
+    key?: string | null;
+};
+export type SendAnswer = {
+    ok: true;
+    id: number;
+    standing: "running" | "next-attempt" | "with-person" | "already-sent";
+    round: number;
+} | {
+    ok: false;
+    reason: "unknown-task" | "invalid" | "closed";
+    message: string;
+};
+/** Send a finding, or count a repeat of one already sent as another round. The caller proves who is sending. */
+export declare function sendFinding(store: Store, input: SendInput, now: Date): SendAnswer;
+/** Send an answered finding back to its owner: one more round, or to a person once the rounds are used. */
+export declare function resendFinding(store: Store, id: number, now: Date): SendAnswer;
+/** A person's decision on a finding. The caller has proved the person. */
+export declare function closeFinding(store: Store, id: number, by: string, note: string, now: Date): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/** The open findings of a run's family it has not been given yet. */
+export declare function undeliveredFindings(store: Store, taskRef: number, runId: number): Finding[];
+/** Recorded only after the file reached the run, or the brief named it: a pending delivery is never counted as read. */
+export declare function markFindingDelivered(store: Store, id: number, runId: number, how: "mailbox" | "brief", now: Date): boolean;
+/** The findings a fresh attempt's brief quotes, recorded as reaching it. Bounded by the caller's brief. */
+export declare function attachFindings(store: Store, taskRef: number, runId: number, now: Date): Finding[];
+/** The agent moved the file to handled/: it read it. That closes nothing. */
+export declare function markFindingRead(store: Store, id: number, runId: number, now: Date): void;
+/** An answer as an agent writes it. Its `key` proves the attempt's own folder wrote it, nothing more. */
+export declare const findingAnswerSchema: z.ZodObject<{
+    key: z.ZodString;
+    finding: z.ZodNumber;
+    answer: z.ZodEnum<{
+        accepted: "accepted";
+        rejected: "rejected";
+    }>;
+    detail: z.ZodString;
+    file: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type FindingAnswerFile = z.infer<typeof findingAnswerSchema>;
+/** Save what an attempt answered. It counts only when that attempt settles (settleFindingAnswers). A finding this run
+ * was not given, or one no longer open, takes no answer. */
+export declare function saveFindingAnswer(store: Store, runId: number, answer: FindingAnswerFile, now: Date): boolean;
+/**
+ * The attempt has settled: each answer it saved counts or is refused, against what the machine saw, not what it said.
+ * Accepted needs a commit past the revision the finding was sent about. Rejected needs a file that exists at the run's
+ * commit. A refused answer leaves the finding open, and the next attempt gets it again.
+ */
+export declare function settleFindingAnswers(store: Store, runId: number, worktree: string, now: Date): number;
+/**
+ * A finished review's HIGH findings. Sent back: each becomes a finding its revision must answer. Not sent back (a family
+ * gets one automatic send-back): a HIGH that repeats an answered finding is that finding's next round, and any other
+ * stays where it is, for the person to decide. Never at the review's expense.
+ */
+export declare function recordReviewFindings(store: Store, input: {
+    run: number;
+    taskId: string;
+    sentBackAs: string | null;
+    high: readonly BuildFinding[];
+}, now: Date): void;
+export declare const NOT_ON_TASK = "That result isn't on this task.";
+/** Whether a run belongs to this task's family. Admission proves the task named, never a run a form or flag names beside
+ * it, so every act that takes a run checks it here: no finding's text crosses a task or a project. */
+export declare function runOnTask(store: Store, runId: number, taskId: string): boolean;
+/** Send one of a result's review findings: `<run>:<number>`, counted from 1 as the result lists them. */
+export declare function sendReviewFinding(store: Store, taskId: string, pointer: string, by: string, now: Date): SendAnswer;
+/** The review finding `<run>:<number>` names, on this task's family: what a send would quote, read once for both. */
+export declare function reviewFindingAt(store: Store, taskId: string, pointer: string): {
+    ok: true;
+    run: number;
+    finding: BuildFinding;
+} | {
+    ok: false;
+    message: string;
+};
+/** Send a result's failed check, with the end of its sealed log as the evidence. The summary is Toolroll's own words. */
+export declare function sendCheckFinding(store: Store, root: string, taskId: string, runId: number, by: string, now: Date): SendAnswer;
+/** A failed check as a send would quote it. */
+export declare function checkFindingAt(store: Store, root: string, taskId: string, runId: number): {
+    ok: true;
+    summary: string;
+    head: string | null;
+    excerpt: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** The folder an attempt's answers go in, and what the brief says about writing one. Trusted words: nothing here is quoted. */
+export declare function findingAnswerRule(folder: string, key: string): string[];
+/** The findings a fresh attempt starts with, quoted as data. `answer` is the folder and key, when this attempt has one. */
+export declare function findingsBriefLines(findings: readonly Finding[], answer: {
+    folder: string;
+    key: string;
+} | null): string[];
+/** How a finding stands, for a person, in one sentence. Text after a colon is the agent's. */
+export declare function findingStandingWords(finding: Finding): string;
+/** Plain lines for `task show`, `finding list` and the handover note. */
+export declare function findingLine(finding: Finding): string;
+/** The web's door to the same gate as chat (familyInReach): the projects this person reaches are those the page can
+ * see and their account may access, and every project in the task's family must be one of them. Null: out of reach. */
+export declare function familyInWebReach(store: Store, who: {
+    name: string;
+}, task: string, visible: (repo: string | null) => boolean): readonly string[] | null;