archsight 0.4.2 → 0.5.0

data/lib/archsight/pdf/resource_sheet.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative "typst"
+
+module Archsight
+  module Pdf
+    # The facts of a resource that is not a page, as Typst markup: its properties (annotations) and its relations in
+    # both directions. Structure comes from alignment and light rules, not from boxes: a muted label column, rows
+    # divided by hairlines, related annotations kept together, and the resources of a relation flowing in columns
+    # instead of one long comma-separated line.
+    class ResourceSheet
+      SKIP = %w[architecture/description architecture/diagram architecture/tags].freeze
+      LONG = 400 # characters; longer single-line values still sit in the table, wrapped, up to MAX
+      MAX = 2000
+      RULE = "0.4pt + theme.muted.lighten(75%)" # as the rule under the rows of every other table
+      NAMES_IN_COLUMNS = 4 # from this many resources a relation lists them in two columns
+
+      # @param markdown [#call] `(String) -> Typst`, renders markdown the way the document does
+      def initialize(resource, markdown:)
+        @resource = resource
+        @markdown = markdown
+      end
+
+      # @return [Array<String>] the sections (heading and content) of the properties, none if there are none
+      def properties
+        short, long = annotations.partition { |key, value| table_value?(key, value) }
+        parts = []
+        parts << "#heading(level: 1)[#{Typst.str("Properties")}]\n\n#{property_table(short)}" unless short.empty?
+        long.each { |key, value| parts << long_value(key, value) }
+        parts
+      end
+
+      # @return [Array<String>] the sections of the outgoing and the incoming relations
+      def relations
+        out = outgoing
+        incoming = self.incoming
+        return [] if out.empty? && incoming.empty?
+
+        parts = ["#heading(level: 1)[#{Typst.str("Relations")}]"]
+        parts << "#heading(level: 2)[#{Typst.str("Outgoing")}]\n\n#{relation_table(out)}" unless out.empty?
+        parts << "#heading(level: 2)[#{Typst.str("Incoming")}]\n\n#{caption("Resources that point to this one; the relation is read from their side.")}\n\n#{relation_table(incoming)}" unless incoming.empty?
+        parts
+      end
+
+      # `dependsOn` -> "depends on"
+      def self.humanize(verb)
+        verb.to_s.gsub(/([a-z0-9])([A-Z])/, '\1 \2').downcase
+      end
+
+      private
+
+      def klass = @resource.class
+
+      def annotations
+        @resource.annotations.reject { |key, value| SKIP.include?(key) || value.to_s.strip.empty? }
+      end
+
+      # Multi-line and markdown values are text, not table cells
+      def table_value?(key, value)
+        !value.to_s.include?("\n") && !%w[markdown multiline].include?(klass.annotation_format(key).to_s)
+      end
+
+      def display(key, value)
+        text = value.to_s
+        text = text.split(",").map(&:strip).reject(&:empty?).join(", ") if klass.annotation_matching(key)&.list?
+        text.length > MAX ? "#{text[0, MAX]}…" : text
+      end
+
+      # Annotations of one namespace (`git/...`, `lifecycle/...`) stay together, separated from the next by a gap
+      def property_table(pairs)
+        grouped = pairs.group_by { |key, _| key.split("/").first }.values
+        cells = grouped.each_with_index.flat_map do |group, index|
+          gap = index.zero? ? [] : ["table.cell(colspan: 2, stroke: none, inset: 3pt)[]"]
+          gap + group.flat_map do |key, value|
+            ["[#text(fill: theme.muted)[#{Typst.str(klass.annotation_title(key))}]]", "[#{Typst.str(display(key, value))}]"]
+          end
+        end
+        "#table(columns: (30%, 1fr), stroke: (x, y) => (bottom: #{RULE}), inset: (x: 0pt, y: 5pt), #{cells.join(", ")})"
+      end
+
+      def long_value(key, value)
+        body = klass.annotation_format(key).to_s == "markdown" ? @markdown.call(value.to_s) : multiline(value.to_s)
+        "#heading(level: 2)[#{Typst.str(klass.annotation_title(key))}]\n\n#{body}"
+      end
+
+      def multiline(text)
+        text.lines.map { |line| Typst.str(line.chomp) }.join("#linebreak()")
+      end
+
+      # { verb => { kind => [instances] } }
+      def outgoing = @resource.relations_grouped
+
+      # incoming comes as { kind => { verb => [instances] } }, shown like the outgoing ones
+      def incoming
+        @resource.references_grouped.each_with_object({}) do |(kind, verbs), by_verb|
+          verbs.each { |verb, instances| (by_verb[verb] ||= {})[kind] = instances }
+        end.sort.to_h
+      end
+
+      # The relation (said once for all of its kinds), the kind, and the names of the resources in one or two columns
+      def relation_table(by_verb)
+        cells = by_verb.flat_map do |verb, kinds|
+          kinds.each_with_index.flat_map do |(kind, instances), index|
+            row = []
+            row << "table.cell(rowspan: #{kinds.size})[#text(weight: \"semibold\")[#{Typst.str(self.class.humanize(verb))}]]" if index.zero?
+            row << "[#pad(right: 8pt, text(fill: theme.muted)[#{Typst.str(breakable(kind))}])]"
+            row << "[#{names(instances)}]"
+          end
+        end
+        "#table(columns: (17%, 24%, 1fr), stroke: (x, y) => (bottom: #{RULE}), inset: (x: 0pt, y: 5pt), #{cells.join(", ")})"
+      end
+
+      def names(instances)
+        list = instances.map(&:name).uniq.sort.map { |name| "[#{Typst.str(breakable(name))}]" }
+        columns = list.size >= NAMES_IN_COLUMNS ? "1fr, 1fr" : "1fr"
+        "#grid(columns: (#{columns},), column-gutter: 10pt, row-gutter: 4pt, #{list.join(", ")})"
+      end
+
+      # Names have no spaces: allow a line break after each `:` and between camel-case words (no visible change)
+      def breakable(name)
+        name.gsub(":", ":\u200B").gsub(/([a-z0-9])([A-Z])/, "\\1\u200B\\2")
+      end
+
+      def caption(text)
+        "#text(size: 8.5pt, fill: theme.muted)[#{Typst.str(text)}]"
+      end
+    end
+  end
+end

