bunset 0.0.2 → 1.0.0

package/README.md

@@ -2,25 +2,18 @@
 
 A zero-dependency CLI tool that automates version bumping and changelog generation for Bun workspace monorepos and single packages.
 
-It reads git commit messages since the last tag, categorizes them by type prefix (`[feat]`, `[fix]`, `[test]`), bumps semantic versions, updates `CHANGELOG.md` per package, and optionally commits and tags the result.
+It reads git commit messages since the last tag, categorizes them by type prefix (`feat:`, `fix:`, `test:`), bumps semantic versions, updates `CHANGELOG.md` per package, and optionally commits and tags the result.
 
 ## Install
 
 ```bash
-bun install
+bun add bunset
 ```
 
 ## Usage
 
 ```bash
-bun src/index.ts [options]
-```
-
-Or link it globally:
-
-```bash
-bun link
-bunset [options]
+bunx bunset [options]
 ```
 
 ### Options
@@ -33,11 +26,12 @@ bunset [options]
 | `--all` | Update all workspace packages |
 | `--changed` | Update only changed packages (default for workspaces) |
 | `--no-commit` | Do not commit changes to git (commits by default) |
-| `--tag` | Tag the commit with new version (default) |
+| `--no-tag` | Tag the commit with new version (default) |
 | `--per-package-tags` | Use `pkg@1.2.3` tags instead of prefixed tags |
-| `--tag-prefix` | Tag prefix (default: `v`, e.g. `v1.2.3`) |
+| `--tag-prefix` | Tag prefix (auto-detected from last tag, or `v` if no tags) |
 | `--sections` | Comma-separated changelog sections (default: `feat,fix,perf`) |
 | `--dry-run` | Preview changes without writing files, committing, or tagging |
+| `--debug` | Show detailed inclusion/exclusion reasoning (implies `--dry-run`) |
 | `--no-filter-by-package` | Include all commits in every package changelog (monorepo) |
 
 When bump type or scope flags are omitted, interactive prompts will ask.
@@ -71,7 +65,22 @@ All these styles work:
 
 An optional scope groups commits under a `#### scope` sub-heading within their type section in the changelog.
 
-Recognized type keywords:
+#### Breaking Changes
+
+Append `!` before the colon (or closing bracket) to mark a commit as a breaking change, per [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/):
+
+```
+feat!: Remove old API
+feat(auth)!: Change token format
+[feat!] Remove old API
+```
+
+A `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer in the commit body is also detected.
+
+Breaking commits are collected into a **Breaking Changes** section at the top of each changelog entry, regardless of which `--sections` are configured. If breaking changes are detected and the bump type is not `major`, a warning is printed.
+
+#### Recognized Type Keywords
+
 - `feat`, `feature` — listed under **Features**
 - `fix`, `bug`, `bugfix` — listed under **Bug Fixes**
 - `refactor` — listed under **Refactors**
@@ -82,26 +91,39 @@ Recognized type keywords:
 - `build` — listed under **Build**
 - `ops` — listed under **Ops**
 - `chore` — listed under **Chores**
+- `ci` — listed under **CI**
 
 Only sections listed in `--sections` (or the `sections` config option) appear in the changelog. The default is `feat,fix,perf`.
 
 ### Config File
 
-Place a `.bunset.toml` in your project root to set persistent defaults so you don't have to pass the same flags every time:
+Place a `.bunset.toml` in your project root to set persistent defaults so you don't have to pass the same flags every time. All fields are optional. CLI flags always take priority over config values.
 
 ```toml
