package-versioner 0.2.0 → 0.4.0

package/docs/CI_CD_INTEGRATION.md

@@ -0,0 +1,165 @@
+# 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
+    }
+  ],
+  "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 behavior
+
+## 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. **Be mindful of Git credentials** - ensure your CI has proper permissions for creating commits and tags 

package/docs/VERSIONING_STRATEGIES.md

@@ -94,3 +94,42 @@ This is the default if the `synced` flag is present and true.
     -   Finally, a **single commit** is created including all the updated `package.json` files, using a summary commit message (e.g., `chore(release): pkg-a, pkg-b 1.2.3 [skip-ci]`).
     -   **Important:** Only package-specific tags are created. The global tag (e.g., `v1.2.3`) is **not** automatically generated in this mode. If your release process (like GitHub Releases) depends on a global tag, you'll need to create it manually in your CI/CD script *after* `package-versioner` completes.
 -   **Use Case:** Releasing specific packages independently while still tagging each released package individually.
+
+## Prerelease Handling
+
+`package-versioner` provides flexible handling for prerelease versions, allowing both creation of prereleases and promotion to stable releases.
+
+### Creating Prereleases
+
+Use the `--prerelease` flag with an identifier to create a prerelease version:
+
+```bash
+# Create a beta prerelease
+npx package-versioner --bump minor --prerelease beta
+# Result: 1.0.0 -> 1.1.0-beta.0
+```
+
+You can also set a default prerelease identifier in your `version.config.json`:
+
+```json
+{
+  "prereleaseIdentifier": "beta"
+}
+```
+
+### Promoting Prereleases to Stable Releases
+
+When using standard bump types (`major`, `minor`, `patch`) with the `--bump` flag on a prerelease version, `package-versioner` will automatically clean the prerelease identifier:
+
+```bash
+# Starting from version 1.0.0-beta.1
+npx package-versioner --bump major
+# Result: 1.0.0-beta.1 -> 2.0.0 (not 2.0.0-beta.0)
+```
+
+This intuitive behavior means you don't need to use an empty prerelease identifier (`--prerelease ""`) to promote a prerelease to a stable version. Simply specify the standard bump type and the tool will automatically produce a clean version number.
+
+This applies to all standard bump types:
+- `--bump major`: 1.0.0-beta.1 -> 2.0.0
+- `--bump minor`: 1.0.0-beta.1 -> 1.1.0 
+- `--bump patch`: 1.0.0-beta.1 -> 1.0.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "package-versioner",
-  "description": "A powerful CLI tool for automated semantic versioning based on Git history and conventional commits. Supports monorepos with synchronized or independent package versioning strategies.",
-  "version": "0.2.0",
+  "description": "A lightweight yet powerful CLI tool for automated semantic versioning based on Git history and conventional commits.",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -39,11 +39,11 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@types/figlet": "^1.5.5",
-    "@types/node": "^22.14.0",
+    "@types/node": "^22.14.1",
     "@types/semver": "^7.3.13",
     "@vitest/coverage-v8": "^3.1.1",
     "husky": "^9.1.7",
-    "lint-staged": "^15.5.0",
+    "lint-staged": "^15.5.1",
     "tsup": "^8.4.0",
     "typescript": "^5.8.3",
     "vitest": "^3.1.1"
@@ -54,7 +54,7 @@
     "commander": "^13.1.0",
     "conventional-changelog-angular": "^8.0.0",
     "conventional-recommended-bump": "^11.0.0",
-    "figlet": "^1.8.0",
+    "figlet": "^1.8.1",
     "git-semver-tags": "^8.0.0",
     "semver": "^7.7.1"
   },