@oss-scout/core 0.11.0 → 1.1.0

package/dist/commands/skip.js

@@ -1,52 +1,41 @@
 /**
  * Skip command — manage the skip list for excluding issues from future searches.
  */
-import { loadLocalState, saveLocalState } from "../core/local-state.js";
-import { createScout } from "../scout.js";
-import { getGitHubToken } from "../core/utils.js";
-/**
- * Create an OssScout instance for skip operations.
- * Uses gist persistence when a token is available, otherwise provided-state mode.
- */
-async function createSkipScout(state) {
-    const token = getGitHubToken() ?? "";
-    if (token) {
-        return createScout({
-            githubToken: token,
-            persistence: "provided",
-            initialState: state,
-        });
-    }
-    return createScout({
-        githubToken: "",
-        persistence: "provided",
-        initialState: state,
-    });
-}
+import { loadLocalState } from "../core/local-state.js";
+import { withScout, persistScout } from "./with-scout.js";
+import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl, } from "./validation.js";
+// Skip operations are local-only, so they don't require a GitHub token.
+const SKIP_SCOUT_OPTIONS = { requireToken: false };
 /**
  * Skip an issue by URL — adds it to the skip list and removes it from saved results.
  * Tries to enrich metadata from saved results if available.
  */
 export async function runSkip(options) {
-    const state = options.state ?? loadLocalState();
-    const scout = await createSkipScout(state);
-    const alreadySkipped = scout
-        .getSkippedIssues()
-        .some((s) => s.url === options.issueUrl);
-    if (alreadySkipped) {
-        return { skipped: false, alreadySkipped: true };
-    }
-    // Try to enrich metadata from saved results
-    const saved = scout
-        .getSavedResults()
-        .find((r) => r.issueUrl === options.issueUrl);
-    const metadata = saved
-        ? { repo: saved.repo, number: saved.number, title: saved.title }
-        : parseIssueUrl(options.issueUrl);
-    scout.skipIssue(options.issueUrl, metadata);
-    saveLocalState(scout.getState());
-    await scout.checkpoint();
-    return { skipped: true, alreadySkipped: false };
+    // Validate up front: skip matching is exact-URL, so a junk or near-miss
+    // URL (trailing slash, query string) would be stored but never exclude
+    // anything — a silent no-op. Reject it with the expected format instead.
+    validateUrl(options.issueUrl);
+    validateGitHubUrl(options.issueUrl, ISSUE_URL_PATTERN, "issue");
+    return withScout(options.state, async (scout) => {
+        const alreadySkipped = scout
+            .getSkippedIssues()
+            .some((s) => s.url === options.issueUrl);
+        if (alreadySkipped) {
+            return { skipped: false, alreadySkipped: true };
+        }
+        // Try to enrich metadata from saved results
+        const saved = scout
+            .getSavedResults()
+            .find((r) => r.issueUrl === options.issueUrl);
+        const metadata = saved
+            ? { repo: saved.repo, number: saved.number, title: saved.title }
+            : parseIssueUrl(options.issueUrl);
+        scout.skipIssue(options.issueUrl, metadata);
+        // Persist only on an actual change so an already-skipped no-op doesn't
+        // trigger a needless gist push.
+        await persistScout(scout);
+        return { skipped: true, alreadySkipped: false };
+    }, SKIP_SCOUT_OPTIONS);
 }
 /**
  * List all skipped issues.
@@ -59,30 +48,31 @@ export function runSkipList(options) {
  * Clear all skipped issues.
  */
 export async function runSkipClear() {
-    const state = loadLocalState();
-    const scout = await createSkipScout(state);
-    scout.clearSkippedIssues();
-    saveLocalState(scout.getState());
-    await scout.checkpoint();
+    await withScout(undefined, (scout) => {
+        scout.clearSkippedIssues();
+    }, { ...SKIP_SCOUT_OPTIONS, persist: true });
 }
 /**
  * Remove a specific issue from the skip list (unskip).
+ *
+ * Deliberately does NOT validate the URL: entries stored before skip-add
+ * validation existed may be junk, and exact-match removal is the only way
+ * to clean them up short of `skip clear`.
  */
 export async function runSkipRemove(options) {
-    const state = loadLocalState();
-    const scout = await createSkipScout(state);
-    const before = scout.getSkippedIssues().length;
-    scout.unskipIssue(options.issueUrl);
-    const removed = before !== scout.getSkippedIssues().length;
-    saveLocalState(scout.getState());
-    await scout.checkpoint();
-    return { removed };
+    return withScout(undefined, async (scout) => {
+        const before = scout.getSkippedIssues().length;
+        scout.unskipIssue(options.issueUrl);
+        const removed = before !== scout.getSkippedIssues().length;
+        await persistScout(scout);
+        return { removed };
+    }, SKIP_SCOUT_OPTIONS);
 }
 /**
  * Parse a GitHub issue URL to extract repo and number.
  */
 function parseIssueUrl(url) {
-    const match = url.match(/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)/);
+    const match = url.match(/^https:\/\/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)$/);
     if (!match)
         return undefined;
     return { repo: match[1], number: parseInt(match[2], 10), title: "" };

