archsight 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c249926b6ff6855b19ace38f11b9f256340e4d77cd00fe4d5f981fcbb0fd12f1
-  data.tar.gz: a0d7267da0223f8faed9a478a2c5ca029cdc23205fdff4feb945adb4d2b78f2e
+  metadata.gz: f7ada570ca5a5647d0cb9dc9f23b37d8adc9c0b6eff5420154c8ef3d30d9ea95
+  data.tar.gz: ba2e28e035b6d091fbfaeef71b0bc8d775f84c88541ecea0de86ba7d256bde42
 SHA512:
-  metadata.gz: 18ae964be21eded1e7be2560cd70a0ea63cb714c76b2d5295b3ec4b1f2b1fc46f5ec418591f53c5856babe389696b96be1436e905ee5ee2bc4b922ecee43d816
-  data.tar.gz: c8c8fbcba5d1f9db3b9d22c9fb2b1182569354fd08e2fd2cf44ba0bfe4b787ffac0446d48db5bd802f01269ea9ff6746383b2887bdf0a0f4b8d9e97e2ee2f9f6
+  metadata.gz: 739c46f505dfa73125839be21c2f0baaba7b4ba2a98926ca449a2cf87088cbc2c910c6b016c67ac7905540430927f94f2dc1b0bdce29735aec1ab29857390d7c
+  data.tar.gz: c259164f01f0d14e47dc5bf7f25a572a1a519dcc92ca788f3191274df5b6e0fd4d3d90fcdc5bc253bca6b454db464aa6ab46eaffa1f5a7f515b000a307506324

data/Dockerfile

@@ -25,6 +25,10 @@ ENV GEM_HOME=/usr/local/bundle
 ENV GEM_PATH=/usr/local/bundle:/usr/local/lib/ruby/gems/4.0.0
 ENV PATH="/usr/local/bundle/bin:${PATH}"
 
+# PDF export (Archsight::Pdf): typst typesets the documents, rsvg-convert turns the diagrams into vector graphics,
+# graphviz draws the dependency graph of a resource
+RUN apk add --no-cache typst rsvg-convert font-liberation font-dejavu font-noto-emoji graphviz
+
 RUN mkdir -p /resources
 
 ENV ARCHSIGHT_RESOURCES_DIR=/resources

data/docs/configuration.md

@@ -37,6 +37,11 @@ that is set but empty counts as not set.
 | `jira.server` | `ARCHSIGHT_JIRA_SERVER` | Name of the Jira server as Confluence knows it (the `server` parameter of its Jira macro). Needed by the Confluence export when Confluence has more than one Jira server: without it the exported `{jira:KEY}` macros have no server and Confluence shows an error |
 | `jira.server_id` | `ARCHSIGHT_JIRA_SERVER_ID` | Id of that server (the `serverId` parameter). Copy both from the storage format of a Jira macro that already works in Confluence (page "Edit in storage format") |
 | `jira.token` | `ARCHSIGHT_JIRA_TOKEN` | Reserved, nothing uses it yet |
+| `pdf.typst` | `ARCHSIGHT_PDF_TYPST` | Path of the `typst` command that typesets the [PDF export](/doc/pdf-export), if it is not on the `PATH` |
+| `pdf.dot` | `ARCHSIGHT_PDF_DOT` | Path of Graphviz' `dot` command that draws the dependency graph in the [PDF export](/doc/pdf-export), if it is not on the `PATH`. Without it the PDF of a resource has no graph |
+| `pdf.timeout` | `ARCHSIGHT_PDF_TIMEOUT` | Seconds a PDF may take to typeset before it is cancelled. Default `60` |
+| `pdf.remote_images` | `ARCHSIGHT_PDF_REMOTE_IMAGES` | `false` stops the PDF export from fetching images that a page embeds by URL (default: fetched, public hosts only) |
+| `pdf.max_analyses` | `ARCHSIGHT_PDF_MAX_ANALYSES` | How many `![[Analysis/...]]` embeds one PDF may run (each can take as long as its own timeout). Default `5`; further ones are shown as a note |
 | `import.cache_root` | `ARCHSIGHT_IMPORT_CACHE_ROOT` | Where the GitHub, GitLab and repository imports clone repositories, and what importers of the resources repository get as `cache_root` / `ARCHSIGHT_CACHE_DIR`. Default `~/.cache/archsight/git`; an import's own `import/config/cacheRoot` wins, see [Importers of the Resources Repository](/doc/import#importers-of-the-resources-repository). Every import makes sure the clones are not indexed by Spotlight (macOS): an empty `.metadata_never_index` in `~/.cache/archsight`, or in the cache root when it is elsewhere |
 
 ## Command line

data/docs/diagram.md

