multicz 1.2.1__tar.gz → 1.3.0__tar.gz

{multicz-1.2.1 → multicz-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: multicz
-Version: 1.2.1
+Version: 1.3.0
 Summary: Multi-component versioning for monorepos: bump apps, charts, and images independently from conventional commits.
 Keywords: semver,monorepo,helm,conventional-commits,release,versioning
 Author: Chris

{multicz-1.2.1 → multicz-1.3.0}/pyproject.toml

@@ -3,7 +3,7 @@
 
 [project]
 name = "multicz"
-version = "1.2.1"
+version = "1.3.0"
 description = "Multi-component versioning for monorepos: bump apps, charts, and images independently from conventional commits."
 readme = "README.md"
 authors = [
@@ -34,6 +34,13 @@ dependencies = [
 [project.scripts]
 multicz = "multicz.cli:app"
 
+# Built-in plugins registered via the same entry-point group third-
+# party plugins use. Disable a built-in by setting
+# `[plugins.<name>] enabled = false` in multicz.toml — there is no
+# privileged loader path.
+[project.entry-points."multicz.plugins"]
+deprecation = "multicz.plugins.builtin.deprecation:DeprecationPlugin"
+
 [project.urls]
 Homepage = "https://github.com/goabonga/multicz"
 Repository = "https://github.com/goabonga/multicz"

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/changelog/markdown.py

@@ -35,11 +35,15 @@ from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass
 from datetime import date
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from ..commits import BumpRule, Commit
 from ..config import ChangelogSection, _default_changelog_sections
 from .bucket import bucket_commits
 
+if TYPE_CHECKING:
+    from ..plugins import ChangelogEntry as PluginChangelogEntry
+
 
 @dataclass(frozen=True)
 class CascadeEntry:
@@ -81,6 +85,7 @@ def render_body(
     cascades: Sequence[CascadeEntry] | None = None,
     cascade_title: str = "Dependencies",
     cascade_format: str = "Track `{upstream}` `{upstream_version}`",
+    plugin_sections: Sequence[PluginChangelogEntry] | None = None,
 ) -> str:
     """Render the section bodies (no leading H2).
 
@@ -125,7 +130,17 @@ def render_body(
             )
             cascade_groups.setdefault(section_name, []).append(line)
 
-    if bucketed.is_empty and not cascade_groups:
+    # Plugin-contributed sections (e.g. "Deprecated", "Removed" from the
+    # built-in deprecation plugin) — grouped by section name, merged with
+    # any matching commit/cascade bucket.
+    plugin_groups: dict[str, list[str]] = {}
+    if plugin_sections:
+        for entry in plugin_sections:
+            if not entry.section or not entry.lines:
+                continue
+            plugin_groups.setdefault(entry.section, []).extend(entry.lines)
+
+    if bucketed.is_empty and not cascade_groups and not plugin_groups:
         return "_No notable changes._\n"
 
     def _commit_line(commit: Commit) -> str:
@@ -174,6 +189,20 @@ def render_body(
     for title, lines in cascade_groups.items():
         ordered.append((title, list(lines)))
 
+    # Plugin sections land last (after commits + cascades) so they read
+    # as a clear "meta" block — typically Deprecated/Removed notices.
+    # If a plugin reuses an existing title (e.g. "Features"), merge
+    # rather than create a duplicate H3.
+    existing_titles = {title for title, _ in ordered}
+    for title, lines in plugin_groups.items():
+        if title in existing_titles:
+            for entry in ordered:
+                if entry[0] == title:
+                    entry[1].extend(lines)
+                    break
+        else:
+            ordered.append((title, list(lines)))
+
     if not ordered:
         return "_No notable changes._\n"
 
@@ -199,6 +228,7 @@ def render_section(
     cascades: Sequence[CascadeEntry] | None = None,
     cascade_title: str = "Dependencies",
     cascade_format: str = "Track `{upstream}` `{upstream_version}`",
+    plugin_sections: Sequence[PluginChangelogEntry] | None = None,
 ) -> str:
     """Render the markdown for a single release section."""
     when = (today or date.today()).isoformat()
@@ -211,6 +241,7 @@ def render_section(
         cascades=cascades,
         cascade_title=cascade_title,
         cascade_format=cascade_format,
+        plugin_sections=plugin_sections,
     )
     return f"## [{version}] - {when}\n\n" + body
 
@@ -265,6 +296,7 @@ def update_changelog_file(
     cascades: Sequence[CascadeEntry] | None = None,
     cascade_title: str = "Dependencies",
     cascade_format: str = "Track `{upstream}` `{upstream_version}`",
+    plugin_sections: Sequence[PluginChangelogEntry] | None = None,
 ) -> None:
     """Render a new section and merge it into ``path`` (creating the file if needed).
 
@@ -283,6 +315,7 @@ def update_changelog_file(
         cascades=cascades,
         cascade_title=cascade_title,
         cascade_format=cascade_format,
+        plugin_sections=plugin_sections,
     )
     existing = path.read_text(encoding="utf-8") if path.exists() else ""
     if drop_prereleases:

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/__init__.py

@@ -57,6 +57,7 @@ from .commands import (  # noqa: E402, F401
     graph,
     init,
     plan,
+    plugins,
     release_notes,
     state,
     status,

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/commands/bump.py

@@ -15,6 +15,7 @@ import typer
 from ...changelog import update_changelog_file
 from ...config import ComponentMatcher
 from ...formats import write_value
+from ...plugins import has_errors, run_enrich_changelog, run_post_plan
 from ...state import (
     STATE_SCHEMA_VERSION,
     ComponentState,
@@ -230,6 +231,15 @@ def bump(
         presenters.render_bump_empty(output=output)
         return
 
+    # Plugin hook — gate the bump on installed plugins (deprecation
+    # removal policy, license check, etc.). Errors abort here BEFORE
+    # any write touches the repo. Warnings + infos surface but proceed.
+    violations = run_post_plan(config, repo, plan)
+    if violations:
+        presenters.render_plugin_violations(violations, output=output)
+    if has_errors(violations):
+        raise typer.Exit(code=1)
+
     matcher = ComponentMatcher(config.components)
     applied: list[AppliedBump] = []
     written: list[Path] = []
@@ -268,6 +278,11 @@ def bump(
             # this is the only thing that explains *why* the
             # release exists.
             cascade_entries = _cascade_entries_for(planned, plan, config)
+            # Let plugins (e.g. deprecation) contribute custom sections
+            # — Deprecated / Removed / SECURITY / etc.
+            plugin_entries = run_enrich_changelog(
+                config, repo, plan, planned.component
+            )
             changelog_path = repo / comp.changelog
             update_changelog_file(
                 changelog_path,
@@ -281,6 +296,7 @@ def bump(
                 cascades=cascade_entries,
                 cascade_title=config.project.cascade_section_title,
                 cascade_format=config.project.cascade_changelog_format,
+                plugin_sections=plugin_entries,
             )
             if changelog_path not in written:
                 written.append(changelog_path)

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/commands/plan.py

@@ -9,6 +9,7 @@ from pathlib import Path
 
 import typer
 
+from ...plugins import run_post_plan, run_status_lines
 from .. import app, err, presenters
 from .._shared import (
     _build_plan_or_exit,
@@ -85,3 +86,15 @@ def plan_cmd(
         presenters.append_plan_summary(summary, plan_obj, header="Release plan")
 
     presenters.render_plan(plan_obj, config, output=output)
+
+    # Preview the post_plan hook so users see violations BEFORE running
+    # `multicz bump` — same contract as the real gate, but never aborts.
+    violations = run_post_plan(config, repo, plan_obj)
+    if violations:
+        presenters.render_plugin_violations(violations, output=output)
+
+    # status_lines surface actionable advice from each plugin
+    # (e.g. "remove deprecation X before bumping to 3.0").
+    advice = run_status_lines(config, repo, plan_obj)
+    if advice:
+        presenters.render_plugin_advice(advice, output=output)

multicz-1.3.0/src/multicz/cli/commands/plugins.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
+"""``multicz plugins`` - list discovered plugins and their config state."""
+
+from __future__ import annotations
+
+import typer
+
+from ...plugins import DEFAULT_REGISTRY
+from .. import app, presenters
+from .._shared import _load
+
+
+@app.command(name="plugins")
+def plugins_cmd(
+    output: str = typer.Option("text", "--output", "-o", help="text | json"),
+) -> None:
+    """List every plugin discovered via the multicz.plugins entry-point
+    group with its enabled/disabled state and config section.
+
+    Useful to verify a third-party plugin is picked up after install,
+    confirm one is disabled via ``enabled = false``, or see at a glance
+    which plugins gate the next ``multicz bump``.
+    """
+    _, config = _load()
+    plugins = list(DEFAULT_REGISTRY)
+    plugins_table: dict[str, dict] = getattr(config, "plugins", {}) or {}
+    presenters.render_plugins_list(plugins, plugins_table, output=output)

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/commands/release_notes.py

@@ -18,6 +18,7 @@ from ...commits import (
     tag_prefix,
 )
 from ...config import ComponentMatcher
+from ...plugins import run_enrich_changelog
 from .. import app, err, presenters
 from .._shared import (
     _build_plan_or_exit,
@@ -159,6 +160,12 @@ def release_notes_cmd(
                 # Cascades only attach to upcoming bumps - past tag mode
                 # has no plan reasons to draw from.
                 cascades=tuple(_cascade_entries_for(bump, plan_obj, config)),
+                # Plugin contributions for this component (Deprecated /
+                # Removed sections from the built-in deprecation plugin,
+                # plus anything third-party plugins add).
+                plugin_sections=tuple(
+                    run_enrich_changelog(config, repo, plan_obj, name)
+                ),
             ))
 
     if not sections:

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/commands/status.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import typer
 
+from ...plugins import run_post_plan, run_status_lines
 from .. import app, presenters
 from .._shared import _build_plan_or_exit, _load
 
@@ -24,3 +25,12 @@ def status(
     repo, config = _load()
     plan_obj = _build_plan_or_exit(repo, config, since=since)
     presenters.render_status_table(plan_obj)
+
+    # Surface plugin violations + advice so `status` doubles as a
+    # "what would break if I ran bump right now" probe.
+    violations = run_post_plan(config, repo, plan_obj)
+    if violations:
+        presenters.render_plugin_violations(violations, output="text")
+    advice = run_status_lines(config, repo, plan_obj)
+    if advice:
+        presenters.render_plugin_advice(advice, output="text")

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/presenters.py

@@ -149,6 +149,150 @@ def render_bump_empty(*, output: str) -> None:
         )
 
 
+def render_plugins_list(plugins, plugins_config, *, output: str) -> None:
+    """Render the ``multicz plugins`` listing.
+
+    ``plugins`` is the iterable of discovered :class:`Plugin` instances
+    (typically ``list(DEFAULT_REGISTRY)``). ``plugins_config`` is
+    ``config.plugins`` — the raw TOML ``[plugins.<name>]`` map keyed by
+    plugin name.
+
+    Three discrete states are surfaced:
+
+    * **active** — ``[plugins.<name>]`` declared in multicz.toml and not
+      explicitly disabled. The runner will invoke it.
+    * **disabled** — section declared but ``enabled = false``. The user
+      has opted out on purpose.
+    * **inactive** — the plugin is discovered via its entry point but
+      no ``[plugins.<name>]`` section is declared. It will *not* run;
+      the project hasn't opted in.
+
+    Text output is a 4-column table; JSON is the machine-readable
+    shape for CI consumers.
+    """
+    rows = []
+    for plugin in plugins:
+        configured = plugin.name in plugins_config
+        section = plugins_config.get(plugin.name, {}) or {}
+        if not configured:
+            status = "inactive"
+        elif section.get("enabled", True):
+            status = "active"
+        else:
+            status = "disabled"
+        impl_cls = type(plugin)
+        module = impl_cls.__module__
+        rows.append(
+            {
+                "name": plugin.name,
+                "status": status,
+                "configured": configured,
+                "enabled": status == "active",
+                "module": module,
+                "class": impl_cls.__name__,
+                "config": section,
+            }
+        )
+    if output == "json":
+        console.print_json(data={"plugins": rows})
+        return
+    if not rows:
+        console.print("[dim]no plugins discovered[/]")
+        console.print(
+            "[dim]install a plugin or check it declares the "
+            "[bold]multicz.plugins[/] entry-point group[/]"
+        )
+        return
+    table = Table()
+    table.add_column("Plugin", style="bold")
+    table.add_column("Status")
+    table.add_column("Module")
+    table.add_column("Config section")
+    status_render = {
+        "active": "[green]active[/]",
+        "disabled": "[yellow]disabled[/]",
+        "inactive": "[dim]inactive[/]",
+    }
+    for row in rows:
+        status_cell = status_render[row["status"]]
+        cfg = row["config"]
+        # Square brackets in TOML section names trigger Rich's markup
+        # parser — escape them so they render literally in the table.
+        section_label = f"\\[plugins.{row['name']}]"
+        if row["status"] == "inactive":
+            cfg_cell = (
+                f"[dim](not in multicz.toml — add {section_label} "
+                "to activate)[/]"
+            )
+        elif cfg:
+            keys = ", ".join(f"{k}={v!r}" for k, v in cfg.items())
+            cfg_cell = f"{section_label} {keys}"
+        else:
+            cfg_cell = f"{section_label} [dim](defaults)[/]"
+        table.add_row(row["name"], status_cell, row["module"], cfg_cell)
+    console.print(table)
+
+
+def render_plugin_advice(lines, *, output: str) -> None:
+    """Render :meth:`Plugin.status_lines` output — free-form actionable
+    text plugins return to inform the user (e.g. "3 deprecations marked
+    for removal in v3.0").
+
+    Text output prefixes each line with a magenta arrow so it stands
+    out from the bump table without screaming like a violation.
+    """
+    if output == "json":
+        console.print_json(data={"advice": list(lines)})
+        return
+    if not lines:
+        return
+    console.print()
+    for line in lines:
+        console.print(f"  [magenta]→[/] {line}")
+
+
+def render_plugin_violations(violations, *, output: str) -> None:
+    """Render the list of :class:`multicz.plugins.Violation` raised by
+    installed plugins after :meth:`Plugin.post_plan`.
+
+    Text output groups by severity (errors first, then warnings, then
+    infos) and prefixes each line with the plugin name. JSON output
+    emits an array suited for CI consumers.
+    """
+    if output == "json":
+        console.print_json(
+            data={
+                "violations": [
+                    {
+                        "severity": v.severity.value,
+                        "message": v.message,
+                        "plugin": v.plugin,
+                        "component": v.component,
+                        "file": str(v.file) if v.file else None,
+                        "line": v.line,
+                    }
+                    for v in violations
+                ]
+            }
+        )
+        return
+    colour = {"error": "red", "warning": "yellow", "info": "cyan"}
+    glyph = {"error": "✗", "warning": "!", "info": "·"}
+    by_severity: dict[str, list] = {"error": [], "warning": [], "info": []}
+    for v in violations:
+        by_severity[v.severity.value].append(v)
+    for sev in ("error", "warning", "info"):
+        for v in by_severity[sev]:
+            loc = ""
+            if v.file:
+                loc = f" [dim]({v.file}{':' + str(v.line) if v.line else ''})[/]"
+            comp = f"[dim]\\[{v.component}][/] " if v.component else ""
+            console.print(
+                f"  [{colour[sev]}]{glyph[sev]}[/] {comp}{v.message}"
+                f" [dim](from {v.plugin})[/]" + loc
+            )
+
+
 def _git_summary_to_json(git: GitSummary) -> dict:
     """Project a GitSummary back to the legacy ``git_summary`` dict shape.
 
@@ -455,6 +599,7 @@ def render_release_notes(
             cascades=list(s.cascades) if s.cascades else None,
             cascade_title=config.project.cascade_section_title,
             cascade_format=config.project.cascade_changelog_format,
+            plugin_sections=list(s.plugin_sections) if s.plugin_sections else None,
         )
         if multi:
             range_label = (

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/cli/results.py

@@ -75,6 +75,11 @@ class ReleaseNotesSection:
     Replaces the per-section dict carried through ``sections: list[dict]``.
     ``cascades`` is empty for the ``--tag`` retrospective mode (no plan
     reasons exist).
+
+    ``plugin_sections`` carries the output of every plugin's
+    :meth:`enrich_changelog` for this component — Deprecated/Removed
+    notices, security advisories, etc. — appended below the commit-driven
+    sections at render time.
     """
 
     component: str
@@ -82,6 +87,7 @@ class ReleaseNotesSection:
     to_version: str
     commits: tuple[Commit, ...]
     cascades: tuple[CascadeEntry, ...] = ()
+    plugin_sections: tuple = ()
 
 
 # ============ validate ============

{multicz-1.2.1 → multicz-1.3.0}/src/multicz/config/models.py

@@ -318,6 +318,12 @@ class Config(BaseModel):
 
     project: ProjectSettings = Field(default_factory=ProjectSettings)
     components: dict[str, Component]
+    # Free-form sub-tables consumed by installed plugins. multicz itself
+    # never validates the inner shape — each plugin is responsible for
+    # parsing its own ``plugins[<plugin-name>]`` slice. Allows
+    # ``[plugins.deprecation]`` in multicz.toml without the core needing
+    # to know what fields the deprecation plugin uses.
+    plugins: dict[str, dict[str, Any]] = Field(default_factory=dict)
 
     @model_validator(mode="before")
     @classmethod

multicz-1.3.0/src/multicz/plugins/__init__.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
+"""multicz plugin system.
+
+Plugins extend the bump / planning / changelog pipeline without touching
+the core. They are discovered via the ``multicz.plugins`` entry-point
+group (``importlib.metadata``), so any package on PYTHONPATH that
+registers an entry point participates automatically.
+
+Built-in plugins live under :mod:`multicz.plugins.builtin` and are
+registered in multicz's own pyproject.toml.
+
+See :mod:`multicz.plugins.protocol` for the hook contract.
+"""
+
+from .protocol import (
+    BasePlugin,
+    ChangelogEntry,
+    Plugin,
+    PluginContext,
+    Severity,
+    Violation,
+)
+from .registry import DEFAULT_REGISTRY, ENTRY_POINT_GROUP, PluginRegistry
+from .runner import (
+    has_errors,
+    run_enrich_changelog,
+    run_post_plan,
+    run_status_lines,
+)
+
+__all__ = [
+    "DEFAULT_REGISTRY",
+    "ENTRY_POINT_GROUP",
+    "BasePlugin",
+    "ChangelogEntry",
+    "Plugin",
+    "PluginContext",
+    "PluginRegistry",
+    "Severity",
+    "Violation",
+    "has_errors",
+    "run_enrich_changelog",
+    "run_post_plan",
+    "run_status_lines",
+]

multicz-1.3.0/src/multicz/plugins/builtin/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
+"""Built-in multicz plugins shipped alongside the core.
+
+Each built-in lives in its own submodule and registers via
+``[project.entry-points."multicz.plugins"]`` in multicz's pyproject.toml
+— same path third-party plugins use, so there's no privileged loader.
+"""

multicz-1.3.0/src/multicz/plugins/builtin/deprecation/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
+"""Built-in deprecation-policy plugin.
+
+Detects deprecation markers in component sources and enforces a
+"remove by version N" policy at bump time. Also contributes
+``Deprecated`` / ``Removed`` sections to changelogs and release notes
+when relevant.
+
+See :mod:`multicz.plugins.builtin.deprecation.plugin` for the public
+:class:`DeprecationPlugin` entry point.
+"""
+
+from .plugin import DeprecationPlugin
+
+__all__ = ["DeprecationPlugin"]