rsmp-validator 0.1.0

data/exe/rsmp-validator

@@ -0,0 +1,121 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'sus'
+require 'sus/config'
+
+def print_help
+  puts <<~HELP
+    RSMP Validator runs conformance tests against RSMP sites and supervisors.
+    Full documentation: https://rsmp-nordic.github.io/rsmp_validator/
+
+    Usage:
+      rsmp-validator [OPTIONS] PATH...
+
+    Examples:
+      rsmp-validator test/site
+      rsmp-validator test/site/core
+      rsmp-validator test/supervisor/connect_spec.rb
+
+    Options:
+      --verbose      Show detailed sus output.
+      --log          Print RSMP log output to stdout.
+      --log PATH     Write RSMP log output to PATH.
+      -h, --help     Show this help.
+
+    Environment:
+      SITE_CONFIG        Path to site test configuration.
+      SUPERVISOR_CONFIG  Path to supervisor test configuration.
+      AUTO_SITE_CONFIG   Path to local site configuration to start automatically.
+  HELP
+end
+
+if ARGV.first == 'help' || ARGV.include?('--help') || ARGV.include?('-h')
+  print_help
+  exit 0
+end
+
+# Parse --log [path] from ARGV before Sus::Config.load consumes remaining args.
+# --log        => RSMP logs to $stdout
+# --log <path> => RSMP logs to file, sus output to console (brief)
+#   + --verbose => sus output also goes to file (interleaved, perfectly ordered)
+# (no --log)   => RSMP logs suppressed
+log_index = ARGV.index('--log')
+log_path = nil
+log_to_stdout = false
+if log_index
+  ARGV.delete_at(log_index)
+  if ARGV[log_index] && !ARGV[log_index].start_with?('-')
+    log_path = ARGV.delete_at(log_index)
+  else
+    log_to_stdout = true
+  end
+end
+
+# Writes to two IOs simultaneously through a single object, so both RSMP messages
+# and Sus verbose output share one file descriptor and are perfectly interleaved.
+class TeeIO
+  def initialize(primary, secondary)
+    @primary = primary
+    @secondary = secondary
+  end
+
+  def write(*args)
+    @primary.write(*args)
+    @secondary.write(*args)
+  end
+
+  def puts(*args)
+    @primary.puts(*args)
+    @secondary.puts(*args)
+  end
+
+  def flush
+    @primary.flush
+    @secondary.flush
+  end
+
+  def isatty       = @primary.isatty
+  def tty?         = @primary.tty?
+end
+
+# Load config/validator.rb instead of config/sus.rb so that conformance tests
+# live in valid/site/ and valid/supervisor/, keeping them separate from the
+# internal tests in test/ that plain `sus` runs.
+validator_config_class = Class.new(Sus::Config) do
+  attr_accessor :log_to_stdout, :log_path, :log_file_io
+
+  def self.path(root)
+    path = File.join(root, 'config/validator.rb')
+    File.exist?(path) ? path : nil
+  end
+end
+
+config = validator_config_class.load
+config.log_to_stdout = log_to_stdout
+config.log_path = log_path
+
+registry = config.registry
+
+def run_suite(config, registry, output, verbose)
+  assertions = Sus::Assertions.default(output: output, verbose: verbose)
+  config.before_tests(assertions)
+  registry.call(assertions)
+  config.after_tests(assertions)
+  exit(1) unless assertions.passed?
+end
+
+# When --log <path> and --verbose are both given, open the file once and share
+# the handle: Sus writes via TeeIO (terminal + file), RSMP writes to the same
+# File object directly. One fd => serialized writes => perfect ordering.
+if log_path && config.verbose?
+  File.open(log_path, 'w') do |log_file|
+    config.log_path = nil
+    config.log_file_io = log_file
+    output = Sus::Output.default(TeeIO.new($stderr, log_file))
+    run_suite(config, registry, output, true)
+  end
+else
+  output = config.verbose? ? config.output : Sus::Output::Null.new
+  run_suite(config, registry, output, config.verbose?)
+end

