Skip to content

README.md

Latest commit

 

History

History
380 lines (280 loc) · 11.3 KB

README.md

File metadata and controls

380 lines (280 loc) · 11.3 KB

README Auto Scan

npm version npm downloads license GitHub stars

CLI tool that scans JavaScript, TypeScript, Python, and PHP projects and automatically generates clean README.md files with installation, usage, scripts, environment variables, and publishing checklist.

Features

  • Multi-Language Support — JavaScript, TypeScript, Python, and PHP projects
  • Smart Project Detection — Automatically detects project types (Node.js, React, Vue, Next.js, Vite, Express, TypeScript, CLI packages, Python, Django, Flask)
  • Package Manager Detection — npm, pnpm, yarn, bun for JS/TS; pip, Poetry, Pipenv for Python; Composer for PHP
  • Package.json Analysis — Extracts metadata, scripts, dependencies, exports, and repository info
  • Auto-Generated Documentation — Creates professional README sections with proper formatting
  • Environment Variables — Parses .env.example and includes variable tables
  • NPM Scripts Table — Generates markdown tables with human-readable script descriptions
  • Python Dependencies — Parses requirements.txt and includes dependency tables
  • Safe by Default — Won't overwrite existing files without --force flag
  • CLI & Library Support — Handles both CLI packages and regular npm libraries
  • Project Structure — Optional file tree with --include-tree
  • Publishing Checklist — Built-in checklist for npm package releases

Installation

Global Installation

npm install -g readme-autoscan

Using npx (No Installation Required)

npx readme-autoscan

Local Development

git clone https://github.com/JomsCode21/README-auto-scan.git
cd README-auto-scan
npm install
npm run build

Usage

Generate a README.md in the current directory:

readme-autoscan

Preview the output without writing a file:

readme-autoscan --dry-run

Write to a custom location:

readme-autoscan --output docs/README.md

Overwrite an existing README.md:

readme-autoscan --force

Include the project file tree:

readme-autoscan --include-tree

Skip the publishing checklist:

readme-autoscan --no-checklist

Examples

readme-autoscan
readme-autoscan --dry-run
readme-autoscan --output docs/README.md
readme-autoscan --force
readme-autoscan --include-tree
readme-autoscan --no-checklist

CLI Options

Option Description
--output <file> Write README to a custom file (default: README.md)
--force Overwrite existing README.md
--dry-run Print generated README without writing a file
--include-tree Include project structure in the README
--no-checklist Skip publishing checklist section
-v, --version Show package version
-h, --help Show help message

Example Output

Here's what a generated README looks like:

# my-awesome-package

A fantastic package that does amazing things.

## Features

- Auto-generated README with project metadata
- Project type detection (Node.js package, TypeScript package)
- NPM scripts documentation with descriptions
- Clean, professional markdown formatting

## Installation

