@reneturcios/greenlight 0.0.0-stage → 0.3.3

package/dist/github.d.ts

@@ -0,0 +1,213 @@
+import type { IssueSnapshot, LinkedPR, CommentSignal, GateKind, Gate, MentionedPR, DuplicateTarget } from "./types.js";
+import { type WorkflowFile } from "./gates.js";
+export declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+/** Thrown by apiGet/apiPost for HTTP 404, so callers can treat "missing" as data. */
+export declare class ApiNotFoundError extends Error {
+    constructor(path: string);
+}
+export declare function githubToken(): string | undefined;
+export declare function apiGet(path: string): Promise<unknown>;
+/** POST helper for write operations (automation commands). Read paths use apiGet. */
+export declare function apiPost(path: string, body: unknown): Promise<unknown>;
+export interface IssueURL {
+    owner: string;
+    repo: string;
+    number: number;
+}
+export declare function parseIssueUrl(url: string): IssueURL;
+/** Fetch issue comments for claim detection. */
+export declare function fetchComments(owner: string, repo: string, number: number): Promise<CommentSignal[]>;
+/**
+ * Find PRs that reference an issue. Timeline cross-references and a text
+ * search for the issue number are discovery only: every candidate PR is
+ * then fetched individually and scored with classifyLinkStrength, so a PR
+ * that merely lists a sibling issue (e.g. pdfcn #91 closing #70 while
+ * mentioning #61) is stored as a "mention", not a "closing" PR. See issue #1.
+ */
+export declare function fetchLinkedPRs(owner: string, repo: string, number: number): Promise<LinkedPR[]>;
+/** Minimal PR detail needed for the comment-mention cross-check. */
+export interface PullRefDetail {
+    number: number;
+    state: "open" | "closed";
+    merged: boolean;
+    title: string;
+    body: string;
+    url: string;
+}
+export interface MentionedPRDeps {
+    fetchPull?: (owner: string, repo: string, number: number) => Promise<PullRefDetail | null>;
+}
+/**
+ * Policy files fetched for gate extraction. Binding contribution rules
+ * increasingly live in house-rules files that CONTRIBUTING only links to
+ * (reticle keeps its claim-first, DCO, .changes and `pnpm verify` rules in
+ * AGENTS.md), so CONTRIBUTING variants are fetched together with AGENTS.md
+ * and CLAUDE.md at the root and under .github/. fastmcp moved its rules
+ * again in 2026, into docs/development/contributing.mdx behind a pointer
+ * CONTRIBUTING.md, which is why the development-guide paths are here too.
+ */
+export declare const HOUSE_RULE_FILES: readonly ["CONTRIBUTING.md", "contributing.md", ".github/CONTRIBUTING.md", "docs/development/contributing.mdx", "docs/development/contributing.md", "AGENTS.md", "CLAUDE.md", ".github/AGENTS.md", ".github/CLAUDE.md"];
+export interface HouseRuleDeps {
+    /** Test seam: fetch a repo-root file's raw text, or undefined when absent. */
+    fetchRaw?: (file: string) => Promise<string | undefined>;
+}
+/** Fetch all existing house-rules files for a repo (best-effort, cached). */
+export declare function fetchHouseRules(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
+    file: string;
+    text: string;
+}[]>;
+/** Fetch CONTRIBUTING.md raw text; returns undefined when the repo has none. */
+export declare function fetchContributing(owner: string, repo: string): Promise<string | undefined>;
+/**
+ * Extract PR references from comment bodies: bare #NNN mentions and full
+ * github.com/<owner>/<repo>/pull/NNN URLs. Returns deduplicated numbers in
+ * order of first appearance.
+ */
+export declare function extractPRReferences(comments: CommentSignal[], owner: string, repo: string): number[];
+/**
+ * PR references per citing comment author: number -> first comment author
+ * that cited it. Used to tag MentionedPRs with fromAuthor.
+ */
+export declare function extractPRReferenceAuthors(comments: CommentSignal[], owner: string, repo: string): Map<number, string>;
+/**
+ * Cross-check PR references found in comments against the PR API.
+ *
+ * Motivation: reticlehq/reticle#691 got a clean GO verdict while its comments
+ * contained a partial claim ("Taking the remaining fallback ask") and a
+ * heads-up that PR #861 covers that work. Neither signal existed in the
+ * timeline or the issue-number search, so both were missed.
+ *
+ * All comments are scanned (PR references are cheap to extract), but each
+ * result records whether the citing comment came from the issue author.
+ * The open-PR downgrade (rule 11) only trusts non-author heads-ups; the
+ * partially-addressed rule (rule 12) also reads the author's, because the
+ * maintainer narrating what already shipped is usually the issue author.
+ * References already found via the timeline/search, and the issue's own
+ * number, are skipped. Bounded at 5 PR fetches per call; the walk is
+ * best-effort and cached like the rest of the issue data.
+ */
+export declare function fetchCommentMentionedPRs(owner: string, repo: string, issueNumber: number, comments: CommentSignal[], knownPRNumbers: number[], deps?: MentionedPRDeps & {
+    issueAuthor?: string;
+}): Promise<MentionedPR[]>;
+export interface WorkflowDeps {
+    /** Test seam: list .github/workflows file names, or undefined when the directory is absent. */
+    listFiles?: () => Promise<string[] | undefined>;
+    /** Test seam: fetch one workflow file's raw text, or undefined when absent. */
+    fetchRaw?: (name: string) => Promise<string | undefined>;
+}
+/**
+ * List the repo's .github/workflows files and fetch their contents
+ * (best-effort, cached). Contents fetch uses raw.githubusercontent, so it
+ * does not consume the api.github.com rate limit. Capped at 12 files: a
+ * repo with more workflows still shows the signal on the suspiciously
+ * named ones first (they are not reordered; name matching catches them).
+ */
+export declare function listWorkflows(owner: string, repo: string, deps?: WorkflowDeps): Promise<WorkflowFile[]>;
+/** Scan a repo's workflows for auto-close automation; returns detected-only gates. */
+export declare function scanWorkflowGates(owner: string, repo: string, deps?: WorkflowDeps): Promise<Gate[]>;
+/**
+ * Extract duplicate target issue numbers from comment bodies ("duplicate
+ * of #N", GitHub's "This issue has been marked as a duplicate of #N").
+ * Pure; tests drive it directly. The last capture group always holds the
+ * number.
+ */
+export declare function extractDuplicateTargets(comments: CommentSignal[]): number[];
+export interface DuplicateTargetDeps {
+    /** Test seam: issue timeline events, used instead of the live call. */
+    timelineEvents?: Array<Record<string, unknown>>;
+    /** Test seam: fetch a referenced issue's live state. */
+    fetchIssue?: (owner: string, repo: string, number: number) => Promise<{
+        state: string;
+        stateReason?: string;
+    } | null>;
+}
+/**
+ * Find other issues this one is marked a duplicate of. Signals: "duplicate
+ * of #N" comments (n8n's bot posts "marked as a duplicate of #N"), and
+ * marked_as_duplicate timeline events when the API surfaces them. Each
+ * unique target is fetched for its current state (bounded at 3), because
+ * only a target closed as completed means the work already shipped and a
+ * build here is wasted.
+ */
+export declare function fetchDuplicateTargets(owner: string, repo: string, number: number, comments: CommentSignal[], deps?: DuplicateTargetDeps): Promise<DuplicateTarget[]>;
+/** A PR URL found in a fix-announcement comment, possibly in another repo of the same org. */
+export interface AttemptPRLink {
+    author: string;
+    owner: string;
+    repo: string;
+    number: number;
+    url: string;
+}
+/**
+ * Extract PR links from fix-announcement comments. Comments from bots and
+ * from the issue author are skipped. The URLs routinely point at sibling
+ * repos in the same org (tscircuit/tscircuit#5563's fixes live in
+ * tscircuit/core and tscircuit/checks), so they are not limited to the
+ * issue's own repo. Pure; tests drive it directly. Bounded at 5 links.
+ */
+export declare function extractAttemptLinkedPRs(comments: CommentSignal[], issueAuthor: string): AttemptPRLink[];
+/** Count open issues labelled good-first-issue or help-wanted. */
+export declare function countStarterIssues(owner: string, repo: string): Promise<number | null>;
+/** Detect a collaborators-only PR creation policy via the community metrics endpoint. */
+export declare function detectRepoPolicy(owner: string, repo: string): Promise<{
+    collaboratorsOnly: boolean;
+}>;
+/** Build a full IssueSnapshot from the live API. */
+export declare function buildIssueSnapshot(owner: string, repo: string, number: number): Promise<IssueSnapshot>;
+export interface ScanCandidate {
+    number: number;
+    title: string;
+    url: string;
+    labels: string[];
+    updatedAt: string;
+}
+/** List open good-first-issue / help-wanted issues for scan mode. */
+export declare function listStarterIssues(owner: string, repo: string, limit?: number): Promise<ScanCandidate[]>;
+/** Raw issue-list item shape from GET /repos/:o/:r/issues. */
+interface IssueListItem {
+    number: number;
+    title: string;
+    html_url: string;
+    labels: Array<{
+        name: string;
+    }>;
+    updated_at: string;
+    pull_request?: unknown;
+    assignees?: Array<{
+        login: string;
+    }>;
+}
+/**
+ * Filter raw issue-list items down to scan candidates: real issues (not
+ * pull requests) with no assignees, newest first. Pure so tests can drive
+ * it with fixtures.
+ */
+export declare function toScanCandidates(items: IssueListItem[]): ScanCandidate[];
+/**
+ * Fallback candidate list for scan mode: the most recent open unassigned
+ * issues in the repo, for repos whose landable issues do not carry
+ * good-first-issue / help-wanted labels. Lists broadly (up to `cap`) so
+ * the caller can take the newest slice.
+ */
+export declare function listRecentUnassignedIssues(owner: string, repo: string, cap?: number): Promise<ScanCandidate[]>;
+export interface ScanCandidateList {
+    issues: ScanCandidate[];
+    /** True when the label pass came back empty and the fallback list was used. */
+    fallbackUsed: boolean;
+}
+export interface ScanDeps {
+    starter?: (owner: string, repo: string, limit: number) => Promise<ScanCandidate[]>;
+    recent?: (owner: string, repo: string, cap: number) => Promise<ScanCandidate[]>;
+}
+/**
+ * Scan candidates for a repo: the label-tagged starter list first; when it
+ * is empty, fall back to recent open unassigned issues (opt out with
+ * fallback: false). Injectable deps keep tests offline.
+ */
+export declare function scanCandidates(owner: string, repo: string, opts?: {
+    fallback?: boolean;
+    limit?: number;
+}, deps?: ScanDeps): Promise<ScanCandidateList>;
+export type { GateKind };