archsight 0.3.0 → 0.3.1

data/lib/archsight/view_table.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Archsight
+  # The result of a view as a plain table (columns and rows of text), for places that cannot run the frontend, such
+  # as the Confluence export. It follows what the web UI shows for a View (`ViewResults.vue`, `ResourceList.vue`):
+  # a Name column, a Kind column unless the view is `list:name`, one column per `view/fields` entry that is not
+  # `name` or `kind`, rows sorted by `view/sort`.
+  module ViewTable
+    # Rows beyond this are cut (the table says how many); a Confluence page is no place for thousands of rows
+    LIMIT = 200
+
+    # @param as [Symbol] :text, :status or :priority (a requirement's, shown as a lozenge) or :markdown
+    # @param resources [Array] resources the cell names (shown one per line, linked where a target exists)
+    Cell = Struct.new(:text, :resources, :as, keyword_init: true) do
+      def initialize(text: "", resources: [], as: :text) = super
+    end
+
+    # @param title [String] shown above the table, may be empty
+    # @param columns [Array<String>] header texts
+    # @param rows [Array<Array<Cell>>] at most LIMIT
+    # @param total [Integer] number of rows before cutting
+    Table = Struct.new(:title, :columns, :rows, :total, keyword_init: true) do
+      def cut = total - rows.length
+    end
+
+    IDENTITY_FIELDS = %w[name kind].freeze
+
+    module_function
+
+    # @raise [Archsight::Query::QueryError] if the query does not parse
+    def build(database, query:, fields: [], sort: [], show_kind: true, title: "", limit: LIMIT)
+      resources = sort_resources(Archsight::Query.parse(query).filter(database), sort)
+      columns = fields.reject { |f| IDENTITY_FIELDS.include?(f) }
+      header = ["Name", (show_kind ? "Kind" : nil), *columns.map { |f| column_title(f) }].compact
+      rows = resources.first(limit).map do |resource|
+        [Cell.new(text: resource.name, resources: [resource]),
+         (Cell.new(text: kind_of(resource)) if show_kind),
+         *columns.map { |f| Cell.new(text: resource.annotations[f].to_s) }].compact
+      end
+      Table.new(title: title, columns: header, rows: rows, total: resources.length)
+    end
+
+    # The table of a ```view block (see Helpers::ViewBlocks)
+    # @raise [Helpers::ViewBlocks::Error, Archsight::Query::QueryError]
+    def from_block(database, source)
+      spec = Helpers::ViewBlocks.parse(source)
+      build(database, query: spec[:query], fields: spec[:fields], sort: spec[:sort], show_kind: spec[:type] == "list:name+kind", title: spec[:title])
+    end
+
+    # The table of a View resource
+    # @raise [Helpers::ViewBlocks::Error, Archsight::Query::QueryError]
+    def from_view(database, view)
+      annotations = view.annotations
+      query = annotations["view/query"].to_s.strip
+      raise Helpers::ViewBlocks::Error, "view #{view.name} has no query" if query.empty?
+
+      build(database, query: query, fields: list(annotations["view/fields"]), sort: list(annotations["view/sort"]),
+                      show_kind: (annotations["view/type"] || "list:name+kind") == "list:name+kind", title: view.name)
+    end
+
+    # "scc/language/Go/loc" -> "Go loc", "activity/createdAt" -> "Activity created At" (as ResourceList.vue titles columns)
+    def column_title(key)
+      segments = key.split("/")
+      title = segments.length >= 2 ? "#{segments[-2]} #{segments[-1]}" : segments.last.to_s
+      title.gsub(/([a-z])([A-Z])/, '\1 \2').sub(/\A./, &:upcase)
+    end
+
+    def kind_of(resource) = resource.class.name.split("::").last
+
+    def list(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+    # `view/sort` fields: name, kind or an annotation, "-" for descending; numbers inside text compare as numbers.
+    # Without a sort the order is by name, like the search API.
+    def sort_resources(resources, sort)
+      return resources.sort_by(&:name) if sort.empty?
+
+      resources.sort { |left, right| compare(left, right, sort) }
+    end
+
+    def compare(left, right, sort)
+      sort.each do |field|
+        key = field.delete_prefix("-")
+        order = natural(value_of(left, key)) <=> natural(value_of(right, key))
+        return field.start_with?("-") ? -order : order unless order.zero?
+      end
+      0
+    end
+
+    def value_of(resource, key)
+      case key
+      when "name" then resource.name
+      when "kind" then kind_of(resource)
+      else resource.annotations[key].to_s
+      end
+    end
+
+    # A key for sorting text with numbers in it the way people expect (item2 < item10, case-insensitive first)
+    def natural(text)
+      [text.scan(/\d+|\D+/).map { |part| part.match?(/\A\d/) ? [0, part.to_i] : [1, part.downcase] }, text]
+    end
+  end
+end

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

@@ -130,13 +130,11 @@ module Archsight::Web::API::JsonHelpers
   end
 
   def build_count_response(query, results, query_time_ms)
-    by_kind = results.group_by { |r| r.class.to_s.split("::").last }
-                     .transform_values(&:length)
     {
       query: query,
       total: results.length,
       query_time_ms: query_time_ms,
-      by_kind: by_kind
+      by_kind: Archsight::MCP.count_by_kind(results)
     }
   end
 
@@ -144,10 +142,13 @@ module Archsight::Web::API::JsonHelpers
     limit, offset = parse_pagination_params
     output = parse_output_param
     sorted = results.sort_by(&:name)
-    pagination = paginate(sorted, limit: limit, offset: offset)
+    # `kind` narrows the hits to one kind; by_kind always counts all hits so the facets stay complete
+    kind = params[:kind].to_s
+    visible = kind.empty? ? sorted : sorted.select { |r| Archsight::MCP.kind_of(r) == kind }
+    pagination = paginate(visible, limit: limit, offset: offset)
 
     instances = pagination[:items].map do |r|
-      resource_summary(r, output: output, omit_kind: false)
+      resource_summary(r, output: output, omit_kind: false).merge(highlights: Archsight::MCP.highlights(r))
     end
 
     {
@@ -157,6 +158,7 @@ module Archsight::Web::API::JsonHelpers
       offset: pagination[:offset],
       count: instances.length,
       query_time_ms: query_time_ms,
+      by_kind: Archsight::MCP.count_by_kind(results),
       instances: instances
     }
   end

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

@@ -650,7 +650,12 @@ paths:
         See the API description for full query language documentation.
 
         Response includes: kind, name, metadata, spec (no relations/references).
-        Additional fields: query, query_time_ms, by_kind (count mode).
+        Additional fields: query, query_time_ms, by_kind.
+
+        Every hit carries `highlights`: the values of the kind's summary attributes (annotations marked
+        `summary: true` in the kind definition, at most 3 per kind, computed ones included) that are set.
+        `by_kind` counts all hits of the query per kind, also when `kind` narrows the list, so a client can show
+        facets and let the user pick one.
       operationId: search
       tags:
         - Search
