@webywz/vibe-commit 0.1.4 → 0.1.5

package/README.md

@@ -56,16 +56,15 @@ vibe-commit install                 # optional prepare-commit-msg hook
 | `--vibe <style>` | `playful` \| `pro` \| `terse` (default: `pro`) |
 | `--no-ai` | Skip the API even if `OPENAI_API_KEY` is set · 即使有 Key 也不走 AI |
 | `--breaking` | Force breaking change (`!` + `BREAKING CHANGE:` footer) · 强制破坏性变更（`!` + footer） |
-
-Offline heuristic also marks breaking when the staged diff removes public `export`s or bumps a `package.json` major version, and always attaches a `BREAKING CHANGE:` footer when `breaking` is true (so `--json` body matches the formatted message).
-
-离线启发式在删掉公开 `export`、或 `package.json` 主版本升级时也会标 breaking；只要 `breaking` 为真就会补上 `BREAKING CHANGE:` footer（`--json` 的 body 与格式化输出一致）。
-
 | `--json` | Machine-readable proposal · 机器可读提案 |
 | `install [--path]` | Install the prepare-commit-msg hook · 安装钩子 |
 | `uninstall [--path]` | Remove the managed hook · 卸载钩子 |
 | `-h` / `-v` | Help / version · 帮助 / 版本 |
 
+Offline heuristic also marks breaking when the staged diff removes public `export`s or bumps a `package.json` major version, and always attaches a `BREAKING CHANGE:` footer when `breaking` is true (so `--json` body matches the formatted message). Dry-run prints a one-line cause; `--json` may include `breakingReason`.
+
+离线启发式在删掉公开 `export`、或 `package.json` 主版本升级时也会标 breaking；只要 `breaking` 为真就会补上 `BREAKING CHANGE:` footer（`--json` 的 body 与格式化输出一致）。干跑会打一行原因；`--json` 可带 `breakingReason`。
+
 **Vibes** · 语气
 
 - **pro** — default. Imperative, review-ready. · 默认：祈使句，可进 review。
@@ -147,7 +146,9 @@ console.log(formatCommit(message));
    - new files / `export function` → `feat`
 3. Optional AI draft with automatic heuristic fallback.
    可选 AI 草稿，失败自动回退启发式。
-4. Managed `prepare-commit-msg` hook via `install` / `uninstall`.
+4. **Breaking** when the diff removes a public `export`, bumps a `package.json` major, adds a `BREAKING CHANGE:` footer, or you pass `--breaking`. Dry-run shows why; `--json` may include `breakingReason`.
+   **破坏性变更**：删公开 `export`、主版本升级、diff 里已有 footer，或传 `--breaking`。干跑说明原因；`--json` 可带 `breakingReason`。
+5. Managed `prepare-commit-msg` hook via `install` / `uninstall`.
    通过 `install` / `uninstall` 管理 `prepare-commit-msg` 钩子。
 
 ---

package/dist/git.js

@@ -13,7 +13,8 @@ export function inspectStaged(cwd = process.cwd()) {
     const raw = git(["diff", "--cached", "-M", "--unified=3"], cwd);
     const diff = assembleDiff(nameStatus, numstat, raw);
     if (diff.files.length === 0) {
-        throw new GitError("No staged changes. Stage files first: git add -p  (or git add <path>)");
+        throw new GitError("No staged changes. Stage files first: git add -p (or git add <path>)\n" +
+            "暂存区为空。请先暂存：git add -p（或 git add <path>）");
     }
     return diff;
 }

package/dist/heuristic.d.ts

@@ -13,9 +13,14 @@ export declare function primaryRole(path: string): CommitType;
 export declare function classifyPath(path: string): CommitType[];
 export declare function inferScope(files: StagedFile[]): string | undefined;
 export declare function inferSubject(diff: StagedDiff, type: CommitType, scope?: string): string;
+export type BreakingKind = "export-removed" | "major-bump" | "footer" | "forced";
 export declare function inferBreaking(diff: StagedDiff): boolean;
-/** Short reason for a BREAKING CHANGE footer, or undefined when not breaking. */
-export declare function breakingReason(diff: StagedDiff): string | undefined;
+/** Why breaking was set — heuristic signal first, then --breaking. */
+export declare function detectBreakingKind(diff: StagedDiff, forced?: boolean): BreakingKind | undefined;
+/** One-line bilingual cause for dry-run / --json.breakingReason. */
+export declare function formatBreakingReason(kind: BreakingKind): string;
+/** Detail text for the BREAKING CHANGE footer, or undefined when not inferred. */
+export declare function breakingFooterDetail(diff: StagedDiff): string | undefined;
 /**
  * Ensure body carries a conventional BREAKING CHANGE footer when breaking.
  * Skips if the body already mentions one. Uses subject as a last-resort reason.

package/dist/heuristic.js

@@ -28,10 +28,16 @@ export function proposeHeuristic(input) {
     const scope = input.scope ?? inferScope(diff.files);
     const subject = inferSubject(diff, type, scope);
     const body = inferBody(diff, type);
-    const breaking = Boolean(input.breaking) || inferBreaking(diff);
+    const forced = Boolean(input.breaking);
+    const kind = detectBreakingKind(diff, forced);
+    const breaking = Boolean(kind);
     const styled = applyVibe({ type, scope, subject, body, breaking }, vibe);
-    const message = { ...styled, engine: "heuristic" };
-    return ensureBreakingFooter(message, breakingReason(diff));
+    const message = {
+        ...styled,
+        engine: "heuristic",
+        breakingReason: kind ? formatBreakingReason(kind) : undefined,
+    };
+    return ensureBreakingFooter(message, breakingFooterDetail(diff));
 }
 export function inferType(diff) {
     const files = diff.files;
@@ -218,10 +224,35 @@ function inferBody(diff, type) {
     return `${lead}\n${listed}${extra}`;
 }
 export function inferBreaking(diff) {
-    return Boolean(breakingReason(diff));
+    return Boolean(detectBreakingKind(diff, false));
+}
+/** Why breaking was set — heuristic signal first, then --breaking. */
+export function detectBreakingKind(diff, forced = false) {
+    if (detectBreakingFooter(diff))
+        return "footer";
+    if (detectRemovedExports(diff).length > 0)
+        return "export-removed";
+    if (detectMajorVersionBump(diff))
+        return "major-bump";
+    if (forced)
+        return "forced";
+    return undefined;
+}
+/** One-line bilingual cause for dry-run / --json.breakingReason. */
+export function formatBreakingReason(kind) {
+    switch (kind) {
+        case "export-removed":
+            return "export removed · 公开 export 删除";
+        case "major-bump":
+            return "major bump · package.json 主版本升级";
+        case "footer":
+            return "BREAKING CHANGE footer in diff";
+        case "forced":
+            return "forced via --breaking · --breaking 强制";
+    }
 }
