archsight 0.3.0 → 0.3.2

data/lib/archsight/resources/business_actor.rb

@@ -36,7 +36,8 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
              sidebar: false,
              filter: :word,
              format: :tag_word,
-             type: Archsight::Annotations::EmailRecipient
+             type: Archsight::Annotations::EmailRecipient,
+             summary: true
 
   annotation "team/members",
              description: 'Team members (format: "Name <email>" or "email")',
@@ -108,7 +109,7 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
   computed_annotation "team/size",
                       title: "Team Size",
                       description: "Number of team members (including sub-teams)",
-                      list: true,
+                      summary: true,
                       type: Integer do
     # Count members from this team
     members = @instance.annotations["team/members"]
@@ -147,7 +148,8 @@ class Archsight::Resources::BusinessActor < Archsight::Resources::Base
   computed_annotation "repository/artifacts/total",
                       title: "Maintained Repositories",
                       description: "Number of git repositories maintained by this team",
-                      type: Integer do
+                      type: Integer,
+                      summary: true do
     count(incoming_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 

data/lib/archsight/resources/business_control.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# BusinessControl represents a control that guides a business process
+class Archsight::Resources::BusinessControl < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a control: a safeguard or decision step with an owner that guides how a business process is carried out.
+
+    ## ArchiMate / TOGAF Definition
+
+    **Layer:** Business
+    **Aspect:** Behavior (guidance)
+
+    ArchiMate has no control element. TOGAF's content metamodel has one: a decision-making step with
+    accountability and authority, applied to a process or function. A control is therefore modelled as
+    a business-layer kind that a `BusinessProcess` is guided by (`guidedBy`).
+
+    ## Usage
+
+    Use BusinessControl to represent:
+
+    - Security and compliance controls (access review, network documentation, backup verification)
+    - Operational checks that a process must pass (change approval, four-eyes principle)
+    - Controls of a standard or framework (BSI C5, ISO 27001, SOC 2), linked to the requirements they satisfy
+
+    ## How it connects
+
+    - A `BusinessProcess` is `guidedBy` the control
+    - The control is `ownedBy` the actor that is accountable for it and `executedBy` the actors that carry it out
+    - The control `satisfies` requirements and is `evidencedBy` compliance evidence
+
+    A control addresses requirements from the **process side**. Whether an application implements a requirement is
+    stated on the application (`realizes`, `plans`, `evidencedBy`), not on the control. Link evidence to a control
+    only for the records the control itself produces (reviews, diagrams, change history, audit logs), and set the
+    `evidence/type` of that evidence to `process`, `documentation` or `audit-log`.
+
+    Put the best practices and the evidence requirements of a control in the description.
+  MD
+
+  icon "shield-search"
+  layer "business"
+
+  annotation "control/id",
+             description: "Identifier of the control in its catalogue (e.g. COS-07)",
+             title: "Control ID",
+             summary: true
+
+  annotation "control/status",
+             description: "Implementation status of the control",
+             enum: %w[implemented partial planned not-implemented],
+             filter: :word,
+             summary: true
+
+  annotation "control/frequency",
+             description: "How often the control is carried out",
+             enum: %w[continuous event-based daily weekly monthly quarterly semi-annually annually],
+             filter: :word,
+             summary: true
+
+  annotation "control/objective",
+             description: "What the control achieves, in one short paragraph",
+             title: "Objective",
+             format: :markdown
+
+  annotation "control/last-review",
+             description: "When the control was last reviewed (ISO 8601 date or time)",
+             title: "Last review",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  annotation "control/next-review",
+             description: "When the control is due for review (ISO 8601 date or time)",
+             title: "Next review",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :executedBy, :businessActors, :BusinessActor
+  relation :satisfies, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
+end

data/lib/archsight/resources/business_process.rb

@@ -30,8 +30,9 @@ class Archsight::Resources::BusinessProcess < Archsight::Resources::Base
   icon "kanban-board"
   layer "business"
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :applicationServices, :ApplicationService
   relation :performedBy, :businessActors, :BusinessActor
+  relation :guidedBy, :businessControls, :BusinessControl
 end

data/lib/archsight/resources/business_product.rb

@@ -33,7 +33,8 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   computed_annotation "repository/artifacts/total",
                       title: "Total Git Repositories",
                       description: "Number of related git repositories",
-                      type: Integer do
+                      type: Integer,
+                      summary: true do
     count(outgoing_transitive('TechnologyArtifact: artifact/type == "repo"'))
   end
 
@@ -110,7 +111,7 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   computed_annotation "activity/createdAt",
                       title: "Created",
                       description: "Earliest repository creation date across all related application services",
-                      list: true,
+                      summary: true,
                       type: Time do
     services = outgoing_transitive(:ApplicationService)
     next nil if services.empty?
@@ -170,7 +171,7 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   computed_annotation "activity/contributors/6m",
                       title: "Contributors (6 months)",
                       description: "Sum of unique contributors in the last 6 months across related services",
-                      list: true,
+                      summary: true,
                       type: Integer do
     services = outgoing_transitive(:ApplicationService)
     next nil if services.empty?
@@ -197,8 +198,8 @@ class Archsight::Resources::BusinessProduct < Archsight::Resources::Base
   end
 
   relation :realizes, :strategyCapabilities, :StrategyCapability
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :applicationServices, :ApplicationService
   relation :exposes, :applicationInterfaces, :ApplicationInterface

data/lib/archsight/resources/compliance_evidence.rb

@@ -25,6 +25,13 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
     - Test results and reports
     - Configuration documentation
     - Process documentation
+
+    ## Evidence of what
+
+    - **Of an application:** linked with `evidencedBy` from a service, component or technology element; it says how
+      that resource meets the requirement it `satisfies`
+    - **Of a control:** linked with `evidencedBy` from a `BusinessControl`; the records the control produces
+      (reviews, diagrams, change history, audit logs). Use `evidence/type` `process`, `documentation` or `audit-log`
   MD
 
   icon "shield-check"
@@ -32,11 +39,41 @@ class Archsight::Resources::ComplianceEvidence < Archsight::Resources::Base
 
   annotation "evidence/type",
              description: "Type of evidence",
-             enum: %w[documentation process configuration audit-log technical-control]
+             enum: %w[documentation process configuration audit-log technical-control],
+             summary: true
 
   annotation "evidence/status",
              description: "Current status of evidence",
-             enum: %w[implemented partial not-implemented]
+             enum: %w[implemented partial not-implemented],
+             summary: true
+
+  # The structured answer to "how does the evidenced resource meet the requirement": one markdown field per
+  # question. `architecture/description` stays a short summary; the fields hold the detail.
+  annotation "evidence/mechanism",
+             description: "How the requirement is implemented: the concrete mechanism and where it lives " \
+                          "(code, chart, configuration), as a short markdown list",
+             format: :markdown
+
+  annotation "evidence/coverage",
+             description: "What the mechanism covers and what it does not (data, flows, tenants, environments)",
+             format: :markdown
+
+  annotation "evidence/operatorView",
+             description: "Whether the mechanism holds against operators (admins, platform staff) or only against " \
+                          "other tenants; names the privileged paths",
+             format: :markdown
+
+  annotation "evidence/verification",
+             description: "How effectiveness is verified: tests, audits, documents; says so when there are none",
+             format: :markdown
+
+  annotation "evidence/gaps",
+             description: "Remaining gaps and open questions, the most important first",
+             format: :markdown
+
+  annotation "evidence/sources",
+             description: "Where the statements come from: repositories and files, wiki pages, tickets",
+             format: :markdown
 
-  relation :satisfies, :businessRequirements, :BusinessRequirement
+  relation :satisfies, :motivationRequirements, :MotivationRequirement
 end

data/lib/archsight/resources/data_object.rb

@@ -38,12 +38,13 @@ class Archsight::Resources::DataObject < Archsight::Resources::Base
   annotation "data/visibility",
              description: "API visibility level",
              title: "Visibility",
-             enum: %w[public private internal]
+             enum: %w[public private internal],
+             summary: true
 
   annotation "generated/variants",
              description: "OpenAPI schema variants compacted into this DataObject",
              title: "Schema Variants",
              sidebar: false
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
 end

data/lib/archsight/resources/import.rb

@@ -38,7 +38,9 @@ class Archsight::Resources::Import < Archsight::Resources::Base
   # Handler selection
   annotation "import/handler",
              description: "Handler class name to execute this import",
-             title: "Handler", enum: %w[
+             title: "Handler",
+             summary: true,
+             enum: %w[
                gitlab github repository
                rest-api rest-api-index
                jira-discover jira-metrics
@@ -57,7 +59,8 @@ class Archsight::Resources::Import < Archsight::Resources::Base
   annotation "import/enabled",
              description: "Whether this import is enabled",
              title: "Enabled",
-             enum: %w[true false]
+             enum: %w[true false],
+             summary: true
 
   annotation "import/priority",
              description: "Execution priority (lower runs first among ready imports)",

data/lib/archsight/resources/{business_constraint.rb → motivation_constraint.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# BusinessConstraint represents restrictions or limitations on architecture
-class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
+# MotivationConstraint represents restrictions or limitations on architecture
+class Archsight::Resources::MotivationConstraint < Archsight::Resources::Base
   include_annotations :git, :architecture
 
   description <<~MD
@@ -18,7 +18,7 @@ class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
 
     ## Usage
 
-    Use BusinessConstraint to represent:
+    Use MotivationConstraint to represent:
 
     - Regulatory requirements (GDPR, SOX, PCI-DSS)
     - Security policies
@@ -28,5 +28,5 @@ class Archsight::Resources::BusinessConstraint < Archsight::Resources::Base
   MD
 
   icon "prohibition"
-  layer "business"
+  layer "motivation"
 end

data/lib/archsight/resources/motivation_goal.rb

@@ -33,5 +33,5 @@ class Archsight::Resources::MotivationGoal < Archsight::Resources::Base
 
   relation :realizes, :outcomes, :MotivationOutcome
   relation :refinedBy, :goals, :MotivationGoal
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationRequirements, :MotivationRequirement
 end

data/lib/archsight/resources/{business_requirement.rb → motivation_requirement.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-# BusinessRequirement represents functional or non-functional requirements
-class Archsight::Resources::BusinessRequirement < Archsight::Resources::Base
+# MotivationRequirement represents functional or non-functional requirements
+class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
   include_annotations :git, :architecture
 
   description <<~MD
@@ -18,34 +18,45 @@ class Archsight::Resources::BusinessRequirement < Archsight::Resources::Base
 
     ## Usage
 
-    Use BusinessRequirement to represent:
+    Use MotivationRequirement to represent:
 
     - Compliance requirements (C5, ISO 27001)
     - Security requirements
     - Performance requirements
     - Functional specifications
     - Legal obligations (GDPR, NIS2)
+
+    ## Who addresses it
+
+    A requirement is where the process side and the application side meet:
+
+    - **Process side:** a `BusinessControl` `satisfies` the requirement; a process is `guidedBy` the control
+    - **Application side:** applications `realize` or `plan` the requirement and are `evidencedBy` `ComplianceEvidence`,
+      which `satisfies` it
+
+    Both show as incoming relations on the requirement's page.
   MD
 
   icon "task-list"
-  layer "business"
+  layer "motivation"
 
   annotation "requirement/type",
              description: "Type of requirement (business or legal)",
-             enum: %w[business legal compliance functional non-functional]
+             enum: %w[business legal compliance functional non-functional],
+             summary: true
 
   annotation "requirement/reference",
              description: "Regulatory or standard reference (comma-separated for multiple)",
              filter: :list,
              enum: %w[c5-2020 itgs-2023 gdpr-2018 nis1 nis2 iso27001 sox pci-dss hipaa eu-data-act-2025 ens
-                      iso27001-2022],
-             list: true
+                      iso27001-2022 vsa-2023 con-11-1],
+             summary: true
 
   annotation "requirement/priority",
              description: "Implementation priority (must, should, may)",
              filter: :word,
              enum: %w[must should may],
-             list: true
+             summary: true
 
   annotation "requirement/story",
              description: "One-line business value statement explaining what the requirement enables",

data/lib/archsight/resources/motivation_stakeholder.rb

@@ -32,7 +32,7 @@ class Archsight::Resources::MotivationStakeholder < Archsight::Resources::Base
   layer "motivation"
 
   relation :hasConcern, :strategyCapabilities, :StrategyCapability
-  relation :hasConcern, :businessRequirements, :BusinessRequirement
-  relation :hasConcern, :businessConstraints, :BusinessConstraint
+  relation :hasConcern, :motivationRequirements, :MotivationRequirement
+  relation :hasConcern, :motivationConstraints, :MotivationConstraint
   relation :hasConcern, :goals, :MotivationGoal
 end

data/lib/archsight/resources/page.rb

@@ -38,11 +38,13 @@ class Archsight::Resources::Page < Archsight::Resources::Base
              description: "Owner responsible for keeping the page up to date (Name <email@domain.com>, or just a name)",
              title: "Owner",
              type: Archsight::Annotations::Person,
-             sidebar: false
+             sidebar: false,
+             summary: true
   annotation "page/status",
              description: "Lifecycle status (e.g. rfc, wip, approved)",
              filter: :word,
-             title: "Status"
+             title: "Status",
+             summary: true
   annotation "page/tags",
              description: "Comma-separated tags",
              filter: :list,

data/lib/archsight/resources/strategy_capability.rb

@@ -30,8 +30,8 @@ class Archsight::Resources::StrategyCapability < Archsight::Resources::Base
   icon "strategy"
   layer "strategy"
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
-  relation :realizes, :businessRequirements, :BusinessRequirement
+  relation :realizes, :motivationConstraints, :MotivationConstraint
+  relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :applicationServices, :ApplicationService
   relation :servedBy, :businessProcesses, :BusinessProcess

data/lib/archsight/resources/technology_artifact.rb

@@ -74,7 +74,7 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
              description: "Repository activity status",
              title: "Activity Status",
              enum: %w[active abandoned bot-only archived inaccessible empty no-code],
-             list: true
+             summary: true
   annotation "activity/reason",
              description: "Reason for activity status (for non-standard statuses)",
              title: "Status Reason",
@@ -83,7 +83,7 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
              description: "Bus factor assessment",
              title: "Bus Factor",
              enum: %w[high medium low unknown],
-             list: true
+             summary: true
   annotation "activity/createdAt",
              description: "Date of first commit (repository creation)",
              title: "Created",
@@ -130,7 +130,8 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   annotation "repository/visibility",
              description: "Repository visibility classification",
              title: "Visibility",
-             enum: %w[private internal open-source public]
+             enum: %w[private internal open-source public],
+             summary: true
   annotation "repository/recentTags",
              description: "Recent git tags (releases)",
              title: "Recent Tags",

data/lib/archsight/resources/technology_node.rb

@@ -34,9 +34,9 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
              description: "Type of infrastructure node",
              title: "Infrastructure Type",
              enum: %w[vm bare-metal kubernetes-node network-appliance storage-array],
-             list: true
+             summary: true
 
-  relation :realizes, :businessConstraints, :BusinessConstraint
+  relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :servedBy, :technologyServices, :TechnologyService
   relation :servedBy, :businessActors, :BusinessActor
 end

data/lib/archsight/resources/technology_service.rb

@@ -37,4 +37,8 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
 
   relation :suppliedBy, :technologyComponents, :TechnologySystemSoftware
   relation :servedBy, :businessActors, :BusinessActor
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/technology_system_software.rb

@@ -34,4 +34,8 @@ class Archsight::Resources::TechnologySystemSoftware < Archsight::Resources::Bas
   relation :realizedThrough, :technologyArtifacts, :TechnologyArtifact
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
+  relation :realizes, :motivationRequirements, :MotivationRequirement
+  relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
+  relation :plans, :motivationRequirements, :MotivationRequirement
+  relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
 end

data/lib/archsight/resources/view.rb

@@ -42,7 +42,8 @@ class Archsight::Resources::View < Archsight::Resources::Base
              description: "Display type for results",
              title: "Display Type",
              enum: %w[list:name list:name+kind],
-             sidebar: false
+             sidebar: false,
+             summary: true
 
   annotation "view/sort",
              description: 'Comma-separated list of fields to sort by. Prefix with - for descending (e.g., "-scc/language/Go/loc,name"). Special fields: name, kind',

data/lib/archsight/resources.rb

@@ -6,6 +6,37 @@ module Archsight
     # Store the class mapping
     @resource_classes = {}
 
+    # Kinds that were renamed: the old name is still accepted (see Database#create_valid_instance) and reported
+    # as deprecated by `archsight lint`. The table is only consulted by lookups; `each` and `resource_classes`
+    # list every kind once, under its new name. Remove an entry (and its relation keys below) to end the transition.
+    KIND_ALIASES = {
+      "BusinessRequirement" => "MotivationRequirement",
+      "BusinessConstraint" => "MotivationConstraint"
+    }.freeze
+
+    # Relation keys (the plural kind names under `spec.<verb>`) that were renamed together with their kind
+    RELATION_KEY_ALIASES = {
+      "businessRequirements" => "motivationRequirements",
+      "businessConstraints" => "motivationConstraints"
+    }.freeze
+
+    # Relations that are never written in a file: they are derived from what a resource's text and diagram say
+    # (see Archsight::References). `mentions` comes from links in text, `depicts` from the nodes of a diagram.
+    # Every kind can have them towards every kind, so instead of one relation per target kind a class gets one per
+    # verb, under the key DERIVED_KEY, that holds resources of any kind (relations are followed by looking at the
+    # resources they hold, not at the kind they were declared for).
+    DERIVED_VERBS = %i[mentions depicts].freeze
+    DERIVED_KEY = :resources
+
+    # The derived relations of every class, next to the ones it declares: [verb, key, kind]
+    DERIVED_RELATIONS = DERIVED_VERBS.map { |verb| [verb, DERIVED_KEY, "Resource"] }.freeze
+
+    # The current name of a kind, whichever of its names is given
+    def self.canonical(klass_name)
+      name = klass_name.to_s
+      KIND_ALIASES.fetch(name, name)
+    end
+
     # Register a resource class
     def self.register(klass)
       # Skip anonymous classes (used in tests)
@@ -20,9 +51,9 @@ module Archsight
       @resource_classes
     end
 
-    # Returns the class by name
+    # Returns the class by name; a renamed kind is found under its old name too
     def self.[](klass_name)
-      @resource_classes[klass_name.to_s]
+      @resource_classes[canonical(klass_name)]
     end
 
     # Iterate over all resource class names (sorted)
@@ -32,7 +63,7 @@ module Archsight
 
     # Get the constant by name (for backward compatibility with const_get)
     def self.const_get(name)
-      @resource_classes[name.to_s] || super
+      @resource_classes[canonical(name)] || super
     end
   end
 end

data/lib/archsight/template.rb

@@ -35,10 +35,10 @@ module Archsight
       end
 
       def add_relations(yaml, klass)
-        return if klass.relations.empty?
+        return if klass.declared_relations.empty?
 
         yaml["spec"] = {} if yaml["spec"].nil?
-        klass.relations.each do |verb, relation_kind, _relation_klass|
+        klass.declared_relations.each do |verb, relation_kind, _relation_klass|
           relation_verb = verb.to_s.delete_prefix(":")
           yaml["spec"][relation_verb] ||= {}
           yaml["spec"][relation_verb][relation_kind.to_s] = []

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

data/lib/archsight/view_table.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Archsight
+  # The result of a view as a plain table (columns and rows of text), for places that cannot run the frontend, such
+  # as the Confluence export. It follows what the web UI shows for a View (`ViewResults.vue`, `ResourceList.vue`):
+  # a Name column, a Kind column unless the view is `list:name`, one column per `view/fields` entry that is not
+  # `name` or `kind`, rows sorted by `view/sort`.
+  module ViewTable
+    # Rows beyond this are cut (the table says how many); a Confluence page is no place for thousands of rows
+    LIMIT = 200
+
+    # @param as [Symbol] :text, :status or :priority (a requirement's, shown as a lozenge) or :markdown
+    # @param resources [Array] resources the cell names (shown one per line, linked where a target exists)
+    Cell = Struct.new(:text, :resources, :as, keyword_init: true) do
+      def initialize(text: "", resources: [], as: :text) = super
+    end
+
+    # @param title [String] shown above the table, may be empty
+    # @param columns [Array<String>] header texts
+    # @param rows [Array<Array<Cell>>] at most LIMIT
+    # @param total [Integer] number of rows before cutting
+    Table = Struct.new(:title, :columns, :rows, :total, keyword_init: true) do
+      def cut = total - rows.length
+    end
+
+    IDENTITY_FIELDS = %w[name kind].freeze
+
+    module_function
+
+    # @raise [Archsight::Query::QueryError] if the query does not parse
+    def build(database, query:, fields: [], sort: [], show_kind: true, title: "", limit: LIMIT)
+      resources = sort_resources(Archsight::Query.parse(query).filter(database), sort)
+      columns = fields.reject { |f| IDENTITY_FIELDS.include?(f) }
+      header = ["Name", (show_kind ? "Kind" : nil), *columns.map { |f| column_title(f) }].compact
+      rows = resources.first(limit).map do |resource|
+        [Cell.new(text: resource.name, resources: [resource]),
+         (Cell.new(text: kind_of(resource)) if show_kind),
+         *columns.map { |f| Cell.new(text: resource.annotations[f].to_s) }].compact
+      end
+      Table.new(title: title, columns: header, rows: rows, total: resources.length)
+    end
+
+    # The table of a ```view block (see Helpers::ViewBlocks)
+    # @raise [Helpers::ViewBlocks::Error, Archsight::Query::QueryError]
+    def from_block(database, source)
+      spec = Helpers::ViewBlocks.parse(source)
+      build(database, query: spec[:query], fields: spec[:fields], sort: spec[:sort], show_kind: spec[:type] == "list:name+kind", title: spec[:title])
+    end
+
+    # The table of a View resource
+    # @raise [Helpers::ViewBlocks::Error, Archsight::Query::QueryError]
+    def from_view(database, view)
+      annotations = view.annotations
+      query = annotations["view/query"].to_s.strip
+      raise Helpers::ViewBlocks::Error, "view #{view.name} has no query" if query.empty?
+
+      build(database, query: query, fields: list(annotations["view/fields"]), sort: list(annotations["view/sort"]),
+                      show_kind: (annotations["view/type"] || "list:name+kind") == "list:name+kind", title: view.name)
+    end
+
+    # "scc/language/Go/loc" -> "Go loc", "activity/createdAt" -> "Activity created At" (as ResourceList.vue titles columns)
+    def column_title(key)
+      segments = key.split("/")
+      title = segments.length >= 2 ? "#{segments[-2]} #{segments[-1]}" : segments.last.to_s
+      title.gsub(/([a-z])([A-Z])/, '\1 \2').sub(/\A./, &:upcase)
+    end
+
+    def kind_of(resource) = resource.class.name.split("::").last
+
+    def list(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+    # `view/sort` fields: name, kind or an annotation, "-" for descending; numbers inside text compare as numbers.
+    # Without a sort the order is by name, like the search API.
+    def sort_resources(resources, sort)
+      return resources.sort_by(&:name) if sort.empty?
+
+      resources.sort { |left, right| compare(left, right, sort) }
+    end
+
+    def compare(left, right, sort)
+      sort.each do |field|
+        key = field.delete_prefix("-")
+        order = natural(value_of(left, key)) <=> natural(value_of(right, key))
+        return field.start_with?("-") ? -order : order unless order.zero?
+      end
+      0
+    end
+
+    def value_of(resource, key)
+      case key
+      when "name" then resource.name
+      when "kind" then kind_of(resource)
+      else resource.annotations[key].to_s
+      end
+    end
+
+    # A key for sorting text with numbers in it the way people expect (item2 < item10, case-insensitive first)
+    def natural(text)
+      [text.scan(/\d+|\D+/).map { |part| part.match?(/\A\d/) ? [0, part.to_i] : [1, part.downcase] }, text]
+    end
+  end
+end