archsight 0.4.2 → 0.5.0

data/lib/archsight/resources/application_service.rb

@@ -35,6 +35,12 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
     the other service's components listed again; a service that many others use is modeled once. A service whose only component has the same name is a smell. See
     the modeling guide, "Choosing the Kind".
 
+    ## Teams
+
+    A service is `maintainedBy` the team (`BusinessActor`) that builds and changes it and `operatedBy` the team
+    (`BusinessActor` or `BusinessRole`) that runs it in production. Build and run are often different teams, which is
+    the point of writing both. `servedBy` stays "who uses it". Both are optional.
+
     ## Security and risk modelling
 
     A service is an asset at risk (`asset/*` profile, protection needs) that loss events `affects`, a trigger target
@@ -230,6 +236,9 @@ class Archsight::Resources::ApplicationService < Archsight::Resources::Base
   relation :dependsOn, :applicationServices, :ApplicationService
   relation :servedBy, :businessActors, :BusinessActor
   relation :servedBy, :technologyServices, :TechnologyService
+  relation :maintainedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessRoles, :BusinessRole
   relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement

data/lib/archsight/resources/config.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+# Config holds settings of a feature of the tool, kept with the model so they are shared and versioned like it
+class Archsight::Resources::Config < Archsight::Resources::Base
+  include_annotations :architecture
+
+  description <<~MD
+    Holds the settings of a feature of the tool, such as the look of the PDF export.
+
+    ## Definition
+
+    A Config is a tool-specific resource type. It carries no architecture, only settings, so that everything that
+    should look or behave the same is written once and shared through the resources repository instead of being
+    repeated in every page. It is not the per-user configuration file (tokens, URLs of other systems): that stays in
+    `~/.config/archsight/archsight.yaml`.
+
+    ## Type
+
+    `config/type` says which feature the settings are for; the feature looks up its own Configs by type, so every
+    feature can have a Config named `default`. The settings of a feature use the annotations of its own prefix.
+
+    | `config/type` | Settings | Used by |
+    |---------------|----------|---------|
+    | `pdf` | `pdf/*`: colours, fonts, logo, header and footer | [PDF export](/doc/pdf-export) |
+
+    A document picks a different Config of the type with the tag `pdf:template:<name>`; without a tag the one named
+    `default` is used, and without any the export has a neutral built-in look.
+
+    ## PDF settings
+
+    - **Colours** (`pdf/color-*`) are hex values (`#0b3d91`). `primary` is used for headings, the cover band and
+      table headers, `accent` for rules and links.
+    - **Fonts** (`pdf/font-*`) are family names. Fonts that are not installed fall back to the built-in ones; put
+      font files in a directory of the resources and name it in `pdf/font-dir` to ship them with the model.
+    - **Logos** (`pdf/logo`, `pdf/logo-light`) are image files (svg, png) of the resources directory, given
+      relative to it. `logo` goes on white (page header), `logo-light` on the coloured cover band.
+    - **Texts** (`pdf/footer-text`, `pdf/classification`) appear on every page.
+  MD
+
+  icon "settings"
+  layer "other"
+
+  TYPE_FORMAT = /\A[a-z][a-z0-9-]*\z/
+
+  annotation "config/type",
+             description: "The feature these settings are for (pdf). The feature looks up its Configs by this type",
+             title: "Type",
+             filter: :word,
+             summary: true,
+             validator: ->(value) { Archsight::Resources::Config.pattern_error(value, TYPE_FORMAT, "a lowercase word such as pdf") }
+
+  COLOR = /\A#(\h{3}|\h{6})\z/
+  FONT_NAME = /\A[\p{L}\p{N} ._+-]{1,80}\z/
+  LENGTH = /\A\d+(\.\d+)?(mm|cm|pt|in)\z/
+
+  # Colour annotations: key suffix, title, role
+  COLORS = {
+    "primary" => ["Primary colour", "headings, cover band, table headers"],
+    "accent" => ["Accent colour", "rules and links"],
+    "text" => ["Text colour", "body text"],
+    "muted" => ["Muted colour", "secondary text, header and footer"],
+    "ok" => ["Positive colour", "good status"],
+    "warn" => ["Warning colour", "warning status"],
+    "danger" => ["Danger colour", "bad status and the classification marking"]
+  }.freeze
+
+  COLORS.each do |key, (title, role)|
+    annotation "pdf/color-#{key}",
+               description: "#{title} as hex value (#rrggbb), used for #{role}",
+               title: title,
+               validator: ->(value) { Archsight::Resources::Config.pattern_error(value, COLOR, "a hex colour such as #0b3d91") },
+               sidebar: false
+  end
+
+  %w[body heading mono].each do |role|
+    annotation "pdf/font-#{role}",
+               description: "Font family of the #{role} text",
+               title: "#{role.capitalize} font",
+               validator: ->(value) { Archsight::Resources::Config.pattern_error(value, FONT_NAME, "a font family name") },
+               sidebar: false
+  end
+
+  annotation "pdf/font-dir",
+             description: "Directory with font files (ttf, otf), relative to the resources directory",
+             title: "Font directory",
+             sidebar: false
+
+  annotation "pdf/logo",
+             description: "Logo for the page header (svg or png), path relative to the resources directory",
+             title: "Logo",
+             validator: ->(value) { Archsight::Resources::Config.logo_error(value) },
+             sidebar: false
+  annotation "pdf/logo-light",
+             description: "Logo for the coloured cover band (svg or png), path relative to the resources directory",
+             title: "Logo (light)",
+             validator: ->(value) { Archsight::Resources::Config.logo_error(value) },
+             sidebar: false
+
+  annotation "pdf/footer-text",
+             description: "Text in the footer of every page (centre)",
+             title: "Footer text",
+             sidebar: false
+  annotation "pdf/classification",
+             description: "Marking shown in the footer of every page, e.g. Internal. A document can override it with " \
+                          "the page property Classification",
+             title: "Classification",
+             sidebar: false
+  annotation "pdf/header-meta",
+             description: "Comma-separated parts of the header line: id, version, date, owner (default: all)",
+             title: "Header line",
+             sidebar: false,
+             validator: ->(value) { Archsight::Resources::Config.header_meta_error(value) }
+  annotation "pdf/lang",
+             description: "Language of the fixed texts (page, contents, ...)",
+             title: "Language",
+             enum: %w[en de],
+             sidebar: false
+  annotation "pdf/paper",
+             description: "Paper size",
+             title: "Paper",
+             enum: %w[a4 a5 us-letter],
+             sidebar: false
+  annotation "pdf/margin",
+             description: "Horizontal page margin as length (e.g. 16mm)",
+             title: "Margin",
+             validator: ->(value) { Archsight::Resources::Config.pattern_error(value, LENGTH, "a length such as 16mm") },
+             sidebar: false
+
+  HEADER_PARTS = %w[id version date owner].freeze
+
+  # Validator helpers: nil if the value is fine, else the message
+  def self.pattern_error(value, pattern, expected)
+    value.to_s.match?(pattern) ? nil : "expected #{expected}"
+  end
+
+  def self.logo_error(value)
+    ext = File.extname(value.to_s).downcase
+    return nil if %w[.svg .png].include?(ext) && Archsight::Assets.normalize(value.to_s)
+
+    "expected a path of an svg or png file relative to the resources directory"
+  end
+
+  def self.header_meta_error(value)
+    unknown = value.to_s.split(",").map(&:strip) - HEADER_PARTS
+    unknown.empty? ? nil : "unknown part #{unknown.join(", ")}; use #{HEADER_PARTS.join(", ")}"
+  end
+end

