@alecsibilia/luca 14.0.0-alpha.2 → 14.0.0-alpha.21

package/engine/journal/final-review-round.ts

@@ -0,0 +1,320 @@
+/**
+ * A final review round as replay rebuilds it: lens results with namespaced
+ * finding ids, the round settling once every due lens is in, and the
+ * fixers' answers to its fix round.
+ */
+import omit from 'lodash/omit'
+
+import {
+    badTestOf,
+    declinedBy,
+    fixerAnswered,
+    handoffAnswered,
+    handoffRole,
+    type FinishedContent,
+} from './agent-turn-replay'
+import type { FinalFinding, FinalReviewState } from './final-review-state'
+import { setupChangeOf } from './ticket-result-replay'
+
+import {
+    isBlocking,
+    lensOf,
+    type Finding,
+    type LensName,
+    type LensReviewResult,
+} from '../agents/role-results'
+
+/**
+ * A lens's finding id, namespaced by its lens (`<lens>-<id>`), since lenses
+ * choose their ids on their own. An id that already starts with the lens's
+ * prefix is kept, so a re-review listing a finding again keeps its id.
+ */
+export const namespacedId = ({
+    lens,
+    id,
+}: {
+    lens: LensName
+    id: string
+}): string => (id.startsWith(`${lens}-`) ? id : `${lens}-${id}`)
+
+/** A lens's result with every finding and ruling id namespaced. */
+const namespaced = ({
+    lens,
+    result,
+}: {
+    lens: LensName
+    result: LensReviewResult
+}): LensReviewResult => ({
+    ...result,
+    findings: result.findings.map((entry) => ({
+        ...entry,
+        id: namespacedId({ lens, id: entry.id }),
+    })),
+    rulings: result.rulings.map((entry) => ({
+        ...entry,
+        finding_id: namespacedId({ lens, id: entry.finding_id }),
+    })),
+})
+
+/**
+ * A fresh-pass finding's id (#548). The fresh lenses see no earlier
+ * findings, so an id they choose may already name a different earlier nit
+ * or declined finding: such an id gets `fresh-` after its lens prefix. The
+ * same nit found again keeps its id, so the PR lists it once.
+ */
+const freshId = ({
+    lens,
+    finding,
+    earlier,
+}: {
+    lens: LensName
+    finding: Finding
+    earlier: Finding[]
+}): string => {
+    const clash = earlier.find(({ id }) => id === finding.id)
+    if (clash === undefined) return finding.id
+    const sameNit =
+        !isBlocking(clash) &&
+        !isBlocking(finding) &&
+        clash.title === finding.title &&
+        clash.file === finding.file
+    return sameNit
+        ? finding.id
+        : `${lens}-fresh-${finding.id.slice(lens.length + 1)}`
+}
+
+/**
+ * A lens's result, namespaced, with its finding ids kept apart from the
+ * earlier rounds' nits and declined findings if this round is the fresh
+ * pass (see `freshId`).
+ */
+const lensResultOf = ({
+    review,
+    lens,
+    result,
+}: {
+    review: FinalReviewState
+    lens: LensName
+    result: LensReviewResult
+}): LensReviewResult => {
+    const named = namespaced({ lens, result })
+    if (!review.fresh) return named
+    const earlier = [
+        ...review.nits,
+        ...review.declined.map(({ finding }) => finding),
+    ]
+    return {
+        ...named,
+        findings: named.findings.map((finding) => ({
+            ...finding,
+            id: freshId({ lens, finding, earlier }),
+        })),
+    }
+}
+
+/**
+ * Every due lens finished this round, and its slow tests ran if they were
+ * due (#563): the round can settle.
+ */
+export const roundDone = ({ review }: { review: FinalReviewState }): boolean =>
+    review.lenses_due.every((lens) => review.results[lens] !== undefined) &&
+    (!review.slow_due || review.slow_tests !== null)
+
+/**
+ * The final review once every due lens finished its round (and its slow
+ * tests ran, if due): settles the last fix round's "won't fix" answers per
+ * lens (see `declinedBy`), keeps the nits, and opens a fix round on the
+ * blocking findings of every due lens, with its fixers, gates, commit, and
+ * push afresh (and fresh fixer sessions). Failed slow tests open one too,
+ * even with no blocking finding (#563): its findings are empty, so only its
+ * gates (and their fix loop) run. No blocking finding and no failed slow
+ * test leaves `fix` null: the review is clean.
+ */
+export const settleRound = ({
+    review,
+}: {
+    review: FinalReviewState
+}): FinalReviewState => {
+    const due = review.lenses_due.flatMap((lens) => {
+        const result = review.results[lens]
+        return result === undefined ? [] : [{ lens, result }]
+    })
+    const tagged = (lens: LensName, findings: Finding[]): FinalFinding[] =>
+        findings.map((entry) => ({ ...entry, lens }))
+    const declined = due.flatMap(({ lens, result }) =>
+        declinedBy({
+            fix:
+                review.fix === null
+                    ? null
+                    : {
+                          ...review.fix,
+                          findings: review.fix.findings.filter(
+                              (entry) => entry.lens === lens
+                          ),
+                      },
+            review: result,
+        }).map((entry) => ({ ...entry, lens }))
+    )
+    const nits = due.flatMap(({ lens, result }) =>
+        tagged(
+            lens,
+            result.findings.filter((entry) => !isBlocking(entry))
+        )
+    )
+    const blocking = due.flatMap(({ lens, result }) =>
+        tagged(lens, result.findings.filter(isBlocking))
+    )
+    const settled: FinalReviewState = {
+        ...review,
+        declined: [...review.declined, ...declined],
+        nits: [
+            ...review.nits,
+            ...nits.filter(
+                (entry, index) =>
+                    !review.nits.some(({ id }) => id === entry.id) &&
+                    nits.findIndex(({ id }) => id === entry.id) === index
+            ),
+        ],
+    }
+    const slowFailed = review.slow_due && review.slow_tests?.ok === false
+    if (blocking.length === 0 && !slowFailed) return { ...settled, fix: null }
+    return {
+        ...settled,
+        fix: {
+            round: review.round,
+            findings: blocking,
+            tests_answered: !blocking.some(({ kind }) => kind === 'test'),
+            code_answered: !blocking.some(({ kind }) => kind === 'code'),
+            responses: [],
+            handed_off: {},
+            bad_test: null,
+        },
+        fixing_started: false,
+        sessions: omit(review.sessions, ['test-writer', 'implementer']),
+        gates: null,
+        gate_fix_rounds: 0,
+        leftovers: null,
+        commit: null,
+        pushed: null,
+    }
+}
+
+/**
+ * Where a finished agent's result goes in the final review: a lens's
+ * result this round (settling the round once every due lens finished), or
+ * a fixer's answer to the open fix round. An implementer result after
+ * failed gates answers a gate fix round, like a ticket's.
+ */
+export const finalResultChange = ({
+    review,
+    finished,
+}: {
+    review: FinalReviewState
+    finished: FinishedContent
+}): FinalReviewState => {
+    const lens = lensOf({ role: finished.role })
+    const { fix } = review
+    if (lens !== null && 'verdict' in finished.result) {
+        if (!review.lenses_due.includes(lens)) return review
+        // The integration lens's first round gives the PR's Summary and
+        // Merge Danger; a re-review's nulls keep them (#513).
+        const { summary_picture, merge_danger } =
+            finished.role === 'integration-lens'
+                ? finished.result
+                : { summary_picture: null, merge_danger: null }
+        const next: FinalReviewState = {
+            ...review,
+            summary_picture: summary_picture ?? review.summary_picture,
+            merge_danger: merge_danger ?? review.merge_danger,
+            results: {
+                ...review.results,
+                [lens]: lensResultOf({
+                    review,
+                    lens,
+                    result: finished.result,
+                }),
+            },
+        }
+        return roundDone({ review: next })
+            ? settleRound({ review: next })
+            : next
+    }
+    // A fixer asking for a change only the owner may make sticks the final
+    // review on it (#617), like a ticket.
+    const setup_change = setupChangeOf({ finished })
+    if (finished.role === 'test-writer') {
+        if (fix === null) return review
+        const responses = finished.result.finding_responses
+        if (!fix.tests_answered) {
+            return {
+                ...review,
+                setup_change,
+                fix: {
+                    ...fix,
+                    tests_answered: true,
+                    ...fixerAnswered({ fix, role: 'test-writer', responses }),
+                },
+            }
+        }
+        if (handoffRole({ fix }) !== 'test-writer') return review
+        return {
+            ...review,
+            setup_change,
+            fix: {
+                ...fix,
+                ...handoffAnswered({ fix, role: 'test-writer', responses }),
+            },
+        }
+    }
+    if (finished.role === 'implementer') {
+        const { result } = finished
+        const responses = result.finding_responses
+        if (fix !== null && fix.tests_answered && !fix.code_answered) {
+            return {
+                ...review,
+                setup_change,
+                fix: {
+                    ...fix,
+                    code_answered: true,
+                    ...fixerAnswered({ fix, role: 'implementer', responses }),
+                    bad_test: badTestOf(result),
+                },
+            }
+        }
+        if (fix !== null && handoffRole({ fix }) === 'implementer') {
+            return {
+                ...review,
+                setup_change,
+                fix: {
+                    ...fix,
+                    ...handoffAnswered({ fix, role: 'implementer', responses }),
+                    bad_test: badTestOf(result),
+                },
+            }
+        }
+        if (review.gates === null) return review
+        // An `environment` answer to failed gates reruns them, using no
+        // gate fix round (#613).
+        if (result.outcome === 'environment' && !review.gates.ok) {
+            return {
+                ...review,
+                setup_change,
+                gates: null,
+                environment_reruns: review.environment_reruns + 1,
+                environment: {
+                    role: 'implementer',
+                    evidence: result.environment?.evidence ?? '',
+                    check: 'gates',
+                    failed: review.gates,
+                },
+            }
+        }
+        return {
+            ...review,
+            setup_change,
+            gates: null,
+            gate_fix_rounds: review.gate_fix_rounds + 1,
+        }
+    }
+    return review
+}

