archetype-py 0.1.0__tar.gz

archetype_py-0.1.0/.github/workflows/archetype.yml

@@ -0,0 +1,36 @@
+name: Archetype Check Template
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  archetype:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Pull down your repository code so CI can inspect it.
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Install Python 3.11 so the Archetype CLI can run.
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # Install Archetype from PyPI into the CI environment.
+      - name: Install Archetype
+        run: |
+          python -m pip install --upgrade pip
+          pip install archetype-py
+
+      # Run architecture rules defined in architecture.py.
+      # This step exits non-zero on violations, which fails the workflow.
+      - name: Run architecture checks
+        run: archetype check .
+
+      # 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.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: Archetype Library CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package and development dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run full test suite
+        run: pytest
+
+      - name: Run Archetype against this codebase
+        run: archetype check .

archetype_py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,62 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Checkout repository contents for test execution.
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Install Python runtime used for tests and packaging checks.
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # Install the project in editable mode with dev dependencies.
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      # Run the full test suite; publication is blocked on any failure.
+      - name: Run tests
+        run: pytest
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      # Checkout repository contents so the package can be built.
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Set up Python for building distribution artifacts.
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # Install Hatch and build source/wheel distributions.
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+          hatch build
+
+      # Publish using PyPI Trusted Publishing (no API token secret required).
+      # Before this works, configure Trusted Publishing in your PyPI project:
+      # https://pypi.org/manage/account/publishing
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

archetype_py-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# IDE / editor
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+
+# Hatch
+.hatch/
+LAUNCH.md

archetype_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 - 2026-05-09
+
+### Added
+- Introduced static import graph analysis that maps module dependencies without executing application code.
+- Added a rule authoring model using `@rule` decorators and a central registry so architectural checks are defined as plain Python.
+- Shipped a readable query DSL with project loading, import constraints, and cycle checks for writing architecture policies.
+- Added a CLI command (`archetype check`) that discovers `architecture.py`, executes rules, and returns CI-friendly exit codes.
+- Added a pytest plugin that auto-collects `architecture.py` rules as native pytest test items with readable failure output.
+- Added a shared reporting layer for consistent violation formatting across CLI and pytest execution paths.
+- Added built-in rule packs for layering constraints, module boundaries, naming conventions, and circular import detection.
+- Added test fixtures and comprehensive pytest coverage for graph construction, DSL behavior, CLI behavior, plugin collection, and built-in rules.
+- Added GitHub Actions workflows for reusable architecture checks in downstream projects and matrix CI for Archetype development.
+- Added packaging and release automation for PyPI publication using GitHub Actions Trusted Publishing.

archetype_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [YEAR] [AUTHOR NAME]
+
+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.