data/lib/archsight/resources/technology_service.rb

@@ -50,6 +50,12 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
     "servedBy" from ApplicationComponent on its page. An ApplicationService that is `servedBy` the service uses it as a
     whole; list a cluster there only when the service's own components run in it.
 
+    ## Teams
+
+    A service is `maintainedBy` the team (`BusinessActor`) that builds and changes it and `operatedBy` the team
+    (`BusinessActor` or `BusinessRole`) that runs it in production. Build and run are often different teams, which is
+    the point of writing both. `servedBy` stays "who uses it". Both are optional.
+
     ## Provisioning
 
     A service that software creates (clusters built by an infrastructure-as-code operator, a database cluster
@@ -75,6 +81,9 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
   relation :suppliedBy, :technologyComponents, :TechnologySystemSoftware
   relation :specializes, :technologyServices, :TechnologyService
   relation :servedBy, :businessActors, :BusinessActor
+  relation :maintainedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessRoles, :BusinessRole
   relation :locatedAt, :technologyFacilities, :TechnologyFacility
   relation :realizedBy, :technologyEquipment, :TechnologyEquipment
   relation :realizes, :motivationRequirements, :MotivationRequirement

data/lib/archsight/version.rb

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

data/lib/archsight/web/api/json_helpers.rb

@@ -106,7 +106,8 @@ module Archsight::Web::API::JsonHelpers
     source = annotations[DIAGRAM_ANNOTATION_KEY]
     return unless source.is_a?(String) && !source.strip.empty?
 
-    Archsight::Helpers::DiagramBlocks.render_diagram(source, resolver: Archsight::Helpers::ResourceResolver.new(db))
+    Archsight::Helpers::DiagramBlocks.render_diagram(source, resolver: Archsight::Helpers::ResourceResolver.new(db),
+                                                             includes: Archsight::Helpers::DiagramIncludes.for(db))
   end
 
   # The values of markdown annotations are rendered to HTML: architecture/description and every annotation the
@@ -190,7 +191,7 @@ module Archsight::Web::API::JsonHelpers
         title: annotation.title,
         description: annotation.description,
         filter_type: annotation.filter.to_s,
-        values: values
+        values: values.map { |value, count| { value: value, count: count } }
       }
     end
   end

