@oss-scout/core 0.10.0 → 0.11.0

package/dist/cli.js

@@ -91,6 +91,7 @@ program
     .option("--strategy <strategies>", `Search strategies (${CONCRETE_STRATEGIES.join(",")},all)`, "all")
     .option("--prefer-languages <list>", "Comma-separated languages to soft-boost in ranking (#1244). Candidates whose repo language matches sort above equally-recommended non-matches. Does not filter results.")
     .option("--prefer-repos <list>", "Comma-separated `owner/repo` slugs to soft-boost in ranking (#1244). Stronger weight than language match. Does not filter results.")
+    .option("--diversity-ratio <n>", "Fraction of result slots (0-1) reserved for candidates that matched NEITHER preference list (#1244). Counterweights echo-chamber bias as boosts accumulate. Default 0 (disabled).")
     .action(async (count, options) => {
     try {
         if (!hasLocalState()) {
@@ -135,12 +136,22 @@ program
                 .filter(Boolean);
             return parts.length > 0 ? parts : undefined;
         };
+        let diversityRatio;
+        if (options.diversityRatio !== undefined) {
+            const parsed = Number(options.diversityRatio);
+            if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+                console.error(`Error: --diversity-ratio must be a number in [0, 1] (got "${options.diversityRatio}")`);
+                process.exit(1);
+            }
+            diversityRatio = parsed;
+        }
         const results = await runSearch({
             maxResults,
             state,
             strategies,
             preferLanguages: splitCsv(options.preferLanguages),
             preferRepos: splitCsv(options.preferRepos),
+            diversityRatio,
         });
         if (options.json) {
             console.log(formatJsonSuccess(results));

package/dist/commands/search.d.ts

@@ -45,6 +45,11 @@ export interface SearchOutput {
          */
         boostScore?: number;
         boostReasons?: string[];
+        /**
+         * Marks a candidate that filled a reserved diversity slot (#1244).
+         * Mutually exclusive with a non-zero `boostScore`.
+         */
+        diversitySlot?: boolean;
     }>;
     excludedRepos: string[];
     aiPolicyBlocklist: string[];
@@ -59,6 +64,8 @@ interface SearchCommandOptions {
     preferLanguages?: string[];
     /** Soft sort boost for candidates in these `owner/repo` slugs (#1244). */
     preferRepos?: string[];
+    /** Diversity counterweight: fraction of slots reserved for unboosted candidates (#1244). */
+    diversityRatio?: number;
 }
 export declare function runSearch(options: SearchCommandOptions): Promise<SearchOutput>;
 export {};

package/dist/commands/search.js

@@ -19,6 +19,7 @@ export async function runSearch(options) {
         strategies: options.strategies,
         preferLanguages: options.preferLanguages,
         preferRepos: options.preferRepos,
+        diversityRatio: options.diversityRatio,
     });
     // Persist results to local state and gist
     scout.saveResults(result.candidates);
@@ -64,6 +65,7 @@ export async function runSearch(options) {
                     : undefined,
                 boostScore: c.boostScore,
                 boostReasons: c.boostReasons,
+                diversitySlot: c.diversitySlot,
             };
         }),
         excludedRepos: result.excludedRepos,

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

@@ -76,6 +76,7 @@ export declare class IssueDiscovery {
         skippedUrls?: Set<string>;
         preferLanguages?: string[];
         preferRepos?: string[];
+        diversityRatio?: number;
     }): Promise<{
         candidates: IssueCandidate[];
         strategiesUsed: SearchStrategy[];

package/dist/core/issue-discovery.js

@@ -22,7 +22,7 @@ import { isDocOnlyIssue, applyPerRepoCap, } from "./issue-filtering.js";
 import { IssueVetter } from "./issue-vetting.js";
 import { getTopicsForCategories } from "./category-mapping.js";
 import { buildEffectiveLabels, interleaveArrays, cachedSearchIssues, fetchIssuesFromMaintainedRepos, filterVetAndScore, fetchIssuesFromKnownRepos, searchAcrossLanguagesAndLabels, } from "./search-phases.js";
-import { annotateBoost } from "./personalization.js";
+import { annotateBoost, applyDiversityRatio } from "./personalization.js";
 const MODULE = "issue-discovery";
 /** If remaining search quota is below this, skip heavy phases (2, 3). */
 const LOW_BUDGET_THRESHOLD = 20;
@@ -517,8 +517,13 @@ export class IssueDiscovery {
             return b.viabilityScore - a.viabilityScore;
         });
         const capped = applyPerRepoCap(allCandidates, 2);
-        info(MODULE, `Search complete: ${tracker.getTotalCalls()} Search API calls used, ${capped.length} candidates returned`);
-        return { candidates: capped.slice(0, maxResults), strategiesUsed };
+        // Diversity counterweight (#1244): when `diversityRatio > 0`, reserve
+        // a fraction of the final slots for candidates that matched neither
+        // preference list. No-op when the ratio is 0 or absent — collapses to
+        // the original `slice(0, maxResults)` behavior.
+        const finalPicks = applyDiversityRatio(capped, maxResults, options.diversityRatio ?? 0);
+        info(MODULE, `Search complete: ${tracker.getTotalCalls()} Search API calls used, ${finalPicks.length} candidates returned`);
+        return { candidates: finalPicks, strategiesUsed };
     }
     /**
      * Vet a specific issue for claimability and project health.

package/dist/core/personalization.d.ts

@@ -1,15 +1,18 @@
 /**
  * Personalization signals for search ranking (#1244).
  *
- * Translates caller-supplied `preferLanguages` / `preferRepos` lists
- * into a soft `boostScore` on each `IssueCandidate`. The final search
- * sort consults this score between the `recommendation` tier and the
- * raw `viabilityScore`, so personalization reorders ties without
- * changing which candidates pass vetting.
- *
- * This is the minimum-viable subset of Option A in #1244: only language
- * and repo bias, no `boostIssueTypes` / `avoidRepos` / `diversityRatio`
- * yet. Those follow up in separate PRs.
+ * Two passes:
+ *
+ *   - `annotateBoost` translates `preferLanguages` / `preferRepos`
+ *     into a soft `boostScore` consumed by issue-discovery's final
+ *     sort tier between `recommendation` and `viabilityScore`.
+ *   - `applyDiversityRatio` reserves a fraction of the final slot
+ *     budget for candidates that matched no preference, counterweighting
+ *     echo-chamber bias as recommendations accumulate over time.
+ *
+ * Still out of scope for #1244: `boostIssueTypes`, `avoidRepos`, and
+ * render-time annotation of `boostReasons` / `diversitySlot` in the CLI
+ * non-JSON output. Those follow up in separate PRs.
  */
 import type { IssueCandidate } from "./types.js";
 /**
@@ -37,3 +40,28 @@ export declare const LANGUAGE_BOOST = 10;
  * retain `boostScore: undefined` and the sort tier collapses to 0.
  */
 export declare function annotateBoost(candidates: IssueCandidate[], preferLanguages?: string[], preferRepos?: string[]): void;
+/**
+ * Apply a diversity-counterweight pass over a pre-sorted candidate list
+ * (#1244). Returns the first `maxResults` picks in priority order:
+ *
+ *   1. Main slots: `maxResults - floor(maxResults * diversityRatio)`
+ *      top candidates from the input. Personalization-biased candidates
+ *      win these slots when present (since the input is already sorted
+ *      by the personalization tier).
+ *   2. Diversity slots: the highest-ranked candidates that carry NO
+ *      `boostScore` — i.e. they matched neither `preferLanguages` nor
+ *      `preferRepos`. Tagged with `diversitySlot: true` for caller
+ *      transparency.
+ *   3. Top-up: if the diversity pool was thinner than the reserve, fall
+ *      back to the remaining sorted candidates so the user gets
+ *      `maxResults` slots whenever the source has enough material.
+ *
+ * `diversityRatio` is clamped to [0, 1]. 0 is a no-op (just slices the
+ * input). 1 means every slot is a diversity slot — useful for
+ * deliberately suppressing personalization without disabling it.
+ *
+ * @param candidates    Pre-sorted candidate list (output of issue-discovery)
+ * @param maxResults    Total slots to fill
+ * @param diversityRatio Fraction of slots reserved for unboosted candidates
+ */
+export declare function applyDiversityRatio(candidates: IssueCandidate[], maxResults: number, diversityRatio: number): IssueCandidate[];

package/dist/core/personalization.js

