rbs 4.0.0.dev.4 → 4.0.0.dev.5

data/docs/inline.md

@@ -0,0 +1,470 @@
+# Inline RBS Type Declaration
+
+Inline RBS type declarations allow you to write type annotations directly in your Ruby source files using comments. Instead of maintaining separate `.rbs` files, you can keep your type information alongside your Ruby code, making it easier to keep types and implementation in sync.
+
+The following example defines `Calculator` class and `add` instance method. The `@rbs` comment gives the type of the `add` method with the RBS method type syntax.
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  def add(a, b)
+    a + b
+  end
+end
+```
+
+## Classes
+
+Inline RBS supports class definitions from your Ruby code. When you define a class in Ruby, the library recognizes it and the corresponding class definition is generated in RBS.
+
+```ruby
+class App
+end
+```
+
+The `::App` class is defined in RBS and you can use it as a type.
+
+### Non-constant class paths
+
+Only classes with constant names are imported. Dynamic or non-constant class definitions are ignored:
+
+```ruby
+# This class is imported
+class MyClass
+end
+
+# This is ignored - dynamic class definition
+MyClass = Class.new do
+end
+
+# This is also ignored - non-constant class name
+object = Object
+class object::MyClass
+end
+```
+
+### Class Nesting
+
+Nested classes work as expected:
+
+```ruby
+class Client
+  class Error
+  end
+end
+```
+
+This creates the types `::Client` and `::Client::Error`.
+
+### Inheritance
+
+Class declarations can have a super class.
+
+```ruby
+class UsersController < ApplicationController
+end
+```
+
+The super class specification must be a constant.
+
+The super class specification allows type applications.
+
+```ruby
+class StringArray < Array #[String]
+end
+```
+
+### Current Limitations
+
+- Generic class definitions are not supported
+
+## Modules
+
+Inline RBS supports module definitions from your Ruby code. When you define a module in Ruby, the library recognizes it and the corresponding module definition is generated in RBS.
+
+```ruby
+module Helper
+end
+```
+
+The `::Helper` module is defined in RBS and you can use it as a type.
+
+### Non-constant module paths
+
+Only modules with constant names are imported. Dynamic or non-constant module definitions are ignored:
+
+```ruby
+# This module is imported
+module MyModule
+end
+
+# This is ignored - dynamic module definition
+MyModule = Module.new do
+end
+
+# This is also ignored - non-constant module name
+object = Object
+module object::MyModule
+end
+```
+
+### Module Nesting
+
+Nested modules work as expected:
+
+```ruby
+module API
+  module V1
+    module Resources
+    end
+  end
+end
+```
+
+This creates the types `::API`, `::API::V1`, and `::API::V1::Resources`.
+
+### Current Limitations
+
+- Generic module definitions are not supported
+- Module self-type constraints are not supported
+
+## Method Definitions
+
+Inline RBS supports methods defined using the `def` syntax in Ruby.
+
+```ruby
+class Calculator
+  def add(x, y) = x+y
+end
+```
+
+It detects method definitions and allows you to add annotation comments to describe their types.
+
+### Unannotated method definition
+
+Methods defined with `def` syntax are detected, but they are untyped.
+
+```ruby
+class Calculator
+  def add(x, y) = x+y
+end
+```
+
+The type of the `Calculator#add` method is `(?) -> untyped` -- it accepts any arguments without type checking and returns an `untyped` object.
+
+### Method type annotation syntax
+
+You can define the type of the method using `@rbs` and `:` syntax.
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  def add(x, y) = x + y
+
+  #: (Integer, Integer) -> Integer
+  def subtract(x, y) = x - y
+end
+```
+
+The type of both methods is `(Integer, Integer) -> Integer` -- they take two `Integer` objects and return an `Integer` object.
+
+Both syntaxes support method overloading:
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  #    | (Float, Float) -> Float
+  def add(x, y) = x + y
+
+  #: (Integer, Integer) -> Integer
+  #: (Float, Float) -> Float
+  def subtract(x, y) = x - y
+end
+```
+
+The type of both methods is `(Integer, Integer) -> Integer | (Float, Float) -> Float`.
+
+> [!NOTE]
+> The `@rbs METHOD-TYPE` syntax allows overloads with the `|` operator, just like in RBS files.
+> Multiple `: METHOD-TYPE` declarations are required for overloads.
+
+#### Doc-style syntax
+
+The `@rbs return: T` syntax declares the return type of a method:
+
+```ruby
+class Calculator
+  # @rbs return: String
+  def to_s
+    "Calculator"
+  end
+end
+```
+
+### Current Limitations
+
+- Class methods and singleton methods are not supported
+- Parameter types are not supported with doc-style syntax
+- Method visibility declaration is not supported yet
+
+## Attributes
+
+Inline RBS supports Ruby's attribute methods: `attr_reader`, `attr_writer`, and `attr_accessor`.
+
+```ruby
+class Person
+  attr_reader :name #: String
+  attr_writer :age #: Integer
+  attr_accessor :email #: String?
+end
+```
+
+It detects these attribute declarations and generates the corresponding getter and setter methods.
+
+The accessor methods and instance variables are defined.
+
+### Unannotated attributes
+
+Attributes defined without type annotations are treated as `untyped`:
+
+```ruby
+class Person
+  attr_reader :name
+  attr_writer :age
+  attr_accessor :email
+end
+```
+
+### Type annotations for attributes
+
+You can add type annotations to attributes using the `#:` syntax in trailing comments:
+
+```ruby
+class Person
+  attr_reader :name #: String
+  attr_writer :age #: Integer
+  attr_accessor :email #: String?
+end
+```
+
+This generates the following typed methods:
+- `name: () -> String`
+- `age=: (Integer) -> Integer`
+- `email: () -> String?` and `email=: (String?) -> String?`
+
+### Multiple attributes
+
+When declaring multiple attributes in one line, the type annotation applies to all attributes:
+
+```ruby
+class Person
+  attr_reader :first_name, :last_name #: String
+  attr_accessor :age, :height #: Integer
+end
+```
+
+All attributes in each declaration share the same type.
+
+### Non-symbol attribute names
+
+Attribute names must be symbol literals.
+
+```ruby
+class Person
+  attr_reader "name" #: String
+
+  age = :age
+  attr_writer age #: Integer
+end
+```
+
+The attribute definitions are ignored because the names are given by string literals and local variables.
+
+### Current Limitations
+
+- Attribute visibility is not supported yet. All attributes are _public_
+
+## Mixin
+
+Inline RBS supports Ruby's mixin methods: `include`, `extend`, and `prepend`.
+
+```ruby
+module Printable
+  # @rbs () -> String
+  def to_print
+    to_s
+  end
+end
+
+class Document
+  include Printable
+  extend Enumerable #[String]
+  prepend Trackable
+end
+```
+
+It detects these mixin declarations and adds them to the class or module definition.
+
+### Basic mixin usage
+
+Mixins work just like in regular RBS files:
+
+```ruby
+module Helper
+end
+
+class MyClass
+  include Helper
+  extend Helper
+  prepend Helper
+end
+```
+
+### Type arguments for generic modules
+
+You can specify type arguments for generic modules using the `#[...]` syntax:
+
+```ruby
+class TodoList
+  include Enumerable #[String]
+
+  # @rbs () { (String) -> void } -> void
+  def each(&block)
+    @items.each(&block)
+  end
+end
+```
+
+### Module name requirements
+
+Only constant module names are supported. Dynamic module references are not allowed:
+
+```ruby
+class MyClass
+  include Helper         # ✓ Works - constant name
+
+  mod = Helper
+  include mod           # ✗ Ignored - non-constant module reference
+
+  include Helper.new    # ✗ Ignored - not a simple constant
+end
+```
+
+### Module name resolution
+
+The module name resolution is based on the nesting of the class/module definitions, unlike Ruby.
+
+Modules accessible through ancestors (super-class/included modules) are not supported.
+
+### Current Limitations
+
+- Only single module arguments are supported (no `include A, B` syntax)
+- Module names must be constants
+
+## Instance Variables
+
+Inline RBS declaration allows defining instance variables.
+
+```ruby
+class Person
+  # @rbs @name: String
+  # @rbs @age: Integer? --
+  #   how old is the person?
+  #   `nil` means it's unspecified.
+
+  # @rbs (String name, Integer? age) -> void
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+end
+```
+
+The `@rbs @VAR-NAME: TYPE` syntax enclosed in `class`/`module` syntax declares instance variables.
+You can add the documentation of the variable followed by two hyphones (`--`).
+
+Instance variable declarations must be under the `class`/`module` syntax, and they are ignored if written inside method definitions.
+
+### Current Limitations
+
+- Only instance variables of class/module instances are allowed
+
+## Constants
+
+Constants are supported by inline RBS declaration.
+
+```ruby
+Foo = 123
+
+module Bar
+  Baz = [1, ""] #: [Integer, String]
+end
+
+# Version of the library
+#
+VERSION = "1.2.3".freeze #: String
+```
+
+### Type Inference for Literal Constants
+
+The types of constants may be automatically inferred when the right-hand side consists of literals:
+
+- **Integers**: `COUNT = 42` → `Integer`
+- **Floats**: `RATE = 3.14` → `Float`
+- **Booleans**: `ENABLED = true` → `bool`
+- **Strings**: `NAME = "test"` → `String`
+- **Symbols**: `STATUS = :ready` → `:ready`
+
+```ruby
+MAX_SIZE = 100           # Inferred as Integer
+PI = 3.14159            # Inferred as Float
+DEBUG = false           # Inferred as bool
+APP_NAME = "MyApp"      # Inferred as String
+DEFAULT_MODE = :strict  # Inferred as :strict
+```
+
+### Explicit Type Annotations
+
+For more complex types or when you want to override inference, use the `#:` syntax:
+
+```ruby
+ITEMS = [1, "hello"] #: [Integer, String]
+CONFIG = { name: "app", version: 1 } #: { name: String, version: Integer }
+CALLBACK = -> { puts "done" } #: ^() -> void
+```
+
+### Documentation Comments
+
+Comments above constant declarations become part of the constant's documentation:
+
+```ruby
+# The maximum number of retries allowed
+# before giving up on the operation
+MAX_RETRIES = 3
+
+# Application configuration loaded from environment
+#
+# This hash contains all the runtime configuration
+# settings for the application.
+CONFIG = load_config() #: Hash[String, untyped]
+```
+
+## Class/module Aliases
+
+Class and module aliases can be defined by assigning existing classes or modules to constants using the `#: class-alias` or `#: module-alias` syntax.
+
+```ruby
+MyObject = Object #: class-alias
+
+MyKernel = Kernel #: module-alias
+```
+
+This creates new type names that refer to the same class or module as the original.
+
+The annotations can have optional type name to specify the class/module name, for the case it cannot be infered through the right-hand-side of the constant declaration.
+
+```ruby
+MyObject = object #: class-alias Object
+
+MyKernel = kernel #: module-alias Kernel
+```