data/lib/archsight/pdf/sample_document.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "document"
+
+module Archsight
+  module Pdf
+    # A fixed sample document in the look of one pdf Config, to see what the settings do without exporting a real page:
+    # a cover page and a page with the elements a document is made of (headings, text, list, quote, table with
+    # status, code). The content is neutral on purpose; only the Config shapes the result. The "resource" of the document
+    # is the Config (an Archsight::Resources::Config of type pdf).
+    class SampleDocument < Document
+      PARTS = %w[cover page].freeze
+      TITLE = "Sample document"
+      BODY = <<~MD
+        ## Summary
+
+        This page shows how headings, text, lists and tables look with the settings of the Config. It is a fixed sample,
+        not one of your documents, so every change of a colour, a font or the logo is visible at once.
+
+        > A quote stands out from the text around it and is set in the same typeface.
+
+        ### What a document contains
+
+        - Text with **strong** and *emphasised* words, `inline code` and a [link](https://example.com)
+        - Lists, tables, diagrams and code, set in the fonts of the Config
+        - Status badges such as {status:green Active} and {status:yellow Planned}
+
+        ## Components
+
+        | Component | Owner | Status |
+        |:----------|:------|:-------|
+        | Billing API | Payments | {status:green Active} |
+        | Export service | Data | {status:yellow Deprecated} |
+        | Legacy gateway | Platform | {status:red End of life} |
+
+        ### Interface
+
+        ```ruby
+        def total(items)
+          items.sum(&:price)
+        end
+        ```
+      MD
+
+      # @param part [String, nil] `cover` or `page` for just that page (a document of one page, so a viewer needs no
+      #   navigation), else both
+      def initialize(database, config, part: nil, **)
+        @part = part if PARTS.include?(part)
+        super(database, config, **)
+      end
+
+      def filename = "#{["preview", super.delete_suffix(".pdf"), @part].compact.join("-")}.pdf"
+
+      private
+
+      def theme_for(_template) = Theme.new(@resource, resources_dir: @resources_dir)
+      def title_for = TITLE
+      def tag_list = @part == "page" ? [] : %w[pdf:cover]
+      def body(images) = @part == "cover" ? "" : markdown(images).render(BODY)
+      def doc_id = "SAMPLE-001"
+      def version = "1.0"
+      def owner = "Alex Example"
+      def kind = "Sample"
+      def classification = @theme.classification
+    end
+  end
+end

data/lib/archsight/pdf/tables.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "typst"
+require_relative "markdown"
+require_relative "../view_table"
+require_relative "../export/confluence/tables"
+
+module Archsight
+  module Pdf
+    # A ViewTable::Table (the result of a view, of requirements or of an analysis) as a Typst table. Views are live
+    # in Archsight; in the PDF they are the data of the moment of the export.
+    module Tables
+      # A column whose longest text is longer than this shares the width (`fr`), shorter ones take what they need
+      LONG = 30
+      SMALL_FONT_FROM = 4 # columns
+      Confluence = Export::Confluence::Tables
+
+      module_function
+
+      # @param table [Archsight::ViewTable::Table]
+      # @param markdown [#call] Typst markup of a markdown text, for the cells of `as: :markdown`
+      # @param empty [String] shown instead of the table when there are no rows
+      # @return [String] Typst markup
+      def typst(table, markdown:, empty: "No results")
+        parts = []
+        parts << heading(table) unless table.title.to_s.empty?
+        parts << (table.rows.empty? ? Typst.note(empty, fill: "#f2f2f2") : grid(table, markdown))
+        parts << "#emph[#{Typst.str("#{table.cut} more #{table.cut == 1 ? "row" : "rows"} not shown, see Archsight")}]" if table.cut.positive?
+        parts.join("\n\n")
+      end
+
+      def heading(table)
+        count = "(#{table.total} #{table.total == 1 ? "item" : "items"})"
+        "#block(sticky: true)[#strong[#{Typst.str(table.title)}] #text(fill: luma(120))[#{Typst.str(count)}]]"
+      end
+
+      def grid(table, markdown)
+        head = table.columns.map { |c| "[#text(weight: \"semibold\")[#{Typst.str(c)}]]" }
+        cells = table.rows.flat_map { |row| row.map { |cell| "[#{cell(cell, markdown)}]" } }
+        out = "#table(columns: (#{widths(table).join(", ")},), table.header(#{head.join(", ")}), #{cells.join(", ")})"
+        table.columns.size >= SMALL_FONT_FROM ? "#[#set text(size: 8.5pt)\n#{out}]" : out
+      end
+
+      # `auto` for short columns, a share of the rest for long ones, so wide tables wrap instead of running off the page
+      def widths(table)
+        table.columns.each_index.map do |i|
+          longest = [table.columns[i].length, *table.rows.map { |row| row[i] ? text_of(row[i]).length : 0 }].max
+          longest > LONG ? "#{(longest / LONG.to_f).round.clamp(1, 4)}fr" : "auto"
+        end
+      end
+
+      def text_of(cell)
+        cell.resources.empty? ? cell.text.to_s : cell.resources.map(&:name).join(" ")
+      end
+
+      def cell(cell, markdown)
+        return cell.resources.map { |resource| Typst.str(resource.name) }.join("#linebreak()") unless cell.resources.empty?
+
+        case cell.as
+        when :status then badge(cell.text, Confluence::STATUS_COLOURS)
+        when :priority then cell.text.to_s.empty? ? "" : badge(cell.text, Confluence::PRIORITY_COLOURS)
+        when :markdown then markdown.call(cell.text.to_s)
+        else cell.text.to_s.split("\n").map { |line| Typst.str(line) }.join("#linebreak()")
+        end
+      end
+
+      def badge(text, colours)
+        Typst.badge(text, Markdown::STATUS_FILL.fetch(colours.fetch(text, "grey"), "#e8e8e8"))
+      end
+    end
+  end
+end

data/lib/archsight/pdf/theme.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "typst"
+require_relative "../assets"
+
+module Archsight
+  module Pdf
+    # The look of an exported document: what a Config resource of type pdf says, with a neutral built-in look for
+    # everything it leaves out (or for no template at all). Every value is checked here, so a template loaded
+    # from a file that was never linted cannot put anything but a colour, a font name or a length into the
+    # Typst source.
+    class Theme
+      DEFAULT_NAME = "default"
+      TYPE = "pdf" # the `config/type` of the Configs that describe the look
+      COLORS = {
+        primary: "#1f3a5f", accent: "#2f7fd1", text: "#1c1c1c", muted: "#6b7280",
+        ok: "#1f9d55", warn: "#d98e04", danger: "#c0392b"
+      }.freeze
+      FONTS = {
+        body: ["Liberation Sans", "DejaVu Sans", "Helvetica", "Arial"],
+        heading: ["Liberation Sans", "DejaVu Sans", "Helvetica", "Arial"],
+        mono: ["DejaVu Sans Mono", "Liberation Mono", "Menlo", "Courier New"]
+      }.freeze
+      PAPERS = %w[a4 a5 us-letter].freeze
+      LANGS = %w[en de].freeze
+      HEADER_PARTS = %w[id version date owner].freeze
+      DEFAULT_MARGIN = "16mm"
+      LOGO_TYPES = %w[.svg .png].freeze
+
+      attr_reader :name, :colors, :fonts, :footer_text, :classification, :header_meta, :lang, :paper, :margin,
+                  :logo, :logo_light, :font_dir
+
+      # @param template [Archsight::Resources::Config, nil]
+      # @param resources_dir [String] logos and fonts are looked up below it
+      def initialize(template = nil, resources_dir: Archsight.resources_dir)
+        @name = template&.name
+        ann = template ? template.annotations : {}
+        @colors = COLORS.to_h { |key, default| [key, color(ann["pdf/color-#{key}"], default)] }
+        @fonts = FONTS.to_h { |key, default| [key, font_list(ann["pdf/font-#{key}"], default)] }
+        @footer_text = blank_to_nil(ann["pdf/footer-text"])
+        @classification = blank_to_nil(ann["pdf/classification"])
+        @header_meta = header_parts(ann["pdf/header-meta"])
+        @lang = LANGS.include?(ann["pdf/lang"]) ? ann["pdf/lang"] : "en"
+        @paper = PAPERS.include?(ann["pdf/paper"]) ? ann["pdf/paper"] : "a4"
+        @margin = ann["pdf/margin"].to_s.match?(Resources::Config::LENGTH) ? ann["pdf/margin"] : DEFAULT_MARGIN
+        @logo = logo_file(ann["pdf/logo"], resources_dir)
+        @logo_light = logo_file(ann["pdf/logo-light"], resources_dir) || @logo
+        @font_dir = font_directory(ann["pdf/font-dir"], resources_dir)
+      end
+
+      # The Config a document asks for (`pdf:template:<name>`), else the one named `default`, else the built-in look. Only
+      # Configs of type pdf count.
+      # @param requested [String, nil] name as written in the tag, with or without the `Config:` and `PDF:` prefixes
+      def self.for(database, requested = nil)
+        wanted = (requested || DEFAULT_NAME).to_s.strip
+        configs = database.instances_by_kind("Config").values.select { |c| c.annotations["config/type"].to_s.casecmp?(TYPE) }
+        new(configs.find { |config| matches?(config.name, wanted) })
+      end
+
+      # `brand`, `PDF:brand` and `Config:PDF:brand` all name the same Config
+      def self.matches?(name, wanted)
+        short(name).casecmp?(short(wanted))
+      end
+
+      def self.short(name)
+        name.to_s.strip.sub(/\AConfig:/i, "").sub(/\APDF:/i, "")
+      end
+
+      # Typst source defining `theme`. `logo` and `logo_light` are the file names the logos were staged under.
+      def to_typst(logo: nil, logo_light: nil)
+        fields = colors.map { |key, hex| "#{key}: #{Typst.color(hex)}" }
+        fields += fonts.map { |key, list| "font-#{key}: (#{list.map { |f| Typst.lit(f) }.join(", ")},)" }
+        fields += [
+          "logo: #{logo ? Typst.lit(logo) : "none"}", "logo-light: #{logo_light ? Typst.lit(logo_light) : "none"}",
+          "footer-text: #{footer_text ? Typst.lit(footer_text) : "none"}",
+          "header-meta: (#{header_meta.map { |p| Typst.lit(p) }.join(", ")},)",
+          "lang: #{Typst.lit(lang)}", "paper: #{Typst.lit(paper)}", "margin: #{margin}"
+        ]
+        "#let theme = (#{fields.join(", ")})\n"
+      end
+
+      private
+
+      def color(value, default)
+        value.to_s.strip.match?(Resources::Config::COLOR) ? value.to_s.strip : default
+      end
+
+      def font_list(value, default)
+        name = value.to_s.strip
+        name.match?(Resources::Config::FONT_NAME) ? [name, *default] : default
+      end
+
+      def header_parts(value)
+        return HEADER_PARTS if value.to_s.strip.empty?
+
+        parts = value.to_s.split(",").map(&:strip) & HEADER_PARTS
+        parts.empty? ? HEADER_PARTS : parts
+      end
+
+      def blank_to_nil(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+
+      # @return [String, nil] absolute path of a logo inside the resources directory
+      def logo_file(path, resources_dir)
+        return nil if path.to_s.strip.empty?
+
+        file = Assets.file_for(path.to_s, resources_dir: resources_dir)
+        file if file && LOGO_TYPES.include?(File.extname(file).downcase)
+      end
+
+      def font_directory(path, resources_dir)
+        normalized = Assets.normalize(path.to_s)
+        return nil unless normalized
+
+        root = File.realpath(resources_dir)
+        dir = File.realpath(File.join(root, normalized))
+        dir if dir.start_with?(root + File::SEPARATOR) && File.directory?(dir)
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/archsight/pdf/typst/archsight.typ

@@ -0,0 +1,152 @@
+// Page shell of the Archsight PDF export. Generic: every colour, font, logo and text comes from `theme`
+// (see Archsight::Pdf::Theme), every per-document value is an argument.
+
+#let labels = (
+  en: (page: "Page", of: "of", contents: "Contents", draft: "DRAFT", doc-id: "Document ID", version: "Version", date: "Date", owner: "Owner", classification: "Classification"),
+  de: (page: "Seite", of: "von", contents: "Inhalt", draft: "ENTWURF", doc-id: "Dokument-ID", version: "Version", date: "Datum", owner: "Eigentümer", classification: "Einstufung"),
+)
+
+// Identifiers have no spaces: allow a line break after `-`, `:` and `/` and between camel-case words (no visible change)
+#let breakable(s) = if type(s) != str { s } else {
+  s.replace(regex("([:/-])"), m => m.text + "\u{200B}").replace(regex("([a-z0-9])([A-Z])"), m => m.captures.at(0) + "\u{200B}" + m.captures.at(1))
+}
+
+// An image at its natural size, shrunk to fit the text width and `max-height` of the page, centred
+#let fit-image(path, max-height: 0.5) = layout(size => context {
+  let natural = measure(image(path))
+  let limit = page.height * max-height
+  let w = calc.min(natural.width, size.width)
+  let h = w * (natural.height / natural.width)
+  if h > limit {
+    h = limit
+    w = h * (natural.width / natural.height)
+  }
+  align(center, image(path, width: w, height: h))
+})
+
+// The meta line of the header: the document id in the mono font, the parts separated by a light bar
+#let _meta-line(theme, id, version, date, owner) = {
+  let t = labels.at(theme.lang)
+  let parts = ()
+  if "id" in theme.header-meta and id != none { parts.push(text(font: theme.font-mono, breakable(id))) }
+  if "version" in theme.header-meta and version != none { parts.push(box[#t.version #version]) }
+  if "date" in theme.header-meta and date != none { parts.push(box[#date]) }
+  if "owner" in theme.header-meta and owner != none { parts.push(box[#owner]) }
+  parts.join(h(4pt) + text(fill: theme.muted.lighten(60%), "|") + h(4pt))
+}
+
+// The document shell: page layout, header, footer, headings, watermark.
+#let doc(
+  theme: none,
+  title: "",
+  doc-id: none,
+  version: none,
+  date: none,
+  owner: none,
+  classification: none,
+  draft: false,
+  landscape: false,
+  body,
+) = {
+  let t = labels.at(theme.lang)
+  set document(title: title)
+  set page(
+    paper: theme.paper,
+    flipped: landscape,
+    margin: (x: theme.margin, top: 22mm, bottom: 16mm),
+    header-ascent: 30%,
+    footer-descent: 35%,
+    header: grid(
+      columns: (1fr, auto),
+      align: (left + bottom, right + bottom),
+      text(size: 7pt, fill: theme.muted.lighten(30%), _meta-line(theme, doc-id, version, date, owner)),
+      if theme.logo != none { image(theme.logo, height: 6.5mm) },
+    ),
+    footer: {
+      set text(size: 7pt, fill: theme.muted)
+      line(length: 100%, stroke: 0.5pt + theme.muted.lighten(70%))
+      v(-2pt)
+      grid(
+        columns: (1fr, auto, 1fr),
+        column-gutter: 8pt,
+        align: (left + horizon, center + horizon, right + horizon),
+        if classification != none { text(weight: "bold", tracking: 0.06em, fill: theme.danger, classification) },
+        if theme.footer-text != none { text(style: "italic", theme.footer-text) },
+        context [#t.page #counter(page).display() #t.of #counter(page).final().first()],
+      )
+    },
+    background: if draft {
+      rotate(-45deg, text(size: 110pt, weight: "bold", fill: theme.muted.transparentize(85%), t.draft))
+    },
+  )
+  set text(font: theme.font-body, size: 10pt, fill: theme.text, lang: theme.lang)
+  set par(justify: false, leading: 0.62em)
+  show raw: set text(font: theme.font-mono, size: 8.5pt)
+  show raw.where(block: true): it => block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%, it)
+  show heading: set text(font: theme.font-heading, fill: theme.primary)
+  show heading.where(level: 1): set text(size: 16pt)
+  show heading.where(level: 2): set text(size: 13pt)
+  show heading.where(level: 3): set text(size: 11pt)
+  show link: set text(fill: theme.accent)
+  // Tables have horizontal rules only: a stronger one under the header, a light one under every other row, no frame and
+  // no vertical lines; the first column is flush with the text. Tables that pass their own stroke keep it.
+  set table(
+    stroke: (x, y) => if y == 0 { (bottom: 0.7pt + theme.muted.lighten(35%)) } else { (bottom: 0.4pt + theme.muted.lighten(75%)) },
+    inset: (x, y) => (left: if x == 0 { 0pt } else { 6pt }, right: 6pt, y: 6pt),
+  )
+  set table.cell(breakable: false)
+  show table.header: set text(weight: "semibold")
+  body
+}
+
+// Title with the kind at its right, a hairline directly below, then an optional intro
+#let title-block(theme: none, title: "", kind: none, intro: none) = {
+  grid(
+    columns: (1fr, auto),
+    align: (left + bottom, right + bottom),
+    text(font: theme.font-heading, size: 22pt, weight: "bold", fill: theme.primary, breakable(title)),
+    if kind != none { text(size: 8pt, fill: theme.muted, kind) },
+  )
+  v(-4pt)
+  line(length: 100%, stroke: 0.5pt + theme.muted.lighten(70%))
+  if intro != none { block(above: 8pt, below: 6pt, text(size: 9pt, fill: theme.muted, intro)) }
+}
+
+// A cover page without header and footer: a band with the logo at its bottom left, kind, title and a short rule, the
+// document meta at the bottom left of the page. The pages after it are numbered from 1.
+#let cover-page(theme: none, title: "", kind: none, doc-id: none, version: none, date: none, owner: none, classification: none) = {
+  let t = labels.at(theme.lang)
+  page(header: none, footer: none, margin: 0mm, background: none)[
+    #block(width: 100%, height: 52mm, fill: theme.primary, inset: (x: theme.margin, bottom: 12mm), align(left + bottom, if theme.logo-light != none { image(theme.logo-light, height: 9mm) }))
+    #block(width: 100%, inset: (x: theme.margin, top: 34mm), {
+      if kind != none {
+        text(size: 7.5pt, weight: 600, tracking: 0.04em, fill: theme.accent, upper(kind))
+        v(2pt)
+      }
+      par(leading: 0.4em, text(font: theme.font-heading, size: 28pt, weight: "bold", fill: theme.primary, breakable(title)))
+      v(10pt)
+      line(length: 36mm, stroke: 2pt + theme.accent)
+    })
+    #let meta = (
+      (t.doc-id, if doc-id != none { text(font: theme.font-mono, breakable(doc-id)) }),
+      (t.version, version),
+      (t.date, date),
+      (t.owner, owner),
+      (t.classification, if classification != none { text(weight: "bold", fill: theme.danger, classification) }),
+    ).filter(m => m.at(1) != none)
+    #place(bottom + left, dx: theme.margin, dy: -20mm, grid(
+      columns: 2,
+      column-gutter: 14pt,
+      row-gutter: 7pt,
+      ..meta.map(((k, v)) => (text(size: 8pt, fill: theme.muted, k), text(size: 9pt, v))).flatten(),
+    ))
+    // the pages after the cover count from 1 (set inside the cover, so that nothing after it forces another page)
+    #counter(page).update(0)
+  ]
+}
+
+#let toc-page(theme: none, depth: 3) = {
+  let t = labels.at(theme.lang)
+  outline(title: t.contents, depth: depth)
+  pagebreak()
+}

