@afoures/auto-release 0.2.12 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # auto-release
 
-A release management tool inspired by Changesets and Release Please, designed for monorepos with app-centric versioning.
+A release management tool inspired by Changesets and Release Please, designed for monorepos with project-centric versioning.
 
 ## Why auto-release?
 
@@ -8,7 +8,7 @@ Release management should be simple. `auto-release` lets you focus on building f
 
 **Language agnostic**: Works with any project type. Built-in components for Node, Bun, Expo, and PHP projects, but you can add custom components for anything.
 
-**Built for monorepos**: Each app can have its own versioning strategy (semver, calver, marketing) and release independently.
+**Built for monorepos**: Each project can have its own versioning strategy (semver, calver, marketing) and release independently.
 
 **Developer-friendly**: Record changes with markdown files as you work. No complex conventions or strict commit messages required.
 
@@ -17,11 +17,13 @@ Release management should be simple. `auto-release` lets you focus on building f
 ## Quick Start
 
 ```bash
-npx --package=@afoures/auto-release@latest auto-release init
+npx @afoures/auto-release@latest init
 # or
-pnpx --package=@afoures/auto-release@latest auto-release init
+pnpx @afoures/auto-release@latest init
 # or
-bunx --package=@afoures/auto-release@latest auto-release init
+yarn dlx @afoures/auto-release@latest init
+# or
+bunx @afoures/auto-release@latest init
 ```
 
 This creates `auto-release.config.ts` and sets up the `.changes` directory.
@@ -29,9 +31,13 @@ This creates `auto-release.config.ts` and sets up the `.changes` directory.
 ### Manual Installation
 
 ```bash
-npm install auto-release
+npm install @afoures/auto-release
+# or
+pnpm add @afoures/auto-release
+# or
+yarn add @afoures/auto-release
 # or
-pnpm add auto-release
+bunx add @afoures/auto-release
 ```
 
 Create `auto-release.config.ts`:
