ormguard 0.1.0__tar.gz

ormguard-0.1.0/.coderabbit.yaml

@@ -0,0 +1,18 @@
+# CodeRabbit configuration — https://docs.coderabbit.ai/reference/configuration
+# AI code review runs via the CodeRabbit GitHub App (install at
+# https://github.com/apps/coderabbitai). No API key or workflow needed.
+language: en-US
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  poem: false
+  review_status: true
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - develop
+      - main
+chat:
+  auto_reply: true

ormguard-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Report incorrect behavior in ormguard
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: Thanks for filing a bug. Please fill in the details below so it can be reproduced.
+  - type: input
+    id: version
+    attributes:
+      label: ormguard version
+      placeholder: "e.g. 0.1.0  (pip show ormguard)"
+    validations:
+      required: true
+  - type: input
+    id: python
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.11"
+    validations:
+      required: true
+  - type: input
+    id: sqlalchemy
+    attributes:
+      label: SQLAlchemy version
+      placeholder: "e.g. 2.0.30"
+    validations:
+      required: true
+  - type: input
+    id: database
+    attributes:
+      label: Database / driver
+      placeholder: "e.g. PostgreSQL 16 (psycopg), SQLite"
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: Model definition plus how you invoke ormguard.
+      render: python
+  - type: textarea
+    id: output
+    attributes:
+      label: ormguard output / traceback
+      render: shell

ormguard-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / discussion
+    url: https://github.com/gogo1414/ormguard/discussions
+    about: Ask usage questions and share ideas (enable Discussions in repo settings).

ormguard-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Suggest an idea or improvement for ormguard
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What are you trying to do that ormguard doesn't support today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

ormguard-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+## Related issue
+
+<!-- e.g. Closes #123 -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / internal
+- [ ] Docs
+- [ ] CI / tooling
+
+## Checklist
+
+- [ ] Tests pass locally (`pytest`)
+- [ ] Lint passes (`ruff check .`)
+- [ ] Added/updated tests for the change
+- [ ] Updated `CHANGELOG.md` under "Unreleased"
+- [ ] Updated docs / README if behavior changed

ormguard-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]

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

@@ -0,0 +1,112 @@
+name: CI
+
+on:
+  push:
+    branches: [develop, main]
+  pull_request:
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags to compute the version
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Unit tests (SQLite, no external DB)
+        run: pytest -q
+      - name: Self-check smoke test
+        run: python -m ormguard --selfcheck --warn-only # selfcheck intentionally finds drift; --warn-only keeps exit 0
+
+  postgres:
+    name: integration (postgres)
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: ormguard
+          POSTGRES_PASSWORD: ormguard
+          POSTGRES_DB: ormguard_test
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags to compute the version
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" "psycopg[binary]"
+      - name: Integration tests (real Postgres)
+        env:
+          DATABASE_URL: postgresql+psycopg://ormguard:ormguard@localhost:5432/ormguard_test
+        run: pytest -q -m postgres
+
+  mysql:
+    name: integration (mysql)
+    runs-on: ubuntu-latest
+    services:
+      mysql:
+        image: mysql:8
+        env:
+          MYSQL_ROOT_PASSWORD: ormguard
+          MYSQL_DATABASE: ormguard_test
+          MYSQL_USER: ormguard
+          MYSQL_PASSWORD: ormguard
+        ports: ["3306:3306"]
+        options: >-
+          --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -pormguard"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags to compute the version
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" "PyMySQL"
+      - name: Integration tests (real MySQL)
+        env:
+          DATABASE_URL_MYSQL: mysql+pymysql://ormguard:ormguard@127.0.0.1:3306/ormguard_test
+        run: pytest -q -m mysql
+
+  # Posts to Slack/Discord only when CI fails AND the matching webhook secret
+  # exists — otherwise every step is skipped, so it stays dormant until set.
+  notify-failure:
+    name: Notify on failure
+    needs: [test, postgres, mysql]
+    if: failure()
+    runs-on: ubuntu-latest
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+      DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    steps:
+      - name: Slack notification
+        if: ${{ env.SLACK_WEBHOOK_URL != '' }}
+        run: |
+          curl -sf -X POST -H 'Content-type: application/json' \
+            --data "{\"text\":\":red_circle: ormguard CI failed on \`${{ github.ref_name }}\` — ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\"}" \
+            "$SLACK_WEBHOOK_URL"
+      - name: Discord notification
+        if: ${{ env.DISCORD_WEBHOOK_URL != '' }}
+        run: |
+          curl -sf -X POST -H 'Content-type: application/json' \
+            --data "{\"content\":\":red_circle: ormguard CI failed on \`${{ github.ref_name }}\` — ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\"}" \
+            "$DISCORD_WEBHOOK_URL"

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

@@ -0,0 +1,49 @@
+name: Release
+
+# Publish to PyPI when a version tag (vX.Y.Z) is pushed.
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored.
+# One-time setup: create the project on PyPI and add this repo as a
+# Trusted Publisher (workflow: release.yml, environment: pypi).
+# Until then this workflow is inert (it only runs on tag push).
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs derives the version from git tags
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ormguard
+    permissions:
+      id-token: write # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ormguard-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+*.db
+.DS_Store
+
+# Generated by hatch-vcs at build time (version derived from git tags)
+ormguard/_version.py

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

