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
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 902d20b9ffcd9cecfb00ce3ab315eb21e29d6bd886aad9f8a76f24e8243f450c
|
|
4
|
+
data.tar.gz: 9c525ce80c3591e8f7ce4174ee88a9b38b5ddd876e5944c49382bc9b550ff9be
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
-
`
|
|
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 `
|
|
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
|
data/lib/archsight/database.rb
CHANGED
|
@@ -91,7 +91,7 @@ module Archsight
|
|
|
91
91
|
end
|
|
92
92
|
|
|
93
93
|
def instance_by_kind(kind, instance)
|
|
94
|
-
|
|
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 =
|
|
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
|
|
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
|
|
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?
|
|
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:
|
|
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)
|
data/lib/archsight/linter.rb
CHANGED
|
@@ -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 `
|
|
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)
|