Almirah 0.4.1 → 0.4.3

data/lib/almirah/doc_items/text_line.rb

@@ -1,6 +1,7 @@
 require 'cgi'
 require 'uri'
 require_relative '../relative_url'
+require_relative '../html_safe'
 
 class TextLineToken
   attr_accessor :value
@@ -11,25 +12,25 @@ class TextLineToken
 end
 
 class ItalicToken < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '*'
   end
 end
 
 class BoldToken < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '**'
   end
 end
 
 class BoldAndItalicToken < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '***'
   end
 end
 
 class ParentheseLeft < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '('
   end
 end
@@ -41,7 +42,7 @@ class ParentheseRight < TextLineToken
 end
 
 class SquareBracketLeft < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '['
   end
 end
@@ -53,13 +54,13 @@ class SquareBracketRight < TextLineToken
 end
 
 class DoubleSquareBracketLeft < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '[['
   end
 end
 
 class DoubleSquareBracketRight < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = ']]'
   end
 end
@@ -71,13 +72,13 @@ class SquareBracketRightAndParentheseLeft < TextLineToken
 end
 
 class BacktickToken < TextLineToken
-  def initialize # rubocop:disable Lint/MissingSuper
+  def initialize
     @value = '`'
   end
 end
 
 class InlineCodeToken < TextLineToken
-  def initialize(raw) # rubocop:disable Lint/MissingSuper
+  def initialize(raw)
     @value = raw
   end
 end
@@ -85,7 +86,7 @@ end
 class TextLineParser
   attr_accessor :supported_tokens
 
-  def initialize # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def initialize
     @supported_tokens = []
     @supported_tokens.append(BoldAndItalicToken.new)
     @supported_tokens.append(BoldToken.new)
@@ -101,7 +102,7 @@ class TextLineParser
     @supported_tokens.append(TextLineToken.new)
   end
 
-  def tokenize(str) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/AbcSize,Metrics/PerceivedComplexity
+  def tokenize(str)
     result = []
     sl = str.length
     si = 0
@@ -133,7 +134,7 @@ class TextLineParser
 
   private
 
-  def fuse_backticks(tokens) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+  def fuse_backticks(tokens)
     result = []
     i = 0
     while i < tokens.length
@@ -217,6 +218,12 @@ class TextLineParser
 end
 
 class TextLineBuilderContext
+  # Literal (non-markup) text run. Subclasses encode it for the HTML context;
+  # the base context leaves it untouched for plain reconstruction/unit tests.
+  def literal_text(str)
+    str
+  end
+
   def italic(str)
     str
   end
@@ -249,7 +256,7 @@ class TextLineBuilder
     @builder_context = builder_context
   end
 
-  def restore(token_list) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  def restore(token_list)
     result = ''
     return '' if token_list.nil?
 
@@ -363,7 +370,11 @@ class TextLineBuilder
           tii += 1
         end
         if is_found
-          result += @builder_context.link(restore(sub_list_url_text), restore(sub_list_url_address))
+          # URL is reconstructed raw (not via restore) so scheme classification
+          # and file-path resolution see the original characters; link() applies
+          # attribute escaping and the scheme allow-list (ADR-188).
+          raw_url = (sub_list_url_address || []).map(&:value).join
+          result += @builder_context.link(restore(sub_list_url_text), raw_url)
         else
           result += '['
           ti = ti_starting_position + 1
@@ -373,7 +384,7 @@ class TextLineBuilder
         result += @builder_context.inline_code(token_list[ti].value)
         ti += 1
       when 'TextLineToken', 'ParentheseLeft', 'ParentheseRight', 'SquareBracketRight', 'DoubleSquareBracketRight'
-        result += token_list[ti].value
+        result += @builder_context.literal_text(token_list[ti].value)
         ti += 1
       else
         ti += 1
@@ -384,12 +395,14 @@ class TextLineBuilder
 end
 
 class TextLine < TextLineBuilderContext
-  @@link_registry = nil # rubocop:disable Style/ClassVars
-  @@broken_links = [] # rubocop:disable Style/ClassVars
+  include HtmlSafe
+
+  @@link_registry = nil
+  @@broken_links = []
 
   class << self
     def link_registry=(registry)