-bump = "patch"                              # "patch" | "minor" | "major"
-scope = "changed"                           # "all" | "changed"
-commit = true
-tag = true
-per-package-tags = false
-sections = ["feat", "fix", "perf"]          # changelog sections and order
-dry-run = false                             # preview without writing
-filter-by-package = true                    # per-package commit filtering (monorepo)
-tag-prefix = "v"                            # prefix for version tags
+bump = "patch"                          # "patch" | "minor" | "major"
+scope = "changed"                       # "all" | "changed"
+commit = true                           # auto-commit (default: true)
+tag = true                              # create git tags (default: true)
+per-package-tags = false                # pkg@version tags (monorepo)
+tag-prefix = "v"                        # tag prefix (default: auto-detect)
+sections = ["feat", "fix", "perf"]      # changelog sections and order
+dry-run = false                         # preview without writing
+debug = false                           # detailed reasoning (implies dry-run)
+filter-by-package = true                # per-package filtering (monorepo)
 ```
 
-All fields are optional. CLI flags always take priority over config values. If `bump` or `scope` is set in config, the interactive prompt for that option is skipped.
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `bump` | `string` | _(prompt)_ | Version bump type: `"patch"`, `"minor"`, or `"major"`. Skips the interactive prompt when set. |
+| `scope` | `string` | _(prompt)_ | Package scope: `"all"` or `"changed"`. Skips the interactive prompt when set (monorepo only). |
+| `commit` | `boolean` | `true` | Whether to auto-commit the version bump and changelog changes. |
+| `tag` | `boolean` | `true` | Whether to create git tags for released versions. |
+| `per-package-tags` | `boolean` | `false` | Use `pkg@1.2.3` tags instead of prefixed tags. In a monorepo, packages with no matching commits are skipped entirely. |
+| `tag-prefix` | `string` | _(auto)_ | Prefix for version tags. Auto-detected from the last git tag when not set (falls back to `"v"` if no tags exist). Set to `""` for bare version numbers, or e.g. `"project-v"` for `project-v1.2.3`. |
+| `sections` | `string[]` | `["feat", "fix", "perf"]` | Which commit types to include in the changelog and in what order. Accepts any recognized type keyword. |
+| `dry-run` | `boolean` | `false` | Preview all changes without writing files, committing, or tagging. |
+| `debug` | `boolean` | `false` | Show detailed inclusion/exclusion reasoning. Implies `dry-run`. |
+| `filter-by-package` | `boolean` | `true` | In a monorepo, only include commits that touched files within each package. Disable with `false` to include all commits in every changelog. |
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunset",
-  "version": "0.0.2",
+  "version": "1.0.0",
   "module": "src/index.ts",
   "type": "module",
   "bin": {

package/src/changelog.test.ts

@@ -18,6 +18,7 @@ function emptyGroups(): GroupedCommits {
     build: [],
     ops: [],
     chore: [],
+    ci: [],
   };
 }
 
@@ -26,13 +27,13 @@ describe("buildChangelogEntry", () => {
     const groups: GroupedCommits = {
       ...emptyGroups(),
       feature: [
-        { hash: "a", message: "", type: "feature", commitScope: null, files: [], description: "Add login" },
+        { hash: "a", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "Add login" },
       ],
       bugfix: [
-        { hash: "b", message: "", type: "bugfix", commitScope: null, files: [], description: "Fix crash" },
+        { hash: "b", message: "", type: "bugfix", commitScope: null, breaking: false, files: [], description: "Fix crash" },
       ],
       test: [
-        { hash: "c", message: "", type: "test", commitScope: null, files: [], description: "Add tests" },
+        { hash: "c", message: "", type: "test", commitScope: null, breaking: false, files: [], description: "Add tests" },
       ],
     };
     const entry = buildChangelogEntry("1.2.0", groups, [], COMMIT_TYPES);
@@ -49,10 +50,10 @@ describe("buildChangelogEntry", () => {
     const groups: GroupedCommits = {
       ...emptyGroups(),
       feature: [
-        { hash: "a", message: "", type: "feature", commitScope: null, files: [], description: "New thing" },
+        { hash: "a", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "New thing" },
       ],
       test: [
-        { hash: "b", message: "", type: "test", commitScope: null, files: [], description: "Add tests" },
+        { hash: "b", message: "", type: "test", commitScope: null, breaking: false, files: [], description: "Add tests" },
       ],
     };
     const entry = buildChangelogEntry("1.0.0", groups);
@@ -64,7 +65,7 @@ describe("buildChangelogEntry", () => {
     const groups: GroupedCommits = {
       ...emptyGroups(),
       feature: [
-        { hash: "a", message: "", type: "feature", commitScope: null, files: [], description: "New thing" },
+        { hash: "a", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "New thing" },
       ],
     };
     const entry = buildChangelogEntry("1.0.0", groups);
@@ -77,10 +78,10 @@ describe("buildChangelogEntry", () => {
     const groups: GroupedCommits = {
       ...emptyGroups(),
       feature: [
-        { hash: "a", message: "", type: "feature", commitScope: null, files: [], description: "Global feature" },
-        { hash: "b", message: "", type: "feature", commitScope: "auth", files: [], description: "Add login" },
-        { hash: "c", message: "", type: "feature", commitScope: "auth", files: [], description: "Add logout" },
-        { hash: "d", message: "", type: "feature", commitScope: "ui", files: [], description: "New dashboard" },
+        { hash: "a", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "Global feature" },
+        { hash: "b", message: "", type: "feature", commitScope: "auth", breaking: false, files: [], description: "Add login" },
+        { hash: "c", message: "", type: "feature", commitScope: "auth", breaking: false, files: [], description: "Add logout" },
+        { hash: "d", message: "", type: "feature", commitScope: "ui", breaking: false, files: [], description: "New dashboard" },
       ],
     };
     const entry = buildChangelogEntry("1.0.0", groups);
@@ -102,7 +103,7 @@ describe("buildChangelogEntry", () => {
     const groups: GroupedCommits = {
       ...emptyGroups(),
       bugfix: [
-        { hash: "a", message: "", type: "bugfix", commitScope: "parser", files: [], description: "Fix edge case" },
+        { hash: "a", message: "", type: "bugfix", commitScope: "parser", breaking: false, files: [], description: "Fix edge case" },
       ],
     };
     const entry = buildChangelogEntry("1.0.0", groups);
@@ -118,6 +119,57 @@ describe("buildChangelogEntry", () => {
     expect(entry).toContain("### Updated Dependencies");
     expect(entry).toContain("- `lodash`: 4.18.0");
   });
+
+  test("renders Breaking Changes section first when breaking commits exist", () => {
+    const groups: GroupedCommits = {
+      ...emptyGroups(),
+      feature: [
+        { hash: "a", message: "", type: "feature", commitScope: null, breaking: true, files: [], description: "Remove old API" },
+        { hash: "b", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "Add new API" },
+      ],
+      bugfix: [
+        { hash: "c", message: "", type: "bugfix", commitScope: "parser", breaking: true, files: [], description: "Change return type" },
+      ],
+    };
+    const entry = buildChangelogEntry("2.0.0", groups, [], ["feature", "bugfix"]);
+    expect(entry).toContain("### Breaking Changes");
+    expect(entry).toContain("- **features**: Remove old API");
+    expect(entry).toContain("- **bug fixes(parser)**: Change return type");
+
+    // Breaking Changes section appears before Features
+    const breakingIdx = entry.indexOf("### Breaking Changes");
+    const featuresIdx = entry.indexOf("### Features");
+    expect(breakingIdx).toBeLessThan(featuresIdx);
+  });
+
+  test("breaking section appears even when commit type is not in sections", () => {
+    const groups: GroupedCommits = {
+      ...emptyGroups(),
+      chore: [
+        { hash: "a", message: "", type: "chore", commitScope: null, breaking: true, files: [], description: "Drop Node 14 support" },
+      ],
+      feature: [
+        { hash: "b", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "Add feature" },
+      ],
+    };
+    // sections only includes "feature", not "chore"
+    const entry = buildChangelogEntry("3.0.0", groups, [], ["feature"]);
+    expect(entry).toContain("### Breaking Changes");
+    expect(entry).toContain("- **chores**: Drop Node 14 support");
+    // Chore section itself should not appear
+    expect(entry).not.toContain("### Chores");
+  });
+
+  test("no Breaking Changes section when no breaking commits", () => {
+    const groups: GroupedCommits = {
+      ...emptyGroups(),
+      feature: [
+        { hash: "a", message: "", type: "feature", commitScope: null, breaking: false, files: [], description: "Add feature" },
+      ],
+    };
+    const entry = buildChangelogEntry("1.1.0", groups);
+    expect(entry).not.toContain("### Breaking Changes");
+  });
 });
 
 describe("writeChangelog", () => {

package/src/changelog.ts

@@ -12,6 +12,7 @@ const SECTION_HEADINGS: Record<CommitType, string> = {
   build: "Build",
   ops: "Ops",
   chore: "Chores",
+  ci: "CI",
 };
 
 export function buildChangelogEntry(
@@ -22,6 +23,20 @@ export function buildChangelogEntry(
 ): string {
   const lines: string[] = [`## ${version}`, ""];
 
