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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 931ae81cd7562b88a4be605ed42cde3edc97e88d5f1c5623872ba3c1ea6fc60a
4
- data.tar.gz: d1c4069f44304777333c400a139ff698727b86a6af72a1706cafe32ba327a13d
3
+ metadata.gz: 902d20b9ffcd9cecfb00ce3ab315eb21e29d6bd886aad9f8a76f24e8243f450c
4
+ data.tar.gz: 9c525ce80c3591e8f7ce4174ee88a9b38b5ddd876e5944c49382bc9b550ff9be
5
5
  SHA512:
6
- metadata.gz: 663df3921270f629b6e8b50f403587077b69d0a601f169920b002cf52e799a522b86ad0b9196a739cad0a630b92cb57bff504744c342706e4419b44a27c1c666
7
- data.tar.gz: ed596c265fba09d9f902432e391297ba9c8c41ba3da8ea4fddf99d17e67b4df69f67ff25be17cc610406b3e4fa247e7db96d9f49d8254c18469cd56aaa07ede5
6
+ metadata.gz: 76a974e8777040e76fdc415d3943812f0d060bbb9b52a03708b2743b1e06431bd173f674ffb7b71cfa010892edab55b506cd210cec5b3851f38d741d1144020e
7
+ data.tar.gz: 6a04c4cd33b260b63717525427b35e69a2905e93c950740a01e44c46b4c7dd015f8daae7abe04ca2c4c032eb674924e7fb2fae621eb7c01790eb6e610d099990
data/README.md CHANGED
@@ -106,6 +106,8 @@ time out the long-lived SSE connection.
106
106
 
107
107
  - `query` - Search and filter resources using the query language
108
108
  - `analyze_resource` - Get detailed resource information and impact analysis
109
+ - `summary` - Explain a resource in context from its name, through a lens chosen by its layer (tunable by a `Config` of type `summary`)
110
+ - `relations` - Direct relations of one resource, filtered by verb, direction and target kind
109
111
  - `resource_doc` - Get documentation for resource kinds
110
112
 
