staged.ts

/**
 * @fileoverview "Ready for the next commit" helpers — `git diff --cached`
 * over only the index. Excludes unstaged tracked-file edits and untracked
 * paths; use `changed.ts` if you need the broader view.
 */

import { normalizePath } from '../paths/normalize'
import { ArrayPrototypeIncludes } from '../primordials/array'
import { getGitDiffSpawnArgs, innerDiff, innerDiffSync } from './_internal'
import { getCachedRealpath, getCwd, getPath } from './repo'

import type { GitDiffOptions } from './types'

/**
 * Get staged files ready for commit (changes added with `git add`).
 *
 * Uses `git diff --cached --name-only` which returns only staged changes.
 * Does NOT include:
 * - Unstaged modifications (changes not added with `git add`)
 * - Untracked files (new files not added to git)
 *
 * This is a focused check for what will be included in the next commit.
 * Useful for validating changes before committing or running pre-commit hooks.
 *
 * @param options - Options controlling path format and filtering.
 * @returns Promise resolving to array of staged file paths.
 *
 * @example
 * ```typescript
 * // Get currently staged files
 * const files = await getStagedFiles()
 * // => ['src/foo.ts']
 *
 * // Stage more files
 * await spawn('git', ['add', 'src/bar.ts'])
 * const files = await getStagedFiles()
 * // => ['src/foo.ts', 'src/bar.ts']
 *
 * // Get absolute paths
 * const files = await getStagedFiles({ absolute: true })
 * // => ['/path/to/repo/src/foo.ts', ...]
 * ```
 */
export async function getStagedFiles(
  options?: GitDiffOptions | undefined,
): Promise<string[]> {
  const args = getGitDiffSpawnArgs(options?.cwd).staged
  return await innerDiff(args, options)
}

/**
 * Get staged files ready for commit (changes added with `git add`).
 *
 * Synchronous version of `getStagedFiles()`. Uses `git diff --cached --name-only`
 * which returns only staged changes. Does NOT include:
 * - Unstaged modifications (changes not added with `git add`)
 * - Untracked files (new files not added to git)
 *
 * This is a focused check for what will be included in the next commit.
 * Useful for validating changes before committing or running pre-commit hooks.
 *
 * @param options - Options controlling path format and filtering.
 * @returns Array of staged file paths.
 *
 * @example
 * ```typescript
 * // Get currently staged files
 * const files = getStagedFilesSync()
 * // => ['src/foo.ts']
 *
 * // Stage more files
 * spawnSync('git', ['add', 'src/bar.ts'])
 * const files = getStagedFilesSync()
 * // => ['src/foo.ts', 'src/bar.ts']
 *
 * // Get absolute paths
 * const files = getStagedFilesSync({ absolute: true })
 * // => ['/path/to/repo/src/foo.ts', ...]
 * ```
 */
export function getStagedFilesSync(
  options?: GitDiffOptions | undefined,
): string[] {
  const args = getGitDiffSpawnArgs(options?.cwd).staged
  return innerDiffSync(args, options)
}

/**
 * Check if a file or directory is staged for commit.
 *
 * Checks if the given pathname has changes staged with `git add` that will
 * be included in the next commit. Does NOT include:
 * - Unstaged modifications (changes not added with `git add`)
 * - Untracked files (new files not in git)
 *
 * For directories, returns `true` if ANY file within the directory is staged.
 *
 * Symlinks in the pathname and cwd are automatically resolved using
 * `fs.realpathSync()` before comparison.
 *
 * @param pathname - File or directory path to check.
 * @param options - Options for the git diff check.
 * @returns Promise resolving to `true` if path is staged, `false` otherwise.
 *
 * @example
 * ```typescript
 * // Check if file is staged
 * const staged = await isStaged('src/foo.ts')
 * // => false
 *
 * // Stage the file
 * await spawn('git', ['add', 'src/foo.ts'])
 * const staged = await isStaged('src/foo.ts')
 * // => true
 *
 * // Check directory
 * const staged = await isStaged('src/')
 * // => true (if any file in src/ is staged)
 * ```
 */
export async function isStaged(
  pathname: string,
  options?: GitDiffOptions | undefined,
): Promise<boolean> {
  const files = await getStagedFiles({
    __proto__: null,
    ...options,
    absolute: false,
  })
  const path = getPath()
  // Resolve pathname to handle symlinks before computing relative path (using cache).
  const resolvedPathname = getCachedRealpath(pathname)
  // options.cwd-passed arm exercised when caller specifies cwd; default getCwd().
  /* c8 ignore start */
  const baseCwd = options?.cwd ? getCachedRealpath(options['cwd']) : getCwd()
  /* c8 ignore stop */
  const relativePath = normalizePath(path.relative(baseCwd, resolvedPathname))
  return ArrayPrototypeIncludes(files, relativePath)
}

/**
 * Check if a file or directory is staged for commit.
 *
 * Synchronous version of `isStaged()`. Checks if the given pathname has
 * changes staged with `git add` that will be included in the next commit.
 * Does NOT include:
 * - Unstaged modifications (changes not added with `git add`)
 * - Untracked files (new files not in git)
 *
 * For directories, returns `true` if ANY file within the directory is staged.
 *
 * Symlinks in the pathname and cwd are automatically resolved using
 * `fs.realpathSync()` before comparison.
 *
 * @param pathname - File or directory path to check.
 * @param options - Options for the git diff check.
 * @returns `true` if path is staged, `false` otherwise.
 *
 * @example
 * ```typescript
 * // Check if file is staged
 * const staged = isStagedSync('src/foo.ts')
 * // => false
 *
 * // Stage the file
 * spawnSync('git', ['add', 'src/foo.ts'])
 * const staged = isStagedSync('src/foo.ts')
 * // => true
 *
 * // Check directory
 * const staged = isStagedSync('src/')
 * // => true (if any file in src/ is staged)
 * ```
 */
export function isStagedSync(
  pathname: string,
  options?: GitDiffOptions | undefined,
): boolean {
  const files = getStagedFilesSync({
    __proto__: null,
    ...options,
    absolute: false,
  })
  const path = getPath()
  // Resolve pathname to handle symlinks before computing relative path (using cache).
  const resolvedPathname = getCachedRealpath(pathname)
  // options.cwd-passed arm exercised when caller specifies cwd; default getCwd().
  /* c8 ignore start */
  const baseCwd = options?.cwd ? getCachedRealpath(options['cwd']) : getCwd()
  /* c8 ignore stop */
  const relativePath = normalizePath(path.relative(baseCwd, resolvedPathname))
  return ArrayPrototypeIncludes(files, relativePath)
}