@oss-scout/core 0.11.0 → 1.0.0

package/dist/core/issue-vetting.js

@@ -14,13 +14,108 @@ import { repoBelongsToCategory } from "./category-mapping.js";
 import { checkNoExistingPR, checkNotClaimed, checkUserMergedPRsInRepo, analyzeRequirements, } from "./issue-eligibility.js";
 import { checkProjectHealth, fetchContributionGuidelines, } from "./repo-health.js";
 import { fetchAndScanAntiLLMPolicy } from "./anti-llm-policy.js";
-import { getHttpCache } from "./http-cache.js";
+import { prefetchIssueCores, issueCoreKey, } from "./issue-graphql.js";
+import { getHttpCache, versionedCacheKey } from "./http-cache.js";
 import { triageWithSLM, buildTriageInput, } from "./slm-triage.js";
 const MODULE = "issue-vetting";
 /** Vetting concurrency: kept low to reduce burst pressure on GitHub's secondary rate limit. */
 const MAX_CONCURRENT_VETTING = 3;
 /** TTL for cached vetting results (15 minutes). Kept short so config changes take effect quickly. */
 const VETTING_CACHE_TTL_MS = 15 * 60 * 1000;
+/**
+ * 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 function deriveRecommendation(input) {
+    const notes = [];
+    const reasonsToApprove = [];
+    const reasonsToSkip = [];
+    // Notes (order preserved from the original vetIssue body).
+    if (!input.noExistingPR)
+        notes.push(input.ownPR
+            ? "Your PR is already in flight for this issue"
+            : "Existing PR found for this issue");
+    if (!input.notClaimed)
+        notes.push("Issue appears to be claimed by someone");
+    if (input.existingPRInconclusive) {
+        notes.push(`Could not verify absence of existing PRs: ${input.existingPRReason || "API error"}`);
+    }
+    if (input.claimInconclusive) {
+        notes.push(`Could not verify claim status: ${input.claimReason || "API error"}`);
+    }
+    if (input.projectCheckFailed) {
+        notes.push(`Could not verify project activity: ${input.projectFailureReason || "API error"}`);
+    }
+    else if (!input.projectIsActive) {
+        notes.push("Project may be inactive");
+    }
+    if (!input.clearRequirements)
+        notes.push("Issue requirements are unclear");
+    if (!input.contributionGuidelinesFound)
+        notes.push("No CONTRIBUTING.md found");
+    // Reasons to skip / approve.
+    if (!input.noExistingPR)
+        reasonsToSkip.push(input.ownPR ? "You already have a PR in flight" : "Has existing PR");
+    if (!input.notClaimed)
+        reasonsToSkip.push("Already claimed");
+    if (!input.projectIsActive && !input.projectCheckFailed)
+        reasonsToSkip.push("Inactive project");
+    if (!input.clearRequirements)
+        reasonsToSkip.push("Unclear requirements");
+    if (input.noExistingPR)
+        reasonsToApprove.push("No existing PR");
+    if (input.notClaimed)
+        reasonsToApprove.push("Not claimed");
+    if (input.projectIsActive && !input.projectCheckFailed)
+        reasonsToApprove.push("Active project");
+    if (input.clearRequirements)
+        reasonsToApprove.push("Clear requirements");
+    if (input.contributionGuidelinesFound)
+        reasonsToApprove.push("Has contribution guidelines");
+    if (input.effectiveMergedCount > 0) {
+        reasonsToApprove.push(`Trusted project (${input.effectiveMergedCount} PR${input.effectiveMergedCount > 1 ? "s" : ""} merged)`);
+    }
+    if (input.orgHasMergedPRs) {
+        reasonsToApprove.push(`Org affinity (merged PRs in other ${input.orgName} repos)`);
+    }
+    if (input.matchesCategory) {
+        reasonsToApprove.push("Matches preferred project category");
+    }
+    if (input.issueClosed) {
+        reasonsToSkip.push("Issue is closed");
+    }
+    // Recommendation.
+    let recommendation;
+    if (input.issueClosed) {
+        recommendation = "skip";
+    }
+    else if (input.ownPR) {
+        // You're already working on this; don't re-surface it as competition.
+        recommendation = "skip";
+    }
+    else if (input.passedAllChecks) {
+        recommendation = "approve";
+    }
+    else if (reasonsToSkip.length > 2) {
+        recommendation = "skip";
+    }
+    else {
+        recommendation = "needs_review";
+    }
+    // Downgrade an "approve" when any check was inconclusive — "approve" should
+    // only be given when checks actually passed, not when they were skipped.
+    const hasInconclusiveChecks = input.projectCheckFailed ||
+        input.existingPRInconclusive ||
+        input.claimInconclusive ||
+        input.mergedCountInconclusive;
+    if (recommendation === "approve" && hasInconclusiveChecks) {
+        recommendation = "needs_review";
+        notes.push("Recommendation downgraded: one or more checks were inconclusive");
+    }
+    return { notes, reasonsToApprove, reasonsToSkip, recommendation };
+}
 export class IssueVetter {
     octokit;
     stateReader;
@@ -43,7 +138,7 @@ export class IssueVetter {
         const sigKey = opts?.featureSignals
             ? `:r${opts.featureSignals.reactions}c${opts.featureSignals.comments}m${opts.featureSignals.hasMilestone ? 1 : 0}o${opts.featureSignals.onRoadmap ? 1 : 0}w${opts.featureSignals.wontfixNoContributor ? 1 : 0}`
             : "";
-        const cacheKey = `vet:${issueUrl}${sigKey}`;
+        const cacheKey = versionedCacheKey(`vet:${issueUrl}${sigKey}`);
         const cached = cache.getIfFresh(cacheKey, VETTING_CACHE_TTL_MS);
         if (cached &&
             typeof cached === "object" &&
@@ -59,19 +154,18 @@ export class IssueVetter {
         }
         const { owner, repo, number } = parsed;
         const repoFullName = `${owner}/${repo}`;
-        // Fetch issue data
-        const { data: ghIssue } = await this.octokit.issues.get({
-            owner,
-            repo,
-            issue_number: number,
-        });
+        // Issue core data: use the batch-prefetched GraphQL result when the caller
+        // supplied one (#169), otherwise fetch it per-issue via REST. Both paths
+        // normalize to the same shape (fetchIssueCore), so downstream logic is
+        // identical regardless of source.
+        const core = opts?.prefetched ?? (await this.fetchIssueCore(owner, repo, number));
         // Check if the user already has merged PRs in this repo (skip the Search API call)
         const reposWithMergedPRs = this.stateReader.getReposWithMergedPRs();
         const hasMergedPRsInRepo = reposWithMergedPRs.includes(repoFullName);
         // Run all vetting checks in parallel — delegates to standalone functions
         const [existingPRCheck, claimCheck, projectHealth, contributionGuidelines, userMergedPRCount,] = await Promise.all([
             checkNoExistingPR(this.octokit, owner, repo, number),
-            checkNotClaimed(this.octokit, owner, repo, number, ghIssue.comments),
+            checkNotClaimed(this.octokit, owner, repo, number, core.commentCount),
             checkProjectHealth(this.octokit, owner, repo),
             fetchContributionGuidelines(this.octokit, owner, repo),
             hasMergedPRsInRepo
@@ -87,8 +181,18 @@ export class IssueVetter {
         const antiLLMPolicy = await fetchAndScanAntiLLMPolicy(this.octokit, owner, repo, { contributingText: contributionGuidelines?.rawContent });
         const noExistingPR = existingPRCheck.passed;
         const notClaimed = claimCheck.passed;
+        // Is the linked PR the user's own open PR (#166)? If so the issue is
+        // "you're already on it", not competition.
+        const username = this.stateReader.getGitHubUsername?.() ?? "";
+        const linkedPR = existingPRCheck.linkedPR;
+        const ownPR = !noExistingPR &&
+            !!linkedPR &&
+            linkedPR.state === "open" &&
+            !linkedPR.merged &&
+            username !== "" &&
+            linkedPR.author.toLowerCase() === username.toLowerCase();
         // Analyze issue quality
-        const clearRequirements = analyzeRequirements(ghIssue.body || "");
+        const clearRequirements = analyzeRequirements(core.body);
         // When the health check itself failed (API error), use a neutral default:
         // don't penalize the repo as inactive, but don't credit it as active either.
         const projectActive = projectHealth.checkFailed
@@ -107,104 +211,76 @@ export class IssueVetter {
             linkedPR: existingPRCheck.linkedPR,
             notes: [],
         };
-        // Build notes
-        if (!noExistingPR)
-            vettingResult.notes.push("Existing PR found for this issue");
-        if (!notClaimed)
-            vettingResult.notes.push("Issue appears to be claimed by someone");
-        if (existingPRCheck.inconclusive) {
-            vettingResult.notes.push(`Could not verify absence of existing PRs: ${existingPRCheck.reason || "API error"}`);
-        }
-        if (claimCheck.inconclusive) {
-            vettingResult.notes.push(`Could not verify claim status: ${claimCheck.reason || "API error"}`);
-        }
-        if (projectHealth.checkFailed) {
-            vettingResult.notes.push(`Could not verify project activity: ${projectHealth.failureReason || "API error"}`);
-        }
-        else if (!projectHealth.isActive) {
-            vettingResult.notes.push("Project may be inactive");
-        }
-        if (!clearRequirements)
-            vettingResult.notes.push("Issue requirements are unclear");
-        if (!contributionGuidelines)
-            vettingResult.notes.push("No CONTRIBUTING.md found");
-        // Create tracked issue
+        // Create tracked issue. It holds a reference to vettingResult, whose
+        // notes are filled in by deriveRecommendation below.
         const trackedIssue = {
-            id: ghIssue.id,
+            id: core.id,
             url: issueUrl,
             repo: repoFullName,
             number,
-            title: ghIssue.title,
+            title: core.title,
             status: "candidate",
-            labels: ghIssue.labels.map((l) => typeof l === "string" ? l : l.name || ""),
-            createdAt: ghIssue.created_at,
-            updatedAt: ghIssue.updated_at,
+            labels: core.labels,
+            createdAt: core.createdAt,
+            updatedAt: core.updatedAt,
             vetted: true,
             vettingResult,
         };
-        // Determine recommendation
-        const reasonsToSkip = [];
-        const reasonsToApprove = [];
-        if (!noExistingPR)
-            reasonsToSkip.push("Has existing PR");
-        if (!notClaimed)
-            reasonsToSkip.push("Already claimed");
-        if (!projectHealth.isActive && !projectHealth.checkFailed)
-            reasonsToSkip.push("Inactive project");
-        if (!clearRequirements)
-            reasonsToSkip.push("Unclear requirements");
-        if (noExistingPR)
-            reasonsToApprove.push("No existing PR");
-        if (notClaimed)
-            reasonsToApprove.push("Not claimed");
-        if (projectHealth.isActive && !projectHealth.checkFailed)
-            reasonsToApprove.push("Active project");
-        if (clearRequirements)
-            reasonsToApprove.push("Clear requirements");
-        if (contributionGuidelines)
-            reasonsToApprove.push("Has contribution guidelines");
-        // Determine effective merged PR count: prefer local state (authoritative if present),
-        // fall back to live GitHub API count to detect contributions made before using oss-scout
-        const effectiveMergedCount = hasMergedPRsInRepo ? 1 : userMergedPRCount;
-        if (effectiveMergedCount > 0) {
-            reasonsToApprove.push(`Trusted project (${effectiveMergedCount} PR${effectiveMergedCount > 1 ? "s" : ""} merged)`);
-        }
-        // Check for org-level affinity (user has merged PRs in another repo under same org)
+        // Effective merged PR count: prefer local state (authoritative if present),
+        // fall back to live GitHub API count to detect contributions made before
+        // using oss-scout. null means the live check transiently failed: score as
+        // 0 but treat the result as inconclusive so it is not cached.
+        const mergedCountInconclusive = !hasMergedPRsInRepo && userMergedPRCount === null;
+        const effectiveMergedCount = hasMergedPRsInRepo
+            ? 1
+            : (userMergedPRCount ?? 0);
+        // Org-level affinity (user has merged PRs in another repo under same org).
         const orgName = repoFullName.split("/")[0];
         let orgHasMergedPRs = false;
         if (orgName && repoFullName.includes("/")) {
             orgHasMergedPRs = reposWithMergedPRs.some((r) => r.startsWith(orgName + "/") && r !== repoFullName);
         }
-        if (orgHasMergedPRs) {
-            reasonsToApprove.push(`Org affinity (merged PRs in other ${orgName} repos)`);
-        }
-        // Check for category preference match
-        const projectCategories = this.stateReader.getProjectCategories();
-        const matchesCategory = repoBelongsToCategory(repoFullName, projectCategories);
-        if (matchesCategory) {
-            reasonsToApprove.push("Matches preferred project category");
-        }
-        let recommendation;
-        if (vettingResult.passedAllChecks) {
-            recommendation = "approve";
-        }
-        else if (reasonsToSkip.length > 2) {
-            recommendation = "skip";
-        }
-        else {
-            recommendation = "needs_review";
-        }
-        // Downgrade to needs_review if any check was inconclusive —
-        // "approve" should only be given when all checks actually passed, not when they were skipped.
+        const matchesCategory = repoBelongsToCategory(repoFullName, this.stateReader.getProjectCategories());
+        // GitHub answers 200 for closed issues, so without an explicit state
+        // check a closed issue would vet as still available (#120).
+        const issueClosed = core.state === "closed";
+        // Never cache a verdict built on inconclusive/failed checks (e.g. a
+        // transient 5xx): that would pin a degraded result for the whole TTL.
         const hasInconclusiveChecks = projectHealth.checkFailed ||
-            existingPRCheck.inconclusive ||
-            claimCheck.inconclusive;
-        if (recommendation === "approve" && hasInconclusiveChecks) {
-            recommendation = "needs_review";
-            vettingResult.notes.push("Recommendation downgraded: one or more checks were inconclusive");
-        }
-        // Calculate repo quality bonus from star/fork counts
-        const repoQualityBonus = calculateRepoQualityBonus(projectHealth.stargazersCount ?? 0, projectHealth.forksCount ?? 0);
+            !!existingPRCheck.inconclusive ||
+            !!claimCheck.inconclusive ||
+            mergedCountInconclusive;
+        const { notes, reasonsToApprove, reasonsToSkip, recommendation } = deriveRecommendation({
+            noExistingPR,
+            ownPR,
+            notClaimed,
+            clearRequirements,
+            contributionGuidelinesFound: !!contributionGuidelines,
+            projectIsActive: projectHealth.checkFailed
+                ? false
+                : projectHealth.isActive,
+            projectCheckFailed: !!projectHealth.checkFailed,
+            projectFailureReason: projectHealth.failureReason,
+            existingPRInconclusive: !!existingPRCheck.inconclusive,
+            existingPRReason: existingPRCheck.inconclusive
+                ? existingPRCheck.reason
+                : undefined,
+            claimInconclusive: !!claimCheck.inconclusive,
+            claimReason: claimCheck.inconclusive ? claimCheck.reason : undefined,
+            mergedCountInconclusive,
+            effectiveMergedCount,
+            orgName,
+            orgHasMergedPRs,
+            matchesCategory,
+            issueClosed,
+            passedAllChecks: vettingResult.passedAllChecks,
+        });
+        vettingResult.notes = notes;
+        // Calculate repo quality bonus from star/fork counts. A failed health
+        // check carries no counts (#158), so the bonus is 0 in that case.
+        const repoQualityBonus = projectHealth.checkFailed
+            ? 0
+            : calculateRepoQualityBonus(projectHealth.stargazersCount ?? 0, projectHealth.forksCount ?? 0);
         if (projectHealth.checkFailed && repoQualityBonus === 0) {
             vettingResult.notes.push("Repo quality bonus unavailable: could not fetch star/fork counts due to API error");
         }
@@ -215,8 +291,8 @@ export class IssueVetter {
             isClaimed: !notClaimed,
             clearRequirements,
             hasContributionGuidelines: !!contributionGuidelines,
-            issueUpdatedAt: ghIssue.updated_at,
-            closedWithoutMergeCount: 0,
+            issueUpdatedAt: core.updatedAt,
+            closedWithoutMergeCount: this.stateReader.getClosedWithoutMergeCount?.(repoFullName) ?? 0,
             mergedPRCount: effectiveMergedCount,
             orgHasMergedPRs,
             repoQualityBonus,
@@ -232,23 +308,22 @@ export class IssueVetter {
             searchPriority = "starred";
         }
         // Optional SLM pre-triage (oss-autopilot#1122). Fail-open: any error
-        // path returns null and the rest of the pipeline is unaffected.
-        const slmConfig = this.stateReader.getSLMTriageConfig?.() ?? {
-            model: "",
-            host: "",
-        };
+        // path returns null and the rest of the pipeline is unaffected. A null
+        // config means SLM triage is disabled (#158).
+        const slmConfig = this.stateReader.getSLMTriageConfig();
         let slmTriage = null;
-        if (slmConfig.model) {
+        if (slmConfig) {
             const slmOpts = { model: slmConfig.model };
             if (slmConfig.host)
                 slmOpts.host = slmConfig.host;
             slmTriage = await triageWithSLM(buildTriageInput({
-                issue: { ...trackedIssue, body: ghIssue.body ?? "" },
+                issue: { ...trackedIssue, body: core.body },
                 linkedPR: existingPRCheck.linkedPR ?? null,
             }), slmOpts);
         }
         const result = {
             issue: trackedIssue,
+            issueState: issueClosed ? "closed" : "open",
             vettingResult,
             projectHealth,
             antiLLMPolicy,
@@ -259,10 +334,38 @@ export class IssueVetter {
             viabilityScore,
             searchPriority,
         };
-        // Cache the vetting result to avoid redundant API calls on repeated searches
-        cache.set(cacheKey, "", result);
+        // Cache the vetting result to avoid redundant API calls on repeated
+        // searches — but never cache results built on inconclusive/failed checks
+        // (e.g. a transient 5xx): that would pin a degraded verdict for the whole
+        // TTL. Next vet retries instead. Mirrors the error-path rule in
+        // issue-eligibility's checkUserMergedPRsInRepo.
+        if (!hasInconclusiveChecks) {
+            cache.set(cacheKey, "", result);
+        }
         return result;
     }
+    /**
+     * 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.
+     */
+    async fetchIssueCore(owner, repo, number) {
+        const { data: ghIssue } = await this.octokit.issues.get({
+            owner,
+            repo,
+            issue_number: number,
+        });
+        return {
+            id: ghIssue.id,
+            title: ghIssue.title,
+            body: ghIssue.body || "",
+            state: ghIssue.state === "closed" ? "closed" : "open",
+            labels: ghIssue.labels.map((l) => typeof l === "string" ? l : l.name || ""),
+            commentCount: ghIssue.comments,
+            createdAt: ghIssue.created_at,
+            updatedAt: ghIssue.updated_at,
+        };
+    }
     /**
      * Vet multiple issues in parallel with concurrency limit
      */
