Refactor release hint logic and add indented logger.

Refactored `ReleaseRule` to return structured results and updated related tests. Introduced `IndentedLoggerAdapter` for structured, indented logging and integrated it into the change log generation process. Enhanced CLI with verbosity options and improved logging outputs for better traceability.

Author: coordt

action.yml

@@ -26,4 +26,5 @@ branding:
   icon: "file-text"
 runs:
   using: "docker"
-  image: "ghcr.io/callowayproject/generate-changelog:v0"
+#  image: "ghcr.io/callowayproject/generate-changelog:v0"
+  image: "Dockerfile"

generate_changelog/cli.py

@@ -12,6 +12,7 @@
 from generate_changelog import __version__
 from generate_changelog.commits import get_context_from_tags
 from generate_changelog.configuration import DEFAULT_CONFIG_FILE_NAMES, Configuration, write_default_config
+from generate_changelog.indented_logger import setup_logging
 from generate_changelog.release_hint import suggest_release_type
 
 
@@ -57,6 +58,13 @@ def generate_config_callback(ctx: Context, param: Parameter, value: bool) -> Non
 @click.option("--output", "-o", type=click.Choice(["release-hint", "notes", "all"]), help="What output to generate.")
 @click.option("--skip-output-pipeline", is_flag=True, help="Do not execute the output pipeline in the configuration.")
 @click.option("--branch-override", "-b", help="Override the current branch for release hint decisions.")
