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.
- checksums.yaml +4 -4
- data/README.md +2 -0
- data/docs/archimate.md +1 -1
- data/docs/diagram.md +12 -2
- data/docs/modeling.md +16 -5
- data/docs/search.md +19 -0
- data/lib/archsight/annotations/capacity_annotations.rb +15 -0
- data/lib/archsight/database.rb +1 -1
- data/lib/archsight/diagram/graph/attributes.rb +11 -3
- data/lib/archsight/diagram/graph/builder.rb +1 -0
- data/lib/archsight/diagram/graph/node.rb +26 -2
- data/lib/archsight/diagram/layout/expander.rb +39 -0
- data/lib/archsight/diagram/layout.rb +11 -0
- data/lib/archsight/diagram/legend/inventory.rb +6 -2
- data/lib/archsight/diagram/parser.rb +1 -1
- data/lib/archsight/diagram/renderer/node_renderer.rb +6 -1
- data/lib/archsight/diagram/renderer/stylesheet.rb +2 -0
- data/lib/archsight/diagram/style/representers.rb +14 -0
- data/lib/archsight/diagram/support/text_metrics.rb +38 -0
- data/lib/archsight/import/handlers/repository.rb +25 -0
- data/lib/archsight/linter.rb +13 -2
- data/lib/archsight/mcp/analyze_resource_tool.rb +145 -43
- data/lib/archsight/mcp/base.rb +112 -5
- data/lib/archsight/mcp/execute_analysis_tool.rb +11 -1
- data/lib/archsight/mcp/query_hints.rb +119 -0
- data/lib/archsight/mcp/query_tool.rb +90 -5
- data/lib/archsight/mcp/relations_tool.rb +89 -0
- data/lib/archsight/mcp/resource_doc_tool.rb +39 -20
- data/lib/archsight/mcp/summary_tool.rb +106 -0
- data/lib/archsight/mcp.rb +2 -0
- data/lib/archsight/query/ast.rb +28 -0
- data/lib/archsight/query/evaluator.rb +2 -0
- data/lib/archsight/query/lexer.rb +2 -2
- data/lib/archsight/query/parser.rb +45 -0
- data/lib/archsight/query/text_search.rb +38 -0
- data/lib/archsight/query.rb +1 -0
- data/lib/archsight/resources/base.rb +12 -0
- data/lib/archsight/resources/business_contract.rb +8 -1
- data/lib/archsight/resources/config.rb +28 -0
- data/lib/archsight/resources/motivation_requirement.rb +10 -0
- data/lib/archsight/resources/technology_device.rb +14 -0
- data/lib/archsight/resources/technology_equipment.rb +3 -1
- data/lib/archsight/resources/technology_node.rb +8 -1
- data/lib/archsight/summary/builder.rb +204 -0
- data/lib/archsight/summary/lens.rb +224 -0
- data/lib/archsight/summary.rb +11 -0
- data/lib/archsight/version.rb +1 -1
- data/lib/archsight/web/application.rb +2 -0
- 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
|
data/lib/archsight/version.rb
CHANGED
|
@@ -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
|
|