@oss-scout/core 0.9.1 → 0.10.0

package/dist/cli.js

@@ -89,6 +89,8 @@ program
     .description("Search for contributable issues using multi-strategy discovery")
     .option("--json", "Output as JSON")
     .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.")
     .action(async (count, options) => {
     try {
         if (!hasLocalState()) {
@@ -124,7 +126,22 @@ program
             }
             strategies.push(parsed.data);
         }
-        const results = await runSearch({ maxResults, state, strategies });
+        const splitCsv = (raw) => {
+            if (!raw)
+                return undefined;
+            const parts = raw
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            return parts.length > 0 ? parts : undefined;
+        };
+        const results = await runSearch({
+            maxResults,
+            state,
+            strategies,
+            preferLanguages: splitCsv(options.preferLanguages),
+            preferRepos: splitCsv(options.preferRepos),
+        });
         if (options.json) {
             console.log(formatJsonSuccess(results));
         }

package/dist/commands/search.d.ts

@@ -37,6 +37,14 @@ export interface SearchOutput {
             updatedAt?: string;
             isStalled: boolean;
         };
+        /**
+         * Personalization sort-tier signal (#1244). Present only when the
+         * caller passed `preferLanguages` / `preferRepos` *and* this
+         * candidate matched at least one of them. `boostReasons` is the
+         * human-readable explanation (e.g. `"repo affinity: vercel/next.js"`).
+         */
+        boostScore?: number;
+        boostReasons?: string[];
     }>;
     excludedRepos: string[];
     aiPolicyBlocklist: string[];
@@ -47,6 +55,10 @@ interface SearchCommandOptions {
     maxResults: number;
     state?: ScoutState;
     strategies?: SearchStrategy[];
+    /** Soft sort boost for candidates whose repo language matches (#1244). */
+    preferLanguages?: string[];
+    /** Soft sort boost for candidates in these `owner/repo` slugs (#1244). */
+    preferRepos?: string[];
 }
 export declare function runSearch(options: SearchCommandOptions): Promise<SearchOutput>;
 export {};

package/dist/commands/search.js

@@ -17,6 +17,8 @@ export async function runSearch(options) {
     const result = await scout.search({
         maxResults: options.maxResults,
         strategies: options.strategies,
+        preferLanguages: options.preferLanguages,
+        preferRepos: options.preferRepos,
     });
     // Persist results to local state and gist
     scout.saveResults(result.candidates);
@@ -60,6 +62,8 @@ export async function runSearch(options) {
                         isStalled: isLinkedPRStalled(c.vettingResult.linkedPR),
                     }
                     : undefined,
+                boostScore: c.boostScore,
+                boostReasons: c.boostReasons,
             };
         }),
         excludedRepos: result.excludedRepos,

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

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

package/dist/core/issue-discovery.js

@@ -22,6 +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";
 const MODULE = "issue-discovery";
 /** If remaining search quota is below this, skip heavy phases (2, 3). */
 const LOW_BUDGET_THRESHOLD = 20;
@@ -486,7 +487,11 @@ export class IssueDiscovery {
                     `Found ${allCandidates.length} candidate${allCandidates.length === 1 ? "" : "s"} but some search phases were limited. ` +
                     `Try again after the rate limit resets for complete results.`;
         }