-      @@link_registry = registry # rubocop:disable Style/ClassVars
+      @@link_registry = registry
     end
 
     def link_registry
@@ -403,7 +416,7 @@ class TextLine < TextLineBuilderContext
     end
 
     def reset_broken_links
-      @@broken_links = [] # rubocop:disable Style/ClassVars
+      @@broken_links = []
     end
 
     def record_broken_link(document, target)
@@ -423,6 +436,11 @@ class TextLine < TextLineBuilderContext
     tlb.restore(tlp.tokenize(str))
   end
 
+  # Literal text run, HTML-escaped for element content (ADR-188, SRS-096).
+  def literal_text(str)
+    escape_text(str)
+  end
+
   def italic(str)
     "<i>#{str}</i>"
   end
@@ -439,24 +457,27 @@ class TextLine < TextLineBuilderContext
     "<code class=\"inline\">#{CGI.escapeHTML(str)}</code>"
   end
 
-  def link(link_text, link_url) # rubocop:disable Metrics/MethodLength
+  def link(link_text, link_url)
     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>"
+      "<a href=\"#{escape_attr(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>"
+      "<a href=\"#{escape_attr(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>"
+      url = safe_url(raw)
+      return link_text if url.nil? # disallowed scheme: render inert (ADR-188, SRS-098)
+
+      "<a target=\"_blank\" rel=\"noopener\" href=\"#{escape_attr(url)}\" 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
+  def wiki_link(inner)
     link_part, sep, alias_text = inner.partition('|')
     target, _hash, fragment = link_part.partition('#')
     display = (sep.empty? ? link_part : alias_text).strip
@@ -480,7 +501,7 @@ class TextLine < TextLineBuilderContext
   # 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
+  def classify_markdown_link(raw)
     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)
@@ -489,10 +510,14 @@ class TextLine < TextLineBuilderContext
     return [:external] unless doc&.output_rel_path && doc.respond_to?(:path) && doc.path && TextLine.link_registry
 
     target = TextLine.link_registry.find_by_source(File.expand_path(path_part, File.dirname(doc.path)))
-    target ? [:internal, target, fragment.empty? ? nil : fragment] : [:broken]
+    if target
+      [:internal, target, fragment.empty? ? nil : fragment]
+    else
+      [:broken]
+    end
   end
 
   def local_markdown_path?(path_part)
