mailmap-checker 0.1.0__tar.gz

mailmap_checker-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: uv sync
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: uv sync
+      - run: uv run bandit -r src
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest --cov --cov-report=term-missing
+
+  commitlint:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npm install @commitlint/cli @commitlint/config-conventional
+      - run: >
+          npx commitlint
+          --from ${{ github.event.pull_request.base.sha }}
+          --to ${{ github.event.pull_request.head.sha }}

mailmap_checker-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - run: uv build
+      - run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_PASSWORD }}

mailmap_checker-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+venv/
+.venv/
+*.egg
+.eggs/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+node_modules/
+uv.lock

mailmap_checker-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.8.3
+    hooks:
+      - id: bandit
+        args: [-r, src]
+
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.21.0
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies:
+          - "@commitlint/config-conventional"

mailmap_checker-0.1.0/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: mailmap-check
+  name: Check .mailmap completeness
+  description: Detect unmapped Git identities by comparing .mailmap against the full commit history.
+  entry: mailmap-checker check
+  language: python
+  always_run: true
+  pass_filenames: false
+  stages: [pre-commit]

mailmap_checker-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-04-02
+
+### Added
+
+- `check` command — scans Git history and exits non-zero when unmapped identities are found.
+- `init` command — creates a `.mailmap` file and runs a full check.
+- `fix` command — generates suggested `.mailmap` entries (`--dry-run` to preview).
+- Identity grouping via Union-Find: same email (case-insensitive) and same email local-part across domains.
+- Pre-commit hook integration (`mailmap-check`).
+
+[0.1.0]: https://github.com/cansarigol/mailmap-checker/releases/tag/v0.1.0

