@oss-scout/core 0.10.0 → 1.0.0

package/dist/core/issue-graphql.js

@@ -0,0 +1,108 @@
+/**
+ * Batched GraphQL prefetch of issue "core" data (#169).
+ *
+ * `vetIssue` re-fetches each issue's basic fields (title, body, state, labels,
+ * timestamps, comment count) via a per-issue REST `issues.get`. When a search
+ * surfaces N issues that all need vetting, that is N separate REST calls before
+ * any of the deeper checks even start.
+ *
+ * `prefetchIssueCores` collapses those N calls into ONE aliased GraphQL query.
+ * The result is a map keyed by `owner/repo#number`; `vetIssue` consumes a hit
+ * instead of calling `issues.get`, and falls back to REST for any miss (a
+ * deleted issue, a permission error on one repo, or a non-fatal GraphQL blip).
+ *
+ * Scope is deliberately limited to the `issues.get` fields. The other vetting
+ * calls (timeline-based PR detection, claim scanning, project health,
+ * contribution guidelines) stay REST — batching those has pagination-semantics
+ * divergence risk and is left as a follow-up.
+ */
+import { rethrowIfFatal, errorMessage } from "./errors.js";
+import { warn } from "./logger.js";
+const MODULE = "issue-graphql";
+/** Map key for a prefetched core, also used by callers to look one up. */
+export function issueCoreKey(owner, repo, number) {
+    return `${owner}/${repo}#${number}`;
+}
+function normalizeNode(node) {
+    return {
+        id: node.databaseId,
+        title: node.title,
+        body: node.body ?? "",
+        state: node.state === "CLOSED" ? "closed" : "open",
+        labels: node.labels.nodes.map((l) => l.name),
+        commentCount: node.comments.totalCount,
+        createdAt: node.createdAt,
+        updatedAt: node.updatedAt,
+    };
+}
+/**
+ * Batch-fetch issue core data with one aliased GraphQL query. Returns a map of
+ * `owner/repo#number` to the normalized core. Issues that the query could not
+ * resolve are simply absent — the caller is expected to fall back to REST for
+ * any key not in the map.
+ *
+ * Failure handling mirrors the rest of the vetter: fatal errors (401 / rate
+ * limit) propagate via `rethrowIfFatal`; a partial-data GraphQL error (one bad
+ * issue in the batch) keeps the aliases that did resolve; any other non-fatal
+ * error returns whatever resolved so the caller degrades to all-REST.
+ */
+export async function prefetchIssueCores(octokit, issues) {
+    const result = new Map();
+    if (issues.length === 0)
+        return result;
+    // Dedup by key so a repeated issue does not allocate a redundant alias.
+    const unique = [
+        ...new Map(issues.map((i) => [issueCoreKey(i.owner, i.repo, i.number), i])).values(),
+    ];
+    // Build a parameterized query — owner/repo/number go through GraphQL
+    // variables, never string-interpolated into the query body, so there is no
+    // injection surface even though parseGitHubUrl already validates them.
+    const varDefs = [];
+    const selections = [];
+    const variables = {};
+    unique.forEach((iss, i) => {
+        varDefs.push(`$o${i}: String!, $n${i}: String!, $num${i}: Int!`);
+        variables[`o${i}`] = iss.owner;
+        variables[`n${i}`] = iss.repo;
+        variables[`num${i}`] = iss.number;
+        selections.push(`i${i}: repository(owner: $o${i}, name: $n${i}) {
+        issue(number: $num${i}) {
+          databaseId
+          title
+          body
+          state
+          labels(first: 100) { nodes { name } }
+          comments { totalCount }
+          createdAt
+          updatedAt
+        }
+      }`);
+    });
+    const query = `query batchIssueCores(${varDefs.join(", ")}) {\n${selections.join("\n")}\n}`;
+    let data;
+    try {
+        data = await octokit.graphql(query, variables);
+    }
+    catch (err) {
+        rethrowIfFatal(err);
+        // octokit's GraphqlResponseError attaches the resolved aliases to `.data`
+        // when only some issues in the batch errored (e.g. one was deleted).
+        const partial = err.data;
+        if (partial) {
+            data = partial;
+        }
+        else {
+            warn(MODULE, `GraphQL prefetch failed, falling back to REST: ${errorMessage(err)}`);
+            return result;
+        }
+    }
+    unique.forEach((iss, i) => {
+        const node = data?.[`i${i}`]?.issue;
+        // A null node (deleted/inaccessible) or a null databaseId leaves the key
+        // absent so the caller fetches it via REST.
+        if (!node || node.databaseId == null)
+            return;
+        result.set(issueCoreKey(iss.owner, iss.repo, iss.number), normalizeNode(node));
+    });
+    return result;
+}

package/dist/core/issue-vetting.d.ts

@@ -7,7 +7,8 @@
  * - repo-health.ts       — project health, contribution guidelines
  */
 import { Octokit } from "@octokit/rest";
-import { type SearchPriority, type IssueCandidate, type ProjectCategory } from "./types.js";
+import { type SearchPriority, type IssueCandidate, type ProjectCategory, type ScoutPreferences, type ScoutState, type MergedPRRecord, type ClosedPRRecord, type OpenPRRecord } from "./types.js";
+import { type PrefetchedIssueCore } from "./issue-graphql.js";
 /**
  * Feature-mode signals supplied by the caller (orchestrator) — the vetter
  * does NOT extract these from the GitHub issue itself. When passed, they
@@ -30,6 +31,15 @@ export type FeatureSignals = {
      */
     wontfixNoContributor?: boolean;
 };