package/dist/commands/sync.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sync command — reconcile tracked open PRs against their current GitHub state
+ * (#164). Records merges/closures, prunes resolved entries, and recomputes repo
+ * scores. Cheaper than a full bootstrap; meant for periodic / daily runs.
+ */
+import type { ScoutState } from "../core/schemas.js";
+import type { SyncResult } from "../core/types.js";
+export declare function runSync(options?: {
+    state?: ScoutState;
+}): Promise<SyncResult>;

package/dist/commands/sync.js

@@ -0,0 +1,10 @@
+/**
+ * Sync command — reconcile tracked open PRs against their current GitHub state
+ * (#164). Records merges/closures, prunes resolved entries, and recomputes repo
+ * scores. Cheaper than a full bootstrap; meant for periodic / daily runs.
+ */
+import { withScout } from "./with-scout.js";
+export async function runSync(options) {
+    // syncOpenPRs checkpoints itself, so withScout doesn't need to persist.
+    return withScout(options?.state, (scout) => scout.syncOpenPRs());
+}

package/dist/commands/vet-list.js

@@ -1,23 +1,7 @@
-import { createScout } from "../scout.js";
-import { requireGitHubToken } from "../core/utils.js";
-import { saveLocalState } from "../core/local-state.js";
+import { withScout } from "./with-scout.js";
 export async function runVetList(options) {
-    const token = requireGitHubToken();
-    const scout = options.state
-        ? await createScout({
-            githubToken: token,
-            persistence: "provided",
-            initialState: options.state,
-        })
-        : await createScout({ githubToken: token });
-    const result = await scout.vetList({
+    return withScout(options.state, (scout) => scout.vetList({
         concurrency: options.concurrency,
         prune: options.prune,
-    });
-    saveLocalState(scout.getState());
-    const persisted = await scout.checkpoint();
-    if (!persisted) {
-        console.error("Warning: changes saved locally but gist sync failed.");
-    }
-    return result;
+    }), { persist: true });
 }

package/dist/commands/vet.js

@@ -1,33 +1,26 @@
 /**
  * Vet command — vets a specific issue for claimability.
  */
-import { createScout } from "../scout.js";
-import { requireGitHubToken } from "../core/utils.js";
+import { withScout } from "./with-scout.js";
 import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl, } from "./validation.js";
 export async function runVet(options) {
     validateUrl(options.issueUrl);
     validateGitHubUrl(options.issueUrl, ISSUE_URL_PATTERN, "issue");
-    const token = requireGitHubToken();
-    const scout = options.state
-        ? await createScout({
-            githubToken: token,
-            persistence: "provided",
-            initialState: options.state,
-        })
-        : await createScout({ githubToken: token });
-    const candidate = await scout.vetIssue(options.issueUrl);
-    return {
-        issue: {
-            repo: candidate.issue.repo,
-            number: candidate.issue.number,
-            title: candidate.issue.title,
-            url: candidate.issue.url,
-            labels: candidate.issue.labels,
-        },
-        recommendation: candidate.recommendation,
-        reasonsToApprove: candidate.reasonsToApprove,
-        reasonsToSkip: candidate.reasonsToSkip,
-        projectHealth: candidate.projectHealth,
-        vettingResult: candidate.vettingResult,
-    };
+    return withScout(options.state, async (scout) => {
+        const candidate = await scout.vetIssue(options.issueUrl);
+        return {
+            issue: {
+                repo: candidate.issue.repo,
+                number: candidate.issue.number,
+                title: candidate.issue.title,
+                url: candidate.issue.url,
+                labels: candidate.issue.labels,
+            },
+            recommendation: candidate.recommendation,
+            reasonsToApprove: candidate.reasonsToApprove,
+            reasonsToSkip: candidate.reasonsToSkip,
+            projectHealth: candidate.projectHealth,
+            vettingResult: candidate.vettingResult,
+        };
+    });
 }

