archsight 0.3.3 → 0.4.1

data/docs/pages.md

@@ -18,7 +18,9 @@ properties:
   Git Repository: https://git.example.com/org/language-strategy
   Ticket: "{jira:ARCH-42}"
 toc: yes
-confluence: https://confluence.example.com/spaces/ARCH/pages/12345/Language+Strategy
+links:
+  confluence: https://confluence.example.com/spaces/ARCH/pages/12345/Language+Strategy
+  jira: https://jira.example.com/browse/ARCH-12
 ---
 
 # Language Strategy
@@ -34,7 +36,7 @@ confluence: https://confluence.example.com/spaces/ARCH/pages/12345/Language+Stra
 | `properties` | Everything else you want to record, as a mapping of `key: value` pairs (kept in order and shown in the page header). Values are inline markdown: links, emphasis, `{macros}` such as `{jira:KEY}` and `[[wiki links]]` work, bare URLs become links. In the API and in queries it is `page/properties`, one `Key: value` per line |
 | `status` | Free text, e.g. `rfc`, `wip`, `approved` |
 | `toc` | `yes` shows a table of contents |
-| `confluence` | URL of the corresponding Confluence page, shown as a link |
+| `links` | A mapping of names to URLs: where the page lives in other systems (`confluence`, `jira`, `github`, ...), shown as links with the icon of the system. Each entry is the annotation `link/<name>` (`link/confluence`), the same links every other resource can have; a link has no direction, it is where the page comes from or where it is published to. The old `confluence: <url>` key still works, is reported as deprecated by `archsight lint` and is moved into `links` when the page is saved in the editor |
 | `name` | Optional unique name; defaults to the file name without `.md`. Files with the same name in different folders need an explicit `name` |
 
 Markdown files without a frontmatter block are ignored.
@@ -128,21 +130,27 @@ is served:
   such requests, so an image embedded in a diagram from an `https://` URL is not shown. Formulas are not typeset.
 - **Kubernetes**: binary files do not fit a ConfigMap (1 MB limit), provide the resources with git-sync or a volume.
 
-## Embedding views and analyses
+## Embedding views, analyses and descriptions
 
 `![[View/Name]]` and `![[Analysis/Name]]` show the live content of a view (its result list) or an analysis (its
-result) inside a page, or in the description of any resource:
+result) inside a page, or in the description of any resource. Any other resource, written `![[Kind/Name]]`, shows its
+description (`architecture/description`), for example the goal a concept is written for:
 
 ```markdown
 ![[View/View:ServiceDependencies]]
 ![[Analysis/Analysis:Service:Count]]
+![[MotivationGoal/Goal:SimplifyArchitecture]]
 ```
 
+The **Embed** button on the page of a resource, view or analysis copies its `![[Kind/Name]]`. An embedded description
+is set off like a quote and links to its resource; `![[...]]` embeds inside it are shown as links (two descriptions
+cannot embed each other without end). Pages cannot be embedded.
+
 The page is shown immediately. Each embed loads on its own, with a spinner, and an analysis runs when the page opens
-(it can be run again from the embed), so a slow query or script never delays the text around it. The embed
+(reload the page to run it again), so a slow query or script never delays the text around it. The embed
 links to the view or analysis page. The server only writes a placeholder: rendering a page (`GET /api/v1/pages/{name}`)
 never runs a query or a script, and API or MCP consumers get `<div class="kind-embed" data-kind data-name>` with a plain
-link to the resource. Other kinds are not embeddable; an unknown name, another kind or an embed written inline in
+link to the resource. An unknown name, a page or an embed written inline in
 a sentence (instead of on its own line) is shown as a marker or a link, and `archsight lint` reports embeds that do not
 resolve. Code blocks and inline code are left alone.
 