data/docs/sigs.md

@@ -131,10 +131,10 @@ You may need to specify `-r` or `-I` to load signatures.
 The default is `-I sig`.
 
 ```shell
-RBS_TEST_OPT='-r pathname -I sig'
+RBS_TEST_OPT='-r logger -I sig'
 ```
 
-Replacing `pathname` with the `stdlib` you want to include. For example, if you need to load `Set` and `BigDecimal` in `stdlib`, you would need to have `RBS_TEST_OPT='-r set -r bigdecimal -I sig'`
+Replacing `logger` with the `stdlib` you want to include. For example, if you need to load `Set` and `BigDecimal` in `stdlib`, you would need to have `RBS_TEST_OPT='-r set -r bigdecimal -I sig'`
 
 `RBS_TEST_LOGLEVEL` can be used to configure log level. Defaults to `info`.
 
@@ -148,7 +148,7 @@ So, a typical command line to start the test would look like the following:
 $ RBS_TEST_LOGLEVEL=error \
   RBS_TEST_TARGET='Kaigi::*' \
   RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
-  RBS_TEST_OPT='-rset -rpathname -Isig -Iprivate' \
+  RBS_TEST_OPT='-rlogger -Isig -Iprivate' \
   RBS_TEST_RAISE=true \
   RUBYOPT='-rbundler/setup -rrbs/test/setup' \
   bundle exec rake test