-/** Short reason for a BREAKING CHANGE footer, or undefined when not breaking. */
-export function breakingReason(diff) {
+/** Detail text for the BREAKING CHANGE footer, or undefined when not inferred. */
+export function breakingFooterDetail(diff) {
     const footer = detectBreakingFooter(diff);
     if (footer)
         return footer;

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { proposeWithAi } from "./ai.ts";
 export { formatCommit, parseCommit, normalizeSubject } from "./format.ts";
 export { inspectStaged, commitWithMessage, GitError } from "./git.ts";
-export { proposeHeuristic, inferType, inferScope, inferSubject, inferBreaking, ensureBreakingFooter, classifyPath, } from "./heuristic.ts";
+export { proposeHeuristic, inferType, inferScope, inferSubject, inferBreaking, detectBreakingKind, formatBreakingReason, breakingFooterDetail, ensureBreakingFooter, classifyPath, } from "./heuristic.ts";
+export type { BreakingKind } from "./heuristic.ts";
 export { parseArgs, helpText, UsageError } from "./parse-args.ts";
 export { assembleDiff, parseUnifiedDiff } from "./parse-diff.ts";
 export { installHook, uninstallHook, runPrepareCommitMsg, shouldSkipPrepareCommitMsg, hasNonCommentContent, HOOK_BEGIN, HOOK_END, } from "./hook.ts";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { proposeWithAi } from "./ai.js";
 export { formatCommit, parseCommit, normalizeSubject } from "./format.js";
 export { inspectStaged, commitWithMessage, GitError } from "./git.js";
-export { proposeHeuristic, inferType, inferScope, inferSubject, inferBreaking, ensureBreakingFooter, classifyPath, } from "./heuristic.js";
+export { proposeHeuristic, inferType, inferScope, inferSubject, inferBreaking, detectBreakingKind, formatBreakingReason, breakingFooterDetail, ensureBreakingFooter, classifyPath, } from "./heuristic.js";
 export { parseArgs, helpText, UsageError } from "./parse-args.js";
 export { assembleDiff, parseUnifiedDiff } from "./parse-diff.js";
 export { installHook, uninstallHook, runPrepareCommitMsg, shouldSkipPrepareCommitMsg, hasNonCommentContent, HOOK_BEGIN, HOOK_END, } from "./hook.js";

package/dist/propose.js

@@ -1,5 +1,5 @@
 import { proposeWithAi } from "./ai.js";
-import { breakingReason, ensureBreakingFooter, proposeHeuristic, } from "./heuristic.js";
+import { breakingFooterDetail, detectBreakingKind, ensureBreakingFooter, formatBreakingReason, proposeHeuristic, } from "./heuristic.js";
 export async function proposeMessage(diff, options, env = process.env) {
     const heuristic = proposeHeuristic({
         diff,
@@ -22,7 +22,14 @@ export async function proposeMessage(diff, options, env = process.env) {
                 message = ai;
         }
     }
-    const breaking = Boolean(options.breaking) || heuristic.breaking || message.breaking;
-    return ensureBreakingFooter({ ...message, breaking }, breakingReason(diff));
+    const forced = Boolean(options.breaking);
+    const breaking = forced || heuristic.breaking || message.breaking;
+    const kind = detectBreakingKind(diff, forced);
+    const breakingReason = kind
+        ? formatBreakingReason(kind)
+        : breaking
+            ? heuristic.breakingReason ?? message.breakingReason
+            : undefined;
+    return ensureBreakingFooter({ ...message, breaking, breakingReason }, breakingFooterDetail(diff));
 }
 //# sourceMappingURL=propose.js.map

package/dist/render.js

@@ -31,6 +31,10 @@ export function renderProposal(diff, message, hints = {}) {
         ...indent(formatted, pc),
         "",
     ];
+    if (message.breaking && message.breakingReason) {
+        lines.push(`  ${pc.yellow("breaking")}  ${pc.dim(message.breakingReason)}`);
+        lines.push("");
+    }
     if (hints.committed) {
         lines.push(`  ${pc.green("committed")}`);
         lines.push("");

package/dist/types.d.ts

@@ -27,6 +27,8 @@ export interface ProposedMessage {
     subject: string;
     body?: string;
     breaking: boolean;
+    /** Short cause when breaking (export removed / major bump / --breaking / footer). */
+    breakingReason?: string;
     engine: Engine;
 }
 export interface ProposeOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webywz/vibe-commit",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Stylish conventional commit messages with personality. Offline-first, AI-optional.",
   "keywords": [
     "git",