Class: Ast::Merge::Comment::Capability

Inherits:
Object
  • Object
show all
Defined in:
lib/ast/merge/comment/capability.rb

Overview

Glossary:

  • Parser capability: what a parser/backend can observe or return.
  • Merge capability: what the merge runtime can safely do with that data.
  • Support style/write model: how observed data is read, owned, and rendered.
  • Ruleset capability declaration: the user-facing feature request.

Comment::Capability is the parser-capability axis for comments. It must not imply that a merge strategy is enabled or that a write model is safe. Ruleset::FeatureProfile and Comment::SupportStyle connect this signal to merge-facing behavior.

This is intentionally a passive value object. It provides shared vocabulary for planning and incremental adoption without changing merge behavior on its own.

Supported levels:

  • :native_full - native comments + attachment hints are available
  • :native_partial - some native comment support, but incomplete ownership data
  • :native_comment_nodes_only - native comment nodes exist, but attachment is unknown
  • :source_augmented - comments are inferred from source text
  • :none - no comment support is available

Constant Summary collapse

LEVELS =

Supported capability levels.

Returns:

  • (Array<Symbol>) 
%i[
  native_full
  native_partial
  native_comment_nodes_only
  source_augmented
  none
].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(level:, details: {}, **options) ⇒ Capability

Returns a new instance of Capability.



83
84
85
86
 
# File 'lib/ast/merge/comment/capability.rb', line 83

def initialize(level:, details: {}, **options)
  @level = normalize_level(level)
  @details = details.merge(options).freeze
end

Instance Attribute Details

#details ⇒ Object (readonly)

Returns the value of attribute details.



39
40
41
 
# File 'lib/ast/merge/comment/capability.rb', line 39

def details
  @details
end

#level ⇒ Object (readonly)

Returns the value of attribute level.



39
40
41
 
# File 'lib/ast/merge/comment/capability.rb', line 39

def level
  @level
end

Class Method Details

.native_comment_nodes_only(**details) ⇒ Capability

Build a capability describing native comment nodes without attachment hints.

Parameters:

  • details (Hash) —

    producer metadata

Returns:



62
63
64
 
# File 'lib/ast/merge/comment/capability.rb', line 62

def native_comment_nodes_only(**details)
  new(level: :native_comment_nodes_only, **details)
end

.native_full(**details) ⇒ Capability

Build a capability describing full native comment support.

Parameters:

  • details (Hash) —

    producer metadata

Returns:



46
47
48
 
# File 'lib/ast/merge/comment/capability.rb', line 46

def native_full(**details)
  new(level: :native_full, **details)
end

.native_partial(**details) ⇒ Capability

Build a capability describing partial native comment support.

Parameters:

  • details (Hash) —

    producer metadata

Returns:



54
55
56
 
# File 'lib/ast/merge/comment/capability.rb', line 54

def native_partial(**details)
  new(level: :native_partial, **details)
end

.none(**details) ⇒ Capability

Build a capability describing no available comment support.

Parameters:

  • details (Hash) —

    producer metadata

Returns:



78
79
80
 
# File 'lib/ast/merge/comment/capability.rb', line 78

def none(**details)
  new(level: :none, **details)
end

.source_augmented(**details) ⇒ Capability

Build a capability describing source-augmented comment support.

Parameters:

  • details (Hash) —

    producer metadata

Returns:



70
71
72
 
# File 'lib/ast/merge/comment/capability.rb', line 70

def source_augmented(**details)
  new(level: :source_augmented, **details)
end

Instance Method Details

#attachment_hints? ⇒ Boolean

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/ast/merge/comment/capability.rb', line 120

def attachment_hints?
  details.fetch(:attachment_hints, native_full?)
end

#augmented? ⇒ Boolean

Returns:

  • (Boolean) 


112
113
114
 
# File 'lib/ast/merge/comment/capability.rb', line 112

def augmented?
  source_augmented?
end

#available? ⇒ Boolean

Returns:

  • (Boolean) 


116
117
118
 
# File 'lib/ast/merge/comment/capability.rb', line 116

def available?
  !none?
end

#comment_nodes? ⇒ Boolean

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/ast/merge/comment/capability.rb', line 124

def comment_nodes?
  details.fetch(:comment_nodes, native_full? || native_comment_nodes_only?)
end

#inspect ⇒ String

Return a concise debug representation of the capability.

Returns:

  • (String) 


146
147
148
 
# File 'lib/ast/merge/comment/capability.rb', line 146

def inspect
  "#<#{self.class.name} level=#{level} details=#{details.inspect}>"
end

#native? ⇒ Boolean

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/ast/merge/comment/capability.rb', line 108

def native?
  native_full? || native_partial? || native_comment_nodes_only?
end

#native_comment_nodes_only? ⇒ Boolean

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/ast/merge/comment/capability.rb', line 96

def native_comment_nodes_only?
  level == :native_comment_nodes_only
end

#native_full? ⇒ Boolean

Returns:

  • (Boolean) 


88
89
90
 
# File 'lib/ast/merge/comment/capability.rb', line 88

def native_full?
  level == :native_full
end

#native_partial? ⇒ Boolean

Returns:

  • (Boolean) 


92
93
94
 
# File 'lib/ast/merge/comment/capability.rb', line 92

def native_partial?
  level == :native_partial
end

#none? ⇒ Boolean

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/ast/merge/comment/capability.rb', line 104

def none?
  level == :none
end

#source_augmented? ⇒ Boolean

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/ast/merge/comment/capability.rb', line 100

def source_augmented?
  level == :source_augmented
end

#to_h ⇒ Hash

Return the capability as a normalized Hash.

Returns:

  • (Hash) 


131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/ast/merge/comment/capability.rb', line 131

def to_h
  {
    level: level,
    details: details,
    native: native?,
    augmented: augmented?,
    available: available?,
    attachment_hints: attachment_hints?,
    comment_nodes: comment_nodes?
  }
end