@@ -674,6 +679,13 @@ paths:
             orphan:
               value: '<- none'
               summary: Find orphan resources
+        - name: kind
+          in: query
+          required: false
+          description: Only return hits of this kind (`total` and paging follow; `by_kind` still counts all hits)
+          schema:
+            type: string
+          example: TechnologyArtifact
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/offset'
         - $ref: '#/components/parameters/output'
@@ -691,6 +703,88 @@ paths:
               schema:
                 $ref: '#/components/schemas/QueryError'
 
+  /api/v1/requirements:
+    get:
+      summary: Business requirements of a selection of resources
+      description: |
+        The business requirements that the resources selected by `of` realize (`implemented`), partially realize
+        (`partial`) or plan (`planned`), merged over all of them: one entry per requirement with the best status and
+        the resources it comes from (`by`). Sorted by priority (must, should, may, none), then name. `story` is
+        rendered HTML.
+      operationId: getRequirements
+      tags:
+        - Search
+      parameters:
+        - name: of
+          in: query
+          required: true
+          description: Query selecting the resources whose requirements are listed
+          schema:
+            type: string
+          example: 'ApplicationService: name =~ "Backup"'
+        - name: priority
+          in: query
+          required: false
+          description: Comma separated list, only requirements with one of these priorities
+          schema:
+            type: string
+          example: must,should
+        - name: status
+          in: query
+          required: false
+          description: Comma separated list, only requirements with one of these statuses
+          schema:
+            type: string
+          example: implemented,partial
+      responses:
+        '200':
+          description: The requirements
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  query:
+                    type: string
+                  total:
+                    type: integer
+                  query_time_ms:
+                    type: number
+                  requirements:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                        status:
+                          type: string
+                          enum: [implemented, partial, planned]
+                        priority:
+                          type: string
+                          nullable: true
+                        story:
+                          type: string
+                          nullable: true
+                        by:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              kind:
+                                type: string
+                              name:
+                                type: string
+                              status:
+                                type: string
+                                enum: [implemented, partial, planned]
+        '400':
+          description: Invalid query, or an unknown priority or status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/QueryError'
+
   /dot:
     get:
       summary: Get full architecture graph as DOT
@@ -1225,6 +1319,40 @@ components:
           items:
             $ref: '#/components/schemas/Kind'
 