@@ -43,6 +49,13 @@ import { github } from 'auto-release/providers'
 import { node } from 'auto-release/components'
 
 export default define_config({
+  projects: {
+    'my-app': {
+      components: [node('packages/my-app')],
+      versioning: semver(),
+      changelog: 'CHANGELOG.md',
+    },
+  },
   git: {
     platform: github({
       token: process.env.GITHUB_TOKEN!,
@@ -51,275 +64,23 @@ export default define_config({
     }),
     target_branch: 'main',
   },
-  apps: {
-    'my-app': {
-      components: [node('packages/my-app')],
-      versioning: semver(),
-      changelog: 'CHANGELOG.md',
-    },
-  },
 })
 ```
 
-## Workflow
-
-### 1. Development
-
-Make changes and record them:
-
-```bash
-auto-release record-change
-```
-
-Commit everything including the change file:
-
-```bash
-git add .
-git commit -m "feat: add new feature"
-git push
-```
-
-### 2. Generate Release PR
-
-On `main` branch, CI should automatically run:
-
-```bash
-auto-release generate-release-pr
-```
-
-This creates/updates a release branch with:
-- Updated versions in component files
-- Generated changelog entries
-- Change files removed
-
-### 3. Test on Release Branch
-
-CI on release branch runs:
-- Tests and quality checks
-- Build and deploy to test/staging environment
-
-### 4. Merge Release PR
-
-When ready, merge the release PR to `main`.
-
-### 5. Tag and Deploy
-
-CI on `main` runs:
-
-```bash
-auto-release tag-release-commit
-```
-
-This creates git tags for all releases, which can trigger deployment to pre-production and production.
-
-## Commands
-
-### `init`
-
-Set up auto-release in your repository:
-
-```bash
-auto-release init
-```
-
-Interactively configures apps, versioning strategies, and git platform.
-
-### `check`
-
-Validate configuration and change files:
-
-```bash
-auto-release check
-```
-
-Use in CI to ensure everything is valid before merging.
-
-### `record-change`
-
-Create a new change file:
-
-```bash
-# Interactive
-auto-release record-change
-
-# Non-interactive
-auto-release record-change --app my-app --type minor
-```
-
-### `list`
-
-List all apps managed by `auto-release` with their current versions:
-
-```bash
-auto-release list
-```
-
-### `generate-release-pr`
-
-Create or update release PRs:
-
-```bash
-# Preview changes
-auto-release generate-release-pr --dry-run
-
-# Create/update PRs
-auto-release generate-release-pr
-
-# Specific apps only
-auto-release generate-release-pr --app my-app --app another-app
-```
-
-### `tag-release-commit`
-
-Create git tags and releases for version changes:
-
-```bash
-# Preview what would be tagged
-auto-release tag-release-commit --dry-run
-
-# Create tags and releases
-auto-release tag-release-commit
-```
-
-Compares HEAD with HEAD^1 to detect version changes. Creates tags in format `app-name@version`.
-
-### `manual-release`
-
-Create a manual release using existing change files:
-
-```bash
-auto-release manual-release
-```
-
-Useful for local testing or emergency releases.
-
-## Configuration
-
-### Apps
-
-The `apps` object defines each releasable unit:
-
-```typescript
-apps: {
-  'my-app': {
-    // Components: where versions are read/written
-    components: [
-      node('packages/my-app'),
-      node('packages/shared'),
-    ],
-
-    // Versioning strategy
-    versioning: semver(),
-
-    // Changelog file path
-    changelog: 'apps/my-app/CHANGELOG.md',
-  },
-}
-```
-
-### Versioning Strategies
-
-```typescript
-import { semver, calver, markver } from 'auto-release/versioning'
-
-// Semantic versioning: 1.2.3
-versioning: semver()  // Change types: major, minor, patch
-
-// Calendar versioning: 2025.1.2
-versioning: calver()  // Change types: feature, fix
-
-// Marketing versioning: 1.0.0
-versioning: markver()  // Change types: marketing, feature, fix
-```
-
-### Git Platforms
-
-#### GitHub
-
-```typescript
-import { github } from 'auto-release/providers'
-
-git: {
-  platform: github({
-    token: process.env.GITHUB_TOKEN!,
-    owner: 'your-org',
-    repo: 'your-repo',
-  }),
-  target_branch: 'main',
-}
-```
-
-#### GitLab
+## Documentation
 
-```typescript
-import { gitlab } from 'auto-release/providers'
-
-git: {
-  platform: gitlab({
-    token: process.env.GITLAB_TOKEN!,
-    project_id: 'your-project-id',
-  }),
-  target_branch: 'main',
-}
-```
-
-### Components
-
-Components define version sources:
-
-- **`node(path)`**: any node project with package.json
-- **`bun(path)`**: any bun project with package.json
-- **`expo(path)`**: any Expo project with package.json and app.json
-- **`php(path)`**: any PHP project with composer.json
-
-```typescript
-import { node, expo, php } from 'auto-release/components'
-
-components: [
-  node('packages/web'),
-  bun('packages/bff'),
-  expo('apps/mobile'),
-  php('packages/api'),
-]
-```
-
-## Change Files
-
-Change files are stored in `.changes/<app-name>/` with format:
-
-```
-<type>.<slug>.md
-```
-
-Examples:
-- `.changes/my-app/major.add-authentication.md`
-- `.changes/my-app/patch.fix-login-bug.md`
-
-The change files folder can be customized.
-
-### Format
-
-**Simple** (title only):
-
-```markdown
-Fix authentication bug in login flow
-```
-
-**Detailed** (with description):
-
-```markdown
-This adds a comprehensive user profile page with:
-- Avatar upload
-- Bio and social links
-- Privacy settings
-```
+- [Configuration](./docs/configuration.md)
+- [Recommended usage](./docs/recommended-usage.md)
+- [Change File anatomy](./docs/change-file-anatomy.md)
+- [Commands](./docs/commands.md)
+- [Lexicon](./docs/lexicon.md)
 
 ## Philosophy
 
-Inspired by Changesets and Release Please, designed for app-centric monorepos where:
+Inspired by Changesets and Release Please, designed for project-centric monorepos where:
 
-- Multiple apps release independently with different versioning strategies
-- Change files are organized by app for clarity
+- Multiple projects release independently with different versioning strategies
+- Change files are organized by project for clarity
 - Release branches allow testing before production
 - Deployment is integrated with the release process
 
@@ -327,4 +88,4 @@ Inspired by Changesets and Release Please, designed for app-centric monorepos wh
 
 MIT
 
-See [LICENSE](./LICENSE)
+See [LICENSE](./LICENSE)

package/dist/lib/commands/check.mjs

@@ -6,10 +6,10 @@ import { find_change_files } from "../change-file.mjs";
 import { join } from "node:path";
 
 //#region src/lib/commands/check.ts
-async function verify_component_version_consistency(app) {
+async function verify_component_version_consistency(project) {
 	const versions = /* @__PURE__ */ new Set();
 	const errors = [];
-	for (const component of app.components) for (const part of component.parts) {
+	for (const component of project.components) for (const part of component.parts) {
 		const file_content = await read_file(part.file);
 		if (file_content === null) {
 			errors.push(`component ${component.root} has no version`);
@@ -19,14 +19,14 @@ async function verify_component_version_consistency(app) {
 		versions.add(version);
 	}
 	if (versions.size === 0) {
-		errors.push(`application ${app.name} has no versions`);
+		errors.push(`project ${project.name} has no versions`);
 		return {
 			ok: false,
 			errors
 		};
 	}
 	if (versions.size > 1) {
-		errors.push(`application ${app.name} has multiple versions: ${Array.from(versions).join(", ")}`);
+		errors.push(`project ${project.name} has multiple versions: ${Array.from(versions).join(", ")}`);
 		return {
 			ok: false,
 			errors
@@ -34,9 +34,9 @@ async function verify_component_version_consistency(app) {
 	}
 	return { ok: true };
 }
-async function validate_changes_files_content(changes_dir, app) {
+async function validate_changes_files_content(changes_dir, project) {
 	const errors = [];
-	const change_files = await find_change_files(join(changes_dir, app.name), { allowed_kinds: app.versioning.allowed_changes });
+	const change_files = await find_change_files(join(changes_dir, project.name), { allowed_kinds: project.versioning.allowed_changes });
 	if (change_files.warnings.length > 0) for (const warning of change_files.warnings) errors.push(warning);
 	for (const change_file of change_files.list) if (change_file.summary.length === 0) errors.push(`change file ${change_file.filename} has no summary`);
 	if (errors.length > 0) return {
@@ -45,9 +45,30 @@ async function validate_changes_files_content(changes_dir, app) {
 	};
 	return { ok: true };
 }
+function validate_groups(projects) {
+	const errors = [];
+	const warnings = [];
+	const group_names = new Set(projects.map((p) => p.release_group));
+	for (const group_name of group_names) {
+		const project_with_same_name = projects.find((p) => p.name === group_name);
+		if (project_with_same_name && project_with_same_name.release_group !== group_name) errors.push(`Group name "${group_name}" conflicts with project name. Groups and projects must have unique names.`);
+	}
+	const group_names_array = Array.from(group_names);
+	for (let i = 0; i < group_names_array.length; i++) for (let j = i + 1; j < group_names_array.length; j++) {
+		const group_a = group_names_array[i];
+		const group_b = group_names_array[j];
+		if (group_a.toLowerCase() === group_b.toLowerCase() && group_a !== group_b) warnings.push(`Groups "${group_a}" and "${group_b}" have similar names (case insensitive match). Consider using consistent casing.`);
+	}
+	const special_char_pattern = /[^a-zA-Z0-9_-]/;
+	for (const group_name of group_names) if (special_char_pattern.test(group_name)) warnings.push(`Group name "${group_name}" contains special characters. Consider using only alphanumeric, hyphens, and underscores for compatibility.`);
+	return {
+		errors,
+		warnings
+	};
+}
 const check = create_command({
 	name: "check",
-	description: "Validate configuration, packages, and change files",
+	description: "Validate configuration, versions, and change files",
 	schema: { config: {
 		type: "string",
 		description: "Path to config file"
@@ -62,18 +83,29 @@ const check = create_command({
 	run: async ({ context }) => {
 		const logger = create_logger();
 		const errors = [];
+		const warnings = [];
 		const config = context.config;
-		for (const app of config.managed_applications) {
-			const component_validation = await verify_component_version_consistency(app);
+		const group_validation = validate_groups(config.managed_projects);
+		errors.push(...group_validation.errors);
+		warnings.push(...group_validation.warnings);
+		for (const project of config.managed_projects) {
+			const component_validation = await verify_component_version_consistency(project);
 			if (!component_validation.ok) errors.push(...component_validation.errors);
-			const changes_validation = await validate_changes_files_content(config.changes_dir, app);
+			const changes_validation = await validate_changes_files_content(config.changes_dir, project);
 			if (!changes_validation.ok) errors.push(...changes_validation.errors);
 		}
 		const valid = errors.length === 0;
-		if (valid) logger.success("All validations passed!");
-		else {
+		if (valid && warnings.length === 0) logger.success("All validations passed!");
+		else if (valid) {
+			logger.warn("Validations passed with warnings:");
+			warnings.forEach((warning) => logger.warn(`  ${warning}`));
+		} else {
 			logger.error("Detected errors:");
 			errors.forEach((err) => logger.error(`  ${err}`));
+			if (warnings.length > 0) {
+				logger.warn("Warnings:");
+				warnings.forEach((warning) => logger.warn(`  ${warning}`));
+			}
 		}
 		if (valid) return {
 			status: "success",

package/dist/lib/commands/generate-release-pr.mjs

@@ -6,6 +6,7 @@ import { find_change_files } from "../change-file.mjs";
 import { diff, reset } from "../utils/git.mjs";
 import { compute_current_version } from "../utils/version.mjs";
 import { parse_markdown } from "../utils/mdast.mjs";
+import { group_projects } from "../utils/group.mjs";
 import { join } from "node:path";
 
 //#region src/lib/commands/generate-release-pr.ts
@@ -17,11 +18,6 @@ const generate_release_pr = create_command({
 			type: "string",
 			description: "Path to config file"
 		},
-		filter: {
-			type: "string",
-			description: "Only generate release PRs for the specified apps",
-			multiple: true
-		},
 		"dry-run": {
 			type: "boolean",
 			description: "Show what would be done without making changes"
@@ -37,79 +33,21 @@ const generate_release_pr = create_command({
 			root: git_root || config.folder
 		};
 	},
-	run: async ({ args: { filter, "dry-run": dry_run = false }, context: { config, root } }) => {
+	run: async ({ args: { "dry-run": dry_run = false }, context: { config, root } }) => {
 		const logger = create_logger();
-		const filtered_applications = filter ? config.managed_applications.filter((app) => filter.includes(app.name)) : config.managed_applications;
-		if (filtered_applications.length === 0) return {
+		const project_groups = group_projects(config.managed_projects);
+		if (project_groups.length === 0) return {
 			status: "success",
-			message: "No apps to release"
+			message: "No projects to release"
 		};
-		for (const app of filtered_applications) {
-			const changes_dir = join(config.changes_dir, app.name);
-			const changes = await find_change_files(changes_dir, { allowed_kinds: app.versioning.allowed_changes });
-			if (changes.warnings.length > 0) for (const warning of changes.warnings) logger.warn(warning);
-			const current_version = await compute_current_version(app, { get_file_content: (file_path) => read_file(file_path) }) ?? app.versioning.initial_version;
-			const next_version = app.versioning.bump({
-				version: current_version,
-				changes: changes.list,
-				date: /* @__PURE__ */ new Date()
-			});
-			const changes_by_kind = /* @__PURE__ */ new Map();
-			for (const change of changes.list) {
-				const existing = changes_by_kind.get(change.kind) ?? [];
-				existing.push(change);
-				changes_by_kind.set(change.kind, existing);
-			}
-			const message_lines = [];
-			const display_map = app.versioning.display_map;
-			for (const [kind, kind_changes] of changes_by_kind.entries()) {
-				const label = display_map[kind]?.plural ?? display_map[kind]?.singular ?? kind;
-				message_lines.push(`\n${label}:`);
-				for (const change of kind_changes) message_lines.push(`  ${change.summary}`);
-			}
-			logger.note(`Release ${app.name} ${next_version}`, message_lines.join("\n"));
-			if (dry_run) continue;
-			await delete_all_files_from_folder(changes_dir);
-			for (const component of app.components) for (const part of component.parts) {
-				const initial_content = await read_file(part.file);
-				if (initial_content === null) continue;
-				const updated_content = part.update_version(initial_content, next_version);
-				await write_file(part.file, updated_content);
-			}
-			const formatter = app.versioning.formatter;
-			const initial_changelog_content = await read_file(app.changelog);
-			const changelog_as_mdast = parse_markdown(initial_changelog_content ?? "");
-			const changelog = formatter.transform_markdown(changelog_as_mdast, initial_changelog_content ?? "");
-			const updated_changelog_content = formatter.format_changelog({
-				...changelog,
-				releases: [{
-					version: next_version,
-					changes: changes.list
-				}, ...changelog.releases.filter((release) => release.version !== next_version)].sort((a, b) => app.versioning.compare(b.version, a.version))
-			}, { app: { name: app.name } });
-			await write_file(app.changelog, updated_changelog_content);
-			const file_operations = await diff(root);
-			await reset(root);
-			const platform = config.git.platform;
-			const release_branch_name = `${config.git.default_release_branch_prefix}/${app.name}`;
-			await platform.create_or_update_branch({
-				branch_name: release_branch_name,
-				base_branch_name: config.git.target_branch,
-				file_operations,
-				commit_message: `chore: prepare release ${app.name}@${next_version}`
-			});
-			await platform.create_or_update_pull_request({
-				head_branch_name: release_branch_name,
-				base_branch_name: config.git.target_branch,
-				title: `release: ${app.name}@${next_version}`,
-				body: formatter.generate_pr_body({
-					app: { name: app.name },
-					current_version,
-					next_version,
-					changes: changes.list
-				}),
-				draft: true
-			});
+		for (const group of project_groups) if (await release_group(group, {
+			config,
+			root,
+			dry_run,
+			logger
+		}) === "skipped") {
+			logger.info(`Skipping group "${group.name}" - no projects with changes`);
+			continue;
 		}
 		if (dry_run) return {
 			status: "success",
@@ -121,6 +59,108 @@ const generate_release_pr = create_command({
 		};
 	}
 });
+async function release_group(group, { config, root, dry_run, logger }) {
+	const project_releases = [];
+	for (const project of group.projects) {
+		const changes_dir = join(config.changes_dir, project.name);
+		const changes_result = await find_change_files(changes_dir, { allowed_kinds: project.versioning.allowed_changes });
+		if (changes_result.warnings.length > 0) for (const warning of changes_result.warnings) logger.warn(warning);
+		if (project.options.skip_release_if_no_change_file && changes_result.list.length === 0) continue;
+		const current_version = await compute_current_version(project, { get_file_content: (file_path) => read_file(file_path) }) ?? project.versioning.initial_version;
+		const next_version = project.versioning.bump({
+			version: current_version,
+			changes: changes_result.list,
+			date: /* @__PURE__ */ new Date()
+		});
+		const changes_by_kind = /* @__PURE__ */ new Map();
+		for (const change of changes_result.list) {
+			const existing = changes_by_kind.get(change.kind) ?? [];
+			existing.push(change);
+			changes_by_kind.set(change.kind, existing);
+		}
+		const message_lines = [];
+		const display_map = project.versioning.display_map;
+		for (const [kind, kind_changes] of changes_by_kind.entries()) {
+			const label = display_map[kind]?.plural ?? display_map[kind]?.singular ?? kind;
+			message_lines.push(`\n${label}:`);
+			for (const change of kind_changes) message_lines.push(`  ${change.summary}`);
+		}
+		logger.note(`Release ${project.name} ${next_version}`, message_lines.join("\n"));
+		if (dry_run) continue;
+		const file_operations = await collect_project_file_operations(project, {
+			changes_dir,
+			changes: changes_result.list,
+			current_version,
+			next_version,
+			root
+		});
+		project_releases.push({
+			project,
+			current_version,
+			next_version,
+			changes: changes_result.list,
+			file_operations
+		});
+	}
+	if (project_releases.length === 0) return "skipped";
+	if (dry_run) return "processed";
+	const all_file_operations = project_releases.flatMap((release) => release.file_operations);
+	const platform = config.git.platform;
+	const release_branch_name = `${config.git.default_release_branch_prefix}/${group.name}`;
+	await platform.create_or_update_branch({
+		branch_name: release_branch_name,
+		base_branch_name: config.git.target_branch,
+		file_operations: all_file_operations,
+		commit_message: `chore: prepare releases for ${group.name}`
+	});
+	const pr_body = generate_pr_body(project_releases);
+	const pr_title = generate_pr_title(project_releases);
+	await platform.create_or_update_pull_request({
+		head_branch_name: release_branch_name,
+		base_branch_name: config.git.target_branch,
+		title: pr_title,
+		body: pr_body,
+		draft: true
+	});
+	return "processed";
+}
+async function collect_project_file_operations(project, { changes_dir, changes, current_version: _current_version, next_version, root }) {
+	await delete_all_files_from_folder(changes_dir);
+	for (const component of project.components) for (const part of component.parts) {
+		const initial_content = await read_file(part.file);
+		if (initial_content === null) continue;
+		const updated_content = part.update_version(initial_content, next_version);
+		await write_file(part.file, updated_content);
+	}
+	const formatter = project.versioning.formatter;
+	const initial_changelog_content = await read_file(project.changelog);
+	const changelog_as_mdast = parse_markdown(initial_changelog_content ?? "");
+	const changelog = formatter.transform_markdown(changelog_as_mdast, initial_changelog_content ?? "");
+	const updated_changelog_content = formatter.format_changelog({
+		...changelog,
+		releases: [{
+			version: next_version,
+			changes
+		}, ...changelog.releases.filter((release) => release.version !== next_version)].sort((a, b) => project.versioning.compare(b.version, a.version))
+	}, { project: { name: project.name } });
+	await write_file(project.changelog, updated_changelog_content);
+	const file_operations = await diff(root);
+	await reset(root);
+	return file_operations;
+}
+function generate_pr_body(project_releases) {
+	return ["This PR is managed by [auto-release](https://github.com/afoures/auto-release). Do not edit it manually.", ...project_releases.map((release) => {
+		return release.project.versioning.formatter.generate_pr_body({
+			project: { name: release.project.name },
+			current_version: release.current_version,
+			next_version: release.next_version,
+			changes: release.changes
+		});
+	})].join("\n\n");
+}
+function generate_pr_title(project_releases) {
+	return `release: ${project_releases.map((release) => `${release.project.name}@${release.next_version}`).join(", ")}`;
+}
 
 //#endregion
 export { generate_release_pr };