data/lib/archsight/web/api/openapi/spec.yaml

@@ -374,6 +374,234 @@ paths:
         "404":
           description: Unknown colour
 
+  "/api/v1/kinds/Config/instances/{name}/preview":
+    get:
+      summary: Preview the look of a PDF Config
+      description: A fixed sample document (cover page and a page with headings, list,
+        quote, table with status badges and code) in the look of one `Config` of type
+        `pdf`, typeset by Typst like every PDF export. Served inline, for showing it
+        in a page. Only the Config shapes the result, so a changed colour, font or logo
+        is visible at once. The response carries an `ETag` (fingerprint of the document
+        and the files it is made of) and answers `304` for a matching `If-None-Match`.
+      operationId: getConfigPreview
+      tags:
+      - PDF
+      parameters:
+      - name: name
+        in: path
+        required: true
+        description: Name of the Config, e.g. `Config:PDF:default`
+        schema:
+          type: string
+      - name: part
+        in: query
+        required: false
+        description: "`cover` or `page` for a document of just that page (the viewer needs no navigation); without it both pages"
+        schema:
+          type: string
+          enum:
+          - cover
+          - page
+      - name: If-None-Match
+        in: header
+        required: false
+        description: The `ETag` of a copy the client has; a match answers `304`
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          headers:
+            ETag:
+              schema:
+                type: string
+            Content-Disposition:
+              description: '`inline; filename="preview-<name>.pdf"`'
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '304':
+          description: The client's copy is current
+        '404':
+          description: No such Config
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: The Config is not of type `pdf`, or the sample could not be typeset
+            (message of typst)
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '503':
+          description: typst is not installed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+
+  "/api/v1/kinds/{kind}/instances/{name}/pdf":
+    get:
+      summary: Download a resource as PDF
+      description: |
+        Returns one resource as a PDF document, laid out by Typst (`typst` must be installed, the container image has it).
+  
+        **What it contains**: a page is exported as written (headings, tables, images, `asd` diagrams as vector graphics,
+        `[[links]]` as their label); any other resource becomes a generated document with its description,
+        properties, relations and its `architecture/diagram`. Tags steer the layout: `pdf:cover`, `pdf:toc`,
+        `pdf:landscape`, `pdf:draft`, `pdf:template:<name>` and `version:<x>`.
+  
+        **Look**: colours, fonts, logo and the texts of header and footer come from the `Config` resource of type `pdf` named
+        `default` (or the one `template` / the tag names); without one a neutral look is used.
+  
+        The response carries an `ETag` (a fingerprint of everything the PDF is made from, so a changed page, image,
+        diagram or template changes it) and answers `304` for a matching `If-None-Match`.
+      operationId: getInstancePdf
+      tags:
+      - PDF
+      parameters:
+      - "$ref": "#/components/parameters/kind"
+      - "$ref": "#/components/parameters/name"
+      - name: template
+        in: query
+        required: false
+        description: Name of a `Config` of type `pdf` to use instead of the tag or `default`
+        schema:
+          type: string
+      - name: draft
+        in: query
+        required: false
+        description: "`1` adds the draft watermark"
+        schema:
+          type: string
+          enum:
+          - '1'
+      - name: If-None-Match
+        in: header
+        required: false
+        description: The `ETag` of a copy the client has; a match answers `304`
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          headers:
+            ETag:
+              schema:
+                type: string
+            Content-Disposition:
+              description: '`attachment; filename="<name>.pdf"`'
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '304':
+          description: The client's copy is current
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: The document could not be typeset (message of typst)
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '503':
+          description: typst is not installed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+  "/api/v1/pages/{name}/pdf":
+    get:
+      summary: Download a page as PDF
+      description: |
+        Returns one page as a PDF document, laid out by Typst (`typst` must be installed, the container image has it).
+  
+        **What it contains**: a page is exported as written (headings, tables, images, `asd` diagrams as vector graphics,
+        `[[links]]` as their label); any other resource becomes a generated document with its description,
+        properties, relations and its `architecture/diagram`. Tags steer the layout: `pdf:cover`, `pdf:toc`,
+        `pdf:landscape`, `pdf:draft`, `pdf:template:<name>` and `version:<x>`.
+  
+        **Look**: colours, fonts, logo and the texts of header and footer come from the `Config` resource of type `pdf` named
+        `default` (or the one `template` / the tag names); without one a neutral look is used.
+  
+        The response carries an `ETag` (a fingerprint of everything the PDF is made from, so a changed page, image,
+        diagram or template changes it) and answers `304` for a matching `If-None-Match`.
+      operationId: getPagePdf
+      tags:
+      - PDF
+      parameters:
+      - "$ref": "#/components/parameters/name"
+      - name: template
+        in: query
+        required: false
+        description: Name of a `Config` of type `pdf` to use instead of the tag or `default`
+        schema:
+          type: string
+      - name: draft
+        in: query
+        required: false
+        description: "`1` adds the draft watermark"
+        schema:
+          type: string
+          enum:
+          - '1'
+      - name: If-None-Match
+        in: header
+        required: false
+        description: The `ETag` of a copy the client has; a match answers `304`
+        schema:
+          type: string
+      responses:
+        '200':
+          description: The PDF
+          headers:
+            ETag:
+              schema:
+                type: string
+            Content-Disposition:
+              description: '`attachment; filename="<name>.pdf"`'
+              schema:
+                type: string
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        '304':
+          description: The client's copy is current
+        '404':
+          description: Not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '422':
+          description: The document could not be typeset (message of typst)
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+        '503':
+          description: typst is not installed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+
   /api/v1/assets/{path}:
     get:
       summary: Get an asset (image or draw.io diagram)
