archdrift 0.1.0__tar.gz

archdrift-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(rtk grep *)",
+      "Bash(git mv *)",
+      "Bash(rtk ls *)",
+      "Bash(rtk pytest *)",
+      "Bash(PYTHONPATH=src rtk pytest tests/ -q)",
+      "Bash(rtk git *)"
+    ]
+  }
+}

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

@@ -0,0 +1,41 @@
+# CI do archdrift.
+#
+# Dois jobs:
+#   1. test     -> pytest em matriz de versões do Python
+#   2. dogfood  -> o repo valida a PRÓPRIA arquitetura com o próprio tool.
+#                  Se este job quebrar, o produto está funcionando. :)
+
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -v
+
+  dogfood:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: pip install -e .
+      - name: Architecture drift check (eating our own dog food)
+        run: archdrift check .

archdrift-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/

archdrift-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Arquitetura — archdrift
+
+> Contrato de arquitetura mantido por `archdrift.py`.
+> Seções entre `<!-- map:begin/end -->` são regeneradas; o resto é seu.
+
+<!-- map:begin stack -->
+## Stack detectada
+
+| Tecnologia | Evidência | O que é |
+|------------|-----------|---------|
+| Python | `pyproject.toml` | manifesto do projeto Python |
+| GitHub Actions | `.github/workflows (1 workflow(s))` | pipelines de CI/CD |
+<!-- map:end stack -->
+
+<!-- map:begin tree -->
+## Estrutura de pastas
+
+<!-- map:hash 8503e20d6c01 -->
+```
+archdrift/
+├── .github/
+│   └── workflows/
+│       └── ci.yml
+├── src/  # Código-fonte principal da aplicação
+│   └── archdrift/
+│       ├── __init__.py
+│       ├── __main__.py
+│       └── cli.py
+├── tests/  # Testes automatizados
+│   └── test_lifecycle.py
+├── .gitignore
+├── LICENSE
+├── pyproject.toml
+└── README.md
+```
+<!-- map:end tree -->
+
+<!-- map:begin contract -->
+## Responsabilidades das pastas
+
+<!-- Edite as descrições abaixo: elas são PRESERVADAS entre gerações. -->
+<!-- Linhas com _(preencher)_ são pendências: `check` falha até você preenchê-las. -->
+
+| Pasta | Responsabilidade |
+|-------|------------------|
+| `.github` | Automação do GitHub |
+| `.github/workflows` | CI: testes em matriz + dogfood do drift check |
+| `src` | Código-fonte principal da aplicação |
+| `src/archdrift` | Pacote Python: CLI, scan, merge e check |
+| `tests` | Testes automatizados |
+<!-- map:end contract -->
+
+## Notas
+
+_Espaço livre: decisões de arquitetura, convenções, ADRs. O script nunca toca nesta seção._

archdrift-0.1.0/LICENSE

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

