@teambit/ci 1.0.485 → 1.0.487

package/sync/main-sync-executor.ts

@@ -0,0 +1,321 @@
+import chalk from 'chalk';
+import { formatWarningSummary } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import type { LanesMain } from '@teambit/lanes';
+import type { CheckoutMain } from '@teambit/checkout';
+import { git } from '../git';
+import type { CiMain } from '../ci.main.runtime';
+import type { CiSyncConfig } from './sync-config';
+import { SYNC_COMMIT_MARKER } from './sync-state';
+import { currentLaneIdStr } from './workspace-lane';
+import type { GitHostProvider } from './git-host-provider';
+import { HALT_SUMMARY_PREFIX, capEntries } from './lane-sync-executor';
+import {
+  addAllExceptScopeAndModules,
+  branchExistsOnRemote,
+  checkoutPristine,
+  checkoutPristineRestore,
+  commitWithIdentity,
+  fetchRemoteHeads,
+  gitWithIdentity,
+  isNonContentPath,
+} from './git-ops';
+
+export type MainSyncDeps = {
+  checkout: CheckoutMain;
+  lanes: LanesMain;
+  /** for reloadWorkspaceFromDisk + switchToLaneForSync */
+  ci: CiMain;
+  logger: Logger;
+  /** undefined => PR operations are logged and skipped; the git half of the sync still runs. */
+  gitHost?: GitHostProvider;
+  cfg: Required<CiSyncConfig>;
+  defaultBranch: string;
+  defaultScope: string;
+};
+
+/**
+ * Reconcile the main scope with the repository's default branch. Stateless: `bit checkout head`
+ * writes the latest exported versions, so an empty `git status` IS convergence and any diff IS the
+ * drift. Under 'pr' the convergence is proposed via `mainSyncBranch`; under 'direct-push' it lands on
+ * the default branch with a plain push. Nothing is ever force-pushed in either mode.
+ */
+/** the "nothing to do" line, shared by both modes */
+const CONVERGED_SUMMARY = 'main -> converged (checkout head produced no changes)';
+
+export class MainSyncExecutor {
+  constructor(private deps: MainSyncDeps) {}
+
+  /**
+   * Returns a summary line (HALT-prefixed on failure) and, like `syncLane`, does not throw — a
+   * main-sync failure must not erase the lane results collected before it.
+   */
+  async syncMain(opts: { dryRun?: boolean } = {}): Promise<string> {
+    const { cfg, defaultBranch, defaultScope, logger } = this.deps;
+    const directPush = cfg.mainSync === 'direct-push';
+    // In direct-push mode the sync branch (and its PR) is not consulted, moved or deleted.
+    const branch = directPush ? defaultBranch : cfg.mainSyncBranch;
+
+    if (cfg.autoMergeMainSyncPr && !directPush) {
+      // Enabling auto-merge is host-specific and not part of the GitHostProvider contract.
+      logger.consoleWarning(
+        `sync.autoMergeMainSyncPr is enabled in the config, but enabling auto-merge is not implemented yet — ` +
+          `the sync PR is opened without it. Use a repository auto-merge rule instead.`
+      );
+    }
+
+    try {
+      await fetchRemoteHeads();
+      // Direct-push always starts from `origin/<defaultBranch>` — the very tip the plain push must
+      // fast-forward. In 'pr' mode an existing sync branch is reused so its PR history survives.
+      const syncBranchExists = directPush ? false : await branchExistsOnRemote(branch);
+      const startPoint = syncBranchExists ? `origin/${branch}` : `origin/${defaultBranch}`;
+      logger.console(
+        chalk.blue(
+          directPush
+            ? `main -> checking the main scope against ${defaultBranch} (direct-push)`
+            : `main -> checking the main scope against ${defaultBranch} (sync branch ${branch})`
+        )
+      );
+
+      await this.resetToStartPoint(branch, startPoint);
+
+      if (syncBranchExists) {
+        // Catch up with the default branch: the PR must stay mergeable, and `checkout head` on a stale
+        // tree would re-commit pre-merge content over the default branch's changes. A merge — never a
+        // rebase, never a force-push — is the only non-destructive way to move a branch with an open PR.
+        const catchUpErr = await this.catchUpWithDefaultBranch(branch);
+        if (catchUpErr) return `${HALT_SUMMARY_PREFIX} main -> ${catchUpErr}`;
+      }
+
+      // `checkout head` resolves versions against the CURRENT lane; a lane pointer on this branch
+      // would make the "drift" the lane's content. Refuse rather than open a wildly wrong PR.
+      // `.bitmap`-derived read: the scope-object read answers "main" on a fresh runner and the guard
+      // would silently stop refusing exactly where it ships (see `workspace-lane.ts`).
+      const currentLane = currentLaneIdStr(this.deps.lanes);
+      if (currentLane) {
+        return (
+          `${HALT_SUMMARY_PREFIX} main -> the .bitmap on ${startPoint} points at lane ` +
+          `"${currentLane}" rather than main, so the main-scope drift cannot be computed`
+        );
+      }
+
+      // `checkoutByCLIValues` rather than `checkout`: it imports current objects first (so `head`
+      // resolves to the remote scope's versions) and persists `.bitmap` on destroy.
+      // `includeNewFromScope`: a component exported to the scope's main but never in this repo's
+      // `.bitmap` would otherwise be invisible to every sync run forever.
+      // `mergeStrategy: 'theirs'` is required: unexported source drift makes components "modified",
+      // and with no strategy the checkout throws. 'theirs' materializes the exported truth — any
+      // reversion of unexported drift is visible in the PR diff. 'ours' is forbidden: it would advance
+      // `.bitmap` while keeping the old files, a commit asserting a state the tree does not have.
+      const results = await this.deps.checkout.checkoutByCLIValues('', {
+        head: true,
+        skipNpmInstall: true,
+        includeNewFromScope: true,
+        mergeStrategy: 'theirs',
+      });
+      const newFromScope = results.newFromScope ?? [];
+      if (newFromScope.length) {
+        logger.console(
+          chalk.blue(
+            `Added ${newFromScope.length} component(s) that exist on ${defaultScope}'s main but not in this ` +
+              `workspace: ${newFromScope.join(', ')}`
+          )
+        );
+      }
+
+      const drift = await this.driftFiles();
+      // Direct-push stays bare: asking the host about `mainSyncBranch`'s PR would be the one
+      // interaction with it this mode promises not to make.
+      if (!drift.length) return directPush ? CONVERGED_SUMMARY : await this.convergedSummary(branch);
+
+      logger.console(
+        formatWarningSummary(`main -> drift in ${drift.length} file(s): ${drift.slice(0, 20).join(', ')}`)
+      );
+
+      if (opts.dryRun) {
+        // The working tree WAS written (a diff-based check has no other way); `finally` restores it. Safe
+        // only because a dry run over a dirty tree is refused before anything runs — the restore rewinds
+        // to HEAD, so an uncommitted change here would be gone (`assertCleanForDryRun`).
+        logger.console(
+          formatWarningSummary(
+            directPush
+              ? `Dry-run: main -> would push the drift directly onto ${branch}`
+              : `Dry-run: main -> would push ${branch} and open a sync PR`
+          )
+        );
+        return directPush
+          ? `main -> drift detected in ${drift.length} file(s) — would push ${branch} directly`
+          : `main -> drift detected in ${drift.length} file(s) — would open sync PR`;
+      }
+
+      await addAllExceptScopeAndModules();
+      await commitWithIdentity(mainSyncCommitMessage(drift.length));
+      // Never force: a rejected push means a concurrent run pushed in between, and in direct-push mode
+      // that rejection is the whole safety story for the default branch. Unambiguous refspec — see
+      // `lane-sync-executor.commitAllAndPush`.
+      await git.push(['origin', `HEAD:refs/heads/${branch}`]);
+      logger.console(chalk.green(`Pushed ${branch}`));
+
+      if (directPush) {
+        const shortSha = (await git.revparse(['--short', 'HEAD'])).trim();
+        return `main -> direct-push (pushed ${branch} @ ${shortSha})`;
+      }
+      const prUrl = await this.ensureSyncPr({ branch, driftCount: drift.length, newFromScope });
+      return `main -> pushed sync commit to ${branch}${prUrl ? ` (PR ${prUrl})` : ''}`;
+    } catch (e: any) {
+      // Same contract as the lane executor: a HALTED line, never a throw mid-run.
+      return `${HALT_SUMMARY_PREFIX} main -> ${e?.message || e}`;
+    } finally {
+      await this.restoreWorkspace();
+    }
+  }
+
+  /**
+   * Put the working tree on the sync branch at a pristine copy of `startPoint`. Pristine is
+   * load-bearing for a diff-based reconciler: any stray modification would be indistinguishable from
+   * main-scope drift. The reload makes `checkout head` read this branch's `.bitmap`.
+   */
+  private async resetToStartPoint(branch: string, startPoint: string) {
+    await checkoutPristine(branch, startPoint, () => this.deps.ci.reloadWorkspaceFromDisk());
+  }
+
+  /**
+   * Merge the default branch into the sync branch so drift is computed against the repository's
+   * current state. Returns a reason string on failure; a conflict needs a human (or deleting the sync
+   * branch, which the next run re-forks).
+   */
+  private async catchUpWithDefaultBranch(branch: string): Promise<string | undefined> {
+    const { defaultBranch, logger } = this.deps;
+    try {
+      // under the identity: a non-fast-forward merge writes a merge COMMIT
+      const out = await gitWithIdentity(['merge', '--no-edit', `origin/${defaultBranch}`]);
+      logger.console(chalk.blue(`Brought ${branch} up to date with origin/${defaultBranch}: ${out.trim()}`));
+    } catch (e: any) {
+      await git.raw(['merge', '--abort']).catch(() => undefined);
+      return (
+        `could not bring the sync branch ${branch} up to date with origin/${defaultBranch}: ${e?.message || e}. ` +
+        `Resolve or delete ${branch} (a deleted sync branch is re-forked from ${defaultBranch} on the next run)`
+      );
+    }
+    // The merge may have brought a new `.bitmap` in from the default branch.
+    await this.deps.ci.reloadWorkspaceFromDisk();
+    return undefined;
+  }
+
+  /**
+   * The "nothing to do" line — plus the open sync PR, if any: converged means the SYNC branch matches
+   * the scope, and the default branch may still differ until that PR merges.
+   */
+  private async convergedSummary(branch: string): Promise<string> {
+    const { gitHost } = this.deps;
+    if (!gitHost) return CONVERGED_SUMMARY;
+    const pr = await gitHost.findPrByBranch(branch).catch(() => undefined);
+    return pr ? `${CONVERGED_SUMMARY} — open sync PR #${pr.number} still awaits review/merge` : CONVERGED_SUMMARY;
+  }
+
+  /**
+   * The files `bit checkout head` changed, i.e. the drift. Excludes `.bit`/`node_modules` — the same
+   * set the commit paths refuse to touch, keeping "counts as drift" and "gets committed" identical.
+   */
+  private async driftFiles(): Promise<string[]> {
+    const status = await git.status();
+    const paths = status.files.map((file) => file.path).filter((path) => !isNonContentPath(path));
+    return [...new Set(paths)];
+  }
+
+  /**
+   * Make sure the pushed branch has an open PR. A git-host failure only warns: the branch is pushed,
+   * which is the load-bearing half, and the next run retries the PR.
+   */
+  private async ensureSyncPr({
+    branch,
+    driftCount,
+    newFromScope,
+  }: {
+    branch: string;
+    driftCount: number;
+    newFromScope: string[];
+  }): Promise<string | undefined> {
+    const { gitHost, logger, defaultBranch } = this.deps;
+    if (!gitHost) {
+      logger.consoleWarning(
+        'No configured git host provider (for GitHub: BIT_GITHUB_TOKEN or GITHUB_TOKEN, plus a repository) — ' +
+          'pushed sync branch, skipping PR operations'
+      );
+      return undefined;
+    }
+    try {
+      const existing = await gitHost.findPrByBranch(branch);
+      if (existing) {
+        logger.console(chalk.blue(`Sync PR ${existing.htmlUrl} is already open — pushed the new commit onto it`));
+        return existing.htmlUrl;
+      }
+      const created = await gitHost.createPr({
+        head: branch,
+        base: defaultBranch,
+        title: 'Bit sync: update to latest main scope versions',
+        body: mainSyncPrBody({ driftCount, newFromScope }),
+      });
+      logger.console(chalk.green(`Opened sync PR ${created.htmlUrl}`));
+      return created.htmlUrl;
+    } catch (e: any) {
+      logger.consoleWarning(`Could not open or find the sync PR for ${branch}: ${e?.message || e}`);
+      return undefined;
+    }
+  }
+
+  /**
+   * Leave git on the default branch and bit on main. Mirrors `LaneSyncExecutor.restoreWorkspace`:
+   * best-effort and warn-only so a restore hiccup can't throw out of a `finally` and mask the real
+   * error; the clean discards untracked files `checkout head` wrote on the converged/dry-run paths.
+   */
+  private async restoreWorkspace() {
+    const { logger, defaultBranch } = this.deps;
+    try {
+      if (currentLaneIdStr(this.deps.lanes)) {
+        const switchErr = await this.deps.ci.switchToLaneForSync('main');
+        if (switchErr) logger.consoleWarning(`Could not switch the workspace back to main: ${switchErr.message}`);
+      }
+      await checkoutPristineRestore(defaultBranch, () => this.deps.ci.reloadWorkspaceFromDisk());
+    } catch (e: any) {
+      logger.consoleWarning(`Could not restore the workspace after the main sync: ${e?.message || e}`);
+    }
+  }
+}
+
+/** The sync commit message: no `Bit-Lane-Head` trailer — main sync keeps no state. */
+function mainSyncCommitMessage(driftCount: number): string {
+  return [
+    `chore(bit-sync): sync git to latest main scope versions (${driftCount} file(s))`,
+    '',
+    SYNC_COMMIT_MARKER,
+  ].join('\n');
+}
+
+function mainSyncPrBody({ driftCount, newFromScope }: { driftCount: number; newFromScope: string[] }): string {
+  const lines = [
+    'Automated sync PR: the Bit scope moved ahead of this repository. This PR checks the workspace out to the ' +
+      'latest exported versions (`bit checkout head --auto-merge-resolve theirs`).',
+    '',
+    `- files changed: ${driftCount}`,
+    '- conflicts between this repository and the scope were resolved **in favour of the scope** — if a file here ' +
+      'held changes that were never exported to Bit, this PR reverts them. Review the diff and close the PR ' +
+      'instead of merging if that is not what you want.',
+  ];
+  if (newFromScope.length) {
+    lines.push(
+      `- components added from the scope (${newFromScope.length}, not previously in this repository's \`.bitmap\`):`,
+      // Bounded like the lane PR body: an over-long body is rejected by the host outright.
+      ...capEntries(
+        newFromScope.map((id) => `  - \`${id}\``),
+        '  - '
+      )
+    );
+  }
+  lines.push(
+    '',
+    'This PR is maintained by `bit ci sync` — re-running the command pushes any further drift onto the same branch.'
+  );
+  return lines.join('\n');
+}