111
113
  **Export to Confluence**: `archsight export --to confluence` publishes pages to the Confluence page they link to, with images, diagrams and draw.io, views and requirements as tables, and refuses to overwrite edits made in Confluence unless `--force` ([Wiki pages](docs/pages.md#exporting-to-confluence)).
data/docs/archimate.md CHANGED
@@ -110,7 +110,7 @@ ArchiMate is an open and independent enterprise architecture modeling language d
110
110
  | **Product** | A coherent collection of services and/or passive structure elements, accompanied by a contract, offered to customers. |
111
111
 
112
112
  Archsight models Contract as `BusinessContract` (aggregated by a `BusinessProduct`, `agreedBy` its parties, `composedOf` its
113
- call-offs, SLAs and amendments) and Product as `BusinessProduct`. Business Object and Representation are not modelled.
113
+ call-offs, SLAs and amendments, `stipulates` the requirements and constraints it makes binding; ArchiMate has no specific relation from a business object to a motivation element, so this is an association with a defined meaning, like `covers`) and Product as `BusinessProduct`. Business Object and Representation are not modelled.
114
114
 
115
115
  ## Application Layer Elements
116
116
 
data/docs/diagram.md CHANGED
@@ -125,6 +125,13 @@ clean -> store
125
125
  - `database "id" { ... }` — a datastore (cylinder).
126
126
  - `queue "id" { ... }` — a queue/topic (hexagon).
127
127
  - `actor "id" { ... }` — an external user (stick figure, label below).
128
+ - `text "id" { ... }` — a descriptive text block without box or fill. It is
129
+ only as tall as its lines (one label line height per line, a little air
130
+ above and below) and as wide as its text, with no minimum width, so a
131
+ `stack` of one-line texts (each with its own `resource`) reads like a list;
132
+ `**bold**`, `*italic*` and `[links](url)` work as in any
133
+ label. `width "N"` wraps the label at N characters per line. `link` or
134
+ `resource` makes the whole block one link (inline links are then ignored).
128
135
 
129
136
  A leaf's shape can be overridden explicitly with `shape "rectangle" |
130
137
  "circle" | "cylinder" | "hexagon" | "actor"`, though the keyword's default
@@ -144,12 +151,15 @@ hint for near misses), never silently ignored.
144
151
  | `tint` | nodes, containers, edges | `gray`, `blue`, `indigo`, `purple`, `pink`, `red`, `orange`, `yellow`, `green`, `teal`, `cyan`, `brown` |
145
152
  | `link` | nodes, containers | `http(s)://…`, `mailto:…` or a relative URL |
146
153
  | `resource` | nodes, containers | a resource name (`Archsight:Web`) or `Kind/Name` (`ApplicationService/Archsight:Web`); see *Linking to resources* |
147
- | `extend` | nodes, containers | `true`, `false`; containers also `height` |
154
+ | `extend` | nodes, containers | `true`, `false`; containers also `height`, and `width` on a direct child of a `layer` |
155
+ | `width` | `text` | characters per line (positive integer); wraps the label |
148
156
  | `anchor` | containers | `top`, `bottom`, `left`, `right`, `center` |
149
157
 
150
158
  `extend "height"` on a direct child of a `layer` grows it to its tallest sibling. Inside such a box (also through a `boundary` around a `stack`), a `stack` child carrying `extend "height"` takes the extra height and moves the ranks below it down, so e.g. a footer rank lines up across the columns. The child can be a `layer` too; its own `extend "height"` children then fill the layer's new height.
151
159
 
152
- `anchor` says where a container's content sits when its box grows: `bottom` (or `top`) when it is made taller, `right` (or `left`) when it is made wider, `center` for the middle. Default: top for `extend "height"`, centered otherwise. It is not inherited, and has no effect on a box whose room is taken by a stack child with `extend "height"`.
160
+ `extend "width"` is the same for the other axis. When a `layer` is made wider than its content (for example it sits in a `stack` next to a wider sibling), its children normally stay together as one block placed by `anchor`. A direct child of the layer with `extend "width"` instead takes the spare width and pushes the siblings after it to the right edge, so `main` can sit at the left edge and `aside` at the right edge, and the `aside` columns line up across stacked layers. Several children with `extend "width"` share the spare width equally. The child's own content stays at its `anchor` (`left` by default) at its natural size. The attribute is an error anywhere but on a direct child of a `layer`; edges to boxes inside the pushed siblings follow their new positions.
161
+
162
+ `anchor` says where a container's content sits when its box grows: `bottom` (or `top`) when it is made taller, `right` (or `left`) when it is made wider, `center` for the middle. Default: top for `extend "height"`, left for `extend "width"`, centered otherwise. It is not inherited, and has no effect on a box whose room is taken by a stack child with `extend "height"`.
153
163
  | `shape` | leaves | `rectangle`, `circle`, `cylinder`, `pipe`, `actor`, `file`, `module` |
154
164
  | `gap` | containers | pixels (`40`), a percentage (`150%`) or a signed one (`+20%`, `-50%`) |
155
165
  | `ranks` | containers | `auto`, `on`, `down`, `right`, `off` |
data/docs/modeling.md CHANGED
@@ -30,13 +30,13 @@ Implementation & Migration layer describes change across all of them. A relation
30
30
  to what that element depends on, is served by, or is answered by. Following relations from a high-level element
31
31
  therefore walks down to people, code and infrastructure, and the relations form a DAG: nothing may lead back to where
32
32
  it started. `archsight lint` reports every cycle (only `dependsOn` is exempt, because components and services may depend on each
33
- other at runtime, and `connectedTo`, because cables between devices run both ways). `specializes`, `composedOf` and `aggregates` are checked per verb, see "Concept and Implementation" and "Deployment".
33
+ other at runtime, and `connectedTo`, because cables between devices run both ways). `specializes`, `composedOf`, `aggregates` and `refinedBy` are checked per verb, see "Concept and Implementation" and "Deployment".
34
34
 
35
35
  There are two families of verbs:
36
36
 
37
37
  | Family | Verbs | Written on | Points to |
38
38
  |--------|-------|------------|-----------|
