phoebe-agent 0.0.0 → 0.1.0

package/dist/src/orchestrator.d.ts

@@ -1,275 +0,0 @@
-export type Issue = {
-    number: number;
-    title: string;
-    body: string;
-    labels: string[];
-    createdAt: string;
-};
-export type BlockerPrState = {
-    hasOpenPr: boolean;
-    openPrNumber?: number;
-    hasMergedPr: boolean;
-    mergedPrNumber?: number;
-};
-export type BaseResolution = {
-    worktreeBase: string;
-    stacked: boolean;
-    blockerIssueNumber?: number;
-    blockerPrNumber?: number;
-};
-declare const PRIORITY_ORDER: readonly ["bug", "tracer", "polish", "refactor"];
-export type Priority = (typeof PRIORITY_ORDER)[number];
-/**
- * Parse blocker references from issue body text (and optional comments).
- * The pattern is configurable via `config.blockedByPattern`; capture group 1
- * must yield the blocker issue number.
- */
-export declare function parseBlockedBy(...texts: string[]): number[];
-export declare function classifyPriority(issue: Issue): Priority;
-export declare function compareIssues(a: Issue, b: Issue): number;
-export declare function issueBranch(issueNumber: number): string;
-/**
- * Resolve the worktree base for an issue.
- * Returns `null` when the issue should be skipped this cycle (blocked with no
- * open/merged blocker PR).
- */
-export declare function resolveWorktreeBase(issue: Issue, blockerStates: ReadonlyMap<number, BlockerPrState>, phoebeBase?: string): BaseResolution | null;
-/** Pick the highest-priority workable issue, or `null` when none qualify. */
-export declare function selectIssue(issues: readonly Issue[], blockerStates: ReadonlyMap<number, BlockerPrState>, phoebeBase?: string): {
-    issue: Issue;
-    resolution: BaseResolution;
-} | null;
-export declare function stackedPrComment(blockerIssueNumber: number, blockerPrNumber: number): string;
-export type ConflictingPrCandidate = {
-    prNumber: number;
-    headRefName: string;
-    issueNumber?: number;
-    headSha?: string;
-    failureWatermark?: ConflictFailWatermark | null;
-};
-export type ConflictFailWatermark = {
-    prHead: string;
-    mainHead: string;
-};
-export declare function buildConflictFailWatermarkMarker(watermark: ConflictFailWatermark): string;
-export declare function parseConflictFailWatermark(text: string): ConflictFailWatermark | null;
-/** Latest marker wins when several failure comments exist on one PR. */
-export declare function parseConflictFailWatermarkFromComments(comments: readonly string[]): ConflictFailWatermark | null;
-export declare function shouldSkipWatermarkConflictFix(opts: {
-    watermark: ConflictFailWatermark | null;
-    currentPrHead: string;
-    currentMainHead: string;
-}): boolean;
-export declare function isPhoebeHeadBranch(branch: string): boolean;
-export type PrScopeConfig = {
-    branchPrefix: string;
-    prScope: "phoebe" | "all";
-    draftPrs: "skip-non-phoebe" | "skip-all" | "include";
-    prOptOutLabel: string;
-};
-export type PrScanFields = {
-    headRefName: string;
-    isDraft: boolean;
-    isCrossRepository: boolean;
-    labels: readonly string[];
-};
-/** Whether an open PR is eligible for conflicts/checks/reviews scanning. */
-export declare function isPrInScope(pr: PrScanFields, scopeConfig?: PrScopeConfig): boolean;
-export declare function parseIssueNumberFromBranch(branch: string): number | null;
-/** GitHub may return UNKNOWN while mergeability is still computing. */
-export declare function isPrMergeConflicting(mergeable: string, mergeStateStatus?: string): boolean;
-/**
- * Skip idle conflict-fix when the PR's issue is still stacked on a blocker with
- * an open PR — its divergence from `main` is expected, not a real conflict.
- */
-export declare function shouldSkipStackedConflictFix(issueBody: string, blockerStates: ReadonlyMap<number, BlockerPrState>): boolean;
-/** Merged blocker PR numbers for lazy catch-up (bottom-up stack order). */
-export declare function getMergedBlockerPrNumbers(issueBody: string, blockerStates: ReadonlyMap<number, BlockerPrState>): number[];
-export declare function stackedCatchUpRetractionComment(blockerPrNumbers: readonly number[]): string;
-export declare function selectConflictFixCandidates(prs: readonly ConflictingPrCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>, opts?: {
-    currentMainHead: string;
-}): ConflictingPrCandidate[];
-export type StatusCheckItem = {
-    __typename?: string;
-    name?: string;
-    context?: string;
-    status?: string;
-    conclusion?: string | null;
-    state?: string;
-};
-export type FailingCheck = {
-    name: string;
-    conclusion: string;
-};
-export declare function checkItemName(item: StatusCheckItem): string;
-export declare function isCheckItemFailing(item: StatusCheckItem): boolean;
-export declare function isCheckItemPending(item: StatusCheckItem): boolean;
-/** Combined rollup: FAILURE when at least one check failed and none are pending. */
-export declare function statusCheckRollupState(checks: readonly StatusCheckItem[]): "FAILURE" | "PENDING" | "SUCCESS" | "NONE";
-export type WorkflowRunItem = {
-    workflowName?: string;
-    name?: string;
-    status?: string;
-    conclusion?: string | null;
-};
-/**
- * Map `gh run list` rows onto StatusCheckItem. The REST Actions API is the
- * check-state source usable by fine-grained PATs — GraphQL statusCheckRollup
- * is GitHub-App/OAuth only. REST enums are lowercase; rows arrive newest
- * first, and only the newest run per workflow counts.
- */
-export declare function workflowRunsToCheckItems(runs: readonly WorkflowRunItem[]): StatusCheckItem[];
-export declare function listFailingChecks(checks: readonly StatusCheckItem[]): FailingCheck[];
-export type ChecksCandidate = {
-    prNumber: number;
-    headRefName: string;
-    issueNumber?: number;
-    headSha?: string;
-    mergeable: string;
-    mergeStateStatus?: string;
-    failingChecks: FailingCheck[];
-    failureWatermark?: ChecksFailWatermark | null;
-};
-export type ChecksFailWatermark = {
-    prHead: string;
-};
-export declare function buildChecksFailWatermarkMarker(watermark: ChecksFailWatermark): string;
-export declare function parseChecksFailWatermark(text: string): ChecksFailWatermark | null;
-export declare function parseChecksFailWatermarkFromComments(comments: readonly string[]): ChecksFailWatermark | null;
-export declare function shouldSkipWatermarkChecksFix(opts: {
-    watermark: ChecksFailWatermark | null;
-    currentPrHead: string;
-}): boolean;
-/** Reuse stacked-blocker skip logic — stacked PR red CI is handled at blocker merge. */
-export declare const shouldSkipStackedChecksFix: typeof shouldSkipStackedConflictFix;
-export declare function selectChecksCandidates(prs: readonly ChecksCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>): ChecksCandidate[];
-/** Pick the single checks unit — oldest PR number among eligible failing-CI candidates. */
-export declare function selectChecksUnit(prs: readonly ChecksCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>): ChecksCandidate | null;
-export type ReviewThreadComment = {
-    createdAt: string;
-    authorLogin: string;
-};
-export type ReviewThread = {
-    isResolved: boolean;
-    isOutdated: boolean;
-    comments: readonly ReviewThreadComment[];
-};
-export type ReviewsCandidate = {
-    prNumber: number;
-    headRefName: string;
-    issueNumber?: number;
-    authorLogin?: string;
-    mergeable: string;
-    mergeStateStatus?: string;
-    threads: readonly ReviewThread[];
-    handledWatermark?: ReviewsHandledWatermark | null;
-};
-export type ReviewsHandledWatermark = {
-    latest: string;
-};
-export declare function buildReviewsHandledMarker(watermark: ReviewsHandledWatermark): string;
-export declare function parseReviewsHandledWatermark(text: string): ReviewsHandledWatermark | null;
-export declare function parseReviewsHandledWatermarkFromComments(comments: readonly string[]): ReviewsHandledWatermark | null;
-export declare function isReviewSummaryComment(body: string): boolean;
-export declare function isActivityNewerThanWatermark(createdAt: string, watermark: ReviewsHandledWatermark | null): boolean;
-export declare function newestReviewThreadCommentCreatedAt(threads: readonly ReviewThread[]): string | null;
-export declare function hasNewNonPhoebeReviewActivity(opts: {
-    threads: readonly ReviewThread[];
-    phoebeLogin: string;
-    authorLogin?: string;
-    watermark: ReviewsHandledWatermark | null;
-}): boolean;
-/** Reuse stacked-blocker skip logic — stacked PR review comments are often about blocker code. */
-export declare const shouldSkipStackedReviewsFix: typeof shouldSkipStackedConflictFix;
-export declare function selectReviewsCandidates(prs: readonly ReviewsCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>, phoebeLogin: string): ReviewsCandidate[];
-/** Pick the single reviews unit — oldest PR number among eligible review-feedback candidates. */
-export declare function selectReviewsUnit(prs: readonly ReviewsCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>, phoebeLogin: string): ReviewsCandidate | null;
-export declare function buildReviewsHandledComment(opts: {
-    latestActivityAt: string | null;
-    failed: boolean;
-}): string;
-export declare const WORK_KIND_NAMES: readonly ["conflicts", "checks", "reviews", "issues"];
-export type WorkKindName = (typeof WORK_KIND_NAMES)[number];
-/** Whether a work-kind may run under `--run-once`. Janitor kinds are persistent-mode only. */
-export declare const WORK_KIND_ONE_SHOT_ELIGIBLE: Record<WorkKindName, boolean>;
-export declare const RUN_ONCE_NOTHING_MESSAGE = "[phoebe] Nothing to do under --run-once (janitor kinds are persistent-mode only).";
-export declare function oneShotWorkKinds(workOrder: readonly WorkKindName[]): readonly WorkKindName[];
-/** Fail fast when `WORK_ORDER` is empty or names an unknown kind. */
-export declare function validateWorkOrder(order: readonly string[]): readonly WorkKindName[];
-/** Pick the single conflict unit — oldest PR number among unblocked candidates. */
-export declare function selectConflictUnit(prs: readonly ConflictingPrCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>, opts?: {
-    currentMainHead: string;
-}): ConflictingPrCandidate | null;
-/** Oldest conflicting PR by number that is eligible for an idle conflict fix. */
-export declare function selectConflictFixUnit(prs: readonly ConflictingPrCandidate[], issueBodies: ReadonlyMap<number, string>, blockerStates: ReadonlyMap<number, BlockerPrState>, opts?: {
-    currentMainHead: string;
-}): ConflictingPrCandidate | null;
-export type IssueWorkUnit = {
-    issue: Issue;
-    resolution: BaseResolution;
-};
-export type WorkUnit = {
-    kind: "conflicts";
-    unit: ConflictingPrCandidate;
-} | {
-    kind: "checks";
-    unit: ChecksCandidate;
-} | {
-    kind: "reviews";
-    unit: ReviewsCandidate;
-} | {
-    kind: "issues";
-    unit: IssueWorkUnit;
-};
-export type WorkSelectionData = {
-    issues: readonly Issue[];
-    blockerStates: ReadonlyMap<number, BlockerPrState>;
-    conflictingPrs: readonly ConflictingPrCandidate[];
-    failingCheckPrs: readonly ChecksCandidate[];
-    reviewActivityPrs: readonly ReviewsCandidate[];
-    issueBodies: ReadonlyMap<number, string>;
-    phoebeBase?: string;
-    phoebeLogin?: string;
-    currentMainHead?: string;
-};
-export type WorkSelectionOptions = {
-    /** When true, skip kinds with `WORK_KIND_ONE_SHOT_ELIGIBLE[kind] === false`. */
-    oneShotOnly?: boolean;
-};
-/** Walk `workOrder` and return the first kind that has a unit of work. */
-export declare function selectFirstWorkUnit(workOrder: readonly WorkKindName[], data: WorkSelectionData, opts?: WorkSelectionOptions): WorkUnit | null;
-export declare function conflictFixFailureComment(prNumber: number, watermark?: ConflictFailWatermark): string;
-/**
- * After a sandbox conflict fix, the host may see 0 unpushed commits even when the sandbox
- * already pushed. Only post a failure comment when origin is unchanged and the PR still
- * conflicts.
- */
-export declare function shouldPostConflictFixFailure(opts: {
-    hostCommitCount: number;
-    originShaBefore: string;
-    originShaAfter: string;
-    mergeable: string;
-    mergeStateStatus?: string;
-}): boolean;
-export declare function checksFixFailureComment(prNumber: number, watermark?: ChecksFailWatermark): string;
-/**
- * After a checks fix agent run, post a failure comment only when the agent made
- * no commits and did not push.
- */
-export declare function shouldPostChecksFixFailure(opts: {
-    hostCommitCount: number;
-    originShaBefore: string;
-    originShaAfter: string;
-}): boolean;
-export declare function formatFailingChecksForPrompt(checks: readonly FailingCheck[]): string;
-export declare function buildInitialPrBody(opts: {
-    issueNumber: number;
-    commitCount: number;
-    stacked?: {
-        blockerIssueNumber: number;
-        blockerPrNumber: number;
-    };
-}): string;
-/** Incremental note for follow-up pushes — no stacked-PR banner. */
-export declare function followUpPrComment(issueNumber: number, commitCount: number): string;
-export {};