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
@@ -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
- # Omit kind from output when filtering by a specific kind (it's redundant)
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, omit_kind: omit_kind) }
121
+ paginated.map { |r| Archsight::MCP.brief_summary(r, with_source: true) }
90
122
  else # "complete"
91
- paginated.map { |r| Archsight::MCP.complete_summary(r, omit_kind: omit_kind) }
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
- JSON.pretty_generate(result)
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
- def call(kind: nil)
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
- kinds << {
61
- kind: kind_symbol.to_s,
62
- description: klass.description || "No description available",
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
- result = {
69
- total: kinds.length,
70
- resource_kinds: kinds
71
- }
72
-
73
- JSON.pretty_generate(result)
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
- kind: kind,
84
- documentation: content
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"
@@ -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
@@ -8,6 +8,7 @@ require_relative "query/errors"
8
8
  require_relative "query/ast"
9
9
  require_relative "query/lexer"
10
10
  require_relative "query/parser"
11
+ require_relative "query/text_search"
11
12
  require_relative "query/evaluator"
12
13
 
13
14
  module Archsight
@@ -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)