multicz 0.3.0__tar.gz → 0.5.0__tar.gz

multicz-0.5.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: multicz
+Version: 0.5.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
+Author-email: Chris <goabonga@pm.me>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.7
+Requires-Dist: tomlkit>=0.13
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: pathspec>=0.12
+Requires-Dist: packaging>=24.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/goabonga/multicz
+Project-URL: Repository, https://github.com/goabonga/multicz
+Project-URL: Issues, https://github.com/goabonga/multicz/issues
+Description-Content-Type: text/markdown
+
+# multicz
+
+Multi-component versioning for monorepos. Bump a Python app, its Docker image,
+and the Helm chart that deploys it from a single conventional-commit history -
+each with its own version line and its own git tag.
+
+<p align="center">
+  <img src="https://github.com/goabonga/multicz/raw/main/docs/demo.gif" alt="multicz demo" width="720">
+</p>
+
+## Install
+
+```bash
+uv tool install multicz   # or: pipx install multicz / pip install multicz
+```
+
+## Quickstart
+
+```bash
+# 1. scaffold a multicz.toml in the repo root
+multicz init
+
+# 2. see what would bump from the current commit window
+multicz changed
+multicz explain api
+
+# 3. apply the bump (writes version files + changelog, commits, tags)
+multicz bump --commit --tag
+
+# 4. ship it
+git push --follow-tags
+```
+
+For multi-component setups (api + chart, app + image + helm, ...), declare
+each component's paths in `multicz.toml` and let mirrors and triggers cascade
+related versions. See the [docs](https://goabonga.github.io/multicz/) for the
+full configuration reference.
+
+## What it does
+
+- **Per-component versions** - each component has its own version line and
+  its own git tag (`api-v1.2.0`, `chart-v0.5.0`).
+- **Conventional-commit driven** - `feat:` → minor, `fix:` → patch,
+  `BREAKING CHANGE:` → major. Scopes route the bump to the right component.
+- **Mirrors and triggers** - bump api `1.2.0` → `1.3.0` and the Helm chart's
+  `appVersion` follows; the chart's own version cascades a patch.
+- **No network, no auto-updates.** Pure `git` + filesystem. Same input yields
+  the same plan byte-for-byte.
+
+## Documentation
+
+Published at **<https://goabonga.github.io/multicz/>**:
+
+- [Get started](https://goabonga.github.io/multicz/get-started/) - install, minimal config, first bump
+- [Concepts](https://goabonga.github.io/multicz/concepts/) - components, mirrors, triggers, cascades, bump policies
+- [Configuration](https://goabonga.github.io/multicz/configuration/) - full `multicz.toml` reference
+- [CLI](https://goabonga.github.io/multicz/cli/) - every command and flag
+- [Recipes](https://goabonga.github.io/multicz/recipes/) - FastAPI + Helm walkthrough, CI matrix gating, release candidates
+- [Why multicz?](https://goabonga.github.io/multicz/why/) - vs. semantic-release, Commitizen, Changesets, bump-my-version
+- [Security](https://goabonga.github.io/multicz/security/) - guarantees and CI hardening
+
+## License
+
+[MIT](https://github.com/goabonga/multicz/blob/main/LICENSE)

multicz-0.5.0/README.md

@@ -0,0 +1,64 @@
+# multicz
+
+Multi-component versioning for monorepos. Bump a Python app, its Docker image,
+and the Helm chart that deploys it from a single conventional-commit history -
+each with its own version line and its own git tag.
+
+<p align="center">
+  <img src="https://github.com/goabonga/multicz/raw/main/docs/demo.gif" alt="multicz demo" width="720">
+</p>
+
+## Install
+
+```bash
+uv tool install multicz   # or: pipx install multicz / pip install multicz
+```
+
+## Quickstart
+
+```bash
+# 1. scaffold a multicz.toml in the repo root
+multicz init
+
+# 2. see what would bump from the current commit window
+multicz changed
+multicz explain api
+
+# 3. apply the bump (writes version files + changelog, commits, tags)
+multicz bump --commit --tag
+
+# 4. ship it
+git push --follow-tags
+```
+
+For multi-component setups (api + chart, app + image + helm, ...), declare
+each component's paths in `multicz.toml` and let mirrors and triggers cascade
+related versions. See the [docs](https://goabonga.github.io/multicz/) for the
+full configuration reference.
+
+## What it does
+
+- **Per-component versions** - each component has its own version line and
+  its own git tag (`api-v1.2.0`, `chart-v0.5.0`).
+- **Conventional-commit driven** - `feat:` → minor, `fix:` → patch,
+  `BREAKING CHANGE:` → major. Scopes route the bump to the right component.
+- **Mirrors and triggers** - bump api `1.2.0` → `1.3.0` and the Helm chart's
+  `appVersion` follows; the chart's own version cascades a patch.
+- **No network, no auto-updates.** Pure `git` + filesystem. Same input yields
+  the same plan byte-for-byte.
+
+## Documentation
+
+Published at **<https://goabonga.github.io/multicz/>**:
+
+- [Get started](https://goabonga.github.io/multicz/get-started/) - install, minimal config, first bump
+- [Concepts](https://goabonga.github.io/multicz/concepts/) - components, mirrors, triggers, cascades, bump policies
+- [Configuration](https://goabonga.github.io/multicz/configuration/) - full `multicz.toml` reference
+- [CLI](https://goabonga.github.io/multicz/cli/) - every command and flag
+- [Recipes](https://goabonga.github.io/multicz/recipes/) - FastAPI + Helm walkthrough, CI matrix gating, release candidates
+- [Why multicz?](https://goabonga.github.io/multicz/why/) - vs. semantic-release, Commitizen, Changesets, bump-my-version
+- [Security](https://goabonga.github.io/multicz/security/) - guarantees and CI hardening
+
+## License
+
+[MIT](https://github.com/goabonga/multicz/blob/main/LICENSE)

{multicz-0.3.0 → multicz-0.5.0}/pyproject.toml

@@ -1,6 +1,9 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
 [project]
 name = "multicz"
-version = "0.3.0"
+version = "0.5.0"
 description = "Multi-component versioning for monorepos: bump apps, charts, and images independently from conventional commits."
 readme = "README.md"
 authors = [
@@ -46,6 +49,9 @@ dev = [
     "pytest-cov>=5.0",
     "ruff>=0.6",
 ]
+docs = [
+    "zensical>=0.0.39",
+]
 
 [tool.ruff]
 line-length = 100

{multicz-0.3.0 → multicz-0.5.0}/src/multicz/__init__.py

@@ -1,4 +1,7 @@
-"""multicz — multi-component versioning for monorepos."""
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
+"""multicz - multi-component versioning for monorepos."""
 
 from importlib.metadata import PackageNotFoundError, version
 

multicz-0.5.0/src/multicz/__main__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
+from .cli import app
+
+app()

{multicz-0.3.0 → multicz-0.5.0}/src/multicz/changelog.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
 """Render and insert per-component CHANGELOG.md sections.
 
 A *section* is the chunk of markdown describing a single release for one
@@ -16,8 +19,8 @@ component:
 The list of section buckets and their titles is configurable via
 ``ProjectSettings.changelog_sections`` so each project can pick its own
 vocabulary (Features/Fixes vs. keep-a-changelog's Added/Changed/Fixed,
-etc.). Commits whose type matches no section are silently dropped — keep
-the changelog focused on user-visible changes — unless
+etc.). Commits whose type matches no section are silently dropped - keep
+the changelog focused on user-visible changes - unless
 ``other_section_title`` is set, which buckets them under that title.
 
 When written into an existing file the new section lands directly after
@@ -42,10 +45,22 @@ 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._``.
+
+    ``section`` and ``format`` are optional per-entry overrides for the
+    default ``cascade_title`` / ``cascade_format`` passed to
+    :func:`render_body`. When ``section`` matches an existing
+    commit-driven section (``Features``, ``Fixes``, ``Breaking
+    changes``, ...), the cascade line is appended to that section's
+    bucket. Otherwise it creates a new section under that name. An
+    explicit empty-string ``section`` (``""``) is **not** the disable
+    switch — to disable the cascade rendering entirely, leave
+    ``section=None`` and pass ``cascade_title=""`` to ``render_body``.
     """
 
     upstream: str
     upstream_version: str
+    section: str | None = None
+    format: str | None = None
 
 _PREAMBLE = (
     "# Changelog\n"
@@ -79,23 +94,32 @@ def render_body(
     """
     sections = list(sections) if sections is not None else _default_changelog_sections()
     relevant = [c for c in commits if c.is_conventional]
-    cascade_lines: list[str] = []
-    if cascades and cascade_title:
+
+    # Group cascades by their *resolved* section name. Per-entry overrides
+    # take precedence over the global cascade_title; an empty resolved
+    # section name means "drop this entry" (preserves the legacy
+    # cascade_title="" disable switch when no per-entry section is set).
+    cascade_groups: dict[str, list[str]] = {}
+    if cascades:
         for entry in cascades:
-            cascade_lines.append(
-                cascade_format.format(
-                    upstream=entry.upstream,
-                    upstream_version=entry.upstream_version,
-                )
+            section_name = entry.section if entry.section is not None else cascade_title
+            if not section_name:
+                continue
+            fmt = entry.format if entry.format is not None else cascade_format
+            line = fmt.format(
+                upstream=entry.upstream,
+                upstream_version=entry.upstream_version,
             )
-    if not relevant and not cascade_lines:
+            cascade_groups.setdefault(section_name, []).append(line)
+
+    if not relevant and not cascade_groups:
         return "_No notable changes._\n"
 
     breaking: list[Commit] = []
     if breaking_title:
         breaking = [c for c in relevant if c.breaking]
 
-    buckets: dict[str, list[Commit]] = {}
+    commit_buckets: dict[str, list[Commit]] = {}
     breaking_set = {id(c) for c in breaking}
     for section in sections:
         type_set = {t.lower() for t in section.types}
@@ -104,7 +128,7 @@ def render_body(
             if id(c) not in breaking_set and c.type.lower() in type_set
         ]
         if items:
-            buckets[section.title] = items
+            commit_buckets[section.title] = items
 
     if other_title:
         claimed = {t.lower() for s in sections for t in s.types}
@@ -113,35 +137,52 @@ def render_body(
             if id(c) not in breaking_set and c.type.lower() not in claimed
         ]
         if leftovers:
-            buckets[other_title] = leftovers
+            commit_buckets[other_title] = leftovers
 
-    ordered: list[tuple[str, list[Commit]]] = (
-        [(breaking_title, breaking)] if breaking else []
-    )
-    for section in sections:
-        if section.title in buckets:
-            ordered.append((section.title, buckets[section.title]))
-    if other_title and other_title in buckets:
-        ordered.append((other_title, buckets[other_title]))
+    def _commit_line(commit: Commit) -> str:
+        scope = f"**{commit.scope}**: " if commit.scope else ""
+        return f"{scope}{commit.subject} (`{commit.sha[:7]}`)"
+
+    # Build the final ordered list of (title, lines). For each
+    # commit-driven section we render the commits first, then append any
+    # cascade lines targeting that same title — so a mirror routed to
+    # ``Features`` lands at the bottom of the existing ``### Features``
+    # bucket rather than creating a parallel one.
+    ordered: list[tuple[str, list[str]]] = []
+
+    if breaking:
+        merged = [_commit_line(c) for c in breaking]
+        merged.extend(cascade_groups.pop(breaking_title, []))
+        ordered.append((breaking_title, merged))
 
-    if not ordered and not cascade_lines:
+    for section in sections:
+        if section.title in commit_buckets:
+            merged = [_commit_line(c) for c in commit_buckets[section.title]]
+            merged.extend(cascade_groups.pop(section.title, []))
+            ordered.append((section.title, merged))
+
+    if other_title and other_title in commit_buckets:
+        merged = [_commit_line(c) for c in commit_buckets[other_title]]
+        merged.extend(cascade_groups.pop(other_title, []))
+        ordered.append((other_title, merged))
+
+    # Whatever cascade sections are left have no matching commit bucket —
+    # render them after the commit-driven sections in their original
+    # insertion order.
+    for title, lines in cascade_groups.items():
+        ordered.append((title, list(lines)))
+
+    if not ordered:
         return "_No notable changes._\n"
 
-    lines: list[str] = []
+    out: list[str] = []
     for title, items in ordered:
-        lines.append(f"### {title}")
-        lines.append("")
-        for commit in items:
-            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)
+        out.append(f"### {title}")
+        out.append("")
+        for item in items:
+            out.append(f"- {item}")
+        out.append("")
+    return "\n".join(out)
 
 
 def render_section(
@@ -223,7 +264,7 @@ def update_changelog_file(
     """Render a new section and merge it into ``path`` (creating the file if needed).
 
     ``drop_prereleases=True`` removes any prior ``## [<version>-<pre>.<n>]``
-    sections from the file before inserting the new release section —
+    sections from the file before inserting the new release section -
     used by the ``promote`` finalize strategy.
     """
     section = render_section(

{multicz-0.3.0 → multicz-0.5.0}/src/multicz/cli.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
 """Command line interface for multicz."""
 
 from __future__ import annotations
@@ -64,7 +67,7 @@ err = Console(stderr=True)
 
 
 _BARE_CONFIG = """\
-# multicz.toml — generic stub. Edit paths and bump_files to match your repo.
+# multicz.toml - generic stub. Edit paths and bump_files to match your repo.
 # Run `multicz init` (without --bare) to scan the working tree and generate
 # a config tailored to the manifests it actually contains.
 
@@ -130,7 +133,7 @@ def init(
     ``charts/*/Chart.yaml``, ``package.json``, ``Cargo.toml``, ``go.mod``,
     ``gradle.properties`` and ``debian/changelog``; one component is
     emitted per detected manifest. ``--bare`` writes a generic
-    single-component stub instead — useful when bootstrapping a brand
+    single-component stub instead - useful when bootstrapping a brand
     new repo.
 
     \b
@@ -277,7 +280,7 @@ def _append_step_summary(path: Path, lines: list[str]) -> None:
 
     Mirrors GitHub Actions' ``$GITHUB_STEP_SUMMARY`` semantics: each
     step's content is appended; the runner concatenates everything into
-    the workflow's run-page summary. Safe to call from local shells —
+    the workflow's run-page summary. Safe to call from local shells -
     the file is just a text file.
     """
     path.parent.mkdir(parents=True, exist_ok=True)
@@ -306,7 +309,7 @@ def _append_plan_summary(path: Path, plan_obj, *, header: str) -> None:
     lines.append("")
     for bump in plan_obj:
         lines.append(
-            f"### `{bump.component}` — {bump.current} → {bump.next} "
+            f"### `{bump.component}` - {bump.current} → {bump.next} "
             f"({bump.kind})"
         )
         lines.append("")
@@ -340,7 +343,7 @@ def _append_bump_summary(
     tag_index = {t.split("-v", 1)[0] if "-v" in t else None: t for t in tags}
     # Fall back to format string lookup when tag_format isn't `<comp>-v<ver>`.
     for name, info in applied.items():
-        tag = tag_index.get(name) or "—"
+        tag = tag_index.get(name) or "-"
         for t in tags:
             if config.tag_format_for(name).format(
                 component=name, version=info["next"]
@@ -442,7 +445,7 @@ def plan_cmd(
     force: list[str] = typer.Option(
         None, "--force",
         help="Force-bump <name>:<kind>. Repeatable. Bypasses commit "
-             "detection — use for manual rebuilds (CVE base image refresh, "
+             "detection - use for manual rebuilds (CVE base image refresh, "
              "weekly artefact rebuild, …).",
     ),
     summary: Path = typer.Option(
@@ -538,7 +541,7 @@ def state(
     repo, config = _load()
     if config.project.state_file is None:
         err.print(
-            "[red]no state_file configured[/] — set "
+            "[red]no state_file configured[/] - set "
             "[bold][project].state_file[/] in multicz.toml"
         )
         raise typer.Exit(code=1)
@@ -577,7 +580,7 @@ def changed(
         None, "--since",
         help="Reference to compare against (e.g. origin/main, HEAD~5). "
              "When omitted, each component is compared against its own "
-             "last tag — same window as the planner uses for bumps.",
+             "last tag - same window as the planner uses for bumps.",
     ),
     output: str = typer.Option(
         "text", "--output", "-o", help="text | json",
@@ -605,7 +608,7 @@ def changed(
               component: ${{ fromJson(needs.detect.outputs.changed) }}
 
     Without --since, the answer is per-component (same window as the
-    planner). With --since, every component shares the reference —
+    planner). With --since, every component shares the reference -
     ideal for "what changed in this PR vs main".
 
     Release commits matching ``project.release_commit_pattern`` are
@@ -744,7 +747,7 @@ def release_notes_cmd(
     notes.
 
     \b
-    Default (notes for the upcoming bump — same set as `plan`):
+    Default (notes for the upcoming bump - same set as `plan`):
       multicz release-notes api
       multicz release-notes --all
 
@@ -948,7 +951,7 @@ def explain(
     bump = plan_obj.bumps.get(component)
     if bump is None:
         console.print(
-            f"[bold]{component}[/]: [dim]no bump pending — "
+            f"[bold]{component}[/]: [dim]no bump pending - "
             "no relevant commits since the last tag[/]"
         )
         return
@@ -1013,7 +1016,7 @@ def _porcelain_paths(repo: Path) -> set[str]:
 
     Used to identify candidate paths to hash before/after running
     ``post_bump`` hooks. A pure set diff would miss a file that's
-    dirty both before and after with different content — the
+    dirty both before and after with different content - the
     canonical case being ``uv run`` itself silently re-syncing
     ``uv.lock`` before multicz even gets to run.
     """
@@ -1108,7 +1111,7 @@ def _component_relevant_commits(
       (project + component, union) are skipped entirely.
 
     When ``since_stable`` is True, the range starts at the previous
-    *stable* tag instead — used by the ``consolidate`` and ``promote``
+    *stable* tag instead - used by the ``consolidate`` and ``promote``
     finalize strategies.
     """
     import re
@@ -1217,10 +1220,10 @@ def _release_commit_message(
 
     Available placeholders:
 
-    * ``{summary}``    — ``api 1.2.0 -> 1.3.0, chart 0.4.0 -> 0.5.0``
-    * ``{components}`` — ``api v1.3.0, chart v0.5.0`` (versions only, ``v`` prefixed)
-    * ``{body}``       — bullet list with kind annotations
-    * ``{count}``      — number of components bumped
+    * ``{summary}``    - ``api 1.2.0 -> 1.3.0, chart 0.4.0 -> 0.5.0``
+    * ``{components}`` - ``api v1.3.0, chart v0.5.0`` (versions only, ``v`` prefixed)
+    * ``{body}``       - bullet list with kind annotations
+    * ``{count}``      - number of components bumped
 
     Literal ``{`` and ``}`` in a template should be escaped as ``{{`` / ``}}``.
     """
@@ -1284,12 +1287,12 @@ def bump(
         None, "--commit-message", "-m",
         help="Verbatim release commit message (overrides the project's "
              "release_commit_message template). Like 'git commit -m', no "
-             "placeholders are expanded — the string is used as-is.",
+             "placeholders are expanded - the string is used as-is.",
     ),
     force: list[str] = typer.Option(
         None, "--force",
         help="Force-bump <name>:<kind>. Repeatable. Bypasses commit "
-             "detection — use for manual rebuilds (e.g. weekly base "
+             "detection - use for manual rebuilds (e.g. weekly base "
              "image refresh: `--force api:patch`).",
     ),
     sign: bool = typer.Option(
@@ -1328,7 +1331,7 @@ def bump(
             console.print_json(data={"bumps": {}})
         else:
             console.print(
-                "[dim]no bumps pending — "
+                "[dim]no bumps pending - "
                 "use [bold]--force <name>:<kind>[/] for a manual bump[/]"
             )
         return
@@ -1390,10 +1393,33 @@ def bump(
                         upstream_planned = plan.bumps.get(reason.upstream)
                         if upstream_planned is None:
                             continue
+                        # When the cascade comes from a mirror, look up
+                        # the matching mirror declaration on the upstream
+                        # component to pick up its optional
+                        # `changelog_section` / `changelog_format`. Trigger
+                        # cascades have no such customization handle and
+                        # always use the project-level defaults.
+                        section_override: str | None = None
+                        format_override: str | None = None
+                        if isinstance(reason, MirrorReason):
+                            upstream_component = config.components.get(
+                                reason.upstream
+                            )
+                            if upstream_component is not None:
+                                for mirror in upstream_component.mirrors:
+                                    if (
+                                        str(mirror.file) == reason.file
+                                        and mirror.key == reason.key
+                                    ):
+                                        section_override = mirror.changelog_section
+                                        format_override = mirror.changelog_format
+                                        break
                         cascade_entries.append(
                             CascadeEntry(
                                 upstream=reason.upstream,
                                 upstream_version=upstream_planned.next,
+                                section=section_override,
+                                format=format_override,
                             )
                         )
                         seen_upstreams.add(reason.upstream)
@@ -1462,7 +1488,7 @@ def bump(
     # Cargo.toml. Files modified by hooks are auto-detected and folded
     # into ``written`` so they ride the release commit.
     #
-    # Detection compares content hashes — not just the dirty-paths set —
+    # Detection compares content hashes - not just the dirty-paths set -
     # because the entry point is typically ``uv run multicz bump``, and
     # ``uv run`` re-syncs the venv (which can rewrite ``uv.lock``) before
     # multicz code runs at all. By the time we snapshot, uv.lock is

{multicz-0.3.0 → multicz-0.5.0}/src/multicz/commits.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
 """Conventional Commit parsing over a git history range.
 
 Resolves the latest tag matching a component's tag prefix, lists the commits
@@ -88,7 +91,7 @@ class Commit:
         ``minor``: ``feat``.
         ``patch``: ``fix``, ``perf``, ``revert``. A revert is a
         user-visible change (something was removed or restored), and a
-        patch is the conservative answer — the next release isn't a
+        patch is the conservative answer - the next release isn't a
         feature or breaking change, but it isn't nothing either.
 
         Other types (``chore``, ``docs``, ``style``, ``refactor``,

{multicz-0.3.0 → multicz-0.5.0}/src/multicz/components.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
 """Map repository file paths to declared components.
 
 Each component owns a set of gitignore-style glob ``paths`` and optional

{multicz-0.3.0 → multicz-0.5.0}/src/multicz/config.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 Chris <goabonga@pm.me>
+
 """Configuration schema for multicz.
 
 The config lives in ``multicz.toml`` at the repo root. It declares one or more
@@ -48,6 +51,29 @@ class FileKey(BaseModel):
     key: str | None = None
 
 
+class Mirror(FileKey):
+    """A mirror target with optional changelog customization.
+
+    Inherits ``file`` / ``key`` from :class:`FileKey`. Adds two optional
+    fields that customize how the resulting cascade line is rendered in
+    the *downstream* component's CHANGELOG when this mirror triggers a
+    bump there:
+
+    * ``changelog_section`` - routes the cascade line to a specific
+      section. Can be the title of an existing section
+      (``Features``, ``Fixes``, ``Dependencies``, ...) or any custom
+      name. When unset, the line falls under the project-level
+      ``cascade_section_title`` (default: ``Dependencies``).
+    * ``changelog_format`` - overrides the default cascade phrase for
+      this specific mirror. The template accepts ``{upstream}`` and
+      ``{upstream_version}`` placeholders. When unset, the project-level
+      ``cascade_changelog_format`` applies.
+    """
+
+    changelog_section: str | None = None
+    changelog_format: str | None = None
+
+
 class Artifact(BaseModel):
     """A build artifact a component produces.
 
@@ -84,7 +110,7 @@ class DebianSettings(BaseModel):
 
     The component's version is read from the topmost stanza of
     ``changelog`` (default ``debian/changelog``) and a new stanza is
-    *prepended* on every bump — older stanzas are never rewritten.
+    *prepended* on every bump - older stanzas are never rewritten.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -103,7 +129,7 @@ class Component(BaseModel):
     paths: list[str] = Field(min_length=1)
     exclude_paths: list[str] = Field(default_factory=list)
     bump_files: list[FileKey] = Field(default_factory=list)
-    mirrors: list[FileKey] = Field(default_factory=list)
+    mirrors: list[Mirror] = Field(default_factory=list)
     # depends_on lists upstream components whose bump should cascade into
     # this one. ``triggers`` is kept as a parse-time alias for users who
     # already wrote it that way; both names normalise to ``depends_on``.
@@ -310,12 +336,12 @@ class Config(BaseModel):
                     f"component name {name!r} is too long "
                     f"(max {COMPONENT_NAME_MAX_LEN} chars). Component names "
                     "appear in git tags, file paths, JSON output, and release "
-                    "notes — keep them short."
+                    "notes - keep them short."
                 )
             if not COMPONENT_NAME_RE.match(name):
                 raise ValueError(
                     f"invalid component name {name!r}: must match "
-                    f"{COMPONENT_NAME_RE.pattern} — "
+                    f"{COMPONENT_NAME_RE.pattern} - "
                     "no slashes, colons, spaces, or path-like characters; "
                     "must start and end with a letter or digit. Component "
                     "names land in git tags, file paths, JSON output, and "