ESLint Auto-Fixex

➡️ CHANGELOG

An opinionated CLI that parses ESLint diagnostics, matches them with curated fix strategies, and rewrites TypeScript sources automatically. This README merges and extends the knowledge from AGENTS.md, QWEN.md, GEMINI.md, and the inline guidelines enforced in this workspace so new contributors can understand every rule in one place.

Table of Contents

1. Project Overview
2. Architecture & Key Files
3. Rulebook (All Mandatory Rules Explained)
4. Supported Fix Strategies
5. CLI Usage (npx & npm scripts)
6. Como foi feito (How it was built)
7. Como funciona (How it works)
8. Como testar (How to test)
9. Sources consulted

Project Overview

• Single entry point: src/index.ts orchestrates CLI parsing, ESLint stderr ingestion, and sequential application of rule-specific fixers that now bundle a shebang so the transpiled code behaves like any other Node executable.
• Purpose: shorten feedback loops by auto-fixing common lint errors before rerunning ESLint for confirmation.
• Technology stack: TypeScript compiled to CommonJS, executed via Node ≥ 18, and distributed through eslint-auto-fixex, which exposes an npm-friendly bin entry callable through npx or a global install.
• Execution mode: run the fixer against individual files or entire folders; it prints emoji-prefixed logs describing each applied strategy and re-runs ESLint afterward.

Architecture & Key Files

• src/index.ts: houses the CLI, error parsers, fixStrategies array, and ruleOrder that forces deterministic execution.
• AGENTS.md: repository-level policies (structure, coding style, testing).
• QWEN.md: contextual brief about fixer capabilities and workflow expectations.
• GEMINI.md: placeholder for future AI-specific instructions.
• package.json: registers the eslint-auto-fixex binary, npm scripts, and the bundled ESLint toolchain required for standalone execution.

Rulebook (All Mandatory Rules Explained)

Core Development Practices

• Single entry point expansion: extend fixStrategies and ruleOrder when adding new ESLint rules; keep helper utilities inside src until the codebase justifies modules.
• Coding style: two-space indentation, trailing semicolons, const by default, PascalCase for types/interfaces, camelCase for functions, and descriptive emoji logs.
• Pure strategies: each fixer receives the file contents plus the matched ESLint errors and must return a new string without side effects.

Toolchain & Commands

• Prefer npm for scripts (npm install, npm run dev, npm run lint). Use npx for one-off CLI execution without installing globally.
• The published binary can be executed through npx eslint-auto-fixex ..., thanks to the npm bin entry.
• Rerun ESLint with npm run lint after auto-fixing to ensure parity.

Contribution Rituals

• TODO policy: start every task with at least two TODOs (implementation + final report) and keep them up to date.
• Mandatory reports: each work session ends with a Markdown report stored under reports/{DD-MM-YYYY_HH-mm}.md, summarizing what changed and why.
• Dual commits per task:
  1. Pre-change commit using :sparkles: lets create {directory} with {description}. Today is {state} and after will be {target} describing intent.
  2. Post-change commit using :sparkles: created: {directory}: {techniques used} detailing the execution and tests.
• Emoji prefixes: follow the provided emoji ↔️ commit-type matrix (✨ feat, 🐛 fix, 📝 docs, 🎨 style, ♻️ refactor, ⚡️ perf, ✅ test, 🔧 chore, 🚀 deploy, 🔥 remove, 🔒 security, 💄 ui, 🤖 ai).
• Clean terminals: keep working within the same terminal session; never spawn new ones.
• Safety: never run rm; prefer non-destructive alternatives and document cleanup steps.

Documentation Deliverables

• Every README (including subdirectories) must link to the root CHANGELOG.md.
• The README must feel like a technical blog post and include the sections “Como foi feito”, “Como funciona”, and “Como testar”, plus a list of information sources.
• Generate OpenAPI schemas (openapi.json) and publish Swagger docs whenever APIs are introduced.
• Any computation mandates a minimalistic HTML report (white background, system fonts, subtle grays, responsive layout, card-like tables) capturing intermediate values.

