@releasekit/version 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,209 @@
+import { LoadOptions } from '@releasekit/config';
+import { ReleaseType } from 'semver';
+import { Packages, Package } from '@manypkg/get-packages';
+import { ReleaseKitError, VersionPackageChangelog } from '@releasekit/core';
+
+interface VersionConfigBase {
+    versionPrefix: string;
+    type?: ReleaseType;
+    prereleaseIdentifier?: string;
+    branchPattern?: string[];
+    baseBranch?: string;
+    path?: string;
+    name?: string;
+}
+interface Config extends VersionConfigBase {
+    tagTemplate: string;
+    packageSpecificTags?: boolean;
+    preset: string;
+    sync: boolean;
+    packages: string[];
+    mainPackage?: string;
+    updateInternalDependencies: 'major' | 'minor' | 'patch' | 'no-internal-update';
+    skip?: string[];
+    commitMessage?: string;
+    versionStrategy?: 'branchPattern' | 'commitMessage';
+    branchPatterns?: BranchPattern[];
+    defaultReleaseType?: ReleaseType;
+    skipHooks?: boolean;
+    dryRun?: boolean;
+    latestTag?: string;
+    isPrerelease?: boolean;
+    mismatchStrategy?: 'error' | 'warn' | 'ignore' | 'prefer-package' | 'prefer-git';
+    cargo?: {
+        enabled?: boolean;
+        paths?: string[];
+    };
+}
+interface BranchPattern {
+    pattern: string;
+    releaseType: ReleaseType;
+}
+interface VersionOptions extends VersionConfigBase {
+    latestTag: string;
+}
+
+declare function loadConfig(options?: LoadOptions): Config;
+
+/**
+ * Version calculation logic
+ */
+
+/**
+ * Calculates the next version number based on the current version and options
+ */
+declare function calculateVersion(config: Config, options: VersionOptions): Promise<string>;
+
+/**
+ * Strategy functions for versioning using the higher-order function pattern
+ */
+
+/**
+ * Available strategy types
+ */
+type StrategyType = 'sync' | 'single' | 'async';
+/**
+ * Strategy function type
+ */
+type StrategyFunction = (packages: PackagesWithRoot, targets?: string[]) => Promise<void>;
+/**
+ * Create a sync versioning strategy function
+ */
+declare function createSyncStrategy(config: Config): StrategyFunction;
+/**
+ * Create a single package versioning strategy function
+ */
+declare function createSingleStrategy(config: Config): StrategyFunction;
+/**
+ * Create an async package versioning strategy function
+ */
+declare function createAsyncStrategy(config: Config): StrategyFunction;
+
+interface PackagesWithRoot extends Packages {
+    root: string;
+}
+/**
+ * Main versioning engine that uses functional strategies
+ */
+declare class VersionEngine {
+    private config;
+    private workspaceCache;
+    private strategies;
+    private currentStrategy;
+    constructor(config: Config, _jsonMode?: boolean);
+    /**
+     * Get workspace packages information - with caching for performance
+     */
+    getWorkspacePackages(): Promise<PackagesWithRoot>;
+    /**
+     * Run the current strategy
+     * @param packages Workspace packages to process
+     * @param targets Optional package targets to process (only used by async strategy)
+     */
+    run(packages: PackagesWithRoot, targets?: string[]): Promise<void>;
+    /**
+     * Change the current strategy
+     * @param strategyType The strategy type to use: 'sync', 'single', or 'async'
+     */
+    setStrategy(strategyType: StrategyType): void;
+}
+
+/**
+ * Version-specific base error that bridges the factory pattern
+ * used by @releasekit/version with the abstract ReleaseKitError base.
+ */
+declare class BaseVersionError extends ReleaseKitError {
+    readonly code: string;
+    readonly suggestions: string[];
+    constructor(message: string, code: string, suggestions?: string[]);
+    static isVersionError(error: unknown): error is BaseVersionError;
+}
+
+/**
+ * Custom error class for versioning operations
+ */
+declare class VersionError extends BaseVersionError {
+}
+/**
+ * Error codes for versioning operations
+ */
+declare enum VersionErrorCode {
+    CONFIG_REQUIRED = "CONFIG_REQUIRED",
+    PACKAGES_NOT_FOUND = "PACKAGES_NOT_FOUND",
+    WORKSPACE_ERROR = "WORKSPACE_ERROR",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    PACKAGE_NOT_FOUND = "PACKAGE_NOT_FOUND",
+    VERSION_CALCULATION_ERROR = "VERSION_CALCULATION_ERROR"
+}
+/**
+ * Creates a VersionError with standard error message for common failure scenarios
+ * @param code Error code
+ * @param details Additional error details
+ * @returns VersionError instance
+ */
+declare function createVersionError(code: VersionErrorCode, details?: string): VersionError;
+
+interface PackageProcessorOptions {
+    skip?: string[];
+    versionPrefix?: string;
+    tagTemplate?: string;
+    commitMessageTemplate?: string;
+    dryRun?: boolean;
+    skipHooks?: boolean;
+    getLatestTag: () => Promise<string | null>;
+    config: Omit<VersionConfigBase, 'versionPrefix' | 'path' | 'name'>;
+    fullConfig: Config;
+}
+interface ProcessResult {
+    updatedPackages: Array<{
+        name: string;
+        version: string;
+        path: string;
+    }>;
+    commitMessage?: string;
+    tags: string[];
+}
+declare class PackageProcessor {
+    private skip;
+    private versionPrefix;
+    private tagTemplate?;
+    private commitMessageTemplate;
+    private dryRun;
+    private skipHooks;
+    private getLatestTag;
+    private config;
+    private fullConfig;
+    constructor(options: PackageProcessorOptions);
+    /**
+     * Process packages based on skip list only (targeting handled at discovery time)
+     */
+    processPackages(packages: Package[]): Promise<ProcessResult>;
+}
+
+/**
+ * JSON Output service for releasekit-version
+ * Centralizes all JSON output handling
+ */
+
+interface JsonOutputData {
+    dryRun: boolean;
+    updates: Array<{
+        packageName: string;
+        newVersion: string;
+        filePath: string;
+    }>;
+    changelogs: VersionPackageChangelog[];
+    commitMessage?: string;
+    tags: string[];
+}
+/**
+ * Enable JSON output mode
+ * @param dryRun Whether this is a dry run
+ */
+declare function enableJsonOutput(dryRun?: boolean): void;
+/**
+ * Get the current JSON output data (for testing)
+ */
+declare function getJsonData(): JsonOutputData;
+
+export { BaseVersionError, type Config, type JsonOutputData, PackageProcessor, type VersionConfigBase, VersionEngine, VersionErrorCode, calculateVersion, createAsyncStrategy, createSingleStrategy, createSyncStrategy, createVersionError, enableJsonOutput, getJsonData, loadConfig };

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import { LoadOptions } from '@releasekit/config';
+import { ReleaseType } from 'semver';
+import { Packages, Package } from '@manypkg/get-packages';
+import { ReleaseKitError, VersionPackageChangelog } from '@releasekit/core';
+
+interface VersionConfigBase {
+    versionPrefix: string;
+    type?: ReleaseType;
+    prereleaseIdentifier?: string;
+    branchPattern?: string[];
+    baseBranch?: string;
+    path?: string;
+    name?: string;
+}
+interface Config extends VersionConfigBase {
+    tagTemplate: string;
+    packageSpecificTags?: boolean;
+    preset: string;
+    sync: boolean;
+    packages: string[];
+    mainPackage?: string;
+    updateInternalDependencies: 'major' | 'minor' | 'patch' | 'no-internal-update';
+    skip?: string[];
+    commitMessage?: string;
+    versionStrategy?: 'branchPattern' | 'commitMessage';
+    branchPatterns?: BranchPattern[];
+    defaultReleaseType?: ReleaseType;
+    skipHooks?: boolean;
+    dryRun?: boolean;
+    latestTag?: string;
+    isPrerelease?: boolean;
+    mismatchStrategy?: 'error' | 'warn' | 'ignore' | 'prefer-package' | 'prefer-git';
+    cargo?: {
+        enabled?: boolean;
+        paths?: string[];
+    };
+}
+interface BranchPattern {
+    pattern: string;
+    releaseType: ReleaseType;
+}
+interface VersionOptions extends VersionConfigBase {
+    latestTag: string;
+}
+
+declare function loadConfig(options?: LoadOptions): Config;
+
+/**
+ * Version calculation logic
+ */
+
+/**
+ * Calculates the next version number based on the current version and options
+ */
+declare function calculateVersion(config: Config, options: VersionOptions): Promise<string>;
+
+/**
+ * Strategy functions for versioning using the higher-order function pattern
+ */
+
+/**
+ * Available strategy types
+ */
+type StrategyType = 'sync' | 'single' | 'async';
+/**
+ * Strategy function type
+ */
+type StrategyFunction = (packages: PackagesWithRoot, targets?: string[]) => Promise<void>;
+/**
+ * Create a sync versioning strategy function
+ */
+declare function createSyncStrategy(config: Config): StrategyFunction;
+/**
+ * Create a single package versioning strategy function
+ */
+declare function createSingleStrategy(config: Config): StrategyFunction;
+/**
+ * Create an async package versioning strategy function
+ */
+declare function createAsyncStrategy(config: Config): StrategyFunction;
+
+interface PackagesWithRoot extends Packages {
+    root: string;
+}
+/**
+ * Main versioning engine that uses functional strategies
+ */
+declare class VersionEngine {
+    private config;
+    private workspaceCache;
+    private strategies;
+    private currentStrategy;
+    constructor(config: Config, _jsonMode?: boolean);
+    /**
+     * Get workspace packages information - with caching for performance
+     */
+    getWorkspacePackages(): Promise<PackagesWithRoot>;
+    /**
+     * Run the current strategy
+     * @param packages Workspace packages to process
+     * @param targets Optional package targets to process (only used by async strategy)
+     */
+    run(packages: PackagesWithRoot, targets?: string[]): Promise<void>;
+    /**
+     * Change the current strategy
+     * @param strategyType The strategy type to use: 'sync', 'single', or 'async'
+     */
+    setStrategy(strategyType: StrategyType): void;
+}
+
+/**
+ * Version-specific base error that bridges the factory pattern
+ * used by @releasekit/version with the abstract ReleaseKitError base.
+ */
+declare class BaseVersionError extends ReleaseKitError {
+    readonly code: string;
+    readonly suggestions: string[];
+    constructor(message: string, code: string, suggestions?: string[]);
+    static isVersionError(error: unknown): error is BaseVersionError;
+}
+
+/**
+ * Custom error class for versioning operations
+ */
+declare class VersionError extends BaseVersionError {
+}
+/**
+ * Error codes for versioning operations
+ */
+declare enum VersionErrorCode {
+    CONFIG_REQUIRED = "CONFIG_REQUIRED",
+    PACKAGES_NOT_FOUND = "PACKAGES_NOT_FOUND",
+    WORKSPACE_ERROR = "WORKSPACE_ERROR",
+    INVALID_CONFIG = "INVALID_CONFIG",
+    PACKAGE_NOT_FOUND = "PACKAGE_NOT_FOUND",
+    VERSION_CALCULATION_ERROR = "VERSION_CALCULATION_ERROR"
+}
+/**
+ * Creates a VersionError with standard error message for common failure scenarios
+ * @param code Error code
+ * @param details Additional error details
+ * @returns VersionError instance
+ */
+declare function createVersionError(code: VersionErrorCode, details?: string): VersionError;
+
+interface PackageProcessorOptions {
+    skip?: string[];
+    versionPrefix?: string;
+    tagTemplate?: string;
+    commitMessageTemplate?: string;
+    dryRun?: boolean;
+    skipHooks?: boolean;
+    getLatestTag: () => Promise<string | null>;
+    config: Omit<VersionConfigBase, 'versionPrefix' | 'path' | 'name'>;
+    fullConfig: Config;
+}
+interface ProcessResult {
+    updatedPackages: Array<{
+        name: string;
+        version: string;
+        path: string;
+    }>;
+    commitMessage?: string;
+    tags: string[];
+}
+declare class PackageProcessor {
+    private skip;
+    private versionPrefix;
+    private tagTemplate?;
+    private commitMessageTemplate;
+    private dryRun;
+    private skipHooks;
+    private getLatestTag;
+    private config;
+    private fullConfig;
+    constructor(options: PackageProcessorOptions);
+    /**
+     * Process packages based on skip list only (targeting handled at discovery time)
+     */
+    processPackages(packages: Package[]): Promise<ProcessResult>;
+}
+
+/**
+ * JSON Output service for releasekit-version
+ * Centralizes all JSON output handling
+ */
+
+interface JsonOutputData {
+    dryRun: boolean;
+    updates: Array<{
+        packageName: string;
+        newVersion: string;
+        filePath: string;
+    }>;
+    changelogs: VersionPackageChangelog[];
+    commitMessage?: string;
+    tags: string[];
+}
+/**
+ * Enable JSON output mode
+ * @param dryRun Whether this is a dry run
+ */
+declare function enableJsonOutput(dryRun?: boolean): void;
+/**
+ * Get the current JSON output data (for testing)
+ */
+declare function getJsonData(): JsonOutputData;
+
+export { BaseVersionError, type Config, type JsonOutputData, PackageProcessor, type VersionConfigBase, VersionEngine, VersionErrorCode, calculateVersion, createAsyncStrategy, createSingleStrategy, createSyncStrategy, createVersionError, enableJsonOutput, getJsonData, loadConfig };

