@socketsecurity/lib 5.18.1 → 5.19.0

package/dist/git.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Git helpers built on top of `spawn`.
+ * Provides utilities for querying repository state - changed/staged files,
+ * diffs, and related metadata - with path normalization, glob filtering,
+ * lazy fs/path loading, and debug instrumentation.
+ */
 /**
  * Options for git diff operations.
  *
@@ -17,6 +23,44 @@
  * const files = await getChangedFiles({ cwd: '/path/to/repo/src' })
  * ```
  */
+/**
+ * Options for filtering packages by git changes.
+ *
+ * Used to determine which packages in a monorepo have changed files.
+ *
+ * @example
+ * ```typescript
+ * // Filter packages with changes
+ * const changed = filterPackagesByChanges(packages)
+ *
+ * // Force include all packages
+ * const all = filterPackagesByChanges(packages, { force: true })
+ *
+ * // Use custom package key
+ * const changed = filterPackagesByChanges(
+ *   packages,
+ *   { packageKey: 'directory' }
+ * )
+ * ```
+ */
+export interface FilterPackagesByChangesOptions {
+    /**
+     * Force include all packages regardless of changes.
+     *
+     * @default false
+     */
+    force?: boolean | undefined;
+    /**
+     * Key to access package path in package objects.
+     *
+     * @default 'path'
+     */
+    packageKey?: string | undefined;
+    /**
+     * Additional options for filtering.
+     */
+    [key: string]: unknown;
+}
 export interface GitDiffOptions {
     /**
      * Return absolute file paths instead of relative paths.
@@ -65,44 +109,6 @@ export interface GitDiffOptions {
      */
     [key: string]: unknown;
 }
-/**
- * Options for filtering packages by git changes.
- *
- * Used to determine which packages in a monorepo have changed files.
- *
- * @example
- * ```typescript
- * // Filter packages with changes
- * const changed = filterPackagesByChanges(packages)
- *
- * // Force include all packages
- * const all = filterPackagesByChanges(packages, { force: true })
- *
- * // Use custom package key
- * const changed = filterPackagesByChanges(
- *   packages,
- *   { packageKey: 'directory' }
- * )
- * ```
- */
-export interface FilterPackagesByChangesOptions {
-    /**
-     * Force include all packages regardless of changes.
-     *
-     * @default false
-     */
-    force?: boolean | undefined;
-    /**
-     * Key to access package path in package objects.
-     *
-     * @default 'path'
-     */
-    packageKey?: string | undefined;
-    /**
-     * Additional options for filtering.
-     */
-    [key: string]: unknown;
-}
 /**
  * Find git repository root by walking up from the given directory.
  *
@@ -203,68 +209,6 @@ export declare function getChangedFiles(options?: GitDiffOptions | undefined): P
  * ```
  */
 export declare function getChangedFilesSync(options?: GitDiffOptions | undefined): string[];
-/**
- * Get unstaged modified files (changes not yet staged for commit).
- *
- * Uses `git diff --name-only` which returns only unstaged modifications
- * to tracked files. Does NOT include:
- * - Untracked files (new files not added to git)
- * - Staged changes (files added with `git add`)
- *
- * This is a focused check for uncommitted changes to existing tracked files.
- * Useful for detecting work-in-progress modifications before staging.
- *
- * @param options - Options controlling path format and filtering.
- * @returns Promise resolving to array of unstaged file paths.
- *
- * @example
- * ```typescript
- * // Get unstaged files
- * const files = await getUnstagedFiles()
- * // => ['src/foo.ts', 'src/bar.ts']
- *
- * // After staging some files
- * await spawn('git', ['add', 'src/foo.ts'])
- * const files = await getUnstagedFiles()
- * // => ['src/bar.ts'] (foo.ts no longer included)
- *
- * // Get absolute paths
- * const files = await getUnstagedFiles({ absolute: true })
- * // => ['/path/to/repo/src/bar.ts']
- * ```
- */
-export declare function getUnstagedFiles(options?: GitDiffOptions | undefined): Promise<string[]>;
-/**
- * Get unstaged modified files (changes not yet staged for commit).
- *
- * Synchronous version of `getUnstagedFiles()`. Uses `git diff --name-only`
- * which returns only unstaged modifications to tracked files. Does NOT include:
- * - Untracked files (new files not added to git)
- * - Staged changes (files added with `git add`)
- *
- * This is a focused check for uncommitted changes to existing tracked files.
- * Useful for detecting work-in-progress modifications before staging.
- *
- * @param options - Options controlling path format and filtering.
- * @returns Array of unstaged file paths.
- *
- * @example
- * ```typescript
- * // Get unstaged files
- * const files = getUnstagedFilesSync()
- * // => ['src/foo.ts', 'src/bar.ts']
- *
- * // After staging some files
- * spawnSync('git', ['add', 'src/foo.ts'])
- * const files = getUnstagedFilesSync()
- * // => ['src/bar.ts'] (foo.ts no longer included)
- *
- * // Get absolute paths
- * const files = getUnstagedFilesSync({ absolute: true })
- * // => ['/path/to/repo/src/bar.ts']
- * ```
- */
-export declare function getUnstagedFilesSync(options?: GitDiffOptions | undefined): string[];
 /**
  * Get staged files ready for commit (changes added with `git add`).
  *
@@ -327,6 +271,68 @@ export declare function getStagedFiles(options?: GitDiffOptions | undefined): Pr
  * ```
  */
 export declare function getStagedFilesSync(options?: GitDiffOptions | undefined): string[];