@@ -43,6 +43,7 @@ archsight diagram three_tier.asd --relation=all    # also show control/data-flow
 archsight diagram overview.asd --theme=compact     # denser spacing + smaller fonts (or cozy, tight)
 archsight diagram overview.asd --legend=bottom     # legend below (or right/left/top/none; default auto)
 archsight diagram *.asd                            # render every file to its own .svg
+archsight diagram app.asd --resources=model/       # resolve include \"file://...\" paths from this directory
 archsight diagram --format *.asd                   # re-indent the sources in place
 archsight diagram --format --check *.asd           # list unformatted sources, exit 1 if any (CI)
 ```
@@ -144,6 +145,11 @@ hint for near misses), never silently ignored.
 | `link` | nodes, containers | `http(s)://…`, `mailto:…` or a relative URL |
 | `resource` | nodes, containers | a resource name (`Archsight:Web`) or `Kind/Name` (`ApplicationService/Archsight:Web`); see *Linking to resources* |
 | `extend` | nodes, containers | `true`, `false`; containers also `height` |
+| `anchor` | containers | `top`, `bottom`, `left`, `right`, `center` |
+
+`extend "height"` on a direct child of a `layer` grows it to its tallest sibling. Inside such a box (also through a `boundary` around a `stack`), a `stack` child carrying `extend "height"` takes the extra height and moves the ranks below it down, so e.g. a footer rank lines up across the columns. The child can be a `layer` too; its own `extend "height"` children then fill the layer's new height.
+
+`anchor` says where a container's content sits when its box grows: `bottom` (or `top`) when it is made taller, `right` (or `left`) when it is made wider, `center` for the middle. Default: top for `extend "height"`, centered otherwise. It is not inherited, and has no effect on a box whose room is taken by a stack child with `extend "height"`.
 | `shape` | leaves | `rectangle`, `circle`, `cylinder`, `pipe`, `actor`, `file`, `module` |
 | `gap` | containers | pixels (`40`), a percentage (`150%`) or a signed one (`+20%`, `-50%`) |
 | `ranks` | containers | `auto`, `on`, `down`, `right`, `off` |
@@ -298,6 +304,69 @@ no broken styling. Library users pass a `resolver:` to `Diagram.render`
 (any `call(reference)` returning a URL, `nil` for a resource that exists but has nowhere to link to (the node stays as it is), `:missing` or `:ambiguous`, see
 `Archsight::Helpers::ResourceResolver`) and, to collect failures, `unresolved: []`.
 
