zendev-commit 0.2.0__py3-none-any.whl

zendev/gitmoji/__init__.py

@@ -0,0 +1,182 @@
+"""Offline gitmoji catalog and official-header parsing."""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass
+from functools import cache
+from importlib.resources import files
+
+from zendev.conventional import ParseIssue
+
+__all__ = [
+    "EmojiConvention",
+    "Gitmoji",
+    "GitmojiCommit",
+    "GitmojiMatch",
+    "load_emoji_conventions",
+    "load_gitmojis",
+    "match_gitmoji",
+    "parse_gitmoji_commit",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Gitmoji:
+    emoji: str
+    code: str
+    description: str
+    name: str
+    semver: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class EmojiConvention:
+    """A Gitmoji intention paired with its canonical zendev commit type."""
+
+    type: str
+    gitmoji: Gitmoji
+
+
+@dataclass(frozen=True, slots=True)
+class GitmojiMatch:
+    gitmoji: Gitmoji
+    token: str
+    remainder: str
+
+
+@dataclass(frozen=True, slots=True)
+class GitmojiCommit:
+    intention: Gitmoji
+    token: str
+    scope: str | None
+    message: str
+    body: str | None
+
+
+@cache
+def load_gitmojis() -> tuple[Gitmoji, ...]:
+    catalog_path = files("zendev").joinpath("data/gitmojis.json")
+    payload = json.loads(catalog_path.read_text(encoding="utf-8"))
+    return tuple(
+        Gitmoji(
+            emoji=item["emoji"],
+            code=item["code"],
+            description=item["description"],
+            name=item["name"],
+            semver=item["semver"],
+        )
+        for item in payload["gitmojis"]
+    )
+
+
+@cache
+def load_emoji_conventions() -> tuple[EmojiConvention, ...]:
+    """Load and validate the complete, strict emoji-to-type convention."""
+
+    mapping_path = files("zendev").joinpath("data/emoji-conventions.toml")
+    payload = tomllib.loads(mapping_path.read_text(encoding="utf-8"))
+    types = payload.get("types")
+    if not isinstance(types, dict):
+        raise ValueError("emoji-conventions.toml must contain a string-to-string [types] table.")
+    type_mapping = {name: value for name, value in types.items() if isinstance(name, str) and isinstance(value, str)}
+    if len(type_mapping) != len(types):
+        raise ValueError("emoji-conventions.toml must contain a string-to-string [types] table.")
+
+    catalog = load_gitmojis()
+    catalog_names = {item.name for item in catalog}
+    mapped_names = set(type_mapping)
+    if mapped_names != catalog_names:
+        missing = ", ".join(sorted(catalog_names - mapped_names)) or "none"
+        extra = ", ".join(sorted(mapped_names - catalog_names)) or "none"
+        raise ValueError(
+            f"Emoji convention must cover the Gitmoji catalog exactly (missing: {missing}; extra: {extra})."
+        )
+
+    type_names = tuple(type_mapping[item.name] for item in catalog)
+    if any(re.fullmatch(r"[a-z0-9]+(?:-[a-z0-9]+)*", type_name) is None for type_name in type_names):
+        raise ValueError("Emoji convention types must be lowercase words separated by single hyphens.")
+    if len(set(type_names)) != len(type_names):
+        raise ValueError("Emoji convention types must be unique.")
+
+    return tuple(EmojiConvention(type=type_mapping[item.name], gitmoji=item) for item in catalog)
+
+
+@cache
+def _token_index() -> tuple[tuple[str, Gitmoji], ...]:
+    tokens: dict[str, Gitmoji] = {}
+    for gitmoji in load_gitmojis():
+        tokens[gitmoji.emoji] = gitmoji
+        tokens[gitmoji.code] = gitmoji
+        without_variation_selector = gitmoji.emoji.replace("\ufe0f", "")
+        tokens.setdefault(without_variation_selector, gitmoji)
+    return tuple(sorted(tokens.items(), key=lambda item: len(item[0]), reverse=True))
+
+
+def match_gitmoji(text: str) -> GitmojiMatch | None:
+    for token, gitmoji in _token_index():
+        if text.startswith(token) and len(text) > len(token) and text[len(token)].isspace():
+            return GitmojiMatch(gitmoji=gitmoji, token=token, remainder=text[len(token) :].lstrip())
+    return None
+
+
+def parse_gitmoji_commit(text: str) -> tuple[GitmojiCommit | None, ParseIssue | None]:
+    """Parse the official gitmoji title form and an optional Git body."""
+
+    lines = text.splitlines()
+    if not lines or not lines[0]:
+        return None, ParseIssue("empty-message", "The commit message is empty.")
+    match = match_gitmoji(lines[0])
+    if match is None:
+        return None, ParseIssue(
+            "invalid-gitmoji",
+            "Expected an official gitmoji Unicode token or shortcode.",
+        )
+
+    remainder = match.remainder
+    scope: str | None = None
+    if remainder.startswith("("):
+        closing = remainder.find(")")
+        if closing <= 1:
+            return None, ParseIssue("invalid-gitmoji-scope", "The gitmoji scope must be non-empty.")
+        scope = remainder[1:closing]
+        remainder = remainder[closing + 1 :]
+        if remainder.startswith(":"):
+            if len(remainder) == 1 or not remainder[1].isspace():
+                return None, ParseIssue(
+                    "invalid-gitmoji-separator",
+                    "A colon after the gitmoji scope must be followed by a space.",
+                )
+            remainder = remainder[1:]
+        elif not remainder or not remainder[0].isspace():
+            return None, ParseIssue(
+                "invalid-gitmoji-separator",
+                "The gitmoji scope and message must be separated by whitespace or ': '.",
+            )
+    elif remainder.startswith(":"):
+        if len(remainder) == 1 or not remainder[1].isspace():
+            return None, ParseIssue(
+                "invalid-gitmoji-separator",
+                "A gitmoji colon must be followed by a space.",
+            )
+        remainder = remainder[1:]
+    message = remainder.lstrip()
+    if not message:
+        return None, ParseIssue("missing-gitmoji-message", "The gitmoji message is required.")
+
+    if len(lines) > 1 and lines[1] != "":
+        return None, ParseIssue(
+            "missing-header-separator",
+            "The body must begin one blank line after the gitmoji message.",
+            line=2,
+        )
+    body = "\n".join(lines[2:]).strip() if len(lines) > 2 else ""
+    return GitmojiCommit(
+        intention=match.gitmoji,
+        token=match.token,
+        scope=scope,
+        message=message,
+        body=body or None,
+    ), None

zendev_commit-0.2.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: zendev-commit
+Version: 0.2.0
+Summary: Commit-message conventions and interactive commit workflows
+Project-URL: Homepage, https://github.com/zendev-lab/zendev
+Project-URL: Issues, https://github.com/zendev-lab/zendev/issues
+Project-URL: Repository, https://github.com/zendev-lab/zendev
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: questionary>=2.1
+Requires-Dist: typer>=0.27
+Description-Content-Type: text/markdown
+
+# zendev-commit
+
+`zendev-commit` owns commit profiles, Conventional Commits and Gitmoji
+validation, the interactive commit flow, and its vendored data. It can be
+installed and used without the complete `zendev` toolkit.
+
+```console
+$ uv add --dev zendev-commit
+$ uvx --from zendev-commit zendev-commit --help
+$ uvx --from zendev-commit zendev-commit-msg --help
+```
+
+`zendev-commit-msg` validates complete commit messages. `zendev-commit`
+interactively builds a message and invokes `git commit`.
+
+## Python API
+
+```python
+from zendev.commit import CommitProfile, validate_commit_message
+
+result = validate_commit_message(
+    "feat(parser): accept empty input",
+    profile=CommitProfile.CONVENTIONAL,
+)
+assert result.valid
+```
+
+## Profiles
+
+Configure the default profile in the consuming repository:
+
+```toml
+[tool.zendev.commit]
+profile = "conventional"
+```
+
+The `--profile` option overrides repository configuration. `auto` reads the
+nearest `pyproject.toml` and falls back to `zendev`.
+
+| Profile | Contract |
+| --- | --- |
+| `zendev` | A Gitmoji emoji or shortcode paired with its canonical commit type. |
+| `conventional` | Conventional Commits 1.0.0, including scopes, breaking changes, bodies, and footers. |
+| `gitmoji` | The Gitmoji title shape with Unicode or shortcode intentions and optional scope/body. |
+
+Examples accepted by the default profile:
+
+```text
+🎉 init: begin a project
+✨ feat: add export
+🐛 fix(parser): handle null token
+:memo: docs: update README
+🚀 deploy: publish the package
+```
+
+Git-generated `Merge`, `Revert`, `fixup!`, `squash!`, `amend!`, and `reword!`
+messages are accepted.
+
+## Commit hook
+
+With `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/zendev-lab/zendev
+    rev: v0.1.0
+    hooks:
+      - id: zendev-commit-msg
+```
+
+With `prek.toml`:
+
+```toml
+[[repos]]
+repo = "https://github.com/zendev-lab/zendev"
+rev = "v0.1.0"
+hooks = [
+  { id = "zendev-commit-msg" },
+]
+```
+
+Install the Git hook:
+
+```console
+$ uvx prek install --hook-type commit-msg
+```
+
+An explicit command is also available:
+
+```console
+$ uvx --from zendev-commit zendev-commit-msg --profile conventional .git/COMMIT_EDITMSG
+```
+
+## Gitmoji data
+
+The default profile uses the vendored catalog in
+[`src/zendev/data/gitmojis.json`](./src/zendev/data/gitmojis.json) and the
+reviewable pairing table in
+[`src/zendev/data/emoji-conventions.toml`](./src/zendev/data/emoji-conventions.toml).
+Validation is deterministic and does not access the network.
+
+The retained upstream license is in
+[`src/zendev/data/LICENSE.gitmoji`](./src/zendev/data/LICENSE.gitmoji).
+Maintainers should follow the
+[vendored-data procedure](../../CONTRIBUTING.md#vendored-gitmoji-data) when
+refreshing the catalog.

zendev_commit-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+zendev/commit/__init__.py,sha256=B46lCIchjlCFtZEu7wP8LQ7vIbzxYnmw6lAAmswmrzw,18458
+zendev/commit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zendev/conventional/__init__.py,sha256=2FrhUa9r8pLctJy_3E0XF9u0x3ztt19854Q49HBeWlI,4130
+zendev/conventional/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zendev/data/LICENSE.gitmoji,sha256=Rj862ib3jsO1Zs4S-gmYLmDl-MBubo3sHzK1WcT01aY,1075
+zendev/data/emoji-conventions.toml,sha256=yqdFA84-QxJtmfvjhaadLwqbozcyD9m2Z7YeyugirL4,1873
+zendev/data/gitmojis.json,sha256=t-8tSHnRPufn-Bd3hP_bAACC0fIvQmF_R_u7fK3yMWc,14924
+zendev/gitmoji/__init__.py,sha256=QCzrKJLOUBqUrmgQ7nlzrGnMMnWX9dXg3cdWZH_c33w,6239
+zendev/gitmoji/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zendev_commit-0.2.0.dist-info/METADATA,sha256=KPbCHZNTMQhp3FJSaTxSo6B7gSj4hwMD8DNcAQLgAtg,3182
+zendev_commit-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+zendev_commit-0.2.0.dist-info/entry_points.txt,sha256=BHU_xD0A8mJquP3qenSFeZiKG4horu78PzFES9kM0c4,97
+zendev_commit-0.2.0.dist-info/RECORD,,

zendev_commit-0.2.0.dist-info/WHEEL

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

zendev_commit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+zendev-commit = zendev.commit:main
+zendev-commit-msg = zendev.commit:hook_main