package/sync/sync-config.spec.ts

@@ -0,0 +1,283 @@
+import { expect } from 'chai';
+import type { CiSyncConfig, LaneTarget } from './sync-config';
+import {
+  syncableLaneNameForBranch,
+  assertValidBranchName,
+  assertValidBranchPrefix,
+  isValidGitBranchName,
+  validateBranchName,
+  resolveSyncConfig,
+  laneNameToBranch,
+  branchToLaneName,
+  isValidLaneName,
+  parseLaneTarget,
+  shouldSyncLane,
+} from './sync-config';
+
+const DEFAULT_SCOPE = 'acme.shop';
+
+/** `refs/` in the middle is git-legal and no refspec here doubles it, so only a LEADING one is refused. */
+const VALID = [
+  'main',
+  'bit-sync/main',
+  'lane/my-lane',
+  'feature/ABC-123_thing',
+  'release-2.0',
+  'a',
+  'feature/refs/foo',
+  'my-refs/foo',
+  'lane/refs',
+  'refs',
+];
+
+const INVALID = [
+  // an option-like leading dash — git would read it as a command-line option
+  '--force',
+  '-delete',
+  // characters and sequences git forbids in a ref, plus control characters
+  'a b',
+  'a\tb',
+  'a..b',
+  'a~b',
+  'a^b',
+  'a:b',
+  'a?b',
+  'a*b',
+  'a[b',
+  'a\\b',
+  'a@{b',
+  '@',
+  'a\u0001b',
+  'a\u007fb',
+  // path-shape rules
+  '',
+  '/x',
+  'x/',
+  'a//b',
+  'a.',
+  'a.lock',
+  '.hidden',
+  'a/.hidden',
+  'a/b.lock',
+  // stricter than git on purpose: every push interpolates the value into `refs/heads/<b>`
+  'refs/heads/foo',
+  'refs/foo',
+  'refs/remotes/origin/foo',
+];
+
+describe('isValidGitBranchName', () => {
+  it('accepts the shapes real configs use', () => {
+    VALID.forEach((name) => expect(isValidGitBranchName(name), name).to.equal(true));
+  });
+
+  it('rejects every shape git would refuse, plus the two this module is stricter about', () => {
+    INVALID.forEach((name) => expect(isValidGitBranchName(name), JSON.stringify(name)).to.equal(false));
+  });
+
+  it('says what is wrong in the terms the user has to act on', () => {
+    expect(validateBranchName('-x')).to.contain('command-line option');
+    expect(validateBranchName('refs/heads/main')).to.contain('bare branch name');
+  });
+});
+
+describe('assertValidBranchName', () => {
+  it('names the offending config key and value, so the message points at the line to fix', () => {
+    let message = '';
+    try {
+      assertValidBranchName('--force', 'sync.branches["my-lane"]');
+    } catch (err: any) {
+      message = err.message;
+    }
+    expect(message).to.contain('sync.branches["my-lane"]');
+    expect(message).to.contain('--force');
+    expect(message).to.contain('workspace.jsonc');
+    expect(() => assertValidBranchName('bit-sync/main', 'sync.mainSyncBranch')).to.not.throw();
+  });
+});
+
+describe('assertValidBranchPrefix', () => {
+  it('accepts an empty prefix (the default) and ordinary directory-ish prefixes', () => {
+    ['', 'lane/', 'bit-'].forEach((prefix) =>
+      expect(() => assertValidBranchPrefix(prefix, 'sync.branchPrefix'), prefix).to.not.throw()
+    );
+  });
+
+  it('rejects a prefix that could never start a valid name', () => {
+    // 'lane//' — an empty path component in the prefix must not be collapsed away by the check
+    ['-x', 'a b/', 'a..b/', 'lane//'].forEach((prefix) =>
+      expect(() => assertValidBranchPrefix(prefix, 'sync.branchPrefix'), prefix).to.throw('sync.branchPrefix')
+    );
+  });
+});
+
+describe('resolveSyncConfig validates branch names up front', () => {
+  /** A bad name must fail at startup naming its config key, not mid-run with git's own ref error. */
+  const rejected: Array<[string, Parameters<typeof resolveSyncConfig>[0]]> = [
+    ['sync.mainSyncBranch', { mainSyncBranch: '--force' }],
+    // a fully-qualified ref where a bare branch name belongs
+    ['sync.mainSyncBranch', { mainSyncBranch: 'refs/heads/bit-sync/main' }],
+    ['sync.branches["my-lane"]', { branches: { 'my-lane': 'a..b' } }],
+    ['sync.branchPrefix', { branchPrefix: '-x' }],
+    // a `refs/`-rooted prefix double-prefixes every derived branch, not just one configured name
+    ['sync.branchPrefix', { branchPrefix: 'refs/heads/' }],
+  ];
+
+  rejected.forEach(([key, raw]) => {
+    it(`rejects ${JSON.stringify(raw)} naming ${key}`, () => {
+      expect(() => resolveSyncConfig(raw)).to.throw(key);
+    });
+  });
+
+  it('accepts the documented defaults unchanged', () => {
+    const cfg = resolveSyncConfig();
+    expect(cfg.mainSyncBranch).to.equal('bit-sync/main');
+    expect(cfg.branchPrefix).to.equal('');
+  });
+});
+
+describe('laneNameToBranch validates the derived name', () => {
+  it('catches a prefix + lane name that only together form something git refuses', () => {
+    // `lane/` is a fine prefix on its own; appending a lane name ending the branch in "." is not.
+    const cfg = resolveSyncConfig({ branchPrefix: 'lane/' });
+    expect(() => laneNameToBranch('x.', cfg)).to.throw('not a valid git branch name');
+    expect(laneNameToBranch('my-lane', cfg)).to.equal('lane/my-lane');
+  });
+
+  it('returns an override as configured (already validated by resolveSyncConfig)', () => {
+    expect(laneNameToBranch('my-lane', resolveSyncConfig({ branches: { 'my-lane': 'custom/branch' } }))).to.equal(
+      'custom/branch'
+    );
+  });
+});
+
+describe('sync-config', () => {
+  it('applies defaults', () => {
+    expect(resolveSyncConfig(undefined)).to.deep.equal({
+      branchPrefix: '',
+      branches: {},
+      lanes: ['*'],
+      mainSyncBranch: 'bit-sync/main',
+      autoMergeMainSyncPr: false,
+      mainSync: 'pr',
+      // a silent policy pick rewrites someone's work, so silence is opt-in
+      onConflict: 'halt',
+    });
+  });
+
+  it('accepts every documented value of the union-typed options', () => {
+    (['pr', 'direct-push'] as const).forEach((v) => expect(resolveSyncConfig({ mainSync: v }).mainSync).to.equal(v));
+    (['halt', 'git-wins', 'lane-wins'] as const).forEach((v) =>
+      expect(resolveSyncConfig({ onConflict: v }).onConflict).to.equal(v)
+    );
+  });
+
+  // Config comes from workspace.jsonc, so the union types are not enforced at runtime: a typo must fail
+  // at startup naming the key, the value and the options, not fall through to whichever mode a
+  // comparison happens to miss.
+  const REJECTED: Array<[CiSyncConfig, RegExp]> = [
+    [{ mainSync: 'direct' as any }, /sync\.mainSync.*"direct".*"pr".*"direct-push"/],
+    [{ onConflict: 'ours' as any }, /sync\.onConflict.*"ours".*"halt".*"git-wins".*"lane-wins"/],
+  ];
+
+  REJECTED.forEach(([raw, expected]) => {
+    it(`refuses ${JSON.stringify(raw)}, naming the key, the value and the valid options`, () => {
+      expect(() => resolveSyncConfig(raw)).to.throw(expected);
+    });
+  });
+
+  it('maps lane <-> branch: an explicit override outranks the prefix in both directions', () => {
+    const cfg = resolveSyncConfig({ branchPrefix: 'lane/', branches: { 'my-lane': 'custom' } });
+    expect(laneNameToBranch('my-lane', cfg)).to.equal('custom');
+    expect(branchToLaneName('custom', cfg)).to.equal('my-lane');
+    expect(branchToLaneName('lane/other', cfg)).to.equal('other');
+    expect(branchToLaneName('unrelated-branch', cfg)).to.equal(undefined);
+    // with no prefix and no override, a branch maps to the same-named lane
+    expect(branchToLaneName('some-lane', resolveSyncConfig({}))).to.equal('some-lane');
+  });
+
+  describe('parseLaneTarget', () => {
+    // A lane name cannot contain '/', so the single '/' is always the scope/name boundary; a hosting
+    // scope needs no dot (self-hosted and test scopes are bare names).
+    const PARSED: Array<[string, LaneTarget]> = [
+      ['my-lane', { hostScope: DEFAULT_SCOPE, name: 'my-lane' }],
+      ['other-org.other-scope/my-lane', { hostScope: 'other-org.other-scope', name: 'my-lane' }],
+      ['bare-scope/my-lane', { hostScope: 'bare-scope', name: 'my-lane' }],
+      ['  my-lane  ', { hostScope: DEFAULT_SCOPE, name: 'my-lane' }],
+    ];
+
+    it('resolves a bare name against defaultScope and splits a scope-qualified id', () => {
+      PARSED.forEach(([input, expected]) =>
+        expect(parseLaneTarget(input, DEFAULT_SCOPE), input).to.deep.equal(expected)
+      );
+    });
+
+    it('refuses malformed targets rather than guessing at them', () => {
+      ['', '   ', '/', '/my-lane', 'scope/', 'a/b/c', 'scope//lane'].forEach((input) =>
+        expect(() => parseLaneTarget(input, DEFAULT_SCOPE), `input: "${input}"`).to.throw()
+      );
+    });
+  });
+
+  it('filters lanes by glob list', () => {
+    expect(shouldSyncLane('anything', resolveSyncConfig({}))).to.equal(true);
+    const cfg = resolveSyncConfig({ lanes: ['feature-*'] });
+    expect(shouldSyncLane('feature-x', cfg)).to.equal(true);
+    expect(shouldSyncLane('hotfix-y', cfg)).to.equal(false);
+    expect(shouldSyncLane('anything', resolveSyncConfig({ lanes: [] }))).to.equal(false);
+  });
+});
+
+// Pins bit's own rule (create-lane.ts), which this module re-states rather than imports.
+describe('isValidLaneName', () => {
+  it('accepts what bit accepts: lowercase alphanumerics plus - _ $ !', () => {
+    ['my-lane', 'lane_1', 'a', 'x$y', 'w!', 'release-2'].forEach((name) =>
+      expect(isValidLaneName(name), name).to.equal(true)
+    );
+  });
+
+  it('rejects uppercase, spaces, dots, the empty string, and the slash a branch name brings in', () => {
+    ['FEATURE', 'Feature', 'a b', 'a.b', '', 'a+b', 'café', 'feature/foo', 'a/b/c'].forEach((name) =>
+      expect(isValidLaneName(name), JSON.stringify(name)).to.equal(false)
+    );
+  });
+
+  it("rejects a name past bit's length limit", () => {
+    expect(isValidLaneName('a'.repeat(800))).to.equal(true);
+    expect(isValidLaneName('a'.repeat(801))).to.equal(false);
+  });
+});
+
+/**
+ * `--all` maps every remote branch through here; anything it returns becomes a sync target whose branch
+ * name is then derived and validated. So the two directions must agree, or an ordinary developer branch
+ * halts the run instead of being skipped.
+ */
+describe('syncableLaneNameForBranch round-trips lane and branch validity', () => {
+  const cfg = (raw: CiSyncConfig = {}) => resolveSyncConfig({ lanes: ['*'], ...raw });
+
+  it('maps an ordinary branch to its lane name', () => {
+    expect(syncableLaneNameForBranch('my-lane', cfg())).to.equal('my-lane');
+  });
+
+  it('skips a branch whose mapped lane name is valid as a LANE but not usable as a BRANCH', () => {
+    // the lane grammar permits `-`, so `-x` is a legal lane name — but git reads it as an option, and
+    // `laneNameToBranch` asserts on it. Enumeration must skip such a branch, not adopt it as a target.
+    expect(isValidLaneName('-x')).to.equal(true);
+    expect(syncableLaneNameForBranch('-x', cfg())).to.equal(undefined);
+    expect(syncableLaneNameForBranch('--force', cfg())).to.equal(undefined);
+  });
+
+  it('skips a branch whose name bit forbids as a lane', () => {
+    expect(syncableLaneNameForBranch('feature/foo', cfg())).to.equal(undefined);
+  });
+
+  it('honours a configured override, which resolveSyncConfig already validated', () => {
+    expect(syncableLaneNameForBranch('release/x', cfg({ branches: { 'lane-x': 'release/x' } }))).to.equal('lane-x');
+  });
+
+  it('applies the round trip through a configured prefix too', () => {
+    const prefixed = cfg({ branchPrefix: 'bit-sync/' });
+    expect(syncableLaneNameForBranch('bit-sync/my-lane', prefixed)).to.equal('my-lane');
+    expect(syncableLaneNameForBranch('my-lane', prefixed)).to.equal(undefined);
+  });
+});