Workflow Safeguards

• Semantic typing initiative: when a primitive hints at a domain meaning (email, amount, boolean flags, etc.), infer a branded type under domains/{Domain}/{Entity}/{name}.ts, expose of/un/make helpers, and document validations in semantic-types.manifest.json.
• Never delete legacy primitive usages; introduce the new brand alongside them until migration is complete.
• Prefer decorators for reusable behaviors whenever logic can be abstracted.
• API schemas, Swagger docs, TODO discipline, reporting, .gitignore coverage (node_modules/, dist/), and npm-based workflows are non-negotiable quality gates.

Supported Fix Strategies

| Rule | What gets fixed | Strategy summary | | --- | --- | --- | | @typescript-eslint/naming-convention | Enforces camelCase where ESLint reported UPPER_CASE identifiers | Parses variable names from diagnostics and rewrites them with camelCase heuristics while preserving intent. | | @typescript-eslint/prefer-nullish-coalescing | || used for nullish checks | Swaps || for ?? when RHS should only trigger on null/undefined. | | eqeqeq | Loose equality comparisons | Replaces ==/!= with ===/!== while keeping operands intact. | | @typescript-eslint/no-floating-promises | Promises not awaited or handled | Wraps expressions with void to mark intentional fire-and-forget operations. | | @typescript-eslint/explicit-function-return-type | Missing return annotations | Infers a best-effort return type and injects it into the function signature. | | @typescript-eslint/no-explicit-any | Unsafe any usage | Replaces any with unknown, nudging consumers to refine types. | | @typescript-eslint/restrict-template-expressions | Non-string values in template literals | Adds String() (or equivalent) conversions so templates remain type-safe. | | no-constant-binary-expression | Binary expressions with both sides constant | Removes the redundant computation entirely. |

CLI Usage (npx & npm scripts)

One-off execution

• npx eslint-auto-fixex src/index.ts
• npx eslint-auto-fixex .

Both commands leverage the bundled ESLint, parser, and plugin, so no additional peer dependencies are necessary in the consumer project.

Global installation

• npm: npm i -g eslint-auto-fixex

After a global install the binary eslint-auto-fixex becomes available in your PATH:

eslint-auto-fixex src/index.ts
eslint-auto-fixex .

Building & publishing

1. npm install
2. npm run build
3. npm publish after verifying the dist folder contains the compiled CLI with the Node shebang.

Como foi feito (How it was built)

1. Collect ESLint JSON output and normalize it into EslintError objects.
2. Sort errors according to ruleOrder to avoid conflicts (e.g., renaming before enforcing template rules).
3. Pipe the file contents through each fixStrategy, logging every mutation with contextual emojis.
4. Re-run ESLint at the end to surface any remaining issues and print a concise summary.

Como funciona (How it works)

• Input: CLI arguments determine whether a single file or a directory tree is linted. The tool shells out to the bundled ESLint binary resolved via require.resolve.
• Processing: For each rule listed above, the strategy inspects relevant slices of the source file, generates patches, and reassembles the file contents.
• Output: Updated files are written back to disk, and the console highlights which fixes were applied, which errors remain, and next steps for the developer.
• Extensibility: Adding a new rule means declaring a new object in fixStrategies, describing it in Portuguese, and wiring it into ruleOrder.

Como testar (How to test)

1. Install dependencies with npm: npm install.
2. Capture current lint errors: npm run lint.
3. Run the bundled CLI: npx eslint-auto-fixex path/to/file.ts or npx eslint-auto-fixex .. During development you can still run npm run dev -- src/index.ts ... to skip compilation.
4. Review the console logs to confirm each rule execution and inspect the git diff.
5. Re-run npm run lint to ensure all blocking issues are gone.
6. Document the session in reports/{DD-MM-YYYY_HH-mm}.md, including commands executed and findings.

Sources consulted

• AGENTS.md
• QWEN.md
• GEMINI.md
• src/index.ts
• package.json