feat: Enhance annotation handling with multiline support and update f… (#29)

* feat: Enhance annotation handling with multiline support and update form builder for markdown
* feat: Implement optimistic locking with content hashing and conflict handling in editor
* feat: Refactor Editor module to use module_function for better encapsulation
* feat: Update RBS annotations, enhance form builder input type handling, and improve validation error messaging
* fix: Add steep ignore comment for block type mismatch in ComputedManager

Author: ionos-landgraf-vin

.rubocop.yml

@@ -185,3 +185,7 @@ Lint/RedundantSafeNavigation:
 Style/EmptyStringInsideInterpolation:
   Exclude:
     - "**/*.haml"
+
+# Allow Steep RBS type annotations (#: Type)
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true

Steepfile

@@ -15,4 +15,5 @@ target :lib do
   check "lib/archsight/annotations/computed.rb"
 
   library "yaml"
+  library "uri"
 end

lib/archsight/annotations/annotation.rb

@@ -81,7 +81,7 @@ def value_for(instance)
 
   # Validate a value and return array of error messages (empty if valid)
   def validate(value)
-    errors = []
+    errors = [] #: Array[String]
     return errors if value.nil?
 
     validate_enum(value, errors)
@@ -104,6 +104,10 @@ def code?
     @format == :ruby
   end
 
+  def multiline?
+    @format == :multiline
+  end
+
   def code_language
     @format if code?
   end

lib/archsight/annotations/computed.rb

@@ -212,7 +212,7 @@ def compute_for(instance, definition)
     @computing.add(cache_key)
     begin
       evaluator = Archsight::Annotations::ComputedEvaluator.new(instance, @database, self)
-      value = evaluator.instance_eval(&definition.block)
+      value = evaluator.instance_eval(&definition.block) # steep:ignore BlockTypeMismatch
 
       # Apply type coercion if specified
       value = coerce_value(value, definition.type) if definition.type

lib/archsight/editor.rb

@@ -3,18 +3,21 @@
 require "yaml"
 require_relative "resources"
 require_relative "editor/file_writer"
+require_relative "editor/content_hasher"
 
 module Archsight
   # Editor handles building and validating resources for the web editor
-  class Editor
+  module Editor
+    module_function
+
     # Build a resource hash from form params
     # @param kind [String] Resource kind (e.g., "TechnologyArtifact")
     # @param name [String] Resource name
     # @param annotations [Hash] Annotation key-value pairs
     # @param relations [Array<Hash>] Array of {verb:, kind:, names:[]} hashes
     #   where kind is the target class name (e.g., "TechnologyArtifact")
     # @return [Hash] Resource hash ready for YAML conversion
-    def self.build_resource(kind:, name:, annotations: {}, relations: [])
+    def build_resource(kind:, name:, annotations: {}, relations: [])
       resource = {
         "apiVersion" => "architecture/v1alpha1",
         "kind" => kind,
@@ -39,7 +42,7 @@ def self.build_resource(kind:, name:, annotations: {}, relations: [])
     # @param name [String] Resource name
     # @param annotations [Hash] Annotation key-value pairs
     # @return [Hash] { valid: Boolean, errors: { field => [messages] } }
-    def self.validate(kind, name:, annotations: {})
+    def validate(kind, name:, annotations: {})
       klass = Archsight::Resources[kind]
       errors = {}
 
@@ -66,7 +69,7 @@ def self.validate(kind, name:, annotations: {})
     # Uses custom YAML dump that formats multiline strings with literal block scalars
     # @param resource_hash [Hash] Resource hash
     # @return [String] YAML string
-    def self.to_yaml(resource_hash)
+    def to_yaml(resource_hash)
       visitor = Psych::Visitors::YAMLTree.create
       visitor << resource_hash
 
@@ -79,7 +82,7 @@ def self.to_yaml(resource_hash)
 
     # Recursively apply literal block style for multiline strings in YAML AST
     # @param node [Psych::Nodes::Node] YAML AST node
-    def self.apply_block_scalar_style(node)
+    def apply_block_scalar_style(node)
       case node
       when Psych::Nodes::Scalar
         if node.value.is_a?(String)
@@ -97,7 +100,7 @@ def self.apply_block_scalar_style(node)
     # Excludes pattern annotations, computed annotations, and annotations with editor: false
     # @param kind [String] Resource kind
     # @return [Array<Archsight::Annotations::Annotation>]
-    def self.editable_annotations(kind)
+    def editable_annotations(kind)
       klass = Archsight::Resources[kind]
       return [] unless klass
 
@@ -115,7 +118,7 @@ def self.editable_annotations(kind)
     # Get available relations for a resource kind
     # @param kind [String] Resource kind
     # @return [Array<Array>] Array of [verb, target_kind, target_class_name]
-    def self.available_relations(kind)
+    def available_relations(kind)
       klass = Archsight::Resources[kind]
       return [] unless klass
 
@@ -125,15 +128,15 @@ def self.available_relations(kind)
     # Get unique verbs for a resource kind's relations
     # @param kind [String] Resource kind
     # @return [Array<String>]
-    def self.relation_verbs(kind)
+    def relation_verbs(kind)
       available_relations(kind).map { |v, _, _| v.to_s }.uniq.sort
     end
 
     # Get valid target class names for a given verb (for UI display and instance lookup)
     # @param kind [String] Resource kind
     # @param verb [String] Relation verb
     # @return [Array<String>] Target class names (e.g., "TechnologyArtifact")
-    def self.target_kinds_for_verb(kind, verb)
+    def target_kinds_for_verb(kind, verb)
       # Relations structure is [verb, relation_name, target_class_name]
       available_relations(kind)
         .select { |v, _, _| v.to_s == verb.to_s }
@@ -147,7 +150,7 @@ def self.target_kinds_for_verb(kind, verb)
     # @param verb [String] Relation verb
     # @param target_class [String] Target class name
     # @return [String, nil] Relation name (e.g., "technologyComponents")
-    def self.relation_name_for(kind, verb, target_class)
+    def relation_name_for(kind, verb, target_class)
       relation = available_relations(kind).find do |v, _, tc|
         v.to_s == verb.to_s && tc.to_s == target_class.to_s
       end
@@ -161,7 +164,7 @@ def self.relation_name_for(kind, verb, target_class)
     # @param verb [String] Relation verb
     # @param relation_name [String] Relation name (e.g., "businessActors")
     # @return [String, nil] Target class name (e.g., "BusinessActor")
-    def self.target_class_for_relation(kind, verb, relation_name)
+    def target_class_for_relation(kind, verb, relation_name)
       relation = available_relations(kind).find do |v, rn, _|
         v.to_s == verb.to_s && rn.to_s == relation_name.to_s
       end
@@ -170,65 +173,65 @@ def self.target_class_for_relation(kind, verb, relation_name)
       relation[2].to_s
     end
 
-    class << self
-      private
+    # Filter out empty values from a hash and convert to plain Hash
+    # (avoids !ruby/hash:Sinatra::IndifferentHash in YAML output)
+    def filter_empty(hash)
+      return {} if hash.nil?
 
-      # Filter out empty values from a hash and convert to plain Hash
-      # (avoids !ruby/hash:Sinatra::IndifferentHash in YAML output)
-      def filter_empty(hash)
-        return {} if hash.nil?
+      result = hash.reject { |_, v| v.nil? || v.to_s.strip.empty? }
+      # Convert to plain Hash to avoid Ruby-specific YAML tags
+      result.to_h
+    end
 
-        result = hash.reject { |_, v| v.nil? || v.to_s.strip.empty? }
-        # Convert to plain Hash to avoid Ruby-specific YAML tags
-        result.to_h
-      end
+    # Build spec hash from relations array
+    # @param source_kind [String] The source resource kind
+    # @param relations [Array<Hash>] Array of {verb:, kind:, names:[]} hashes
+    #   where kind is the target class name (e.g., "TechnologyArtifact")
+    # @return [Hash] Spec hash with proper relation_name keys
+    def build_spec(source_kind, relations)
+      return {} if relations.nil? || relations.empty?
 
-      # Build spec hash from relations array
-      # @param source_kind [String] The source resource kind
-      # @param relations [Array<Hash>] Array of {verb:, kind:, names:[]} hashes
-      #   where kind is the target class name (e.g., "TechnologyArtifact")
-      # @return [Hash] Spec hash with proper relation_name keys
-      def build_spec(source_kind, relations)
-        return {} if relations.nil? || relations.empty?
-
-        spec = {}
-        relations.each { |rel| add_relation_to_spec(spec, source_kind, rel) }
-        deduplicate_spec_values(spec)
-      end
+      spec = {}
+      relations.each { |rel| add_relation_to_spec(spec, source_kind, rel) }
+      deduplicate_spec_values(spec)
+    end
 
-      def add_relation_to_spec(spec, source_kind, rel)
-        verb, target_class, names = extract_relation_parts(rel)
-        return if invalid_relation?(verb, target_class, names)
+    def add_relation_to_spec(spec, source_kind, rel)
+      verb, target_class, names = extract_relation_parts(rel)
+      return if invalid_relation?(verb, target_class, names)
 
-        relation_name = Archsight::Editor.relation_name_for(source_kind, verb, target_class)
-        return unless relation_name
+      rel_name = relation_name_for(source_kind, verb, target_class)
+      return unless rel_name
 
-        spec[verb.to_s] ||= {}
-        spec[verb.to_s][relation_name] ||= []
-        spec[verb.to_s][relation_name].concat(names)
-      end
+      spec[verb.to_s] ||= {}
+      spec[verb.to_s][rel_name] ||= []
+      spec[verb.to_s][rel_name].concat(names)
+    end
 
-      def extract_relation_parts(rel)
-        verb = rel[:verb] || rel["verb"]
-        target_class = rel[:kind] || rel["kind"]
-        names = normalize_names(rel[:names] || rel["names"] || [])
-        [verb, target_class, names]
-      end
+    def extract_relation_parts(rel)
+      verb = rel[:verb] || rel["verb"]
+      target_class = rel[:kind] || rel["kind"]
+      names = normalize_names(rel[:names] || rel["names"] || [])
+      [verb, target_class, names]
+    end
 
-      def normalize_names(names)
-        names = [names] unless names.is_a?(Array)
-        names.map(&:to_s).reject(&:empty?)
-      end
+    def normalize_names(names)
+      names = [names] unless names.is_a?(Array)
+      names.map(&:to_s).reject(&:empty?)
+    end
 
-      def invalid_relation?(verb, target_class, names)
-        verb.nil? || verb.to_s.strip.empty? ||
-          target_class.nil? || target_class.to_s.strip.empty? ||
-          names.empty?
-      end
+    def invalid_relation?(verb, target_class, names)
+      verb.nil? || verb.to_s.strip.empty? ||
+        target_class.nil? || target_class.to_s.strip.empty? ||
+        names.empty?
+    end
 
-      def deduplicate_spec_values(spec)
-        spec.transform_values { |kinds| kinds.transform_values(&:uniq) }
-      end
+    def deduplicate_spec_values(spec)
+      spec.transform_values { |kinds| kinds.transform_values(&:uniq) }
     end
+
+    private_class_method :filter_empty, :build_spec, :add_relation_to_spec,
+                         :extract_relation_parts, :normalize_names, :invalid_relation?,
+                         :deduplicate_spec_values
   end
 end

lib/archsight/editor/content_hasher.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Archsight
+  module Editor
+    # ContentHasher generates SHA256 hashes for optimistic locking
+    module ContentHasher
+      module_function
+
+      # Generate a hash of YAML content for comparison
+      # Normalizes line endings before hashing to ensure consistency across platforms
+      # @param content [String] YAML content
+      # @return [String] 16-character hex hash
+      def hash(content)
+        normalized = content.gsub("\r\n", "\n").gsub("\r", "\n")
+        Digest::SHA256.hexdigest(normalized)[0, 16]
+      end
+
+      # Validate that content hasn't changed since expected_hash was computed
+      # @param path [String] File path
+      # @param start_line [Integer] Line number where document starts
+      # @param expected_hash [String, nil] Expected content hash
+      # @return [Hash, nil] Error hash with :conflict and :error keys, or nil if valid
+      def validate(path:, start_line:, expected_hash:)
+        return nil unless expected_hash
+
+        current_content = FileWriter.read_document(path: path, start_line: start_line)
+        current_hash = hash(current_content)
+
+        return nil if current_hash == expected_hash
+
+        { conflict: true, error: "Conflict: The resource has been modified. Please reload the page and try again." }
+      end
+    end
+  end
+end

lib/archsight/editor/file_writer.rb

@@ -1,17 +1,39 @@
 # frozen_string_literal: true
 
 module Archsight
-  class Editor
-    # FileWriter handles writing YAML documents back to multi-document files
+  module Editor
+    # FileWriter handles reading and writing YAML documents in multi-document files
     module FileWriter
       class WriteError < StandardError; end
 
+      module_function
+
+      # Read a YAML document from a file starting at a given line
+      # @param path [String] File path
+      # @param start_line [Integer] Line number where document starts (1-indexed)
+      # @return [String] Document content
+      # @raise [WriteError] if file not found or line out of bounds
+      def read_document(path:, start_line:)
+        raise WriteError, "File not found: #{path}" unless File.exist?(path)
+
+        lines = File.readlines(path)
+        start_idx = start_line - 1 # Convert to 0-indexed
+
+        raise WriteError, "Line #{start_line} is beyond end of file" if start_idx >= lines.length
+
+        # Find the end of this document (next --- or EOF)
+        end_idx = find_document_end(lines, start_idx)
+
+        # Extract and join the document lines
+        lines[start_idx...end_idx].join
+      end
+
       # Replace a YAML document in a file starting at a given line
       # @param path [String] File path
       # @param start_line [Integer] Line number where document starts (1-indexed)
       # @param new_yaml [String] New YAML content (without leading ---)
       # @raise [WriteError] if file cannot be written or document not found at expected line
-      def self.replace_document(path:, start_line:, new_yaml:)
+      def replace_document(path:, start_line:, new_yaml:)
         raise WriteError, "File not found: #{path}" unless File.exist?(path)
         raise WriteError, "File not writable: #{path}" unless File.writable?(path)
 
@@ -38,7 +60,7 @@ def self.replace_document(path:, start_line:, new_yaml:)
       # @param lines [Array<String>] File lines
       # @param start_idx [Integer] Starting line index (0-indexed)
       # @return [Integer] End index (exclusive - the line after the document ends)
-      def self.find_document_end(lines, start_idx)
+      def find_document_end(lines, start_idx)
         # Start searching from the line after start_idx
         idx = start_idx + 1