39
- | Responsibility and provider (down) | `performedBy`, `ownedBy`, `operatedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `representedBy`, `realizedThrough`, `exposes`, `provisions`, `connects`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
39
+ | Responsibility and provider (down) | `performedBy`, `ownedBy`, `operatedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `representedBy`, `realizedThrough`, `exposes`, `provisions`, `connects`, `mitigatedBy`, `refinedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
40
40
  | Realization (up) | `realizes`, `partiallyRealizes`, `plans`, `satisfies`, `evidencedBy` (on the evidenced element), `provides` | the concrete element | the abstract element it answers to (requirement, goal, capability, plateau) |
41
41
 
42
42
  Rules:
@@ -215,7 +215,7 @@ TechnologySystemSoftware, TechnologyService, TechnologyArtifact). The same princ
215
215
  down to the team, which points to nothing further. On a TechnologyFacility, `servedBy` stays the operator of
216
216
  the site.
217
217
  14. A client device (developer workstation, laptop, phone) is a `TechnologyDevice` with a client `device/type` and
218
- `device/os`, `device/osVersion`, `device/arch`, `device/ownership`, `device/managed` and `device/encryption`; the
218
+ `device/os`, `device/osVersion`, `device/arch` (the CPU generation of a server is `device/cpu`, the exact model `device/cpuModel`), `device/ownership`, `device/managed` and `device/encryption`; the
219
219
  vendor and product are in `device/model` (also for a hardened workstation that runs the user's operating system
220
220
  virtualized beside other isolated sessions, which is a `workstation`). Model the individual machine when it is
221
221
  inventoried, otherwise one `TechnologyNode` per client platform `realizedBy` the devices. The operating system is
@@ -385,6 +385,8 @@ Model **why** the architecture exists.
385
385
 
386
386
  **Example chain:** Stakeholder "Security Team" → hasConcern → Goal "Achieve Compliance" → realizes → Requirement "Encrypt data at rest"; Stakeholder "Security Team" → representedBy → Actor "Security Office"
387
387
 
388
+ **Refining a requirement:** a catalogue requirement (IT-Grundschutz, C5) is either taken as it is, or made more concrete: it is `refinedBy` the requirements derived from it (`spec.refinedBy.motivationRequirements`). The relation is written on the abstract requirement and points down like `composedOf`, so the chain reads top-down from the catalogue through the derived requirements to what realizes them; the derived requirement shows the catalogue requirement as incoming "refines". Chains must not form a cycle.
389
+
388
390
  **Source of a requirement:** the stakeholder that `hasConcern` for a requirement (directly, or for the goal the requirement answers) is its source, and the stakeholder is `representedBy` the `BusinessActor` or `BusinessRole` behind it: the actual organisation, not a generic "customer". This follows ArchiMate, where a stakeholder is a motivation role associated with the actor or role that plays it, and TOGAF, where the requirements repository records each requirement's source and the stakeholder map links stakeholders to organisation units. The requirement's page shows its stakeholders, the actor's page the stakeholder roles it represents. A source is optional.
389
391
 
390
392
  ### Strategy Layer
@@ -435,7 +437,7 @@ Model **who** does **what** in business terms.
435
437
 
436
438
  **Controls:** Process "Incident Response" → guidedBy → Control "Escalation Review" → ownedBy / executedBy → Role or Actor. How controls, requirements and evidence fit together is described under Relation Patterns below.
437
439
 
438
- **Contracts:** Product → aggregates → Contract (framework) → composedOf → Contract (call-off) → covers → Equipment, and the call-off → realizedThrough → Deliverable ← realizes ← Work Package → affects → Equipment. The contract is `agreedBy` the actual organisations (the customer and the provider), not a generic role. All relations are written on the more abstract element; the equipment, the actors and the deliverable show them as incoming ("covered by", "agreed contracts", "fulfils"). A contract is a `BusinessContract`, not a `DataObject` and not text in a description.
440
+ **Contracts:** Product → aggregates → Contract (framework) → composedOf → Contract (call-off) → covers → Equipment, and the call-off → realizedThrough → Deliverable ← realizes ← Work Package → affects → Equipment. The contract is `agreedBy` the actual organisations (the customer and the provider), not a generic role. Contract → stipulates → Requirement / Constraint is the legal basis of an obligation, alongside Stakeholder → hasConcern (who wants it), Element → realizes (what fulfils it) and Evidence → satisfies (the proof); a requirement the provider derives itself is not stipulated by a contract but is linked from the stipulated requirement it refines (`refinedBy`). Granularity follows `composedOf`: the framework contract stipulates the general obligations, an SLA its service levels, a call-off what was ordered with it. All relations are written on the more abstract element; the equipment, the actors and the deliverable show them as incoming ("covered by", "agreed contracts", "fulfils"). A contract is a `BusinessContract`, not a `DataObject` and not text in a description.
439
441
 
440
442
  ```yaml
441
443
  kind: BusinessProduct
@@ -457,7 +459,16 @@ spec:
457
459
  agreedBy:
458
460
  businessActors: [CustomerOrg, ProviderOrg]
459
461
  composedOf:
460
- businessContracts: [Contract:Customer:Block1, Contract:Customer:Block2]
462
+ businessContracts: [Contract:Customer:Block1, Contract:Customer:Block2, Contract:Customer:SLA]
463
+ ---
464
+ kind: BusinessContract
465
+ metadata:
466
+ name: Contract:Customer:SLA
467
+ annotations:
468
+ contract/type: sla
469
+ spec:
470
+ stipulates:
471
+ motivationRequirements: [Req:Availability, Req:ResponseTime]
461
472
  ---
462
473
  kind: BusinessContract
463
474
  metadata:
data/docs/search.md CHANGED
@@ -13,6 +13,7 @@ The search box supports a powerful query language for filtering architecture res
13
13
  | `activity/status?` | Annotation exists (is set) |
14
14
  | `! activity/status?` | Annotation doesn't exist |
15
15
  | `-> ApplicationInterface` | Has relation to a kind |
16
+ | `text =~ "failover"` | Any string annotation contains the text |
16
17
 
17
18
  ## Name Search
18
19
 
