enablement-build-monorepo-version 1.0.27 → 2.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Chris Doty
+Copyright (c) 2026 Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,225 @@
-# enablement-build-monorepo-version
-
-This detects changes in the children packages of a monorepo.
-
-
+# enablement-build-monorepo-version
+
+Detects which packages in a monorepo have changed by hashing their source folders, computes the next semantic version for each changed package, and emits Azure DevOps pipeline variables. Dependency propagation is recursive — changing a leaf package automatically marks all transitive dependents as changed too.
+
+## Usage
+
+```bash
+npx enablement-build-monorepo-version@latest [flags]
+```
+
+---
+
+## How it works
+
+1. **Hash** — Each subfolder under the configured `children` directories is hashed (source files only; `node_modules`, `dist`, etc. are excluded).
+2. **Compare** — Hashes are diffed against a saved state file (`.cicd/hash.json` by default).
+3. **Propagate** — Any package whose hash changed is marked `CHANGED`. All transitive dependents (read from `dependencies.json`) are also marked `CHANGED` via a breadth-first traversal.
+4. **Version** — The next semver is determined from the current version found in each package's version manifest (`package.json`, `version.json`, or `pyproject.toml`) using conventional-commit rules.
+5. **Output** — Azure DevOps `##vso[task.setvariable]` lines are written to stdout for consumption by downstream pipeline steps.
+
+---
+
+## CLI flags
+
+| Flag | Default | Description |
+|---|---|---|
+| `--hash` | off | Compute and **save** current hashes to the hash state file. Must be run before `--changed` / `--version` to establish a baseline. |
+| `--changed` | off | Print the list of changed packages and emit a `changed` pipeline variable. |
+| `--version` | off | Emit a pipeline variable per changed package containing its next version. |
+| `--save` | off | Write the bumped version back into each changed package's version manifest (`package.json`, `version.json`, or `pyproject.toml`). Requires `--version`. |
+| `--tag` | off | Create a git tag (`<short-name>/<version>`) for each changed package, where `short-name` is the npm package name with its scope prefix removed (e.g. `@scope/lib-foo` → `lib-foo/1.2.3`). |
+| `--retag` | off | Convert existing tags that use the old folder-name format to the new short-package-name format. Non-destructive: old tags are left in place. |
+| `--init` | off | Inject `release:*` scripts into the root `package.json` of the target project. Adds scripts that are missing; strips `--children` from any that already exist. Combine with `--try` to preview changes. |
+| `--try` | off | Dry-run mode. Prints what each operation **would** do without writing any files, creating tags, or modifying any manifests. Combine with any other flags to preview their effect. |
+| `--debug` | off | Verbose logging of hashes, comparisons, and version resolution. |
+| `--children <dirs>` | auto-detect | Comma- or space-separated list of top-level directories to scan (e.g. `components,saas`). When omitted, directories are read from `pnpm-workspace.yaml` or `package.json` workspaces automatically. Falls back to `packages` if neither file is found. |
+| `--platform <name>` | auto-detect | Force the CI output format: `ado` (Azure DevOps) or `github` (GitHub Actions). Auto-detected from the presence of a `.github/` directory. |
+| `--prefixPath <path>` | `./` | Root path prepended to all file lookups. Useful when running from a different working directory. |
+| `--hashFile <path>` | auto-detect | Path (relative to `prefixPath`) where hash state is stored between runs. Defaults to `.github/hash.json` if a `.github/` directory exists at the root, otherwise `.cicd/hash.json`. |
+| `--dependencies <path>` | `dependencies.json` | Path to the NX-style dependency graph used for transitive change propagation. |
+| `--hashExcludeFolders <list>` | see below | Comma-separated folder names to skip when hashing. |
+| `--hashExcludeFiles <list>` | see below | Comma-separated file names to skip when hashing. |
+| `--hashFiles <list>` | — | Comma-separated individual file paths to include in the hash state (outside of `children` folders). |
+
+**Default excluded folders:** `node_modules`, `coverage`, `dist`, `bin`, `obj`, `__pycache__`, `.vs`, `.nx`, `.vscode`, `.idea`, `.git`, `.github`, `.azuredevops`, `.release`
+
+**Default excluded files:** `.npmrc`, `CHANGELOG.md`, `README.md`
+
+---
+
+## Supported version manifests
+
+Each package directory is scanned for a version manifest in this priority order:
+
+| File | Format | Version field |
+|---|---|---|
+| `package.json` | JSON | `"version": "1.2.3"` |
+| `version.json` | JSON (same shape as `package.json`) | `"version": "1.2.3"` |
+| `pyproject.toml` | TOML | `version = "1.2.3"` under `[project]` or `[tool.poetry]` |
+
+The first file found is used. If none exists the package is treated as version `0.0.0`.
+
+---
+
+## Version bump rules
+
+Versions follow semver and are bumped based on the **current version** in the package's version manifest:
+
+| Trigger | Bump | Example |
+|---|---|---|
+| `fix:` prefix in any recent commit message | Patch (`0.0.x`) | `1.2.3` → `1.2.4` |
+| `feat:` prefix in any recent commit message | Minor (`0.x.0`) | `1.2.3` → `1.3.0` |
+| `BREAKING` anywhere in any recent commit message | Major (`x.0.0`) | `1.2.3` → `2.0.0` |
+
+> Currently the version bump always applies a patch increment — conventional-commit scanning via `git log` is stubbed. The bump logic is in `src/version.mjs`.
+
+---
+
+## Pipeline variable output
+
+The output format is auto-detected from the presence of a `.github/` directory at the root. It can also be forced with `--platform ado` or `--platform github`.
+
+### Azure DevOps (default when no `.github/` directory)
+
+Variables are written to stdout using the `##vso` task command:
+
+```
+##vso[task.setvariable variable=<safeName>;isoutput=true;]<version>
+##vso[task.setvariable variable=changed;isoutput=true]["pkg-a","pkg-b"]
+##vso[task.setvariable variable=components;isoutput=true]true
+```
+
+### GitHub Actions (when `.github/` directory is present)
+
+Variables are written to the `$GITHUB_OUTPUT` file (falls back to stdout if the env var is not set):
+
+```
+safeName=<version>
+changed=["pkg-a","pkg-b"]
+components=true
+```
+
+Consume them in a subsequent step with `${{ steps.<step-id>.outputs.<name> }}`.
+
+---
+
+### Variable reference
+
+| Variable | Value |
+|---|---|
+| `<safeName>` (per changed package) | Next version for changed packages; previous version for unchanged ones. `safeName` is the folder name with `-`, `_`, and `.` removed. |
+| `changed` | JSON array of changed package folder names. |
+| `<folderName>` | `true` for each top-level folder containing at least one changed package. |
+
+---
+
+## `dependencies.json` format
+
+The file must be an NX project graph export. The relevant section is `graph.dependencies`, where each key is a package name and its value is an array of `{ source, target }` edges:
+
+```json
+{
+  "graph": {
+    "dependencies": {
+      "@scope/pkg-a": [
+        { "source": "@scope/pkg-a", "target": "@scope/shared-lib", "type": "static" }
+      ]
+    }
+  }
+}
+```
+
+Generate it from an NX workspace with:
+
+```bash
+nx graph --file=dependencies.json
+```
+
+If the file is missing or the `--dependencies` path doesn't exist, change propagation is skipped and only directly-changed packages are reported (a warning is printed).
+
+---
+
+## Typical pipeline usage
+
+```yaml
+# Step 1 — establish baseline hashes (run once, commit the result)
+# Workspace directories are auto-detected from pnpm-workspace.yaml / package.json workspaces
+- script: npx enablement-build-monorepo-version --hash
+
+# Step 2 — detect changes and emit version variables for downstream steps
+- script: npx enablement-build-monorepo-version --changed --version
+  name: versions
+
+# Step 3 — consume a variable from step 2
+- script: echo "$(versions.mypackagename)"
+```
+
+To bump and persist the new versions back to `package.json`:
+
+```bash
+npx enablement-build-monorepo-version --changed --version --save
+```
+
+To override the auto-detected directories, pass `--children` explicitly:
+
+```bash
+npx enablement-build-monorepo-version --changed --version --children components,saas
+```
+
+---
+
+## Bootstrapping a new repo
+
+Run `--init` once from the root of any monorepo to inject the standard `release:*` scripts into its `package.json`:
+
+```bash
+npx enablement-build-monorepo-version --init
+```
+
+Preview what would change without writing anything:
+
+```bash
+npx enablement-build-monorepo-version --init --try
+```
+
+The following scripts are injected (skipped if already present; `--children` stripped if already there):
+
+| Script | Command |
+|---|---|
+| `release:try` | dry-run of the full release flow |
+| `release:changed` | list changed packages |
+| `release:version` | bump and save versions |
+| `release:finalize` | write hashes |
+| `release:retag` | migrate tags to package-name format |
+
+---
+
+## Development
+
+```
+src/
+├── index.mjs        CLI entry point and main() orchestration
+├── lib.mjs          Core logic (exported for testing)
+├── version.mjs      Semver bump logic
+└── folder-hash.mjs  Recursive folder hashing
+
+tests/
+├── lib.test.mjs     Unit tests for lib.mjs
+├── dependencies.json  Sample NX dependency graph fixture
+├── package.json       Sample package.json fixture
+├── version.json       Sample version.json fixture
+└── pyproject.toml     Sample pyproject.toml fixture
+```
+
+Run the test suite:
+
+```bash
+pnpm test
+```
+
+Watch mode:
+
+```bash
+pnpm test:watch
+```

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "enablement-build-monorepo-version",
-  "version": "1.0.27",
+  "version": "2.0.2",
   "description": "This detects changes in the children packages of a monorepo.",
   "type": "module",
