深入 lerna 发包机制 —— lerna version

.
├── CHANGELOG.md 
├── README.md
├── __tests__  // 测试相关目录
├── command.js  // cli 的入口文件，lerna version 的一些选项都可以在其中看到
├── index.js // version 执行逻辑相关的函数文件
├── lib // 相关的工具函数，根据名称可以推断出其功能
│   ├── __mocks__
│   ├── create-release.js
│   ├── get-current-branch.js
│   ├── git-add.js
│   ├── git-commit.js
│   ├── git-push.js
│   ├── git-tag.js
│   ├── is-anything-committed.js
│   ├── is-behind-upstream.js
│   ├── is-breaking-change.js
│   ├── prompt-version.js
│   ├── remote-branch-exists.js
│   └── update-lockfile-version.js
└── package.json

class VersionCommand extends Command {
  // 一些 options 的检查和整合
  configureProperties() {}

  // 初始化
  initialize() {}

  // 执行逻辑
  execute() {}

  // 其他部分就是一些类里面的工具函数例如 getVersionsForUpdates
  // ...
}

// 检验 --create-release 使用场景
if (this.createRelease && this.options.conventionalCommits !== true) {
  throw new ValidationError("ERELEASE", "To create a release, you must enable --conventional-commits");
}
if (this.createRelease && this.options.changelog === false) {
  throw new ValidationError("ERELEASE", "To create a release, you cannot pass --no-changelog");
}

// 这里是把一些用户传进来的 git 相关参数放在 gitOptions 中
this.gitOpts = {
  // amend 用来跳 lerna version 的 git push 的,默认为 true, --amend 用户传参数
  amend,
  commitHooks,
  granularPathspec,
  signGitCommit,
  signGitTag,
  forceGitTag,
};

// 用户传了 --exact 就不用给 version 设置 ^ 前缀
// npm 包的 version 前缀相关可以参考: https://docs.npmjs.com/misc/config#save-prefix
this.savePrefix = this.options.exact ? "" : "^";

initialize() {
  // ...
  // 1. git 仓库相关的检验
  if (this.requiresGit) {
  } else {
    // 跳过 git 仓库相关的校验，给个提示
  }

  // 2. 获取到需要更新的包
  this.updates = collectUpdates();
  // 如果该数组为空，就停止执行
  if (!this.updates.length) {}

  // 3. 包相关的生命周期函数(这些函数是在 lerna.json 中设置的，可以在 lerna 文档中找到相关设置)
  this.runPackageLifecycle = createRunner(this.options);

  // 4. 将 获得需要更新版本, 更新版本， 确认更新函数放在一个 tasks 数组中，之后执行 
  const tasks = [
    () => this.getVersionsForUpdates(),
    // versions 是由上一步的 getVersionsForUpdates
    versions => this.setUpdatesForVersions(versions),
    () => this.confirmVersions(),
  ];

  // 5. 检查当前 git 的本地工作区
  if (this.commitAndTag && this.gitOpts.amend !== true) {
    // 这里会把一个检查函数放在 task 函数的队列顶部
    const check = checkUncommittedOnly ? checkWorkingTree.throwIfUncommitted : checkWorkingTree;
    tasks.unshift(() => check(this.execOpts));
  } else {}

  // 6. 执行 task 函数里面内容
  return pWaterfall(tasks);
}

// 只要这些参数存在其中之一就证明目前是需要验证 git 相关的内容
get requiresGit() {
    return (
      this.commitAndTag || this.pushToRemote || this.options.allowBranch || this.options.conventionalCommits
    );
  }

function currentBranch(opts) {
  log.silly("currentBranch");

  const branch = childProcess.execSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], opts);
  log.verbose("currentBranch", branch);

  return branch;
}

this.updates = collectUpdates(
  this.packageGraph.rawPackageList,
  // 项目图
  this.packageGraph,
  // 执行 git 命令的一些 option 有 maxBuffer 和 cwd 两个参数
  this.execOpts,
  // cli 的一些 参数 以及 lerna.json 里面的一些配置和环境变量等
  this.options
).filer(node => {
  // 这里会把满足 pkg.json 里面设置了 private: true 且传递了 --no-private 参数的子package 跳过更新
  if (node.pkg.private && this.options.private === false) {
    // 这里 --no-privte 应该是个默认行为，这是可以给 lerna 来个 pr 的
    return false;
  }

  // 当前包没有 version 参数 也会做个 judge
  if (!node.version) {
    // pkg 的 pkg.json 里面没设置 version 参数，但设置了 private 还是可以跳的
    if (node.pkg.private) {
    } else {
      // 抛错
    }
  }

  // 把有 version 的筛出去
  return !!node.version;
})