@@ -31,6 +32,24 @@ without spaces they are one word, found by name or alias like any other bare wor
31
32
  ITGS:A001 # the resource with the alias ITGS:A001
32
33
  ApplicationService:ITGS:A001 # the same, in one kind
33
34
 
35
+ ## Text Search
36
+
37
+ `text` searches the content of resources: every string annotation (descriptions, titles, `link/*`, page content, ...)
38
+ is checked for the pattern, case-insensitively, like `name =~`:
39
+
40
+ text =~ "failover" # any annotation mentions failover
41
+ text: "failover" # the same, short
42
+ text =~ /fail(over|back)/i # regex literal with flags
43
+ text(architecture/description) =~ "standby" # only this annotation
44
+ text(link/*, page/content) =~ "PROJ-1234" # several keys, `*` is any run of characters
45
+ ApplicationService: text =~ "failover" & -> ApplicationComponent # combined with anything else
46
+
47
+ In a quoted string a backslash only escapes the next character (`"\d"` is `d`); write patterns with escapes as `/regex/`.
48
+
49
+ A resource matches when one of the checked annotations matches. The MCP `query` tool shows the annotation and a short
50
+ snippet around the match for each hit (`matched_text`). The bare word `text` is still a name search; text in YAML
51
+ comments is not searched.
52
+
34
53
  ## Kind Filter
35
54
 
36
55
  Prefix your query with `Kind:` to filter by resource type (a capitalised word that is a kind, followed by a space or
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Capacity module adds the counts that describe how much a group of hosts holds in reserve. A reserve is a number,
4
+ # not a machine: any host can take the role and the actual spare changes over time, so it is not a flag on a device.
5
+ module Archsight::Annotations::Capacity
6
+ def self.included(base)
7
+ base.class_eval do
8
+ annotation "capacity/spareHosts",
9
+ description: "Number of hosts held in reserve (n+1 spares), not tied to a specific machine; the source is a link/* annotation",
10
+ title: "Spare Hosts",
11
+ type: Integer,
12
+ validator: ->(value) { "'#{value}' is not a count of zero or more" unless value.match?(/\A\d+\z/) }
13
+ end
14
+ end
15
+ end
@@ -91,7 +91,7 @@ module Archsight
91
91
  end
92
92
 
93
93
  def instance_by_kind(kind, instance)
94
- @instances[Archsight::Resources[kind]][instance]
94
+ instances_by_kind(kind)[instance]
95
95
  end
96
96
 
97
97
  # The resource of a kind that has `identifier` as one of its aliases (a value of a unique annotation), when exactly
@@ -25,15 +25,18 @@ module Archsight
25
25
  # `Graph::Node`/`Graph::Edge`/`Graph::DataFlow` and with `docs/diagram.md`.
26
26
  module Attributes
27
27
  NODE = %w[label tint link resource extend].freeze
28
- LEAF_KINDS = %i[component application api database queue actor file].freeze
28
+ LEAF_KINDS = %i[component application api database queue actor file text].freeze
29
29
  LEAF = (NODE + %w[shape]).freeze
30
+ # A `text` has no box to restyle (no `shape`), but may wrap at `width` characters.
31
+ TEXT = (NODE + %w[width]).freeze
32
+ WIDTH_FORMAT = /\A[1-9]\d*\z/
30
33
  CONTAINER = (NODE + %w[gap ranks columns anchor]).freeze
31
34
  EDGE = %w[label style relation tint].freeze
32
35
  DATAFLOW = %w[label color].freeze
33
36
 
34
37
  EDGE_STYLES = %w[straight orthogonal].freeze
35
38
  LEAF_EXTEND = %w[true false].freeze
36
- CONTAINER_EXTEND = %w[true false height].freeze
39
+ CONTAINER_EXTEND = %w[true false height width].freeze
37
40
  ANCHORS = %w[top bottom left right center].freeze
38
41
 
39
42
  # `40` (pixels), `150%` (of the default), `+20%`/`-50%` (relative);
@@ -47,7 +50,11 @@ module Archsight
47
50
  module_function
48
51
 
49
52
  def check_node!(block, ranks_modes:)
50
- allowed = leaf?(block) ? LEAF : CONTAINER
53
+ allowed = if block.kind == :text
54
+ TEXT
55
+ else
56
+ leaf?(block) ? LEAF : CONTAINER
57
+ end
51
58
  where = "#{block.kind} #{block.anonymous ? "(anonymous)" : block.id.inspect}"
52
59
  block.attrs.each do |key, value|
53
60
  check_name!(key, allowed, where, block.line)
@@ -119,6 +126,7 @@ module Archsight
119
126
  when "extend" then check_value!(key, value, leaf?(block) ? LEAF_EXTEND : CONTAINER_EXTEND, where, line)
120
127
  when "anchor" then check_value!(key, value, ANCHORS, where, line)
121
128
  when "gap" then check_format!(key, value, GAP_FORMAT, "a pixel count (40), a percentage (150%) or a signed one (+20%, -50%)", where, line)
129
+ when "width" then check_format!(key, value, WIDTH_FORMAT, "a positive number of characters per line", where, line)
122
130
  when "link" then check_link!(value, where, line)
123
131
  when "resource" then check_resource!(value, block, where, line)
124
132
  end
@@ -10,6 +10,7 @@ module Archsight
10
10
  raise GraphError, "#{block.kind} has an empty id (line #{block.line})" if block.id.strip.empty?
11
11
 
12
12
  Attributes.check_node!(block, ranks_modes: RANKS_MODES)
13
+ raise GraphError, "extend \"width\" on #{block.kind} #{block.id.inspect} (line #{block.line}) only applies to a direct child of a layer" if block.attrs["extend"] == "width" && !parent&.layer?
13
14
 
14
15
  node = Node.for(id: block.id, kind: block.kind, attrs: block.attrs, children: [], parent: parent,
15
16
  anonymous: block.anonymous, line: block.line)
@@ -122,7 +122,7 @@ module Archsight
122
122
  # untouched.
123
123
  def extend?(inherited)
124
124
  raw = attrs["extend"]
125
- return inherited if raw.nil? || raw == "height"
125
+ return inherited if raw.nil? || %w[height width].include?(raw)
126
126
 
127
127
  raw != "false"
128
128
  end
@@ -137,6 +137,15 @@ module Archsight
137
137
  attrs["extend"] == "height"
138
138
  end
139
139
 
140
+ # `extend "width"` on a direct child of a `layer`: the child takes an
141
+ # equal share of the layer's spare width (when the layer is made
142
+ # wider than its content), which pushes the siblings after it to the
143
+ # right edge. Its own content stays at its `anchor` (left by
144
+ # default). Never inherited, like `extend "height"`.
145
+ def extend_width?
146
+ attrs["extend"] == "width"
147
+ end
148
+
140
149
  # Where this container's content sits when its box grows by `extra`
141
150
  # along `axis`: the `anchor` attr (`top`/`bottom` for height,
142
151
  # `left`/`right` for width, `center`), else `default`. Returns how
@@ -228,6 +237,21 @@ module Archsight
228
237
  def default_shape = "file"
229
238
  end
230
239
 
240
+ # A borderless, descriptive text block: sized and placed like a
241
+ # component with the same label (so `\n` and `width` wrapping give
242
+ # the same margins), but drawn without box or fill. `width "N"` wraps
243
+ # the label at N characters per line.
244
+ class TextNode < Node
245
+ def leaf? = true
246
+ def default_shape = "text"
247
+
248
+ def label
249
+ text = super
250
+ width = attrs["width"]
251
+ width ? TextMetrics.wrap(text, width.to_i) : text
252
+ end
253
+ end
254
+
231
255
  class Group < Node; end
232
256
 
233
257
  class Boundary < Node
@@ -245,7 +269,7 @@ module Archsight
245
269
 
246
270
  Node::KIND_CLASSES = {
247
271
  component: Component, application: Application, api: Api, database: Database,
248
- queue: Queue, actor: Actor, file: FileNode, group: Group, boundary: Boundary, layer: Layer, stack: Stack
272
+ queue: Queue, actor: Actor, file: FileNode, text: TextNode, group: Group, boundary: Boundary, layer: Layer, stack: Stack
249
273
  }.freeze
250
274
  end
251
275
  end
@@ -71,6 +71,8 @@ module Archsight
71
71
 
72
72
  axis.set_size(box, own_target) if extra.positive?
73
73
 
74
+ return spread_width(node, extra) if extra.positive? && spreads_width?(node, axis)
75
+
74
76
  # `extend`'s multi-child stretching only kicks in for a ranked
75
77
  # node (`stack`/`layer`): both use `Stacker#pack`'s "every child's
76
78
  # cross-axis coordinate sits at half the shared width/height"
@@ -150,8 +152,45 @@ module Archsight
150
152
  end
151
153
  end
152
154
 
155
+ # `extend "width"`: grows `node` to `target` width keeping its content at its `anchor` (left by default),
156
+ # or, for a `layer`, hands the room to its own `extend "width"` children.
157
+ def grow_width(node, target)
158
+ box = @boxes[node.id]
159
+ extra = target - box.width
160
+ return if extra <= 0
161
+
162
+ box.width = target
163
+ return if node.children.empty?
164
+ return spread_width(node, extra) if spreads_width?(node, Axis::WIDTH)
165
+
166
+ recenter_children(node, Axis::WIDTH, node.anchor_shift(Axis::WIDTH, extra, default: :left))
167
+ end
168
+
153
169
  private
154
170
 
171
+ def spreads_width?(node, axis)
172
+ axis == Axis::WIDTH && node.layer? && node.children.any?(&:extend_width?)
173
+ end
174
+
175
+ # A layer made `extra` wider: its `extend "width"` children share the extra width equally and the
176
+ # children after them move right by what was added before them, keeping every gap (so the last
177
+ # sibling ends at the layer's right edge). The re-flow starts at the first child's original leading
178
+ # edge, like `stretch_children`.
179
+ def spread_width(node, extra)
180
+ ordered = node.children.sort_by { |c| Axis::WIDTH.position(@boxes[c.id]) }
181
+ gaps = ordered.each_cons(2).map { |a, b| gap_between(a, b, Axis::WIDTH) }
182
+ pos = Axis::WIDTH.leading_edge(@boxes[ordered.first.id])
183
+ growers = ordered.select(&:extend_width?)
184
+ share = extra / growers.length.to_f
185
+
186
+ ordered.each_with_index do |c, i|
187
+ grow_width(c, @boxes[c.id].width + share) if c.extend_width?
188
+ box = @boxes[c.id]
189
+ Axis::WIDTH.set_position(box, pos + (box.width / 2.0))
190
+ pos += box.width + (gaps[i] || 0.0)
191
+ end
192
+ end
193
+
155
194
  # A grown `layer`'s `extend "height"` children fill the new height
156
195
  # too (they were only matched to their tallest sibling before).
157
196
  def fill_layer(node, extra)
@@ -27,6 +27,9 @@ module Archsight
27
27
  # between the ancestor boxes that are direct children of the group being
28
28
  # laid out, so connected subsystems are still pulled toward each other.
29
29
  class Layout
30
+ # Air above and below the lines of a `text` node.
31
+ TEXT_PADDING = 2.0
32
+
30
33
  Box = Struct.new(:x, :y, :width, :height) do
31
34
  # `left`/`right`/`top`/`bottom` fall through to a live computation
32
35
  # until `freeze_bounds!` runs -- every read during `Layout.compute`
@@ -171,10 +174,18 @@ module Archsight
171
174
  return [width, @theme.actor_figure_height + @theme.actor_label_height + extra_height]
172
175
  end
173
176
 
177
+ return text_size(node, extra_height) if node.kind == :text
178
+
174
179
  width = [label_width(node) + @theme.node_label_padding, @theme.node_min_width].max
175
180
  [width, @theme.node_height + extra_height]
176
181
  end
177
182
 
183
+ # A text node has no box to pad out: one line height per line and a little air, and no minimum width, so a
184
+ # stack of one-line texts reads like the lines of a single multi-line one.
185
+ def text_size(node, extra_height)
186
+ [label_width(node) + @theme.node_label_padding, @theme.label_line_height + extra_height + (2 * TEXT_PADDING)]
187
+ end
188
+
178
189
  def label_width(node)
179
190
  return TextMetrics.rendered_width(node.label, font_size: @theme.node_font_size) if @theme.measure_text_with_font_metrics
180
191
 
@@ -96,7 +96,7 @@ module Archsight
96
96
  # `tinted_containers` below), not a flat swatch, unless that same
97
97
  # tint is *also* used by a leaf elsewhere.
98
98
  def used_tints
99
- names = @graph.nodes_by_id.values.reject(&:container?).filter_map(&:tint).uniq
99
+ names = @graph.nodes_by_id.values.reject { |n| n.container? || n.kind == :text }.filter_map(&:tint).uniq
100
100
  Tints.names.select { |n| names.include?(n) }.map { |n| Tints.for(n) }
101
101
  end
102
102
 
@@ -138,7 +138,11 @@ module Archsight
138
138
 
139
139
  def collect_leaves(nodes)
140
140
  nodes.each do |n|
141
- n.leaf? ? @leaf_nodes << n : collect_leaves(n.children)
141
+ if n.leaf?
142
+ @leaf_nodes << n unless n.kind == :text
143
+ else
144
+ collect_leaves(n.children)
145
+ end
142
146
  end
143
147
  end
144
148
  end
@@ -42,7 +42,7 @@ module Archsight
42
42
  include TableLayout
43
43
 
44
44
  CONTAINER_KEYWORDS = %w[group layer stack boundary].freeze
45
- LEAF_KEYWORDS = %w[component application api database queue actor file].freeze
45
+ LEAF_KEYWORDS = %w[component application api database queue actor file text].freeze
46
46
  BLOCK_KEYWORDS = (CONTAINER_KEYWORDS + LEAF_KEYWORDS).freeze
47
47
  # `layer`/`stack` may be used without an id, purely as a layout hint
48
48
  # (see AST::Block#anonymous) — a `group`/`boundary` always renders a
@@ -103,7 +103,12 @@ module Archsight
103
103
  body.raw(@text_renderer.wrap_link(representer.markup(cx, cy, w, h, id: @ids.id(node), **style), node.link))
104
104
  body.raw(@text_renderer.label_text(representer.label_x(box), representer.label_y(box, @theme), node.label,
105
105
  font_size: representer.label_font_size(@theme), link: node.link,
106
- attrs: @ids.label_attrs(node), extra_class: hover_class(node)))
106
+ attrs: @ids.label_attrs(node), extra_class: label_class(node)))
107
+ end
108
+
109
+ # A `text` has no shape for the broken-link styling to dash, so its label is dimmed and dashed itself.
110
+ def label_class(node)
111
+ [hover_class(node), ("asd-broken-text" if node.kind == :text && node.broken_link)].compact.join(" ").then { |c| c unless c.empty? }
107
112
  end
108
113
  end
109
114
  end
@@ -234,6 +234,8 @@ module Archsight
234
234
  .asd-run-bold { font-weight: bold; }
235
235
  .asd-run-italic { font-style: italic; }
236
236
  .asd-run-underline { text-decoration: underline; }
237
+ .asd-broken-text { opacity: 0.6; text-decoration: underline dashed; }
238
+ .asd-text-hit { fill: transparent; stroke: none; }
237
239
  CSS
238
240
  end
239
241
 
@@ -275,6 +275,19 @@ module Archsight
275
275
  def legend_label = "Module"
276
276
  end
277
277
 
278
+ # Draws no box: a transparent rect only keeps the whole text block
279
+ # hoverable/clickable (a `link`/`resource` wraps it in an `<a>`).
280
+ class TextRepresenter < Base
281
+ def markup(cx, cy, w, h, id: nil, **)
282
+ m = Renderer::Markup.new
283
+ m.element("rect", id: part(id, "body"), x: fmt(cx - (w / 2.0)), y: fmt(cy - (h / 2.0)), width: fmt(w), height: fmt(h), class: "asd-text-hit")
284
+ m.to_s
285
+ end
286
+
287
+ def stretchable? = true
288
+ def legend_label = "Text"
289
+ end
290
+
278
291
  REGISTRY = {} # rubocop:disable Style/MutableConstant -- filled by .register
279
292
 
280
293
  def self.register(name, representer)
@@ -294,6 +307,7 @@ module Archsight
294
307
  register("actor", Actor.new)
295
308
  register("file", FileRepresenter.new)
296
309
  register("module", ModuleRepresenter.new)
310
+ register("text", TextRepresenter.new)
297
311
  end
298
312
  end
299
313
  end
@@ -127,6 +127,44 @@ module Archsight
127
127
  nil
128
128
  end
129
129
 
130
+ # `text` word-wrapped at `width` characters per line (plain
131
+ # characters: markdown markers take no room). Existing `\n` breaks
132
+ # stay. A marked-up run that crosses a break is closed on that line
133
+ # and re-opened on the next, so every line stays valid markdown-lite;
134
+ # a word longer than `width` gets its own line, never split.
135
+ def wrap(text, width)
136
+ wrapped = text.split("\n", -1).flat_map { |line| wrap_line(text, line, width) }.join("\n")
137
+ MarkdownText.like(text, wrapped)
138
+ end
139
+
140
+ def wrap_line(source, line, width)
141
+ chars = markdown_runs(MarkdownText.like(source, line)).flat_map { |content, style| content.each_char.map { |c| [c, style] } }
142
+ words = chars.chunk_while { |a, b| (a[0] == " ") == (b[0] == " ") }.reject { |w| w[0][0] == " " }
143
+ lines = words.each_with_object([]) do |word, acc|
144
+ if acc.any? && acc.last.length + 1 + word.length <= width
145
+ gap_style = acc.last.last[1] == word.first[1] ? word.first[1] : {}
146
+ acc.last.concat([[" ", gap_style]], word)
147
+ else
148
+ acc << word.dup
149
+ end
150
+ end
151
+ lines.empty? ? [line] : lines.map { |l| runs_to_markdown(source, l) }
152
+ end
153
+
154
+ MARKERS = { bold: "**", italic: "*", underline: "__" }.freeze
155
+
156
+ def runs_to_markdown(source, chars)
157
+ out = chars.chunk_while { |a, b| a[1] == b[1] }.map do |group|
158
+ content = group.map(&:first).join
159
+ style = group.first[1]
160
+ if style[:link] then "[#{content}](#{style[:link]})"
161
+ elsif (key = style.keys.first) then "#{MARKERS.fetch(key)}#{content}#{MARKERS.fetch(key)}"
162
+ else content
163
+ end
164
+ end.join
165
+ MarkdownText.like(source, out)
166
+ end
167
+
130
168
  # How much taller a label is than a single line, given the space
131
169
  # between stacked lines -- 0 for a one-line label.
132
170
  def extra_height(text, line_height:)
@@ -116,6 +116,7 @@ class Archsight::Import::Handlers::Repository < Archsight::Import::Handler
116
116
 
117
117
  def update_repository
118
118
  run_git(%w[git fetch --quiet], @path)
119
+ repair_unborn_head if empty_repository?
119
120
  return if empty_repository? # Skip merge for empty repos
120
121
 
121
122
  # FETCH_HEAD may be absent when git fetch brings nothing new (e.g. no
@@ -133,6 +134,30 @@ class Archsight::Import::Handlers::Repository < Archsight::Import::Handler
133
134
  run_git(%w[git reset --hard FETCH_HEAD], @path)
134
135
  end
135
136
 
137
+ # A clone made while the remote was empty keeps an unborn local branch: later fetches only
138
+ # advance the origin/* refs, so HEAD never gets a commit and the repository would be
139
+ # reported as empty. Point the local default branch at the remote one.
140
+ def repair_unborn_head
141
+ remote_ref = remote_default_ref
142
+ return unless remote_ref
143
+
144
+ progress.warn("Local HEAD has no commits but #{remote_ref} does, checking it out")
145
+ run_git(["git", "checkout", "--quiet", "-B", remote_ref.delete_prefix("origin/"), remote_ref], @path)
146
+ end
147
+
148
+ # The remote-tracking ref of the remote's default branch (`origin/main`), or nil when the
149
+ # remote has no commits.
150
+ def remote_default_ref
151
+ Open3.capture3("git", "remote", "set-head", "origin", "--auto", chdir: @path) # origin/HEAD is unset after an empty clone
152
+ out, _, status = Open3.capture3("git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD", chdir: @path)
153
+ return out.strip if status.success? && resolve_ref(out.strip)
154
+
155
+ # the remote did not name a default branch: fall back to the branch the clone started on
156
+ branch, _, status = Open3.capture3("git", "symbolic-ref", "--short", "HEAD", chdir: @path)
157
+ candidate = "origin/#{branch.strip}"
158
+ candidate if status.success? && resolve_ref(candidate)
159
+ end
160
+
136
161
  def empty_repository?
137
162
  # Check if HEAD exists (empty repos have no commits)
138
163
  _, _, status = Open3.capture3("git", "rev-parse", "HEAD", chdir: @path)
@@ -20,7 +20,7 @@ module Archsight
20
20
  # Structure relations between elements of one kind (specialization, composition, aggregation). Each verb is
21
21
  # checked on its own: a chain of one of them must not lead back to where it started. They stay out of the
22
22
  # general check above so that a cycle is reported once.
23
- HIERARCHY_VERBS = %i[specializes composedOf aggregates].freeze
23
+ HIERARCHY_VERBS = %i[specializes composedOf aggregates refinedBy].freeze
24
24
 
25
25
  def initialize(database)
26
26
  @database = database
@@ -192,7 +192,7 @@ module Archsight
192
192
  report_cycles(graph) { |start, path| "#{start.path_ref}: #{start.klass} '#{start.name}' is part of a relation cycle (#{path})" }
193
193
  end
194
194
 
195
- # `specializes`, `composedOf` and `aggregates` (one chain per verb) must not lead back to where they started
195
+ # `specializes`, `composedOf`, `aggregates` and `refinedBy` (one chain per verb) must not lead back to where they started
196
196
  def validate_hierarchy_cycles
197
197
  HIERARCHY_VERBS.each do |hierarchy_verb|
198
198
  graph = relation_graph { |verb| verb == hierarchy_verb }
@@ -306,6 +306,8 @@ module Archsight
306
306
  next
307
307
  end
308
308
 
309
+ validate_summary_lens_key(instance, key)
310
+
309
311
  # Content checks don't depend on enum/type constraints
310
312
  validate_markdown(instance, key, value) if annotation.markdown?
311
313
  validate_diagram(instance, key, value) if annotation.diagram?
@@ -320,6 +322,15 @@ module Archsight
320
322
  end
321
323
  end
322
324
 
325
+ # `summary/lens-<layer or Kind>`: a suffix that names neither would be ignored silently
326
+ def validate_summary_lens_key(instance, key)
327
+ suffix = key[%r{\Asummary/lens-(.+)\z}, 1]
328
+ return unless suffix && instance.klass == "Config"
329
+
330
+ problem = Archsight::Summary::Lens.key_error(suffix)
331
+ @errors << "#{instance.path_ref}: Annotation '#{key}' #{problem}" if problem
332
+ end
333
+
323
334
  # The resource a `Name` / `Kind/Name` annotation points to must exist; a bare `Name` means the same kind
324
335
  def validate_resource_reference(instance, key, value)
325
336
  return if Archsight::Helpers::ResourceResolver.new(@database).find_annotated(value, instance.klass).is_a?(Array)