commitizen-spdx-changelog 0.1.2__py3-none-any.whl

commitizen_spdx_changelog/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2026 Pablo Hörtner <redtux@pm.me>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Entry point for the commitizen-spdx-changelog package.
+
+Provides the package namespace and re-exports the public API.
+"""
+
+# src/commitizen_spdx_changelog/__init__.py
+#
+# This file is part of commitizen-spdx-changelog, a plugin
+# for commitizen that generates changelogs in SPDX format.

commitizen_spdx_changelog/formatters/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 Pablo Hörtner <redtux@pm.me>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Changelog formatters for commitizen-spdx-changelog.
+
+This subpackage contains the SPDX/REUSE-aware Markdown changelog format
+implementation and its supporting utilities.
+"""
+
+# src/commitizen_spdx_changelog/formatters/__init__.py
+#
+# This file is part of commitizen-spdx-changelog, a plugin
+# for commitizen that generates changelogs in SPDX format.

commitizen_spdx_changelog/formatters/spdx_markdown.py

@@ -0,0 +1,142 @@
+# SPDX-FileCopyrightText: 2026 Pablo Hörtner <redtux@pm.me>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""SPDX/REUSE-aware Markdown changelog format for commitizen.
+
+Compatible with REUSE/SPDX-compliant changelogs that carry a ``---``
+delimited YAML frontmatter block (e.g. SPDX headers) before the Markdown
+body. Registered under the ``commitizen.changelog_format`` entry point
+as ``spdx-markdown``.
+
+Note: importing this module directly, before anything else in the
+process has imported ``commitizen.changelog_formats``, will raise an
+``AttributeError`` due to a circular import inside commitizen's own
+entry-point-loading machinery (it loads all registered
+``commitizen.changelog_format`` plugins, including this one, from a
+module-level dict comprehension). This never occurs during real ``cz``
+usage, since commitizen's CLI bootstrap imports
+``commitizen.changelog_formats`` before scanning plugins. It can occur
+if a test imports this module cold — see ``tests/conftest.py`` for the
+one-line warm-up import that avoids it for the test suite.
+"""
+
+from __future__ import annotations
+
+import io
+from collections.abc import Sequence
+from pathlib import Path
+
+from commitizen.changelog import IncrementalMergeInfo, Metadata
+from commitizen.changelog_formats.markdown import Markdown
+
+
+def _strip_frontmatter(lines: Sequence[str]) -> tuple[list[str], int]:
+    """Strip ``---``-delimited YAML frontmatter.
+
+    Args:
+        lines: The input lines, which may start with ``---`` frontmatter.
+
+    Returns:
+        A tuple of ``(clean_lines, offset)`` where ``clean_lines`` is the
+        content after the closing ``---`` and ``offset`` is the number of
+        frontmatter lines (0 if no frontmatter is detected).
+    """
+    if not lines or lines[0].rstrip() != "---":
+        return list(lines), 0
+
+    in_fm = False
+    offset = 0
+    for i, line in enumerate(lines):
+        stripped = line.rstrip()
+        if stripped == "---":
+            offset += 1
+            if not in_fm:
+                in_fm = True
+            else:
+                return list(lines[i + 1 :]), offset
+        elif in_fm:
+            offset += 1
+
+    return list(lines), 0  # unclosed frontmatter — treat as no-op
+
+
+class SPDXMarkdown(Markdown):
+    """Markdown changelog format with YAML frontmatter awareness.
+
+    Overrides two methods from :class:`commitizen.changelog_formats.markdown.Markdown`:
+
+    - ``get_metadata()`` — strips frontmatter via :func:`_strip_frontmatter`,
+      delegates to ``get_metadata_from_file()``, then shifts the returned
+      line indices by the frontmatter line count.
+    - ``get_latest_full_release()`` — same stripping and index shift applied
+      to ``get_latest_full_release_from_file()``.
+
+    Attributes:
+        config: The commitizen configuration object.
+    """
+
+    def __init__(self, config=None):
+        if config is None:
+            from commitizen.config.base_config import BaseConfig
+
+            config = BaseConfig()
+        if "encoding" not in config.settings:
+            config.update({"encoding": "utf-8"})
+        super().__init__(config)
+
+    def get_metadata(self, filepath: str) -> Metadata:
+        """Extract changelog metadata with frontmatter offset correction.
+
+        Args:
+            filepath: Path to the changelog file.
+
+        Returns:
+            A :class:`commitizen.changelog.Metadata` instance with line
+            indices adjusted for stripped YAML frontmatter.
+        """
+        file = Path(filepath)
+        if not file.is_file():
+            return Metadata()
+
+        encoding = self.config.settings.get("encoding", "utf-8")
+        raw = file.read_text(encoding=encoding)
+        clean_lines, offset = _strip_frontmatter(raw.splitlines(keepends=True))
+
+        meta = self.get_metadata_from_file(io.StringIO("".join(clean_lines)))
+
+        if meta.unreleased_start is not None:
+            meta.unreleased_start += offset
+        if meta.unreleased_end is not None:
+            meta.unreleased_end += offset
+        if meta.latest_version_position is not None:
+            meta.latest_version_position += offset
+
+        return meta
+
+    def get_latest_full_release(self, filepath: str) -> IncrementalMergeInfo:
+        """Retrieve the latest full release info with frontmatter offset correction.
+
+        Args:
+            filepath: Path to the changelog file.
+
+        Returns:
+            An :class:`commitizen.changelog.IncrementalMergeInfo` with the
+            release index adjusted for stripped YAML frontmatter.
+        """
+        file = Path(filepath)
+        if not file.is_file():
+            return IncrementalMergeInfo()
+
+        encoding = self.config.settings.get("encoding", "utf-8")
+        raw = file.read_text(encoding=encoding)
+        clean_lines, offset = _strip_frontmatter(raw.splitlines(keepends=True))
+
+        result = self.get_latest_full_release_from_file(
+            io.StringIO("".join(clean_lines))
+        )
+
+        return IncrementalMergeInfo(
+            name=result.name,
+            index=(result.index + offset) if result.index is not None else None,
+        )

commitizen_spdx_changelog-0.1.2.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: commitizen-spdx-changelog
+Version: 0.1.2
+Summary: Commitizen changelog format plugin with YAML frontmatter awareness for REUSE/SPDX-compliant changelogs
+Keywords: commitizen,changelog,spdx,reuse,yaml,frontmatter
+Author: Pablo Hörtner
+Author-email: Pablo Hörtner <redtux@pm.me>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: commitizen>=4.16.3
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/redtux/commitizen-spdx-changelog
+Project-URL: Issues, https://github.com/redtux/commitizen-spdx-changelog/issues
+Project-URL: Source, https://github.com/redtux/commitizen-spdx-changelog
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 Pablo Hörtner <redtux@pm.me>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# 𝗰𝗼𝗺𝗺𝗶𝘁𝗶𝘇𝗲𝗻-𝚜𝚙𝚍𝚡-𝓬𝓱𝓪𝓷𝓰𝓮𝓵𝓸𝓰
+
+[![Typing SVG][typing-svg-badge]][typing-svg-link]
+
+[![License][license-badge]][license-link] [![PyPI][pypi-badge]][pypi-link]
+[![Python][python-badge]][pypi-link] [![CI][ci-badge]][ci-link]
+[![Release][release-badge]][release-link]
+
+A [commitizen] changelog format plugin with YAML frontmatter awareness —
+designed for REUSE/SPDX-compliant changelogs. No more false version detection
+from license headers like `Apache-2.0`.
+
+> [!WARNING]
+> _This project is in early development._
+
+## Features
+
+- [x] **SPDX-aware** — strips `---`-delimited YAML frontmatter before parsing
+- [x] **Correct version detection** — no false positives from `Apache-2.0` style
+    headers
+- [x] **Drop-in replacement** — extends commitizen's built-in `Markdown` format
+- [x] **Zero extra config** — just set `changelog_format = "spdx-markdown"`
+
+## Why do I need this?
+
+If you keep your changelog in `docs/changelog.md` instead of the project root,
+placing it alongside your documentation lets readers of your published site who
+might not directly browse the git repository stay informed about recent changes.
+
+Documentation generators like [Zensical], [Docusaurus], and tools using Google's
+[Open Knowledge Format (OKF)][okf] require a YAML front matter for `meta` data.
+
+When you apply a [REUSE/SPDX][reuse] license header with `reuse annotate`, the
+header lands as a YAML comment inside the front matter, not as an HTML comment:
+
+<!-- REUSE-IgnoreStart -->
+
+- `# SPDX-License-Identifier: Apache-2.0`
+
+<!-- REUSE-IgnoreEnd -->
+
+**The catch:** commitizen's built-in `Markdown` format does not understand YAML
+front matter. It reads `Apache-2.0` as a version number, causing
+`cz bump --changelog` to fail silently or produce wrong results.
+
+> [!NOTE]
+> This plugin strips the front matter before parsing, so your changelog stays
+> compliant, doc-generator-friendly, and commitizen-compatible — all at once.
+
+## Getting started
+
+### Installation
+
+```sh
+uv add commitizen-spdx-changelog
+# or: pip install commitizen-spdx-changelog
+```
+
+> [!TIP]
+> See the [docs landing page](docs/index.md) for a full overview, and the
+> [usage guide](docs/guide.md) for furher setup and workflow instructions.
+
+### Configuration
+
+In `pyproject.toml`:
+
+```toml
+[tool.commitizen]
+changelog_format = "spdx-markdown"
+```
+
+### Usage
+
+```sh
+cz bump --changelog
+```
+
+The plugin handles changelogs with SPDX frontmatter like:
+
+```markdown
+---
+# SPDX-FileCopyrightText: 2026 Pablo Hörtner <redtux@pm.me>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+icon: lucide/git-commit-vertical
+---
+
+# Changelog
+
+## 0.4.0 (2026-06-08)
+...
+```
+
+### Development
+
+```sh
+direnv allow
+uv sync --group dev
+```
+
+> [!TIP]
+> Running `direnv allow` will activate the [devbox] environment automatically.
+> See the [Devbox guide](docs/devbox.md) for all available commands and tools.
+
+## Contributing
+
+> [!NOTE]
+> Bug reports, feature requests, and pull requests are welcome.
+
+- See [docs/contributing.md](docs/contributing.md) for guidelines.
+
+For documentation contributions, please follow these principles:
+
+Write for humans, keep it minimal, update docs with code, delete dead content.
+Every page in `docs/` and the project `README.md` are held to these standards.
+
+## License
+
+Distributed under the terms of the [Apache License 2.0](LICENSE.md).
+
+- Copyright © 2026 Pablo Hörtner
+
+<!-- References -->
+
+[ci-badge]: https://badgen.net/github/checks/redtux/commitizen-spdx-changelog
+[ci-link]: https://github.com/redtux/commitizen-spdx-changelog/actions
+[commitizen]: https://commitizen-tools.github.io/commitizen/
+[devbox]: https://github.com/jetify-com/devbox
+[docusaurus]: https://docusaurus.io/
+[license-badge]: https://badgen.net/github/license/redtux/commitizen-spdx-changelog
+[license-link]: LICENSE.md
+[okf]: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+[pypi-badge]: https://badgen.net/pypi/v/commitizen-spdx-changelog
+[pypi-link]: https://pypi.org/project/commitizen-spdx-changelog/
+[python-badge]: https://badgen.net/pypi/python/commitizen-spdx-changelog
+[release-badge]: https://badgen.net/github/release/redtux/commitizen-spdx-changelog
+[release-link]: https://github.com/redtux/commitizen-spdx-changelog/releases
+[reuse]: https://reuse.software/
+[typing-svg-badge]: https://readme-typing-svg.demolab.com?font=Fira+Code&pause=1000&width=435&lines=SPDX-compliant+Commitizen+Changelogs
+[typing-svg-link]: https://git.io/typing-svg
+[zensical]: https://zensical.org/

commitizen_spdx_changelog-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+commitizen_spdx_changelog/__init__.py,sha256=JeuT7vZA__OchhhAzoA74u5BIFnnTpMjukq8_vuBNXU,392
+commitizen_spdx_changelog/formatters/__init__.py,sha256=mxXxvueP2p5pyl_Y35HdoIfH9K2jESGrmpoKNWU6-ZI,454
+commitizen_spdx_changelog/formatters/spdx_markdown.py,sha256=h3oPis3rBqUYpRuPfleQ6P8i1icZ_i4W21X51mydiI4,5084
+commitizen_spdx_changelog/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+commitizen_spdx_changelog-0.1.2.dist-info/WHEEL,sha256=s49dN1sxqzkgPplo4QuUaKomil-_cbDzeLK4-pZKD-A,81
+commitizen_spdx_changelog-0.1.2.dist-info/entry_points.txt,sha256=TL_iZ11fIGMCO1ikcrpk_FQ5oMGJX0urLspCbe-eY0M,111
+commitizen_spdx_changelog-0.1.2.dist-info/METADATA,sha256=KJwsD8F14cB13fOrSKZcvDMIFAkSk8ERohqqKwn2x4A,5555
+commitizen_spdx_changelog-0.1.2.dist-info/RECORD,,

commitizen_spdx_changelog-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.24
+Root-Is-Purelib: true
+Tag: py3-none-any

commitizen_spdx_changelog-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[commitizen.changelog_format]
+spdx-markdown = commitizen_spdx_changelog.formatters.spdx_markdown:SPDXMarkdown
+