archetype-py 0.2.3__tar.gz → 0.3.0__tar.gz

{archetype_py-0.2.3 → archetype_py-0.3.0}/.github/workflows/archetype.yml

@@ -4,8 +4,13 @@ on:
   push:
     branches:
       - main
+    tags:
+      - "v*"
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   archetype:
     runs-on: ubuntu-latest
@@ -13,7 +18,11 @@ jobs:
     steps:
       # Pull down your repository code so CI can inspect it.
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+        with:
+          token: ${{ github.token }}
+          ref: ${{ github.ref }}
+          fetch-depth: 0
 
       # Install Python 3.11 so the Archetype CLI can run.
       - name: Set up Python
@@ -28,9 +37,15 @@ jobs:
           pip install archetype-py
 
       # Run architecture rules defined in architecture.py.
-      # This step exits non-zero on violations, which fails the workflow.
+      # If the installed Archetype supports GitHub annotations, emit inline
+      # PR annotations. Otherwise, fall back to standard checks.
       - name: Run architecture checks
-        run: archetype check .
+        run: |
+          if archetype check --help | grep -q -- '--github-annotations'; then
+            archetype check . --github-annotations
+          else
+            archetype check .
+          fi
 
       # If your team already runs pytest in CI, you can skip this workflow file.
       # Archetype's pytest plugin runs architecture.py rules automatically during pytest.

{archetype_py-0.2.3 → archetype_py-0.3.0}/.github/workflows/ci.yml

@@ -4,8 +4,13 @@ on:
   push:
     branches:
       - main
+    tags:
+      - "v*"
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
@@ -16,7 +21,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+        with:
+          token: ${{ github.token }}
+          ref: ${{ github.ref }}
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5

{archetype_py-0.2.3 → archetype_py-0.3.0}/.github/workflows/publish.yml

@@ -8,11 +8,17 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
 
     steps:
       # Checkout repository contents for test execution.
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+        with:
+          token: ${{ github.token }}
+          ref: ${{ github.ref }}
+          fetch-depth: 0
 
       # Install Python runtime used for tests and packaging checks.
       - name: Set up Python
@@ -40,7 +46,11 @@ jobs:
     steps:
       # Checkout repository contents so the package can be built.
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+        with:
+          token: ${{ github.token }}
+          ref: ${{ github.ref }}
+          fetch-depth: 0
 
       # Set up Python for building distribution artifacts.
       - name: Set up Python