+## Including diagrams
+
+`include "<path>"` splices another diagram in at that position, so a part
+that several diagrams share (a platform, a network, a team's services) is
+written once:
+
+```
+group "app" {
+  component "web" { label "Web server" }
+  stack {
+    include "archsight://ApplicationComponent/Platform:Database"
+  }
+}
+include "file://shared/network.asd"
+web -> db
+```
+
+The options of an `include` go in braces after the path (`namespace`, see below).
+
+| Path | Included diagram |
+|------|------------------|
+| `archsight://<Kind>/<name>` | the `architecture/diagram` annotation of that resource |
+| `file://<path>` | an `.asd` file, relative to the resources directory (also in nested includes) |
+
+A path that leaves the resources directory (`..`, absolute paths, symlinks
+pointing out) or is not an `.asd` file is refused. An `include` stands
+wherever a `layer` or `stack` can: at the top level or inside a container
+(not inside a leaf like `component`, and not together with `columns`). Included
+diagrams may include others (up to 8 levels, 100 includes in all; a cycle is an
+error). Nodes are one namespace across all of it, so an id defined twice is an
+error, and an edge in either part may name a node of the other.
+
+### Including a diagram more than once
+
+Ids are one namespace, so including the same diagram twice would define
+every node twice. A `namespace` puts `<namespace>.` in front of every id the
+included diagram defines (nodes and dataflows, and the references to them inside
+it):
+
+```
+include "archsight://ApplicationComponent/Platform:Server" { namespace "a" }
+include "archsight://ApplicationComponent/Platform:Server" { namespace "b" }
+a.web -> b.db
+```
+
+A node without a `label` keeps showing its own id (`web`, not `a.web`), and the same
+id from different includes no longer clashes. A reference inside the included diagram to an id it
+does not define names a node of the including diagram and stays as it is. Namespaces
+nest: a diagram included with `namespace "o"` that itself includes one with `namespace "in"` has
+`o.in.…` ids. A namespace is a name of letters, digits, `_` and `-`, joined by dots.
+
+Dataflows and `theme`/`legend`/`ranks` apply to the whole diagram: an included
+diagram holding them keeps them when it is included at the top level, and they are
+ignored, with a warning, when it is included inside a container. The warning is
+written to the server log and listed by `archsight lint`.
+
+A missing resource or file, a bad path or a broken included diagram fails the
+diagram with an error that names the include (`archsight lint` reports it). Standalone
+`archsight diagram` takes `file://` paths relative to `--resources DIR` (default:
+the directory of the input) and has no `archsight://`. Library users pass `includes:` to
+`Diagram.render`, any `call(path)` returning the source or `:missing`, `:forbidden` or `:invalid`
+(see `Archsight::Helpers::DiagramIncludes`), and `warnings: []` to collect the warnings.
+
 ## Diagrams in markdown
 
 A fenced code block tagged `asd` in any markdown the web UI renders (docs,

data/docs/index.md.erb

@@ -8,6 +8,7 @@ Welcome to the Architecture Documentation System. This documentation covers how
 - [Configuration](/doc/configuration) - The configuration file and environment variables for tokens and URLs
 - [Query Syntax](/doc/search) - Search and filter resources
 - [Wiki Pages](/doc/pages) - Author markdown pages and arrange them in the sidebar tree
+- [PDF Export](/doc/pdf-export) - Download pages and resources as PDF, with a Config for the look
 - [Architecture Modeling](/doc/modeling) - How to model your architecture
 - [REST API Documentation](/docs/api) - JSON API for programmatic access
 - [Diagrams](/doc/diagram) - Render `.asd` diagram files to SVG

data/docs/modeling.md

@@ -36,7 +36,7 @@ There are two families of verbs:
 
 | Family | Verbs | Written on | Points to |
 |--------|-------|------------|-----------|
-| Responsibility and provider (down) | `performedBy`, `ownedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `representedBy`, `realizedThrough`, `exposes`, `provisions`, `connects`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
+| Responsibility and provider (down) | `performedBy`, `ownedBy`, `operatedBy`, `executedBy`, `servedBy`, `guidedBy`, `maintainedBy`, `contributedBy`, `hasConcern`, `representedBy`, `realizedThrough`, `exposes`, `provisions`, `connects`, `mitigatedBy`, `influences`, `triggers`, `affects`, `assesses`, `contains`, `closedBy`, `compares` | the element that needs, uses or is concerned with something | what provides it or is responsible for it |
 | Realization (up) | `realizes`, `partiallyRealizes`, `plans`, `satisfies`, `evidencedBy` (on the evidenced element), `provides` | the concrete element | the abstract element it answers to (requirement, goal, capability, plateau) |
 
 Rules:
@@ -616,6 +616,8 @@ Relations are written on the element that is placed (see [Direction of Relations
 | `TechnologyFacility` | `composedOf` | `TechnologyFacility` (nested sites, the rooms of a data center) |
 | `TechnologyFacility` | `servedBy` | `BusinessActor` (the operator) |
 | `TechnologyDevice`, `TechnologyEquipment`, `TechnologyNode`, `TechnologyCommunicationNetwork` | `ownedBy` | `BusinessActor`, `BusinessRole` (the team that operates it) |
+| `ApplicationComponent`, `ApplicationService`, `TechnologyService` | `operatedBy` | `BusinessActor`, `BusinessRole` (the team that runs it in production) |
+| `ApplicationComponent`, `ApplicationService`, `TechnologyService` | `maintainedBy` | `BusinessActor` (the team that builds and changes it) |
 | `TechnologyDevice`, `TechnologyEquipment`, `TechnologyNode` | `servedBy` | `BusinessActor` (the team it is dedicated to, e.g. a test partition) |
 
 `locatedAt` with many targets is the point: a service that runs in three data centers is **one** service with three

data/docs/pdf-export.md

@@ -0,0 +1,118 @@
+# PDF Export
+
+Every [page](/doc/pages) and every resource can be downloaded as a PDF. The document is typeset by [Typst](https://typst.app),
+so the server (or the machine running the CLI) needs the `typst` command; the container image has it, together with
+`rsvg-convert` (turns diagrams into vector graphics), `dot` of Graphviz (draws the dependency graph) and a few fonts.
+
+## Getting a PDF
+
+- **Web UI:** the **PDF** button next to **Edit** on a page or resource.
+- **API:** `GET /api/v1/pages/{name}/pdf` and `GET /api/v1/kinds/{kind}/instances/{name}/pdf`, see the [REST API documentation](/docs/api).
+  The response has an `ETag` that changes whenever the page, an image, a diagram or the template changes.
+  Query parameters: `template` (name of a pdf Config) and `draft=1` (watermark).
+- **CLI:** `archsight pdf <page>` or `archsight pdf Kind/Name`, with `-o file.pdf`, `--template` and `--draft`.
+
+Without `typst` the API answers `503` and the button shows the reason.
+
+## What is in the document
+
+- A **page** is typeset as written: headings, text, tables (with their alignment), task lists, code, images next to the page,
+  `asd` diagrams (as vector graphics), `[[links]]` (as their label), `{status:...}` (a coloured box), `{jira:KEY}` (a link
+  when `jira.issue_url` is set) and `{emoticon:...}`. Macros that need the running application (`{children}`) are left out.
+  Mermaid blocks and draw.io images cannot be drawn on the server: a note stands there (and the Mermaid source).
+- **Tables** have horizontal rules only: a stronger one under the header row and a light one under every other row, no frame
+  and no vertical lines, in the muted colour of the Config; the first column is flush with the text.
+- **Live content is the data of the moment of the export**, as in the Confluence export:
+  - `![[View/Name]]` and ```` ```view ```` blocks are tables (title, number of items, repeated header row; long columns
+    share the width), `` ```requirements `` blocks are the requirements table.
+  - `![[Analysis/Name]]` runs the analysis and puts its sections (headings, text, tables, lists, messages) into the document.
+    An analysis runs for as long as its own `analysis/timeout` allows, so at most 5 run per document (`pdf.max_analyses`),
+    and a result is reused for a minute. A failed analysis shows its error.
+  - `![[Kind/Name]]` of another kind is the resource's description.
+  - Only an embed on a line of its own (or several, one per line) is content; inside a sentence it stays its name.
+  - What cannot be shown (unknown or ambiguous reference, an invalid view or requirements block) is a visible note in the
+    document, never blank space. Embeds inside an embedded description are not expanded again.
+- **Images by URL** (`![](https://...)`) are fetched by the server so they can go into the PDF. Only public hosts on https/http
+  are contacted (never loopback, private or link-local addresses, so the server cannot be used to reach the network
+  behind it), at most 10 MB and 10 seconds each, and only real png, jpeg, gif or webp files are used; otherwise the alt text
+  is shown. `pdf.remote_images: false` turns this off.
+- Any other **resource** becomes a generated document: its description, its properties, its relations and its
+  `architecture/diagram`, and its **dependency graph**, shown first, as on its page (the resources its relations lead to, two steps
+  deep, following its own layer and the one below it, nodes coloured by layer), drawn by `dot` in the direction, left to
+  right or top to bottom, in which it is larger on the page. A resource without
+  relations has no graph, and without `dot` the document is made without it. Properties are a label and value list (related annotations kept together; lists as "a, b";
+  multi-line and markdown values as sections of their own). Relations are shown in both directions, **Outgoing** (what this
+  resource points to) and **Incoming** (what points to it, read from the other side): the relation is named once, with the
+  kind next to it and the resources flowing in two columns, so a resource with many relations stays readable.
+
+## Steering the layout with tags
+
+Tags of the page (`tags:` in the frontmatter) or of a resource (`architecture/tags`):
+
+| Tag | Effect |
+|-----|--------|
+| `pdf:cover` | A cover page (logo band, title, id, version, date, owner) instead of the title block |
+| `pdf:toc` | A table of contents |
+| `pdf:landscape` | Landscape pages |
+| `pdf:draft` | A "draft" watermark on every page |
+| `pdf:no-graph` | Leave the dependency graph out of a resource's document |
+| `pdf:template:<name>` | Use the pdf Config `<name>` instead of `default` |
+| `version:<x>` | The document version in the header (else the page property `Version`, else `1`) |
+
+Further page data used by the layout: `title`, `owner` (else `author`), `updated` (else today), and the page properties
+`Document ID` (default `Kind/name`) and `Classification` (red marking in the footer, default from the template).
+
+## The look: Config
+
+A `Config` resource (layer *Other*) holds settings of a feature of the tool, kept with the model; `config/type` says
+which feature. The PDF export reads the Configs of type `pdf`: colours, fonts, logo and the text around the pages. The one
+named `default` is used for every document that does not name another (`pdf:template:<name>`); `brand`, `PDF:brand` and
+`Config:PDF:brand` all name the same Config. Without any a neutral look is used. A Config of another type is never used
+for the PDF, so every feature can have its own `default`. (The per-user file with tokens and URLs stays
+[`~/.config/archsight/archsight.yaml`](/doc/configuration).)
+
+```yaml
+apiVersion: architecture/v1alpha1
+kind: Config
+metadata:
+  name: Config:PDF:default
+  annotations:
+    config/type: pdf
+    pdf/color-primary: "#1f3a5f"
+    pdf/color-accent: "#2f7fd1"
+    pdf/logo: assets/logo.svg
+    pdf/logo-light: assets/logo-white.svg
+    pdf/footer-text: Generated with Archsight
+    pdf/classification: Internal
+    pdf/font-body: Open Sans
+    pdf/font-dir: assets/fonts
+spec: {}
+```
+
+| Annotation | Meaning |
+|------------|---------|
+| `config/type` | `pdf` for these settings |
+| `pdf/color-primary`, `-accent`, `-text`, `-muted`, `-ok`, `-warn`, `-danger` | Hex colours (`#rrggbb`) |
+| `pdf/font-body`, `-heading`, `-mono` | Font families, tried before the built-in fallbacks |
+| `pdf/font-dir` | Directory (relative to the resources directory) with font files (ttf, otf) that ship with the model |
+| `pdf/logo`, `pdf/logo-light` | svg or png, relative to the resources directory. `logo` is shown on white (page header), `logo-light` on the cover band |
+| `pdf/footer-text`, `pdf/classification` | Texts in the footer of every page |
+| `pdf/header-meta` | Parts of the header line: `id, version, date, owner` |
+| `pdf/lang` | Language of the fixed texts: `en` or `de` |
+| `pdf/paper`, `pdf/margin` | `a4`, `a5` or `us-letter`; horizontal margin such as `16mm` |
+
+Values are checked when they are loaded (and by `archsight lint`): something that is not a colour, a font name or a length is
+ignored and the default is used.
+
+## Seeing the look
+
+The page of a Config of type `pdf` shows its settings as they look (the colours, the fonts, the logo on white and on
+the cover band, the page settings) and, beside them, a **preview**: a fixed sample document (a cover page and a page with
+headings, a list, a quote, a table with status badges and code) typeset by the server with exactly these settings, one
+tab for the cover and one for the page. It shows the saved Config; after an edit the page typesets it again.
+The same sample is `GET /api/v1/kinds/Config/instances/{name}/preview` (`?part=cover` or `?part=page` for one page).
+
+## Settings
+
+`pdf.typst` (`ARCHSIGHT_PDF_TYPST`) is the path of the `typst` command if it is not on the `PATH`, `pdf.dot` (`ARCHSIGHT_PDF_DOT`) the same for `dot`, `pdf.timeout`
+(`ARCHSIGHT_PDF_TIMEOUT`) the seconds a document may take (default 60), `pdf.remote_images` (`ARCHSIGHT_PDF_REMOTE_IMAGES`) `false` to never fetch images by URL, `pdf.max_analyses` (`ARCHSIGHT_PDF_MAX_ANALYSES`) the number of analyses one document may run (default 5). See [Configuration](/doc/configuration).

data/lib/archsight/analysis/typst_renderer.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "../markdown"
+require_relative "../pdf/typst"
+require_relative "../pdf/markdown"
 require_relative "../diagram"
 
 module Archsight
@@ -10,20 +12,18 @@ module Archsight
     # All text is emitted as Typst string literals (`#"..."`) and structure as
     # function calls (`#strong[...]`), so no content can be mistaken for markup.
     class TypstRenderer
+      include Archsight::Pdf::Typst
+
       ROW_LIMIT = 10
       HEADING_OFFSET = 2 # section level 0 becomes a level-2 heading, the analysis name is level 1
-      LANGUAGE = /\A[A-Za-z0-9+#-]+\z/
       MESSAGE_FILL = { error: "rgb(\"#fde8e8\")", warning: "rgb(\"#fff3cc\")", info: "rgb(\"#ddeeff\")" }.freeze
-      SYMBOLS = {
-        ndash: "–", mdash: "—", hellip: "…", laquo: "«", raquo: "»", laquo_space: "« ", raquo_space: " »",
-        lsquo: "‘", rsquo: "’", ldquo: "“", rdquo: "”"
-      }.freeze
 
       PREAMBLE = <<~TYPST
         #set document(title: "Archsight analysis")
         #set page(paper: "a4", margin: 2cm, numbering: "1")
         #set text(size: 10pt)
         #show raw.where(block: true): it => block(fill: luma(245), inset: 8pt, radius: 3pt, width: 100%, it)
+        #set table(stroke: (x, y) => if y == 0 { (bottom: 0.7pt + luma(150)) } else { (bottom: 0.4pt + luma(220)) }, inset: (x, y) => (left: if x == 0 { 0pt } else { 6pt }, right: 6pt, y: 6pt))
       TYPST
 
       # @param results [Array<Archsight::Analysis::Result>]
@@ -31,10 +31,12 @@ module Archsight
       # @param template [String, nil] Typst file to import instead of the built-in layout. It must define
       #   `archsight-report` (a show rule for the document) and `analysis-result` (one call per analysis,
       #   with the data sections as a dictionary and the other sections as body).
-      def initialize(results, verbose: false, template: nil)
+      # @param full [Boolean] show every table row and list item, without the error backtrace of `verbose`
+      def initialize(results, verbose: false, template: nil, full: false)
         @results = results
         @verbose = verbose
         @template = template
+        @full = full
       end
 
       # @return [String] Typst source
@@ -44,6 +46,17 @@ module Archsight
         [PREAMBLE, title, summary, *@results.map { |result| render_result(result) }].join("\n")
       end
 
+      # One section of a result as Typst markup (nil for data that only templates use)
+      # @param heading_offset [Integer] added to the level of a heading section
+      def section(section, heading_offset: HEADING_OFFSET)
+        render_section(section, heading_offset)
+      end
+
+      # The error of a failed result as Typst markup
+      def error(result)
+        error_block(result)
+      end
+
       private
 
       def title
@@ -120,9 +133,9 @@ module Archsight
         lines.join("\n\n")
       end
 
-      def render_section(section)
+      def render_section(section, heading_offset = HEADING_OFFSET)
         case section[:type]
-        when :heading then "#heading(level: #{[section[:level] + HEADING_OFFSET, 6].min})[#{str(section[:text])}]"
+        when :heading then "#heading(level: #{[section[:level] + heading_offset, 6].min})[#{str(section[:text])}]"
         when :text then markdown(section[:content])
         when :table then table(section[:headers], section[:rows])
         when :list then list(section[:items])
@@ -139,15 +152,14 @@ module Archsight
 
       # A template produces a document to hand out, so it gets every row
       def full?
-        @verbose || !@template.nil?
+        @verbose || @full || !@template.nil?
       end
 
       def table(headers, rows)
         shown = full? ? rows : rows.first(ROW_LIMIT)
-        head = headers.map { |header| "[#strong[#{str(header)}]]" }
+        head = headers.map { |header| "[#text(weight: \"semibold\")[#{str(header)}]]" }
         cells = shown.flat_map { |row| headers.each_index.map { |i| "[#{str(row[i])}]" } }
-        out = "#table(columns: #{headers.size}, inset: 5pt, stroke: 0.5pt + luma(200), " \
-              "table.header(#{head.join(", ")}), #{cells.join(", ")})"
+        out = "#table(columns: #{headers.size}, table.header(#{head.join(", ")}), #{cells.join(", ")})"
         out += "\n\n#emph[#{str("...and #{rows.size - ROW_LIMIT} more rows")}]" if shown.size < rows.size
         out
       end
@@ -172,73 +184,8 @@ module Archsight
         [message_block(:error, "Diagram could not be rendered: #{e.message}"), raw(source, "asd")].join("\n\n")
       end
 
-      def raw(source, lang)
-        lang_arg = lang.to_s.match?(LANGUAGE) ? ", lang: #{lit(lang)}" : ""
-        "#raw(#{lit(source.to_s.chomp)}, block: true#{lang_arg})"
-      end
-
-      # 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
-
-      # ---- markdown -> Typst
-
       def markdown(source, inline: false)
-        root = Archsight::Markdown.document(source).root
-        out = blocks(root.children)
-        inline ? out.gsub(/\n\n+/, " #linebreak() ") : out
-      end
-
-      def blocks(elements)
-        elements.filter_map { |node| block(node) }.join("\n\n")
-      end
-
-      def block(node)
-        case node.type
-        when :p then inlines(node.children)
-        when :header then "#heading(level: #{[node.options[:level] + 1, 6].min})[#{inlines(node.children)}]"
-        when :codeblock then raw(node.value, node.options[:lang])
-        when :blockquote then "#quote(block: true)[#{blocks(node.children)}]"
-        when :ul then "#list(#{node.children.map { |li| "[#{blocks(li.children)}]" }.join(", ")})"
-        when :ol then "#enum(#{node.children.map { |li| "[#{blocks(li.children)}]" }.join(", ")})"
-        when :hr then "#line(length: 100%)"
-        when :table then markdown_table(node)
-        when :blank, :html_element, :xml_comment then nil
-        else inlines(node.children) unless node.children.empty?
-        end
-      end
-
-      def markdown_table(node)
-        rows = node.children.flat_map(&:children)
-        cells = rows.map { |tr| tr.children.map { |td| "[#{inlines(td.children)}]" } }
-        width = cells.map(&:size).max || 1
-        "#table(columns: #{width}, inset: 5pt, stroke: 0.5pt + luma(200), #{cells.flatten.join(", ")})"
-      end
-
-      def inlines(elements)
-        elements.map { |node| inline(node) }.join
-      end
-
-      def inline(node)
-        case node.type
-        when :text then str(node.value)
-        when :em then "#emph[#{inlines(node.children)}]"
-        when :strong then "#strong[#{inlines(node.children)}]"
-        when :codespan then "#raw(#{lit(node.value)})"
-        when :a then "#link(#{lit(node.attr["href"])})[#{inlines(node.children)}]"
-        when :br then "#linebreak()"
-        when :entity then str(node.value.char)
-        when :smart_quote, :typographic_sym then str(SYMBOLS.fetch(node.value, node.value.to_s))
-        when :html_element then inlines(node.children)
-        else inlines(node.children)
-        end
+        Archsight::Pdf::Markdown.new(heading_offset: 1, diagram: method(:diagram)).render(source, inline: inline)
       end
     end
   end

data/lib/archsight/cli.rb

@@ -279,6 +279,7 @@ module Archsight
     option :theme, type: :string, desc: "Spacing/font-size theme (default: the file's own `theme` statement)"
     option :legend, type: :string, desc: "Legend placement (default: the file's own `legend` statement, else auto)"
     option :profile, aliases: "-p", type: :boolean, desc: "Print stage timing stats after each render"
+    option :resources, aliases: "-r", type: :string, desc: "Directory that `include \"file://...\"` paths are relative to (default: the input's directory)"
     option :format, type: :boolean, desc: "Re-indent the inputs in place instead of rendering them (-o: write a single input there)"
     option :check, type: :boolean, desc: "With --format: only list the inputs that are not formatted, exit 1 if any"
     def diagram(*inputs)
@@ -295,7 +296,7 @@ module Archsight
 
       status = diagram::CLI.new.run_with(
         inputs: inputs, output: options[:output], watch: options[:watch], profile: options[:profile],
-        format: options[:format], check: options[:check],
+        format: options[:format], check: options[:check], resources: options[:resources],
         style: options[:style], theme: options[:theme], legend: options[:legend],
         relation_filter: if relation.nil?
                            diagram::Relations::DEFAULT_FILTER
@@ -355,6 +356,43 @@ module Archsight
       exit 1
     end
 
+    desc "pdf TARGET", "Export a page or resource as PDF (needs typst)"
+    long_desc <<~DESC
+      Typesets a page (TARGET is its name) or any other resource (TARGET is Kind/Name) as a PDF with Typst, the same
+      document the PDF button of the web UI downloads. The look comes from the Config of type pdf named default (or --template),
+      the tags pdf:cover, pdf:toc, pdf:landscape, pdf:draft and pdf:template:<name> steer the layout. The typst command
+      is taken from the PATH, or from ARCHSIGHT_PDF_TYPST / `pdf.typst` in ~/.config/archsight/archsight.yaml.
+      See the PDF Export page of the documentation.
+    DESC
+    option :output, aliases: "-o", type: :string, desc: "Output file (default: <name>.pdf in the current directory)"
+    option :template, type: :string, desc: "Name of the pdf Config to use (default: the tag or `default`)"
+    option :draft, type: :boolean, default: false, desc: "Add the draft watermark"
+    def pdf(target)
+      configure_resources
+      require "archsight/database"
+      require "archsight/pdf"
+
+      db = Archsight::Database.new(Archsight.resources_dir, compute_annotations: false)
+      begin
+        db.reload!
+      rescue Archsight::ResourceError => e
+        display_error_with_context(e.to_s)
+        exit 1
+      end
+
+      kind, name = target.include?("/") ? target.split("/", 2) : ["Page", target]
+      resource = Archsight::Resources[kind] && (db.instance_by_kind(kind, name) || db.instance_by_alias(kind, name))
+      abort "Error: #{kind} '#{name}' not found" unless resource
+
+      document = Archsight::Pdf.document(db, resource, template: options[:template], draft: options[:draft])
+      file = options[:output] || document.filename
+      File.binwrite(file, Archsight::Pdf.compile(document))
+      puts "Wrote #{file}"
+    rescue Archsight::Pdf::Error => e
+      warn "Error: #{e.message}"
+      exit 1
+    end
+
     desc "module SUBCOMMAND", "Module analysis commands (e.g. module graph PATH)"
     subcommand "module", ModuleCLI
 

data/lib/archsight/database.rb

@@ -109,11 +109,12 @@ module Archsight
       matches.first if matches.one?
     end
 
-    # Collect unique annotation values across all instances of a kind
+    # Annotation values across all instances of a kind with the number of instances using each,
+    # most used first (ties by value): [[value, count], ...]
     def annotation_values(kind, annotation)
       instances = instances_by_kind(kind).values
-      values = instances.flat_map { |inst| Array(annotation.value_for(inst)) }
-      values.compact.uniq.sort
+      counts = instances.flat_map { |inst| Array(annotation.value_for(inst)).compact.uniq }.tally
+      counts.sort_by { |value, count| [-count, value.to_s] }
     end
 
     # Get filterable annotations with their values for a kind (excludes empty)

data/lib/archsight/diagram/cli.rb

@@ -3,6 +3,7 @@
 require "optparse"
 require_relative "."
 require_relative "formatter"
+require_relative "../helpers/diagram_includes"
 
 module Archsight
   module Diagram
@@ -79,6 +80,8 @@ module Archsight
           opts.on("-p", "--profile", "Print stage timing stats after each render") do
             options[:profile] = true
           end
+          opts.on("--resources=DIR", "Directory that include \"file://...\" paths are relative to " \
+                                     "(default: the input file's directory)") { |v| options[:resources] = v }
           opts.on("--format", "Re-indent the inputs in place instead of rendering them (-o: write a single input there)") do
             options[:format] = true
           end
@@ -155,7 +158,9 @@ module Archsight
         total_start = Process.clock_gettime(Process::CLOCK_MONOTONIC) if profile
 
         svg = Archsight::Diagram.render(File.read(input), relation_filter: options[:relation_filter], profile: stats,
-                                                          style: options[:style], theme: options[:theme], legend: options[:legend])
+                                                          style: options[:style], theme: options[:theme], legend: options[:legend],
+                                                          includes: includes_for(input, options), warnings: warnings = [])
+        warnings.each { |message| warn "archsight-diagram: #{input}: #{message}" }
 
         write_start = Process.clock_gettime(Process::CLOCK_MONOTONIC) if profile
         File.write(output, svg)
@@ -172,6 +177,11 @@ module Archsight
         1
       end
 
+      # Standalone, `include` reads `file://` paths only (there is no model for `archsight://`)
+      def includes_for(input, options)
+        Helpers::DiagramIncludes.new(nil, resources_dir: options[:resources] || File.dirname(File.expand_path(input)))
+      end
+
       def print_stats(stats, total_start)
         total = Process.clock_gettime(Process::CLOCK_MONOTONIC) - total_start
         parts = stats.map { |key, seconds| "#{key}=#{format("%.1fms", seconds * 1000)}" }

data/lib/archsight/diagram/errors.rb

@@ -5,5 +5,6 @@ module Archsight
     class Error < StandardError; end
     class ParseError < Error; end
     class GraphError < Error; end
+    class IncludeError < Error; end
   end
 end

data/lib/archsight/diagram/graph/attributes.rb

@@ -27,13 +27,14 @@ module Archsight
         NODE = %w[label tint link resource extend].freeze
         LEAF_KINDS = %i[component application api database queue actor file].freeze
         LEAF = (NODE + %w[shape]).freeze
-        CONTAINER = (NODE + %w[gap ranks columns]).freeze
+        CONTAINER = (NODE + %w[gap ranks columns anchor]).freeze
         EDGE = %w[label style relation tint].freeze
         DATAFLOW = %w[label color].freeze
 
         EDGE_STYLES = %w[straight orthogonal].freeze
         LEAF_EXTEND = %w[true false].freeze
         CONTAINER_EXTEND = %w[true false height].freeze
+        ANCHORS = %w[top bottom left right center].freeze
 
         # `40` (pixels), `150%` (of the default), `+20%`/`-50%` (relative);
         # see `GapSpec`.
@@ -116,6 +117,7 @@ module Archsight
           when "tint" then check_value!(key, value, Tints.names, where, line)
           when "ranks" then check_value!(key, value, ranks_modes, where, line)
           when "extend" then check_value!(key, value, leaf?(block) ? LEAF_EXTEND : CONTAINER_EXTEND, where, line)
+          when "anchor" then check_value!(key, value, ANCHORS, where, line)
           when "gap" then check_format!(key, value, GAP_FORMAT, "a pixel count (40), a percentage (150%) or a signed one (+20%, -50%)", where, line)
           when "link" then check_link!(value, where, line)
           when "resource" then check_resource!(value, block, where, line)

data/lib/archsight/diagram/graph/node.rb

@@ -130,11 +130,28 @@ module Archsight
         # `extend "height"` on a direct child of a `layer` grows that
         # child's box to its tallest sibling's height, leaving its own
         # content top-aligned where it already sits. Never inherited --
-        # only the node carrying the attr is affected.
+        # only the node carrying the attr is affected. In a `stack` inside such a
+        # grown box it absorbs the extra height instead (see
+        # `Expander#grow_height`).
         def extend_height?
           attrs["extend"] == "height"
         end
 
+        # Where this container's content sits when its box grows by `extra`
+        # along `axis`: the `anchor` attr (`top`/`bottom` for height,
+        # `left`/`right` for width, `center`), else `default`. Returns how
+        # far to shift the children (0 = leading edge, `extra` = trailing).
+        # Never inherited; a value for the other axis is ignored.
+        def anchor_shift(axis, extra, default:)
+          value = attrs["anchor"]
+          value = default.to_s unless (axis == Axis::HEIGHT ? %w[top bottom center] : %w[left right center]).include?(value)
+          case value
+          when "top", "left" then 0.0
+          when "bottom", "right" then extra.to_f
+          else extra / 2.0
+          end
+        end
+
         def link
           attrs["link"]
         end