package/engine/journal/final-review-state.ts

@@ -0,0 +1,180 @@
+/**
+ * The shape of the final review as replay rebuilds it, with its findings,
+ * fix round and failures, and the final review before it starts.
+ */
+import type { AgentFailure, StuckReason } from './journal-record'
+import type {
+    DeclinedFinding,
+    EnvironmentRerun,
+    ReplayedGates,
+    ReviewFix,
+    TicketProgress,
+} from './ticket-progress'
+
+import type {
+    AgentRole,
+    Finding,
+    LensName,
+    LensReviewResult,
+    MergeDanger,
+} from '../agents/role-results'
+import type { LeftoverHit } from '../gates/gate-schemas'
+
+/** A final review finding: its id namespaced as `<lens>-<id>`, and its lens. */
+export type FinalFinding = Finding & { lens: LensName }
+
+/** A finding declined in the final review, with the lens that let it go. */
+export type FinalDeclined = DeclinedFinding & { lens: LensName }
+
+/** A rule file for the rules lens, as the engine read it (`null`: unreadable). */
+export type RuleFile = { path: string; text: string | null }
+
+/** A failed agent turn no agent of that role finished after. */
+export type ReplayedAgentFailure = {
+    role: AgentRole
+    error: string
+    failure: AgentFailure
+    session_id: string | null
+}
+
+/**
+ * The open final review fix round: the blocking findings of every lens due
+ * in the round, and which fixers answered. Like a ticket's `ReviewFix`.
+ */
+export type FinalReviewFix = Omit<ReviewFix, 'findings'> & {
+    findings: FinalFinding[]
+}
+
+/**
+ * Where the final review stands, from its records: its round, the lenses
+ * due, each lens's result this round, the open fix round and its fixers,
+ * gates, commit, and push, and what goes in the PR. Ticket-less agent,
+ * gate, scan, commit, and push records belong here once
+ * `final_review_started` is journaled.
+ */
+export type FinalReviewState = {
+    /** 0 before the final review starts, then 1, 2, ... */
+    round: number
+    from_sha: string | null
+    head_sha: string | null
+    /** The files `git diff <from_sha>..<head_sha>` changes. */
+    files: string[]
+    /** The lenses due this round. */
+    lenses_due: LensName[]
+    rules: RuleFile[]
+    /** Each due lens's result this round, finding ids namespaced. */
+    results: Partial<Record<LensName, LensReviewResult>>
+    /** The open fix round; `null` before the first review settles or once clean. */
+    fix: FinalReviewFix | null
+    /** `final_review_fixing` is journaled for the open fix round. */
+    fixing_started: boolean
+    /** The session of each role's latest turn, for follow-ups. */
+    sessions: Partial<Record<AgentRole, string>>
+    /** Each role's failed turn, if no agent of that role finished after it. */
+    agent_failures: Partial<Record<AgentRole, ReplayedAgentFailure>>
+    /** Failed tries (agent, result, guard) per role, over the whole final review. */
+    failed_tries: Partial<Record<AgentRole, number>>
+    /** Engine failures in a row, per role. */
+    engine_failures: Partial<Record<AgentRole, number>>
+    /** The open fix round's gates, and its gate fix follow-ups. */
+    gates: ReplayedGates | null
+    gate_fix_rounds: number
+    /**
+     * The fixer's `environment` answers to failed gates (#613), over the
+     * whole final review, each a rerun that used no gate fix round.
+     */
+    environment_reruns: number
+    /** The latest `environment` answer, until the next agent answers. */
+    environment: EnvironmentRerun | null
+    /** The open fix round's leftover scan and commit. */
+    leftovers: LeftoverHit[] | null
+    commit: { sha: string; files: string[] } | null
+    /** The open fix round's push. */
+    pushed: string | null
+    /** This round's slow tests are due (#563): round 1, with a slow command. */
+    slow_due: boolean
+    /** A fix commit was pushed since round 1: a fresh pass is due once clean (#548). */
+    fix_pushed: boolean
+    /** This round is the fresh pass (#548), or its fix round. */
+    fresh: boolean
+    /** The fresh pass started; there is at most one per final review (#548). */
+    fresh_started: boolean
+    /** This round's slow test run (`gates_run` `final_slow`), once journaled. */
+    slow_tests: ReplayedGates | null
+    /** Every nit the lenses reported, one per id. */
+    nits: FinalFinding[]
+    declined: FinalDeclined[]
+    /** Every assumption a final review agent made, oldest first. */
+    assumptions: string[]
+    /**
+     * How many turns each final review role ran out of turns (#543), in the
+     * order each first did, for the PR.
+     */
+    out_of_turns: Partial<Record<AgentRole, number>>
+    passed: boolean
+    stuck: { reason: StuckReason; detail: string } | null
+    shipped: boolean
+    /**
+     * The commit of the edits left uncommitted at ship time (#509), not
+     * reviewed; `null` with none.
+     */
+    shipped_edits: { sha: string; message: string; files: string[] } | null
+    /**
+     * A change only the owner may make, asked for by a fixer (#617); the
+     * final review is stuck on it until a `retry`.
+     */
+    setup_change: TicketProgress['setup_change']
+    /** The fixer whose turn a crash cut off; cleared once a fixer starts. */
+    crashed_turn: AgentRole | null
+    /**
+     * The PR's Summary picture, from the integration lens (#513). It is kept
+     * across rounds; a later non-null answer replaces it.
+     */
+    summary_picture: string | null
+    /**
+     * The PR's Merge Danger, from the integration lens (#513). It is kept
+     * across rounds; a later non-null answer replaces it.
+     */
+    merge_danger: MergeDanger | null
+}
+
+/** The final review before it starts. */
+export const EMPTY_FINAL_REVIEW: FinalReviewState = {
+    round: 0,
+    from_sha: null,
+    head_sha: null,
+    files: [],
+    lenses_due: [],
+    rules: [],
+    results: {},
+    fix: null,
+    fixing_started: false,
+    sessions: {},
+    agent_failures: {},
+    failed_tries: {},
+    engine_failures: {},
+    gates: null,
+    gate_fix_rounds: 0,
+    environment_reruns: 0,
+    environment: null,
+    leftovers: null,
+    commit: null,
+    pushed: null,
+    slow_due: false,
+    fix_pushed: false,
+    fresh: false,
+    fresh_started: false,
+    slow_tests: null,
+    nits: [],
+    declined: [],
+    assumptions: [],
+    out_of_turns: {},
+    passed: false,
+    stuck: null,
+    shipped: false,
+    shipped_edits: null,
+    setup_change: null,
+    crashed_turn: null,
+    summary_picture: null,
+    merge_danger: null,
+}

