@loopover/engine 1.0.0

package/dist/advisory/gate-advisory.d.ts

@@ -0,0 +1,151 @@
+import type { Advisory, AdvisoryConclusion, AdvisoryFinding, AdvisorySeverity, GateRuleMode, PullRequestRecord, RepositoryRecord } from "../types/predicted-gate-types.js";
+import type { GuardrailPathMatch } from "../signals/change-guardrail.js";
+export type GateCheckConclusion = "success" | "failure" | "action_required" | "neutral" | "skipped";
+export type GateCheckPolicy = {
+    linkedIssueGateMode?: GateRuleMode | undefined;
+    duplicatePrGateMode?: GateRuleMode | undefined;
+    /** Historical readiness-score mode. Retained for config compatibility, but readiness is informational only:
+     *  a low readiness score may be surfaced as an advisory warning and must never fail the Gate check. */
+    qualityGateMode?: GateRuleMode | undefined;
+    qualityGateMinScore?: number | null | undefined;
+    /** When `block`, a dual-model AI consensus defect (`ai_consensus_defect` finding) becomes a hard
+     *  blocker. Defaults to advisory — AI never blocks unless the maintainer opts in. */
+    aiReviewGateMode?: GateRuleMode | undefined;
+    /** Minimum calibrated confidence (0-1) configured for AI close calibration. AI defect findings still BLOCK the
+     *  gate under `aiReviewGateMode: block` even when below this floor — the floor never turns a real defect into a
+     *  non-blocker on its own. What varies below the floor is {@link aiReviewLowConfidenceDisposition}. `null`/
+     *  undefined ⇒ the 0.93 default. */
+    aiReviewCloseConfidence?: number | null | undefined;
+    /** Disposition for a sub-floor `ai_consensus_defect`/`ai_review_split` finding (#4603) — see the host copy's
+     *  doc comment (`src/rules/advisory.ts` / `src/types.ts`) for the full semantics. `null`/undefined ⇒
+     *  `hold_for_review` (the shipped default). Only `advisory_only` changes what `isConfiguredGateBlocker` returns
+     *  for these codes here; `one_shot`/`hold_for_review` are indistinguishable to this predictor (the
+     *  `hold_for_review` vs `one_shot` difference is a disposition-planner concern this predictor doesn't model). */
+    aiReviewLowConfidenceDisposition?: "one_shot" | "hold_for_review" | "advisory_only" | undefined;
+    readinessScore?: number | null | undefined;
+    /** When `block`, the deterministic slop score becomes a hard blocker once `slopRisk >= slopGateMinScore`
+     *  (default threshold 60, the `high` band). Defaults to off/advisory — slop never blocks unless opted in. */
+    slopGateMode?: GateRuleMode | undefined;
+    slopGateMinScore?: number | null | undefined;
+    slopRisk?: number | null | undefined;
+    /** Master "merge-readiness" composite (#551). When set (advisory/block) it OVERRIDES all four sub-gates —
+     *  linked-issue, duplicate, quality/readiness, slop — to its mode, so a maintainer flips ONE switch instead
+     *  of four and the review-agent check stays the single required check. `off` = sub-gates use their own modes. */
+    mergeReadinessGateMode?: GateRuleMode | undefined;
+    /** Focus-manifest policy gate (#555). When `block`, linked-issue/test policy findings become hard blockers.
+     *  Path-based manual-review holds are configured only with `settings.hardGuardrailGlobs`.
+     *  An INDEPENDENT dimension, deliberately NOT folded into the merge-readiness composite so #555 stays focused.
+     *  `off`/`advisory` = the findings stay advisory (never block). Default off. */
+    manifestPolicyGateMode?: GateRuleMode | undefined;
+    /** Self-authored linked-issue gate. When `block`, a `self_authored_linked_issue` finding — raised when
+     *  the PR author also filed the linked issue — becomes a hard blocker. Defaults to `advisory` — the
+     *  finding is surfaced but never blocks unless the maintainer opts in. */
+    selfAuthoredLinkedIssueGateMode?: GateRuleMode | undefined;
+    /** CLA / license-compatibility gate (#2564). When `block`, a `cla_consent_missing` finding — raised when
+     *  neither configured detection method (a consent phrase in the PR body, or a named CLA-bot check-run
+     *  conclusion) confirms consent — becomes a hard blocker. `off` (default) = no finding at all; `advisory` =
+     *  the finding surfaces but never blocks. Independent of every other gate dimension, like manifestPolicy. */
+    claGateMode?: GateRuleMode | undefined;
+    /** First-time-contributor grace (#552). RESERVED / currently INERT (#2266): threaded through from config,
+     *  but evaluateGateCheckCore never reads it (see the removal note below) — a would-be blocker gates a
+     *  genuine newcomer exactly like a repeat contributor. Kept for potential future use. */
+    firstTimeContributorGrace?: boolean | undefined;
+    /** The PR author's merged PR count in THIS repo. RESERVED / currently INERT (#2266) alongside
+     *  firstTimeContributorGrace above — populated but never read by the gate evaluator today. */
+    authorMergedPrCount?: number | undefined;
+    /** The PR author's closed-unmerged PR count in THIS repo. RESERVED / currently INERT (#2266) alongside
+     *  firstTimeContributorGrace above — populated but never read by the gate evaluator today. */
+    authorClosedUnmergedPrCount?: number | undefined;
+    /** The PR author's confirmed-Gittensor status. Carried for context/telemetry only — it no longer
+     *  changes the gate verdict (every author is gated identically; a configured blocker fails the gate
+     *  regardless of confirmed status, which now affects only on-chain scoring). `undefined` = unresolved.
+     *  (#gate-nonconfirmed) */
+    confirmedContributor?: boolean | undefined;
+    /** PR-size HOLD (#gate-size). When set (advisory/block), a PR with >= sizeGateMaxFiles changed files OR
+     *  >= sizeGateMaxLines changed (added+deleted) lines that would OTHERWISE pass is HELD for manual review — a
+     *  neutral gate → "manual" verdict, never auto-merged and never a hard failure. Defaults off; thresholds default
+     *  to 10 files / 1000 lines. This is a HOLD (advisory dry-run friendly), not a close. */
+    sizeGateMode?: GateRuleMode | undefined;
+    /** Lockfile-tamper-risk gate (#2563). When `block`, a `lockfile_tamper_risk` finding (produced by
+     *  review/lockfile-tamper.ts when a changed package-lock.json's resolved/integrity value changed without a
+     *  matching package.json version bump, or points off the npm registry) becomes a hard blocker. Defaults to
+     *  `off` — the finding is never produced when off, and never blocks under `advisory`. */
+    lockfileIntegrityGateMode?: GateRuleMode | undefined;
+    /** Aggregate change size, threaded from the resolved file list (changedLineCount = additions + deletions). */
+    changedFileCount?: number | null | undefined;
+    changedLineCount?: number | null | undefined;
+    /** True when the PR's diff trips a configured hard guardrail path.
+     *  A guardrail hit HOLDS an otherwise-passing gate for manual review (neutral → "manual"), never auto-merged.
+     *  Empty/absent guardrail globs disable this path. (#gate-guardrail) */
+    guardrailHit?: boolean | undefined;
+    /** Matched changed paths/globs for the guardrail hold. Empty when the caller only knows "unknown path set"
+     *  (fail-safe guardrail hit) rather than exact paths. */
+    guardrailMatches?: GuardrailPathMatch[] | undefined;
+    /** Dry-run disposition (#gate-dryrun). When true, the gate ALSO computes the would-be conclusion with every
+     *  `advisory` sub-gate promoted to `block` and exposes it as `displayConclusion` (the rendered merge/close/manual
+     *  verdict), WITHOUT changing the posted, non-enforcing `conclusion`. Lets advisory mode show exactly what it WOULD
+     *  do (close/merge/manual) before the maintainer flips to real enforcement. Default off. */
+    dryRun?: boolean | undefined;
+};
+export type GateCheckEvaluation = {
+    enabled: boolean;
+    conclusion: GateCheckConclusion;
+    /** Dry-run only (#gate-dryrun): the would-be conclusion (advisory sub-gates promoted to block) used to render the
+     *  merge/close/manual verdict. Absent ⇒ the renderer falls back to `conclusion`. Never affects what is posted. */
+    displayConclusion?: GateCheckConclusion | undefined;
+    title: string;
+    summary: string;
+    blockers: AdvisoryFinding[];
+    warnings: AdvisoryFinding[];
+};
+export declare function buildPullRequestAdvisory(repo: RepositoryRecord | null, pr: PullRequestRecord | null, context?: {
+    otherOpenPullRequests?: PullRequestRecord[];
+    requireLinkedIssue?: boolean;
+    /** Duplicate-winner adjudication (#dup-winner). When true AND this PR is the cluster winner (the lowest
+     *  open sibling number), the `duplicate_pr_risk` finding is suppressed so the winner is not gate-blocked /
+     *  closed as a duplicate. Default/false ⇒ every duplicate sibling keeps the finding (byte-identical). The
+     *  caller sets this to `env.GITTENSORY_DUPLICATE_WINNER === "true"`. */
+    duplicateWinnerEnabled?: boolean;
+    /** Author logins of the linked issues (one entry per resolved issue, may be null when unknown). Used to
+     *  surface a `self_authored_linked_issue` finding when the PR author also opened the linked issue. Absent
+     *  or empty ⇒ the finding is never raised (fail-open: unknown issue authorship stays advisory-only). */
+    linkedIssueAuthorLogins?: (string | null | undefined)[];
+    /** Same-account issue-avoidance countermeasure (#unlinked-issue-guardrail-followup): `pr.linkedIssues` is
+     *  populated by a pure body-text regex that never checks whether the cited issue is actually OPEN, so a
+     *  contributor can satisfy `linkedIssueGateMode: "block"` by citing an already-CLOSED (or fabricated)
+     *  issue number. When the caller has live-verified that NONE of this PR's linked issue numbers resolve to
+     *  a confirmed-open issue, it sets this true and `missing_linked_issue` fires exactly as if nothing were
+     *  linked at all. Absent/false ⇒ byte-identical to today (presence alone still satisfies the requirement)
+     *  — this is fail-open by construction: the caller only ever sets it true after a live check confirms
+     *  every reference is dead, never on ambiguity. */
+    confirmedNoOpenLinkedIssue?: boolean;
+}): Advisory;
+declare function advisory(targetType: Advisory["targetType"], targetKey: string, repoFullName: string, findings: AdvisoryFinding[], fallbackSummary: string, pullNumber?: number, issueNumber?: number, headSha?: string): Advisory;
+declare function highestSeverity(findings: AdvisoryFinding[]): AdvisorySeverity;
+declare function conclusionForSeverity(severity: AdvisorySeverity, findings: AdvisoryFinding[]): AdvisoryConclusion;
+/** Oversized-PR manual-review HOLD finding (#gate-size), or null when the size gate is off or the PR is within both
+ *  thresholds. A HOLD (→ neutral gate → "manual" verdict), never a hard blocker, so it is dry-run/advisory friendly. */
+declare function buildSizeHoldFinding(policy: GateCheckPolicy): AdvisoryFinding | null;
+declare function buildGuardrailHoldFinding(matches?: GuardrailPathMatch[]): AdvisoryFinding;
+declare function promoteAdvisoryToBlock(policy: GateCheckPolicy): GateCheckPolicy;
+export declare function evaluateGateCheck(advisoryResult: Advisory, policy?: GateCheckPolicy): GateCheckEvaluation;
+declare function gatePolicyBlocks(mode: GateRuleMode | undefined, defaultMode: GateRuleMode): boolean;
+declare function isConfiguredGateBlocker(finding: AdvisoryFinding, policy: GateCheckPolicy): boolean;
+declare function buildQualityGateWarning(policy: GateCheckPolicy): AdvisoryFinding | null;
+declare function buildSlopGateBlocker(policy: GateCheckPolicy): AdvisoryFinding | null;
+declare function gateMode(value: GateRuleMode | null | undefined): GateRuleMode;
+/** @internal Exported for unit tests of advisory severity wiring. */
+export declare const gateAdvisoryInternals: {
+    advisory: typeof advisory;
+    highestSeverity: typeof highestSeverity;
+    conclusionForSeverity: typeof conclusionForSeverity;
+    buildSizeHoldFinding: typeof buildSizeHoldFinding;
+    buildGuardrailHoldFinding: typeof buildGuardrailHoldFinding;
+    promoteAdvisoryToBlock: typeof promoteAdvisoryToBlock;
+    isConfiguredGateBlocker: typeof isConfiguredGateBlocker;
+    buildQualityGateWarning: typeof buildQualityGateWarning;
+    buildSlopGateBlocker: typeof buildSlopGateBlocker;
+    gateMode: typeof gateMode;
+    gatePolicyBlocks: typeof gatePolicyBlocks;
+};
+export {};