@teambit/objects 0.0.0-00042bc99514ea12d897f81bcd0181e2b034c615

package/models/lane-history.spec.ts

@@ -0,0 +1,35 @@
+import { expect } from 'chai';
+
+import { LaneHistory } from './lane-history';
+
+const makeItem = (date: string) => ({
+  log: { date, username: 'tester' },
+  components: [],
+});
+
+describe('LaneHistory', () => {
+  describe('getHistoryIds', () => {
+    it('returns ids sorted by date even when insertion order is not chronological', () => {
+      const laneHistory = LaneHistory.parse(
+        JSON.stringify({
+          name: 'tmp4',
+          scope: 'my-scope',
+          laneHash: 'abc',
+          history: {
+            'newer-local': makeItem('1746369091000'), // 5/4/2026, 12:51 PM
+            'older-remote-1': makeItem('1746127977000'), // 5/1/2026, 3:32 PM
+            'older-remote-2': makeItem('1746127986000'), // 5/1/2026, 3:33 PM
+            'between-remote': makeItem('1746358729000'), // 5/4/2026, 9:58 AM
+          },
+        })
+      );
+
+      expect(laneHistory.getHistoryIds()).to.deep.equal([
+        'older-remote-1',
+        'older-remote-2',
+        'between-remote',
+        'newer-local',
+      ]);
+    });
+  });
+});

package/models/lane-history.ts

@@ -0,0 +1,131 @@
+import { v4 } from 'uuid';
+import { getStringifyArgs } from '@teambit/legacy.utils';
+import { getBasicLog } from '@teambit/harmony.modules.get-basic-log';
+import { BitObject } from '../objects';
+import type Lane from './lane';
+
+type Log = { date: string; username?: string; email?: string; message?: string };
+
+export type HistoryItem = {
+  log: Log;
+  components: string[];
+  deleted?: string[];
+  // hidden lane.updateDependents at the time of the snapshot. Recorded in their own field so
+  // `historyItem.components` keeps its workspace-checkout/revert contract intact — those flows
+  // must not materialize hidden entries into the bitmap.
+  updateDependents?: string[];
+};
+
+type History = { [uuid: string]: HistoryItem };
+
+type LaneHistoryProps = {
+  name: string;
+  scope: string;
+  laneHash: string;
+  history: History;
+};
+
+export class LaneHistory extends BitObject {
+  private name: string;
+  private scope: string;
+  private laneHash: string;
+  private history: History;
+
+  constructor(props: LaneHistoryProps) {
+    super();
+    this.name = props.name;
+    this.scope = props.scope;
+    this.laneHash = props.laneHash;
+    this.history = props.history;
+  }
+
+  id() {
+    return `${this.laneHash}:${LaneHistory.name}`;
+  }
+
+  static fromLaneObject(laneObject: Lane): LaneHistory {
+    return new LaneHistory({
+      scope: laneObject.scope,
+      name: laneObject.name,
+      laneHash: laneObject.hash().toString(),
+      history: {},
+    });
+  }
+
+  toObject(): Record<string, any> {
+    return {
+      name: this.name,
+      scope: this.scope,
+      laneHash: this.laneHash,
+      history: this.history,
+    };
+  }
+
+  toString(pretty: boolean): string {
+    const args = getStringifyArgs(pretty);
+    return JSON.stringify(this.toObject(), ...args);
+  }
+
+  toBuffer(pretty): Buffer {
+    return Buffer.from(this.toString(pretty));
+  }
+
+  getHistory(): History {
+    return this.history;
+  }
+
+  getHistoryIds(): string[] {
+    return Object.entries(this.history)
+      .sort(([, a], [, b]) => Number(a.log.date) - Number(b.log.date))
+      .map(([id]) => id);
+  }
+
+  async addHistory(laneObj: Lane, msg?: string, historyKey?: string) {
+    const log: Log = await getBasicLog();
+    if (msg) log.message = msg;
+    const components = laneObj.toComponentIds().toStringArray();
+    const deleted = laneObj.components
+      .filter((c) => c.isDeleted)
+      .map((c) => c.id.changeVersion(c.head.toString()).toString());
+    // Always write `updateDependents` (even when empty) so checkout/revert can distinguish a
+    // post-PR entry that legitimately had no hidden entries (drop current hidden) from a legacy
+    // pre-PR entry that never recorded the field at all (leave current hidden alone).
+    const updateDependents = (laneObj.updateDependents || []).map((id) => id.toString());
+    this.history[historyKey || v4()] = {
+      log,
+      components,
+      ...(deleted.length && { deleted }),
+      updateDependents,
+    };
+  }
+
+  removeHistoryEntries(keys: string[]) {
+    for (const key of keys) {
+      delete this.history[key];
+    }
+  }
+
+  merge(laneHistory: LaneHistory) {
+    this.history = { ...this.history, ...laneHistory.history };
+  }
+
+  static create(name: string, scope: string, laneHash: string) {
+    return new LaneHistory({
+      name,
+      scope,
+      laneHash,
+      history: {},
+    });
+  }
+
+  static parse(contents: string): LaneHistory {
+    const parsed = JSON.parse(contents);
+    const props: LaneHistoryProps = {
+      name: parsed.name,
+      scope: parsed.scope,
+      laneHash: parsed.laneHash,
+      history: parsed.history,
+    };
+    return new LaneHistory(props);
+  }
+}

package/models/lane.ts

@@ -0,0 +1,400 @@
+import { v4 } from 'uuid';
+import { gte } from 'semver';
+import { cloneDeep, isEqual, pickBy } from 'lodash';
+import { BitError } from '@teambit/bit-error';
+import { ComponentID, ComponentIdList } from '@teambit/component-id';
+import { isSnap } from '@teambit/component-version';
+import { LaneId, DEFAULT_LANE, LANE_REMOTE_DELIMITER } from '@teambit/lane-id';
+import type { Scope } from '@teambit/legacy.scope';
+import { CFG_USER_EMAIL_KEY, CFG_USER_NAME_KEY, PREVIOUS_DEFAULT_LANE } from '@teambit/legacy.constants';
+import { ValidationError } from '@teambit/legacy.cli.error';
+import { logger } from '@teambit/legacy.logger';
+import { getStringifyArgs } from '@teambit/legacy.utils';
+import { sha1 } from '@teambit/toolbox.crypto.sha1';
+import { hasVersionByRef } from '@teambit/component.snap-distance';
+import type { Repository } from '../objects';
+import { BitObject, Ref } from '../objects';
+import type Version from './version';
+import { getConfig } from '@teambit/config-store';
+
+export type Log = { date: string; username?: string; email?: string; profileImage?: string };
+
+export type LaneProps = {
+  name: string;
+  scope: string;
+  log: Log;
+  components?: LaneComponent[];
+  hash: string;
+  schema?: string;
+  readmeComponent?: LaneReadmeComponent;
+  forkedFrom?: LaneId;
+  updateDependents?: ComponentID[];
+  overrideUpdateDependents?: boolean;
+};
+
+const OLD_LANE_SCHEMA = '0.0.0';
+const SCHEMA_INCLUDING_DELETED_COMPONENTS_DATA = '1.0.0';
+const CURRENT_LANE_SCHEMA = SCHEMA_INCLUDING_DELETED_COMPONENTS_DATA;
+
+export type LaneComponent = { id: ComponentID; head: Ref; isDeleted?: boolean };
+export type LaneReadmeComponent = { id: ComponentID; head: Ref | null };
+export default class Lane extends BitObject {
+  name: string;
+  scope: string;
+  components: LaneComponent[];
+  log: Log;
+  schema: string;
+  readmeComponent?: LaneReadmeComponent;
+  forkedFrom?: LaneId;
+  _hash: string; // reason for the underscore prefix is that we already have hash as a method
+  isNew = false; // doesn't get saved in the object. only needed for in-memory instance
+  hasChanged = false; // doesn't get saved in the object. only needed for in-memory instance
+  /**
+   * components that are dependents of components in the lane and need to be re-snapped against the
+   * lane's heads. populated by the bare-scope cascade producer (UI "snap updates" / `bit _snap`)
+   * and by `bit _merge-lane`. these entries are part of the lane's graph (Ripple CI builds them,
+   * merge engine refreshes them) but are intentionally hidden from workspace-facing flows
+   * (`bit status`, `bit compile`, `bit install`, the bitmap).
+   */
+  updateDependents?: ComponentID[];
+  private overrideUpdateDependents?: boolean;
+  constructor(props: LaneProps) {
+    super();
+    if (!props.name) throw new TypeError('Lane constructor expects to get a name parameter');
+    this.name = props.name;
+    this.scope = props.scope;
+    this.components = props.components || [];
+    this.log = props.log || { date: Date.now().toString() };
+    this._hash = props.hash;
+    this.readmeComponent = props.readmeComponent;
+    this.forkedFrom = props.forkedFrom;
+    this.schema = props.schema || OLD_LANE_SCHEMA;
+    this.updateDependents = props.updateDependents;
+    this.overrideUpdateDependents = props.overrideUpdateDependents;
+  }
+  id(): string {
+    return this.scope + LANE_REMOTE_DELIMITER + this.name;
+  }
+  hash(): Ref {
+    if (!this._hash) {
+      throw new Error('hash is missing from a Lane object');
+    }
+    return new Ref(this._hash);
+  }
+  changeName(name: string) {
+    this.name = name;
+    this.hasChanged = true;
+  }
+  changeScope(scope: string) {
+    this.scope = scope;
+    this.hasChanged = true;
+  }
+  refs(): Ref[] {
+    return this.components.map((c) => c.head);
+  }
+  validateBeforePersisting(str: string) {
+    logger.debug(`validating lane object: ${this.hash().toString()} ${this.id()}`);
+    const lane = Lane.parse(str, this.hash().toString());
+    lane.validate();
+  }
+  toObject() {
+    const obj = pickBy(
+      {
+        name: this.name,
+        scope: this.scope,
+        components: this.components.map((component) => ({
+          id: { scope: component.id.scope, name: component.id.fullName },
+          head: component.head.toString(),
+          ...(component.isDeleted && { isDeleted: component.isDeleted }),
+        })),
+        log: this.log,
+        readmeComponent: this.readmeComponent && {
+          id: { scope: this.readmeComponent.id.scope, name: this.readmeComponent.id.fullName },
+          head: this.readmeComponent.head?.toString() ?? null,
+        },
+        forkedFrom: this.forkedFrom && this.forkedFrom.toObject(),
+        schema: this.schema,
+        updateDependents: this.updateDependents?.map((c) => c.toString()),
+        overrideUpdateDependents: this.overrideUpdateDependents,
+      },
+      (val) => !!val
+    );
+    return obj;
+  }
+  static from(props: LaneProps): Lane {
+    return new Lane(props);
+  }
+  static create(
+    name: string,
+    scope: string,
+    forkedFrom?: LaneId,
+    bitCloudUser?: {
+      username?: string;
+      email?: string;
+      profileImage?: string;
+    }
+  ) {
+    const log = {
+      date: Date.now().toString(),
+      username: bitCloudUser?.username || getConfig(CFG_USER_NAME_KEY),
+      email: bitCloudUser?.email || getConfig(CFG_USER_EMAIL_KEY),
+      profileImage: bitCloudUser?.profileImage,
+    };
+    const lane = new Lane({ name, scope, hash: sha1(v4()), log, forkedFrom, schema: CURRENT_LANE_SCHEMA });
+    lane.isNew = true;
+    lane.hasChanged = true;
+    return lane;
+  }
+  static parse(contents: string, hash: string): Lane {
+    const laneObject = JSON.parse(contents);
+    return Lane.from({
+      name: laneObject.name,
+      scope: laneObject.scope,
+      log: laneObject.log,
+      components: laneObject.components.map((component) => ({
+        id: ComponentID.fromObject({ scope: component.id.scope, name: component.id.name }),
+        head: new Ref(component.head),
+        isDeleted: component.isDeleted,
+      })),
+      readmeComponent: laneObject.readmeComponent && {
+        id: ComponentID.fromObject({
+          scope: laneObject.readmeComponent.id.scope,
+          name: laneObject.readmeComponent.id.name,
+        }),
+        head: laneObject.readmeComponent.head && new Ref(laneObject.readmeComponent.head),
+      },
+      forkedFrom: laneObject.forkedFrom && LaneId.from(laneObject.forkedFrom.name, laneObject.forkedFrom.scope),
+      updateDependents: laneObject.updateDependents?.map((c) => ComponentID.fromString(c)),
+      overrideUpdateDependents: laneObject.overrideUpdateDependents,
+      hash: laneObject.hash || hash,
+      schema: laneObject.schema,
+    });
+  }
+  toBuffer(pretty?: boolean) {
+    const args = getStringifyArgs(pretty);
+    const obj = this.toObject();
+    const str = JSON.stringify(obj, ...args);
+    if (this.validateBeforePersist) this.validateBeforePersisting(str);
+    return Buffer.from(str);
+  }
+  addComponent(component: LaneComponent) {
+    const existsComponent = this.getComponent(component.id);
+    if (existsComponent) {
+      if (
+        !existsComponent.head.isEqual(component.head) ||
+        Boolean(existsComponent.isDeleted) !== Boolean(component.isDeleted)
+      ) {
+        this.hasChanged = true;
+      }
+      existsComponent.id = component.id;
+      existsComponent.head = component.head;
+      existsComponent.isDeleted = component.isDeleted;
+    } else {
+      logger.debug(`Lane.addComponent, adding component ${component.id.toString()} to lane ${this.id()}`);
+      this.components.push(component);
+      this.hasChanged = true;
+    }
+  }
+  findUpdateDependent(componentId: ComponentID): ComponentID | undefined {
+    return this.updateDependents?.find((c) => c.isEqualWithoutVersion(componentId));
+  }
+  getUpdateDependentAsLaneComponent(componentId: ComponentID): LaneComponent | undefined {
+    const found = this.findUpdateDependent(componentId);
+    if (!found?.version) return undefined;
+    return { id: found.changeVersion(undefined), head: Ref.from(found.version) };
+  }
+  removeComponentFromUpdateDependentsIfExist(componentId: ComponentID) {
+    if (!this.findUpdateDependent(componentId)) return;
+    this.updateDependents = this.updateDependents?.filter((c) => !c.isEqualWithoutVersion(componentId));
+    if (!this.updateDependents?.length) this.updateDependents = undefined;
+    this.hasChanged = true;
+  }
+  addComponentToUpdateDependents(componentId: ComponentID) {
+    if (!componentId.hasVersion()) {
+      throw new ValidationError(`Lane.addComponentToUpdateDependents: ${componentId.toString()} is missing a version`);
+    }
+    this.removeComponentFromUpdateDependentsIfExist(componentId);
+    (this.updateDependents ||= []).push(componentId);
+    this.hasChanged = true;
+  }
+  removeAllUpdateDependents() {
+    if (!this.updateDependents?.length) return;
+    this.updateDependents = undefined;
+    this.hasChanged = true;
+  }
+  /**
+   * Signals an explicit `_snap --update-dependents` insertion. On export, the receiving scope
+   * gates its "add this new hidden entry" branch on this flag so a stale workspace lane can't
+   * resurrect entries the Cloud UI dropped. Workspace cascades — which only update existing
+   * entries — deliberately do NOT set the flag. The field is also serialized by `Lane.toObject`
+   * for older remotes that gate their pre-diverge-check override branch on it.
+   */
+  setOverrideUpdateDependents(overrideUpdateDependents: boolean) {
+    this.overrideUpdateDependents = overrideUpdateDependents;
+    this.hasChanged = true;
+  }
+
+  shouldOverrideUpdateDependents(): boolean {
+    return Boolean(this.overrideUpdateDependents);
+  }
+
+  removeComponent(id: ComponentID): boolean {
+    const existsComponent = this.getComponent(id);
+    if (!existsComponent) return false;
+    this.components = this.components.filter((c) => !c.id.isEqualWithoutVersion(id));
+    this.hasChanged = true;
+    return true;
+  }
+  getComponent(id: ComponentID): LaneComponent | undefined {
+    return this.components.find((c) => c.id.isEqualWithoutVersion(id));
+  }
+  getComponentHead(bitId: ComponentID): Ref | null {
+    const found = this.components.find((c) => c.id.isEqual(bitId));
+    if (found) return found.head;
+    return null;
+  }
+  setLaneComponents(laneComponents: LaneComponent[]) {
+    // this gets called when adding lane-components from other lanes/remotes, so it's better to
+    // clone the objects to not change the original data.
+    this.components = laneComponents.map((c) => ({
+      id: c.id.clone(),
+      head: c.head.clone(),
+      ...(c.isDeleted && { isDeleted: c.isDeleted }),
+    }));
+    this.hasChanged = true;
+  }
+  setReadmeComponent(id?: ComponentID) {
+    const previousReadme = this.readmeComponent;
+    if (!id) {
+      this.readmeComponent = undefined;
+      if (previousReadme) this.hasChanged = true;
+      return;
+    }
+    const readmeComponent = this.getComponent(id);
+    if (!readmeComponent) {
+      this.readmeComponent = { id, head: null };
+    } else {
+      this.readmeComponent = readmeComponent;
+    }
+    if (
+      !previousReadme ||
+      !previousReadme.id.isEqual(id) ||
+      previousReadme.head?.toString() !== this.readmeComponent.head?.toString()
+    ) {
+      this.hasChanged = true;
+    }
+  }
+
+  async isFullyMerged(scope: Scope): Promise<boolean> {
+    const { unmerged } = await this.getMergedAndUnmergedIds(scope);
+    return unmerged.length === 0;
+  }
+  async getMergedAndUnmergedIds(scope: Scope): Promise<{ merged: ComponentID[]; unmerged: ComponentID[] }> {
+    const merged: ComponentID[] = [];
+    const unmerged: ComponentID[] = [];
+    await Promise.all(
+      this.components.map(async (component) => {
+        const modelComponent = await scope.getModelComponentIfExist(component.id);
+        if (!modelComponent) {
+          unmerged.push(component.id);
+          return;
+        }
+        const startTraverseFrom = modelComponent.getHead() || null; // it's important to have it as null and not as undefined, see hasVersionByRef
+        const headExist = await hasVersionByRef(modelComponent, component.head, scope.objects, startTraverseFrom);
+        if (headExist) merged.push(component.id);
+        else unmerged.push(component.id);
+      })
+    );
+    return { merged, unmerged };
+  }
+  /**
+   * @deprecated use toComponentIds instead
+   */
+  toBitIds(): ComponentIdList {
+    return this.toComponentIds();
+  }
+  toComponentIds(): ComponentIdList {
+    return ComponentIdList.fromArray(this.components.map((c) => c.id.changeVersion(c.head.toString())));
+  }
+  toComponentIdsIncludeUpdateDependents(): ComponentIdList {
+    return ComponentIdList.fromArray(this.toComponentIds().concat(this.updateDependents || []));
+  }
+  toLaneId() {
+    return new LaneId({ scope: this.scope, name: this.name });
+  }
+  collectObjectsById(repo: Repository): Promise<Array<{ id: ComponentID; objects: BitObject[] }>> {
+    return Promise.all(
+      this.components.map(async (component) => {
+        const headVersion = (await component.head.load(repo)) as Version;
+        const objects = [headVersion, ...headVersion.collect(repo)];
+        return { id: component.id, objects };
+      })
+    );
+  }
+  includeDeletedData(): boolean {
+    return gte(this.schema, SCHEMA_INCLUDING_DELETED_COMPONENTS_DATA);
+  }
+  setSchemaToSupportDeletedData() {
+    this.schema = SCHEMA_INCLUDING_DELETED_COMPONENTS_DATA;
+    this.hasChanged = true;
+  }
+  setSchemaToNotSupportDeletedData() {
+    this.schema = OLD_LANE_SCHEMA;
+    this.hasChanged = true;
+  }
+  getCompHeadIncludeUpdateDependents(componentId: ComponentID): Ref | undefined {
+    const comp = this.getComponent(componentId);
+    if (comp) return comp.head;
+    return this.getUpdateDependentAsLaneComponent(componentId)?.head;
+  }
+  validate() {
+    const message = `unable to save Lane object "${this.id()}"`;
+    const bitIds = this.toComponentIds();
+    this.components.forEach((component) => {
+      if (bitIds.filterWithoutVersion(component.id).length > 1) {
+        throw new ValidationError(`${message}, the following component is duplicated "${component.id.fullName}"`);
+      }
+      if (!isSnap(component.head.hash)) {
+        throw new ValidationError(
+          `${message}, lane component ${component.id.toStringWithoutVersion()} head should be a hash, got ${
+            component.head.hash
+          }`
+        );
+      }
+    });
+    if (this.name === DEFAULT_LANE) {
+      throw new BitError(`${message}, this name is reserved as the default lane`);
+    }
+    if (this.name === PREVIOUS_DEFAULT_LANE) {
+      throw new BitError(`${message}, this name is reserved as the old default lane`);
+    }
+  }
+  isEqual(lane: Lane): boolean {
+    if (this.id() !== lane.id()) return false;
+    // include isDeleted in equality so a soft-delete flip with the same head still counts as a
+    // state change — `Lane.isEqual` is used by importers to decide whether to write a
+    // LaneHistory entry.
+    const normalize = (l: Lane) =>
+      l.components
+        .map((c) => ({
+          id: c.id.toStringWithoutVersion(),
+          head: c.head.toString(),
+          isDeleted: Boolean(c.isDeleted),
+        }))
+        .sort((a, b) =>
+          `${a.id}@${a.head}:${a.isDeleted ? 1 : 0}`.localeCompare(`${b.id}@${b.head}:${b.isDeleted ? 1 : 0}`)
+        );
+    const thisUpdDeps = (this.updateDependents || []).map((c) => c.toString()).sort();
+    const otherUpdDeps = (lane.updateDependents || []).map((c) => c.toString()).sort();
+    return isEqual(normalize(this), normalize(lane)) && isEqual(thisUpdDeps, otherUpdDeps);
+  }
+  clone() {
+    return new Lane({
+      ...this,
+      hash: this._hash,
+      overrideUpdateDependents: this.overrideUpdateDependents,
+      components: cloneDeep(this.components),
+      updateDependents: this.updateDependents ? cloneDeep(this.updateDependents) : undefined,
+    });
+  }
+}

