Patchworks

Overview

Patchworks is a powerful CLI tool designed to streamline version management and change tracking in software projects. It helps developers efficiently manage dependency updates by providing semantic versioning analysis, breaking change detection, and batch selection capabilities.

Features

• Detects and processes breaking changes in dependencies.
• Generates update reports in Markdown and console formats.
• Fetches release notes and changelogs automatically from GitHub or fallback URLs.
• Validates package metadata to ensure required fields are present.
• Categorizes release notes into various types such as features, fixes, and breaking changes.
• Computes TF-IDF rankings for important terms in release notes.
• Provides a user-friendly command-line interface for managing updates.

Installation

Global Installation (Recommended)

Install Patchworks globally to use it from any directory:

npm install -g patchworks

Local Installation

Install Patchworks in your project:

npm install patchworks

Development Installation

For development or testing:

git clone https://github.com/shanemiller89/patchworks.git
cd patchworks
npm install
npm link  # Creates a global symlink for development

Requirements

• Node.js 14 or higher
• npm 6 or higher

Verify Installation

After installation, verify that Patchworks is working correctly:

# Check version
patchworks --version

# View available commands
patchworks --help

# Test a command (shows help for reports)
patchworks reports --help

If you encounter any issues, see the Troubleshooting section below.

Troubleshooting

Node.js Version Managers

If you're using a Node.js version manager (like nvm, asdf, or n), you might need additional steps:

• asdf: After installation, run asdf reshim nodejs
• nvm: No additional steps needed
• n: No additional steps needed

If the patchworks command is not found after installation:

1. Verify the installation: npm list -g patchworks
2. Check your PATH: echo $PATH
3. Try reinstalling: npm uninstall -g patchworks && npm install -g patchworks

Usage

Global Installation

If installed globally, use the command directly:

patchworks --help

Local Installation

If installed locally, use npx:

npx patchworks --help

Available Commands

Get help on any command:

patchworks help [command]

CLI Commands Reference

patchworks menu

Display the interactive main menu for navigating the tool.

# Basic usage
patchworks menu

# With specific level and options
patchworks menu minor --limit 5 --summary

Options:

• [level] - Optional update level (patch, minor, major)
• --limit <number> - Limit the number of updates processed
• --level-scope <scope> - Control semantic version filtering (strict or cascade)
• --summary - Generate a summary report
• --skipped - Show skipped packages in the output
• --install - Install dependencies after processing

patchworks update

Run the main update program with specified options.

# Update minor versions with limit
patchworks update minor --limit 10

# Update patch versions with installation
patchworks update patch --limit 5 --install

# Update with summary and show excluded packages
patchworks update major --summary --show-excluded

Arguments:

• <level> - Required update level (patch, minor, major)

Options:

• --limit <number> - Limit the number of updates processed
• --level-scope <scope> - Control semantic version filtering (strict or cascade)
• --summary - Generate a summary report
• --skipped - Show skipped packages in the output
• --install - Install dependencies after processing
• --exclude-repoless - Exclude packages without repositories
• --show-excluded - Show excluded packages in the console output

patchworks reports

Generate reports based on the current state of dependencies (read-only mode).

# Generate a minor version report
patchworks reports minor

# Generate patch report with summary
patchworks reports patch --summary --limit 20

# Generate comprehensive report showing all details
patchworks reports major --skipped --show-excluded

Arguments:

• <level> - Required update level (patch, minor, major)

Options:

• --limit <number> - Limit the number of updates processed
• --level-scope <scope> - Control semantic version filtering (strict or cascade)
• --summary - Generate a summary report
• --skipped - Show skipped packages in the output
• --exclude-repoless - Exclude packages without repositories
• --show-excluded - Show excluded packages in the console output

Example Workflows

Basic Update Workflow

# 1. First, generate a report to see what's available
patchworks reports minor --summary

# 2. Run the update process with a reasonable limit
patchworks update minor --limit 10 --summary

# 3. Use the interactive menu for more control
patchworks menu minor

Configuration Setup

Generate a default configuration file:

1. Run the main menu command:

   patchworks menu

2. Choose Generate Config to create patchworks-config.json in your project.

Advanced Usage

# Update only packages with repositories, excluding those without
patchworks update patch --exclude-repoless --limit 15

# Generate detailed report showing skipped packages
patchworks reports minor --skipped --show-excluded --summary

# Debug mode for troubleshooting
patchworks update minor --debug --limit 5

API Documentation

Patchworks can also be used as a module in your Node.js applications.

Basic Usage

import { main } from 'patchworks';
import { readConfig } from 'patchworks/config/configUtil.js';

// Run patchworks programmatically
const options = {
  level: 'minor',
  limit: 10,
  summary: true,
  reportsOnly: true // Generate reports without making changes
};

await main(options);

Core Functions

main(options)

Main entry point for running patchworks programmatically.

Parameters:

• options (Object) - Configuration options
  • level (String) - Update level: 'patch', 'minor', or 'major'
  • limit (Number) - Maximum number of packages to process
  • summary (Boolean) - Generate summary report
  • reportsOnly (Boolean) - Only generate reports, don't make changes
  • install (Boolean) - Install dependencies after processing
  • excludeRepoless (Boolean) - Exclude packages without repositories

readConfig()

Read configuration from patchworks-config.json.

import { readConfig } from 'patchworks/config/configUtil.js';

const config = await readConfig();
console.log(config); // { level: 'minor', limit: 10, ... }

Configuration Utilities

import { generateConfig } from 'patchworks/config/configUtil.js';

// Generate a default configuration file
await generateConfig();

Analysis Functions

TF-IDF Analysis

import { computeTFIDFRanking } from 'patchworks/analysis/computeTFIDFRanking.js';

const rankings = computeTFIDFRanking(releaseNotes);

Log Categorization

import { categorizeLogs } from 'patchworks/analysis/categorizeLogs.js';

const categories = categorizeLogs(logData);

Version Processing

import { processVersions } from 'patchworks/tasks/versionProcessor/versionProcessor.js';

const results = await processVersions(packages, options);

Notes

• This is the initial stable release of Patchworks
• Feedback and bug reports are welcome via GitHub issues
• For installation issues, please check the troubleshooting section above
• See CHANGELOG.md for version history and breaking changes

License

MIT License