+/**
+ * Get unstaged modified files (changes not yet staged for commit).
+ *
+ * Uses `git diff --name-only` which returns only unstaged modifications
+ * to tracked files. Does NOT include:
+ * - Untracked files (new files not added to git)
+ * - Staged changes (files added with `git add`)
+ *
+ * This is a focused check for uncommitted changes to existing tracked files.
+ * Useful for detecting work-in-progress modifications before staging.
+ *
+ * @param options - Options controlling path format and filtering.
+ * @returns Promise resolving to array of unstaged file paths.
+ *
+ * @example
+ * ```typescript
+ * // Get unstaged files
+ * const files = await getUnstagedFiles()
+ * // => ['src/foo.ts', 'src/bar.ts']
+ *
+ * // After staging some files
+ * await spawn('git', ['add', 'src/foo.ts'])
+ * const files = await getUnstagedFiles()
+ * // => ['src/bar.ts'] (foo.ts no longer included)
+ *
+ * // Get absolute paths
+ * const files = await getUnstagedFiles({ absolute: true })
+ * // => ['/path/to/repo/src/bar.ts']
+ * ```
+ */
+export declare function getUnstagedFiles(options?: GitDiffOptions | undefined): Promise<string[]>;
+/**
+ * Get unstaged modified files (changes not yet staged for commit).
+ *
+ * Synchronous version of `getUnstagedFiles()`. Uses `git diff --name-only`
+ * which returns only unstaged modifications to tracked files. Does NOT include:
+ * - Untracked files (new files not added to git)
+ * - Staged changes (files added with `git add`)
+ *
+ * This is a focused check for uncommitted changes to existing tracked files.
+ * Useful for detecting work-in-progress modifications before staging.
+ *
+ * @param options - Options controlling path format and filtering.
+ * @returns Array of unstaged file paths.
+ *
+ * @example
+ * ```typescript
+ * // Get unstaged files
+ * const files = getUnstagedFilesSync()
+ * // => ['src/foo.ts', 'src/bar.ts']
+ *
+ * // After staging some files
+ * spawnSync('git', ['add', 'src/foo.ts'])
+ * const files = getUnstagedFilesSync()
+ * // => ['src/bar.ts'] (foo.ts no longer included)
+ *
+ * // Get absolute paths
+ * const files = getUnstagedFilesSync({ absolute: true })
+ * // => ['/path/to/repo/src/bar.ts']
+ * ```
+ */
+export declare function getUnstagedFilesSync(options?: GitDiffOptions | undefined): string[];
 /**
  * Check if a file or directory has any git changes.
  *
@@ -399,142 +405,142 @@ export declare function isChanged(pathname: string, options?: GitDiffOptions | u
  */
 export declare function isChangedSync(pathname: string, options?: GitDiffOptions | undefined): boolean;
 /**
- * Check if a file or directory has unstaged changes.
+ * Check if a file or directory is staged for commit.
  *
- * Checks if the given pathname has modifications that are not yet staged
- * for commit (changes not added with `git add`). Does NOT include:
- * - Staged changes (already added with `git add`)
+ * 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 has
- * unstaged changes.
+ * 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 has unstaged changes, `false` otherwise.
+ * @returns Promise resolving to `true` if path is staged, `false` otherwise.
  *
  * @example
  * ```typescript
- * // Check if file has unstaged changes
- * const unstaged = await isUnstaged('src/foo.ts')
- * // => true
+ * // Check if file is staged
+ * const staged = await isStaged('src/foo.ts')
+ * // => false
  *
- * // After staging the file
+ * // Stage the file
  * await spawn('git', ['add', 'src/foo.ts'])
- * const unstaged = await isUnstaged('src/foo.ts')
- * // => false
+ * const staged = await isStaged('src/foo.ts')
+ * // => true
  *
  * // Check directory
- * const unstaged = await isUnstaged('src/')
- * // => true (if any file in src/ has unstaged changes)
+ * const staged = await isStaged('src/')
+ * // => true (if any file in src/ is staged)
  * ```
  */