+/**
+ * SLM pre-triage configuration (oss-autopilot#1122). `host` is the Ollama
+ * endpoint; an empty `host` means "use the triage default". A `null` config
+ * (not this shape) means SLM triage is disabled (#158).
+ */
+export interface SLMConfig {
+    model: string;
+    host: string;
+}
 /**
  * Read-only interface for accessing scout state during issue vetting.
  * Implementations may be backed by gist persistence, in-memory state, etc.
@@ -46,15 +56,89 @@ export interface ScoutStateReader {
     /** Numeric quality score for a repo, or null if not evaluated. */
     getRepoScore(repo: string): number | null;
     /**
-     * SLM pre-triage config (oss-autopilot#1122). Returns the configured
-     * model id and Ollama host, or empty strings when not configured —
-     * vetIssue treats either of these as "skip the SLM call".
+     * SLM pre-triage config (oss-autopilot#1122). Returns the configured model
+     * id and Ollama host, or `null` when SLM triage is not configured — vetIssue
+     * skips the SLM call on `null`. Required (#158): the old optional method with
+     * an empty-string sentinel could not distinguish "not configured" from "host
+     * defaulted"; `SLMConfig | null` makes the absence explicit.
+     */
+    getSLMTriageConfig(): SLMConfig | null;
+    /**
+     * Number of the user's PRs closed without merge in this repo (#125).
+     * Optional so existing implementations keep compiling; absent reads as 0.
+     */
+    getClosedWithoutMergeCount?(repo: string): number;
+    /**
+     * The configured GitHub username, used to tell the user's own in-flight PR
+     * apart from a competing one (#166). Optional; absent reads as "unknown".
+     */
+    getGitHubUsername?(): string;
+}
+/**
+ * Write side of the scout state, consumed by the bootstrap flow. Defined here
+ * next to ScoutStateReader so core/bootstrap.ts can depend on this contract
+ * instead of importing the OssScout facade from the package root (an upward
+ * dependency). OssScout implements it (#156).
+ */
+export interface ScoutStateWriter {
+    /** Read current preferences (bootstrap reads githubUsername). */
+    getPreferences(): Readonly<ScoutPreferences>;
+    /** Replace the cached starred-repo list. */
+    setStarredRepos(repos: string[]): void;
+    /** Record a merged PR (deduplicated by URL). */
+    recordMergedPR(pr: MergedPRRecord): void;
+    /** Record a PR closed without merge (deduplicated by URL). */
+    recordClosedPR(pr: ClosedPRRecord): void;
+    /** Record an open PR (deduplicated by URL). */
+    recordOpenPR(pr: OpenPRRecord): void;
+    /** Snapshot the current state (bootstrap reports counts from it). */
+    getState(): Readonly<ScoutState>;
+}
+/**
+ * Inputs to deriveRecommendation: the already-computed check results and
+ * affinity signals. Kept as a flat record of primitives so the derivation is a
+ * pure function, independently unit-testable (#157).
+ */
+export interface RecommendationInput {
+    noExistingPR: boolean;
+    /**
+     * The linked PR is the user's own open PR (#166). When true, the existing-PR
+     * block is reframed as "you're already on it" — a skip with a clear reason —
+     * instead of a competing-PR penalty.
      */
-    getSLMTriageConfig?(): {
-        model: string;
-        host: string;
-    };
+    ownPR: boolean;
+    notClaimed: boolean;
+    clearRequirements: boolean;
+    contributionGuidelinesFound: boolean;
+    projectIsActive: boolean;
+    projectCheckFailed: boolean;
+    projectFailureReason?: string;
+    existingPRInconclusive: boolean;
+    existingPRReason?: string;
+    claimInconclusive: boolean;
+    claimReason?: string;
+    mergedCountInconclusive: boolean;
+    effectiveMergedCount: number;
+    orgName: string;
+    orgHasMergedPRs: boolean;
+    matchesCategory: boolean;
+    issueClosed: boolean;
+    /** noExistingPR && notClaimed && projectActive && clearRequirements. */
+    passedAllChecks: boolean;
 }
+export interface RecommendationOutput {
+    notes: string[];
+    reasonsToApprove: string[];
+    reasonsToSkip: string[];
+    recommendation: "approve" | "skip" | "needs_review";
+}
+/**
+ * Derive the human-readable notes, approve/skip reasons, and the final
+ * recommendation from a vet's check results. Pure: no I/O, no state reads — the
+ * caller computes the inputs and threads them in. Extracted from vetIssue so
+ * the recommendation logic is testable in isolation (#157).
+ */
+export declare function deriveRecommendation(input: RecommendationInput): RecommendationOutput;
 export declare class IssueVetter {
     private octokit;
     private stateReader;
@@ -70,7 +154,20 @@ export declare class IssueVetter {
      */
     vetIssue(issueUrl: string, opts?: {
         featureSignals?: FeatureSignals;
+        /**
+         * Issue core data already fetched in a batch GraphQL query (#169). When
+         * present it replaces the per-issue REST `issues.get`; otherwise the
+         * core is fetched via REST. The two paths are normalized to the same
+         * shape so behaviour is identical either way.
+         */
+        prefetched?: PrefetchedIssueCore;
     }): Promise<IssueCandidate>;
+    /**
+     * Fetch a single issue's core fields via REST and normalize them to the same
+     * shape as a GraphQL prefetch (#169). The REST fallback path when no
+     * prefetched core was supplied.
+     */
+    private fetchIssueCore;
     /**
      * Vet multiple issues in parallel with concurrency limit
      */