Almirah 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3c6b1d68ee25c9b62690c4cdda45ec2d790960a6e75762576ddc60d6c3136e5
-  data.tar.gz: 334ef7251595119cd27bf980eeb53a8f02d913cde7d2fc5d0844a1d863b6c825
+  metadata.gz: b4a6b0c92714af081d54b235449ab825fa86842d61869f31cd331a44c702efdc
+  data.tar.gz: cf2074e5c3f500689359912872166c1f13c08e59bde29408c90ee7b34fbe18fe
 SHA512:
-  metadata.gz: 20383b85a3d59d35a3c6259095e7e8b6709055b6670e2b651fdecdd814eee54b71ebf7d2cc1958c85bc998a426361dfff470c1c10749044334ae7ec7f1a69616
-  data.tar.gz: d1d066ecfc0cfe644eaa28f42d793342e328f42d3eefc0e1fdeb2290c8ff281009bd59b99d23893604f89927ab698a922ef844af1e702c45a3a0a5d51926ff84
+  metadata.gz: 21654dccede23f1828f02b4446f11f626d12ee5d7d3689b96636d6b1be0465de44fddbacd05606935326a27d4317bfaf0b5596813e907a38580ea6591bc430ca
+  data.tar.gz: d3821259aeb7e5ff6306c3d9ccec25720030e659e351cd2c32a7791a8520ddea0039e6cab7f083b0244c82095e7c219c14de465bcda55b326eca184d06ce3bc7

data/lib/almirah/console_reporter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Reporter prints concise, aligned progress lines for the processing pipeline:
+#
+#   parsing specifications ..... 4 ok
+#   parsing test protocols ..... 2 ok
+#   parsing decisions .......... 14 ok
+#   traceability matrices ...... 4 ok
+#   coverage matrices .......... 1 ok
+#   implementation matrices .... 1 ok
+#   decision links ............. 5 ok
+#   rendering HTML ............. ./build/index.html
+#
+# ANSI colour is applied only when writing to an interactive terminal, so piped
+# or captured output stays clean.
+module ConsoleReporter
+  COLUMN = 28 # label is dot-padded out to this column, then the value follows
+
+  module_function
+
+  def count(label, number)
+    emit(label, "#{number} ok", 92) # green highlight
+  end
+
+  def result(label, value)
+    emit(label, value, 96) # cyan highlight
+  end
+
+  def warn(label, value)
+    emit(label, value.to_s, 91) # red highlight
+  end
+
+  # Colourises a detail line with the same red as warn (TTY-gated).
+  def warn_detail(text)
+    colorize(text, 91)
+  end
+
+  def emit(label, value, color_code)
+    dotted = "#{label} ".ljust(COLUMN, '.')
+    puts "#{dotted} #{colorize(value, color_code)}"
+  end
+
+  def colorize(text, color_code)
+    $stdout.tty? ? "\e[#{color_code}m#{text}\e[0m" : text
+  end
+end

data/lib/almirah/doc_fabric.rb

@@ -17,12 +17,6 @@ class DocFabric
   @@spec_colors = %w[cff4d2 fbeee6 ffcad4 bce6ff e4dfd9 f9e07f cbe54e d3e7ee eab595 86e3c3
                      ffdca2 ffffff ffdd94 d0e6a5 ffb284 f3dbcf c9bbc8 c6c09c]
 
-  def self.add_lazy_doc_id(path)
-    if res = /(\w+)[.]md$/.match(path)
-      TextLine.add_lazy_doc_id(res[1])
-    end
-  end
-
   def self.create_specification(path)
     color = @@spec_colors[@@color_index]
     @@color_index += 1

data/lib/almirah/doc_items/controlled_table.rb

@@ -151,7 +151,7 @@ class ControlledTable < DocItem # rubocop:disable Style/Documentation
   end
 
   def add_row(row)
-    columns = row.split('|')
+    columns = split_table_cells(row)
 
     @rows.append(format_columns(columns))
 

data/lib/almirah/doc_items/doc_item.rb

@@ -19,4 +19,16 @@ class DocItem < TextLine # rubocop:disable Style/Documentation
   def get_url
     ''
   end
+
+  # Splits a Markdown table row into its cell strings, treating a backslash-escaped
+  # pipe (\|) as a literal character within a cell rather than a column separator
+  # (e.g. a "|" inside an inline code span such as `[[target\|alias]]`). The escaping
+  # backslash is dropped so the cell renders the intended literal pipe.
+  def split_table_cells(row)
+    row.split(/(?<!\\)\|/).map { |cell| cell.gsub('\\|', '|') }
+  end
+
+  def owner_document
+    @parent_doc
+  end
 end

data/lib/almirah/doc_items/markdown_table.rb

@@ -12,7 +12,7 @@ class MarkdownTable < DocItem
 
     res = /^[|](.*[|])/.match(heading_row)
     @column_names = if res
-                      res[1].split('|')
+                      split_table_cells(res[1])
                     else
                       ['# ERROR# ']
                     end
@@ -49,7 +49,7 @@ class MarkdownTable < DocItem
   end
 
   def add_row(row)
