Mode to export an "externs" file instead of replacing constants?

[dorner]

Is your feature request related to a problem? Please describe.
The PRs I've put in so far have mostly been related to Sord being able to read external files in order to avoid the "Constant not found" errors. I'm wondering what benefit we actually get from this feature. The output of sord (either RBI or RBS) are going to be fed into a type checker, which can then complain about constants that aren't found. Tapioca itself, when it reads gems, outputs a todo file that lists the constants it couldn't find rather than change the output to force you to make changes.

Describe the solution you'd like
A --replace-extern mode where when Sord finds a constant it doesn't know about, it exports it to an externs file and leaves it as is in the RBI/RBS output. This way Sord doesn't even need to read in any dependencies, because it can assume that the user has those dependencies where their type checker can find them.

Does this sound like a good idea? It should be relatively easy to implement. @AaronC81

[apiology]

I was also working to understand the motivation for that feature - if it's something that should stick around, it'd be great leave a breadcrumb for the next person. Maybe in the README, maybe under the features bullet list? Something like "* Reads in all constants in gems so that it can [fill in the blank]"

[AaronC81]

It's been a long time since I first started working on Sord, so my justifications for any features have been somewhat lost to time. Those breadcrumbs would have been helpful ;)

---

I'm wondering what benefit we actually get from this feature. The output of sord (either RBI or RBS) are going to be fed into a type checker, which can then complain about constants that aren't found.

The idea was to make the initial adoption of Sord a bit easier. If you already have a codebase full of YARD types, you might not have been relying on their precise correctness before.

Doing a little bit of namespace resolution means you're more likely to get something that type-checks on your first go, if there are minor namespacing errors throughout your docs. e.g:

module Model
  class Cookie
  end
end

module Logic
  class CookieManager
    # @return [<Cookie>]
    def cookies; end
  end
end

# sord infer - Cookie was resolved to Model::Cookie
sig { returns(T::Array[Model::Cookie]) }
def cookies; end

---

In the corpus of examples in rake examples:seed, there are some instances of this feature being useful:

[INFER] (RSpec::Core::Formatters::BaseFormatter#start) lib/rspec/core/formatters/base_formatter.rb:32: StartNotification was resolved to RSpec::Core::Notifications::StartNotification
[INFER] (YARD::CLI::Server#create_library_version_if_yardopts_exist) lib/yard/cli/server.rb:115: LibraryVersion was resolved to YARD::Server::LibraryVersion
[INFER] (Bundler::Molinillo::SpecificationProvider#sort_dependencies) lib/bundler/vendor/molinillo/lib/molinillo/modules/specification_provider.rb:82: Conflict was resolved to Bundler::Molinillo::Resolver::Resolution::Conflict

but also this case where it's clearly incorrect:

[INFER] (GraphQL::StaticValidation::DefinitionDependencies::DependencyMap#unmet_dependencies) lib/graphql/static_validation/definition_dependencies.rb:80: Node was resolved to RubyVM::AbstractSyntaxTree::Node

---

On the other hand - YARD itself doesn't make any effort to do this. In that example, Cookie isn't linked in the generated docs:

---

I think there's some amount of value in the way it works currently - and I agree @apiology that this should be clearly documented somewhere.

That said, I'm definitely on board with an option like you've described, @dorner.

I think Sord already leaves constants as they are now - it used to be much more aggressive with the SORD_ERROR replacement iirc.

I haven't played much with Tapioca but I'd be interested to learn about how that works.