backend-diet 1.0.0

package/README.md

@@ -0,0 +1,224 @@
+# backend-diet 🥗
+
+[![npm version](https://img.shields.io/npm/v/backend-diet?style=flat-square)](https://www.npmjs.com/package/backend-diet)
+[![CI](https://github.com/1iPluto/backend-diet/actions/workflows/ci.yml/badge.svg)](https://github.com/1iPluto/backend-diet/actions/workflows/ci.yml)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+> **Put your project on a diet.** Scan your source code, identify specific library functions you're actually using, and get native Node.js / Web API alternatives — with code snippets, in your terminal, right now.
+
+Most tools tell you a package is large. **backend-diet tells you exactly what to replace and how.**
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| **AST-accurate scanning** | Uses Babel to parse JS/TS/JSX/TSX — no regex false positives |
+| **Refactor Score** | A 0–100 score graded CRITICAL → SVELTE showing how lean your project is |
+| **Code snippets** | Every suggestion shows a before/after code snippet in the terminal |
+| **Auto-Patch `--fix`** | Automatically rewrites trivial replacements (e.g. `uuidv4()` → `crypto.randomUUID()`) |
+| **Badge generator `--badge`** | One command generates a Shields.io badge for your README |
+| **Time Machine `--since`** | Tracks score history across git commits with an ASCII sparkline |
+| **CI-friendly `--format json`** | Full JSON output for integration into CI pipelines |
+
+---
+
+## Install
+
+```bash
+# No install needed — run on any project instantly
+npx backend-diet scan
+
+# Global install
+npm install -g backend-diet
+
+# As a dev dependency
+npm install --save-dev backend-diet
+```
+
+---
+
+## Usage
+
+```bash
+# Scan the current directory
+backend-diet scan
+
+# Scan a specific directory
+backend-diet scan ./src
+
+# Show trivial auto-patches (dry run)
+backend-diet scan --fix
+
+# Apply patches in-place
+backend-diet scan --fix --yes
+
+# Generate a README badge
+backend-diet scan --badge
+
+# Track score over the last 20 commits
+backend-diet scan --since HEAD~20
+
+# CI mode — JSON output
+backend-diet scan --format json
+
+# Ignore vendor files
+backend-diet scan --ignore "vendor/**" "generated/**"
+```
+
+---
+
+## Refactor Score
+
+```
+Score = 100 − round((bytes_you_could_remove / total_dep_bytes) × 100)
+```
+
+| Score | Grade | Meaning |
+|---|---|---|
+| 90–100 | 🥗 SVELTE | Your project is already very lean |
+| 70–89 | ✅ HEALTHY | A few improvements possible |
+| 40–69 | ⚠️ NEEDS WORK | Significant savings on the table |
+| 0–39 | 💀 CRITICAL | Heavy bloat detected (CI will exit 1) |
+
+---
+
+## Supported Packages
+
+| Package | Coverage | Total Gzipped Size |
+|---|---|---|
+| `lodash` | 19 functions | ~24 KB |
+| `moment` | 9 functions | ~72 KB |
+| `axios` | 7 functions | ~14 KB |
+| `uuid` | 2 functions | ~3.7 KB |
+| `bluebird` | 9 functions | ~17 KB |
+| `underscore` | 12 functions | ~6.8 KB |
+
+---
+
+## Auto-Patch Examples
+
+### `uuid` → `crypto.randomUUID()`
+
+```diff
+- import { v4 as uuidv4 } from 'uuid';
+- const id = uuidv4();
++ const id = crypto.randomUUID();
+```
+
+### `_.cloneDeep` → `structuredClone()`
+
+```diff
+- import { cloneDeep } from 'lodash';
+- const copy = cloneDeep(obj);
++ const copy = structuredClone(obj);
+```
+
+### `_.get` → Optional chaining
+
+```diff
+- import { get } from 'lodash';
+- const val = get(obj, 'a.b.c', defaultVal);
++ const val = obj?.a?.b?.c ?? defaultVal;
+```
+
+---
+
+## CI Integration
+
+Add to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "diet": "backend-diet scan --format json"
+  }
+}
+```
+
+Or use it as a GitHub Actions step:
+
+```yaml
+- name: Bundle diet check
+  run: npx backend-diet scan --format json
+  # Exits with code 1 if score is CRITICAL
+```
+
+---
+
+## Time Machine
+
+backend-diet saves a `.backend-diet-history.json` in your project root. Each scan appends an entry with the score, grade, and current git SHA.
+
+```bash
+backend-diet scan --since HEAD~20
+# Shows a sparkline: ▁▂▃▃▄▅▅▆▅▄▃
+# "Score trending DOWN — your bundle is getting fatter."
+```
+
+Add `.backend-diet-history.json` to version control to share trends with your team.
+
+---
+
+## Contributing — Add a Package to the Database
+
+The diet database is the heart of this tool. Community contributions are the primary growth engine.
+
+To add support for a new package:
+
+1. Fork the repo
+2. Create `src/database/packs/<package-name>.ts`
+3. Follow the `PackageEntry` interface (see `src/types.ts`)
+4. Export it and register it in `src/database/index.ts`
+5. Open a PR with the title: `feat: add <package-name> to diet database`
+
+**The bar for a good entry:**
+- Real package (check bundlephobia.com for size)
+- Has a native Node ≥18 alternative
+- Snippet must be copy-pasteable and correct
+
+---
+
+## Conventional Commits
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new package to diet database
+fix: resolve false positive on namespace imports
+perf: switch file walker to fast-glob
+refactor: extract scorer into standalone module
+docs: update Time Machine section in README
+chore: upgrade @babel/traverse
+test: add unit tests for lodash cloneDeep detection
+```
+
+Releases and changelogs are automated from commit history using `standard-version`.
+
+---
+
+## Publishing a New Release
+
+```bash
+# 1. Bump version (auto-updates package.json + CHANGELOG.md)
+npx standard-version
+
+# 2. Push with tags
+git push --follow-tags origin main
+
+# GitHub Actions auto-publishes to npm on tag push
+```
+
+---
+
+## Author
+
+**Marwan Said** · [github.com/1iPluto](https://github.com/1iPluto)
+
+---
+
+## License
+
+MIT

package/bin/pkg-diet.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+'use strict';
+
+require('../dist/cli.js');