archsight 0.3.3 → 0.4.0

data/lib/archsight/resources.rb

@@ -14,6 +14,12 @@ module Archsight
       "BusinessConstraint" => "MotivationConstraint"
     }.freeze
 
+    # Annotations that were renamed: the old key is rewritten to the new one when a document is loaded (see
+    # Database#accept_old_names) and reported as deprecated by `archsight lint`.
+    ANNOTATION_ALIASES = {
+      "page/confluence" => "link/confluence"
+    }.freeze
+
     # Relation keys (the plural kind names under `spec.<verb>`) that were renamed together with their kind
     RELATION_KEY_ALIASES = {
       "businessRequirements" => "motivationRequirements",
@@ -28,6 +34,12 @@ module Archsight
     DERIVED_VERBS = %i[mentions depicts].freeze
     DERIVED_KEY = :resources
 
+    # The layers a kind belongs to (Base.layer), top to bottom: why (motivation), what we want to become (strategy),
+    # how the change happens (implementation and migration), then the architecture it changes (business, application,
+    # technology). `other` holds the tool's own kinds (pages, views, imports, ...) and stays last. Everything that
+    # lists or orders layers uses this; the frontend repeats it in frontend/src/composables/useLayers.js.
+    LAYERS = %w[motivation strategy implementation business application technology other].freeze
+
     # The derived relations of every class, next to the ones it declares: [verb, key, kind]
     DERIVED_RELATIONS = DERIVED_VERBS.map { |verb| [verb, DERIVED_KEY, "Resource"] }.freeze
 

data/lib/archsight/version.rb

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

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Archsight; end
+module Archsight::Web; end
+module Archsight::Web::API; end
+
+# JSON of `POST /api/v1/kinds/Analysis/instances/:name/execute`: the result and its sections
+module Archsight::Web::API::AnalysisHelpers
+  def build_analysis_result(result)
+    data = {
+      name: result.name,
+      success: result.success?,
+      has_findings: result.has_findings?,
+      duration: result.duration,
+      sections: result.sections.map { |s| serialize_analysis_section(s) }
+    }
+
+    if result.failed?
+      data[:error] = result.error
+      data[:error_backtrace] = result.error_backtrace if result.error_backtrace&.any?
+    end
+
+    data
+  end
+
+  def serialize_analysis_section(section)
+    case section[:type]
+    when :heading
+      { type: "heading", level: section[:level], text: section[:text] }
+    when :text
+      { type: "text", content: markdown(section[:content]) }
+    # the *_html fields: the values as inline markdown with [[Kind/Name]] links, next to the raw values
+    when :message
+      { type: "message", level: section[:level].to_s, message: section[:message],
+        message_html: analysis_html(section[:message]) }
+    when :table
+      { type: "table", headers: section[:headers], rows: section[:rows],
+        rows_html: section[:rows].map { |row| row.map { |cell| analysis_html(cell) } } }
+    when :list
+      { type: "list", items: section[:items], items_html: section[:items].map { |item| analysis_html(item) } }
+    when :code
+      { type: "code", lang: section[:lang], content: section[:content] }
+    else
+      { type: section[:type].to_s }
+    end
+  end
+
+  # A value of a table cell, list item or message as html: HTML in it stays text (escaped first) except a line
+  # break (`<br>` or a newline, the usual way to break a line in a table cell), markdown and [[Kind/Name]] links are
+  # rendered; a value without markup is only escaped, so large tables stay cheap
+  def analysis_html(value)
+    escaped = Rack::Utils.escape_html(value.to_s).gsub(%r{&lt;br\s*/?&gt;}i, "<br>").gsub(/\r?\n/, "<br>")
+    escaped.match?(/[*_`\[{]|https?:/) ? inline_markdown(escaped) : escaped
+  end
+end

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

@@ -66,7 +66,8 @@ module Archsight::Web::API::JsonHelpers
         description: klass.description,
         layer: klass.layer,
         icon: klass.icon,
-        instance_count: count
+        instance_count: count,
+        self_relations: Archsight::GraphvisRenderer.self_relations(klass).any?
       }
     end
     kinds.sort_by { |k| k[:kind] }
@@ -92,6 +93,7 @@ module Archsight::Web::API::JsonHelpers
       name: instance.name,
       metadata: { annotations: render_annotations(instance.annotations, base: Archsight::Assets.base_dir_for(instance, resources_dir: Archsight.resources_dir), kind: kind) },
       annotation_formats: Archsight::Resources[kind]&.annotation_formats(instance.annotations.keys) || {},
+      annotation_links: Archsight::Helpers::ResourceResolver.new(db).annotation_links(kind, instance.annotations),
       spec: serialize_spec(instance.spec),
       relations: extract_relations(instance),
       references: extract_references(instance),
@@ -193,42 +195,6 @@ module Archsight::Web::API::JsonHelpers
     end
   end
 
-  def build_analysis_result(result)
-    data = {
-      name: result.name,
-      success: result.success?,
-      has_findings: result.has_findings?,
-      duration: result.duration,
-      sections: result.sections.map { |s| serialize_analysis_section(s) }
-    }
-
-    if result.failed?
-      data[:error] = result.error
-      data[:error_backtrace] = result.error_backtrace if result.error_backtrace&.any?
-    end
-
-    data
-  end
-
-  def serialize_analysis_section(section)
-    case section[:type]
-    when :heading
-      { type: "heading", level: section[:level], text: section[:text] }
-    when :text
-      { type: "text", content: markdown(section[:content]) }
-    when :message
-      { type: "message", level: section[:level].to_s, message: section[:message] }
-    when :table
-      { type: "table", headers: section[:headers], rows: section[:rows] }
-    when :list
-      { type: "list", items: section[:items] }
-    when :code
-      { type: "code", lang: section[:lang], content: section[:content] }
-    else
-      { type: section[:type].to_s }
-    end
-  end
-
   def extract_references(instance)
     references = {}
 

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

@@ -254,7 +254,7 @@ paths:
         Returns one page with its metadata and its body rendered to HTML.
 
         **Metadata** comes from the frontmatter: `title` (falls back to the name), `status`, `author` and
-        `owner` (`Name <email>`, split into `name` and `email`), `tags` and the `confluence` URL.
+        `owner` (`Name <email>`, split into `name` and `email`), `tags` and the `links` (name and URL, e.g. `confluence`).
 
         **`html`** is the markdown body rendered once per request:
         - GitHub-flavoured markdown (tables, fenced code, task lists).
@@ -309,7 +309,7 @@ paths:
                 owner:
                   name: Jane Doe
                   email: jane.doe@example.com
-                confluence: null
+                links: {}
                 tags:
                   - howto
                   - wiki
@@ -1489,7 +1489,7 @@ components:
           description: Whether the analysis executed successfully
         has_findings:
           type: boolean
-          description: Whether the analysis produced findings
+          description: Whether the script produced any output (tables, lists, text, ...). Output is not a problem; errors and warnings the script reports are message sections
         duration:
           type: number
           format: float
@@ -1869,7 +1869,7 @@ components:
 
     PageResponse:
       type: object
-      required: [name, title, status, author, owner, created, updated, properties, confluence, tags, toc, breadcrumb, html, backlinks]
+      required: [name, title, status, author, owner, created, updated, properties, links, tags, toc, breadcrumb, html, backlinks]
       properties:
         name:
           type: string
@@ -1909,10 +1909,12 @@ components:
               html:
                 type: string
                 description: The value rendered as inline markdown (links, emphasis, `{macros}`, `[[wiki links]]`), without a paragraph around it
-        confluence:
-          type: [string, 'null']
-          format: uri
-          description: URL of the corresponding Confluence page
+        links:
+          type: object
+          description: Links of the page to other systems, by name (`confluence`, `jira`, ...)
+          additionalProperties:
+            type: string
+            format: uri
         tags:
           type: array
           items:

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

@@ -41,7 +41,7 @@ module Archsight::Web::API::PageHelpers
       created: annotations["page/created"],
       updated: annotations["page/updated"],
       properties: page.properties.map { |key, value| { key: key, value: value, html: inline_markdown(value, page) } },
-      confluence: annotations["page/confluence"],
+      links: annotations.select { |key, _| key.start_with?("link/") }.transform_keys { |key| key.delete_prefix("link/") },
       tags: Archsight::Resources::Page.annotation_matching("page/tags")&.value_for(page) || [],
       toc: annotations["page/toc"] == "yes" ? Archsight::PageTree.toc(body) : [],
       breadcrumb: tree.breadcrumb(page),
@@ -50,13 +50,6 @@ module Archsight::Web::API::PageHelpers
     }
   end
 
-  # A short text (a page property) rendered as inline markdown: links, emphasis, `{macros}`, [[wiki links]], without the
-  # paragraph around it
-  def inline_markdown(text, page)
-    html = markdown(text.to_s, base: Archsight::Assets.base_dir_for(page, resources_dir: Archsight.resources_dir), page: page)
-    html.strip.sub(%r{\A<p>(.*)</p>\z}m, '\1')
-  end
-
   # The header already shows the title, so a leading "# Title" that repeats it is dropped
   # (Confluence exports and hand-written pages usually start with one).
   def strip_duplicate_title(body, page)

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

@@ -5,6 +5,7 @@ require "sinatra/extension"
 require_relative "json_helpers"
 require_relative "page_helpers"
 require_relative "requirements_helpers"
+require_relative "analysis_helpers"
 require_relative "../../assets"
 
 module Archsight; end
@@ -18,6 +19,7 @@ module Archsight::Web::API::Routes
   helpers Archsight::Web::API::JsonHelpers
   helpers Archsight::Web::API::PageHelpers
   helpers Archsight::Web::API::RequirementsHelpers
+  helpers Archsight::Web::API::AnalysisHelpers
 
   # Rendering is CPU work, previews are typed, not pasted
   MAX_DIAGRAM_SOURCE = 100_000
@@ -67,10 +69,13 @@ module Archsight::Web::API::Routes
     klass = Archsight::Resources[kind]
     json_error("Kind '#{kind}' not found", status: 404, error_type: "NotFound") unless klass
 
-    instance = db.instance_by_kind(kind, name)
+    # an alias finds the one resource that has it; the response carries the real name
+    instance = db.instance_by_kind(kind, name) || db.instance_by_alias(kind, name)
     json_error("Instance '#{name}' not found", status: 404, error_type: "NotFound") unless instance
 
-    json_response(build_instance_response(kind, instance))
+    # graph_layers: the layers its dependency graph follows when the page opens
+    json_response(build_instance_response(kind, instance)
+      .merge(graph_layers: Archsight::GraphvisRenderer.default_graph_layers(instance.class.layer)))
   end
 
   # GET /api/v1/pages - Page tree built from PageMenu resources, page tags and filters and the home page

data/lib/archsight/web/application.rb

@@ -25,17 +25,25 @@ class Archsight::Web::Application < Sinatra::Base
     attr_accessor :db
 
     def database
-      @database ||= Archsight::Database.new(Archsight.resources_dir).tap(&:reload!)
+      @database ||= Archsight::Database.new(Archsight.resources_dir).tap(&:reload!).tap { |db| load_import_handlers(db) }
     end
 
     def reload!
       start = Time.new
       puts "== Reloading ..." if database.verbose
       database.reload!
+      load_import_handlers(database)
       dur = (Time.new - start) * 1000
       puts format("== done %0.2f ms", dur) if database.verbose
     end
 
+    # The import handlers, built-in and of the resources repository (import/handlerPath), so the editor knows the
+    # same handler names as `archsight lint`. A file that does not load is reported, the server keeps running.
+    def load_import_handlers(db)
+      require "archsight/import"
+      Archsight::Import::HandlerLoader.load(db).each { |problem| warn "Import handler: #{problem}" }
+    end
+
     # Configure application for the given environment
     # @param env [Symbol] :development or :production
     # @param logging [Boolean, nil] Override default logging setting
@@ -135,6 +143,15 @@ class Archsight::Web::Application < Sinatra::Base
       settings.environment == :development
     end
 
+    # A short text (a page property, an analysis table cell) rendered as inline markdown: links, emphasis,
+    # `{macros}`, [[wiki links]], without the paragraph around it
+    # @param page [Archsight::Resources::Page, nil] the page the text belongs to, for its relative images and macros
+    def inline_markdown(text, page = nil)
+      base = page && Archsight::Assets.base_dir_for(page, resources_dir: Archsight.resources_dir)
+      html = markdown(text.to_s, base: base, page: page)
+      html.strip.sub(%r{\A<p>(.*)</p>\z}m, '\1')
+    end
+
     # Render markdown to HTML with optional URL resolution for repository content
     # @param data [String] Markdown content
     # @param git_url [String, nil] Git URL for resolving relative paths (e.g., for README images)
@@ -282,14 +299,33 @@ class Archsight::Web::Application < Sinatra::Base
     serve_vue
   end
 
+  # The resources of a kind and the relations between them (see GraphvisRenderer#create_graph_kind)
+  get "/kinds/:kind/dot" do
+    halt 404, "kind #{params["kind"]} unknown" unless Archsight::Resources[params["kind"]]
+
+    content_type "text/plain"
+    create_graph_kind(db, params["kind"])
+  end
+
+  # An alias in the URL redirects to the resource's real name (`:` stays readable, the rest is escaped)
   get "/kinds/:kind/instances/:instance" do
+    kind = params["kind"]
+    name = params["instance"]
+    if Archsight::Resources[kind] && !db.instance_by_kind(kind, name) && (instance = db.instance_by_alias(kind, name))
+      redirect "/kinds/#{kind}/instances/#{ERB::Util.url_encode(instance.name).gsub("%3A", ":")}"
+    end
+
     serve_vue
   end
 
+  # `depth`: steps from the instance (a positive number; missing or `all`: every step), `layers`: the layers it
+  # follows, comma separated (missing or none known: every layer)
   get "/kinds/:kind/instances/:instance/dot" do
     @kind = params["kind"]
     @instance = params["instance"]
+    depth = params["depth"].to_s.match?(/\A[1-9]\d*\z/) ? params["depth"].to_i : nil
+    layers = params["layers"].to_s.split(",").map(&:strip) & Archsight::Resources::LAYERS
     content_type "text/plain"
-    create_graph_one(db, @kind, @instance)
+    create_graph_one(db, @kind, @instance, max_depth: depth, layers: layers.empty? ? nil : layers)
   end
 end

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

@@ -57,7 +57,8 @@ module Archsight
           data = build_form_metadata(kind, klass)
           data[:mode] = "edit"
           data[:name] = instance.name
-          data[:annotations] = instance.annotations.dup
+          # defaults are not in the file, a save leaves them out
+          data[:annotations] = instance.annotations.reject { |key, _| instance.defaulted?(key) }
           data[:relations] = extract_instance_relations(instance)
           data[:path_ref] = source_ref(instance)
           data[:content_hash] = source_content_hash(instance)

data/lib/archsight/web/public/vue/ApiDocsPage-COp4onwn.js

@@ -0,0 +1 @@
+import{F as e,I as t,K as n,N as r,T as i,W as a,et as o,i as s,it as c,k as l,tt as u}from"./index-BGlYCbi7.js";var d={class:`api-docs-page`},f={key:0,class:`pico-color-red-500`},p=s({__name:`ApiDocsPage`,setup(s){let p=i(),m=o(null),h=o(null);function g(e){return new Promise((t,n)=>{if(window.Redoc)return t();let r=document.createElement(`script`);r.src=e,r.onload=t,r.onerror=()=>n(Error(`Failed to load ReDoc`)),document.head.appendChild(r)})}return a(async()=>{try{await g(`https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js`),window.Redoc.init(`/api/v1/openapi.yaml`,{},m.value)}catch(e){h.value=e.message}}),(i,a)=>(n(),t(`div`,d,[r(`a`,{href:`#`,class:`back-link`,onClick:a[0]||=l(e=>u(p).back(),[`prevent`])},`← Back`),h.value?(n(),t(`div`,f,c(h.value),1)):e(``,!0),r(`div`,{ref_key:`container`,ref:m},null,512)]))}},[[`__scopeId`,`data-v-4823b89b`]]);export{p as default};

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

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