From 4f36c158d74f5691ba4a9213c7831d8eb81fbbd4 Mon Sep 17 00:00:00 2001 From: Vincent Landgraf Date: Fri, 13 Nov 2026 08:59:09 +0100 Subject: [PATCH] feat(resources): add Grouping, the ArchiMate composite element A Grouping aggregates or composes resources of every kind, groupings included, so groups nest. Members are listed on the grouping only, one key per kind under `aggregates` or `composedOf`; members show their groups as incoming relations. - Grouping.declare_members! declares both verbs towards every kind once all kinds are loaded; Resources.relation_key gives the spec key of a kind, matching the keys the model already uses - template shows a few member kinds instead of ~90 empty lists (Base.template_relations) - summary lens: Grouping lists its members, members name their groups - linter reports nesting cycles (existing hierarchy cycle check) - docs (archimate, modeling, index, icons) and a payments example Co-Authored-By: Claude Opus 5.5 --- docs/archimate.md | 7 +- docs/icons.md | 1 + docs/index.md.erb | 1 + docs/modeling.md | 36 +++- examples/archsight/groupings/payments.yaml | 41 ++++ lib/archsight/resources.rb | 28 +++ lib/archsight/resources/base.rb | 5 + lib/archsight/resources/grouping.rb | 80 ++++++++ lib/archsight/summary/lens.rb | 10 + lib/archsight/template.rb | 4 +- sig/archsight/resources.rbs | 4 + test/grouping_test.rb | 213 +++++++++++++++++++++ 12 files changed, 423 insertions(+), 7 deletions(-) create mode 100644 examples/archsight/groupings/payments.yaml create mode 100644 lib/archsight/resources/grouping.rb create mode 100644 test/grouping_test.rb diff --git a/docs/archimate.md b/docs/archimate.md index 62a5279..47fc0a5 100644 --- a/docs/archimate.md +++ b/docs/archimate.md @@ -44,8 +44,8 @@ ArchiMate is an open and independent enterprise architecture modeling language d | Relationship | Supported as | |--------------|--------------| | **Specialization** | `specializes` between technology elements of one kind (node, system software, service), see "Concept and Implementation" in the modeling guide | -| **Composition** | `composedOf` between nodes and between system software | -| **Aggregation** | `aggregates` between technology artifacts (an image contains packages), see "Deployment" in the modeling guide | +| **Composition** | `composedOf` between nodes and between system software; from a `Grouping` to resources of any kind | +| **Aggregation** | `aggregates` between technology artifacts (an image contains packages), see "Deployment" in the modeling guide; from a `Grouping` to resources of any kind | | **Assignment** | `assignedTo` from a node or system software to the technology artifacts deployed on it | ### Relationship Connectors @@ -198,7 +198,8 @@ call-offs, SLAs and amendments, `stipulates` the requirements and constraints it | **Grouping** | Aggregates or composes concepts that belong together based on some common characteristic. | | **Location** | A conceptual or physical place or position where concepts are located (structure elements) or performed (behavior elements). | -**Supported in archsight:** Location (`Location`) is modelled and shown under Other. Grouping is not. +**Supported in archsight:** Location (`Location`) and Grouping (`Grouping`) are modelled and shown under Other. A +grouping aggregates or composes resources of every kind, groupings included, see "Grouping" in the modeling guide. ## ArchiMate Layers diff --git a/docs/icons.md b/docs/icons.md index ae338b3..5ee6510 100644 --- a/docs/icons.md +++ b/docs/icons.md @@ -40,6 +40,7 @@ Current icon assignments for each resource type: | TechnologyDevice | `server` | | | TechnologyFacility | `building` | | | Location | `map-pin` | | +| Grouping | `square-dashed` | | | TechnologyNode | `server-connection` | | | StrategyCapability | `strategy` | | | TechnologyArtifact | `puzzle` | | diff --git a/docs/index.md.erb b/docs/index.md.erb index 6d7bb9c..a807212 100644 --- a/docs/index.md.erb +++ b/docs/index.md.erb @@ -93,6 +93,7 @@ Resources representing technology infrastructure and artifacts. ### Other - [ComplianceEvidence](/doc/resources/compliance_evidence) - Evidence for compliance requirements +- [Grouping](/doc/resources/grouping) - Domains, scopes and families of resources of any kind - [Location](/doc/resources/location) - Countries, metros, regions and other places - [View](/doc/resources/view) - Saved queries and custom views diff --git a/docs/modeling.md b/docs/modeling.md index 9f5a226..a8818ca 100644 --- a/docs/modeling.md +++ b/docs/modeling.md @@ -936,9 +936,10 @@ How to model it: - **Vulnerability scan.** One `MotivationAssessment` of type `vulnerability` per finding, `assesses` every node it was found on, `influences` the loss events and risks it makes possible. Business impact follows from the model: the node serves services, services serve processes. -- **Grouping (risk domains).** ArchiMate has no domain element; set `risk/domain` (and `risk/category`: hazard, +- **Risk domains.** Set `risk/domain` (and `risk/category`: hazard, financial, operational, strategic, compliance, security) on events, assessments, drivers, requirements, controls and - assets, and query or build a `View` per domain to see its threats, risks, measures and assets together. + assets, and query or build a `View` per domain to see its threats, risks, measures and assets together. A `Grouping` + is only worth it when the domain itself has an owner, a description or members that share no annotation. - **Policies.** The text of a policy is a `Page`; the structured statement (owner, validity, status, framework) is a `MotivationPrinciple` that links to the page with `[[Page]]`. - **Initial and residual risk.** Record both on the assessment (`risk/initial-*`, `risk/residual-*`) and the decision @@ -975,6 +976,37 @@ A ComplianceEvidence answers "how is the requirement met" in structured markdown `evidence/verification`, `evidence/gaps` and `evidence/sources`. Because they are separate annotations they can be queried, for example `ComplianceEvidence: evidence/gaps =~ "needs review"`. +### Grouping + +A `Grouping` gathers resources that belong together by a criterion that is not a place: a domain, the scope of a +programme or review, a product family that spans layers. It holds resources of every kind, other groupings included, so +groups nest. The members are listed on the grouping only, one key per kind under one of two verbs: + +| Verb | Means | Example | +|------|-------|---------| +| `aggregates` | the member belongs to the group and stands on its own; it can be in several groups | a shared service in two domains | +| `composedOf` | the member is a part of this whole and of no other | the components that exist only for the domain | + +```yaml +kind: Grouping +metadata: + name: Domain:Payments +spec: + aggregates: + strategyCapabilities: [Payment Processing] + groupings: [Domain:Payments:Refunds] + composedOf: + applicationComponents: [Payments:API, CardVault:API] +``` + +A member's page lists its groups under Relations, and the MCP `summary` names them ("Groups" or "Part of"). Queries +follow membership like any relation: `ApplicationComponent: <- Grouping` (in some group), `Grouping: -> "Payments:API"`. +A grouping that contains itself through other groupings is a cycle that `archsight lint` reports. + +Use a grouping when the set is a thing of its own (it has an owner, a description, a page). Resources that only share an +attribute (a team, a tag, a risk domain) are found by a query or a `View`; a place is a `Location`; the wiki menu is a +`PageMenu`. + ### Derived References Text and diagrams already say which resources they are about, so archsight turns that into relations instead of asking you diff --git a/examples/archsight/groupings/payments.yaml b/examples/archsight/groupings/payments.yaml new file mode 100644 index 0000000..d1b7f34 --- /dev/null +++ b/examples/archsight/groupings/payments.yaml @@ -0,0 +1,41 @@ +apiVersion: architecture/v1alpha1 +kind: Grouping +metadata: + name: Domain:Payments + annotations: + architecture/description: | + Everything that moves money for the online checkout: the capability, the product, the services and + components that realize it, and the platform they run on. Refunds form a group of their own inside it. +spec: + aggregates: + strategyCapabilities: + - Payment Processing + businessProducts: + - Online Checkout + applicationServices: + - Payment Authorization + technologyServices: + - Payments:Cluster + groupings: + - Domain:Payments:Refunds + composedOf: + applicationComponents: + - Payments:API + - CardVault:API + - Payments:ClusterOperator +--- +apiVersion: architecture/v1alpha1 +kind: Grouping +metadata: + name: Domain:Payments:Refunds + annotations: + architecture/description: Giving money back to customers, from the service to the worker that does it. +spec: + aggregates: + applicationServices: + - Refunds + composedOf: + applicationComponents: + - Refunds:Worker + technologyArtifacts: + - Repo:refunds-worker diff --git a/lib/archsight/resources.rb b/lib/archsight/resources.rb index 2e21106..0426835 100644 --- a/lib/archsight/resources.rb +++ b/lib/archsight/resources.rb @@ -43,6 +43,31 @@ module Resources # The derived relations of every class, next to the ones it declares: [verb, key, kind] DERIVED_RELATIONS = DERIVED_VERBS.map { |verb| [verb, DERIVED_KEY, "Resource"] }.freeze + # Relation keys that do not follow the rule of #relation_key (lowerCamel kind name, made plural): the keys the + # model has used for these kinds from the start + IRREGULAR_RELATION_KEYS = { + "Analysis" => "analyses", + "MotivationGoal" => "goals", + "MotivationOutcome" => "outcomes", + "Page" => "pages", + "PageMenu" => "menus", + "TechnologyEquipment" => "technologyEquipment", + "TechnologySystemSoftware" => "technologySystemSoftware" + }.freeze + + # The key under `spec.` that holds resources of a kind (ApplicationComponent -> applicationComponents), + # for relations that are declared for many kinds at once (see Grouping) + def self.relation_key(kind_name) + name = kind_name.to_s + IRREGULAR_RELATION_KEYS.fetch(name) do + key = name[0].downcase + name[1..] + if key.end_with?("y") && !key.end_with?("ay", "ey", "oy", "uy") then "#{key.chop}ies" + elsif key.end_with?("s", "x", "ch", "sh") then "#{key}es" + else "#{key}s" + end + end + end + # The current name of a kind, whichever of its names is given def self.canonical(klass_name) name = klass_name.to_s @@ -90,3 +115,6 @@ module Archsight::Annotations; end Dir[File.join(__dir__, "annotations", "*.rb")].each { |file| require_relative file } require_relative "resources/base" Dir[File.join(__dir__, "resources", "*.rb")].each { |file| require_relative file } + +# A Grouping holds resources of every kind, so its relations can only be declared once all kinds are known +Archsight::Resources::Grouping.declare_members! diff --git a/lib/archsight/resources/base.rb b/lib/archsight/resources/base.rb index 057b1f9..e5139cf 100644 --- a/lib/archsight/resources/base.rb +++ b/lib/archsight/resources/base.rb @@ -25,6 +25,11 @@ def self.declared_relations @declared_relations || [] end + # The relations the template of the kind (`archsight template`, the example of its docs page) shows + def self.template_relations + declared_relations + end + # Every relation a resource of this kind can have: the declared ones and the derived ones (`mentions`, # `depicts`, see Archsight::References). Everything that follows relations (queries, graphs, impact analysis) # uses this; what lets a user write or choose relations uses declared_relations. diff --git a/lib/archsight/resources/grouping.rb b/lib/archsight/resources/grouping.rb new file mode 100644 index 0000000..ea0597e --- /dev/null +++ b/lib/archsight/resources/grouping.rb @@ -0,0 +1,80 @@ +# frozen_string_literal: true + +# Grouping gathers resources of any kind that belong together by some criterion +class Archsight::Resources::Grouping < Archsight::Resources::Base + include_annotations :git, :architecture + + description <<~MD + Gathers resources of any kind, other groupings included, that belong together by some criterion. + + ## ArchiMate Definition + + **Layer:** Other (ArchiMate: composite element) + **Aspect:** Composite + + The grouping element aggregates or composes concepts that belong together based on some common + characteristic. Unlike a location, the criterion is not a place: a domain, a programme, a product family, + a migration scope, the subject of a review. + + ## Usage + + Use Grouping to represent: + + - Domains and sub-domains (Payments, Identity) + - The scope of a programme, a review or an audit + - A product family that spans business, application and technology resources + + ## Members + + A grouping lists its members in `spec`, one key per kind, under one of two verbs: + + - `aggregates`: the member belongs to the group but also stands on its own; it can be in several groups + - `composedOf`: the member is a part of this whole and of no other + + ```yaml + spec: + aggregates: + applicationComponents: [Payment Gateway] + businessProcesses: [Refund Handling] + groupings: [Card Payments] + composedOf: + dataObjects: [Payment] + ``` + + A grouping can contain groupings, so groups nest; a grouping that contains itself (directly or through + others) is reported by `archsight lint`. Members do not name their groups: a member's page lists the groups + it is in. + + ## Not this kind + + - A place is a `Location` + - The menu of the wiki is a `PageMenu` + - Resources that only share an attribute (a team, a tag, a risk domain) need no grouping: a query or a view + finds them + MD + + icon "square-dashed" + layer "other" + + # The verbs a grouping holds its members with + MEMBER_VERBS = %i[aggregates composedOf].freeze + + # The relations shown in the template of the kind; the declared ones cover every kind + TEMPLATE_KINDS = %w[ApplicationComponent BusinessProcess Grouping].freeze + + class << self + # Declares MEMBER_VERBS towards every kind, this one included. Called once all kinds are loaded (see + # lib/archsight/resources.rb), since a class body only sees the kinds loaded before it. + def declare_members! + @declared_relations = [] + @relations = nil + MEMBER_VERBS.each do |verb| + Archsight::Resources.each { |kind| relation verb, Archsight::Resources.relation_key(kind).to_sym, kind } + end + end + + def template_relations + declared_relations.select { |_, _, kind| TEMPLATE_KINDS.include?(kind) } + end + end +end diff --git a/lib/archsight/summary/lens.rb b/lib/archsight/summary/lens.rb index 7acd06e..60826f7 100644 --- a/lib/archsight/summary/lens.rb +++ b/lib/archsight/summary/lens.rb @@ -40,6 +40,7 @@ class ParseError < StandardError; end in assesses, influences: Assessed and influenced by out evidencedBy: Evidence out ownedBy: Owners + in aggregates, composedOf: Groups in mentions, depicts: Documented in LENS "strategy" => <<~LENS, @@ -47,6 +48,7 @@ class ParseError < StandardError; end out servedBy: Served by in hasConcern: Stakeholders in realizes: Realized by + in aggregates, composedOf: Groups in mentions, depicts: Documented in LENS "implementation" => <<~LENS, @@ -59,6 +61,7 @@ class ParseError < StandardError; end out realizes: Realizes in realizes: Realized by out performedBy, ownedBy: People + in aggregates, composedOf: Groups in mentions, depicts: Documented in LENS "business" => <<~LENS, @@ -88,6 +91,7 @@ class ParseError < StandardError; end out evidencedBy: Evidence in servedBy: Served in exposes: Exposed by + in aggregates, composedOf: Groups in mentions, depicts: Documented in LENS "technology" => <<~LENS, @@ -111,6 +115,12 @@ class ParseError < StandardError; end # Kinds whose layer lens is too coarse; looked up before the lens of the layer KIND_DEFAULTS = { + "Grouping" => <<~LENS, + out aggregates: Members + out composedOf: Composed of + in aggregates, composedOf: Part of + in mentions, depicts: Documented in + LENS "BusinessActor" => <<~LENS, in performedBy, executedBy: Performs in ownedBy: Owns diff --git a/lib/archsight/template.rb b/lib/archsight/template.rb index 483b9bb..779702b 100644 --- a/lib/archsight/template.rb +++ b/lib/archsight/template.rb @@ -35,10 +35,10 @@ def add_annotations(yaml, klass) end def add_relations(yaml, klass) - return if klass.declared_relations.empty? + return if klass.template_relations.empty? yaml["spec"] = {} if yaml["spec"].nil? - klass.declared_relations.each do |verb, relation_kind, _relation_klass| + klass.template_relations.each do |verb, relation_kind, _relation_klass| relation_verb = verb.to_s.delete_prefix(":") yaml["spec"][relation_verb] ||= {} yaml["spec"][relation_verb][relation_kind.to_s] = [] diff --git a/sig/archsight/resources.rbs b/sig/archsight/resources.rbs index 9c61f20..d4ce645 100644 --- a/sig/archsight/resources.rbs +++ b/sig/archsight/resources.rbs @@ -5,6 +5,9 @@ module Archsight DERIVED_VERBS: Array[Symbol] DERIVED_KEY: Symbol DERIVED_RELATIONS: Array[[Symbol, Symbol, String]] + IRREGULAR_RELATION_KEYS: Hash[String, String] + + def self.relation_key: (String | Symbol) -> String def self.register: (untyped) -> void def self.resource_classes: () -> Hash[String, singleton(Base)] @@ -29,6 +32,7 @@ module Archsight MAX_SUMMARY_ANNOTATIONS: Integer def self.declared_relations: () -> Array[[Symbol, Symbol, String]] def self.relations: () -> Array[[Symbol, Symbol, String]] + def self.template_relations: () -> Array[[Symbol, Symbol, String]] def self.annotation: (String, ?description: String?, ?filter: Symbol?, ?title: String?, ?format: Symbol?, ?enum: Array[String]?, ?sidebar: bool, ?type: Class?, ?summary: bool, ?editor: bool, ?validator: (^(String) -> String?)?, ?unique: bool, ?deprecated: String?) -> void def self.annotations: () -> Array[Annotations::Annotation] def self.computed_annotation: (String, ?description: String?, ?filter: Symbol?, ?title: String?, ?format: Symbol?, ?enum: Array[String]?, ?sidebar: bool, ?type: Class?, ?summary: bool) { () -> untyped } -> void diff --git a/test/grouping_test.rb b/test/grouping_test.rb new file mode 100644 index 0000000..93c2787 --- /dev/null +++ b/test/grouping_test.rb @@ -0,0 +1,213 @@ +# frozen_string_literal: true + +require "test_helper" +require "tmpdir" +require "rack/test" +require "archsight/web/application" +require "json" + +# Grouping (ArchiMate composite element): aggregates or composes resources of every kind, groupings included +class GroupingTest < Minitest::Test + include Rack::Test::Methods + + def app + Archsight::Web::Application + end + + RESOURCES = <<~YAML + --- + apiVersion: architecture/v1alpha1 + kind: ApplicationComponent + metadata: + name: Payments:API + spec: {} + --- + apiVersion: architecture/v1alpha1 + kind: BusinessProcess + metadata: + name: Refund Handling + spec: {} + --- + apiVersion: architecture/v1alpha1 + kind: DataObject + metadata: + name: Payment + spec: {} + --- + apiVersion: architecture/v1alpha1 + kind: Grouping + metadata: + name: Domain:Payments + spec: + aggregates: + applicationComponents: + - Payments:API + groupings: + - Domain:Refunds + composedOf: + dataObjects: + - Payment + --- + apiVersion: architecture/v1alpha1 + kind: Grouping + metadata: + name: Domain:Refunds + spec: + aggregates: + businessProcesses: + - Refund Handling + applicationComponents: + - Payments:API + YAML + + def with_db(yaml = RESOURCES) + Dir.mktmpdir do |dir| + File.write(File.join(dir, "test.yaml"), yaml) + db = Archsight::Database.new(dir, verbose: false, compute_annotations: false) + db.reload! + yield db + end + end + + def test_kind_is_a_composite_in_the_other_layer + klass = Archsight::Resources["Grouping"] + + assert_equal "other", klass.layer + assert_equal "square-dashed", klass.icon + end + + def test_declares_both_verbs_towards_every_kind_itself_included + declared = Archsight::Resources::Grouping.declared_relations + + Archsight::Resources::Grouping::MEMBER_VERBS.each do |verb| + targets = declared.select { |v, _, _| v == verb }.map(&:last) + + assert_equal Archsight::Resources.resource_classes.keys.sort, targets.sort, "#{verb} must reach every kind" + end + assert_includes declared, [:aggregates, :groupings, "Grouping"] + end + + def test_declaring_members_again_does_not_duplicate + before = Archsight::Resources::Grouping.declared_relations.dup + Archsight::Resources::Grouping.declare_members! + + assert_equal before, Archsight::Resources::Grouping.declared_relations + end + + # A grouping uses the key the rest of the model already uses for a kind, so members are written the same way + # everywhere (kinds only reached through a shared key such as technologyComponents are skipped) + def test_relation_key_matches_the_keys_already_in_use + used = Hash.new { |h, k| h[k] = [] } + Archsight::Resources.resource_classes.each do |name, klass| + next if name == "Grouping" + + klass.declared_relations.each { |_, key, kind| used[kind.to_s] << key.to_s } + end + + used.each do |kind, keys| + next if keys.uniq == ["technologyComponents"] + + assert_includes keys, Archsight::Resources.relation_key(kind), "key of #{kind}" + end + end + + def test_relation_key_plurals + assert_equal "applicationComponents", Archsight::Resources.relation_key("ApplicationComponent") + assert_equal "businessProcesses", Archsight::Resources.relation_key("BusinessProcess") + assert_equal "strategyCapabilities", Archsight::Resources.relation_key("StrategyCapability") + assert_equal "groupings", Archsight::Resources.relation_key("Grouping") + assert_equal "analyses", Archsight::Resources.relation_key("Analysis") + end + + def test_members_of_every_kind_and_nested_groups_resolve + with_db do |db| + payments = db.instance_by_kind("Grouping", "Domain:Payments") + grouped = payments.relations_grouped + + assert_equal ["Payments:API"], grouped["aggregates"]["ApplicationComponent"].map(&:name) + assert_equal ["Domain:Refunds"], grouped["aggregates"]["Grouping"].map(&:name) + assert_equal ["Payment"], grouped["composedOf"]["DataObject"].map(&:name) + end + end + + def test_a_member_lists_every_group_it_is_in + with_db do |db| + api = db.instance_by_kind("ApplicationComponent", "Payments:API") + groups = api.references_grouped["Grouping"][:aggregates].map(&:name) + + assert_equal %w[Domain:Payments Domain:Refunds], groups.sort + end + end + + def test_query_follows_membership + with_db do |db| + names = db.query("ApplicationComponent: <- Grouping").map(&:name) + + assert_includes names, "Payments:API" + end + end + + def test_example_model_lints_clean + assert_empty(with_db { |db| Archsight::Linter.new(db).validate }) + end + + def test_a_group_containing_itself_is_a_cycle + yaml = <<~YAML + --- + apiVersion: architecture/v1alpha1 + kind: Grouping + metadata: + name: Group:A + spec: + aggregates: + groupings: [Group:B] + --- + apiVersion: architecture/v1alpha1 + kind: Grouping + metadata: + name: Group:B + spec: + aggregates: + groupings: [Group:A] + YAML + errors = with_db(yaml) { |db| Archsight::Linter.new(db).validate } + + assert_match(/Grouping 'Group:\w' is part of a cycle of aggregates relations/, errors.join("\n")) + end + + def test_summary_of_a_member_names_its_groups + with_db do |db| + text = Archsight::Summary::Builder.new(db).call(db.instance_by_kind("ApplicationComponent", "Payments:API")) + + assert_includes text, "Groups" + assert_includes text, "[[Grouping/Domain:Payments]]" + end + end + + def test_summary_of_a_grouping_lists_its_members + with_db do |db| + text = Archsight::Summary::Builder.new(db).call(db.instance_by_kind("Grouping", "Domain:Payments")) + + assert_includes text, "Members" + assert_includes text, "[[ApplicationComponent/Payments:API]]" + assert_includes text, "[[DataObject/Payment]]" + end + end + + def test_template_shows_a_few_member_kinds_only + spec = YAML.safe_load(Archsight::Template.generate("Grouping"))["spec"] + + assert_equal %w[aggregates composedOf], spec.keys + assert_equal %w[applicationComponents businessProcesses groupings], spec["aggregates"].keys + end + + def test_api_shows_the_example_grouping + Archsight.resources_dir = File.expand_path("../examples/archsight", __dir__) + Archsight::Web::Application.database.reload! + get "/api/v1/kinds/Grouping/instances/Domain:Payments" + + assert_predicate last_response, :ok? + assert_includes last_response.body, "Domain:Payments:Refunds" + assert_includes last_response.body, "Payments:API" + end +end