@teambit/ci 0.0.0-01196c5baebfaeabe37f33253bb4c38b8b774ea8

package/ci.docs.mdx

@@ -0,0 +1,258 @@
+---
+description: 'Aspect that eases the Bit workflow in CI'
+labels: ['aspect', 'ci']
+---
+
+# Bit CI
+
+Bit's **`bit ci`** commands (plus one BVM enhancement) wrap several routine Bit tasks into single-purpose scripts so your CI pipelines stay short, readable and consistent.
+
+| Command                           | Purpose                                               | Typical CI Stage       |
+| --------------------------------- | ----------------------------------------------------- | ---------------------- |
+| [`bit ci verify`](#bit-ci-verify) | Lint + build gate on every commit                     | pre-push / commit hook |
+| [`bit ci pr`](#bit-ci-pr)         | Snap + export a feature lane when a PR opens/updates  | pull-request pipeline  |
+| [`bit ci merge`](#bit-ci-merge)   | Tag + export new semantic versions on merge to `main` | merge-to-main pipeline |
+
+---
+
+## `bit ci verify`
+
+|                  |                                                   |
+| ---------------- | ------------------------------------------------- |
+| **Syntax**       | `bit ci verify`                                   |
+| **What it does** | Ensures the component passes CI on every commit   |
+| **Runs**         | `bit install && bit status --strict && bit build` |
+
+### When to run
+
+- Every commit that **is not** part of an open Pull Request (e.g. a pre-push hook).
+- As an early CI job to fail fast on dependency drift or broken builds.
+
+### Exit behaviour
+
+The command stops at the first failing step (`status`, then `build`) and returns a non-zero exit code.
+
+---
+
+## `bit ci pr`
+
+Export a lane to Bit Cloud whenever a Pull Request is opened or updated.
+
+```bash
+bit ci pr [--message <string>] [--build] [--lane <string>]
+```
+
+| Flag        | Shorthand | Description                                                                               |
+| ----------- | --------- | ----------------------------------------------------------------------------------------- |
+| `--message` | `-m`      | Changelog entry. If omitted, tries the latest Git commit message (fails if unavailable).  |
+| `--build`   | `-b`      | Build locally before export. If absent, Ripple-CI builds the components.                  |
+| `--lane`    | `-l`      | Explicit lane name. Falls back to the current Git branch name. Performs input validation. |
+
+### Internal flow (fail-fast on any step)
+
+1. **Resolve lane name**
+   - From `--lane` or current Git branch.
+   - If the lane doesn’t exist remotely, create it; otherwise, `bit lane checkout <lane>`.
+2. **Run wrapped Bit commands**
+
+   ```bash
+   bit install
+   bit status --strict
+   bit lane create <lane>      # no-op if already exists
+   bit snap --message "<msg>" --build
+   bit export
+   ```
+
+3. **Clean-up**
+
+   ```bash
+   bit lane switch main   # leaves .bitmap unchanged in the working tree
+   ```
+
+### Typical CI placement
+
+Run on the _pull-request_ event after tests but before any deploy step.
+
+---
+
+## `bit ci merge`
+
+Publishes new semantic versions after a PR merges to `main`.
+
+```bash
+bit ci merge [--message <string>] [--build] [--increment <level>] [--patch|--minor|--major] [--increment-by <number>]
+```
+
+| Flag              | Shorthand | Description                                                                                                         |
+| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
+| `--message`       | `-m`      | Changelog entry (defaults to last Git commit message).                                                              |
+| `--build`         | `-b`      | Build locally (otherwise Ripple-CI does it). Required if workspace contains _soft-tagged_ components.               |
+| `--strict`        | `-s`      | Fail on warnings as well as errors (default: only fails on errors).                                                 |
+| `--increment`     | `-l`      | Version bump level: `major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, `prerelease` (default: `patch`). |
+| `--patch`         | `-p`      | Shortcut for `--increment patch`.                                                                                   |
+| `--minor`         |           | Shortcut for `--increment minor`.                                                                                   |
+| `--major`         |           | Shortcut for `--increment major`.                                                                                   |
+| `--pre-release`   |           | Shortcut for `--increment prerelease` with optional identifier.                                                     |
+| `--prerelease-id` |           | Prerelease identifier (e.g. "dev" to get "1.0.0-dev.1").                                                            |
+| `--increment-by`  |           | Increment by more than 1 (e.g. `--increment-by 2` with patch: 0.0.1 → 0.0.3).                                       |
+
+### Automatic Version Bump Detection
+
+When **no explicit version flags** are provided, `bit ci merge` can automatically determine the version bump level from the commit message:
+
+1. **Explicit Keywords** (highest priority):
+
+   - `BIT-BUMP-MAJOR` anywhere in commit message → major version bump
+   - `BIT-BUMP-MINOR` anywhere in commit message → minor version bump
+
+2. **Conventional Commits** (when enabled):
+
+   - `feat!:` or `BREAKING CHANGE` → major version bump
+   - `feat:` → minor version bump
+   - `fix:` → patch version bump
+
+3. **Default**: patch version bump
+
+**Note**: Auto-detection only occurs when no version flags (`--patch`, `--minor`, `--major`, etc.) are provided. Explicit flags always take precedence.
+
+### Internal flow
+
+1. **Ensure main lane**
+
+   ```bash
+   bit lane switch main   # preserves working tree files
+   ```
+
+2. **Tag, build, export**
+
+   ```bash
+   bit install
+   bit tag --message "<msg>" --build --persist   # --persist only if soft tags exist
+   bit export
+   ```
+
+3. **Archive remote lane** (house-keeping).
+4. **Commit lock-file updates**
+
+   ```bash
+   git add .bitmap pnpm-lock.yaml
+   git commit -m "chore(release): sync bitmap + lockfile"
+   ```
+
+### Version bump examples
+
+```bash
+# Explicit version bump (takes precedence over auto-detection)
+bit ci merge --minor --message "feat: add new API endpoint"
+bit ci merge --major --message "feat!: breaking API changes"
+bit ci merge --patch --increment-by 3 --message "fix: critical patches"
+
+# Automatic detection from commit message (no flags needed)
+git commit -m "feat: add new API endpoint"
+bit ci merge --build  # → auto-detects minor bump
+
+git commit -m "feat!: breaking API changes"
+bit ci merge --build  # → auto-detects major bump
+
+git commit -m "fix: resolve memory leak"
+bit ci merge --build  # → auto-detects patch bump (if conventional commits enabled)
+
+# Using explicit keywords for auto-detection
+git commit -m "feat: add new feature BIT-BUMP-MINOR"
+bit ci merge --build  # → auto-detects minor bump
+
+git commit -m "refactor: major code restructure BIT-BUMP-MAJOR"
+bit ci merge --build  # → auto-detects major bump
+
+# Default patch increment (when no detection rules match)
+git commit -m "chore: update dependencies"
+bit ci merge --build  # → defaults to patch bump
+
+# Prerelease increment (explicit flag required)
+bit ci merge --pre-release dev --message "feat: experimental feature"
+```
+
+### CI hint
+
+Gate this step behind a branch-protection rule so only fast-forward merges trigger a release.
+
+---
+
+## Configuration
+
+The CI aspect supports configuration in `workspace.jsonc`:
+
+```json
+{
+  "teambit.git/ci": {
+    "commitMessageScript": "node scripts/generate-commit-message.js",
+    "useConventionalCommitsForVersionBump": true,
+    "useExplicitBumpKeywords": true
+  }
+}
+```
+
+### `commitMessageScript`
+
+**Optional.** Path to a script that generates custom commit messages for the `bit ci merge` command.
+
+- **Default**: Uses `"chore: update .bitmap and lockfiles as needed [skip ci]"`
+- **Usage**: The script should output the desired commit message to stdout
+- **Security**: Commands are parsed to avoid shell injection - no chaining allowed
+- **Working Directory**: Script runs in the workspace root directory
+
+**Example script:**
+
+```javascript
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+
+try {
+  const version = execSync('npm show @my/package version', { encoding: 'utf8' }).trim();
+  console.log(`bump version to ${version} [skip ci]`);
+} catch {
+  console.log('chore: update .bitmap and lockfiles as needed [skip ci]');
+}
+```
+
+### `useConventionalCommitsForVersionBump`
+
+**Optional.** Enable automatic version bump detection based on conventional commit patterns.
+
+- **Default**: `false` (disabled)
+- **When enabled**: Analyzes commit messages for conventional commit patterns:
+  - `feat!:` or `BREAKING CHANGE` → major version bump
+  - `feat:` → minor version bump
+  - `fix:` → patch version bump
+
+```json
+{
+  "teambit.git/ci": {
+    "useConventionalCommitsForVersionBump": true
+  }
+}
+```
+
+### `useExplicitBumpKeywords`
+
+**Optional.** Enable automatic version bump detection using explicit keywords.
+
+- **Default**: `true` (enabled)
+- **Keywords**:
+  - `BIT-BUMP-MAJOR` anywhere in commit message → major version bump
+  - `BIT-BUMP-MINOR` anywhere in commit message → minor version bump
+
+```json
+{
+  "teambit.git/ci": {
+    "useExplicitBumpKeywords": false // disable explicit keywords
+  }
+}
+```
+
+**Example usage:**
+
+```bash
+git commit -m "feat: add new feature BIT-BUMP-MINOR"
+bit ci merge --build  # → automatically uses minor version bump
+```

package/commands/merge.cmd.ts

@@ -0,0 +1,78 @@
+import type { Command, CommandOptions } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import { OutsideWorkspaceError, type Workspace } from '@teambit/workspace';
+import { ReleaseType } from 'semver';
+import { validateOptions } from '@teambit/snapping';
+import { CiMain } from '../ci.main.runtime';
+
+type Options = {
+  message?: string;
+  build?: boolean;
+  strict?: boolean;
+  increment?: ReleaseType;
+  patch?: boolean;
+  minor?: boolean;
+  major?: boolean;
+  preRelease?: string;
+  prereleaseId?: string;
+  incrementBy?: number;
+  verbose?: boolean;
+};
+
+export class CiMergeCmd implements Command {
+  name = 'merge';
+  description = 'Merges a PR';
+  group = 'collaborate';
+
+  options: CommandOptions = [
+    ['m', 'message <message>', 'If set, use it as the tag message, if not, try and grab from git-commit-message'],
+    ['b', 'build', 'Set to true to build the app locally, false (default) will build on Ripple CI'],
+    ['s', 'strict', 'Set to true to fail on warnings as well as errors, false (default) only fails on errors'],
+    [
+      'l',
+      'increment <level>',
+      'options are: [major, premajor, minor, preminor, patch, prepatch, prerelease], default to patch',
+    ],
+    ['', 'prerelease-id <id>', 'prerelease identifier (e.g. "dev" to get "1.0.0-dev.1")'],
+    ['p', 'patch', 'syntactic sugar for "--increment patch"'],
+    ['', 'minor', 'syntactic sugar for "--increment minor"'],
+    ['', 'major', 'syntactic sugar for "--increment major"'],
+    ['', 'pre-release [identifier]', 'syntactic sugar for "--increment prerelease" and `--prerelease-id <identifier>`'],
+    [
+      '',
+      'increment-by <number>',
+      '(default to 1) increment semver flag (patch/minor/major) by. e.g. incrementing patch by 2: 0.0.1 -> 0.0.3.',
+    ],
+    ['', 'verbose', 'show verbose output'],
+  ];
+
+  constructor(
+    private workspace: Workspace,
+    private logger: Logger,
+    private ci: CiMain
+  ) {}
+
+  async report(args: unknown, options: Options) {
+    this.logger.console('\n\n');
+    this.logger.console('🚀 Initializing Merge command');
+    if (!this.workspace) throw new OutsideWorkspaceError();
+
+    const { releaseType, preReleaseId } = validateOptions(options);
+
+    // Check if user explicitly provided any version bump flags
+    const explicitVersionBump = Boolean(
+      options.increment || options.patch || options.minor || options.major || options.preRelease
+    );
+
+    return this.ci.mergePr({
+      message: options.message,
+      build: options.build,
+      strict: options.strict,
+      releaseType,
+      preReleaseId,
+      incrementBy: options.incrementBy,
+      explicitVersionBump,
+      verbose: options.verbose,
+    });
+  }
+}

package/commands/pr.cmd.ts

@@ -0,0 +1,76 @@
+import type { Command, CommandOptions } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import { OutsideWorkspaceError, type Workspace } from '@teambit/workspace';
+import type { CiMain } from '../ci.main.runtime';
+
+type Options = {
+  message?: string;
+  build?: boolean;
+  lane?: string;
+  strict?: boolean;
+};
+
+export class CiPrCmd implements Command {
+  name = 'pr';
+  description = 'This command is meant to run when a PR was open/updated and meant to export a lane to bit-cloud.';
+  group = 'collaborate';
+
+  options: CommandOptions = [
+    ['m', 'message <message>', 'If set, set it as the snap message, if not, try and grab from git-commit-message'],
+    ['l', 'lane <lane>', 'If set, use as the lane name, if not available, grab from git-branch name'],
+    ['b', 'build', 'Set to true to build the app locally, false (default) will build on Ripple CI'],
+    ['s', 'strict', 'Set to true to fail on warnings as well as errors, false (default) only fails on errors'],
+  ];
+
+  constructor(
+    private workspace: Workspace,
+    private logger: Logger,
+    private ci: CiMain
+  ) {}
+
+  async report(args: unknown, options: Options) {
+    this.logger.console('\n\n');
+    this.logger.console('🚀 Initializing PR command');
+    if (!this.workspace) throw new OutsideWorkspaceError();
+
+    let laneIdStr: string;
+    let message: string;
+
+    if (options.lane) {
+      laneIdStr = options.lane;
+    } else {
+      const currentBranch = await this.ci.getBranchName().catch((e) => {
+        throw new Error(`Failed to get branch name from Git: ${e.toString()}`);
+      });
+      if (!currentBranch) {
+        throw new Error('Failed to get branch name');
+      }
+      // Sanitize branch name to make it valid for Bit lane IDs by replacing slashes with dashes
+      const sanitizedBranch = currentBranch.replace(/\//g, '-');
+      laneIdStr = `${this.workspace.defaultScope}/${sanitizedBranch}`;
+    }
+
+    if (options.message) {
+      message = options.message;
+    } else {
+      const commitMessage = await this.ci.getGitCommitMessage();
+      if (!commitMessage) {
+        throw new Error('Failed to get commit message');
+      }
+      message = commitMessage;
+    }
+
+    const results = await this.ci.snapPrCommit({
+      laneIdStr: laneIdStr,
+      message,
+      build: options.build,
+      strict: options.strict,
+    });
+
+    if (results) {
+      return results;
+    }
+
+    return `PR command executed successfully`;
+  }
+}

package/commands/verify.cmd.ts

@@ -0,0 +1,25 @@
+import type { Command, CommandOptions } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import { OutsideWorkspaceError, type Workspace } from '@teambit/workspace';
+import { CiMain } from '../ci.main.runtime';
+
+export class CiVerifyCmd implements Command {
+  name = 'verify';
+  description = 'CI commands';
+  group = 'development';
+
+  options: CommandOptions = [];
+
+  constructor(
+    private workspace: Workspace,
+    private logger: Logger,
+    private ci: CiMain
+  ) {}
+
+  async report() {
+    this.logger.console('\n\n🚀 Initializing Verify command');
+    if (!this.workspace) throw new OutsideWorkspaceError();
+
+    return this.ci.verifyWorkspaceStatus();
+  }
+}

package/dist/ci.aspect.d.ts

@@ -0,0 +1,3 @@
+import { Aspect } from '@teambit/harmony';
+export declare const CiAspect: Aspect;
+export default CiAspect;

package/dist/ci.aspect.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.CiAspect = void 0;
+function _harmony() {
+  const data = require("@teambit/harmony");
+  _harmony = function () {
+    return data;
+  };
+  return data;
+}
+const CiAspect = exports.CiAspect = _harmony().Aspect.create({
+  id: 'teambit.git/ci'
+});
+var _default = exports.default = CiAspect;
+
+//# sourceMappingURL=ci.aspect.js.map

package/dist/ci.aspect.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_harmony","data","require","CiAspect","exports","Aspect","create","id","_default","default"],"sources":["ci.aspect.ts"],"sourcesContent":["import { Aspect } from '@teambit/harmony';\n\nexport const CiAspect = Aspect.create({\n  id: 'teambit.git/ci',\n});\n\nexport default CiAspect;\n"],"mappings":";;;;;;AAAA,SAAAA,SAAA;EAAA,MAAAC,IAAA,GAAAC,OAAA;EAAAF,QAAA,YAAAA,CAAA;IAAA,OAAAC,IAAA;EAAA;EAAA,OAAAA,IAAA;AAAA;AAEO,MAAME,QAAQ,GAAAC,OAAA,CAAAD,QAAA,GAAGE,iBAAM,CAACC,MAAM,CAAC;EACpCC,EAAE,EAAE;AACN,CAAC,CAAC;AAAC,IAAAC,QAAA,GAAAJ,OAAA,CAAAK,OAAA,GAEYN,QAAQ","ignoreList":[]}

package/dist/ci.cmd.d.ts

@@ -0,0 +1,17 @@
+import type { Command, CommandOptions } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import type { Workspace } from '@teambit/workspace';
+export declare class CiCmd implements Command {
+    private workspace;
+    private logger;
+    name: string;
+    description: string;
+    group: string;
+    options: CommandOptions;
+    commands: Command[];
+    constructor(workspace: Workspace, logger: Logger);
+    report(): Promise<{
+        code: number;
+        data: string;
+    }>;
+}

package/dist/ci.cmd.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CiCmd = void 0;
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+class CiCmd {
+  constructor(workspace, logger) {
+    this.workspace = workspace;
+    this.logger = logger;
+    _defineProperty(this, "name", 'ci <sub-command>');
+    _defineProperty(this, "description", 'CI commands');
+    _defineProperty(this, "group", 'collaborate');
+    _defineProperty(this, "options", []);
+    _defineProperty(this, "commands", []);
+  }
+  async report() {
+    return {
+      code: 1,
+      data: '[ci] not implemented'
+    };
+  }
+}
+exports.CiCmd = CiCmd;
+
+//# sourceMappingURL=ci.cmd.js.map

package/dist/ci.cmd.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["CiCmd","constructor","workspace","logger","_defineProperty","report","code","data","exports"],"sources":["ci.cmd.ts"],"sourcesContent":["import type { Command, CommandOptions } from '@teambit/cli';\nimport type { Logger } from '@teambit/logger';\nimport type { Workspace } from '@teambit/workspace';\n\nexport class CiCmd implements Command {\n  name = 'ci <sub-command>';\n  description = 'CI commands';\n  group = 'collaborate';\n\n  options: CommandOptions = [];\n  commands: Command[] = [];\n\n  constructor(\n    private workspace: Workspace,\n    private logger: Logger\n  ) {}\n\n  async report() {\n    return { code: 1, data: '[ci] not implemented' };\n  }\n}\n"],"mappings":";;;;;;;;;AAIO,MAAMA,KAAK,CAAoB;EAQpCC,WAAWA,CACDC,SAAoB,EACpBC,MAAc,EACtB;IAAA,KAFQD,SAAoB,GAApBA,SAAoB;IAAA,KACpBC,MAAc,GAAdA,MAAc;IAAAC,eAAA,eATjB,kBAAkB;IAAAA,eAAA,sBACX,aAAa;IAAAA,eAAA,gBACnB,aAAa;IAAAA,eAAA,kBAEK,EAAE;IAAAA,eAAA,mBACN,EAAE;EAKrB;EAEH,MAAMC,MAAMA,CAAA,EAAG;IACb,OAAO;MAAEC,IAAI,EAAE,CAAC;MAAEC,IAAI,EAAE;IAAuB,CAAC;EAClD;AACF;AAACC,OAAA,CAAAR,KAAA,GAAAA,KAAA","ignoreList":[]}