@releasekit/version 0.3.1 → 0.4.0

package/README.md

@@ -133,10 +133,19 @@ Configure via `releasekit.config.json`:
 | `cargo.enabled` | Update Cargo.toml files | `true` |
 | `cargo.paths` | Directories containing Cargo.toml | auto-detect |
 
+## Using in CI
+
+A few things to keep in mind when running `releasekit-version` in a pipeline:
+
+- **Always pass `fetch-depth: 0`** on checkout — the tool reads git history to determine the version bump and will produce incorrect results on a shallow clone.
+- **Use `--json`** for reliable downstream parsing. Text output format can change; the JSON schema is stable.
+- **`NO_COLOR=1`** disables ANSI colour codes in log output. Most CI environments set `CI=true` automatically, which the tool detects and adjusts for.
+
+If you are running the full release pipeline (version + changelog + publish), use `@releasekit/release` instead of invoking `releasekit-version` directly. See the [CI setup guide](../release/docs/ci-setup.md).
+
 ## Documentation
 
 - [Versioning Strategies and Concepts](./docs/versioning.md)
-- [CI/CD Integration](./docs/CI_CD_INTEGRATION.md)
 
 ## Acknowledgements
 

package/dist/{chunk-V6S7BEBD.js → chunk-ZTFI7TXV.js}

