feat(commit): add interactive live subject preview

ttw225 · ttw225 · commit 5dc4cec53477 · 2026-03-18T17:27:03.000+08:00
diff --git a/commitizen/commands/commit.py b/commitizen/commands/commit.py
@@ -6,9 +6,10 @@
 import subprocess
 import tempfile
 from pathlib import Path
-from typing import TYPE_CHECKING, TypedDict
+from typing import TYPE_CHECKING, Any, TypedDict
 
 import questionary
+from prompt_toolkit.application.current import get_app
 
 from commitizen import factory, git, out
 from commitizen.cz.exceptions import CzException
@@ -25,8 +26,16 @@
     NothingToCommitError,
 )
 from commitizen.git import smart_open
+from commitizen.interactive_preview import (
+    make_length_validator as make_length_validator_preview,
+)
+from commitizen.interactive_preview import (
+    make_toolbar_content as make_toolbar_content_preview,
+)
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from commitizen.config import BaseConfig
 
 
@@ -45,6 +54,11 @@ class CommitArgs(TypedDict, total=False):
 class Commit:
     """Show prompt for the user to create a guided commit."""
 
+    # Questionary types for interactive preview hooks (length validator / toolbar),
+    # based on questionary 2.0.1
+    VALIDATABLE_TYPES = {"input", "text", "password", "path", "checkbox"}
+    BOTTOM_TOOLBAR_TYPES = {"input", "text", "password", "confirm"}
+
     def __init__(self, config: BaseConfig, arguments: CommitArgs) -> None:
         if not git.is_git_project():
             raise NotAGitProjectError()
@@ -71,13 +85,120 @@ def _read_backup_message(self) -> str | None:
             encoding=self.config.settings["encoding"]
         ).strip()
 
+    def _build_commit_questions(
+        self,
+        questions: list,
+        preview_enabled: bool,
+        max_preview_length: int,
+    ) -> list:
+        """Build the list of questions to ask; add toolbar/validate when preview enabled."""
+        if not preview_enabled:
+            return list(questions)
+
+        default_answers: dict[str, Any] = {
+            q["name"]: q.get("default", "")
+            for q in questions
+            if isinstance(q.get("name"), str)
+        }
+        field_filters: dict[str, Any] = {
+            q["name"]: q.get("filter")
+            for q in questions
+            if isinstance(q.get("name"), str)
+        }
+        answers_state: dict[str, Any] = {}
+
+        def _get_current_buffer_text() -> str:
+            try:
+                app = get_app()
+                buffer = app.layout.current_buffer
+                return buffer.text if buffer is not None else ""
+            except Exception:
+                return ""
+
+        def subject_builder(current_field: str, current_text: str) -> str:
+            preview_answers: dict[str, Any] = default_answers.copy()
+            preview_answers.update(answers_state)
+            if current_field:
+                field_filter = field_filters.get(current_field)
+                if field_filter:
+                    try:
+                        preview_answers[current_field] = field_filter(current_text)
+                    except Exception:
+                        preview_answers[current_field] = current_text
+                else:
+                    preview_answers[current_field] = current_text
+            try:
+                return self.cz.message(preview_answers).partition("\n")[0].strip()
+            except Exception:
+                return ""
+
+        def make_stateful_filter(
+            name: str, original_filter: Callable[[str], Any] | None
+        ) -> Callable[[str], Any]:
+            def _filter(raw: str) -> Any:
+                value = original_filter(raw) if original_filter else raw
+                answers_state[name] = value
+                return value
+
+            return _filter
+
+        def make_toolbar(name: str) -> Callable[[], str]:
+            def _toolbar() -> str:
+                return make_toolbar_content_preview(
+                    subject_builder,
+                    name,
+                    _get_current_buffer_text(),
+                    max_length=max_preview_length,
+                )
+
+            return _toolbar
+
+        def make_length_validator(name: str) -> Callable[[str], bool | str]:
+            return make_length_validator_preview(
+                subject_builder,
+                name,
+                max_length=max_preview_length,
+            )
+
+        enhanced_questions: list[dict[str, object]] = []
+        for q in questions:
+            q_dict = dict(q)
+            q_type = q_dict.get("type")
+            name = q_dict.get("name")
+
+            if isinstance(name, str):
+                original_filter = q_dict.get("filter")
+                q_dict["filter"] = make_stateful_filter(name, original_filter)
+
+                if q_type in self.BOTTOM_TOOLBAR_TYPES:
+                    q_dict["bottom_toolbar"] = make_toolbar(name)
+
+                if q_type in self.VALIDATABLE_TYPES:
+                    q_dict["validate"] = make_length_validator(name)
+
+            enhanced_questions.append(q_dict)
+        return enhanced_questions
+
     def _get_message_by_prompt_commit_questions(self) -> str:
