@teambit/ci 0.0.0-01196c5baebfaeabe37f33253bb4c38b8b774ea8

package/dist/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/dist/ci.main.runtime.d.ts

@@ -0,0 +1,132 @@
+import type { RuntimeDefinition } from '@teambit/harmony';
+import { type CLIMain } from '@teambit/cli';
+import { type LoggerMain, type Logger } from '@teambit/logger';
+import { type Workspace } from '@teambit/workspace';
+import { type BuilderMain } from '@teambit/builder';
+import { type StatusMain } from '@teambit/status';
+import { type LanesMain } from '@teambit/lanes';
+import { type SnappingMain } from '@teambit/snapping';
+import { type ExportMain } from '@teambit/export';
+import { type ImporterMain } from '@teambit/importer';
+import { type CheckoutMain } from '@teambit/checkout';
+import { ReleaseType } from 'semver';
+export interface CiWorkspaceConfig {
+    /**
+     * Path to a custom script that generates commit messages for `bit ci merge` operations.
+     * The script will be executed when components are tagged and committed to the repository.
+     * If not specified, falls back to the default commit message:
+     * "chore: update .bitmap and lockfiles as needed [skip ci]"
+     *
+     * @example
+     * ```json
+     * {
+     *   "teambit.git/ci": {
+     *     "commitMessageScript": "node scripts/generate-commit-message.js"
+     *   }
+     * }
+     * ```
+     */
+    commitMessageScript?: string;
+    /**
+     * Enables automatic version bump detection from conventional commit messages.
+     * When enabled, the system analyzes commit messages to determine the appropriate version bump:
+     * - `feat!:` or `BREAKING CHANGE` → major version bump
+     * - `feat:` → minor version bump
+     * - `fix:` → patch version bump
+     *
+     * Only applies when no explicit version flags (--patch, --minor, --major) are provided.
+     *
+     * @default false
+     * @example
+     * ```json
+     * {
+     *   "teambit.git/ci": {
+     *     "useConventionalCommitsForVersionBump": true
+     *   }
+     * }
+     * ```
+     */
+    useConventionalCommitsForVersionBump?: boolean;
+    /**
+     * Enables detection of explicit version bump keywords in commit messages.
+     * When enabled, the system looks for these keywords in commit messages:
+     * - `BIT-BUMP-MAJOR` → major version bump
+     * - `BIT-BUMP-MINOR` → minor version bump
+     *
+     * These keywords have higher priority than conventional commits parsing.
+     * Only applies when no explicit version flags are provided.
+     *
+     * @default true
+     * @example
+     * ```json
+     * {
+     *   "teambit.git/ci": {
+     *     "useExplicitBumpKeywords": true
+     *   }
+     * }
+     * ```
+     */
+    useExplicitBumpKeywords?: boolean;
+}
+export declare class CiMain {
+    private workspace;
+    private builder;
+    private status;
+    private lanes;
+    private snapping;
+    private exporter;
+    private importer;
+    private checkout;
+    private logger;
+    private config;
+    static runtime: RuntimeDefinition;
+    static dependencies: any;
+    static slots: any;
+    constructor(workspace: Workspace, builder: BuilderMain, status: StatusMain, lanes: LanesMain, snapping: SnappingMain, exporter: ExportMain, importer: ImporterMain, checkout: CheckoutMain, logger: Logger, config: CiWorkspaceConfig);
+    static provider([cli, workspace, loggerAspect, builder, status, lanes, snapping, exporter, importer, checkout]: [
+        CLIMain,
+        Workspace,
+        LoggerMain,
+        BuilderMain,
+        StatusMain,
+        LanesMain,
+        SnappingMain,
+        ExportMain,
+        ImporterMain,
+        CheckoutMain
+    ], config: CiWorkspaceConfig): Promise<CiMain>;
+    getBranchName(): Promise<string>;
+    getDefaultBranchName(): Promise<string>;
+    getGitCommitMessage(): Promise<string | null>;
+    private parseVersionBumpFromCommit;
+    private getCustomCommitMessage;
+    private verifyWorkspaceStatusInternal;
+    private switchToLane;
+    verifyWorkspaceStatus(): Promise<{
+        code: number;
+        data: string;
+    }>;
+    snapPrCommit({ laneIdStr, message, build, strict, }: {
+        laneIdStr: string;
+        message: string;
+        build: boolean | undefined;
+        strict: boolean | undefined;
+    }): Promise<"No changes detected, nothing to snap" | undefined>;
+    mergePr({ message: argMessage, build, strict, releaseType, preReleaseId, incrementBy, explicitVersionBump, verbose, }: {
+        message?: string;
+        build?: boolean;
+        strict?: boolean;
+        releaseType: ReleaseType;
+        preReleaseId?: string;
+        incrementBy?: number;
+        explicitVersionBump?: boolean;
+        verbose?: boolean;
+    }): Promise<{
+        code: number;
+        data: string;
+    }>;
+    /**
+     * Auto-detect version bump from commit messages if no explicit version bump was provided
+     */
+    private determineReleaseType;
+}