-    columns = row.split('|')
+    columns = split_table_cells(row)
     @rows.append(columns.map!(&:strip))
     true
   end

data/lib/almirah/doc_items/text_line.rb

@@ -1,4 +1,6 @@
 require 'cgi'
+require 'uri'
+require_relative '../relative_url'
 
 class TextLineToken
   attr_accessor :value
@@ -50,6 +52,18 @@ class SquareBracketRight < TextLineToken
   end
 end
 
+class DoubleSquareBracketLeft < TextLineToken
+  def initialize # rubocop:disable Lint/MissingSuper
+    @value = '[['
+  end
+end
+
+class DoubleSquareBracketRight < TextLineToken
+  def initialize # rubocop:disable Lint/MissingSuper
+    @value = ']]'
+  end
+end
+
 class SquareBracketRightAndParentheseLeft < TextLineToken
   def initialize
     @value = ']('
@@ -77,6 +91,8 @@ class TextLineParser
     @supported_tokens.append(BoldToken.new)
     @supported_tokens.append(ItalicToken.new)
     @supported_tokens.append(BacktickToken.new)
+    @supported_tokens.append(DoubleSquareBracketLeft.new)
+    @supported_tokens.append(DoubleSquareBracketRight.new)
     @supported_tokens.append(SquareBracketRightAndParentheseLeft.new)
     @supported_tokens.append(ParentheseLeft.new)
     @supported_tokens.append(ParentheseRight.new)
@@ -220,6 +236,10 @@ class TextLineBuilderContext
   def link(_link_text, link_url)
     link_url
   end
+
+  def wiki_link(inner)
+    "[[#{inner}]]"
+  end
 end
 
 class TextLineBuilder
@@ -229,7 +249,7 @@ class TextLineBuilder
     @builder_context = builder_context
   end
 
-  def restore(token_list)
+  def restore(token_list) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
     result = ''
     return '' if token_list.nil?
 
@@ -296,6 +316,25 @@ class TextLineBuilder
           result += '***'
           ti = ti_starting_position + 1
         end
+      when 'DoubleSquareBracketLeft'
+        # wiki/Obsidian link: collect raw text up to the closing "]]"
+        is_found = false
+        ti_starting_position = ti
+        tii = ti + 1
+        while tii < tl
+          if token_list[tii].instance_of?(DoubleSquareBracketRight)
+            inner = token_list[(ti + 1)..(tii - 1)].map(&:value).join
+            result += @builder_context.wiki_link(inner)
+            ti = tii + 1
+            is_found = true
+            break
+          end
+          tii += 1
+        end
+        unless is_found
+          result += '[['
+          ti = ti_starting_position + 1
+        end
       when 'SquareBracketLeft'
         # try to find closing part
         is_found = false
@@ -333,7 +372,7 @@ class TextLineBuilder
       when 'InlineCodeToken'
         result += @builder_context.inline_code(token_list[ti].value)
         ti += 1
-      when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight'
+      when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight', 'DoubleSquareBracketRight'
         result += token_list[ti].value
         ti += 1
       else
@@ -345,11 +384,37 @@ class TextLineBuilder
 end
 
 class TextLine < TextLineBuilderContext
-  @@lazy_doc_id_dict = {}
+  @@link_registry = nil # rubocop:disable Style/ClassVars
+  @@broken_links = [] # rubocop:disable Style/ClassVars
+
+  class << self
+    def link_registry=(registry)
+      @@link_registry = registry # rubocop:disable Style/ClassVars
+    end
 
-  def self.add_lazy_doc_id(id)
-    doc_id = id.to_s.downcase
-    @@lazy_doc_id_dict[doc_id] = doc_id
+    def link_registry
+      @@link_registry
+    end
+
+    # Cross-document links that could not be resolved to a managed document,
+    # collected during rendering for reporting (ADR-186, SRS-094).
+    def broken_links
+      @@broken_links
+    end
+
+    def reset_broken_links
+      @@broken_links = [] # rubocop:disable Style/ClassVars
+    end
+
+    def record_broken_link(document, target)
+      @@broken_links << { document: document&.id, target: target }
+    end
+  end
+
+  # The document that owns this text line. Used to resolve cross-document links
+  # relative to the current page. nil for stand-alone text (e.g. unit tests).
+  def owner_document
+    nil
   end
 
   def format_string(str)
@@ -374,30 +439,60 @@ class TextLine < TextLineBuilderContext
     "<code class=\"inline\">#{CGI.escapeHTML(str)}</code>"
   end
 