-        # Prompt user for the commit message
         questions = self.cz.questions()
         for question in (q for q in questions if q["type"] == "list"):
             question["use_shortcuts"] = self.config.settings["use_shortcuts"]
+
+        preview_enabled = bool(
+            self.arguments.get("preview", False)
+            or self.config.settings.get("preview", False)
+        )
+        max_preview_length = self.arguments.get(
+            "message_length_limit",
+            self.config.settings.get("message_length_limit", 0),
+        )
+
+        questions_to_ask = self._build_commit_questions(
+            questions, preview_enabled, max_preview_length
+        )
+
         try:
-            answers = questionary.prompt(questions, style=self.cz.style)
+            answers = questionary.prompt(questions_to_ask, style=self.cz.style)
         except ValueError as err:
             root_err = err.__context__
             if isinstance(root_err, CzException):
diff --git a/commitizen/interactive_preview.py b/commitizen/interactive_preview.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from shutil import get_terminal_size
+
+from prompt_toolkit.utils import get_cwidth
+
+SubjectBuilder = Callable[[str, str], str]
+
+
+def _wrap_display_width(text: str, width: int) -> list[str]:
+    """Wrap text by terminal display width (columns).
+
+    Each character width is computed with get_cwidth so CJK/full-width
+    characters are handled correctly.
+    """
+    if width <= 0 or not text:
+        return [text] if text else []
+
+    lines: list[str] = []
+    current: list[str] = []
+    current_width = 0
+
+    for char in text:
+        char_width = get_cwidth(char)
+        if current_width + char_width > width and current:
+            lines.append("".join(current))
+            current = []
+            current_width = 0
+
+        current.append(char)
+        current_width += char_width
+
+    if current:
+        lines.append("".join(current))
+
+    return lines
+
+
+def make_toolbar_content(
+    subject_builder: SubjectBuilder,
+    current_field: str,
+    current_text: str,
+    *,
+    max_length: int | None,
+) -> str:
+    """Build bottom toolbar content with live preview and length counter.
+
+    - First line (or multiple lines): preview of the commit subject, wrapped by
+      terminal display width.
+    - Last line: character count, optionally including the max length.
+    """
+    preview = subject_builder(current_field, current_text)
+    current_length = len(preview)
+
+    if max_length is not None and max_length > 0:
+        counter = f"{current_length}/{max_length} chars"
+    else:
+        counter = f"{current_length} chars"
+
+    try:
+        width = get_terminal_size().columns
+    except OSError:
+        width = 80
+
+    wrapped_preview = _wrap_display_width(preview, width)
+    preview_block = "\n".join(wrapped_preview)
+
+    padding = max(0, width - len(counter))
+    counter_line = f"{' ' * padding}{counter}"
+
+    return f"{preview_block}\n{counter_line}"
+
+
+def make_length_validator(
+    subject_builder: SubjectBuilder,
+    field: str,
+    *,
+    max_length: int | None,
+) -> Callable[[str], bool | str]:
+    """Create a questionary-style validator for subject length.
+
+    The validator:
+    - Uses the subject_builder to get the full preview string for the current
+      answers_state and field value.
+    - Applies max_length on the character count (len). A value of 0 or None
+      disables the limit.
+    """
+
+    def _validate(text: str) -> bool | str:
+        if not max_length or max_length <= 0:
+            return True
+
+        preview = subject_builder(field, text)
+        length = len(preview)
+        if length <= max_length:
+            return True
+
+        return f"{length}/{max_length} chars (subject length exceeded)"
+
+    return _validate
