Module: Docscribe::Infer

Defined in:
lib/docscribe/infer.rb,
lib/docscribe/infer/names.rb,
lib/docscribe/infer/params.rb,
lib/docscribe/infer/raises.rb,
lib/docscribe/infer/returns.rb,
lib/docscribe/infer/ast_walk.rb,
lib/docscribe/infer/literals.rb,
lib/docscribe/infer/constants.rb

Overview

Best-effort inference utilities used to generate YARD tags.

This module is intentionally heuristic:

  • it aims to be useful for common Ruby patterns
  • it prefers safe fallback behavior when uncertain
  • when inference cannot be specific, it falls back to Object

External signature sources such as RBS and Sorbet are applied later in the doc builder and can override these inferred types.

Defined Under Namespace

Modules: ASTWalk, Literals, Names, Params, Raises, Returns

Constant Summary collapse

FALLBACK_TYPE =

Default fallback type used when inference cannot be certain.

'Object'
DEFAULT_ERROR =

Ruby's implicit rescue target for bare rescue.

'StandardError'
LITERAL_TYPE_MAP =

Node type to literal type name mapping.

{
  int: 'Integer',
  float: 'Float',
  str: 'String',
  dstr: 'String',
  sym: 'Symbol',
  true: 'Boolean',
  false: 'Boolean',
  nil: 'nil',
  array: 'Array',
  hash: 'Hash',
  regexp: 'Regexp'
}.freeze

Class Method Summary collapse

Class Method Details

.const_full_name(node) ⇒ String?

Convert a constant AST node into its fully qualified name.

Parameters:

  • node (Parser::AST::Node, nil) —

    constant AST node to resolve

Returns:

  • (String, nil) 


132
133
134
 
# File 'lib/docscribe/infer.rb', line 132

def const_full_name(node)
  Names.const_full_name(node)
end

.infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true) ⇒ String

Infer a parameter type from its internal name form and optional default expression.

The internal parameter name may include:

  • * for rest args
  • ** for keyword rest args
  • & for block args
  • trailing : for keyword args

Parameters:

  • name (String) —

    internal parameter name representation

  • default_str (String?) —

    source for the default expression

  • fallback_type (String) (defaults to: FALLBACK_TYPE) —

    default type when uncertain

  • treat_options_keyword_as_hash (Boolean) (defaults to: true) —

    treat options: as Hash

Returns:

  • (String) 


54
55
56
57
58
59
60
61
 
# File 'lib/docscribe/infer.rb', line 54

def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
  Params.infer_param_type(
    name,
    default_str,
    fallback_type: fallback_type,
    treat_options_keyword_as_hash: treat_options_keyword_as_hash
  )
end

.infer_raises_from_node(node) ⇒ Array<String>

Infer exception classes raised or rescued within an AST node.

Parameters:

  • node (Parser::AST::Node) —

    constant AST node to resolve

Returns:

  • (Array<String>) 


36
37
38
 
# File 'lib/docscribe/infer.rb', line 36

def infer_raises_from_node(node)
  Raises.infer_raises_from_node(node)
end

.infer_return_type(method_source) ⇒ String

Infer a return type from full method source.

Parameters:

  • method_source (String?) —

    method definition source

Returns:

  • (String) 


75
76
77
 
# File 'lib/docscribe/infer.rb', line 75

def infer_return_type(method_source)
  Returns.infer_return_type(method_source)
end

.infer_return_type_from_node(node) ⇒ String

Infer a return type from an already parsed :def / :defs node.

Parameters:

  • node (Parser::AST::Node) —

    constant AST node to resolve

Returns:

  • (String) 


83
84
85
 
# File 'lib/docscribe/infer.rb', line 83

def infer_return_type_from_node(node)
  Returns.infer_return_type_from_node(node)
end

.last_expr_type(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true) ⇒ String?

Infer the type of the last expression in an AST node.

Parameters:

  • node (Parser::AST::Node, nil) —

    constant AST node to resolve

  • fallback_type (String) (defaults to: FALLBACK_TYPE) —

    default type when uncertain

  • nil_as_optional (Boolean) (defaults to: true) —

    render nil as optional

Returns:

  • (String, nil) 


120
121
122
123
124
125
126
 
# File 'lib/docscribe/infer.rb', line 120

def last_expr_type(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
  Returns.last_expr_type(
    node,
    fallback_type: fallback_type,
    nil_as_optional: nil_as_optional
  )
end

.parse_expr(src) ⇒ Parser::AST::Node?

Parse a standalone expression source string for inference helpers.

Parameters:

  • src (String?) —

    expression source to parse

Returns:

  • (Parser::AST::Node, nil) 


67
68
69
 
# File 'lib/docscribe/infer.rb', line 67

def parse_expr(src)
  Params.parse_expr(src)
end

.returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil, param_types: nil, container: nil, signature_provider: nil) ⇒ Hash<Symbol, String, Array<(Array<String>, String)>>

Return structured normal/rescue return information for a method node.

Result shape:

  • :normal => the normal return type
  • :rescues => rescue-branch conditional return info

Parameters:

  • node (Parser::AST::Node) —

    constant AST node to resolve

  • fallback_type (String) (defaults to: FALLBACK_TYPE) —

    default type when uncertain

  • nil_as_optional (Boolean) (defaults to: true) —

    render nil as optional

  • core_rbs_provider (Docscribe::Types::RBS::Provider?) (defaults to: nil) —

    core RBS type lookup provider

  • param_types (Hash<String, String>?) (defaults to: nil) —

    parameter name -> type map

  • container (String?) (defaults to: nil)
  • signature_provider (Docscribe::Types::ProviderChain?) (defaults to: nil)

Returns:

  • (Hash<Symbol, String, Array<(Array<String>, String)>>) 


101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/docscribe/infer.rb', line 101

def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil, # rubocop:disable Metrics/ParameterLists
                           param_types: nil, container: nil, signature_provider: nil)
  Returns.returns_spec_from_node(
    node,
    fallback_type: fallback_type,
    nil_as_optional: nil_as_optional,
    core_rbs_provider: core_rbs_provider,
    param_types: param_types,
    container: container,
    signature_provider: signature_provider
  )
end

.type_from_literal(node, fallback_type: FALLBACK_TYPE) ⇒ String

Infer a YARD-ish type string from a literal AST node.

Parameters:

  • node (Parser::AST::Node, nil) —

    constant AST node to resolve

  • fallback_type (String) (defaults to: FALLBACK_TYPE) —

    default type when uncertain

Returns:

  • (String) 


141
142
143
 
# File 'lib/docscribe/infer.rb', line 141

def type_from_literal(node, fallback_type: FALLBACK_TYPE)
  Literals.type_from_literal(node, fallback_type: fallback_type)
end

.unify_types(type_a, type_b, fallback_type: FALLBACK_TYPE, nil_as_optional: true) ⇒ String

Unify two inferred type strings conservatively.

Parameters:

  • type_a (String, nil) —

    first type to unify

  • type_b (String, nil) —

    second type to unify

  • fallback_type (String) (defaults to: FALLBACK_TYPE) —

    default type when uncertain

  • nil_as_optional (Boolean) (defaults to: true) —

    render nil as optional

Returns:

  • (String) 


152
153
154
155
156
157
158
159
 
# File 'lib/docscribe/infer.rb', line 152

def unify_types(type_a, type_b, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
  Returns.unify_types(
    type_a,
    type_b,
    fallback_type: fallback_type,
    nil_as_optional: nil_as_optional
  )
end