release-suite 0.1.0 → 1.0.0

package/docs/compute-version.md

@@ -0,0 +1,204 @@
+# 📦 computeVersion
+
+`computeVersion()` is the core engine of **Release Suite**. It is responsible for analyzing Git history and determining whether a new semantic version should be released.
+
+This document defines its **official, immutable contract**, behavior, limitations, and CLI integration rules.
+
+---
+
+## 🎯 Purpose
+
+- Analyze Git commits since the last release
+- Detect semantic version bumps (`major`, `minor`, `patch`)
+- Decide **if** a release should happen
+- Provide deterministic, machine-readable output
+
+`computeVersion()` **never mutates files**, **never prints logs**, and **never exits the process**.
+
+---
+
+## 🧠 Programmatic API
+
+### Signature
+
+```ts
+computeVersion(options?: {
+  cwd?: string;
+}): ComputeVersionResult
+```
+
+### Options
+
+| Option | Description                                                                              |
+| ------ | ---------------------------------------------------------------------------------------- |
+| `cwd`  | Working directory where Git and `package.json` are resolved. Defaults to `process.cwd()` |
+
+---
+
+## 📜 Official Return Contract (Frozen)
+
+### Type Definition
+
+```ts
+type ComputeVersionResult =
+  | {
+      hasRelease: true;
+      baseVersion: string;
+      nextVersion: string;
+      bump: "major" | "minor" | "patch";
+      commitsAnalyzed: number;
+    }
+  | {
+      hasRelease: false;
+      baseVersion: string;
+      reason: "no-bump-detected" | "no-commits";
+      commitsAnalyzed: number;
+    };
+```
+
+---
+
+## 🟢 Release Detected
+
+Returned when at least one commit implies a semantic bump.
+
+Example:
+
+```json
+{
+  "hasRelease": true,
+  "baseVersion": "1.4.2",
+  "nextVersion": "1.5.0",
+  "bump": "minor",
+  "commitsAnalyzed": 8
+}
+```
+
+---
+
+## 🟡 No Release Detected
+
+### No commits since last release
+
+```json
+{
+  "hasRelease": false,
+  "reason": "no-commits",
+  "baseVersion": "1.4.2",
+  "commitsAnalyzed": 0
+}
+```
+
+### Commits found, but no semantic bump
+
+```json
+{
+  "hasRelease": false,
+  "reason": "no-bump-detected",
+  "baseVersion": "1.4.2",
+  "commitsAnalyzed": 5
+}
+```
+
+---
+
+## 🧪 Semantic Bump Rules
+
+The highest bump found **wins**:
+
+| Commit Type                | Bump    |
+| -------------------------- | ------- |
+| `feat!`, `BREAKING CHANGE` | `major` |
+| `feat`                     | `minor` |
+| `fix`, `perf`, `refactor`  | `patch` |
+
+Custom prefixes and emojis are supported as long as they resolve to these semantic meanings.
+
+---
+
+## 🔀 Squash & Merge Strategy
+
+`computeVersion()` works in **both**:
+
+- Full commit history (merge commits)
+- Squash & merge workflows
+
+### ⚠️ Important Recommendation
+
+If your repository uses **Squash & Merge**, configure GitHub to:
+
+> **“Use Pull request title and commit details”**
+
+And enforce **Conventional Commits** in PR titles:
+
+```text
+fix: normalize path resolution
+feat!: drop legacy API support
+```
+
+This ensures `computeVersion()` can reliably detect semantic intent.
+
+---
+
+## 🖥 CLI Integration
+
+The CLI wrapper (`rs-compute-version`) is a thin layer on top of `computeVersion()`.
+
+### Flags
+
+| Flag        | Description                              |
+| ----------- | ---------------------------------------- |
+| `--json`    | Outputs the full result as JSON          |
+| `--ci`      | Enables CI-friendly logging (future use) |
+| `--preview` | Semantic alias (no behavior change)      |
+
+---
+
+## 🚦 CLI Exit Codes (Contract)
+
+| Exit Code | Meaning                       |
+| --------- | ----------------------------- |
+| `0`       | Release generated             |
+| `10`      | No bump detected              |
+| `2`       | No commits since last release |
+| `1`       | Unexpected error              |
+
+> CI pipelines **must** rely on exit codes, not stdout parsing.
+
+---
+
+## 🚫 Explicit Non-Goals
+
+`computeVersion()` does **not**:
+
+- Modify `package.json`
+- Create Git tags
+- Generate changelogs
+- Access GitHub APIs
+- Enforce commit conventions
+
+These responsibilities belong to other tools in Release Suite.
+
+---
+
+## 🧊 Contract Stability
+
+This contract is considered **stable and frozen**.
+
+Any breaking change requires:
+
+- Major version bump of `release-suite`
+- Explicit migration notes
+- CI-safe transition plan
+
+---
+
+## ✅ Summary
+
+- Deterministic
+- Side-effect free
+- CI-safe
+- Fully testable
+- Explicit failure modes
+
+`computeVersion()` is designed to be boring — and reliable.

