etcion 0.2.0__tar.gz

etcion-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug Report
+about: Something isn't working as expected
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Describe the bug
+
+A clear description of what the bug is.
+
+## To reproduce
+
+```python
+# Minimal code that reproduces the issue
+```
+
+## Expected behavior
+
+What you expected to happen.
+
+## Actual behavior
+
+What actually happened. Include the full error message/traceback if applicable.
+
+## Environment
+
+- etcion version: (e.g., 0.1.0)
+- Python version: (e.g., 3.12.3)
+- OS: (e.g., Ubuntu 24.04, macOS 15, Windows 11)

etcion-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new capability or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem or use case
+
+What are you trying to do? Why is the current behavior insufficient?
+
+## Proposed solution
+
+Describe what you'd like to happen.
+
+## Alternatives considered
+
+Any other approaches you've thought about.
+
+## Additional context
+
+Links to relevant ArchiMate spec sections, related issues, or examples from other tools.

etcion-0.2.0/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,15 @@
+---
+name: Question
+about: Ask about usage, architecture, or the ArchiMate spec
+title: ""
+labels: question
+assignees: ""
+---
+
+## Question
+
+What would you like to know?
+
+## Context
+
+What are you trying to accomplish? Include code snippets if relevant.

etcion-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff check src/ test/
+
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: ruff format --check src/ test/
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=etcion --cov-report=term-missing --cov-fail-under=90

etcion-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

etcion-0.2.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+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/spec/v2.0.0.html).
+
+## [0.2.0] - 30 Mar 2026
+
+### Added
+
+- **Pattern matching engine** -- define structural patterns with typed node
+  placeholders, relationship constraints, attribute filters (`.node(**kwargs)`),
+  lambda predicates (`.where()`), and cardinality constraints (`.min_edges()`,
+  `.max_edges()`). Find all matches (`pattern.match(model)`), check existence
+  (`pattern.exists(model)`), and identify gaps (`pattern.gaps(model, anchor=...)`).
+- **Pattern composition** -- combine reusable pattern fragments via
+  `pattern_a.compose(pattern_b)`, with conflict detection on shared aliases.
+- **Pattern serialization** -- `pattern.to_dict()` and `Pattern.from_dict(data)`
+  for JSON storage and sharing. Includes version field for forward compatibility.
+- **Pattern validation rules** -- `PatternValidationRule` (pattern must exist),
+  `AntiPatternRule` (pattern must NOT exist), `RequiredPatternRule` (every
+  anchor-type element must participate). All integrate with `Model.validate()`.
+- **Impact analysis (what-if modeling)** -- `analyze_impact()` computes the
+  blast radius of proposed changes: `remove`, `merge`, `replace`,
+  `add_relationship`, `remove_relationship`. Returns `ImpactResult` with
+  affected concepts (depth + path metadata), broken relationships, permission
+  violations, and an immutable result model.
+- **Change chaining** -- `chain_impacts()` combines sequential operations with
+  ID-based deduplication. Feed `impact.resulting_model` into the next analysis
+  for multi-step migration planning.
+- **Model querying** -- `elements_of_type()`, `elements_by_layer()`,
+  `elements_by_aspect()`, `elements_by_name()` (substring or regex),
+  `relationships_of_type()`, `connected_to()`, `sources_of()`, `targets_of()`.
+- **networkx integration** -- `Model.to_networkx()` converts to a cached
+  `MultiDiGraph` with full element/relationship attributes. Optional dependency
+  via `pip install etcion[graph]`.
+- **Viewpoint catalogue** -- 28 predefined standard viewpoints from the
+  ArchiMate specification, accessible via `VIEWPOINT_CATALOGUE["Organization"]`.
+- **Model comparison** -- `diff_models()` with `ModelDiff`, `ConceptChange`,
+  `FieldChange` dataclasses. Supports `match_by="id"` and `match_by="type_name"`.
+- **Plugin hooks** -- `register_element_type()`, `register_permission_rule()`,
+  `ValidationRule` protocol with `Model.add_validation_rule()`.
+- **Permission cache warming** -- `warm_cache()` for deterministic startup
+  latency in performance-sensitive environments.
+- **Performance benchmark suite** -- `test/benchmarks/` with import, construction,
+  validation, serialization, and memory benchmarks.
+- **MkDocs documentation site** -- API reference (auto-generated), user guide,
+  architecture overview, ADR index, permission matrix.
+- **CI/CD pipelines** -- GitHub Actions for lint, format, typecheck, test
+  (Python 3.12 + 3.13 matrix), and tag-triggered PyPI publishing.
+- **Viewpoint-constrained patterns** -- optional `Pattern(viewpoint=vp)`
+  validates all node/edge types at construction time.
+
+## [0.1.0] - 26 Mar 2026
+
+### Added
+
+- ArchiMate 3.2 metamodel: all element types across Business, Application,
+  Technology, Strategy, Motivation, Implementation & Migration, and Composite layers.
+- Complete relationship type system with source/target validation matrix.
+- Open Group Exchange Format XML serialization and deserialization.
+- XSD validation against bundled ArchiMate 3.1 schemas.
+- Conformance profiles (flag, standard, full).
+- Opaque XML preservation for organizations and views during round-trip.
+- Archi tool interoperability (import and export verified).
+- PEP 561 `py.typed` marker for downstream type checking.

etcion-0.2.0/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**etcion** is an early-stage Python library implementing the ArchiMate 3.2 metamodel.
+
+- Python 3.12.3 via `.venv/`
+- Source code goes in `src/etcion/`
+- Tests go in `test/`
+- Build system: `hatchling` via `pyproject.toml`
+
+## Directory Layout
+
+```
+src/      # Main source code
+test/     # Tests
+etc/      # Configuration files
+docs/     # Documentation
+assets/   # Static assets / images
+```
+
+## Development Setup
+
+Activate the virtual environment and install in editable mode with dev dependencies:
+
+```bash
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest                    # Run all tests
+pytest -x                 # Stop on first failure
+pytest -m "not slow"      # Skip slow tests
+```
+
+### Linting and Formatting
+
+```bash
+ruff check src/ test/           # Lint
+ruff check src/ test/ --fix     # Lint and auto-fix
+ruff format src/ test/          # Format in place
+ruff format --check src/ test/  # Check formatting without changing files
+```
+
+### Type Checking
+
+```bash
+mypy src/         # Type-check library source
+mypy src/ test/   # Type-check library and tests
+```
+
+### Build
+
+```bash
+pip install -e ".[dev]"   # Editable install with dev dependencies
+pip install -e .          # Editable install, runtime deps only
+```

etcion-0.2.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: etcion
+Version: 0.2.0
+Summary: Architecture as code — build, query, validate, and analyze enterprise architecture models in Python
+Project-URL: Homepage, https://github.com/korpodevs/etcion
+Project-URL: Documentation, https://korpodevs.github.io/etcion/
+Project-URL: Repository, https://github.com/korpodevs/etcion
+Project-URL: Issues, https://github.com/korpodevs/etcion/issues
+Project-URL: Changelog, https://github.com/korpodevs/etcion/blob/main/CHANGELOG.md
+Author: etcion contributors
+License-Expression: MIT
+Keywords: archi,archimate,architecture-as-code,enterprise-architecture,metamodel,open-group
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: lxml<6.0,>=5.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: networkx<4.0,>=3.0; extra == 'dev'
+Requires-Dist: pydantic<3.0,>=2.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Provides-Extra: graph
+Requires-Dist: networkx<4.0,>=3.0; extra == 'graph'
+Provides-Extra: xml
+Requires-Dist: lxml<6.0,>=5.0; extra == 'xml'
+Description-Content-Type: text/markdown
+
+# etcion
+
+Architecture as code. Build, query, validate, and analyze enterprise architecture models in Python.
+
+## Why etcion?
+
+Enterprise architecture models are rich data structures — typed elements, directed relationships, cross-layer dependencies, governance rules. But most EA tooling treats them as static diagrams locked inside proprietary formats.
+
+**etcion** turns your architecture into a first-class Python data structure. Once it's code, you can query it, validate it against rules, test what-if scenarios, diff versions, and integrate it with the rest of your analytical toolkit — pandas, networkx, Jupyter notebooks, CI/CD pipelines, or anything else Python touches.
+
+Built on the [ArchiMate 3.2](https://pubs.opengroup.org/architecture/archimate32-doc/) metamodel. Compatible with [Archi](https://www.archimatetool.com/) via the Open Group Exchange Format.
+
+## What you can do
+
+**Build models programmatically**
+
+```python
+from etcion import (
+    BusinessProcess, ApplicationService, ApplicationComponent,
+    Model, Serving, Assignment,
+)
+
+order_handling = BusinessProcess(name="Order Handling")
+api = ApplicationService(name="Order API")
+backend = ApplicationComponent(name="Order Service")
+
+model = Model(concepts=[
+    order_handling, api, backend,
+    Serving(name="serves", source=api, target=order_handling),
+    Assignment(name="runs", source=backend, target=api),
+])
+```
+
+**Query the model graph**
+
+```python
+model.elements_by_layer(Layer.BUSINESS)
+model.elements_by_name("Order", regex=False)
+model.connected_to(backend)
+model.sources_of(order_handling)
+```
+
+**Detect structural patterns**
+
+```python
+from etcion.patterns import Pattern, RequiredPatternRule
+
+# Every BusinessService must be backed by an ApplicationService
+service_backing = (
+    Pattern()
+    .node("biz", BusinessService)
+    .node("app", ApplicationService)
+    .edge("app", "biz", Serving)
+)
+
+# Find services missing their backing
+gaps = service_backing.gaps(model, anchor="biz")
+
+# Enforce as a validation rule
+model.add_validation_rule(RequiredPatternRule(
+    pattern=service_backing,
+    anchor="biz",
+    description="Every BusinessService must be served by an ApplicationService",
+))
+```
+
+**Detect anti-patterns**
+
+```python
+from etcion.patterns import AntiPatternRule
+
+# Technology should not directly serve Business (must go through Application)
+bad_pattern = (
+    Pattern()
+    .node("tech", TechnologyService)
+    .node("biz", BusinessProcess)
+    .edge("tech", "biz", Serving)
+)
+
+model.add_validation_rule(AntiPatternRule(
+    pattern=bad_pattern,
+    description="Technology must not directly serve Business layer",
+))
+```
+
+**Model what-if scenarios**
+
+```python
+from etcion import analyze_impact, chain_impacts
+
+# What breaks if we decommission the legacy CRM?
+impact = analyze_impact(model, remove=legacy_crm, max_depth=3)
+for item in impact.affected:
+    print(f"  depth={item.depth}  {item.concept.name}")
+print(f"Broken relationships: {len(impact.broken_relationships)}")
+
+# What happens if we consolidate three systems onto one platform?
+impact = analyze_impact(model, merge=([sys_a, sys_b, sys_c], target_platform))
+print(f"Permission violations: {len(impact.violations)}")
+
+# Chain multiple changes and validate the result
+i1 = analyze_impact(model, remove=old_system)
+i2 = analyze_impact(i1.resulting_model, replace=(legacy_db, cloud_db))
+errors = i2.resulting_model.validate()
+```
+
+**Validate against the spec**
+
+```python
+errors = model.validate()           # Collect all errors
+model.validate(strict=True)         # Raise on first error
+
+from etcion import is_permitted, Serving, ApplicationService, BusinessProcess
+is_permitted(Serving, ApplicationService, BusinessProcess)  # True
+```
+
+**Exchange with Archi and other tools**
+
+```python
+from etcion.serialization.xml import write_model, read_model
+
+write_model(model, "architecture.xml", model_name="My Architecture")
+loaded = read_model("exported_from_archi.xml")
+```
+
+**Compare model versions**
+
+```python
+from etcion import diff_models
+
+diff = diff_models(baseline_model, proposed_model)
+print(diff.summary())  # "ModelDiff: 3 added, 1 removed, 2 modified"
+```
+
+## Installation
+
+```bash
+pip install etcion              # Core library
+pip install etcion[xml]         # + XML serialization (lxml)
+pip install etcion[graph]       # + Pattern matching & impact analysis (networkx)
+pip install etcion[xml,graph]   # Both
+```
+
+Requires Python 3.12 or later.
+
+## ArchiMate Coverage
+
+58 concrete element types across all 7 layers, 11 relationship types, Junction, and 28 predefined viewpoints.
+
+| Layer | Elements |
+|-------|----------|
+| Strategy | Resource, Capability, ValueStream, CourseOfAction |
+| Business | BusinessActor, BusinessRole, BusinessCollaboration, BusinessInterface, BusinessProcess, BusinessFunction, BusinessInteraction, BusinessEvent, BusinessService, BusinessObject, Contract, Representation, Product |
+| Application | ApplicationComponent, ApplicationCollaboration, ApplicationInterface, ApplicationFunction, ApplicationInteraction, ApplicationProcess, ApplicationEvent, ApplicationService, DataObject |
+| Technology | Node, Device, SystemSoftware, TechnologyCollaboration, TechnologyInterface, Path, CommunicationNetwork, TechnologyFunction, TechnologyProcess, TechnologyInteraction, TechnologyEvent, TechnologyService, Artifact |
+| Physical | Equipment, Facility, DistributionNetwork, Material |
+| Motivation | Stakeholder, Driver, Assessment, Goal, Outcome, Principle, Requirement, Constraint, Meaning, Value |
+| Implementation & Migration | WorkPackage, Deliverable, ImplementationEvent, Plateau, Gap |
+
+## Archi Compatibility
+
+etcion reads and writes the Open Group ArchiMate Exchange Format, verified against [Archi](https://www.archimatetool.com/).
+
+**Import into Archi:** `File > Import > Open Exchange XML Model`
+**Export from Archi:** `File > Export > Open Exchange XML Model`
+
+Diagram layouts, folder organization, and visual styles survive round-trip as opaque XML.
+
+## Extending
+
+```python
+# Custom validation rules
+from etcion.validation.rules import ValidationRule
+
+class RequireDocumentation:
+    def validate(self, model):
+        from etcion.exceptions import ValidationError
+        return [
+            ValidationError(f"'{e.name}' has no documentation")
+            for e in model.elements if not e.description
+        ]
+
+model.add_validation_rule(RequireDocumentation())
+
+# Language customization via profiles
+from etcion.metamodel.profiles import Profile
+
+cloud_profile = Profile(
+    name="Cloud",
+    specializations={ApplicationComponent: ["Microservice", "Lambda", "Container"]},
+)
+model.apply_profile(cloud_profile)
+```
+
+## Development
+
+```bash
+git clone https://github.com/korpodevs/etcion.git
+cd etcion
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+pytest                    # 2685 tests
+ruff check src/ test/     # Lint
+mypy src/                 # Type check
+mkdocs serve              # Local docs
+```
+
+## License
+
+MIT