@oss-autopilot/core 0.58.0 → 0.59.0

package/dist/core/formatter-detection.js

@@ -0,0 +1,360 @@
+/**
+ * Formatter Detection Module (#703)
+ *
+ * Programmatically detects formatters/linters configured in a local repo directory
+ * and diagnoses CI formatting failures from log output.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { debug } from './logger.js';
+const MODULE = 'formatter-detection';
+// ── Prettier config file patterns ──────────────────────────────────────────
+const PRETTIER_CONFIG_PATTERNS = [
+    '.prettierrc',
+    '.prettierrc.json',
+    '.prettierrc.yml',
+    '.prettierrc.yaml',
+    '.prettierrc.json5',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.mjs',
+    '.prettierrc.toml',
+    'prettier.config.js',
+    'prettier.config.cjs',
+    'prettier.config.mjs',
+];
+// ── ESLint config file patterns ────────────────────────────────────────────
+const ESLINT_CONFIG_PATTERNS = [
+    '.eslintrc',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.yml',
+    '.eslintrc.yaml',
+    '.eslintrc.json',
+    'eslint.config.js',
+    'eslint.config.cjs',
+    'eslint.config.mjs',
+    'eslint.config.ts',
+];
+// ── package.json script names that indicate formatting ─────────────────────
+const FORMAT_SCRIPT_NAMES = ['lint:fix', 'format', 'fmt', 'lint', 'format:check', 'format:fix'];
+// ── CI log patterns for each formatter ────────────────────────────────────
+const CI_PATTERNS = [
+    {
+        formatter: 'prettier',
+        patterns: [/Code style issues found/i, /Forgot to run Prettier/i, /prettier --check/i],
+    },
+    {
+        formatter: 'ruff',
+        patterns: [/ruff format.*--check/i, /ruff format.*would reformat/i],
+    },
+    {
+        formatter: 'black',
+        patterns: [/Oh no! .* files? would be reformatted/i, /black --check/i],
+    },
+    {
+        formatter: 'rustfmt',
+        patterns: [/Diff in .*\.rs/i, /rustfmt --check/i, /cargo fmt.*--check/i],
+    },
+    {
+        formatter: 'biome',
+        patterns: [/biome check/i, /biome ci/i, /Found \d+ fixable diagnostics?/i],
+    },
+    {
+        formatter: 'eslint',
+        patterns: [/eslint.*--fix/i, /eslint.*\d+ problems?/i],
+    },
+    {
+        formatter: 'gofmt',
+        patterns: [/gofmt -d/i, /goimports/i],
+    },
+    {
+        formatter: 'clang-format',
+        patterns: [/clang-format/i],
+    },
+    {
+        formatter: 'rubocop',
+        patterns: [/rubocop.*offense/i, /rubocop -a/i],
+    },
+];
+/**
+ * Safely read and parse a JSON file. Returns undefined on failure.
+ */
+function readJsonFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (err) {
+        debug(MODULE, `Failed to parse ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Safely read a text file. Returns undefined on failure.
+ */
+function readTextFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        debug(MODULE, `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Find the first existing file from a list of candidates in a directory.
+ */
+function findFirstExisting(dir, candidates) {
+    for (const candidate of candidates) {
+        if (fs.existsSync(path.join(dir, candidate))) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Read and parse package.json once. Returns undefined if not found or invalid.
+ */
+function readPackageJson(repoPath) {
+    return readJsonFile(path.join(repoPath, 'package.json'));
+}
+/**
+ * Extract formatting-related scripts from a parsed package.json.
+ */
+function extractPackageJsonScripts(pkg) {
+    if (!pkg?.scripts)
+        return [];
+    const results = [];
+    for (const scriptName of FORMAT_SCRIPT_NAMES) {
+        const command = pkg.scripts[scriptName];
+        if (command) {
+            results.push({ name: scriptName, command });
+        }
+    }
+    return results;
+}
+/**
+ * Check if prettier is listed in devDependencies or dependencies.
+ */
+function hasPrettierDependency(pkg) {
+    if (!pkg)
+        return false;
+    return !!(pkg.devDependencies?.['prettier'] || pkg.dependencies?.['prettier']);
+}
+/**
+ * Check if a TOML file contains a specific section header.
+ */
+function tomlHasSection(repoPath, fileName, sectionPattern) {
+    const content = readTextFile(path.join(repoPath, fileName));
+    if (!content)
+        return false;
+    return content.includes(sectionPattern);
+}
+/**
+ * Detect formatters and linters configured in a repository.
+ *
+ * Checks config files in priority order using fs.existsSync() / fs.readFileSync().
+ * Returns all detected formatters, plus any formatting-related package.json scripts.
+ *
+ * @param repoPath - Absolute path to the repository root directory
+ * @returns Detection result with formatters ordered by priority and extracted package.json scripts
+ * @throws {Error} If repoPath does not exist or is not a directory
+ */
+export function detectFormatters(repoPath) {
+    if (!fs.existsSync(repoPath) || !fs.statSync(repoPath).isDirectory()) {
+        throw new Error(`Repository path does not exist or is not a directory: ${repoPath}`);
+    }
+    const formatters = [];
+    const pkg = readPackageJson(repoPath);
+    // 1. Biome (highest priority for JS/TS — replaces prettier + eslint)
+    const biomeConfig = findFirstExisting(repoPath, ['biome.json', 'biome.jsonc']);
+    if (biomeConfig) {
+        formatters.push({
+            name: 'biome',
+            configPath: biomeConfig,
+            fixCommand: 'npx @biomejs/biome check --write',
+            checkCommand: 'npx @biomejs/biome check',
+            supportsFileArgs: true,
+        });
+    }
+    // 2. Prettier
+    const prettierConfig = findFirstExisting(repoPath, PRETTIER_CONFIG_PATTERNS);
+    if (prettierConfig) {
+        formatters.push({
+            name: 'prettier',
+            configPath: prettierConfig,
+            fixCommand: 'npx prettier --write .',
+            checkCommand: 'npx prettier --check .',
+            supportsFileArgs: true,
+        });
+    }
+    else if (hasPrettierDependency(pkg)) {
+        formatters.push({
+            name: 'prettier',
+            configPath: 'package.json',
+            fixCommand: 'npx prettier --write .',
+            checkCommand: 'npx prettier --check .',
+            supportsFileArgs: true,
+        });
+    }
+    // 3. ESLint
+    const eslintConfig = findFirstExisting(repoPath, ESLINT_CONFIG_PATTERNS);
+    if (eslintConfig) {
+        formatters.push({
+            name: 'eslint',
+            configPath: eslintConfig,
+            fixCommand: 'npx eslint --fix .',
+            checkCommand: 'npx eslint .',
+            supportsFileArgs: true,
+        });
+    }
+    // 4. Rust (Cargo.toml → rustfmt)
+    if (fs.existsSync(path.join(repoPath, 'Cargo.toml'))) {
+        formatters.push({
+            name: 'rustfmt',
+            configPath: 'Cargo.toml',
+            fixCommand: 'cargo fmt',
+            checkCommand: 'cargo fmt --check',
+            supportsFileArgs: false,
+        });
+    }
+    // 5. Python — ruff takes priority over black
+    const hasPyproject = fs.existsSync(path.join(repoPath, 'pyproject.toml'));
+    if (hasPyproject && tomlHasSection(repoPath, 'pyproject.toml', '[tool.ruff]')) {
+        formatters.push({
+            name: 'ruff',
+            configPath: 'pyproject.toml',
+            fixCommand: 'ruff format .',
+            checkCommand: 'ruff format --check .',
+            supportsFileArgs: true,
+        });
+    }
+    else if (hasPyproject && tomlHasSection(repoPath, 'pyproject.toml', '[tool.black]')) {
+        formatters.push({
+            name: 'black',
+            configPath: 'pyproject.toml',
+            fixCommand: 'black .',
+            checkCommand: 'black --check .',
+            supportsFileArgs: true,
+        });
+    }
+    else if (fs.existsSync(path.join(repoPath, 'ruff.toml'))) {
+        formatters.push({
+            name: 'ruff',
+            configPath: 'ruff.toml',
+            fixCommand: 'ruff format .',
+            checkCommand: 'ruff format --check .',
+            supportsFileArgs: true,
+        });
+    }
+    // 6. Go
+    if (fs.existsSync(path.join(repoPath, 'go.mod'))) {
+        formatters.push({
+            name: 'gofmt',
+            configPath: 'go.mod',
+            fixCommand: 'gofmt -w .',
+            checkCommand: 'gofmt -d .',
+            supportsFileArgs: true,
+        });
+    }
+    // 7. Clang-format
+    if (fs.existsSync(path.join(repoPath, '.clang-format'))) {
+        formatters.push({
+            name: 'clang-format',
+            configPath: '.clang-format',
+            fixCommand: 'clang-format -i',
+            checkCommand: 'clang-format --dry-run --Werror',
+            supportsFileArgs: true,
+        });
+    }
+    // 8. RuboCop
+    if (fs.existsSync(path.join(repoPath, '.rubocop.yml'))) {
+        formatters.push({
+            name: 'rubocop',
+            configPath: '.rubocop.yml',
+            fixCommand: 'rubocop -a',
+            checkCommand: 'rubocop',
+            supportsFileArgs: true,
+        });
+    }
+    // Extract package.json scripts
+    const packageJsonScripts = extractPackageJsonScripts(pkg);
+    debug(MODULE, `Detected ${formatters.length} formatters in ${repoPath}`);
+    return { formatters, packageJsonScripts, repoPath };
+}
+/**
+ * Diagnose whether CI log output indicates a formatting failure.
+ *
+ * Pattern-matches known formatter error strings. When repoPath is provided,
+ * cross-references with {@link detectFormatters} to provide a targeted fix command.
+ *
+ * @param logOutput - Raw CI log output to analyze
+ * @param repoPath - Optional repo path for cross-referencing with local formatter config
+ * @returns Diagnosis with matched formatter, fix command, and evidence strings
+ */
+export function diagnoseCIFormatterFailure(logOutput, repoPath) {
+    if (!logOutput.trim()) {
+        return { isFormattingFailure: false, evidence: [] };
+    }
+    const evidence = [];
+    let matchedFormatter;
+    for (const { formatter, patterns } of CI_PATTERNS) {
+        for (const pattern of patterns) {
+            const match = logOutput.match(pattern);
+            if (match) {
+                evidence.push(match[0]);
+                if (!matchedFormatter) {
+                    matchedFormatter = formatter;
+                }
+            }
+        }
+    }
+    if (!matchedFormatter) {
+        return { isFormattingFailure: false, evidence: [] };
+    }
+    // Cross-reference with local detection to get the fix command
+    let fixCommand;
+    if (repoPath) {
+        try {
+            const detected = detectFormatters(repoPath);
+            const localMatch = detected.formatters.find((f) => f.name === matchedFormatter);
+            if (localMatch) {
+                fixCommand = localMatch.fixCommand;
+            }
+        }
+        catch (err) {
+            debug(MODULE, `Cross-reference failed for ${repoPath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Fallback fix commands when CI-matched formatter wasn't found locally or no repoPath provided
+    if (!fixCommand) {
+        const fallbackCommands = {
+            prettier: 'npx prettier --write .',
+            eslint: 'npx eslint --fix .',
+            biome: 'npx @biomejs/biome check --write',
+            black: 'black .',
+            ruff: 'ruff format .',
+            rustfmt: 'cargo fmt',
+            gofmt: 'gofmt -w .',
+            'clang-format': 'clang-format -i',
+            rubocop: 'rubocop -a',
+        };
+        fixCommand = fallbackCommands[matchedFormatter];
+    }
+    return {
+        isFormattingFailure: true,
+        formatter: matchedFormatter,
+        fixCommand,
+        evidence,
+    };
+}
+/**
+ * Return the first (highest-priority) detected formatter, or undefined if none found.
+ *
+ * @param result - Detection result from {@link detectFormatters}
+ * @returns The highest-priority formatter, or undefined if none detected
+ */
+export function getPreferredFormatter(result) {
+    return result.formatters[0];
+}

package/dist/core/github.d.ts

@@ -11,14 +11,37 @@ export interface RateLimitInfo {
     /** ISO timestamp when the rate limit window resets. */
     resetAt: string;
 }
-/** Throttle callbacks used by the Octokit client. Exported for testability. */
+/**
+ * Throttle callbacks used by the Octokit client. Exported for testability.
+ * @returns Rate limit and secondary rate limit handler callbacks
+ */
 export declare function getRateLimitCallbacks(): {
     onRateLimit: (retryAfter: number, options: unknown, _octokit: unknown, retryCount: number) => boolean;
     onSecondaryRateLimit: (retryAfter: number, options: unknown, _octokit: unknown, retryCount: number) => boolean;
 };
+/**
+ * Get a shared, throttled Octokit instance for the given token.
+ * Returns a cached instance if the token matches, otherwise creates a new one.
+ *
+ * The client retries on primary rate limits (up to 2 retries) and
+ * secondary rate limits (1 retry).
+ *
+ * @param token - GitHub personal access token
+ * @returns Authenticated Octokit instance with rate limit throttling
+ *
+ * @example
+ * ```typescript
+ * import { getOctokit, requireGitHubToken } from '@oss-autopilot/core';
+ *
+ * const octokit = getOctokit(requireGitHubToken());
+ * const { data } = await octokit.repos.get({ owner: 'facebook', repo: 'react' });
+ * ```
+ */
 export declare function getOctokit(token: string): Octokit;
 /**
  * Check the GitHub Search API rate limit quota.
- * Returns the remaining requests, total limit, and reset time for the search endpoint.
+ *
+ * @param token - GitHub personal access token
+ * @returns Remaining requests, total limit, and reset time for the search endpoint
  */
 export declare function checkRateLimit(token: string): Promise<RateLimitInfo>;

package/dist/core/github.js

@@ -12,7 +12,10 @@ let _currentToken = null;
 function formatResetTime(date) {
     return date.toLocaleTimeString('en-US', { hour12: false });
 }
-/** Throttle callbacks used by the Octokit client. Exported for testability. */
+/**
+ * Throttle callbacks used by the Octokit client. Exported for testability.
+ * @returns Rate limit and secondary rate limit handler callbacks
+ */
 export function getRateLimitCallbacks() {
     return {
         onRateLimit: (retryAfter, options, _octokit, retryCount) => {
@@ -37,6 +40,24 @@ export function getRateLimitCallbacks() {
         },
     };
 }
+/**
+ * Get a shared, throttled Octokit instance for the given token.
+ * Returns a cached instance if the token matches, otherwise creates a new one.
+ *
+ * The client retries on primary rate limits (up to 2 retries) and
+ * secondary rate limits (1 retry).
+ *
+ * @param token - GitHub personal access token
+ * @returns Authenticated Octokit instance with rate limit throttling
+ *
+ * @example
+ * ```typescript
+ * import { getOctokit, requireGitHubToken } from '@oss-autopilot/core';
+ *
+ * const octokit = getOctokit(requireGitHubToken());
+ * const { data } = await octokit.repos.get({ owner: 'facebook', repo: 'react' });
+ * ```
+ */
 export function getOctokit(token) {
     // Return cached instance only if token matches
     if (_octokit && _currentToken === token)
@@ -51,7 +72,9 @@ export function getOctokit(token) {
 }
 /**
  * Check the GitHub Search API rate limit quota.
- * Returns the remaining requests, total limit, and reset time for the search endpoint.
+ *
+ * @param token - GitHub personal access token
+ * @returns Remaining requests, total limit, and reset time for the search endpoint
  */
 export async function checkRateLimit(token) {
     const octokit = getOctokit(token);

package/dist/core/index.d.ts

@@ -16,4 +16,5 @@ export { HttpCache, getHttpCache, cachedRequest, type CacheEntry } from './http-
 export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
 export { computeContributionStats, type ContributionStats, type ComputeStatsInput } from './stats.js';
 export { fetchPRTemplate, type PRTemplateResult } from './pr-template.js';
+export { detectFormatters, diagnoseCIFormatterFailure, getPreferredFormatter, type DetectedFormatter, type FormatterDetectionResult, type CIFormatterDiagnosis, type FormatterName, } from './formatter-detection.js';
 export * from './types.js';

package/dist/core/index.js

@@ -16,4 +16,5 @@ export { HttpCache, getHttpCache, cachedRequest } from './http-cache.js';
 export { CRITICAL_STATUSES, applyStatusOverrides, computeRepoSignals, groupPRsByRepo, assessCapacity, collectActionableIssues, computeActionMenu, toShelvedPRRef, formatActionHint, formatBriefSummary, formatSummary, printDigest, } from './daily-logic.js';
 export { computeContributionStats } from './stats.js';
 export { fetchPRTemplate } from './pr-template.js';
+export { detectFormatters, diagnoseCIFormatterFailure, getPreferredFormatter, } from './formatter-detection.js';
 export * from './types.js';

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

@@ -10,6 +10,18 @@
  * - search-phases.ts   — search helpers, caching, batched repo search
  */
 import { type IssueCandidate } from './types.js';
+/**
+ * Multi-phase issue discovery engine that searches GitHub for contributable issues.
+ *
+ * Search phases (in priority order):
+ * 1. Repos where user has merged PRs (highest merge probability)
+ * 2. Preferred organizations
+ * 3. Starred repos
+ * 4. General label-filtered search
+ * 5. Actively maintained repos
+ *
+ * Each candidate is vetted for claimability and scored 0-100 for viability.
+ */
 export declare class IssueDiscovery {
     private octokit;
     private stateManager;
@@ -17,21 +29,42 @@ export declare class IssueDiscovery {
     private vetter;
     /** Set after searchIssues() runs if rate limits affected the search (low pre-flight quota or mid-search rate limit hits). */
     rateLimitWarning: string | null;
+    /** @param githubToken - GitHub personal access token or token from `gh auth token` */
     constructor(githubToken: string);
     /**
      * Fetch the authenticated user's starred repositories from GitHub.
      * Updates the state manager with the list and timestamp.
+     * @returns Array of starred repo names in "owner/repo" format
      */
     fetchStarredRepos(): Promise<string[]>;
     /**
-     * Get starred repos, fetching from GitHub if cache is stale
+     * Get starred repos, fetching from GitHub if cache is stale.
+     * @returns Array of starred repo names in "owner/repo" format
      */
     getStarredReposWithRefresh(): Promise<string[]>;
     /**
      * Search for issues matching our criteria.
      * Searches in priority order: merged-PR repos first (no label filter), then starred repos,
-     * then general search, then actively maintained repos (#349).
+     * then general search, then actively maintained repos.
      * Filters out issues from low-scoring and excluded repos.
+     *
+     * @param options - Search configuration
+     * @param options.languages - Programming languages to filter by
+     * @param options.labels - Issue labels to search for
+     * @param options.maxResults - Maximum candidates to return (default: 10)
+     * @returns Scored and sorted issue candidates
+     * @throws {ValidationError} If no candidates found and no rate limits prevented the search
+     *
+     * @example
+     * ```typescript
+     * import { IssueDiscovery, requireGitHubToken } from '@oss-autopilot/core';
+     *
+     * const discovery = new IssueDiscovery(requireGitHubToken());
+     * const candidates = await discovery.searchIssues({ maxResults: 5 });
+     * for (const c of candidates) {
+     *   console.log(`${c.issue.repo}#${c.issue.number}: ${c.viabilityScore}/100`);
+     * }
+     * ```
      */
     searchIssues(options?: {
         languages?: string[];
@@ -39,16 +72,23 @@ export declare class IssueDiscovery {
         maxResults?: number;
     }): Promise<IssueCandidate[]>;
     /**
-     * Vet a specific issue (delegates to IssueVetter).
+     * Vet a specific issue for claimability and project health.
+     * @param issueUrl - Full GitHub issue URL
+     * @returns The vetted issue candidate with recommendation and scores
+     * @throws {ValidationError} If the URL is invalid or the issue cannot be fetched
      */
     vetIssue(issueUrl: string): Promise<IssueCandidate>;
     /**
-     * Save search results to ~/.oss-autopilot/found-issues.md
-     * Results are sorted by viability score (highest first)
+     * Save search results to ~/.oss-autopilot/found-issues.md.
+     * Results are sorted by viability score (highest first).
+     * @param candidates - Issue candidates to save
+     * @returns Absolute path to the written file
      */
     saveSearchResults(candidates: IssueCandidate[]): string;
     /**
-     * Format issue candidate for display
+     * Format issue candidate as a markdown display string.
+     * @param candidate - The issue candidate to format
+     * @returns Multi-line markdown string with vetting details
      */
     formatCandidate(candidate: IssueCandidate): string;
 }

package/dist/core/issue-discovery.js

@@ -22,6 +22,18 @@ import { IssueVetter } from './issue-vetting.js';
 import { getTopicsForCategories } from './category-mapping.js';
 import { buildLabelQuery, buildEffectiveLabels, interleaveArrays, cachedSearchIssues, filterVetAndScore, searchInRepos, } from './search-phases.js';
 const MODULE = 'issue-discovery';
+/**
+ * Multi-phase issue discovery engine that searches GitHub for contributable issues.
+ *
+ * Search phases (in priority order):
+ * 1. Repos where user has merged PRs (highest merge probability)
+ * 2. Preferred organizations
+ * 3. Starred repos
+ * 4. General label-filtered search
+ * 5. Actively maintained repos
+ *
+ * Each candidate is vetted for claimability and scored 0-100 for viability.
+ */
 export class IssueDiscovery {
     octokit;
     stateManager;
@@ -29,6 +41,7 @@ export class IssueDiscovery {
     vetter;
     /** Set after searchIssues() runs if rate limits affected the search (low pre-flight quota or mid-search rate limit hits). */
     rateLimitWarning = null;
+    /** @param githubToken - GitHub personal access token or token from `gh auth token` */
     constructor(githubToken) {
         this.githubToken = githubToken;
         this.octokit = getOctokit(githubToken);
@@ -38,6 +51,7 @@ export class IssueDiscovery {
     /**
      * Fetch the authenticated user's starred repositories from GitHub.
      * Updates the state manager with the list and timestamp.
+     * @returns Array of starred repo names in "owner/repo" format
      */
     async fetchStarredRepos() {
         info(MODULE, 'Fetching starred repositories...');
@@ -93,7 +107,8 @@ export class IssueDiscovery {
         }
     }
     /**
-     * Get starred repos, fetching from GitHub if cache is stale
+     * Get starred repos, fetching from GitHub if cache is stale.
+     * @returns Array of starred repo names in "owner/repo" format
      */
     async getStarredReposWithRefresh() {
         if (this.stateManager.isStarredReposStale()) {
@@ -104,8 +119,26 @@ export class IssueDiscovery {
     /**
      * Search for issues matching our criteria.
      * Searches in priority order: merged-PR repos first (no label filter), then starred repos,
-     * then general search, then actively maintained repos (#349).
+     * then general search, then actively maintained repos.
      * Filters out issues from low-scoring and excluded repos.
+     *
+     * @param options - Search configuration
+     * @param options.languages - Programming languages to filter by
+     * @param options.labels - Issue labels to search for
+     * @param options.maxResults - Maximum candidates to return (default: 10)
+     * @returns Scored and sorted issue candidates
+     * @throws {ValidationError} If no candidates found and no rate limits prevented the search
+     *
+     * @example
+     * ```typescript
+     * import { IssueDiscovery, requireGitHubToken } from '@oss-autopilot/core';
+     *
+     * const discovery = new IssueDiscovery(requireGitHubToken());
+     * const candidates = await discovery.searchIssues({ maxResults: 5 });
+     * for (const c of candidates) {
+     *   console.log(`${c.issue.repo}#${c.issue.number}: ${c.viabilityScore}/100`);
+     * }
+     * ```
      */
     async searchIssues(options = {}) {
         const config = this.stateManager.getState().config;
@@ -453,14 +486,19 @@ export class IssueDiscovery {
         return capped.slice(0, maxResults);
     }
     /**
-     * Vet a specific issue (delegates to IssueVetter).
+     * Vet a specific issue for claimability and project health.
+     * @param issueUrl - Full GitHub issue URL
+     * @returns The vetted issue candidate with recommendation and scores
+     * @throws {ValidationError} If the URL is invalid or the issue cannot be fetched
      */
     async vetIssue(issueUrl) {
         return this.vetter.vetIssue(issueUrl);
     }
     /**
-     * Save search results to ~/.oss-autopilot/found-issues.md
-     * Results are sorted by viability score (highest first)
+     * Save search results to ~/.oss-autopilot/found-issues.md.
+     * Results are sorted by viability score (highest first).
+     * @param candidates - Issue candidates to save
+     * @returns Absolute path to the written file
      */
     saveSearchResults(candidates) {
         // Sort by viability score descending
@@ -489,7 +527,9 @@ export class IssueDiscovery {
         return outputFile;
     }
     /**
-     * Format issue candidate for display
+     * Format issue candidate as a markdown display string.
+     * @param candidate - The issue candidate to format
+     * @returns Multi-line markdown string with vetting details
      */
     formatCandidate(candidate) {
         const { issue, vettingResult, projectHealth, recommendation, reasonsToApprove, reasonsToSkip } = candidate;