multicz 0.2.2__tar.gz → 0.4.0__tar.gz

{multicz-0.2.2 → multicz-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: multicz
-Version: 0.2.2
+Version: 0.4.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
@@ -960,6 +960,28 @@ exec multicz check "$1"
 * `.properties` — line-based `key=value` substitution (e.g. `gradle.properties`)
 * anything else — treated as a one-line `VERSION` file (`key = ` omitted)
 
+### Regex escape hatch (`key = "regex:..."`)
+
+For files no structured parser handles — Python `__version__`,
+TypeScript `export const VERSION`, Cargo `version = "..."` *outside*
+the `[package]` table, Makefile `VERSION := ...`, shell scripts,
+Dockerfile `LABEL version=...` — prefix the key with `regex:`:
+
+```toml
+[components.api]
+bump_files = [
+    { file = "pyproject.toml", key = "project.version" },
+    { file = "src/api/__init__.py", key = 'regex:^__version__\s*=\s*"([^"]+)"' },
+]
+```
+
+The pattern needs exactly one capture group locating the version
+literal. Matching uses `re.MULTILINE`, and only the *first* match's
+capture group is rewritten — surrounding text (quotes, indentation,
+comments, the rest of the file) is preserved byte-for-byte. Bad
+patterns (uncompilable, no group, no match in file) surface at
+`multicz validate --strict` rather than at bump time.
+
 ### Debian packages (`format = "debian"`)
 
 `multicz` writes a proper `debian/changelog` instead of a markdown

{multicz-0.2.2 → multicz-0.4.0}/README.md

@@ -932,6 +932,28 @@ exec multicz check "$1"
 * `.properties` — line-based `key=value` substitution (e.g. `gradle.properties`)
 * anything else — treated as a one-line `VERSION` file (`key = ` omitted)
 
+### Regex escape hatch (`key = "regex:..."`)
+
+For files no structured parser handles — Python `__version__`,
+TypeScript `export const VERSION`, Cargo `version = "..."` *outside*
+the `[package]` table, Makefile `VERSION := ...`, shell scripts,
+Dockerfile `LABEL version=...` — prefix the key with `regex:`:
+
+```toml
+[components.api]
+bump_files = [
+    { file = "pyproject.toml", key = "project.version" },
+    { file = "src/api/__init__.py", key = 'regex:^__version__\s*=\s*"([^"]+)"' },
+]
+```
+
+The pattern needs exactly one capture group locating the version
+literal. Matching uses `re.MULTILINE`, and only the *first* match's
+capture group is rewritten — surrounding text (quotes, indentation,
+comments, the rest of the file) is preserved byte-for-byte. Bad
+patterns (uncompilable, no group, no match in file) surface at
+`multicz validate --strict` rather than at bump time.
+
 ### Debian packages (`format = "debian"`)
 
 `multicz` writes a proper `debian/changelog` instead of a markdown

{multicz-0.2.2 → multicz-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "multicz"
-version = "0.2.2"
+version = "0.4.0"
 description = "Multi-component versioning for monorepos: bump apps, charts, and images independently from conventional commits."
 readme = "README.md"
 authors = [

{multicz-0.2.2 → multicz-0.4.0}/src/multicz/changelog.py

@@ -29,12 +29,24 @@ from __future__ import annotations
 
 import re
 from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
 from datetime import date
 from pathlib import Path
 
 from .commits import Commit
 from .config import ChangelogSection, _default_changelog_sections
 
+
+@dataclass(frozen=True)
+class CascadeEntry:
+    """A non-commit reason for a bump (mirror or trigger), surfaced in
+    the changelog so cascade-only releases describe what made them
+    happen instead of rendering ``_No notable changes._``.
+    """
+
+    upstream: str
+    upstream_version: str
+
 _PREAMBLE = (
     "# Changelog\n"
     "\n"
@@ -49,16 +61,34 @@ def render_body(
     sections: Sequence[ChangelogSection] | None = None,
     breaking_title: str = "Breaking changes",
     other_title: str = "",
+    cascades: Sequence[CascadeEntry] | None = None,
+    cascade_title: str = "Dependencies",
+    cascade_format: str = "Track `{upstream}` `{upstream_version}`",
 ) -> str:
     """Render the section bodies (no leading H2).
 
     Empty string ``breaking_title`` disables the breaking bucket (breaking
     commits then fall through to whichever section claims their type).
     Empty string ``other_title`` drops unmatched conventional commits.
+
+    ``cascades`` lists upstream bumps that pulled this component along
+    (mirror writes, trigger edges). When present and ``cascade_title``
+    is non-empty, they render as a dedicated H3 section; this also
+    suppresses the ``_No notable changes._`` placeholder when no
+    commits otherwise apply.
     """
     sections = list(sections) if sections is not None else _default_changelog_sections()
     relevant = [c for c in commits if c.is_conventional]
-    if not relevant:
+    cascade_lines: list[str] = []
+    if cascades and cascade_title:
+        for entry in cascades:
+            cascade_lines.append(
+                cascade_format.format(
+                    upstream=entry.upstream,
+                    upstream_version=entry.upstream_version,
+                )
+            )
+    if not relevant and not cascade_lines:
         return "_No notable changes._\n"
 
     breaking: list[Commit] = []
@@ -94,7 +124,7 @@ def render_body(
     if other_title and other_title in buckets:
         ordered.append((other_title, buckets[other_title]))
 
-    if not ordered:
+    if not ordered and not cascade_lines:
         return "_No notable changes._\n"
 
     lines: list[str] = []
@@ -105,6 +135,12 @@ def render_body(
             scope = f"**{commit.scope}**: " if commit.scope else ""
             lines.append(f"- {scope}{commit.subject} (`{commit.sha[:7]}`)")
         lines.append("")
+    if cascade_lines:
+        lines.append(f"### {cascade_title}")
+        lines.append("")
+        for entry in cascade_lines:
+            lines.append(f"- {entry}")
+        lines.append("")
     return "\n".join(lines)
 
 
@@ -116,6 +152,9 @@ def render_section(
     sections: Sequence[ChangelogSection] | None = None,
     breaking_title: str = "Breaking changes",
     other_title: str = "",
+    cascades: Sequence[CascadeEntry] | None = None,
+    cascade_title: str = "Dependencies",
+    cascade_format: str = "Track `{upstream}` `{upstream_version}`",
 ) -> str:
     """Render the markdown for a single release section."""
     when = (today or date.today()).isoformat()
@@ -124,6 +163,9 @@ def render_section(
         sections=sections,
         breaking_title=breaking_title,
         other_title=other_title,
+        cascades=cascades,
+        cascade_title=cascade_title,
+        cascade_format=cascade_format,
     )
     return f"## [{version}] - {when}\n\n" + body
 
@@ -174,6 +216,9 @@ def update_changelog_file(
     breaking_title: str = "Breaking changes",
     other_title: str = "",
     drop_prereleases: bool = False,
+    cascades: Sequence[CascadeEntry] | None = None,
+    cascade_title: str = "Dependencies",
+    cascade_format: str = "Track `{upstream}` `{upstream_version}`",
 ) -> None:
     """Render a new section and merge it into ``path`` (creating the file if needed).
 
@@ -188,6 +233,9 @@ def update_changelog_file(
         sections=sections,
         breaking_title=breaking_title,
         other_title=other_title,
+        cascades=cascades,
+        cascade_title=cascade_title,
+        cascade_format=cascade_format,
     )
     existing = path.read_text(encoding="utf-8") if path.exists() else ""
     if drop_prereleases:

{multicz-0.2.2 → multicz-0.4.0}/src/multicz/cli.py

@@ -14,7 +14,7 @@ from rich.console import Console
 from rich.table import Table
 
 from . import __version__
-from .changelog import render_body, update_changelog_file
+from .changelog import CascadeEntry, render_body, update_changelog_file
 from .commits import (
     DEFAULT_TYPES,
     commits_in_range,
@@ -1376,6 +1376,27 @@ def bump(
                     planned.component, config, repo, matcher,
                     since_stable=use_stable_since,
                 )
+                # Surface mirror/trigger cascades as a Dependencies
+                # section: when a release is purely cascade-driven
+                # (e.g. chart bumps because api updated appVersion),
+                # this is the only thing that explains *why* the
+                # release exists.
+                cascade_entries: list[CascadeEntry] = []
+                seen_upstreams: set[str] = set()
+                for reason in planned.reasons:
+                    if isinstance(reason, MirrorReason | TriggerReason):
+                        if reason.upstream in seen_upstreams:
+                            continue
+                        upstream_planned = plan.bumps.get(reason.upstream)
+                        if upstream_planned is None:
+                            continue
+                        cascade_entries.append(
+                            CascadeEntry(
+                                upstream=reason.upstream,
+                                upstream_version=upstream_planned.next,
+                            )
+                        )
+                        seen_upstreams.add(reason.upstream)
                 changelog_path = repo / comp.changelog
                 update_changelog_file(
                     changelog_path,
@@ -1385,6 +1406,9 @@ def bump(
                     breaking_title=config.project.breaking_section_title,
                     other_title=config.project.other_section_title,
                     drop_prereleases=is_final and strategy == "promote",
+                    cascades=cascade_entries,
+                    cascade_title=config.project.cascade_section_title,
+                    cascade_format=config.project.cascade_changelog_format,
                 )
                 if changelog_path not in written:
                     written.append(changelog_path)

{multicz-0.2.2 → multicz-0.4.0}/src/multicz/config.py

@@ -231,6 +231,14 @@ class ProjectSettings(BaseModel):
     )
     breaking_section_title: str = "Breaking changes"
     other_section_title: str = ""
+    # Section + line format for cascade-only bumps (mirror or trigger).
+    # Replaces the legacy ``_No notable changes._`` placeholder when the
+    # only reason for a release is an upstream component bumping. Set
+    # ``cascade_section_title = ""`` to disable and fall back to the
+    # placeholder. ``cascade_changelog_format`` accepts ``{upstream}`` and
+    # ``{upstream_version}`` placeholders.
+    cascade_section_title: str = "Dependencies"
+    cascade_changelog_format: str = "Track `{upstream}` `{upstream_version}`"
     finalize_strategy: Literal["consolidate", "promote", "annotate"] = "consolidate"
     overlap_policy: Literal["error", "first-match", "allow", "all"] = "error"
     ignored_types: list[str] = Field(default_factory=list)

{multicz-0.2.2 → multicz-0.4.0}/src/multicz/writers.py

@@ -13,22 +13,54 @@ A ``key`` is a dotted path (``project.version``, ``image.tag``). Passing
 files the dotted-path interpretation is disabled — the key is taken
 verbatim, since properties files routinely use dotted keys (``a.b.c``)
 that are *not* nested.
+
+A ``key`` prefixed with ``regex:`` is a language-agnostic escape hatch:
+the rest of the string is a regex with one capture group locating the
+version literal. Useful for ``__version__ = "X"`` in Python,
+``export const VERSION = "X"`` in TypeScript, ``VERSION := X`` in
+Makefiles, etc. The regex is anchored with :data:`re.MULTILINE`, and
+only the *first* match's capture group is rewritten.
 """
 
 from __future__ import annotations
 
 import io
 import json
+import re
 from pathlib import Path
 
 import tomlkit
 from ruamel.yaml import YAML
 
+REGEX_KEY_PREFIX = "regex:"
+
 
 class WriterError(RuntimeError):
     """Raised when a value cannot be read or written."""
 
 
+def _is_regex_key(key: str | None) -> bool:
+    return key is not None and key.startswith(REGEX_KEY_PREFIX)
+
+
+def _compile_regex_key(key: str) -> re.Pattern[str]:
+    pattern = key[len(REGEX_KEY_PREFIX):]
+    if not pattern:
+        raise WriterError(f"empty regex pattern in key: {key!r}")
+    try:
+        compiled = re.compile(pattern, re.MULTILINE)
+    except re.error as exc:
+        raise WriterError(
+            f"invalid regex {pattern!r} in key {key!r}: {exc}"
+        ) from exc
+    if compiled.groups < 1:
+        raise WriterError(
+            f"regex {pattern!r} must contain exactly one capture "
+            "group locating the version literal"
+        )
+    return compiled
+
+
 def _split_key(key: str) -> list[str]:
     parts = [part for part in key.split(".") if part]
     if not parts:
@@ -121,6 +153,14 @@ def read_value(file: Path, key: str | None) -> str:
     text = file.read_text(encoding="utf-8")
     if key is None:
         return text.strip()
+    if _is_regex_key(key):
+        pattern = _compile_regex_key(key)
+        match = pattern.search(text)
+        if not match:
+            raise WriterError(
+                f"regex {key!r} matched nothing in {file}"
+            )
+        return match.group(1)
     if _is_properties(file):
         result = _read_property(text, key)
         if result is None:
@@ -157,6 +197,22 @@ def write_value(file: Path, key: str | None, value: str) -> None:
         file.write_text(value + "\n", encoding="utf-8")
         return
 
+    if _is_regex_key(key):
+        pattern = _compile_regex_key(key)
+        text = file.read_text(encoding="utf-8")
+        match = pattern.search(text)
+        if not match:
+            raise WriterError(
+                f"regex {key!r} matched nothing in {file}"
+            )
+        # Replace only the first match's capture group, preserving the
+        # surrounding text byte-for-byte (quotes, indentation, comments).
+        g_start, g_end = match.span(1)
+        file.write_text(
+            text[:g_start] + value + text[g_end:], encoding="utf-8"
+        )
+        return
+
     if _is_properties(file):
         text = file.read_text(encoding="utf-8")
         file.write_text(_write_property(text, key, value), encoding="utf-8")