@@ -0,0 +1,17 @@
+# Dev hooks for this repo. Install with: pre-commit install
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ormguard-selfcheck
+        name: ormguard selfcheck
+        entry: python -m ormguard --selfcheck --warn-only
+        language: system
+        pass_filenames: false
+        always_run: true

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

@@ -0,0 +1,31 @@
+# Hooks that downstream projects can use by adding ormguard to their
+# .pre-commit-config.yaml:
+#
+#   - repo: https://github.com/gogo1414/ormguard
+#     rev: v0.1.0
+#     hooks:
+#       - id: ormguard
+#         args: ["--url", "sqlite:///app.db", "--metadata", "myapp.db:Base"]
+#
+# Or the zero-config smoke test:
+#
+#   - repo: https://github.com/gogo1414/ormguard
+#     rev: v0.1.0
+#     hooks:
+#       - id: ormguard-selfcheck
+
+- id: ormguard
+  name: ormguard schema validation
+  description: Validate that the database schema matches your SQLAlchemy models.
+  entry: ormguard
+  language: python
+  pass_filenames: false
+  always_run: true
+
+- id: ormguard-selfcheck
+  name: ormguard selfcheck
+  description: Run ormguard's self-contained SQLite demo (no database required).
+  entry: ormguard --selfcheck --warn-only
+  language: python
+  pass_filenames: false
+  always_run: true

