> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nodejs/userland-migrations/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Comprehensive API reference for Node.js Userland Migrations codemod utilities

The `@nodejs/codemod-utils` package provides a comprehensive set of utilities for building Node.js codemods with [ast-grep](https://ast-grep.github.io/). These utilities handle complex patterns for import/require analysis, binding resolution, code transformation, and package.json processing.

## Why Use These Utilities?

Building Node.js codemods requires handling complex patterns for:

* **Import/Require Analysis**: Finding and analyzing `import` statements and `require()` calls for specific modules
* **Binding Resolution**: Determining how imported functions are accessed locally (destructured, aliased, etc.)
* **Code Transformation**: Safely removing unused imports and modifying code while preserving formatting
* **Package.json Processing**: Analyzing and transforming `package.json` scripts that use Node.js

These utilities provide battle-tested solutions for common codemod operations, reducing boilerplate and ensuring consistent behavior across all migration recipes.

## API Categories

### Import and Require Detection

Utilities for finding and analyzing module dependencies:

* [getModuleDependencies](/api/import-require-detection#getmoduledependencies) - Find all import/require statements for a module
* [getNodeImportStatements](/api/import-require-detection#getnodeimportstatements) - Find ES module import statements
* [getNodeImportCalls](/api/import-require-detection#getnodeimportcalls) - Find dynamic import calls
* [getNodeRequireCalls](/api/import-require-detection#getnoderequirecalls) - Find CommonJS require calls

### Binding Resolution and Transformation

Utilities for resolving and manipulating import bindings:

* [resolveBindingPath](/api/binding-resolution#resolvebindingpath) - Resolve global API paths to local bindings
* [removeBinding](/api/binding-resolution#removebinding) - Remove specific bindings from imports
* [updateBinding](/api/binding-resolution#updatebinding) - Update or replace bindings

### AST-grep Helper Functions

Core utilities for working with AST nodes:

* [detectIndentUnit](/api/ast-grep-utilities#detectindentunit) - Detect indentation style
* [getLineIndent](/api/ast-grep-utilities#getlineindent) - Get indentation for a specific line
* [getShebang](/api/ast-grep-utilities#getshebang) - Find Node.js shebang lines
* [getScope](/api/ast-grep-utilities#getscope) - Find enclosing scope for a node
* [removeLines](/api/ast-grep-utilities#removelines) - Safely remove line ranges
* [getDefaultImportIdentifier](/api/ast-grep-utilities#getdefaultimportidentifier) - Get default import identifier
* [getRequireNamespaceIdentifier](/api/ast-grep-utilities#getrequirenamespaceidentifier) - Get namespace require identifier
* [replaceNodeJsArgs (shebang)](/api/ast-grep-utilities#replacenodejsargs-shebang) - Replace Node.js args in shebangs

### Package.json Utilities

Utilities for processing package.json files:

* [removeDependencies](/api/package-json-utilities#removedependencies) - Remove dependencies from package.json
* [getScriptsNode](/api/package-json-utilities#getscriptsnode) - Find the scripts section
* [getNodeJsUsage](/api/package-json-utilities#getnodejsusage) - Find Node.js usage in scripts
* [replaceNodeJsArgs](/api/package-json-utilities#replacenodejsargs) - Replace Node.js arguments in scripts
* [removeNodeJsArgs](/api/package-json-utilities#removenodejsargs) - Remove Node.js arguments from scripts

## Type Definitions

All utilities use types from `@codemod.com/jssg-types`:

* `SgRoot<Js>` - Root AST node for JavaScript/TypeScript
* `SgNode<Js>` - Individual AST node
* `Edit` - Represents a code edit operation
* `Range` - Represents a position range in source code

## Getting Started

Import utilities directly from their respective modules:

```typescript theme={null}
import { getModuleDependencies } from '@nodejs/codemod-utils/ast-grep/module-dependencies';
import { resolveBindingPath } from '@nodejs/codemod-utils/ast-grep/resolve-binding-path';
import removeDependencies from '@nodejs/codemod-utils/remove-dependencies';
```

## Common Patterns

### Finding Module Dependencies

```typescript theme={null}
const ast = context.getAST();
const fsImports = getModuleDependencies(ast, 'fs');
// Finds: import fs from 'fs'; import { readFile } from 'node:fs';
// Finds: const fs = require('fs')
// Finds: const fs = await import('fs')
```

### Resolving Bindings

```typescript theme={null}
// Given: const { types } = require('node:util');
const path = resolveBindingPath(node, '$.types.isNativeError');
// Returns: 'types.isNativeError'

// Given: const util = require('node:util');
const path = resolveBindingPath(node, '$.types.isNativeError');
// Returns: 'util.types.isNativeError'
```

### Removing Bindings

```typescript theme={null}
// Given: const { types, isNativeError } = require('node:util');
const result = removeBinding(node, 'isNativeError');
// Edit to: const { types } = require('node:util');

// Given: const { isNativeError } = require('node:util');
const result = removeBinding(node, 'isNativeError');
// Returns: lineToRemove range to remove entire statement
```