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
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require_relative "base"
|
|
4
|
+
require_relative "query_hints"
|
|
4
5
|
|
|
5
6
|
class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
6
7
|
tool_name "query"
|
|
@@ -17,6 +18,11 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
17
18
|
• Annotation filters: 'activity/status == "active"', 'scc/language/Go/loc > 5000'
|
|
18
19
|
Operators: == (equals), != (not equals), =~ (regex match), >, <, >=, <=
|
|
19
20
|
|
|
21
|
+
• Free-text search over the string annotations (descriptions, links, titles, ...):
|
|
22
|
+
text =~ "failover" (also text: "failover"; case-insensitive regex, like name =~)
|
|
23
|
+
text(architecture/description) =~ "x", text(link/*, page/content) =~ "x" restrict the keys (* = any run)
|
|
24
|
+
Each hit shows matched_text: the annotation key and a snippet around the match.
|
|
25
|
+
|
|
20
26
|
• Relation queries:
|
|
21
27
|
-> Kind (has outgoing relation to kind), -> "Name" (to specific instance)
|
|
22
28
|
<- Kind (has incoming relation from kind), <- "Name" (from specific instance)
|
|
@@ -38,6 +44,24 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
38
44
|
'-> none & <- none' - true orphans with no relations at all
|
|
39
45
|
'~> $(web-checkout)' - transitively reaches instance matching "web-checkout"
|
|
40
46
|
'<- $(TechnologyArtifact: activity/status == "active")' - referenced by active artifacts
|
|
47
|
+
'ApplicationComponent: <- none & -> none' - components nothing refers to and that refer to nothing (orphans of one kind)
|
|
48
|
+
'ApplicationComponent: ~> $(name == "web-checkout")' - components that transitively reach web-checkout
|
|
49
|
+
'ApplicationService: -{realizedThrough}> ApplicationComponent' - only along one relation verb (<{verb}- for incoming)
|
|
50
|
+
'ApplicationService: text =~ "failover" & -> ApplicationComponent' - services whose text mentions failover and that have components
|
|
51
|
+
'text(link/*) =~ "PROJ-1234"' - every resource that links ticket PROJ-1234
|
|
52
|
+
For the impact of changing a resource use analyze_resource(impact=true) with kinds/exclude_kinds/depth/limit.
|
|
53
|
+
|
|
54
|
+
TYPICAL FLOW: find the exact name with a name search (output='brief' shows kind, name and source file),
|
|
55
|
+
then call analyze_resource or relations with that kind and name. Use output='count' first to see how big
|
|
56
|
+
a result is, 'brief' to list it, and 'complete' (with fields=[...] and a small limit) only for details.
|
|
57
|
+
|
|
58
|
+
PITFALLS:
|
|
59
|
+
• A filter on an annotation key that does not exist matches nothing; the result then carries a warning
|
|
60
|
+
'unknown annotation key ...' listing the known keys. Keys are exact and case-sensitive.
|
|
61
|
+
• Annotation values are strings: compare with == "x", numbers with > < >=, regex with =~.
|
|
62
|
+
• output='complete' returns every annotation and relation of each hit: combine it with fields and limit.
|
|
63
|
+
• Add a Kind: prefix when you can; without it every kind is searched, which is slower and noisier.
|
|
64
|
+
• Pages and menus are resources too (Page, PageMenu): exclude them with a Kind: prefix when you look for architecture.
|
|
41
65
|
DESC
|
|
42
66
|
arguments do
|
|
43
67
|
required(:query).filled(:string).description(
|
|
@@ -51,6 +75,10 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
51
75
|
"'brief' = minimal output with just kind and name for each resource, " \
|
|
52
76
|
"'count' = only totals grouped by kind, no individual resources returned"
|
|
53
77
|
)
|
|
78
|
+
optional(:fields).array(:string).description(
|
|
79
|
+
"Only these annotation keys and relation verbs in output='complete' " \
|
|
80
|
+
"(e.g. ['activity/status', 'maintainedBy']). Default: all. Keeps results small."
|
|
81
|
+
)
|
|
54
82
|
optional(:limit).filled(:integer).description(
|
|
55
83
|
"Maximum results to return (1-500). Use with offset for pagination. Ignored when output='count'."
|
|
56
84
|
)
|
|
@@ -60,7 +88,7 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
60
88
|
)
|
|
61
89
|
end
|
|
62
90
|
|
|
63
|
-
def call(query:, output: "complete", limit: 50, offset: 0)
|
|
91
|
+
def call(query:, output: "complete", limit: 50, offset: 0, fields: nil)
|
|
64
92
|
db = Archsight::MCP.db
|
|
65
93
|
|
|
66
94
|
begin
|
|
@@ -68,9 +96,13 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
68
96
|
results = parsed_query.filter(db)
|
|
69
97
|
total = results.length
|
|
70
98
|
|
|
71
|
-
#
|
|
99
|
+
# Complete output omits the kind when filtering by a specific kind (it's redundant); brief always names
|
|
100
|
+
# it, so a hit can feed analyze_resource(kind, name) without guessing
|
|
72
101
|
omit_kind = !parsed_query.kind_filter.nil?
|
|
73
102
|
|
|
103
|
+
conditions = Archsight::MCP::QueryHints.relation_conditions(parsed_query.ast)
|
|
104
|
+
text_conditions = Archsight::MCP::QueryHints.text_conditions(parsed_query.ast)
|
|
105
|
+
|
|
74
106
|
# Count-only mode: return totals grouped by kind
|
|
75
107
|
if output == "count"
|
|
76
108
|
by_kind = results.group_by { |r| r.class.to_s.split("::").last }
|
|
@@ -86,11 +118,17 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
86
118
|
paginated = results.sort_by(&:name).drop(offset).take(limit)
|
|
87
119
|
resources = case output
|
|
88
120
|
when "brief"
|
|
89
|
-
paginated.map { |r| Archsight::MCP.brief_summary(r,
|
|
121
|
+
paginated.map { |r| Archsight::MCP.brief_summary(r, with_source: true) }
|
|
90
122
|
else # "complete"
|
|
91
|
-
paginated.map
|
|
123
|
+
paginated.map do |r|
|
|
124
|
+
summary = Archsight::MCP.complete_summary(r, omit_kind: omit_kind, with_source: true)
|
|
125
|
+
Archsight::MCP.project(summary, fields)
|
|
126
|
+
end
|
|
92
127
|
end
|
|
93
128
|
|
|
129
|
+
add_matched_via(resources, paginated, conditions)
|
|
130
|
+
add_matched_text(resources, paginated, text_conditions)
|
|
131
|
+
|
|
94
132
|
result = {
|
|
95
133
|
query: query,
|
|
96
134
|
total: total,
|
|
@@ -101,7 +139,10 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
101
139
|
}
|
|
102
140
|
end
|
|
103
141
|
|
|
104
|
-
|
|
142
|
+
warnings = Archsight::MCP::QueryHints.unknown_key_warnings(parsed_query)
|
|
143
|
+
result = result.merge(warnings: warnings) unless warnings.empty?
|
|
144
|
+
|
|
145
|
+
fit_response(result, output, fields)
|
|
105
146
|
rescue Archsight::Query::QueryError => e
|
|
106
147
|
JSON.pretty_generate({
|
|
107
148
|
error: "Query error",
|
|
@@ -110,4 +151,48 @@ class Archsight::MCP::QueryTool < FastMcp::Tool
|
|
|
110
151
|
})
|
|
111
152
|
end
|
|
112
153
|
end
|
|
154
|
+
|
|
155
|
+
private
|
|
156
|
+
|
|
157
|
+
# For text queries (`text =~ "x"`): the annotation and the snippet around the match, per hit
|
|
158
|
+
def add_matched_text(summaries, resources, conditions)
|
|
159
|
+
return if conditions.empty?
|
|
160
|
+
|
|
161
|
+
summaries.zip(resources).each do |summary, resource|
|
|
162
|
+
found = Archsight::MCP::QueryHints.matched_text(resource, conditions)
|
|
163
|
+
summary[:matched_text] = found unless found.empty?
|
|
164
|
+
end
|
|
165
|
+
end
|
|
166
|
+
|
|
167
|
+
# For relation queries (`-> Kind`, `<- "Name"`): the direct relations that made each hit match
|
|
168
|
+
def add_matched_via(summaries, resources, conditions)
|
|
169
|
+
return if conditions.empty?
|
|
170
|
+
|
|
171
|
+
summaries.zip(resources).each do |summary, resource|
|
|
172
|
+
via = Archsight::MCP::QueryHints.matched_via(resource, conditions)
|
|
173
|
+
summary[:matched_via] = via unless via.empty?
|
|
174
|
+
end
|
|
175
|
+
end
|
|
176
|
+
|
|
177
|
+
# Cuts the resources of an oversized result down (halving until it fits) and says how to get the rest
|
|
178
|
+
def fit_response(result, output, fields)
|
|
179
|
+
return JSON.pretty_generate(result) unless result[:resources]
|
|
180
|
+
|
|
181
|
+
full = result[:resources]
|
|
182
|
+
Archsight::MCP.fit(result) do |attempt|
|
|
183
|
+
keep = [full.length / (2**attempt), 1].max
|
|
184
|
+
result.merge(
|
|
185
|
+
resources: full.take(keep),
|
|
186
|
+
count: keep,
|
|
187
|
+
truncated: "Response cut to #{keep} of #{full.length} resources (size budget). " \
|
|
188
|
+
"#{hint_for(output, fields)}"
|
|
189
|
+
)
|
|
190
|
+
end
|
|
191
|
+
end
|
|
192
|
+
|
|
193
|
+
def hint_for(output, fields)
|
|
194
|
+
return "Use a smaller limit with offset, or output='brief'/'count'." if output == "complete" && fields.nil?
|
|
195
|
+
|
|
196
|
+
"Use a smaller limit with offset."
|
|
197
|
+
end
|
|
113
198
|
end
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "base"
|
|
4
|
+
|
|
5
|
+
class Archsight::MCP::RelationsTool < FastMcp::Tool
|
|
6
|
+
tool_name "relations"
|
|
7
|
+
|
|
8
|
+
description <<~DESC.gsub("\n", " ").strip
|
|
9
|
+
List the DIRECT relations of one resource, filtered and grouped by verb. No transitive expansion, no other
|
|
10
|
+
resource details (use analyze_resource for those, or depth/impact for transitive views).
|
|
11
|
+
|
|
12
|
+
Each relation is {verb, direction, kind, name}: direction 'out' = this resource points at the target
|
|
13
|
+
(e.g. realizedThrough), 'in' = the other resource points at this one (e.g. what it is servedBy).
|
|
14
|
+
|
|
15
|
+
EXAMPLES:
|
|
16
|
+
kind="ApplicationService", name="X", verb="realizedThrough" - only the direct realizedThrough targets
|
|
17
|
+
kind="ApplicationComponent", name="Y", direction="in", target_kind="ApplicationService" - which services use Y
|
|
18
|
+
|
|
19
|
+
A name that does not exist returns the closest matches across all kinds.
|
|
20
|
+
|
|
21
|
+
TYPICAL FLOW: find the exact name with query (output='brief'), then ask for one verb or one target kind here.
|
|
22
|
+
PITFALLS: kind and name are exact and case-sensitive; verbs are exact (a verb the resource does not have
|
|
23
|
+
gives a warning listing the verbs it has); 'in' relations are the ones other resources declare towards it.
|
|
24
|
+
DESC
|
|
25
|
+
arguments do
|
|
26
|
+
required(:kind).filled(:string).description("Resource kind, e.g. ApplicationService")
|
|
27
|
+
required(:name).filled(:string).description(
|
|
28
|
+
"Exact name of the resource (case-sensitive). A wrong name returns suggestions."
|
|
29
|
+
)
|
|
30
|
+
optional(:verb).filled(:string).description("Only this relation verb (e.g. 'realizedThrough', 'servedBy')")
|
|
31
|
+
optional(:direction).filled(:string).description(
|
|
32
|
+
"'out' (this resource points at the target), 'in' (the other points at this one), 'both' (default)"
|
|
33
|
+
)
|
|
34
|
+
optional(:target_kind).filled(:string).description("Only relations whose other end is of this kind")
|
|
35
|
+
optional(:limit).filled(:integer).description("Maximum relations returned (default 100, max 500)")
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
DIRECTIONS = %w[out in both].freeze
|
|
39
|
+
|
|
40
|
+
def call(kind:, name:, verb: nil, direction: "both", target_kind: nil, limit: 100)
|
|
41
|
+
return error("Unknown resource kind: #{kind}") unless Archsight::Resources[kind]
|
|
42
|
+
return error("Unknown direction: #{direction}. Use out, in or both") unless DIRECTIONS.include?(direction)
|
|
43
|
+
|
|
44
|
+
instance = Archsight::MCP.db.instance_by_kind(kind, name)
|
|
45
|
+
return not_found(kind, name) unless instance
|
|
46
|
+
|
|
47
|
+
build(instance, kind, name, verb, direction, target_kind, [[limit.to_i, 1].max, 500].min)
|
|
48
|
+
rescue StandardError => e
|
|
49
|
+
error("#{e.class}: #{e.message}")
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
private
|
|
53
|
+
|
|
54
|
+
def build(instance, kind, name, verb, direction, target_kind, limit)
|
|
55
|
+
all = Archsight::MCP.direct_relations(instance)
|
|
56
|
+
relations = all.select do |rel|
|
|
57
|
+
(verb.nil? || rel[:verb] == verb) &&
|
|
58
|
+
(direction == "both" || rel[:direction] == direction) &&
|
|
59
|
+
(target_kind.nil? || rel[:kind] == target_kind)
|
|
60
|
+
end
|
|
61
|
+
relations = relations.sort_by { |rel| [rel[:verb], rel[:direction], rel[:kind], rel[:name]] }
|
|
62
|
+
shown = relations.first(limit)
|
|
63
|
+
|
|
64
|
+
result = { resource: { kind: kind, name: name }, total: relations.length, shown: shown.length }
|
|
65
|
+
result[:by_verb] = relations.group_by { |rel| rel[:verb] }.transform_values(&:length)
|
|
66
|
+
result[:relations] = shown.group_by { |rel| rel[:verb] }
|
|
67
|
+
result[:truncated] = "#{relations.length - shown.length} more not listed; narrow with verb, direction or target_kind" if shown.length < relations.length
|
|
68
|
+
warning = unknown_verb_warning(all, verb)
|
|
69
|
+
result[:warning] = warning if warning && relations.empty?
|
|
70
|
+
JSON.pretty_generate(result)
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
def unknown_verb_warning(all, verb)
|
|
74
|
+
return nil if verb.nil? || all.any? { |rel| rel[:verb] == verb }
|
|
75
|
+
|
|
76
|
+
known = all.map { |rel| rel[:verb] }.uniq.sort
|
|
77
|
+
"This resource has no relations with verb \"#{verb}\". Verbs present: #{known.empty? ? "none" : known.join(", ")}"
|
|
78
|
+
end
|
|
79
|
+
|
|
80
|
+
def not_found(kind, name)
|
|
81
|
+
suggestions = Archsight::MCP.suggest(name, kind: kind)
|
|
82
|
+
message = ["Resource not found: #{kind}/#{name}", Archsight::MCP.did_you_mean(suggestions)].compact.join(". ")
|
|
83
|
+
JSON.pretty_generate({ error: "Error", message: message, suggestions: suggestions })
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def error(message)
|
|
87
|
+
JSON.pretty_generate({ error: "Error", message: message })
|
|
88
|
+
end
|
|
89
|
+
end
|
|
@@ -18,6 +18,11 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
|
|
|
18
18
|
Includes description, available annotations, relations, and a YAML example template.
|
|
19
19
|
Example: kind="TechnologyArtifact"
|
|
20
20
|
|
|
21
|
+
TYPICAL FLOW: list the kinds, then ask for one kind, with section=annotations to learn which annotation keys a
|
|
22
|
+
query filter can use, or section=relations to learn which verbs connect it to other kinds.
|
|
23
|
+
PITFALLS: kind names are exact and case-sensitive; without a kind only a one-line list comes back (not the
|
|
24
|
+
full documentation of every kind), so always name the kind you need.
|
|
25
|
+
|
|
21
26
|
COMMON RESOURCE KINDS:
|
|
22
27
|
• TechnologyArtifact - Code repositories, artifacts, and technology components
|
|
23
28
|
• ApplicationComponent - Services and application building blocks
|
|
@@ -29,15 +34,21 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
|
|
|
29
34
|
arguments do
|
|
30
35
|
optional(:kind).filled(:string).description(
|
|
31
36
|
'Resource kind to get documentation for (e.g., "TechnologyArtifact", "ApplicationComponent"). ' \
|
|
32
|
-
"If not specified, returns a list of all available resource kinds."
|
|
37
|
+
"If not specified, returns a compact list of all available resource kinds (one line each)."
|
|
38
|
+
)
|
|
39
|
+
optional(:section).filled(:string).description(
|
|
40
|
+
"Only this part of a kind's documentation: 'description' (everything before the annotations), " \
|
|
41
|
+
"'annotations', 'relations' or 'example'. Default: the whole document. Needs a kind."
|
|
33
42
|
)
|
|
34
43
|
end
|
|
35
44
|
|
|
36
|
-
|
|
45
|
+
SECTIONS = %w[description annotations relations example].freeze
|
|
46
|
+
|
|
47
|
+
def call(kind: nil, section: nil)
|
|
37
48
|
if kind.nil? || kind.empty?
|
|
38
49
|
list_resource_kinds
|
|
39
50
|
else
|
|
40
|
-
get_resource_documentation(kind)
|
|
51
|
+
get_resource_documentation(kind, section)
|
|
41
52
|
end
|
|
42
53
|
rescue StandardError => e
|
|
43
54
|
error_response(e.message, e.class.name)
|
|
@@ -52,36 +63,44 @@ class Archsight::MCP::ResourceDocTool < FastMcp::Tool
|
|
|
52
63
|
})
|
|
53
64
|
end
|
|
54
65
|
|
|
66
|
+
# One line per kind ("Kind (layer): first sentence"), so the whole list stays a few KB
|
|
55
67
|
def list_resource_kinds
|
|
56
68
|
kinds = []
|
|
57
69
|
|
|
58
70
|
Archsight::Resources.each do |kind_symbol|
|
|
59
71
|
klass = Archsight::Resources.const_get(kind_symbol)
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
annotation_count: klass.annotations.count,
|
|
64
|
-
relation_count: klass.declared_relations.count
|
|
65
|
-
}
|
|
72
|
+
text = Archsight::MCP.one_liner(klass.description, max: 80)
|
|
73
|
+
text = "No description available" if text.empty?
|
|
74
|
+
kinds << "#{kind_symbol} (#{klass.layer}): #{text}"
|
|
66
75
|
end
|
|
67
76
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
77
|
+
JSON.pretty_generate({
|
|
78
|
+
total: kinds.length,
|
|
79
|
+
hint: 'Call resource_doc(kind: "<Kind>") for the full documentation, add section: ' \
|
|
80
|
+
"description|annotations|relations|example for one part.",
|
|
81
|
+
resource_kinds: kinds
|
|
82
|
+
})
|
|
74
83
|
end
|
|
75
84
|
|
|
76
|
-
def get_resource_documentation(kind)
|
|
85
|
+
def get_resource_documentation(kind, section)
|
|
77
86
|
klass = Archsight::Resources[kind]
|
|
78
87
|
return error_response("Unknown resource kind: #{kind}") unless klass
|
|
79
88
|
|
|
89
|
+
return error_response("Unknown section: #{section}. Use one of #{SECTIONS.join(", ")}") if section && !SECTIONS.include?(section)
|
|
90
|
+
|
|
80
91
|
content = Archsight::Documentation.generate(kind)
|
|
92
|
+
content = extract_section(content, section) if section
|
|
93
|
+
result = { kind: kind }
|
|
94
|
+
result[:section] = section if section
|
|
95
|
+
result[:documentation] = content
|
|
81
96
|
|
|
82
|
-
JSON.pretty_generate(
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
97
|
+
JSON.pretty_generate(result)
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
# "description" is everything before `## Annotations`; the others are the `## Name` block of that heading
|
|
101
|
+
def extract_section(content, section)
|
|
102
|
+
return content.split(/^## Annotations$/, 2).first.to_s.strip if section == "description"
|
|
103
|
+
|
|
104
|
+
content[/^## #{section.capitalize}$.*?(?=^## |\z)/m].to_s.strip
|
|
86
105
|
end
|
|
87
106
|
end
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "base"
|
|
4
|
+
require_relative "../summary"
|
|
5
|
+
|
|
6
|
+
class Archsight::MCP::SummaryTool < FastMcp::Tool
|
|
7
|
+
tool_name "summary"
|
|
8
|
+
|
|
9
|
+
description <<~DESC.gsub("\n", " ").strip
|
|
10
|
+
Explain a resource in context from its name: what it is (kind, layer, description, key facts) and how it fits in,
|
|
11
|
+
as a short markdown summary. Which relations are followed depends on the layer of the resource (the lens):
|
|
12
|
+
motivation = stakeholders, parent goals and refinements, requirements, evidence; strategy = what realizes and
|
|
13
|
+
serves it; business = people, controls, products and contracts; application = interfaces, what it runs on, what
|
|
14
|
+
depends on it, owners; technology = what it is built on, what runs on it, where it is, owners; implementation =
|
|
15
|
+
plateau, gap and work package chain.
|
|
16
|
+
|
|
17
|
+
Every resource in the summary is a link [[Kind/Name]]: take kind and name from it for the next call. A group
|
|
18
|
+
that is cut off says how many more there are and the exact relations(...) call that lists them. Empty groups are
|
|
19
|
+
not shown. A closing section points to the other layers that have related resources.
|
|
20
|
+
|
|
21
|
+
EXAMPLES:
|
|
22
|
+
name="Backup" - finds the resource of that name in any kind; several matches come back as a list to choose from
|
|
23
|
+
kind="MotivationRequirement", name="R-7" - motivation lens: stakeholders, refinements, realized by, evidence
|
|
24
|
+
kind="ApplicationComponent", name="checkout" - application lens: interfaces, runs on, used by, owners
|
|
25
|
+
kind="TechnologyNode", name="node-1" - technology lens: runs on it, location, owners
|
|
26
|
+
kind="BusinessProcess", name="Billing", lens="application" - the same resource through another layer's lens
|
|
27
|
+
TYPICAL FLOW: query to find the name (or pass it directly), summary for the overview, then relations or
|
|
28
|
+
analyze_resource for details. PITFALLS: the name is exact and case-sensitive (a close one is suggested); per_section
|
|
29
|
+
only widens the lists, the summary stays bounded; lenses can be tuned per layer by a Config of type summary.
|
|
30
|
+
DESC
|
|
31
|
+
arguments do
|
|
32
|
+
required(:name).filled(:string).description(
|
|
33
|
+
"Name of the resource (or one of its aliases). Case-sensitive; without kind every kind is searched."
|
|
34
|
+
)
|
|
35
|
+
optional(:kind).filled(:string).description("Kind of the resource, to tell apart equal names, e.g. ApplicationComponent")
|
|
36
|
+
optional(:lens).filled(:string).description(
|
|
37
|
+
"View the resource through another layer's lens: #{Archsight::Resources::LAYERS.join(", ")}. Default: its own layer."
|
|
38
|
+
)
|
|
39
|
+
optional(:per_section).filled(:integer).description(
|
|
40
|
+
"Resources listed per relation group (1-20, default 5). The overall size stays capped."
|
|
41
|
+
)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def call(name:, kind: nil, lens: nil, per_section: 5)
|
|
45
|
+
return error("Unknown lens: #{lens}. Use one of #{Archsight::Resources::LAYERS.join(", ")}") if lens && !Archsight::Resources::LAYERS.include?(lens)
|
|
46
|
+
return error("Unknown resource kind: #{kind}") if kind && !Archsight::Resources[kind]
|
|
47
|
+
|
|
48
|
+
found = resolve(name, kind)
|
|
49
|
+
return not_found(name, kind) if found.empty?
|
|
50
|
+
return ambiguous(name, found) if found.length > 1
|
|
51
|
+
|
|
52
|
+
summarize(found.first, lens, per_section)
|
|
53
|
+
rescue StandardError => e
|
|
54
|
+
error("#{e.class}: #{e.message}")
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
private
|
|
58
|
+
|
|
59
|
+
def summarize(instance, lens, per_section)
|
|
60
|
+
info = Archsight::MCP.source_info(instance)
|
|
61
|
+
markdown = Archsight::Summary::Builder.new(Archsight::MCP.db, per_section: per_section)
|
|
62
|
+
.call(instance, lens_layer: lens, source: info)
|
|
63
|
+
JSON.pretty_generate({
|
|
64
|
+
kind: instance.klass,
|
|
65
|
+
name: instance.name,
|
|
66
|
+
layer: instance.class.layer,
|
|
67
|
+
lens: lens || instance.class.layer
|
|
68
|
+
}.merge(info).merge(summary: markdown))
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
# The resources called `name` (an alias counts, then the same name in another letter case), of `kind` or of any kind
|
|
72
|
+
def resolve(name, kind)
|
|
73
|
+
db = Archsight::MCP.db
|
|
74
|
+
kinds = kind ? [kind] : db.instances.keys.map { |klass| klass.to_s.split("::").last }
|
|
75
|
+
[
|
|
76
|
+
-> { kinds.filter_map { |k| db.instance_by_kind(k, name) } },
|
|
77
|
+
-> { kinds.filter_map { |k| db.instance_by_alias(k, name) } },
|
|
78
|
+
-> { kinds.flat_map { |k| db.instances_by_kind(k).values.select { |i| i.name.to_s.casecmp?(name) } } }
|
|
79
|
+
].each do |attempt|
|
|
80
|
+
found = attempt.call.uniq
|
|
81
|
+
return found unless found.empty?
|
|
82
|
+
end
|
|
83
|
+
[]
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def ambiguous(name, found)
|
|
87
|
+
candidates = found.sort_by { |i| [i.klass, i.name] }.map do |i|
|
|
88
|
+
{ kind: i.klass, name: i.name, link: "[[#{i.klass}/#{i.name}]]", description: Archsight::MCP.extract_description(i) }
|
|
89
|
+
end
|
|
90
|
+
JSON.pretty_generate({
|
|
91
|
+
ambiguous: true,
|
|
92
|
+
message: "#{found.length} resources are called #{name}; call summary again with kind set to one of them",
|
|
93
|
+
candidates: candidates
|
|
94
|
+
})
|
|
95
|
+
end
|
|
96
|
+
|
|
97
|
+
def not_found(name, kind)
|
|
98
|
+
suggestions = Archsight::MCP.suggest(name, kind: kind)
|
|
99
|
+
message = ["Resource not found: #{[kind, name].compact.join("/")}", Archsight::MCP.did_you_mean(suggestions)].compact.join(". ")
|
|
100
|
+
JSON.pretty_generate({ error: "Error", message: message, suggestions: suggestions })
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
def error(message)
|
|
104
|
+
JSON.pretty_generate({ error: "Error", message: message })
|
|
105
|
+
end
|
|
106
|
+
end
|
data/lib/archsight/mcp.rb
CHANGED
|
@@ -3,5 +3,7 @@
|
|
|
3
3
|
require_relative "mcp/base"
|
|
4
4
|
require_relative "mcp/query_tool"
|
|
5
5
|
require_relative "mcp/analyze_resource_tool"
|
|
6
|
+
require_relative "mcp/relations_tool"
|
|
7
|
+
require_relative "mcp/summary_tool"
|
|
6
8
|
require_relative "mcp/resource_doc_tool"
|
|
7
9
|
require_relative "mcp/execute_analysis_tool"
|
data/lib/archsight/query/ast.rb
CHANGED
|
@@ -93,6 +93,34 @@ module Archsight::Query::AST
|
|
|
93
93
|
end
|
|
94
94
|
end
|
|
95
95
|
|
|
96
|
+
# Free-text condition: text =~ "pattern", text: "pattern", text(key, key/*) =~ "pattern". Matches when a string
|
|
97
|
+
# annotation (all of them, or the ones named by `keys`, which may end in a `*` wildcard) contains the pattern.
|
|
98
|
+
class TextCondition < Node
|
|
99
|
+
attr_reader :keys, :operator, :value
|
|
100
|
+
|
|
101
|
+
def initialize(keys, operator, value)
|
|
102
|
+
@keys = keys # Array of String (annotation keys or key patterns), or nil for every annotation
|
|
103
|
+
@operator = operator # "=~"
|
|
104
|
+
@value = value # StringValue or RegexValue
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
# The compiled pattern, built once per query (every resource is checked against it)
|
|
108
|
+
def regexp
|
|
109
|
+
@regexp ||= Archsight::Query::AST.regexp_for(value)
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
# The key patterns as regular expressions (`*` = any run of characters), nil = every key
|
|
113
|
+
def key_patterns
|
|
114
|
+
return nil unless keys
|
|
115
|
+
|
|
116
|
+
@key_patterns ||= keys.map { |key| Regexp.new("\\A#{Regexp.escape(key).gsub("\\*", ".+")}\\z") }
|
|
117
|
+
end
|
|
118
|
+
|
|
119
|
+
def accept(visitor)
|
|
120
|
+
visitor.visit_text_condition(self)
|
|
121
|
+
end
|
|
122
|
+
end
|
|
123
|
+
|
|
96
124
|
# Kind condition: kind == "SomeKind" or kind =~ "pattern"
|
|
97
125
|
class KindCondition < Node
|
|
98
126
|
attr_reader :operator, :value
|
|
@@ -143,6 +143,8 @@ class Archsight::Query::Evaluator
|
|
|
143
143
|
evaluate_annotation_exists_condition(node, instance)
|
|
144
144
|
when Archsight::Query::AST::AnnotationInCondition
|
|
145
145
|
evaluate_annotation_in_condition(node, instance)
|
|
146
|
+
when Archsight::Query::AST::TextCondition
|
|
147
|
+
Archsight::Query::TextSearch.matches?(instance, node)
|
|
146
148
|
when Archsight::Query::AST::KindCondition
|
|
147
149
|
evaluate_kind_condition(node, instance)
|
|
148
150
|
when Archsight::Query::AST::KindInCondition
|
|
@@ -245,8 +245,8 @@ class Archsight::Query::Lexer
|
|
|
245
245
|
|
|
246
246
|
# Allow letters, digits, underscores, hyphens, slashes, and dots in identifiers
|
|
247
247
|
# This supports annotation paths like "activity/status" and "scc/language/Go/loc"
|
|
248
|
-
# and resource names like "teleport.e"
|
|
249
|
-
while @position < @input.length && @input[@position] =~ %r{[a-zA-Z0-9_
|
|
248
|
+
# and resource names like "teleport.e"; `*` is for key patterns such as text(link/*)
|
|
249
|
+
while @position < @input.length && @input[@position] =~ %r{[a-zA-Z0-9_\-/.*]}
|
|
250
250
|
value += @input[@position]
|
|
251
251
|
@position += 1
|
|
252
252
|
end
|
|
@@ -388,6 +388,8 @@ class Archsight::Query::Parser
|
|
|
388
388
|
path = current_token.value
|
|
389
389
|
advance
|
|
390
390
|
|
|
391
|
+
return parse_text_condition if path == "text" && text_condition_ahead?
|
|
392
|
+
|
|
391
393
|
# Check if this is followed by an operator (annotation condition),
|
|
392
394
|
# a question mark (existence check), or a bare identifier (name shortcut)
|
|
393
395
|
if %i[EQ NEQ MATCH GT LT GTE LTE IN].include?(current_token.type)
|
|
@@ -403,6 +405,49 @@ class Archsight::Query::Parser
|
|
|
403
405
|
end
|
|
404
406
|
end
|
|
405
407
|
|
|
408
|
+
# `text` starts a free-text condition when `=~`, `:` plus a value, or a key list in parentheses follows;
|
|
409
|
+
# otherwise it is the bare word "text" (a name search)
|
|
410
|
+
def text_condition_ahead?
|
|
411
|
+
case current_token.type
|
|
412
|
+
when :MATCH, :LPAREN then true
|
|
413
|
+
when :COLON then %i[STRING REGEX].include?(peek_token&.type)
|
|
414
|
+
else false
|
|
415
|
+
end
|
|
416
|
+
end
|
|
417
|
+
|
|
418
|
+
# text =~ "x" | text: "x" | text(architecture/description, link/*) =~ "x"
|
|
419
|
+
def parse_text_condition
|
|
420
|
+
keys = nil
|
|
421
|
+
if current_token.type == :LPAREN
|
|
422
|
+
advance
|
|
423
|
+
keys = parse_text_keys
|
|
424
|
+
expect(:RPAREN)
|
|
425
|
+
end
|
|
426
|
+
|
|
427
|
+
raise Archsight::Query::ParseError.new("Expected =~ or : after text", position: current_token.position, source: nil) unless %i[MATCH COLON].include?(current_token.type)
|
|
428
|
+
|
|
429
|
+
advance
|
|
430
|
+
|
|
431
|
+
value_token = current_token
|
|
432
|
+
value = parse_value
|
|
433
|
+
check_value("=~", value, value_token)
|
|
434
|
+
Archsight::Query::AST::TextCondition.new(keys, "=~", value)
|
|
435
|
+
end
|
|
436
|
+
|
|
437
|
+
def parse_text_keys
|
|
438
|
+
keys = []
|
|
439
|
+
loop do
|
|
440
|
+
raise Archsight::Query::ParseError.new("Expected an annotation key in text(...)", position: current_token.position, source: nil) unless %i[IDENTIFIER STRING].include?(current_token.type)
|
|
441
|
+
|
|
442
|
+
keys << current_token.value
|
|
443
|
+
advance
|
|
444
|
+
break unless current_token.type == :COMMA
|
|
445
|
+
|
|
446
|
+
advance
|
|
447
|
+
end
|
|
448
|
+
keys
|
|
449
|
+
end
|
|
450
|
+
|
|
406
451
|
# Names contain colons (`Archsight:CLI`, `ITGS:A001`). A bare name written without spaces around its colons is
|
|
407
452
|
# one word: `ApplicationService:ITGS:A001` is the kind and the name `ITGS:A001`.
|
|
408
453
|
def glue_name(first)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative "ast"
|
|
4
|
+
|
|
5
|
+
# Free-text search over the string annotations of a resource (`text =~ "x"`), shared by the evaluator and by the
|
|
6
|
+
# MCP query tool, which shows where the text was found.
|
|
7
|
+
module Archsight::Query::TextSearch
|
|
8
|
+
SNIPPET_WIDTH = 60
|
|
9
|
+
|
|
10
|
+
class << self
|
|
11
|
+
# Yields [key, value, MatchData] for every string annotation of `instance` the condition matches
|
|
12
|
+
def each_match(instance, condition, &block)
|
|
13
|
+
return enum_for(:each_match, instance, condition) unless block
|
|
14
|
+
|
|
15
|
+
regex = condition.regexp
|
|
16
|
+
keys = condition.key_patterns
|
|
17
|
+
instance.annotations.each do |key, value|
|
|
18
|
+
next unless value.is_a?(String)
|
|
19
|
+
next if keys&.none? { |pattern| pattern.match?(key) }
|
|
20
|
+
|
|
21
|
+
match = regex.match(value)
|
|
22
|
+
block.call(key, value, match) if match
|
|
23
|
+
end
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
def matches?(instance, condition)
|
|
27
|
+
!each_match(instance, condition).first.nil?
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
# A short single-line excerpt of `value` around the match
|
|
31
|
+
def snippet(value, match, width: SNIPPET_WIDTH)
|
|
32
|
+
from = [match.begin(0) - width, 0].max
|
|
33
|
+
to = [match.end(0) + width, value.length].min
|
|
34
|
+
text = value[from...to].gsub(/\s+/, " ").strip
|
|
35
|
+
"#{"…" if from.positive?}#{text}#{"…" if to < value.length}"
|
|
36
|
+
end
|
|
37
|
+
end
|
|
38
|
+
end
|
data/lib/archsight/query.rb
CHANGED
|
@@ -195,6 +195,7 @@ module Archsight
|
|
|
195
195
|
def initialize(raw, path_ref)
|
|
196
196
|
@raw = raw
|
|
197
197
|
@path_ref = path_ref
|
|
198
|
+
@merged_refs = [] # : Array[LineReference]
|
|
198
199
|
@references = []
|
|
199
200
|
# Auto-discover annotation keys
|
|
200
201
|
return unless annotations
|
|
@@ -372,6 +373,17 @@ module Archsight
|
|
|
372
373
|
merged = Archsight::Helpers.deep_merge(@raw, inst.raw)
|
|
373
374
|
union_list_annotations!(merged, inst.raw)
|
|
374
375
|
@raw = merged
|
|
376
|
+
@merged_refs << inst.path_ref
|
|
377
|
+
end
|
|
378
|
+
|
|
379
|
+
# Every document this resource is made of (the first one, then the ones merged into it), as LineReferences
|
|
380
|
+
def source_refs
|
|
381
|
+
[path_ref, *@merged_refs].compact.uniq { |ref| [ref.path, ref.line_no] }
|
|
382
|
+
end
|
|
383
|
+
|
|
384
|
+
# True when an importer or generator wrote (part of) the resource: it carries a `generated/script` annotation
|
|
385
|
+
def generated?
|
|
386
|
+
!annotations["generated/script"].to_s.empty?
|
|
375
387
|
end
|
|
376
388
|
|
|
377
389
|
# Annotations hold strings, which replace each other on merge. The values of a list annotation (tags, aliases)
|