@oss-autopilot/core 1.17.4 → 2.0.0

package/dist/core/utils.d.ts

@@ -1,303 +0,0 @@
-/**
- * Shared utility functions
- */
-/** Default concurrency limit for parallel GitHub API requests. */
-export declare const DEFAULT_CONCURRENCY = 5;
-/** Async sleep — exported for mockability in tests. */
-export declare function sleep(ms: number): Promise<void>;
-/**
- * Returns the oss-autopilot data directory path, creating it if it does not exist.
- *
- * The directory is located at `~/.oss-autopilot/` and serves as the root for
- * all persisted user data (state, backups, cache).
- *
- * @returns Absolute path to the data directory (e.g., `/Users/you/.oss-autopilot`)
- *
- * @example
- * const dir = getDataDir();
- * // "/Users/you/.oss-autopilot"
- */
-export declare function getDataDir(): string;
-/**
- * Returns the path to the state file (`~/.oss-autopilot/state.json`).
- *
- * Implicitly creates the data directory via {@link getDataDir} if it does not exist.
- *
- * @returns Absolute path to `state.json`
- *
- * @example
- * const statePath = getStatePath();
- * // "/Users/you/.oss-autopilot/state.json"
- */
-export declare function getStatePath(): string;
-/**
- * Returns the backup directory path, creating it if it does not exist.
- *
- * Located at `~/.oss-autopilot/backups/`. Used for automatic state backups
- * before each write operation.
- *
- * @returns Absolute path to the backups directory
- *
- * @example
- * const backupDir = getBackupDir();
- * // "/Users/you/.oss-autopilot/backups"
- */
-export declare function getBackupDir(): string;
-/**
- * Returns the HTTP cache directory path, creating it if it does not exist.
- *
- * Located at `~/.oss-autopilot/cache/`. Used by {@link HttpCache} to store
- * ETag-based response caches for GitHub API endpoints.
- *
- * @returns Absolute path to the cache directory
- *
- * @example
- * const cacheDir = getCacheDir();
- * // "/Users/you/.oss-autopilot/cache"
- */
-export declare function getCacheDir(): string;
-/**
- * Returns the path to the local Gist ID file (`~/.oss-autopilot/gist-id`).
- *
- * This file stores the GitHub Gist ID used by the Gist-based persistence layer,
- * avoiding a search-by-description API call on every session.
- *
- * Implicitly creates the data directory via {@link getDataDir} if it does not exist.
- *
- * @returns Absolute path to `gist-id`
- *
- * @example
- * const gistIdPath = getGistIdPath();
- * // "/Users/you/.oss-autopilot/gist-id"
- */
-export declare function getGistIdPath(): string;
-/**
- * Returns the path to the local state cache file (`~/.oss-autopilot/state-cache.json`).
- *
- * This file is a write-through cache of the Gist-hosted state, used as a fallback
- * when the GitHub API is unreachable (degraded mode).
- *
- * Implicitly creates the data directory via {@link getDataDir} if it does not exist.
- *
- * @returns Absolute path to `state-cache.json`
- *
- * @example
- * const cachePath = getStateCachePath();
- * // "/Users/you/.oss-autopilot/state-cache.json"
- */
-export declare function getStateCachePath(): string;
-/**
- * Represents a parsed GitHub pull request or issue URL.
- *
- * @property owner - The repository owner (e.g., `"facebook"`)
- * @property repo - The repository name (e.g., `"react"`)
- * @property number - The PR or issue number
- * @property type - Whether the URL points to a pull request or an issue
- */
-interface ParsedGitHubUrl {
-    owner: string;
-    repo: string;
-    number: number;
-    type: 'pull' | 'issues';
-}
-/**
- * Parses a GitHub pull request or issue URL into its components.
- *
- * Only accepts HTTPS GitHub URLs (`https://github.com/...`). Returns `null` for
- * invalid URLs, non-GitHub URLs, or URLs with invalid owner/repo characters.
- *
- * @param url - Full GitHub URL (e.g., `"https://github.com/owner/repo/pull/42"`)
- * @returns Parsed URL components, or `null` if the URL is invalid or not a recognized GitHub PR/issue URL
- *
- * @example
- * parseGitHubUrl('https://github.com/facebook/react/pull/123')
- * // { owner: "facebook", repo: "react", number: 123, type: "pull" }
- *
- * @example
- * parseGitHubUrl('https://github.com/vercel/next.js/issues/456')
- * // { owner: "vercel", repo: "next.js", number: 456, type: "issues" }
- *
- * @example
- * parseGitHubUrl('https://example.com/not-github')
- * // null
- */
-export declare function parseGitHubUrl(url: string): ParsedGitHubUrl | null;
-/**
- * Extracts the owner and repo from a GitHub web URL
- * (e.g. `https://github.com/owner/repo/pull/42`, `https://github.com/owner/repo/`).
- *
- * Unlike {@link parseGitHubUrl}, this does **not** require a PR or issue number in the URL.
- * Like `parseGitHubUrl`, it enforces an `https://github.com/` prefix.
- *
- * @param url - An HTTPS GitHub URL containing at least `github.com/owner/repo`
- * @returns `{ owner, repo }` or `null` if the URL cannot be parsed or contains invalid owner/repo characters
- *
- * @example
- * extractOwnerRepo('https://github.com/facebook/react/pull/123')
- * // { owner: "facebook", repo: "react" }
- *
- * @example
- * extractOwnerRepo('https://github.com/vercel/next.js/')
- * // { owner: "vercel", repo: "next.js" }
- */
-export declare function extractOwnerRepo(url: string): {
-    owner: string;
-    repo: string;
-} | null;
-/**
- * Calculates the number of whole days between two dates, clamped to zero.
- *
- * Returns `0` if `from` is after `to` — reversed ranges and clock-skew do not
- * produce negative values. Partial days are truncated (e.g., 1.9 days -> 1).
- *
- * @param from - The start date
- * @param to - The end date (defaults to the current date/time)
- * @returns Number of whole days between the two dates, minimum `0`
- *
- * @example
- * daysBetween(new Date('2024-01-01'), new Date('2024-01-10'))
- * // 9
- *
- * @example
- * daysBetween(new Date('2024-01-10'), new Date('2024-01-01'))
- * // 0 (clamped; reversed ranges are not signed)
- */
-export declare function daysBetween(from: Date, to?: Date): number;
-/**
- * Splits an `"owner/repo"` string into its owner and repo components.
- *
- * @param repoFullName - Full repository name in `"owner/repo"` format
- * @returns Object with `owner` and `repo` string properties
- * @throws {Error} If the input does not contain both an owner and repo separated by `/`
- *
- * @example
- * splitRepo('facebook/react')
- * // { owner: "facebook", repo: "react" }
- */
-export declare function splitRepo(repoFullName: string): {
-    owner: string;
-    repo: string;
-};
-/**
- * Case-insensitive check whether a repo owner matches the given GitHub username.
- * Used to skip a user's own repos (PRs to your own repos aren't OSS contributions).
- */
-export declare function isOwnRepo(owner: string, username: string): boolean;
-/**
- * Read the CLI package version from package.json relative to the running CLI bundle.
- * Resolves `../package.json` from `process.argv[1]` (the bundle entry point).
- * Falls back to '0.0.0' if the file is unreadable.
- */
-export declare function getCLIVersion(): string;
-/**
- * Formats a timestamp as a human-readable relative time string.
- *
- * Returns minutes for < 1 hour, hours for < 1 day, days for < 30 days,
- * and a locale-formatted date string for anything older.
- *
- * @param dateStr - ISO 8601 date string
- * @returns Relative time like `"5m ago"`, `"3h ago"`, `"12d ago"`, or a formatted date
- *
- * @example
- * formatRelativeTime('2024-01-20T10:00:00Z')
- * // "5d ago" (if called on Jan 25)
- *
- * @example
- * formatRelativeTime(new Date(Date.now() - 120000).toISOString())
- * // "2m ago"
- */
-export declare function formatRelativeTime(dateStr: string): string;
-/**
- * Creates a descending date comparator function for use with `Array.prototype.sort()`.
- *
- * Items with `null` or `undefined` dates are treated as epoch (sorted last).
- *
- * @param getDate - Accessor function that extracts a date value from each item
- * @returns A comparator function that sorts items from newest to oldest
- *
- * @example
- * const prs = [{ createdAt: '2024-01-01' }, { createdAt: '2024-06-15' }];
- * prs.sort(byDateDescending(pr => pr.createdAt));
- * // [{ createdAt: '2024-06-15' }, { createdAt: '2024-01-01' }]
- */
-export declare function byDateDescending<T>(getDate: (item: T) => string | number | null | undefined): (a: T, b: T) => number;
-/**
- * Retrieves a GitHub authentication token, checking sources in priority order.
- *
- * Checks `GITHUB_TOKEN` environment variable first, then falls back to `gh auth token`
- * from the GitHub CLI. The result is cached after the first successful lookup (or first
- * failed attempt), so subsequent calls are instant and do not spawn subprocesses.
- *
- * @returns The GitHub token string, or `null` if no token is available
- *
- * @example
- * const token = getGitHubToken();
- * if (token) {
- *   // use token for API calls
- * }
- */
-export declare function getGitHubToken(): string | null;
-/**
- * Returns a GitHub token or throws an error with setup instructions.
- *
- * Delegates to {@link getGitHubToken} and throws if no token is found. Use this
- * in commands that cannot proceed without authentication.
- *
- * @returns The GitHub token string (guaranteed non-null)
- * @throws {ConfigurationError} If no token is available, with instructions for `gh auth login` or setting `GITHUB_TOKEN`
- *
- * @example
- * const token = requireGitHubToken(); // throws if not authenticated
- */
-export declare function requireGitHubToken(): string;
-/**
- * Resets the cached GitHub token and fetch-attempted flag.
- *
- * Intended for use in tests to ensure a clean state between test cases.
- * After calling this, the next call to {@link getGitHubToken} will re-fetch the token.
- *
- * @example
- * afterEach(() => {
- *   resetGitHubTokenCache();
- * });
- */
-export declare function resetGitHubTokenCache(): void;
-/**
- * Asynchronous version of {@link getGitHubToken}.
- *
- * Uses `execFile` (non-blocking) instead of `execFileSync` to avoid blocking
- * the event loop during CLI cold start. Shares the same cache as the synchronous
- * version, so a successful async fetch makes subsequent sync calls instant.
- *
- * @returns The GitHub token string, or `null` if no token is available
- *
- * @example
- * const token = await getGitHubTokenAsync();
- * if (token) {
- *   // use token for API calls
- * }
- */
-export declare function getGitHubTokenAsync(): Promise<string | null>;
-/**
- * Check whether the state file exists without creating the data directory.
- * Used for first-run detection in the CLI — we don't want to create
- * `~/.oss-autopilot/` just to check if the user has ever run the tool.
- */
-export declare function stateFileExists(): boolean;
-/**
- * Detect the authenticated GitHub username via the `gh` CLI.
- *
- * Runs `gh api user --jq '.login'` asynchronously and validates the result
- * against GitHub's username rules. Never throws — returns `null` on any failure
- * (gh not installed, not authenticated, invalid output, etc.).
- *
- * @returns The GitHub username string, or `null` if detection fails
- *
- * @example
- * const username = await detectGitHubUsername();
- * if (username) {
- *   console.log(`Logged in as ${username}`);
- * }
- */
-export declare function detectGitHubUsername(): Promise<string | null>;
-export {};