@@ -269,16 +277,26 @@ The form has the frontmatter keys as fields and the body as a markdown field (ri
 conflict if the file changed since the form was opened, and a file with broken frontmatter, without
 frontmatter or with a changed name is rejected before it is written.
 
-The saved frontmatter is rewritten in the order `title, tags, author, owner, status, toc, confluence`.
-`name` and keys the form does not know are kept; YAML comments inside the frontmatter are not.
+The saved frontmatter is rewritten in the order `title, tags, author, owner, status, toc, created, updated, properties`.
+`name`, `links` and keys the form does not know are kept (an old `confluence:` key becomes `links: { confluence: ... }`); YAML comments inside the frontmatter are not.
 
 Inside the rich editor, an ` ```asd ` block shows a live [diagram preview](/doc/diagram#preview-in-the-editor).
 
+### Migrating `confluence:` to `links`
+
+`archsight lint` lists every page that still uses `confluence:` (or `page/confluence`) as a deprecation without failing.
+Pages written as markdown can be moved with a find and replace over the resources directory; a page that has `links`
+already keeps that value:
+
+```bash
+find resources -name '*.md' -exec perl -0pi -e 's/^confluence:\s*(\S+)\s*$/links:\n  confluence: $1/m' {} +
+```
+
 ## Exporting to Confluence
 
-`archsight export --to confluence [PAGE...]` publishes pages to the Confluence page named in their `confluence:` frontmatter
+`archsight export --to confluence [PAGE...]` publishes pages to the Confluence page named in their `links.confluence` frontmatter
 (Confluence Data Center; a page URL such as `https://host/spaces/KEY/pages/12345/Title`, `.../pages/viewpage.action?pageId=12345`
-or `.../display/KEY/Title`). Without `PAGE` every page that has a `confluence:` link is exported.
+or `.../display/KEY/Title`). Without `PAGE` every page that has a `confluence` link is exported.
 
 ```bash
 archsight export --to confluence -r resources                 # all linked pages
@@ -290,8 +308,13 @@ archsight export --to confluence handbook-home --force        # overwrite change
 **Page properties**: the frontmatter is exported as a Page Properties table (the `details` macro) above the body, so Confluence
 keeps its property reports working: Document status (a status lozenge; `wip`/`draft` yellow, `rfc`/`review` blue,
 `approved`/`done`/`ga` green, `deprecated`/`rejected` red, anything else grey), Document owner, Document author, Teams (the
-`Team:<name>` tags), Tags and every entry of `properties`. People are written as their name. `created` and `updated` are not
-exported. The Confluence import (not part of Archsight) does the reverse, which is why `Team:` tags and `properties` exist.
+`Team:<name>` tags) and every entry of `properties`. People are written as their name. `created` and `updated` are not
+exported, and neither are the other tags: they are the page's labels (below). The Confluence import (not part of Archsight) does the reverse, which is why `Team:` tags and `properties` exist.
+
+**Labels**: the tags of a page become its Confluence labels, so label macros and searches find the page. A label is
+lowercase without spaces or `!#&()*,.:;<>?@[]^`, those become a dash (`Team:BSS` is the label `team-bss`). A tag that is
+removed removes the label again, but only labels the export added itself (recorded in the marker): labels somebody set
+in Confluence stay. Labels are not versioned, so a page whose labels alone change gets no new version.
 
 **Credentials** are a personal access token, set as `confluence.token` in the [configuration file](/doc/configuration)
 (`~/.config/archsight/archsight.yaml`, `--config PATH` for another file) or in `ARCHSIGHT_CONFLUENCE_TOKEN`. The host comes from
@@ -316,9 +339,9 @@ confluence:
 With `drawio` off nothing draw.io-specific is written, so any Confluence shows the diagrams. Rendering a `.drawio` needs the
 draw.io desktop CLI (`drawio`, or `ARCHSIGHT_DRAWIO_CLI`) on the machine that exports; the preview of an SVG needs
 `rsvg-convert` or that CLI. A diagram that cannot be rendered fails the page instead of leaving a blank diagram. Attachments an
-earlier export added and the page no longer uses are removed; attachments added by others are left alone. `[[links]]` and markdown links to pages (`[text](/pages/name)`) that have a Confluence link
+earlier export added and the page no longer uses are removed (a draw.io diagram is attached under its name and a hash of its content, so a changed diagram is a new attachment, because the draw.io macro would keep showing the first version of an attachment it names); attachments added by others are left alone. `[[links]]` and markdown links to pages (`[text](/pages/name)`) that have a Confluence link
 become links to them, other links to Archsight (pages without a Confluence link, resources, searches) are plain text. A page with a broken image, a diagram that does not render or an invalid
