@oss-scout/core 0.11.0 → 1.0.0

package/dist/core/personalization.js

@@ -27,39 +27,47 @@
 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.
+ * 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 function boostScoreOf(candidate) {
+    return candidate.personalization?.kind === "boosted"
+        ? candidate.personalization.score
+        : 0;
+}
+/**
+ * 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 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));
+    const repoSet = new Set((preferRepos ?? []).map((r) => r.trim().toLowerCase()).filter(Boolean));
     if (langSet.size === 0 && repoSet.size === 0)
-        return;
-    for (const c of candidates) {
+        return candidates;
+    return candidates.map((c) => {
         let score = 0;
         const reasons = [];
-        if (repoSet.size > 0 && repoSet.has(c.issue.repo)) {
+        if (repoSet.size > 0 && repoSet.has(c.issue.repo.toLowerCase())) {
             score += REPO_BOOST;
             reasons.push(`repo affinity: ${c.issue.repo}`);
         }
-        const lang = c.projectHealth.language;
+        const lang = c.projectHealth.checkFailed ? null : 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;
-        }
-    }
+        if (score === 0)
+            return c;
+        return { ...c, personalization: { kind: "boosted", score, reasons } };
+    });
 }
 /**
  * Apply a diversity-counterweight pass over a pre-sorted candidate list
@@ -108,10 +116,10 @@ export function applyDiversityRatio(candidates, maxResults, diversityRatio) {
             break;
         if (seen.has(c.issue.url))
             continue;
-        if (c.boostScore && c.boostScore > 0)
+        if (boostScoreOf(c) > 0)
             continue;
-        c.diversitySlot = true;
-        picks.push(c);
+        // Tag a shallow copy rather than mutating the shared candidate (#158).
+        picks.push({ ...c, personalization: { kind: "diversity" } });
         seen.add(c.issue.url);
     }
     for (const c of candidates) {

package/dist/core/preference-fields.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared preference-field metadata and value parsing.
+ *
+ * The CLI (`commands/config.ts`) and the MCP `config-set` tool both update a
+ * single preference from a raw string. They used to carry separate, drifting
+ * copies of the key tables and parse logic — the CLI was missing the SLM
+ * triage keys, the MCP side lacked the `scope` special case and the +/- array
+ * syntax. This module is the single source of truth both drive (#153).
+ */
+import type { ScoutPreferences } from "./schemas.js";
+export type FieldConfig = {
+    type: "array" | "number" | "float" | "boolean" | "string";
+} | {
+    type: "enum" | "enum-array";
+    validValues: readonly string[];
+};
+export declare const FIELD_CONFIGS: Record<string, FieldConfig>;
+/**
+ * Every configurable preference key, derived from the schema so a new
+ * preference can't be silently left unconfigurable. `assertFieldConfigsCover`
+ * (exercised by a unit test) fails loudly if FIELD_CONFIGS drifts from this.
+ */
+export declare const PREFERENCE_KEYS: readonly string[];
+/** Sorted key list for "unknown key" error messages and help text. */
+export declare const SORTED_PREFERENCE_KEYS: readonly string[];
+/**
+ * Throw if any schema preference lacks a FIELD_CONFIG entry. Called from a
+ * test so adding a preference to the schema without teaching config-set how to
+ * parse it is caught in CI rather than at a user's first `config set newKey`.
+ */
+export declare function assertFieldConfigsCover(): void;
+/**
+ * Apply an array update: plain set, +append, or -remove.
+ *
+ * The -remove form starts with a dash, which commander rejects as an unknown
+ * option unless escaped: `config set excludeRepos -- "-spam/repo"`. The MCP
+ * tool has no commander layer so it can pass `-spam/repo` directly. Documented
+ * in the CLI help and README (#132).
+ */
+export declare function updateArray(current: string[], value: string): string[];
+/**
+ * Apply a single key/value update to a preferences object and return the
+ * fully validated result. The raw string `value` is the form both the CLI and
+ * the MCP tool receive; arrays accept comma-separated values and the +add /
+ * -remove syntax. Throws ValidationError on an unknown key or a bad value.
+ */
+export declare function applyPreferenceField(preferences: ScoutPreferences, key: string, value: string): ScoutPreferences;

package/dist/core/preference-fields.js