-export declare function isUnstaged(pathname: string, options?: GitDiffOptions | undefined): Promise<boolean>;
+export declare function isStaged(pathname: string, options?: GitDiffOptions | undefined): Promise<boolean>;
 /**
- * Check if a file or directory has unstaged changes.
+ * Check if a file or directory is staged for commit.
  *
- * Synchronous version of `isUnstaged()`. Checks if the given pathname has
- * modifications that are not yet staged for commit (changes not added with
- * `git add`). Does NOT include:
- * - Staged changes (already added with `git add`)
+ * 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 has
- * unstaged changes.
+ * 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 has unstaged changes, `false` otherwise.
+ * @returns `true` if path is staged, `false` otherwise.
  *
  * @example
  * ```typescript
- * // Check if file has unstaged changes
- * const unstaged = isUnstagedSync('src/foo.ts')
- * // => true
+ * // Check if file is staged
+ * const staged = isStagedSync('src/foo.ts')
+ * // => false
  *
- * // After staging the file
+ * // Stage the file
  * spawnSync('git', ['add', 'src/foo.ts'])
- * const unstaged = isUnstagedSync('src/foo.ts')
- * // => false
+ * const staged = isStagedSync('src/foo.ts')
+ * // => true
  *
  * // Check directory
- * const unstaged = isUnstagedSync('src/')
- * // => true (if any file in src/ has unstaged changes)
+ * const staged = isStagedSync('src/')
+ * // => true (if any file in src/ is staged)
  * ```
  */
-export declare function isUnstagedSync(pathname: string, options?: GitDiffOptions | undefined): boolean;
+export declare function isStagedSync(pathname: string, options?: GitDiffOptions | undefined): boolean;
 /**
- * Check if a file or directory is staged for commit.
+ * Check if a file or directory has unstaged changes.
  *
- * 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`)
+ * Checks if the given pathname has modifications that are not yet staged
+ * for commit (changes not added with `git add`). Does NOT include:
+ * - Staged changes (already added with `git add`)
  * - Untracked files (new files not in git)
  *
- * For directories, returns `true` if ANY file within the directory is staged.
+ * For directories, returns `true` if ANY file within the directory has
+ * unstaged changes.
  *
  * 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.
+ * @returns Promise resolving to `true` if path has unstaged changes, `false` otherwise.
  *
  * @example
  * ```typescript
- * // Check if file is staged
- * const staged = await isStaged('src/foo.ts')
- * // => false
+ * // Check if file has unstaged changes
+ * const unstaged = await isUnstaged('src/foo.ts')
+ * // => true
  *
- * // Stage the file
+ * // After staging the file
  * await spawn('git', ['add', 'src/foo.ts'])
- * const staged = await isStaged('src/foo.ts')
- * // => true
+ * const unstaged = await isUnstaged('src/foo.ts')
+ * // => false
  *
  * // Check directory
- * const staged = await isStaged('src/')
- * // => true (if any file in src/ is staged)
+ * const unstaged = await isUnstaged('src/')
+ * // => true (if any file in src/ has unstaged changes)
  * ```
  */
-export declare function isStaged(pathname: string, options?: GitDiffOptions | undefined): Promise<boolean>;
+export declare function isUnstaged(pathname: string, options?: GitDiffOptions | undefined): Promise<boolean>;
 /**
- * Check if a file or directory is staged for commit.
+ * Check if a file or directory has unstaged changes.
  *
- * 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`)
+ * Synchronous version of `isUnstaged()`. Checks if the given pathname has
+ * modifications that are not yet staged for commit (changes not added with
+ * `git add`). Does NOT include:
+ * - Staged changes (already added with `git add`)
  * - Untracked files (new files not in git)
  *
- * For directories, returns `true` if ANY file within the directory is staged.
+ * For directories, returns `true` if ANY file within the directory has
+ * unstaged changes.
  *
  * 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.
+ * @returns `true` if path has unstaged changes, `false` otherwise.
  *
  * @example
  * ```typescript
- * // Check if file is staged
- * const staged = isStagedSync('src/foo.ts')
- * // => false
+ * // Check if file has unstaged changes
+ * const unstaged = isUnstagedSync('src/foo.ts')
+ * // => true
  *
- * // Stage the file
+ * // After staging the file
  * spawnSync('git', ['add', 'src/foo.ts'])
- * const staged = isStagedSync('src/foo.ts')
- * // => true
+ * const unstaged = isUnstagedSync('src/foo.ts')
+ * // => false
  *
  * // Check directory
- * const staged = isStagedSync('src/')
- * // => true (if any file in src/ is staged)
+ * const unstaged = isUnstagedSync('src/')
+ * // => true (if any file in src/ has unstaged changes)
  * ```
  */
-export declare function isStagedSync(pathname: string, options?: GitDiffOptions | undefined): boolean;
+export declare function isUnstagedSync(pathname: string, options?: GitDiffOptions | undefined): boolean;