-  def link(link_text, link_url)
-    # define default result first
-    result = "<a target=\"_blank\" rel=\"noopener\" href=\"#{link_url}\" class=\"external\">#{link_text}</a>"
+  def link(link_text, link_url) # rubocop:disable Metrics/MethodLength
+    raw = link_url.to_s
+    kind, target, fragment = classify_markdown_link(raw)
+    case kind
+    when :internal
+      href = RelativeUrl.between(owner_document.output_rel_path, target.output_rel_path, fragment: fragment)
+      "<a href=\"#{href}\" class=\"external\">#{link_text}</a>"
+    when :broken
+      TextLine.record_broken_link(owner_document, raw)
+      "<a href=\"#{raw}\" class=\"broken_link\" title=\"Unresolved cross-document link\">#{link_text}</a>"
+    else
+      "<a target=\"_blank\" rel=\"noopener\" href=\"#{raw}\" class=\"external\">#{link_text}</a>"
+    end
+  end
+
+  # Resolves an Obsidian/wiki link "[[target#fragment|alias]]" to a managed
+  # document by its unique id/filename, independent of folder (ADR-186).
+  def wiki_link(inner) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize,Metrics/MethodLength
+    link_part, sep, alias_text = inner.partition('|')
+    target, _hash, fragment = link_part.partition('#')
+    display = (sep.empty? ? link_part : alias_text).strip
+    display = link_part.strip if display.empty?
+
+    doc = TextLine.link_registry&.find_by_id(target.strip)
+    if doc && owner_document&.output_rel_path
+      href = RelativeUrl.between(owner_document.output_rel_path, doc.output_rel_path,
+                                 fragment: fragment.strip.empty? ? nil : fragment.strip)
+      "<a href=\"#{href}\" class=\"external\">#{CGI.escapeHTML(display)}</a>"
+    elsif owner_document&.output_rel_path
+      TextLine.record_broken_link(owner_document, "[[#{inner}]]")
+      "<span class=\"broken_link\" title=\"Unresolved wiki link\">#{CGI.escapeHTML(display)}</span>"
+    else
+      "[[#{inner}]]"
+    end
+  end
+
+  private
 
-    lazy_doc_id = nil
-    anchor = nil
+  # Classifies a Markdown link target as :internal (a managed document, resolved
+  # against the owning document's source directory), :broken (a local .md path
+  # that does not resolve), or :external (everything else). ADR-186.
+  def classify_markdown_link(raw) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    path_part, _sep, fragment = raw.partition('#')
+    path_part = URI::DEFAULT_PARSER.unescape(path_part) # decode %20 etc. to match the real file path
+    return [:external] unless local_markdown_path?(path_part)
 
-    if res = /(\w+)[.]md$/.match(link_url)          # link
-      lazy_doc_id = res[1].to_s.downcase
+    doc = owner_document
+    return [:external] unless doc&.output_rel_path && doc.respond_to?(:path) && doc.path && TextLine.link_registry
 