-        // Sort by priority, recommendation, then viability score
+        // Personalization annotation (#1244): tag each candidate with
+        // boostScore + boostReasons before sorting so the new sort tier has
+        // values to read. No-op when neither preference list is supplied.
+        annotateBoost(allCandidates, options.preferLanguages, options.preferRepos);
+        // Sort by priority, recommendation, boost (#1244), then viability score
         allCandidates.sort((a, b) => {
             const priorityOrder = {
                 merged_pr: 0,
@@ -501,6 +506,14 @@ export class IssueDiscovery {
                 recommendationOrder[b.recommendation];
             if (recDiff !== 0)
                 return recDiff;
+            // Personalization tier (#1244): higher boostScore wins. Treats
+            // undefined as 0 so unboosted candidates rank below boosted peers
+            // but stay ordered among themselves by viabilityScore. No-op when
+            // `preferLanguages`/`preferRepos` are absent — all candidates carry
+            // `boostScore: undefined` and the difference collapses to 0.
+            const boostDiff = (b.boostScore ?? 0) - (a.boostScore ?? 0);
+            if (boostDiff !== 0)
+                return boostDiff;
             return b.viabilityScore - a.viabilityScore;
         });
         const capped = applyPerRepoCap(allCandidates, 2);

package/dist/core/personalization.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+import type { IssueCandidate } from "./types.js";
+/**
+ * Boost weights. Tuned conservatively so personalization tips equally-
+ * scored candidates without drowning out high-viability normal results.
+ *
+ * Rationale:
+ *   - Repo affinity is the strongest signal — a candidate in a repo the
+ *     user has merged PRs into has real relationship context. Worth the
+ *     higher boost.
+ *   - Language match is broad and easy to satisfy. Lower weight.
+ */
+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.
+ *
+ * No-op when both preference lists are empty or undefined: candidates
+ * retain `boostScore: undefined` and the sort tier collapses to 0.
+ */
+export declare function annotateBoost(candidates: IssueCandidate[], preferLanguages?: string[], preferRepos?: string[]): void;

package/dist/core/personalization.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/**
+ * Boost weights. Tuned conservatively so personalization tips equally-
+ * scored candidates without drowning out high-viability normal results.
+ *
+ * Rationale:
+ *   - Repo affinity is the strongest signal — a candidate in a repo the
+ *     user has merged PRs into has real relationship context. Worth the
+ *     higher boost.
+ *   - Language match is broad and easy to satisfy. Lower weight.
+ */
+export const REPO_BOOST = 20;
+export 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.
+ *
+ * No-op when both preference lists are empty or undefined: candidates
+ * retain `boostScore: undefined` and the sort tier collapses to 0.
+ */
+export function annotateBoost(candidates, preferLanguages, preferRepos) {
+    const langSet = new Set((preferLanguages ?? []).map((l) => l.trim().toLowerCase()).filter(Boolean));
+    const repoSet = new Set((preferRepos ?? []).map((r) => r.trim()).filter(Boolean));
+    if (langSet.size === 0 && repoSet.size === 0)
+        return;
+    for (const c of candidates) {
+        let score = 0;
+        const reasons = [];
+        if (repoSet.size > 0 && repoSet.has(c.issue.repo)) {
+            score += REPO_BOOST;
+            reasons.push(`repo affinity: ${c.issue.repo}`);
+        }
+        const lang = c.projectHealth.language;
+        if (langSet.size > 0 && lang && langSet.has(lang.toLowerCase())) {
+            score += LANGUAGE_BOOST;
+            reasons.push(`language match: ${lang}`);
+        }
+        if (score > 0) {
+            c.boostScore = score;
+            c.boostReasons = reasons;
+        }
+    }
+}

package/dist/core/types.d.ts

@@ -53,6 +53,19 @@ export interface IssueCandidate {
     reasonsToApprove: string[];
     viabilityScore: number;
     searchPriority: SearchPriority;
+    /**
+     * Personalization sort tier (#1244). Populated only when the caller
+     * passes `preferLanguages` / `preferRepos` to `search()` *and* the
+     * candidate matches at least one. Affects sort order between the
+     * `recommendation` tier and `viabilityScore`; never used as a filter.
+     */
+    boostScore?: number;
+    /**
+     * Human-readable reasons the candidate matched personalization bias
+     * (#1244). Mirrors `reasonsToApprove`/`reasonsToSkip` shape for
+     * symmetry with the existing surface.
+     */
+    boostReasons?: string[];
 }
 /** Subset of RepoScore fields that callers may update. */
 export interface RepoScoreUpdate {
@@ -122,6 +135,21 @@ export type ScoutConfig = {
 export interface SearchOptions {
     maxResults?: number;
     strategies?: SearchStrategy[];
+    /**
+     * Per-call personalization bias: candidates whose repo language matches
+     * one of these (case-insensitive) get a soft sort boost above
+     * equally-recommended non-matches (#1244). Does not filter results, does
+     * not change `viabilityScore`. Empty / undefined disables the boost.
+     */
+    preferLanguages?: string[];
+    /**
+     * Per-call personalization bias: candidates in one of these
+     * `owner/repo` slugs get a soft sort boost above equally-recommended
+     * non-matches (#1244). Stronger weight than language match. Does not
+     * filter results, does not change `viabilityScore`. Empty / undefined
+     * disables the boost.
+     */
+    preferRepos?: string[];
 }
 /** Result of a search operation. */
 export interface SearchResult {

package/dist/scout.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.9.1",
+  "version": "0.10.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": {