@modulify/conventional-release 0.1.0

package/README.md

@@ -0,0 +1,380 @@
+# @modulify/conventional-release
+
+Release orchestration package for conventional workflows.
+
+This workspace combines:
+- semantic version recommendation from `@modulify/conventional-bump`,
+- changelog rendering and writing from `@modulify/conventional-changelog`,
+- package manifest updates,
+- release finalization with commit and tag creation.
+
+The package is library-first. It exposes:
+- `createScope()` to inspect what would be released,
+- `run()` to apply the release flow,
+- `conventional-release` as a config-driven CLI binary.
+
+## Installation
+
+```bash
+yarn add -D @modulify/conventional-release
+```
+
+Other package managers:
+
+```bash
+npm install -D @modulify/conventional-release
+pnpm add -D @modulify/conventional-release
+bun add -d @modulify/conventional-release
+```
+
+## Mental model
+
+The package works in two stages:
+
+1. `createScope(options)` discovers the release scope for the repository.
+It resolves packages, filters workspaces, detects affected packages, and produces ordered release slices.
+2. `run(options)` resolves the same scope and applies side effects.
+It updates manifests, writes the changelog, creates a commit, and creates tags.
+
+`Scope` is the declarative view of a release.
+`Slice` is one execution unit inside that scope.
+
+In `sync` mode there is usually one slice for the whole repository.
+In `async` mode each affected package gets its own slice.
+In `hybrid` mode packages can be split into named `partitions`.
+
+## Quick start
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+const result = await run()
+
+if (!result.changed) {
+  console.log('No changes since last release')
+} else {
+  for (const slice of result.slices) {
+    if (!slice.changed) continue
+
+    console.log(slice.id, slice.nextVersion, slice.tag)
+  }
+}
+```
+
+## CLI
+
+The package ships a `conventional-release` binary.
+
+Typical usage:
+
+```bash
+conventional-release
+conventional-release --dry
+conventional-release --dry --verbose --tags
+```
+
+From a project script:
+
+```json
+{
+  "scripts": {
+    "release": "conventional-release",
+    "release:dry": "conventional-release --dry"
+  }
+}
+```
+
+Without adding a local script:
+
+```bash
+npx @modulify/conventional-release --dry
+npm exec conventional-release -- --dry
+yarn dlx @modulify/conventional-release --dry
+pnpm dlx @modulify/conventional-release --dry
+bunx @modulify/conventional-release --dry
+```
+
+Useful flags:
+
+- `--dry`: compute versions, files, and tags without write-side effects
+- `--verbose`: show detailed per-slice progress output
+- `--tags`: print generated tags in the final summary
+- `--release-as <type>`: force `major`, `minor`, or `patch`
+- `--prerelease <channel>`: use `alpha`, `beta`, or `rc`
+
+The CLI reads the same repository configuration as the library API and wires a lifecycle reporter into `run()`.
+
+## Inspect before running
+
+Use `createScope()` when you want a dry, deterministic view of the release shape:
+
+```ts
+import { createScope } from '@modulify/conventional-release'
+
+const scope = await createScope({
+  mode: 'hybrid',
+})
+
+console.log(scope.mode)
+console.log(scope.packages.map((pkg) => pkg.path))
+console.log(scope.slices.map((slice) => slice.id))
+```
+
+This is useful for:
+- the built-in package CLI,
+- custom CLIs,
+- dashboards,
+- approval flows,
+- tests around release planning.
+
+## Running a release
+
+`run()` applies the release flow and returns per-slice results:
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+const result = await run({
+  mode: 'sync',
+  dry: true,
+})
+
+console.log(result.changed)
+console.log(result.files)
+console.log(result.slices)
+```
+
+When `dry: true` is used, the package still resolves versions, tags, and touched files, but skips write-side effects.
+
+## Configuration sources
+
+Configuration is resolved in this order:
+
+1. `package.json` field `release`
+2. `release.config.ts`, `release.config.mjs`, or `release.config.js`
+3. inline options passed to `run()` or `createScope()`
+
+Inline options always win.
+
+Example `package.json`:
+
+```json
+{
+  "name": "example-repo",
+  "version": "1.0.0",
+  "release": {
+    "mode": "sync",
+    "tagPrefix": "v"
+  }
+}
+```
+
+Example `release.config.ts`:
+
+```ts
+import type { Options } from '@modulify/conventional-release'
+
+const config: Options = {
+  mode: 'hybrid',
+  partitions: {
+    core: {
+      mode: 'sync',
+      workspaces: ['@scope/core-*'],
+    },
+    plugins: {
+      mode: 'async',
+      workspaces: ['packages/plugins/*'],
+      tagPrefix: 'plugin-',
+    },
+  },
+}
+
+export default config
+```
+
+## Common options
+
+The most important public options are:
+
+- `mode`: release strategy, one of `sync`, `async`, or `hybrid`
+- `releaseAs`: explicit semver bump override such as `major`, `minor`, or `patch`
+- `prerelease`: prerelease channel, one of `alpha`, `beta`, or `rc`
+- `fromTag`: explicit lower bound tag for advisory commit analysis
+- `tagPrefix`: tag matcher used during advisory commit analysis
+- `workspaces`: include and exclude filters for workspace discovery
+- `partitions`: named hybrid slices for mixed release strategies
+- `dependencyPolicy`: how internal dependency ranges are updated, one of `preserve`, `caret`, or `exact`
+- `install`: whether install should run after manifest updates
+- `tagName`, `tagMessage`, `commitMessage`: custom formatters for release output
+- `changelogFile`: changelog output path relative to the repository root
+
+Important:
+- `tagPrefix` affects release discovery and commit analysis boundaries.
+- `tagPrefix` does not format the new tag name by itself.
+- To change produced tag names, use `tagName`.
+
+## Single-package repository
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+await run({
+  mode: 'sync',
+  fromTag: 'v1.0.0',
+})
+```
+
+This is the simplest setup and usually produces one slice:
+- one next version,
+- one commit,
+- one tag.
+
+By default, a changed `sync` slice produces a tag like `v1.2.3`.
+
+## Monorepo with independent packages
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+await run({
+  mode: 'async',
+  workspaces: {
+    include: ['packages/*'],
+  },
+})
+```
+
+This creates one slice per affected package.
+
+By default, each changed async slice produces a tag like `package-name@1.2.3`.
+
+## Monorepo with grouped release behavior
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+await run({
+  mode: 'hybrid',
+  partitions: {
+    app: {
+      mode: 'sync',
+      workspaces: ['@scope/app', '@scope/web'],
+    },
+    plugins: {
+      mode: 'async',
+      workspaces: ['packages/plugins/*'],
+    },
+  },
+})
+```
+
+This is useful when some packages must move in lockstep, while others can release independently.
+
+By default, partition slices use tags like `partition-name@1.2.3`.
+
+## Result shape
+
+`run()` returns:
+
+- `changed`: whether at least one slice changed version
+- `files`: all files touched by changed slices
+- `packages`: all packages in resolved scope
+- `affected`: packages affected by the current working tree
+- `slices`: ordered slice results with:
+  - `id`
+  - `kind`
+  - `mode`
+  - `packages`
+  - `currentVersion`
+  - `nextVersion`
+  - `releaseType`
+  - `tag`
+  - `commitMessage`
+  - `tagMessage`
+
+Example:
+
+```ts
+const result = await run({ dry: true })
+
+for (const slice of result.slices) {
+  console.log({
+    id: slice.id,
+    changed: slice.changed,
+    nextVersion: slice.nextVersion,
+    tag: slice.tag,
+  })
+}
+```
+
+## Install behavior
+
+After manifest updates the package can run the repository package manager install command.
+
+`install` supports three forms:
+
+- `false`: skip install entirely
+- `true` or omitted: run install with default extra arguments for the detected package manager
+- `string[]`: run install and append these extra arguments after the `install` subcommand
+
+Example:
+
+```ts
+await run({
+  install: ['--mode=skip-build'],
+})
+```
+
+That becomes conceptually:
+
+```bash
+<package-manager> install --mode=skip-build
+```
+
+## Package manager detection
+
+The package detects the package manager in this order:
+
+1. `package.json#packageManager`
+2. lockfiles in the repository root
+3. fallback to `npm`
+
+Recognized lockfiles:
+
+- `yarn.lock`
+- `pnpm-lock.yaml`
+- `package-lock.json`
+- `bun.lock`
+- `bun.lockb`
+
+Default install extras:
+
+- `yarn`: `--no-immutable`
+- `npm`: no extra args
+- `pnpm`: no extra args
+- `bun`: no extra args
+
+## Tag and message customization
+
+Custom formatters receive a `TagContext` object:
+
+```ts
+import { run } from '@modulify/conventional-release'
+
+await run({
+  tagName: ({ version, partition, packages }) => {
+    const name = partition ?? packages[0]?.name ?? 'release'
+
+    return `${name}@${version}`
+  },
+  commitMessage: ({ tag }) => `chore(release): ${tag}`,
+  tagMessage: ({ tag }) => `chore(release): ${tag}`,
+})
+```
+
+## Notes
+
+- The package detects the package manager from `package.json#packageManager` or lockfiles.
+- The default fallback package manager is `npm`.
+- The package does not perform `git push`.
+- CLI-style push hints belong in the CLI layer, not in the library result.