function collectUpdates(filteredPackages, packageGraph, execOpts, commandOptions) {
   // ...
  // forced 是需要强制发布的包名的一个 Set 对象
  const forced = getPackagesForOption(useConventionalGraduate ? conventionalGraduate : forcePublish);
  // 获取到当前 monorepo 下的 packageList 是个以package name为key的map对象
  const packages =
    filteredPackages.length === packageGraph.size
      ? packageGraph
      : new Map(filteredPackages.map(({ name }) => [name, packageGraph.get(name)]));

  // --since <ref> 参数 lerna version 这边为 undefined
   let committish = commandOptions.since;

  if (hasTags(execOpts)) {
    // 获取到上次 附注tag(即 git tag -a "v3" -m "xx" 创建的 tag)
    const { sha, refCount, lastTagName } = describeRef.sync(execOpts, commandOptions.includeMergedTags);

    // 上一次 tagCommit 到当前的提交数量为 refCount 
    if (refCount === "0" && forced.size === 0 && !committish) {
      log.notice("", "Current HEAD is already released, skipping change detection.");
      return [];
    }

    // 这个是个测试版本的选项
    if (commandOptions.canary) {
      committish = `${sha}^..${sha}`;
    } else if (!committish) {
      // 如果这个地方连 tag 都没有的话， committish 就会成 undefined, 之后就会用初始化的 commit 来算
      committish = lastTagName;
    }
  }

    // 用户使用了 --conventional-commits --conventional-graduate 这个选项
    if (useConventionalGraduate) {
      // 会把所有预发布的包更新成正式包版本，这里只是给个 log
      if (forced.has("*")) {
        // --force-publish 就发布所有 
        log.info("", "Graduating all prereleased packages");
      } else {
        log.info("", "Graduating prereleased packages");
      }
    } else if (!committish || forced.has('*')) {
      // 使用了 --force-publish 或者 tag 没有找到(之前没有使用过lerna发包)，就会当成所有包需要更新
      log.info("", "Assuming all packages changed");

      // 这个 collectPackages 会有三个参数，还有个 isCandidate 用来添加筛选条件判断哪些包需要更新
      // 这里 isCandidate 没传意味着传进去的 packages 都要更新
      return collectPackges(packages, {
        onInclude: name => log.verbose("updated", name),
        // 这个 excludeDependents 是由 --no-private 参数来决定去 exclude 掉一些 private: true 的包
        excludeDependents,
      })
    }

  // 下面就是正常的收集情况
  // ...
  return collectPackages(packages, {
    // 这里相比较于上面就多了一个 isCandidate, 只有符合下面 isForced(强制更新), needsBump(跳过一些之前没有被 prereleased 的包)
    // hasDiff(有改动的包，在这里 ignoreChanges 会生效一波)
    isCandidate: (node, name) => isForced(node, name) || needsBump(node) || hasDiff(node),
    onInclude: name => log.verbose("updated", name),
    excludeDependents,
  });
}

// 这里的一些 version 函数都是根据之前获取到的 updates 数组来进行相关的工作
const tasks = [
  // 获得需要更新的 version 
  () => this.getVersionsForUpdates(),
  // 将 versions 设置上去，这里执行的时候是个 reduce 过程，实际上是把 上一步函数返回的 versions 值拿到了返回出来
  versions => this.setUpdatesForVersions(versions),
  // 确认更新
  () => this.confirmVersions(),
];

// 中间有个根据选项在 tasks 队列顶端插入 check 函数，检查一下当前 git 的 working tree 是否正常
// ...

// 按照 reduce 去执行任务队列中的方法
return pWaterfall(tasks);

