ferro-orm 0.11.0__tar.gz → 0.12.0__tar.gz

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/.github/PERMISSIONS.md

@@ -133,12 +133,12 @@ permissions:
 
 **Why These Permissions:**
 - `pages: write` - Allows the workflow to:
-  - Deploy the generated MkDocs static site to GitHub Pages
+  - Deploy the generated Zensical static site to GitHub Pages
   - Update the Pages deployment for the repository
 - `id-token: write` - Allows secure OIDC auth for Pages deployment
 
 **What It Does:**
-- Builds MkDocs docs
+- Builds Zensical docs
 - Deploys docs to GitHub Pages
 
 ---

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/.github/pull_request_template.md

@@ -33,4 +33,12 @@
 
 ## Related Issues
 
-<!-- Example: Closes #123 -->
+- Closes #
+- Closes #
+
+<!-- Use one line per completed issue: Closes #123 / Fixes #123 / Resolves #123 -->
+
+## Exit Steps
+
+- [ ] Related completed issues are linked above with Closes/Fixes/Resolves
+- [ ] Issue statuses are updated/auto-close on merge

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/.github/workflows/ci.yml

@@ -3,9 +3,9 @@ name: CI
 on:
   workflow_call:
   pull_request:
-    branches: [main]
+    branches: [main, feat/ir-first]
   push:
-    branches: [main]
+    branches: [main, feat/ir-first]
   workflow_dispatch:
 
 concurrency:
@@ -16,6 +16,33 @@ permissions:
   contents: read
 
 jobs:
+  changed-shadow-paths:
+    name: Detect Shadow-Report Paths
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    outputs:
+      requires_shadow_reports: ${{ steps.filter.outputs.shadow }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Detect planner/IR path changes
+        id: filter
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            shadow:
+              - 'src/operations.rs'
+              - 'src/query.rs'
+              - 'src/schema.rs'
+              - 'src/migrate.rs'
+              - 'src/backend.rs'
+              - 'src/connection.rs'
+              - 'src/ferro/ir/**'
+              - 'crates/ferro-schema-ir/**'
+              - 'tests/test_shadow_reports.py'
+              - 'tests/fixtures/shadow_reports/**'
+
   lint-and-format:
     name: Lint & Format (Pre-commit / Prek)
     runs-on: ubuntu-latest
@@ -126,6 +153,10 @@ jobs:
         run: |
           uv run maturin develop
 
+      - name: Run IR vector contract harness
+        run: |
+          uv run pytest -v tests/test_ir_vectors_contract.py
+
       - name: Run pytest
         run: |
           uv run pytest -v --cov=src --cov-report=xml --cov-report=term
@@ -169,6 +200,10 @@ jobs:
         run: |
           uv run maturin develop
 
+      - name: Run IR vector contract harness
+        run: |
+          uv run pytest -v tests/test_ir_vectors_contract.py
+
       - name: Run pytest
         run: |
           uv run pytest -v --cov=src --cov-report=xml --cov-report=term
@@ -236,6 +271,64 @@ jobs:
         run: |
           uv run pytest -v -m "backend_matrix or postgres_only" --db-backends=sqlite,postgres
 
+  test-shadow-reports-pr:
+    name: Shadow reports (touched paths)
+    runs-on: ubuntu-latest
+    needs: [changed-shadow-paths]
+    if: github.event_name == 'pull_request' && needs.changed-shadow-paths.outputs.requires_shadow_reports == 'true'
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: ferro
+          POSTGRES_PASSWORD: ferro
+          POSTGRES_DB: ferro
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U ferro -d ferro"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      FERRO_SUPABASE_URL: postgresql://ferro:ferro@127.0.0.1:5432/ferro?sslmode=disable
+      FERRO_SHADOW_RUNTIME: "1"
+      FERRO_SHADOW_RUNTIME_STRICT: "1"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install UV
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust build
+        uses: Swatinem/rust-cache@v2
+        with:
+          prefix-key: v1
+          cache-on-failure: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --only-group ci-test --no-install-project --python 3.13
+
+      - name: Build Rust extension
+        run: |
+          uv run maturin develop
+
+      - name: Verify stable shadow reports
+        run: |
+          uv run pytest -v tests/test_shadow_reports.py::test_shadow_report_fixture_stable --db-backends=sqlite,postgres
+
   check-conventional-commits:
     name: Check Conventional Commits
     runs-on: ubuntu-latest
@@ -285,7 +378,7 @@ jobs:
 
   all-checks:
     name: All Checks Passed
-    needs: [lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-rust]
+    needs: [changed-shadow-paths, lint-and-format, test-python-pr, test-python-main, test-python-backend-matrix, test-shadow-reports-pr, test-rust]
     runs-on: ubuntu-latest
     if: always()
     steps:
@@ -294,10 +387,15 @@ jobs:
         run: |
           ok() { [[ "$1" == "success" || "$1" == "skipped" ]]; }
 
+          if [[ "${{ needs.changed-shadow-paths.result }}" == "failure" ]]; then
+            echo "Shadow path detection failed; refusing to treat shadow gate as passed."
+            exit 1
+          fi
           if ! ok "${{ needs.lint-and-format.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-pr.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-main.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-python-backend-matrix.result }}"; then exit 1; fi
+          if ! ok "${{ needs.test-shadow-reports-pr.result }}"; then exit 1; fi
           if ! ok "${{ needs.test-rust.result }}"; then exit 1; fi
 
           echo "All checks passed!"

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/.github/workflows/publish-docs.yml

@@ -18,7 +18,7 @@ permissions:
 
 jobs:
   build-docs:
-    name: Build docs (MkDocs)
+    name: Build docs (Zensical)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -40,9 +40,9 @@ jobs:
         run: |
           uv sync --only-group docs --no-install-project --python 3.13
 
-      - name: Build MkDocs site
+      - name: Build Zensical site
         run: |
-          uv run --no-sync mkdocs build
+          uv run --no-sync zensical build --clean
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/.gitignore

@@ -189,7 +189,7 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
-# mkdocs documentation
+# zensical documentation
 /site
 
 # mypy

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/AGENTS.md

@@ -190,3 +190,89 @@ What this means in practice:
 
 This rule binds human contributors and AI agents equally, and overrides any
 agent default that biases toward minimal or expedient changes.
+
+---
+
+## I-8: Docs examples show both field-declaration styles
+
+Ferro supports two equivalent ways to declare model fields: assignment
+(`name: str = Field(unique=True)`) and `Annotated` metadata
+(`name: Annotated[str, Field(unique=True)]`). Every documentation example
+that declares model fields with `Field()`/`FerroField()` options must show
+**both** styles, side by side, as content tabs:
+
+    === "Assignment"
+
+        ```python
+        --8<-- "docs/examples/<example>.py:models"
+        ```
+
+    === "Annotated"
+
+        ```python
+        --8<-- "docs/examples/<example>_annotated.py:models"
+        ```
+
+Rules:
+
+- Both tabs must be backed by real, runnable code. Snippet-embedded model
+  definitions get a runnable `<name>_annotated.py` companion in
+  `docs/examples/` (exercised by `tests/test_docs_examples.py`); inline
+  blocks are written in both styles and compile-checked by the same test.
+- Constructs with only one valid form appear identically in both tabs and
+  are not tabbed on their own: forward FKs are always
+  `Annotated[Target, ForeignKey(...)]`, and `BackRef()` / `ManyToMany()`
+  are always assignments.
+- Code blocks that do not declare fields (queries, mutations, transactions,
+  usage snippets) are not affected by this rule.
+
+This keeps users from ever wondering whether something is possible in their
+preferred declaration style.
+
+---
+
+## I-9: Lambda predicates are the official query style
+
+Documentation and examples use the lambda predicate style for all queries:
+
+```python
+adults = await User.where(lambda t: t.age >= 18).all()
+```
+
+Rules:
+
+- **Every query example** in docs, docstring `Examples:` sections, and
+  `docs/examples/` scripts uses lambda predicates.
+- When the predicate styles themselves are documented, present them in
+  order **lambda > `col()` > operator**, with lambda labeled the officially
+  recommended style.
+- **Operator style** (`User.where(User.age >= 18)`) is compatible today but
+  is slated for deprecation in a future release and fails static type
+  checking (`User.age >= 18` types as `bool`; `where()` expects
+  `QueryNode | Predicate`). Docs say so explicitly wherever the style is
+  shown.
+- **`order_by` is not a predicate** and keeps attribute style
+  (`order_by(User.age, "desc")`). Passing a lambda to `order_by` silently
+  produces a junk column name — never show it.
+
+The canonical comparisons live in `docs/pages/guide/queries.md`
+("Predicate Styles") and `docs/pages/concepts/query-typing.md`; everywhere
+else uses lambda without restating the trade-offs.
+
+---
+
+## I-10: PRs must close scoped issues explicitly
+
+Issue closure is part of feature completion, not optional cleanup.
+
+Rules:
+
+- Every PR that completes scoped work **must** include GitHub auto-close
+  keywords in the PR body for each completed issue, e.g.
+  `Closes #89`, `Fixes #90`, `Resolves #91`.
+- Do not rely on manual post-merge issue triage when the work is already done
+  in the PR; encode closure directly in the PR body.
+- PRs must include an explicit exit-steps checklist item confirming issue status
+  updates are complete before merge.
+- AI agents and human contributors follow the same requirement. If issue status
+  closure is missing, the PR is not done.

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/CHANGELOG.md

@@ -1,6 +1,20 @@
 # CHANGELOG
 
 
+## v0.12.0 (2026-06-23)
+
+### Documentation
+
+- Rewrite site on Zensical with runnable examples
+  ([#70](https://github.com/syn54x/ferro-orm/pull/70),
+  [`da86911`](https://github.com/syn54x/ferro-orm/commit/da869118c55314363139a021c139a52a2bc8d1fb))
+
+### Features
+
+- IR-first architecture program (Phases 0–7) ([#116](https://github.com/syn54x/ferro-orm/pull/116),
+  [`1c22857`](https://github.com/syn54x/ferro-orm/commit/1c228577aa663c4630a5c8a33f0bb000ebe288b2))
+
+
 ## v0.11.0 (2026-06-11)
 
 ### Chores

{ferro_orm-0.11.0 → ferro_orm-0.12.0}/CONTRIBUTING.md

@@ -37,7 +37,7 @@ This will install all development dependencies including:
 - Testing tools (pytest, pytest-asyncio, pytest-cov)
 - Linting and formatting tools (ruff, prek)
 - Build tools (maturin)
-- Documentation tools (mkdocs-material)
+- Documentation tools (zensical)
 - Release tools (commitizen, python-semantic-release)
 
 ### 3. Install Pre-commit Hooks
@@ -102,10 +102,10 @@ cargo clippy               # Rust linting
 
 ```bash
 # Serve documentation locally (with live reload)
-uv run mkdocs serve
+uv run zensical serve
 
 # Build documentation
-uv run mkdocs build
+uv run zensical build
 
 # Documentation will be available at http://127.0.0.1:8000/
 ```