pncat/README.md

Enhanced pnpm catalogs management with advanced workspace dependency control.

# pncat

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![bundle][bundle-src]][bundle-href]
[![JSDocs][jsdocs-src]][jsdocs-href]
[![License][license-src]][license-href]

Advanced dependency management for pnpm workspaces with catalog support.

> [!NOTE]
> Enhanced pnpm workspace management with intelligent dependency cataloging, inspired by [taze](https://github.com/antfu-collective/taze) and [@antfu/nip](https://github.com/antfu/nip).

```bash
pnpm add -D pncat
```

## Features

**🔍 Detect** - Scan workspace to identify catalogable dependencies

**🚀 Migrate** - Automatically group dependencies by rules

**➕ Add** - Install dependencies with catalog support

**🗑️ Remove** - Safely remove dependencies with catalog awareness

**🧹 Clean** - Find and remove unused catalog dependencies

**↩️ Revert** - Revert cataloged dependencies to package.json

## Usage

### Detect Catalogable Dependencies

```bash
pncat detect
```

Scans your workspace to identify dependencies that could be moved to catalogs.

<p align='center'>
<img src='./assets/detect-r.png' />
</p>

### Smart Catalog Migration

```bash
pncat migrate -f
```

Automatically groups dependencies by rules (e.g., lint, test, utils), updating both `pnpm.workspace.yaml` and relevant `package.json`.

Default rules can be found in `src/rules.ts`. To customize rules, create a `pncat.config.ts` file in the root directory.

<p align='center'>
<img src='./assets/migrate-r.png' />
</p>

#### Migration Guide

To preserve existing catalogs, run `pncat migrate` - this will only migrate uncataloged dependencies.

To update catalog groups according to rules, run `pncat migrate -f`, or do a clean migration with `pncat revert` → `pncat migrate`.

### Add with Catalog Support

```bash
pncat add bumpp -D
```

Add dependencies with prompts and catalogs support (credit to [@antfu/nip](https://github.com/antfu/nip)). It also supports adding monorepo workspace packages using the `workspace:` protocol.

Starting from version 0.4.0, manual catalog specification is no longer supported. All dependencies are automatically assigned based on your catalog rules configuration.

<p align='center'>
<img src='./assets/add-r.png' />
</p>

### Safe Dependency Removal

```bash
pncat remove bumpp
```

Display which catalog group is using the dependency. If confirmed, it will remove the dependency from both `pnpm.workspace.yaml` and `package.json`.

<p align='center'>
<img src='./assets/remove-r.png' />
</p>

### Catalog Cleanup

```bash
pncat clean
```

Find unused catalog dependencies and remove them from `pnpm.workspace.yaml`.

<p align='center'>
<img src='./assets/clean-r.png' />
</p>

### Revert Cataloged Dependencies

```bash
pncat revert
```

Reverts cataloged dependencies to `package.json`. Useful for monorepo restructuring or migration.

<p align='center'>
<img src='./assets/revert-r.png' />
</p>

## Configuration

Create a `pncat.config.ts` file to customize catalog rules:

```ts
import { defineConfig, mergeCatalogRules } from 'pncat'

export default defineConfig({
  // To extend default rules instead, use:
  // catalogRules: mergeCatalogRules([...])
  catalogRules: [
    {
      name: 'vue',
      match: ['vue', 'vue-router', 'pinia'],
      // smaller numbers represent higher priority
      priority: 15,
      // Advanced: version-specific rules
      specifierRules: [
        { specifier: '<3.0.0', suffix: 'legacy', match: ['vue'] }
      ]
    }
  ],
  // Control how version ranges are processed
  specifierOptions: {
    skipComplexRanges: true,
    allowPreReleases: true,
    allowWildcards: false
  }
})
```

**Catalog Rules:**
- `name`: catalog name (required)
- `match`: packages to include, supports RegExp (required)
- `priority`: smaller numbers represent higher priority (optional)
- `specifierRules`: version-specific rules (optional)
  - `specifier`: semver range like ">=3.0.0", "<2.0.0" (required)
  - `match`: specific packages this rule applies to (optional, defaults to parent match)
  - `name`: complete catalog name (takes priority over suffix)
  - `suffix`: catalog suffix (e.g., "legacy", "modern")

**Specifier Options (optional):**
- `skipComplexRanges`: Skip complex ranges like "||", "-", ">=" (default: true)
- `skipRangeTypes`: Specific range types to skip (overrides skipComplexRanges)
  - `'||'`: Logical OR (e.g., "^3.0.0 || ^4.0.0")
  - `'-'`: Hyphen range (e.g., "1.2.3 - 2.3.4")
  - `'>='`, `'<='`, `'>'`, `'<'`: Comparison ranges
  - `'x'`: Wildcard (e.g., "3.x")
  - `'*'`: Any version
  - `'pre-release'`: Beta/alpha/rc versions
- `allowPreReleases`: Allow beta/alpha/rc versions (default: true)
- `allowWildcards`: Allow wildcard versions like "3.x", "*" (default: false)

## Why pncat?

For monorepo repositories, maintaining consistent dependency versions across multiple packages is crucial. Grouping dependencies can significantly improve project understanding, making it easier to collaborate within teams or keep track of the project's structure.

Currently, pnpm's catalog support is limited. For example, there is no built-in feature for adding or migrating dependencies into specific groups. Managing the catalog manually across the entire project can be time-consuming and error-prone. To address this, pncat was developed.

Additionally, when migrating a specific package in a monorepo that uses catalogs, it's important to also migrate the `pnpm.workspace.yaml` file. This requires manually comparing which catalogs need to be removed. To streamline this process, the `clean` and `revert` commands were introduced to automate this task.

Special thanks to [@antfu](https://github.com/antfu) — his article [Categorizing Dependencies](https://antfu.me/posts/categorize-deps) provided great inspiration and guidance during the development of this tool.

## Roadmap

### Core Features
- [x] Detect catalogable dependencies
- [x] Migrate to catalogs
- [x] Install dependency with catalog support
- [x] Safely remove dependency
- [x] Cleanup unused catalog dependencies
- [x] Revert cataloged dependencies version to `package.json`

### Advanced
- [x] Config file support
- [x] Custom grouping rules
- [x] Custom specifier processing
- [x] Specifier conflict resolution

## Related Projects

+ [eslint-plugin-pnpm-catalog](https://github.com/onmax/eslint-plugin-pnpm-catalog) by [@onmax](https://github.com/onmax) - ESLint plugin that enforces the use of named catalogs in pnpm workspaces

## License

[MIT](./LICENSE) License © [jinghaihan](https://github.com/jinghaihan)

<!-- Badges -->

[npm-version-src]: https://img.shields.io/npm/v/pncat?style=flat&colorA=080f12&colorB=1fa669
[npm-version-href]: https://npmjs.com/package/pncat
[npm-downloads-src]: https://img.shields.io/npm/dm/pncat?style=flat&colorA=080f12&colorB=1fa669
[npm-downloads-href]: https://npmjs.com/package/pncat
[bundle-src]: https://img.shields.io/bundlephobia/minzip/pncat?style=flat&colorA=080f12&colorB=1fa669&label=minzip
[bundle-href]: https://bundlephobia.com/result?p=pncat
[license-src]: https://img.shields.io/badge/license-MIT-blue.svg?style=flat&colorA=080f12&colorB=1fa669
[license-href]: https://github.com/jinghaihan/pncat/LICENSE
[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
[jsdocs-href]: https://www.jsdocs.io/package/pncat