commit-shield 0.2.0__tar.gz

commit_shield-0.2.0/.commit-guard.toml.example

@@ -0,0 +1,84 @@
+# commit-guard configuration.
+#
+# Copy this file to `.commit-guard.toml` in your repository root, or move the
+# settings under a `[tool.commit-guard]` table in your `pyproject.toml`.
+#
+# Precedence, lowest to highest:
+#   built-in defaults  <  pyproject.toml  <  .commit-guard.toml  <  CLI flags
+#
+# Discovery walks upward from the current directory to the repository root, so
+# a package inside a monorepo can override the rules set at the top level.
+# Every setting below is optional; the value shown is the default.
+
+# ---------------------------------------------------------------------------
+# Commit message rules
+# ---------------------------------------------------------------------------
+
+# Allowed commit types. Replaces the default list entirely.
+types = [
+    "feat", "fix", "docs", "style", "refactor",
+    "perf", "test", "build", "ci", "chore", "revert",
+]
+
+# Allowed scopes, as in `feat(api): ...`. An empty list allows any scope.
+scopes = []
+
+# Require every commit to carry a scope. Setting this to true with an empty
+# `scopes` list is rejected, since it would reject every possible commit.
+require_scope = false
+
+# Maximum length of the header (the first line).
+max_header_len = 72
+
+# Minimum length of the subject, i.e. the text after `type(scope):`.
+subject_min_len = 3
+
+# Allow the subject to end with a period.
+allow_trailing_period = false
+
+# Maximum length of a body line. 0 disables the check. URLs, git trailers
+# (`Co-Authored-By:`), and indented or quoted lines are always exempt, since
+# those cannot be wrapped without breaking them.
+max_body_line_len = 0
+
+# Skip validation for messages git writes itself: merges, reverts, and the
+# fixup!/squash! markers used by interactive rebase.
+skip_merge_commits = true
+skip_prefixes = ["merge ", "revert ", "fixup!", "squash!", "amend!"]
+
+# ---------------------------------------------------------------------------
+# Staged file rules
+# ---------------------------------------------------------------------------
+
+# Maximum staged blob size, in megabytes.
+max_size_mb = 10.0
+
+# Paths matching any of these regexes are reported as sensitive. Setting this
+# key REPLACES the built-in list; to keep the defaults and add to them, use
+# `extra_sensitive_patterns` below instead.
+#
+# sensitive_patterns = [
+#     "(^|/)\.env($|\..*)",
+#     "(^|/).*\.(pem|pkcs12|pfx|p12|jks|keystore)$",
+#     "(^|/)id_(rsa|dsa|ed25519|ecdsa)($|\..*)",
+#     "(^|/).*(secret|password|credential)s?.*\.(json|ya?ml|txt|ini|cfg)$",
+#     "(^|/)\.(npmrc|pypirc|netrc)$",
+#     "(^|/)\.aws/credentials$",
+#     "(^|/).*\.key$",
+# ]
+
+# Patterns APPENDED to the built-in list. This is usually what you want.
+extra_sensitive_patterns = []
+
+# Paths that look sensitive but are safe to commit. Matched with shell-style
+# globs against both the full path and the file name; an entry ending in `/`
+# exempts a whole directory.
+allowlist = [
+    "*.example",
+    "*.sample",
+    "*.template",
+    "*.dist",
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+]

commit_shield-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: "🐛 Bug Report"
+description: File a bug report to help us improve commit-guard.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report an issue!
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Run command 'commit-guard check ...'
+        2. With config '...'
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS version, Python version, commit-guard version
+      placeholder: Ubuntu 24.04 / macOS Sonoma / Windows 11, Python 3.12, commit-guard v0.2.0

commit_shield-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: "💡 Feature Request"
+description: Suggest an idea or feature enhancement for commit-guard.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We welcome feature requests and ideas from the community!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: Is your feature request related to a problem or limitation?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: A clear and concise description of what you want to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative solutions or features you've considered.

commit_shield-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+## Description
+<!-- Briefly describe what this PR does, why it is needed, and link any related issues. -->
+Fixes #
+
+## Type of Change
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] 📝 Documentation update
+- [ ] 🧪 Tests / CI improvement
+- [ ] ⚡ Performance improvement
+
+## Checklist
+- [ ] My code adheres to the project's zero-external-dependency rule for runtime code.
+- [ ] I have added unit tests that prove my fix is effective or that my feature works.
+- [ ] All tests pass locally with `python -m unittest discover -s tests`.
+- [ ] Code is formatted and typed properly.
+- [ ] I have updated relevant documentation if applicable.

