npm package: @mod10/cicachecleaner
Description: A CLI tool to clean npm cache based on current project dependencies
Author: mod10
Latest version: 0.0.1

# CI Cache Cleaner

A CLI tool for cleaning npm cache that analyzes the dependency tree of the current project and removes unused cached content.

## Introduction

In CI/CD environments, `~/.npm` or specific cache directories are often cached to accelerate dependency installation. Over time, as package versions are updated, older versions of packages remain in the cache, causing the cache size to continuously expand, increasing storage costs and network transmission time.

CI Cache Cleaner uses `@npmcli/arborist` to analyze the complete dependency tree of the current project and compares it with the cached content to safely delete unused cache entries. It supports preserving package metadata cache, ensuring that necessary metadata information is retained during the cleanup process to meet the needs of projects that use `--prefer-offline`.

## Differences from Other Solutions

### Why not use lockfile as cache key?

Using lockfile as a cache key is certainly a good solution and is recommended under normal circumstances. However, using lockfile also has some problems:

1. Once the lockfile changes, the previous cache expires entirely, resulting in lower cache hit rates.
2. In enterprises, there may be many projects that do not use or fail to properly use lockfiles.

### Why not use npm cache verify?

The `npm cache verify` command cannot clean up unused dependency caches in projects. It is mainly used to verify cache integrity and remove corrupted entries, but it does not identify and delete packages that are intact but no longer depended on by the project.

### Why not use pnpm store prune?

When pnpm uses remote caching in CI environments, it causes `pnpm store prune` to be unable to accurately track which dependencies are still referenced, as symbolic links are broken during this process, affecting the accuracy of cache cleanup.

## Limitations of Current Solution

1. Relies on the `@npmcli/arborist` library to analyze the dependency tree, which increases the complexity and number of dependencies of the project.
2. Requires a valid `package-lock.json` and `node_modules` directory in the project to accurately analyze dependencies.
3. For certain special package management scenarios (such as complex dependencies in monorepos), there may be cases of inaccurate analysis.
4. Due to the need to traverse the entire dependency tree and compare it with cached content, for large projects there may be longer execution times, requiring evaluation of efficiency comparisons with other solutions.
5. Only supports cache cleanup for the npm ecosystem and is not applicable to other package managers.

## Installation

```bash
npm install -g @mod10/cicachecleaner
```

## Usage

```bash
# Basic usage (using default cache path)
ccc

# Specify cache path
ccc -p /path/to/cache

# Specify project location
ccc -l /path/to/project

# Dry run mode (only show what will be deleted)
ccc --dry-run

# Skip confirmation prompt
ccc --force

# Show help
ccc --help

# Show version
ccc --version
```

## Options

- `-p, --path <path>`: npm cache directory path (default: ~/.npm/_cacache)
- `-l, --location <dir>`: project location directory (default: current directory)
- `-d, --dry-run`: list what will be deleted without actually deleting
- `-f, --force`: skip confirmation prompt
- `-h, --help`: show help information
- `-v, --version`: show version information

## Development

```bash
# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Run Lint
npm run lint

# Link locally for CLI testing
npm link
```

## License

MIT