package/engine/journal/gate-entries.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+import {
+    GateCheckSchema,
+    RedCheckResultSchema,
+    TestCaseRefSchema,
+    TestCaseSchema,
+    TestRunSchema,
+} from '../gates/gate-schemas'
+
+/**
+ * The journal entries of the checks on a ticket or the run branch: the red
+ * check, the dependency install, and the gates.
+ */
+
+/**
+ * A lone rerun (#544): the check ran again while no other test run went,
+ * holding every test slot, after its old tests failed in another ticket
+ * too. Left out on every other check.
+ */
+const EXCLUSIVE_FIELD = { exclusive: z.boolean().optional() }
+
+export const RedCheckEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('red_check'),
+    content: RedCheckResultSchema.extend({
+        tests: TestRunSchema,
+        ...EXCLUSIVE_FIELD,
+    }),
+})
+
+/** Where the gates or the install ran: a ticket's worktree, or the run branch. */
+export const GateTargetSchema = z.enum(['ticket', 'run_branch'])
+
+export type GateTarget = z.infer<typeof GateTargetSchema>
+
+/**
+ * Where a `gates_run` ran: a ticket's worktree, the run branch, or the
+ * final review's slow tests on the run branch (#563), which run once
+ * round 1's lenses are in and are not the fix round's gates.
+ */
+const GatesRunTargetSchema = z.enum([...GateTargetSchema.options, 'final_slow'])
+
+/**
+ * The engine installed the dependencies from the lockfile, without changing
+ * it, in a new ticket worktree or the run branch's checkout, before any agent
+ * or gate ran there. `check` is `null` when there is no `package.json`, so
+ * nothing to install. The run branch's record has no ticket.
+ */
+export const DependenciesInstalledEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('dependencies_installed'),
+    content: z.object({
+        target: GateTargetSchema,
+        check: GateCheckSchema.nullable(),
+    }),
+})
+
+export const GatesRunEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('gates_run'),
+    content: z.object({
+        target: GatesRunTargetSchema,
+        ok: z.boolean(),
+        checks: z.array(GateCheckSchema),
+        /**
+         * A ticket's gates only: the test cases of the ticket's red test
+         * files, with their `expect()` counts (#581). Missing in old journals.
+         */
+        cases: z.array(TestCaseSchema).optional(),
+        /**
+         * A ticket's and a join's gates only: the test cases that failed in
+         * any bun run (#544), so a test failing in two tickets is spotted.
+         * Left out with none, and in old journals.
+         */
+        failed_cases: z.array(TestCaseRefSchema).optional(),
+        ...EXCLUSIVE_FIELD,
+    }),
+})