commit_shield-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Tests (${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        include:
+          # setup-python no longer ships 3.8 for ubuntu-latest (24.04), so the
+          # oldest supported interpreter is pinned to 22.04.
+          - os: ubuntu-22.04
+            python-version: "3.8"
+          # commit-guard writes git hooks and manipulates paths, so Windows is
+          # exercised at both ends of the supported range.
+          - os: windows-latest
+            python-version: "3.8"
+          - os: windows-latest
+            python-version: "3.13"
+          - os: macos-latest
+            python-version: "3.13"
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Configure git identity
+      # The hook tests initialise throwaway repositories.
+      run: |
+        git config --global user.email "ci@example.com"
+        git config --global user.name "CI"
+        git config --global init.defaultBranch main
+
+    - name: Run unit tests (built-in unittest)
+      run: python -m unittest discover tests -v
+
+    - name: Test CLI execution
+      run: |
+        pip install .
+        commit-guard --version
+        commit-guard check-msg -m "feat(ci): test github actions workflow"
+
+  lint:
+    name: Lint and type-check
+    runs-on: ubuntu-latest
+    # Separate job on purpose: ruff and mypy are development tools only. They
+    # are installed here and never become runtime dependencies of the package.
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install lint tooling
+      run: pip install "ruff==0.6.9" "mypy==1.11.2"
+
+    - name: Ruff (lint)
+      run: ruff check commit_guard tests
+
+    - name: Ruff (format check)
+      run: ruff format --check commit_guard tests
+
+    - name: Mypy
+      run: mypy commit_guard
+
+  package:
+    name: Verify package builds
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Build sdist and wheel
+      run: |
+        pip install build
+        python -m build
+
+    - name: Check that the dynamic version resolves
+      # Guards against __version__ and the packaging metadata drifting apart.
+      run: |
+        pip install dist/*.whl
+        test "$(commit-guard --version)" = "commit-guard $(python -c 'import commit_guard; print(commit_guard.__version__)')"

commit_shield-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Build and upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install build tool
+      run: pip install build
+
+    - name: Build sdist and wheel
+      run: python -m build
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

commit_shield-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv
+venv/
+ENV/
+.env
+.pytest_cache/
+.ruff_cache/

commit_shield-0.2.0/.pre-commit-hooks.yaml

@@ -0,0 +1,14 @@
+- id: commit-guard-msg
+  name: commit-guard-msg
+  description: Validate commit message against Conventional Commits standard
+  entry: commit-guard check-msg
+  language: python
+  stages: [commit-msg]
+  always_run: true
+
+- id: commit-guard-files
+  name: commit-guard-files
+  description: Validate staged files for size and sensitive patterns
+  entry: commit-guard check-files --strict
+  language: python
+  stages: [pre-commit]

commit_shield-0.2.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-18
+
+The theme of this release is correctness and configurability. v0.1.0 validated
+the happy path; this release fixes the cases where it was wrong, and lets you
+change the rules without editing the source.
+
+### Added
+
+- **Configuration files.** Settings are read from `[tool.commit-guard]` in
+  `pyproject.toml` or from a standalone `.commit-guard.toml`. Discovery walks
+  upward from the current directory to the repository root, so a monorepo can
+  override rules per package. Precedence is: built-in defaults, then
+  `pyproject.toml`, then `.commit-guard.toml`, then CLI flags.
+- `--config PATH` to name a configuration file explicitly (disables discovery),
+  and `--no-config` to ignore configuration files entirely.
+- `-q` / `--quiet` on the validating subcommands, to suppress success output
+  while still reporting failures.
+- **`uninstall` subcommand**, which removes only hooks commit-guard installed
+  and restores any hook it previously backed up.
+- `install --force` to replace a hook owned by another tool, keeping the
+  original as `<hook>.bak`, and `install --msg-only` to skip the `pre-commit`
+  hook.
+- `install` now installs a `pre-commit` hook (`check-files --strict`) in
+  addition to `commit-msg`.
+- An allowlist for paths that look sensitive but are not: `*.example`,
+  `*.sample`, `*.template`, `*.dist` and friends are no longer flagged.
+- Configurable `scopes` with `require_scope`, `subject_min_len`,
+  `allow_trailing_period`, and an optional `max_body_line_len` body check that
+  exempts URLs, git trailers and indented or quoted lines.
+- An example `.commit-guard.toml.example` documenting every setting.
+
+### Fixed
+
+- **Merge, revert, fixup and squash commits no longer fail validation.** Git
+  generates these messages itself, so rejecting them made `git merge` and
+  interactive rebase unusable. Controlled by `skip_merge_commits` and
+  `skip_prefixes`.
+- **`install` no longer destroys an existing hook.** It now refuses to
+  overwrite a hook it does not own, names the framework that owns it
+  (pre-commit, husky, lefthook) in the message, and only replaces it with
+  `--force`, keeping a `.bak` copy.
+- **Git failures are no longer treated as "nothing to check".** v0.1.0 caught
+  every exception around git and returned success, so a broken repository or a
+  missing `git` silently passed the commit. Git errors now exit with code 2.
+- **File size is read from the staged blob, not the working tree.** Checking
+  the file on disk reported the wrong size whenever the working copy had moved
+  on from what was staged.
+- **Installed hooks call `sys.executable`, not a bare `python`.** The old hook
+  broke wherever the interpreter commit-guard was installed into was not first
+  on `PATH`, or was not named `python`.
+- `__version__` and the packaging metadata can no longer drift: the version is
+  single-sourced from `commit_guard/__init__.py` via Hatch.
+
+### Changed
+
+- **Exit code 2 now means "commit-guard could not do its job"**, as distinct
+  from exit code 1, "the commit is invalid". Exit code 0 still means success.
+  Scripts that only branch on zero/non-zero are unaffected.
+- Unknown keys in a configuration file are an error rather than a silent
+  no-op, so a typo such as `max_header_length` is reported instead of ignored.
+- An uppercase type (`Feat: ...`) now reports "type must be lowercase" instead
+  of the generic format error.
+
+### Compatibility
+
+- Public API from v0.1.0 is unchanged: `check_commit_message(msg,
+  max_header_len=...)` and `check_file_path(path, max_size_mb=...)` keep their
+  signatures, and `CONVENTIONAL_TYPES` is still exported. Both functions take
+  a new optional `config=` argument.
+- Still zero runtime dependencies, still `requires-python >= 3.8`. TOML is read
+  with `tomllib` on 3.11+ and with a small bundled parser below that.
+
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- Initial release: Conventional Commits validation, detection of sensitive
+  staged files and oversized blobs, a `commit-msg` hook installer, and
+  `pre-commit` framework integration.
+
+[0.2.0]: https://github.com/lui01212/commit-guard/releases/tag/v0.2.0
+[0.1.0]: https://github.com/lui01212/commit-guard/releases/tag/v0.1.0

commit_shield-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,114 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+luynbv@glotechvn.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+**Community Impact**: A violation through a single incident or series of
+actions.
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

commit_shield-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to commit-guard
+
+Welcome! We are excited to have you contribute to **commit-guard**.
+
+---
+
+## 🌟 Good First Issues
+
+Looking for your first contribution? Check our [open issues with label `good first issue`](https://github.com/lui01212/commit-guard/issues?q=is%3Aissue+state%3Aopen+label%3A%22good+first+issue%22). Common beginner tasks include:
+- Adding new sensitive file patterns to `commit_guard/checkers.py`.
+- Adding unit test cases for edge-case commit messages.
+- Improving documentation or translation of error messages.
+
+---
+
+## 🛠️ Development Setup
+
+1. **Fork and clone:**
+   ```bash
+   git clone https://github.com/<your-username>/commit-guard.git
+   cd commit-guard
+   ```
+
+2. **Zero-dependency philosophy:**
+   This project relies exclusively on Python standard libraries! No heavy third-party packages are required.
+
+3. **Running tests:**
+   Run the test suite using Python's built-in `unittest`:
+   ```bash
+   python -m unittest discover tests
+   ```
+
+4. **Making changes:**
+   - Create a branch: `git checkout -b feature/your-feature-name`
+   - Write tests for your changes in `tests/test_checkers.py`.
+   - Run tests to ensure everything passes: `python -m unittest`
+   - Commit with Conventional Commits: `git commit -m "feat(checker): add regex check for api keys"`
+   - Push and open a Pull Request!

commit_shield-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lui01212
+
+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.