package/bin/cli.cjs

@@ -0,0 +1,308 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const gitToolkit = require("@modulify/git-toolkit");
+const shell = require("@modulify/git-toolkit/shell");
+const index = require("../dist/index.cjs");
+const yargs = require("yargs");
+const helpers = require("yargs/helpers");
+const chalk = require("chalk");
+const figures = require("figures");
+const util = require("node:util");
+function _interopNamespaceDefault(e) {
+  const n = Object.create(null, { [Symbol.toStringTag]: { value: "Module" } });
+  if (e) {
+    for (const k in e) {
+      if (k !== "default") {
+        const d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: () => e[k]
+        });
+      }
+    }
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+const util__namespace = /* @__PURE__ */ _interopNamespaceDefault(util);
+const DEFAULTS = {
+  dry: false,
+  verbose: false,
+  tags: false
+};
+class CliParseError extends Error {
+  help;
+}
+async function parseArgv(argv = process.argv) {
+  const parser = yargs(helpers.hideBin(argv)).locale("en").scriptName("conventional-release").usage("Usage: $0 [options]").option("release-as", {
+    alias: "r",
+    describe: "Specify the release type (major|minor|patch)",
+    requiresArg: true,
+    string: true
+  }).option("prerelease", {
+    alias: "p",
+    describe: "Specify the prerelease type (alpha|beta|rc)",
+    requiresArg: true,
+    string: true
+  }).option("dry", {
+    type: "boolean",
+    default: DEFAULTS.dry,
+    describe: "See the commands that running release would run"
+  }).option("verbose", {
+    type: "boolean",
+    default: DEFAULTS.verbose,
+    describe: "Show detailed per-slice progress output"
+  }).option("tags", {
+    type: "boolean",
+    default: DEFAULTS.tags,
+    describe: "Show generated tags in the final output"
+  }).exitProcess(false).check((options) => {
+    if (!["alpha", "beta", "rc", void 0].includes(options.prerelease)) {
+      throw new Error("prerelease should be one of alpha, beta, rc or undefined");
+    }
+    return true;
+  }).showHelpOnFail(false).fail((message) => {
+    throw new Error(message);
+  }).alias("version", "v").alias("help", "h").example("$0", "Update changelog and tag release").example("$0 --dry --verbose", "Show a detailed dry-run release preview").pkgConf("release").wrap(97);
+  let parsed;
+  try {
+    parsed = await parser.parseAsync();
+  } catch (error) {
+    const failure = new CliParseError(error.message);
+    const help = await parser.getHelp();
+    failure.help = [help].flat().join("\n");
+    throw failure;
+  }
+  return {
+    releaseAs: parsed.releaseAs,
+    prerelease: parsed.prerelease,
+    dry: parsed.dry,
+    verbose: parsed.verbose,
+    tags: parsed.tags
+  };
+}
+function createReporter({
+  output,
+  git,
+  showTags = false,
+  verbosity = "summary"
+}) {
+  if (verbosity === "detailed") {
+    return new DetailedReporter({
+      output,
+      git,
+      showTags
+    });
+  }
+  return new SummaryReporter({
+    output,
+    git,
+    showTags
+  });
+}
+class SummaryReporter {
+  output;
+  git;
+  showTags;
+  scope = null;
+  position = /* @__PURE__ */ new Map();
+  constructor({
+    output,
+    git,
+    showTags
+  }) {
+    this.output = output;
+    this.git = git;
+    this.showTags = showTags;
+  }
+  async onStart(context) {
+    this.output.info(
+      context.dry ? "Starting dry release" : "Starting release"
+    );
+  }
+  async onScope(scope, context) {
+    this.scope = scope;
+    this.position = new Map(
+      scope.slices.map((slice, index2) => [slice.id, index2 + 1])
+    );
+  }
+  async onSliceStart(slice) {
+    this.output.info("Running slice %s", [this.describeProgress(slice)]);
+  }
+  async onSuccess(result) {
+    if (!result.changed) {
+      this.output.success("No changes since last release");
+      return;
+    }
+    const changed = result.slices.filter((slice) => slice.changed);
+    const primary = changed[0];
+    const packages = collectPackages(changed);
+    this.output.success("Release slices: %s", [String(changed.length)]);
+    this.output.success("Updated packages: %s", [String(packages.length)]);
+    if (primary) {
+      this.output.success("Next version: %s", [primary.nextVersion]);
+    }
+    if (result.dry) {
+      this.output.info("No committing or tagging since this was a dry run");
+      return;
+    }
+    this.output.success("Committed %s staged files", [String(result.files.length)]);
+    if (this.showTags) {
+      const tags = collectTags(changed);
+      if (tags.length) {
+        this.output.success("Tags: %s", [tags.join(", ")]);
+      }
+    }
+    this.output.info("Run `%s` to publish", [
+      `git push --follow-tags origin ${await this.resolveBranch()}`
+    ]);
+  }
+  async onError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    this.output.error(message);
+  }
+  describeProgress(slice) {
+    const position = this.position.get(slice.id);
+    const total = this.scope?.slices.length;
+    const label = describeSlice(slice);
+    return position && total ? `${position}/${total}: ${label}` : label;
+  }
+  async resolveBranch() {
+    try {
+      return await this.git.revParse("HEAD", { abbrevRef: true });
+    } catch {
+      return "%branch%";
+    }
+  }
+}
+class DetailedReporter extends SummaryReporter {
+  async onScope(scope, context) {
+    await super.onScope(scope, context);
+    this.output.info("%s scope: %s packages, %s affected, %s slices", [
+      scope.mode,
+      String(scope.packages.length),
+      String(scope.affected.length),
+      String(scope.slices.length)
+    ]);
+  }
+  async onSliceSuccess(slice) {
+    if (!slice.changed) {
+      this.output.warn("Completed slice %s without version changes (%s)", [
+        describeSlice(slice),
+        slice.currentVersion
+      ]);
+      return;
+    }
+    this.output.success("Completed slice %s: %s -> %s (%s)", [
+      describeSlice(slice),
+      slice.currentVersion,
+      slice.nextVersion,
+      slice.releaseType
+    ]);
+    if (this.showTags && slice.tag) {
+      this.output.info("Tag: %s", [slice.tag]);
+    }
+  }
+  async onSuccess(result) {
+    await super.onSuccess(result);
+    if (!result.changed) {
+      return;
+    }
+    const packages = collectPackages(result.slices.filter((slice) => slice.changed));
+    this.output.info("Updated packages: %s", [describePackages(packages)]);
+  }
+}
+function describeSlice(slice) {
+  if (slice.partition) {
+    return `${slice.partition} [${describePackages(slice.packages)}]`;
+  }
+  return describePackages(slice.packages);
+}
+function describePackages(packages) {
+  return packages.map((pkg) => pkg.name ?? pkg.path).join(", ");
+}
+function collectTags(slices) {
+  return slices.map((slice) => slice.tag).filter((tag) => !!tag);
+}
+function collectPackages(slices) {
+  const packages = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const slice of slices) {
+    for (const pkg of slice.packages) {
+      const identity = pkg.name ?? pkg.path;
+      if (seen.has(identity)) {
+        continue;
+      }
+      seen.add(identity);
+      packages.push(pkg);
+    }
+  }
+  return packages;
+}
+class ConsoleOutput {
+  write(message) {
+    console.info(message);
+  }
+  writeError(message) {
+    console.error(message);
+  }
+}
+class Output {
+  output;
+  theme;
+  constructor({
+    dry,
+    output = new ConsoleOutput(),
+    theme = createDefaultTheme(dry)
+  }) {
+    this.output = output;
+    this.theme = theme;
+  }
+  info(template, context = [], figure = this.theme.info) {
+    this.output.write(format(template, context, figure));
+  }
+  success(template, context = [], figure = this.theme.success) {
+    this.output.write(format(template, context, figure));
+  }
+  warn(template, context = [], figure = this.theme.warning) {
+    this.output.write(format(template, context, figure));
+  }
+  error(template, context = [], figure = this.theme.error) {
+    this.output.writeError(format(template, context, figure));
+  }
+}
+function createDefaultTheme(dry) {
+  return {
+    success: dry ? chalk.yellow(figures.tick) : chalk.green(figures.tick),
+    warning: chalk.yellow(figures.warning),
+    error: chalk.red(figures.cross),
+    info: chalk.blue(figures.info)
+  };
+}
+function format(template, context, figure) {
+  const bold = (arg) => chalk.bold(arg);
+  const message = util__namespace.format(template, ...context.map(bold));
+  return `${figure} ${message}`;
+}
+async function main(argv = process.argv) {
+  const cwd = process.cwd();
+  const options = await parseArgv(argv);
+  const output = new Output({
+    dry: options.dry,
+    output: new ConsoleOutput()
+  });
+  const git = new gitToolkit.GitCommander({ sh: new shell.Runner(cwd) });
+  await index.run({
+    cwd,
+    dry: options.dry,
+    releaseAs: options.releaseAs,
+    prerelease: options.prerelease,
+    reporter: createReporter({
+      output,
+      git,
+      showTags: options.tags,
+      verbosity: options.verbose ? "detailed" : "summary"
+    })
+  });
+}
+exports.main = main;