# Desgin Doc of rbs subtract

This document describes rbs subtract.

## Basic Usage

You can use `rbs subtract` from command line.

# Print RBS to the stdout, which is generated.rbs - hand-written.rbs
$ rbs subtract generated.rbs hand-written.rbs

# It takes multiple minuends. The last argument becomes subtrahend.
$ rbs subtract generated-a.rbs generated-b.rbs hand-written.rbs

# It updates `.rbs` files directly with `-w` option.
$ rbs subtract -w generated-a.rbs generated-b.rbs hand-written.rbs

# It takes multiple subtrahends with --subtrahend option
$ rbs subtract generated.rbs --subtrahend=hand-written-a.rbs --subtrahend=hand-written-b.rbs

## The purpose of rbs subtract

`rbs subtract` focuses on conbining auto-generated RBSs and hand-written RBSs (or two kinds auto-generated RBSs).

There are several RBS generators. For example, `rbs prototype`, RBS Rails, and so on. They are useful, but the RBSs generated by them is not complete, for example, they include `untyped`.

So we want to override the generated RBSs with hand-written RBSs. But we had no good way to override them.

# auto-generated RBS
class C
  # This definition doesn't describe the argument and returned value types,
  # so we want to describe them with hand-written RBS.
  def m: (untyped) -> untyped
end

# hand-written RBS
class C
  # The following definition does not work with the generated RBS
  # because RBS doesn't allow duplicated method definitions.
  def m: (String) -> Integer
  
  # The following definition is valid, but it is not the expected behavior
  # because the overload still has `(untyped) -> untyped`.
  def m: (String) -> Integer | ...
end

To solve this problem, we need to remove `C#m` definition from the generated RBS. But modifing a generated file by the hand introduces hard maintainability sooner or later.

`rbs subtract` solves this problem. It removes duplicated definitions from the generated RBS automatically. Then we can maintain the generated RBSs.

The `rbs subtract`'s goal is modifying generated RBSs to make it valid with the other RBSs. So, after `rbs subtract a.rbs b.rbs > c.rbs`, the environment including `b.rbs` and `c.rbs` has to be valid.

## Example workflow with rbs subtract

We can use this command with the following workflow on a Rails application.

# Generate RBSs for Active Record models under sig/rbs_rails directory
$ bin/rake rbs_rails:all

# Generate RBSs for all Ruby code under sig/prototype directory
$ rbs prototype rb --out-dir=sig/prototype --base-dir=. app lib

# Remove methods generated by RBS Rails from sig/prototype
$ rbs subtract --write sig/prototype sig/rbs_rails
# Remove hand-written methods from generated RBSs
$ rbs subtract --write sig/prototype sig/rbs_rails sig/hand-written

Then the sig directory contains a complete RBS files as an environment. It means `rbs -Isig validate` passes (if there is no missing classes and so on).

## Detailed specifications

See the test file.

## Implementation details

The main implementation is `RBS::Subtractor`. It subtracts an environment from declarations.

It uses `RBS::Environment` as the subtrahend.

It needs to merge several class declarations for the same class, so `RBS::Declarations` is not appropriate for this purpose.

The subtrahend RBSs is probably incomplete RBS, for example, it may depend on the minuend RBS. `RBS::DefinitionBuilder` does not work in this case, so it is inappropriate also.

## Limitations

### Interfaces mixin

`rbs subtract` is not aware of interfaces mixins. For example

# minuend - generated
class C
  def x: () -> untyped
end

# subtrahend - hand-written
class C
  include _I
end

interface _I
  def x: () -> untyped
end

# subtracted by `rbs subtract`
class C
  def x: () -> untyped
end

`x` method remains in the subtracted. Because it is actually defined by `_I`, but not `C`.

It causes duplicated method definition error, so I'd like to improve this situation.

#### Solution ideas

* Remove entire of `class C` from subtracted if the subtrahend incldues interface mixins.
* We can fix this problem easily.
* But it may remove necessary methods.
* Use DefinitionBuilder to trace inheritance
* DefinitionBuilder builds inheritance, so we can remove methods defined by interface correctly.
* But DefinitionBuilder needs complete RBS environment.
* Search interface inheritance by the Subtractor
* Re-implement DefinitionBuilder, but it works with incomplete environment.
* It is bit of hard, and it doesn't 100% emulate the behavior.

### Different type parameters

The subtracted RBS doesn't work with the subtrahend if the subtrahend contains a class/module with type parameters.

# a.rbs
class C
  def foo: () -> untyped
end

# b.rbs
class C[T]
  def bar: () -> untyped
end

# rbs subtract a.rbs b.rbs is the following, the same as a.rbs
# The type parameter of `C` is different, so it causes an error.
class C
  def foo: () -> untyped
end

### attr_accessor

Currently `rbs subtract` command removes `attr_accessor` if the subtrahend contains one of the methods that `attr_accessor` defines. For example

# minuend.rbs
class C
  # It defines a and a=
  attr_accessor a: String
end

# subtrahend.rbs
class C
  def a: () -> String
end

In this case, `rbs subtract a.rbs b.rbs` prints nothing. It removes `C#a=` unexpectedly.

We can fix this problem more easily than other problems. We can convert `attr_accessor` to a `attr_{reader,writer}` in this case.

## Alternative Approaches

This section describes alternative approaches that I considered.

### Specify multiple subtrahends

#### Decided specification

`rbs subtract` treat the last argument as a subtrahend by default. But you can also specify multiple subtrahends by `--subtrahend` option. For example:

# Specify one subtrahend
$ rbs subtract minuend.rbs subtrahend.rbs

# Specify two or more subtrahends
$ rbs subtract minuend.rbs --subtrahend=subtrahend_1.rbs --subtrahend=subtrahend_2.rbs

#### Why this feature is necessary

Specifying multiple subtrahends is useful on the following situaion.

.
└── sig
    ├── app
    │   └── models/user.rbs
    ├── lib
    │   └── lib.rbs
    ├── prototype
    │   └── app/models/user.rbs
    └── rbs_rails
        └── app/moels/user.rbs

6 directories, 4 files

In this case, `rbs subtract` executes `(sig/prototype + sig/rbs_rails) - (sig/app + sig/lib)`, which takes two directories as the subtrahends.

#### Alternative Solutions

I considered the following solutions too.

# Separate minuends and subtrahends by `-`
#
# It looks cool, but it is not common as CLI.
# And I'm not sure I can implement it easily with optparse, because `-` is a meta character of optparse.
$ rbs subtract sig/prototype sig/rbs_rails - sig/app sig/lib

# Add --minuend option
#
# It is not bad, but I like --subtrahend.
$ rbs subtract --minuend=sig/prototype --minuend=sig/rbs_rails sig/app sig/lib

# Add --minuend and --subtrahend options
#
# It is too redundant.
$ rbs subtract --minuend=sig/prototype --minuend=sig/rbs_rails \
  --subtrahend=sig/app --subtrahend=sig/lib

# Specify comma separated files as subtrahend
#
# I do not want to implement the comma separated files because of escaping comma.
# It will introduce complexity.
$ rbs subtract sig/prototype sig/rbs_rails sig/app,sig/lib