aronrepo 2.2.1 → 3.0.0

package/dist/index.js

@@ -1,12 +1,759 @@
-//#region src/index.ts
-const packages = [
-	"@aronrepo/commitlint-config",
-	"@aronrepo/conventional-commits",
-	"@aronrepo/conventional-changelog-config",
-	"@aronrepo/semantic-release-config",
-	"@aronrepo/semantic-release-pnpm"
-];
-//#endregion
-export { packages };
+import picomatch from "picomatch";
+import semver from "semver";
+// src/commits.ts
+/** Release levels in descending order. */
+const releaseLevels = [
+	"major",
+	"minor",
+	"patch"
+];
+function compareRelease(a, b) {
+	const rank = (release) => release ? 3 - releaseLevels.indexOf(release) : 0;
+	return rank(a) - rank(b);
+}
+function maxRelease(...releases) {
+	return releases.reduce((highest, release) => compareRelease(release, highest) > 0 ? release : highest, false);
+}
+/**
+* The Aronrepo commit types. The table is fixed: repositories choose a release
+* mode and release paths, not their own types.
+*
+* Release notes list the groups in this order.
+*/
+const commits = [
+	{
+		type: "Bump",
+		scope: "Major",
+		release: "major",
+		description: "Release a major version. Only the repository owner decides it."
+	},
+	{
+		type: "Bump",
+		scope: "Minor",
+		release: "minor",
+		description: "Release a minor version. Only the repository owner decides it."
+	},
+	{
+		type: "Bump",
+		scope: "Patch",
+		release: "patch",
+		description: "Release a patch version without another release commit."
+	},
+	{
+		type: "Add",
+		release: "minor",
+		group: "Additions",
+		description: "A new capability: a new API, export, option, command, or package."
+	},
+	{
+		type: "Improve",
+		release: "patch",
+		group: "Improvements",
+		description: "A better existing capability without new API: behavior, output, messages, or defaults."
+	},
+	{
+		type: "Perf",
+		release: "patch",
+		group: "Performance",
+		description: "Faster or lighter published code with the same behavior."
+	},
+	{
+		type: "Fix",
+		release: "patch",
+		group: "Bug Fixes",
+		description: "A bug fix in published behavior."
+	},
+	{
+		type: "Deprecate",
+		release: "patch",
+		group: "Deprecations",
+		description: "Mark a published capability as deprecated while it keeps working."
+	},
+	{
+		type: "Drop",
+		release: "patch",
+		group: "Removals",
+		description: "Remove a published capability."
+	},
+	{
+		type: "Upgrade",
+		release: "patch",
+		group: "Dependencies",
+		description: "Change a runtime dependency of a published package."
+	},
+	{
+		type: "Revert",
+		release: "patch",
+		group: "Reverts",
+		description: "Revert a commit. It releases what the reverted commit released."
+	},
+	{
+		type: "Docs",
+		scope: "README",
+		release: "patch",
+		group: "Documentation",
+		description: "Change a published package README."
+	},
+	{
+		type: "Docs",
+		release: false,
+		description: "Documentation that is not a published package README."
+	},
+	{
+		type: "Test",
+		release: false,
+		description: "Tests that cover existing behavior."
+	},
+	{
+		type: "Benchmark",
+		release: false,
+		description: "Benchmark harnesses, fixtures, and reports."
+	},
+	{
+		type: "Example",
+		release: false,
+		description: "Examples that do not ship in a package."
+	},
+	{
+		type: "Build",
+		release: false,
+		description: "Build tooling and development configuration."
+	},
+	{
+		type: "CI",
+		release: false,
+		description: "CI workflows and automation."
+	},
+	{
+		type: "Style",
+		release: false,
+		description: "Formatting and lint-only changes."
+	},
+	{
+		type: "Refactor",
+		release: false,
+		description: "Code changes that keep published behavior."
+	},
+	{
+		type: "Chore",
+		release: false,
+		description: "Maintenance: development dependencies, lockfiles, metadata, agent guidance, and unpublished workspaces."
+	}
+];
+/**
+* Types from earlier Aronrepo versions. They still resolve in history so old
+* commits release as before, but `aronrepo check` rejects them in new commits.
+*/
+const legacyCommits = [
+	{
+		type: "Feat",
+		replacement: "Add"
+	},
+	{
+		type: "New",
+		replacement: "Add"
+	},
+	{
+		type: "Update",
+		replacement: "Improve"
+	},
+	{
+		type: "Misc",
+		replacement: "Chore"
+	}
+];
+const types = [...new Set(commits.map(({ type }) => type))];
+const legacyTypes = legacyCommits.map(({ type }) => type);
+const releaseCommits = commits.filter(({ release }) => release !== false);
+const nonReleaseCommits = commits.filter(({ release }) => release === false);
+const releaseTypes = [...new Set(releaseCommits.map(({ type }) => type))];
+const nonReleaseTypes = [...new Set(nonReleaseCommits.map(({ type }) => type))];
+/** Release notes groups in display order. */
+const releaseGroups = [...new Set(commits.flatMap(({ group }) => group ? [group] : []))];
+function normalizeType(type) {
+	return legacyCommits.find((legacy) => legacy.type === type)?.replacement ?? type;
+}
+function findCommitRule(type, scope) {
+	const current = normalizeType(type);
+	if (!current) return void 0;
+	return commits.find((commit) => commit.type === current && commit.scope === scope) ?? commits.find((commit) => commit.type === current && commit.scope === void 0);
+}
+// src/policy.ts
+const releaseModes = ["explicit", "auto"];
+const defaultReleaseMode = "explicit";
+const defaultReleasePathExcludes = [
+	"**/tests/**",
+	"**/test/**",
+	"**/__tests__/**",
+	"**/*.{test,spec}.*",
+	"**/benchmarks/**",
+	"**/examples/**",
+	"**/CHANGELOG.md",
+	".github/**",
+	".husky/**"
+];
+function defineConfig(config) {
+	return config;
+}
+function getReleasePolicy(config = {}) {
+	const mode = config.release?.mode ?? "explicit";
+	if (!releaseModes.includes(mode)) throw new Error(`Unknown Aronrepo release mode "${String(mode)}". Use one of: ${releaseModes.join(", ")}.`);
+	return {
+		mode,
+		...config.release?.paths !== void 0 ? { paths: config.release.paths } : {}
+	};
+}
+const defaultReleasePolicy = { mode: defaultReleaseMode };
+/** Returns a matcher for release paths, or `undefined` when every path may release. */
+function createReleasePathMatcher(paths) {
+	if (!paths || !paths.include) return void 0;
+	const include = picomatch(paths.include.length ? paths.include : ["!**"], { dot: true });
+	const exclude = picomatch(paths.exclude ?? defaultReleasePathExcludes, { dot: true });
+	return (file) => include(file) && !exclude(file);
+}
+/**
+* Release level of a commit type in the given mode, ignoring breaking markers and paths.
+* Use `resolveCommitRelease()` for the full decision.
+*/
+function getReleaseType(type, scope, policy = defaultReleasePolicy) {
+	const release = findCommitRule(type, scope)?.release;
+	if (release === void 0) return void 0;
+	return capRelease(release, type, policy);
+}
+function capRelease(release, type, policy) {
+	if (policy.mode === "explicit" && type !== "Bump" && (release === "major" || release === "minor")) return "patch";
+	return release;
+}
+const headerPattern = /^([A-Z]\w*)(?:\(([0-9A-Z`_#~].*)\))?: ([0-9A-Z`_#~].*)$/;
+const breakingHeaderPattern = /^([A-Z]\w*)(?:\(([^)]*)\))?!: (.+)$/;
+const breakingNotePattern = /^BREAKING[ -]CHANGE:/m;
+const footerLinePattern = /^BREAKING[ -]CHANGE:/;
+const githubRevertPattern = /^Revert "([\s\S]+)"$/;
+const revertHashPattern = /This reverts commit ([0-9a-f]{7,40})/i;
+const trailerPattern = /^[\w-]+: /;
+/** `BREAKING CHANGE:` footer texts; each runs until a blank line, another footer, or a git trailer. */
+function readBreakingNotes(lines) {
+	const notes = [];
+	let current;
+	for (const line of lines) {
+		const start = /^BREAKING[ -]CHANGE:\s*(.*)$/.exec(line);
+		if (start) {
+			if (current) notes.push(current.join(" ").trim());
+			current = [start[1]];
+		} else if (current && line.trim() && !trailerPattern.test(line)) current.push(line.trim());
+		else if (current) {
+			notes.push(current.join(" ").trim());
+			current = void 0;
+		}
+	}
+	if (current) notes.push(current.join(" ").trim());
+	return notes.filter(Boolean);
+}
+function parseCommit(message, hash) {
+	const [header = "", ...rest] = message.replace(/\r\n/g, "\n").trim().split("\n");
+	const body = rest.join("\n").trim();
+	const parsed = {
+		header,
+		body,
+		...hash ? { hash } : {}
+	};
+	const layout = [];
+	if (rest.length && rest[0].trim()) layout.push("body-leading-blank");
+	if (rest.some((line, index) => index > 0 && footerLinePattern.test(line) && rest[index - 1].trim())) layout.push("footer-leading-blank");
+	if (layout.length) parsed.layout = layout;
+	const breakingNotes = readBreakingNotes(rest);
+	if (breakingNotes.length) parsed.breakingNotes = breakingNotes;
+	const regular = headerPattern.exec(header);
+	const match = regular ?? breakingHeaderPattern.exec(header);
+	if (match) {
+		parsed.type = match[1];
+		if (match[2]) parsed.scope = match[2];
+		parsed.subject = match[3];
+		if (!regular) parsed.breaking = "header";
+	}
+	if (!parsed.breaking && breakingNotePattern.test(body)) parsed.breaking = "footer";
+	const githubRevert = githubRevertPattern.exec(header);
+	if (githubRevert || parsed.type === "Revert") {
+		const revertedHeader = githubRevert?.[1] ?? (parsed.subject && headerPattern.test(parsed.subject) ? parsed.subject : void 0);
+		const revertedHash = revertHashPattern.exec(body)?.[1];
+		parsed.revert = {
+			...revertedHeader ? { header: revertedHeader } : {},
+			...revertedHash ? { hash: revertedHash } : {}
+		};
+	}
+	return parsed;
+}
+const nonReleaseAlternatives = [
+	"Chore",
+	"Refactor",
+	"Style",
+	"Test",
+	"Docs",
+	"Build",
+	"CI",
+	"Benchmark",
+	"Example"
+];
+function suggestNonReleaseHeader(commit) {
+	const subject = commit.subject ?? "";
+	const scope = commit.scope ? `(${commit.scope})` : "";
+	switch (commit.type) {
+		case "Docs": return `Docs: ${subject}`;
+		case "Upgrade": return `Chore(Deps): ${subject}`;
+		default: return `Chore${scope}: ${subject}`;
+	}
+}
+const looseHeaderPattern = /^(\w+)(?:\(([^)]*)\))?(!)?: ?(.*)$/;
+function diagnoseHeader(header) {
+	const format = "Use `Type(Scope): Summary` or `Type: Summary` with an Aronrepo commit type.";
+	const match = looseHeaderPattern.exec(header);
+	if (!match) return format;
+	const [, type, scope, bang, subject] = match;
+	if (!/^[A-Z]/.test(type)) return `The type \`${type}\` must be PascalCase, such as \`${type[0].toUpperCase()}${type.slice(1)}\`. ${format}`;
+	if (bang) return `Aronrepo headers do not use \`!\`. ${format}`;
+	if (scope !== void 0 && !/^[0-9A-Z`_#~]/.test(scope)) return `The scope \`${scope}\` must start with an uppercase letter or digit. ${format}`;
+	if (!subject) return `The summary is empty. ${format}`;
+	if (!/^[0-9A-Z`_#~]/.test(subject)) return `The summary must start with an uppercase letter or digit. ${format}`;
+	return format;
+}
+function formatRelease(release) {
+	return release ? release : "none";
+}
+function resolveCommitRelease(input, policy = defaultReleasePolicy, options = {}) {
+	const commit = typeof input === "string" ? parseCommit(input) : input;
+	const decision = {
+		...commit.hash ? { hash: commit.hash } : {},
+		header: commit.header,
+		...commit.type ? { type: commit.type } : {},
+		...commit.scope ? { scope: commit.scope } : {},
+		...commit.subject ? { subject: commit.subject } : {},
+		...commit.breakingNotes ? { breakingNotes: commit.breakingNotes } : {},
+		release: false,
+		reasons: [],
+		violations: []
+	};
+	if (commit.revert?.header && !commit.type) decision.type = "Revert";
+	else if (!commit.type) {
+		decision.reasons.push("Header does not follow `Type(Scope): Summary`; no release.");
+		decision.violations.push({
+			rule: "header-format",
+			message: diagnoseHeader(commit.header)
+		});
+		return decision;
+	} else if (!types.includes(commit.type) && !legacyTypes.includes(commit.type)) {
+		decision.reasons.push(`Unknown type \`${commit.type}\`; no release.`);
+		decision.violations.push({
+			rule: "unknown-type",
+			message: `\`${commit.type}\` is not an Aronrepo commit type. Use one of: ${types.join(", ")}.`
+		});
+		return decision;
+	} else if (!findCommitRule(commit.type, commit.scope)) {
+		decision.reasons.push(`\`${commit.type}${commit.scope ? `(${commit.scope})` : ""}\` is not an Aronrepo commit type; no release.`);
+		decision.violations.push({
+			rule: "unknown-type",
+			message: `\`${commit.type}\` needs a scope: ${commits.filter(({ type }) => type === commit.type).map(({ type, scope }) => `\`${type}(${scope})\``).join(", ")}.`
+		});
+		return decision;
+	}
+	if (commit.subject?.endsWith(".")) decision.violations.push({
+		rule: "subject-full-stop",
+		message: "The summary must not end with a period.",
+		suggestion: commit.header.replace(/\.+$/, "")
+	});
+	for (const rule of commit.layout ?? []) decision.violations.push({
+		rule,
+		severity: "warning",
+		message: rule === "body-leading-blank" ? "Leave a blank line between the header and the body." : "Leave a blank line before a `BREAKING CHANGE:` footer."
+	});
+	if (commit.type && legacyTypes.includes(commit.type)) {
+		const replacement = normalizeType(commit.type);
+		const scope = commit.scope ? `(${commit.scope})` : "";
+		decision.reasons.push(`\`${commit.type}\` is a legacy type; it releases like \`${replacement}\`.`);
+		decision.violations.push({
+			rule: "legacy-type",
+			message: `\`${commit.type}\` is a legacy Aronrepo type. Use \`${replacement}\`.`,
+			suggestion: `${replacement}${scope}: ${commit.subject ?? ""}`
+		});
+	}
+	let release;
+	if (decision.type === "Revert" && commit.revert?.header) {
+		release = resolveCommitRelease(commit.revert.header, policy, options).release;
+		decision.reasons.push(`Reverts \`${commit.revert.header}\`, which releases ${formatRelease(release)}.`);
+	} else {
+		const rule = findCommitRule(decision.type, decision.scope);
+		release = capRelease(rule.release, decision.type, policy);
+		decision.reasons.push(`\`${decision.type}${decision.scope ? `(${decision.scope})` : ""}\` releases ${formatRelease(release)} in ${policy.mode} mode.`);
+		if (release !== rule.release) decision.reasons.push(`Explicit mode caps \`${decision.type}\` at patch; only \`Bump(Minor)\` or \`Bump(Major)\` raise the version further.`);
+	}
+	const isBumpMajor = decision.type === "Bump" && decision.scope === "Major";
+	if (commit.breaking && !isBumpMajor) {
+		const marker = commit.breaking === "header" ? "`!` header" : "`BREAKING CHANGE:` footer";
+		if (policy.mode === "auto") {
+			release = "major";
+			decision.reasons.push(`The ${marker} releases major in auto mode.`);
+		} else {
+			decision.reasons.push(`The ${marker} is ignored in explicit mode; only \`Bump(Major)\` releases major.`);
+			decision.violations.push({
+				rule: "implicit-breaking",
+				message: `A ${marker} does not release a major version in explicit mode. Describe the change without the breaking marker, or ask the repository owner whether to add a \`Bump(Major)\` commit.`
+			});
+		}
+	}
+	const isBump = decision.type === "Bump";
+	if (release && !isBump && options.files && options.isReleasePath) {
+		if (!options.files.filter(options.isReleasePath).length) {
+			decision.reasons.push("No changed file ships in a published package; no release.");
+			decision.violations.push({
+				rule: "release-paths",
+				message: `\`${decision.type}${decision.scope ? `(${decision.scope})` : ""}\` releases ${formatRelease(release)}, but the commit changes no release paths. Use a non-release type: ${nonReleaseAlternatives.join(", ")}.`,
+				suggestion: suggestNonReleaseHeader({
+					...commit,
+					type: decision.type
+				})
+			});
+			release = false;
+		}
+	}
+	decision.release = release;
+	return decision;
+}
+function resolveRelease(inputs, policy = defaultReleasePolicy, options = {}) {
+	const parsed = inputs.map((input) => parseCommit(input.message, input.hash));
+	const decisions = parsed.map((commit, index) => resolveCommitRelease(commit, policy, {
+		...options,
+		...inputs[index].files ? { files: inputs[index].files } : {}
+	}));
+	parsed.forEach((commit, index) => {
+		const revertedHash = commit.revert?.hash;
+		if (!revertedHash) return;
+		const revertedIndex = parsed.findIndex((candidate) => candidate.hash?.startsWith(revertedHash) || candidate.hash && revertedHash.startsWith(candidate.hash));
+		if (revertedIndex === -1 || revertedIndex === index) return;
+		for (const [target, other] of [[index, revertedIndex], [revertedIndex, index]]) {
+			decisions[target].release = false;
+			decisions[target].reasons.push(`Cancelled by \`${parsed[other].header}\` in the same release.`);
+		}
+	});
+	return {
+		release: maxRelease(...decisions.map(({ release }) => release)),
+		commits: decisions
+	};
+}
+// src/agent.ts
+function getAgentCommitPolicy(policy = defaultReleasePolicy, options = {}) {
+	const explicit = policy.mode === "explicit";
+	const cli = options.cli ?? "npx aronrepo";
+	return {
+		mode: policy.mode,
+		defaultInternalCommit: "Chore(Agent): Clarify commit selection policy",
+		defaultInternalType: "Chore",
+		defaultInternalScope: "Agent",
+		releaseImpactRule: "Use a release type only when the commit changes files that ship in a published package (release paths) and affects published behavior, public API, release behavior, or published README content. Otherwise use a non-release type.",
+		ownerDecisions: explicit ? [
+			"Never write `Bump(Major)` or `Bump(Minor)` unless the user explicitly asked for that release level in the current conversation.",
+			"Never add a `BREAKING CHANGE:` footer or a `Type!:` header. If a change breaks published behavior, stop and ask the user how to release it.",
+			"Every type except `Bump(Minor)` and `Bump(Major)` releases at most a patch. Pick the type that describes the change, not the release level you want."
+		] : [
+			"Never write `Bump(Major)` or `Bump(Minor)` unless the user explicitly asked for that release level in the current conversation.",
+			"A `BREAKING CHANGE:` footer releases a major version. Add one only for a real break in published behavior or public API, and tell the user.",
+			"`Add` releases a minor version. Use it only for new capabilities of published packages."
+		],
+		releaseWorthyChanges: [
+			"Published package runtime behavior",
+			"Public API, exports, or types",
+			"Release, changelog, or versioning behavior",
+			"Published README content that requires a package patch release"
+		],
+		nonReleaseDefaults: [
+			"Agent instructions, prompts, and repository context: `Chore(Agent)`",
+			"Sites, apps, and other unpublished workspaces: `Chore(<Scope>)`, `Refactor`, `Style`, or `Test`, even for fixes and performance work",
+			"Tests that only cover existing behavior: `Test`",
+			"Benchmark harnesses, fixtures, reports, and measurement-only changes: `Benchmark` (never `Perf`)",
+			"Build tooling and dev-only configuration: `Build`; CI workflows: `CI`; formatting: `Style`",
+			"Development dependencies, lockfiles, and routine metadata: `Chore(Deps)` or `Chore`",
+			"Examples: `Example`; internal or site documentation: `Docs`",
+			"Refactors that do not change published behavior: `Refactor`"
+		],
+		verification: [`${cli} check --from origin/main --to HEAD`, `${cli} explain`],
+		examples: [
+			{
+				commit: "Add(Core): Support ESM config files",
+				use: "A new capability in a published package",
+				release: getReleaseType("Add", "Core", policy) ?? false,
+				...explicit ? { avoid: "Feat(Core): Support ESM config files" } : {}
+			},
+			{
+				commit: "Chore(Site): Fix the homepage header transition",
+				use: "A fix in an unpublished site or app workspace",
+				release: false,
+				avoid: "Fix(Site): Fix the homepage header transition"
+			},
+			{
+				commit: "Chore(Agent): Update repository guidance for coding agents",
+				use: "Agent instructions, prompts, or repo context",
+				release: false,
+				avoid: "Feat(Agent): Add agent guide"
+			},
+			{
+				commit: "Test(Release): Cover scoped README bump rules",
+				use: "Tests that validate existing release behavior",
+				release: false
+			},
+			{
+				commit: "Benchmark(Benchmarks): Refresh benchmark report",
+				use: "Benchmark-only changes when the benchmark area is the useful scope",
+				release: false,
+				avoid: "Perf(Benchmarks): Refresh benchmark report"
+			},
+			{
+				commit: "Benchmark: Refresh benchmark report",
+				use: "Benchmark-only changes when no clear scope exists",
+				release: false
+			},
+			{
+				commit: "CI(GitHub): Update PR title check permissions",
+				use: "CI workflow, status check, and automation changes that do not change release behavior",
+				release: false,
+				avoid: "Fix(CI): Update PR title check permissions"
+			},
+			{
+				commit: "Build(Tooling): Update Vitest config",
+				use: "Build system, bundler, local tooling, and dev-only configuration changes",
+				release: false,
+				avoid: "Update(Build): Update Vitest config"
+			},
+			{
+				commit: "Style(Lint): Format TypeScript files",
+				use: "Formatting, lint-only, whitespace, or readability changes with no behavior change",
+				release: false,
+				avoid: "Improve(Core): Format TypeScript files"
+			},
+			{
+				commit: "Chore(Deps): Update Vitest dev dependency",
+				use: "Development dependency, lockfile, audit report, and routine metadata changes",
+				release: false,
+				avoid: "Upgrade(Deps): Update Vitest dev dependency"
+			},
+			{
+				commit: "Example(Release): Add a release workflow sample",
+				use: "Example-only additions or updates that do not change published package behavior",
+				release: false,
+				avoid: "Add(Example): Add a release workflow sample"
+			},
+			{
+				commit: "Docs: Add commit type examples",
+				use: "Documentation that is not published as package README content",
+				release: false
+			},
+			{
+				commit: "Docs(README): Clarify package installation",
+				use: "A published package README (not the repository root README)",
+				release: "patch"
+			},
+			{
+				commit: "Fix(Release): Preserve workspace dependency ranges",
+				use: "A release behavior bug that affects published package behavior",
+				release: "patch"
+			}
+		]
+	};
+}
+/** Agent policy for the default `explicit` mode. */
+const agentCommitPolicy = getAgentCommitPolicy();
+function formatRule(type, scope) {
+	return `\`${type}${scope ? `(${scope})` : ""}\``;
+}
+function getReleaseTable(policy = defaultReleasePolicy) {
+	const rows = {
+		major: [],
+		minor: [],
+		patch: [],
+		none: []
+	};
+	for (const { type, scope } of commits) rows[getReleaseType(type, scope, policy) || "none"].push(formatRule(type, scope));
+	if (policy.mode === "auto") rows.major.push("`BREAKING CHANGE:` footer");
+	return rows;
+}
+const agentsBlockStart = "<!-- aronrepo:commit-policy:start -->";
+const agentsBlockEnd = "<!-- aronrepo:commit-policy:end -->";
+/** Renders the generated commit policy block for AGENTS.md, including its markers. */
+function renderAgentsBlock(policy = defaultReleasePolicy, options = {}) {
+	const agent = getAgentCommitPolicy(policy, options);
+	const paths = options.releasePaths;
+	const typeRows = commits.map(({ type, scope, description }) => `| ${formatRule(type, scope)} | ${getReleaseType(type, scope, policy) || "none"} | ${description} |`);
+	return [
+		agentsBlockStart,
+		"<!-- Generated by `aronrepo agents --write`. Edit aronrepo.config.js and regenerate instead of editing this block. -->",
+		"",
+		"## Commit and Release Policy",
+		"",
+		`Release mode: **${policy.mode}**. ${policy.mode === "explicit" ? "Only the repository owner decides minor and major versions, with `Bump(Minor)` and `Bump(Major)` commits." : "`Add` releases minor versions, and `BREAKING CHANGE:` footers release major versions."}`,
+		"",
+		"Commit headers and PR titles use `Type(Scope): Summary` or `Type: Summary`: a PascalCase type, an optional scope for the package or area, and a sentence-case summary without a trailing period.",
+		"",
+		"| Type | Release | Use for |",
+		"| --- | --- | --- |",
+		...typeRows,
+		"",
+		`Legacy types are rejected: ${legacyCommits.map(({ type, replacement }) => `\`${type}\` (use \`${replacement}\`)`).join(", ")}.`,
+		"",
+		"### Release decisions belong to the owner",
+		"",
+		...agent.ownerDecisions.map((rule) => `- ${rule}`),
+		"",
+		"### Choosing a type",
+		"",
+		`- ${agent.releaseImpactRule}`,
+		"- Pick the type that describes the change: a new capability is `Add`, a better existing capability is `Improve`, a bug fix is `Fix`, and a runtime dependency change is `Upgrade`.",
+		`- A commit that changes no release path must use a non-release type (${nonReleaseAlternatives.map((type) => `\`${type}\``).join(", ")}), even when it fixes or speeds up something.`,
+		"- Split unrelated changes so each commit carries its own release level.",
+		"",
+		"Non-release defaults:",
+		"",
+		...agent.nonReleaseDefaults.map((rule) => `- ${rule}`),
+		"",
+		"### Release paths",
+		"",
+		...paths?.include ? [
+			"Only changes to these files can release a version:",
+			"",
+			...paths.include.map((glob) => `- \`${glob}\``),
+			"",
+			`Excluding: ${(paths.exclude ?? defaultReleasePathExcludes).map((glob) => `\`${glob}\``).join(", ")}.`
+		] : ["Every path can release a version in this repository."],
+		"",
+		"### Before handing off commits",
+		"",
+		...agent.verification.map((command) => `- \`${command}\``),
+		"",
+		"`aronrepo explain` prints the next release level and the reason for each commit. Tell the user when it is not what they expect.",
+		agentsBlockEnd
+	].join("\n");
+}
+// src/version.ts
+/** Prerelease branches. Each publishes `X.Y.Z-<branch>.N` on the npm dist-tag of the same name. */
+const prereleaseChannels = [
+	"alpha",
+	"beta",
+	"rc",
+	"canary"
+];
+/** Branches that release: `main` publishes on `latest`, and each prerelease branch on its own dist-tag. */
+const releaseBranches = ["main", ...prereleaseChannels];
+/** The release channel of a branch, or `undefined` when the branch does not release. */
+function getReleaseChannel(branch) {
+	if (branch === "main") return {
+		branch,
+		distTag: "latest"
+	};
+	if (branch && prereleaseChannels.includes(branch)) return {
+		branch,
+		distTag: branch,
+		prerelease: branch
+	};
+}
+/** The first version of a repository without version tags. */
+const initialVersion = "1.0.0";
+function toVersionTag(version) {
+	return `v${version}`;
+}
+/** The version of a `vX.Y.Z` or `vX.Y.Z-pre.N` tag, or `undefined` for other tags. */
+function parseVersionTag(tag) {
+	if (!tag.startsWith("v")) return void 0;
+	const version = tag.slice(1);
+	return semver.valid(version) === version ? version : void 0;
+}
+function versionsOf(tags) {
+	return tags.flatMap((tag) => {
+		const version = parseVersionTag(tag);
+		return version ? [version] : [];
+	});
+}
+function highest(versions) {
+	return versions.length ? semver.rsort([...versions])[0] : void 0;
+}
+function stableVersions(versions) {
+	return versions.filter((version) => !semver.prerelease(version));
+}
+function channelVersions(versions, prerelease) {
+	return versions.filter((version) => semver.prerelease(version)?.[0] === prerelease);
+}
+function coreVersion(version) {
+	return `${semver.major(version)}.${semver.minor(version)}.${semver.patch(version)}`;
+}
+/** The latest stable version among tags, if any. */
+function getLatestStableVersion(tags) {
+	return highest(stableVersions(versionsOf(tags)));
+}
+/**
+* The tag a channel's release range starts from: the latest stable tag, or on a
+* prerelease branch the latest tag of that channel when it is newer.
+*/
+function getBaseTag(channel, reachableTags) {
+	const versions = versionsOf(reachableTags);
+	const stable = highest(stableVersions(versions));
+	if (channel.prerelease) {
+		const prerelease = highest(channelVersions(versions, channel.prerelease).filter((version) => !stable || semver.gt(version, stable)));
+		if (prerelease) return toVersionTag(prerelease);
+	}
+	return stable ? toVersionTag(stable) : void 0;
+}
+/**
+* The next version of a channel.
+*
+* `main` raises the latest stable version by `release`. A prerelease branch
+* targets the same version, or the version its earlier prereleases already
+* target when that is higher, and numbers the prerelease after every existing
+* tag of that version and channel.
+*/
+function getNextVersion(channel, release, tags) {
+	const reachable = versionsOf(tags.reachable);
+	const stable = highest(stableVersions(reachable));
+	const target = stable ? semver.inc(stable, release) : initialVersion;
+	if (!channel.prerelease) return target;
+	const previous = highest(channelVersions(reachable, channel.prerelease).filter((version) => !stable || semver.gt(version, stable)));
+	const core = previous && semver.gte(coreVersion(previous), target) ? coreVersion(previous) : target;
+	const numbers = channelVersions(versionsOf(tags.all), channel.prerelease).filter((version) => coreVersion(version) === core).map((version) => Number(semver.prerelease(version)?.[1] ?? 0));
+	return `${core}-${channel.prerelease}.${Math.max(0, ...numbers) + 1}`;
+}
+// src/notes.ts
+const breakingTitle = "⚠ Breaking Changes";
+function groupOf(decision) {
+	if (decision.type === "Revert") return "Reverts";
+	return findCommitRule(decision.type, decision.scope)?.group;
+}
+function formatEntry(decision, repositoryUrl) {
+	const summary = decision.subject ?? decision.header;
+	const scope = decision.scope ? `**${decision.scope}:** ` : "";
+	const hash = decision.hash ? decision.hash.slice(0, 7) : void 0;
+	return `- ${scope}${summary}${hash ? repositoryUrl ? ` ([${hash}](${repositoryUrl}/commit/${decision.hash}))` : ` (${hash})` : ""}`;
+}
+/**
+* Markdown release notes. Only commits that release appear, grouped by type in
+* the order of the commit table; `BREAKING CHANGE:` footers of major releases
+* come first.
+*/
+function renderReleaseNotes(options) {
+	const { version, previousTag, repositoryUrl } = options;
+	const tag = `v${version}`;
+	const lines = [`## ${repositoryUrl && previousTag ? `[${version}](${repositoryUrl}/compare/${previousTag}...${tag})` : version}${options.date ? ` (${options.date})` : ""}`];
+	const released = options.commits.filter(({ release }) => release);
+	const breaking = released.filter(({ release }) => release === "major").flatMap(({ breakingNotes }) => breakingNotes ?? []);
+	if (breaking.length) lines.push("", `### ${breakingTitle}`, "", ...breaking.map((note) => `- ${note}`));
+	const groups = /* @__PURE__ */ new Map();
+	for (const decision of released) {
+		const group = groupOf(decision);
+		if (!group) continue;
+		groups.set(group, [...groups.get(group) ?? [], decision]);
+	}
+	for (const group of releaseGroups) {
+		const entries = groups.get(group);
+		if (!entries) continue;
+		const sorted = [...entries].sort((a, b) => (a.scope ?? "").localeCompare(b.scope ?? "", "en") || (a.subject ?? a.header).localeCompare(b.subject ?? b.header, "en"));
+		lines.push("", `### ${group}`, "", ...sorted.map((decision) => formatEntry(decision, repositoryUrl)));
+	}
+	if (!breaking.length && !groups.size) lines.push("", "No changes to published packages.");
+	return `${lines.join("\n")}\n`;
+}
+export { agentCommitPolicy, agentsBlockEnd, agentsBlockStart, commits, compareRelease, createReleasePathMatcher, defaultReleaseMode, defaultReleasePathExcludes, defaultReleasePolicy, defineConfig, findCommitRule, getAgentCommitPolicy, getBaseTag, getLatestStableVersion, getNextVersion, getReleaseChannel, getReleasePolicy, getReleaseTable, getReleaseType, headerPattern, initialVersion, legacyCommits, legacyTypes, maxRelease, nonReleaseAlternatives, nonReleaseCommits, nonReleaseTypes, normalizeType, parseCommit, parseVersionTag, prereleaseChannels, releaseBranches, releaseCommits, releaseGroups, releaseLevels, releaseModes, releaseTypes, renderAgentsBlock, renderReleaseNotes, resolveCommitRelease, resolveRelease, toVersionTag, types };
 
 //# sourceMappingURL=index.js.map