package/eslint.config.js

@@ -1,47 +1,89 @@
-// eslint.config.js
-import js from "@eslint/js";
-import prettierConfig from "eslint-config-prettier";
-import pluginImport from "eslint-plugin-import";
-import globals from "globals";
-
-export default [
-  js.configs.recommended,
-  {
-    files: ["bin/**/*.js"],
-    plugins: {
-      import: pluginImport,
-    },
-    languageOptions: {
-      ecmaVersion: "latest",
-      sourceType: "module",
-      globals: {
-        ...globals.node,
-      },
-    },
-    rules: {
-      "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
-      "no-console": "off",
-      "prefer-const": "warn",
-      eqeqeq: ["error", "always"],
-      curly: ["error", "all"],
-      "import/order": [
-        "warn",
-        {
-          groups: [
-            "builtin",
-            "external",
-            "internal",
-            "parent",
-            "sibling",
-            "index",
-          ],
-          alphabetize: { order: "asc", caseInsensitive: true },
-        },
-      ],
-    },
-  },
-  prettierConfig,
-  {
-    ignores: ["dist/**/*.js"],
-  },
-];
+// eslint.config.js
+import js from "@eslint/js";
+import prettierConfig from "eslint-config-prettier";
+import pluginImport from "eslint-plugin-import";
+import globals from "globals";
+
+export default [
+  js.configs.recommended,
+
+  // =====================
+  // BIN (CLI)
+  // =====================
+  {
+    files: ["bin/**/*.js"],
+    plugins: {
+      import: pluginImport,
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      "no-console": "off",
+      "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+      "prefer-const": "warn",
+      eqeqeq: ["error", "always"],
+      curly: ["error", "all"],
+      "import/order": [
+        "warn",
+        {
+          groups: [
+            "builtin",
+            "external",
+            "internal",
+            "parent",
+            "sibling",
+            "index",
+          ],
+          alphabetize: { order: "asc", caseInsensitive: true },
+        },
+      ],
+    },
+  },
+
+  // =====================
+  // LIB (reusable code)
+  // =====================
+  {
+    files: ["lib/**/*.js"],
+    plugins: {
+      import: pluginImport,
+    },
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+      },
+    },
+    rules: {
+      "no-console": "warn",
+      "no-unused-vars": ["warn", { argsIgnorePattern: "^_" }],
+      "prefer-const": "warn",
+      eqeqeq: ["error", "always"],
+      curly: ["error", "all"],
+      "import/order": [
+        "warn",
+        {
+          groups: [
+            "builtin",
+            "external",
+            "internal",
+            "parent",
+            "sibling",
+            "index",
+          ],
+          alphabetize: { order: "asc", caseInsensitive: true },
+        },
+      ],
+    },
+  },
+  prettierConfig,
+  {
+    ignores: ["dist/**/*.js"],
+  },
+];

package/lib/git.js