@@ -1,15 +1,18 @@
 /**
  * Personalization signals for search ranking (#1244).
  *
- * Translates caller-supplied `preferLanguages` / `preferRepos` lists
- * into a soft `boostScore` on each `IssueCandidate`. The final search
- * sort consults this score between the `recommendation` tier and the
- * raw `viabilityScore`, so personalization reorders ties without
- * changing which candidates pass vetting.
- *
- * This is the minimum-viable subset of Option A in #1244: only language
- * and repo bias, no `boostIssueTypes` / `avoidRepos` / `diversityRatio`
- * yet. Those follow up in separate PRs.
+ * Two passes:
+ *
+ *   - `annotateBoost` translates `preferLanguages` / `preferRepos`
+ *     into a soft `boostScore` consumed by issue-discovery's final
+ *     sort tier between `recommendation` and `viabilityScore`.
+ *   - `applyDiversityRatio` reserves a fraction of the final slot
+ *     budget for candidates that matched no preference, counterweighting
+ *     echo-chamber bias as recommendations accumulate over time.
+ *
+ * Still out of scope for #1244: `boostIssueTypes`, `avoidRepos`, and
+ * render-time annotation of `boostReasons` / `diversitySlot` in the CLI
+ * non-JSON output. Those follow up in separate PRs.
  */
 /**
  * Boost weights. Tuned conservatively so personalization tips equally-
@@ -58,3 +61,66 @@ export function annotateBoost(candidates, preferLanguages, preferRepos) {
         }
     }
 }
+/**
+ * Apply a diversity-counterweight pass over a pre-sorted candidate list
+ * (#1244). Returns the first `maxResults` picks in priority order:
+ *
+ *   1. Main slots: `maxResults - floor(maxResults * diversityRatio)`
+ *      top candidates from the input. Personalization-biased candidates
+ *      win these slots when present (since the input is already sorted
+ *      by the personalization tier).
+ *   2. Diversity slots: the highest-ranked candidates that carry NO
+ *      `boostScore` — i.e. they matched neither `preferLanguages` nor
+ *      `preferRepos`. Tagged with `diversitySlot: true` for caller
+ *      transparency.
+ *   3. Top-up: if the diversity pool was thinner than the reserve, fall
+ *      back to the remaining sorted candidates so the user gets
+ *      `maxResults` slots whenever the source has enough material.
+ *
+ * `diversityRatio` is clamped to [0, 1]. 0 is a no-op (just slices the
+ * input). 1 means every slot is a diversity slot — useful for
+ * deliberately suppressing personalization without disabling it.
+ *
+ * @param candidates    Pre-sorted candidate list (output of issue-discovery)
+ * @param maxResults    Total slots to fill
+ * @param diversityRatio Fraction of slots reserved for unboosted candidates
+ */
+export function applyDiversityRatio(candidates, maxResults, diversityRatio) {
+    if (maxResults <= 0)
+        return [];
+    const ratio = Math.max(0, Math.min(1, diversityRatio));
+    if (ratio === 0)
+        return candidates.slice(0, maxResults);
+    const diversityReserve = Math.min(Math.floor(maxResults * ratio), maxResults);
+    if (diversityReserve === 0)
+        return candidates.slice(0, maxResults);
+    const mainBudget = maxResults - diversityReserve;
+    const picks = [];
+    const seen = new Set();
+    for (const c of candidates) {
+        if (picks.length >= mainBudget)
+            break;
+        picks.push(c);
+        seen.add(c.issue.url);
+    }
+    for (const c of candidates) {
+        if (picks.length >= maxResults)
+            break;
+        if (seen.has(c.issue.url))
+            continue;
+        if (c.boostScore && c.boostScore > 0)
+            continue;
+        c.diversitySlot = true;
+        picks.push(c);
+        seen.add(c.issue.url);
+    }
+    for (const c of candidates) {
+        if (picks.length >= maxResults)
+            break;
+        if (seen.has(c.issue.url))
+            continue;
+        picks.push(c);
+        seen.add(c.issue.url);
+    }
+    return picks;
+}

package/dist/core/types.d.ts

@@ -66,6 +66,14 @@ export interface IssueCandidate {
      * symmetry with the existing surface.
      */
     boostReasons?: string[];
+    /**
+     * Marks a candidate that filled a reserved diversity slot (#1244).
+     * Populated only when `diversityRatio > 0` was passed AND the
+     * candidate matched no personalization bias. Mutually exclusive with
+     * a non-zero `boostScore` (a candidate cannot be both biased-toward
+     * and a diversity slot in the same result set).
+     */
+    diversitySlot?: boolean;
 }
 /** Subset of RepoScore fields that callers may update. */
 export interface RepoScoreUpdate {
@@ -150,6 +158,16 @@ export interface SearchOptions {
      * disables the boost.
      */
     preferRepos?: string[];
+    /**
+     * Counterweight against echo-chamber bias as `preferLanguages` /
+     * `preferRepos` boosts accumulate over time (#1244). A value of 0.2
+     * means "reserve roughly 20% of the final slots for candidates that
+     * matched NEITHER preference list," filling them from the same sorted
+     * pool but skipping any candidate carrying a `boostScore`. 0 disables
+     * the counterweight; 1 makes every slot a diversity slot. Range
+     * clamped to [0, 1].
+     */
+    diversityRatio?: number;
 }
 /** Result of a search operation. */
 export interface SearchResult {

package/dist/scout.js

@@ -150,6 +150,7 @@ export class OssScout {
             skippedUrls,
             preferLanguages: options?.preferLanguages,
             preferRepos: options?.preferRepos,
+            diversityRatio: options?.diversityRatio,
         });
         this.state.lastSearchAt = new Date().toISOString();
         this.dirty = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Personalized GitHub issue finder with multi-strategy search, deep vetting, and viability scoring — CLI, library, MCP server, and Claude Code plugin",
   "type": "module",
   "bin": {