@teambit/ci 0.0.0-0116fb794cbc27e424eae2192c63c5225562b86d

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,107 @@
+import type { Command, CommandOptions } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import { OutsideWorkspaceError, type Workspace } from '@teambit/workspace';
+import type { ReleaseType } from 'semver';
+import { validateOptions } from '@teambit/snapping';
+import { BitError } from '@teambit/bit-error';
+import type { MergeStrategy } from '@teambit/component.modules.merge-helper';
+import type { 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;
+  versionsFile?: string;
+  autoMergeResolve?: MergeStrategy;
+  forceTheirs?: boolean;
+  laneName?: string;
+};
+
+export class CiMergeCmd implements Command {
+  name = 'merge';
+  description = 'Tags and exports new semantic versions after merging a PR to main.';
+  extendedDescription = `By default, bumps patch versions when merging to main. If specific configuration variables are set, it can use commit messages or explicit flags to determine the version bump. Runs install, tag, build, and export, then archives the remote lane and syncs lockfiles. Use in merge-to-main CI pipelines to publish releases.`;
+  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.',
+    ],
+    ['', 'versions-file <path>', 'path to a file containing component versions. format: "component-id: version"'],
+    ['', 'verbose', 'show verbose output'],
+    [
+      'r',
+      'auto-merge-resolve <merge-strategy>',
+      'in case of merge conflict during checkout, resolve according to the provided strategy: [ours, theirs, manual]',
+    ],
+    ['', 'force-theirs', 'do not merge during checkout, just overwrite with incoming files'],
+    ['', 'lane-name <name>', 'specify the lane name to delete after merge (auto-detected if not provided)'],
+  ];
+
+  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();
+
+    // Validate autoMergeResolve option
+    if (
+      options.autoMergeResolve &&
+      options.autoMergeResolve !== 'ours' &&
+      options.autoMergeResolve !== 'theirs' &&
+      options.autoMergeResolve !== 'manual'
+    ) {
+      throw new BitError('--auto-merge-resolve must be one of the following: [ours, theirs, manual]');
+    }
+
+    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,
+      versionsFile: options.versionsFile,
+      autoMergeResolve: options.autoMergeResolve,
+      forceTheirs: options.forceTheirs,
+      laneName: options.laneName,
+    });
+  }
+}

package/commands/pr.cmd.ts

@@ -0,0 +1,75 @@
+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 = 'Exports a feature lane to Bit Cloud when a Pull Request is opened or updated.';
+  extendedDescription = `Resolves the lane name from --lane or the current Git branch, validates it, and runs install, status, snap, and export. Cleans up by switching back to main. Use in pull-request CI pipelines after tests and before deploy.`;
+  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');
+      }
+      laneIdStr = this.ci.convertBranchToLaneId(currentBranch);
+    }
+
+    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,26 @@
+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';
+
+export class CiVerifyCmd implements Command {
+  name = 'verify';
+  description = 'Ensures the workspace passes CI checks on every commit.';
+  extendedDescription = `Runs lint, build, and status checks to catch dependency drift or broken builds early. Typically used as a pre-push hook or early CI job. Stops at the first failing step and returns a non-zero exit code.`;
+  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":[]}