@afoures/auto-release 0.2.12 → 0.3.0

package/dist/lib/commands/tag-release-commit.mjs

@@ -7,17 +7,17 @@ import { relative } from "node:path";
 
 //#region src/lib/commands/tag-release-commit.ts
 /**
-* Get the version of an app at a specific git revision
+* Get the version of a project at a specific git revision
 */
-async function get_app_version_at_revision(app, root, revision) {
+async function get_project_version_at_revision(project, root, revision) {
 	try {
-		const version = await compute_current_version(app, { get_file_content: (file_path) => {
+		const version = await compute_current_version(project, { get_file_content: (file_path) => {
 			const relative_path = relative(root, file_path);
 			return read_file_at_revision(root, revision, relative_path);
-		} }) ?? app.versioning.initial_version;
-		if (!app.versioning.validate({ version })) return {
+		} }) ?? project.versioning.initial_version;
+		if (!project.versioning.validate({ version })) return {
 			ok: false,
-			error: `Invalid version format for ${app.name} at revision ${revision}: ${version}`
+			error: `Invalid version format for ${project.name} at revision ${revision}: ${version}`
 		};
 		return {
 			ok: true,
@@ -26,7 +26,7 @@ async function get_app_version_at_revision(app, root, revision) {
 	} catch (error) {
 		return {
 			ok: false,
-			error: `Failed to get version for ${app.name} at revision ${revision}: ${error.message}`
+			error: `Failed to get version for ${project.name} at revision ${revision}: ${error.message}`
 		};
 	}
 }
@@ -60,34 +60,37 @@ const tag_release_commit = create_command({
 			status: "success",
 			message: "HEAD has no parent commit - nothing to tag"
 		};
-		const changed_apps = [];
-		for (const app of config.managed_applications) {
-			const head_result = await get_app_version_at_revision(app, root, head_sha);
+		const changed_projects = [];
+		for (const project of config.managed_projects) {
+			const head_result = await get_project_version_at_revision(project, root, head_sha);
 			if (!head_result.ok) return {
 				status: "error",
-				error: `Failed to get HEAD version for ${app.name}: ${head_result.error}`
+				error: `Failed to get HEAD version for ${project.name}: ${head_result.error}`
 			};
-			const base_result = await get_app_version_at_revision(app, root, base_sha);
+			const base_result = await get_project_version_at_revision(project, root, base_sha);
 			if (!base_result.ok) return {
 				status: "error",
-				error: `Failed to get base version for ${app.name}: ${base_result.error}`
+				error: `Failed to get base version for ${project.name}: ${base_result.error}`
 			};
-			if (head_result.version !== base_result.version) changed_apps.push({
-				app,
+			if (head_result.version !== base_result.version) changed_projects.push({
+				project,
 				head_version: head_result.version,
 				base_version: base_result.version
 			});
 		}
-		if (changed_apps.length === 0) return {
+		if (changed_projects.length === 0) return {
 			status: "success",
 			message: "No version changes detected"
 		};
-		logger.info(`Detected version changes in ${changed_apps.length} app(s):`);
-		for (const { app, head_version, base_version } of changed_apps) logger.info(`  ${app.name}: ${base_version} → ${head_version}`);
+		logger.info(`Detected version changes in ${changed_projects.length} project(s):`);
+		for (const { project, head_version, base_version } of changed_projects) logger.info(`  ${project.name}: ${base_version} → ${head_version}`);
 		if (dry_run) {
 			logger.info("\nDry run - would create tags and releases:");
-			for (const { app, head_version } of changed_apps) {
-				const tag = `${app.name}@${head_version}`;
+			for (const { project, head_version } of changed_projects) {
+				const tag = config.git.tag_generator({
+					project: { name: project.name },
+					version: head_version
+				});
 				logger.info(`  - Tag: ${tag}`);
 				logger.info(`  - Release: ${tag}`);
 			}
@@ -96,15 +99,18 @@ const tag_release_commit = create_command({
 				message: "Dry run completed - no changes were made"
 			};
 		}
-		const tagged_apps = [];
+		const tagged_projects = [];
 		const errors = [];
-		for (const { app, head_version } of changed_apps) {
-			const tag = `${app.name}@${head_version}`;
+		for (const { project, head_version } of changed_projects) {
+			const tag = config.git.tag_generator({
+				project: { name: project.name },
+				version: head_version
+			});
 			try {
 				const existing_tag = await config.git.platform.get_tag({ tag });
 				if (existing_tag !== null) if (existing_tag.commit_sha === head_sha) {
 					logger.info(`Tag ${tag} already exists on commit ${head_sha} - skipping`);
-					tagged_apps.push(tag);
+					tagged_projects.push(tag);
 					continue;
 				} else {
 					errors.push(`Tag ${tag} already exists but points to different commit (${existing_tag.commit_sha} vs ${head_sha})`);
@@ -119,16 +125,16 @@ const tag_release_commit = create_command({
 					tag,
 					release: {
 						name: tag,
-						body: app.versioning.formatter.generate_release_notes({
-							app: {
-								name: app.name,
-								changelog: app.changelog
+						body: project.versioning.formatter.generate_release_notes({
+							project: {
+								name: project.name,
+								changelog: project.changelog
 							},
 							version: head_version
 						})
 					}
 				});
-				tagged_apps.push(tag);
+				tagged_projects.push(tag);
 				logger.success(`Tagged and released ${tag}`);
 			} catch (error) {
 				errors.push(`Failed to tag/release ${tag}: ${error.message}`);
@@ -140,7 +146,7 @@ const tag_release_commit = create_command({
 		};
 		return {
 			status: "success",
-			message: tagged_apps.length === 1 ? `Tagged 1 app: ${tagged_apps[0]}` : `Tagged ${tagged_apps.length} apps: ${tagged_apps.join(", ")}`
+			message: tagged_projects.length === 1 ? `Tagged 1 project: ${tagged_projects[0]}` : `Tagged ${tagged_projects.length} projects: ${tagged_projects.join(", ")}`
 		};
 	}
 });

package/dist/lib/config.d.mts

@@ -1,5 +1,5 @@
 import { GitPlatformClient } from "./platforms/types.mjs";
-import { AutoReleaseConfig, ManagedApplication } from "./types.mjs";
+import { AutoReleaseConfig, ManagedProject } from "./types.mjs";
 
 //#region src/lib/config.d.ts
 declare function define_config<const config extends AutoReleaseConfig>(config: config): InternalConfig;
@@ -14,8 +14,14 @@ declare class InternalConfig {
     platform: GitPlatformClient;
     target_branch: string;
     default_release_branch_prefix: string;
+    tag_generator: (args: {
+      project: {
+        name: string;
+      };
+      version: string;
+    }) => string;
   };
-  get managed_applications(): Array<ManagedApplication>;
+  get managed_projects(): Array<ManagedProject>;
 }
 //#endregion
 export { define_config };

package/dist/lib/config.mjs

@@ -33,11 +33,12 @@ var InternalConfig = class {
 		return {
 			platform: this.#config.git.platform,
 			target_branch: this.#config.git.target_branch || "main",
-			default_release_branch_prefix: this.#config.git.default_release_branch_prefix || "release"
+			default_release_branch_prefix: this.#config.git.default_release_branch_prefix || "release",
+			tag_generator: this.#config.git.tag_generator || (({ project, version }) => `${project.name}@${version}`)
 		};
 	}
-	get managed_applications() {
-		return Object.entries(this.#config.apps).map(([name, definition]) => {
+	get managed_projects() {
+		return Object.entries(this.#config.projects).map(([name, definition]) => {
 			const components = definition.components.map((component) => component(this.folder));
 			return {
 				name,
@@ -130,16 +131,15 @@ async function find_nearest_config(options) {
 */
 function validate_config(config) {
 	if (!config.git) throw new Error("Auto-release config must have a \"git\" platform. Use github() or gitlab() from \"auto-release/providers\"");
-	if (!config.apps || typeof config.apps !== "object" || Array.isArray(config.apps)) throw new Error("Auto-release config must have an \"apps\" record (object keyed by app name)");
-	const app_entries = Object.entries(config.apps);
-	if (app_entries.length === 0) throw new Error("Auto-release config must have at least one app");
-	for (const [name, app] of app_entries) {
-		if (!app.components || !Array.isArray(app.components)) throw new Error(`App "${name}" must have a "components" array`);
-		if (app.components.length === 0) throw new Error(`App "${name}" must have at least one component`);
-		if (!app.versioning) throw new Error(`App "${name}" must have a "versioning" config`);
-		if (typeof app.versioning.bump !== "function") throw new Error(`App "${name}" versioning must have a "bump" function. Did you forget to call the strategy function?`);
-		if (!app.versioning.allowed_changes || !Array.isArray(app.versioning.allowed_changes)) throw new Error(`App "${name}" versioning must have an "allowed_changes" array`);
-		if (!app.changelog || typeof app.changelog !== "string") throw new Error(`App "${name}" must have a changelog path (string)`);
+	if (!config.projects || typeof config.projects !== "object" || Array.isArray(config.projects)) throw new Error("Auto-release config must have a \"projects\" record (object keyed by project name)");
+	const project_entries = Object.entries(config.projects);
+	for (const [name, project] of project_entries) {
+		if (!project.components || !Array.isArray(project.components)) throw new Error(`Project "${name}" must have a "components" array`);
+		if (project.components.length === 0) throw new Error(`Project "${name}" must have at least one component`);
+		if (!project.versioning) throw new Error(`Project "${name}" must have a "versioning" config`);
+		if (typeof project.versioning.bump !== "function") throw new Error(`Project "${name}" versioning must have a "bump" function. Did you forget to call the strategy function?`);
+		if (!project.versioning.allowed_changes || !Array.isArray(project.versioning.allowed_changes)) throw new Error(`Project "${name}" versioning must have an "allowed_changes" array`);
+		if (!project.changelog || typeof project.changelog !== "string") throw new Error(`Project "${name}" must have a changelog path (string)`);
 	}
 }
 

package/dist/lib/formatter.mjs

@@ -88,12 +88,10 @@ function default_formatter({ allowed_changes, display_map }) {
 		},
 		format_changelog(changelog, context) {
 			const lines = [];
-			if (changelog.root.title) lines.push(changelog.root.title);
-			else lines.push(`# \`${context.app.name}\` changelog`);
-			if (changelog.root.description.length > 0) {
-				console.log(changelog.root.description);
-				lines.push(changelog.root.description.join("\n"));
-			} else lines.push(`This is the changelog for \`${context.app.name}\`.`);
+			if (changelog.root.title) lines.push(changelog.root.title, "");
+			else lines.push(`# \`${context.project.name}\` changelog`, "");
+			if (changelog.root.description.length > 0) lines.push(changelog.root.description.join("\n"), "");
+			else lines.push(`This is the changelog for \`${context.project.name}\`.`, "");
 			for (const release of changelog.releases) {
 				const release_lines = [`## ${release.version}`, ""];
 				for (const change_kind of allowed_changes) {
@@ -107,17 +105,20 @@ function default_formatter({ allowed_changes, display_map }) {
 				if (release.changes.length === 0) release_lines.push("No changes in this release.", "");
 				lines.push(release_lines.join("\n"));
 			}
-			return lines.join("\n\n");
+			return lines.join("\n");
 		},
-		generate_release_notes({ app, version }) {
+		generate_release_notes({ project, version }) {
 			const hash = version.replaceAll(".", "");
-			const file = `${app.changelog}#${hash}`;
-			return `[See the changelog for ${app.name}@${version} release notes](${file})`;
+			const file = `${project.changelog}#${hash}`;
+			return `[See the changelog for ${project.name}@${version} release notes](${file})`;
 		},
-		generate_pr_body({ app, current_version, next_version, changes }) {
+		generate_pr_body({ project, current_version, next_version, changes }) {
 			const lines = [];
-			lines.push(`# Release ${app.name} ${next_version}`);
-			lines.push(`Version: ${current_version} → ${next_version}`);
+			lines.push("This PR is managed by `[auto-release](https://github.com/afoures/auto-release)`. Do not edit it manually.");
+			lines.push(`## Automated release for \`${project.name}\``);
+			lines.push(`Version: \`${current_version}\` → \`${next_version}\``);
+			lines.push("");
+			lines.push("## Changelog");
 			const grouped = /* @__PURE__ */ new Map();
 			for (const change of changes) {
 				const group = grouped.get(change.kind) ?? [];
@@ -130,7 +131,7 @@ function default_formatter({ allowed_changes, display_map }) {
 				const labels = resolved_display_map[kind];
 				const heading = labels?.plural ?? labels?.singular ?? kind;
 				lines.push("");
-				lines.push(`## ${heading}`);
+				lines.push(`### ${heading}`);
 				for (const change of items) {
 					lines.push(change.summary);
 					lines.push("");

package/dist/lib/types.d.mts

@@ -13,22 +13,28 @@ interface AutoReleaseConfig {
     platform: GitPlatformClient;
     target_branch?: string;
     default_release_branch_prefix?: string;
+    tag_generator?: (args: {
+      project: {
+        name: string;
+      };
+      version: string;
+    }) => string;
   };
-  apps: Record<string, AppDefinition>;
+  projects: Record<string, ProjectDefinition>;
 }
 /**
- * App definition
+ * Project definition
  */
-interface AppDefinition {
+interface ProjectDefinition {
   components: Array<Component>;
   versioning: VersionManager;
   changelog: string;
 }
-type ManagedApplication = {
+type ManagedProject = {
   name: string;
   components: Array<ResolvedComponent>;
   versioning: VersionManager;
   changelog: string;
 };
 //#endregion
-export { AutoReleaseConfig, ManagedApplication };
+export { AutoReleaseConfig, ManagedProject };

package/dist/lib/utils/branch-protection.mjs

@@ -1,6 +1,3 @@
-import "./git.mjs";
-import { cancel, confirm, isCancel, log } from "@clack/prompts";
-
 //#region src/lib/utils/branch-protection.ts
 /**
 * Detect if we're running in a CI environment

package/dist/lib/utils/version.mjs

@@ -1,14 +1,14 @@
 //#region src/lib/utils/version.ts
-async function compute_current_version(app, { get_file_content }) {
+async function compute_current_version(project, { get_file_content }) {
 	const versions = /* @__PURE__ */ new Set();
-	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 get_file_content(part.file);
 		if (file_content === null) continue;
 		const version = part.get_current_version(file_content);
 		versions.add(version);
 	}
 	if (versions.size === 0) return null;
-	return Array.from(versions).sort((a, b) => app.versioning.compare(a, b)).at(-1) ?? null;
+	return Array.from(versions).sort((a, b) => project.versioning.compare(a, b)).at(-1) ?? null;
 }
 
 //#endregion

package/dist/lib/versioning/types.d.mts

@@ -25,7 +25,7 @@ type Formatter<change_kinds extends string = string, parsed_changelog extends {
    * @returns Markdown string that will be written to the changelog file
    */
   format_changelog(changelog: NoInfer<parsed_changelog>, context: {
-    app: {
+    project: {
       name: string;
     };
   }): string;
@@ -35,7 +35,7 @@ type Formatter<change_kinds extends string = string, parsed_changelog extends {
    * @returns Markdown string for PR body
    */
   generate_pr_body(options: {
-    app: {
+    project: {
       name: string;
     };
     current_version: string;
@@ -43,12 +43,12 @@ type Formatter<change_kinds extends string = string, parsed_changelog extends {
     changes: ChangeFile<change_kinds>[];
   }): string;
   /**
-   * Generate release notes for a given app to use in GitHub/GitLab release bodies.
+   * Generate release notes for a given project to use in GitHub/GitLab release bodies.
    * @param options - The options for generating release notes
    * @returns Markdown string for release body
    */
   generate_release_notes(options: {
-    app: {
+    project: {
       name: string;
       changelog: string;
     };

package/docs/change-file-anatomy.md

@@ -0,0 +1,31 @@
+# Change Files
+
+Change files are stored in `.changes/<project-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
+```

package/docs/commands.md

@@ -0,0 +1,80 @@
+# Commands
+
+## `init`
+
+Set up auto-release in your repository:
+
+```bash
+auto-release init
+```
+
+Interactively configures projects, 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 --project my-app --type minor
+```
+
+## `list`
+
+List all projects 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 projects only
+auto-release generate-release-pr --filter my-app --filter 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 `project-name@version`.
+
+## `manual-release`
+
+Create a manual release using existing change files:
+
+```bash
+auto-release manual-release
+```
+
+Useful for local testing or emergency releases.

package/docs/configuration.md

@@ -0,0 +1,116 @@
+# Configuration
+
+## Projects
+
+The `projects` object defines each releasable unit:
+
+```typescript
+projects: {
+  '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',
+  tag_generator: ({ project, version }) => `${project.name}-${version}`,
+}
+```
+
+### GitLab
+
+```typescript
+import { gitlab } from 'auto-release/providers'
+
+git: {
+  platform: gitlab({
+    token: process.env.GITLAB_TOKEN!,
+    project_id: 'your-project-id',
+  }),
+  target_branch: 'main',
+}
+```
+
+## Tag Generator
+
+Customize the format of git tags created during release:
+
+```typescript
+git: {
+  // ... other options
+  tag_generator: ({ project, version }) => `${project.name}-${version}`,
+}
+```
+
+**Default**: `project-name@version` (e.g., `my-app@1.2.3`)
+
+**Custom examples**:
+
+```typescript
+// Version only: 1.2.3
+tag_generator: ({ version }) => `${version}`
+
+// Prefixed: v1.2.3
+tag_generator: ({ version }) => `v${version}`
+
+// With prefix: release/my-app-1.2.3
+tag_generator: ({ project, version }) => `release/${project.name}-${version}`
+```
+
+## 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'),
+]
+```

package/docs/lexicon.md

@@ -0,0 +1,23 @@
+# `auto-release` Lexicon
+
+This is a list of words and phrases used in `auto-release` to help contributors and users have a shared understanding of various concepts in the project.
+
+- **change file** - A markdown file documenting a single change to a project. Change files are stored in the changes directory with the format `<kind>.<slug>.md` (e.g., `major.add-authentication.md`). Change files are stackable, running `generate-release-pr` will apply any number of change files correctly to calculate the next version and generate changelog entries.
+- **changes directory** - The `.changes/` folder where change files are stored. This directory contains subdirectories for each project (e.g., `.changes/my-app/`), and each subdirectory contains the change files for that project.
+- **change kind** - The type of change represented by a change file (e.g., `major`, `minor`, `patch`, `feature`, `fix`). The valid kinds for a project are defined by its versioning strategy's `allowed_changes`. This determines how the version will be bumped.
+- **slug** - A unique identifier for a change file, used in the filename between the kind and the `.md` extension. Generated automatically or provided by the user (e.g., `add-authentication` in `major.add-authentication.md`).
+- **project** - A releasable unit in your repository or monorepo. Each project has its own independent versioning strategy, one or more components, its own changelog, and a dedicated subdirectory in the changes directory. Projects are defined in the configuration file.
+- **component** - A source of version information within a project. Components define where versions are read from and written to. Built-in component types include `node()/bun()` for package.json files, `expo()` for app.json files, and `php()` for composer.json files. All components within a project must have the same version.
+- **versioning strategy** - Defines how versions are calculated and formatted for a project. Each strategy specifies valid change kinds and a `bump()` function to compute the next version from the current version and collected change kinds.
+- **bump**
+  - (1) The command/process to apply all current change files, calculate new versions, update all component files, update changelogs, and remove processed change files.
+  - (2) The act of updating a project's version to a new version based on change files.
+- **changelog** - A markdown file where release entries are appended for a project. Each project specifies its changelog path in the configuration. Changelog entries are generated from change file summaries using the formatter.
+- **formatter** - Controls how changelogs and release notes are generated from change files. The formatter can parse markdown from change files and format changelog sections. The default formatter groups changes by kind and outputs markdown lists.
+- **target branch** - The main branch where releases are merged to (typically `main` or `master`). This is the branch that release PRs target and where version tags are created.
+- **release branch** - A branch created by the `generate-release-pr` command containing updated versions in all component files, new changelog entries, and removed change files. Format: `<prefix>/<project-name>` (e.g., `release/my-app`).
+- **release PR** - A pull request from a release branch to the target branch, containing all version updates and changelog changes for a release. Created or updated by the `generate-release-pr` command.
+- **git platform** - The hosting service for your git repository (GitHub or GitLab). The git platform integration is used to create and update release PRs, manage release notes, and interact with the repository API. Configured in the configuration file with authentication tokens.
+- **tag** - A git tag created when a version change is detected on the target branch after a release PR is merged. Format: `<project-name>@<version>` (e.g., `my-app@1.2.3`). Created by the `tag-release-commit` command, typically run in CI.
+- **release** - The combination of versioning, updating changelogs, creating a git tag, and publishing release notes on the git platform. This happens when a release PR is merged and the `tag-release-commit` command detects the version change.
+- **config file** - The `auto-release.config.ts` TypeScript configuration file at the root of your repository. Defines projects, their components, versioning strategies, changelog paths, and git platform settings.