if (repoVersion) {
  // 这里是用户传了 lerna version [] 后面数组里面的 semver bump 参数，可以直接跳掉 prompt 过程，然后对对应的版本去直接 bump
  // 这里对应的是正式的 released 版本
  predicate = makeGlobalVersionPredicate(repoVersion);
} else if (increment && independentVersions) {
  // increament 相较于 repoVersion 的区别在于这里对应的是非正式版本的包，处于一个 prereleased 阶段
  // 过程和上面是差不多的，这里对应的是所有的 indepent 包(即用户在 lerna.json 里面设置了 indepent)
  predicate = node => semver.inc(node.version, increment, resolvePrereleaseId(node.prereleaseId));
} else if (increment) {
  // 这里对应的是 fixed 的包 prereleased 版本更新
} else if (conventionalCommits) {
  // 如果是 --conventional-commits 这里就直接帮用户生成了，不用prompt了
  return this.recommendVersions(resolvePrereleaseId);
} else if (independentVersions) {
  // 这个就是对正常的 indepent 包进行 prompt 的一个过程
  predicate = makePromptVersion(resolvePrereleaseId);
} else {
  // fixed 包进行 prompt
  // ...
}

// 上面的 predicate 是个返回 newversion 的函数
// 会放到 getVersion 即其返回的 newVersion，然后再用 reduceVersions 这个方法去生成上面我提到的 Map 对象
// reduceVersion 也是一个典型的 reduce 应用(即上一步的结果可以用于下一步的函数执行)
return Promise.resolve(predicate).then(getVersion => this.reduceVersions(getVersion));

setUpdatesForVersions(versions) {
    if (this.project.isIndependent() || versions.size === this.packageGraph.size) {
      // 只需要检查部分固定的版本
      this.updatesVersions = versions;
    } else {
      let hasBreakingChange;
      for (const [name, bump] of versions) {
        // 这里直接看代码知道 breakChange 的判断比我介绍要直观多，代码在下面
        hasBreakingChange = hasBreakingChange || isBreakingChange(this.packageGraph.get(name).version, bump);
      }
      if (hasBreakingChange) {
        this.updates = Array.from(this.packageGraph.values());
        // 把 private 设成 true 的包筛出去
        if (this.options.private === false) {
          this.updates = this.updates.filter(node => !node.pkg.private);
        }
        this.updatesVersions = new Map(this.updates.map(node => [node.name, this.globalVersion]));
      } else {
        this.updatesVersions = versions;
      }
    }

    this.packagesToVersion = this.updates.map(node => node.pkg);
  }

// releaseType 能判断是包的哪一位发生了变化，这里的判断其实有些迷惑行为.jpg
const releaseType = semver.diff(currentVersion, nextVersion);
let breaking;
if (releaseType === "major") {
  // self-evidently
  breaking = true;
} else if (releaseType === "minor") {
  // 0.1.9 => 0.2.0 is breaking
  // lt 是小于
  breaking = semver.lt(currentVersion, "1.0.0");
} else if (releaseType === "patch") {
  // 0.0.1 => 0.0.2 is breaking(?)
  breaking = semver.lt(currentVersion, "0.1.0");
} else {
  // versions are equal, or any prerelease
  breaking = false;
}

execute(){
   // 放入更新包版本的函数
    const tasks = [() => this.updatePackageVersions()];
    // 用户可以通过设置 --no-git-tag-version 来跳过 tag 和 commit 的过程
    // 这个 commitAndTag 默认为 true 
    if (this.commitAndTag) {
      tasks.push(() => this.commitAndTagUpdates());
    } else {
      this.logger.info("execute", "Skipping git tag/commit");
    }

   // pushToRemote 受到 commitAndTag 和 ammend 参数的共同影响
   // 用户可以单独通过 --amend 来让 lerna version 最后不 push
    if (this.pushToRemote) {
      tasks.push(() => this.gitPushToRemote());
    } else {
      this.logger.info("execute", "Skipping git push");
    }

   // 这个 createRelease 使用来设置特定平台的 release发布的，配合 --conventional-commits 来一起使用
   // 这个不做详细的介绍
    if (this.createRelease) {
      this.logger.info("execute", "Creating releases...");
      tasks.push(() =>
        createRelease(
          this.options.createRelease,
          { tags: this.tags, releaseNotes: this.releaseNotes },
          { gitRemote: this.options.gitRemote, execOpts: this.execOpts }
        )
      );
    } else {
      this.logger.info("execute", "Skipping releases");
    }

   // pWaterfall 这个方法就是封装了一下 p-reduce 这个库函数
    return pWaterfall(tasks).then(() => {
      // 这里的 composed 是用来标记当前是 lerna version 还是 lerna publish 在执行
      if (!this.composed) {
        // lerna version 就结束这个过程
        this.logger.success("version", "finished");
      }
      // 如果是 lerna publish 就耀把这些参数返回出去
      return {
        updates: this.updates,
        updatesVersions: this.updatesVersions,
      };
    });
 }