+@click.option(
+    "--verbose",
+    "-v",
+    count=True,
+    required=False,
+    help="Print verbose logging to stderr. Can specify several times for more verbosity.",
+)
 @click.version_option(version=__version__)
 def cli(
     config: Optional[Path],
@@ -65,6 +73,7 @@ def cli(
     output: Optional[str],
     skip_output_pipeline: bool,
     branch_override: Optional[str],
+    verbose: int,
 ) -> None:
     """Generate a change log from git commits."""
     from generate_changelog import templating
@@ -73,6 +82,9 @@ def cli(
     echo_func = functools.partial(echo, quiet=bool(output))
     configuration = get_user_config(config, echo_func)
 
+    verbosity = verbose or configuration.verbosity
+    setup_logging(verbosity)
+
     repository = Repo(repo_path) if repo_path else Repo(search_parent_directories=True)
 
     current_branch = repository.head if repository.head.is_detached else repository.active_branch

generate_changelog/configuration.py

@@ -201,6 +201,9 @@ class Configuration:
     group_by: list = field(default_factory=list)
     """Group the commits within a version by these commit attributes."""
 
+    verbosity: int = 0
+    """Level of verbose logging output."""
+
     #
     # Commit filtering
     #

generate_changelog/indented_logger.py

@@ -0,0 +1,147 @@
+"""A logger adapter that adds an indent to the beginning of each message."""
+
+import logging
+import logging.config
+from contextvars import ContextVar
+from typing import Any, MutableMapping, Optional, Tuple, Union
+
+import click
+from rich.console import Console, RenderableType
+from rich.padding import Padding
+from rich.text import Text
+
+CURRENT_INDENT = ContextVar("current_indent", default=0)
+
+
+class IndentedLoggerAdapter(logging.LoggerAdapter):
+    """
+    Logger adapter that adds an indent to the beginning of each message.
+
+    Parameters:
+        logger: The logger to adapt.
+        extra: Extra values to add to the logging context.
+        depth: The number of `indent_char` to generate for each indent level.
+        indent_char: The character or string to use for indenting.
+        reset: `True` if the indent level should be reset to zero.
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger,
+        extra: Optional[dict] = None,
+        depth: int = 2,
+        indent_char: str = " ",
+        reset: bool = False,
+    ):
+        super().__init__(logger, extra or {})
+        self.console = Console(force_terminal=True)
+        self._depth = depth
+        self._indent_char = indent_char
+        if reset:
+            self.reset()
+
+    @property
+    def current_indent(self) -> int:
+        """
+        The current indent level.
+        """
+        return CURRENT_INDENT.get()
+
+    def indent(self, amount: int = 1) -> None:
+        """
+        Increase the indent level by `amount`.
+        """
+        CURRENT_INDENT.set(CURRENT_INDENT.get() + amount)
+
+    def dedent(self, amount: int = 1) -> None:
+        """
+        Decrease the indent level by `amount`.
+        """
+        CURRENT_INDENT.set(max(0, CURRENT_INDENT.get() - amount))
+
+    def reset(self) -> None:
+        """
+        Reset the indent level to zero.
+        """
+        CURRENT_INDENT.set(0)
+
+    @property
+    def indent_str(self) -> str:
+        """
+        The indent string.
+        """
+        return (self._indent_char * self._depth) * CURRENT_INDENT.get()
+
+    def process(
+        self, msg: Union[str, RenderableType], kwargs: Optional[MutableMapping[str, Any]]
+    ) -> Tuple[str, MutableMapping[str, Any]]:
+        """
+        Process the message and add the indent.
+
+        Args:
+            msg: The logging message.
+            kwargs: Keyword arguments passed to the logger.
+
+        Returns:
+            A tuple containing the message and keyword arguments.
+        """
+        if isinstance(msg, RenderableType):
+            with self.console.capture() as capture:
+                self.console.print(Padding(msg, (0, 0, 0, len(self.indent_str))))
+            msg = Text.from_ansi(capture.get())
+        else:
+            msg = self.indent_str + msg
+
+        return msg, kwargs
+
+
+VERBOSITY = {
+    0: (logging.WARNING, "%(message)s"),
+    1: (logging.INFO, "%(message)s"),
+    2: (logging.DEBUG, "%(message)s"),
+    3: (logging.DEBUG, "%(message)s %(pathname)s:%(lineno)d"),
+}
+
+
+def get_indented_logger(name: str) -> IndentedLoggerAdapter:
+    """Get a logger with indentation."""
+    return IndentedLoggerAdapter(logging.getLogger(name))
+
+
+def setup_logging(verbose: int = 0) -> None:
+    """Configure the logging."""
+    logging.config.dictConfig(get_config(verbose))
+    root_logger = get_indented_logger("")
+    root_logger.setLevel(logging.WARNING)
+
+
+def get_config(verbose: int = 0) -> dict:
+    """Get the loggic config."""
+    verbosity, log_format = VERBOSITY.get(verbose, VERBOSITY[3])
+    return {
+        "version": 1,
+        "formatters": {
+            "default": {
+                "format": log_format,
+                "datefmt": "[%X]",
+            }
+        },
+        "handlers": {
+            "default": {
+                "class": "rich.logging.RichHandler",
+                "markup": True,
+                "rich_tracebacks": True,
+                "show_level": False,
+                "show_path": False,
+                "show_time": False,
+                "tracebacks_suppress": [click],
+                "formatter": "default",
+            }
+        },
+        "loggers": {
+            "generate_changelog": {
+                "handlers": ["default"],
+                "level": verbosity,
+            }
+        },
+    }

generate_changelog/release_hint.py

@@ -1,11 +1,19 @@
 """Methods for generating a release hint."""
 
+import copy
 import fnmatch
 import re
-from typing import List, Optional, Sequence, Union
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Set, Union
+
+from rich.table import Table
+from rich.text import Text
 
 from generate_changelog.configuration import RELEASE_TYPE_ORDER, Configuration
 from generate_changelog.context import CommitContext, VersionContext
+from generate_changelog.indented_logger import get_indented_logger
+
+logger = get_indented_logger(__name__)
 
 
 class InvalidRuleError(Exception):
@@ -14,6 +22,24 @@ class InvalidRuleError(Exception):
     pass
 
 
+@dataclass
+class ReleaseRuleResult:
+    """The result of evaluating a release rule."""
+
+    matches_grouping: bool
+    matches_path: bool
+    matches_branch: bool
+    result: str
+
+    @property
+    def matches_all(self) -> bool:
+        """All the commit criteria were met."""
+        return all([self.matches_grouping, self.matches_path, self.matches_branch])
+
+    def __str__(self) -> str:
+        return self.result or ""
+
+
 class ReleaseRule:
     """
     A commit evaluation rule for hinting at the level of change.
@@ -35,7 +61,7 @@ def __init__(
         branch: Optional[str] = None,
     ):
         self.match_result = match_result
-        self.no_match_result = no_match_result
+        self.no_match_result = no_match_result or "no-release"
         self.grouping = grouping if grouping != "*" else None
         normalized_path = path if path != "*" else None
         if isinstance(normalized_path, str):
@@ -109,15 +135,22 @@ def matches_branch(self, current_branch: str) -> bool:
         """
         return bool(re.match(self.branch, current_branch)) if self.branch else True
 
-    def __call__(self, commit: CommitContext, current_branch: str) -> Optional[str]:
+    def __call__(self, commit: CommitContext, current_branch: str) -> ReleaseRuleResult:
         """Evaluate the commit using this rule."""
         if not self.is_valid:
             raise InvalidRuleError()
 
         matches_grouping = self.matches_grouping(commit)
         matches_path = self.matches_path(commit)
         matches_branch = self.matches_branch(current_branch)
-        return self.match_result if all([matches_grouping, matches_path, matches_branch]) else self.no_match_result
+        matches_all = all([matches_grouping, matches_path, matches_branch])
+        result = self.match_result if matches_all else self.no_match_result
+        return ReleaseRuleResult(
+            matches_grouping=matches_grouping,
+            matches_path=matches_path,
+            matches_branch=matches_branch,
+            result=result,
+        )
 
 
 class RuleProcessor:
@@ -130,6 +163,7 @@ class RuleProcessor:
 
     def __init__(self, rule_list: List[dict]):
         self.rules = [ReleaseRule(**kwargs) for kwargs in rule_list]
+        self.results: List[ReleaseRuleResult] = []
 
     def __call__(self, commit: CommitContext, current_branch: str) -> Optional[str]:
         """
@@ -142,13 +176,28 @@ def __call__(self, commit: CommitContext, current_branch: str) -> Optional[str]:
         Returns:
             The release hint
         """
-        suggestions = {rule(commit, current_branch) for rule in self.rules}
+        self.results = [rule(commit, current_branch) for rule in self.rules]
+        suggestions: Set[str] = {str(result.result) for result in self.results}
         if unknown_suggestions := suggestions - set(RELEASE_TYPE_ORDER):
             return unknown_suggestions.pop()  # Return a random value from the unknowns
 
         sorted_suggestions = sorted(suggestions, key=lambda s: RELEASE_TYPE_ORDER.index(s))
         return sorted_suggestions[-1]
 
+    def rule_string(self) -> str:
+        """Return a string representation of the rules."""
+        output: List[str] = []
+        for i, rule in enumerate(self.rules):
+            output.extend(
+                (
+                    f"Rule: {i}",
+                    f"  Grouping: {rule.grouping}",
+                    f"  Path: {rule.path}",
+                    f"  Branch: {rule.branch}",
+                )
+            )
+        return "\n".join(output)
+
 
 def suggest_release_type(current_branch: str, version_contexts: List[VersionContext], config: Configuration) -> str:
     """
@@ -160,20 +209,60 @@ def suggest_release_type(current_branch: str, version_contexts: List[VersionCont
         config: The current configuration
 
     Returns:
-        The type of release based on the rules, or ``no-release``
+        The type of release based on the rules, or `no-release`
     """
+    logger.info("Processing commits to suggest release type...")
+    logger.indent()
     rule_processor = RuleProcessor(rule_list=config.release_hint_rules)
+    logger.debug(rule_processor.rule_string())
 
     # If the latest release is not "unreleased", there is no need for a release
     if version_contexts[0].label != config.unreleased_label:
+        logger.info(f"The latest release is {version_contexts[0].label}. No release is suggested.")
+        logger.dedent()
         return "no-release"
 
     suggestions = set()
+    results = {}
     for commit_group in version_contexts[0].grouped_commits:
         suggestions |= {rule_processor(commit, current_branch) for commit in commit_group.commits}
+        results["Grouping: " + " ".join(commit_group.grouping)] = copy.deepcopy(rule_processor.results)
+
+    print_table(results)
 
     if not suggestions:
+        logger.info("No suggestions found. No release is suggested.")
+        logger.dedent()
         return "no-release"
 
     sorted_suggestions = sorted(suggestions, key=lambda s: RELEASE_TYPE_ORDER.index(s))
-    return sorted_suggestions[-1] or "no-release"
+    result = sorted_suggestions[-1] or "no-release"
+    logger.info("Suggested release type: %s", result)
+    logger.dedent()
+    return result
+
+
+def format_bool(bool_var: bool) -> Text:
+    """Format a boolean value as a string."""
+    return Text("X", style="bold green") if bool_var else Text("-", style="bold red")
+
+
+def print_table(results: dict) -> None:
+    """Print the test results as a table."""
+    for group_name, result_list in results.items():
+        table = Table(title=group_name, title_justify="left")
+        table.add_column("Rule", justify="center")
+        table.add_column("Group", justify="center")
+        table.add_column("Path", justify="center")
+        table.add_column("Branch", justify="center")
+        table.add_column("Result")
+
+        for i, result in enumerate(result_list):
+            table.add_row(
+                str(i),
+                format_bool(result.matches_grouping),
+                format_bool(result.matches_path),
+                format_bool(result.matches_branch),
+                result.result,
+            )
+        logger.debug(table)