@@ -1581,9 +1809,16 @@ components:
           description: Filter type (e.g., "select", "boolean")
         values:
           type: array
+          description: Available values with the number of instances using them, most used first
           items:
-            type: string
-          description: Available values for the filter
+            type: object
+            required: [value, count]
+            properties:
+              value:
+                type: string
+              count:
+                type: integer
+                description: Number of instances with this value
 
     AnalysisResult:
       type: object
@@ -2113,6 +2348,8 @@ tags:
     description: Search and query operations
   - name: Pages
     description: Wiki pages (markdown with frontmatter), the page tree and the home page
+  - name: PDF
+    description: Pages and resources as PDF documents (Typst)
   - name: Assets
     description: Images and draw.io diagrams that markdown embeds
   - name: Macros

data/lib/archsight/web/api/page_helpers.rb

@@ -24,7 +24,7 @@ module Archsight::Web::API::PageHelpers
       next if counts.empty?
 
       { key: annotation.key, title: annotation.title, filter_type: annotation.filter.to_s,
-        values: counts.sort.map { |value, count| { value: value, count: count } } }
+        values: counts.sort_by { |value, count| [-count, value.to_s] }.map { |value, count| { value: value, count: count } } }
     end
   end
 

data/lib/archsight/web/api/pdf_helpers.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../../pdf"
+require_relative "../../pdf/cache"
+require_relative "../../pdf/sample_document"
+
+module Archsight; end
+module Archsight::Web; end
+module Archsight::Web::API; end
+
+# Download of a page or resource as PDF
+module Archsight::Web::API::PdfHelpers
+  CACHE = Archsight::Pdf::Cache.new
+  COMPILER = Archsight::Pdf::Compiler.new
+
+  # Sends the PDF of `resource`. The ETag is the fingerprint of everything the PDF is made from, so a client (and
+  # the server's cache) keeps it exactly as long as the page, its images, diagrams and the template are unchanged.
+  # Query: `template` (name of a pdf Config), `draft=1` (watermark).
+  def serve_pdf(resource)
+    pdf_response do
+      Archsight::Pdf.document(db, resource, compiler: COMPILER, template: params[:template].to_s.empty? ? nil : params[:template],
+                                            draft: params[:draft] == "1")
+    end
+  end
+
+  # Sends the sample document in the look of a pdf Config, shown in the page instead of downloaded
+  def serve_pdf_preview(config)
+    pdf_response("inline") { Archsight::Pdf::SampleDocument.new(db, config, part: params[:part], pdf_images: COMPILER.pdf_images?) }
+  end
+
+  # Typesets the document the block builds and sends it; typst problems are answered as JSON errors
+  def pdf_response(disposition = "attachment")
+    document = yield
+    headers "X-Content-Type-Options" => "nosniff"
+    cache_control :private, :must_revalidate, max_age: 0
+    etag document.fingerprint
+    pdf = CACHE.fetch(document.fingerprint) { Archsight::Pdf.compile(document, compiler: COMPILER) }
+    content_type "application/pdf"
+    headers "Content-Disposition" => %(#{disposition}; filename="#{document.filename}")
+    pdf
+  rescue Archsight::Pdf::Unavailable => e
+    json_error(e.message, status: 503, error_type: "ServiceUnavailable")
+  rescue Archsight::Pdf::Error => e
+    json_error(e.message, status: 422, error_type: "UnprocessableEntity")
+  end
+end

data/lib/archsight/web/api/routes.rb

@@ -6,6 +6,7 @@ require_relative "json_helpers"
 require_relative "page_helpers"
 require_relative "requirements_helpers"
 require_relative "analysis_helpers"
+require_relative "pdf_helpers"
 require_relative "../../assets"
 require_relative "../../openapi"
 
@@ -21,6 +22,7 @@ module Archsight::Web::API::Routes
   helpers Archsight::Web::API::PageHelpers
   helpers Archsight::Web::API::RequirementsHelpers
   helpers Archsight::Web::API::AnalysisHelpers
+  helpers Archsight::Web::API::PdfHelpers
 
   # Rendering is CPU work, previews are typed, not pasted
   MAX_DIAGRAM_SOURCE = 100_000
@@ -79,6 +81,26 @@ module Archsight::Web::API::Routes
       .merge(graph_layers: Archsight::GraphvisRenderer.default_graph_layers(instance.class.layer)))
   end
 