-  "module": "./index.mjs",
-  "bin": "./index.mjs",
+  "module": "./src/index.mjs",
+  "bin": "./src/index.mjs",
   "license": "MIT",
-  "author": "Chris Doty",
-  "scripts": {
-    "start": "node index.mjs"
+  "author": "Contributors",
+  "jest": {
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/*.test.mjs"
+    ]
   },
   "dependencies": {
     "minimatch": "~10.1.1"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  },
+  "scripts": {
+    "start": "node src/index.mjs",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
   }
 }

package/src/index.mjs

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+import path from 'path';
+import { readFileSync, writeFileSync, existsSync, lstatSync } from "fs";
+import { exec } from "child_process";
+
+import { hashElement } from "./folder-hash.mjs";
+import { dependencyMap, compare, getCurrentVersion, updateVersion, retagToPackageNames, detectOldFormatTags, resolveWorkspaceChildren, applyInitScripts, RELEASE_SCRIPTS, emitVariable } from "./lib.mjs";
+
+
+async function main(options) {
+  return new Promise((mainResolve, mainreject) => {
+    const hashOptions = { encoding: 'hex', folders: { exclude: options.hashExcludeFolders }, files: { exclude: options.hashExcludeFiles } };
+    const current = {};
+    const changeList = [];
+    const scanlist = [];
+    const changedFolders = [];
+
+    if (!options.children) {
+      const detected = resolveWorkspaceChildren(options.prefixPath);
+      if (detected) {
+        if (options.debug) console.log(`Auto-detected workspace children: ${detected}`);
+        options.children = detected;
+      } else {
+        options.children = 'packages';
+        console.log('\x1b[33m%s\x1b[0m', 'Warning: no workspace config found, defaulting --children to "packages"');
+      }
+    }
+
+    if (options.try) {
+      console.log('\x1b[36m%s\x1b[0m', '[try] Dry-run mode — no changes will be made\n');
+    }
+
+    const changeConfig = path.join(options.prefixPath, options.hashFile);
+    let previous = {};
+
+    // make sure hash config file exists
+    if (!existsSync(changeConfig)) {
+      if (options.try) {
+        console.log('\x1b[36m%s\x1b[0m', `[try] Hash file ${changeConfig} not found — treating previous state as empty`);
+      } else {
+        writeFileSync(changeConfig, "{}", "utf8");
+      }
+    }
+
+    let dependencies = {};
+    if (options.dependencies) {
+      if (existsSync(options.dependencies)) {
+        dependencies = dependencyMap(options.dependencies);
+        if (options.debug) console.log('Loaded dependencies\n', JSON.stringify(dependencies));
+      } else {
+        console.log('\x1b[33m%s\x1b[0m', `Could not load dependency file ${options.dependencies}`);
+      }
+    }
+
+    // load previous hashes
+    const data = existsSync(changeConfig) ? readFileSync(changeConfig, "utf8") : "{}";
+    previous = JSON.parse(data);
+    if (options.debug) console.log("PREVIOUS", JSON.stringify(previous));
+
+    options.hashFiles.forEach(file => {
+      scanlist.push(new Promise((resolve, reject) => {
+        const absPath = path.resolve(file);
+        const directoryPath = path.dirname(absPath);
+        const filename = path.basename(absPath);
+        const foldername = path.basename(directoryPath);
+        hashElement(filename, directoryPath, options).then(async hashedFile => {
+          if (options.debug) console.log("HASH", JSON.stringify(hashedFile));
+          if (options.hash) {
+            current[foldername + "." + hashedFile.name] = { hash: hashedFile.hash };
+          }
+          resolve("OK");
+        })
+        .catch(error => {
+          return console.error('hashing failed:', error);
+        });
+      }));
+    });
+
+    let children = options.children.replace(/\s/g, ",");
+    children.split(',').forEach((packageFolder) => {
+      scanlist.push(new Promise((resolve, reject) => {
+        hashElement(path.join(options.prefixPath, packageFolder), hashOptions).then(async hash => {
+          const children = hash.children;
+          if (options.debug) console.log("HASH", JSON.stringify(children));
+
+          for (let i = 0; i < children.length; i++) {
+            let name = children[i].name;
+            if (name.substring(0, 1) === "_" || name === "version") continue;
+            if (lstatSync(path.join(options.prefixPath, packageFolder, name)).isFile()) continue;
+            if (!existsSync(path.join(options.prefixPath, packageFolder, name))) continue;
+
+            delete children[i].children;
+            let v = getCurrentVersion(options.prefixPath, packageFolder, name);
+            current[name] = { hash: children[i].hash, ...v };
+          }
+
+          if (options.changed || options.version || options.tag) {
+            let results = await compare(packageFolder, previous, current, dependencies, options);
+            if (options.debug) console.log("COMPARE", JSON.stringify(results));
+
+            for (let i = 0; i < results.length; i++) {
+              if (results[i].value.changed) {
+                changeList.push(results[i].value.name);
+                if (changedFolders.indexOf(results[i].value.packageFolder) < 0) changedFolders.push(results[i].value.packageFolder);
+              }
+            }
+
+            for (let i = 0; i < results.length; i++) {
+              if (results[i].value.packageFolder !== packageFolder) continue;
+              if (options.version) {
+                if (options.debug) console.log(results[i]);
+                let safeName = results[i].value.name;
+                safeName = safeName.replace(/-/g, '').replace(/_/g, '').replace(/\./g, '');
+                if (results[i].value.changed) {
+                  emitVariable(safeName, results[i].value.version, options.platform);
+                  if (options.saveVersion) {
+                    scanlist.push(updateVersion(packageFolder, results[i].value.name, results[i].value.version, options));
+                  }
+                } else {
+                  emitVariable(safeName, results[i].value.previous, options.platform);
+                }
+              }
+              if (options.tag) {
+                scanlist.push(new Promise((resolve, reject) => {
+                  let v = results[i].value.version;
+                  if (!v) v = getCurrentVersion(options.prefixPath, packageFolder, results[i].value.name)?.version;
+                  const shortName = (results[i].value.fullName || results[i].value.name).replace(/^@[^/]+\//, '');
+                  let rev = shortName + '@' + v;
+                  let tagPath = shortName + '/' + v;
+                  if (options.try) {
+                    console.log('\x1b[36m%s\x1b[0m', `[try] Would create tag ${tagPath}`);
+                    resolve(rev);
+                    return;
+                  }
+                  exec(`git describe --tags "${tagPath}"`, (err) => {
+                    if (err) {
+                      exec(`git tag "${tagPath}" -m "${rev}"`, (err2) => {
+                        if (err2) { reject(err2); return; }
+                        resolve(rev);
+                      });
+                      return;
+                    }
+                  });
+                }));
+              }
+            }
+          }
+
+          // save current hashes
+          if (options.hash) {
+            let names = Object.keys(current);
+            for (let i = 0; i < names.length; i++) {
+              if (current[names[i]].packageFolder !== packageFolder) continue;
+              let v = getCurrentVersion(options.prefixPath, packageFolder, names[i]);
+              current[names[i]].version = v.version;
+              current[names[i]].fullName = v.fullName;
+            }
+          }
+          resolve("OK");
+        })
+        .catch(error => {
+          return console.error('hashing failed:', error);
+        });
+      }));
+    });
+
+    Promise.all(scanlist).then(() => {
+      if (options.changed) {
+        console.log(`CHANGED - ${JSON.stringify(changeList)}`);
+        emitVariable('changed', JSON.stringify(changeList), options.platform);
+
+        if (changedFolders.length > 0) {
+          if (options.debug) console.log(`FOLDERS CHANGED - ${JSON.stringify(changedFolders)}`);
+          changedFolders.map((packageFolder) => {
+            packageFolder = packageFolder.replace(/\//g, '_');
+            emitVariable(packageFolder, 'true', options.platform);
+          });
+        }
+      }
+
+      // write current hashes
+      if (options.hash) {
+        let result = Object.keys(current).sort().reduce(
+          (obj, key) => { obj[key] = current[key]; return obj; },
+          {}
+        );
+        if (options.try) {
+          console.log('\x1b[36m%s\x1b[0m', `[try] Would write updated hashes to ${changeConfig}`);
+        } else {
+          writeFileSync(changeConfig, JSON.stringify(result, null, 2), "utf8");
+          console.log('folder hashes written successfully');
+        }
+      }
+
+      const finish = () => {
+        if (options.retag) {
+          if (options.try) {
+            detectOldFormatTags(options).then((offending) => {
+              if (offending.length === 0) {
+                console.log('\x1b[36m%s\x1b[0m', '[try] No tags found in old format — nothing to retag');
+              } else {
+                console.log('\x1b[36m%s\x1b[0m', `[try] Would retag ${offending.length} tag(s):`);
+                offending.forEach(({ old, suggested }) =>
+                  console.log('\x1b[36m%s\x1b[0m', `[try]   ${old}  →  ${suggested}`)
+                );
+              }
+              mainResolve("DONE");
+            }, mainreject);
+          } else {
+            retagToPackageNames(options).then(() => mainResolve("DONE"), mainreject);
+          }
+        } else {
+          mainResolve("DONE");
+        }
+      };
+
+      if (options.tag) {
+        detectOldFormatTags(options).then((offending) => {
+          if (offending.length > 0) {
+            console.log('\x1b[33m%s\x1b[0m', `\nWarning: ${offending.length} tag(s) use the old folder-name format and will not match new tags:`);
+            offending.forEach(({ old, suggested }) =>
+              console.log('\x1b[33m%s\x1b[0m', `  ${old}  →  ${suggested}`)
+            );
+            console.log('\x1b[33m%s\x1b[0m', 'Run with --retag to migrate these to the new package-name format.\n');
+          }
+          finish();
+        }, mainreject);
+      } else {
+        finish();
+      }
+    }, mainreject);
+  });
+}
+
+let options = {
+  saveVersion: false,
+  changed: false,
+  version: false,
+  hash: false,
+  tag: false,
+  retag: false,
+  init: false,
+  try: false,
+  commit: false,
+  children: null,
+  platform: null,
+  hashFiles: [],
+  prefixPath: './',
+  debug: false,
+  hashFile: null,
+  hashExcludeFolders: ['node_modules', 'coverage', 'dist', 'bin', 'obj', '__pycache__', '.vs', '.nx', '.vscode', '.idea', '.git', '.github', '.azuredevops', '.release'],
+  hashExcludeFiles: ['.npmrc', 'CHANGELOG.md', 'README.md'],
+  dependencies: "dependencies.json"
+};
+
+if (process.argv.length === 2) {
+  console.error('Expected at least one argument!');
+  process.exit(1);
+} else {
+  let argv = process.argv;
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === "--save") options.saveVersion = true;
+    else if (argv[i] === "--debug") options.debug = true;
+    else if (argv[i] === "--changed") options.changed = true;
+    else if (argv[i] === "--version") options.version = true;
+    else if (argv[i] === "--hash") options.hash = true;
+    else if (argv[i] === "--tag") options.tag = true;
+    else if (argv[i] === "--retag") options.retag = true;
+    else if (argv[i] === "--init") options.init = true;
+    else if (argv[i] === "--try") options.try = true;
+    else if (argv[i] === "--hashExcludeFolders" || argv[i] === "--hashExcludeFiles") {
+      let name = argv[i].substring(2);
+      options[name] = argv[i + 1].split(',');
+      i++;
+    }
+    else if (argv[i] === "--hashFiles") {
+      let name = argv[i].substring(2);
+      options[name] = argv[i + 1].split(',');
+      i++;
+    } else if (argv[i].substring(0, 2) === "--") {
+      let name = argv[i].substring(2);
+      if (options[name] !== undefined) {
+        options[name] = argv[i + 1];
+        i++;
+      } else {
+        console.error(`Expected a known option, got ${argv[i]}`);
+        process.exit(1);
+      }
+    }
+  }
+}
+
+const hasGitHub = existsSync(path.join(options.prefixPath, '.github'));
+if (!options.hashFile) {
+  options.hashFile = hasGitHub ? '.github/hash.json' : '.cicd/hash.json';
+}
+if (!options.platform) {
+  options.platform = hasGitHub ? 'github' : 'ado';
+}
+
+async function initPackage(options) {
+  const pkgFile = path.join(options.prefixPath, 'package.json');
+  if (!existsSync(pkgFile)) {
+    console.error(`No package.json found at ${pkgFile}`);
+    process.exit(1);
+  }
+  const pkg = JSON.parse(readFileSync(pkgFile, 'utf8'));
+  const result = applyInitScripts(pkg);
+
+  if (result.added.length === 0 && result.updated.length === 0) {
+    console.log('[init] No changes needed — all release:* scripts are already present');
+    return;
+  }
+
+  if (options.try) {
+    result.added.forEach(name =>
+      console.log('\x1b[36m%s\x1b[0m', `[try] Would add ${name}: ${RELEASE_SCRIPTS[name]}`));
+    result.updated.forEach(name =>
+      console.log('\x1b[36m%s\x1b[0m', `[try] Would update ${name}: remove --children flag`));
+    return;
+  }
+
+  writeFileSync(pkgFile, JSON.stringify(result.pkg, null, 2) + '\n', 'utf8');
+  result.added.forEach(name => console.log(`[init] Added ${name}`));
+  result.updated.forEach(name => console.log(`[init] Updated ${name}: removed --children flag`));
+}
+
+(async () => {
+  try {
+    if (options.init) {
+      await initPackage(options);
+      return;
+    }
+    const text = await main(options);
+    console.log(text);
+  } catch (e) {
+    console.log(e);
+    process.exit(1);
+  }
+})();