doc: clarify example (#221)

Author: AugustinMauroy

CONTRIBUTING.md

@@ -39,6 +39,9 @@ Each codemod resides in its own directory under `recipes/` and should include:
 
 **`src/workflow.ts` example:**
 ```ts
+import { getNodeImportStatements } from "@nodejs/codemod-utils/ast-grep/import-statement";
+import { getNodeRequireCalls } from "@nodejs/codemod-utils/ast-grep/require-call";
+import { resolveBindingPath } from '@nodejs/codemod-utils/ast-grep/resolve-binding-path';
 import type { SgRoot, Edit } from "@codemod.com/jssg-types/main";
 import type JS from "@codemod.com/jssg-types/langs/javascript";
 
@@ -55,8 +58,25 @@ export default function transform(root: SgRoot<JS>): string | null {
 	const rootNode = root.root();
 	const edits: Edit[] = [];
 
-	// do some transformation
-	edits.push(...);
+	const allStatementNodes = [
+		...getNodeImportStatements(root, 'api'),
+		...getNodeRequireCalls(root, 'api')
+		];
+
+	for (const statementNode of allStatementNodes) {
+		const bindingPath = resolveBindingPath(statementNode, 'api.fn');
+		if (!bindingPath) continue;
+		// Find all calls to the resolved bindingPath
+		const callNodes = rootNode.findDescendants((node) => {
+			return node.isCallExpression() &&
+				node.getChild('callee')?.getText() === bindingPath;
+		});
+		for (const callNode of callNodes) {
+			// Perform transformation on callNode
+			// e.g., replace 'api.fn' with 'api.newFn'
+			edits.push(...);
+		}
+	}
 
 	if (edits.length === 0) return null;
 

utils/README.md

@@ -123,112 +123,3 @@ import { getNodeJsUsage } from '@nodejs/codemod-utils';
 // Finds scripts like: "start": "node server.js", "build": "node.exe build.js"
 const nodeUsages = getNodeJsUsage(packageJsonAst);
 ```
-
-## Practical Examples
-
-### Complete Codemod Workflow
-
-Here's how these utilities work together in a typical Node.js deprecation codemod:
-
-```typescript
-import astGrep from '@ast-grep/napi';
-import {
-  getNodeImportStatements,
-  getNodeRequireCalls,
-  resolveBindingPath,
-  removeBinding,
-  removeLines
-} from '@nodejs/codemod-utils';
-
-export default function workflow({ file, options }) {
-  // 1. Parse the source code
-  const ast = astGrep.parse(astGrep.Lang.JavaScript, file.source);
-
-  // 2. Find all util imports/requires
-  const importStatements = getNodeImportStatements(ast, 'util');
-  const requireCalls = getNodeRequireCalls(ast, 'util');
-  const allUtilNodes = [...importStatements, ...requireCalls];
-
-  // 3. Find and transform deprecated API usage
-  const edits = [];
-  const linesToRemove = [];
-
-  for (const node of allUtilNodes) {
-    // Resolve how the deprecated API is accessed locally
-    const localPath = resolveBindingPath(node, '$.types.isNativeError');
-
-    if (localPath) {
-      // Find all usages of the deprecated API
-      const usages = ast.root().findAll({
-        rule: {
-          kind: 'call_expression',
-          has: {
-            field: 'function',
-            kind: 'member_expression',
-            regex: localPath.replace('.', '\\.')
-          }
-        }
-      });
-
-      // Transform each usage
-      for (const usage of usages) {
-        edits.push({
-          startIndex: usage.range().start.index,
-          endIndex: usage.range().end.index,
-          newText: usage.text().replace(localPath, 'util.types.isError')
-        });
-      }
-
-      // Remove the binding if it's no longer needed
-      const bindingRemoval = removeBinding(node, 'types');
-      if (bindingRemoval?.edit) {
-        edits.push(bindingRemoval.edit);
-      } else if (bindingRemoval?.lineToRemove) {
-        linesToRemove.push(bindingRemoval.lineToRemove);
-      }
-    }
-  }
-
-  // 4. Apply all transformations
-  let transformedSource = file.source;
-
-  // Apply edits
-  for (const edit of edits.reverse()) { // reverse to maintain indices
-    transformedSource = transformedSource.slice(0, edit.startIndex) +
-                      edit.newText +
-                      transformedSource.slice(edit.endIndex);
-  }
-
-  // Remove entire lines
-  if (linesToRemove.length > 0) {
-    transformedSource = removeLines(transformedSource, linesToRemove);
-  }
-
-  return {
-    ...file,
-    source: transformedSource
-  };
-}
-```
-
-### Handling Different Import Patterns
-
-The utilities automatically handle various import/require patterns:
-
-```typescript
-// ES Modules
-import util from 'util';              // → util.types.isNativeError
-import { types } from 'util';         // → types.isNativeError
-import { types as t } from 'util';    // → t.isNativeError
-
-// CommonJS
-const util = require('util');         // → util.types.isNativeError
-const { types } = require('util');    // → types.isNativeError
-const { types: t } = require('util'); // → t.isNativeError
-
-// Mixed with node: protocol
-import { types } from 'node:util';    // → types.isNativeError
-const util = require('node:util');    // → util.types.isNativeError
-```
-
-This unified approach ensures your codemods work correctly regardless of how developers import Node.js modules in their projects.