data/docs/syntax.md

@@ -650,7 +650,7 @@ _module-type-parameters_ ::=                                                  #
 
 Class declaration can have type parameters and superclass. When you omit superclass, `::Object` is assumed.
 
-* Super class arguments and generic class upperbounds are not *classish-context* nor *self-context*
+* Super class arguments and generic class bounds are not *classish-context* nor *self-context*
 
 ### Module declaration
 
@@ -668,7 +668,7 @@ end
 
 The `Enumerable` module above requires `each` method for enumerating objects.
 
-* Self type arguments and generic class upperbounds are not *classish-context* nor *self-context*
+* Self type arguments and generic class bounds are not *classish-context* nor *self-context*
 
 ### Class/module alias declaration
 
@@ -764,7 +764,8 @@ _module-type-parameter_ ::= _generics-unchecked_ _generics-variance_ _type-varia
 _method-type-param_ ::= _type-variable_ _generics-bound_
 
 _generics-bound_ ::=                 (No type bound)
-                   | `<` _type_      (The generics parameter is bounded)
+                   | `<` _type_      (The generics parameter has an upper bound)
+                   | '>' _type_      (The generics parameter has a lower bound)
 
 _default-type_ ::=                    (No default type)
                  | `=` _type_         (The generics parameter has default type)