+    Highlight:
+      type: object
+      required:
+        - key
+        - title
+        - value
+      properties:
+        key:
+          type: string
+          description: Annotation key, exactly as the query language takes it
+          example: activity/status
+        title:
+          type: string
+          description: Display title of the annotation
+          example: Activity Status
+        value:
+          description: The value; an array for list annotations, a number for Integer/Float typed ones
+          oneOf:
+            - type: string
+            - type: number
+            - type: array
+              items:
+                type: string
+        format:
+          type: string
+          nullable: true
+          description: Rendering hint of the annotation (tag_word, tag_list, markdown, link, ...)
+          example: tag_word
+        type:
+          type: string
+          nullable: true
+          description: Short name of the value type when the annotation declares one (Integer, Float, Time, Person, ...)
+          example: Integer
+
     Instance:
       type: object
       required:
@@ -1247,6 +1375,11 @@ components:
           type: object
           additionalProperties: true
           description: Instance specification
+        highlights:
+          type: array
+          description: Values of the kind's summary attributes that are set (search results only)
+          items:
+            $ref: '#/components/schemas/Highlight'
         relations:
           type: object
           additionalProperties:
@@ -1307,7 +1440,7 @@ components:
           type: object
           additionalProperties:
             type: integer
-          description: Result counts by kind (count mode only)
+          description: Result counts by kind (search and count mode; all hits of the query, not only the current page)
         instances:
           type: array
           items:

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Archsight; end
+module Archsight::Web; end
+module Archsight::Web::API; end
+
+# Parameters and JSON of `GET /api/v1/requirements` (see Archsight::Requirements)
+module Archsight::Web::API::RequirementsHelpers
+  # @param name [Symbol] a comma separated list parameter, every value of which must be one of `allowed`
+  def csv_param(name, allowed)
+    values = params[name].to_s.split(",").map(&:strip).reject(&:empty?)
+    invalid = values - allowed
+    json_error("Parameter '#{name}' must be #{allowed.join(", ")}, not '#{invalid.first}'", status: 400, error_type: "BadRequest") unless invalid.empty?
+
+    values
+  end
+
+  def build_requirements_response(query, requirements, query_time_ms)
+    {
+      query: query,
+      total: requirements.length,
+      query_time_ms: query_time_ms,
+      requirements: requirements.map { |r| r.merge(story: r[:story] && markdown(r[:story])) }
+    }
+  end
+end

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

@@ -4,6 +4,7 @@ require "sinatra/base"
 require "sinatra/extension"
 require_relative "json_helpers"
 require_relative "page_helpers"
+require_relative "requirements_helpers"
 require_relative "../../assets"
 
 module Archsight; end
@@ -16,6 +17,7 @@ module Archsight::Web::API::Routes
 
   helpers Archsight::Web::API::JsonHelpers
   helpers Archsight::Web::API::PageHelpers
+  helpers Archsight::Web::API::RequirementsHelpers
 
   # Rendering is CPU work, previews are typed, not pasted
   MAX_DIAGRAM_SOURCE = 100_000
@@ -110,6 +112,23 @@ module Archsight::Web::API::Routes
     end
   end
 
+  # GET /api/v1/requirements - The business requirements of the resources a query selects (see Archsight::Requirements)
+  get "/api/v1/requirements" do
+    query = params[:of]
+    json_error("Query parameter 'of' is required", status: 400, error_type: "BadRequest") unless query
+
+    priority = csv_param(:priority, Archsight::Requirements::PRIORITIES)
+    status = csv_param(:status, Archsight::Requirements::STATUSES.values)
+    start_time = Time.now
+
+    begin
+      requirements = Archsight::Requirements.collect(db, of: query, priority: priority, status: status)
+      json_response(build_requirements_response(query, requirements, ((Time.now - start_time) * 1000).round(2)))
+    rescue Archsight::Query::QueryError => e
+      json_error(e.message, status: 400, error_type: "QueryError", query: query)
+    end
+  end
+
   # GET /api/v1/assets/*path - Images and draw.io diagrams that markdown embeds. The path is relative to the
   # resources directory; only files of the allowed types inside it are ever served, never anything outside of
   # it and never resource definitions (see Archsight::Assets). Outside, missing and not-served-type all

data/lib/archsight/web/application.rb

@@ -140,6 +140,9 @@ class Archsight::Web::Application < Sinatra::Base
       html = Archsight::Helpers::AssetImages.rewrite(html, base_dir: base, resources_dir: Archsight.resources_dir) if base
       # ```asd blocks become placeholders until the text passes below are done (see DiagramBlocks)
       html, diagrams = Archsight::Helpers::DiagramBlocks.extract(html, resolver: Archsight::Helpers::ResourceResolver.new(db))
