@reneturcios/greenlight 0.3.11 → 0.5.0

package/dist/protocol.d.ts

@@ -0,0 +1,232 @@
+/**
+ * The Greenlight Claim Protocol core engine (Phase 1, Greenlight v0.4.0).
+ *
+ * Implements SPEC.md sections 3 (the claim), 4 (policy file) and 5.1 (status
+ * payload) as pure functions over injected data: no network, no dates other
+ * than the caller's `now`, no exceptions on bad input.
+ *
+ * Design commitments carried over from the spec:
+ * - GitHub is the source of truth: a claim is a comment carrying the marker
+ *   `<!-- greenlight-claim v1 -->`, ordered by the comment's own created_at
+ *   (ties broken by comment id). The engine never invents timestamps.
+ * - Claims are leases, not property: expiry is computed lazily by any reader.
+ * - The state machine replays events chronologically (claims, heartbeats,
+ *   releases, PR links), so a later build phase (the Ledger indexer) and the
+ *   client-side CLI share one truth.
+ *
+ * Spec ambiguities resolved here (each is flagged DECISION in a comment):
+ * 1. A second protocol claim by the same author while their earlier claim is
+ *    still alive is treated as a heartbeat, not a new claim (anti-squatting).
+ * 2. A promoted claim restarts its lease at promotion time: its expiry is
+ *    promotion + lease (capped by promotion + tenure cap). Without this, long
+ *    queues would be born dead.
+ * 3. A rocket reaction carries no timestamp in our input shape, so it counts
+ *    as a heartbeat "as of now" (extends expiry to now + lease).
+ * 4. A linked PR in state "closed" (not merged) keeps the claim "linked"
+ *    (lease frozen); the claim does not quietly resume.
+ * 5. A mergedPrNumber that is not among linkedPrs is synthesized as a linked
+ *    merged PR with createdAt = now. It freezes the current holder; it does
+ *    not resurrect a claim that already expired before the merge was known
+ *    (expiry is lazy but materialized, not speculative).
+ * 6. Heartbeats only count after a claim's activation; a queued claimant's
+ *    earlier comments do not pre-extend the lease.
+ * 7. Comments with unparseable createdAt are skipped entirely (they cannot be
+ *    ordered, and ordering is the whole game).
+ */
+import type { Verdict } from "./types.js";
+export declare const PROTOCOL_VERSION = 1;
+export declare const CLAIM_MARKER = "<!-- greenlight-claim v1 -->";
+export declare const RELEASE_MARKER = "<!-- greenlight-claim release -->";
+/** Spec 3.4: squatting budget, indexed active claims per account. */
+export declare const MAX_ACTIVE_CLAIMS_PER_ACCOUNT = 5;
+/** Repo claim policy, from `.greenlight/claims.json`. */
+export interface ClaimsPolicy {
+    protocol: 1;
+    lease_days: number;
+    tenure_cap_days: number;
+    queue: boolean;
+    who_can_claim: string;
+    maintainers: string[];
+    /** True when the policy text could not be parsed or named another protocol
+     *  version; the rest of the fields are the safe defaults. */
+    invalid?: boolean;
+}
+export declare function defaultClaimsPolicy(): ClaimsPolicy;
+/**
+ * Parse a `.greenlight/claims.json` body. Never throws: bad JSON (or a
+ * protocol version this engine cannot read) degrades to the defaults with
+ * `invalid: true`.
+ */
+export declare function parseClaimsPolicy(jsonText: string): ClaimsPolicy;
+export interface ParsedClaimComment {
+    isClaim: boolean;
+    isRelease: boolean;
+    plan: string | null;
+    etaDays: number | null;
+    queueOk: boolean | null;
+}
+/**
+ * Detect a protocol claim (or release) comment and parse the optional
+ * structured lines after the marker. Unknown lines are ignored; the marker
+ * alone is a valid claim.
+ */
+export declare function parseClaimComment(body: string): ParsedClaimComment;
+/** One issue comment, as seen by the protocol engine. */
+export interface ProtocolCommentInput {
+    author: string;
+    body: string;
+    createdAt: string;
+    id: number | string;
+    url?: string;
+}
+/** A reaction on a comment. No timestamp in this shape (see DECISION 3). */
+export interface ProtocolReactionInput {
+    commentId: number | string;
+    user: string;
+    content: string;
+}
+/**
+ * A PR with closing intent toward the issue. Callers pre-classify link
+ * strength (reuse guard's extractors); this engine only needs the timing.
+ */
+export interface ProtocolLinkedPrInput {
+    number: number;
+    state: "open" | "closed" | "merged";
+    createdAt: string;
+}
+export interface ClaimStateInput {
+    comments: ProtocolCommentInput[];
+    reactions?: ProtocolReactionInput[];
+    linkedPrs?: ProtocolLinkedPrInput[];
+    /** A PR known to have merged fixing this issue (used when linkedPrs lacks it). */
+    mergedPrNumber?: number | null;
+    policy?: ClaimsPolicy;
+    /** ISO "now". Defaults to the real current time; pass explicitly in tests. */
+    now?: string;
+    repo?: string;
+    issue?: number;
+}
+export type ClaimStateName = "active" | "linked" | "completed" | "released" | "expired" | "queued";
+export interface ClaimHistoryEvent {
+    event: string;
+    at: string;
+    by: string;
+}
+/** One protocol claim in the chain, fully resolved. */
+export interface ResolvedClaim {
+    /** 1-based position in the chronological chain (1 = head). */
+    position: number;
+    claimant: string;
+    claimedAt: string;
+    commentId: number | string;
+    commentUrl: string | null;
+    plan: string | null;
+    etaDays: number | null;
+    queueOk: boolean | null;
+    state: ClaimStateName;
+    /** When this claim's lease started (claimedAt, or promotion time). */
+    activatedAt: string;
+    expiresAt: string;
+    lastHeartbeatAt: string;
+    linkedPr: number | null;
+    history: ClaimHistoryEvent[];
+}
+/** The SPEC 3.2 record shape, as stored in the Ledger and returned by the API. */
+export interface ProtocolClaimRecord {
+    v: 1;
+    repo: string | null;
+    issue: number | null;
+    claimant: string;
+    claimed_at: string;
+    comment_url: string | null;
+    state: ClaimStateName;
+    lease_days: number;
+    expires_at: string;
+    last_heartbeat_at: string;
+    linked_pr: number | null;
+    queue_position: number;
+    history: ClaimHistoryEvent[];
+    over_cap?: boolean;
+}
+export interface ProtocolComputation {
+    /** Every protocol claim ever posted, in claimed_at order (ties by id). */
+    claims: ResolvedClaim[];
+    /** The claim holding the issue at `now`, or null when the issue is free. */
+    active: ResolvedClaim | null;
+    /** Claims waiting behind the holder (positions 2+). */
+    queue: ResolvedClaim[];
+    /** The SPEC 3.2 record for the active claim, or null. */
+    activeRecord: ProtocolClaimRecord | null;
+    policy: ClaimsPolicy;
+}
+/**
+ * Replay the claim chain for one issue and resolve every claim's state at
+ * `now`. Pure: no network, no exceptions on messy input.
+ */
+export declare function computeClaimState(input: ClaimStateInput): ProtocolComputation;
+/**
+ * Spec 3.4: mark claims whose claimant holds more than the squatting budget
+ * of active claims. `activeCounts` maps login -> active claim count (the
+ * caller supplies it from the Ledger or another computation; nothing is
+ * fetched here). Returns new records; the input is untouched.
+ */
+export declare function applyOverCap(records: ProtocolClaimRecord[], activeCounts: Record<string, number>): ProtocolClaimRecord[];
+export interface StatusCompetingPr {
+    number: number;
+    author: string;
+    state: "open" | "closed" | "merged";
+    url?: string;
+}
+export interface StatusGate {
+    kind: string;
+    detected: boolean;
+    evidence?: string;
+}
+export interface IssueStatusArgs {
+    issueUrl: string;
+    computation: ProtocolComputation;
+    competingPrs?: StatusCompetingPr[];
+    gates?: StatusGate[];
+    /** Null when the repo has no policy file (protocol works as a signal only). */
+    repoProtocol: {
+        honored: boolean;
+        lease_days: number;
+    } | null;
+    checkedAt?: string;
+    staleAfterSeconds?: number;
+}
+export interface IssueStatusPayload {
+    issue: string;
+    /** Null when there are no protocol claims: the verdict is the caller's. */
+    verdict: Verdict | null;
+    reason: string | null;
+    claim: {
+        state: ClaimStateName;
+        claimant: string;
+        claimed_at: string;
+        expires_at: string;
+        queue: Array<{
+            claimant: string;
+            position: number;
+            claimed_at: string;
+        }>;
+        over_cap?: boolean;
+    } | null;
+    protocol_note: string | null;
+    competing_prs: StatusCompetingPr[];
+    gates: StatusGate[];
+    repo_protocol: {
+        honored: boolean;
+        lease_days: number;
+    } | null;
+    checked_at: string;
+    stale_after_seconds: number;
+}
+/**
+ * Build the SPEC 5.1 issue-status payload from a protocol computation plus
+ * caller-supplied context (competing PRs, gates). Verdict mapping:
+ * active protocol claim -> TAKEN (expiry in the reason); a completed claim
+ * -> TAKEN naming the merged PR; expired-only history -> GO with a note;
+ * no protocol claims at all -> verdict null, claim null.
+ */
+export declare function buildIssueStatus(args: IssueStatusArgs): IssueStatusPayload;