package/dist/index.js

@@ -0,0 +1,30 @@
+import {
+  PackageProcessor,
+  VersionEngine,
+  VersionErrorCode,
+  calculateVersion,
+  createAsyncStrategy,
+  createSingleStrategy,
+  createSyncStrategy,
+  createVersionError,
+  enableJsonOutput,
+  getJsonData,
+  loadConfig
+} from "./chunk-GLFC564Q.js";
+import {
+  BaseVersionError
+} from "./chunk-GQLJ7JQY.js";
+export {
+  BaseVersionError,
+  PackageProcessor,
+  VersionEngine,
+  VersionErrorCode,
+  calculateVersion,
+  createAsyncStrategy,
+  createSingleStrategy,
+  createSyncStrategy,
+  createVersionError,
+  enableJsonOutput,
+  getJsonData,
+  loadConfig
+};

package/docs/CI_CD_INTEGRATION.md

@@ -0,0 +1,197 @@
+# CI/CD Integration
+
+`package-versioner` is designed to work seamlessly in CI/CD pipelines, making it easy to automate versioning as part of your release workflow.
+
+## JSON Output Mode
+
+For programmatic consumption in CI/CD scripts, `package-versioner` provides a structured JSON output option:
+
+```bash
+# Output results in JSON format
+npx package-versioner --json
+
+# Combine with dry-run for planning
+npx package-versioner --dry-run --json
+```
+
+This will suppress all normal console output and instead output a single JSON object containing:
+
+```json
+{
+  "dryRun": false,                            // Whether this was a dry run
+  "updates": [                                // Array of packages that were updated
+    {
+      "packageName": "@scope/package-a",     // Package name
+      "newVersion": "1.2.3",                 // New version number
+      "filePath": "/path/to/package.json"    // Path to the updated package.json
+    }
+  ],
+  "changelogs": [                            // Structured changelog data per package
+    {
+      "packageName": "@scope/package-a",     // Package name
+      "version": "1.2.3",                   // New version
+      "previousVersion": "v1.2.2",          // Previous tag (null if none)
+      "revisionRange": "v1.2.2..HEAD",      // Git revision range used
+      "repoUrl": "https://github.com/org/repo", // Repository URL (null if unknown)
+      "entries": [                           // Parsed changelog entries
+        { "type": "added", "description": "New feature", "scope": "core" },
+        { "type": "fixed", "description": "Bug fix" }
+      ]
+    }
+  ],
+  "commitMessage": "chore(release): v1.2.3", // The commit message that was used
+  "tags": [                                  // Array of tags that were created
+    "v1.2.3"                                 // or package-specific tags in targeted mode
+  ]
+}
+```
+
+### Benefits of JSON Output
+
+The structured JSON output provides several advantages for CI/CD integration:
+
+- **Reliable Parsing**: Unlike text logs that might change format or include ANSI color codes, the JSON structure remains consistent
+- **Programmatic Access**: Easily extract specific values like version numbers for subsequent steps
+- **Conditional Workflows**: Trigger different CI actions based on the presence of updates or specific version changes
+- **Audit Trail**: Store the JSON output as artifacts for version change tracking
+- **Error Handling**: Better detect and respond to versioning issues in your pipeline
+
+## Sample CI/CD Integration Patterns
+
+Here are some common ways to incorporate `package-versioner` into your CI/CD pipeline:
+
+### GitHub Actions Workflow Example
+
+```yaml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  version:
+    runs-on: ubuntu-latest
+    outputs:
+      changes_detected: ${{ steps.version.outputs.changes_detected }}
+      new_version: ${{ steps.version.outputs.new_version }}
+    
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0  # Important for git history
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Determine version
+        id: version
+        run: |
+          # Run in JSON mode for parsing
+          VERSION_OUTPUT=$(npx package-versioner --json)
+          echo "Version output: $VERSION_OUTPUT"
+          
+          # Use jq to parse the JSON output
+          CHANGES_DETECTED=$(echo "$VERSION_OUTPUT" | jq -r '.updates | length > 0')
+          echo "changes_detected=$CHANGES_DETECTED" >> $GITHUB_OUTPUT
+          
+          if [ "$CHANGES_DETECTED" = "true" ]; then
+            # Extract the first package's new version as representative version
+            NEW_VERSION=$(echo "$VERSION_OUTPUT" | jq -r '.updates[0].newVersion')
+            echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          fi
+  
+  publish:
+    needs: version
+    if: needs.version.outputs.changes_detected == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      # Publishing steps using the detected version
+      - run: echo "Would publish version ${{ needs.version.outputs.new_version }}"
+```
+
+### GitLab CI Pipeline Example
+
+```yaml
+stages:
+  - version
+  - publish
+
+determine_version:
+  stage: version
+  script:
+    - npm ci
+    - |
+      VERSION_OUTPUT=$(npx package-versioner --json)
+      echo "VERSION_OUTPUT=$VERSION_OUTPUT" >> version.env
+      
+      # Parse values for use in later stages
+      CHANGES_DETECTED=$(echo "$VERSION_OUTPUT" | jq -r '.updates | length > 0')
+      echo "CHANGES_DETECTED=$CHANGES_DETECTED" >> version.env
+      
+      if [ "$CHANGES_DETECTED" = "true" ]; then
+        NEW_VERSION=$(echo "$VERSION_OUTPUT" | jq -r '.updates[0].newVersion')
+        echo "NEW_VERSION=$NEW_VERSION" >> version.env
+      fi
+  artifacts:
+    reports:
+      dotenv: version.env
+
+publish:
+  stage: publish
+  needs: determine_version
+  script:
+    - echo "Publishing version $NEW_VERSION"
+  rules:
+    - if: $CHANGES_DETECTED == "true"
+```
+
+## Working with Tags in CI
+
+When using the targeted mode with `-t` flag, `package-versioner` creates package-specific tags (e.g., `@scope/package-a@1.2.0`) but not a global tag. If your release process needs a global tag, you can add a step to your CI/CD pipeline:
+
+```bash
+# Create a global tag based on the representative version
+NEW_VERSION=$(echo "$VERSION_OUTPUT" | jq -r '.updates[0].newVersion')
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
+git push origin "v$NEW_VERSION"
+```
+
+## Environment Variables
+
+`package-versioner` respects the following environment variables:
+
+- `NO_COLOR=1`: Disables colored output in logs (automatically detected in CI environments)
+- `CI=true`: Most CI environments set this automatically, which helps the tool adjust its output behaviour
+
+## Skipping CI for Version Commits
+
+If you want to prevent additional CI runs when version commits are made, you can include CI skip flags in your commit message template in `version.config.json`:
+
+```json
+{
+  "commitMessage": "chore(release): ${version} [skip ci]",
+  // other configuration options...
+}
+```
+
+Common CI skip patterns include:
+- `[skip ci]` or `[ci skip]` - Works in GitHub Actions, GitLab CI, CircleCI
+- `[skip-ci]` - Alternative format supported by some CI systems
+- `[no ci]` - Another variant 
+
+Each CI system might have slightly different syntax, so check your CI provider's documentation for the exact skip token to use.
+
+## Tips for Reliable CI/CD Integration
+
+1. **Always use `--json`** in CI/CD pipelines for consistent output parsing
+2. **Use the `fetch-depth: 0`** option in GitHub Actions (or equivalent in other CIs) to ensure access to the full Git history
+3. **Store the JSON output** as a build artifact for debugging and auditing
+4. **Consider dry runs** in your preview/staging branches to validate version changes before they're applied
+5. **Use `--project-dir`** when running from a different directory than your project root
+6. **Be mindful of Git credentials** - ensure your CI has proper permissions for creating commits and tags