package/engine/journal/intake-entries.ts

@@ -0,0 +1,87 @@
+import { z } from 'zod'
+
+import { ENTRY_FIELDS } from './entry-fields'
+
+import {
+    IntakeProblemSchema,
+    IntakeReadSchema,
+    LeftOutTicketSchema,
+    SpecSnapshotSchema,
+    TicketSnapshotSchema,
+} from '../intake/intake-schemas'
+
+/**
+ * The journal entries of intake: what it read, a refusal, nothing to do,
+ * and the spec and ticket snapshots.
+ */
+
+export const IntakeReadEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('intake_read'),
+    content: IntakeReadSchema,
+})
+
+/**
+ * A label the refusal couldn't add or remove (#500), with the tracker's
+ * error. The refusal goes on without it.
+ */
+export const LabelFailureSchema = z.object({
+    ticket: z.number().int().positive(),
+    label: z.string(),
+    change: z.enum(['add', 'remove']),
+    error: z.string(),
+})
+
+export type LabelFailure = z.infer<typeof LabelFailureSchema>
+
+/**
+ * Intake refused the run. `label_failures` are the labels it couldn't
+ * move; older journals have none.
+ */
+export const IntakeRefusedEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('intake_refused'),
+    content: z.object({
+        problems: z.array(IntakeProblemSchema),
+        label_failures: z.array(LabelFailureSchema).default([]),
+    }),
+})
+
+/**
+ * The run ends with nothing to do: at intake, as every ticket of the spec
+ * is closed, or after it, as every ticket's work was already on the base
+ * branch (`already_done`, #484; the engine closed those tickets). At
+ * intake, `left_out` names the open tickets left for a person (#499), when
+ * those are all that is open. Older journals have none.
+ */
+export const NothingToDoEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('nothing_to_do'),
+    content: z.object({
+        closed_tickets: z.array(z.number().int()),
+        already_done: z.array(z.number().int().positive()).default([]),
+        left_out: z.array(LeftOutTicketSchema).default([]),
+    }),
+})
+
+export const SpecSnapshotEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('spec_snapshot'),
+    content: z.object({
+        spec: SpecSnapshotSchema,
+        /** The open tickets in blocker order; one `ticket_snapshot` each. */
+        ticket_order: z.array(z.number().int().positive()),
+        closed_tickets: z.array(z.number().int().positive()),
+        /**
+         * The open tickets left out for a person, and why (#499). The run
+         * doesn't build them or touch them. Older journals have none.
+         */
+        left_out: z.array(LeftOutTicketSchema).default([]),
+    }),
+})
+
+export const TicketSnapshotEntrySchema = z.object({
+    ...ENTRY_FIELDS,
+    kind: z.literal('ticket_snapshot'),
+    content: TicketSnapshotSchema,
+})