[10.0.0 branch] Return a new Dependency class instead of raw Hash objects, from analyses' :dependencies result. - Githubissues

librariesio / bibliothecary

:notebook_with_decorative_cover: Libraries.io Package Manager Manifest Parsers

https://libraries.io/rubygems/bibliothecary

GNU Affero General Public License v3.0

89 stars 36 forks source link

[10.0.0 branch] Return a new Dependency class instead of raw Hash objects, from analyses' :dependencies result. #596

Closed tiegz closed 2 months ago

tiegz commented 2 months ago

This defines a new Bibliothecary::Dependency class, and proposes to return instances of that object from parsed manifests, instead of Hashes.

Current behavior (<10.0)

Bibliothecary returns a list of dependency Hashes in its analyses, e.g.:

analysis = Bibliothecary.analyse_file("package.json", "package.json")
analysis[:dependencies]
=> [{ name: "jquery", requirement: ">= 1.9.1", type: "runtime" }]

New behavior (>= 10.0)

analysis = Bibliothecary.analyse_file("package.json", "package.json")
analysis[:dependencies]
=> [Bibliothecary::Dependency.new(name: "jquery", requirement: ">= 1.9.1", type: "runtime")],

Benefits

Having a dedicated Dependency class will:

... define a contract between Bibliothecary and its downstream users
... raise errors when a field is accessed on a dependency that doesn't exist
... documents the possible fields of dependencies
... sets requirements for dependencies ("name" and "requirement")

Downsides

breaking change (this would be merged into the 10-0 branch)
more verbose Bibliothecary code
doesn't benefit from autocomplete for most people, since most IDEs aren't aware of required gems

TODO

[x] swift_pm.rb
[x] shard.rb
[x] rubygems.rb
[x] pypi.rb
[x] pub.rb
[x] packagist.rb
[x] nuget.rb
[x] npm.rb
[x] meteor.rb
[x] maven.rb
[x] julia.rb
[x] hex.rb
[x] haxelib.rb
[x] hackage.rb
[x] go.rb
[x] elm.rb
[x] dub.rb
[x] cran.rb
[x] cpan.rb
[x] conda.rb
[x] cocoapods.rb
[x] clojars.rb
[x] carthage.rb
[x] cargo.rb
[x] bower.rb
[x] CycloneDX and SPDX multi parsers
[x] CHANGELOG.md file (or README section) that describes how to upgrade apps for this change in 10.0