\`\`\`bash
npm install my-awesome-package
\`\`\`

## Usage

\`\`\`javascript
import myawesomepackage from "my-awesome-package";

// Use the package
myawesomepackage.someFunction();
\`\`\`

## Available Scripts

| Script | Description              | Command             |
| ------ | ------------------------ | ------------------- |
| dev    | Start development server | `vite`              |
| build  | Build for production     | `tsc && vite build` |
| test   | Run test suite           | `vitest`            |

## License

This project is licensed under the MIT License.

Project Type Detection

README Auto Scan automatically detects these project types:

Type Detection Criteria
CLI Package Has bin field in package.json
TypeScript Has typescript dependency or tsconfig.json
React App Has react dependency
Vue App Has vue dependency
Next.js Has next dependency or next.config.js
Vite Has vite dependency or vite.config.*
Express Has express dependency
Python Has requirements.txt, pyproject.toml, setup.py, etc.
Django Has manage.py or django in dependencies
Flask Has app.py or flask in dependencies
Laravel Has artisan or laravel/framework in composer requirements

Multi-Language Support

README Auto Scan supports JavaScript, TypeScript, Python, and PHP projects.

Language Detection Files
JavaScript/TypeScript package.json, tsconfig.json, vite.config.*, next.config.js
Python requirements.txt, pyproject.toml, setup.py, Pipfile, poetry.lock, main.py, app.py, manage.py
PHP composer.json, composer.lock, index.php, artisan, phpunit.xml, phpunit.xml.dist

JavaScript/TypeScript Package Manager Detection

README Auto Scan automatically detects your package manager from lock files and generates matching commands.

Lock File Package Manager
package-lock.json npm
pnpm-lock.yaml pnpm
yarn.lock yarn
bun.lockb or bun.lock bun

Example with pnpm:

pnpm install
pnpm dev
pnpm build

Python Support

README Auto Scan detects common Python project files and generates Python-friendly README sections.

Python Tool Detection File Example Commands
pip requirements.txt pip install -r requirements.txt
Poetry pyproject.toml, poetry.lock poetry install
Pipenv Pipfile pipenv install
Django manage.py python manage.py runserver

Example Python README output:

# my-python-project

A Python project.

## Installation

\`\`\`bash
pip install -r requirements.txt
\`\`\`

### Python Example

Run the application:

\`\`\`bash
python main.py
\`\`\`

Run tests:

\`\`\`bash
pytest
\`\`\`

Dependencies:

| Package | Version |
| ------- | ------- |
| requests | latest |
| flask | ==3.0.0 |

PHP and Laravel Support

README Auto Scan detects common PHP and Laravel project files and generates PHP-friendly README sections.

PHP Type Detection Files
Basic PHP index.php, composer.json
Composer composer.json, composer.lock
Laravel artisan, routes/web.php, routes/api.php, bootstrap/app.php, app/Http
PHPUnit phpunit.xml, phpunit.xml.dist
PHP Tool Example Commands
Composer composer install
Laravel Artisan php artisan serve
Laravel Tests php artisan test
PHPUnit vendor/bin/phpunit

Development

# Install dependencies
npm install

# Run type checking
npm run check

# Build the project
npm run build

# Run tests
npm test

# Preview generated README for this project
npm run dev

Project Structure

readme-autoscan/
├─ src/
│  ├─ cli.ts                 # CLI entry point and argument parsing
│  ├─ scanner.ts             # Project scanning and analysis
│  ├─ detector.ts            # Project type detection
│  ├─ generator.ts           # README markdown generation
│  ├─ env.ts                 # .env.example parsing
│  ├─ scripts.ts             # NPM script descriptions
│  ├─ package-manager.ts    # Package manager detection
│  ├─ utils.ts               # Utility functions
│  └─ languages/
│     ├─ python.ts           # Python project detection
│     └─ php.ts              # PHP/Laravel project detection
├─ tests/
│  ├─ generator.test.ts
│  ├─ package-manager.test.ts
│  ├─ scripts.test.ts
│  ├─ utils.test.ts
│  ├─ env.test.ts
│  └─ python.test.ts         # Python detection tests
├─ bin/
│  └─ readme-autoscan.js     # Executable entry point
├─ package.json
├─ tsconfig.json
├─ README.md
└─ LICENSE

Generated README Sections

The tool generates these sections based on your project:

  1. Title & Description — From package.json
  2. Features — Auto-detected capabilities
  3. Installation — NPM install instructions
  4. Usage — CLI or library usage examples
  5. CLI Usage — If it's a CLI package
  6. Available Scripts — Markdown table from package.json
  7. Environment Variables — From .env.example
  8. Project Structure — With --include-tree
  9. API / Exports — Main/module/types entries
  10. Development — Setup instructions
  11. Publishing Checklist — For npm packages
  12. License — From package.json
  13. Contributing — Standard contribution message

Generated README Examples

README Auto Scan includes example generated README files for all supported project types. Use these examples to preview the README style before running the CLI in your own project.

Project Type Example
JavaScript Package examples/javascript-package/README.generated.md
TypeScript Package examples/typescript-package/README.generated.md
Python pip Project examples/python-pip/README.generated.md
Python Poetry Project examples/python-poetry/README.generated.md
Python Pipenv Project examples/python-pipenv/README.generated.md
Python Django Project examples/python-django/README.generated.md
Basic PHP Project examples/php-basic/README.generated.md
Laravel Project examples/php-laravel/README.generated.md

Preview an example locally:

cd examples/python-pip
npx readme-autoscan --dry-run

See examples/README.md for more details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Copyright (c) 2026 JomsCode21

Links

Made for the JavaScript, TypeScript, Python, and PHP community