+  # GET /api/v1/kinds/Config/instances/:name/preview - A sample document in the look of a pdf Config (inline PDF)
+  get "/api/v1/kinds/Config/instances/:name/preview" do
+    config = db.instance_by_kind("Config", params[:name]) || db.instance_by_alias("Config", params[:name])
+    json_error("Instance '#{params[:name]}' not found", status: 404, error_type: "NotFound") unless config
+    json_error("Config '#{config.name}' is not of type #{Archsight::Pdf::Theme::TYPE}", status: 422, error_type: "UnprocessableEntity") unless config.annotations["config/type"].to_s.casecmp?(Archsight::Pdf::Theme::TYPE)
+
+    serve_pdf_preview(config)
+  end
+
+  # GET /api/v1/kinds/:kind/instances/:name/pdf - The resource as PDF document (Typst), see Archsight::Pdf
+  get "/api/v1/kinds/:kind/instances/:name/pdf" do
+    klass = Archsight::Resources[params[:kind]]
+    json_error("Kind '#{params[:kind]}' not found", status: 404, error_type: "NotFound") unless klass
+
+    instance = db.instance_by_kind(params[:kind], params[:name]) || db.instance_by_alias(params[:kind], params[:name])
+    json_error("Instance '#{params[:name]}' not found", status: 404, error_type: "NotFound") unless instance
+
+    serve_pdf(instance)
+  end
+
   # GET /api/v1/pages - Page tree built from PageMenu resources, page tags and filters and the home page
   # (shown at `/`; it is not in the tree unless a menu contains it)
   get "/api/v1/pages" do
@@ -95,6 +117,14 @@ module Archsight::Web::API::Routes
     json_response(build_page_response(page))
   end
 
+  # GET /api/v1/pages/:name/pdf - The page as PDF document (Typst), see Archsight::Pdf
+  get "/api/v1/pages/:name/pdf" do
+    page = db.instance_by_kind("Page", params[:name])
+    json_error("Page '#{params[:name]}' not found", status: 404, error_type: "NotFound") unless page
+
+    serve_pdf(page)
+  end
+
   # GET /api/v1/search - Search with query language
   get "/api/v1/search" do
     query = params[:q]
