feat(rules): add within field to distinguish top-level container kind

Enrich IR nodes/edges with `within` (top-level container kind) alongside immediate `kind`, update rule field accessors/docs/examples, and add tests covering nested container behavior.

Author: akhundMurad

docs/architecture/v2.md

@@ -76,6 +76,39 @@ All v1 container fields (`name`, `description`, `context`, `code`, `tags`) remai
 | `module` | Logical module within a service |
 | `library` | Shared library used by other containers |
 
+### Enriched Fields: `kind` vs `within`
+
+When code is analyzed, each node and edge is enriched with container metadata. For nested containers, there are two important fields:
+
+| Field | Meaning | Example Value |
+|-------|---------|---------------|
+| `kind` | Immediate container's kind | `module` for code in `billing-service.invoice-module` |
+| `within` | Top-level container's kind | `service` for any code inside `billing-service` |
+
+**Example:** For code at `services/billing/domain/invoice/model/invoice.py`:
+
+```
+billing-service (kind: service)
+└── invoice-module (kind: module)
+    └── model/invoice.py  ← this file
+```
+
+The enriched fields would be:
+
+| Field | Value |
+|-------|-------|
+| `container` | `billing-service.invoice-module` |
+| `service` | `billing-service` |
+| `kind` | `module` |
+| `within` | `service` |
+
+**When to use each in rules:**
+
+- Use `kind` to match the specific container type (e.g., target only code directly in modules)
+- Use `within` to match anything inside a service hierarchy (e.g., catch all service code, including nested modules)
+
+See [Rules DSL: kind vs within](../rules.md#kind-vs-within) for detailed examples.
+
 ### Dot-Qualified IDs
 
 Nested containers are addressed using dot-qualified IDs. For the example above:

docs/rules.md

@@ -41,8 +41,9 @@ rule:
 | Field | Description |
 |-------|-------------|
 | `node.symbol_kind` | Symbol type: `file`, `module`, `class`, `function`, etc. |
-| `node.kind` | Container kind: `service`, `module`, `library` (v2 only) |
-| `node.service` | Top-level container ancestor (v2 only) |
+| `node.kind` | Immediate container kind: `service`, `module`, `library` (v2 only) |
+| `node.within` | Top-level container's kind (v2 only) — see [kind vs within](#kind-vs-within) |
+| `node.service` | Top-level container ancestor ID (v2 only) |
 | `node.path` | File path |
 | `node.name` | Symbol name |
 | `node.layer` | Architectural layer |
@@ -59,8 +60,9 @@ rule:
 | `from.layer` / `to.layer` | Source/target layer |
 | `from.context` / `to.context` | Source/target bounded context |
 | `from.container` / `to.container` | Source/target container ID |
-| `from.service` / `to.service` | Source/target top-level service (v2 only) |
-| `from.kind` / `to.kind` | Source/target container kind (v2 only) |
+| `from.service` / `to.service` | Source/target top-level service ID (v2 only) |
+| `from.kind` / `to.kind` | Source/target immediate container kind (v2 only) |
+| `from.within` / `to.within` | Source/target top-level container's kind (v2 only) — see [kind vs within](#kind-vs-within) |
 | `from.fqname` / `to.fqname` | Fully qualified names |
 | `from.id` / `to.id` | Full canonical ID strings |
 | `dep.type` | Dependency type (`import`, `call`, etc.) |
@@ -154,9 +156,36 @@ rule:
   suggestion: Access infrastructure through application services instead
 ```
 
+## kind vs within
+
+In v2 schemas with nested containers, there's an important distinction:
+
+| Field | Meaning | Example |
+|-------|---------|---------|
+| `kind` | Immediate container's kind | `module` for code in `billing-service.invoice-module` |
+| `within` | Top-level container's kind | `service` for any code inside `billing-service` |
+
+**When to use each:**
+
+- Use **`kind`** when you want to match the specific container type (e.g., "only code directly in a module")
+- Use **`within`** when you want to match anything inside a service hierarchy (e.g., "any code belonging to a service, including nested modules")
+
+**Example:** Code at `services/billing/domain/invoice/model/invoice.py` inside `billing-service.invoice-module`:
+
+```
+billing-service (kind: service)
+└── invoice-module (kind: module)
+    └── invoice.py  ← this file
+```
+
+| Field | Value |
+|-------|-------|
+| `kind` | `module` (immediate container) |
+| `within` | `service` (top-level container) |
+
 ## Example: Cross-Service Rules (v2)
 
-These rules use v2-only fields (`from.service`, `to.service`, `from.kind`, `to.kind`):
+These rules use v2-only fields (`from.service`, `to.service`, `from.kind`, `to.kind`, `from.within`, `to.within`):
 
 ```yaml
 # Forbid cross-service domain dependencies
@@ -172,7 +201,7 @@ rule:
       - from.layer == domain
   message: Domain code must not depend on another service
 
-# Libraries must not depend on services
+# Libraries must not depend on services (using 'within' for nested containers)
 rule:
   id: library-no-service-deps
   name: Libraries must be independent of services
@@ -181,7 +210,13 @@ rule:
   action: forbid
   when:
     all:
-      - from.kind == library
-      - to.kind == service
+      - from.within == library
+      - to.within == service
   message: Library code must not import service code
+  suggestion: Move shared code to a library or create a proper API contract
 ```
+
+!!! note "Why use `within` instead of `kind`?"
+    Using `to.kind == service` would NOT match code inside nested modules like `billing-service.invoice-module`, because the immediate container's kind is `module`, not `service`.
+
+    Using `to.within == service` matches ANY code inside a service hierarchy, including nested modules.

examples/microservices-platform/README.md

@@ -24,12 +24,25 @@ The platform consists of three containers:
 The rules demonstrate v2-specific fields:
 
 - `from.service != to.service` — detect cross-service dependencies
-- `from.kind == library` / `to.kind == service` — enforce library independence
+- `from.within == library` / `to.within == service` — enforce library independence
 - `from.layer` / `to.layer` — standard layer constraints
 
+### `kind` vs `within`
+
+For nested containers, there's an important distinction:
+
+| Field | Meaning | Example |
+|-------|---------|---------|
+| `kind` | Immediate container's kind | `module` for code in `invoice-module` |
+| `within` | Top-level container's kind | `service` for any code inside `billing-service` |
+
+**Why use `within`?** Using `to.kind == service` would NOT match code inside nested modules (like `invoice-module`), because the immediate kind is `module`. Using `to.within == service` matches ANY code inside the service hierarchy.
+
 ## Running
 
 ```bash
 cd examples/microservices-platform
 pacta scan . --model architecture.yml --rules rules.pacta.yml
 ```
+
+This will detect a violation because `libs/shared/money.py` imports from `services/billing/domain/invoice/model/invoice.py`.

examples/microservices-platform/libs/shared/money.py

@@ -1,3 +1,12 @@
+# This import violates the library-no-service-deps rule
+# Libraries should not depend on service code
+from services.billing.domain.invoice.model.invoice import Invoice
+
+
 class Money:
     def __init__(self, amount: float):
         self.amount = amount
+
+    def to_invoice(self) -> Invoice:
+        # This method couples library code to service code - a violation!
+        return Invoice(amount=self.amount)

examples/microservices-platform/rules.pacta.yml

@@ -1,33 +1,49 @@
-rules:
-  - id: no-cross-service-domain-deps
-    name: Domain must not depend on other services
-    severity: error
-    target: dependency
-    action: forbid
-    when:
-      all:
-        - from.service != to.service
-        - from.layer == domain
-    message: Domain code must not depend on another service
+# Microservices Platform Rules
+#
+# Field reference:
+#   - kind: immediate container's kind (service, module, library)
+#   - within: top-level container's kind (for nested containers)
+#
+# Example: code in billing-service.invoice-module has:
+#   - kind = 'module' (immediate container)
+#   - within = 'service' (top-level container)
+#
+# Use 'within' to match any code inside a service hierarchy (including nested modules).
+# Use 'kind' to match only the immediate container type.
 
-  - id: library-no-service-deps
-    name: Libraries must be independent of services
-    severity: error
-    target: dependency
-    action: forbid
-    when:
-      all:
-        - from.kind == library
-        - to.kind == service
-    message: Library code must not import service code
+rule:
+  id: no-cross-service-domain-deps
+  name: Domain must not depend on other services
+  severity: error
+  target: dependency
+  action: forbid
+  when:
+    all:
+      - from.service != to.service
+      - from.layer == domain
+  message: Domain code must not depend on another service
 
-  - id: no-infra-to-api
-    name: Infrastructure must not depend on API layer
-    severity: error
-    target: dependency
-    action: forbid
-    when:
-      all:
-        - from.layer == infra
-        - to.layer == api
-    message: Infrastructure layer must not depend on the API layer
+rule:
+  id: library-no-service-deps
+  name: Libraries must be independent of services
+  severity: error
+  target: dependency
+  action: forbid
+  when:
+    all:
+      - from.within == library
+      - to.within == service
+  message: Library code must not import service code
+  suggestion: Move shared code to a library or create a proper API contract
+
+rule:
+  id: no-infra-to-api
+  name: Infrastructure must not depend on API layer
+  severity: error
+  target: dependency
+  action: forbid
+  when:
+    all:
+      - from.layer == infra
+      - to.layer == api
+  message: Infrastructure layer must not depend on the API layer

pacta/ir/types.py

@@ -146,7 +146,8 @@ class IRNode:
 
     # v2: service-level enrichment
     service: str | None = None  # top-level container ancestor
-    container_kind: str | None = None  # container kind (service/module/library)
+    container_kind: str | None = None  # immediate container kind (service/module/library)
+    within: str | None = None  # top-level container's kind (for nested containers)
 
     attributes: Mapping[str, Any] = field(default_factory=dict)
 
@@ -163,6 +164,7 @@ def to_dict(self) -> dict[str, Any]:
             "tags": list(self.tags),
             "service": self.service,
             "container_kind": self.container_kind,
+            "within": self.within,
             "attributes": dict(self.attributes),
         }
 
@@ -180,6 +182,7 @@ def from_dict(data: Mapping[str, Any]) -> "IRNode":
             tags=tuple(data.get("tags", [])),
             service=data.get("service"),
             container_kind=data.get("container_kind"),
+            within=data.get("within"),
             attributes=dict(data.get("attributes", {})),
         )
 
@@ -214,6 +217,8 @@ class IREdge:
     dst_service: str | None = None
     src_container_kind: str | None = None
     dst_container_kind: str | None = None
+    src_within: str | None = None  # top-level container's kind for source
+    dst_within: str | None = None  # top-level container's kind for destination
 
     def to_dict(self) -> dict[str, Any]:
         return {
@@ -233,6 +238,8 @@ def to_dict(self) -> dict[str, Any]:
             "dst_service": self.dst_service,
             "src_container_kind": self.src_container_kind,
             "dst_container_kind": self.dst_container_kind,
+            "src_within": self.src_within,
+            "dst_within": self.dst_within,
         }
 
     @staticmethod
@@ -254,6 +261,8 @@ def from_dict(data: Mapping[str, Any]) -> "IREdge":
             dst_service=data.get("dst_service"),
             src_container_kind=data.get("src_container_kind"),
             dst_container_kind=data.get("dst_container_kind"),
+            src_within=data.get("src_within"),
+            dst_within=data.get("dst_within"),
         )
 
 

pacta/mapping/enricher.py

@@ -72,14 +72,20 @@ def _enrich_node(self, node: IRNode, model: ArchitectureModel) -> IRNode:
         if container_id is not None:
             context_id = model.get_context_for_container(container_id)
 
-        # v2: derive service (top-level ancestor) and container_kind
+        # v2: derive service (top-level ancestor), container_kind, and within
         service: str | None = None
         container_kind: str | None = None
+        within: str | None = None
         if container_id is not None:
             service = container_id.split(".")[0]
+            # container_kind = immediate container's kind
             container = model.get_container(container_id)
             if container is not None and container.kind is not None:
                 container_kind = container.kind.value
+            # within = top-level container's kind (for nested containers)
+            top_container = model.get_container(service)
+            if top_container is not None and top_container.kind is not None:
+                within = top_container.kind.value
 
         # Return enriched node if anything changed, otherwise return original
         if (
@@ -89,6 +95,7 @@ def _enrich_node(self, node: IRNode, model: ArchitectureModel) -> IRNode:
             and node.tags == tags
             and node.service == service
             and node.container_kind == container_kind
+            and node.within == within
         ):
             return node
 
@@ -100,6 +107,7 @@ def _enrich_node(self, node: IRNode, model: ArchitectureModel) -> IRNode:
             tags=tags,
             service=service,
             container_kind=container_kind,
+            within=within,
         )
 
     def _match_container(self, node: IRNode, model: ArchitectureModel) -> str | None:
@@ -175,12 +183,14 @@ def _enrich_edge(self, edge: IREdge, node_lookup: dict[str, IRNode]) -> IREdge:
         src_context = src_node.context if src_node else None
         src_service = src_node.service if src_node else None
         src_container_kind = src_node.container_kind if src_node else None
+        src_within = src_node.within if src_node else None
 
         dst_container = dst_node.container if dst_node else None
         dst_layer = dst_node.layer if dst_node else None
         dst_context = dst_node.context if dst_node else None
         dst_service = dst_node.service if dst_node else None
         dst_container_kind = dst_node.container_kind if dst_node else None
+        dst_within = dst_node.within if dst_node else None
 
         # Return enriched edge if anything changed
         if (
@@ -194,6 +204,8 @@ def _enrich_edge(self, edge: IREdge, node_lookup: dict[str, IRNode]) -> IREdge:
             and edge.dst_service == dst_service
             and edge.src_container_kind == src_container_kind
             and edge.dst_container_kind == dst_container_kind
+            and edge.src_within == src_within
+            and edge.dst_within == dst_within
         ):
             return edge
 
@@ -209,6 +221,8 @@ def _enrich_edge(self, edge: IREdge, node_lookup: dict[str, IRNode]) -> IREdge:
             dst_service=dst_service,
             src_container_kind=src_container_kind,
             dst_container_kind=dst_container_kind,
+            src_within=src_within,
+            dst_within=dst_within,
         )
 
     def _normalize_path(self, path: str) -> str: