@made-by-moonlight/athene-plugin-scm-github 0.9.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Composio, Inc.
+Copyright (c) 2026 slievr (Athene fork)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/graphql-batch.d.ts

@@ -0,0 +1,229 @@
+/**
+ * GraphQL Batch PR Enrichment
+ *
+ * Efficiently fetches data for multiple PRs using GraphQL aliases.
+ * Reduces API calls from N×3 to 1 (or a few if batching needed).
+ */
+import { execFile } from "node:child_process";
+import { type BatchObserver, type CIStatus, type PREnrichmentData, type PRInfo, type PRState, type ReviewDecision } from "@made-by-moonlight/athene-core";
+import { LRUCache } from "./lru-cache.js";
+declare let execFileAsync: typeof execFile.__promisify__;
+/**
+ * Set execFileAsync for testing.
+ * Allows mocking the underlying execFile in unit tests.
+ *
+ * NOTE: This bypasses the gh tracer (execGhObserved). Tests that need to
+ * verify tracer behavior should mock execGhObserved directly or use
+ * setExecGhAsync instead.
+ */
+export declare function setExecFileAsync(fn: typeof execFileAsync): void;
+/**
+ * Set execGhAsync for testing — preserves tracer in the call chain.
+ * Use this when testing code that should exercise the traced execution path.
+ */
+export declare function setExecGhAsync(fn: (args: string[], timeout: number, operation: string) => Promise<string>): void;
+/**
+ * ETag cache for REST API endpoints.
+ * Used to avoid expensive GraphQL queries when nothing has changed.
+ *
+ * Keys:
+ * - PR list: "prList:{owner}/{repo}"
+ * - Commit status: "commit:{owner}/{repo}#{sha}"
+ */
+interface ETagCache {
+    prList: LRUCache<string, string>;
+    commitStatus: LRUCache<string, string>;
+    reviewComments: LRUCache<string, string>;
+}
+/**
+ * Result of checking if PR data has changed via ETag guards.
+ */
+interface ETagGuardResult {
+    shouldRefresh: boolean;
+    details: string[];
+    /** Repos where Guard 1 returned 304 — no PR list changes, detectPR can be skipped. */
+    prListUnchangedRepos: Set<string>;
+}
+/** Result of enrichSessionsPRBatch including Guard 1 PR-discovery info. */
+export interface BatchEnrichmentResult {
+    enrichment: Map<string, PREnrichmentData>;
+    /** Repos where Guard 1 returned 304 — safe to skip detectPR. */
+    prListUnchangedRepos: Set<string>;
+}
+/**
+ * Clear all ETag cache entries.
+ * Useful for testing or when forcing a refresh.
+ */
+export declare function clearETagCache(): void;
+/**
+ * Get PR list ETag for a repository.
+ */
+export declare function getPRListETag(owner: string, repo: string): string | undefined;
+/**
+ * Get commit status ETag for a specific commit.
+ */
+export declare function getCommitStatusETag(owner: string, repo: string, sha: string): string | undefined;
+/**
+ * Set PR list ETag for a repository.
+ * Exported for testing.
+ */
+export declare function setPRListETag(owner: string, repo: string, etag: string): void;
+/**
+ * Set commit status ETag for a specific commit.
+ * Exported for testing.
+ */
+export declare function setCommitStatusETag(owner: string, repo: string, sha: string, etag: string): void;
+/**
+ * Update PR metadata cache with latest enrichment data.
+ * Called after successful GraphQL batch enrichment.
+ */
+declare function updatePRMetadataCache(prKey: string, enrichment: PREnrichmentData, headSha: string | null): void;
+/**
+ * 2-Guard ETag Strategy: Check if PR enrichment cache needs refreshing.
+ *
+ * Before running expensive GraphQL batch queries, use two lightweight REST API
+ * ETag checks to detect if anything actually changed:
+ *
+ * Guard 1: PR List ETag Check (per repo)
+ *   - Detects: New commits, PR title/body edits, labels changes, reviews, PR state changes
+ *   - Misses: CI status changes
+ *
+ * Guard 2: Commit Status ETag Check (per PR with cached metadata)
+ *   - Checks ALL PRs with cached metadata and head SHA
+ *   - Detects: CI check starts, passes, fails, or external status updates
+ *   - Critical for catching CI transitions (failing -> passing, passing -> failing, etc.)
+ *
+ * @param prs - PRs to check
+ * @returns true if GraphQL batch should run, false if nothing changed
+ */
+export declare function shouldRefreshPREnrichment(prs: PRInfo[], extraRepos?: string[], observer?: BatchObserver): Promise<ETagGuardResult>;
+/**
+ * Get cached PR metadata for testing.
+ */
+export declare function getPRMetadataCache(): Map<string, {
+    headSha: string | null;
+    ciStatus: CIStatus;
+}>;
+/**
+ * Get cached PR enrichment data for testing.
+ */
+export declare function getPREnrichmentDataCache(): Map<string, PREnrichmentData>;
+/**
+ * Set PR metadata for testing.
+ */
+export declare function setPRMetadata(key: string, metadata: {
+    headSha: string | null;
+    ciStatus: CIStatus;
+}): void;
+/**
+ * Clear PR metadata cache for testing.
+ */
+export declare function clearPRMetadataCache(): void;
+/** Test-only: reset the once-per-process gh_unavailable guard. */
+export declare function _resetGhUnavailableEmittedForTesting(): void;
+/** Test-only: reset the once-per-PR batch extraction failure guard. */
+export declare function _resetBatchEnrichPRFailedEmittedForTesting(): void;
+/**
+ * Maximum number of PRs to query in a single GraphQL batch.
+ * GitHub has limits on query complexity and we stay well under this limit.
+ */
+export declare const MAX_BATCH_SIZE = 25;
+/**
+ * Guard 1: PR List ETag Check (per repo)
+ *
+ * Detects if PR metadata has changed in a repository using REST ETag.
+ *
+ * - Endpoint: GET /repos/{owner}/{repo}/pulls?state=open&sort=updated&direction=desc
+ * - Detects: New commits, PR title/body edits, label changes, reviews, PR state changes
+ * - Misses: CI status changes (handled by Guard 2)
+ *
+ * @returns true if PR list has changed (200 OK), false if unchanged (304 Not Modified)
+ */
+declare function checkPRListETag(owner: string, repo: string, observer?: BatchObserver): Promise<boolean>;
+/**
+ * Guard 2: Check-Runs ETag Check (per PR with cached head SHA)
+ *
+ * Detects if CI status has changed for a specific commit using REST ETag.
+ *
+ * - Endpoint: GET /repos/{owner}/{repo}/commits/{head_sha}/check-runs
+ *   Uses the check-runs endpoint (not legacy /status) because the batch
+ *   query reads `statusCheckRollup` which aggregates check-runs. Pure-Actions
+ *   repos only update check-runs, not the legacy combined-status endpoint.
+ * - Detects: CI check starts, passes, fails, or external status updates
+ *
+ * @returns true if CI status has changed (200 OK), false if unchanged (304 Not Modified)
+ */
+declare function checkCommitStatusETag(owner: string, repo: string, sha: string, observer?: BatchObserver): Promise<boolean>;
+/**
+ * Guard 3: Review Comments ETag Check (per PR)
+ *
+ * Detects if inline review comments have changed on a PR.
+ * Used to gate the getReviewThreads GraphQL call — if no new comments
+ * exist (304), the cached result is reused without a GraphQL call.
+ *
+ * - Endpoint: GET /repos/{owner}/{repo}/pulls/{number}/comments
+ *   No per_page limit — the ETag covers the full resource. With per_page=1,
+ *   the ETag only covers the first page, so new comments on page 2+ would
+ *   never bust the validator. Typical PR comment counts are small (<100)
+ *   so the unbounded list is fine.
+ * - Detects: New review comments, edited comments, deleted comments
+ * - Cost: 0 REST points on 304, 1 REST point on 200
+ */
+export declare function checkReviewCommentsETag(owner: string, repo: string, prNumber: number, observer?: BatchObserver): Promise<boolean>;
+/**
+ * Generate a GraphQL batch query for multiple PRs using aliases.
+ *
+ * Each PR gets a unique alias (pr0, pr1, pr2...) and the query
+ * fetches the same fields for each PR.
+ */
+export declare function generateBatchQuery(prs: PRInfo[]): {
+    query: string;
+    variables: Record<string, unknown>;
+};
+/**
+ * Parse raw CI state from status check rollup.
+ *
+ * Uses only the top-level aggregate state to determine overall CI status.
+ * Individual check details are parsed separately via parseCheckContexts().
+ */
+declare function parseCIState(statusCheckRollup: unknown): CIStatus;
+/**
+ * Parse review decision from GraphQL response.
+ */
+declare function parseReviewDecision(reviewDecision: unknown): ReviewDecision;
+/**
+ * Parse PR state from GraphQL response.
+ */
+declare function parsePRState(state: unknown): PRState;
+/**
+ * Extract enrichment data from a single PR result.
+ *
+ * Returns the enrichment data along with the head SHA for ETag caching.
+ */
+declare function extractPREnrichment(pullRequest: unknown): {
+    data: PREnrichmentData;
+    headSha: string | null;
+} | null;
+/**
+ * Main batch enrichment function with 2-Guard ETag Strategy.
+ *
+ * Before running expensive GraphQL batch queries, uses two lightweight REST API
+ * ETag checks to detect if anything actually changed:
+ *
+ * 1. Guard 1: PR List ETag Check (per repo)
+ *    - Detects PR metadata changes (commits, reviews, labels, state)
+ *    - Cost: 1 REST point if changed, 0 if unchanged (304)
+ *
+ * 2. Guard 2: Commit Status ETag Check (per PR with pending CI)
+ *    - Detects CI status changes for PRs with pending CI
+ *    - Cost: 1 REST point if changed, 0 if unchanged (304)
+ *
+ * If guards indicate no changes, skips GraphQL entirely (saves ~50 points per batch).
+ * If any guard detects a change, runs GraphQL batch queries.
+ *
+ * Returns a Map keyed by "${owner}/${repo}#${number}" for efficient lookup.
+ */
+export declare function enrichSessionsPRBatch(prs: PRInfo[], observer?: BatchObserver, repos?: string[]): Promise<BatchEnrichmentResult>;
+export { parseCIState, parseReviewDecision, parsePRState, extractPREnrichment, checkPRListETag, checkCommitStatusETag, updatePRMetadataCache, };
+export type { ETagCache, ETagGuardResult };
+//# sourceMappingURL=graphql-batch.d.ts.map

package/dist/graphql-batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-batch.d.ts","sourceRoot":"","sources":["../src/graphql-batch.ts"],"names":[],"mappings":"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"}