@afoures/auto-release 0.2.11 → 0.3.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/change-file.mjs

@@ -37,11 +37,12 @@ async function parse_change_file(path) {
 	const filename = basename(path);
 	const match = CHANGE_FILENAME_REGEX.exec(filename);
 	if (!match) return /* @__PURE__ */ new Error(`Invalid change filename format: ${path} (expected: <kind>.<slug>.md)`);
-	const file_content = await read_file(path);
+	let file_content = await read_file(path);
+	file_content = file_content?.trim() ?? null;
 	if (file_content === null) return /* @__PURE__ */ new Error(`Change file is missing: ${path}`);
-	if (!file_content.trim()) return /* @__PURE__ */ new Error("Change file is empty");
+	if (!file_content) return /* @__PURE__ */ new Error("Change file is empty");
 	const [title, ...rest] = file_content.split("\n");
-	const text = `- ${title}\n${rest.map((line) => `  ${line}`).join("\n")}`;
+	const text = [`- ${title}`, ...rest.map((line) => `  ${line}`)].join("\n");
 	return new ChangeFile({
 		slug: match.groups.slug,
 		kind: match.groups.kind,

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 {
@@ -47,7 +47,7 @@ async function validate_changes_files_content(changes_dir, app) {
 }
 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"
@@ -63,10 +63,10 @@ const check = create_command({
 		const logger = create_logger();
 		const errors = [];
 		const config = context.config;
-		for (const app of config.managed_applications) {
-			const component_validation = await verify_component_version_consistency(app);
+		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;

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

@@ -19,7 +19,7 @@ const generate_release_pr = create_command({
 		},
 		filter: {
 			type: "string",
-			description: "Only generate release PRs for the specified apps",
+			description: "Only generate release PRs for the specified projects",
 			multiple: true
 		},
 		"dry-run": {
@@ -39,17 +39,17 @@ const generate_release_pr = create_command({
 	},
 	run: async ({ args: { filter, "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 filtered_projects = filter ? config.managed_projects.filter((project) => filter.includes(project.name)) : config.managed_projects;
+		if (filtered_projects.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 });
+		for (const project of filtered_projects) {
+			const changes_dir = join(config.changes_dir, project.name);
+			const changes = await find_change_files(changes_dir, { allowed_kinds: project.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({
+			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.list,
 				date: /* @__PURE__ */ new Date()
@@ -61,23 +61,23 @@ const generate_release_pr = create_command({
 				changes_by_kind.set(change.kind, existing);
 			}
 			const message_lines = [];
-			const display_map = app.versioning.display_map;
+			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}`);
+				for (const change of kind_changes) message_lines.push(`  ${change.summary}`);
 			}
-			logger.note(`Release ${app.name} ${next_version}`, message_lines.join("\n"));
+			logger.note(`Release ${project.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) {
+			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 = app.versioning.formatter;
-			const initial_changelog_content = await read_file(app.changelog);
+			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({
@@ -85,25 +85,25 @@ const generate_release_pr = create_command({
 				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);
+				}, ...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);
 			const platform = config.git.platform;
-			const release_branch_name = `${config.git.default_release_branch_prefix}/${app.name}`;
+			const release_branch_name = `${config.git.default_release_branch_prefix}/${project.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}`
+				commit_message: `chore: prepare release ${project.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}`,
+				title: `release: ${project.name}@${next_version}`,
 				body: formatter.generate_pr_body({
-					app: { name: app.name },
+					project: { name: project.name },
 					current_version,
 					next_version,
 					changes: changes.list