ormguard-0.1.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to this project are documented here. 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/).
+
+## [Unreleased]
+
+### Fixed
+
+- CLI no longer crashes with `UnicodeEncodeError` on legacy consoles (e.g.
+  Windows cp949); stdout/stderr are reconfigured to UTF-8. (#12)
+
+### Documentation
+
+- Added a top-of-README "Quickstart (60 seconds)" with copy-paste install,
+  `--selfcheck`, FastAPI guard, and CI snippets. (#11)
+
+### Added
+
+- Optional enum validation (`Config(check_enums=True)`): emits `enum_mismatch`
+  when an enum column's allowed values differ between the ORM and the database
+  (native enums on Postgres/MySQL), naming the differing values. Opt-in, WARN,
+  and skipped when either side exposes no enum values. (#5)
+- Optional CHECK-constraint validation (`Config(check_constraints=True)`): emits
+  `check_missing` / `check_extra`, compared by constraint *name* only (the
+  expression text is dialect-rewritten on reflection, so it is not diffed);
+  unnamed constraints are skipped. Opt-in, WARN. (#5)
+- Webhook notifications: `--notify-webhook URL` (and `--notify-on error|any`)
+  POST the report to a Slack- or Discord-compatible incoming webhook when drift
+  is found — one payload works for both, standard library only, best-effort.
+  Also exposed as a `notify-webhook` input on the GitHub Action. (#22)
+- Reusable GitHub Action (`action.yml`): run ormguard in any repo's CI with a
+  few lines — inputs for `database-url`, `metadata`, extra `args`, install
+  `version`, and `python-version`. (#8)
+- Optional server-default validation (`Config(check_server_defaults=True)` /
+  `--check-defaults`): emits `default_missing` / `default_extra` by comparing
+  *presence* of a DB default (not its value, which is dialect-dependent),
+  skipping primary keys. Opt-in, defaults to WARN. (#4)
+- MySQL integration test + CI job (`mysql` marker) alongside the existing
+  Postgres one, covering the MySQL dialect's reflection. (#7)
+- Optional index validation (`Config(check_indexes=True)` / `--check-indexes`):
+  emits `index_missing` / `index_extra`, compared by column set + uniqueness,
+  skipping PK/unique-constraint-backed indexes. Opt-in, defaults to WARN. (#2)
+- Optional foreign-key validation (`Config(check_foreign_keys=True)` /
+  `--check-foreign-keys`): emits `fk_missing` / `fk_extra`, compared by local
+  columns + referred table + referred columns. Opt-in, defaults to WARN. (#3)
+
+- Contribution scaffolding: issue forms (bug / feature), PR template,
+  `CONTRIBUTING.md`, `CHANGELOG.md`, `CLAUDE.md`.
+- Dependabot for pip and GitHub Actions.
+- Release workflow: publishes to PyPI via Trusted Publishing on `v*` tags.
+- CodeRabbit AI code review on pull requests (via the CodeRabbit GitHub App,
+  configured by `.coderabbit.yaml`).
+- CI failure notifications to Slack/Discord (dormant until a webhook is set).
+- `pre-commit` hooks: `ormguard-selfcheck` and `ormguard` for downstream users,
+  plus a dev config (ruff + selfcheck).
+
+### Changed
+
+- `type_mismatch` now normalizes types per dialect before comparing — folds
+  `INT(11)`/`INTEGER`, `CHARACTER VARYING`/`VARCHAR`, `DOUBLE PRECISION`/`DOUBLE`,
+  `TINYINT(1)`/`BOOLEAN`, and `TIMESTAMP` spellings — so `check_types` produces
+  far fewer false positives (genuine length/precision/tz differences still
+  flagged). (#6)
+- Version is now derived from git tags via `hatch-vcs` (single source of truth);
+  removed the duplicated hardcoded version in `pyproject.toml` and
+  `ormguard/__init__.py`.
+
+## [0.1.0] - 2026-06
+
+### Added
+
+- Initial proof of concept: fail-fast schema validation for SQLAlchemy.
+- `validate`, `assert_schema`, `validate_many`, `format_matrix` public API.
+- FastAPI startup guard (`schema_guard_lifespan`).
+- CLI (`python -m ormguard`) with `--selfcheck`.
+- Checks: `table_missing`, `column_missing`, `column_extra`,
+  `nullable_mismatch`, opt-in `type_mismatch`.
+
+[Unreleased]: https://github.com/gogo1414/ormguard/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/gogo1414/ormguard/releases/tag/v0.1.0

ormguard-0.1.0/CLAUDE.md

@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and other AI assistants) working in this repo.
+
+## What ormguard is
+
+Fail-fast schema validation for SQLAlchemy — the equivalent of Hibernate's
+`hibernate.ddl-auto=validate`. At startup (or in CI) it reflects the connected
+database and checks that it matches the ORM entities, catching entity↔DB drift
+at boot instead of as a runtime `column does not exist` error.
+
+## Commands
+
+```bash
+python -m pip install -e ".[dev]"   # setup
+pytest                               # unit tests (SQLite, no external DB)
+ruff check .                         # lint (line-length 110)
+python -m ormguard --selfcheck       # self-contained end-to-end demo
+pytest -m postgres                   # integration tests (needs DATABASE_URL)
+```
+
+## Layout
+
+- `ormguard/core.py` — `validate()` / `assert_schema()` orchestration.
+- `ormguard/reflect.py` — reflect the live DB schema.
+- `ormguard/orm.py`, `ormguard/model.py` — read ORM metadata; `Finding`,
+  `Severity`, `ValidationReport`, `SchemaValidationError`.
+- `ormguard/diff.py` — compare reflected schema vs ORM, produce findings.
+- `ormguard/config.py` — `Config` (schemas, ignores, severity toggles).
+- `ormguard/cli.py` — `python -m ormguard` argument parsing.
+- `ormguard/selfcheck.py` — in-memory SQLite demo with deliberate drift.
+- `ormguard/integrations/` — framework hooks (e.g. FastAPI lifespan).
+- `tests/` — SQLite by default; `@pytest.mark.postgres` for real Postgres.
+- `docs/` — DESIGN.md, USAGE.md, V2_OFFLINE_REPLAY.md.
+
+## Conventions
+
+- Public API is what `ormguard/__init__.py` exports — keep it stable; note
+  breaking changes in `CHANGELOG.md`.
+- Support SQLAlchemy >= 1.4 and Python 3.9–3.12 (the CI matrix).
+- Type/dialect comparisons are dialect-sensitive — keep `type_mismatch` opt-in.
+- Version is derived from git tags via `hatch-vcs`; never hardcode a version.
+- Work on a branch and open a PR; do not push to `main` directly.
+- Add tests for behavior changes; `pytest` and `ruff check .` must pass.

ormguard-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to ormguard
+
+Thanks for your interest in improving ormguard! This project is small and
+welcomes issues and pull requests.
+
+## Development setup
+
+```bash
+git clone https://github.com/gogo1414/ormguard.git
+cd ormguard
+python -m pip install -e ".[dev]"
+```
+
+## Everyday commands
+
+```bash
+pytest                      # unit tests (in-memory SQLite, no external DB)
+ruff check .                # lint
+python -m ormguard --selfcheck   # end-to-end smoke test against SQLite drift
+```
+
+Postgres integration tests are opt-in (they need a real database):
+
+```bash
+export DATABASE_URL="postgresql+psycopg://user:pass@localhost:5432/db"
+pytest -m postgres
+```
+
+### Optional: pre-commit
+
+```bash
+pip install pre-commit
+pre-commit install          # runs ruff + selfcheck on every commit
+```
+
+## Pull request workflow
+
+1. Branch from `main` (`feat/...`, `fix/...`, `chore/...`).
+2. Make the change with tests. Keep the public API in `ormguard/__init__.py` stable.
+3. Add an entry to `CHANGELOG.md` under **Unreleased**.
+4. Open a PR — the template checklist covers tests, lint, and changelog.
+5. CI (Python 3.9–3.12 + Postgres integration) must pass before merge.
+
+Direct pushes to `main` are avoided; everything goes through a PR.
+
+## Versioning & releases
+
+Versions come from git tags via `hatch-vcs` — there is **no version string to
+edit by hand**. To cut a release:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The `Release` workflow builds the package and publishes it to PyPI via Trusted
+Publishing. We follow [Semantic Versioning](https://semver.org/).

ormguard-0.1.0/LICENSE

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