{"id":20758528,"url":"https://github.com/darkpurple141/eslint-codemod-utils","last_synced_at":"2025-10-15T04:40:00.501Z","repository":{"id":37708556,"uuid":"462115818","full_name":"DarkPurple141/eslint-codemod-utils","owner":"DarkPurple141","description":"A collection of AST Utils to mimic jscodeshift esque precision to codemods in eslint","archived":false,"fork":false,"pushed_at":"2025-10-01T19:54:40.000Z","size":498,"stargazers_count":16,"open_issues_count":14,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-01T21:29:23.824Z","etag":null,"topics":["eslint","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DarkPurple141.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-02-22T03:01:17.000Z","updated_at":"2025-04-09T10:20:48.000Z","dependencies_parsed_at":"2023-12-13T14:28:03.563Z","dependency_job_id":"a012edb4-4667-4868-91d1-e0fba56e72a1","html_url":"https://github.com/DarkPurple141/eslint-codemod-utils","commit_stats":{"total_commits":159,"total_committers":5,"mean_commits":31.8,"dds":0.559748427672956,"last_synced_commit":"0eca36fde661d1fb14df0ac4622abc664c29730f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/DarkPurple141/eslint-codemod-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkPurple141%2Feslint-codemod-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkPurple141%2Feslint-codemod-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkPurple141%2Feslint-codemod-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkPurple141%2Feslint-codemod-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DarkPurple141","download_url":"https://codeload.github.com/DarkPurple141/eslint-codemod-utils/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DarkPurple141%2Feslint-codemod-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279049858,"owners_count":26093368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eslint","typescript"],"created_at":"2024-11-17T09:51:49.917Z","updated_at":"2025-10-15T04:40:00.484Z","avatar_url":"https://github.com/DarkPurple141.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESLint Codemod Utilities\n\n![brach build status](https://github.com/darkpurple141/eslint-codemod-utils/actions/workflows/build-test.yml/badge.svg?branch=master)\n[![npm version](https://img.shields.io/npm/v/eslint-codemod-utils?style=flat-square)](https://www.npmjs.com/package/eslint-codemod-utils)\n\nThe `eslint-codemod-utils` package is a library of helper functions designed to enable code evolution in a similar way to `jscodeshift` - but leaning on the live and ongoing enforcement of `eslint` in your source - rather than one off codemod scripts. It provides first class typescript support and will supercharge your custom eslint rules.\n\n## Installation\n\n```sh\npnpm add -D eslint-codemod-utils\n```\n\n```sh\nyarn add -D eslint-codemod-utils\n```\n\n```sh\nnpm i --save-dev eslint-codemod-utils\n```\n\n## Getting started\n\nTo create a basic JSX node, you might do something like this:\n\n```ts\nimport {\n  jsxElement,\n  jsxOpeningElement,\n  jsxClosingElement,\n  identifier,\n} from 'eslint-codemod-utils'\n\nconst modalName = identifier({ name: 'Modal' })\nconst modal = jsxElement({\n  openingElement: jsxOpeningElement({ name: modalName, selfClosing: false }),\n  closingElement: jsxClosingElement({ name: modalName }),\n})\n```\n\nThis would produce an `espree` compliant node type that you can **also** nicely stringify to apply your eslint\nfixes. For example:\n\n```ts\nmodal.toString()\n// produces: \u003cModal\u003e\u003c/Modal\u003e\n```\n\nThe real power of this approach is when combining these utilties with `eslint` rule custom fixe. In these cases, rather than\nrelying on string manipulation - which can be inexact, hacky or complex to reason about - you can instead focus on only the fix you actually need to affect.\n\n### Your first `eslint` codemod\n\nWriting a codemod is generally broken down into three parts:\n\n1. Find\n2. Modify\n3. Remove / Cleanup\n\nThe `eslint` custom rule API allows us to find nodes fairly simply, but how might we modify them? Let's say we're trying to add a new element required to be composed by our Design System's Modal element - a `ModalBody` which is going to\nbe wrapped by the original `Modal` container. Assuming you've found the right node a normal fix might look like this:\n\n```ts\nimport { Rule } from 'eslint'\n\nfunction fix(fixer: Rule.RuleFixer) {\n  return fixer.replaceText(node, '\u003cModal\u003e\u003cModalBody\u003e\u003c/ModalBody\u003e\u003c/Modal\u003e')\n}\n```\n\nSo for this input:\n\n```ts\nconst MyModal = () =\u003e \u003cModal\u003e\u003c/Modal\u003e\n```\n\nWe make this change:\n\n```diff\n- const MyModal = () =\u003e \u003cModal\u003e\u003c/Modal\u003e\n+ const MyModal = () =\u003e \u003cModal\u003e\u003cModalBody\u003e\u003c/ModalBody\u003e\u003c/Modal\u003e\n```\n\nThis kinda works, but the problem is the existing usage of Modal in our codebase is likely (guaranteed!) to be considerably more complex than\nthis example.\n\n- If our Modal has props, we need to consider them\n- If our Modal has children, we need to consider them\n- If our Modal is aliased, we need to consider that\n\nInstead of relying on string manipulation to reconstruct the existing AST, we instead leverage the information `eslint` is already giving to us.\n\n```ts\nimport * as esUtils from 'eslint-codemod-utils'\nimport { Rule } from 'eslint'\n\n// This is slightly more verbose, but it's considerably more robust -\n// Simply re-using and spitting out the exisitng AST as a string\nfunction fix(fixer: Rule.RuleFixer) {\n  const jsxIdentifier = esUtils.jsxIdentifier({ name: 'ModalBody' })\n  const modalBodyNode = esUtils.jsxElement({\n    openingElement: esUtils.jsxOpeningElement({ name: jsxIdentifier }),\n    closingElement: esUtils.jsxClosingElement({ name: jsxIdentifier }),\n    // pass children of original element to new wrapper\n    children: node.children,\n  })\n  return fixer.replaceText(\n    node,\n    esUtils.jsxElement({ ...node, children: [modalBodyNode] }).toString()\n  )\n}\n```\n\nThe above will work for the original example:\n\n```diff\n- const MyModal = () =\u003e \u003cModal\u003e\u003c/Modal\u003e\n+ const MyModal = () =\u003e \u003cModal\u003e\u003cModalBody\u003e\u003c/ModalBody\u003e\u003c/Modal\u003e\n```\n\nBut it will also work for:\n\n```diff\n- const MyModal = () =\u003e \u003cModal type=\"full-width\"\u003e\u003c/Modal\u003e\n+ const MyModal = () =\u003e \u003cModal type=\"full-width\"\u003e\u003cModalBody\u003e\u003c/ModalBody\u003e\u003c/Modal\u003e\n```\n\nOr:\n\n```diff\n- const MyModal = () =\u003e \u003cModal\u003e\u003cSomeChild/\u003e\u003c/Modal\u003e\n+ const MyModal = () =\u003e \u003cModal\u003e\u003cModalBody\u003e\u003cSomeChild/\u003e\u003c/ModalBody\u003e\u003c/Modal\u003e\n```\n\nIt's a declarative approach to solve the same problem.\n\nSee the [eslint-plugin-example](packages/eslint-plugin-codemod) for examples of more real world fixes.\n\n## How it works\n\nThe library provides a 1-1 mapping of types to utility functions every `espree` node type. These are all lowercase complements to the underlying type they represent;\neg. `jsxIdentifier` produces a `JSXIdentifier` node representation. These nodes all implement their own `toString`. This means any string cast will recursively produce the correct string output for any valid `espree` AST.\n\nEach helper takes in a valid `espree` node and spits out an augmented one that can be more easily stringified. See -\u003e [API](API.md) for more.\n\n## Motivation\n\nThis idea came about after wrestling with the limitations of `eslint` rule fixes. For context, `eslint` rules rely heavily on string based utilities to apply\nfixes to code. For example this fix which appends a semi-colon to a `Literal` (from the `eslint` documentation website itself):\n\n```js\ncontext.report({\n  node: node,\n  message: 'Missing semicolon',\n  fix: function (fixer) {\n    return fixer.insertTextAfter(node, ';')\n  },\n})\n```\n\nThis works fine if your fixes are trivial, but it works less well for more complex uses cases. As soon as you need to traverse other AST nodes and combine information for a fix, combine fixes; the simplicity of the `RuleFixer` API starts to buckle.\n\nIn codemod tools like [jscodeshift](https://github.com/facebook/jscodeshift), the AST is baked in to the way fixes are applied - rather than applying fixes your script needs to return a collection of AST nodes which are then parsed and integrated into the source. This is a little more heavy duty but it also is more resillient.\n\nThe missing piece for `ESlint` is a matching set of utilties to allow the flexibility to dive into the AST approach where and when a developer feels it is appropriate.\nThis library aims to bridge some of that gap and with some different thinking around just how powerful `ESLint` can be.\n\nFixes can then theoretically deal with more complex use cases like this:\n\n```ts\n/**\n * This is part of a fix to demonstrate changing a prop in a specific element with\n * a much more surgical approach to node manipulation.\n */\nimport {\n  jsxOpeningElement,\n  jsxAttribute,\n  jsxIdentifier,\n} from 'eslint-codemod-utils'\n\n// ... further down the file\ncontext.report({\n  node: node,\n  message: 'error',\n  fix(fixer) {\n    // The variables 'fixed' works with the espree AST to create\n    // its own representation which can easily be stringified\n    const fixed = jsxOpeningElement({\n      name: node.name,\n      selfClosing: node.selfClosing,\n      attributes: node.attributes.map((attr) =\u003e {\n        if (attr.type === 'JSXAttribute' \u0026\u0026 attr.name.name === 'open') {\n          const internal = jsxAttribute({\n            // espree nodes are spread into the util with no issues\n            ...attr,\n            // others are recreated or re-mapped\n            name: jsxIdentifier({\n              ...attr.name,\n              name: 'isOpen',\n            }),\n          })\n          return internal\n        }\n\n        return attr\n      }),\n    })\n\n    return fixer.replaceText(node, fixed.toString())\n  },\n})\n```\n\n## Similar projects\n\n- AST Types [https://github.com/benjamn/ast-types](https://github.com/benjamn/ast-types)\n- Codeshift Community [https://www.codeshiftcommunity.com/](https://www.codeshiftcommunity.com/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkpurple141%2Feslint-codemod-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarkpurple141%2Feslint-codemod-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarkpurple141%2Feslint-codemod-utils/lists"}