@@ -777,6 +778,9 @@ _generics-unchecked_ ::=              (Empty)
                        | `unchecked`  (Skips variance annotation validation)
 ```
 
+A type parameter can have both upper and lower bounds, which can be specified in either order:
+`[T < UpperBound > LowerBound]` or `[T > LowerBound < UpperBound]`.
+
 RBS allows class/module/interface/type alias definitions and methods to be generic.
 
 ```rbs
@@ -834,13 +838,38 @@ class PrettyPrint[T < _Output]
 end
 ```
 
-If a type parameter has an upper bound, the type parameter must be instantiated with types that is a subtype of the upper bound.
+If a type parameter has an upper bound, the type parameter must be instantiated with types that are a subtype of the upper bound.
 
 ```rbs
 type str_printer = PrettyPrint[String]    # OK
 type int_printer = PrettyPrint[Integer]   # Type error
 ```
 
+If a type parameter has a lower bound, the type parameter must be instantiated with types that are a supertype of the lower bound.
+
+```rbs
+class PrettyPrint[T > Numeric]
+end
+
+type obj_printer = PrettyPrint[Object]    # OK
+type int_printer = PrettyPrint[Integer]   # Type error
+```
+
+A type parameter can have both an upper and a lower bound, and these bounds can be specified in any order.
+
+```rbs
+class FlexibleProcessor[T > Integer < Numeric]
+  # This class processes types T that are supertypes of Integer but also subtypes of Numeric.
+  # This includes Integer, Rational, Complex, Float, and Numeric itself.
+  def calculate: (T) -> T
+end
+
+type int_processor = FlexibleProcessor[Integer]   # OK (Integer > Integer and Integer < Numeric)
+type num_processor = FlexibleProcessor[Numeric]   # OK (Numeric > Integer and Numeric < Numeric)
+type obj_processor = FlexibleProcessor[Object]    # Type error (Object is not < Numeric)
+type str_processor = FlexibleProcessor[String]    # Type error (String is not > Integer)
+```
+
 The generics type parameter of modules, classes, interfaces, or type aliases can have a default type.
 
 ```rbs

data/docs/type_fingerprint.md

@@ -0,0 +1,21 @@
+# Type Fingerprint of RBS Inline AST
+
+Type fingerprint of RBS Inline AST is an object that can be used to detect if the RBS Inline AST is updated and the type checker should type check the whole codebase again.
+
+1. If the AST update is related to the type information, the fingerprint is changed -- adding new type, including new module, changing method type, etc. The type checker should type check the codebase with updated type information.
+2. If the AST updated is not related to the type information, the fingerprint keeps the last value -- changing the method implementation, adding a method call in the top level, adding white spaces and new lines, etc. The type checker can skip updating the type information, and type checking only the implementation of the file is sufficient.
+3. Documentation comments are considered type related information for now.
+
+## Type Fingerprint Calculation
+
+The type fingerprint is calculated by converting AST nodes to standardized data structures that represent only the type-relevant information. Each AST class implements a `type_fingerprint` method that returns mainly arrays and strings.
+
+We expect not using the values for something other than change detection. Compare old and new fingerprints, and we can detect the change between the RBS inline AST if the fingerprints are different.
+
+The fingerprint methods are implemented across:
+
+- `AST::Ruby::Annotations::*#type_fingerprint` - Returns `untyped` (arrays, strings, or nil)
+- `AST::Ruby::Members::*#type_fingerprint` - Returns `untyped` (typically arrays)
+- `AST::Ruby::Declarations::*#type_fingerprint` - Returns `untyped` (typically arrays)
+- `InlineParser::Result#type_fingerprint` - Returns `untyped` (array of declaration fingerprints)
+

data/exe/rbs

@@ -4,4 +4,4 @@ $LOAD_PATH << File.join(__dir__, "../lib")
 require "rbs"
 require "rbs/cli"
 
-RBS::CLI.new(stdout: STDOUT, stderr: STDERR).run(ARGV.dup)
+exit RBS::CLI.new(stdout: STDOUT, stderr: STDERR).run(ARGV.dup)