-```` ```view ````/```` ```requirements ```` block is not exported and reported as failed. The Confluence title is kept. The exported page uses the Confluence layout: the page properties top left, the note that the page is generated by Archsight top right, and the content below in a section of its own.
+```` ```view ````/```` ```requirements ```` block is not exported and reported as failed. The Confluence title is kept. The exported page uses the Confluence layout: the page properties top left, the note that the page is generated by Archsight top right, and the content below in a section of its own. When the resources are a git checkout with an `origin` remote, the note names the repository and links the source file to its page on the git host (GitHub `/blob/`, GitLab `/-/blob/`, on the checked out branch, or the commit when the HEAD is detached; other hosts get only the repository link, and so does a file git does not track). User names and tokens in the remote URL never appear in the link.
 
 **Views and requirements** are live in Archsight, so Confluence gets a regular table with the data of the moment of the export (every
 export writes the current data; a page whose tables did not change is `unchanged`): `![[View/Name]]` on a line of its own, a
@@ -326,7 +349,15 @@ export writes the current data; a page whose tables did not change is `unchanged
 the view (Name, Kind unless `list:name`, the `view/fields`, sorted by `view/sort`; times are the stored values, not "3 days ago") or
 the requirements table (status and priority as status lozenges: implemented green, partial yellow, planned blue; `must` red,
 `should` yellow, `may` grey), and names of pages that have a Confluence link as links. At most 200 rows are exported, a note says how many
-were left out. A `![[View/..]]` that is not alone on its line or names no view stays a note, and so does `![[Analysis/..]]` (it runs a script).
+were left out. A `![[View/..]]` that is not alone on its line or names no view stays a note.
+
+**Analyses** (`![[Analysis/Name]]` on a line of its own) are run at the export and their result is written into the page, the data
+of the moment like a view: headings, text, tables and lists as Confluence content (`[[links]]` as for the page, `<br>` and newlines
+in a cell break the line), `info`/`warning`/`error` messages as info, note and warning panels, code as a code macro. The result
+holds no time or run time, so a page whose analysis gives the same result stays `unchanged`. A failing analysis is a note in the page,
+an analysis that is not alone on its line or names no analysis stays a note.
+An embedded description (`![[MotivationGoal/Name]]` on a line of its own) is text, not live content: it is written into the page
+as it is in Archsight; embeds inside it stay notes.
 
 **Links in diagrams**: a node with `resource "Some Page"` links to the Confluence page of that wiki page (the page's own
 `confluence:` link) instead of its Archsight address, which means nothing in Confluence. A reference to a page without a

data/docs/search.md

@@ -24,9 +24,17 @@ Type any word to search by name (case-insensitive regex match):
     name != "OldService"    # not equal
     name in ("a", "b")      # name is one of several options
 
+Names often contain colons (`Archsight:CLI`) and so do [aliases](/doc/modeling#identity-and-links) (`ITGS:A001`). Typed
+without spaces they are one word, found by name or alias like any other bare word:
+
+    Archsight:CLI           # the resources named Archsight:CLI
+    ITGS:A001               # the resource with the alias ITGS:A001
+    ApplicationService:ITGS:A001   # the same, in one kind
+
 ## Kind Filter
 
-Prefix your query with `Kind:` to filter by resource type:
+Prefix your query with `Kind:` to filter by resource type (a capitalised word that is a kind, followed by a space or
+nothing; `Kind:Name` without a space is the kind and a name):
 
     TechnologyArtifact:                              # all of this kind
     TechnologyArtifact: activity/status == "active"  # filtered
@@ -246,6 +254,18 @@ Active containerized services:
 
     TechnologyArtifact: activity/status == "active" & repository/artifacts == "container"
 
+Everything that is on its way out:
+
+    lifecycle/status in ("deprecated", "sunset", "end-of-life")
+
+Resources in use (a resource without a status is active, the annotation's default):
+
+    lifecycle/status == "active"
+
+What is planned, not yet in use:
+
+    lifecycle/status == "planned"
+
 Services exposing APIs:
 
     ApplicationComponent: -> ApplicationInterface

data/docs/togaf.md

@@ -123,13 +123,14 @@ The metamodel defines architectural entities and their relationships across all
 **Cross-Cutting:**
 
 - **Principle**, **Constraint**, **Requirement**, **Location**
+- **Stakeholder**: `MotivationStakeholder`, with its concerns (`hasConcern`); the organisation unit or actor behind it is linked with `representedBy` (`BusinessActor`, `BusinessRole`). The stakeholder that has the concern is the source of a requirement, as recorded in the requirements repository
 - **Gap**, **Work Package**, **Deliverable**, **Plateau**, **Implementation Event**: the Implementation & Migration layer (`ImplementationGap`, `ImplementationWorkPackage`, `ImplementationDeliverable`, `ImplementationPlateau`, `ImplementationEvent`)
 
 **Governance:**
 
 - **Control**: a decision-making step with accountability and authority, applied to a process or function. ArchiMate has no element for it; Archsight models it as `BusinessControl`, which a `BusinessProcess` is `guidedBy`
 
-**Risk and security:** the Open Group overlay (*Modeling Enterprise Risk Management and Security with the ArchiMate Language*) maps threats to **Driver** (`MotivationDriver`), threat and loss events to **Business/Application/Technology Event**, risks and vulnerabilities to **Assessment** (`MotivationAssessment`), control objectives to **Goal**, control measures to **Requirement** and policies to **Principle** (`MotivationPrinciple`), each with a type annotation. See [Modeling Guide](modeling.md#security-and-risk). How relations are directed (top-down, DAG) is described under [Direction of Relations](modeling.md#direction-of-relations).
+**Risk and security:** the Open Group overlay (*Modeling Enterprise Risk Management and Security with the ArchiMate Language*) maps threats to **Driver** (`MotivationDriver`), threat and loss events to **Business/Application/Technology Event**, risks and vulnerabilities to **Assessment** (`MotivationAssessment`), control objectives to **Goal**, control measures to **Requirement** and policies to **Principle** (`MotivationPrinciple`), each with a type annotation. See [Modeling Guide](modeling.md#security-and-risk). How relations are directed (top-down, DAG) is described under [Direction of Relations](modeling.md#direction-of-relations). Which of capability, product, service and component an element is follows the questions in [Choosing the Kind](modeling.md#choosing-the-kind).
 
 ### Critical Relationships
 

data/lib/archsight/analysis/result.rb

@@ -36,7 +36,8 @@ module Archsight
         @analysis.name
       end
 
-      # @return [Boolean] true if any content sections exist (excluding messages)
+      # @return [Boolean] true if the script produced any output (tables, lists, text, ...; not counting messages).
+      #   Output is not a problem (many analyses are reports); see #warnings?
       def has_findings?
         @sections.any? { |s| %i[table list text heading code].include?(s[:type]) }
       end
@@ -51,6 +52,11 @@ module Archsight
         @sections.count { |s| s[:type] == :message && s[:level] == :warning }
       end
 
+      # @return [Boolean] true if the script reported an error or a warning itself (`error(...)`, `warning(...)`)
+      def warnings?
+        (error_count + warning_count).positive?
+      end
+
       # Convert result to markdown (only script-generated content)
       # @param verbose [Boolean] Include detailed output
       # @return [String] Markdown formatted output
@@ -82,7 +88,7 @@ module Archsight
       def status_emoji
         return "❌" unless success?
 
-        has_findings? ? "⚠️" : "✅"
+        warnings? ? "⚠️" : "✅"
       end
 
       # Formatted duration string

data/lib/archsight/analysis/sandbox.rb

@@ -221,6 +221,14 @@ module Archsight
         @sections << { type: :code, content: content, lang: lang }
       end
 
+      # Attach structured data for document templates (archsight analyze --format typst --template).
+      # Not shown in the web UI or the terminal; a template renders it instead of the other sections.
+      # @param key [String, Symbol] Name the template looks the data up by
+      # @param value [Hash, Array, String, Numeric, Boolean, nil] JSON-like value
+      def data(key, value)
+        @sections << { type: :data, key: key.to_s, value: value }
+      end
+
       # Legacy output methods - still supported for backward compatibility
 
       # Report findings (legacy method - creates appropriate section based on data type)

data/lib/archsight/analysis/typst_renderer.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative "../markdown"
+require_relative "../diagram"
+
+module Archsight
+  module Analysis
+    # Renders analysis results as one Typst document (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.
+    class TypstRenderer
+      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)
+      TYPST
+
+      # @param results [Array<Archsight::Analysis::Result>]
+      # @param verbose [Boolean] show every table row and list item and the error backtrace
+      # @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)
+        @results = results
+        @verbose = verbose
+        @template = template
+      end
+
+      # @return [String] Typst source
+      def render
+        return [template_preamble, *@results.map { |result| template_result(result) }].join("\n") if @template
+
+        [PREAMBLE, title, summary, *@results.map { |result| render_result(result) }].join("\n")
+      end
+
+      private
+
+      def title
+        "#align(center)[#text(size: 20pt, weight: \"bold\")[#{str("Archsight analysis")}]]\n"
+      end
+
+      def summary
+        completed = @results.count(&:success?)
+        failed = @results.count(&:failed?)
+        with_warnings = @results.count { |result| result.success? && result.warnings? }
+        items = ["#{completed} completed"]
+        items << "#{failed} failed" if failed.positive?
+        items << "#{with_warnings} with warnings" if with_warnings.positive?
+        "#list(#{items.map { |item| "[#{str(item)}]" }.join(", ")})\n"
+      end
+
+      def template_preamble
+        counts = { count: @results.size, passed: @results.count(&:success?), failed: @results.count(&:failed?),
+                   findings: @results.count(&:has_findings?) }
+        "#import #{lit(@template)}: *\n#show: archsight-report.with(#{named_args(counts)})\n"
+      end
+
+      # One `analysis-result` call: metadata and data as named arguments, the rendered sections as body
+      def template_result(result)
+        data = result.sections.select { |s| s[:type] == :data }.to_h { |s| [s[:key], s[:value]] }
+        body = []
+        body << error_block(result) if result.failed?
+        body.concat(result.sections.filter_map { |section| render_section(section) })
+        args = { name: result.name, description: description(result), state: state(result),
+                 duration: result.duration_str, data: data }
+        "#analysis-result(#{named_args(args)})[\n#{body.join("\n\n")}\n]\n"
+      end
+
+      def description(result)
+        analysis = result.analysis
+        analysis.respond_to?(:annotations) ? analysis.annotations["analysis/description"] : nil
+      end
+
+      def state(result)
+        return "failed" if result.failed?
+
+        result.has_findings? ? "findings" : "passed"
+      end
+
+      def named_args(hash)
+        hash.map { |key, value| "#{key}: #{typst_value(value)}" }.join(", ")
+      end
+
+      # A Ruby value as a Typst literal: Hash -> dictionary (string keys), Array -> array, nil -> none
+      def typst_value(value)
+        case value
+        when Hash then value.empty? ? "(:)" : "(#{value.map { |k, v| "#{lit(k.to_s)}: #{typst_value(v)}" }.join(", ")})"
+        when Array then "(#{value.map { |v| typst_value(v) }.join(", ")}#{"," if value.size == 1})"
+        when Integer, true, false then value.to_s
+        when Float then value.finite? ? value.to_s : "none"
+        when nil then "none"
+        else lit(value.to_s)
+        end
+      end
+
+      def render_result(result)
+        parts = ["#pagebreak(weak: true)", "#heading(level: 1)[#{str(result.name)}]"]
+        status = result.failed? ? "failed" : "completed"
+        status += ", #{result.duration_str}" unless result.duration_str.empty?
+        parts << "#text(fill: gray)[#{str(status)}]"
+        parts << error_block(result) if result.failed?
+        parts.concat(result.sections.filter_map { |section| render_section(section) })
+        "#{parts.join("\n\n")}\n"
+      end
+
+      def error_block(result)
+        lines = [message_block(:error, "**Error:** #{result.error}")]
+        lines << "#raw(#{lit(result.error_backtrace.join("\n"))}, block: true)" if @verbose && result.error_backtrace&.any?
+        lines.join("\n\n")
+      end
+
+      def render_section(section)
+        case section[:type]
+        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])
+        when :code then code(section)
+        when :message then message_block(section[:level], section[:message])
+        when :data then nil # only for templates, passed to analysis-result
+        end
+      end
+
+      def message_block(level, text)
+        fill = MESSAGE_FILL.fetch(level, MESSAGE_FILL[:info])
+        "#block(fill: #{fill}, inset: 8pt, radius: 3pt, width: 100%)[#{markdown(text, inline: true)}]"
+      end
+
+      # A template produces a document to hand out, so it gets every row
+      def full?
+        @verbose || !@template.nil?
+      end
+
+      def table(headers, rows)
+        shown = full? ? rows : rows.first(ROW_LIMIT)
+        head = headers.map { |header| "[#strong[#{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 += "\n\n#emph[#{str("...and #{rows.size - ROW_LIMIT} more rows")}]" if shown.size < rows.size
+        out
+      end
+
+      def list(items)
+        shown = full? ? items : items.first(ROW_LIMIT)
+        out = "#list(#{shown.map { |item| "[#{markdown(item, inline: true)}]" }.join(", ")})"
+        out += "\n\n#emph[#{str("...and #{items.size - ROW_LIMIT} more items")}]" if shown.size < items.size
+        out
+      end
+
+      def code(section)
+        return diagram(section[:content]) if section[:lang].to_s == "asd"
+
+        raw(section[:content], section[:lang])
+      end
+
+      def diagram(source)
+        svg = Archsight::Diagram.render(source)
+        "#image(bytes(#{lit(svg)}), format: \"svg\", width: 100%)"
+      rescue Archsight::Diagram::Error => e
+        [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
+      end
+    end
+  end
+end

data/lib/archsight/analysis.rb

@@ -9,3 +9,4 @@ end
 require_relative "analysis/result"
 require_relative "analysis/sandbox"
 require_relative "analysis/executor"
+require_relative "analysis/typst_renderer"

data/lib/archsight/annotations/annotation.rb

@@ -2,10 +2,11 @@
 
 require_relative "email_recipient"
 require_relative "person"
+require_relative "resource_reference"
 
 # Annotation represents a single annotation definition with its schema and behavior
 class Archsight::Annotations::Annotation
-  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :summary, :editor
+  attr_reader :key, :description, :filter, :format, :enum, :sidebar, :type, :summary, :editor, :deprecated, :default
 
   def initialize(key, options = {})
     @key = key
@@ -18,6 +19,9 @@ class Archsight::Annotations::Annotation
     @summary = options.fetch(:summary, false)
     @editor = options.fetch(:editor, true)
     @type = options[:type]
+    @unique = options[:unique] == true
+    @deprecated = options[:deprecated]
+    @default = options[:default]
 
     # Auto-add filter if enum present
     @filter ||= :word if @enum
@@ -51,6 +55,22 @@ class Archsight::Annotations::Annotation
     @filter == :list
   end
 
+  # A unique annotation holds identifiers: no two resources of a kind share a value (checked by `archsight lint`)
+  def unique?
+    @unique
+  end
+
+  # A deprecated annotation still loads and works, but `archsight lint` reports every use with what to use instead
+  # (the `deprecated:` text)
+  def deprecated?
+    !@deprecated.nil?
+  end
+
+  # @return [Boolean] true if the value names another resource (`Name` or `Kind/Name`)
+  def resource?
+    @format == :resource
+  end
+
   # Summary annotations are returned with every search hit (at most MAX_SUMMARY per kind)
   def summary?
     @summary == true
@@ -122,9 +142,11 @@ class Archsight::Annotations::Annotation
     @format if code? || diagram?
   end
 
-  # Example value for templates
+  # Example value for templates: the default, else the first value of the enum
   def example_value
-    if @enum
+    if @default
+      @default
+    elsif @enum
       @enum.first || "TODO"
     elsif @type == Float
       0.0
@@ -144,6 +166,7 @@ class Archsight::Annotations::Annotation
     when "Float" then "Expected a float value"
     when "Archsight::Annotations::EmailRecipient" then 'Expected email format: "Name <email@domain.com>" or "email@domain.com"'
     when "Archsight::Annotations::Person" then 'Expected "Name", "Name <email@domain.com>" or "email@domain.com"'
+    when "Archsight::Annotations::ResourceReference" then "Expected a resource name of the same kind (Archsight:Web) or Kind/Name (ApplicationService/Archsight:Web)"
     else "Invalid value for type #{@type}"
     end
   end
@@ -184,6 +207,7 @@ class Archsight::Annotations::Annotation
     when "URI" then valid_uri?(string_value)
     when "Archsight::Annotations::EmailRecipient" then Archsight::Annotations::EmailRecipient.valid?(string_value)
     when "Archsight::Annotations::Person" then Archsight::Annotations::Person.valid?(string_value)
+    when "Archsight::Annotations::ResourceReference" then Archsight::Annotations::ResourceReference.valid?(string_value)
     else true
     end
   end
@@ -203,6 +227,9 @@ class Archsight::Annotations::Annotation
   end
 
   def derive_format
+    return :identifier if unique?
+    return :resource if @type == Archsight::Annotations::ResourceReference
+
     case @filter
     when :word then :tag_word
     when :list then :tag_list

data/lib/archsight/annotations/architecture_annotations.rb

@@ -4,7 +4,11 @@ require "uri"
 
 # Architecture module adds common architecture annotations to resource classes
 module Archsight::Annotations::Architecture
+  # in the order of a resource's life; a resource that sets none is `active` (the annotation's default)
+  LIFECYCLE_STATUSES = %w[planned active deprecated sunset end-of-life].freeze
+
   def self.included(base)
+    base.include Archsight::Annotations::Links
     base.class_eval do
       annotation "architecture/abbr",
                  description: "Abbreviation or short name",
@@ -21,10 +25,53 @@ module Archsight::Annotations::Architecture
                  description: "Documentation URL or reference",
                  title: "Documentation",
                  type: URI
+      annotation "architecture/aliases",
+                 description: "Other identifiers of the resource (comma-separated), e.g. ITGS:A001; " \
+                              "unique among the resources of a kind",
+                 title: "Aliases",
+                 filter: :list,
+                 sidebar: false,
+                 unique: true
       annotation "architecture/tags",
                  description: "Comma-separated tags",
                  filter: :list,
                  title: "Tags"
     end
+    define_lifecycle(base)
+  end
+
+  def self.define_lifecycle(base)
+    base.class_eval do
+      annotation "lifecycle/status",
+                 description: "Lifecycle state: planned (not yet in use), active (the default), deprecated (do not " \
+                              "start new uses), sunset (being phased out) or end-of-life (no longer operated or supported)",
+                 enum: LIFECYCLE_STATUSES,
+                 default: "active",
+                 title: "Lifecycle"
+      annotation "lifecycle/activeAt",
+                 description: "When the resource goes (or went) into use (ISO 8601 date or time)",
+                 title: "Active at",
+                 validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+      annotation "lifecycle/deprecatedAt",
+                 description: "When the resource was deprecated (ISO 8601 date or time)",
+                 title: "Deprecated at",
+                 validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+      annotation "lifecycle/sunsetAt",
+                 description: "When the resource goes (or went) into sunset (ISO 8601 date or time)",
+                 title: "Sunset at",
+                 validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+      annotation "lifecycle/endOfLifeAt",
+                 description: "When the resource reaches (or reached) end-of-life (ISO 8601 date or time)",
+                 title: "End of life at",
+                 validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+      annotation "lifecycle/replacedBy",
+                 description: "The resource that replaces this one: a name for the same kind, Kind/Name for another (a component can be replaced by an ApplicationService/...)",
+                 title: "Replaced by",
+                 type: Archsight::Annotations::ResourceReference
+      annotation "lifecycle/reason",
+                 description: "Why the resource is deprecated",
+                 title: "Reason",
+                 format: :markdown
+    end
   end
 end

data/lib/archsight/annotations/link_annotations.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Links module adds the links of a resource to other systems: `link/<name>` holds a URL, the name says which
+# (confluence, jira, github, ...). A link has no direction; it can be where the resource comes from or where it
+# was published to.
+module Archsight::Annotations::Links
+  def self.included(base)
+    base.class_eval do
+      annotation "link/*",
+                 description: "Links to the resource in other systems and to related documents (name and URL)",
+                 sidebar: false,
+                 validator: ->(value) { "'#{value}' is not an http(s) URL" unless value.match?(%r{\Ahttps?://\S+\z}) }
+    end
+  end
+end