archdrift-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: archdrift
+Version: 0.1.0
+Summary: Architecture contract for AI coding agents: a curated, human-edited ARCHITECTURE.md with drift detection in CI.
+Project-URL: Homepage, https://github.com/EvertDeveloper/archdrift
+Project-URL: Issues, https://github.com/EvertDeveloper/archdrift/issues
+Author: Everton Godoi
+License: MIT
+License-File: LICENSE
+Keywords: agents-md,ai-agents,architecture,claude-code,context-engineering,cursor,documentation,drift-detection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# archdrift
+
+**Architecture contract for AI coding agents.** A curated `ARCHITECTURE.md` that agents read, humans edit, and CI enforces — so your architecture docs never rot.
+
+[![CI](https://github.com/SEU_USUARIO/archdrift/actions/workflows/ci.yml/badge.svg)](https://github.com/SEU_USUARIO/archdrift/actions)
+[![PyPI](https://img.shields.io/pypi/v/archdrift)](https://pypi.org/project/archdrift/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+---
+
+## The problem
+
+Tools like Repomix and CodeGraph are **descriptive**: they read your code and tell agents what exists. But no tool captures what your architecture is *supposed* to be — the intent behind it. So agents guess, `ARCHITECTURE.md` files rot within weeks, and nobody notices until an agent (or a new dev) builds on top of stale assumptions.
+
+## The idea
+
+`archdrift` makes your `ARCHITECTURE.md` **normative**:
+
+1. **Generated map** — folder tree, detected stack, responsibilities table. Curated for token efficiency: code files listed, assets collapsed.
+2. **Human curation that survives** — edit any description in the responsibilities table, add ADRs and notes anywhere outside the managed sections. Regeneration **never** destroys your edits.
+3. **Drift detection in CI** — `archdrift check` exits 1 when reality diverges from the documented contract. The doc can't rot, because rot breaks the build.
+
+```
+┌─────────────┐   generate    ┌─────────────────┐   read    ┌────────────┐
+│  Filesystem │ ────────────▶ │ ARCHITECTURE.md │ ────────▶ │  AI agent  │
+└─────────────┘               │  (you curate)   │           └────────────┘
+       ▲                      └─────────────────┘
+       │                               │ check (CI)
+       └───────── drift? exit 1 ◀──────┘
+```
+
+## Quick start
+
+```bash
+uvx archdrift .          # or: pipx run archdrift .
+```
+
+This generates `ARCHITECTURE.md` (the contract) and `structure.json` (the graph, for tooling). Folders without a known role get marked `_(preencher)_` — fill them in, they're preserved forever.
+
+Then enforce it in CI:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Architecture drift check
+  run: uvx archdrift check .
+```
+
+Now every PR that adds an undocumented folder, deletes a documented one, or changes structure without regenerating the map **fails the build** until someone updates the contract.
+
+## How merging works
+
+Managed sections are delimited by markers:
+
+```markdown
+<!-- map:begin tree -->
+...regenerated by the tool...
+<!-- map:end tree -->
+
+## ADR-001                      ← yours, never touched
+
+<!-- map:begin contract -->
+| Folder | Responsibility |
+| `src/models` | Prisma entities — NEVER import from controllers |  ← your edit, preserved
+<!-- map:end contract -->
+```
+
+Priority for each folder's description: **your edit** > name-based heuristic > pending placeholder.
+
+## Why not just use a repo packer / knowledge graph?
+
+Use both. Repomix, CodeGraph, aider's repo-map are excellent at telling agents *what the code is*. `archdrift` covers the piece they can't infer: *what the architecture is meant to be* — and keeps that promise honest via CI. It's `dependency-cruiser` energy, rethought for the agent era, in a single zero-dependency Python file.
+
+## Roadmap
+
+- [x] Managed sections + merge (human curation survives regeneration)
+- [x] `check` mode — drift detection with meaningful exit codes for CI
+- [x] Stack detection, token-efficient tree (type-aware truncation)
+- [ ] `AGENTS.md` integration (pointer section into the emerging convention)
+- [ ] Declarative rules (`src/controllers must-not-import src/repositories`)
+- [ ] MCP server mode
+- [ ] Semantic graph: declared dependencies vs. real imports — the diff is the product
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+MIT licensed. Issues and PRs welcome.

archdrift-0.1.0/README.md

@@ -0,0 +1,91 @@
+# archdrift
+
+**Architecture contract for AI coding agents.** A curated `ARCHITECTURE.md` that agents read, humans edit, and CI enforces — so your architecture docs never rot.
+
+[![CI](https://github.com/SEU_USUARIO/archdrift/actions/workflows/ci.yml/badge.svg)](https://github.com/SEU_USUARIO/archdrift/actions)
+[![PyPI](https://img.shields.io/pypi/v/archdrift)](https://pypi.org/project/archdrift/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![Zero deps](https://img.shields.io/badge/dependencies-0-brightgreen)
+
+---
+
+## The problem
+
+Tools like Repomix and CodeGraph are **descriptive**: they read your code and tell agents what exists. But no tool captures what your architecture is *supposed* to be — the intent behind it. So agents guess, `ARCHITECTURE.md` files rot within weeks, and nobody notices until an agent (or a new dev) builds on top of stale assumptions.
+
+## The idea
+
+`archdrift` makes your `ARCHITECTURE.md` **normative**:
+
+1. **Generated map** — folder tree, detected stack, responsibilities table. Curated for token efficiency: code files listed, assets collapsed.
+2. **Human curation that survives** — edit any description in the responsibilities table, add ADRs and notes anywhere outside the managed sections. Regeneration **never** destroys your edits.
+3. **Drift detection in CI** — `archdrift check` exits 1 when reality diverges from the documented contract. The doc can't rot, because rot breaks the build.
+
+```
+┌─────────────┐   generate    ┌─────────────────┐   read    ┌────────────┐
+│  Filesystem │ ────────────▶ │ ARCHITECTURE.md │ ────────▶ │  AI agent  │
+└─────────────┘               │  (you curate)   │           └────────────┘
+       ▲                      └─────────────────┘
+       │                               │ check (CI)
+       └───────── drift? exit 1 ◀──────┘
+```
+
+## Quick start
+
+```bash
+uvx archdrift .          # or: pipx run archdrift .
+```
+
+This generates `ARCHITECTURE.md` (the contract) and `structure.json` (the graph, for tooling). Folders without a known role get marked `_(preencher)_` — fill them in, they're preserved forever.
+
+Then enforce it in CI:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Architecture drift check
+  run: uvx archdrift check .
+```
+
+Now every PR that adds an undocumented folder, deletes a documented one, or changes structure without regenerating the map **fails the build** until someone updates the contract.
+
+## How merging works
+
+Managed sections are delimited by markers:
+
+```markdown
+<!-- map:begin tree -->
+...regenerated by the tool...
+<!-- map:end tree -->
+
+## ADR-001                      ← yours, never touched
+
+<!-- map:begin contract -->
+| Folder | Responsibility |
+| `src/models` | Prisma entities — NEVER import from controllers |  ← your edit, preserved
+<!-- map:end contract -->
+```
+
+Priority for each folder's description: **your edit** > name-based heuristic > pending placeholder.
+
+## Why not just use a repo packer / knowledge graph?
+
+Use both. Repomix, CodeGraph, aider's repo-map are excellent at telling agents *what the code is*. `archdrift` covers the piece they can't infer: *what the architecture is meant to be* — and keeps that promise honest via CI. It's `dependency-cruiser` energy, rethought for the agent era, in a single zero-dependency Python file.
+
+## Roadmap
+
+- [x] Managed sections + merge (human curation survives regeneration)
+- [x] `check` mode — drift detection with meaningful exit codes for CI
+- [x] Stack detection, token-efficient tree (type-aware truncation)
+- [ ] `AGENTS.md` integration (pointer section into the emerging convention)
+- [ ] Declarative rules (`src/controllers must-not-import src/repositories`)
+- [ ] MCP server mode
+- [ ] Semantic graph: declared dependencies vs. real imports — the diff is the product
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -v
+```
+
+MIT licensed. Issues and PRs welcome.

archdrift-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+# ---------------------------------------------------------------------------
+# Empacotamento do archdrift
+#
+# Publicação:  python -m build && twine upload dist/*
+# Dev local:   pip install -e ".[dev]"
+# Uso final:   uvx archdrift .    (ou: pipx run archdrift .)
+# ---------------------------------------------------------------------------
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "archdrift"
+version = "0.1.0"
+description = "Architecture contract for AI coding agents: a curated, human-edited ARCHITECTURE.md with drift detection in CI."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Everton Godoi" }]   # TODO: preencher antes de publicar
+keywords = [
+    "ai-agents", "architecture", "documentation", "drift-detection",
+    "claude-code", "cursor", "agents-md", "context-engineering",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Quality Assurance",
+]
+# Zero dependências de runtime — só stdlib. Isso é feature, não acidente:
+# instala em qualquer lugar, roda em qualquer CI, sem supply chain risk.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "build", "twine"]
+
+[project.scripts]
+archdrift = "archdrift.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/EvertDeveloper/archdrift"   # TODO: preencher
+Issues = "https://github.com/EvertDeveloper/archdrift/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/archdrift"]

archdrift-0.1.0/src/archdrift/__init__.py

@@ -0,0 +1,17 @@
+"""
+archdrift — Contrato de arquitetura para agentes de código.
+
+API pública mínima: quem quiser usar como biblioteca (em vez de CLI)
+importa daqui. Tudo o mais em cli.py é considerado interno.
+"""
+
+from archdrift.cli import (
+    main,
+    cmd_generate,
+    cmd_check,
+    scan,
+    detect_stack,
+)
+
+__version__ = "0.1.0"
+__all__ = ["main", "cmd_generate", "cmd_check", "scan", "detect_stack"]

archdrift-0.1.0/src/archdrift/__main__.py

@@ -0,0 +1,6 @@
+"""Permite executar como módulo: python -m archdrift generate ."""
+
+from archdrift.cli import main
+
+if __name__ == "__main__":
+    main()