@@ -179,9 +209,10 @@ module Archsight::Web::API::Routes
       resolver = Archsight::Helpers::ResourceResolver.new(db)
       headers "Content-Security-Policy" => "default-src 'none'; style-src 'unsafe-inline'; sandbox"
       cache_control :public, :must_revalidate, max_age: 0
-      etag Archsight::Helpers::DiagramBlocks.fingerprint(source, resolver: resolver)
+      includes = Archsight::Helpers::DiagramIncludes.for(db)
+      etag Archsight::Helpers::DiagramBlocks.fingerprint(source, resolver: resolver, includes: includes)
       content_type "image/svg+xml"
-      Archsight::Helpers::DiagramBlocks.standalone_svg(source, resolver: resolver)
+      Archsight::Helpers::DiagramBlocks.standalone_svg(source, resolver: resolver, includes: includes)
     rescue Archsight::Diagram::Error => e
       json_error("Diagram does not render: #{e.message}", status: 422, error_type: "DiagramError")
     end
@@ -201,7 +232,7 @@ module Archsight::Web::API::Routes
     json_error("A JSON body with a 'source' string is required", status: 400, error_type: "BadRequest") unless source.is_a?(String)
 
     resolver = Archsight::Helpers::ResourceResolver.new(db)
-    json_response(Archsight::Helpers::DiagramBlocks.preview(source, resolver: resolver))
+    json_response(Archsight::Helpers::DiagramBlocks.preview(source, resolver: resolver, includes: Archsight::Helpers::DiagramIncludes.for(db)))
   end
 
   # POST /api/v1/kinds/Analysis/instances/:name/execute - Execute an analysis

data/lib/archsight/web/application.rb

@@ -161,7 +161,8 @@ class Archsight::Web::Application < Sinatra::Base
       html = Archsight::Markdown.document(data).to_html
       html = Archsight::Helpers::AssetImages.rewrite(html, base_dir: base, resources_dir: Archsight.resources_dir) if base
       # ```asd blocks become placeholders until the text passes below are done (see DiagramBlocks)
-      html, diagrams = Archsight::Helpers::DiagramBlocks.extract(html, resolver: Archsight::Helpers::ResourceResolver.new(db))
+      html, diagrams = Archsight::Helpers::DiagramBlocks.extract(html, resolver: Archsight::Helpers::ResourceResolver.new(db),
+                                                                       includes: Archsight::Helpers::DiagramIncludes.for(db))
       # so are ```view and ```requirements blocks (see ViewBlocks, RequirementsBlocks)
       html, views = Archsight::Helpers::ViewBlocks.extract(html)
       html, requirements = Archsight::Helpers::RequirementsBlocks.extract(html)

data/lib/archsight/web/public/vue/DocPage-D3QtnrmO.js

@@ -0,0 +1 @@
+import{B as e,L as t,R as n,X as r,it as i,p as a,t as o,tt as s}from"./index-BF4zUlWZ.js";import{t as c}from"./WikiPage-Bi7dzY2h.js";var l={key:1},u={__name:`DocPage`,props:{filename:String},setup(u){let d=u,f=i(null);function p(e,t){let n=new DOMParser().parseFromString(e,`text/html`).body,r=n.querySelector(`:scope > article`)||n,i=r.querySelector(`h1`),a=i?.textContent.trim()||t.split(`/`).pop().replace(/[-_]/g,` `);i?.remove();let o=[...r.querySelectorAll(`h2[id], h3[id], h4[id]`)].map(e=>({level:Number(e.tagName[1]),id:e.id,text:e.textContent.trim()})),s=[{title:`Documentation`}];return t.startsWith(`resources/`)&&s.push({title:`Resource types`}),{title:a,html:r.innerHTML,toc:o.length>=2?o:[],breadcrumb:s}}async function m(){let e=await a(d.filename);f.value=e?p(e,d.filename):{title:`Not found`,html:`<p>Documentation not found.</p>`,toc:[],breadcrumb:[{title:`Documentation`}]},o(f.value.title)}return s(()=>d.filename,m,{immediate:!0}),(i,a)=>f.value?(r(),n(c,{key:0,title:f.value.title,html:f.value.html,breadcrumb:f.value.breadcrumb,toc:f.value.toc},null,8,[`title`,`html`,`breadcrumb`,`toc`])):(r(),e(`article`,l,[...a[0]||=[t(`p`,null,`Loading...`,-1)]]))}};export{u as default};