{archetype_py-0.2.3 → archetype_py-0.3.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0 - 2026-05-26
+
+### Added
+- Git pre-commit hook integration via `archetype install-hook`.
+- GitHub PR inline annotations support with `--github-annotations`.
+- Baseline mode for legacy repositories via `--write-baseline` and `--baseline`.
+- Project config defaults through `archetype.toml`.
+- Exclude paths support via CLI (`--exclude`) and config.
+- Versioned JSON contract with explicit `schema_version`.
+- Namespace package and monorepo layout support improvements.
+- Changed-files mode with `--changed-from <git-ref>`.
+
+### Changed
+- CI/release workflows expanded to cover new check and packaging behaviors.
+
 ## 0.1.0 - 2026-05-09
 
 ### Added
@@ -48,12 +63,6 @@
 ## 0.2.3 — 2026-05-16
 
 ### Added
-- @warn decorator for non-blocking rule violations
-- @skip decorator to temporarily disable rules
-- @since decorator for date-scoped enforcement
-- @rule timeout parameter for pathological graphs
-- Glob pattern support in module matching
-- Rule grouping with group context manager
 - archetype init command for scaffolding
 - --quiet flag to show only failures and warnings
 - --format json flag for machine-readable output
@@ -67,4 +76,4 @@
 - src layout detection in archetype init
 - Verbose violation messages now concise and scannable
 - --quiet flag correctly filters JSON output
-- Naming convention violation message format cleaned up
+- Naming convention violation message format cleaned up

archetype_py-0.3.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: archetype-py
+Version: 0.3.0
+Summary: Enforce architectural rules as code. Catch structural violations before they merge.
+Project-URL: Homepage, https://github.com/MossabArektout/archetype-py
+Project-URL: Documentation, https://github.com/MossabArektout/archetype-py
+Author-email: Mossab Arektout <mossabarektout2000@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click
+Requires-Dist: networkx
+Requires-Dist: rich
+Provides-Extra: benchmarks
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# archetype-py
+
+Enforce architectural rules as code. Catch structural violations before they merge.
+
+[GitHub Repository](https://github.com/MossabArektout/archetype-py)  
+[Documentation](https://github.com/MossabArektout/archetype-py#readme)
+
+## Why archetype-py
+
+Most tooling checks formatting, typing, and tests, but not architecture drift.  
+`archetype-py` lets you codify structural boundaries and enforce them in local runs, CI, and pytest.
+
+## When to use / When not to use
+
+Use archetype-py when:
+- You want architecture rules to run automatically in CI and pytest.
+- You need to prevent forbidden imports, layer violations, or import cycles.
+- You are adopting architecture checks incrementally in a legacy codebase (baseline mode).
+
+Do not use archetype-py when:
+- You only need style/type checks (linters and type checkers are enough).
+- Your project is a very small script with no meaningful module boundaries.
+- You are looking for runtime policy enforcement instead of static import-graph checks.
+
+## Install
+
+```bash
+pip install archetype-py
+```
+
+## Quick Start
+
+```bash
+archetype init .
+archetype check .
+```
+
+Create an `architecture.py` file and define your rules:
+
+```python
+from archetype import rule
+from archetype.rules import layers
+
+@rule("layers are ordered")
+def layer_order() -> None:
+    layers(["myapp.api", "myapp.services", "myapp.db"]).are_ordered()
+```
+
+## Core Features
+
+- Architecture rules for forbidden imports, allowlisted imports, and protected boundaries
+- Transitive dependency checks with `must_not_depend_on`
+- Layer order enforcement with `layers(...).are_ordered()`
+- Import cycle detection with `no_cycles(...)`
+- Rule decorators: `@rule`, `@warn`, `@skip`, `@since`
+- Rule grouping via `group("...")` and targeted execution with `--group`
+- `archetype init` scaffolding for starter `architecture.py`
+- JSON and text reporting (`--format json|text`) with stable JSON contract versioning
+- Quiet output mode (`--quiet`) for CI-friendly logs
+- Import graph caching for faster repeated runs (`--cache`, `--no-cache`)
+- Parallel execution control with `--workers`
+- Baseline adoption for legacy codebases (`--write-baseline`, `--baseline`)
+- Changed-files scope mode (`--changed-from <git-ref>`)
+- GitHub Actions inline PR annotations (`--github-annotations`)
+- Path exclusions via CLI (`--exclude`) and config
+- Project config defaults through `archetype.toml`
+- Git pre-commit hook installer (`archetype install-hook`)
+- Project layout support for flat, `src/`, namespace packages (PEP 420), and monorepos
+- CLI command and pytest plugin support for local and CI enforcement
+
+## CI Example
+
+```yaml
+- run: archetype check .
+```
+
+For full guides, examples, and release notes, use the GitHub README and changelog.

archetype_py-0.3.0/PYPI.md

@@ -0,0 +1,77 @@
+# archetype-py
+
+Enforce architectural rules as code. Catch structural violations before they merge.
+
+[GitHub Repository](https://github.com/MossabArektout/archetype-py)  
+[Documentation](https://github.com/MossabArektout/archetype-py#readme)
+
+## Why archetype-py
+
+Most tooling checks formatting, typing, and tests, but not architecture drift.  
+`archetype-py` lets you codify structural boundaries and enforce them in local runs, CI, and pytest.
+
+## When to use / When not to use
+
+Use archetype-py when:
+- You want architecture rules to run automatically in CI and pytest.
+- You need to prevent forbidden imports, layer violations, or import cycles.
+- You are adopting architecture checks incrementally in a legacy codebase (baseline mode).
+
+Do not use archetype-py when:
+- You only need style/type checks (linters and type checkers are enough).
+- Your project is a very small script with no meaningful module boundaries.
+- You are looking for runtime policy enforcement instead of static import-graph checks.
+
+## Install
+
+```bash
+pip install archetype-py
+```
+
+## Quick Start
+
+```bash
+archetype init .
+archetype check .
+```
+
+Create an `architecture.py` file and define your rules:
+
+```python
+from archetype import rule
+from archetype.rules import layers
+
+@rule("layers are ordered")
+def layer_order() -> None:
+    layers(["myapp.api", "myapp.services", "myapp.db"]).are_ordered()
+```
+
+## Core Features
+
+- Architecture rules for forbidden imports, allowlisted imports, and protected boundaries
+- Transitive dependency checks with `must_not_depend_on`
+- Layer order enforcement with `layers(...).are_ordered()`
+- Import cycle detection with `no_cycles(...)`
+- Rule decorators: `@rule`, `@warn`, `@skip`, `@since`
+- Rule grouping via `group("...")` and targeted execution with `--group`
+- `archetype init` scaffolding for starter `architecture.py`
+- JSON and text reporting (`--format json|text`) with stable JSON contract versioning
+- Quiet output mode (`--quiet`) for CI-friendly logs
+- Import graph caching for faster repeated runs (`--cache`, `--no-cache`)
+- Parallel execution control with `--workers`
+- Baseline adoption for legacy codebases (`--write-baseline`, `--baseline`)
+- Changed-files scope mode (`--changed-from <git-ref>`)
+- GitHub Actions inline PR annotations (`--github-annotations`)
+- Path exclusions via CLI (`--exclude`) and config
+- Project config defaults through `archetype.toml`
+- Git pre-commit hook installer (`archetype install-hook`)
+- Project layout support for flat, `src/`, namespace packages (PEP 420), and monorepos
+- CLI command and pytest plugin support for local and CI enforcement
+
+## CI Example
+
+```yaml
+- run: archetype check .
+```
+
+For full guides, examples, and release notes, use the GitHub README and changelog.

archetype_py-0.2.3/PKG-INFO → archetype_py-0.3.0/README.md

@@ -1,27 +1,3 @@
-Metadata-Version: 2.4
-Name: archetype-py
-Version: 0.2.3
-Summary: Enforce architectural rules as code. Catch structural violations before they merge.
-Project-URL: Homepage, https://github.com/MossabArektout/archetype-py
-Project-URL: Documentation, https://github.com/MossabArektout/archetype-py
-Author-email: Mossab Arektout <mossabarektout2000@gmail.com>
-License: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.11
-Requires-Dist: click
-Requires-Dist: networkx
-Requires-Dist: rich
-Provides-Extra: benchmarks
-Provides-Extra: dev
-Requires-Dist: hatch; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Description-Content-Type: text/markdown
-
 [![PyPI version](https://img.shields.io/pypi/v/archetype-py)](https://pypi.org/project/archetype-py/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/archetype-py/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/MossabArektout/archetype-py/blob/main/LICENSE)
@@ -40,6 +16,7 @@ Description-Content-Type: text/markdown
 - [Minimum `architecture.py` Example](#minimum-architecturepy-example)
 - [Features](#features)
 - [Decorators and Commands](#decorators-and-commands)
+- [Baseline Mode](#baseline-mode)
 - [Perfect For](#perfect-for)
 - [Installation](#installation)
 - [Build & Test](#build--test)
@@ -229,11 +206,21 @@ def no_import_cycles() -> None:
 - Import cycle detection
 - Protected module boundaries
 
+### Project Layout Support
+- Flat package layouts
+- Single `src/` layouts
+- Namespace packages (PEP 420, without `__init__.py`)
+- Monorepos with multiple `src` roots
+
 ### Workflow Features
 - Rule grouping
 - Warning-level rules
 - Temporary rule skips with context
 - Changed-file enforcement (`since`)
+- Legacy baseline snapshot/suppression (`--write-baseline`, `--baseline`)
+- Diff-scoped checks (`--changed-from <ref>`)
+- First-class project config defaults (`archetype.toml`)
+- Path exclusions (`--exclude`, `archetype.toml`, legacy `[tool.archetype].exclude`)
 - Pytest integration
 - CI-friendly exit codes
 
@@ -251,13 +238,211 @@ Rules are written in `architecture.py` with decorators. Below are all decorator-
 
 Decorator order tip: place `@rule(...)` first, then wrappers like `@warn`, `@skip`, or `@since`.
 
+### `@since` Date Format
+
+`@since(...)` only accepts ISO calendar dates in `YYYY-MM-DD` format. The
+decorator validates this when `architecture.py` is loaded, so invalid values
+raise a clear `ValueError` instead of being ignored.
+
+```python
+@since("2026-01-01")  # valid
+def recent_violations_only() -> None:
+    ...
+
+@since("01-01-2026")  # invalid: expected YYYY-MM-DD
+def ambiguous_date() -> None:
+    ...
+```
+
+Invalid dates show the expectation in the error message:
+
+```text
+Invalid date '01-01-2026'. Expected format: YYYY-MM-DD.
+```
+
 | Command | Description | Example |
 |---|---|---|
 | `archetype init [path]` | Detects project structure and generates a starter `architecture.py` file. | `archetype init .` |
 | `archetype check [path]` | Loads `architecture.py` and runs all registered architecture rules. | `archetype check .` |
 | `archetype check [path] --group <name>` | Runs only rules that belong to the specified group. | `archetype check . --group core` |
+| `archetype check [path] --exclude <pattern>` | Excludes paths from analysis and reporting (repeatable). | `archetype check . --exclude /vendor/ --exclude /migrations/` |
+| `archetype check [path] --write-baseline <file> --baseline <file>` | Writes a baseline snapshot and suppresses matching legacy violations so only new ones fail. | `archetype check . --baseline archetype-baseline.json` |
+| `archetype check [path] --changed-from <ref>` | Limits reported violations to files changed since `<ref>` (branch name or commit SHA). | `archetype check . --changed-from origin/main` |
+| `archetype check [path] --github-annotations` | Emits GitHub Actions inline annotations (`::error`/`::warning`) for PR diffs. | `archetype check . --github-annotations` |
+| `archetype install-hook [path]` | Installs (or updates) a managed git pre-commit hook that runs `archetype check` before each commit. | `archetype install-hook .` |
+
+### Excluding Paths
+
+Exclude noisy folders such as generated code, migrations, or vendored dependencies:
+
+```bash
+archetype check . --exclude /vendor/ --exclude /migrations/
+```
+
+You can also define defaults in `archetype.toml`:
+
+```toml
+exclude = ["/vendor/", "/migrations/"]
+```
+
+Legacy compatibility: if `archetype.toml` is missing, Archetype still reads
+`[tool.archetype]` from `pyproject.toml`.
+
+### Project Config (`archetype.toml`)
+
+Archetype auto-discovers `archetype.toml` in the project root passed to
+`archetype check [path]`.
+
+Supported defaults:
+
+- `format` (`"text"` or `"json"`)
+- `quiet` (`true`/`false`)
+- `group` (`string`)
+- `exclude` (`string` or `string[]`)
+- `workers` (`int >= 1`)
+- `cache` (`true`/`false`)
+
+Example:
+
+```toml
+format = "json"
+quiet = true
+group = "Layer boundaries"
+exclude = ["/vendor/", "/migrations/"]
+workers = 4
+cache = true
+```
+
+Precedence:
+
+- CLI flags override `archetype.toml`.
+- `archetype.toml` overrides built-in defaults.
+- If config is missing, behavior remains unchanged.
+
+### Pre-commit Hook
+
+Install a git pre-commit hook in one command:
 
+```bash
+archetype install-hook .
+```
+
+Behavior:
+
+- Creates `.git/hooks/pre-commit` if missing.
+- Appends an Archetype-managed block if a custom pre-commit hook already exists.
+- Updates the managed block if Archetype already installed it.
+- Blocks the commit when `archetype check` fails, and prints violations directly in the commit terminal output.
+
+### Changed-files Mode
+
+Use diff scope to speed up checks in large repositories:
+
+```bash
+archetype check . --changed-from origin/main
+```
+
+`<ref>` can be a branch name (for example `origin/main`) or a commit SHA.
+
+When enabled:
+- Text output shows a scope banner with mode, ref, and changed file count.
+- JSON output includes a `scope` object with mode/ref/file metadata.
+
+### GitHub PR Annotations
+
+Use GitHub Actions annotations to surface violations directly on PR diff lines:
+
+```bash
+archetype check . --github-annotations
+```
+
+In GitHub Actions, these appear as inline file/line annotations for each violation
+while preserving the normal non-zero exit code when checks fail.
 
+## Baseline Mode
+
+Use baseline mode to adopt archetype in legacy repos without failing on pre-existing violations.
+
+Create a baseline snapshot:
+
+```bash
+archetype check . --write-baseline archetype-baseline.json
+```
+
+Run checks against that baseline (matching old violations are suppressed):
+
+```bash
+archetype check . --baseline archetype-baseline.json
+```
+
+You can combine with JSON output to track counts:
+
+```bash
+archetype check . --baseline archetype-baseline.json --format json
+```
+
+JSON output includes:
+- `schema_version`: top-level contract version for machine consumers
+- `summary`: rule-level pass/fail/warn/skip counts
+- `violations.total`: total current violations before suppression
+- `violations.new`: violations not found in the baseline
+- `violations.suppressed`: violations matched and suppressed by baseline
+
+### JSON Contract (Versioned)
+
+Archetype JSON output is versioned for CI and other integrations.
+
+Current contract version:
+
+- `schema_version: 1`
+
+Versioning policy:
+
+- Non-breaking additions (for example new optional fields) keep the same `schema_version`.
+- Breaking shape changes (rename/remove/type changes) must increment `schema_version`.
+- Contract tests in CI enforce the current schema shape.
+
+Field definitions:
+
+- `schema_version` (`int`): machine-readable contract version.
+- `summary` (`object`): counts by rule status.
+- `violations` (`object`): aggregate violation counts.
+- `rules` (`array`): per-rule results with status and violations.
+- `scope` (`object`, optional): present when `--changed-from` is used.
+
+Example (`--format json`):
+
+```json
+{
+  "schema_version": 1,
+  "summary": {
+    "passed": 2,
+    "failed": 1,
+    "warned": 0,
+    "skipped": 0,
+    "total": 3
+  },
+  "violations": {
+    "total": 1,
+    "new": 1,
+    "suppressed": 0
+  },
+  "rules": [
+    {
+      "name": "api-must-not-import-db",
+      "status": "failed",
+      "group": "core",
+      "since_date": null,
+      "violations": [
+        {
+          "module": "simple_project.api",
+          "message": "Module 'simple_project.api' must not import 'simple_project.db'"
+        }
+      ]
+    }
+  ]
+}
+```
 
 ## Perfect For
 
@@ -298,6 +483,8 @@ archetype check .
 - `0`: no blocking failures (passes and warnings only)
 - `1`: one or more blocking rule failures
 
+When `--baseline` is used, exit code `1` means there are **new** blocking violations not present in the baseline.
+
 ---
 
 ## Troubleshooting
@@ -306,6 +493,7 @@ archetype check .
 - Rules seem to do nothing: confirm your rules are decorated with `@rule("...")`; undecorated functions are not registered.
 - `@since(...)` behavior is unexpected: verify the date format is `YYYY-MM-DD` and that your git history is available in the checked path.
 - Import path mismatches: use fully qualified module paths (`myapp.api`, not file paths like `src/api.py`).
+- Namespace package imports not showing up: ensure modules live under discovered package roots (repo root, top-level `src/`, or nested monorepo `*/src` roots).
 
 ---
 

{archetype_py-0.2.3 → archetype_py-0.3.0}/archetype/__init__.py

@@ -2,8 +2,7 @@
 
 from archetype.dsl.query import imports, load_project
 from archetype.rule import group, registry, rule, since, skip, warn
-
-module = None
+from archetype.rules import module
 
 __all__ = [
     "rule",

{archetype_py-0.2.3 → archetype_py-0.3.0}/archetype/analysis/cache.py

@@ -4,19 +4,27 @@ from __future__ import annotations
 
 import pickle
 from pathlib import Path
+from typing import Iterable
 
 import networkx as nx
 
+from archetype.analysis.path_filters import is_path_excluded, normalize_exclude_patterns
+
 
 def get_cache_path(project_root: Path) -> Path:
     """Return the cache file path for a project."""
     return project_root.resolve() / ".archetype_cache"
 
 
-def compute_file_signatures(project_root: Path) -> dict[str, float]:
+def compute_file_signatures(
+    project_root: Path,
+    *,
+    exclude_patterns: Iterable[str] | None = None,
+) -> dict[str, float]:
     """Compute mtime signatures for Python files under project_root."""
     signatures: dict[str, float] = {}
     root = project_root.resolve()
+    normalized_excludes = normalize_exclude_patterns(exclude_patterns)
 
     for file_path in root.rglob("*.py"):
         parts = file_path.parts
@@ -24,7 +32,11 @@ def compute_file_signatures(project_root: Path) -> dict[str, float]:
             continue
         if ".venv" in parts or "venv" in parts or "site-packages" in parts:
             continue
+        if is_path_excluded(file_path, root, normalized_excludes):
+            continue
         signatures[str(file_path.resolve())] = file_path.stat().st_mtime
+    for excluded in normalized_excludes:
+        signatures[f"__archetype_exclude__:{excluded}"] = -1.0
 
     return signatures