@akagilnc/pi-workflow-roles 0.1.5797 → 0.1.5820

package/dist/ticket-snapshot.js

@@ -0,0 +1,486 @@
+/**
+ * GitHub ticket snapshot adapter (factory board S2).
+ *
+ * Thin layer: explicit book→repo bindings + open set (+ named closed drills)
+ * → BoardSnapshot. Does not scan ledgers, does not guess git remote.
+ *
+ * Parent / blocked_by edges come from GitHub's native issue relationship API
+ * (GraphQL parent + blockedBy). Binding or API failure throws — callers render
+ * the error loudly; never invent an empty successful board.
+ *
+ * blockedBy is paginated to completion (or fails loudly). Never expose a
+ * truncated first page as the full blocker set.
+ */
+import { createGhApiRunner } from "./gh-api-runner.js";
+import { isRecord } from "./unknown-value.js";
+import { isPositiveTicketNumber } from "./run-ticket-number.js";
+/** Retention window: merged tickets leave the default board closedAt+24h later. */
+export const RETENTION_WINDOW_MS = 24 * 60 * 60 * 1000;
+export class TicketSnapshotBindingError extends Error {
+    kind = "binding";
+    bookKey;
+    constructor(bookKey, message) {
+        super(message);
+        this.name = "TicketSnapshotBindingError";
+        this.bookKey = bookKey;
+    }
+}
+export class TicketSnapshotApiError extends Error {
+    kind = "api";
+    bookKey;
+    constructor(bookKey, message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "TicketSnapshotApiError";
+        this.bookKey = bookKey;
+    }
+}
+function requireNonEmpty(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${label} must be a non-empty string`);
+    return trimmed;
+}
+function mapIssueState(raw) {
+    if (raw === "OPEN" || raw === "open")
+        return "open";
+    if (raw === "CLOSED" || raw === "closed")
+        return "closed";
+    throw new Error(`unexpected issue state: ${String(raw)}`);
+}
+/**
+ * Parse one blockedBy connection page. Completeness requires pageInfo;
+ * missing pageInfo is a loud failure (never treat a truncated first page as full).
+ */
+function parseBlockedByPage(raw, label) {
+    if (raw === undefined || raw === null) {
+        return { edges: [], hasNextPage: false, endCursor: null };
+    }
+    if (!isRecord(raw) || !Array.isArray(raw.nodes)) {
+        throw new Error(`${label} invalid`);
+    }
+    const pageInfo = raw.pageInfo;
+    if (!isRecord(pageInfo) || typeof pageInfo.hasNextPage !== "boolean") {
+        throw new Error(`${label}.pageInfo missing — cannot establish blockedBy completeness`);
+    }
+    let endCursor = null;
+    if (pageInfo.endCursor === null || pageInfo.endCursor === undefined) {
+        endCursor = null;
+    }
+    else if (typeof pageInfo.endCursor === "string") {
+        endCursor = pageInfo.endCursor;
+    }
+    else {
+        throw new Error(`${label}.pageInfo.endCursor invalid`);
+    }
+    if (pageInfo.hasNextPage && !endCursor) {
+        throw new Error(`${label}.pageInfo endCursor missing while hasNextPage`);
+    }
+    const edges = [];
+    for (const [index, node] of raw.nodes.entries()) {
+        if (!isRecord(node) || typeof node.number !== "number") {
+            throw new Error(`${label}.nodes[${index}] invalid`);
+        }
+        edges.push({
+            issueNumber: node.number,
+            state: mapIssueState(node.state),
+        });
+    }
+    return {
+        edges,
+        hasNextPage: pageInfo.hasNextPage,
+        endCursor,
+    };
+}
+function parseClosedAt(raw, label) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw !== "string" || !Number.isFinite(Date.parse(raw))) {
+        throw new Error(`${label}.closedAt invalid`);
+    }
+    return raw;
+}
+function parseTicketNode(raw, label) {
+    if (!isRecord(raw))
+        throw new Error(`${label} is not an object`);
+    const number = raw.number;
+    if (!isPositiveTicketNumber(number)) {
+        throw new Error(`${label}.number invalid`);
+    }
+    if (typeof raw.title !== "string")
+        throw new Error(`${label}.title missing`);
+    const milestoneRaw = raw.milestone;
+    let milestone = null;
+    if (milestoneRaw === null || milestoneRaw === undefined) {
+        milestone = null;
+    }
+    else if (isRecord(milestoneRaw) && typeof milestoneRaw.title === "string") {
+        milestone = milestoneRaw.title;
+    }
+    else {
+        throw new Error(`${label}.milestone invalid`);
+    }
+    let parentIssueNumber = null;
+    if (raw.parent === null || raw.parent === undefined) {
+        parentIssueNumber = null;
+    }
+    else if (isRecord(raw.parent) && typeof raw.parent.number === "number") {
+        parentIssueNumber = raw.parent.number;
+    }
+    else {
+        throw new Error(`${label}.parent invalid`);
+    }
+    const state = mapIssueState(raw.state);
+    const closedAtRaw = parseClosedAt(raw.closedAt, label);
+    if (state === "closed" && closedAtRaw === null) {
+        throw new Error(`${label}.closedAt missing for closed issue`);
+    }
+    // Open tickets never carry a closure endpoint into landing-cycle math.
+    const closedAt = state === "closed" ? closedAtRaw : null;
+    return {
+        ticket: {
+            issueNumber: number,
+            title: raw.title,
+            state,
+            milestone,
+            parentIssueNumber,
+            closedAt,
+        },
+        blockedByPage: parseBlockedByPage(raw.blockedBy, `${label}.blockedBy`),
+    };
+}
+const BLOCKED_BY_PAGE_SIZE = 100;
+function blockedBySelection(afterVar) {
+    const afterArg = afterVar ? `, after: ${afterVar}` : "";
+    return `blockedBy(first: ${BLOCKED_BY_PAGE_SIZE}${afterArg}) {
+          pageInfo { hasNextPage endCursor }
+          nodes { number state }
+        }`;
+}
+function buildOpenIssuesQuery() {
+    return `query($owner: String!, $repo: String!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    issues(states: OPEN, first: 100, after: $after, orderBy: { field: CREATED_AT, direction: ASC }) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number
+        title
+        state
+        closedAt
+        milestone { title }
+        parent { number }
+        ${blockedBySelection()}
+      }
+    }
+  }
+}`;
+}
+function buildClosedIssuesQuery(numbers) {
+    const aliases = numbers
+        .map((n, index) => `
+    c${index}: issue(number: ${n}) {
+      number
+      title
+      state
+      closedAt
+      milestone { title }
+      parent { number }
+      ${blockedBySelection()}
+    }`)
+        .join("\n");
+    return `query($owner: String!, $repo: String!) {
+  repository(owner: $owner, name: $repo) {
+    ${aliases}
+  }
+}`;
+}
+function buildClosedIssuesDrainQuery() {
+    return `query($owner: String!, $repo: String!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    issues(states: CLOSED, first: 100, after: $after, orderBy: { field: UPDATED_AT, direction: DESC }) {
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        number
+        title
+        state
+        closedAt
+        milestone { title }
+        parent { number }
+        ${blockedBySelection()}
+      }
+    }
+  }
+}`;
+}
+function buildBlockedByPageQuery() {
+    return `query($owner: String!, $repo: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    issue(number: $number) {
+      ${blockedBySelection("$after")}
+    }
+  }
+}`;
+}
+async function ghGraphql(runner, query, variables, signal) {
+    const args = [
+        "api",
+        "graphql",
+        "--hostname",
+        "github.com",
+        "--include",
+        "-f",
+        `query=${query}`,
+    ];
+    for (const [key, value] of Object.entries(variables)) {
+        if (value === null) {
+            args.push("-F", `${key}=null`);
+        }
+        else if (typeof value === "number") {
+            // GraphQL Int variables must be typed, not string-forced.
+            args.push("-F", `${key}=${value}`);
+        }
+        else {
+            args.push("-f", `${key}=${value}`);
+        }
+    }
+    const response = await runner(args, signal === undefined ? {} : { signal });
+    if (response.status < 200 || response.status >= 300) {
+        throw new Error(`GitHub GraphQL HTTP ${response.status}: ${response.bodyText.slice(0, 400)}`);
+    }
+    let payload;
+    try {
+        payload = JSON.parse(response.bodyText);
+    }
+    catch (error) {
+        throw new Error("GitHub GraphQL returned malformed JSON", { cause: error });
+    }
+    if (!isRecord(payload))
+        throw new Error("GitHub GraphQL payload is not an object");
+    if (payload.errors !== undefined) {
+        const msg = JSON.stringify(payload.errors).slice(0, 600);
+        throw new Error(`GitHub GraphQL errors: ${msg}`);
+    }
+    return payload.data;
+}
+/**
+ * Drain blockedBy pages until complete. Never return a partial first page as full.
+ */
+async function completeBlockedBy(runner, owner, repo, issueNumber, firstPage, signal) {
+    const edges = [...firstPage.edges];
+    let hasNextPage = firstPage.hasNextPage;
+    let endCursor = firstPage.endCursor;
+    while (hasNextPage) {
+        if (!endCursor) {
+            throw new Error(`blockedBy pagination incomplete for #${issueNumber}: missing endCursor`);
+        }
+        const data = await ghGraphql(runner, buildBlockedByPageQuery(), { owner, repo, number: issueNumber, after: endCursor }, signal);
+        if (!isRecord(data) || !isRecord(data.repository) || !isRecord(data.repository.issue)) {
+            throw new Error(`blockedBy page missing for #${issueNumber}`);
+        }
+        const page = parseBlockedByPage(data.repository.issue.blockedBy, `blockedBy[#${issueNumber}]`);
+        edges.push(...page.edges);
+        hasNextPage = page.hasNextPage;
+        endCursor = page.endCursor;
+    }
+    return edges;
+}
+async function materializeTicket(runner, owner, repo, raw, label, signal) {
+    const parsed = parseTicketNode(raw, label);
+    const blockedBy = await completeBlockedBy(runner, owner, repo, parsed.ticket.issueNumber, parsed.blockedByPage, signal);
+    return {
+        ...parsed.ticket,
+        blockedBy,
+    };
+}
+export function createGhTicketSnapshotTransport(runner = createGhApiRunner()) {
+    return {
+        async listBookTickets(input) {
+            const owner = requireNonEmpty(input.owner, "owner");
+            const repo = requireNonEmpty(input.repo, "repo");
+            const retentionNow = input.retentionNow;
+            if (retentionNow !== undefined && !Number.isFinite(retentionNow.getTime())) {
+                throw new Error("retentionNow must be a finite Date");
+            }
+            const tickets = new Map();
+            let after = null;
+            for (;;) {
+                const data = await ghGraphql(runner, buildOpenIssuesQuery(), { owner, repo, after }, input.signal);
+                if (!isRecord(data) || !isRecord(data.repository)) {
+                    throw new Error("GitHub GraphQL repository missing");
+                }
+                const issues = data.repository.issues;
+                if (!isRecord(issues) || !Array.isArray(issues.nodes)) {
+                    throw new Error("GitHub GraphQL issues connection missing");
+                }
+                for (const [index, node] of issues.nodes.entries()) {
+                    if (node === null)
+                        continue;
+                    const ticket = await materializeTicket(runner, owner, repo, node, `open[${index}]`, input.signal);
+                    tickets.set(ticket.issueNumber, ticket);
+                }
+                const pageInfo = issues.pageInfo;
+                if (!isRecord(pageInfo) ||
+                    typeof pageInfo.hasNextPage !== "boolean") {
+                    throw new Error("GitHub GraphQL pageInfo missing");
+                }
+                if (!pageInfo.hasNextPage)
+                    break;
+                if (typeof pageInfo.endCursor !== "string" || !pageInfo.endCursor) {
+                    throw new Error("GitHub GraphQL endCursor missing");
+                }
+                after = pageInfo.endCursor;
+            }
+            if (retentionNow !== undefined) {
+                // Closed drain: complete pagination only (never a truncated first page),
+                // then the mechanical merge+24h candidate set with the family shared clock.
+                const closedPool = new Map();
+                let closedAfter = null;
+                for (;;) {
+                    const data = await ghGraphql(runner, buildClosedIssuesDrainQuery(), { owner, repo, after: closedAfter }, input.signal);
+                    if (!isRecord(data) || !isRecord(data.repository)) {
+                        throw new Error("GitHub GraphQL repository missing");
+                    }
+                    const issues = data.repository.issues;
+                    if (!isRecord(issues) || !Array.isArray(issues.nodes)) {
+                        throw new Error("GitHub GraphQL closed issues connection missing");
+                    }
+                    for (const [index, node] of issues.nodes.entries()) {
+                        if (node === null)
+                            continue;
+                        const ticket = await materializeTicket(runner, owner, repo, node, `closedDrain[${index}]`, input.signal);
+                        closedPool.set(ticket.issueNumber, ticket);
+                    }
+                    const pageInfo = issues.pageInfo;
+                    if (!isRecord(pageInfo) || typeof pageInfo.hasNextPage !== "boolean") {
+                        throw new Error("GitHub GraphQL closed issues pageInfo missing — cannot establish completeness");
+                    }
+                    if (!pageInfo.hasNextPage)
+                        break;
+                    if (typeof pageInfo.endCursor !== "string" || !pageInfo.endCursor) {
+                        throw new Error("GitHub GraphQL closed issues endCursor missing");
+                    }
+                    closedAfter = pageInfo.endCursor;
+                }
+                // Family roots from native parent edges across open ∪ closed (cycle-safe).
+                const allByNumber = new Map([...tickets, ...closedPool]);
+                const rootOf = (ticket) => {
+                    const seen = new Set();
+                    let current = ticket;
+                    for (;;) {
+                        if (seen.has(current.issueNumber))
+                            return current;
+                        seen.add(current.issueNumber);
+                        const parentNumber = current.parentIssueNumber;
+                        if (parentNumber === null)
+                            return current;
+                        const parent = allByNumber.get(parentNumber);
+                        if (!parent)
+                            return current; // edge outside the book — self is the best clock
+                        current = parent;
+                    }
+                };
+                const nowMs = retentionNow.getTime();
+                for (const candidate of closedPool.values()) {
+                    if (tickets.has(candidate.issueNumber))
+                        continue;
+                    const root = rootOf(candidate);
+                    if (root.state === "open") {
+                        // 陪跑: merged children stay while the family root is open.
+                        tickets.set(candidate.issueNumber, candidate);
+                        continue;
+                    }
+                    const rootClosedAt = root.closedAt;
+                    if (rootClosedAt === null) {
+                        throw new Error(`closed family root #${root.issueNumber} missing closedAt`);
+                    }
+                    if (Date.parse(rootClosedAt) + RETENTION_WINDOW_MS > nowMs) {
+                        tickets.set(candidate.issueNumber, candidate);
+                    }
+                    // else: the family has exited (root closedAt+24h passed) — not supplied.
+                }
+            }
+            const closedNumbers = [
+                ...new Set(input.closedIssueNumbers.filter((n) => isPositiveTicketNumber(n) && !tickets.has(n))),
+            ].sort((a, b) => a - b);
+            // Fetch named closed issues in modest batches (alias query size).
+            const batchSize = 20;
+            for (let offset = 0; offset < closedNumbers.length; offset += batchSize) {
+                const batch = closedNumbers.slice(offset, offset + batchSize);
+                if (batch.length === 0)
+                    continue;
+                const data = await ghGraphql(runner, buildClosedIssuesQuery(batch), { owner, repo }, input.signal);
+                if (!isRecord(data) || !isRecord(data.repository)) {
+                    throw new Error("GitHub GraphQL repository missing for closed drills");
+                }
+                for (let index = 0; index < batch.length; index += 1) {
+                    const node = data.repository[`c${index}`];
+                    if (node === null || node === undefined) {
+                        throw new Error(`named closed issue #${batch[index]} not found in ${owner}/${repo}`);
+                    }
+                    const ticket = await materializeTicket(runner, owner, repo, node, `closed[#${batch[index]}]`, input.signal);
+                    tickets.set(ticket.issueNumber, ticket);
+                }
+            }
+            return [...tickets.values()].sort((a, b) => a.issueNumber - b.issueNumber);
+        },
+    };
+}
+function assertBinding(binding) {
+    if (!binding.bookKey.trim()) {
+        throw new TicketSnapshotBindingError(binding.bookKey, "bookKey must be a non-empty string");
+    }
+    const owner = binding.owner?.trim() ?? "";
+    const repo = binding.repo?.trim() ?? "";
+    if (!owner || !repo) {
+        throw new TicketSnapshotBindingError(binding.bookKey, `binding missing owner/repo for book ${binding.bookKey}`);
+    }
+    return { owner, repo };
+}
+/**
+ * Fetch a board snapshot from explicit book→repo bindings.
+ * Never inspects git remotes. Transport failures become TicketSnapshotApiError.
+ * Duplicate bookKey bindings fail closed before any transport work.
+ */
+export async function fetchBoardSnapshot(input) {
+    if (!Array.isArray(input.bindings) || input.bindings.length === 0) {
+        throw new TicketSnapshotBindingError("", "bindings must be a non-empty array");
+    }
+    // Reject duplicate bookKeys before any API / ledger work — bookKey is the
+    // sole join identity across bindings, snapshot books, and swimlanes.
+    const seenBookKeys = new Set();
+    for (const binding of input.bindings) {
+        const key = binding.bookKey;
+        if (seenBookKeys.has(key)) {
+            throw new TicketSnapshotBindingError(key, `duplicate bookKey binding: ${key}`);
+        }
+        seenBookKeys.add(key);
+    }
+    const books = [];
+    for (const binding of input.bindings) {
+        const { owner, repo } = assertBinding(binding);
+        const closedIssueNumbers = input.closedIssueNumbersByBook?.[binding.bookKey] ?? [];
+        try {
+            const tickets = await input.transport.listBookTickets({
+                owner,
+                repo,
+                closedIssueNumbers,
+                ...(input.retentionNow !== undefined ? { retentionNow: input.retentionNow } : {}),
+                ...(input.signal !== undefined ? { signal: input.signal } : {}),
+            });
+            books.push({
+                bookKey: binding.bookKey,
+                owner,
+                repo,
+                tickets,
+            });
+        }
+        catch (error) {
+            if (error instanceof TicketSnapshotBindingError)
+                throw error;
+            const message = error instanceof Error
+                ? error.message
+                : `ticket snapshot API failed for book ${binding.bookKey}`;
+            throw new TicketSnapshotApiError(binding.bookKey, `ticket snapshot API failed for book ${binding.bookKey}: ${message}`, { cause: error });
+        }
+    }
+    return { books };
+}