+  // Collect breaking changes across all types
+  const breakingCommits = Object.values(groups).flat().filter((c) => c.breaking);
+  if (breakingCommits.length > 0) {
+    lines.push("### Breaking Changes", "");
+    for (const c of breakingCommits) {
+      const typeLabel = c.type ? SECTION_HEADINGS[c.type].toLowerCase() : "unknown";
+      const prefix = c.commitScope
+        ? `**${typeLabel}(${c.commitScope})**`
+        : `**${typeLabel}**`;
+      lines.push(`- ${prefix}: ${c.description}`);
+    }
+    lines.push("");
+  }
+
   for (const type of sections) {
     const commits = groups[type];
     if (commits.length === 0) continue;

package/src/cli.ts

@@ -16,9 +16,10 @@ Options:
   --no-commit          Do not commit the version bump and changelog
   --no-tag             Do not create git tags for released versions
   --per-package-tags   Use package-scoped tags (pkg@version) instead of prefixed
-  --tag-prefix <str>   Tag prefix (default: "v", e.g. v1.2.3)
+  --tag-prefix <str>   Tag prefix (auto-detected from last tag, or "v" if no tags)
   --sections <list>    Comma-separated changelog sections (default: feat,fix,perf)
   --dry-run            Preview changes without writing files, committing, or tagging
+  --debug              Show detailed inclusion/exclusion reasoning (implies --dry-run)
   --no-filter-by-package
                        Include all commits in every package changelog (monorepo)
   --help, -h           Show this help message
@@ -36,6 +37,15 @@ Commit format:
 
   An optional scope groups commits under a sub-heading in the changelog.
 
+  Breaking changes (Conventional Commits 1.0.0):
+    Append ! before the colon to mark a breaking change:
+      feat!: Remove old API
+      feat(auth)!: Change token format
+      [feat!] Remove old API
+    Or include a "BREAKING CHANGE:" footer in the commit body.
+    Breaking commits are collected into a "Breaking Changes" section at the
+    top of the changelog entry. A warning is printed if the bump is not major.
+
   Recognized type keywords:
     feat, feature          → Features
     fix, bug, bugfix       → Bug Fixes
@@ -47,12 +57,25 @@ Commit format:
     build                  → Build
     ops                    → Ops
     chore                  → Chores
+    ci                     → CI
   Only sections listed in --sections (or config) are included in the changelog.
   Default sections: feat, fix, perf.
 
-Config:
+Config file (.bunset.toml):
   Place a .bunset.toml in your project root to set persistent defaults.
-  CLI flags always override config values. See README for format.`);
+  All fields are optional. CLI flags always override config values.
+
+  Example:
+    bump = "patch"                          # "patch" | "minor" | "major"
+    scope = "changed"                       # "all" | "changed"
+    commit = true                           # auto-commit (default: true)
+    tag = true                              # create git tags (default: true)
+    per-package-tags = false                # pkg@version tags (monorepo)
+    tag-prefix = "v"                        # tag prefix (default: auto-detect)
+    sections = ["feat", "fix", "perf"]      # changelog sections and order
+    dry-run = false                         # preview without writing
+    debug = false                           # detailed reasoning (implies dry-run)
+    filter-by-package = true                # per-package filtering (monorepo)`);
 }
 
 export function resolveOptions(
@@ -74,6 +97,7 @@ export function resolveOptions(
       "dry-run": { type: "boolean", default: false },
       "filter-by-package": { type: "boolean", default: true },
       "tag-prefix": { type: "string" },
+      debug: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
     },
     strict: true,
@@ -100,7 +124,8 @@ export function resolveOptions(
     ?? config.sections
     ?? DEFAULT_SECTIONS;
 
-  const dryRun = values["dry-run"] ? true : (config.dryRun ?? false);
+  const debug = values.debug ? true : (config.debug ?? false);
+  const dryRun = debug || values["dry-run"] ? true : (config.dryRun ?? false);
 
   const filterByPackage = values["filter-by-package"] === false
     ? false
@@ -108,14 +133,14 @@ export function resolveOptions(
 
   const tagPrefix = values["tag-prefix"] as string | undefined
     ?? config.tagPrefix
-    ?? "v";
+    ?? null;
 
   if (bump && scope) {
-    return { scope, bump, commit, tag, perPackageTags, sections, dryRun, filterByPackage, tagPrefix };
+    return { scope, bump, commit, tag, perPackageTags, sections, dryRun, filterByPackage, tagPrefix, debug };
   }
 
   return promptForMissing(
-    { commit, tag, perPackageTags, sections, dryRun, filterByPackage, tagPrefix },
+    { commit, tag, perPackageTags, sections, dryRun, filterByPackage, tagPrefix, debug },
     bump,
     scope,
     isWs,
@@ -156,7 +181,8 @@ interface MergedDefaults {
   sections: CommitType[];
   dryRun: boolean;
   filterByPackage: boolean;
-  tagPrefix: string;
+  tagPrefix: string | null;
+  debug: boolean;
 }
 
 async function promptForMissing(

package/src/commits.test.ts

@@ -8,6 +8,7 @@ describe("parseCommit", () => {
     const result = parseCommit("abc123", "[feat] Add user auth");
     expect(result.type).toBe("feature");
     expect(result.commitScope).toBeNull();
+    expect(result.breaking).toBe(false);
     expect(result.files).toEqual([]);
     expect(result.description).toBe("Add user auth");
   });
@@ -204,18 +205,94 @@ describe("parseCommit", () => {
     const result = parseCommit("vwx234", "[feat No closing bracket");
     expect(result.type).toBeNull();
   });
+
+  // Breaking change `!` marker
+  test("parses feat!: as breaking", () => {
+    const result = parseCommit("brk1", "feat!: breaking change");
+    expect(result.type).toBe("feature");
+    expect(result.breaking).toBe(true);
+    expect(result.description).toBe("breaking change");
+  });
+
+  test("parses feat(auth)!: as breaking with scope", () => {
+    const result = parseCommit("brk2", "feat(auth)!: breaking");
+    expect(result.type).toBe("feature");
+    expect(result.commitScope).toBe("auth");
+    expect(result.breaking).toBe(true);
+    expect(result.description).toBe("breaking");
+  });
+
+  test("parses [feat!] as breaking", () => {
+    const result = parseCommit("brk3", "[feat!] breaking");
+    expect(result.type).toBe("feature");
+    expect(result.breaking).toBe(true);
+    expect(result.description).toBe("breaking");
+  });
+
+  test("parses [feat(auth)!]: as breaking with scope", () => {
+    const result = parseCommit("brk4", "[feat(auth)!]: breaking");
+    expect(result.type).toBe("feature");
+    expect(result.commitScope).toBe("auth");
+    expect(result.breaking).toBe(true);
+    expect(result.description).toBe("breaking");
+  });
+
+  test("parses [feat(auth)!] as breaking with scope and no colon", () => {
+    const result = parseCommit("brk4b", "[feat(auth)!] breaking");
+    expect(result.type).toBe("feature");
+    expect(result.commitScope).toBe("auth");
+    expect(result.breaking).toBe(true);
+    expect(result.description).toBe("breaking");
+  });
+
+  test("parses fix!: as breaking", () => {
+    const result = parseCommit("brk5", "fix!: desc");
+    expect(result.type).toBe("bugfix");
+    expect(result.breaking).toBe(true);
+  });
+
+  // BREAKING CHANGE footer in body
+  test("detects BREAKING CHANGE: in body", () => {
+    const result = parseCommit("brk6", "feat: add feature", "BREAKING CHANGE: old API removed");
+    expect(result.type).toBe("feature");
+    expect(result.breaking).toBe(true);
+  });
+
+  test("detects BREAKING-CHANGE: in body", () => {
+    const result = parseCommit("brk7", "feat: add feature", "BREAKING-CHANGE: old API removed");
+    expect(result.type).toBe("feature");
+    expect(result.breaking).toBe(true);
+  });
+
+  test("body without breaking footer is not breaking", () => {
+    const result = parseCommit("brk8", "feat: add feature", "Just some extra details");
+    expect(result.breaking).toBe(false);
+  });
+
+  // ci type
+  test("parses ci: commit", () => {
+    const result = parseCommit("ci1", "ci: setup pipeline");
+    expect(result.type).toBe("ci");
+    expect(result.description).toBe("setup pipeline");
+  });
+
+  test("parses [ci] commit", () => {
+    const result = parseCommit("ci2", "[ci] Add GitHub Actions");
+    expect(result.type).toBe("ci");
+    expect(result.description).toBe("Add GitHub Actions");
+  });
 });
 
 describe("groupCommits", () => {
   test("groups commits by type", () => {
     const commits: ParsedCommit[] = [
-      { hash: "a", message: "", type: "feature", commitScope: null, description: "F1", files: [] },
-      { hash: "b", message: "", type: "bugfix", commitScope: null, description: "B1", files: [] },
-      { hash: "c", message: "", type: "test", commitScope: null, description: "T1", files: [] },
-      { hash: "d", message: "", type: "feature", commitScope: "auth", description: "F2", files: [] },
-      { hash: "e", message: "", type: "refactor", commitScope: null, description: "R1", files: [] },
-      { hash: "f", message: "", type: "chore", commitScope: null, description: "C1", files: [] },
-      { hash: "g", message: "", type: null, commitScope: null, description: "Ignored", files: [] },
+      { hash: "a", message: "", type: "feature", commitScope: null, description: "F1", breaking: false, files: [] },
+      { hash: "b", message: "", type: "bugfix", commitScope: null, description: "B1", breaking: false, files: [] },
+      { hash: "c", message: "", type: "test", commitScope: null, description: "T1", breaking: false, files: [] },
+      { hash: "d", message: "", type: "feature", commitScope: "auth", description: "F2", breaking: false, files: [] },
+      { hash: "e", message: "", type: "refactor", commitScope: null, description: "R1", breaking: false, files: [] },
+      { hash: "f", message: "", type: "chore", commitScope: null, description: "C1", breaking: false, files: [] },
+      { hash: "g", message: "", type: null, commitScope: null, description: "Ignored", breaking: false, files: [] },
     ];
     const groups = groupCommits(commits);
     expect(groups.feature).toHaveLength(2);
@@ -237,10 +314,10 @@ describe("groupCommits", () => {
 
 describe("filterCommitsForPackage", () => {
   const commits: ParsedCommit[] = [
-    { hash: "a", message: "", type: "feature", commitScope: null, description: "A feat", files: ["packages/a/src/index.ts"] },
-    { hash: "b", message: "", type: "bugfix", commitScope: null, description: "B fix", files: ["packages/b/src/main.ts"] },
-    { hash: "c", message: "", type: "feature", commitScope: null, description: "Both", files: ["packages/a/lib/x.ts", "packages/b/lib/y.ts"] },
-    { hash: "d", message: "", type: "feature", commitScope: null, description: "No files", files: [] },
+    { hash: "a", message: "", type: "feature", commitScope: null, description: "A feat", breaking: false, files: ["packages/a/src/index.ts"] },
+    { hash: "b", message: "", type: "bugfix", commitScope: null, description: "B fix", breaking: false, files: ["packages/b/src/main.ts"] },
+    { hash: "c", message: "", type: "feature", commitScope: null, description: "Both", breaking: false, files: ["packages/a/lib/x.ts", "packages/b/lib/y.ts"] },
+    { hash: "d", message: "", type: "feature", commitScope: null, description: "No files", breaking: false, files: [] },
   ];
 
   test("filters commits to only those touching the package", () => {
@@ -257,7 +334,7 @@ describe("filterCommitsForPackage", () => {
 
   test("includes commits with no files (fallback)", () => {
     const noFileCommits: ParsedCommit[] = [
-      { hash: "x", message: "", type: "feature", commitScope: null, description: "X", files: [] },
+      { hash: "x", message: "", type: "feature", commitScope: null, description: "X", breaking: false, files: [] },
     ];
     const filtered = filterCommitsForPackage(noFileCommits, "/root/packages/a", "/root");
     expect(filtered).toHaveLength(1);

package/src/commits.ts

@@ -16,6 +16,7 @@ const TYPE_MAP: Record<string, CommitType> = {
   build: "build",
   ops: "ops",
   chore: "chore",
+  ci: "ci",
 };
 
 export const COMMIT_TYPES: CommitType[] = [
@@ -29,34 +30,57 @@ export const COMMIT_TYPES: CommitType[] = [
   "build",
   "ops",
   "chore",
+  "ci",
 ];
 
 export function normalizeType(keyword: string): CommitType | null {
   return TYPE_MAP[keyword.toLowerCase()] ?? null;
 }
 
-// Matches: [type(scope)] desc, [type]: desc, type(scope): desc, type: desc
-const COMMIT_PATTERN = /^\[([^\]]+)\]:?\s*(.*)$|^(\w+(?:\([^)]*\))?):\s+(.*)$/;
+// Matches: [type(scope)!] desc, [type]: desc, type(scope)!: desc, type: desc
+const COMMIT_PATTERN = /^\[([^\]]+)\]:?\s*(.*)$|^(\w+(?:\([^)]*\))?!?):\s+(.*)$/;
 const SCOPE_PATTERN = /^(\w+)\(([^)]*)\)$/;
 
-export function parseCommit(hash: string, message: string): ParsedCommit {
+const BREAKING_FOOTER_PATTERN = /^BREAKING[ -]CHANGE:\s/m;
+
+export function parseCommit(hash: string, message: string, body?: string): ParsedCommit {
   const trimmed = message.trim();
   const match = COMMIT_PATTERN.exec(trimmed);
 
   if (!match) {
-    return { hash, message: trimmed, type: null, commitScope: null, description: trimmed, files: [] };
+    return { hash, message: trimmed, type: null, commitScope: null, description: trimmed, breaking: false, files: [] };
   }
 
-  const raw = (match[1] ?? match[3])!.trim();
+  let raw = (match[1] ?? match[3])!.trim();
   const description = (match[2] ?? match[4])!.trim();
 
+  // Detect trailing `!` breaking marker
+  let breaking = false;
+  if (raw.endsWith("!")) {
+    breaking = true;
+    raw = raw.slice(0, -1);
+  }
+
   const scopeMatch = SCOPE_PATTERN.exec(raw);
-  const keyword = scopeMatch ? scopeMatch[1]! : raw;
-  const commitScope = scopeMatch ? scopeMatch[2]!.trim() : null;
+  let keyword: string;
+  let commitScope: string | null;
+
+  if (scopeMatch) {
+    keyword = scopeMatch[1]!;
+    commitScope = scopeMatch[2]!.trim();
+  } else {
+    keyword = raw;
+    commitScope = null;
+  }
 
   const type = TYPE_MAP[keyword.toLowerCase()] ?? null;
 
-  return { hash, message: trimmed, type, commitScope, description, files: [] };
+  // Scan body for BREAKING CHANGE footer
+  if (!breaking && body && BREAKING_FOOTER_PATTERN.test(body)) {
+    breaking = true;
+  }
+
+  return { hash, message: trimmed, type, commitScope, description, breaking, files: [] };
 }
 
 export function filterCommitsForPackage(

package/src/config.ts

@@ -49,6 +49,10 @@ export async function loadConfig(
     config.tagPrefix = raw["tag-prefix"];
   }
 
+  if (typeof raw.debug === "boolean") {
+    config.debug = raw.debug;
+  }
+
   if (Array.isArray(raw.sections)) {
     const sections: CommitType[] = [];
     for (const s of raw.sections) {

package/src/git.ts

@@ -12,24 +12,31 @@ export async function getLastTag(cwd: string): Promise<string | null> {
 export async function getCommitsSince(
   cwd: string,
   sinceRef: string | null,
-): Promise<{ hash: string; message: string }[]> {
+): Promise<{ hash: string; message: string; body: string }[]> {
+  const fmt = "%x00%H%x00%s%x00%b";
   let result;
   if (sinceRef) {
     result =
-      await $`git -C ${cwd} log ${sinceRef}..HEAD --pretty=format:%H%n%s --no-merges`.quiet();
+      await $`git -C ${cwd} log ${sinceRef}..HEAD --pretty=format:${fmt} --no-merges`.quiet();
   } else {
     result =
-      await $`git -C ${cwd} log --pretty=format:%H%n%s --no-merges`.quiet();
+      await $`git -C ${cwd} log --pretty=format:${fmt} --no-merges`.quiet();
   }
 
   const text = result.text().trim();
   if (!text) return [];
 
-  const lines = text.split("\n");
-  const commits: { hash: string; message: string }[] = [];
+  const commits: { hash: string; message: string; body: string }[] = [];
+  // Split on the leading \x00 that starts each record
+  const records = text.split("\x00");
 
-  for (let i = 0; i < lines.length - 1; i += 2) {
-    commits.push({ hash: lines[i]!, message: lines[i + 1]! });
+  // records[0] is empty (before the first \x00), then groups of 3: hash, subject, body
+  for (let i = 1; i + 2 < records.length; i += 3) {
+    commits.push({
+      hash: records[i]!.trim(),
+      message: records[i + 1]!.trim(),
+      body: records[i + 2]!.trim(),
+    });
   }
 
   return commits;

package/src/index.ts

@@ -29,25 +29,87 @@ const isWs = await isWorkspace(cwd);
 const config = await loadConfig(cwd);
 const options = await resolveOptions(isWs, config);
 
+const dbg = options.debug;
+function debug(msg: string): void {
+  if (dbg) console.log(`[debug] ${msg}`);
+}
+
+if (dbg) {
+  console.log("--- Debug Mode (dry-run implied) ---\n");
+  debug(`cwd: ${cwd}`);
+  debug(`workspace: ${isWs}`);
+  debug(`config loaded: ${JSON.stringify(config)}`);
+  debug(`resolved options: ${JSON.stringify(options)}`);
+  console.log("");
+}
+
 const allPackages = await getAllPackages(cwd);
 const lastTag = await getLastTag(cwd);
 const rawCommits = await getCommitsSince(cwd, lastTag);
 
+// Resolve tagPrefix: explicit value wins, otherwise infer from last tag
+let tagPrefix: string;
+if (options.tagPrefix !== null) {
+  tagPrefix = options.tagPrefix;
+  debug(`tag prefix explicit: "${tagPrefix}"`);
+} else if (lastTag) {
+  const semverMatch = lastTag.match(/\d+\.\d+\.\d+/);
+  tagPrefix = semverMatch ? lastTag.slice(0, semverMatch.index) : "v";
+  debug(`tag prefix auto-detected: "${tagPrefix}" (from tag: ${lastTag})`);
+} else {
+  tagPrefix = "v";
+  debug(`tag prefix default: "${tagPrefix}" (no previous tags found)`);
+}
+
+debug(`last tag: ${lastTag ?? "(none)"}`);
+debug(`raw commits since tag: ${rawCommits.length}`);
+
 if (rawCommits.length === 0) {
   console.log("No commits found since last tag. Nothing to do.");
   process.exit(0);
 }
 
-const parsed = rawCommits.map((c) => parseCommit(c.hash, c.message));
+const parsed = rawCommits.map((c) => parseCommit(c.hash, c.message, c.body));
+
+if (dbg) {
+  console.log("");
+  debug("--- Parsed commits ---");
+  for (const c of parsed) {
+    const typeStr = c.type ?? "UNRECOGNIZED";
+    const scopeStr = c.commitScope ? `(${c.commitScope})` : "";
+    const included = c.type && options.sections.includes(c.type) ? "INCLUDED" : "EXCLUDED";
+    debug(`  ${c.hash.slice(0, 7)} ${typeStr}${scopeStr}: ${c.description} → ${included} (section: ${c.type ?? "none"})`);
+  }
+  console.log("");
+}
+
+// Warn if breaking changes detected with non-major bump
+const hasBreaking = parsed.some((c) => c.breaking);
+if (hasBreaking && options.bump !== "major") {
+  console.log(`\u26a0 Breaking changes detected but bump is "${options.bump}" (not "major").`);
+  if (dbg) {
+    for (const c of parsed.filter((c) => c.breaking)) {
+      debug(`  breaking: ${c.hash.slice(0, 7)} ${c.message}`);
+    }
+  }
+  console.log("");
+}
 
 // In a monorepo with filtering, fetch the file list for each commit
 const shouldFilter = isWs && options.filterByPackage;
+debug(`per-package filtering: ${shouldFilter ? "enabled" : "disabled"}`);
 if (shouldFilter) {
   await Promise.all(
     parsed.map(async (commit) => {
       commit.files = await getCommitFiles(cwd, commit.hash);
     }),
   );
+  if (dbg) {
+    for (const c of parsed) {
+      debug(`  ${c.hash.slice(0, 7)} files: ${c.files.length > 0 ? c.files.join(", ") : "(none)"}`);
+    }
+    console.log("");
+  }
 }
 
 const globalGroups = groupCommits(parsed);
@@ -62,6 +124,8 @@ let packages =
     ? await getChangedPackages(cwd, allPackages, lastTag)
     : allPackages;
 
+debug(`scope: ${options.scope}, packages to process: ${packages.map((p) => p.name).join(", ") || "(none)"}`);
+
 if (packages.length === 0) {
   console.log("No changed packages found. Nothing to do.");
   process.exit(0);
@@ -81,7 +145,7 @@ function packageHasChanges(groups: GroupedCommits): boolean {
 }
 
 if (options.dryRun) {
-  console.log("--- Dry Run ---\n");
+  if (!dbg) console.log("--- Dry Run ---\n");
 
   const tags: string[] = [];
 
@@ -89,6 +153,24 @@ if (options.dryRun) {
     const groups = getPackageGroups(pkg, parsed);
     const hasChanges = packageHasChanges(groups);
 
+    if (dbg) {
+      debug(`--- Package: ${pkg.name} ---`);
+      debug(`  path: ${pkg.path}`);
+      debug(`  current version: ${pkg.version ?? "0.0.0"}`);
+      for (const section of options.sections) {
+        const commits = groups[section];
+        if (commits.length > 0) {
+          debug(`  ${section}: ${commits.length} commit(s)`);
+          for (const c of commits) {
+            debug(`    - ${c.hash.slice(0, 7)} ${c.description}${c.commitScope ? ` (scope: ${c.commitScope})` : ""}`);
+          }
+        } else {
+          debug(`  ${section}: 0 commits`);
+        }
+      }
+      debug(`  has matching commits: ${hasChanges}`);
+    }
+
     if (!hasChanges && options.perPackageTags) {
       console.log(`${pkg.name}: no matching commits, skipping.`);
       continue;
@@ -117,7 +199,7 @@ if (options.dryRun) {
       if (options.perPackageTags) {
         tags.push(`${pkg.name}@${newVersion}`);
       } else {
-        tags.push(`${options.tagPrefix}${newVersion}`);
+        tags.push(`${tagPrefix}${newVersion}`);
       }
     }
   }
@@ -177,7 +259,7 @@ for (const pkg of packages) {
     if (options.perPackageTags) {
       tags.push(`${pkg.name}@${newVersion}`);
     } else {
-      tags.push(`${options.tagPrefix}${newVersion}`);
+      tags.push(`${tagPrefix}${newVersion}`);
     }
   }
 }

package/src/types.ts

@@ -10,7 +10,8 @@ export type CommitType =
   | "docs"
   | "build"
   | "ops"
-  | "chore";
+  | "chore"
+  | "ci";
 
 export interface CliOptions {
   scope: PackageScope;
@@ -21,7 +22,8 @@ export interface CliOptions {
   sections: CommitType[];
   dryRun: boolean;
   filterByPackage: boolean;
-  tagPrefix: string;
+  tagPrefix: string | null;
+  debug: boolean;
 }
 
 export interface ParsedCommit {
@@ -30,6 +32,7 @@ export interface ParsedCommit {
   type: CommitType | null;
   commitScope: string | null;
   description: string;
+  breaking: boolean;
   files: string[];
 }