@@ -0,0 +1,73 @@
+import { run } from "./utils.js";
+
+/* ===========================
+ * Git helpers
+ * =========================== */
+
+/**
+ * Return the most recent Git tag reachable from HEAD, with a leading "v" prefix removed.
+ *
+ * Runs `git describe --tags --abbrev=0` in the provided working directory and strips a
+ * single leading "v" from the tag name (e.g. "v1.2.3" -> "1.2.3").
+ *
+ * @param {string} cwd - The working directory in which to run the Git command.
+ * @returns {string|null} The most recent tag without a leading "v", or null if no tag is found
+ *                        or the Git command fails.
+ */
+export function getLastTag(cwd) {
+  try {
+    const tag = run("git describe --tags --abbrev=0", cwd);
+    return tag.replace(/^v/, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Retrieve commits from Git using a compact, machine-friendly format.
+ *
+ * Executes `git log <range> --pretty=format:%H%x1f%s%x1f%b` in the given working directory,
+ * splits the output by newline, and returns an array of non-empty lines.
+ *
+ * Each array element is a single string formatted as:
+ *   "<commit-hash>\x1F<subject>\x1F<body>"
+ * where "\x1F" is the ASCII unit separator (0x1F) used to delimit fields.
+ *
+ * If the git command fails (e.g., not a repository, invalid range, or other error),
+ * an empty array is returned.
+ *
+ * @param {string} range - The git log range to query (e.g. "HEAD", "v1.0.0..HEAD", "master..feature").
+ * @param {string} [cwd] - Optional working directory path in which to run the git command.
+ * @returns {string[]} Array of commit entries, each as "<hash>\x1F<subject>\x1F<body>". Empty array on failure.
+ *
+ * @example
+ * // Possible return:
+ * // ["a1b2c3d4e5f6g7h8i9j0\u001FAdd feature X\u001FImplementation details...", ...]
+ */
+export function getCommits(range, cwd) {
+  try {
+    return run(
+      `git log ${range} --pretty=format:%H%x1f%s%x1f%b`,
+      cwd
+    )
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Parse a commit line encoded with ASCII Unit Separator characters into its parts.
+ *
+ * The input is expected to contain fields separated by '\x1f' in the order:
+ * hash, subject, body. If subject or body are missing, they default to an empty string.
+ *
+ * @param {string} line - Raw commit line with fields delimited by '\x1f'.
+ * @returns {{hash: string, subject: string, body: string}} An object containing the
+ *          commit hash, subject, and body.
+ */
+export function parseCommit(line) {
+  const [hash, subject = "", body = ""] = line.split("\x1f");
+  return { hash, subject, body };
+}

package/lib/utils.js

@@ -0,0 +1,45 @@
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/* ===========================
+ * Utilities
+ * =========================== */
+
+/**
+ * Execute a shell command synchronously and return its stdout as a trimmed UTF-8 string.
+ *
+ * @param {string} cmd - The command to execute (passed to child_process.execSync).
+ * @param {string} [cwd] - Optional working directory in which to run the command.
+ * @returns {string} The command's stdout, decoded as UTF-8 and trimmed of surrounding whitespace.
+ * @throws {Error|import('child_process').ExecSyncError} If the command fails or exits with a non-zero status.
+ * @see {@link https://nodejs.org/api/child_process.html#child_processexecsynccommand-options|child_process.execSync}
+ */
+export function run(cmd, cwd) {
+  return execSync(cmd, { encoding: "utf8", cwd }).trim();
+}
+
+/**
+ * Read the "version" field from a package.json file in the given directory.
+ *
+ * Synchronously reads and parses `<cwd>/package.json` and returns its `version`.
+ * Any errors (missing file, invalid JSON, missing `version`, etc.) are caught
+ * and a default version string of `"0.0.0"` is returned.
+ *
+ * @param {string} cwd - Path to the directory containing package.json.
+ * @returns {string} The package version, or `"0.0.0"` if it cannot be read.
+ *
+ * @example
+ * // returns "1.2.3" if /my/project/package.json contains { "version": "1.2.3" }
+ * const v = readPackageVersion('/my/project');
+ */
+export function readPackageVersion(cwd) {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(cwd, "package.json"), "utf8")
+    );
+    return pkg.version;
+  } catch {
+    return "0.0.0";
+  }
+}

package/lib/versioning.js

@@ -0,0 +1,110 @@
+/* ===========================
+ * Semver detection
+ * =========================== */
+
+const COMMIT_RE =
+  /^(feat|fix|refactor|docs|chore|style|test|build|perf|ci|cleanup|remove)(\(.+\))?(!)?:/i;
+
+/**
+ * Normalize a subject string by removing leading emoji and trimming whitespace.
+ *
+ * This function:
+ * - Strips a leading colon-style emoji shortcode (e.g. ":smile:"). Consecutive shortcodes
+ *   without intervening spaces (e.g. ":a::b: ...") are removed as a single leading block.
+ * - Removes leading Unicode emoji in the U+1F300–U+1FAFF range (one or more), using a
+ *   Unicode-aware match.
+ * - Trims surrounding whitespace from the resulting string.
+ *
+ * @param {string} subject - The input subject (e.g. a commit/PR subject).
+ * @returns {string} The normalized subject with any leading emoji/shortcodes removed and trimmed.
+ *
+ * @example
+ * normalizeSubject(':sparkles: Add new feature') // 'Add new feature'
+ * @example
+ * normalizeSubject('🚀✨  Deploy') // 'Deploy'
+ * @example
+ * normalizeSubject('  :a::b:Multiple emojis at start  ') // 'Multiple emojis at start'
+ */
+function normalizeSubject(subject) {
+  return subject
+    // remove emoji at start
+    .replace(/^:\S+:\s*/, "")
+    // remove unicode emoji at start
+    .replace(/^[\u{1F300}-\u{1FAFF}]+\s*/u, "")
+    .trim();
+}
+
+/**
+ * Determine the semantic version bump implied by a commit message.
+ *
+ * The function inspects the commit subject and body using a conventional-commit
+ * pattern (COMMIT_RE) and the presence of "BREAKING CHANGE":
+ * - Returns "major" if the body contains "BREAKING CHANGE" (case-insensitive)
+ *   or the commit header contains the conventional "!" breaking-change marker.
+ * - Returns "minor" if the header matches COMMIT_RE and the commit type is "feat".
+ * - Returns "patch" if the header matches COMMIT_RE and the commit type is "fix".
+ * - Returns "none" if no relevant indicators are present.
+ *
+ * @param {Object} params - Destructured input object.
+ * @param {string} params.subject - Commit subject/summary line to be matched against COMMIT_RE.
+ * @param {string} params.body - Commit body text used to detect "BREAKING CHANGE".
+ * @returns {'major'|'minor'|'patch'|'none'} The semantic version bump type.
+ */
+export function detectBumpType({ subject, body }) {
+  const cleanSubject = normalizeSubject(subject);
+
+  // Ignore revert commits entirely
+  if (/^revert\b/i.test(cleanSubject)) return "none";
+
+  const match = cleanSubject.match(COMMIT_RE);
+
+  const breaking =
+    /BREAKING CHANGE/i.test(body) || (match && match[3] === "!");
+
+  if (breaking) return "major";
+  if (!match) return "none";
+
+  const type = match[1].toLowerCase();
+  if (type === "feat") return "minor";
+  if (type === "fix") return "patch";
+
+  return "none";
+}
+
+/**
+ * Increment a semantic version string.
+ *
+ * Given a version string in the form "major.minor.patch", this function
+ * parses the numeric components (non-numeric or missing parts are treated as 0)
+ * and returns a new version string with the requested part bumped:
+ * - "major": increments major, resets minor and patch to 0
+ * - "minor": increments minor, resets patch to 0
+ * - any other value (including omitted): increments patch
+ *
+ * Parsing details:
+ * - Each segment is parsed with parseInt(..., 10); if parsing yields NaN,
+ *   that segment is treated as 0.
+ *
+ * @param {string} base - The base version string (e.g. "1.2.3").
+ * @param {string} [bump] - The part to bump: "major", "minor", or "patch".
+ *                          If omitted or any other value, the patch is bumped.
+ * @returns {string} The new version string in "major.minor.patch" format.
+ *
+ * @example
+ * bumpVersion("1.2.3", "patch"); // => "1.2.4"
+ * @example
+ * bumpVersion("1.2.3", "minor"); // => "1.3.0"
+ * @example
+ * bumpVersion("1.2.3", "major"); // => "2.0.0"
+ * @example
+ * bumpVersion("1", "patch");     // => "1.0.1"  (missing parts treated as 0)
+ * @example
+ * bumpVersion("a.b.c", "minor"); // => "0.1.0"  (non-numeric parts treated as 0)
+ */
+export function bumpVersion(base, bump) {
+  const [major, minor, patch] = base.split(".").map(n => parseInt(n, 10) || 0);
+
+  if (bump === "major") return `${major + 1}.0.0`;
+  if (bump === "minor") return `${major}.${minor + 1}.0`;
+  return `${major}.${minor}.${patch + 1}`;
+}