mailmap_checker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Sarigol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mailmap_checker-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: mailmap-checker
+Version: 0.1.0
+Summary: Pre-commit hook that checks and maintains .mailmap completeness
+Project-URL: Repository, https://github.com/cansarigol/mailmap-checker
+Project-URL: Changelog, https://github.com/cansarigol/mailmap-checker/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/cansarigol/mailmap-checker/issues
+Author-email: Can Sarigol <ertugrulsarigol@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: deduplication,git,identity,mailmap,pre-commit
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mailmap-checker
+
+[![PyPI version](https://img.shields.io/pypi/v/mailmap-checker)](https://pypi.org/project/mailmap-checker/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mailmap-checker)](https://pypi.org/project/mailmap-checker/)
+[![CI](https://github.com/cansarigol/mailmap-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/cansarigol/mailmap-checker/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A pre-commit hook that detects unmapped Git identities by comparing your `.mailmap` against the full commit history. It groups authors by email address and email local-part so duplicates are caught even across domain changes.
+
+## How it works
+
+The checker scans `git log` for all unique author identities and groups them using two rules:
+
+**Rule 1 — Same email (case-insensitive)**
+
+Identities that share the exact same email address are the same person.
+
+```
+Alice Johnson <alice@acme.com>
+alice.j       <alice@acme.com>   ← same email, grouped together
+```
+
+**Rule 2 — Same email local-part (different domain)**
+
+Identities whose email local-part (the part before `@`) matches are likely the same person who changed companies or used a different address.
+
+```
+Alice Johnson <alice.johnson@acme.com>
+Alice Johnson <alice.johnson@oldcorp.com>    ← same local-part, grouped
+Alice J       <alice.johnson@personal.net>   ← same local-part, grouped
+```
+
+Once groups are built, the checker looks for identities that are **not mapped** in `.mailmap`. If a group has more than one identity and any of them is missing from the file, the hook fails and reports the gap.
+
+### Example
+
+Given these three identities in git history and an empty `.mailmap`:
+
+```
+Alice Johnson <alice.johnson@acme.com>
+Alice Johnson <alice.johnson@oldcorp.com>
+Alice J       <alice.johnson@personal.net>
+```
+
+`mailmap-checker check` detects the gap:
+
+```
+Found 2 unmapped identities in 1 group:
+
+  Canonical: Alice J <alice.johnson@personal.net>
+    - Alice Johnson <alice.johnson@acme.com>
+    - Alice Johnson <alice.johnson@oldcorp.com>
+```
+
+`mailmap-checker fix --dry-run` suggests entries to add:
+
+```
+Suggested .mailmap entries:
+
+  Alice J <alice.johnson@personal.net> Alice Johnson <alice.johnson@acme.com>
+  Alice J <alice.johnson@personal.net> Alice Johnson <alice.johnson@oldcorp.com>
+```
+
+> **Note:** When no `.mailmap` exists, the tool picks the alphabetically first identity as the canonical. In this case it chose `Alice J <alice.johnson@personal.net>`, but the actual preferred identity is likely `Alice Johnson <alice.johnson@acme.com>`. The `.mailmap` format places the canonical (left) and the alias (right) on each line. After running `fix`, open `.mailmap` and swap the canonical if needed:
+>
+> ```
+> Alice Johnson <alice.johnson@acme.com> Alice Johnson <alice.johnson@oldcorp.com>
+> Alice Johnson <alice.johnson@acme.com> Alice J <alice.johnson@personal.net>
+> ```
+
+## Installation
+
+### Pre-commit hook (recommended)
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/cansarigol/mailmap-checker
+    rev: ""  # run: pre-commit autoupdate
+    hooks:
+      - id: mailmap-check
+```
+
+Then run `pre-commit autoupdate` to pin the latest release.
+
+### Standalone
+
+```bash
+pip install mailmap-checker
+```
+
+## Usage
+
+### `check`
+
+Scan all Git authors and exit non-zero if any identity is missing from `.mailmap`.
+
+```bash
+mailmap-checker check
+```
+
+### `init`
+
+Create a `.mailmap` file (if it does not exist) and run a full check.
+
+```bash
+mailmap-checker init
+```
+
+### `fix`
+
+Preview or apply suggested `.mailmap` entries.
+
+```bash
+# Preview
+mailmap-checker fix --dry-run
+
+# Apply
+mailmap-checker fix
+```
+
+All commands accept `--mailmap <path>` to use a custom file path.
+
+## Contributing
+
+```bash
+git clone https://github.com/cansarigol/mailmap-checker.git
+cd mailmap-checker
+uv sync
+uv run poe setup   # installs pre-commit and commit-msg hooks
+uv run poe check    # lint + security + tests
+```
+
+Commits must follow [Conventional Commits](https://www.conventionalcommits.org/) with a required scope (e.g. `feat(cli): add --verbose flag`).
+
+## License
+
+[MIT](LICENSE)

mailmap_checker-0.1.0/README.md

@@ -0,0 +1,138 @@
+# mailmap-checker
+
+[![PyPI version](https://img.shields.io/pypi/v/mailmap-checker)](https://pypi.org/project/mailmap-checker/)
+[![Python versions](https://img.shields.io/pypi/pyversions/mailmap-checker)](https://pypi.org/project/mailmap-checker/)
+[![CI](https://github.com/cansarigol/mailmap-checker/actions/workflows/ci.yml/badge.svg)](https://github.com/cansarigol/mailmap-checker/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A pre-commit hook that detects unmapped Git identities by comparing your `.mailmap` against the full commit history. It groups authors by email address and email local-part so duplicates are caught even across domain changes.
+
+## How it works
+
+The checker scans `git log` for all unique author identities and groups them using two rules:
+
+**Rule 1 — Same email (case-insensitive)**
+
+Identities that share the exact same email address are the same person.
+
+```
+Alice Johnson <alice@acme.com>
+alice.j       <alice@acme.com>   ← same email, grouped together
+```
+
+**Rule 2 — Same email local-part (different domain)**
+
+Identities whose email local-part (the part before `@`) matches are likely the same person who changed companies or used a different address.
+
+```
+Alice Johnson <alice.johnson@acme.com>
+Alice Johnson <alice.johnson@oldcorp.com>    ← same local-part, grouped
+Alice J       <alice.johnson@personal.net>   ← same local-part, grouped
+```
+
+Once groups are built, the checker looks for identities that are **not mapped** in `.mailmap`. If a group has more than one identity and any of them is missing from the file, the hook fails and reports the gap.
+
+### Example
+
+Given these three identities in git history and an empty `.mailmap`:
+
+```
+Alice Johnson <alice.johnson@acme.com>
+Alice Johnson <alice.johnson@oldcorp.com>
+Alice J       <alice.johnson@personal.net>
+```
+
+`mailmap-checker check` detects the gap:
+
+```
+Found 2 unmapped identities in 1 group:
+
+  Canonical: Alice J <alice.johnson@personal.net>
+    - Alice Johnson <alice.johnson@acme.com>
+    - Alice Johnson <alice.johnson@oldcorp.com>
+```
+
+`mailmap-checker fix --dry-run` suggests entries to add:
+
+```
+Suggested .mailmap entries:
+
+  Alice J <alice.johnson@personal.net> Alice Johnson <alice.johnson@acme.com>
+  Alice J <alice.johnson@personal.net> Alice Johnson <alice.johnson@oldcorp.com>
+```
+
+> **Note:** When no `.mailmap` exists, the tool picks the alphabetically first identity as the canonical. In this case it chose `Alice J <alice.johnson@personal.net>`, but the actual preferred identity is likely `Alice Johnson <alice.johnson@acme.com>`. The `.mailmap` format places the canonical (left) and the alias (right) on each line. After running `fix`, open `.mailmap` and swap the canonical if needed:
+>
+> ```
+> Alice Johnson <alice.johnson@acme.com> Alice Johnson <alice.johnson@oldcorp.com>
+> Alice Johnson <alice.johnson@acme.com> Alice J <alice.johnson@personal.net>
+> ```
+
+## Installation
+
+### Pre-commit hook (recommended)
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/cansarigol/mailmap-checker
+    rev: ""  # run: pre-commit autoupdate
+    hooks:
+      - id: mailmap-check
+```
+
+Then run `pre-commit autoupdate` to pin the latest release.
+
+### Standalone
+
+```bash
+pip install mailmap-checker
+```
+
+## Usage
+
+### `check`
+
+Scan all Git authors and exit non-zero if any identity is missing from `.mailmap`.
+
+```bash
+mailmap-checker check
+```
+
+### `init`
+
+Create a `.mailmap` file (if it does not exist) and run a full check.
+
+```bash
+mailmap-checker init
+```
+
+### `fix`
+
+Preview or apply suggested `.mailmap` entries.
+
+```bash
+# Preview
+mailmap-checker fix --dry-run
+
+# Apply
+mailmap-checker fix
+```
+
+All commands accept `--mailmap <path>` to use a custom file path.
+
+## Contributing
+
+```bash
+git clone https://github.com/cansarigol/mailmap-checker.git
+cd mailmap-checker
+uv sync
+uv run poe setup   # installs pre-commit and commit-msg hooks
+uv run poe check    # lint + security + tests
+```
+
+Commits must follow [Conventional Commits](https://www.conventionalcommits.org/) with a required scope (e.g. `feat(cli): add --verbose flag`).
+
+## License
+
+[MIT](LICENSE)

mailmap_checker-0.1.0/commitlint.config.js

@@ -0,0 +1,11 @@
+module.exports = {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'scope-empty': [2, 'never'],
+    'type-enum': [
+      2,
+      'always',
+      ['feat', 'fix', 'docs', 'perf', 'test', 'build', 'ci', 'chore', 'revert', 'sec', 'refactor'],
+    ],
+  },
+};

mailmap_checker-0.1.0/pyproject.toml

@@ -0,0 +1,117 @@
+[project]
+name = "mailmap-checker"
+version = "0.1.0"
+description = "Pre-commit hook that checks and maintains .mailmap completeness"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Can Sarigol", email = "ertugrulsarigol@gmail.com" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+keywords = ["git", "mailmap", "pre-commit", "identity", "deduplication"]
+
+[project.scripts]
+mailmap-checker = "mailmap_checker.cli:main"
+
+[project.urls]
+Repository = "https://github.com/cansarigol/mailmap-checker"
+Changelog = "https://github.com/cansarigol/mailmap-checker/blob/main/CHANGELOG.md"
+Issues = "https://github.com/cansarigol/mailmap-checker/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailmap_checker"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=6.0",
+    "ruff>=0.11",
+    "bandit>=1.8",
+    "poethepoet>=0.34",
+    "pre-commit>=4.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "C4",
+    "PIE",
+    "FURB",
+    "PERF",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["mailmap_checker"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+[tool.bandit]
+targets = ["src"]
+
+[tool.poe]
+env = { UV_PROJECT_ENVIRONMENT = "venv" }
+
+[tool.poe.tasks.setup]
+help = "Install git hooks (run once after cloning)"
+sequence = [
+    { cmd = "pre-commit install" },
+    { cmd = "pre-commit install --hook-type commit-msg" },
+]
+
+[tool.poe.tasks.lint]
+help = "Run ruff linter and format check"
+sequence = [
+    { cmd = "ruff check src tests" },
+    { cmd = "ruff format --check src tests" },
+]
+
+[tool.poe.tasks.format]
+help = "Format code with ruff"
+cmd = "ruff format src tests"
+
+[tool.poe.tasks.test]
+help = "Run tests with coverage"
+cmd = "pytest --cov --cov-report=term-missing"
+
+[tool.poe.tasks.security]
+help = "Run bandit security checks"
+cmd = "bandit -r src"
+
+[tool.poe.tasks.check]
+help = "Run all checks (lint + security + test)"
+sequence = [
+    { ref = "lint" },
+    { ref = "security" },
+    { ref = "test" },
+]

mailmap_checker-0.1.0/src/mailmap_checker/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"