data/lib/doc_gen/parser.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+# DocGen: Prism-based parser and Jekyll Markdown renderer for test documentation.
+#
+# Usage:
+#   require_relative 'lib/doc_gen/parser'
+#   require_relative 'lib/doc_gen/renderer'
+#
+#   contexts = DocGen::Parser.parse_files(Dir['test/**/*_spec.rb'])
+#   DocGen::Renderer.render(contexts, output_dir: 'docs/tests')
+module DocGen
+  # A context represents a `describe` block. It holds child contexts and specs.
+  Context = Struct.new(:name, :docstring, :children, :file, :line, :parent, keyword_init: true) do
+    # Direct child specs (it/specify blocks).
+    def specs
+      children.grep(Spec)
+    end
+
+    # Direct child contexts (nested describe blocks).
+    def subcontexts
+      children.grep(Context)
+    end
+
+    # Full display name, dropping the root component when nested.
+    # Examples:
+    #   root 'Site::Tlc::Io'       => 'Site::Tlc::Io'
+    #   child 'IO' of above         => 'IO'
+    #   grandchild 'Input' of above => 'IO Input'
+    def full_name
+      parts = [name]
+      ctx = parent
+      while ctx.is_a?(Context)
+        parts.unshift(ctx.name)
+        ctx = ctx.parent
+      end
+      parts.shift if parts.size > 1
+      parts.join(' ')
+    end
+
+    # Hierarchical output path relative to the output directory root.
+    # Examples:
+    #   root 'Site::Tlc::Io'              => 'site_tlc_io.md'
+    #   child 'IO'                         => 'site_tlc_io/io.md'
+    #   grandchild 'Input'                 => 'site_tlc_io/io/input.md'
+    def output_path
+      parts = []
+      ctx = self
+      while ctx.is_a?(Context)
+        parts.unshift(DocGen.slugify(ctx.name))
+        ctx = ctx.parent
+      end
+      "#{parts.join('/')}.md"
+    end
+  end
+
+  # A spec represents an `it` or `specify` block.
+  Spec = Struct.new(:name, :docstring, :source, :file, :line, :parent, keyword_init: true) do
+    # Full display name including ancestors (root component dropped, same as Context).
+    def full_name
+      parts = [name]
+      ctx = parent
+      while ctx.is_a?(Context)
+        parts.unshift(ctx.name)
+        ctx = ctx.parent
+      end
+      parts.shift if parts.size > 1
+      parts.join(' ')
+    end
+  end
+
+  # Convert a name to a URL/filesystem-friendly slug.
+  def self.slugify(name)
+    name.gsub('::', '_')
+        .gsub(/[^a-zA-Z0-9_]+/, '_')
+        .gsub(/_+/, '_')
+        .gsub(/\A_+|_+\z/, '')
+        .downcase
+  end
+
+  # Convert a raw describe name to a human-readable title.
+  # Takes the last :: segment and splits CamelCase into words.
+  # Examples:
+  #   'Site::Tlc::DetectorLogics' => 'Detector Logics'
+  #   'Site::Core'                => 'Core'
+  #   'Detector Logic'            => 'Detector Logic'  (already readable)
+  def self.humanize(name)
+    segment = name.split('::').last || name
+    segment.gsub(/([a-z\d])([A-Z])/, '\1 \2')
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1 \2')
+  end
+
+  # Builds a namespace tree from flat parsed contexts by merging on '::' segments.
+  # e.g. 'Site::Tlc::Alarm' becomes Site -> Tlc -> Alarm in the tree.
+  class NamespaceBuilder
+    def build(raw_contexts)
+      @node_map = {}
+      sorted = raw_contexts.sort_by { |ctx| ctx.name.include?('::') ? 0 : 1 }
+      sorted.each { |raw| process_raw_context(raw) }
+      @node_map.values.select { |n| n.parent.nil? }
+    end
+
+    private
+
+    def process_raw_context(raw)
+      segments = raw.name.split('::')
+      segments.each_with_index { |_seg, idx| ensure_namespace_node(segments, idx, raw) }
+      leaf = @node_map[raw.name]
+      leaf.docstring ||= raw.docstring
+      raw.children.each { |child| adopt_child(leaf, child) }
+    end
+
+    def ensure_namespace_node(segments, idx, raw)
+      path = segments[0..idx].join('::')
+      return if @node_map.key?(path)
+
+      parent_node = idx.positive? ? @node_map[segments[0...idx].join('::')] : nil
+      node = Context.new(
+        name: segments[idx], docstring: nil, children: [],
+        file: raw.file, line: raw.line, parent: parent_node
+      )
+      @node_map[path] = node
+      parent_node.children << node if parent_node
+    end
+
+    def adopt_child(leaf, child)
+      if child.is_a?(Context)
+        adopt_context_child(leaf, child)
+      else
+        child.parent = leaf
+        leaf.children << child
+      end
+    end
+
+    def adopt_context_child(leaf, child)
+      existing = leaf.children.find { |c| c.is_a?(Context) && c.name == child.name }
+      if existing
+        merge_into_existing(existing, child)
+      elsif child.children.any?
+        child.parent = leaf
+        leaf.children << child
+      end
+    end
+
+    def merge_into_existing(existing, child)
+      existing.docstring ||= child.docstring
+      child.children.each do |grandchild|
+        grandchild.parent = existing
+        existing.children << grandchild
+      end
+    end
+  end
+
+  # Parses Ruby test files using Prism and builds a tree of Context and Spec objects.
+  class Parser
+    # Parse an array of file paths and return an array of root Context objects.
+    def self.parse_files(paths)
+      new.parse_files(paths)
+    end
+
+    def parse_files(paths)
+      raw = Array(paths).flat_map { |path| parse_file(path) }
+      NamespaceBuilder.new.build(raw)
+    end
+
+    private
+
+    def parse_file(path)
+      source = File.read(path)
+      result = Prism.parse(source)
+      lines = source.lines
+      comment_map = build_comment_map(result, lines)
+      top_nodes = result.value.statements&.body || []
+      parse_block(top_nodes, path, comment_map, lines, nil)
+    end
+
+    # Recursively parses AST nodes into Context/Spec objects.
+    def parse_block(nodes, file, comment_map, lines, parent_context)
+      roots = []
+      Array(nodes).each do |node|
+        next unless node.is_a?(Prism::CallNode)
+
+        case node.name
+        when :describe
+          ctx = handle_describe(node, file, comment_map, lines, parent_context)
+          roots << ctx if ctx && parent_context.nil?
+        when :it, :specify
+          handle_spec(node, file, comment_map, lines, parent_context)
+        end
+      end
+      roots
+    end
+
+    def handle_describe(node, file, comment_map, lines, parent_context)
+      ctx = make_context(node, file, comment_map, parent_context)
+      return unless ctx
+
+      parent_context.children << ctx if parent_context
+      body = block_body(node)
+      parse_block(body, file, comment_map, lines, ctx) if body
+      ctx
+    end
+
+    def handle_spec(node, file, comment_map, lines, parent_context)
+      spec = make_spec(node, file, comment_map, lines, parent_context)
+      parent_context.children << spec if spec
+    end
+
+    def make_context(node, file, comment_map, parent_context)
+      name = string_arg(node)
+      return unless name
+
+      Context.new(name: name, docstring: extract_docstring(node.location.start_line, comment_map),
+                  children: [], file: file, line: node.location.start_line, parent: parent_context)
+    end
+
+    def make_spec(node, file, comment_map, lines, parent_context)
+      name = string_arg(node)
+      return unless name
+      return unless parent_context.is_a?(Context)
+
+      Spec.new(name: name, docstring: extract_docstring(node.location.start_line, comment_map),
+               source: extract_source(node, lines), file: file,
+               line: node.location.start_line, parent: parent_context)
+    end
+
+    # Build a map of line_number => comment_text for standalone comment lines only.
+    # Inline comments (e.g. `foo # bar`) are excluded.
+    def build_comment_map(result, lines)
+      result.comments.each_with_object({}) do |comment, map|
+        line_num = comment.location.start_line
+        source_line = lines[line_num - 1] || ''
+        map[line_num] = comment.slice if source_line.strip.start_with?('#')
+      end
+    end
+
+    # Extract the string value of the first argument to a call node.
+    # Returns nil for non-string or missing arguments.
+    def string_arg(node)
+      return nil unless node.arguments
+
+      first = node.arguments.arguments.first
+      case first
+      when Prism::StringNode, Prism::SymbolNode then first.unescaped
+      end
+    end
+
+    # Return the body statement array from a block node, or nil.
+    def block_body(node)
+      return nil unless node.block&.body
+
+      body = node.block.body
+      body.is_a?(Prism::StatementsNode) ? body.body : nil
+    end
+
+    # Walk backwards from the line before start_line collecting contiguous comment lines.
+    # A blank line or non-comment line stops the collection.
+    def extract_docstring(start_line, comment_map)
+      doc_lines = []
+      current = start_line - 1
+      while comment_map[current]
+        doc_lines.unshift(comment_map[current].sub(/^\s*#\s?/, ''))
+        current -= 1
+      end
+      doc_lines.join("\n").strip
+    end
+
+    # Extract the full source of the `it`/`specify` call (including block body).
+    def extract_source(node, lines)
+      start = node.location.start_line - 1
+      stop  = node.location.end_line
+      lines[start...stop].join.chomp
+    end
+  end
+end

data/lib/doc_gen/renderer.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require_relative 'parser'
+
+module DocGen
+  # Renders a tree of Context objects to Jekyll-compatible Markdown files.
+  #
+  # Frontmatter fields produced:
+  #   layout, title, parmalink (sic - preserved from original for compatibility),
+  #   has_children, has_toc, parent, grand_parent (when applicable)
+  #
+  # Jekyll nav hierarchy (just-the-docs):
+  #   depth 0  ->  parent: "Test Suite"  (no grand_parent)
+  #   depth 1  ->  parent: <root name>,  grand_parent: "Test Suite"
+  #   depth 2+ ->  parent: <direct parent name>,  grand_parent: <grandparent name or "Test Suite">
+  class Renderer
+    # Render an array of root Context objects to output_dir.
+    def self.render(contexts, output_dir:)
+      new(output_dir: output_dir).render(contexts)
+    end
+
+    def initialize(output_dir:)
+      @output_dir = output_dir
+    end
+
+    def render(contexts)
+      FileUtils.mkdir_p(@output_dir)
+      contexts.each { |ctx| render_context(ctx) }
+    end
+
+    private
+
+    # Write a single context page and recurse into subcontexts.
+    def render_context(ctx)
+      path = File.join(@output_dir, ctx.output_path)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, context_content(ctx))
+      ctx.subcontexts.each { |child| render_context(child) }
+    end
+
+    # Assemble the full Markdown content for a context page.
+    def context_content(ctx)
+      parts = [
+        frontmatter(ctx),
+        page_title(ctx),
+        description(ctx)
+      ]
+      parts << context_toc(ctx)   if ctx.subcontexts.any?
+      parts << specification_toc  if ctx.specs.any?
+      parts << specifications(ctx) if ctx.specs.any?
+      parts.join
+    end
+
+    # Jekyll frontmatter block.
+    def frontmatter(ctx)
+      fields = {
+        layout: 'page',
+        title: DocGen.humanize(ctx.name),
+        parmalink: DocGen.slugify(ctx.full_name),
+        has_children: ctx.subcontexts.any?,
+        has_toc: false,
+        parent: parent_title(ctx)
+      }
+      grand = grand_parent_title(ctx)
+      fields[:grand_parent] = grand if grand
+
+      lines = fields.map { |k, v| "#{k}: #{v}" }.join("\n")
+      "---\n#{lines}\n---\n\n"
+    end
+
+    # H1 heading using humanized name.
+    def page_title(ctx)
+      "# #{DocGen.humanize(ctx.name)}\n{: .no_toc}\n\n"
+    end
+
+    # Context-level docstring (comment above the describe block), if present.
+    def description(ctx)
+      return '' if ctx.docstring.nil? || ctx.docstring.strip.empty?
+
+      "#{ctx.docstring.strip}\n\n"
+    end
+
+    # Sorted list of links to child contexts.
+    def context_toc(ctx)
+      items = ctx.subcontexts.sort_by(&:name).map do |child|
+        "- [#{DocGen.humanize(child.name)}]({{ site.baseurl }}{% link #{link_path(child)} %})"
+      end.join("\n")
+
+      "### Categories\n{: .no_toc .text-delta }\n#{items}\n\n"
+    end
+
+    # just-the-docs inline TOC marker (picks up ## headings from spec sections).
+    def specification_toc
+      "### Tests\n{: .no_toc .text-delta }\n\n- TOC\n{:toc}\n\n"
+    end
+
+    # All spec sections for the context, sorted by name.
+    def specifications(ctx)
+      ctx.specs.sort_by(&:name).map { |spec| spec_section(spec) }.join("\n\n")
+    end
+
+    # One spec rendered as a ## section with docstring and collapsible source.
+    def spec_section(spec)
+      heading   = "## #{DocGen.humanize(spec.parent.name)} #{spec.name}"
+      docstring = spec.docstring.to_s.strip
+      src       = indent(spec.source.to_s)
+
+      parts = [heading]
+      parts << "\n\n#{docstring}" unless docstring.empty?
+      parts << "\n\n<details markdown=\"block\">\n  " \
+               "<summary>\n     " \
+               "View Source\n  " \
+               "</summary>\n" \
+               "```ruby\n#{src}\n```\n" \
+               '</details>'
+      "#{parts.join}\n"
+    end
+
+    # De-indent source by the leading whitespace of the last line.
+    def indent(source)
+      lines = source.lines
+      return source if lines.empty?
+
+      n = /^(\s*)/.match(lines.last)[0].size
+      lines.map do |line|
+        i = [n, /^(\s*)/.match(line)[0].size].min
+        line[i..]
+      end.join
+    end
+
+    # Jekyll {% link %} path for a context (relative to the Jekyll site root).
+    # Matches the `tests/` output prefix used by the rake task.
+    def link_path(ctx)
+      "tests/#{ctx.output_path}"
+    end
+
+    # Title of the logical parent for Jekyll frontmatter.
+    # Returns "Test Suite" for root contexts (depth 0).
+    def parent_title(ctx)
+      ctx.parent ? DocGen.humanize(ctx.parent.name) : 'Test Suite'
+    end
+
+    # Title of the logical grandparent for Jekyll frontmatter.
+    # Added for all non-root contexts (depth >= 1).
+    # Returns nil for root contexts.
+    def grand_parent_title(ctx)
+      return nil unless ctx.parent
+
+      parent_title(ctx.parent)
+    end
+  end
+end

data/lib/rsmp/validator/async_context.rb

@@ -0,0 +1,15 @@
+module RSMP
+  module Validator
+    # Sus fixture module that runs each test inside the shared Async reactor.
+    # Include this in the sus base class to ensure all tests run within the reactor context.
+    module AsyncContext
+      def around
+        RSMP::Validator.reactor.run do |_task|
+          yield
+        ensure
+          RSMP::Validator.reactor.interrupt
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/auto_node.rb

@@ -0,0 +1,82 @@
+require 'rsmp'
+
+module RSMP
+  module Validator
+    # Base class for automatically starting a local RSMP node (site or supervisor)
+    # when testing the validator or RSMP gem itself.
+    class AutoNode
+      include RSMP::Validator::Log
+
+      attr_reader :node, :task
+
+      def initialize
+        @node = nil
+        @task = nil
+      end
+
+      # Start the auto node inside the async reactor
+      def start
+        return if @node
+
+        @node = build_node
+
+        @task = Async do |task|
+          task.annotate "auto_#{node_type}"
+          log("Starting auto #{node_type}")
+          @node.start
+        rescue Async::TimeoutError
+          raise RSMP::TimeoutError, "Timeout while starting auto #{node_type}"
+        end
+      end
+
+      # Stop the auto node
+      def stop
+        if @node
+          log("Stopping auto #{node_type}")
+          @node.ignore_errors RSMP::DisconnectError do
+            @node.stop
+          end
+        end
+        @task&.stop
+      ensure
+        @task = nil
+        @node = nil
+      end
+
+      # Check if the auto node is running
+      def running?
+        @node && @task
+      end
+
+      protected
+
+      def config
+        RSMP::Validator.auto_node_config
+      end
+
+      def node_type
+        raise NotImplementedError, 'Subclasses must implement node_type'
+      end
+
+      def build_node
+        raise NotImplementedError, 'Subclasses must implement build_node'
+      end
+
+      def create_logger
+        logger_settings = RSMP::Validator.node_log_settings.dup
+        logger_settings['prefix'] = default_log_prefix
+        auto_log_settings = RSMP::Validator.auto_node_log_settings
+        logger_settings.merge!(auto_log_settings) if auto_log_settings && !auto_log_settings.empty?
+        logger_settings.delete('stream') if auto_log_settings && auto_log_settings['path']
+        RSMP::Logger.new(logger_settings)
+      end
+
+      def default_log_prefix
+        case node_type
+        when 'supervisor' then '[SUPERVISOR]'
+        when 'site'       then '[TLC]       '
+        end
+      end
+    end
+  end
+end

data/lib/rsmp/validator/auto_site.rb

@@ -0,0 +1,30 @@
+require_relative 'auto_node'
+
+module RSMP
+  module Validator
+    # Automatically starts a local RSMP site for testing.
+    class AutoSite < RSMP::Validator::AutoNode
+      protected
+
+      def node_type
+        'site'
+      end
+
+      def build_node
+        klass = case config['type']
+                when 'tlc'
+                  RSMP::TLC::TrafficControllerSite
+                else
+                  RSMP::Site
+                end
+
+        site_settings = ConfigNormalizer.normalize_site_settings(config)
+
+        klass.new(
+          site_settings: site_settings,
+          logger: create_logger
+        )
+      end
+    end
+  end
+end

data/lib/rsmp/validator/auto_supervisor.rb

@@ -0,0 +1,23 @@
+require_relative 'auto_node'
+
+module RSMP
+  module Validator
+    # Automatically starts a local RSMP supervisor for testing.
+    class AutoSupervisor < RSMP::Validator::AutoNode
+      protected
+
+      def node_type
+        'supervisor'
+      end
+
+      def build_node
+        supervisor_settings = ConfigNormalizer.normalize_supervisor_settings(config)
+
+        RSMP::Supervisor.new(
+          supervisor_settings: supervisor_settings,
+          logger: create_logger
+        )
+      end
+    end
+  end
+end