@loopover/engine 1.0.0

package/dist/scoring/preview.d.ts

@@ -0,0 +1,246 @@
+import type { ContributorEvidenceRecord, RepositoryRecord, RepoTimeDecayOverrides, ScoringModelSnapshotRecord, ScorePreviewRecord } from "./types.js";
+export type ScorePreviewInput = {
+    repoFullName: string;
+    targetType?: ScorePreviewRecord["targetType"];
+    targetKey?: string | undefined;
+    contributorLogin?: string | undefined;
+    labels?: string[] | undefined;
+    linkedIssueMode?: "none" | "standard" | "maintainer" | undefined;
+    linkedIssueContext?: LinkedIssueMultiplierContext | undefined;
+    sourceTokenScore?: number | undefined;
+    totalTokenScore?: number | undefined;
+    sourceLines?: number | undefined;
+    testTokenScore?: number | undefined;
+    nonCodeTokenScore?: number | undefined;
+    /** Raw non-code line count before upstream's MAX_LINES_SCORED_FOR_NON_CODE_EXT cap. */
+    nonCodeLines?: number | undefined;
+    existingContributorTokenScore?: number | undefined;
+    openPrCount?: number | undefined;
+    /** Contributor's current open-issue count for the repo, used for the open-issue spam gate (#808). */
+    openIssueCount?: number | undefined;
+    /** Repo-level merged PR count for upstream contributor-history eligibility (#808). */
+    mergedPullRequests?: number | undefined;
+    /** Count of valid solved issues for upstream issue-discovery eligibility (#808). */
+    validSolvedIssues?: number | undefined;
+    /** Issue-discovery credibility for upstream issue-discovery eligibility (#808). */
+    issueCredibility?: number | undefined;
+    credibility?: number | undefined;
+    changesRequestedCount?: number | undefined;
+    fixedBaseScore?: number | undefined;
+    metadataOnly?: boolean | undefined;
+    pendingMergedPrCount?: number | undefined;
+    pendingClosedPrCount?: number | undefined;
+    approvedPrCount?: number | undefined;
+    observedApprovedPrCount?: number | undefined;
+    observedStalePrCount?: number | undefined;
+    observedClosedPrCount?: number | undefined;
+    observedDraftPrCount?: number | undefined;
+    observedBlockedPrCount?: number | undefined;
+    observedMaintainerPrCount?: number | undefined;
+    duplicateRiskCount?: number | undefined;
+    expectedOpenPrCountAfterMerge?: number | undefined;
+    projectedCredibility?: number | undefined;
+    scenarioNotes?: string[] | undefined;
+    pendingScenarioObserved?: boolean | undefined;
+    observedScenarioNotes?: string[] | undefined;
+    branchEligibility?: BranchEligibilityInput | undefined;
+    /** Hours since the PR merged, for upstream time-decay (#703). Absent / below the grace period = a fresh
+     *  PR (multiplier 1.0). Only consulted when `applyTimeDecay` is on. */
+    prAgeHours?: number | undefined;
+    /** Opt-in upstream time-decay (#703), default OFF and env-gated (SCORING_TIME_DECAY_ENABLED) at the call
+     *  site. Even when on, a fresh PR is unaffected, so it never changes a normal new-PR preview. */
+    applyTimeDecay?: boolean | undefined;
+};
+export type BranchEligibilityInput = {
+    status: "eligible" | "ineligible" | "unknown";
+    source?: "github_metadata" | "local_metadata" | "registry" | "user_supplied" | undefined;
+    reason?: string | undefined;
+    checkedAt?: string | undefined;
+    stale?: boolean | undefined;
+};
+export type BranchEligibilityResult = {
+    required: boolean;
+    status: "eligible" | "ineligible" | "unknown" | "not_required";
+    evidence: "provided" | "missing";
+    source: "github_metadata" | "local_metadata" | "registry" | "user_supplied" | "missing";
+    reason?: string | undefined;
+    checkedAt?: string | undefined;
+    stale: boolean;
+    warnings: string[];
+};
+export type LinkedIssueMultiplierStatus = "not_required" | "raw" | "plausible" | "validated" | "invalid" | "unavailable";
+export type LinkedIssueMultiplierSource = "none" | "user_supplied" | "official_mirror" | "github_cache" | "issue_quality" | "missing";
+export type LinkedIssueMultiplierContext = {
+    status?: Exclude<LinkedIssueMultiplierStatus, "not_required"> | undefined;
+    source?: Exclude<LinkedIssueMultiplierSource, "none"> | undefined;
+    issueNumbers?: number[] | undefined;
+    solvedByPullRequests?: number[] | undefined;
+    reason?: string | undefined;
+    warnings?: string[] | undefined;
+};
+export type LinkedIssueMultiplierDecision = {
+    mode: "none" | "standard" | "maintainer";
+    status: LinkedIssueMultiplierStatus;
+    source: LinkedIssueMultiplierSource;
+    eligible: boolean;
+    issueNumbers: number[];
+    solvedByPullRequests: number[];
+    baseMultiplier: number;
+    appliedMultiplier: number;
+    reason: string;
+    warnings: string[];
+};
+export type ScoreGateBlocker = {
+    code: "repo_not_registered" | "inactive_allocation" | "base_token_gate" | "open_pr_threshold" | "open_issue_threshold" | "merged_pr_history_floor" | "issue_discovery_validity_floor" | "credibility_floor" | "review_penalty" | "metadata_only" | "linked_issue_invalid" | "linked_issue_unvalidated" | "branch_ineligible" | "branch_eligibility_missing" | "duplicate_risk" | "stale_work";
+    severity: "blocker" | "reducer" | "context";
+    detail: string;
+};
+export type ScoreGateDelta = {
+    gate: "open_pr_threshold" | "open_issue_threshold" | "merged_pr_history_floor" | "issue_discovery_validity_floor" | "credibility_floor" | "linked_issue_multiplier";
+    current: string;
+    projected: string;
+    explanation: string;
+};
+export type ScoreScenarioPreview = {
+    name: "current" | "cleanGates" | "afterPendingMerges" | "afterApprovedPrsMerge" | "afterStalePrsClose" | "linkedIssueFixed" | "bestReasonableCase";
+    source: "current_data" | "user_supplied" | "github_observed" | "gittensory_projection";
+    assumptions: string[];
+    scoreEstimate: ScorePreviewResult["scoreEstimate"];
+    gates: ScorePreviewResult["gates"];
+    effectiveEstimatedScore: number;
+    underlyingPotentialScore: number;
+    blockedBy: ScoreGateBlocker[];
+    linkedIssueMultiplier: LinkedIssueMultiplierDecision;
+    deltaExplanation: string;
+};
+export type ScorePreviewResult = {
+    repoFullName: string;
+    generatedAt: string;
+    scoringModelSnapshotId: string;
+    activeModel: ScoringModelSnapshotRecord["activeModel"];
+    privateOnly: true;
+    laneMath: {
+        repoEmissionShare: number;
+        ossEmissionShare: number;
+        repoSlice: number;
+        directPrSlice: number;
+        issueDiscoverySlice: number;
+        issueDiscoveryShare: number;
+    };
+    scoreEstimate: {
+        /** Computed base score (the earned foundation before multipliers apply). */
+        baseScore: number;
+        /** The maximum possible baseScore given the active model and snapshot constants; used by the score
+         *  breakdown to surface saturation vs sub-cap status. Undefined when a fixedBaseScore override is in
+         *  effect (the override is not bounded by the model cap). */
+        baseScoreCap?: number;
+        densityMultiplier: number;
+        contributionBonus: number;
+        labelMultiplier: number;
+        issueMultiplier: number;
+        credibilityMultiplier: number;
+        reviewPenaltyMultiplier: number;
+        openPrMultiplier: number;
+        openIssueMultiplier: number;
+        /** Upstream merged-PR history floor (#808). 0 when below MIN_VALID_MERGED_PRS; 1 when unknown or eligible. */
+        mergedHistoryMultiplier: number;
+        /** Upstream issue-discovery validity floor (#808). 0 when below MIN_VALID_SOLVED_ISSUES or MIN_ISSUE_CREDIBILITY. */
+        issueDiscoveryHistoryMultiplier: number;
+        /** Upstream sigmoid time-decay multiplier (#703). 1 = no decay (fresh PR, or feature off). */
+        timeDecayMultiplier: number;
+        estimatedMergedScore: number;
+        pendingSaturationScore: number;
+    };
+    linkedIssueMultiplier: LinkedIssueMultiplierDecision;
+    gates: {
+        baseTokenGatePassed: boolean;
+        openPrThreshold: number;
+        openPrCount: number;
+        /** Effective open-PR collateral fraction (OPEN_PR_COLLATERAL_PERCENT × reviewCollateralMultiplier). */
+        collateralFraction: number;
+        /** Upstream open-PR review-collateral multiplier from CHANGES_REQUESTED reviews (≥ 1, capped). */
+        reviewCollateralMultiplier: number;
+        credibilityFloor: number;
+        credibilityObserved: number;
+        openIssueThreshold: number;
+        openIssueCount: number;
+        mergedPrFloor: number;
+        /** Observed merged PR count when supplied or inferred from contributor evidence; absent when unknown. */
+        mergedPullRequests?: number | undefined;
+        validSolvedIssuesFloor: number;
+        /** Observed valid solved-issue count when supplied; absent when unknown. */
+        validSolvedIssues?: number | undefined;
+        issueCredibilityFloor: number;
+        /** Observed issue-discovery credibility when supplied; absent when unknown. */
+        issueCredibility?: number | undefined;
+        /** Upstream non-code line scoring cap (MAX_LINES_SCORED_FOR_NON_CODE_EXT); non-code token score beyond this
+         *  many changed non-code lines is not scored. */
+        nonCodeLineCap: number;
+        /** Observed raw non-code line count before the cap; absent when no non-code line count was supplied. */
+        nonCodeLinesObserved?: number | undefined;
+    };
+    branchEligibility: BranchEligibilityResult;
+    effectiveEstimatedScore: number;
+    underlyingPotentialScore: number;
+    blockedBy: ScoreGateBlocker[];
+    gateDeltas: ScoreGateDelta[];
+    scenarioPreviews: ScoreScenarioPreview[];
+    scoreabilityStatus: "blocked" | "conditionally_scoreable" | "scoreable" | "hold";
+    warnings: string[];
+    assumptions: string[];
+    recommendation: {
+        level: "strong_fit" | "reasonable_fit" | "needs_work" | "hold";
+        actions: string[];
+    };
+};
+export declare function buildScorePreview(args: {
+    input: ScorePreviewInput;
+    repo: RepositoryRecord | null;
+    snapshot: ScoringModelSnapshotRecord;
+    contributorEvidence?: ContributorEvidenceRecord | null | undefined;
+}): ScorePreviewResult;
+export declare function makeScorePreviewRecord(input: ScorePreviewInput, snapshot: ScoringModelSnapshotRecord, result: ScorePreviewResult): ScorePreviewRecord;
+/** True when `label` matches the configured multiplier `pattern` under the SAME case-insensitive fnmatch glob
+ *  semantics scoring uses to resolve label multipliers (see {@link labelPatternToRegExp}). Exported so the
+ *  signals surfaces that audit configured label keys (config-quality, label-audit) match them as the GLOBS they
+ *  are: a `type:*` key must count `type:bug-fix` as observed/configured, not silently report it missing because
+ *  the literal pattern never appears verbatim on a real issue/PR. A literal key (no glob metacharacter) still
+ *  matches only its exact label, so existing configs behave identically. */
+export declare function labelMatchesPattern(label: string, pattern: string): boolean;
+export declare const LABEL_PATTERN_REGEXP_CACHE_MAX_ENTRIES = 256;
+export declare function clearLabelPatternRegExpCacheForTest(): void;
+export declare function labelPatternRegExpCacheKeysForTest(): string[];
+/**
+ * Project the standard linked-issue multiplier decision under the assumption that a planned PR
+ * becomes the merged solver of the given issue(s). Reuses {@link decideLinkedIssueMultiplier} — the
+ * same eligibility rule used by buildScorePreview — so standalone validators stay consistent with
+ * the scoring engine. The numeric multiplier on the returned decision is private; callers that are
+ * public-safe should surface only `eligible`/`status`/`reason`.
+ */
+export declare function projectLinkedIssueMultiplierForPlannedSolve(issueNumbers: number[]): LinkedIssueMultiplierDecision;
+/**
+ * Resolve a repo's time-decay curve: each parameter is the repo's per-repo override (from the registry's
+ * `scoring.time_decay`) when present, else the global default constant from the live scoring snapshot.
+ * Mirrors upstream's `resolve_time_decay` (RepoTimeDecayConfig overlaid on the module constants).
+ *
+ * Parity note (#1320): upstream coerces ONLY `grace_period_hours` to an integer
+ * (`grace_period_hours=int(pick(...))`) while the three curve params stay floats. A maintainer may legally
+ * configure a fractional grace (upstream validates `0 <= grace_period_hours <= 168`), so the resolved grace
+ * must be truncated toward zero to match the validator — otherwise a PR aged between `trunc(grace)` and
+ * `grace` is treated as fresh in the preview but already decaying upstream.
+ */
+export declare function resolveTimeDecay(constants: Record<string, number>, overrides?: RepoTimeDecayOverrides | null): {
+    gracePeriodHours: number;
+    sigmoidMidpointDays: number;
+    sigmoidSteepness: number;
+    minMultiplier: number;
+};
+/**
+ * Upstream gittensor's sigmoid time-decay multiplier (#703), ported verbatim from the validator's
+ * `calculate_time_decay` (gittensor/validator/utils/datetime_utils.py): for the first grace-period hours the
+ * multiplier is exactly 1.0 (hard cutoff); after that it follows a logistic on days-since-merge centred at
+ * the sigmoid midpoint (50% at that point), floored at the minimum multiplier. The curve params are
+ * resolved PER-REPO (overrides ?? snapshot defaults), so each maintainer's registry hyperparameters apply.
+ * Pure + deterministic.
+ */
+export declare function calculateTimeDecay(prAgeHours: number, constants: Record<string, number>, overrides?: RepoTimeDecayOverrides | null): number;