@@ -277,13 +380,37 @@ export class IssueVetter {
         // the token is invalid and no other issue will succeed either —
         // continuing to log per-issue warnings buries the actual problem.
         let firstAuthError = null;
-        for (const url of urls) {
+        // Dedup defensively: the pending map is keyed by URL, so a duplicate
+        // input would overwrite the in-flight entry and its finally-cleanup
+        // would deregister the second task, letting allSettled return while a
+        // vet still runs (#129). Callers dedup today, but nothing enforced it.
+        const uniqueUrls = [...new Set(urls)];
+        // Batch-prefetch issue core data in one GraphQL query (#169), replacing N
+        // per-issue REST `issues.get` calls. Any URL the prefetch can't resolve
+        // (parse failure, deleted issue, non-fatal GraphQL error) is simply absent
+        // from the map and vetIssue falls back to REST for it. A fatal error (401 /
+        // rate limit) propagates out of prefetchIssueCores and aborts the batch,
+        // matching the per-issue auth-error handling below.
+        const prefetched = await prefetchIssueCores(this.octokit, uniqueUrls.flatMap((url) => {
+            const p = parseGitHubUrl(url);
+            return p && p.type === "issues"
+                ? [{ owner: p.owner, repo: p.repo, number: p.number }]
+                : [];
+        }));
+        const prefetchFor = (url) => {
+            const p = parseGitHubUrl(url);
+            return p && p.type === "issues"
+                ? prefetched.get(issueCoreKey(p.owner, p.repo, p.number))
+                : undefined;
+        };
+        for (const url of uniqueUrls) {
             if (candidates.length >= maxResults)
                 break;
             if (firstAuthError)
                 break; // stop scheduling once auth has failed
             attemptedCount++;
-            const task = this.vetIssue(url)
+            const core = prefetchFor(url);
+            const task = this.vetIssue(url, core ? { prefetched: core } : undefined)
                 .then((candidate) => {
                 if (candidates.length < maxResults) {
                     // Override the priority if provided

package/dist/core/local-state.d.ts

@@ -11,6 +11,10 @@ export declare function hasLocalState(): boolean;
  */
 export declare function loadLocalState(): ScoutState;
 /**
- * Save state to local file using atomic write (write to .tmp, then rename).
+ * Save state to local file using atomic write (write to a unique tmp file,
+ * then rename). A fixed ".tmp" path let two concurrent processes interleave
+ * write/rename and crash one of them with ENOENT. The load-mutate-save cycle
+ * is still last-writer-wins (no lock), but each save is now atomic and
+ * crash-free on its own.
  */
-export declare function saveLocalState(state: ScoutState): void;
+export declare function saveLocalState(state: Readonly<ScoutState>): void;

package/dist/core/local-state.js

@@ -3,7 +3,7 @@
  */
 import * as fs from "fs";
 import * as path from "path";
-import { ScoutStateSchema } from "./schemas.js";
+import { ScoutStateSchema, parseScoutState } from "./schemas.js";
 import { getDataDir } from "./utils.js";
 import { debug, warn } from "./logger.js";
 import { errorMessage } from "./errors.js";
@@ -24,7 +24,7 @@ export function loadLocalState() {
     const statePath = getStatePath();
     try {
         const raw = fs.readFileSync(statePath, "utf-8");
-        return ScoutStateSchema.parse(JSON.parse(raw));
+        return parseScoutState(JSON.parse(raw));
     }
     catch (err) {
         const code = err?.code;
@@ -45,14 +45,32 @@ export function loadLocalState() {
         return ScoutStateSchema.parse({ version: 1 });
     }
 }
+/** Monotonic counter so two saves in one process never share a tmp path. */
+let tmpCounter = 0;
 /**
- * Save state to local file using atomic write (write to .tmp, then rename).
+ * Save state to local file using atomic write (write to a unique tmp file,
+ * then rename). A fixed ".tmp" path let two concurrent processes interleave
+ * write/rename and crash one of them with ENOENT. The load-mutate-save cycle
+ * is still last-writer-wins (no lock), but each save is now atomic and
+ * crash-free on its own.
  */
 export function saveLocalState(state) {
     const statePath = getStatePath();
-    const tmpPath = statePath + ".tmp";
+    const tmpPath = `${statePath}.tmp.${process.pid}.${tmpCounter++}`;
     const data = JSON.stringify(state, null, 2) + "\n";
     fs.writeFileSync(tmpPath, data, { mode: 0o600 });
-    fs.renameSync(tmpPath, statePath);
+    try {
+        fs.renameSync(tmpPath, statePath);
+    }
+    catch (err) {
+        // Do not leave an orphan tmp file behind on a failed rename
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            // already gone
+        }
+        throw err;
+    }
     debug(MODULE, "State saved");
 }

package/dist/core/logger.d.ts

@@ -1,10 +1,18 @@
 /**
- * Lightweight debug logger for oss-scout.
- * Activated by the global --debug CLI flag.
+ * Lightweight leveled logger for oss-scout.
  *
- * All debug/warn output goes to stderr so it never contaminates
- * the --json stdout contract.
+ * All output goes to stderr so it never contaminates the --json stdout
+ * contract. The CLI raises the level to "debug" via the global --debug flag;
+ * library hosts that don't want oss-scout's "[INFO] Phase 0..." chatter can
+ * lower it with setLogLevel (or ScoutConfig.logLevel) — including to "silent"
+ * (#156).
  */
+export type LogLevel = "silent" | "warn" | "info" | "debug";
+/** Set the minimum level that will be emitted. */
+export declare function setLogLevel(level: LogLevel): void;
+/** Current minimum emitted level. */
+export declare function getLogLevel(): LogLevel;
+/** Raise the level to "debug" (used by the CLI --debug flag). */
 export declare function enableDebug(): void;
 export declare function debug(module: string, message: string, ...args: unknown[]): void;
 export declare function info(module: string, message: string, ...args: unknown[]): void;

package/dist/core/logger.js

@@ -1,25 +1,51 @@
 /**
- * Lightweight debug logger for oss-scout.
- * Activated by the global --debug CLI flag.
+ * Lightweight leveled logger for oss-scout.
  *
- * All debug/warn output goes to stderr so it never contaminates
- * the --json stdout contract.
+ * All output goes to stderr so it never contaminates the --json stdout
+ * contract. The CLI raises the level to "debug" via the global --debug flag;
+ * library hosts that don't want oss-scout's "[INFO] Phase 0..." chatter can
+ * lower it with setLogLevel (or ScoutConfig.logLevel) — including to "silent"
+ * (#156).
  */
-let debugEnabled = false;
+const LEVEL_RANK = {
+    silent: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+};
+// Default "info" preserves the historical behavior: info + warn emit, debug is
+// suppressed until --debug (enableDebug) or setLogLevel raises the level.
+let currentLevel = "info";
+/** Set the minimum level that will be emitted. */
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+/** Current minimum emitted level. */
+export function getLogLevel() {
+    return currentLevel;
+}
+/** Raise the level to "debug" (used by the CLI --debug flag). */
 export function enableDebug() {
-    debugEnabled = true;
+    currentLevel = "debug";
+}
+function shouldLog(level) {
+    return LEVEL_RANK[currentLevel] >= LEVEL_RANK[level];
 }
 export function debug(module, message, ...args) {
-    if (!debugEnabled)
+    if (!shouldLog("debug"))
         return;
     const timestamp = new Date().toISOString();
     console.error(`[${timestamp}] [DEBUG] [${module}] ${message}`, ...args);
 }
 export function info(module, message, ...args) {
+    if (!shouldLog("info"))
+        return;
     const timestamp = new Date().toISOString();
     console.error(`[${timestamp}] [INFO] [${module}] ${message}`, ...args);
 }
 export function warn(module, message, ...args) {
+    if (!shouldLog("warn"))
+        return;
     const timestamp = new Date().toISOString();
     console.error(`[${timestamp}] [WARN] [${module}] ${message}`, ...args);
 }

package/dist/core/personalization.d.ts

@@ -28,18 +28,23 @@ import type { IssueCandidate } from "./types.js";
 export declare const REPO_BOOST = 20;
 export declare const LANGUAGE_BOOST = 10;
 /**
- * Annotate each candidate with `boostScore` and `boostReasons` based on
- * the caller-supplied preference lists. Mutates the array in place; the
- * caller is responsible for re-sorting afterwards.
- *
- * Mutation (rather than returning new objects) keeps the personalization
- * step a single linear pass over the array the caller already holds —
- * the sort step reads back from the same objects.
+ * The personalization sort weight of a candidate: its boost score, or 0 when it
+ * is not boosted (unboosted or a diversity slot). Reads the structural
+ * `personalization` field (#158) so callers never poke at the old loose
+ * `boostScore` field.
+ */
+export declare function boostScoreOf(candidate: IssueCandidate): number;
+/**
+ * Return a new candidate list where each candidate that matches a
+ * caller-supplied preference carries `personalization: { kind: "boosted", ... }`.
+ * Does NOT mutate the input candidates (#158) — matched candidates are shallow
+ * copies with the field set; unmatched candidates are passed through unchanged.
+ * The caller re-sorts the returned array.
  *
- * No-op when both preference lists are empty or undefined: candidates
- * retain `boostScore: undefined` and the sort tier collapses to 0.
+ * No-op when both preference lists are empty or undefined: the input array is
+ * returned as-is and the sort tier collapses to 0 for every candidate.
  */
-export declare function annotateBoost(candidates: IssueCandidate[], preferLanguages?: string[], preferRepos?: string[]): void;
+export declare function annotateBoost(candidates: IssueCandidate[], preferLanguages?: string[], preferRepos?: string[]): IssueCandidate[];
 /**
  * Apply a diversity-counterweight pass over a pre-sorted candidate list
  * (#1244). Returns the first `maxResults` picks in priority order: