archsight 0.5.2 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +2 -0
  3. data/docs/archimate.md +1 -1
  4. data/docs/diagram.md +12 -2
  5. data/docs/modeling.md +16 -5
  6. data/docs/search.md +19 -0
  7. data/lib/archsight/annotations/capacity_annotations.rb +15 -0
  8. data/lib/archsight/database.rb +1 -1
  9. data/lib/archsight/diagram/graph/attributes.rb +11 -3
  10. data/lib/archsight/diagram/graph/builder.rb +1 -0
  11. data/lib/archsight/diagram/graph/node.rb +26 -2
  12. data/lib/archsight/diagram/layout/expander.rb +39 -0
  13. data/lib/archsight/diagram/layout.rb +11 -0
  14. data/lib/archsight/diagram/legend/inventory.rb +6 -2
  15. data/lib/archsight/diagram/parser.rb +1 -1
  16. data/lib/archsight/diagram/renderer/node_renderer.rb +6 -1
  17. data/lib/archsight/diagram/renderer/stylesheet.rb +2 -0
  18. data/lib/archsight/diagram/style/representers.rb +14 -0
  19. data/lib/archsight/diagram/support/text_metrics.rb +38 -0
  20. data/lib/archsight/import/handlers/repository.rb +25 -0
  21. data/lib/archsight/linter.rb +13 -2
  22. data/lib/archsight/mcp/analyze_resource_tool.rb +145 -43
  23. data/lib/archsight/mcp/base.rb +112 -5
  24. data/lib/archsight/mcp/execute_analysis_tool.rb +11 -1
  25. data/lib/archsight/mcp/query_hints.rb +119 -0
  26. data/lib/archsight/mcp/query_tool.rb +90 -5
  27. data/lib/archsight/mcp/relations_tool.rb +89 -0
  28. data/lib/archsight/mcp/resource_doc_tool.rb +39 -20
  29. data/lib/archsight/mcp/summary_tool.rb +106 -0
  30. data/lib/archsight/mcp.rb +2 -0
  31. data/lib/archsight/query/ast.rb +28 -0
  32. data/lib/archsight/query/evaluator.rb +2 -0
  33. data/lib/archsight/query/lexer.rb +2 -2
  34. data/lib/archsight/query/parser.rb +45 -0
  35. data/lib/archsight/query/text_search.rb +38 -0
  36. data/lib/archsight/query.rb +1 -0
  37. data/lib/archsight/resources/base.rb +12 -0
  38. data/lib/archsight/resources/business_contract.rb +8 -1
  39. data/lib/archsight/resources/config.rb +28 -0
  40. data/lib/archsight/resources/motivation_requirement.rb +10 -0
  41. data/lib/archsight/resources/technology_device.rb +14 -0
  42. data/lib/archsight/resources/technology_equipment.rb +3 -1
  43. data/lib/archsight/resources/technology_node.rb +8 -1
  44. data/lib/archsight/summary/builder.rb +204 -0
  45. data/lib/archsight/summary/lens.rb +224 -0
  46. data/lib/archsight/summary.rb +11 -0
  47. data/lib/archsight/version.rb +1 -1
  48. data/lib/archsight/web/application.rb +2 -0
  49. metadata +9 -1
@@ -34,11 +34,16 @@ class Archsight::Resources::BusinessContract < Archsight::Resources::Base
34
34
  - It is `agreedBy` its parties: the actual organisations (the customer, the provider), not a generic role
35
35
  - It is `composedOf` its parts: call-offs, SLAs and amendments, which are contracts themselves (no cycles)
36
36
  - It `covers` what it obliges the provider to deliver: equipment, nodes, technology and application services
37
+ - It `stipulates` the `MotivationRequirement`s and `MotivationConstraint`s it makes binding: the legal basis of
38
+ an obligation. Link them instead of restating sizes, availability or response times in the description. A
39
+ requirement the provider derives itself (a design that refines a contractual obligation) is not stipulated by
40
+ a contract, it is `refinedBy`-linked from the stipulated requirement it refines. A requirement can be stipulated by several
41
+ contracts (a framework and a call-off)
37
42
  - It is `realizedThrough` the `ImplementationDeliverable` that fulfils it; the `ImplementationWorkPackage` that
38
43
  `realizes` the deliverable `affects` the equipment it installs
39
44
 
40
45
  The other side shows these as incoming relations: the contracts an actor agreed, what covers a piece of
41
- equipment or a service, the contract a deliverable fulfils.
46
+ equipment or a service, the contract a deliverable fulfils, and on a requirement the contracts that stipulate it.
42
47
  MD
43
48
 
44
49
  icon "journal-page"
@@ -68,5 +73,7 @@ class Archsight::Resources::BusinessContract < Archsight::Resources::Base
68
73
  relation :covers, :technologyNodes, :TechnologyNode
69
74
  relation :covers, :technologyServices, :TechnologyService
70
75
  relation :covers, :applicationServices, :ApplicationService
76
+ relation :stipulates, :motivationRequirements, :MotivationRequirement
77
+ relation :stipulates, :motivationConstraints, :MotivationConstraint
71
78
  relation :realizedThrough, :implementationDeliverables, :ImplementationDeliverable
72
79
  end
@@ -1,5 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require_relative "../summary/lens"
4
+
3
5
  # Config holds settings of a feature of the tool, kept with the model so they are shared and versioned like it
4
6
  class Archsight::Resources::Config < Archsight::Resources::Base
5
7
  include_annotations :architecture
@@ -22,10 +24,29 @@ class Archsight::Resources::Config < Archsight::Resources::Base
22
24
  | `config/type` | Settings | Used by |
23
25
  |---------------|----------|---------|
24
26
  | `pdf` | `pdf/*`: colours, fonts, logo, header and footer | [PDF export](/doc/pdf-export) |
27
+ | `summary` | `summary/lens-<layer>`: what the MCP `summary` tool follows per layer | MCP `summary` tool |
25
28
 
26
29
  A document picks a different Config of the type with the tag `pdf:template:<name>`; without a tag the one named
27
30
  `default` is used, and without any the export has a neutral built-in look.
28
31
 
32
+ ## Summary lenses
33
+
34
+ The MCP `summary` tool explains a resource through a lens chosen by its kind or layer. A Config of type `summary`
35
+ (the one named `default`) replaces the built-in lens of a layer with `summary/lens-<layer>` (`motivation`, `strategy`,
36
+ `implementation`, `business`, `application`, `technology`, `other`) and the one of a single kind with
37
+ `summary/lens-<Kind>` (for example `summary/lens-BusinessActor`); the kind wins over the layer. The built-in lenses
38
+ end with `in mentions, depicts: Documented in` (the pages that describe the resource); a lens of your own has to
39
+ list it to keep that section. One section per line,
40
+ `<out|in> <verb>[, <verb>...] [depth=N][: <title>]`; `out` = the resource declares the relation, `in` = the other
41
+ resource points at it, `*` = every verb:
42
+
43
+ ```yaml
44
+ summary/lens-application: |
45
+ out exposes: Interfaces
46
+ in dependsOn: Used by
47
+ out servedBy depth=2: Runs on
48
+ ```
49
+
29
50
  ## PDF settings
30
51
 
31
52
  - **Colours** (`pdf/color-*`) are hex values (`#0b3d91`). `primary` is used for headings, the cover band and
@@ -139,6 +160,13 @@ class Archsight::Resources::Config < Archsight::Resources::Base
139
160
  sidebar: false,
140
161
  validator: ->(value) { Archsight::Resources::Config.keep_space_error(value) }
141
162
 
163
+ annotation "summary/lens-*",
164
+ description: "Lens of a layer (summary/lens-application) or of one kind (summary/lens-BusinessActor) for the " \
165
+ "MCP summary tool: one section per line, `<out|in> <verb>[, <verb>] [depth=N][: <title>]`",
166
+ title: "Summary lens",
167
+ sidebar: false,
168
+ validator: ->(value) { Archsight::Summary::Lens.parse_error(value) }
169
+
142
170
  HEADER_PARTS = %w[id version date owner].freeze
143
171
  HEADING_LEVELS = (1..6).to_a.freeze
144
172
  KEEP_SPACE = /\A([1-6]):(\d{1,3})%?\z/
@@ -42,6 +42,15 @@ class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
42
42
  the requirement answers. The stakeholder is `representedBy` the actor or role behind it, so the chain reaches the
43
43
  actual organisation that asked for the requirement.
44
44
 
45
+ ## Refinement
46
+
47
+ A requirement is either taken as it is or made more concrete: the catalogue requirement (an IT-Grundschutz
48
+ building block requirement, a C5 criterion) is `refinedBy` the requirements derived from it, one or several, in
49
+ any depth. The relation is written on the more abstract requirement and points down, like `composedOf`; the
50
+ derived requirement shows the catalogue requirement as incoming "refines". Everything that realizes, plans or
51
+ satisfies the derived requirement thereby answers to the catalogue requirement as well. A catalogue requirement
52
+ taken as it is needs no relation: link it directly. The chain must not form a cycle (`archsight lint`).
53
+
45
54
  ## Security and risk modelling
46
55
 
47
56
  - **Control measure:** `requirement/type` `control-measure` is a measure that a control objective
@@ -78,6 +87,7 @@ class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
78
87
  title: "Story",
79
88
  format: :markdown
80
89
 
90
+ relation :refinedBy, :motivationRequirements, :MotivationRequirement
81
91
  relation :realizes, :outcomes, :MotivationOutcome
82
92
  relation :realizes, :motivationPrinciples, :MotivationPrinciple
83
93
  end
@@ -47,6 +47,13 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
47
47
  - Who uses it is the team or role (`servedBy`), not a person; a client device needs no room, `locatedAt` an
48
48
  office is optional
49
49
 
50
+ ## CPU generation
51
+
52
+ `device/arch` is the instruction set; `device/cpu` is the microarchitecture or generation ("Ice Lake",
53
+ "Zen 5") and `device/cpuModel` the exact model number. Hosts of one generation share the CPU features a VM can
54
+ be given and the live-migration domain, so `device/cpu == "Ice Lake"` lists them. The vendor product of the
55
+ machine stays in `device/model`.
56
+
50
57
  ## Not this kind
51
58
 
52
59
  - A VM, a Kubernetes node or a host role is a `TechnologyNode`
@@ -115,6 +122,13 @@ class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
115
122
  title: "Architecture",
116
123
  enum: %w[x86_64 arm64 riscv64 other],
117
124
  filter: :word
125
+ annotation "device/cpu",
126
+ description: "CPU microarchitecture or generation, e.g. Ice Lake, Sierra Forest, Zen 5",
127
+ title: "CPU",
128
+ filter: :word
129
+ annotation "device/cpuModel",
130
+ description: "Exact CPU model number, e.g. Xeon Gold 6338",
131
+ title: "CPU Model"
118
132
  annotation "device/ownership",
119
133
  description: "Who owns the device",
120
134
  title: "Ownership",
@@ -2,7 +2,7 @@
2
2
 
3
3
  # TechnologyEquipment represents racks, fabrics and physical clusters inside a facility
4
4
  class Archsight::Resources::TechnologyEquipment < Archsight::Resources::Base
5
- include_annotations :git, :architecture
5
+ include_annotations :git, :architecture, :capacity
6
6
 
7
7
  description <<~MD
8
8
  Represents physical equipment inside a facility: racks, network fabrics, physical clusters.
@@ -49,6 +49,8 @@ class Archsight::Resources::TechnologyEquipment < Archsight::Resources::Base
49
49
  The devices of a partition are normally served by the same team; `archsight lint` warns when one is not
50
50
  - A `BusinessContract` `covers` the equipment it obliges the provider to deliver, and the `ImplementationWorkPackage` that
51
51
  installs or changes it `affects` it
52
+ - `capacity/spareHosts` is the number of hosts of a site or delivered block held in reserve (n+1); it is a count,
53
+ not a machine, so it is not a flag on a `TechnologyDevice`. The source goes into a `link/*` annotation
52
54
  MD
53
55
 
54
56
  icon "cpu"
@@ -2,7 +2,7 @@
2
2
 
3
3
  # TechnologyNode represents physical infrastructure (VMs, servers, Kubernetes nodes)
4
4
  class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
5
- include_annotations :git, :architecture, :asset, :risk
5
+ include_annotations :git, :architecture, :asset, :risk, :capacity
6
6
 
7
7
  description <<~MD
8
8
  Represents physical infrastructure hosting application components.
@@ -54,6 +54,13 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
54
54
  A logical node (a host role, "the hypervisors of the platform") is `realizedBy` the `TechnologyDevice`s, the
55
55
  physical machines, that make it up.
56
56
 
57
+ ## Spare hosts
58
+
59
+ A host role or pool keeps hosts in reserve (n+1). The reserve is a count, not a machine: any host can take the
60
+ role and the actual spare changes, so `capacity/spareHosts` holds the number on the node (not a flag on a
61
+ `TechnologyDevice`) and a `link/*` annotation the source. "N hosts, of which K spare" is the devices the node is
62
+ `realizedBy` and this count.
63
+
57
64
  ## Concept and implementation
58
65
 
59
66
  A node can `specialize` another node (ArchiMate specialization): the general node is the concept (a regional
@@ -0,0 +1,204 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+
5
+ module Archsight
6
+ module Summary
7
+ # The direct relations of a resource, both ways, as Related(verb, direction, resource); "out" = the resource
8
+ # declares the relation, "in" = the other resource points at it
9
+ Related = Struct.new(:verb, :direction, :resource)
10
+
11
+ module Relations
12
+ module_function
13
+
14
+ def direct(instance)
15
+ outgoing = instance.relations_grouped.flat_map do |verb, kinds|
16
+ kinds.values.flatten.map { |target| Related.new(verb.to_s, "out", target) }
17
+ end
18
+ incoming = instance.references.map { |ref| Related.new(ref[:verb].to_s, "in", ref[:instance]) }
19
+ (outgoing + incoming).uniq { |rel| [rel.verb, rel.direction, rel.resource.object_id] }
20
+ end
21
+ end
22
+
23
+ # Builds the summary of one resource as markdown: what it is, the sections of its lens (each relation group with
24
+ # a count and the first few resources as `[[Kind/Name]]` links, and the exact call that lists the rest) and a
25
+ # pointer to the other layers that have related resources. Empty sections are not shown. The result is bounded: the
26
+ # lists shrink and sections drop until it fits `max_chars`. Only the model is read, so it is reproducible.
27
+ class Builder
28
+ NOISE_KINDS = %w[Page PageMenu].freeze # followed only by an explicit verb, never through `*`
29
+ DESCRIPTION_CHARS = 400
30
+ FACTS = 6
31
+
32
+ Group = Struct.new(:label, :resources, :call)
33
+ Block = Struct.new(:title, :groups)
34
+
35
+ def initialize(database, per_section: 5, max_chars: 6000)
36
+ @db = database
37
+ @per_section = [[per_section.to_i, 1].max, 20].min
38
+ @max_chars = max_chars
39
+ end
40
+
41
+ # @param lens_layer [String, nil] the layer whose lens to use instead of the one of the resource's kind
42
+ # @param source [Hash, nil] where the resource is defined: {source: "path:line", generated: bool}
43
+ # @return [String] markdown
44
+ def call(instance, lens_layer: nil, source: nil)
45
+ @source = source
46
+ lens = lens_layer || instance.class.layer
47
+ sections = Lens.for(@db, lens, kind: lens_layer ? nil : instance.klass)
48
+ blocks = sections.filter_map { |section| block_for(instance, section) }
49
+ render_bounded(instance, lens, blocks)
50
+ end
51
+
52
+ private
53
+
54
+ def render_bounded(instance, lens, blocks)
55
+ limits = [@per_section, 3, 2, 1].uniq.select { |n| n <= @per_section }
56
+ text = nil
57
+ limits.each do |per|
58
+ text = render(instance, lens, blocks, per)
59
+ return text if text.length <= @max_chars
60
+ end
61
+ blocks = blocks.dup
62
+ while blocks.length > 1 && text.length > @max_chars
63
+ blocks.pop
64
+ text = render(instance, lens, blocks, limits.last, omitted: true)
65
+ end
66
+ text
67
+ end
68
+
69
+ def render(instance, lens, blocks, per, omitted: false)
70
+ lines = header(instance, lens)
71
+ blocks.each do |block|
72
+ lines << "" << "## #{block.title}"
73
+ block.groups.each { |group| lines << group_line(group, per) }
74
+ end
75
+ lines.concat(other_layers(instance, lens))
76
+ lines << "" << "_More sections were left out to keep this short; use the `relations` tool for the rest._" if omitted
77
+ lines.join("\n")
78
+ end
79
+
80
+ def header(instance, lens)
81
+ kind = instance.klass
82
+ layer = instance.class.layer
83
+ meta = ["**#{kind}**", "#{layer} layer"]
84
+ meta << "viewed through the #{lens} lens" if lens != layer
85
+ lines = ["# #{link(instance)}", meta.join(" · ")]
86
+ lines << source_line if @source&.dig(:source)
87
+ description = description_of(instance)
88
+ lines << "" << description if description
89
+ facts = facts_of(instance)
90
+ lines << "" << facts.join(" · ") unless facts.empty?
91
+ lines
92
+ end
93
+
94
+ def source_line
95
+ note = @source[:generated] ? " (generated: change the importer or generator, not this file)" : ""
96
+ "Defined in `#{@source[:source]}`#{note}"
97
+ end
98
+
99
+ # The opening of the description: its first paragraph up to a list, heading or code block, which stay in the
100
+ # resource itself
101
+ def description_of(instance)
102
+ paragraph = instance.annotations["architecture/description"].to_s.strip.split(/\n\s*\n/).first.to_s
103
+ lines = paragraph.lines.take_while { |line| !line.match?(/\A\s*([-*+]\s|\d+[.)]\s|\#|```)/) }
104
+ text = lines.map(&:strip).join(" ").sub(/:\z/, "").strip
105
+ return nil if text.empty?
106
+
107
+ text.length > DESCRIPTION_CHARS ? "#{text[0, DESCRIPTION_CHARS - 1].rstrip}…" : text
108
+ end
109
+
110
+ # The summary attributes of the kind that have a value, as "Title: value"
111
+ def facts_of(instance)
112
+ instance.class.summary_annotations.filter_map do |annotation|
113
+ value = Array(annotation.value_for(instance)).map(&:to_s).reject(&:empty?)
114
+ next if value.empty?
115
+
116
+ text = value.join(", ")
117
+ "#{annotation.title}: #{text.length > 80 ? "#{text[0, 79]}…" : text}"
118
+ end.first(FACTS)
119
+ end
120
+
121
+ def block_for(instance, section)
122
+ groups = section.depth > 1 ? deep_groups(instance, section) : direct_groups(instance, section)
123
+ groups.empty? ? nil : Block.new(section.title, groups)
124
+ end
125
+
126
+ def direct_groups(instance, section)
127
+ matching(Relations.direct(instance), section).group_by(&:verb).sort.map do |verb, rels|
128
+ entries = ordered(rels.map(&:resource))
129
+ call = "relations(kind: #{instance.klass.to_json}, name: #{instance.name.to_json}, verb: #{verb.to_json}, direction: #{section.direction.to_json})"
130
+ Group.new(verb, entries, call)
131
+ end
132
+ end
133
+
134
+ # Resources reached in up to `depth` steps along the section's verbs, grouped by step, nearest first
135
+ def deep_groups(instance, section)
136
+ seen = {}.compare_by_identity
137
+ seen[instance] = true
138
+ frontier = [instance]
139
+ (1..section.depth).filter_map do |step|
140
+ reached = []
141
+ frontier.each do |resource|
142
+ matching(Relations.direct(resource), section).each do |rel|
143
+ next if seen[rel.resource]
144
+
145
+ seen[rel.resource] = true
146
+ reached << rel.resource
147
+ end
148
+ end
149
+ frontier = reached
150
+ next if reached.empty?
151
+
152
+ Group.new("#{section.verbs.join("/")} (step #{step})", ordered(reached), deep_call(instance, section))
153
+ end
154
+ end
155
+
156
+ def deep_call(instance, section)
157
+ verbs = section.all_verbs? ? "" : ", verbs: #{section.verbs.to_json}"
158
+ "analyze_resource(kind: #{instance.klass.to_json}, name: #{instance.name.to_json}, impact: true, direction: #{section.direction.to_json}#{verbs}, depth: #{section.depth})"
159
+ end
160
+
161
+ def matching(relations, section)
162
+ relations.select do |rel|
163
+ next false unless rel.direction == section.direction
164
+ next false if section.all_verbs? && NOISE_KINDS.include?(rel.resource.klass)
165
+
166
+ section.all_verbs? || section.verbs.include?(rel.verb)
167
+ end
168
+ end
169
+
170
+ # Resources with a description first (they explain themselves), then by name: reproducible
171
+ def ordered(resources)
172
+ resources.uniq(&:object_id).sort_by { |r| [r.annotations["architecture/description"].to_s.strip.empty? ? 1 : 0, r.name] }
173
+ end
174
+
175
+ def group_line(group, per)
176
+ shown = group.resources.first(per)
177
+ total = group.resources.length
178
+ label = total > 1 ? "#{group.label} (#{total})" : group.label
179
+ line = "- #{label}: #{shown.map { |r| link(r) }.join(", ")}"
180
+ rest = total - shown.length
181
+ rest.positive? ? "#{line}, +#{rest} more: `#{group.call}`" : line
182
+ end
183
+
184
+ # Layers other than the one the lens shows that have directly related resources
185
+ def other_layers(instance, lens)
186
+ by_layer = Relations.direct(instance).map(&:resource).uniq(&:object_id).group_by { |r| r.class.layer }
187
+ by_layer = by_layer.reject { |layer, _| layer == lens || layer == "other" }
188
+ return [] if by_layer.empty?
189
+
190
+ lines = ["", "## Related in other layers"]
191
+ Lens::DEFAULTS.each_key do |layer|
192
+ resources = by_layer[layer] or next
193
+ kinds = resources.group_by(&:klass).sort.map { |kind, list| "#{kind} #{list.length}" }.join(", ")
194
+ lines << "- #{layer} (#{resources.length}): #{kinds}; `summary(kind: #{instance.klass.to_json}, name: #{instance.name.to_json}, lens: #{layer.to_json})`"
195
+ end
196
+ lines
197
+ end
198
+
199
+ def link(resource)
200
+ "[[#{resource.klass}/#{resource.name}]]"
201
+ end
202
+ end
203
+ end
204
+ end
@@ -0,0 +1,224 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Archsight
4
+ module Summary
5
+ # What a summary follows from a resource, depending on its layer: an ordered list of sections, each one a set of
6
+ # relation verbs in one direction (and how many steps deep).
7
+ #
8
+ # One section per line, `<out|in> <verb>[, <verb>...] [depth=N][: <title>]`:
9
+ #
10
+ # in servedBy, realizedBy: Used by
11
+ # out dependsOn depth=2: Depends on
12
+ # in *: Referenced by
13
+ #
14
+ # `out` = the resource points at the target (it declares the relation), `in` = the target points at it; `*` = every
15
+ # verb. The built-in lenses below apply when the model has no Config of type `summary`; its annotation
16
+ # `summary/lens-<layer>` replaces the lens of that layer and `summary/lens-<Kind>` the one of a single kind (the
17
+ # kind wins), so lenses are tuned without a release.
18
+ module Lens
19
+ TYPE = "summary" # the `config/type` of the Config that holds the lenses
20
+ DEFAULT_CONFIG = "default"
21
+ MAX_DEPTH = 5
22
+
23
+ Section = Struct.new(:title, :direction, :verbs, :depth) do
24
+ def all_verbs?
25
+ verbs == ["*"]
26
+ end
27
+ end
28
+
29
+ class ParseError < StandardError; end
30
+
31
+ DEFAULTS = {
32
+ "motivation" => <<~LENS,
33
+ in hasConcern: Stakeholders
34
+ out representedBy: Represented by
35
+ in refinedBy: Refines
36
+ out refinedBy: Refined by
37
+ in realizes, partiallyRealizes, plans: Realized by
38
+ in satisfies, stipulates: Satisfied by
39
+ out mitigatedBy: Mitigated by
40
+ in assesses, influences: Assessed and influenced by
41
+ out evidencedBy: Evidence
42
+ out ownedBy: Owners
43
+ in mentions, depicts: Documented in
44
+ LENS
45
+ "strategy" => <<~LENS,
46
+ out realizes: Realizes
47
+ out servedBy: Served by
48
+ in hasConcern: Stakeholders
49
+ in realizes: Realized by
50
+ in mentions, depicts: Documented in
51
+ LENS
52
+ "implementation" => <<~LENS,
53
+ out contains: Contains
54
+ in contains: Part of
55
+ out compares: Compares
56
+ out closedBy: Closed by
57
+ in closedBy: Closes
58
+ out affects: Affects
59
+ out realizes: Realizes
60
+ in realizes: Realized by
61
+ out performedBy, ownedBy: People
62
+ in mentions, depicts: Documented in
63
+ LENS
64
+ "business" => <<~LENS,
65
+ out performedBy, ownedBy, executedBy, agreedBy: People
66
+ out guidedBy: Controls
67
+ out servedBy: Supported by
68
+ out exposes: Exposes
69
+ out aggregates, composedOf: Composed of
70
+ in aggregates, composedOf, compositeOf: Part of
71
+ out realizes, satisfies, stipulates: Requirements
72
+ out covers: Covers
73
+ out evidencedBy, provides: Evidence
74
+ in performedBy, ownedBy, executedBy: Responsible for
75
+ in maintainedBy, operatedBy, contributedBy: Maintains and operates
76
+ in mentions, depicts: Documented in
77
+ LENS
78
+ "application" => <<~LENS,
79
+ out exposes: Interfaces
80
+ out realizedThrough, realizedBy: Realized through
81
+ in realizedThrough, realizedBy: Realizes
82
+ out servedBy, provisions: Runs on
83
+ out dependsOn: Depends on
84
+ in dependsOn: Used by
85
+ in serves: Serves
86
+ out maintainedBy, operatedBy: Owners
87
+ out realizes, partiallyRealizes, plans: Requirements
88
+ out evidencedBy: Evidence
89
+ in servedBy: Served
90
+ in exposes: Exposed by
91
+ in mentions, depicts: Documented in
92
+ LENS
93
+ "technology" => <<~LENS,
94
+ out servedBy, realizedBy, suppliedBy, realizedThrough: Built on
95
+ in servedBy, realizedBy, suppliedBy, assignedTo: Runs on it
96
+ out composedOf, aggregates: Composed of
97
+ in composedOf, aggregates: Part of
98
+ out locatedAt: Located at
99
+ out connectedTo, connects: Connected to
100
+ out maintainedBy, operatedBy, ownedBy, contributedBy: Owners
101
+ out realizes, partiallyRealizes, plans: Requirements
102
+ out evidencedBy: Evidence
103
+ in mentions, depicts: Documented in
104
+ LENS
105
+ "other" => <<~LENS
106
+ out *: Points at
107
+ in *: Referenced by
108
+ in mentions, depicts: Documented in
109
+ LENS
110
+ }.freeze
111
+
112
+ # Kinds whose layer lens is too coarse; looked up before the lens of the layer
113
+ KIND_DEFAULTS = {
114
+ "BusinessActor" => <<~LENS,
115
+ in performedBy, executedBy: Performs
116
+ in ownedBy: Owns
117
+ in maintainedBy, operatedBy, contributedBy: Maintains and operates
118
+ out compositeOf: Composed of
119
+ in compositeOf: Part of
120
+ in representedBy: Represented as stakeholder
121
+ in agreedBy: Contracts
122
+ in servedBy: Serves
123
+ in mentions, depicts: Documented in
124
+ LENS
125
+ "ApplicationService" => <<~LENS,
126
+ out realizedThrough: Realized through
127
+ out dependsOn: Depends on
128
+ in dependsOn: Used by
129
+ in servedBy: Serves
130
+ out maintainedBy: Owners
131
+ out realizes, partiallyRealizes, plans: Requirements
132
+ out evidencedBy: Evidence
133
+ in mentions, depicts: Documented in
134
+ LENS
135
+ "MotivationAssessment" => <<~LENS
136
+ out assesses: Assesses
137
+ out influences: Influences
138
+ out mitigatedBy: Mitigated by
139
+ out ownedBy: Owners
140
+ in mentions, depicts: Documented in
141
+ LENS
142
+ }.freeze
143
+
144
+ class << self
145
+ # The sections for a resource of `kind` in `layer`, from the first of: the `summary/lens-<Kind>` and then the
146
+ # `summary/lens-<layer>` of the Config named `default` of type summary (or the first of that type), the built-in
147
+ # lens of the kind, the built-in lens of the layer
148
+ def for(database, layer, kind: nil)
149
+ candidates = [configured(database, kind), configured(database, layer), KIND_DEFAULTS[kind], DEFAULTS[layer]]
150
+ candidates.compact.each do |text|
151
+ return parse(text)
152
+ rescue ParseError
153
+ next # a bad Config (the linter reports it) must not break the summary: the next candidate is used
154
+ end
155
+ parse(DEFAULTS["other"])
156
+ end
157
+
158
+ # nil when `suffix` of a `summary/lens-<suffix>` key is a layer or a kind, else the message
159
+ def key_error(suffix)
160
+ return nil if Archsight::Resources::LAYERS.include?(suffix) || Archsight::Resources[suffix]
161
+
162
+ "expected a layer (#{Archsight::Resources::LAYERS.join(", ")}) or a kind, not #{suffix}"
163
+ end
164
+
165
+ # Sections of lens text; raises ParseError naming the line
166
+ def parse(text)
167
+ text.to_s.lines.map.with_index(1) { |line, number| [line.strip, number] }.reject { |line, _| line.empty? || line.start_with?("#") }.map do |line, number|
168
+ parse_line(line)
169
+ rescue ParseError => e
170
+ raise ParseError, "line #{number} (#{line}): #{e.message}"
171
+ end
172
+ end
173
+
174
+ # nil when the text is a valid lens, else the message (the validator of the Config annotation)
175
+ def parse_error(text)
176
+ sections = parse(text)
177
+ sections.empty? ? "expected at least one line like `in servedBy: Used by`" : nil
178
+ rescue ParseError => e
179
+ e.message
180
+ end
181
+
182
+ def known_verbs
183
+ @known_verbs ||= Archsight::Resources.constants.filter_map do |name|
184
+ klass = Archsight::Resources.const_get(name)
185
+ klass.relations.map { |verb, _, _| verb.to_s } if klass.is_a?(Class) && klass < Archsight::Resources::Base
186
+ end.flatten.uniq.sort
187
+ end
188
+
189
+ private
190
+
191
+ def configured(database, key)
192
+ return nil unless key
193
+
194
+ configs = database.instances_by_kind("Config").values.select { |c| c.annotations["config/type"].to_s.casecmp?(TYPE) }
195
+ config = configs.find { |c| c.name == DEFAULT_CONFIG } || configs.first
196
+ text = config&.annotations&.[]("summary/lens-#{key}").to_s
197
+ text.strip.empty? ? nil : text
198
+ end
199
+
200
+ def parse_line(line)
201
+ spec, title = line.split(":", 2).map(&:strip)
202
+ direction, rest = spec.split(/\s+/, 2)
203
+ raise ParseError, "expected `out` or `in` first" unless %w[out in].include?(direction)
204
+
205
+ depth = 1
206
+ words = rest.to_s.split(/[,\s]+/).reject(&:empty?).reject do |word|
207
+ next false unless (m = word.match(/\Adepth=(\d+)\z/))
208
+
209
+ depth = m[1].to_i
210
+ true
211
+ end
212
+ raise ParseError, "expected at least one verb" if words.empty?
213
+ raise ParseError, "depth must be 1 to #{MAX_DEPTH}" unless depth.between?(1, MAX_DEPTH)
214
+
215
+ verbs = words.include?("*") ? ["*"] : words
216
+ unknown = verbs - ["*"] - known_verbs
217
+ raise ParseError, "unknown verb #{unknown.join(", ")}" unless unknown.empty?
218
+
219
+ Section.new(title.to_s.empty? ? "#{direction} #{verbs.join(", ")}" : title, direction, verbs, depth)
220
+ end
221
+ end
222
+ end
223
+ end
224
+ end
@@ -0,0 +1,11 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "summary/lens"
4
+ require_relative "summary/builder"
5
+
6
+ module Archsight
7
+ # A short, structured explanation of a resource in context: what it is and how it fits in, assembled from the model
8
+ # only. See Archsight::Summary::Lens for what is followed per layer and Archsight::MCP::SummaryTool for the entry point.
9
+ module Summary
10
+ end
11
+ end
@@ -4,5 +4,5 @@
4
4
  # Do not edit manually.
5
5
 
6
6
  module Archsight
7
- VERSION = "0.5.2"
7
+ VERSION = "0.5.3"
8
8
  end
@@ -92,6 +92,8 @@ class Archsight::Web::Application < Sinatra::Base
92
92
 
93
93
  mcp_server.register_tool(Archsight::MCP::QueryTool)
94
94
  mcp_server.register_tool(Archsight::MCP::AnalyzeResourceTool)
95
+ mcp_server.register_tool(Archsight::MCP::SummaryTool)
96
+ mcp_server.register_tool(Archsight::MCP::RelationsTool)
95
97
  mcp_server.register_tool(Archsight::MCP::ResourceDocTool)
96
98
  mcp_server.register_tool(Archsight::MCP::ExecuteAnalysisTool)
97
99