package/models/model-component.spec.ts

@@ -0,0 +1,55 @@
+import { expect } from 'chai';
+
+import ModelComponent from './model-component';
+import { clone } from 'lodash';
+
+const modelComponentFixture = {
+  name: 'bar/foo',
+  scope: 'remote-scope',
+  versions: {
+    '0.0.1': '125a37bdb17220bdc1406a9a28a3dde4eec91225',
+  },
+  lang: 'javascript',
+  deprecated: false,
+  bindingPrefix: '@bit',
+  remotes: [
+    {
+      url: 'file:///tmp/remote-scope',
+      name: 'remote-scope',
+      date: '1572532837438',
+    },
+  ],
+  state: {
+    versions: {
+      '0.0.1': {
+        local: true,
+      },
+    },
+  },
+};
+
+const getModelComponentFixture = (): typeof modelComponentFixture => {
+  return clone(modelComponentFixture);
+};
+
+const getModelComponent = (obj: object): ModelComponent => {
+  return ModelComponent.parse(JSON.stringify(obj));
+};
+
+describe('ModelComponent', () => {
+  describe('validate', () => {
+    let validateFunc: Function;
+    describe('duplicate hashes', () => {
+      let modelComponent: ModelComponent;
+      before(() => {
+        const fixture = getModelComponentFixture();
+        fixture.versions['0.0.2'] = fixture.versions['0.0.1'];
+        modelComponent = getModelComponent(fixture);
+        validateFunc = () => modelComponent.validate();
+      });
+      it('should throw an error', () => {
+        expect(validateFunc).to.throw('the following hash(es) are duplicated');
+      });
+    });
+  });
+});