-    path_part.match?(/\.(md|markdown)\z/i) && !path_part.match?(%r{\A[a-z][a-z0-9+.\-]*://}i)
+    path_part.match?(/\.(md|markdown)\z/i) && !path_part.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
   end
 end

data/lib/almirah/doc_items/todo_block.rb

@@ -1,22 +1,21 @@
-require_relative "doc_item"
+require_relative 'doc_item'
 
 class TodoBlock < DocItem
+  attr_accessor :text
 
-    attr_accessor :text
+  def initialize(text)
+    @text = text
+  end
 
-    def initialize(text)
-        @text = text
+  def to_html
+    s = ''
+    f_text = format_string(@text)
+    if @@html_table_render_in_progress
+      s += "</table>\n"
+      @@html_table_render_in_progress = false
     end
 
-    def to_html
-        s = ''
-        f_text = format_string(@text)
-        if @@html_table_render_in_progress
-            s += "</table>\n"
-            @@html_table_render_in_progress = false
-        end
-
-        s += "<div class=\"todoblock\"><p>#{f_text}</div>\n"
-        return s
-    end
-end
+    s += "<div class=\"todoblock\"><p>#{f_text}</div>\n"
+    s
+  end
+end

data/lib/almirah/doc_items/work_item.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# A single Scope-table row of a Decision Record, modelled as a node in the
+# per-row dependency network (ADR-194). Each work item carries its canonical
+# identity (`<record>.<step>.<activity>`), the bounded per-row Status it reads
+# its readiness from (ADR-193), and predecessor / successor edges spanning both
+# intra-record (step order) and cross-record (Depends On) links.
+#
+# `predecessors` / `successors` follow the house list-of-single-key-hashes shape
+# (ADR-197): each entry maps a readable `record.step.activity` label to the
+# resolved WorkItem. Every cross-record edge additionally records whether it
+# stays within a decision_groups folder (in-group) or crosses to another
+# (cross-group); that tag is inert here and consumed by the critical-chain step
+# (ADR-195). Readiness ignores it — a cross-group predecessor blocks exactly
+# like an in-group one.
+class WorkItem
+  # Canonical phase order used only as the fallback for activity-type-aligned
+  # resolution when the prerequisite has no row of the dependent's exact Item.
+  ACTIVITY_ORDER = %w[Analysis Requirements Code Tests].freeze
+
+  attr_reader :record_id, :step, :activity, :owner, :status, :depends_on_refs,
+              :focused_estimate, :safe_estimate, :record_sequence, :start_date, :target_date
+  attr_accessor :predecessors, :successors, :cross_group_predecessor_labels, :resolved_dependencies
+
+  def initialize(record_id:, step:, activity:, owner:, status:, depends_on_refs:, # rubocop:disable Metrics/ParameterLists
+                 focused_estimate: 0.0, safe_estimate: 0.0, record_sequence: 0,
+                 start_date: nil, target_date: nil)
+    @record_id = record_id
+    @step = step
+    @activity = activity.to_s.strip
+    @owner = owner.to_s.strip
+    @status = status.to_s.strip
+    @depends_on_refs = depends_on_refs # array of record ref strings, e.g. ["ADR-193"]
+    # The row's authored committed window (ADR-213): the Scope Start Date and
+    # Target Date as parsed Dates (nil when absent/unparseable). Distinct from the
+    # computed schedule -- these are the author's intent, drawn on the tracking lane.
+    @start_date = start_date
+    @target_date = target_date
+    # Per-row scheduling estimates in working days (ADR-195); the focused estimate
+    # is the scheduling duration, safe - focused the safety aggregated into the
+    # project buffer. record_sequence is the owning record's number, used only as
+    # a deterministic priority tiebreak in the critical-chain scheduler.
+    @focused_estimate = focused_estimate
+    @safe_estimate = safe_estimate
+    @record_sequence = record_sequence
+    @predecessors = []
+    @successors = []
+    @cross_group_predecessor_labels = []
+    # One entry per resolved Depends On reference, keyed by the authored ref:
+    # { ref => { doc:, anchor:, label: } }. `anchor` is the target's resolved
+    # work-item row anchor (nil when the target has no `#` step column, so the
+    # link opens the record page); `label` is the resolved work item's id, for
+    # the link tooltip. Used to render the Depends On cell as deep links.
+    @resolved_dependencies = {}
+  end
+
+  def id
+    "#{@record_id}.#{@step}.#{@activity}"
+  end
+
+  # The anchor of this work item's row in its rendered Scope table — the deep-link
+  # target a dependent record points at. Namespaced with `.scope.` so it never
+  # collides with the Affected Documents controlled table, whose rows anchor on
+  # the same `<record>.<step>` scheme on the same page.
+  def row_anchor
+    "#{@record_id}.scope.#{@step}"
+  end
+
+  def add_resolved_dependency(ref, doc, anchor, label)
+    @resolved_dependencies[ref] = { doc: doc, anchor: anchor, label: label }
+  end
+
+  def activity_rank
+    ACTIVITY_ORDER.index(@activity) || ACTIVITY_ORDER.length
+  end
+
+  # A row is "started" once it leaves To Do; both In-Progress and Done count, so
+  # a Done row whose predecessor never finished is still flagged as a violation.
+  def started?
+    @status == 'In-Progress' || @status == 'Done'
+  end
+
+  def done?
+    @status == 'Done'
+  end
+
+  def add_predecessor(work_item, cross_group:)
+    @predecessors << { work_item.id => work_item }
+    @cross_group_predecessor_labels << work_item.id if cross_group
+  end
+
+  def add_successor(work_item)
+    @successors << { work_item.id => work_item }
+  end
+
+  def predecessor_items
+    @predecessors.map { |edge| edge.values.first }
+  end
+
+  def successor_items
+    @successors.map { |edge| edge.values.first }
+  end
+
+  # Same-record, lower-numbered steps — the intra-record (phase-order) edges.
+  def intra_record_predecessors
+    predecessor_items.select { |p| p.record_id == @record_id }
+  end
+
+  # Resolved Depends On edges into other records (in-group or cross-group alike).
+  def cross_record_predecessors
+    predecessor_items.reject { |p| p.record_id == @record_id }
+  end
+
+  # Kitted when every predecessor — intra- and cross-record, regardless of the
+  # in-group / cross-group tag — is Done; trivially kitted when it has none.
+  def fully_kitted?
+    predecessor_items.all?(&:done?)
+  end
+
+  # A started row with an unfinished lower-numbered step in the same record.
+  def phase_order_violation?
+    started? && intra_record_predecessors.any? { |p| !p.done? }
+  end
+
+  # A started row whose resolved cross-record predecessor is not yet Done.
+  def cross_record_violation?
+    started? && cross_record_predecessors.any? { |p| !p.done? }
+  end
+end

data/lib/almirah/doc_parser.rb

@@ -8,13 +8,14 @@ require_relative 'doc_items/todo_block'
 require_relative 'doc_items/controlled_paragraph'
 require_relative 'doc_items/markdown_table'
 require_relative 'doc_items/controlled_table'
+require_relative 'doc_items/scope_table'
 require_relative 'doc_items/image'
 require_relative 'doc_items/markdown_list'
 require_relative 'doc_items/doc_footer'
 require_relative 'doc_items/frontmatter'
 
-class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
-  def self.try_to_extract_frontmatter(doc, text_lines) # rubocop:disable Metrics/MethodLength
+class DocParser
+  def self.try_to_extract_frontmatter(doc, text_lines)
     lines_to_remove = 0
     frontmatter_lines = ''
     if /^(-{3,})/.match(text_lines[0])
@@ -174,7 +175,7 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
 
           doc.items.append(item)
 
-        elsif res = /^([*\-]\s+)(.*)/.match(s) # check if unordered list start
+        elsif res = /^([*-]\s+)(.*)/.match(s) # check if unordered list start
 
           if doc.title == ''
             # dummy section if root is not a Document Title (level 0)
@@ -187,7 +188,7 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
 
           temp_md_table = process_temp_table(doc, temp_md_table)
 
-          row = res[2]
+          res[2]
 
           if temp_md_list
             temp_md_list.add_row(s)
@@ -201,7 +202,7 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
 
           temp_md_table = process_temp_table(doc, temp_md_table)
 
-          row = res[1]
+          res[1]
 
           if temp_md_list
             temp_md_list.add_row(s)
@@ -248,9 +249,14 @@ class DocParser # rubocop:disable Metrics/ClassLength,Style/Documentation
 
             if temp_md_table
               if temp_md_table.is_separator_detected # if there is a separator
-                # check if parent doc is a Protocol, or a Decision Record inside an "Affected Documents" section
-                if doc.instance_of?(Protocol) ||
-                   (doc.instance_of?(Decision) && in_section?(doc, 'Affected Documents'))
+                # A Decision Record's Scope table is parsed into a purpose-built
+                # ScopeTable (ADR-194); a Protocol, or a Decision inside an
+                # "Affected Documents" section, into a ControlledTable.
+                if doc.instance_of?(Decision) && in_section?(doc, 'Scope') &&
+                   temp_md_table.instance_of?(MarkdownTable)
+                  temp_md_table = ScopeTable.new(doc, temp_md_table)
+                elsif doc.instance_of?(Protocol) ||
+                      (doc.instance_of?(Decision) && in_section?(doc, 'Affected Documents'))
                   # check if it is a controlled table
                   tmp = /(.*)\s+>\[(\S*)\]/.match(row)
                   if tmp && (temp_md_table.instance_of? MarkdownTable)

data/lib/almirah/doc_types/base_document.rb

@@ -2,7 +2,7 @@
 
 require_relative '../relative_url'
 
-class BaseDocument # rubocop:disable Style/Documentation
+class BaseDocument
   attr_accessor :title, :id, :dom, :headings, :output_rel_path
 
   class << self
@@ -17,7 +17,13 @@ class BaseDocument # rubocop:disable Style/Documentation
     @dom = nil
   end
 
-  def save_html_to_file(html_rows, nav_pane, output_file_path) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+  # Whether this page needs the Chart.js library loaded (overridden by the
+  # planning pages that render charts).
+  def needs_chartjs?
+    false
+  end
+
+  def save_html_to_file(html_rows, nav_pane, output_file_path)
     gem_root = File.expand_path './../../..', File.dirname(__FILE__)
     template_file = "#{gem_root}/lib/almirah/templates/page.html"
 
@@ -29,6 +35,8 @@ class BaseDocument # rubocop:disable Style/Documentation
                           "#{@id}.html"
                         elsif instance_of? DecisionsOverview
                           'overview.html'
+                        elsif instance_of? CriticalChainPage
+                          'critical-chain.html'
                         elsif instance_of? Decision
                           "#{@id}.html"
                         else
@@ -36,7 +44,7 @@ class BaseDocument # rubocop:disable Style/Documentation
                         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
+    file_data.each do |s|
       if s.include?('{{CONTENT}}')
         html_rows.each do |r|
           file.puts r
@@ -51,7 +59,7 @@ class BaseDocument # rubocop:disable Style/Documentation
         if @id == 'index'
           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
+        elsif needs_chartjs?
           file.puts '<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>'
         end
       elsif s.include?('{{HOME_BUTTON}}')
@@ -60,7 +68,10 @@ class BaseDocument # rubocop:disable Style/Documentation
         else
           file.puts index_link(rel_to('index.html'))
         end
-        file.puts decisions_link(rel_to('decisions/overview.html')) if BaseDocument.show_decisions_link
+        if BaseDocument.show_decisions_link
+          file.puts decisions_link(rel_to('decisions/overview.html'))
+          file.puts critical_chain_link(rel_to('decisions/critical-chain.html'))
+        end
       elsif s.include?('{{GEM_VERSION}}')
         file.puts "(#{Gem.loaded_specs['Almirah'].version.version})"
       else
@@ -75,6 +86,11 @@ class BaseDocument # rubocop:disable Style/Documentation
     %(<a id="decisions_menu_item" href="#{href}">#{icon}&nbsp;Decision Records</a>)
   end
 
+  def critical_chain_link(href)
+    icon = '<span><i class="fa fa-link" aria-hidden="true"></i></span>'
+    %(<a id="critical_chain_menu_item" href="#{href}">#{icon}&nbsp;Critical Chain</a>)
+  end
+
   def index_link(href)
     icon = '<span><i class="fa fa-info" aria-hidden="true"></i></span>'
     %(<a id="index_menu_item" href="#{href}">#{icon}&nbsp;Index</a>)

data/lib/almirah/doc_types/coverage.rb

@@ -2,7 +2,7 @@
 
 require_relative 'base_document'
 
-class Coverage < BaseDocument # rubocop:disable Style/Documentation
+class Coverage < BaseDocument
   attr_accessor :top_doc, :bottom_doc, :covered_items, :passed_steps_number, :failed_steps_number
 
   def initialize(top_doc)
@@ -21,7 +21,7 @@ class Coverage < BaseDocument # rubocop:disable Style/Documentation
     puts "\e[35mTraceability: #{@id}\e[0m"
   end
 
-  def to_html(nav_pane, output_file_path) # rubocop:disable Metrics/MethodLength
+  def to_html(nav_pane, output_file_path)
     html_rows = []
 
     html_rows.append('')
@@ -43,7 +43,7 @@ class Coverage < BaseDocument # rubocop:disable Style/Documentation
     save_html_to_file(html_rows, nav_pane, output_file_path)
   end
 
-  def render_table_row(top_item) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+  def render_table_row(top_item)
     s = ''
     if top_item.coverage_links
       id_color = if top_item.coverage_links.length > 1