decode 0.24.2 → 0.24.4

data/sig/decode.rbs

@@ -0,0 +1,1189 @@
+module Decode
+  VERSION: String
+
+  # Represents comment parsing and processing functionality.
+  module Comment
+    # Describes an attribute type.
+    #
+    # - `@attribute [Integer] The person's age.`
+    class Attribute < Tag
+      PATTERN: Regexp
+
+      attr_reader type(@type): String
+
+      @type: String
+
+      # Build an attribute from a directive and match.
+      public def self.build: (String directive, MatchData match) -> untyped
+
+      # Initialize a new attribute.
+      public def initialize: (String directive, String type) -> void
+    end
+
+    # Represents a constant type declaration.
+    #
+    # - `@constant [Regexp] Pattern for matching parameters.`
+    class Constant < Tag
+      PATTERN: Regexp
+
+      attr_reader type(@type): String
+
+      @type: String
+
+      # Build a constant from a directive and regex match.
+      public def self.build: (String directive, MatchData match) -> Constant
+
+      # Initialize a new constant.
+      public def initialize: (String directive, String type) -> void
+    end
+
+    # Represents a node in a comment tree structure.
+    class Node
+      attr_reader children(@children): Array[Node | Text]?
+
+      @children: Array[Node | Text]?
+
+      # Initialize the node.
+      public def initialize: (Array[Node | Text]? children) -> void
+
+      # Whether this node has any children nodes.
+      # Ignores {Text} instances.
+      public def children?: () -> bool
+
+      # Add a child node to this node.
+      public def add: (Node | Text child) -> self
+
+      # Enumerate all non-text children nodes.
+      public def each: () { (Node node) -> void } -> (Enumerator[Node] | self)
+
+      # Filter children nodes by class type.
+      public def filter: (Class klass) { (Object node) -> void } -> (Enumerator[Node] | self)
+
+      # Any lines of text associated with this node.
+      public def text: () -> Array[String]?
+
+      # Traverse the tags from this node using {each}. Invoke `descend.call(child)` to recursively traverse the specified child.
+      public def traverse: () { (Node node, Proc descend) -> void } -> untyped
+
+      # Extract text lines from Text children of this node.
+      def extract_text: () -> Array[String]?
+    end
+
+    # Describes a method option (keyword argument).
+    #
+    # - `@option :cached [bool] Whether to cache the value.`
+    class Option < Parameter
+    end
+
+    # Represents a named method parameter.
+    #
+    # - `@parameter age [Float] The users age.`
+    class Parameter < Tag
+      PATTERN: Regexp
+
+      attr_reader name(@name): String
+
+      attr_reader type(@type): String
+
+      @name: String
+
+      @type: String
+
+      # Build a parameter from a directive and regex match.
+      public def self.build: (String directive, MatchData match) -> Parameter
+
+      # Initialize a new parameter.
+      public def initialize: (String directive, String name, String type) -> void
+    end
+
+    # Asserts a specific property about the method signature.
+    #
+    # - `@reentrant This method is thread-safe.`
+    # - `@deprecated Please use {other_method} instead.`
+    # - `@blocking This method may block.`
+    # - `@asynchronous This method may yield.`
+    class Pragma < Tag
+      # Parse a pragma directive from text.
+      public def self.parse: (String directive, String text, Array[String] lines, Array[Tag] tags, ?Integer level) -> untyped
+
+      # Build a pragma from a directive and text.
+      public def self.build: (String directive, String text) -> untyped
+
+      # Initialize a new pragma.
+      public def initialize: (String directive) -> void
+    end
+
+    # Identifies that a method might raise an exception.
+    #
+    # - `@raises [ArgumentError] If the argument cannot be coerced.`
+    class Raises < Attribute
+    end
+
+    # Represents an RBS type annotation following rbs-inline syntax.
+    #
+    # Examples:
+    # - `@rbs generic T` - Declares a generic type parameter for a class
+    # - `@rbs [T] () { () -> T } -> Task[T]` - Complete method type signature
+    class RBS < Tag
+      attr_reader text(@text): String
+
+      @text: String
+
+      # Parse an RBS pragma from text.
+      public def self.parse: (String directive, String text, Array[String] lines, Array[Tag] tags, ?Integer level) -> untyped
+
+      # Build an RBS pragma from a directive and text.
+      public def self.build: (String directive, String text) -> untyped
+
+      # Initialize a new RBS pragma.
+      public def initialize: (String directive, String? text) -> void
+
+      # Check if this is a generic type declaration.
+      public def generic?: () -> bool
+
+      # Extract the generic type parameter name.
+      public def generic_parameter: () -> String?
+
+      # Check if this is a method type signature.
+      public def method_signature?: () -> bool
+
+      # Get the method type signature text.
+      public def method_signature: () -> String?
+    end
+
+    # Represents a return value.
+    #
+    # Example: `@returns [Integer] The person's age.`
+    class Returns < Attribute
+    end
+
+    # Represents a documentation tag parsed from a comment directive.
+    # Subclasses should define a PATTERN constant for matching their specific syntax.
+    class Tag < Node
+      PATTERN: Regexp
+
+      attr_reader directive(@directive): String
+
+      @directive: String
+
+      # Abstract method: Build a tag from directive and match data.
+      # Subclasses must implement this method.
+      public def self.build: (String directive, MatchData match) -> Tag
+
+      # Build a pattern for bracketed content, supporting nested brackets.
+      public def self.bracketed_content: (Symbol name) -> String
+
+      # Match text against the tag pattern.
+      public def self.match: (String text) -> untyped
+
+      # Parse a tag from a directive and text.
+      public def self.parse: (String directive, String text, Array[String] lines, Tags tags, ?Integer level) -> untyped
+
+      # Initialize a new tag.
+      public def initialize: (String directive) -> void
+    end
+
+    # Represents a collection of documentation tags and their parsing logic.
+    class Tags
+      PATTERN: Regexp
+
+      # Build a tags parser with directive mappings.
+      public def self.build: () { (Hash[String, Class]) -> void } -> Tags
+
+      # Initialize a new tags parser.
+      public def initialize: (Hash[String, _Directive] directives) -> void
+
+      # Check if a line has valid indentation for the given level.
+      public def valid_indentation?: (String line, Integer level) -> bool
+
+      # Parse documentation tags from lines.
+      public def parse: (Array[String] lines, ?Integer level) { (Node | Text) -> void } -> void
+
+      # Ignore lines at the specified indentation level.
+      public def ignore: (Array[String] lines, ?Integer level) -> untyped
+    end
+
+    # A structured comment.
+    class Text
+      attr_reader line(@line): String
+
+      @line: String
+
+      # Initialize a new text node.
+      public def initialize: (String line) -> void
+
+      # Traverse the text node.
+      public def traverse: () -> untyped
+    end
+
+    # Identifies that a method might throw a specific symbol.
+    #
+    # - `@throws [:skip] To skip recursion.`
+    class Throws < Attribute
+    end
+
+    # Describes a block parameter.
+    #
+    # - `@yields {|person| ... } If a block is given.`
+    #
+    # Should contain nested parameters.
+    class Yields < Tag
+      PATTERN: Regexp
+
+      # Build a yields tag from a directive and match.
+      public def self.build: (String directive, MatchData match) -> untyped
+
+      # Initialize a new yields tag.
+      public def initialize: (String directive, String block) -> void
+    end
+  end
+
+  # A symbol with attached documentation.
+  class Definition
+    attr_reader path(@path): Array[Symbol]
+
+    attr_reader parent(@parent): Definition?
+
+    attr_reader language(@language): Language::Generic
+
+    attr_reader source(@source): Source?
+
+    attr_reader comments(@comments): Array[String]?
+
+    attr_reader visibility(@visibility): Symbol
+
+    @path: Array[Symbol]
+
+    @parent: Definition?
+
+    @language: Language::Generic
+
+    @source: Source?
+
+    @comments: Array[String]?
+
+    @visibility: Symbol
+
+    # Initialize the symbol.
+    public def initialize: (Symbol | Array[Symbol] path, ?parent: Definition?, ?language: Language::Generic?, ?comments: Array[String]?, ?visibility: Symbol, ?source: Source?) -> void
+
+    # Generate a debug representation of the definition.
+    public def inspect: () -> untyped
+
+    public def name: () -> untyped
+
+    # The full path to the definition.
+    public def full_path: () -> Array[Symbol]
+
+    # Whether the definition is considered part of the public interface.
+    # This is used to determine whether the definition should be documented for coverage purposes.
+    public def public?: () -> bool
+
+    # Whether the definition has documentation.
+    public def documented?: () -> bool
+
+    # The qualified name is an absolute name which includes any and all namespacing.
+    public def qualified_name: () -> String
+
+    public def nested_name: () -> String
+
+    # Does the definition name match the specified prefix?
+    public def start_with?: (String prefix) -> bool
+
+    # Convert this definition into another kind of definition.
+    public def convert: (Symbol kind) -> untyped
+
+    # A short form of the definition.
+    # e.g. `def short_form`.
+    public def short_form: () -> String?
+
+    # A long form of the definition.
+    # e.g. `def initialize(kind, name, comments, **options)`.
+    public def long_form: () -> String?
+
+    # A long form which uses the qualified name if possible.
+    # Defaults to {long_form}.
+    public def qualified_form: () -> String?
+
+    # Whether the definition spans multiple lines.
+    public def multiline?: () -> bool
+
+    # The full text of the definition.
+    public def text: () -> String?
+
+    # Whether this definition can contain nested definitions.
+    public def container?: () -> bool
+
+    # Whether this represents a single entity to be documented (along with it's contents).
+    public def nested?: () -> bool
+
+    # Structured access to the definitions comments.
+    public def documentation: () -> Documentation?
+
+    # The location of the definition.
+    public def location: () -> Location?
+  end
+
+  # Structured access to a set of comment lines.
+  class Documentation < Comment::Node
+    attr_reader comments(@comments): Array[String]
+
+    attr_reader language(@language): Language::Generic?
+
+    @comments: Array[String]
+
+    @language: Language::Generic?
+
+    # Initialize the documentation with an array of comments, within a specific language.
+    public def initialize: (Array[String] comments, Language::Generic? language) -> void
+  end
+
+  # Represents a list of definitions organised for quick lookup and lexical enumeration.
+  class Index
+    attr_reader languages(@languages): Languages
+
+    attr_reader sources(@sources): Hash[String, Source]
+
+    attr_reader definitions(@definitions): Hash[String, Definition]
+
+    attr_reader trie(@trie): Trie[Definition]
+
+    @languages: Languages
+
+    @sources: Hash[String, Source]
+
+    @definitions: Hash[String, Definition]
+
+    @trie: Trie[Definition]
+
+    # Create and populate an index from the given paths.
+    public def self.for: (*String, ?languages: Languages) -> Index
+
+    # Initialize an empty index.
+    public def initialize: (?Languages languages) -> void
+
+    # Generate a string representation of this index.
+    public def inspect: () -> String
+
+    # Updates the index by parsing the specified files.
+    # All extracted definitions are merged into the existing index.
+    public def update: (Array[String] paths) -> untyped
+
+    # Lookup the specified reference and return matching definitions.
+    public def lookup: (Language::Reference reference, ?relative_to: Definition?) -> Definition?
+  end
+
+  # Language specific parsers and definitions.
+  module Language
+    # Represents a generic language implementation that can be extended for specific languages.
+    class Generic
+      attr_reader name(@name): String
+
+      attr_reader extensions(@extensions): Array[String]
+
+      attr_reader tags(@tags): Comment::Tags
+
+      @name: String
+
+      @extensions: Array[String]
+
+      @tags: Comment::Tags
+
+      # Initialize a new generic language.
+      public def initialize: (String name, ?extensions: Array[String], ?tags: Comment::Tags) -> void
+
+      # Get all names for this language.
+      public def names: () -> Array[String]
+
+      # Generate a language-specific reference.
+      public def reference_for: (String identifier) -> Reference
+
+      # Get the parser for this language.
+      public def parser: () -> untyped
+
+      # Parse the input yielding definitions.
+      public def definitions_for: (Source source) { (Definition definition) -> void } -> Enumerator[Segment]
+
+      # Parse the input yielding segments.
+      # Segments are constructed from a block of top level comments followed by a block of code.
+      public def segments_for: (Source source) { (Segment segment) -> void } -> Enumerator[Segment]
+
+      # Generate a code representation with syntax highlighting and link resolution.
+      public def code_for: (String text, Index index, ?relative_to: Definition) -> untyped
+    end
+
+    # An reference which can be resolved to zero or more definitions.
+    class Reference
+      attr_reader identifier(@identifier): String
+
+      attr_reader language(@language): Language::Generic
+
+      @identifier: String
+
+      @language: Language::Generic
+
+      # Initialize the reference.
+      public def initialize: (String identifier, Language::Generic language, ?Array[String]? lexical_path) -> void
+
+      # Generate a string representation of the reference.
+      public def to_s: () -> untyped
+
+      # Generate a debug representation of the reference.
+      public def inspect: () -> untyped
+
+      # Whether the reference starts at the base of the lexical tree.
+      public def absolute?: () -> bool
+
+      # Check if this is a relative reference.
+      public def relative?: () -> bool
+
+      # Split an identifier into prefix and name components.
+      public def split: (String identifier) -> untyped
+
+      # Get the lexical path of this reference.
+      public def lexical_path: () -> untyped
+
+      # Calculate the priority of a definition for matching.
+      public def priority: (String definition, String prefix) -> untyped
+
+      # Find the best matching definition from a list.
+      public def best: (Array[Definition] definitions) -> Definition?
+
+      # The lexical path of the reference.
+      public def path: () -> Array[Symbol]
+    end
+
+    # Represents an interface for extracting information from Ruby source code.
+    module Ruby
+      # Create a new Ruby language instance.
+      public def self.new: () -> Ruby::Generic
+
+      # Represents an alias statement, e.g., `alias new_name old_name` or `alias_method :new_name, :old_name`
+      class Alias < Definition
+        # Initialize a new alias definition.
+        public def initialize: (String new_name, String old_name, **Hash options) -> void
+
+        # Generate a short form representation of the alias.
+        public def short_form: () -> untyped
+
+        # Generate a long form representation of the alias.
+        public def long_form: () -> untyped
+
+        # Generate a string representation of the alias.
+        public def to_s: () -> untyped
+      end
+
+      # A Ruby-specific attribute.
+      class Attribute < Definition
+        # The short form of the attribute.
+        # e.g. `attr :value`.
+        public def short_form: () -> untyped
+
+        # Generate a long form representation of the attribute.
+        public def long_form: () -> untyped
+      end
+
+      # A Ruby-specific block which might carry other definitions.
+      class Block < Definition
+        # A block can sometimes be a container for other definitions.
+        public def container?: () -> bool
+
+        # Generate a nested name for the block.
+        public def nested_name: () -> untyped
+
+        # The short form of the block.
+        # e.g. `foo`.
+        public def short_form: () -> untyped
+
+        # The long form of the block.
+        # e.g. `foo(:bar)`.
+        public def long_form: () -> untyped
+
+        # The fully qualified name of the block.
+        # e.g. `::Barnyard::foo`.
+        public def qualified_form: () -> untyped
+
+        # Convert the block to a different kind of definition.
+        public def convert: (Symbol kind) -> untyped
+      end
+
+      # A Ruby-specific block which might carry other definitions.
+      class Call < Definition
+        # A block can sometimes be a container for other definitions.
+        public def container?: () -> bool
+
+        # The short form of the class.
+        # e.g. `foo`.
+        public def short_form: () -> untyped
+
+        # The long form of the class.
+        # e.g. `foo(:bar)`.
+        public def long_form: () -> untyped
+
+        # The fully qualified name of the block.
+        # e.g. `class ::Barnyard::Dog`.
+        public def qualified_form: () -> untyped
+      end
+
+      # A Ruby-specific class.
+      class Class < Definition
+        # Initialize a new class definition.
+        public def initialize: (*Array arguments, ?super_class: String, **Hash options) -> void
+
+        # A class is a container for other definitions.
+        public def container?: () -> bool
+
+        # The short form of the class.
+        # e.g. `class Animal`.
+        public def short_form: () -> untyped
+
+        # The long form of the class.
+        # e.g. `class Dog < Animal`.
+        public def long_form: () -> untyped
+
+        # The fully qualified name of the class.
+        # e.g. `class ::Barnyard::Dog`.
+        public def qualified_form: () -> untyped
+      end
+
+      # A Ruby-specific singleton class.
+      class Singleton < Definition
+        # Generate a nested name for the singleton class.
+        public def nested_name: () -> untyped
+
+        # A singleton class is a container for other definitions.
+        public def container?: () -> bool
+
+        # Typically, a singleton class does not contain other definitions.
+        public def nested?: () -> bool
+
+        # The short form of the class.
+        # e.g. `class << self`.
+        public def short_form: () -> untyped
+
+        private def absolute_path: () -> untyped
+      end
+
+      # A Ruby-specific block of code.
+      class Code
+        attr_reader text(@text): String
+
+        attr_reader root(@root): untyped
+
+        attr_reader index(@index): Index
+
+        attr_reader relative_to(@relative_to): Definition?
+
+        attr_reader language(@language): Language::Generic
+
+        @text: String
+
+        @root: untyped
+
+        @index: Index
+
+        @relative_to: Definition?
+
+        @language: Language::Generic
+
+        # Initialize a new code block.
+        public def initialize: (String text, Index index, language: Language::Generic, ?relative_to: Definition?) -> void
+
+        # Extract definitions from the code.
+        public def extract: (?Array into) -> Array
+
+        # Traverse the syntax tree and extract definitions.
+        private def traverse: (untyped node, Array into) -> self
+      end
+
+      # A Ruby-specific constant.
+      class Constant < Definition
+        # The short form of the constant.
+        # e.g. `NAME`.
+        public def short_form: () -> untyped
+
+        # Generate a nested name for the constant.
+        public def nested_name: () -> untyped
+
+        # The long form of the constant.
+        # e.g. `NAME = "Alice"`.
+        public def long_form: () -> untyped
+      end
+
+      # Represents a Ruby-specific definition extracted from source code.
+      class Definition < Decode::Definition
+        attr_reader node(@node): Parser::AST::Node
+
+        attr_reader visibility(@visibility): Symbol
+
+        @node: Parser::AST::Node
+
+        @visibility: Symbol
+
+        # Initialize the definition from the syntax tree node.
+        public def initialize: (*Array arguments, ?visibility: Symbol, ?node: Parser::AST::Node, **Hash options) -> void
+
+        # Check if this definition is public.
+        public def public?: () -> bool
+
+        # Check if this definition is protected.
+        public def protected?: () -> bool
+
+        # Check if this definition is private.
+        public def private?: () -> bool
+
+        # Check if this definition spans multiple lines.
+        public def multiline?: () -> bool
+
+        # The source code associated with the definition.
+        public def text: () -> String
+
+        # Get the location of this definition.
+        public def location: () -> Location?
+      end
+
+      # A Ruby-specific function.
+      class Function < Method
+        # Generate a nested name for the function.
+        public def nested_name: () -> untyped
+
+        # The node which contains the function arguments.
+        public def arguments_node: () -> untyped
+      end
+
+      # Represents the Ruby language implementation for parsing and analysis.
+      class Generic < Language::Generic
+        # Get the parser for Ruby source code.
+        public def parser: () -> Language::Ruby::Parser
+
+        # Generate a language-specific reference for Ruby.
+        public def reference_for: (String identifier) -> Reference
+
+        # Generate a code representation with syntax highlighting and link resolution.
+        public def code_for: (String text, Index index, ?relative_to: Definition) -> Code
+      end
+
+      # A Ruby-specific method.
+      class Method < Definition
+        # Initialize a new method definition.
+        public def initialize: (*Array arguments, ?receiver: String, **Hash options) -> void
+
+        # Generate a nested name for the method.
+        public def nested_name: () -> untyped
+
+        # The short form of the method.
+        # e.g. `def puts` or `def self.puts`.
+        public def short_form: () -> untyped
+
+        # The node which contains the function arguments.
+        public def arguments_node: () -> untyped
+
+        # The long form of the method.
+        # e.g. `def puts(*lines, separator: "\n")` or `def self.puts(*lines, separator: "\n")`.
+        public def long_form: () -> untyped
+
+        # The fully qualified name of the block.
+        # e.g. `::Barnyard#foo`.
+        public def qualified_form: () -> untyped
+
+        # Override the qualified_name method to handle method name joining correctly
+        public def qualified_name: () -> untyped
+
+        # Convert the method to a different kind of definition.
+        public def convert: (Symbol kind) -> untyped
+      end
+
+      # A Ruby-specific module.
+      class Module < Definition
+        # A module is a container for other definitions.
+        public def container?: () -> bool
+
+        # The short form of the module.
+        # e.g. `module Barnyard`.
+        public def short_form: () -> untyped
+
+        # Generate a long form representation of the module.
+        public def long_form: () -> untyped
+
+        # The fully qualified name of the module.
+        # e.g. `module ::Barnyard::Dog`.
+        public def qualified_form: () -> untyped
+      end
+
+      # The Ruby source code parser.
+      class Parser
+        attr_reader language(@language): Language::Generic
+
+        attr_reader visibility(@visibility): Symbol
+
+        attr_reader definitions(@definitions): Hash
+
+        @language: Language::Generic
+
+        @visibility: Symbol
+
+        @definitions: Hash
+
+        # Initialize a new Ruby parser.
+        public def initialize: (Language::Generic language) -> void
+
+        # Parse the source code using Prism.
+        public def parse_source: (Source source) -> untyped
+
+        # Parse the given source object, can be a string or a Source instance.
+        private def parse_source: (String | Source source) -> untyped
+
+        # Extract definitions from the given input file.
+        public def definitions_for: (Source source) -> Enumerator[Definition]
+
+        # Walk over the syntax tree and extract relevant definitions with their associated comments.
+        public def walk_definitions: (untyped node, ?Definition? parent, ?Source? source) -> untyped
+
+        # Extract segments from the given input file.
+        public def segments_for: (Source source) -> Enumerator[Segment]
+
+        # Extract clean comment text from a node by removing leading # symbols and whitespace.
+        # Only returns comments that directly precede the node (i.e., are adjacent to it).
+        # Extract comments that directly precede a node.
+        private def comments_for: (untyped node) -> Array[String]
+
+        # Assign a definition to a parent scope.
+        private def assign_definition: (Definition? parent, Definition definition) -> untyped
+
+        # Look up a definition in the parent scope.
+        private def lookup_definition: (Definition? parent, Symbol name) -> Definition?
+
+        # Store a definition in the parent scope.
+        private def store_definition: (Definition? parent, Symbol name, Definition definition) -> untyped
+
+        private def with_visibility: (?untyped visibility) -> untyped
+
+        private def attribute_name_for: (untyped node) -> untyped
+
+        private def nested_path_for: (untyped node, ?untyped path) -> untyped
+
+        private def nested_name_for: (untyped node) -> untyped
+
+        private def symbol_name_for: (untyped node) -> untyped
+
+        private def receiver_for: (untyped node) -> untyped
+
+        private def singleton_name_for: (untyped node) -> untyped
+
+        private def kind_for: (untyped node, ?untyped comments) -> untyped
+
+        private def scope_for: (untyped comments, ?untyped parent) -> untyped
+
+        private def constant_names_for: (untyped child_nodes) -> untyped
+
+        private def walk_segments: (untyped node, untyped comments) -> untyped
+      end
+
+      # An Ruby-specific reference which can be resolved to zero or more definitions.
+      class Reference < Language::Reference
+        # Create a reference from a constant node.
+        public def self.from_const: (Prism::Node node, Language::Generic language) -> Reference
+
+        # Append a constant node to the path.
+        public def self.append_const: (Prism::Node node, ?Array path) -> Array
+
+        # Split a Ruby identifier into prefix and name components.
+        public def split: (String text) -> Array
+      end
+
+      # A Ruby specific code segment.
+      class Segment < Decode::Segment
+        # Initialize a new Ruby segment.
+        public def initialize: (Array[String] comments, Generic language, Prism::Node node, **Hash options) -> void
+
+        # Expand the segment to include another node.
+        public def expand: (Prism::Node node) -> untyped
+
+        # The source code trailing the comments.
+        public def code: () -> String?
+      end
+    end
+  end
+
+  # Represents a context for looking up languages based on file extension or name.
+  class Languages
+    REFERENCE: Regexp
+
+    attr_reader named(@named): Hash[String, Language::Generic]
+
+    attr_reader extensions(@extensions): Hash[String, Language::Generic]
+
+    @named: Hash[String, Language::Generic]
+
+    @extensions: Hash[String, Language::Generic]
+
+    # Create a new languages context with all supported languages.
+    public def self.all: () -> Languages
+
+    # Initialize a new languages context.
+    public def initialize: () -> void
+
+    # Freeze the languages context to prevent further modifications.
+    public def freeze: () -> untyped
+
+    # Add a language to this context.
+    public def add: (Language::Generic language) -> self
+
+    # Fetch a language by name, creating a generic language if needed.
+    public def fetch: (String name) -> Language::Generic?
+
+    # Create a source object for the given file path.
+    public def source_for: (String path) -> Source?
+
+    # Parse a language agnostic reference.
+    public def parse_reference: (String text, ?default_language: Language::Generic?) -> Language::Reference?
+
+    # Create a reference for the given language and identifier.
+    public def reference_for: (String name, String identifier) -> Language::Reference?
+  end
+
+  # Represents a location in a source file.
+  class Location
+    attr_reader path(@path): String
+
+    attr_reader line(@line): Integer
+
+    @path: String
+
+    @line: Integer
+
+    public def initialize: (untyped path, untyped line) -> void
+
+    # Generate a string representation of the location.
+    public def to_s: () -> untyped
+  end
+
+  # RBS generation functionality for Ruby type signatures.
+  module RBS
+    # Represents a Ruby class definition wrapper for RBS generation.
+    class Class < Wrapper
+      # Initialize a new class wrapper.
+      public def initialize: (Decode::Definition definition) -> void
+
+      # Extract generic type parameters from the class definition.
+      public def generics: () -> Array[Symbol]
+
+      # Convert the class definition to RBS AST
+      public def to_rbs_ast: (?untyped method_definitions, ?untyped constant_definitions, ?untyped attribute_definitions, ?untyped index) -> untyped
+
+      private def extract_generics: () -> untyped
+
+      # Build a constant RBS declaration.
+      private def build_constant_rbs: (untyped constant_definition) -> untyped
+
+      # Convert a simple name to RBS TypeName (not qualified).
+      private def simple_name_to_rbs: (untyped name) -> untyped
+
+      # Build attribute RBS declarations and infer instance variable types.
+      private def build_attributes_rbs: (Array attribute_definitions) -> Array
+
+      # Convert a qualified name to RBS TypeName
+      private def qualified_name_to_rbs: (untyped qualified_name) -> untyped
+    end
+
+    # Represents a generator for RBS type declarations.
+    class Generator
+      attr_reader loader(@loader): ::RBS::EnvironmentLoader
+
+      attr_reader environment(@environment): ::RBS::Environment
+
+      attr_reader include_private(@include_private): bool
+
+      @loader: ::RBS::EnvironmentLoader
+
+      @environment: ::RBS::Environment
+
+      @include_private: bool
+
+      # Initialize a new RBS generator.
+      # Sets up the RBS environment for type resolution.
+      public def initialize: (?include_private: bool) -> void
+
+      # Generate RBS declarations for the given index.
+      public def generate: (Decode::Index index, ?output: IO) -> untyped
+
+      # Build nested RBS declarations preserving the parent hierarchy.
+      private def build_nested_declaration: (Definition definition, Hash declarations, Index index) -> untyped?
+
+      # Convert a definition to RBS AST.
+      private def definition_to_rbs: (Definition definition, Index index) -> untyped
+
+      # Get methods for a given definition efficiently using trie lookup.
+      private def get_methods_for_definition: (Definition definition, Index index) -> Array
+
+      # Get constants for a given definition efficiently using trie lookup.
+      private def get_constants_for_definition: (Definition definition, Index index) -> Array
+
+      # Get attributes for a given definition efficiently using trie lookup.
+      private def get_attributes_for_definition: (Definition definition, Index index) -> Array
+    end
+
+    # Represents a Ruby method definition wrapper for RBS generation.
+    class Method < Wrapper
+      # Initialize a new method wrapper.
+      public def initialize: (Decode::Definition definition) -> void
+
+      # Extract method signatures from the method definition.
+      public def signatures: () -> Array
+
+      # Extract keyword arguments from the method definition.
+      public def keyword_arguments: () -> Hash
+
+      # Extract return type from the method definition.
+      public def return_type: () -> ::RBS::Types::t
+
+      # Extract parameters from the method definition.
+      public def parameters: () -> Array
+
+      # Convert the method definition to RBS AST
+      public def to_rbs_ast: (?untyped index) -> untyped
+
+      # Build a complete RBS function type from AST information.
+      public def build_function_type_from_ast: (Definition definition, Index index) -> RBS::Types::Function
+
+      private def extract_signatures: () -> untyped
+
+      # Extract return type from method documentation.
+      private def extract_return_type: (untyped definition, untyped index) -> untyped
+
+      # Extract parameter types from method documentation.
+      private def extract_parameters: (untyped definition, untyped index) -> untyped
+
+      # Extract parameter information from the Prism AST node.
+      private def extract_parameters_from_ast: (Definition definition) -> Array
+
+      # Extract keyword arguments from @option tags and AST.
+      private def extract_keyword_arguments: (untyped definition, untyped index) -> untyped
+
+      # Extract keyword arguments from the Prism AST node.
+      private def extract_keyword_arguments_from_ast: (Definition definition) -> Hash
+
+      # Extract documented parameter types into a hash for lookup.
+      private def extract_documented_parameter_types: (Definition definition) -> Hash
+
+      # Make a type optional if it's not already nullable.
+      private def make_type_optional_if_needed: (RBS::Types::t type) -> RBS::Types::t
+
+      # Extract block type from method documentation.
+      private def extract_block_type: (untyped definition, untyped index) -> untyped
+
+      # Infer return type based on method patterns and heuristics.
+      private def infer_return_type: (untyped definition) -> untyped
+    end
+
+    # Represents a Ruby module definition wrapper for RBS generation.
+    class Module < Wrapper
+      # Initialize a new module wrapper.
+      public def initialize: (Decode::Definition definition) -> void
+
+      # Convert the module definition to RBS AST
+      public def to_rbs_ast: (?Array[Method] method_definitions, ?Array[Constant] constant_definitions, ?Array[Attribute] attribute_definitions, ?Index? index) -> RBS::AST::Declarations::Module
+
+      # Build a constant RBS declaration.
+      private def build_constant_rbs: (untyped constant_definition) -> untyped
+
+      # Convert a simple name to RBS TypeName (not qualified).
+      private def simple_name_to_rbs: (untyped name) -> untyped
+
+      # Build attribute RBS declarations and infer instance variable types.
+      private def build_attributes_rbs: (Array attribute_definitions) -> Array
+    end
+
+    module Type
+      # Check if an RBS type represents a nullable/optional type
+      # This method recursively traverses the type tree to find nil anywhere
+      public def self.nullable?: (untyped rbs_type) -> bool
+
+      # Parse a type string and convert it to RBS type
+      public def self.parse: (String type_string) -> untyped
+    end
+
+    # Base wrapper class for RBS generation from definitions.
+    class Wrapper
+      # Initialize the wrapper instance variables.
+      public def initialize: (Definition definition) -> void
+
+      # Extract RBS tags from the definition's documentation.
+      public def tags: () -> Array
+
+      # Extract comment from the definition's documentation.
+      public def comment: () -> RBS::AST::Comment?
+
+      # Extract RBS tags from the definition's documentation.
+      private def extract_tags: () -> Array
+
+      # Extract comment from definition documentation.
+      private def extract_comment: (?Definition definition) -> RBS::AST::Comment?
+    end
+  end
+
+  # An abstract namespace for nesting definitions.
+  class Scope < Definition
+    public def short_form: () -> String
+
+    # Scopes are always containers.
+    public def container?: () -> bool
+  end
+
+  # A chunk of code with an optional preceeding comment block.
+  #
+  # ~~~ ruby
+  # # Get the first segment from a source file:
+  # segment = source.segments.first
+  # ~~~
+  class Segment
+    attr_reader comments(@comments): Array[String]
+
+    attr_reader language(@language): Language::Generic
+
+    @comments: Array[String]
+
+    @language: Language::Generic
+
+    # Initialize a new segment.
+    public def initialize: (Array[String] comments, Language::Generic language) -> void
+
+    # An interface for accsssing the documentation of the definition.
+    public def documentation: () -> Documentation?
+
+    # The source code trailing the comments.
+    public def code: () -> String?
+  end
+
+  # Represents a source file in a specific language.
+  class Source
+    attr_reader path(@path): StringPath
+
+    attr_reader language(@language): Language::Generic
+
+    @path: StringPath
+
+    @language: Language::Generic
+
+    # Initialize a new source file.
+    public def initialize: (String path, Language::Generic language) -> void
+
+    # Read the source file into an internal buffer/cache.
+    public def read: () -> String
+
+    # Open the source file and read all definitions.
+    public def definitions: () { (Definition definition) -> void } -> Enumerator[Definition]
+
+    # Open the source file and read all segments.
+    public def segments: () { (Segment segment) -> void } -> Enumerator[Segment]
+
+    # Generate code representation with optional index for link resolution.
+    public def code: (?Index? index, ?relative_to: Definition?) -> String
+  end
+
+  # Provides syntax rewriting and linking functionality.
+  module Syntax
+    # Represents a link to a definition in the documentation.
+    class Link < Match
+      # Initialize a new link.
+      public def initialize: (Range range, Definition definition) -> void
+
+      # Apply the link to the output.
+      public def apply: (String output, Rewriter rewriter) -> untyped
+    end
+
+    # Represents a match in the source text for syntax rewriting.
+    class Match
+      # Initialize a new match.
+      public def initialize: (Range range) -> void
+
+      # Apply the match to extract text from source.
+      public def apply: (String source) -> untyped
+
+      # Apply the match to the output.
+      public def apply: (String output, Rewriter rewriter) -> untyped
+
+      # Compare matches by their starting position.
+      public def <=>: (Match other) -> untyped
+
+      # Get the starting offset of this match.
+      public def offset: () -> untyped
+
+      # Get the size of this match.
+      public def size: () -> untyped
+    end
+
+    # Provides text rewriting functionality with match-based substitutions.
+    class Rewriter
+      attr_reader text(@text): String
+
+      attr_reader matches(@matches): Array[Match]
+
+      @text: String
+
+      @matches: Array[Match]
+
+      # Initialize a new rewriter.
+      public def initialize: (String text) -> void
+
+      # Add a match to the rewriter.
+      public def <<: (Match match) -> self
+
+      # Returns a chunk of raw text with no formatting.
+      public def text_for: (untyped range) -> untyped
+
+      # Apply all matches to generate the rewritten output.
+      public def apply: (?Array output) -> untyped
+
+      # Generate a link to a definition.
+      public def link_to: (Definition definition, String text) -> untyped
+    end
+  end
+
+  # Represents a prefix-trie data structure for fast lexical lookups.
+  class Trie[T]
+    attr_reader root(@root): Node
+
+    @root: Node
+
+    # Initialize an empty trie.
+    public def initialize: () -> void
+
+    # Insert the specified value at the given path into the trie.
+    public def insert: (Array[Symbol] path, T value) -> untyped
+
+    # Lookup the values at the specified path.
+    public def lookup: (Array[Symbol] path) -> Node?
+
+    # Enumerate all lexical scopes under the specified path.
+    public def each: (?Array[Symbol]) { (Array[Symbol], Array[T] | nil) -> void } -> void
+
+    # Traverse the trie starting from the specified path.
+    # See {Node#traverse} for details.
+    public def traverse: (?Array[Symbol]) { (Array[Symbol], Node, Proc) -> void } -> void
+
+    # Represents a single node in the trie.
+    class Node
+      attr_reader values(@values): Array[T]?
+
+      attr_reader children(@children): Hash[Symbol, Node]
+
+      @values: Array[T]?
+
+      @children: Hash[Symbol, Node]
+
+      # Initialize an empty node.
+      public def initialize: () -> void
+
+      # Generate a string representation of this node.
+      public def inspect: () -> String
+
+      # Look up a lexical path starting at this node.
+      public def lookup: (Array[Symbol] path, ?Integer index) -> Node?
+
+      # Traverse the trie from this node.
+      # Invoke `descend.call` to traverse the children of the current node.
+      public def traverse: (?Array[Symbol]) { (Array[Symbol], Node, Proc) -> void } -> void
+    end
+  end
+end