package/dist/commands/with-scout.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared command scaffolding (#154).
+ *
+ * Every command repeated the same prologue (require token, load state, build
+ * the scout) and most repeated the same epilogue (write local state, gist
+ * checkpoint, warn on gist failure). The warning text was byte-identical in
+ * three files and inconsistently omitted in skip.ts. `withScout` owns the
+ * prologue plus an optional persist epilogue; `persistScout` is the epilogue
+ * on its own for commands that persist only on some code paths.
+ */
+import type { OssScout } from "../scout.js";
+import type { ScoutState } from "../core/schemas.js";
+/**
+ * Write the scout's state to disk and push the gist checkpoint, warning to
+ * stderr if the gist push failed (local save still succeeded).
+ */
+export declare function persistScout(scout: OssScout): Promise<void>;
+export interface WithScoutOptions {
+    /** Persist via persistScout after fn resolves. Default false. */
+    persist?: boolean;
+    /**
+     * Require a GitHub token (throws if absent). Default true. Skip-list
+     * operations are local-only and pass false so they work without auth.
+     */
+    requireToken?: boolean;
+}
+/**
+ * Build a scout for the given (or loaded) state, run fn against it, and
+ * optionally persist afterward. Centralizes the create/persist/warn boilerplate
+ * shared by the search, vet, vet-list, features, and skip commands.
+ */
+export declare function withScout<T>(state: ScoutState | undefined, fn: (scout: OssScout) => Promise<T> | T, options?: WithScoutOptions): Promise<T>;

package/dist/commands/with-scout.js

@@ -0,0 +1,41 @@
+/**
+ * Shared command scaffolding (#154).
+ *
+ * Every command repeated the same prologue (require token, load state, build
+ * the scout) and most repeated the same epilogue (write local state, gist
+ * checkpoint, warn on gist failure). The warning text was byte-identical in
+ * three files and inconsistently omitted in skip.ts. `withScout` owns the
+ * prologue plus an optional persist epilogue; `persistScout` is the epilogue
+ * on its own for commands that persist only on some code paths.
+ */
+import { buildCommandScout } from "./command-scout.js";
+import { requireGitHubToken, getGitHubToken } from "../core/utils.js";
+import { loadLocalState, saveLocalState } from "../core/local-state.js";
+const GIST_SYNC_WARNING = "Warning: changes saved locally but gist sync failed.";
+/**
+ * Write the scout's state to disk and push the gist checkpoint, warning to
+ * stderr if the gist push failed (local save still succeeded).
+ */
+export async function persistScout(scout) {
+    saveLocalState(scout.getState());
+    const persisted = await scout.checkpoint();
+    if (!persisted) {
+        console.error(GIST_SYNC_WARNING);
+    }
+}
+/**
+ * Build a scout for the given (or loaded) state, run fn against it, and
+ * optionally persist afterward. Centralizes the create/persist/warn boilerplate
+ * shared by the search, vet, vet-list, features, and skip commands.
+ */
+export async function withScout(state, fn, options = {}) {
+    const { persist = false, requireToken = true } = options;
+    const token = requireToken ? requireGitHubToken() : (getGitHubToken() ?? "");
+    const resolvedState = state ?? loadLocalState();
+    const scout = await buildCommandScout(resolvedState, token);
+    const result = await fn(scout);
+    if (persist) {
+        await persistScout(scout);
+    }
+    return result;
+}

package/dist/core/anti-llm-policy.js

@@ -7,10 +7,9 @@
  * can rely on a structured `AntiLLMPolicyResult` rather than re-implementing
  * the scan in agent prose.
  */
-import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
-import { warn } from "./logger.js";
-import { getHttpCache } from "./http-cache.js";
-const MODULE = "anti-llm-policy";
+import { getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { getHttpCache, versionedCacheKey } from "./http-cache.js";
+import { probeRepoFile } from "./probe-repo-file.js";
 /** TTL for cached anti-LLM policy scan results (1 hour). Policy docs change rarely. */
 const POLICY_SCAN_CACHE_TTL_MS = 60 * 60 * 1000;
 /**
@@ -85,40 +84,13 @@ const SOURCE_FILE_FAMILIES = [
         paths: ["README.md", "readme.md", "Readme.md"],
     },
 ];
-/**
- * Fetch one path's raw text content. The `transient` flag distinguishes a
- * clean miss (404 — file absent) from a degraded miss (5xx, network) so the
- * caller can decide whether to cache "no policy" or retry. Throws on
- * 401/auth and rate-limit per documented project error strategy.
- */
-async function fetchFileText(octokit, owner, repo, path) {
-    try {
-        const { data } = await octokit.repos.getContent({ owner, repo, path });
-        if ("content" in data && typeof data.content === "string") {
-            return {
-                text: Buffer.from(data.content, "base64").toString("utf-8"),
-                transient: false,
-            };
-        }
-        return { text: null, transient: false };
-    }
-    catch (error) {
-        const status = getHttpStatusCode(error);
-        if (status === 404)
-            return { text: null, transient: false };
-        if (status === 401 || isRateLimitError(error))
-            throw error;
-        warn(MODULE, `Unexpected error fetching ${path} from ${owner}/${repo}: ${errorMessage(error)}`);
-        return { text: null, transient: true };
-    }
-}
 /**
  * Fetch the first available file from a family. Probes are issued in parallel,
  * but auth/rate-limit rejections re-throw so the IssueVetter's existing
  * rate-limit handling kicks in instead of silently caching a wrong answer.
  */
 async function fetchFamilyText(octokit, owner, repo, paths) {
-    const results = await Promise.allSettled(paths.map((p) => fetchFileText(octokit, owner, repo, p)));
+    const results = await Promise.allSettled(paths.map((p) => probeRepoFile(octokit, owner, repo, p)));
     let hadTransientFailure = false;
     for (const result of results) {
         if (result.status === "fulfilled") {
@@ -162,7 +134,7 @@ function isAntiLLMPolicyResult(value) {
  */
 export async function fetchAndScanAntiLLMPolicy(octokit, owner, repo, options) {
     const cache = getHttpCache();
-    const cacheKey = `anti-llm-policy:${owner}/${repo}`;
+    const cacheKey = versionedCacheKey(`anti-llm-policy:${owner}/${repo}`);
     const cached = cache.getIfFresh(cacheKey, POLICY_SCAN_CACHE_TTL_MS);
     if (isAntiLLMPolicyResult(cached))
         return cached;

package/dist/core/bootstrap.d.ts

@@ -2,7 +2,7 @@
  * First-run bootstrap — fetches starred repos and PR history from GitHub
  * to seed the scout's state with the user's contribution context.
  */
-import type { OssScout } from "../scout.js";
+import type { ScoutStateWriter } from "./issue-vetting.js";
 export interface BootstrapResult {
     starredRepoCount: number;
     mergedPRCount: number;
@@ -12,4 +12,4 @@ export interface BootstrapResult {
     skippedDueToRateLimit: boolean;
     errors: string[];
 }
-export declare function bootstrapScout(scout: OssScout, token: string): Promise<BootstrapResult>;
+export declare function bootstrapScout(scout: ScoutStateWriter, token: string): Promise<BootstrapResult>;

package/dist/core/bootstrap.js

@@ -4,7 +4,7 @@
  */
 import { getOctokit, checkRateLimit } from "./github.js";
 import { debug, warn } from "./logger.js";
-import { ConfigurationError, errorMessage, getHttpStatusCode, isRateLimitError, } from "./errors.js";
+import { ConfigurationError, errorMessage, rethrowIfFatal } from "./errors.js";
 import { extractRepoFromUrl } from "./utils.js";
 const MODULE = "bootstrap";
 const STARRED_MAX_PAGES = 5;
@@ -51,8 +51,7 @@ export async function bootstrapScout(scout, token) {
         scout.setStarredRepos(starredRepos);
     }
     catch (err) {
-        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-            throw err;
+        rethrowIfFatal(err);
         warn(MODULE, `Failed to fetch starred repos: ${errorMessage(err)}`);
         errors.push("starred repos fetch failed");
     }
@@ -83,8 +82,7 @@ export async function bootstrapScout(scout, token) {
         debug(MODULE, `Imported ${mergedPRCount} merged PRs`);
     }
     catch (err) {
-        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-            throw err;
+        rethrowIfFatal(err);
         warn(MODULE, `Failed to fetch merged PRs: ${errorMessage(err)}`);
         errors.push("merged PR fetch failed");
     }
@@ -115,8 +113,7 @@ export async function bootstrapScout(scout, token) {
         debug(MODULE, `Imported ${closedPRCount} closed PRs`);
     }
     catch (err) {
-        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-            throw err;
+        rethrowIfFatal(err);
         warn(MODULE, `Failed to fetch closed PRs: ${errorMessage(err)}`);
         errors.push("closed PR fetch failed");
     }
@@ -147,8 +144,7 @@ export async function bootstrapScout(scout, token) {
         debug(MODULE, `Imported ${openPRCount} open PRs`);
     }
     catch (err) {
-        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
-            throw err;
+        rethrowIfFatal(err);
         warn(MODULE, `Failed to fetch open PRs: ${errorMessage(err)}`);
         errors.push("open PR fetch failed");
     }

package/dist/core/errors.d.ts

@@ -21,6 +21,16 @@ export declare class ValidationError extends OssScoutError {
 export declare function errorMessage(e: unknown): string;
 export declare function getHttpStatusCode(error: unknown): number | undefined;
 export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Re-throw an error if it is one that must always propagate: a 401 (auth) or
+ * any rate-limit condition (429, 403 + rate-limit/abuse). Otherwise return so
+ * the caller can degrade gracefully. Centralizes the guard that was
+ * copy-pasted across ~16 catch blocks (#154).
+ *
+ * Note: catch sites that deliberately treat a rate limit as degradable use a
+ * bare `getHttpStatusCode(err) === 401` check instead and must NOT call this.
+ */
+export declare function rethrowIfFatal(error: unknown): void;
 /** Error codes for JSON output. */
 export type ErrorCode = "AUTH_REQUIRED" | "CONFIGURATION" | "NETWORK" | "NOT_FOUND" | "RATE_LIMITED" | "STATE_CORRUPTED" | "UNKNOWN" | "VALIDATION";
 /**

package/dist/core/errors.js

@@ -46,10 +46,27 @@ export function isRateLimitError(error) {
         return true;
     if (status === 403) {
         const msg = errorMessage(error).toLowerCase();
-        return msg.includes("rate limit");
+        // "rate limit" also covers GitHub's "secondary rate limit" wording;
+        // abuse-detection 403s carry neither substring but are the same
+        // back-off-and-retry condition, so they must propagate too (#138).
+        return msg.includes("rate limit") || msg.includes("abuse detection");
     }
     return false;
 }
+/**
+ * Re-throw an error if it is one that must always propagate: a 401 (auth) or
+ * any rate-limit condition (429, 403 + rate-limit/abuse). Otherwise return so
+ * the caller can degrade gracefully. Centralizes the guard that was
+ * copy-pasted across ~16 catch blocks (#154).
+ *
+ * Note: catch sites that deliberately treat a rate limit as degradable use a
+ * bare `getHttpStatusCode(err) === 401` check instead and must NOT call this.
+ */
+export function rethrowIfFatal(error) {
+    if (getHttpStatusCode(error) === 401 || isRateLimitError(error)) {
+        throw error;
+    }
+}
 /**
  * Map an unknown error to a structured ErrorCode for JSON output.
  */
@@ -62,10 +79,8 @@ export function resolveErrorCode(err) {
     if (status === 401)
         return "AUTH_REQUIRED";
     if (status === 403) {
-        const msg = errorMessage(err).toLowerCase();
-        if (msg.includes("rate limit") || msg.includes("abuse detection"))
-            return "RATE_LIMITED";
-        return "AUTH_REQUIRED";
+        // Single source of truth for the 403 rate-limit/abuse classification
+        return isRateLimitError(err) ? "RATE_LIMITED" : "AUTH_REQUIRED";
     }
     if (status === 404)
         return "NOT_FOUND";

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

@@ -138,10 +138,22 @@ export interface DiscoverFeaturesBroadOptions {
  * is independently testable without mocking the Search API.
  */
 export declare function buildBroadFeatureSearchQuery(opts: {
-    languages?: string[];
+    /** Single language per query; see buildBroadFeatureSearchQueries. */
+    language?: string;
     excludeRepos?: string[];
     excludeOrgs?: string[];
 }): string;
+/**
+ * One query per language. A combined `(language:a OR language:b)` clause
+ * pushed the query past GitHub's 5-operator limit (the label ORs already
+ * spend all five), so every 2+ language config drew a 422 that the caller
+ * swallowed into "no results" (#121). "any" disables the filter.
+ */
+export declare function buildBroadFeatureSearchQueries(opts: {
+    languages?: string[];
+    excludeRepos?: string[];
+    excludeOrgs?: string[];
+}): string[];
 /**
  * Orchestrate broad / cross-repo feature discovery (#100). Bypasses anchor
  * resolution; runs a single GitHub Search API query for feature-labeled