archsight 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47bed92ae99f141a261c0dc19a47095a566bd60b9c6a9201dbcd2f6298e1a35f
-  data.tar.gz: 5ff9e1d7d7f02162192a95d86a3a89194b1e450006f4766191da9206f7de55bf
+  metadata.gz: 336946fbac9548285ad368125db862c2f1926d99f2f40c1d40ba4155ebe8ca45
+  data.tar.gz: 63ff3e1a973432f98b5ffb66ac9c518a204c0f87d90ee495615cf60bba293cd3
 SHA512:
-  metadata.gz: dd5b2c1db012e147af1f123c530184b1c4a6eab3b5e7e1e1dbacb658c6e70080b461975d659d68faeca43118989d52d63d134a91fee79767966f06797e352b3c
-  data.tar.gz: f50137692088c6f3a24e799eb7433206e5124c5d83805b94e4d1ea1992537b71528f742538fe6362f4c56c547ffa88cca3d5719bfa153fb09181b893046f4de5
+  metadata.gz: e76456b0f0ed4db22057a4df669953dfcdf7747ed8293ca3092be866e4eea6a4e4c63df6ffeaf6f163da552bf163f409dcb1184a1a493d12e565b0304e527202
+  data.tar.gz: 60a37bef6e039f2bcb20d23fc1010baacdebc65cdded4e8d2f91992583bf60f8245c74175ef26945f3b67e67d6a3421de962c3d8513536376383b55e98bf8afb

data/README.md

@@ -97,11 +97,11 @@ claude mcp add --transport sse ionos-architecture http://localhost:4567/mcp/sse
 - `analyze_resource` - Get detailed resource information and impact analysis
 - `resource_doc` - Get documentation for resource kinds
 
