etcion 0.2.0__py3-none-any.whl

etcion/__init__.py

@@ -0,0 +1,350 @@
+"""etcion -- Python implementation of the ArchiMate 3.2 metamodel."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _meta_version
+
+try:
+    __version__: str = _meta_version("etcion")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0.dev0"
+
+# Phase 4: Model comparison and diff utilities (EPIC-024, FEAT-24.1)
+from etcion.comparison import ConceptChange, FieldChange, ModelDiff, diff_models
+from etcion.conformance import CONFORMANCE, ConformanceProfile
+from etcion.derivation.engine import DerivationEngine
+from etcion.enums import (
+    AccessMode,
+    Aspect,
+    AssociationDirection,
+    ContentCategory,
+    InfluenceSign,
+    JunctionType,
+    Layer,
+    PurposeCategory,
+    RelationshipCategory,
+)
+from etcion.exceptions import (
+    ConformanceError,
+    DerivationError,
+    PyArchiError,
+    ValidationError,
+)
+
+# Phase 5: Impact analysis engine (ADR-043, Issue #9)
+from etcion.impact import ImpactedConcept, ImpactResult, analyze_impact, chain_impacts
+
+# Phase 2: Application layer (EPIC-008)
+from etcion.metamodel.application import (
+    ApplicationCollaboration,
+    ApplicationComponent,
+    ApplicationEvent,
+    ApplicationFunction,
+    ApplicationInteraction,
+    ApplicationInterface,
+    ApplicationInternalActiveStructureElement,
+    ApplicationInternalBehaviorElement,
+    ApplicationProcess,
+    ApplicationService,
+    DataObject,
+)
+
+# Phase 2: Business layer (EPIC-007)
+from etcion.metamodel.business import (
+    BusinessActor,
+    BusinessCollaboration,
+    BusinessEvent,
+    BusinessFunction,
+    BusinessInteraction,
+    BusinessInterface,
+    BusinessInternalActiveStructureElement,
+    BusinessInternalBehaviorElement,
+    BusinessObject,
+    BusinessPassiveStructureElement,
+    BusinessProcess,
+    BusinessRole,
+    BusinessService,
+    Contract,
+    Product,
+    Representation,
+)
+from etcion.metamodel.concepts import (
+    Concept,
+    Element,
+    Relationship,
+    RelationshipConnector,
+)
+from etcion.metamodel.elements import (
+    ActiveStructureElement,
+    BehaviorElement,
+    CompositeElement,
+    Event,
+    ExternalActiveStructureElement,
+    ExternalBehaviorElement,
+    Function,
+    Grouping,
+    Interaction,
+    InternalActiveStructureElement,
+    InternalBehaviorElement,
+    Location,
+    MotivationElement,
+    PassiveStructureElement,
+    Process,
+    StructureElement,
+)
+
+# Phase 2: Implementation & Migration layer (EPIC-012)
+from etcion.metamodel.implementation_migration import (
+    Deliverable,
+    Gap,
+    ImplementationEvent,
+    Plateau,
+    WorkPackage,
+)
+from etcion.metamodel.model import Model
+
+# Phase 2: Motivation layer (EPIC-011)
+from etcion.metamodel.motivation import (
+    Assessment,
+    Constraint,
+    Driver,
+    Goal,
+    Meaning,
+    Outcome,
+    Principle,
+    Requirement,
+    Stakeholder,
+    Value,
+)
+from etcion.metamodel.notation import NotationMetadata
+
+# Phase 2: Physical layer (EPIC-010)
+from etcion.metamodel.physical import (
+    DistributionNetwork,
+    Equipment,
+    Facility,
+    Material,
+    PhysicalActiveStructureElement,
+    PhysicalPassiveStructureElement,
+)
+
+# Phase 3: Language customization (EPIC-018)
+from etcion.metamodel.profiles import Profile
+from etcion.metamodel.relationships import (
+    Access,
+    Aggregation,
+    Assignment,
+    Association,
+    Composition,
+    DependencyRelationship,
+    DynamicRelationship,
+    Flow,
+    Influence,
+    Junction,
+    OtherRelationship,
+    Realization,
+    Serving,
+    Specialization,
+    StructuralRelationship,
+    Triggering,
+)
+
+# Phase 2: Strategy layer (EPIC-006)
+from etcion.metamodel.strategy import (
+    Capability,
+    CourseOfAction,
+    Resource,
+    StrategyBehaviorElement,
+    StrategyStructureElement,
+    ValueStream,
+)
+
+# Phase 2: Technology layer (EPIC-009)
+from etcion.metamodel.technology import (
+    Artifact,
+    CommunicationNetwork,
+    Device,
+    Node,
+    Path,
+    SystemSoftware,
+    TechnologyCollaboration,
+    TechnologyEvent,
+    TechnologyFunction,
+    TechnologyInteraction,
+    TechnologyInterface,
+    TechnologyInternalActiveStructureElement,
+    TechnologyInternalBehaviorElement,
+    TechnologyProcess,
+    TechnologyService,
+)
+
+# Phase 4: Predefined Viewpoint Catalogue (EPIC-022, FEAT-22.1)
+from etcion.metamodel.viewpoint_catalogue import VIEWPOINT_CATALOGUE, ViewpointCatalogue
+
+# Phase 3: Viewpoints (EPIC-017)
+from etcion.metamodel.viewpoints import Concern, View, Viewpoint
+from etcion.validation.permissions import is_permitted, warm_cache
+from etcion.validation.rules import ValidationRule
+
+SPEC_VERSION: str = "3.2"
+"""The ArchiMate specification version implemented by this library."""
+
+__all__: list[str] = [
+    "__version__",
+    "SPEC_VERSION",
+    # exceptions (FEAT-00.2)
+    "PyArchiError",
+    "ValidationError",
+    "DerivationError",
+    "ConformanceError",
+    # conformance (FEAT-01.1)
+    "ConformanceProfile",
+    "CONFORMANCE",
+    # root type hierarchy (EPIC-002)
+    "Concept",
+    "Element",
+    "Relationship",
+    "RelationshipConnector",
+    "Model",
+    # language structure (EPIC-003)
+    "Aspect",
+    "Layer",
+    "NotationMetadata",
+    # EPIC-004: Generic Metamodel -- Abstract Element Hierarchy
+    "ActiveStructureElement",
+    "BehaviorElement",
+    "CompositeElement",
+    "Event",
+    "ExternalActiveStructureElement",
+    "ExternalBehaviorElement",
+    "Function",
+    "Grouping",
+    "InternalActiveStructureElement",
+    "InternalBehaviorElement",
+    "Interaction",
+    "Location",
+    "MotivationElement",
+    "PassiveStructureElement",
+    "Process",
+    "StructureElement",
+    # EPIC-005: Relationships and Relationship Connectors
+    "RelationshipCategory",
+    "AccessMode",
+    "AssociationDirection",
+    "InfluenceSign",
+    "JunctionType",
+    "StructuralRelationship",
+    "DependencyRelationship",
+    "DynamicRelationship",
+    "OtherRelationship",
+    "Composition",
+    "Aggregation",
+    "Assignment",
+    "Realization",
+    "Serving",
+    "Access",
+    "Influence",
+    "Association",
+    "Triggering",
+    "Flow",
+    "Specialization",
+    "Junction",
+    "DerivationEngine",
+    "is_permitted",
+    "warm_cache",
+    "ValidationRule",
+    # Strategy layer (EPIC-006)
+    "StrategyStructureElement",
+    "StrategyBehaviorElement",
+    "Resource",
+    "Capability",
+    "ValueStream",
+    "CourseOfAction",
+    # Business layer (EPIC-007)
+    "BusinessInternalActiveStructureElement",
+    "BusinessInternalBehaviorElement",
+    "BusinessPassiveStructureElement",
+    "BusinessActor",
+    "BusinessRole",
+    "BusinessCollaboration",
+    "BusinessInterface",
+    "BusinessProcess",
+    "BusinessFunction",
+    "BusinessInteraction",
+    "BusinessEvent",
+    "BusinessService",
+    "BusinessObject",
+    "Contract",
+    "Representation",
+    "Product",
+    # Application layer (EPIC-008)
+    "ApplicationInternalActiveStructureElement",
+    "ApplicationInternalBehaviorElement",
+    "ApplicationComponent",
+    "ApplicationCollaboration",
+    "ApplicationInterface",
+    "ApplicationFunction",
+    "ApplicationInteraction",
+    "ApplicationProcess",
+    "ApplicationEvent",
+    "ApplicationService",
+    "DataObject",
+    # Technology layer (EPIC-009)
+    "TechnologyInternalActiveStructureElement",
+    "TechnologyInternalBehaviorElement",
+    "Node",
+    "Device",
+    "SystemSoftware",
+    "TechnologyCollaboration",
+    "TechnologyInterface",
+    "Path",
+    "CommunicationNetwork",
+    "TechnologyFunction",
+    "TechnologyProcess",
+    "TechnologyInteraction",
+    "TechnologyEvent",
+    "TechnologyService",
+    "Artifact",
+    # Physical layer (EPIC-010)
+    "PhysicalActiveStructureElement",
+    "PhysicalPassiveStructureElement",
+    "Equipment",
+    "Facility",
+    "DistributionNetwork",
+    "Material",
+    # Motivation layer (EPIC-011)
+    "Stakeholder",
+    "Driver",
+    "Assessment",
+    "Goal",
+    "Outcome",
+    "Principle",
+    "Requirement",
+    "Constraint",
+    "Meaning",
+    "Value",
+    # Implementation & Migration layer (EPIC-012)
+    "WorkPackage",
+    "Deliverable",
+    "ImplementationEvent",
+    "Plateau",
+    "Gap",
+    # Viewpoints & Language Customization (Phase 3)
+    "Viewpoint",
+    "View",
+    "Concern",
+    "Profile",
+    "PurposeCategory",
+    "ContentCategory",
+    # Predefined Viewpoint Catalogue (EPIC-022, FEAT-22.1)
+    "ViewpointCatalogue",
+    "VIEWPOINT_CATALOGUE",
+    # Model comparison and diff utilities (EPIC-024, FEAT-24.1)
+    "FieldChange",
+    "ConceptChange",
+    "ModelDiff",
+    "diff_models",
+    # Impact analysis engine (ADR-043, Issue #9)
+    "ImpactedConcept",
+    "ImpactResult",
+    "analyze_impact",
+]

etcion/comparison.py

@@ -0,0 +1,152 @@
+"""Model comparison and diff utilities (EPIC-024, FEAT-24.1 / FEAT-24.2)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from etcion.metamodel.concepts import Concept, Relationship
+from etcion.metamodel.model import Model
+
+__all__: list[str] = [
+    "FieldChange",
+    "ConceptChange",
+    "ModelDiff",
+    "diff_models",
+]
+
+
+@dataclass(frozen=True)
+class FieldChange:
+    """A single field-level change between two concept snapshots."""
+
+    field: str
+    old: Any
+    new: Any
+
+
+@dataclass(frozen=True)
+class ConceptChange:
+    """A concept present in both models whose fields differ."""
+
+    concept_id: str
+    concept_type: str
+    changes: dict[str, FieldChange]
+
+
+@dataclass(frozen=True)
+class ModelDiff:
+    """Immutable result of comparing two models."""
+
+    added: tuple[Concept, ...]
+    removed: tuple[Concept, ...]
+    modified: tuple[ConceptChange, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable dict representation."""
+
+        def _concept_entry(c: Concept) -> dict[str, Any]:
+            return {
+                "id": c.id,
+                "type": type(c).__name__,
+                "name": getattr(c, "name", None),
+            }
+
+        def _change_entry(cc: ConceptChange) -> dict[str, Any]:
+            return {
+                "concept_id": cc.concept_id,
+                "concept_type": cc.concept_type,
+                "changes": {k: {"old": fc.old, "new": fc.new} for k, fc in cc.changes.items()},
+            }
+
+        return {
+            "added": [_concept_entry(c) for c in self.added],
+            "removed": [_concept_entry(c) for c in self.removed],
+            "modified": [_change_entry(cc) for cc in self.modified],
+        }
+
+    def summary(self) -> str:
+        """Return a human-readable one-line summary."""
+        return (
+            f"ModelDiff: {len(self.added)} added, "
+            f"{len(self.removed)} removed, "
+            f"{len(self.modified)} modified"
+        )
+
+    def __str__(self) -> str:
+        return self.summary()
+
+    def __bool__(self) -> bool:
+        return bool(self.added or self.removed or self.modified)
+
+
+def _build_key(concept: Concept, match_by: Literal["id", "type_name"]) -> str | tuple[str, str]:
+    """Return the lookup key for a concept."""
+    if match_by == "id":
+        return concept.id
+    # match_by == "type_name"
+    name = getattr(concept, "name", "") or ""
+    return (type(concept).__name__, name)
+
+
+def _normalize_dump(concept: Concept) -> dict[str, Any]:
+    """Return a model_dump() dict with id removed and source/target normalized."""
+    d = concept.model_dump()
+    d.pop("id", None)
+    if isinstance(concept, Relationship):
+        d["source"] = concept.source.id
+        d["target"] = concept.target.id
+    return d
+
+
+def _diff_fields(dump_a: dict[str, Any], dump_b: dict[str, Any]) -> dict[str, FieldChange]:
+    """Compare two normalized dumps, returning changed fields."""
+    changes: dict[str, FieldChange] = {}
+    all_keys = dump_a.keys() | dump_b.keys()
+    for key in all_keys:
+        old = dump_a.get(key)
+        new = dump_b.get(key)
+        if old != new:
+            changes[key] = FieldChange(field=key, old=old, new=new)
+    return changes
+
+
+def diff_models(
+    model_a: Model,
+    model_b: Model,
+    *,
+    match_by: Literal["id", "type_name"] = "id",
+) -> ModelDiff:
+    """Compare two models and return a structured diff.
+
+    :param model_a: Baseline ("before") model.
+    :param model_b: Revised ("after") model.
+    :param match_by: ``"id"`` matches concepts by id; ``"type_name"`` matches
+        by ``(type_name, name)`` tuple.
+    :returns: A frozen :class:`ModelDiff`.
+    """
+    lookup_a = {_build_key(c, match_by): c for c in model_a.concepts}
+    lookup_b = {_build_key(c, match_by): c for c in model_b.concepts}
+
+    keys_a = set(lookup_a)
+    keys_b = set(lookup_b)
+
+    added = tuple(lookup_b[k] for k in keys_b - keys_a)
+    removed = tuple(lookup_a[k] for k in keys_a - keys_b)
+
+    modified: list[ConceptChange] = []
+    for key in keys_a & keys_b:
+        ca, cb = lookup_a[key], lookup_b[key]
+        dump_a = _normalize_dump(ca)
+        dump_b = _normalize_dump(cb)
+        changes = _diff_fields(dump_a, dump_b)
+        if changes:
+            modified.append(
+                ConceptChange(
+                    concept_id=ca.id,
+                    concept_type=type(ca).__name__,
+                    changes=changes,
+                )
+            )
+
+    return ModelDiff(added=added, removed=removed, modified=tuple(modified))

etcion/conformance.py

@@ -0,0 +1,136 @@
+"""Conformance profile for the etcion ArchiMate 3.2 implementation.
+
+This module declares which features of the ArchiMate 3.2 specification the
+library commits to implementing.  The :class:`ConformanceProfile` dataclass
+carries boolean flags grouped by the specification's three compliance levels:
+
+* **shall** -- mandatory features for a conformant implementation.
+* **should** -- recommended features the library plans to support.
+* **may** -- optional features explicitly out of scope.
+
+The module-level :data:`CONFORMANCE` singleton is the canonical instance.
+It is re-exported from ``etcion.__init__`` so consumers can inspect the
+library's conformance declaration via ``etcion.CONFORMANCE``.
+
+.. note::
+   This module does **not** import ``SPEC_VERSION`` from ``etcion.__init__``
+   to avoid a circular import.  The ``spec_version`` field uses the literal
+   ``"3.2"`` as its default.  The conformance test suite asserts that this
+   value equals ``etcion.SPEC_VERSION``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__: list[str] = [
+    "ConformanceProfile",
+    "CONFORMANCE",
+]
+
+
+@dataclass(frozen=True)
+class ConformanceProfile:
+    """Machine-readable declaration of ArchiMate 3.2 conformance scope.
+
+    Every field defaults to the library's declared intent.  ``shall``-level
+    and ``should``-level fields default to ``True`` (the library commits to
+    implementing them).  The sole ``may``-level field defaults to ``False``
+    (explicitly out of scope).
+
+    The dataclass is frozen to prevent accidental mutation of the library's
+    conformance contract.
+    """
+
+    # --- spec version ---
+
+    # The ArchiMate specification version this profile targets.
+    spec_version: str = "3.2"
+
+    # --- shall-level (mandatory for conformance) ---
+
+    # Full classification framework: layers (7) and aspects (5).
+    # Reference: ArchiMate 3.2 Specification, Sections 3.4--3.5.
+    language_structure: bool = True
+
+    # Abstract element hierarchy: Concept, Element, Relationship,
+    # RelationshipConnector ABCs.
+    # Reference: ArchiMate 3.2 Specification, Section 3.1.
+    generic_metamodel: bool = True
+
+    # Strategy layer element types: Resource, Capability, ValueStream,
+    # CourseOfAction.
+    # Reference: ArchiMate 3.2 Specification, Chapter 7.
+    strategy_elements: bool = True
+
+    # Motivation layer element types: Stakeholder, Driver, Assessment, Goal,
+    # Outcome, Principle, Requirement, Constraint, Meaning, Value.
+    # Reference: ArchiMate 3.2 Specification, Chapter 6.
+    motivation_elements: bool = True
+
+    # Business layer element types: BusinessActor, BusinessRole,
+    # BusinessCollaboration, BusinessInterface, BusinessProcess,
+    # BusinessFunction, BusinessInteraction, BusinessEvent,
+    # BusinessService, BusinessObject, Contract, Representation, Product.
+    # Reference: ArchiMate 3.2 Specification, Chapter 8.
+    business_elements: bool = True
+
+    # Application layer element types: ApplicationComponent,
+    # ApplicationCollaboration, ApplicationInterface, ApplicationFunction,
+    # ApplicationInteraction, ApplicationProcess, ApplicationEvent,
+    # ApplicationService, DataObject.
+    # Reference: ArchiMate 3.2 Specification, Chapter 9.
+    application_elements: bool = True
+
+    # Technology layer element types: Node, Device, SystemSoftware,
+    # TechnologyCollaboration, TechnologyInterface, Path,
+    # CommunicationNetwork, TechnologyFunction, TechnologyProcess,
+    # TechnologyInteraction, TechnologyEvent, TechnologyService, Artifact.
+    # Reference: ArchiMate 3.2 Specification, Chapter 10.
+    technology_elements: bool = True
+
+    # Physical layer element types: Equipment, Facility,
+    # DistributionNetwork, Material.
+    # Reference: ArchiMate 3.2 Specification, Chapter 11.
+    physical_elements: bool = True
+
+    # Implementation & Migration layer element types: WorkPackage,
+    # Deliverable, ImplementationEvent, Plateau, Gap.
+    # Reference: ArchiMate 3.2 Specification, Chapter 13.
+    implementation_migration_elements: bool = True
+
+    # Support for relationships that cross layer boundaries, including all
+    # 11 concrete relationship types and the Junction connector.
+    # Reference: ArchiMate 3.2 Specification, Chapter 5.
+    cross_layer_relationships: bool = True
+
+    # Full Appendix B relationship permission matrix encoding and the
+    # ``is_permitted`` lookup function.
+    # Reference: ArchiMate 3.2 Specification, Appendix B.
+    relationship_permission_table: bool = True
+
+    # Notation metadata: corner shapes, default layer colors, and badge
+    # letters for each concrete element type.
+    # Reference: ArchiMate 3.2 Specification, Appendix A.
+    iconography_metadata: bool = True
+
+    # --- should-level (recommended, not mandatory) ---
+
+    # Defining and applying viewpoints to filter model views.
+    # Reference: ArchiMate 3.2 Specification, Chapter 14.
+    viewpoint_mechanism: bool = True
+
+    # Profile and extension mechanisms for customizing the language.
+    # Reference: ArchiMate 3.2 Specification, Chapter 15.
+    language_customization: bool = True
+
+    # --- may-level (optional, out of scope) ---
+
+    # Appendix C example viewpoints (Basic, Organization, etc.).
+    # This feature does not affect conformance checks.
+    # Reference: ArchiMate 3.2 Specification, Appendix C.
+    example_viewpoints: bool = False
+
+
+CONFORMANCE: ConformanceProfile = ConformanceProfile()
+"""The canonical conformance profile singleton for the etcion library."""

etcion/derivation/__init__.py

@@ -0,0 +1,19 @@
+"""etcion.derivation -- Relationship derivation engine.
+
+This sub-package implements the ArchiMate 3.2 relationship derivation rules,
+computing implied (derived) relationships from chains of direct relationships
+in a model.
+
+Modules
+-------
+engine
+    DerivationEngine class implementing the derive() method and chain
+    traversal logic.  (TODO: EPIC-005, FEAT-05.10)
+
+Import policy
+-------------
+This package MAY import from etcion.metamodel, etcion.enums, and
+etcion.validation.  It is the top of the internal dependency graph.
+"""
+
+# No public symbols yet -- DerivationEngine is added in EPIC-005.