updatePackageVersions() {
  const { conventionalCommits, changelogPreset, changelog = true } = this.options;
  const independentVersions = this.project.isIndependent();
  const rootPath = this.project.manifest.location;
  // 记录修改的文件
  const changedFiles = new Set();

  // 这里的一系列链式调用以及异步方法都是用的 promise，作者甚至在源码这里吐槽想用 async/await...
  let chain = Promise.resolve();

  // 这里的 action 其实也是个 reduce 执行过程，即前一步的函数会把结果给后面
  const actions = [
    // .. 里面是一堆和 pkg 更新有关的函数
    // 在这一步会有个函数更新掉版本
    pkg => {
        // 把新版本设置上
       pkg.set("version", this.updatesVersions.get(pkg.name));

      // 与 pkg 有关的依赖(也要跟着一起更新)
      // 这里也是从 core 那边拿到的依赖图，然后可以得到一个 pkg 依赖了哪些 lerna 内部的库，那些内部库也要跟着更新
      for (const [depName, resolved] of this.packageGraph.get(pkg.name).localDependencies) {
          const depVersion = this.updatesVersions.get(depName);
          if (depVersion && resolved.type !== "directory") {
            // don't overwrite local file: specifiers, they only change during publish
            pkg.updateLocalDependency(resolved, depVersion, this.savePrefix);
          }
       }
      // 更新 pkg-lock.json 中版本，并且将修改反映到 pkg 文件中(pkg.serialize())
      // 然后 then 的时候将修改记录下来在 changeFiles 中
       return Promise.all([updateLockfileVersion(pkg), pkg.serialize()]).then(// ...);
    }
    // ..
  ]；

  // 如果是 --conventional-commits 则会帮我们自动生成 CHANGELOG
  // 下面的 updateChangelog 方法也是可以看到的
  if (conventionalCommits && changelog) {
      // we can now generate the Changelog, based on the
      // the updated version that we're about to release.
      const type = independentVersions ? "independent" : "fixed";

      actions.push(pkg =>
        ConventionalCommitUtilities.updateChangelog(pkg, type, {
          changelogPreset,
          rootPath,
          tagPrefix: this.tagPrefix,
        }).then(({ logPath, newEntry }) => {
          // commit the updated changelog
          changedFiles.add(logPath);
          // 添加 released notes
          if (independentVersions) {
            this.releaseNotes.push({
              name: pkg.name,
              notes: newEntry,
            });
          }
          return pkg;
        })
      );
    }
  // pPipe 是封装的一个按照 reduce 顺序执行异步函数的方法
  // 这里会把前面的 action 一一执行，得到最后一步返回的结果
  const mapUpdate = pPipe(actions);

  // 按照拓扑顺序去执行前面拿到的一些需要更新的包，以及需要更新的 pathFile
  chain = chain.then(() =>
      runTopologically(this.packagesToVersion, mapUpdate, {
        concurrency: this.concurrency,
        rejectCycles: this.options.rejectCycles,
      })
   );

  // fixed 类型的 monorepo 项目的更新，会多一个 lerna.json 修改
  // 因为要修改里面的版本，这里也会和上面一样有 --conventional-commits 的判断，不做过多讲解
 if (!independentVersions) {}

 // 前面有说这个值默认是 true，这里会把修改 git add 到缓存区
 if (this.commitAndTag) {
     chain = chain.then(() => gitAdd(Array.from(changedFiles), this.gitOpts, this.execOpts));
 }

 return chain;
}

commitAndTagUpdates() {
    let chain = Promise.resolve();

  // 这一步会完成 git add . 和 git tag 的操作，commit 的 message 可以用户自行设置或者 lerna 会帮你自动生成
    if (this.project.isIndependent()) {
      chain = chain.then(() => this.gitCommitAndTagVersionForUpdates());
    } else {
      chain = chain.then(() => this.gitCommitAndTagVersion());
    }

    chain = chain.then(tags => {
      this.tags = tags;
    });
    // ...

    return chain;
}

gitPushToRemote() {
  this.logger.info("git", "Pushing tags...");

  // gitPush 简单封装了一下 git push 命令
  return gitPush(this.gitRemote, this.currentBranch, this.execOpts);
}