@proteinjs/build 1.9.2 → 2.0.0

package/src/versionWorkspace.ts

@@ -13,8 +13,14 @@ const fixedVersionWorkspacesToVersion: { [workspacePath: string]: boolean } = {}
 
 export async function versionWorkspace() {
   const dryRun = isDryRun();
+  const planOnly = isPlanOnly();
 
-  if (dryRun) {
+  if (planOnly) {
+    logger.info({
+      message:
+        'Plan-only mode enabled. Scan + commit-leaves + would-be bumps will be computed and logged; nothing will be written to disk, built, tested, published, committed, or pushed.',
+    });
+  } else if (dryRun) {
     logger.info({ message: 'Dry run mode enabled. Publish and push operations will be skipped.' });
   }
   const workspacePath = process.cwd();
@@ -23,8 +29,8 @@ export async function versionWorkspace() {
   if (workspaceRootDirty) {
     logger.info({ message: `> Workspace root is dirty, will skip pull/push for root repo` });
   }
-  if (dryRun) {
-    logger.info({ message: `> Dry run: skipping pullWorkspace for (${workspacePath})` });
+  if (dryRun || planOnly) {
+    logger.info({ message: `> Skipping pullWorkspace for (${workspacePath})` });
   } else {
     await pullWorkspace(workspacePath, workspaceRootDirty);
   }
@@ -42,22 +48,91 @@ export async function versionWorkspace() {
   });
 
   logger.info({ message: `> Versioning workspace (${workspacePath})` });
+
+  // Phase 0: scan every candidate package's unpushed commits up front. This
+  // gives us a map of packages that have their own local changes to ship,
+  // separate from the traditional "dependency bumped, cascade" trigger.
+  const commitBumps = await scanCommitBumps(filteredPackageNames, packageMap);
+  if (commitBumps.size === 0) {
+    logger.info({ message: `> No packages have unpushed commits` });
+  } else {
+    const scanSummary = Array.from(commitBumps.entries())
+      .map(([name, bump]) => `${cw.color(name)}:${bump}`)
+      .join(', ');
+    logger.info({ message: `> Packages with unpushed commits: ${scanSummary}` });
+  }
+
+  // Phase 1: identify commit-leaves — packages with unpushed commits whose
+  // direct workspace-local deps have none. These are the roots of change
+  // and must be versioned+published first; once they're out, the cascade of
+  // dep-version rewrites propagates to the rest.
+  const commitLeaves = computeCommitLeaves(commitBumps, packageGraph, filteredPackageNames);
+  if (commitLeaves.length > 0) {
+    logger.info({
+      message: `> Commit-leaves (root changes, will publish first): ${commitLeaves.map((n) => cw.color(n)).join(', ')}`,
+    });
+  }
+
+  // Phase 2: unified topo-ordered loop. For each package we combine two
+  // signals: own unpushed commits (from `commitBumps`) and dep-version
+  // rewrites (from `applyDependencyVersionRewrites`). A package publishes
+  // iff either signal fires. The effective bump is the max of (own-commit
+  // bump) and (cascade → 'patch'). Topo order (deps-first) ensures leaves
+  // publish before dependents that need to consume their new versions, and
+  // any non-leaf commit-haver still gets its own-commit bump respected
+  // rather than being demoted to 'patch' by the cascade.
   for (const packageName of filteredPackageNames) {
     const localPackage = packageMap[packageName];
     const skipBumpingPackageVersion = isInFixedVersionWorkspace(localPackage);
-    const dependenciesChanged = await bumpDependencies(
-      localPackage,
-      packageMap,
-      packageGraph,
-      skipBumpingPackageVersion
-    );
-    if (!dependenciesChanged) {
+    const ownBump = skipBumpingPackageVersion ? undefined : commitBumps.get(packageName);
+    const dependenciesChanged = await applyDependencyVersionRewrites(localPackage, packageMap, packageGraph);
+    const cascadeBump: CommitBump | undefined = dependenciesChanged ? 'patch' : undefined;
+    const effectiveBump = maxBump(ownBump, cascadeBump);
+
+    if (!effectiveBump && !dependenciesChanged) {
       continue;
     }
 
-    await buildAndTest(localPackage);
+    if (effectiveBump && !skipBumpingPackageVersion) {
+      const currentVersion = localPackage.packageJson.version;
+      // In-memory version mutation runs in plan-only too so downstream
+      // packages see the right dep versions when we simulate cascades.
+      localPackage.packageJson.version = semver.inc(currentVersion, effectiveBump);
+      const sourceNote = ownBump
+        ? cascadeBump
+          ? `own+cascade, own=${ownBump}`
+          : `own=${ownBump}`
+        : 'dep cascade';
+      const planPrefix = planOnly ? 'would bump' : 'bumping';
+      logger.info({
+        message: `(${cw.color(packageName)}) ${planPrefix} version (${effectiveBump}; ${sourceNote}) from ${currentVersion} -> ${localPackage.packageJson.version}`,
+      });
+    }
+
+    // Fixed-version workspace tracking: record even in plan-only so we can
+    // report the would-be synced version below. This is metadata only — the
+    // actual sync (disk write, commit, push) is gated by the planOnly /
+    // dryRun guards after the loop.
     if (isInFixedVersionWorkspace(localPackage) && localPackage.workspace) {
       fixedVersionWorkspacesToVersion[localPackage.workspace.path] = true;
+    }
+
+    if (planOnly) {
+      // Plan-only: skip the disk write, the build/test, publish, push/tag,
+      // and the eventual syncFixedVersionWorkspaces pass. The in-memory
+      // mutation above is enough to keep the simulated cascade correct for
+      // the remaining packages in this loop.
+      continue;
+    }
+
+    if (effectiveBump || dependenciesChanged) {
+      await Fs.writeFiles([
+        { path: localPackage.filePath, content: JSON.stringify(localPackage.packageJson, null, 2) },
+      ]);
+    }
+
+    await buildAndTest(localPackage);
+    if (isInFixedVersionWorkspace(localPackage) && localPackage.workspace) {
       logger.info({
         message: `(${cw.color(packageName)}) skipping version push for package in a fixed-version workspace`,
       });
@@ -71,6 +146,13 @@ export async function versionWorkspace() {
     await pushAndTag(localPackage);
   }
 
+  if (planOnly) {
+    await logPlannedFixedVersionSyncs(Object.keys(fixedVersionWorkspacesToVersion), packageMap, workspaceToPackageMap);
+    logger.info({ message: `> Plan-only: skipping fixed-version sync, metarepo push, and symlink refresh` });
+    logger.info({ message: `> Finished versioning workspace (${workspacePath}) [plan-only]` });
+    return;
+  }
+
   const pushWithoutSync = true;
   await syncFixedVersionWorkspaces(
     Object.keys(fixedVersionWorkspacesToVersion),
@@ -97,6 +179,35 @@ function isDryRun() {
   return false;
 }
 
+/**
+ * Plan-only mode: the strictest possible preview. Runs Phase 0 (commit-bump
+ * scan) and Phase 1 (commit-leaf detection) so you can see which packages
+ * would be published and at what level, then simulates the topo-ordered
+ * cascade in memory (for correct would-be bump reporting) but:
+ *
+ *   - does NOT write any package.json or lerna.json to disk
+ *   - does NOT run `npm install` / lint / build / test
+ *   - does NOT publish, commit, push, tag, or refresh symlinks
+ *
+ * Intended for a fast preview of "what will this release do?" Implies
+ * dry-run for the few checks that need a binary answer (e.g. `publish`'s
+ * own dry-run guard), but the stricter plan-only guards in the main loop
+ * mean those code paths never execute in the first place.
+ */
+function isPlanOnly() {
+  const args = process.argv.slice(2);
+  if (args.includes('--plan-only') || args.includes('--planonly') || args.includes('--plan')) {
+    return true;
+  }
+
+  const envFlag = process.env.VERSION_WORKSPACE_PLAN_ONLY ?? process.env.PLAN_ONLY;
+  if (envFlag) {
+    return envFlag === 'true' || envFlag === '1';
+  }
+
+  return false;
+}
+
 function isInFixedVersionWorkspace(localPackage: LocalPackage) {
   return (
     localPackage.workspace &&
@@ -155,12 +266,22 @@ async function pullWorkspace(workspacePath: string, skipRootRepo = false) {
   logger.info({ message: `> Finished pulling workspace (${workspacePath})` });
 }
 
-async function bumpDependencies(
+/**
+ * Rewrite `localPackage`'s dependency-version fields in package.json to match
+ * the current in-memory versions of its workspace-local deps. Returns true if
+ * any dep version was rewritten (i.e. a dep's already-bumped version now
+ * differs from what this package.json records). Pure rewrite — does NOT bump
+ * `localPackage`'s own version; the caller decides that by combining this
+ * result with the commit-scan map (see `versionWorkspace`).
+ *
+ * Writing the package.json to disk is left to the caller too, so we can apply
+ * the own-version bump in the same write.
+ */
+async function applyDependencyVersionRewrites(
   localPackage: LocalPackage,
   packageMap: LocalPackageMap,
-  packageGraph: any,
-  skipBumpingPackageVersion = false
-) {
+  packageGraph: any
+): Promise<boolean> {
   const localDependencies = packageGraph.successors(localPackage.name);
   if (!localDependencies || localDependencies.length == 0) {
     return false;
@@ -193,20 +314,63 @@ async function bumpDependencies(
     dependenciesChanged = true;
   }
 
-  if (dependenciesChanged) {
-    if (!skipBumpingPackageVersion) {
-      const currentVersion = localPackage.packageJson.version;
-      const packageDir = path.dirname(localPackage.filePath);
-      const bump = (await hasFeatureCommits(packageDir)) ? 'minor' : 'patch';
-      localPackage.packageJson.version = semver.inc(currentVersion, bump);
-      logger.info({
-        message: `(${cw.color(localPackage.name)}) bumping version (${bump}) from ${currentVersion} -> ${localPackage.packageJson.version}`,
-      });
+  return dependenciesChanged;
+}
+
+/**
+ * Up-front scan: for each candidate package, classify the unpushed commits
+ * in its own git repo into a semver bump level. Returns a map (only contains
+ * entries for packages with classifiable unpushed commits). Packages with no
+ * unpushed commits or missing upstream branches are absent from the map.
+ *
+ * This is the input to `computeCommitLeaves` and to the per-package bump-level
+ * combine in the main loop.
+ */
+async function scanCommitBumps(
+  packageNames: string[],
+  packageMap: LocalPackageMap
+): Promise<Map<string, CommitBump>> {
+  const result = new Map<string, CommitBump>();
+  for (const packageName of packageNames) {
+    const localPackage = packageMap[packageName];
+    const packageDir = path.dirname(localPackage.filePath);
+    const bump = await classifyUnpushedCommits(packageDir);
+    if (bump) {
+      result.set(packageName, bump);
     }
-    await Fs.writeFiles([{ path: localPackage.filePath, content: JSON.stringify(localPackage.packageJson, null, 2) }]);
   }
+  return result;
+}
 
-  return dependenciesChanged;
+/**
+ * A package is a "commit-leaf" if it has unpushed commits (i.e. appears in
+ * `scanMap`) AND none of its direct workspace-local deps have unpushed
+ * commits. These are the true sources of change — they trigger the entire
+ * cascade, so they must be versioned + published first.
+ *
+ * Direct deps only (not transitive): the topo-ordered main loop handles
+ * transitivity naturally by cascading dep-version rewrites forward.
+ *
+ * Returns leaves in topo order (deps-first) so independent leaves publish
+ * in a deterministic, dependency-respecting sequence.
+ */
+function computeCommitLeaves(
+  scanMap: Map<string, CommitBump>,
+  packageGraph: any,
+  sortedPackageNames: string[]
+): string[] {
+  const leaves: string[] = [];
+  for (const packageName of sortedPackageNames) {
+    if (!scanMap.has(packageName)) {
+      continue;
+    }
+    const directDeps: string[] = packageGraph.successors(packageName) ?? [];
+    const anyDepHasCommits = directDeps.some((dep) => scanMap.has(dep));
+    if (!anyDepHasCommits) {
+      leaves.push(packageName);
+    }
+  }
+  return leaves;
 }
 
 type DependencyVersion = { prefix?: string; version: string; isLocalPath?: boolean };
@@ -292,13 +456,54 @@ async function syncFixedVersionWorkspaces(
   logger.info({ message: `> Synced fixed-version workspaces` });
 }
 
+/**
+ * Plan-only companion to `syncFixedVersionWorkspaces`: for each fixed-version
+ * workspace that would be touched, classify unpushed commits at the workspace
+ * root and log the version it would sync to. No disk writes, no git ops.
+ */
+async function logPlannedFixedVersionSyncs(
+  fixedVersionWorkspacePaths: string[],
+  packageMap: LocalPackageMap,
+  workspaceToPackageMap: { [workspacePath: string]: string[] }
+) {
+  if (fixedVersionWorkspacePaths.length === 0) {
+    return;
+  }
+  logger.info({ message: `> Fixed-version workspaces that would sync:` });
+  for (const workspacePath of fixedVersionWorkspacePaths) {
+    const workspacePackageNames = workspaceToPackageMap[workspacePath] ?? [];
+    const anyPackageInWs = workspacePackageNames.map((n) => packageMap[n]).find((p) => p?.workspace?.lernaJson);
+    const lernaJson = anyPackageInWs?.workspace?.lernaJson;
+    const repoName = path.basename(workspacePath.endsWith(path.sep) ? workspacePath.slice(0, -1) : workspacePath);
+    if (!lernaJson) {
+      logger.info({
+        message: `  (${cw.color(repoName)}) would sync fixed-version workspace (lerna.json not available; bump level unknown)`,
+      });
+      continue;
+    }
+    // Mirror `syncFixedVersions`: classify commits at the workspace root;
+    // fall back to 'patch' when there are no classifiable unpushed commits
+    // (the sync was triggered purely by a sub-package's dep-version rewrite).
+    const bump = (await classifyUnpushedCommits(workspacePath)) ?? 'patch';
+    const wouldBeVersion = semver.inc(lernaJson.version, bump);
+    logger.info({
+      message: `  (${cw.color(repoName)}) would sync fixed-version workspace ${lernaJson.version} -> ${wouldBeVersion} (${bump})`,
+    });
+  }
+}
+
 async function syncFixedVersions(workspacePath: string, localPackages: LocalPackage[]): Promise<string | false> {
   const lernaJson = localPackages[0].workspace?.lernaJson;
   if (!lernaJson) {
     throw new Error(`Cannot find lerna.json for workspace: ${workspacePath}`);
   }
 
-  const bump = (await hasFeatureCommits(workspacePath)) ? 'minor' : 'patch';
+  // Fixed-version workspaces bump at the workspace-root level; use the
+  // net-bump classifier so a `feat!`/`BREAKING CHANGE` in any sub-package
+  // promotes the whole workspace to major. Fall back to patch when there
+  // are no classifiable unpushed commits (i.e. nothing to publish, but we
+  // were called because dep rewrites on a sub-package triggered the sync).
+  const bump = (await classifyUnpushedCommits(workspacePath)) ?? 'patch';
   const highestVersion = semver.inc(lernaJson.version, bump);
   if (!highestVersion) {
     throw new Error(`Lerna version not specified for workspace: ${workspacePath}`);
@@ -748,19 +953,86 @@ async function hasPendingChanges(dir: string): Promise<boolean> {
   });
 }
 
-async function hasFeatureCommits(dir: string): Promise<boolean> {
+export type CommitBump = 'major' | 'minor' | 'patch';
+
+const BUMP_ORDER: Record<CommitBump, number> = { patch: 1, minor: 2, major: 3 };
+
+function maxBump(a: CommitBump | undefined, b: CommitBump | undefined): CommitBump | undefined {
+  if (!a) {
+    return b;
+  }
+  if (!b) {
+    return a;
+  }
+  return BUMP_ORDER[a] >= BUMP_ORDER[b] ? a : b;
+}
+
+/**
+ * Classify the net semver bump implied by the set of commits in HEAD that
+ * aren't yet on the tracked upstream branch (`git log @{u}..HEAD`).
+ *
+ *   - `major`: any commit declares `BREAKING CHANGE` in subject/body, or
+ *              uses the conventional-commits `!` marker (`feat!:`,
+ *              `fix(scope)!:`, etc.).
+ *   - `minor`: any commit is a `feat` (type, optionally scoped, no `!`).
+ *   - `patch`: any other commit is present (fix/chore/refactor/docs/…).
+ *   - `undefined`: no unpushed commits, OR no tracked upstream (the `@{u}`
+ *                  shorthand errors silently — treated as "nothing to ship").
+ *
+ * Uses `%B` (full body) separated by a null byte so footer-style
+ * `BREAKING CHANGE:` lines are visible. Shells out to `git` directly so we
+ * don't depend on any repo state beyond a valid upstream ref.
+ */
+export async function classifyUnpushedCommits(dir: string): Promise<CommitBump | undefined> {
   return new Promise((resolve) => {
-    exec('git log @{u}..HEAD --oneline', { cwd: dir }, (error, stdout) => {
+    // `\x00` as record separator; each record is the full commit message body.
+    exec('git log @{u}..HEAD --format=%B%x00', { cwd: dir }, (error, stdout) => {
       if (error || !stdout.trim()) {
-        resolve(false);
+        resolve(undefined);
         return;
       }
-      const hasFeature = stdout.split('\n').some((line) => /^[a-f0-9]+\s+feat[\s(:]/i.test(line));
-      resolve(hasFeature);
+      const commits = stdout.split('\x00').map((s) => s.trim()).filter((s) => s.length > 0);
+      let result: CommitBump | undefined;
+      for (const commit of commits) {
+        result = maxBump(result, classifyCommitMessage(commit));
+        if (result === 'major') {
+          break;
+        }
+      }
+      resolve(result);
     });
   });
 }
 
+/**
+ * Classify a single commit message by conventional-commits rules. Exported
+ * so unit tests can exercise it without spawning git.
+ */
+export function classifyCommitMessage(message: string): CommitBump | undefined {
+  if (!message.trim()) {
+    return undefined;
+  }
+  const [subject, ...rest] = message.split('\n');
+  const body = rest.join('\n');
+
+  // Breaking-change markers. `type!:` / `type(scope)!:` on the subject,
+  // or `BREAKING CHANGE:` / `BREAKING-CHANGE:` anywhere (subject or body/footer).
+  if (/^\w+(\([^)]*\))?!:/.test(subject)) {
+    return 'major';
+  }
+  if (/BREAKING[ -]CHANGE\s*:/i.test(`${subject}\n${body}`)) {
+    return 'major';
+  }
+
+  // `feat` type (optionally scoped) on the subject → minor.
+  if (/^feat(\([^)]*\))?:/i.test(subject)) {
+    return 'minor';
+  }
+
+  // Any other commit counts as patch.
+  return 'patch';
+}
+
 export async function evictGitLocks(workspacePath: string) {
   const gitDir = path.join(workspacePath, '.git');
   const lockFiles = await Fs.getFilePathsMatchingGlob(gitDir, '**/*.lock');

package/test/classifyCommitMessage.test.ts

@@ -0,0 +1,95 @@
+import { classifyCommitMessage } from '../src/versionWorkspace';
+
+describe('classifyCommitMessage', () => {
+  describe('major (breaking-change)', () => {
+    it('classifies `feat!:` as major', () => {
+      expect(classifyCommitMessage('feat!: remove deprecated api')).toBe('major');
+    });
+
+    it('classifies `fix!:` as major', () => {
+      expect(classifyCommitMessage('fix!: change default behavior')).toBe('major');
+    });
+
+    it('classifies scoped `feat(scope)!:` as major', () => {
+      expect(classifyCommitMessage('feat(auth)!: replace cookie format')).toBe('major');
+    });
+
+    it('classifies `BREAKING CHANGE:` footer as major', () => {
+      expect(
+        classifyCommitMessage(
+          'feat: reorganize tool outputs\n\nDetails here.\n\nBREAKING CHANGE: tool result shape changed'
+        )
+      ).toBe('major');
+    });
+
+    it('classifies `BREAKING-CHANGE:` (hyphenated) as major', () => {
+      expect(classifyCommitMessage('refactor: blah\n\nBREAKING-CHANGE: something')).toBe('major');
+    });
+
+    it('classifies `BREAKING CHANGE:` in subject as major', () => {
+      expect(classifyCommitMessage('feat: BREAKING CHANGE: removed old flow')).toBe('major');
+    });
+  });
+
+  describe('minor (feat)', () => {
+    it('classifies `feat:` as minor', () => {
+      expect(classifyCommitMessage('feat: add streaming support')).toBe('minor');
+    });
+
+    it('classifies scoped `feat(scope):` as minor', () => {
+      expect(classifyCommitMessage('feat(ui): new button')).toBe('minor');
+    });
+
+    it('is case-insensitive for type', () => {
+      expect(classifyCommitMessage('FEAT: uppercase type')).toBe('minor');
+    });
+  });
+
+  describe('patch (everything else)', () => {
+    it('classifies `fix:` as patch', () => {
+      expect(classifyCommitMessage('fix: off-by-one')).toBe('patch');
+    });
+
+    it('classifies scoped `fix(scope):` as patch', () => {
+      expect(classifyCommitMessage('fix(parser): handle empty input')).toBe('patch');
+    });
+
+    it('classifies `chore:` as patch', () => {
+      expect(classifyCommitMessage('chore: bump deps')).toBe('patch');
+    });
+
+    it('classifies `docs:` as patch', () => {
+      expect(classifyCommitMessage('docs: update README')).toBe('patch');
+    });
+
+    it('classifies `refactor:` as patch', () => {
+      expect(classifyCommitMessage('refactor: extract helper')).toBe('patch');
+    });
+
+    it('classifies non-conventional messages as patch', () => {
+      expect(classifyCommitMessage('some random commit')).toBe('patch');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('returns undefined for an empty message', () => {
+      expect(classifyCommitMessage('')).toBeUndefined();
+    });
+
+    it('returns undefined for a whitespace-only message', () => {
+      expect(classifyCommitMessage('   \n\n  ')).toBeUndefined();
+    });
+
+    it('does not treat `feature:` as a feat', () => {
+      // Only exact `feat` type should promote to minor; `feature` is not a
+      // Conventional Commits type and falls through to patch.
+      expect(classifyCommitMessage('feature: something')).toBe('patch');
+    });
+
+    it('does not treat a mid-sentence "BREAKING CHANGE" without the colon as major', () => {
+      // The colon is the conventional-commits signal; without it, this is
+      // just prose in the body.
+      expect(classifyCommitMessage('feat: this is NOT a BREAKING CHANGE really')).toBe('minor');
+    });
+  });
+});

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Brent Bahry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.