+      # so are ```view and ```requirements blocks (see ViewBlocks, RequirementsBlocks)
+      html, views = Archsight::Helpers::ViewBlocks.extract(html)
+      html, requirements = Archsight::Helpers::RequirementsBlocks.extract(html)
 
       # Resolve relative URLs if we have a git URL (for repository READMEs)
       if git_url && (base_url = github_raw_base_url(git_url))
@@ -157,7 +160,9 @@ class Archsight::Web::Application < Sinatra::Base
       # Convert [[Target]] / [[Target|label]] wiki-style links to page and resource links
       html = Archsight::Helpers::Embeds.new(db).render(html)
       html = Archsight::Helpers::WikiLinks.new(db).render(Archsight::Helpers::Macros.render(html, context: Archsight::Helpers::Macros::Context.new(db, page)))
-      Archsight::Helpers::DiagramBlocks.restore(html, diagrams)
+      html = Archsight::Helpers::DiagramBlocks.restore(html, diagrams)
+      html = Archsight::Helpers::ViewBlocks.restore(html, views)
+      Archsight::Helpers::RequirementsBlocks.restore(html, requirements)
     end
 
     # Generate asset path with cache-busting query string based on file mtime

data/lib/archsight/web/public/vue/ApiDocsPage-D-cPRZCT.js

@@ -0,0 +1 @@
+import{$ as e,B as t,H as n,M as r,T as i,X as a,Y as o,j as s,k as c,t as l,x as u}from"./index-D7m61Ahx.js";var d={class:`api-docs-page`},f={key:0,class:`pico-color-red-500`},p=l({__name:`ApiDocsPage`,setup(l){let p=u(),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 t(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}}),(t,o)=>(n(),r(`div`,d,[c(`a`,{href:`#`,class:`back-link`,onClick:o[0]||=i(e=>a(p).back(),[`prevent`])},`← Back`),h.value?(n(),r(`div`,f,e(h.value),1)):s(``,!0),c(`div`,{ref_key:`container`,ref:m},null,512)]))}},[[`__scopeId`,`data-v-4823b89b`]]);export{p as default};

data/lib/archsight/web/public/vue/ApiDocsPage-DZ0fa5-h.css

@@ -0,0 +1 @@
+.back-link[data-v-4823b89b]{z-index:100;font-size:var(--fs-sm);background:#fff;border:1px solid #ddd;border-radius:4px;padding:6px 14px;text-decoration:none;position:fixed;top:12px;right:12px;box-shadow:0 1px 4px #0000001a}

data/lib/archsight/web/public/vue/{DocPage-uaT8CdFm.js → DocPage-DK6vNDbF.js}

@@ -1 +1 @@
-import{G as e,J as t,O as n,V as r,j as i,k as a,s as o}from"./index-CyVWObLU.js";import{t as s}from"./WikiPage-DbmWkM7W.js";var c={key:1},l={__name:`DocPage`,props:{filename:String},setup(l){let u=l,d=t(null);function f(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 p(){let e=await o(u.filename);d.value=e?f(e,u.filename):{title:`Not found`,html:`<p>Documentation not found.</p>`,toc:[],breadcrumb:[{title:`Documentation`}]},document.title=`${d.value.title} - Archsight`}return e(()=>u.filename,p,{immediate:!0}),(e,t)=>d.value?(r(),a(s,{key:0,title:d.value.title,html:d.value.html,breadcrumb:d.value.breadcrumb,toc:d.value.toc},null,8,[`title`,`html`,`breadcrumb`,`toc`])):(r(),i(`article`,c,[...t[0]||=[n(`p`,null,`Loading...`,-1)]]))}};export{l as default};
+import{A as e,H as t,K as n,M as r,Y as i,k as a,s as o}from"./index-D7m61Ahx.js";import{t as s}from"./WikiPage-CeCQBTDS.js";var c={key:1},l={__name:`DocPage`,props:{filename:String},setup(l){let u=l,d=i(null);function f(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 p(){let e=await o(u.filename);d.value=e?f(e,u.filename):{title:`Not found`,html:`<p>Documentation not found.</p>`,toc:[],breadcrumb:[{title:`Documentation`}]},document.title=`${d.value.title} - Archsight`}return n(()=>u.filename,p,{immediate:!0}),(n,i)=>d.value?(t(),e(s,{key:0,title:d.value.title,html:d.value.html,breadcrumb:d.value.breadcrumb,toc:d.value.toc},null,8,[`title`,`html`,`breadcrumb`,`toc`])):(t(),r(`article`,c,[...i[0]||=[a(`p`,null,`Loading...`,-1)]]))}};export{l as default};