@cleocode/core 2026.9.23 → 2026.9.24

package/dist/tasks/component-pr.d.ts

@@ -15,8 +15,16 @@
  *  - its files are the ones its merge commit changed that still exist in the
  *    integration PR's merge commit — never the whole integration diff.
  *
+ * A component that did not merge into the integration branch as a PR — closed
+ * by hand after a `git merge --no-ff`, marked merged by GitHub, stacked on
+ * another component, main-merged afterwards, or rebased into the batch — is
+ * verified commit by commit instead (T12710): every commit of its own is in
+ * the integration merge by ancestry, or by `git patch-id` when rebased, and
+ * {@link findComponentLanding} follows it to that integration PR.
+ *
  * @task T12671
  * @task T12672
+ * @task T12710
  */
 /** One component PR as `gh pr view` reports it. */
 export interface ComponentPrView {
@@ -34,6 +42,10 @@ export interface ComponentPrView {
     state: string;
     /** Merge commit, or null when unmerged. */
     mergeCommitSha: string | null;
+    /** Head branch tip the PR carried, when known (T12710). */
+    headRefOid?: string | null;
+    /** The PR's commits, oldest first, when known (T12710). */
+    commits?: string[];
 }
 /** Reads one PR; null when `gh` cannot. */
 export type ViewComponentPr = (prNumber: number, root: string) => Promise<ComponentPrView | null>;
@@ -66,6 +78,24 @@ export type ComponentPrResolution = {
     reason: string;
     codeName: 'E_EVIDENCE_INSUFFICIENT' | 'E_EVIDENCE_CONTENT_MISMATCH' | 'E_EVIDENCE_TOOL_FAILED';
 };
+/**
+ * Deadline for one git subprocess in component verification
+ * (`CLEO_GIT_TIMEOUT_MS`, default 30 s). A read that outlives it is killed
+ * and the verification refuses with `E_EVIDENCE_TOOL_FAILED` (T12710 review).
+ *
+ * @returns Milliseconds.
+ * @task T12710
+ */
+export declare function gitTimeoutMs(): number;
+/**
+ * A git subprocess outlived {@link gitTimeoutMs} and was killed.
+ *
+ * @task T12710
+ */
+export declare class GitTimeoutError extends Error {
+    /** @param args - The git arguments that timed out. */
+    constructor(args: readonly string[]);
+}
 /** Default {@link ViewComponentPr}: `gh pr view <n>`. */
 export declare const defaultViewComponentPr: ViewComponentPr;
 /**
@@ -91,9 +121,138 @@ export declare function componentLandedChanges(root: string, componentMerge: str
     files: string[];
     deleted: string[];
 };
+/** A refusal in the shape every component check returns. */
+type Refusal = Extract<ComponentPrResolution, {
+    ok: false;
+}>;
+/** The integration PR's side of a commit-level check. */
+export type LandingMerge = Pick<LandingPr, 'prNumber' | 'mergeCommitSha'>;
+/** A component's change verified commit by commit against one landing merge. */
+export type ComponentCommitsLanded = {
+    ok: true;
+    /** Newest component commit the landing carries (the original tip when rebased). */
+    tip: string;
+    /** Files the component changed that survive in the landing merge. */
+    files: string[];
+    /** Files the component deleted that the landing merge lacks. */
+    deleted: string[];
+} | Refusal;
+/**
+ * Verify, commit by commit, that a landing merge carries a component PR's
+ * change, whatever happened to the PR itself (T12710): closed by hand, marked
+ * merged by GitHub, stacked on another component, main merged into its head
+ * afterwards, or rebased into the batch.
+ *
+ * - Every non-merge commit of the PR is an ancestor of the landing merge, or
+ *   — when the batch was rebased — has the same `git patch-id` as a commit
+ *   the landing merge introduced (`<merge>^1..<merge>`). Git is the proof;
+ *   no PR body is consulted.
+ * - At least one of them is new in the landing merge (not already on its
+ *   first parent), so the landing PR is the one that landed it.
+ * - The credited files are only the paths the PR's own commits changed, and
+ *   only where the landing merge still carries the change (blob identical,
+ *   or the component's hunks reverse-apply and do not re-apply — T12689).
+ *
+ * @param root - Git checkout holding every commit.
+ * @param c - The component PR, with its commit list.
+ * @param landing - The integration PR number and its merge commit.
+ * @returns The component's tip and surviving changes, or the refusal.
+ * @task T12710
+ */
+export declare function componentCommitsLanded(root: string, c: ComponentPrView, landing: LandingMerge): ComponentCommitsLanded;
+/**
+ * The first commit on `ref`'s first-parent chain that contains `sha`: the
+ * commit that landed it on the default branch. `sha` itself when it is on
+ * that chain; null when `ref` does not contain it.
+ *
+ * @param root - Git checkout.
+ * @param sha - A commit.
+ * @param ref - The default branch ref, e.g. `origin/main`.
+ * @returns The landing commit, or null.
+ * @task T12710
+ */
+export declare function landingCommitOn(root: string, sha: string, ref: string): string | null;
+/** A merged PR that may have landed a component (a candidate integration PR). */
+export interface LandingCandidate {
+    /** PR number. */
+    number: number;
+    /** Head (integration) branch. */
+    headRefName: string;
+    /** Branch it merged into. */
+    baseRefName: string;
+    /** `MERGED`, `OPEN` or `CLOSED`. */
+    state: string;
+    /** Final head commit, when known. */
+    headRefOid: string | null;
+    /** Merge commit on the base branch, or null. */
+    mergeCommitSha: string | null;
+    /** PR body (a hint only, never proof). */
+    body: string;
+}
+/** A bounded `gh` PR search: the PRs, or why it failed (offline, timeout). */
+export type LandingSearch = {
+    ok: true;
+    prs: LandingCandidate[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** `gh` lookups {@link findComponentLanding} needs (tests inject). */
+export interface ComponentLandingDeps {
+    /** Merged PRs whose merge commit may be `sha`. */
+    prsByMergeCommit?: (sha: string, root: string) => Promise<LandingSearch>;
+    /** Merged PRs whose body may list `#<componentPrNumber>` — a hint for rebased batches. */
+    prsListingComponent?: (componentPrNumber: number, root: string) => Promise<LandingSearch>;
+}
+/** Default {@link ComponentLandingDeps}: bounded `gh pr list` searches. */
+export declare const defaultComponentLandingDeps: Required<ComponentLandingDeps>;
+/** The integration PR that landed a component, with the component's surviving changes. */
+export type ComponentLanding = {
+    ok: true;
+    /** The integration PR (merged into the default branch). */
+    landing: LandingCandidate & {
+        mergeCommitSha: string;
+    };
+    /** Files the component changed that survive in the landing merge. */
+    files: string[];
+    /** Files the component deleted that the landing merge lacks. */
+    deleted: string[];
+} | Refusal;
+/**
+ * Follow a component PR to the PR that landed it on the default branch
+ * (T12671, T12710). Resolution, git first:
+ *
+ * 1. Ancestry: the newest PR commit the default branch contains is landed by
+ *    the first commit on the default branch's first-parent chain containing
+ *    it; the merged PR whose merge commit that is, is the landing PR. When
+ *    that commit is the component's own merge, it landed directly: `null`.
+ * 2. Rebased batch (no PR commit is on the default branch): merged PRs into
+ *    the default branch whose body lists `#<component>` are candidates — a
+ *    hint only — and each is accepted only through patch-id proof.
+ *
+ * Either way {@link componentCommitsLanded} is the proof: every commit of the
+ * component is in the landing merge, and only its surviving files are
+ * credited. A `gh` failure (offline, timeout) is a refusal, never a hang.
+ *
+ * @param root - Git checkout with the default branch fetched.
+ * @param c - The component PR (with its commits).
+ * @param defaultRef - The default branch ref, e.g. `origin/main`.
+ * @param deps - `gh` lookups (tests inject).
+ * @returns The landing PR and surviving changes, a refusal, or `null` when the
+ *   PR landed directly (its own merge is on the default branch).
+ * @task T12710
+ */
+export declare function findComponentLanding(root: string, c: ComponentPrView, defaultRef: string, deps?: ComponentLandingDeps): Promise<ComponentLanding | null>;
 /**
  * Verify that `componentPrNumber` is a component the integration PR landed,
- * and derive its landed files.
+ * and derive its landed files. Two proofs, first match wins:
+ *
+ * - the component PR merged into the integration PR's head branch, whose
+ *   head contains its merge commit (T12671);
+ * - otherwise every commit of its own is in the integration merge, by
+ *   ancestry or patch-id ({@link componentCommitsLanded}, T12710) — a
+ *   component closed by hand, marked merged by GitHub, stacked, main-merged
+ *   afterwards, or rebased into the batch.
  *
  * @param componentPrNumber - The task's own (component) PR.
  * @param landing - The integration PR that reached the default branch.
@@ -101,6 +260,8 @@ export declare function componentLandedChanges(root: string, componentMerge: str
  * @param view - PR reader (tests inject).
  * @returns The component's linkage fields and files, or the refusal.
  * @task T12671
+ * @task T12710
  */
 export declare function resolveComponentPr(componentPrNumber: number, landing: LandingPr, root: string, view?: ViewComponentPr): Promise<ComponentPrResolution>;
+export {};
 //# sourceMappingURL=component-pr.d.ts.map

package/dist/tasks/component-pr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component-pr.d.ts","sourceRoot":"","sources":["../../src/tasks/component-pr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe;IACf,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,2CAA2C;AAC3C,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;AAElG,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qDAAqD;AACrD,MAAM,MAAM,qBAAqB,GAC7B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mCAAmC;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EACJ,yBAAyB,GACzB,6BAA6B,GAC7B,wBAAwB,CAAC;CAC9B,CAAC;AAsBN,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,EAAE,eAoCpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAsCxC;AA2ED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,eAAwC,GAC7C,OAAO,CAAC,qBAAqB,CAAC,CAsDhC"}
+{"version":3,"file":"component-pr.d.ts","sourceRoot":"","sources":["../../src/tasks/component-pr.ts"],"names":[],"mappings":"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"}