CodeCare CLI

A lightweight command-line tool to analyze and report on your codebase health.

Overview

CodeCare scans a project and reports common code health signals such as large files, duplicate files, empty files, and files exceeding a configurable line limit. Reports can be generated as PDF or JSON.

Key Features

• Codebase analysis for large files, duplicates, empty files, and long files
• PDF and JSON report generation
• Configurable scan patterns, size limits, and line limits
• Exclude patterns to skip folders like node_modules

Installation

Install from the npm registry (recommended for end users):

# install globally so `codecare` is available system-wide
npm install -g codecare

# or install locally into a project
npm install codecare

Project configuration

You can create a project-level config file to persist defaults and thresholds. Supported files: .codecarerc (JSON), codecare.config.json, or a codecare field in package.json.

Example .codecarerc:

{
  "pattern": "**/*",
  "exclude": "node_modules/**,dist/**",
  "size": 100000,
  "maxLines": 600,
  "maxDuplicates": 0,
  "maxLargeFiles": 10,
  "maxFilesExceedingLineLimit": 5,
  "failOnThreshold": true,
  "output": "json",
  "directory": "./reports"
}

When failOnThreshold is true, codecare check will exit with code 2 if any configured threshold is exceeded — useful for CI enforcement.

codecare init — create starter config

Use codecare init to create a starter .codecarerc in the current directory. Use --force to overwrite an existing file.

codecare init
codecare init --force

Usage

Run from the root of the project you want to scan. The CLI exposes the main check command.

Basic usage:

codecare check

Options (important ones):

• -p, --pattern <pattern>: Glob pattern to include files (default **/*)
• -x, --exclude <exclude>: Comma-separated glob patterns to exclude (default node_modules/**)
• -s, --size <size>: Size limit (bytes) to mark files as large (default 50000)
• -l, --max-lines <maxLines>: Maximum lines allowed per file (default 500)
• -o, --output <output>: Report format: pdf or json (default pdf)
• -d, --directory <directory>: Directory to save reports (default ./reports)

Example:

1. Check the health of the codebase

Analyzes the codebase and generates a report.

codecare check [options]

Options:

• -p, --pattern <pattern>
  Glob pattern to specify which files to include in the scan.
  Default: **/* (all files in the project directory).

  Example:

  codecare check --pattern "src/**/*.js"

  codecare check --p "src/**/*.js"

• -s, --size <size>
  Size limit (in bytes) to classify files as "large".
  Default: 50000 (50KB).

  Example:

  codecare check --size 100000

  codecare check --s 100000

• -o, --output <output>
  Format of the generated report.
  Options: pdf (default), json.

  Example:

  codecare check --output json

  codecare check --o json

• -l, --max-lines <maxLines>
  Maximum lines of code allowed in a single file.
  Default: 500 lines

  Example:

  codecare check --max-lines json

  codecare check --l json

• -d, --directory <directory>
  Directory where the generated report will be saved.
  Default: ./reports.

  Example:

  codecare check --directory ./custom-reports

  codecare check --d ./custom-reports

---

Global Commands

1. View Help

Displays the list of commands and options available in the CLI.

codecare help

2. View Version

Displays the current version of the CLI.

codecare --version

codecare --V

---

Examples

1. Run a basic health check and generate an PDF report in the default location:

   codecare check

2. Scan only .js files in the src directory:

   codecare check --pattern "src/**/*.js"

3. Set the size limit for large files to 100KB and output a JSON report:

   codecare check --size 100000 --output json

4. Generate an PDF report in a custom directory:

   codecare check --directory ./output/reports

5. Set the number of lines of code to 600 and output a PDF report

   codecare check --max-lines 600 --output pdf

Local development

If you want to work from the source on your machine, clone the repository and install dependencies:

git clone https://github.com/rakshixh/CodeCare.git
cd CodeCare
npm install

To install the package locally from the current folder (quick test as if published):

npm install -g .

To create a tarball and install that instead of linking:

npm pack
# then (example filename depends on package.json version)
npm install -g ./codecare-1.3.0.tgz

Testing with npm link

Use npm link when actively developing the CLI and testing it in other projects without repeatedly packing or publishing.

1. From the CodeCare project root, install deps and create a global link:

npm install
npm link

2. In the project where you want to test (or the same repo for quick checks), run:

npm link codecare
# now `codecare` is available globally and points to your local source
codecare check --output json --directory ./reports/local-test

3. To remove the link when finished:

npm unlink codecare    # in the consumer project
npm unlink              # in the CodeCare project

This workflow lets you iterate quickly without rebuilding or republishing.

Recommended Local QA

• Run the CLI against a smaller sample first (use --pattern to limit scope).
• Use --output json to integrate results with scripts or CI.
• If Puppeteer fails to launch when generating PDFs, ensure system has required dependencies or run in a Docker container (see Troubleshooting below).

Troubleshooting

• Puppeteer / PDF: If PDF generation fails, try running with --output json to confirm scan logic is working. On some Windows or headless CI runners, you may need to install additional libraries or run Puppeteer with custom launch options.

Contributing

Contributions are welcome. Suggested workflow:

1. Fork the repository and create a feature branch.
2. Implement your changes and include tests where appropriate.
3. Open a pull request describing the change and why it's useful.

Guidelines:

• Keep changes minimal and focused.
• Run npm install to ensure dependencies are satisfied.

Project Structure

• index.js - CLI entrypoint
• commands/ - CLI command implementations (check, help)
• utils/ - core utilities (file scanning, report generation)
• config.js - default configuration values

License

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