archetype_py-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: archetype-py
+Version: 0.1.0
+Summary: Archetype statically analyzes Python projects to enforce architectural rules as code.
+Project-URL: Homepage, https://github.com/your-org/your-repo
+Project-URL: Documentation, https://github.com/your-org/your-repo
+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: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+![PyPI](https://img.shields.io/pypi/v/archetype) ![Python](https://img.shields.io/pypi/pyversions/archetype) ![License](https://img.shields.io/badge/license-MIT-green) ![CI](https://img.shields.io/github/actions/workflow/status/your-org/your-repo/ci.yml?branch=main)
+
+## Architectural rules should not live in people’s heads
+Architectural rules usually exist in engineers’ heads but nowhere in the codebase.
+Archetype turns those rules into executable Python checks that run in `archetype check` and `pytest`.
+
+```python
+# architecture.py
+from archetype import imports, rule
+
+@rule("api does not import db")
+def api_not_db() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+
+@rule("services only import db")
+def services_only_db() -> None:
+    imports("myapp.services").must_only_import_from("myapp.db")
+```
+
+```text
+$ archetype check .
+✓ api does not import db
+✗ services only import db
+  - myapp.services.user -> myapp.cache: Module 'myapp.services.user' imports 'myapp.cache', which is outside the allowed set: ('myapp.db',).
+Summary: 1 passed, 1 failed, 2 total rules.
+```
+
+## Installation
+```bash
+pip install archetype-py
+```
+
+## Quickstart
+1. Install Archetype.
+
+```bash
+pip install archetype-py
+```
+
+2. Create `architecture.py` in your project root.
+
+```bash
+touch architecture.py
+```
+
+3. Add your first rule with the imports DSL.
+
+```python
+# architecture.py
+from archetype import imports, rule
+
+@rule("api does not import db")
+def api_not_db() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+```
+
+4. Run the checker.
+
+```bash
+archetype check .
+```
+
+5. Read the output and fix violations.
+
+```text
+✓ api does not import db
+Summary: 1 passed, 0 failed, 1 total rules.
+```
+
+If your project already runs `pytest`, running `pytest` is sufficient because Archetype rules are collected and executed by the pytest plugin.
+
+## Why Archetype exists
+Style tools enforce how code looks. Type tools enforce what values can flow through code. Architectural tools enforce which parts of the system are allowed to depend on which other parts.
+
+Pylint and similar linters are strong at local code quality checks, and Mypy is strong at static type correctness. Neither is designed to express team-level dependency contracts like “API cannot import DB” or “internal modules are private outside their package boundary.”
+
+Archetype keeps rules in `architecture.py` as normal Python functions, not static YAML declarations. That makes rules executable, reviewable, testable, and easy to evolve with the codebase using the same language and tooling your team already uses.
+
+## Built-in rules reference
+### `layers`
+Enforces that lower layers do not import upper layers.
+
+```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()
+```
+
+### `module` (module boundaries)
+Enforces that a protected internal module is only imported from an allowed parent scope.
+
+```python
+from archetype import rule
+from archetype.rules import module
+
+@rule("internal auth is private")
+def auth_boundary() -> None:
+    module("myapp.auth.internal").only_imported_within("myapp.auth")
+```
+
+### `classes_in` and `functions_in` (naming conventions)
+Enforces class naming patterns and required top-level functions in matched modules.
+
+```python
+from archetype import rule
+from archetype.rules import classes_in, functions_in
+
+@rule("service classes end with Service")
+def class_names() -> None:
+    classes_in("myapp.services").all_match(r".*Service$")
+
+@rule("api modules expose handle")
+def api_handle_exists() -> None:
+    functions_in("myapp.api").must_include("handle")
+```
+
+### `no_cycles`
+Enforces that there are no import cycles in the whole project or in a selected module scope.
+
+```python
+from archetype import rule
+from archetype.rules import no_cycles
+
+@rule("no cycles in services")
+def services_no_cycles() -> None:
+    no_cycles("myapp.services")
+```
+
+## Writing custom rules
+```python
+from archetype import imports, rule
+
+@rule("custom architecture policy")
+def custom_policy() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+    imports("myapp.services").has_no_cycles()
+    imports("myapp.services").must_only_import_from("myapp.db", "myapp.shared")
+```
+
+Any Python function decorated with `@rule` that returns without raising is a passing rule. Rules can use the full Python language, so you can encode architecture constraints that do not fit generic linters or static config.
+
+## CI integration
+```yaml
+name: Archetype Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  archetype:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install archetype-py
+      - run: archetype check .
+```
+
+If your CI already runs `pytest`, no additional CI configuration is required.
+
+## Contributing
+Source code and issue tracking are in the GitHub repository: `https://github.com/your-org/your-repo`.
+Contributions are welcome; open an issue first to discuss scope before submitting a pull request.

archetype_py-0.1.0/README.md

@@ -0,0 +1,172 @@
+![PyPI](https://img.shields.io/pypi/v/archetype) ![Python](https://img.shields.io/pypi/pyversions/archetype) ![License](https://img.shields.io/badge/license-MIT-green) ![CI](https://img.shields.io/github/actions/workflow/status/your-org/your-repo/ci.yml?branch=main)
+
+## Architectural rules should not live in people’s heads
+Architectural rules usually exist in engineers’ heads but nowhere in the codebase.
+Archetype turns those rules into executable Python checks that run in `archetype check` and `pytest`.
+
+```python
+# architecture.py
+from archetype import imports, rule
+
+@rule("api does not import db")
+def api_not_db() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+
+@rule("services only import db")
+def services_only_db() -> None:
+    imports("myapp.services").must_only_import_from("myapp.db")
+```
+
+```text
+$ archetype check .
+✓ api does not import db
+✗ services only import db
+  - myapp.services.user -> myapp.cache: Module 'myapp.services.user' imports 'myapp.cache', which is outside the allowed set: ('myapp.db',).
+Summary: 1 passed, 1 failed, 2 total rules.
+```
+
+## Installation
+```bash
+pip install archetype-py
+```
+
+## Quickstart
+1. Install Archetype.
+
+```bash
+pip install archetype-py
+```
+
+2. Create `architecture.py` in your project root.
+
+```bash
+touch architecture.py
+```
+
+3. Add your first rule with the imports DSL.
+
+```python
+# architecture.py
+from archetype import imports, rule
+
+@rule("api does not import db")
+def api_not_db() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+```
+
+4. Run the checker.
+
+```bash
+archetype check .
+```
+
+5. Read the output and fix violations.
+
+```text
+✓ api does not import db
+Summary: 1 passed, 0 failed, 1 total rules.
+```
+
+If your project already runs `pytest`, running `pytest` is sufficient because Archetype rules are collected and executed by the pytest plugin.
+
+## Why Archetype exists
+Style tools enforce how code looks. Type tools enforce what values can flow through code. Architectural tools enforce which parts of the system are allowed to depend on which other parts.
+
+Pylint and similar linters are strong at local code quality checks, and Mypy is strong at static type correctness. Neither is designed to express team-level dependency contracts like “API cannot import DB” or “internal modules are private outside their package boundary.”
+
+Archetype keeps rules in `architecture.py` as normal Python functions, not static YAML declarations. That makes rules executable, reviewable, testable, and easy to evolve with the codebase using the same language and tooling your team already uses.
+
+## Built-in rules reference
+### `layers`
+Enforces that lower layers do not import upper layers.
+
+```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()
+```
+
+### `module` (module boundaries)
+Enforces that a protected internal module is only imported from an allowed parent scope.
+
+```python
+from archetype import rule
+from archetype.rules import module
+
+@rule("internal auth is private")
+def auth_boundary() -> None:
+    module("myapp.auth.internal").only_imported_within("myapp.auth")
+```
+
+### `classes_in` and `functions_in` (naming conventions)
+Enforces class naming patterns and required top-level functions in matched modules.
+
+```python
+from archetype import rule
+from archetype.rules import classes_in, functions_in
+
+@rule("service classes end with Service")
+def class_names() -> None:
+    classes_in("myapp.services").all_match(r".*Service$")
+
+@rule("api modules expose handle")
+def api_handle_exists() -> None:
+    functions_in("myapp.api").must_include("handle")
+```
+
+### `no_cycles`
+Enforces that there are no import cycles in the whole project or in a selected module scope.
+
+```python
+from archetype import rule
+from archetype.rules import no_cycles
+
+@rule("no cycles in services")
+def services_no_cycles() -> None:
+    no_cycles("myapp.services")
+```
+
+## Writing custom rules
+```python
+from archetype import imports, rule
+
+@rule("custom architecture policy")
+def custom_policy() -> None:
+    imports("myapp.api").must_not_import("myapp.db")
+    imports("myapp.services").has_no_cycles()
+    imports("myapp.services").must_only_import_from("myapp.db", "myapp.shared")
+```
+
+Any Python function decorated with `@rule` that returns without raising is a passing rule. Rules can use the full Python language, so you can encode architecture constraints that do not fit generic linters or static config.
+
+## CI integration
+```yaml
+name: Archetype Check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  archetype:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install archetype-py
+      - run: archetype check .
+```
+
+If your CI already runs `pytest`, no additional CI configuration is required.
+
+## Contributing
+Source code and issue tracking are in the GitHub repository: `https://github.com/your-org/your-repo`.
+Contributions are welcome; open an issue first to discuss scope before submitting a pull request.

archetype_py-0.1.0/archetype/__init__.py

@@ -0,0 +1,3 @@
+"""Archetype public package exports."""
+
+from archetype.init import *  # noqa: F401,F403

archetype_py-0.1.0/archetype/analysis/__init__.py

@@ -0,0 +1,3 @@
+"""Archetype analysis subpackage."""
+
+from archetype.analysis.init import *  # noqa: F401,F403

archetype_py-0.1.0/archetype/analysis/ast_utils.py

@@ -0,0 +1,19 @@
+"""AST traversal helpers used by Archetype static analysis."""
+
+from __future__ import annotations
+
+import ast
+
+
+def get_class_names(tree: ast.AST) -> list[str]:
+    """Return all class names defined anywhere in the AST."""
+    return [node.name for node in ast.walk(tree) if isinstance(node, ast.ClassDef)]
+
+
+def get_top_level_function_names(tree: ast.AST) -> list[str]:
+    """Return names of module-level functions only (excluding class methods)."""
+    return [
+        node.name
+        for node in getattr(tree, "body", [])
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
+    ]