@theholocron/semantic-release-config 8.9.0-alpha.1 → 8.9.0-alpha.16

package/README.md

@@ -51,6 +51,20 @@ export default defineConfig();
 | `exec`     | `{ prepareCmd?, publishCmd? }` | `undefined`                                                   | Commands for `@semantic-release/exec`. Omit if not needed.                                                                        |
 | `assets`   | `string[]`                     | `['CHANGELOG.md', 'package.json', 'packages/*/package.json']` | Files committed by `@semantic-release/git` after release.                                                                         |
 
+## Releasing a version group
+
+A monorepo that releases several folders on their own lines uses `groupReleaseConfig()`. It builds on `defineConfig()` (same rules, notes and plugin order) and takes the same options plus a `group`: tags are `<group>-v<version>`, the analyzer and notes generator see only commits that touched the group's `paths` (default `[group]`), and the changelog, release commit assets and message are the group's.
+
+```js
+import { groupReleaseConfig, ungroupedReleaseConfig } from "@theholocron/semantic-release-config";
+
+export default process.env.RELEASE_GROUP
+  ? groupReleaseConfig({ group: process.env.RELEASE_GROUP, branches: ["main"] })
+  : ungroupedReleaseConfig({ groups: ["clients"], branches: ["main"] });
+```
+
+`ungroupedReleaseConfig()` is the mirror for everything in no group: it skips commits confined to the `groups` folders. `folderScoped`, `ungroupedScoped`, `commitFiles` and `inScope` are exported too.
+
 ## Plugin pipeline
 
 The config wires up this fixed plugin order:
@@ -60,7 +74,7 @@ The config wires up this fixed plugin order:
 3. `@semantic-release/changelog` — writes `CHANGELOG.md`
 4. `@semantic-release/exec` — repo-specific version bump and publish commands _(only when `exec` is passed)_
 5. `@semantic-release/git` — commits updated files back to the repo
