Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (56 loc) · 3.27 KB

AGENTS.md

File metadata and controls

73 lines (56 loc) · 3.27 KB
Raw

Agent Notes

Project Purpose

convert-to-arrow is an npm CLI codemod that converts safe JavaScript and TypeScript function declarations into equivalent const arrow-function expressions. The CLI entrypoint is src/cli.ts; the published binary points at dist/cli.js, which is generated by npm run build.

Core Implementation

  • The codemod is implemented with ts-morph in src/cli.ts.
  • The CLI accepts one optional path argument. Non-glob inputs are expanded to /**/*.{ts,tsx}; explicit glob inputs are used as provided.
  • node_modules is always excluded from conversion.
  • The CLI chooses a tsconfig.json from the provided directory when present, otherwise from the repository root/current working directory.
  • Default scanning targets .ts and .tsx. JavaScript is supported only when callers pass an explicit JS-inclusive glob such as "**/*.{js,jsx,ts,tsx}".
  • Do not edit dist/ directly. Change src/cli.ts and let npm run build regenerate output.

Conversion Rules To Preserve

The codemod should convert ordinary named local functions, named exported functions, generic functions, async functions, type predicate returns, default/rest/destructured parameters, JSDoc, and named default exports.

The codemod should skip cases where arrow functions would change semantics or produce invalid output, including:

  • overload declarations/implementations
  • declaration files and ambient declarations
  • class methods and object-literal methods
  • generator functions
  • anonymous default exports
  • functions with a this parameter
  • functions whose bodies use this, super, arguments, or new.target
  • functions with asserts ... return types

For .tsx files, single generic arrow functions need the trailing comma form (<T,>) to avoid JSX parsing ambiguity.

Tests

  • Tests live in test/*.test.js and use Node's built-in node:test runner.
  • Test helpers are in test/helpers/cli.js.
  • Tests create temporary projects, run the built CLI from dist/cli.js, and compare transformed files exactly.
  • npm run test runs npm run build first, then node --test test/*.test.js.
  • Add or update focused tests whenever conversion behavior changes. Prefer small fixture projects through createProject, runCli, readProjectFile, and assertTypeScriptProject.
  • test/all-cases.fixture.tsx is a tracked source fixture; tests copy it to a temp project and assert that the original fixture remains unchanged.

Formatting And Style

  • This is an ESM TypeScript project ("type": "module").
  • Formatting and linting are handled by Biome.
  • Style is 2-space indentation, double quotes, no semicolons, and LF line endings.
  • Keep implementation changes narrow. The CLI is intentionally straightforward and procedural.

Useful Commands

  • npm run dev -- <path-or-glob> runs the TypeScript CLI through tsx.
  • npm run build builds dist/cli.js with tsup.
  • npm run test builds and runs the test suite.
  • npm run typecheck runs TypeScript without emit.
  • npm run format:check and npm run lint:check check Biome formatting/linting.
  • npm run verify runs the full repository check: knip, format check, lint check, typecheck, and tests.

Required Verification

Always run npm run verify before finalizing any work in this repository, and report the result.