-    elsif res = /(\w*)[.]md(#.*)$/.match(link_url)  # link with anchor
-      if res && res.length > 2
-        lazy_doc_id = res[1]
-        anchor = res[2]
-      end
-    end
+    target = TextLine.link_registry.find_by_source(File.expand_path(path_part, File.dirname(doc.path)))
+    target ? [:internal, target, fragment.empty? ? nil : fragment] : [:broken]
+  end
 
-    if lazy_doc_id && @@lazy_doc_id_dict.key?(lazy_doc_id)
-      result = if anchor
-                 "<a href=\".\\..\\#{lazy_doc_id}\\#{lazy_doc_id}.html#{anchor}\" class=\"external\">#{link_text}</a>"
-               else
-                 "<a href=\".\\..\\#{lazy_doc_id}\\#{lazy_doc_id}.html\" class=\"external\">#{link_text}</a>"
-               end
-    end
-    result
+  def local_markdown_path?(path_part)
+    path_part.match?(/\.(md|markdown)\z/i) && !path_part.match?(%r{\A[a-z][a-z0-9+.\-]*://}i)
   end
 end

data/lib/almirah/doc_types/base_document.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative '../relative_url'
+
 class BaseDocument # rubocop:disable Style/Documentation
-  attr_accessor :title, :id, :dom, :headings
+  attr_accessor :title, :id, :dom, :headings, :output_rel_path
 
   class << self
     attr_accessor :show_decisions_link
@@ -32,6 +34,7 @@ class BaseDocument # rubocop:disable Style/Documentation
                         else
                           "#{@id}/#{@id}.html"
                         end
+    @output_rel_path = output_file_path.split('/build/', 2).last
     file = File.open(output_file_path, 'w')
     file_data.each do |s| # rubocop:disable Metrics/BlockLength
       if s.include?('{{CONTENT}}')
@@ -43,51 +46,21 @@ class BaseDocument # rubocop:disable Style/Documentation
       elsif s.include?('{{DOCUMENT_TITLE}}')
         file.puts s.gsub! '{{DOCUMENT_TITLE}}', @title
       elsif s.include?('{{STYLES_AND_SCRIPTS}}')
+        file.puts "<link rel=\"stylesheet\" href=\"#{rel_to('css/main.css')}\">"
+        file.puts "<script src=\"#{rel_to('scripts/main.js')}\"></script>"
         if @id == 'index'
-          file.puts '<script type="module" src="./scripts/orama_search.js"></script>'
-          file.puts '<link rel="stylesheet" href="./css/search.css">'
-          file.puts '<link rel="stylesheet" href="./css/main.css">'
-          file.puts '<script src="./scripts/main.js"></script>'
-        elsif instance_of? Specification
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Traceability
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Coverage
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Implementation
-          file.puts '<link rel="stylesheet" href="../../css/main.css">'
-          file.puts '<script src="../../scripts/main.js"></script>'
-        elsif instance_of? Protocol
-          file.puts '<link rel="stylesheet" href="../../../css/main.css">'
-          file.puts '<script src="../../../scripts/main.js"></script>'
+          file.puts "<script type=\"module\" src=\"#{rel_to('scripts/orama_search.js')}\"></script>"
+          file.puts "<link rel=\"stylesheet\" href=\"#{rel_to('css/search.css')}\">"
         elsif instance_of? DecisionsOverview
-          file.puts '<link rel="stylesheet" href="../css/main.css">'
-          file.puts '<script src="../scripts/main.js"></script>'
           file.puts '<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>'
-        elsif instance_of? Decision
-          file.puts "<link rel=\"stylesheet\" href=\"#{root_prefix}css/main.css\">"
-          file.puts "<script src=\"#{root_prefix}scripts/main.js\"></script>"
         end
       elsif s.include?('{{HOME_BUTTON}}')
         if @id == 'index'
-          file.puts '<a id="home_menu_item" href="./index.html"><span><i class="fa fa-home" aria-hidden="true"></i></span>&nbsp;Home</a>'
-          file.puts decisions_link('./decisions/overview.html') if BaseDocument.show_decisions_link
-        elsif instance_of? Protocol
-          file.puts '<a id="index_menu_item" href="./../../../index.html"><span><i class="fa fa-info" aria-hidden="true"></i></span>&nbsp;Index</a>'
-          file.puts decisions_link('./../../../decisions/overview.html') if BaseDocument.show_decisions_link
-        elsif instance_of? DecisionsOverview
-          file.puts index_link('./../index.html')
-          file.puts decisions_link('./overview.html')
-        elsif instance_of? Decision
-          file.puts index_link("#{root_prefix}index.html")
-          file.puts decisions_link("#{root_prefix}decisions/overview.html")
+          file.puts home_link(rel_to('index.html'))
         else
-          file.puts '<a id="index_menu_item" href="./../../index.html"><span><i class="fa fa-info" aria-hidden="true"></i></span>&nbsp;Index</a>'
-          file.puts decisions_link('./../../decisions/overview.html') if BaseDocument.show_decisions_link
+          file.puts index_link(rel_to('index.html'))
         end
+        file.puts decisions_link(rel_to('decisions/overview.html')) if BaseDocument.show_decisions_link
       elsif s.include?('{{GEM_VERSION}}')
         file.puts "(#{Gem.loaded_specs['Almirah'].version.version})"
       else
@@ -106,4 +79,14 @@ class BaseDocument # rubocop:disable Style/Documentation
     icon = '<span><i class="fa fa-info" aria-hidden="true"></i></span>'
     %(<a id="index_menu_item" href="#{href}">#{icon}&nbsp;Index</a>)
   end
+
+  def home_link(href)
+    icon = '<span><i class="fa fa-home" aria-hidden="true"></i></span>'
+    %(<a id="home_menu_item" href="#{href}">#{icon}&nbsp;Home</a>)
+  end
+
+  # Relative URL from this page to a target path under the build root.
+  def rel_to(target)
+    RelativeUrl.between(@output_rel_path, target)
+  end
 end

data/lib/almirah/doc_types/decisions_overview.rb

@@ -72,6 +72,10 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
     [75, 192, 192], [153, 102, 255], [201, 203, 207]
   ].freeze
 
+  # Records with a missing or ambiguous current-status marker are surfaced under
+  # this category as a data-quality indicator rather than being silently dropped.
+  UNDEFINED_STATUS_LABEL = 'Undefined'
+
   def render_charts_grid # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
     counts = @project.project_data.decisions.each_with_object(Hash.new(0)) do |item, cntr|
       cntr[item.record_type] += 1 if item.record_type
@@ -81,6 +85,7 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
     pie_colors = labels.each_with_index.map { |_, i| palette_rgba(i, 0.5) }
 
     velocity = velocity_chart_data
+    status_dist = status_distribution_chart_data
 
     <<~HTML
       <div class="decisions_overview_charts">
@@ -115,7 +120,20 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
       \t\t\t});
       \t\t</script>
       \t</div>
-      \t<div class="chart_cell"></div>
+      \t<div class="chart_cell">
+      \t\t<canvas id="decisions_status_bar"></canvas>
+      \t\t<script>
+      \t\t\tnew Chart(document.getElementById('decisions_status_bar'), {
+      \t\t\t\ttype: 'bar',
+      \t\t\t\tdata: #{status_dist.to_json},
+      \t\t\t\toptions: {
+      \t\t\t\t\tindexAxis: 'y',
+      \t\t\t\t\tplugins: { title: { display: true, text: 'Decision Records by Current Status' }, legend: { display: false } },
+      \t\t\t\t\tscales: { x: { beginAtZero: true, ticks: { precision: 0 } } }
+      \t\t\t\t}
+      \t\t\t});
+      \t\t</script>
+      \t</div>
       </div>
     HTML
   end
@@ -144,6 +162,32 @@ class DecisionsOverview < BaseDocument # rubocop:disable Style/Documentation,Met
     }
   end
 
+  # Tally each decision record under its current status (the "*"-marked Status
+  # row). Records whose current status is undefined fall under "Undefined", which
+  # is ordered last; real statuses keep first-seen order. The count is baked into
+  # each label so small categories stay legible on a linear axis next to a
+  # dominant one.
+  def status_distribution_chart_data # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    counts = Hash.new(0)
+    keys = []
+    @project.project_data.decisions.each do |doc|
+      status = doc.current_status
+      key = status.nil? || status.strip.empty? ? UNDEFINED_STATUS_LABEL : status
+      keys << key unless counts.key?(key)
+      counts[key] += 1
+    end
+    keys << UNDEFINED_STATUS_LABEL if keys.delete(UNDEFINED_STATUS_LABEL)
+
+    colors = keys.each_with_index.map do |k, i|
+      k == UNDEFINED_STATUS_LABEL ? palette_rgba(CHART_PALETTE.length - 1, 0.5) : palette_rgba(i, 0.5)
+    end
+    {
+      labels: keys.map { |k| "#{k} (#{counts[k]})" },
+      datasets: [{ label: 'Decision records', data: keys.map { |k| counts[k] },
+                   backgroundColor: colors, borderWidth: 0 }]
+    }
+  end
+
   def palette_rgba(index, alpha)
     r, g, b = CHART_PALETTE[index % CHART_PALETTE.length]
     "rgba(#{r}, #{g}, #{b}, #{alpha})"

data/lib/almirah/doc_types/source_file.rb

@@ -25,7 +25,6 @@ class SourceFile < PersistentDocument
     depth = relative_path.count('/') + 1 # +1 for the repository folder
     depth += 1 # for the source_files folder
     @specifications_path = "./#{'../' * depth}specifications/"
-    puts @specifications_path
   end
 
   def to_console
@@ -78,13 +77,10 @@ class SourceFile < PersistentDocument
     @html_file_path = output_file_path
     FileUtils.mkdir_p(File.dirname(output_file_path))
 
-    # Calculate the relative path depth to determine correct number of parent directory symbols
-    relative_path = @path.sub("#{@root_path}/", '')
-    depth = relative_path.count('/') + 1 # +1 for the repository folder
-    depth += 1 # for the source_files folder
-    css_path = "#{'../' * depth}css/main.css"
-    js_path = "#{'../' * depth}scripts/main.js"
-    index_path = "#{'../' * depth}index.html"
+    @output_rel_path = output_file_path.split('/build/', 2).last
+    css_path = rel_to('css/main.css')
+    js_path = rel_to('scripts/main.js')
+    index_path = rel_to('index.html')
 
     file = File.open(output_file_path, 'w')
     file_data.each do |s|

data/lib/almirah/link_registry.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Project-wide registry of managed documents, used to resolve cross-document
+# links (ADR-186) to their generated output pages. Documents are indexed by
+# their id / filename stem (case-insensitive, folder-independent) and, when they
+# originate from a source file, by their absolute source path (for native
+# Markdown relative links).
+class LinkRegistry
+  attr_reader :collisions
+
+  def initialize
+    @by_id = {}
+    @by_source = {}
+    @collisions = []
+  end
+
+  # Each registered document is expected to already carry an output_rel_path
+  # (its generated page, relative to the build root).
+  def register(doc)
+    key = doc.id.to_s.downcase
+    if @by_id.key?(key) && !@by_id[key].equal?(doc)
+      @collisions << key
+    else
+      @by_id[key] = doc
+    end
+    return unless doc.respond_to?(:path) && doc.path
+
+    @by_source[File.expand_path(doc.path)] = doc
+  end
+
+  def find_by_id(id)
+    @by_id[id.to_s.downcase]
+  end
+
+  def find_by_source(source_path)
+    @by_source[File.expand_path(source_path)]
+  end
+end

data/lib/almirah/project/project_data.rb

@@ -1,9 +1,11 @@
+require_relative '../link_registry'
+
 class ProjectData
   attr_reader :specifications, :protocols, :traceability_matrices, :coverage_matrices, :source_files,
               :specifications_dictionary, :covered_specifications_dictionary, :implemented_specifications_dictionary,
-              :implementation_matrices, :decisions
+              :implementation_matrices, :decisions, :link_registry
 
-  def initialize
+  def initialize # rubocop:disable Metrics/MethodLength
     @specifications = []
     @protocols = []
     @traceability_matrices = []
@@ -15,5 +17,7 @@ class ProjectData
     @specifications_dictionary = {}
     @covered_specifications_dictionary = {}
     @implemented_specifications_dictionary = {}
+
+    @link_registry = LinkRegistry.new
   end
 end

data/lib/almirah/project.rb

@@ -9,6 +9,8 @@ require_relative 'search/specifications_db'
 require_relative 'project/doc_linker'
 require_relative 'project_configuration'
 require_relative 'project/project_data'
+require_relative 'console_reporter'
+require_relative 'relative_url'
 
 class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
   attr_accessor :index, :project, :configuration, :project_data
@@ -47,6 +49,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     link_all_source_files
     link_all_decisions
     check_wrong_specification_referenced
+    build_link_registry
     create_index
     render_all_specifications(@project_data.specifications)
     render_all_specifications(@project_data.traceability_matrices)
@@ -58,6 +61,8 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     render_all_decisions
     render_index
     create_search_data
+    report_broken_links
+    report_rendered
   end
 
   def specifications_and_results(test_run) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
@@ -70,6 +75,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     link_all_source_files
     link_all_decisions
     check_wrong_specification_referenced
+    build_link_registry
     create_index
     render_all_specifications(@project_data.specifications)
     render_all_specifications(@project_data.traceability_matrices)
@@ -81,20 +87,60 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     render_all_decisions
     render_index
     create_search_data
+    report_broken_links
+    report_rendered
+  end
+
+  def report_rendered
+    root = @configuration.project_root_directory
+    base = root == Dir.pwd ? '.' : root
+    ConsoleReporter.result('rendering HTML', File.join(base, 'build', 'index.html'))
+  end
+
+  # Reports cross-document links that could not be resolved (ADR-186, SRS-094),
+  # naming the linking document. The build still completes.
+  def report_broken_links
+    broken = TextLine.broken_links
+    return if broken.empty?
+
+    ConsoleReporter.warn('broken links', broken.length)
+    broken.each { |b| puts ConsoleReporter.warn_detail("  #{b[:document] || '?'}: #{b[:target]}") }
+  end
+
+  # Assigns each document its generated output path (relative to the build root)
+  # and registers it for cross-document link resolution (ADR-186). Runs after all
+  # documents are parsed and before any rendering, so link targets are known.
+  def build_link_registry # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    reg = @project_data.link_registry
+    TextLine.link_registry = reg
+    TextLine.reset_broken_links
+    @project_data.specifications.each do |d|
+      d.output_rel_path = "specifications/#{d.id}/#{d.id}.html"
+      reg.register(d)
+    end
+    @project_data.protocols.each do |d|
+      d.output_rel_path = "tests/protocols/#{d.id}/#{d.id}.html"
+      reg.register(d)
+    end
+    @project_data.decisions.each do |d|
+      d.output_rel_path = "decisions/#{d.html_rel_path}"
+      reg.register(d)
+    end
+    @project_data.source_files.each do |d|
+      rel = d.path.sub("#{d.root_path}/", '')
+      d.output_rel_path = "source_files/#{d.repository}/#{rel}.html"
+      reg.register(d)
+    end
   end
 
   def parse_all_specifications
     path = @configuration.project_root_directory
-    # do a lasy pass first to get the list of documents id
     Dir.glob("#{path}/specifications/**/*.md").each do |f|
-      DocFabric.add_lazy_doc_id(f)
-    end
-    # parse documents in the second pass
-    Dir.glob("#{path}/specifications/**/*.md").each do |f| # rubocop:disable Style/CombinableLoops
       doc = DocFabric.create_specification(f)
       @project_data.specifications.append(doc)
       @project_data.specifications_dictionary[doc.id.to_s.downcase] = doc
     end
+    ConsoleReporter.count('parsing specifications', @project_data.specifications.length)
   end
 
   def parse_all_protocols
@@ -103,6 +149,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       doc = DocFabric.create_protocol(f)
       @project_data.protocols.append(doc)
     end
+    ConsoleReporter.count('parsing test protocols', @project_data.protocols.length)
   end
 
   def parse_all_source_files
@@ -132,6 +179,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       @project_data.decisions.append(doc)
     end
     BaseDocument.show_decisions_link = @project_data.decisions.any?
+    ConsoleReporter.count('parsing decisions', @project_data.decisions.length)
   end
 
   def parse_test_run(test_run)
@@ -158,6 +206,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
         @project_data.traceability_matrices.append doc
       end
     end
+    ConsoleReporter.count('traceability matrices', @project_data.traceability_matrices.length)
   end
 
   def link_all_protocols # rubocop:disable Metrics/MethodLength
@@ -174,16 +223,20 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       doc = DocFabric.create_coverage_matrix(value)
       @project_data.coverage_matrices.append doc
     end
+    ConsoleReporter.count('coverage matrices', @project_data.coverage_matrices.length)
   end
 
   def link_all_decisions
+    number_of_links = 0
     @project_data.decisions.each do |d|
       @project_data.specifications.each do |s|
         next unless d.up_link_docs.key?(s.id.to_s)
 
         DocLinker.link_decision_to_spec(d, s)
+        number_of_links += 1
       end
     end
+    ConsoleReporter.count('decision links', number_of_links)
   end
 
   def link_all_source_files
@@ -194,6 +247,7 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       doc = DocFabric.create_implementation_document(value)
       @project_data.implementation_matrices.append doc
     end
+    ConsoleReporter.count('implementation matrices', @project_data.implementation_matrices.length)
   end
 
   def check_wrong_specification_referenced # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
@@ -267,14 +321,12 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     @index = Index.new(@project)
   end
 
-  def render_all_specifications(spec_list) # rubocop:disable Metrics/MethodLength
+  def render_all_specifications(spec_list)
     path = @configuration.project_root_directory
 
     FileUtils.mkdir_p("#{path}/build/specifications")
 
     spec_list.each do |doc|
-      doc.to_console
-
       img_src_dir = "#{path}/specifications/#{doc.id}/img"
       img_dst_dir = "#{path}/build/specifications/#{doc.id}/img"
 
@@ -310,8 +362,6 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     FileUtils.mkdir_p("#{path}/build/source_files")
 
     @project_data.source_files.each do |doc|
-      doc.to_console
-
       doc.to_html("#{path}/build/source_files/")
     end
   end
@@ -320,8 +370,6 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     path = @configuration.project_root_directory
 
     doc = @index
-    doc.to_console
-
     doc.to_html("#{path}/build/")
   end
 
@@ -332,7 +380,6 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
     FileUtils.mkdir_p("#{path}/build/decisions")
 
     doc = DocFabric.create_decisions_overview(@project)
-    doc.to_console
     doc.to_html("#{path}/build/decisions/")
   end
 
@@ -347,7 +394,6 @@ class Project # rubocop:disable Metrics/ClassLength,Style/Documentation
       depth = 1 + (out_dir_rel == '.' ? 0 : out_dir_rel.split('/').size)
       doc.root_prefix = '../' * depth
       doc.specifications_path = "./#{doc.root_prefix}specifications/"
-      doc.to_console
       doc.to_html(NavigationPane.new(doc), "#{out_dir}/")
     end
   end

data/lib/almirah/project_configuration.rb

@@ -4,7 +4,7 @@ class ProjectConfiguration
     attr_accessor :project_root_directory, :parameters
 
     def initialize(path)
-        @project_root_directory = path
+        @project_root_directory = File.expand_path(path)
         @parameters = {}
         load_project_file
     end

data/lib/almirah/project_template.rb

@@ -14,6 +14,7 @@ class ProjectTemplate # rubocop:disable Style/Documentation
     create_architecture
     create_tests
     create_test_runs
+    create_decisions
   end
 
   def create_requirements
@@ -265,7 +266,7 @@ class ProjectTemplate # rubocop:disable Style/Documentation
   end
 
   def run_test_003
-    path = File.join(@project_root, 'tests/runs/010/tq-002')
+    path = File.join(@project_root, 'tests/runs/010/tq-001')
     FileUtils.mkdir_p path
 
     file_content = <<~EOS
@@ -295,4 +296,91 @@ class ProjectTemplate # rubocop:disable Style/Documentation
     file.puts file_content
     file.close
   end
+
+  def create_decisions
+    path = File.join(@project_root, 'decisions')
+    FileUtils.mkdir_p path
+
+    file_content = <<~EOS
+      ---
+      title: "ADR-001: Start Project Decision"
+      ---
+
+      # Status
+
+      |  | Date | Status |
+      |:---:|---|---|
+      | * | #{Time.now.strftime('%d-%m-%Y')} | Proposed |
+
+      # Context
+
+      This is an example decision record. It demonstrates how Almirah captures a
+      decision and links it to the requirements it affects.
+
+      # Decision
+
+      Describe the decision here. The leading "*" in the Status table marks the
+      current state of the record.
+
+      # Scope
+
+      | Item | Status | Start Date | Target Date | Description |
+      |---|---|---|---|---|
+      | Requirements | To Do | | | |
+      | Code | To Do | | | |
+      | Tests | To Do | | | |
+
+      # Out of Scope
+
+      The ADR contains the most important sections with no detailed content.
+
+      # Consequences
+
+      ## Positive
+
+      An ADR example will clearly show the approach Almirah framework use for any software changes.
+
+      ## Negative
+
+      The format of this ADR can be different that is required for the real project.
+
+      ## Neutral
+
+      TBD
+
+      # Alternatives Considered
+
+      - **Add an empty `decisions/` directory only.** Rejected: an empty folder neither teaches the format nor causes the overview page to render, so it would not exercise the feature.
+
+      # Affected Documents
+
+      Table below shows a requirement whose text this decision creates or updates.
+
+      | # | Proposed Text | Req-ID |
+      |---|---|---|
+      | 1 | This is a first requirement (controlled paragraph with ID equal to "REQ-001"). | >[REQ-001] |
+
+      # Software Versions
+
+      | Software Version Category | Software Version ID |
+      |---|---|
+      | Latest Released Version | n/a |
+      | Issue Found in Version | n/a |
+      | Target Release Version | 0.0.1 |
+
+      # References
+
+      TBD
+
+      # Review Evidences
+
+      TBD
+
+    EOS
+
+    path = File.join(path, 'adr-001-start-project-decision.md')
+    file = File.open(path, 'w')
+    file.puts file_content
+    file.close
+  end
 end

data/lib/almirah/relative_url.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+# Computes the relative URL between two generated pages, each given as a path
+# relative to the build root (e.g. "decisions/release 0.4.1/adr-185.html").
+# Produces forward-slash separators with spaces percent-encoded. Shared by all
+# internal cross-document links (ADR-186).
+module RelativeUrl
+  module_function
+
+  def between(from_output_rel, to_output_rel, fragment: nil)
+    from_dir = Pathname.new(from_output_rel).dirname
+    rel = Pathname.new(to_output_rel).relative_path_from(from_dir).to_s
+    url = rel.split('/').map { |segment| encode_segment(segment) }.join('/')
+    fragment && !fragment.empty? ? "#{url}##{fragment}" : url
+  end
+
+  def encode_segment(segment)
+    segment.gsub(' ', '%20')
+  end
+end

data/lib/almirah/search/specifications_db.rb

@@ -16,7 +16,7 @@ class SpecificationsDb
     @specifications.each do |sp|
       sp.items.each do |i|
         if (i.instance_of? Paragraph) or (i.instance_of? ControlledParagraph)
-          e = { 'document' => i.parent_doc.title, \
+          e = { 'doc_title' => i.parent_doc.title, \
                 'doc_color' => i.parent_doc.color, \
                 'text' => i.text, \
                 'heading_url' => i.parent_heading.get_url, \
@@ -36,7 +36,7 @@ class SpecificationsDb
     item_to_process.rows.each do |r|
       if r.is_a?(MarkdownList)
         f_text = r.text
-        e = {   'document' => item_for_reference.parent_doc.title, \
+        e = {   'doc_title' => item_for_reference.parent_doc.title, \
                 'doc_color' => item_for_reference.parent_doc.color, \
                 'text' => f_text, \
                 'heading_url' => item_for_reference.parent_heading.get_url, \
@@ -45,7 +45,7 @@ class SpecificationsDb
         add_markdown_list_item_to_db(data, item_for_reference, r)
       else
         f_text = r
-        e = {   'document' => item_for_reference.parent_doc.title, \
+        e = {   'doc_title' => item_for_reference.parent_doc.title, \
                 'doc_color' => item_for_reference.parent_doc.color, \
                 'text' => f_text, \
                 'heading_url' => item_for_reference.parent_heading.get_url, \
@@ -61,7 +61,7 @@ class SpecificationsDb
     item_to_process.rows.each do |row|
       table_text += "| #{row.join(' | ')} |"
     end
-    e = {   'document' => item_for_reference.parent_doc.title, \
+    e = {   'doc_title' => item_for_reference.parent_doc.title, \
             'doc_color' => item_for_reference.parent_doc.color, \
             'text' => table_text, \
             'heading_url' => item_for_reference.parent_heading.get_url, \

data/lib/almirah/templates/css/main.css

@@ -154,6 +154,11 @@ a:active {
     text-decoration: none;
     display: inline-block;
 }
+a.broken_link, a.broken_link:link, a.broken_link:visited, span.broken_link {
+    color: #c00;
+    text-decoration: underline wavy #c00;
+    cursor: help;
+}
 div.blockquote {
     display: block;
     background:#f9f9fb;

data/lib/almirah/templates/scripts/orama_search.js

@@ -1,5 +1,5 @@
 // Do search only on the Index Page
-import { create, search, insert } from 'https://unpkg.com/@orama/orama@latest/dist/index.js'
+import { create, search, insert } from 'https://unpkg.com/@orama/orama@3.1.18/dist/browser/index.js'
 
 // Create DB
 const db = await create({
@@ -19,7 +19,7 @@ const data_rows = await response.json();
 let i = 0;
 while (i < data_rows.length) {
     await insert(db, {
-        document: data_rows[i]["document"],
+        doc_title: data_rows[i]["doc_title"],
         doc_color: data_rows[i]["doc_color"],
         text: data_rows[i]["text"],
         heading_url: data_rows[i]["heading_url"],
@@ -66,7 +66,7 @@ async function search_onKeyUp(){
     }else{
 
         searchResult.hits.forEach ((value, index, array) =>{
-            const doc_title = value.document["document"]
+            const doc_title = value.document["doc_title"]
             const doc_color = value.document["doc_color"]
             const heading_url = value.document["heading_url"]
             const heading_text = value.document["heading_text"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: Almirah
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Oleksandr Ivanov
@@ -58,6 +58,7 @@ extra_rdoc_files: []
 files:
 - bin/almirah
 - lib/almirah.rb
+- lib/almirah/console_reporter.rb
 - lib/almirah/doc_fabric.rb
 - lib/almirah/doc_items/blockquote.rb
 - lib/almirah/doc_items/code_block.rb
@@ -89,6 +90,7 @@ files:
 - lib/almirah/doc_types/traceability.rb
 - lib/almirah/dom/doc_section.rb
 - lib/almirah/dom/document.rb
+- lib/almirah/link_registry.rb
 - lib/almirah/navigation_pane.rb
 - lib/almirah/project.rb
 - lib/almirah/project/doc_linker.rb
@@ -96,6 +98,7 @@ files:
 - lib/almirah/project_configuration.rb
 - lib/almirah/project_template.rb
 - lib/almirah/project_utility.rb
+- lib/almirah/relative_url.rb
 - lib/almirah/search/specifications_db.rb
 - lib/almirah/source_file_parser.rb
 - lib/almirah/templates/css/main.css