@@ -122,14 +122,14 @@ var GitHubReleaseConfigSchema = z.object({
   perPackage: z.boolean().default(true),
   prerelease: z.union([z.literal("auto"), z.boolean()]).default("auto"),
   /**
-   * Controls how release notes are sourced for GitHub releases.
-   * - 'auto': Use RELEASE_NOTES.md if it exists, then per-package changelog
-   *   data from the version output, then GitHub's auto-generated notes.
-   * - 'github': Always use GitHub's auto-generated notes.
-   * - 'none': No notes body.
-   * - Any other string: Treated as a file path to read notes from.
+   * Controls the source for the GitHub release body.
+   * - 'auto': Use release notes if enabled, else changelog, else GitHub auto-generated.
+   * - 'releaseNotes': Use LLM-generated release notes (requires notes.releaseNotes.enabled: true).
+   * - 'changelog': Use formatted changelog entries.
+   * - 'generated': Use GitHub's auto-generated notes.
+   * - 'none': No body.
    */
-  releaseNotes: z.union([z.literal("auto"), z.literal("github"), z.literal("none"), z.string()]).default("auto")
+  body: z.enum(["auto", "releaseNotes", "changelog", "generated", "none"]).default("auto")
 });
 var VerifyRegistryConfigSchema = z.object({
   enabled: z.boolean().default(true),
@@ -173,7 +173,7 @@ var PublishConfigSchema = z.object({
     draft: true,
     perPackage: true,
     prerelease: "auto",
-    releaseNotes: "auto"
+    body: "auto"
   }),
   verify: VerifyConfigSchema.default({
     npm: {
@@ -194,10 +194,10 @@ var TemplateConfigSchema = z.object({
   path: z.string().optional(),
   engine: z.enum(["handlebars", "liquid", "ejs"]).optional()
 });
-var OutputConfigSchema = z.object({
-  format: z.enum(["markdown", "github-release", "json"]),
+var LocationModeSchema = z.enum(["root", "packages", "both"]);
+var ChangelogConfigSchema = z.object({
+  mode: LocationModeSchema.optional(),
   file: z.string().optional(),
-  options: z.record(z.string(), z.unknown()).optional(),
   templates: TemplateConfigSchema.optional()
 });
 var LLMOptionsSchema = z.object({
@@ -257,17 +257,20 @@ var LLMConfigSchema = z.object({
   scopes: ScopeConfigSchema.optional(),
   prompts: LLMPromptsConfigSchema.optional()
 });
+var ReleaseNotesConfigSchema = z.object({
+  mode: LocationModeSchema.optional(),
+  file: z.string().optional(),
+  templates: TemplateConfigSchema.optional(),
+  llm: LLMConfigSchema.optional()
+});
 var NotesInputConfigSchema = z.object({
   source: z.string().optional(),
   file: z.string().optional()
 });
 var NotesConfigSchema = z.object({
-  input: NotesInputConfigSchema.optional(),
-  output: z.array(OutputConfigSchema).default([{ format: "markdown", file: "CHANGELOG.md" }]),
-  monorepo: MonorepoConfigSchema.optional(),
-  templates: TemplateConfigSchema.optional(),
-  llm: LLMConfigSchema.optional(),
-  updateStrategy: z.enum(["prepend", "regenerate"]).default("prepend")
+  changelog: z.union([z.literal(false), ChangelogConfigSchema]).optional(),
+  releaseNotes: z.union([z.literal(false), ReleaseNotesConfigSchema]).optional(),
+  updateStrategy: z.enum(["prepend", "regenerate"]).optional()
 });
 var CILabelsConfigSchema = z.object({
   stable: z.string().default("release:stable"),
@@ -629,6 +632,7 @@ function formatVersionPrefix(prefix) {
   return prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
 }
 function formatTag(version, prefix, packageName, template, packageSpecificTags) {
+  const sanitizedPackageName = packageName?.startsWith("@") ? packageName.slice(1).replace(/\//g, "-") : packageName;
   if (template?.includes("${packageName}") && !packageName) {
     log(
       `Warning: Your tagTemplate contains \${packageName} but no package name is available.
@@ -642,10 +646,10 @@ To fix this:
     );
   }
   if (template) {
-    return template.replace(/\$\{version\}/g, version).replace(/\$\{prefix\}/g, prefix).replace(/\$\{packageName\}/g, packageName || "");
+    return template.replace(/\$\{version\}/g, version).replace(/\$\{prefix\}/g, prefix).replace(/\$\{packageName\}/g, sanitizedPackageName || "");
   }
-  if (packageSpecificTags && packageName) {
-    return `${packageName}@${prefix}${version}`;
+  if (packageSpecificTags && sanitizedPackageName) {
+    return `${sanitizedPackageName}@${prefix}${version}`;
   }
   return `${prefix}${version}`;
 }
@@ -742,9 +746,10 @@ async function lastMergeBranchName(branches, baseBranch) {
 }
 async function getLatestTagForPackage(packageName, versionPrefix, options) {
   try {
-    const tagTemplate = options?.tagTemplate || `\${prefix}\${version}`;
     const packageSpecificTags = options?.packageSpecificTags ?? false;
-    const escapedPackageName = escapeRegExp(packageName);
+    const tagTemplate = options?.tagTemplate || (packageSpecificTags ? `\${packageName}@\${prefix}\${version}` : `\${prefix}\${version}`);
+    const sanitizedPackageName = packageName.startsWith("@") ? packageName.slice(1).replace(/\//g, "-") : packageName;
+    const escapedPackageName = escapeRegExp(sanitizedPackageName);
     const escapedPrefix = versionPrefix ? escapeRegExp(versionPrefix) : "";
     log(
       `Looking for tags for package ${packageName} with prefix ${versionPrefix || "none"}, packageSpecificTags: ${packageSpecificTags}`,
@@ -763,45 +768,20 @@ async function getLatestTagForPackage(packageName, versionPrefix, options) {
       const packageTagPattern = escapeRegExp(tagTemplate).replace(/\\\$\\\{packageName\\\}/g, `(?:${escapedPackageName})`).replace(/\\\$\\\{prefix\\\}/g, `(?:${escapedPrefix})`).replace(/\\\$\\\{version\\\}/g, "(?:[0-9]+\\.[0-9]+\\.[0-9]+(?:-[a-zA-Z0-9.-]+)?)");
       log(`Using package tag pattern: ${packageTagPattern}`, "debug");
       const packageTagRegex = new RegExp(`^${packageTagPattern}$`);
-      let packageTags = allTags.filter((tag) => packageTagRegex.test(tag));
+      const packageTags = allTags.filter((tag) => packageTagRegex.test(tag));
       log(`Found ${packageTags.length} matching tags for ${packageName}`, "debug");
       if (packageTags.length > 0) {
         log(`Found ${packageTags.length} package tags using configured pattern`, "debug");
         log(`Using most recently created tag: ${packageTags[0]}`, "debug");
         return packageTags[0];
       }
-      if (versionPrefix) {
-        const pattern1 = new RegExp(`^${escapedPackageName}@${escapeRegExp(versionPrefix)}`);
-        packageTags = allTags.filter((tag) => pattern1.test(tag));
-        if (packageTags.length > 0) {
-          log(`Found ${packageTags.length} package tags using pattern: packageName@${versionPrefix}...`, "debug");
-          log(`Using most recently created tag: ${packageTags[0]}`, "debug");
-          return packageTags[0];
-        }
-      }
-      if (versionPrefix) {
-        const pattern2 = new RegExp(`^${escapeRegExp(versionPrefix)}${escapedPackageName}@`);
-        packageTags = allTags.filter((tag) => pattern2.test(tag));
-        if (packageTags.length > 0) {
-          log(`Found ${packageTags.length} package tags using pattern: ${versionPrefix}packageName@...`, "debug");
-          log(`Using most recently created tag: ${packageTags[0]}`, "debug");
-          return packageTags[0];
-        }
-      }
-      const pattern3 = new RegExp(`^${escapedPackageName}@`);
-      packageTags = allTags.filter((tag) => pattern3.test(tag));
-      if (packageTags.length === 0) {
-        log("No matching tags found for pattern: packageName@version", "debug");
-        if (allTags.length > 0) {
-          log(`Available tags: ${allTags.join(", ")}`, "debug");
-        } else {
-          log("No tags available in the repository", "debug");
-        }
-        return "";
+      log("No matching tags found for configured tag pattern", "debug");
+      if (allTags.length > 0) {
+        log(`Available tags: ${allTags.join(", ")}`, "debug");
+      } else {
+        log("No tags available in the repository", "debug");
       }
-      log(`Found ${packageTags.length} package tags for ${packageName}`, "debug");
-      log(`Using most recently created tag: ${packageTags[0]}`, "debug");
-      return packageTags[0];
+      return "";
     }
     log(`Package-specific tags disabled for ${packageName}, falling back to global tags`, "debug");
     return "";
@@ -1863,30 +1843,38 @@ function createSyncStrategy(config) {
       let latestTag = await getLatestTag();
       let mainPkgPath = packages.root;
       let mainPkgName;
+      let versionSourcePath = mainPkgPath;
+      let versionSourceName;
       if (mainPackage) {
         const mainPkg = packages.packages.find((p) => p.packageJson.name === mainPackage);
         if (mainPkg) {
           mainPkgPath = mainPkg.dir;
           mainPkgName = mainPkg.packageJson.name;
+          versionSourcePath = mainPkgPath;
+          versionSourceName = mainPkgName;
           log(`Using ${mainPkgName} as primary package for version determination`, "info");
         } else {
           log(`Main package '${mainPackage}' not found. Using root package for version determination.`, "warning");
         }
+      } else if (packages.packages.length > 0) {
+        versionSourcePath = packages.packages[0].dir;
+        versionSourceName = packages.packages[0].packageJson.name;
+        log(`No mainPackage specified; using ${versionSourceName} as sync version source`, "info");
       }
       if (!mainPkgPath) {
         mainPkgPath = process.cwd();
         log(`No valid package path found, using current working directory: ${mainPkgPath}`, "warning");
       }
-      if (mainPkgName) {
-        const packageSpecificTag = await getLatestTagForPackage(mainPkgName, formattedPrefix, {
+      if (versionSourceName) {
+        const packageSpecificTag = await getLatestTagForPackage(versionSourceName, formattedPrefix, {
           tagTemplate,
           packageSpecificTags: config.packageSpecificTags
         });
         if (packageSpecificTag) {
           latestTag = packageSpecificTag;
-          log(`Using package-specific tag for ${mainPkgName}: ${latestTag}`, "debug");
+          log(`Using package-specific tag for ${versionSourceName}: ${latestTag}`, "debug");
         } else {
-          log(`No package-specific tag found for ${mainPkgName}, using global tag: ${latestTag}`, "debug");
+          log(`No package-specific tag found for ${versionSourceName}, using global tag: ${latestTag}`, "debug");
         }
       }
       const nextVersion = await calculateVersion(config, {
@@ -1895,8 +1883,8 @@ function createSyncStrategy(config) {
         branchPattern,
         baseBranch,
         prereleaseIdentifier,
-        path: mainPkgPath,
-        name: mainPkgName,
+        path: versionSourcePath,
+        name: versionSourceName,
         type: config.type
       });
       if (!nextVersion) {
@@ -2002,7 +1990,10 @@ function createSyncStrategy(config) {
         nextVersion,
         formattedPrefix,
         tagPackageName,
-        tagTemplate,
+        // Only pass tagTemplate when we have a package name to substitute into it.
+        // In multi-package sync mode tagPackageName is null, so omit the template to
+        // avoid a spurious ${packageName} warning and a malformed tag like "-v1.0.0".
+        tagPackageName ? tagTemplate : void 0,
         config.packageSpecificTags || false
       );
       let formattedCommitMessage;

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   loadConfig,
   log,
   printJsonOutput
-} from "./chunk-V6S7BEBD.js";
+} from "./chunk-ZTFI7TXV.js";
 import {
   readPackageVersion
 } from "./chunk-2MN2VLZF.js";

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   flushPendingWrites,
   getJsonData,
   loadConfig
-} from "./chunk-V6S7BEBD.js";
+} from "./chunk-ZTFI7TXV.js";
 import {
   BaseVersionError
 } from "./chunk-2MN2VLZF.js";

package/docs/versioning.md

@@ -4,7 +4,7 @@
 
 ## How the Next Version is Calculated
 
-There are two primary methods the tool uses to decide the version bump (e.g., patch, minor, major), configured via the `versionStrategy` option in `version.config.json`:
+There are two primary methods the tool uses to decide the version bump (e.g., patch, minor, major), configured via the `versionStrategy` option in `releasekit.config.json`:
 
 ### 1. Conventional Commits (`versionStrategy: "conventional"`)
 
@@ -14,7 +14,7 @@ This is the default strategy. `releasekit-version` analyzes Git commit messages
 -   **Minor Bump (e.g., 1.2.3 -> 1.3.0):** Triggered by `feat:` commit types.
 -   **Major Bump (e.g., 1.2.3 -> 2.0.0):** Triggered by commits with `BREAKING CHANGE:` in the footer or `feat!:`, `fix!:` etc. in the header.
 
-The specific preset used for analysis (e.g., "angular", "conventional") can be set using the `preset` option in `version.config.json`.
+The specific preset used for analysis (e.g., "angular", "conventional") can be set using the `preset` option in `releasekit.config.json`.
 
 **Format:** `<type>(<scope>): <subject>`
 
@@ -39,9 +39,9 @@ The specific preset used for analysis (e.g., "angular", "conventional") can be s
 
 This strategy uses the name of the current Git branch (or the most recently merged branch matching a pattern, if applicable) to determine the version bump.
 
-You define patterns in the `branchPattern` array in `version.config.json`. Each pattern is a string like `"prefix:bumptype"`.
+You define patterns in the `branchPattern` array in `releasekit.config.json`. Each pattern is a string like `"prefix:bumptype"`.
 
-**Example `version.config.json`:**
+**Example `releasekit.config.json`:**
 
 ```json
 {
@@ -156,7 +156,7 @@ Mismatches are detected in the following cases:
 - Git tag is ahead by a major or minor version (e.g., tag `2.0.0` vs package `1.0.0`)
 - Git tag is a prerelease but package.json is a stable release (e.g., tag `1.0.0-beta.1` vs package `1.0.0`)
 
-Configure it in `version.config.json`:
+Configure it in `releasekit.config.json`:
 ```json
 {
   "mismatchStrategy": "prefer-package"
@@ -277,7 +277,7 @@ This configuration will process all packages in the `@mycompany` scope except fo
 
 ### Tag Template Configuration
 
-You can customize how tags are formatted using the following configuration options in `version.config.json`:
+You can customize how tags are formatted using the following configuration options in `releasekit.config.json`:
 
 ```json
 {
@@ -430,7 +430,7 @@ For global commit messages, use templates without `${packageName}`:
 
 ## Monorepo Versioning Modes
 
-While primarily used for single packages now, `releasekit-version` retains options for monorepo workflows, controlled mainly by the `sync` flag in `version.config.json`.
+While primarily used for single packages now, `releasekit-version` retains options for monorepo workflows, controlled mainly by the `sync` flag in `releasekit.config.json`.
 
 ### Sync Mode (`sync: true`)
 
@@ -475,7 +475,7 @@ npx releasekit-version --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`:
+You can also set a default prerelease identifier in your `releasekit.config.json`:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@releasekit/version",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Semantic versioning based on Git history and conventional commits",
   "type": "module",
   "module": "./dist/index.js",
@@ -72,8 +72,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0",
-    "@releasekit/config": "0.0.0",
-    "@releasekit/core": "0.0.0"
+    "@releasekit/core": "0.0.0",
+    "@releasekit/config": "0.0.0"
   },
   "engines": {
     "node": ">=20"

package/docs/CI_CD_INTEGRATION.md

@@ -1,197 +0,0 @@
-# CI/CD Integration
-
-`releasekit-version` 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, `releasekit-version` provides a structured JSON output option:
-
-```bash
-# Output results in JSON format
-npx releasekit-version --json
-
-# Combine with dry-run for planning
-npx releasekit-version --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 my-package 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 `releasekit-version` 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@v6
-        with:
-          fetch-depth: 0  # Important for git history
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        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 releasekit-version --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 releasekit-version --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, `releasekit-version` 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
-
-`releasekit-version` 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 ${packageName} v${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