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) 


128
129
130
 
# File 'lib/docscribe/infer.rb', line 128

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) 


116
117
118
119
120
121
122
 
# File 'lib/docscribe/infer.rb', line 116

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) ⇒ 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

Returns:

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


99
100
101
102
103
104
105
106
107
108
 
# File 'lib/docscribe/infer.rb', line 99

def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true, core_rbs_provider: nil,
                           param_types: 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
  )
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) 


137
138
139
 
# File 'lib/docscribe/infer.rb', line 137

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) 


148
149
150
151
152
153
154
155
 
# File 'lib/docscribe/infer.rb', line 148

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