@@ -0,0 +1,178 @@
+/**
+ * Shared preference-field metadata and value parsing.
+ *
+ * The CLI (`commands/config.ts`) and the MCP `config-set` tool both update a
+ * single preference from a raw string. They used to carry separate, drifting
+ * copies of the key tables and parse logic — the CLI was missing the SLM
+ * triage keys, the MCP side lacked the `scope` special case and the +/- array
+ * syntax. This module is the single source of truth both drive (#153).
+ */
+import { ScoutPreferencesSchema, IssueScopeSchema, ProjectCategorySchema, PersistenceModeSchema, SearchStrategySchema, } from "./schemas.js";
+import { ValidationError } from "./errors.js";
+export const FIELD_CONFIGS = {
+    githubUsername: { type: "string" },
+    languages: { type: "array" },
+    labels: { type: "array" },
+    scope: { type: "enum-array", validValues: IssueScopeSchema.options },
+    excludeRepos: { type: "array" },
+    excludeOrgs: { type: "array" },
+    aiPolicyBlocklist: { type: "array" },
+    projectCategories: {
+        type: "enum-array",
+        validValues: ProjectCategorySchema.options,
+    },
+    minStars: { type: "number" },
+    maxIssueAgeDays: { type: "number" },
+    includeDocIssues: { type: "boolean" },
+    minRepoScoreThreshold: { type: "number" },
+    interPhaseDelayMs: { type: "number" },
+    persistence: { type: "enum", validValues: PersistenceModeSchema.options },
+    defaultStrategy: {
+        type: "enum-array",
+        validValues: SearchStrategySchema.options,
+    },
+    broadPhaseDelayMs: { type: "number" },
+    skipBroadWhenSufficientResults: { type: "number" },
+    preferLanguages: { type: "array" },
+    preferRepos: { type: "array" },
+    diversityRatio: { type: "float" },
+    slmTriageModel: { type: "string" },
+    slmTriageHost: { type: "string" },
+    featuresAnchorThreshold: { type: "number" },
+    featuresSplitRatio: { type: "float" },
+};
+/**
+ * Every configurable preference key, derived from the schema so a new
+ * preference can't be silently left unconfigurable. `assertFieldConfigsCover`
+ * (exercised by a unit test) fails loudly if FIELD_CONFIGS drifts from this.
+ */
+export const PREFERENCE_KEYS = Object.keys(ScoutPreferencesSchema.shape);
+/** Sorted key list for "unknown key" error messages and help text. */
+export const SORTED_PREFERENCE_KEYS = [
+    ...PREFERENCE_KEYS,
+].sort();
+/**
+ * Throw if any schema preference lacks a FIELD_CONFIG entry. Called from a
+ * test so adding a preference to the schema without teaching config-set how to
+ * parse it is caught in CI rather than at a user's first `config set newKey`.
+ */
+export function assertFieldConfigsCover() {
+    const missing = PREFERENCE_KEYS.filter((k) => !(k in FIELD_CONFIGS));
+    if (missing.length > 0) {
+        throw new Error(`FIELD_CONFIGS is missing entries for preference keys: ${missing.join(", ")}`);
+    }
+    const extra = Object.keys(FIELD_CONFIGS).filter((k) => !PREFERENCE_KEYS.includes(k));
+    if (extra.length > 0) {
+        throw new Error(`FIELD_CONFIGS has entries for unknown preference keys: ${extra.join(", ")}`);
+    }
+}
+function parseBoolean(value) {
+    const lower = value.toLowerCase();
+    if (lower === "true" || lower === "yes")
+        return true;
+    if (lower === "false" || lower === "no")
+        return false;
+    throw new ValidationError(`Invalid boolean value: "${value}". Use true/false or yes/no.`);
+}
+function parseIntValue(value, key) {
+    const num = parseInt(value, 10);
+    if (isNaN(num)) {
+        throw new ValidationError(`Invalid number for "${key}": "${value}"`);
+    }
+    return num;
+}
+function parseFloatValue(value, key) {
+    const num = Number.parseFloat(value);
+    if (isNaN(num)) {
+        throw new ValidationError(`Invalid number for "${key}": "${value}"`);
+    }
+    return num;
+}
+function parseArrayValue(value) {
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Apply an array update: plain set, +append, or -remove.
+ *
+ * The -remove form starts with a dash, which commander rejects as an unknown
+ * option unless escaped: `config set excludeRepos -- "-spam/repo"`. The MCP
+ * tool has no commander layer so it can pass `-spam/repo` directly. Documented
+ * in the CLI help and README (#132).
+ */
+export function updateArray(current, value) {
+    if (value.startsWith("+")) {
+        const toAdd = parseArrayValue(value.slice(1));
+        const merged = [...current];
+        for (const item of toAdd) {
+            if (!merged.includes(item))
+                merged.push(item);
+        }
+        return merged;
+    }
+    if (value.startsWith("-")) {
+        const toRemove = new Set(parseArrayValue(value.slice(1)));
+        return current.filter((item) => !toRemove.has(item));
+    }
+    return parseArrayValue(value);
+}
+/**
+ * Apply a single key/value update to a preferences object and return the
+ * fully validated result. The raw string `value` is the form both the CLI and
+ * the MCP tool receive; arrays accept comma-separated values and the +add /
+ * -remove syntax. Throws ValidationError on an unknown key or a bad value.
+ */
+export function applyPreferenceField(preferences, key, value) {
+    const field = FIELD_CONFIGS[key];
+    if (!field) {
+        throw new ValidationError(`Unknown config key: "${key}". Valid keys: ${SORTED_PREFERENCE_KEYS.join(", ")}`);
+    }
+    const prefs = { ...preferences };
+    switch (field.type) {
+        case "string":
+            prefs[key] = value;
+            break;
+        case "boolean":
+            prefs[key] = parseBoolean(value);
+            break;
+        case "number":
+            prefs[key] = parseIntValue(value, key);
+            break;
+        case "float":
+            prefs[key] = parseFloatValue(value, key);
+            break;
+        case "array": {
+            const current = prefs[key] ?? [];
+            prefs[key] = updateArray(current, value);
+            break;
+        }
+        case "enum": {
+            const validValues = field.validValues;
+            if (!validValues.includes(value)) {
+                throw new ValidationError(`Invalid value for "${key}": "${value}". Valid: ${validValues.join(", ")}`);
+            }
+            prefs[key] = value;
+            break;
+        }
+        case "enum-array": {
+            const current = prefs[key] ?? [];
+            const updated = updateArray(current, value);
+            const validValues = field.validValues;
+            const invalid = updated.filter((s) => !validValues.includes(s));
+            if (invalid.length > 0) {
+                throw new ValidationError(`Invalid value(s) for "${key}": ${invalid.join(", ")}. Valid: ${validValues.join(", ")}`);
+            }
+            // For 'scope', an empty array means undefined (all scopes).
+            if (key === "scope") {
+                prefs[key] = updated.length > 0 ? updated : undefined;
+            }
+            else {
+                prefs[key] = updated;
+            }
+            break;
+        }
+    }
+    return ScoutPreferencesSchema.parse(prefs);
+}

package/dist/core/repo-health.js

@@ -5,7 +5,7 @@
  * from issue-level eligibility logic.
  */
 import { daysBetween } from "./utils.js";
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError, rethrowIfFatal, } from "./errors.js";
 import { warn } from "./logger.js";
 import { getHttpCache, cachedRequest, cachedTimeBased } from "./http-cache.js";
 const MODULE = "repo-health";
@@ -73,19 +73,14 @@ export async function checkProjectHealth(octokit, owner, repo) {
         });
     }
     catch (error) {
-        if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
-            throw error;
-        }
+        rethrowIfFatal(error);
         const errMsg = errorMessage(error);
         warn(MODULE, `Error checking project health for ${owner}/${repo}: ${errMsg}`);