-**Export to Confluence**: `archsight export --to confluence` publishes pages to the Confluence page they link to, with images, diagrams and draw.io, and refuses to overwrite edits made in Confluence unless `--force` ([Wiki pages](docs/pages.md#exporting-to-confluence)).
+**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)).
 
 **Macros** such as `{status:yellow WIP}` and `{emoticon:2705}` work inline in pages ([Wiki pages](docs/pages.md#macros)).
 
-**Views and analyses** can be embedded in pages with `![[View/Name]]` / `![[Analysis/Name]]` ([Wiki pages](docs/pages.md#embedding-views-and-analyses)).
+**Views and analyses** can be embedded in pages with `![[View/Name]]` / `![[Analysis/Name]]` ([Wiki pages](docs/pages.md#embedding-views-and-analyses)); a view can also be written in place with a ```` ```view ```` block ([inline views](docs/pages.md#inline-views)), and the business requirements of a selection of resources shown with a ```` ```requirements ```` block ([requirements](docs/pages.md#business-requirements-of-a-selection-of-resources)).
 
 **Images and draw.io diagrams** are plain files in the resources directory and are embedded in markdown with relative
 paths (`![](../img/a.png)`, `![](../../fop/flow.drawio)`); only files of image, draw.io and `.asd` diagram types inside the resources

data/docs/computed_annotations.md

@@ -40,9 +40,13 @@ Computed annotations support all the same options as regular annotations:
 | `enum` | Array | nil | Allowed values |
 | `sidebar` | Boolean | false | Show in sidebar |
 | `type` | Class | nil | Type for value coercion (Integer, Float, String) |
-| `list` | Boolean | false | Whether values are lists |
+| `summary` | Boolean | false | Return the value with every search hit of this kind (at most 3 per kind) |
 | `&block` | Block | required | The computation logic |
 
+`summary: true` (also available on regular `annotation` definitions) marks the value as a summary attribute: the
+search API returns it with every hit of the kind (`highlights`) and the result page shows it next to the name.
+A kind can have at most 3 summary annotations; a fourth raises an `ArgumentError` when the kind is defined.
+
 ### Value Handling
 
 - **Nil values**: Not stored (annotation key won't exist)
@@ -89,8 +93,7 @@ end
 computed_annotation 'computed/languages',
                     title: 'Languages',
                     description: 'All programming languages used',
-                    filter: :list,
-                    list: true do
+                    filter: :list do
   collect(outgoing_transitive(:TechnologyArtifact), 'scc/languages')
 end
 ```
@@ -299,8 +302,7 @@ class ApplicationComponent < Base
   computed_annotation 'computed/languages',
                       title: 'Languages',
                       description: 'All programming languages used across related artifacts',
-                      filter: :list,
-                      list: true do
+                      filter: :list do
     collect(outgoing_transitive(:TechnologyArtifact), 'scc/languages')
   end
 

data/docs/licenses.md

@@ -236,8 +236,7 @@ end
 # Collect all unique dependency licenses across the portfolio
 computed_annotation 'computed/license_types',
                     title: 'All License Types',
-                    filter: :list,
-                    list: true do
+                    filter: :list do
   collect(outgoing_transitive(:TechnologyArtifact), 'license/dependencies/licenses')
 end
 

data/docs/modeling.md

@@ -144,9 +144,13 @@ BusinessRequirement
        ↑ satisfies
 ComplianceEvidence
        ↑ evidencedBy
-ApplicationService
+ApplicationService (or TechnologyService / TechnologySystemSoftware)
 ```
 
+Technology elements such as a Kubernetes cluster runtime can plan, realize and be evidenced
+for requirements directly, so the requirement does not have to be attached to a placeholder
+ApplicationService. Applications deployed on them point to the TechnologyService with `servedBy`.
+
 ## Annotation Best Practices
 
 Use annotations to capture metadata:

data/docs/pages.md

@@ -146,6 +146,53 @@ link to the resource. Other kinds are not embeddable; an unknown name, another k
 a sentence (instead of on its own line) is shown as a marker or a link, and `archsight lint` reports embeds that do not
 resolve. Code blocks and inline code are left alone.
 
+### Inline views
+
+A view that only this page needs does not have to be a resource of its own: a fenced ```` ```view ```` block holds the
+View as it would be written in a YAML file and is shown like an embedded view:
+
+````markdown
+```view
+apiVersion: architecture/v1alpha1
+kind: View
+metadata:
+  name: Services without backup      # the title above the list, optional
+  annotations:
+    view/query: 'ApplicationService: backup/mode == "none"'
+    view/fields: name, @owner
+    view/sort: -name
+    view/type: list:name
+```
+````
+
+Only `view/query` is required; `kind`, if given, must be `View` and `apiVersion` can be left out. Other annotations are
+ignored, so a View's YAML can be pasted in unchanged (to turn the block into a real view later, or the other way round).
+It loads and runs in the browser like any embed; the server only writes `<div class="view-embed" data-title data-query
+data-fields data-sort data-type>` around the source. A block that is not a valid View (broken YAML, missing or
+unparsable query, unknown `view/*` key or type) shows an error box with the source, and `archsight lint` reports it.
+
+### Business requirements of a selection of resources
+
+The "Business Requirements" table of an instance page (the requirements it `realizes`, `partiallyRealizes` or `plans`,
+with status, priority and story) can be put on a page for any selection of resources with a ```` ```requirements ```` block:
+
+````markdown
+```requirements
+title: Requirements of the backup services     # optional, default "Business Requirements"
+of: 'ApplicationService: name =~ "Backup"'     # required: query selecting the resources
+priority: must                                 # optional: must, should, may (one value or a list)
+status: [implemented, partial]                 # optional: implemented, partial, planned
+```
+````
+
+The table has one row per requirement of all selected resources. Its status is the best one any of them gives it
+(`realizes` = implemented, then `partially`, then `plans` = planned), and a "Realized by" column names the resources with their own
+status (left out when only one resource is selected). Rows are sorted by priority, then name; `priority` and `status` filter the rows.
+Like views, the block is only a placeholder on the server (`<div class="requirements-embed" data-title data-of data-priority
+data-status>` around the source): the frontend loads the rows from `GET /api/v1/requirements?of=&priority=&status=`, so rendering a page
+never runs the query. A block with a missing or unparsable `of`, an unknown key, priority or status shows an error box with the
+source, and `archsight lint` reports it.
+
 ## Macros
 
 Inline macros are written `{name:arguments}` and named like the macros of Confluence. They work inside a sentence, a
@@ -202,6 +249,8 @@ If several pages qualify, a page named `home` wins over one that is only titled
 - Tables, code blocks and other GitHub-flavoured markdown.
 - Diagrams: fenced ```` ```asd ```` blocks (see [Diagrams](/doc/diagram)) replace draw.io drawings.
 - Links: `[[Page title]]`, `[[page-name]]`, `[[Name|label]]` and `[[Kind/Name]]` link to pages and resources.
+  A link without a label shows the title of a page and the name of a resource (`[[ApplicationComponent/KubeVirt]]` shows "KubeVirt"); hovering it shows the
+  kind and the first line of the description (the status of a page). The export to Confluence writes the same texts, without the hover.
 
 ## Editing
 
@@ -224,6 +273,7 @@ or `.../display/KEY/Title`). Without `PAGE` every page that has a `confluence:`
 
 ```bash
 archsight export --to confluence -r resources                 # all linked pages
+archsight export --to confluence -r resources --tag public    # only pages tagged `public` (repeat or list: any match)
 archsight export --to confluence handbook-home --dry-run      # show what would happen
 archsight export --to confluence handbook-home --force        # overwrite changes made in Confluence
 ```
@@ -257,10 +307,17 @@ confluence:
 With `drawio` off nothing draw.io-specific is written, so any Confluence shows the diagrams. Rendering a `.drawio` needs the
 draw.io desktop CLI (`drawio`, or `ARCHSIGHT_DRAWIO_CLI`) on the machine that exports; the preview of an SVG needs
 `rsvg-convert` or that CLI. A diagram that cannot be rendered fails the page instead of leaving a blank diagram. Attachments an
-earlier export added and the page no longer uses are removed; attachments added by others are left alone. `[[links]]` to pages that have a Confluence link
-become links to them, other links are plain text; embedded views and analyses (`![[View/..]]`) become a note, their content
-is live and exists in Archsight only. A page with a broken image or a diagram that does not render is not exported and
-reported as failed. The Confluence title is kept.
+earlier export added and the page no longer uses are removed; attachments added by others are left alone. `[[links]]` and markdown links to pages (`[text](/pages/name)`) that have a Confluence link
+become links to them, other links to Archsight (pages without a Confluence link, resources, searches) are plain text. A page with a broken image, a diagram that does not render or an invalid
+```` ```view ````/```` ```requirements ```` block is not exported and reported as failed. The Confluence title is kept. The exported page uses the Confluence layout: the page properties top left, the note that the page is generated by Archsight top right, and the content below in a section of its own.
+
+**Views and requirements** are live in Archsight, so Confluence gets a regular table with the data of the moment of the export (every
+export writes the current data; a page whose tables did not change is `unchanged`): `![[View/Name]]` on a line of its own, a
+```` ```view ```` block and a ```` ```requirements ```` block each become a table with the title and item count above it, the columns of
+the view (Name, Kind unless `list:name`, the `view/fields`, sorted by `view/sort`; times are the stored values, not "3 days ago") or
+the requirements table (status and priority as status lozenges: implemented green, partial yellow, planned blue; `must` red,
+`should` yellow, `may` grey), and names of pages that have a Confluence link as links. At most 200 rows are exported, a note says how many
+were left out. A `![[View/..]]` that is not alone on its line or names no view stays a note, and so does `![[Analysis/..]]` (it runs a script).
 
 **Links in diagrams**: a node with `resource "Some Page"` links to the Confluence page of that wiki page (the page's own
 `confluence:` link) instead of its Archsight address, which means nothing in Confluence. A reference to a page without a
@@ -276,8 +333,8 @@ changed it and when, and the command exits with 1. `--force` overwrites it anywa
 were replaced. A page whose generated content is unchanged is left alone (no new version).
 
 **Locking and revisions**: unless `--no-lock`, editing is restricted to the exporting user (if the server does not allow it,
-the export still succeeds and says "NOT locked"). Every exported version has the message "Generated by Archsight <version> from
-<file>, do not edit in Confluence", and the page starts with a note that it is generated and that the source file is the place
+the export still succeeds and says "NOT locked"). Every exported version has the message "Generated by Archsight `<version>` from
+`<file>`, do not edit in Confluence", and the page starts with a note that it is generated and that the source file is the place
 to edit.
 
 ## Pages and AI assistants (MCP)

data/docs/search.md

@@ -263,3 +263,20 @@ Using `in` to simplify OR conditions:
 
     # Combined with other conditions:
     activity/status == "active" & repository/artifacts in ("container", "chart")
+
+## Search results
+
+The result page lists the hits with a count per kind. Click a kind to narrow the list; the query stays the same.
+Every hit also shows its **summary attributes**: up to three annotations per kind (normal or computed) that
+the kind definition marks with `summary: true`, for example the activity status of a repository or the priority
+of a requirement. Clicking a tag value searches for that value.
+
+The same data is available from the API: `GET /api/v1/search?q=...` returns `by_kind` (hits per kind, for all
+hits of the query) and, for each hit, `highlights`:
+
+    "highlights": [
+      { "key": "activity/status", "title": "Activity Status", "value": "active", "format": "tag_word", "type": null }
+    ]
+
+Add `kind=TechnologyArtifact` to narrow the hits to one kind (`total` and paging follow, `by_kind` still counts
+all hits).

data/lib/archsight/annotations/annotation.rb

@@ -5,7 +5,7 @@ require_relative "person"
 
 # Annotation represents a single annotation definition with its schema and behavior
 class Archsight::Annotations::Annotation
-  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :list, :editor
+  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :summary, :editor
 
   def initialize(key, options = {})
     @key = key
@@ -15,7 +15,7 @@ class Archsight::Annotations::Annotation
     @enum = options[:enum]
     @validator = options[:validator]
     @sidebar = options.fetch(:sidebar, true)
-    @list = options.fetch(:list, false)
+    @summary = options.fetch(:summary, false)
     @editor = options.fetch(:editor, true)
     @type = options[:type]
 
@@ -51,8 +51,9 @@ class Archsight::Annotations::Annotation
     @filter == :list
   end
 
-  def list_display?
-    @list == true
+  # Summary annotations are returned with every search hit (at most MAX_SUMMARY per kind)
+  def summary?
+    @summary == true
   end
 
   def has_validation?

data/lib/archsight/annotations/computed.rb

@@ -28,7 +28,7 @@ class Archsight::Annotations::ComputedEvaluator
     @instance = instance
     @database = database
     @manager = manager
-    @resolver = Archsight::Annotations::ComputedRelationResolver.new(instance, database)
+    @resolver = Archsight::Annotations::ComputedRelationResolver.new(instance, database, manager.traversal_cache)
   end
 
   # Access a regular annotation value from the current instance
@@ -170,8 +170,12 @@ end
 # ComputedManager orchestrates the computation of all computed annotations.
 # It handles lazy evaluation, caching, and cycle detection.
 class Archsight::Annotations::ComputedManager
+  # Shared by all resolvers of this run, see ComputedRelationResolver::TraversalCache
+  attr_reader :traversal_cache
+
   def initialize(database)
     @database = database
+    @traversal_cache = Archsight::Annotations::ComputedRelationResolver::TraversalCache.new(database)
     @computed_cache = {}  # { [instance_object_id, key] => value }
     @computing = Set.new  # For cycle detection
   end

data/lib/archsight/annotations/relation_resolver.rb

@@ -13,10 +13,88 @@
 class Archsight::Annotations::ComputedRelationResolver
   MAX_DEPTH = 10
 
-  def initialize(instance, database)
+  # TraversalCache holds what can be shared between all resolvers of one computation run: the unfiltered
+  # transitive neighbourhood of an instance (relations are fixed once the database is verified), parsed filter
+  # queries, one query evaluator and the short kind names. Filter results are never cached because they may
+  # depend on computed annotations that are set while the run progresses.
+  class TraversalCache
+    def initialize(database)
+      @database = database
+      @reach = {}
+      @queries = {}
+      @kind_names = {}.compare_by_identity
+    end
+
+    # Short kind name of a resource class ("ApplicationComponent")
+    def kind_name(klass)
+      @kind_names[klass] ||= klass.name.split("::").last
+    end
+
+    # Parsed query for a selector string
+    def query(selector)
+      @queries[selector] ||= begin
+        require_relative "../query/lexer"
+        require_relative "../query/parser"
+        Archsight::Query::Parser.new(Archsight::Query::Lexer.new(selector).tokenize).parse
+      end
+    end
+
+    def evaluator
+      @evaluator ||= begin
+        require_relative "../query/evaluator"
+        Archsight::Query::Evaluator.new(@database)
+      end
+    end
+
+    # All instances reachable from `start` within max_depth hops (direction :outgoing or :incoming),
+    # each once, in breadth-first order. `start` itself is included when a cycle leads back to it.
+    def reachable(start, direction, max_depth)
+      by_instance = (@reach[[direction, max_depth]] ||= {}.compare_by_identity)
+      by_instance[start] ||= walk(start, direction, max_depth)
+    end
+
+    private
+
+    def walk(start, direction, max_depth)
+      results = []
+      listed = {}.compare_by_identity
+      expanded = { start => true }.compare_by_identity
+      frontier = [start]
+      depth = 0
+      while depth < max_depth && !frontier.empty?
+        following = []
+        frontier.each do |node|
+          neighbours(node, direction).each do |other|
+            unless listed.key?(other)
+              listed[other] = true
+              results << other
+            end
+            next if expanded.key?(other)
+
+            expanded[other] = true
+            following << other
+          end
+        end
+        frontier = following
+        depth += 1
+      end
+      results
+    end
+
+    def neighbours(inst, direction)
+      if direction == :outgoing
+        inst.class.relations.flat_map { |verb, kind_name, _klass_name| inst.relations(verb, kind_name) }
+      else
+        (inst.references || []).filter_map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }
+      end
+    end
+  end
+
+  # @param cache [TraversalCache, nil] shared per computation run; a private one is created when omitted
+  def initialize(instance, database, cache = nil)
     @instance = instance
     @database = database
-    @query_cache = {}
+    @cache = cache || TraversalCache.new(database)
   end
 
   # Get direct outgoing relations (-> Kind)
@@ -41,11 +119,7 @@ class Archsight::Annotations::ComputedRelationResolver
   # @param max_depth [Integer] Maximum traversal depth (default 10)
   # @return [Array] Array of transitively related instances
   def outgoing_transitive(filter = nil, max_depth: MAX_DEPTH)
-    visited = Set.new
-    results = []
-
-    collect_transitive_outgoing(@instance, filter, visited, 0, max_depth, results)
-    results.uniq
+    filtered(@cache.reachable(@instance, :outgoing, max_depth), filter)
   end
 
   # Get direct incoming relations (<- Kind)
@@ -70,15 +144,23 @@ class Archsight::Annotations::ComputedRelationResolver
   # @param max_depth [Integer] Maximum traversal depth (default 10)
   # @return [Array] Array of instances that transitively reference this one
   def incoming_transitive(filter = nil, max_depth: MAX_DEPTH)
-    visited = Set.new
-    results = []
-
-    collect_transitive_incoming(@instance, filter, visited, 0, max_depth, results)
-    results.uniq
+    filtered(@cache.reachable(@instance, :incoming, max_depth), filter)
   end
 
   private
 
+  def filtered(instances, filter)
+    return instances.dup if filter.nil?
+
+    if filter.is_a?(Symbol)
+      kind = filter.to_s
+      instances.select { |inst| @cache.kind_name(inst.class) == kind }
+    else
+      query_node = @cache.query(filter)
+      instances.select { |inst| @cache.evaluator.matches?(query_node, inst) }
+    end
+  end
+
   # Check if an instance matches the given filter
   # @param instance [Object] The instance to check
   # @param filter [Symbol, String, nil] Kind filter or query selector
@@ -86,75 +168,10 @@ class Archsight::Annotations::ComputedRelationResolver
   def matches_filter?(instance, filter)
     return true if filter.nil?
 
-    instance_kind = instance.class.name.split("::").last
-
     if filter.is_a?(Symbol)
-      # Simple kind check
-      instance_kind == filter.to_s
+      @cache.kind_name(instance.class) == filter.to_s
     else
-      # Query selector - parse and evaluate
-      query_node = parse_query(filter)
-      evaluator.matches?(query_node, instance)
-    end
-  end
-
-  # Parse a query string (with caching)
-  def parse_query(query_string)
-    @query_cache[query_string] ||= begin
-      require_relative "../query/lexer"
-      require_relative "../query/parser"
-      tokens = Archsight::Query::Lexer.new(query_string).tokenize
-      Archsight::Query::Parser.new(tokens).parse
-    end
-  end
-
-  # Get or create the query evaluator
-  def evaluator
-    @evaluator ||= begin
-      require_relative "../query/evaluator"
-      Archsight::Query::Evaluator.new(@database)
-    end
-  end
-
-  # Recursively collect transitive outgoing relations
-  def collect_transitive_outgoing(inst, filter, visited, depth, max_depth, results)
-    return if depth >= max_depth
-
-    key = "#{inst.class}/#{inst.name}"
-    return if visited.include?(key)
-
-    visited.add(key)
-
-    inst.class.relations.each do |verb, kind_name, _klass_name|
-      rels = inst.relations(verb, kind_name)
-      rels.each do |rel|
-        # Add to results if matches filter (or no filter)
-        results << rel if matches_filter?(rel, filter)
-
-        # Continue traversal (regardless of whether this matched)
-        collect_transitive_outgoing(rel, filter, visited.dup, depth + 1, max_depth, results)
-      end
-    end
-  end
-
-  # Recursively collect transitive incoming relations
-  def collect_transitive_incoming(inst, filter, visited, depth, max_depth, results)
-    return if depth >= max_depth
-
-    key = "#{inst.class}/#{inst.name}"
-    return if visited.include?(key)
-
-    visited.add(key)
-
-    refs = inst.references || []
-    # Extract instances from reference hashes
-    instances = refs.map { |ref| ref.is_a?(Hash) ? ref[:instance] : ref }.compact
-    instances.each do |ref|
-      # Add to results if matches filter (or no filter)
-      results << ref if matches_filter?(ref, filter)
-
-      # Continue traversal (regardless of whether this matched)
-      collect_transitive_incoming(ref, filter, visited.dup, depth + 1, max_depth, results)
+      @cache.evaluator.matches?(@cache.query(filter), instance)
     end
   end
 end

data/lib/archsight/cli.rb

@@ -282,7 +282,7 @@ module Archsight
     desc "export [PAGE...]", "Export wiki pages to another system"
     long_desc <<~DESC
       Publishes wiki pages to the system named by --to. With no PAGE, every page that links to a target
-      page (for confluence: `confluence: <page URL>` in its frontmatter) is exported.
+      page (for confluence: `confluence: <page URL>` in its frontmatter) is exported. --tag TAG limits the export to pages carrying one of the given tags.
 
       confluence: a page is only overwritten when Confluence still holds what the last export wrote. Pages
       never exported before, or edited in Confluence since, are reported as blocked and not exported until
@@ -295,6 +295,7 @@ module Archsight
     option :force, type: :boolean, default: false, desc: "Overwrite pages that were edited in the target since the last export"
     option :lock, type: :boolean, default: true, desc: "Restrict editing of exported pages to the exporting user (--no-lock to skip)"
     option :dry_run, type: :boolean, default: false, desc: "Show what would be exported without writing anything"
+    option :tag, type: :array, default: [], desc: "Only export pages with at least one of these tags (repeatable, case-insensitive)"
     option :config, type: :string, desc: "Configuration file (default: ARCHSIGHT_CONFIG or ~/.config/archsight/archsight.yaml)"
     option :drawio, type: :boolean, desc: "The target has the draw.io app: export diagrams as draw.io macros, else as images (default: `confluence.drawio` of the configuration)"
     def export(*names)
@@ -317,7 +318,7 @@ module Archsight
       end
       exporter = Archsight::Export.exporter_for(options[:to]).new(
         database: db, resources_dir: Archsight.resources_dir, force: options[:force], lock: options[:lock],
-        dry_run: options[:dry_run], settings: settings, drawio: options[:drawio]
+        dry_run: options[:dry_run], settings: settings, drawio: options[:drawio], tags: options[:tag]
       )
       results = exporter.run(names)
       print_export_results(results)

data/lib/archsight/database.rb

@@ -119,7 +119,8 @@ module Archsight
       kind = obj["kind"] || raise("kind not defined")
       klass = Archsight::Resources[kind] || raise("#{kind} is not a valid kind")
       inst = klass.new(obj, @current_ref)
-      inst.name || raise("metadata name of #{kind} not present")
+      raise("metadata name of #{kind} not present") if inst.name.to_s.strip.empty?
+
       inst
     end
 

data/lib/archsight/documentation.rb

@@ -142,7 +142,8 @@ module Archsight
         rows = ["| Annotation | Description | Values |", "|------------|-------------|--------|"]
         annotations.each do |a|
           values = format_values(a)
-          rows << "| `#{a.key}` | #{a.description || "-"} | #{values} |"
+          description = a.summary? ? "#{a.description || "-"} _(summary: shown with search hits)_" : (a.description || "-")
+          rows << "| `#{a.key}` | #{description} | #{values} |"
         end
         rows.join("\n")
       end

data/lib/archsight/export/confluence/exporter.rb

@@ -31,8 +31,9 @@ module Archsight
         # @param database [Archsight::Database]
         # @param settings [Credentials::Settings, nil] token and draw.io support; default: Credentials.load
         # @param drawio [Boolean, nil] overrides the settings' draw.io flag
+        # @param tags [Array<String>] only export pages that have at least one of these `page/tags` (case-insensitive)
         # @param client_factory [#call, nil] `(base_url, token) -> Client`, for tests
-        def initialize(database:, resources_dir:, force: false, lock: true, dry_run: false, settings: nil, drawio: nil, client_factory: nil)
+        def initialize(database:, resources_dir:, force: false, lock: true, dry_run: false, settings: nil, drawio: nil, tags: [], client_factory: nil)
           @database = database
           @resources_dir = resources_dir
           @force = force
@@ -40,6 +41,7 @@ module Archsight
           @dry_run = dry_run
           @settings = settings
           @drawio = drawio
+          @tags = Array(tags).map { |t| t.to_s.strip.downcase }.reject(&:empty?)
           @client_factory = client_factory || ->(base, secret) { Client.new(base: base, token: secret) }
           @clients = {}
         end
@@ -55,17 +57,24 @@ module Archsight
         # @return [Array<Array(Page|String, Result|nil)>]
         def select(names)
           all = @database.instances_by_kind("Page")
-          return all.values.select { |p| link(p) }.sort_by(&:name).map { |p| [p, nil] } if names.empty?
+          return all.values.select { |p| link(p) && tagged?(p) }.sort_by(&:name).map { |p| [p, nil] } if names.empty?
 
           names.map do |name|
             page = all[name]
             if page.nil? then [name, Result.new(page: name, status: :failed, message: "no such page")]
             elsif link(page).nil? then [page, Result.new(page: name, status: :skipped, message: "no `confluence:` link in the frontmatter")]
+            elsif !tagged?(page) then [page, Result.new(page: name, status: :skipped, message: "has none of the tags #{@tags.join(", ")}")]
             else [page, nil]
             end
           end
         end
 
+        def tagged?(page)
+          return true if @tags.empty?
+
+          page.annotations["page/tags"].to_s.split(",").map { |t| t.strip.downcase }.intersect?(@tags)
+        end
+
         def link(page)
           value = page.annotations["page/confluence"].to_s.strip
           value.empty? ? nil : value