-6. `@semantic-release/github` — creates a GitHub release
+6. `@semantic-release/github` — creates a GitHub release, and labels the issues and pull requests it ships `released` on every branch (the plugin's default is `released on @<channel>` on a prerelease branch)
 
 ## Named exports
 

package/dist/index.d.ts

@@ -1,3 +1,12 @@
+/** Runs `git` with `args` in `cwd`, feeding it `input` on stdin, and returns stdout. */
+export type GitRun = (args: string[], input: string, cwd: string) => string;
+/**
+ * The repo-relative files each of `hashes` changed, from one
+ * `git diff-tree --stdin` call. A commit that changes nothing (or a merge
+ * commit) maps to `[]`. Paths come back verbatim, not quoted, whatever they
+ * contain.
+ */
+export declare function commitFiles(cwd: string, hashes: readonly string[], run?: GitRun): Map<string, string[]>;
 interface ExecOptions {
   prepareCmd?: string;
   publishCmd?: string;
@@ -13,6 +22,7 @@ interface Options {
   npm?: boolean | NpmOptions;
   assets?: string[];
 }
+/** The `@semantic-release/commit-analyzer` plugin with the Conventional Commits preset: `feat` releases a minor, `fix`, `perf`, `refactor` and `chore(deps)` a patch, and a breaking change a major. */
 export declare const commitAnalyzer: (string | {
   preset: string;
   releaseRules: ({
@@ -32,6 +42,7 @@ export declare const commitAnalyzer: (string | {
     scope?: undefined;
   })[];
 })[];
+/** The `@semantic-release/release-notes-generator` plugin with the Conventional Commits preset, grouping commits into changelog sections by type. */
 export declare const releaseNotesGenerator: (string | {
   preset: string;
   presetConfig: {
@@ -50,4 +61,116 @@ export declare const releaseNotesGenerator: (string | {
  * @see https://semantic-release.gitbook.io/semantic-release/usage/configuration
  */
 export declare function defineConfig({ branches, exec, npm, assets }?: Options): object;
-export {};
+/** The slice of a semantic-release commit this module reads. */
+interface ReleaseCommit {
+  /** Full commit hash. */
+  hash: string;
+  [key: string]: unknown;
+}
+/** The slice of a semantic-release plugin context this module reads; everything else passes through untouched. */
+interface ReleaseContext {
+  /** The directory semantic-release runs in: the repo being released. */
+  cwd?: string;
+  /** The commits analysed for this release. */
+  commits?: ReleaseCommit[];
+  [key: string]: unknown;
+}
+/** A semantic-release plugin step that looks at commits. */
+type CommitStep = "analyzeCommits" | "generateNotes" | "success";
+type StepFn = (pluginConfig: unknown, context: ReleaseContext) => unknown;
+/** A plugin module that implements `Step`. */
+type StepPlugin<Step extends CommitStep> = Partial<Record<Step, StepFn>>;
+/** What the folder-scoped release plugin depends on, each replaceable in a test. */
+interface FolderScopedDeps {
+  /**
+   * Loads a plugin module by specifier, resolved from `cwd` (the repo being released). Defaults to a
+   * dynamic `import()` of the module as `cwd` resolves it, which is how semantic-release loads its own plugins.
+   */
+  load?: (specifier: string, cwd: string) => Promise<unknown>;
+  /** Lists the files each commit changed. Defaults to `git diff-tree`. */
+  listFiles?: typeof commitFiles;
+}
+/**
+ * An inline semantic-release plugin that runs `step` of the stock plugin
+ * (`@semantic-release/commit-analyzer` for `analyzeCommits`,
+ * `@semantic-release/release-notes-generator` for `generateNotes`) over only
+ * the commits that changed a file at or under `paths`.
+ *
+ * After a monorepo import, `lastTag..HEAD` spans every folder's commits, so an
+ * unscoped analyzer would release a folder for a commit that never touched it.
+ * The wrapped plugin is loaded on first use, so it only needs to be installed
+ * where a release actually runs. Commits are listed with one `git diff-tree`
+ * call, in `context.cwd`.
+ */
+export declare function folderScoped<Step extends CommitStep>(step: Step, paths: readonly string[], deps?: FolderScopedDeps): StepPlugin<Step>;
+/**
+ * The mirror of {@link folderScoped}, for the release of everything that is in **no**
+ * version group: it sees only commits that changed a file outside every group folder. A commit
+ * confined to a group (and the group's imported history) belongs to that group's release; letting the
+ * repo-wide one analyze it would release the repo for a change that is not in it, and write the
+ * group's commits into the repo's changelog.
+ */
+export declare function ungroupedScoped<Step extends CommitStep>(step: Step, groups: readonly string[], deps?: FolderScopedDeps): StepPlugin<Step>;
+/** The file `specifier` resolves to for the repo at `cwd`, else for `semantic-release`; `requireFrom` is a seam for tests. */
+export declare function resolvePlugin(specifier: string, cwd: string, requireFrom?: (file: string) => {
+  resolve(id: string): string;
+}): string;
+/**
+ * Splits the GitHub plugin's entry so its "released in…" comments and labels go only to the PRs and
+ * issues of the commits `scoped` keeps. The entry stays as it was, so it still publishes the GitHub
+ * release, but with the commenting turned off; `scoped` (a {@link folderScoped} or
+ * {@link ungroupedScoped} `success` step) then does the commenting with the entry's own config.
+ */
+export declare function commentOnlyFor(entry: string | [string, Record<string, unknown> | undefined], scoped: StepPlugin<"success">): ((string | [string, Record<string, unknown> | undefined]) | [object, unknown])[];
+/** What `defineConfig()` from `@theholocron/semantic-release-config` accepts. */
+type DefineConfigOptions = NonNullable<Parameters<typeof defineConfig>[0]>;
+interface GroupReleaseOptions extends DefineConfigOptions {
+  /**
+   * The version group: a folder of the repo (`clients`, `observability`, `cli`) that
+   * releases on its own. It prefixes the tags (`clients-v1.43.2`) and the release commit.
+   */
+  group: string;
+  /** Repo-relative folders whose commits release this group. Defaults to `[group]`. */
+  paths?: readonly string[];
+  /** The group's changelog. Defaults to `<group>/CHANGELOG.md`. */
+  changelogFile?: string;
+}
+/**
+ * A semantic-release config that releases one version group of a monorepo,
+ * built on the org's `defineConfig()` so its rules, notes layout and plugin
+ * order stay the same:
+ *
+ * - tags are `<group>-v<version>`, so each group finds its own last release;
+ * - the commit analyzer and notes generator see only commits that touched the
+ *   group's `paths` ({@link folderScoped});
+ * - the changelog, the release commit's assets and its message are the group's.
+ *
+ * Run one `semantic-release` per group. Cross-group dependencies resolve from
+ * the registry, so `paths` is the group's folder unless more is listed.
+ */
+export declare function groupReleaseConfig(options: GroupReleaseOptions): object;
+/**
+ * Whether any of `files` (repo-relative, `/`-separated) sits at or under one of
+ * `paths` (repo-relative folders). `clients` matches `clients/http/x.ts` but
+ * not `clients-old/x.ts`.
+ */
+export declare function inScope(files: readonly string[], paths: readonly string[]): boolean;
+/**
+ * Whether any of `files` sits **outside** every one of `folders`: the mirror of
+ * {@link inScope}. A commit that only touches the version groups' folders is out;
+ * one that touches anything else, even beside a group's files, is in.
+ */
+export declare function outsideFolders(files: readonly string[], folders: readonly string[]): boolean;
+interface UngroupedReleaseOptions extends DefineConfigOptions {
+  /** The version groups released on their own: folders of the repo whose commits this release ignores. */
+  groups: readonly string[];
+}
+/**
+ * The semantic-release config for everything that is in no version group, built on the org's
+ * `defineConfig()`: tags, changelog and release commit are the repo's own, as before. The commit
+ * analyzer and notes generator skip commits confined to the `groups` folders, because those
+ * belong to the groups' releases ({@link ungroupedScoped}). With no groups it is `defineConfig()`
+ * unchanged.
+ */
+export declare function ungroupedReleaseConfig({ groups, ...options }: UngroupedReleaseOptions): object;
+export type { CommitStep, DefineConfigOptions, FolderScopedDeps, GroupReleaseOptions, ReleaseCommit, ReleaseContext, StepPlugin, UngroupedReleaseOptions };

package/dist/index.js

@@ -1,4 +1,42 @@
-// index.ts
+import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+// commit-files/commit-files.ts
+const defaultGitRun = (args, input, cwd) => execFileSync("git", args, {
+	cwd,
+	input,
+	encoding: "utf8",
+	maxBuffer: 268435456
+});
+/**
+* The repo-relative files each of `hashes` changed, from one
+* `git diff-tree --stdin` call. A commit that changes nothing (or a merge
+* commit) maps to `[]`. Paths come back verbatim, not quoted, whatever they
+* contain.
+*/
+function commitFiles(cwd, hashes, run = defaultGitRun) {
+	const files = new Map(hashes.map((hash) => [hash, []]));
+	if (hashes.length === 0) return files;
+	const out = run([
+		"-c",
+		"core.quotePath=false",
+		"diff-tree",
+		"--stdin",
+		"--name-only",
+		"-r",
+		"--root"
+	], `${hashes.join("\n")}\n`, cwd);
+	let current;
+	for (const line of out.split("\n")) {
+		if (line === "") continue;
+		const known = files.get(line);
+		if (known) current = known;
+		else current?.push(line);
+	}
+	return files;
+}
+// define-config/define-config.ts
 const releaseRules = [
 	{
 		type: "feat",
@@ -64,10 +102,12 @@ const types = [
 		hidden: true
 	}
 ];
+/** The `@semantic-release/commit-analyzer` plugin with the Conventional Commits preset: `feat` releases a minor, `fix`, `perf`, `refactor` and `chore(deps)` a patch, and a breaking change a major. */
 const commitAnalyzer = ["@semantic-release/commit-analyzer", {
 	preset: "conventionalcommits",
 	releaseRules
 }];
+/** The `@semantic-release/release-notes-generator` plugin with the Conventional Commits preset, grouping commits into changelog sections by type. */
 const releaseNotesGenerator = ["@semantic-release/release-notes-generator", {
 	preset: "conventionalcommits",
 	presetConfig: { types }
@@ -97,8 +137,182 @@ function defineConfig({ branches = ["main"], exec, npm, assets } = {}) {
 				assets: resolvedAssets,
 				message: defaultMessage
 			}],
-			"@semantic-release/github"
+			["@semantic-release/github", { releasedLabels: ["released"] }]
+		]
+	};
+}
+// in-scope/in-scope.ts
+/**
+* Whether any of `files` (repo-relative, `/`-separated) sits at or under one of
+* `paths` (repo-relative folders). `clients` matches `clients/http/x.ts` but
+* not `clients-old/x.ts`.
+*/
+function inScope(files, paths) {
+	const folders = paths.map((path) => path.replace(/^\.\//, "").replace(/\/+$/, ""));
+	return files.some((file) => folders.some((folder) => file === folder || file.startsWith(`${folder}/`)));
+}
+/**
+* Whether any of `files` sits **outside** every one of `folders`: the mirror of
+* {@link inScope}. A commit that only touches the version groups' folders is out;
+* one that touches anything else, even beside a group's files, is in.
+*/
+function outsideFolders(files, folders) {
+	const normalized = folders.map((folder) => folder.replace(/^\.\//, "").replace(/\/+$/, ""));
+	return files.some((file) => !normalized.some((folder) => file === folder || file.startsWith(`${folder}/`)));
+}
+// folder-scoped/folder-scoped.ts
+/** The semantic-release plugin that implements each commit-reading step. `success` is the GitHub plugin's "released in…" comments. */
+const MODULES = {
+	analyzeCommits: "@semantic-release/commit-analyzer",
+	generateNotes: "@semantic-release/release-notes-generator",
+	success: "@semantic-release/github"
+};
+/**
+* An inline semantic-release plugin that runs `step` of the stock plugin
+* (`@semantic-release/commit-analyzer` for `analyzeCommits`,
+* `@semantic-release/release-notes-generator` for `generateNotes`) over only
+* the commits that changed a file at or under `paths`.
+*
+* After a monorepo import, `lastTag..HEAD` spans every folder's commits, so an
+* unscoped analyzer would release a folder for a commit that never touched it.
+* The wrapped plugin is loaded on first use, so it only needs to be installed
+* where a release actually runs. Commits are listed with one `git diff-tree`
+* call, in `context.cwd`.
+*/
+function folderScoped(step, paths, deps = {}) {
+	return scopedBy(step, (files) => inScope(files, paths), deps);
+}
+/**
+* The mirror of {@link folderScoped}, for the release of everything that is in **no**
+* version group: it sees only commits that changed a file outside every group folder. A commit
+* confined to a group (and the group's imported history) belongs to that group's release; letting the
+* repo-wide one analyze it would release the repo for a change that is not in it, and write the
+* group's commits into the repo's changelog.
+*/
+function ungroupedScoped(step, groups, deps = {}) {
+	return scopedBy(step, (files) => outsideFolders(files, groups), deps);
+}
+/**
+* `import()` of `specifier` the way semantic-release finds its own plugins: as the repo at `cwd` resolves it,
+* else as `semantic-release` does (the stock plugins are its dependencies, not the repo's). A bare `import()`
+* would resolve from this file, inside astromech, where neither is visible.
+*/
+function importFrom(specifier, cwd) {
+	return import(pathToFileURL(resolvePlugin(specifier, cwd)).href);
+}
+/** The file `specifier` resolves to for the repo at `cwd`, else for `semantic-release`; `requireFrom` is a seam for tests. */
+function resolvePlugin(specifier, cwd, requireFrom = createRequire) {
+	const fromRepo = requireFrom(join(cwd, "package.json"));
+	try {
+		return fromRepo.resolve(specifier);
+	} catch {
+		return requireFrom(fromRepo.resolve("semantic-release")).resolve(specifier);
+	}
+}
+function scopedBy(step, keep, { load = importFrom, listFiles = commitFiles }) {
+	const scoped = async (pluginConfig, context) => {
+		const { commits = [], cwd = process.cwd() } = context;
+		const inner = await load(MODULES[step], cwd);
+		const files = listFiles(cwd, commits.map((commit) => commit.hash));
+		const kept = commits.filter((commit) => keep(files.get(commit.hash) ?? []));
+		return inner[step]?.(pluginConfig, {
+			...context,
+			commits: kept
+		});
+	};
+	return { [step]: scoped };
+}
+/**
+* Splits the GitHub plugin's entry so its "released in…" comments and labels go only to the PRs and
+* issues of the commits `scoped` keeps. The entry stays as it was, so it still publishes the GitHub
+* release, but with the commenting turned off; `scoped` (a {@link folderScoped} or
+* {@link ungroupedScoped} `success` step) then does the commenting with the entry's own config.
+*/
+function commentOnlyFor(entry, scoped) {
+	const [name, config] = Array.isArray(entry) ? entry : [entry, void 0];
+	return [[name, {
+		...config,
+		successComment: false,
+		releasedLabels: false
+	}], [scoped, config]];
+}
+// group-release-config/group-release-config.ts
+const GROUP = /^[a-z][a-z0-9-]*$/;
+/**
+* A semantic-release config that releases one version group of a monorepo,
+* built on the org's `defineConfig()` so its rules, notes layout and plugin
+* order stay the same:
+*
+* - tags are `<group>-v<version>`, so each group finds its own last release;
+* - the commit analyzer and notes generator see only commits that touched the
+*   group's `paths` ({@link folderScoped});
+* - the changelog, the release commit's assets and its message are the group's.
+*
+* Run one `semantic-release` per group. Cross-group dependencies resolve from
+* the registry, so `paths` is the group's folder unless more is listed.
+*/
+function groupReleaseConfig(options) {
+	const { group, paths = [group], changelogFile = `${group}/CHANGELOG.md`, assets, ...rest } = options;
+	if (!GROUP.test(group)) throw new TypeError(`release group must be a lowercase folder name like "clients", got ${JSON.stringify(group)}`);
+	if (paths.length === 0) throw new TypeError(`release group ${JSON.stringify(group)} needs at least one path`);
+	const base = defineConfig({
+		...rest,
+		assets: assets ?? [
+			changelogFile,
+			`${group}/**/package.json`,
+			"!**/node_modules/**"
 		]
+	});
+	const scope = (entry) => {
+		const [name, config] = Array.isArray(entry) ? entry : [entry, void 0];
+		switch (name) {
+			case "@semantic-release/commit-analyzer": return [[folderScoped("analyzeCommits", paths), config]];
+			case "@semantic-release/release-notes-generator": return [[folderScoped("generateNotes", paths), config]];
+			case "@semantic-release/changelog": return [[name, {
+				...config,
+				changelogFile
+			}]];
+			case "@semantic-release/git": return [[name, {
+				...config,
+				message: groupMessage(config?.["message"], group)
+			}]];
+			case "@semantic-release/github": return commentOnlyFor(entry, folderScoped("success", paths));
+			default: return [entry];
+		}
+	};
+	return {
+		...base,
+		tagFormat: `${group}-v\${version}`,
+		plugins: base.plugins.flatMap(scope)
+	};
+}
+/** `chore(release): <version> …` becomes `chore(release): <group> <version> …`. */
+function groupMessage(message, group) {
+	return message.replace(/^chore\(release\): /, `chore(release): ${group} `);
+}
+// ungrouped-release-config/ungrouped-release-config.ts
+/**
+* The semantic-release config for everything that is in no version group, built on the org's
+* `defineConfig()`: tags, changelog and release commit are the repo's own, as before. The commit
+* analyzer and notes generator skip commits confined to the `groups` folders, because those
+* belong to the groups' releases ({@link ungroupedScoped}). With no groups it is `defineConfig()`
+* unchanged.
+*/
+function ungroupedReleaseConfig({ groups, ...options }) {
+	const base = defineConfig(options);
+	if (groups.length === 0) return base;
+	const scope = (entry) => {
+		const [name, config] = Array.isArray(entry) ? entry : [entry, void 0];
+		switch (name) {
+			case "@semantic-release/commit-analyzer": return [[ungroupedScoped("analyzeCommits", groups), config]];
+			case "@semantic-release/release-notes-generator": return [[ungroupedScoped("generateNotes", groups), config]];
+			case "@semantic-release/github": return commentOnlyFor(entry, ungroupedScoped("success", groups));
+			default: return [entry];
+		}
+	};
+	return {
+		...base,
+		plugins: base.plugins.flatMap(scope)
 	};
 }
-export { commitAnalyzer, defineConfig, releaseNotesGenerator };
+export { commentOnlyFor, commitAnalyzer, commitFiles, defineConfig, folderScoped, groupReleaseConfig, inScope, outsideFolders, releaseNotesGenerator, resolvePlugin, ungroupedReleaseConfig, ungroupedScoped };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/semantic-release-config",
-  "version": "8.9.0-alpha.1",
+  "version": "8.9.0-alpha.16",
   "description": "A semantic-release configuration for automated versioning and publishing.",
   "keywords": [
     "semantic-release",
@@ -33,12 +33,15 @@
     "dist/"
   ],
   "devDependencies": {
-    "@vitest/coverage-v8": "^5.0.5",
-    "tsdown": "^0.23.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@vitest/coverage-v8": "^5.1.0",
+    "conventional-changelog-conventionalcommits": "9.3.1",
+    "tsdown": "^0.23.5",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.5",
-    "@theholocron/tsconfig": "8.9.0-alpha.1",
-    "@theholocron/vitest-config": "8.9.0-alpha.1"
+    "vitest": "^5.1.0",
+    "@theholocron/tsconfig": "8.9.0-alpha.16",
+    "@theholocron/vitest-config": "8.9.0-alpha.16"
   },
   "peerDependencies": {
     "@semantic-release/changelog": "^6",
@@ -62,10 +65,10 @@
     "access": "public"
   },
   "scripts": {
-    "delivery.build": "tsdown",
-    "sourceQuality.staticAnalysis": "eslint .",
+    "build": "tsdown",
+    "lint:code": "eslint .",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest",
-    "verification.typeSafety": "tsc --noEmit",
-    "verification.unitTests": "vitest run"
+    "typecheck": "tsc --noEmit"
   }
 }