data/lib/archsight/pdf/typst.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Archsight
+  module Pdf
+    # Building blocks for Typst source (https://typst.app). All text is emitted as Typst string literals
+    # (`#"..."`) and structure as function calls (`#strong[...]`), so no content can be mistaken for markup.
+    module Typst
+      LANGUAGE = /\A[A-Za-z0-9+#-]+\z/
+
+      module_function
+
+      # A Typst string literal, for use as a function argument
+      def lit(text)
+        escaped = text.to_s.delete("\r").gsub(/[\\"]/) { "\\#{Regexp.last_match(0)}" }.gsub("\n", "\\n")
+        "\"#{escaped}\""
+      end
+
+      # A Typst string literal as markup, for use inside content
+      def str(text)
+        "##{lit(text)}"
+      end
+
+      # A block of preformatted text
+      def raw(source, lang = nil)
+        lang_arg = lang.to_s.match?(LANGUAGE) ? ", lang: #{lit(lang)}" : ""
+        "#raw(#{lit(source.to_s.chomp)}, block: true#{lang_arg})"
+      end
+
+      # A short text on a coloured background (a status)
+      def badge(text, hex)
+        "#box(fill: #{color(hex)}, inset: (x: 4pt, y: 1pt), radius: 2pt)[#{str(text)}]"
+      end
+
+      # A framed message that stands where something could not be shown
+      def note(text, fill: "#fff3cc")
+        "#block(fill: #{color(fill)}, inset: 8pt, radius: 3pt, width: 100%)[#{str(text)}]"
+      end
+
+      # A Typst colour from `#rrggbb` / `#rgb`
+      def color(hex)
+        "rgb(#{lit(hex)})"
+      end
+    end
+  end
+end

data/lib/archsight/pdf.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require "fileutils"
+require_relative "pdf/compiler"
+require_relative "pdf/document"
+
+module Archsight
+  # PDF export of pages and resources, laid out by Typst (https://typst.app, installed as the `typst` command).
+  # See Archsight::Pdf::Document for what steers it and Archsight::Resources::Config (type pdf) for the look.
+  module Pdf
+    module_function
+
+    # @param resource [Archsight::Resources::Base] a page or any other resource
+    # @return [Archsight::Pdf::Document]
+    def document(database, resource, compiler: Compiler.new, **)
+      Document.new(database, resource, pdf_images: compiler.pdf_images?, **)
+    end
+
+    # The PDF of a prepared document
+    # @return [String]
+    # @raise [Unavailable, Error]
+    def compile(document, compiler: Compiler.new)
+      Dir.mktmpdir("archsight-pdf") do |dir|
+        document.files.each { |name, content| File.binwrite(File.join(dir, name), content) }
+        compiler.compile(dir, font_paths: document.font_paths)
+      end
+    end
+  end
+end

data/lib/archsight/references.rb

@@ -26,9 +26,10 @@ module Archsight
     # Adds the derived relations to every resource of the database.
     def derive!(database)
       finder = Finder.new(database)
+      includes = Helpers::DiagramIncludes.for(database)
       database.instances.values.flat_map(&:values).each do |inst|
         text_sources(inst).each { |markdown| mentions(markdown, finder).each { |target| link(inst, :mentions, target) } }
-        diagram_sources(inst, database).each { |source| depictions(source, finder).each { |target| link(inst, :depicts, target) } }
+        diagram_sources(inst, database).each { |source| depictions(source, finder, includes).each { |target| link(inst, :depicts, target) } }
       end
     end
 
@@ -44,8 +45,8 @@ module Archsight
     # The resources the nodes of a diagram source name with `resource "..."`; a source that is not a valid diagram
     # names none.
     # @return [Array<Base>]
-    def depictions(source, finder)
-      Diagram.resource_references(source).filter_map { |reference| finder.reference(reference) }
+    def depictions(source, finder, includes = nil)
+      Diagram.resource_references(source, includes: includes).filter_map { |reference| finder.reference(reference) }
     rescue Diagram::Error
       []
     end

data/lib/archsight/resources/application_component.rb

@@ -55,6 +55,13 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
     works in queries like a tag but is not a sidebar filter, as there are too many distinct values. Deployable forms (container image, chart, package) are `TechnologyArtifact`s, not
     component types.
 
+    ## Teams
+
+    A component 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. Both are optional; without a direct `maintainedBy`, the build team is the one that
+    maintains the component's `TechnologyArtifact`s.
+
     ## Where it runs
 
     A component is `servedBy` the `TechnologyService` it is deployed on (a product's cluster, a managed platform) and
@@ -426,6 +433,9 @@ class Archsight::Resources::ApplicationComponent < Archsight::Resources::Base
   relation :servedBy, :technologyComponents, :TechnologySystemSoftware
   relation :servedBy, :technologyServices, :TechnologyService
   relation :provisions, :technologyServices, :TechnologyService
+  relation :maintainedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessActors, :BusinessActor
+  relation :operatedBy, :businessRoles, :BusinessRole
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationComponents, :ApplicationComponent