+        // The check failed: only the repo and the reason are known. The
+        // discriminated ProjectHealth type intentionally has no place for the
+        // neutral-default snapshot fields this used to fabricate (#158).
         return {
             repo: `${owner}/${repo}`,
-            lastCommitAt: "",
-            daysSinceLastCommit: 999,
-            openIssuesCount: 0,
-            avgIssueResponseDays: 0,
-            ciStatus: "unknown",
-            isActive: false,
             checkFailed: true,
             failureReason: errMsg,
         };
@@ -104,6 +99,22 @@ export async function fetchContributionGuidelines(octokit, owner, repo) {
     if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
         return cached.guidelines;
     }
+    // Concurrent vets of issues from one repo share a single probe (#124)
+    const inflight = guidelinesInflight.get(cacheKey);
+    if (inflight)
+        return inflight;
+    const promise = fetchContributionGuidelinesUncached(octokit, owner, repo);
+    guidelinesInflight.set(cacheKey, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        guidelinesInflight.delete(cacheKey);
+    }
+}
+const guidelinesInflight = new Map();
+async function fetchContributionGuidelinesUncached(octokit, owner, repo) {
+    const cacheKey = `${owner}/${repo}`;
     const filesToCheck = [
         "CONTRIBUTING.md",
         ".github/CONTRIBUTING.md",
@@ -160,9 +171,13 @@ function parseContributionGuidelines(content) {
         rawContent: content,
     };
     const lowerContent = content.toLowerCase();
-    // Detect branch naming conventions
+    // Detect branch naming conventions. CONTRIBUTING.md is attacker-controlled
+    // (it belongs to the repo being vetted): the unbounded [^\n]* pair forced
+    // quadratic backtracking on a long quote-less line, stalling the vet
+    // (#152). Bounded quantifiers keep the scan linear-ish; real conventions
+    // sit well inside 200 chars of their keyword.
     if (lowerContent.includes("branch")) {
-        const branchMatch = content.match(/branch[^\n]*(?:named?|format|convention)[^\n]*[`"]([^`"]+)[`"]/i);
+        const branchMatch = content.match(/branch[^\n]{0,200}?(?:named?|format|convention)[^\n]{0,200}?[`"]([^`"\n]{1,100})[`"]/i);
         if (branchMatch) {
             guidelines.branchNamingConvention = branchMatch[1];
         }
@@ -172,7 +187,7 @@ function parseContributionGuidelines(content) {
         guidelines.commitMessageFormat = "conventional commits";
     }
     else if (lowerContent.includes("commit message")) {
-        const commitMatch = content.match(/commit message[^\n]*[`"]([^`"]+)[`"]/i);
+        const commitMatch = content.match(/commit message[^\n]{0,200}?[`"]([^`"\n]{1,100})[`"]/i);
         if (commitMatch) {
             guidelines.commitMessageFormat = commitMatch[1];
         }
@@ -193,8 +208,9 @@ function parseContributionGuidelines(content) {
         guidelines.linter = "RuboCop";
     else if (lowerContent.includes("prettier"))
         guidelines.formatter = "Prettier";
-    // Detect CLA requirement
-    if (lowerContent.includes("cla") ||
+    // Detect CLA requirement. Word boundary matters: a bare substring check
+    // matches "class", "clang", "clarify", etc. and flags nearly every doc.
+    if (/\bcla\b/.test(lowerContent) ||
         lowerContent.includes("contributor license agreement")) {
         guidelines.claRequired = true;
     }

package/dist/core/roadmap.js

@@ -10,7 +10,7 @@
  * Auth (401) and rate-limit errors propagate, matching the rest of the
  * codebase's error strategy. Other errors degrade gracefully (warn + empty).
  */
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { errorMessage, getHttpStatusCode, rethrowIfFatal } from "./errors.js";
 import { warn } from "./logger.js";
 const MODULE = "roadmap";
 /** TTL for roadmap fetch results (1 hour). */
@@ -97,6 +97,21 @@ export async function fetchRoadmapIssueRefs(octokit, owner, repo) {
     if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
         return cached.refs;
     }
+    // Concurrent feature vets of issues from one repo share a probe (#124)
+    const inflight = roadmapInflight.get(cacheKey);
+    if (inflight)
+        return inflight;
+    const promise = fetchRoadmapIssueRefsUncached(octokit, owner, repo, cacheKey);
+    roadmapInflight.set(cacheKey, promise);
+    try {
+        return await promise;
+    }
+    finally {
+        roadmapInflight.delete(cacheKey);
+    }
+}
+const roadmapInflight = new Map();
+async function fetchRoadmapIssueRefsUncached(octokit, owner, repo, cacheKey) {
     for (const path of ROADMAP_PATHS) {
         try {
             const { data } = await octokit.repos.getContent({ owner, repo, path });
@@ -109,8 +124,7 @@ export async function fetchRoadmapIssueRefs(octokit, owner, repo) {
             return refs;
         }
         catch (err) {
-            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-                throw err;
+            rethrowIfFatal(err);
             const status = getHttpStatusCode(err);
             if (status === 404)
                 continue; // path missing — try next