Feat: add live subject preview for interactive commit (--preview)

commitizen/cli.py

@@ -164,6 +164,11 @@ def __call__(
                         "type": int,
                         "help": "Set the length limit of the commit message; 0 for no limit.",
                     },
+                    {
+                        "name": ["--preview"],
+                        "action": "store_true",
+                        "help": "Show live first-line (subject) preview while typing.",
+                    },
                     {
                         "name": ["--"],
                         "action": "store_true",

commitizen/commands/check.py

@@ -21,7 +21,7 @@ class CheckArgs(TypedDict, total=False):
     commit_msg: str
     rev_range: str
     allow_abort: bool
-    message_length_limit: int
+    message_length_limit: int | None
     allowed_prefixes: list[str]
     message: str
     use_default_range: bool
@@ -46,8 +46,12 @@ def __init__(self, config: BaseConfig, arguments: CheckArgs, *args: object) -> N
         )
 
         self.use_default_range = bool(arguments.get("use_default_range"))
-        self.max_msg_length = arguments.get(
-            "message_length_limit", config.settings.get("message_length_limit", 0)
+
+        message_length_limit = arguments.get("message_length_limit")
+        self.message_length_limit: int = (
+            message_length_limit
+            if message_length_limit is not None
+            else config.settings["message_length_limit"]
         )
 
         # we need to distinguish between None and [], which is a valid value
@@ -100,7 +104,7 @@ def __call__(self) -> None:
                     pattern=pattern,
                     allow_abort=self.allow_abort,
                     allowed_prefixes=self.allowed_prefixes,
-                    max_msg_length=self.max_msg_length,
+                    max_msg_length=self.message_length_limit,
                     commit_hash=commit.rev,
                 )
             ).is_valid

commitizen/commands/commit.py

@@ -25,6 +25,7 @@
     NothingToCommitError,
 )
 from commitizen.git import smart_open
+from commitizen.preview_questions import build_preview_questions
 
 if TYPE_CHECKING:
     from commitizen.config import BaseConfig
@@ -35,11 +36,12 @@ class CommitArgs(TypedDict, total=False):
     dry_run: bool
     edit: bool
     extra_cli_args: str
-    message_length_limit: int
+    message_length_limit: int | None
     no_retry: bool
     signoff: bool
     write_message_to_file: Path | None
     retry: bool
+    preview: bool
 
 
 class Commit:
@@ -54,6 +56,18 @@ def __init__(self, config: BaseConfig, arguments: CommitArgs) -> None:
         self.arguments = arguments
         self.backup_file_path = get_backup_file_path()
 
+        message_length_limit = arguments.get("message_length_limit")
+        self.message_length_limit: int = (
+            message_length_limit
+            if message_length_limit is not None
+            else config.settings["message_length_limit"]
+        )
+
+        self.preview_enabled = bool(
+            self.arguments.get("preview", False)
+            or self.config.settings.get("preview", False)
+        )
+
     def _read_backup_message(self) -> str | None:
         # Check the commit backup file exists
         if not self.backup_file_path.is_file():
@@ -65,12 +79,19 @@ def _read_backup_message(self) -> str | None:
         ).strip()
 
     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"]
+
+        questions_to_ask = build_preview_questions(
+            self.cz,
+            questions,
+            enabled=self.preview_enabled,
+            max_length=self.message_length_limit,
+        )
+
         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):
@@ -85,19 +106,14 @@ def _get_message_by_prompt_commit_questions(self) -> str:
         return message
 
     def _validate_subject_length(self, message: str) -> None:
-        message_length_limit = self.arguments.get(
-            "message_length_limit", self.config.settings.get("message_length_limit", 0)
-        )
         # By the contract, message_length_limit is set to 0 for no limit
-        if (
-            message_length_limit is None or message_length_limit <= 0
-        ):  # do nothing for no limit
+        if self.message_length_limit <= 0:
             return
 
         subject = message.partition("\n")[0].strip()
-        if len(subject) > message_length_limit:
+        if len(subject) > self.message_length_limit:
             raise CommitMessageLengthExceededError(
-                f"Length of commit message exceeds limit ({len(subject)}/{message_length_limit}), subject: '{subject}'"
+                f"Length of commit message exceeds limit ({len(subject)}/{self.message_length_limit}), subject: '{subject}'"
             )
 
     def manual_edit(self, message: str) -> str:

commitizen/defaults.py

@@ -65,6 +65,7 @@ class Settings(TypedDict, total=False):
     version_type: str | None
     version: str | None
     breaking_change_exclamation_in_title: bool
+    preview: bool
 
 
 CONFIG_FILES: tuple[str, ...] = (
@@ -115,6 +116,7 @@ class Settings(TypedDict, total=False):
     "extras": {},
     "breaking_change_exclamation_in_title": False,
     "message_length_limit": 0,  # 0 for no limit
+    "preview": False,
 }
 
 MAJOR = "MAJOR"

commitizen/interactive_preview.py

@@ -0,0 +1,102 @@
+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,
+) -> 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)
+
+    counter = (
+        f"{current_length}/{max_length} chars"
+        if max_length > 0
+        else 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,
+) -> 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 disables
+      the limit.
+    """
+
+    def _validate(text: str) -> bool | str:
+        if 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

commitizen/preview_questions.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from prompt_toolkit.application.current import get_app
+
+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.cz.base import BaseCommitizen
+    from commitizen.question import CzQuestion
+
+
+# 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 build_preview_questions(
+    cz: BaseCommitizen,
+    questions: list[CzQuestion],
+    *,
+    enabled: bool,
+    max_length: int,
+) -> list[CzQuestion]:
+    """Return questions enhanced with interactive preview, when enabled."""
+    if not enabled:
+        return questions
+
+    max_preview_length = max_length
+
+    default_answers: dict[str, Any] = {
+        q["name"]: q.get("default", "")
+        for q in questions
+        if isinstance(q.get("name"), str)
+    }
+    field_filters: dict[str, Callable[[str], str] | None] = {
+        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 cz.message(preview_answers).partition("\n")[0].strip()
+        except Exception:
+            return ""
+
+    def make_stateful_filter(
+        name: str, original_filter: Callable[[str], str] | None
+    ) -> Callable[[str], str]:
+        def _filter(raw: str) -> str:
+            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[CzQuestion] = []
+    for q in questions:
+        q_dict = q.copy()
+        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 BOTTOM_TOOLBAR_TYPES:
+                q_dict["bottom_toolbar"] = make_toolbar(name)
+
+            if q_type in VALIDATABLE_TYPES:
+                q_dict["validate"] = make_length_validator(name)
+
+        enhanced_questions.append(q_dict)
+
+    return enhanced_questions