@reneturcios/greenlight 0.3.10 → 0.4.0

package/dist/protocol-fetch.js

@@ -0,0 +1,350 @@
+/**
+ * Claim Protocol wiring (Greenlight v0.4.0): fetch layer, status assembly,
+ * and the check/guard integration points.
+ *
+ * The engine itself (src/protocol.ts) is pure: it never touches the network.
+ * This module assembles the engine's inputs from the GitHub API, computes
+ * issue status payloads, and merges protocol verdicts with the legacy
+ * check verdicts. All network access goes through injectable fetchers
+ * (the GuardDeps seam pattern), so every path is unit-testable without
+ * touching the API.
+ *
+ * Precedence (protocol vs legacy verdict), documented here because two
+ * engines now speak: the protocol verdict overrides legacy *claim
+ * inference* only. It never overrides gates, and it never overrides
+ * cross-referenced PR evidence. When both the protocol and a
+ * cross-referenced PR say TAKEN, the reasons merge.
+ */
+import { apiGet, ApiNotFoundError, buildIssueSnapshot, fetchLinkedPRs, } from "./github.js";
+import { scoreIssue } from "./verdict.js";
+import { computeClaimState, parseClaimsPolicy, parseClaimComment, defaultClaimsPolicy, buildIssueStatus, } from "./protocol.js";
+async function paginate(path) {
+    const out = [];
+    for (let page = 1; page <= 5; page++) {
+        const sep = path.includes("?") ? "&" : "?";
+        const data = (await apiGet(`${path}${sep}per_page=100&page=${page}`));
+        out.push(...data);
+        if (data.length < 100)
+            break;
+    }
+    return out;
+}
+async function defaultFetchComments(owner, repo, number) {
+    const data = await paginate(`/repos/${owner}/${repo}/issues/${number}/comments`);
+    return data.map((c) => ({
+        id: typeof c.id === "number" ? c.id : String(c.id ?? ""),
+        author: String(c.user?.login ?? "unknown"),
+        body: String(c.body ?? ""),
+        createdAt: String(c.created_at ?? ""),
+        url: typeof c.html_url === "string" ? c.html_url : undefined,
+    }));
+}
+async function defaultFetchReactions(owner, repo, commentId) {
+    try {
+        const data = (await apiGet(`/repos/${owner}/${repo}/issues/comments/${commentId}/reactions`));
+        return (data ?? []).map((r) => ({
+            commentId,
+            user: String(r.user?.login ?? "unknown"),
+            content: String(r.content ?? ""),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read `.greenlight/claims.json` from the repo's default branch. 404 means
+ * the repo has not adopted the protocol (honored: false); any other failure
+ * degrades the same way rather than claiming protocol state we cannot see.
+ */
+async function defaultFetchPolicy(owner, repo) {
+    try {
+        const repoInfo = (await apiGet(`/repos/${owner}/${repo}`));
+        const branch = typeof repoInfo.default_branch === "string" ? repoInfo.default_branch : "main";
+        const file = (await apiGet(`/repos/${owner}/${repo}/contents/.greenlight/claims.json?ref=${encodeURIComponent(branch)}`));
+        if (typeof file.content !== "string") {
+            return { honored: false, policy: defaultClaimsPolicy(), invalid: false };
+        }
+        const text = Buffer.from(file.content, "base64").toString("utf8");
+        const policy = parseClaimsPolicy(text);
+        return { honored: true, policy, invalid: !!policy.invalid };
+    }
+    catch (err) {
+        if (err instanceof ApiNotFoundError) {
+            return { honored: false, policy: defaultClaimsPolicy(), invalid: false };
+        }
+        return { honored: false, policy: defaultClaimsPolicy(), invalid: false };
+    }
+}
+/**
+ * Assemble a protocol state from already-fetched data. Pure: the unit
+ * tests drive every integration path through this without the network.
+ */
+export function assembleProtocolState(owner, repo, number, comments, reactions, linkedPrInputs, mergedPrNumber, policyFetch, nowIso) {
+    const inputs = comments.map((c) => ({
+        author: c.author,
+        body: c.body,
+        createdAt: c.createdAt,
+        id: c.id,
+        url: c.url,
+    }));
+    const reactionInputs = reactions.map((r) => ({
+        commentId: r.commentId,
+        user: r.user,
+        content: r.content,
+    }));
+    const computation = computeClaimState({
+        comments: inputs,
+        reactions: reactionInputs,
+        linkedPrs: linkedPrInputs,
+        mergedPrNumber,
+        policy: policyFetch.policy,
+        now: nowIso,
+        repo: `${owner}/${repo}`,
+        issue: number,
+    });
+    return {
+        computation,
+        repoProtocol: policyFetch.honored
+            ? { honored: true, lease_days: policyFetch.policy.lease_days }
+            : null,
+        policyInvalid: policyFetch.invalid,
+        issueUrl: `https://github.com/${owner}/${repo}/issues/${number}`,
+        linkedPrDetails: [],
+    };
+}
+/**
+ * Full protocol fetch for one issue: comments, reactions on marker
+ * comments only, the repo policy, and timing detail for closing-strength
+ * linked PRs. Best-effort: anything unreadable degrades to "no evidence".
+ */
+export async function fetchProtocolState(owner, repo, number, deps = {}) {
+    const nowIso = (deps.now ?? (() => new Date().toISOString()))();
+    const fetchComments = deps.fetchComments ?? defaultFetchComments;
+    const fetchReactions = deps.fetchReactions ?? defaultFetchReactions;
+    const fetchPRs = deps.fetchLinkedPRs ?? fetchLinkedPRs;
+    const fetchPolicy = deps.fetchPolicy ?? defaultFetchPolicy;
+    let comments = [];
+    try {
+        comments = await fetchComments(owner, repo, number);
+    }
+    catch {
+        comments = [];
+    }
+    const markerComments = comments.filter((c) => parseClaimComment(c.body).isClaim);
+    // Reactions are fetched only for marker comments: the heartbeat signal
+    // exists only where a protocol claim exists, and each reaction list is
+    // its own API call.
+    const reactions = [];
+    for (const mc of markerComments) {
+        try {
+            const rs = await fetchReactions(owner, repo, mc.id);
+            for (const r of rs)
+                reactions.push({ ...r, commentId: mc.id });
+        }
+        catch {
+            // A missing reactions list just means no heartbeats from reactions.
+        }
+    }
+    let policyFetch;
+    try {
+        policyFetch = await fetchPolicy(owner, repo);
+    }
+    catch {
+        policyFetch = { honored: false, policy: defaultClaimsPolicy(), invalid: false };
+    }
+    let linked = [];
+    try {
+        linked = await fetchPRs(owner, repo, number);
+    }
+    catch {
+        linked = [];
+    }
+    const closing = linked.filter((p) => p.linkStrength === "closing");
+    // Detail for closing PRs: author and created_at feed the status payload
+    // and the engine's link timing. The engine only needs timing when
+    // protocol claims exist, but the payload wants authors either way, so one
+    // pass serves both. A failed detail fetch degrades: the PR stays in the
+    // payload from snapshot data, and merged ones still reach the engine
+    // through the mergedPrNumber fallback (the engine synthesizes timing for
+    // those; see DECISION 5 in protocol.ts).
+    const details = [];
+    const linkedPrInputs = [];
+    let mergedPrNumber = null;
+    for (const p of closing) {
+        try {
+            const d = (await apiGet(`/repos/${owner}/${repo}/pulls/${p.number}`));
+            const merged = d.merged_at != null;
+            const state = merged ? "merged" : p.state === "closed" ? "closed" : "open";
+            const createdAt = typeof d.created_at === "string" ? d.created_at : null;
+            const author = String(d.user?.login ?? "unknown");
+            details.push({ number: p.number, author, state, url: p.url, createdAt });
+            if (createdAt) {
+                linkedPrInputs.push({ number: p.number, state, createdAt });
+            }
+            else if (merged && mergedPrNumber === null) {
+                mergedPrNumber = p.number;
+            }
+            if (merged && mergedPrNumber === null)
+                mergedPrNumber = p.number;
+        }
+        catch {
+            details.push({ number: p.number, author: "unknown", state: p.state, url: p.url, createdAt: null });
+            if (p.state === "merged" && mergedPrNumber === null)
+                mergedPrNumber = p.number;
+        }
+    }
+    const result = assembleProtocolState(owner, repo, number, comments, reactions, linkedPrInputs, mergedPrNumber, policyFetch, nowIso);
+    result.linkedPrDetails = details;
+    return result;
+}
+/**
+ * The full pre-flight computation for one issue: the legacy verdict
+ * machinery plus the protocol state, assembled into the SPEC 5.1 payload.
+ */
+export async function computeIssueStatus(owner, repo, number, opts = {}) {
+    const deps = opts.deps ?? {};
+    const fetchSnapshot = deps.fetchSnapshot ?? buildIssueSnapshot;
+    const snapshot = await fetchSnapshot(owner, repo, number);
+    if (opts.externalGates)
+        snapshot.externalGates = opts.externalGates;
+    const legacy = scoreIssue(snapshot);
+    const proto = await fetchProtocolState(owner, repo, number, deps);
+    const competingPrs = proto.linkedPrDetails.map((d) => ({
+        number: d.number,
+        author: d.author,
+        state: d.state,
+        url: d.url,
+    }));
+    const gates = legacy.gates.map((g) => ({
+        kind: g.kind,
+        detected: g.detected,
+        ...(typeof g.evidence === "string" && g.evidence ? { evidence: g.evidence } : {}),
+    }));
+    const status = buildIssueStatus({
+        issueUrl: snapshot.sourceUrl,
+        computation: proto.computation,
+        competingPrs,
+        gates,
+        repoProtocol: proto.repoProtocol,
+        checkedAt: new Date().toISOString(),
+    });
+    return {
+        snapshot,
+        legacy,
+        status,
+        computation: proto.computation,
+        repoProtocol: proto.repoProtocol,
+        policyInvalid: proto.policyInvalid,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Verdict merge: the precedence rule                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * Reason prefixes produced by the legacy verdict engine's claim rules
+ * (rules 4, 5/5b, 6/6b, and warning W in verdict.ts). When the protocol
+ * holds a live claim, these lines are the ones the protocol supersedes;
+ * every other reason (PR evidence, gates, duplicates, bounty, decay)
+ * survives the merge.
+ */
+const CLAIM_REASON_PREFIXES = [
+    "claim race: ",
+    "claimed by ",
+    "stale claim by ",
+    "stale partial claim by ",
+    "soft claim by ",
+];
+function isClaimDerivedReason(reason) {
+    if (CLAIM_REASON_PREFIXES.some((p) => reason.startsWith(p)))
+        return true;
+    // Rule 5b fresh partial: "<author> claimed the <scope> part ...; the rest may still be open"
+    return / claimed .*; the rest may still be open$/.test(reason);
+}
+/** Flags the legacy engine sets for claim inference; the protocol replaces them. */
+const CLAIM_DERIVED_FLAGS = ["claimed", "stale_claim", "partial-claim", "weak-claim"];
+/**
+ * Merge the protocol verdict with the legacy verdict.
+ *
+ * Precedence: the protocol verdict overrides legacy *claim inference*.
+ * It never overrides gates, and it never overrides cross-referenced PR
+ * evidence. When both the protocol and a cross-referenced PR say TAKEN,
+ * the reasons merge (protocol reason first, PR evidence kept).
+ */
+export function mergeProtocolVerdict(legacy, status) {
+    const protocolField = {
+        verdict: status.verdict,
+        reason: status.reason,
+        claim: status.claim,
+        protocol_note: status.protocol_note,
+        repo_protocol: status.repo_protocol,
+    };
+    const protocolLines = [];
+    if (status.verdict === "TAKEN" && status.claim) {
+        const c = status.claim;
+        protocolLines.push(`protocol claim: @${c.claimant} holds this issue until ${c.expires_at.slice(0, 10)} (state: ${c.state})`);
+        if (c.queue.length > 0) {
+            protocolLines.push(`queue: ${c.queue.map((q) => `@${q.claimant} (#${q.position})`).join(", ")}`);
+        }
+        if (status.protocol_note)
+            protocolLines.push(status.protocol_note);
+        if (legacy.verdict === "GATED") {
+            // Gates are ritual, not inference: a repo that blocks outside PRs
+            // blocks them no matter who holds a claim. The protocol becomes
+            // context, not a verdict.
+            return {
+                verdict: "GATED",
+                reasons: [...legacy.reasons, status.reason ?? "protocol claim active"],
+                flags: [...legacy.flags, "protocol-claim"],
+                claims: legacy.claims,
+                gates: legacy.gates,
+                protocol: protocolField,
+                protocolLines,
+            };
+        }
+        // Protocol wins over the legacy claim assessment; PR-derived evidence
+        // (open closing PR, cross-referenced PRs) survives the merge.
+        const keptReasons = legacy.reasons.filter((r) => !isClaimDerivedReason(r));
+        const keptFlags = legacy.flags.filter((f) => !CLAIM_DERIVED_FLAGS.includes(f));
+        return {
+            verdict: "TAKEN",
+            reasons: [status.reason ?? "protocol claim active", ...keptReasons],
+            flags: ["protocol-claim", ...keptFlags],
+            claims: legacy.claims,
+            gates: legacy.gates,
+            protocol: protocolField,
+            protocolLines,
+        };
+    }
+    if (status.verdict === "GO") {
+        // Expired-only history: the protocol has nothing live, so the verdict
+        // stands and the note rides along.
+        protocolLines.push(status.protocol_note ?? "past protocol claims have all ended; no active lease");
+        return {
+            verdict: legacy.verdict,
+            reasons: [...legacy.reasons, status.reason ?? status.protocol_note ?? "protocol: no active claims"],
+            flags: [...legacy.flags, "protocol-expired"],
+            claims: legacy.claims,
+            gates: legacy.gates,
+            protocol: protocolField,
+            protocolLines,
+        };
+    }
+    // No protocol claims at all: legacy stands, one quiet line.
+    protocolLines.push(status.protocol_note ?? "no protocol claims on this issue");
+    return {
+        verdict: legacy.verdict,
+        reasons: legacy.reasons,
+        flags: legacy.flags,
+        claims: legacy.claims,
+        gates: legacy.gates,
+        protocol: protocolField,
+        protocolLines,
+    };
+}
+/** The `check` command's full pipeline: legacy verdict merged with protocol. */
+export async function checkIssueWithProtocol(owner, repo, number, opts = {}) {
+    const { snapshot, legacy, status } = await computeIssueStatus(owner, repo, number, opts);
+    return { snapshot, legacy, status, merged: mergeProtocolVerdict(legacy, status) };
+}
+//# sourceMappingURL=protocol-fetch.js.map

package/dist/protocol-fetch.js.map

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

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;