typegap 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 7b010dc8e1cbdcf758c36bb15b2a29433bf48b8d06fd50a66d7c53e2fd9f6c9c
4
+ data.tar.gz: 778ff424520098c970234c6327fa7b0051c64c3e0b6b7944b0925d2eaef2f6e2
5
+ SHA512:
6
+ metadata.gz: bbbf82ec2a9f46743762966b41c2b47091c39c27b1872e31b1af14c1af8017a85f9a9cb5aca97c7cb5464efe56c41de704764d92daa0beb90284b7342e02419a
7
+ data.tar.gz: 736435d6d416841e98e8e35f453c4b8a6e7d9add4fcd830f1b3031bb11f7b48ff83b80eb5b22fc03a3d8a70fa27bd1f9d33ee725637f37cdc484321ec10b2c76
data/CHANGELOG.md ADDED
@@ -0,0 +1,11 @@
1
+ # Changelog
2
+
3
+ ## [0.1.0] - 2026-11-16
4
+
5
+ First release. typegap reports where a Ruby project's RBS types and its code disagree, on the typing Steep infers.
6
+
7
+ - 25 rules that port typescript-eslint's type-aware rules, and UntypedCall, which is off by default. `typegap --rules` lists them with the rule each follows.
8
+ - `typegap [--json] [--only RULES] [--except RULES] [--root DIR] [PATH...]` prints one finding per line, or one JSON object per finding, and exits 1 when it finds one.
9
+ - The rules stay silent on a value from `Hash#[]`, `Array#first`, and other calls RBS core types as never nil, and on an instance variable, since each can be nil whatever its type says.
10
+ - Steep's unreachable-branch hint and deprecation warning are reported as UnreachableBranch and DeprecatedReference, except a branch decided by one of those values.
11
+ - Steep 2.1 on Ruby 3.3 or later.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 meganemura
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.ja.md ADDED
@@ -0,0 +1,65 @@
1
+ # typegap
2
+
3
+ typegap は、Ruby プロジェクトの RBS の型とコードが食い違っている場所を見つけます。
4
+
5
+ Steep は型を破るコードを報告します。
6
+ typegap は、型から見て要らない、ありえない、使い方を誤りやすいコードを報告します。
7
+ たとえば、型が nil にならないと言っている値への `&.`、union の一部を取りこぼした `case`、比べられない要素の `sort` です。
8
+ どのルールも [typescript-eslint](https://typescript-eslint.io/rules/) の型を使うルールを移したもので、型は自分で推論せず Steep が推論したものを読みます。
9
+
10
+ RBS で型を書いたコードでは、見つかるものの多くは死んだコードではなく、型とコードのすき間です。
11
+ `x` が nil にならない型なので `x&.name` が報告されたとき、要らないのが `&.` なのか、型が言いすぎなのかは分かりません。
12
+ どちらを直すかは読む人が決めます。
13
+
14
+ ## はじめかた
15
+
16
+ Steep で型検査しているプロジェクトに typegap を足します。
17
+
18
+ ```ruby
19
+ # Gemfile
20
+ gem "typegap", require: false
21
+ ```
22
+
23
+ `Steepfile` のある場所で動かします。
24
+
25
+ ```console
26
+ $ bundle exec typegap
27
+ lib/shop.rb:28:5: UnnecessarySafeNavigation: `name` is `::String`, never nil, so `&.` is not needed
28
+ lib/shop.rb:43:5: CaseExhaustiveness: `status` is `(:open | :closed)`, but no `when` handles `:closed` and there is no `else`
29
+ lib/shop.rb:52:5: SortWithoutComparable: `::Point` has only Object#<=>, so `sort` raises ArgumentError. Pass a block or `sort_by`
30
+ 3 findings
31
+ ```
32
+
33
+ すき間が見つかると終了コード 1、なければ 0、動かせないときは 2 で終わります。
34
+ CI では `steep check` のあとに動かせます。
35
+
36
+ ```console
37
+ $ bundle exec typegap --json # 1 件ずつ JSON で出す
38
+ $ bundle exec typegap lib/shop.rb # この Ruby ファイルだけ見る(シグネチャのファイルは見ない)
39
+ $ bundle exec typegap --only CaseExhaustiveness,SortWithoutComparable
40
+ $ bundle exec typegap --except UnusedResult
41
+ $ bundle exec typegap --rules # 全ルールと、元にした typescript-eslint のルール
42
+ ```
43
+
44
+ ## ルール
45
+
46
+ ルールの一覧は [README.md](README.md#rules) の表にあります。
47
+ UntypedCall だけは既定で止めています。
48
+ 多くのプロジェクトでは件数が多すぎて一覧として読めないので、型がどこで途切れているかを見たいときに `--only UntypedCall` で動かします。
49
+
50
+ ## typegap が信じないもの
51
+
52
+ RBS の core は、nil を返すことがあるのに nil にならない型をつけているメソッドがあります。
53
+ たとえば、ない鍵を引いた `Hash#[]` や、空の配列の `Array#first` です。
54
+ インスタンス変数も、代入される前は型にかかわらず nil です。
55
+ ここで型を信じると、コードを守っている nil の確かめを報告してしまうので、typegap はこれらの値については何も言いません。
56
+ `untyped`、型変数、`self`、Steep が展開しなかった別名についても何も言いません。
57
+
58
+ ## 必要なもの
59
+
60
+ Ruby 3.3 以降と Steep 2.1 です。
61
+ typegap は公開 API ではない Steep の型検査サービスを読むので、typegap の各バージョンは Steep のマイナーバージョンを 1 つだけ受け付けます。
62
+
63
+ ## ライセンス
64
+
65
+ MIT です。[LICENSE](LICENSE) を見てください。
data/README.md ADDED
@@ -0,0 +1,93 @@
1
+ # typegap
2
+
3
+ typegap finds the places where a Ruby project's RBS types and its code disagree.
4
+
5
+ Steep reports code that breaks its types.
6
+ typegap reports code that its types make unnecessary, impossible, or easy to misuse: a `&.` on a value the type says is never nil, a `case` that misses a member of a union, a `sort` on elements that cannot compare.
7
+ Each rule ports a type-aware rule of [typescript-eslint](https://typescript-eslint.io/rules/), and reads the types Steep infers instead of inferring its own.
8
+
9
+ In a codebase typed with RBS, most findings are a gap between the type and the code, not dead code.
10
+ When `x&.name` is reported because `x` is typed as never nil, either the `&.` is not needed or the type says too much.
11
+ The finding does not say which; the reader decides.
12
+
13
+ ## Getting started
14
+
15
+ Add typegap to a project that type checks with Steep:
16
+
17
+ ```ruby
18
+ # Gemfile
19
+ gem "typegap", require: false
20
+ ```
21
+
22
+ Run it where the `Steepfile` is:
23
+
24
+ ```console
25
+ $ bundle exec typegap
26
+ lib/shop.rb:28:5: UnnecessarySafeNavigation: `name` is `::String`, never nil, so `&.` is not needed
27
+ lib/shop.rb:43:5: CaseExhaustiveness: `status` is `(:open | :closed)`, but no `when` handles `:closed` and there is no `else`
28
+ lib/shop.rb:52:5: SortWithoutComparable: `::Point` has only Object#<=>, so `sort` raises ArgumentError. Pass a block or `sort_by`
29
+ 3 findings
30
+ ```
31
+
32
+ typegap exits 1 when it finds a gap, 0 when it finds none, and 2 when it cannot run.
33
+ A CI job can run it after `steep check`.
34
+
35
+ ```console
36
+ $ bundle exec typegap --json # one JSON object per finding
37
+ $ bundle exec typegap lib/shop.rb # only these Ruby files (signature files are skipped)
38
+ $ bundle exec typegap --only CaseExhaustiveness,SortWithoutComparable
39
+ $ bundle exec typegap --except UnusedResult
40
+ $ bundle exec typegap --rules # every rule and the typescript-eslint rule it follows
41
+ ```
42
+
43
+ ## Rules
44
+
45
+ | Rule | Reports | Follows |
46
+ | --- | --- | --- |
47
+ | UnnecessarySafeNavigation | `&.` on a value whose type has no nil | no-unnecessary-condition |
48
+ | UnnecessaryNilCheck | `nil?`, `== nil` on a value whose type has no nil | no-unnecessary-condition |
49
+ | AlwaysTruthyCondition | a condition whose type is never nil or false | strict-boolean-expressions |
50
+ | UnnecessaryDefault | `x \|\| default` where `x` is never nil or false | no-unnecessary-condition |
51
+ | OrReplacesFalse | `x \|\| default` where `x` can be false, which `\|\|` replaces too | prefer-nullish-coalescing |
52
+ | UnnecessaryTypeCheck | `is_a?`, `kind_of?`, `Class === x`, `respond_to?` the type already answers | no-unnecessary-condition |
53
+ | UnnecessaryBooleanCompare | `== true` on a `bool` | no-unnecessary-boolean-literal-compare |
54
+ | UnnecessaryConversion | `.to_s`, `"#{x}"`, `Integer(x)` on a value of that class | no-unnecessary-type-conversion |
55
+ | RestrictInterpolation | interpolating nil, a collection, or an object with no `to_s` of its own | restrict-template-expressions |
56
+ | CaseExhaustiveness | a `case` on a union of literals or classes that misses a member and has no `else` | switch-exhaustiveness-check |
57
+ | ImpossibleLiteralComparison | `==` against a literal the type cannot hold | no-unsafe-enum-comparison |
58
+ | UnusedResult | `strip`, `map`, `sort` and other copies whose result is dropped | no-floating-promises |
59
+ | VoidValueUsed | using the value of a method typed `void` | no-confusing-void-expression |
60
+ | UnnecessaryTypeAssertion | a `#:` assertion that repeats the inferred type | no-unnecessary-type-assertion |
61
+ | NilDroppingAssertion | a `#:` assertion that removes nil without a check | no-unsafe-type-assertion |
62
+ | SortWithoutComparable | `sort`, `min`, `max` on elements with no `<=>` among them | require-array-sort-compare |
63
+ | PreferFind | `select { }.first` | prefer-find |
64
+ | MisusedSplat | `*` on a Hash | no-misused-spread |
65
+ | PredicateReturnType | a `?` method that does not return `bool` | naming-convention |
66
+ | PreferReturnSelfType | a method that returns `self` typed as its class | prefer-return-this-type |
67
+ | UnreachableBranch | Steep's own unreachable-branch hint, which `steep check` hides by default | no-unnecessary-condition |
68
+ | DeprecatedReference | a call to a method marked `%a{deprecated}` | no-deprecated |
69
+ | RedundantTypeConstituents | `String \| untyped`, `String \| String`, `bool \| true`, `String??` in a signature | no-redundant-type-constituents |
70
+ | UnnecessaryTypeParameter | a method type parameter used once | no-unnecessary-type-parameters |
71
+ | GetterSetterMismatch | a getter and a setter of the same name with different types | related-getter-setter-pairs |
72
+ | UntypedCall (off by default) | each call on `untyped` | no-unsafe-call |
73
+
74
+ UntypedCall reports too much to read as a list in most projects.
75
+ Run it with `--only UntypedCall` to see where the types run out.
76
+
77
+ ## What typegap distrusts
78
+
79
+ RBS core types some methods as never nil although they return nil: `Hash#[]` on a missing key, `Array#first` on an empty array.
80
+ An instance variable is nil before it is set, whatever its type says.
81
+ typegap stays silent on a value from these, because trusting the type there would report the very nil check that keeps the code safe.
82
+ It also stays silent on `untyped`, a type variable, `self`, and an alias Steep did not expand.
83
+
84
+ ## Requirements
85
+
86
+ Ruby 3.3 or later, and Steep 2.1.
87
+ typegap reads Steep's type check service, which is not a public API, so each typegap version allows one minor version of Steep.
88
+
89
+ ## License
90
+
91
+ MIT. See [LICENSE](LICENSE).
92
+
93
+ [Japanese](README.ja.md)
data/exe/typegap ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "typegap"
5
+
6
+ exit Typegap::CLI.new.run(ARGV)
@@ -0,0 +1,70 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Typegap
5
+ # The `typegap` command. It prints one finding per line, or one JSON object
6
+ # per line with `--json`, and exits 1 when there is a finding, so a CI job
7
+ # can run it as is.
8
+ class CLI
9
+ USAGE = "Usage: typegap [--json] [--only RULE,...] [--except RULE,...] [--root DIR] [PATH...]" #: String
10
+
11
+ # @rbs out: IO
12
+ # @rbs err: IO
13
+ def initialize(out: $stdout, err: $stderr) #: void
14
+ @out = out
15
+ @err = err
16
+ end
17
+
18
+ # 0 with no finding, 1 with findings, 2 when the command cannot run.
19
+ # @rbs argv: Array[String]
20
+ #: (Array[String]) -> Integer
21
+ def run(argv)
22
+ options = parse(argv.dup)
23
+ return 0 if options[:done]
24
+
25
+ rules = Rules.select(only: options[:only], except: options[:except])
26
+ findings = Typegap.run(root: options[:root], paths: options[:paths], rules: rules)
27
+ report(findings, json: options[:json])
28
+ findings.empty? ? 0 : 1
29
+ rescue OptionParser::ParseError, ArgumentError => e
30
+ @err.puts "typegap: #{e.message}"
31
+ @err.puts USAGE
32
+ 2
33
+ end
34
+
35
+ private
36
+
37
+ # @rbs argv: Array[String]
38
+ #: (Array[String]) -> Hash[Symbol, untyped]
39
+ def parse(argv)
40
+ options = { json: false, only: nil, except: [], root: Dir.pwd, done: false } #: Hash[Symbol, untyped]
41
+ parser = OptionParser.new(USAGE)
42
+ parser.on("--json", "Print one JSON object per finding") { options[:json] = true }
43
+ parser.on("--only RULES", Array, "Run only these rules (comma separated)") { options[:only] = _1 }
44
+ parser.on("--except RULES", Array, "Skip these rules (comma separated)") { options[:except] = _1 }
45
+ parser.on("--root DIR", "The directory that holds the Steepfile (default: .)") { options[:root] = _1 }
46
+ parser.on("--rules", "List the rules and exit") do
47
+ Rules::ALL.each { @out.puts "#{_1.name}#{_1.default ? "" : " (off by default)"}: follows #{_1.follows}" }
48
+ options[:done] = true
49
+ end
50
+ parser.on("--version", "Print the version and exit") do
51
+ @out.puts VERSION
52
+ options[:done] = true
53
+ end
54
+ parser.on("-h", "--help", "Print this help and exit") do
55
+ @out.puts parser.help
56
+ options[:done] = true
57
+ end
58
+ options[:paths] = parser.parse(argv)
59
+ options
60
+ end
61
+
62
+ # @rbs findings: Array[Finding]
63
+ # @rbs json: bool
64
+ #: (Array[Finding], json: bool) -> void
65
+ def report(findings, json:)
66
+ findings.each { @out.puts(json ? JSON.generate(_1.to_h) : _1.to_s) }
67
+ @err.puts "#{findings.size} finding#{findings.size == 1 ? "" : "s"}" unless json
68
+ end
69
+ end
70
+ end
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Typegap
5
+ # One place where the types and the code disagree, or where the code does
6
+ # what the types make unnecessary or impossible. It carries no severity: the
7
+ # rule name says what kind of gap it is, and the reader decides whether the
8
+ # code or the type is wrong.
9
+ class Finding
10
+ attr_reader :path #: String
11
+ attr_reader :line #: Integer
12
+ attr_reader :column #: Integer
13
+ attr_reader :rule #: String
14
+ attr_reader :message #: String
15
+
16
+ # @rbs path: String
17
+ # @rbs line: Integer
18
+ # @rbs column: Integer
19
+ # @rbs rule: String
20
+ # @rbs message: String
21
+ def initialize(path:, line:, column:, rule:, message:) #: void
22
+ @path = path
23
+ @line = line
24
+ @column = column
25
+ @rule = rule
26
+ @message = message
27
+ end
28
+
29
+ #: () -> Array[String | Integer]
30
+ def sort_key = [path, line, column, rule]
31
+
32
+ #: () -> Hash[Symbol, String | Integer]
33
+ def to_h = { path: path, line: line, column: column, rule: rule, message: message }
34
+
35
+ #: () -> String
36
+ def to_s = "#{path}:#{line}:#{column}: #{rule}: #{message}"
37
+ end
38
+ end
@@ -0,0 +1,80 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Typegap
5
+ # Type checks a project the way `steep check` does, from its Steepfile, and
6
+ # hands each Ruby file's typing to a block. It reads Steep's own service
7
+ # instead of re-implementing inference, so a finding means what Steep
8
+ # inferred. That service is not a public API, so this file is the one place
9
+ # that touches it.
10
+ class Project
11
+ attr_reader :root #: String
12
+
13
+ # @rbs root: String
14
+ def initialize(root) #: void
15
+ @root = File.expand_path(root)
16
+ steepfile = File.join(@root, "Steepfile")
17
+ raise ArgumentError, "no Steepfile in #{@root}" unless File.file?(steepfile)
18
+
19
+ @steep = Steep::Project.new(steepfile_path: Pathname(steepfile))
20
+ Steep::Project::DSL.parse(@steep, File.read(steepfile), filename: steepfile)
21
+ @service = Steep::Services::TypeCheckService.new(project: @steep)
22
+ @loaded = false #: bool
23
+ end
24
+
25
+ # Each Ruby source file of a target, relative to the root, with its typing
26
+ # and the RBS definition builder of its target. A file Steep could not
27
+ # type (a syntax error) is skipped: `steep check` reports it.
28
+ #
29
+ # @rbs paths: Array[String]
30
+ # @rbs &block: (String, untyped, untyped) -> void
31
+ #: (Array[String]) { (String, untyped, untyped) -> void } -> void
32
+ def each_typing(paths = [], &block)
33
+ load
34
+ wanted = paths.map { relative(_1) }
35
+ source_paths.each do |path|
36
+ next unless wanted.empty? || wanted.include?(path.to_s)
37
+
38
+ target = @steep.target_for_source_path(path) or next
39
+ @service.typecheck_source(path: path, target: target)
40
+ typing = @service.source_files.fetch(path).typing or next
41
+ block.call(path.to_s, typing, @service.signature_services.fetch(target.name).latest_builder)
42
+ end
43
+ end
44
+
45
+ # The signature files under sig/, which hold this project's own types.
46
+ # Stubs of other gems (sig-deps/ and the like) are not this project's to fix.
47
+ #: () -> Array[String]
48
+ def own_signature_paths
49
+ load
50
+ @changes.keys.map(&:to_s).select { _1.end_with?(".rbs") && _1.start_with?("sig/") }.sort
51
+ end
52
+
53
+ private
54
+
55
+ #: () -> void
56
+ def load
57
+ return if @loaded
58
+
59
+ @changes = {} #: Hash[Pathname, Array[untyped]]
60
+ Dir.glob("**/*.{rb,rbs}", base: @root).each do |file|
61
+ path = Pathname(file)
62
+ next unless @steep.targets.any? { _1.possible_source_file?(path) || _1.possible_signature_file?(path) }
63
+
64
+ @changes[path] = [Steep::Services::ContentChange.string(File.read(File.join(@root, file)))]
65
+ end
66
+ @service.update(changes: @changes)
67
+ @loaded = true
68
+ end
69
+
70
+ #: () -> Array[Pathname]
71
+ def source_paths = @changes.keys.select { _1.extname == ".rb" }.sort
72
+
73
+ # @rbs path: String
74
+ #: (String) -> String
75
+ def relative(path)
76
+ full = File.expand_path(path, Dir.pwd)
77
+ full.start_with?("#{@root}/") ? full.delete_prefix("#{@root}/") : path
78
+ end
79
+ end
80
+ end
@@ -0,0 +1,56 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Typegap
5
+ # The rules, each with the typescript-eslint rule it ports. A rule that is
6
+ # off by default reports too much to read as a list: it is a map to read
7
+ # with `--only`.
8
+ module Rules
9
+ Rule = Data.define(:name, :follows, :default)
10
+
11
+ ALL = [
12
+ Rule.new("UnnecessarySafeNavigation", "no-unnecessary-condition", true),
13
+ Rule.new("UnnecessaryNilCheck", "no-unnecessary-condition", true),
14
+ Rule.new("AlwaysTruthyCondition", "strict-boolean-expressions, no-unnecessary-condition", true),
15
+ Rule.new("UnnecessaryDefault", "no-unnecessary-condition (??)", true),
16
+ Rule.new("OrReplacesFalse", "prefer-nullish-coalescing", true),
17
+ Rule.new("UnnecessaryTypeCheck", "no-unnecessary-condition", true),
18
+ Rule.new("UnnecessaryBooleanCompare", "no-unnecessary-boolean-literal-compare", true),
19
+ Rule.new("UnnecessaryConversion", "no-unnecessary-template-expression, no-unnecessary-type-conversion", true),
20
+ Rule.new("RestrictInterpolation", "restrict-template-expressions, no-base-to-string", true),
21
+ Rule.new("CaseExhaustiveness", "switch-exhaustiveness-check", true),
22
+ Rule.new("ImpossibleLiteralComparison", "no-unsafe-enum-comparison", true),
23
+ Rule.new("UnusedResult", "no-floating-promises", true),
24
+ Rule.new("VoidValueUsed", "no-confusing-void-expression", true),
25
+ Rule.new("UnnecessaryTypeAssertion", "no-unnecessary-type-assertion", true),
26
+ Rule.new("NilDroppingAssertion", "no-unsafe-type-assertion, non-nullable-type-assertion-style", true),
27
+ Rule.new("SortWithoutComparable", "require-array-sort-compare", true),
28
+ Rule.new("PreferFind", "prefer-find", true),
29
+ Rule.new("MisusedSplat", "no-misused-spread", true),
30
+ Rule.new("PredicateReturnType", "naming-convention", true),
31
+ Rule.new("PreferReturnSelfType", "prefer-return-this-type", true),
32
+ Rule.new("UnreachableBranch", "no-unnecessary-condition (Steep's own diagnostic)", true),
33
+ Rule.new("DeprecatedReference", "no-deprecated (Steep's own diagnostic)", true),
34
+ Rule.new("RedundantTypeConstituents", "no-redundant-type-constituents, no-duplicate-type-constituents", true),
35
+ Rule.new("UnnecessaryTypeParameter", "no-unnecessary-type-parameters", true),
36
+ Rule.new("GetterSetterMismatch", "related-getter-setter-pairs", true),
37
+ Rule.new("UntypedCall", "no-unsafe-call, no-unsafe-member-access", false)
38
+ ].freeze #: Array[Rule]
39
+
40
+ NAMES = ALL.map(&:name).freeze #: Array[String]
41
+
42
+ # The rule names that run: `only` when given, else every default rule,
43
+ # less `except`. An unknown name raises, so a typo does not silently run
44
+ # nothing.
45
+ #
46
+ # @rbs only: Array[String]?
47
+ # @rbs except: Array[String]
48
+ #: (only: Array[String]?, except: Array[String]) -> Array[String]
49
+ def self.select(only:, except:)
50
+ unknown = (only || []) + except - NAMES
51
+ raise ArgumentError, "unknown rule: #{unknown.join(", ")} (rules: #{NAMES.join(", ")})" unless unknown.empty?
52
+
53
+ (only || ALL.select(&:default).map(&:name)) - except
54
+ end
55
+ end
56
+ end
@@ -0,0 +1,166 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module Typegap
5
+ # The rules that read one signature file, as written or as rbs-inline
6
+ # writes it. They report a type that says less than it seems to: a union
7
+ # that `untyped` swallows, a type parameter that ties nothing together, a
8
+ # getter and a setter that disagree.
9
+ #
10
+ # It reads the file's declarations only. It does not resolve names, so it
11
+ # needs no environment.
12
+ class SignatureCheck
13
+ # @rbs path: String
14
+ # @rbs text: String
15
+ # @rbs rules: Array[String]
16
+ def initialize(path, text, rules) #: void
17
+ @path = path
18
+ @text = text
19
+ @rules = rules
20
+ @found = [] #: Array[Finding]
21
+ end
22
+
23
+ # A file RBS cannot parse has no findings: `steep check` reports it.
24
+ #: () -> Array[Finding]
25
+ def findings
26
+ _, _, decls = RBS::Parser.parse_signature(@text)
27
+ decls.each { decl(_1) }
28
+ @found
29
+ rescue RBS::ParsingError
30
+ []
31
+ end
32
+
33
+ private
34
+
35
+ # @rbs loc: untyped
36
+ # @rbs rule: String
37
+ # @rbs message: String
38
+ #: (untyped, String, String) -> void
39
+ def add(loc, rule, message)
40
+ return unless loc && @rules.include?(rule)
41
+
42
+ @found << Finding.new(path: @path, line: loc.start_line, column: loc.start_column + 1, rule: rule, message: message)
43
+ end
44
+
45
+ # @rbs decl: untyped
46
+ #: (untyped) -> void
47
+ def decl(decl)
48
+ case decl
49
+ when RBS::AST::Declarations::Class, RBS::AST::Declarations::Module, RBS::AST::Declarations::Interface
50
+ decl.members.each { member(_1) }
51
+ getter_setter(decl)
52
+ decl.members.each { decl(_1) if _1.is_a?(RBS::AST::Declarations::Base) }
53
+ when RBS::AST::Declarations::TypeAlias, RBS::AST::Declarations::Constant, RBS::AST::Declarations::Global
54
+ each_type(decl.type)
55
+ end
56
+ end
57
+
58
+ # @rbs member: untyped
59
+ #: (untyped) -> void
60
+ def member(member)
61
+ case member
62
+ when RBS::AST::Members::MethodDefinition
63
+ member.overloads.each do |overload|
64
+ method_type = overload.method_type
65
+ # MethodType#each_type walks the block's types too.
66
+ method_type.each_type { each_type(_1) }
67
+ type_params(member, method_type)
68
+ end
69
+ when RBS::AST::Members::Attribute, RBS::AST::Members::InstanceVariable,
70
+ RBS::AST::Members::ClassInstanceVariable, RBS::AST::Members::ClassVariable
71
+ each_type(member.type)
72
+ when RBS::AST::Members::Include, RBS::AST::Members::Extend, RBS::AST::Members::Prepend
73
+ member.args.each { each_type(_1) }
74
+ end
75
+ end
76
+
77
+ # @rbs type: untyped
78
+ #: (untyped) -> void
79
+ def each_type(type)
80
+ redundant(type)
81
+ type.each_type { each_type(_1) } if type.respond_to?(:each_type)
82
+ end
83
+
84
+ # @rbs type: untyped
85
+ #: (untyped) -> void
86
+ def redundant(type)
87
+ case type
88
+ when RBS::Types::Union
89
+ types = type.types
90
+ if types.any? { _1.is_a?(RBS::Types::Bases::Any) }
91
+ add(type.location, "RedundantTypeConstituents", "`#{type}` contains `untyped`, so the whole union is untyped")
92
+ end
93
+ dups = types.map(&:to_s).tally.select { _2 > 1 }.keys
94
+ add(type.location, "RedundantTypeConstituents", "`#{type}` lists #{dups.join(", ")} twice") if dups.any?
95
+ if types.any? { _1.is_a?(RBS::Types::Bases::Bool) } &&
96
+ types.any? { _1.is_a?(RBS::Types::Literal) && [true, false].include?(_1.literal) }
97
+ add(type.location, "RedundantTypeConstituents", "`#{type}` has `bool` and a true or false literal")
98
+ end
99
+ when RBS::Types::Optional
100
+ add(type.location, "RedundantTypeConstituents", "`#{type}`: the inner type already includes nil, so `?` adds nothing") if nil_inside?(type.type)
101
+ end
102
+ end
103
+
104
+ # @rbs type: untyped
105
+ #: (untyped) -> bool
106
+ def nil_inside?(type)
107
+ case type
108
+ when RBS::Types::Optional, RBS::Types::Bases::Any, RBS::Types::Bases::Nil then true
109
+ when RBS::Types::Union then type.types.any? { _1.is_a?(RBS::Types::Bases::Nil) || _1.is_a?(RBS::Types::Optional) }
110
+ else false
111
+ end
112
+ end
113
+
114
+ # A type parameter used once relates nothing: `[T] (T) -> void` takes
115
+ # anything, as `(untyped) -> void` or `(top) -> void` does.
116
+ # @rbs member: untyped
117
+ # @rbs method_type: untyped
118
+ #: (untyped, untyped) -> void
119
+ def type_params(member, method_type)
120
+ method_type.type_params.each do |param|
121
+ uses = 0
122
+ count = lambda do |t|
123
+ uses += 1 if t.is_a?(RBS::Types::Variable) && t.name == param.name
124
+ t.each_type { count.(_1) } if t.respond_to?(:each_type)
125
+ end
126
+ method_type.each_type { count.(_1) }
127
+ method_type.type_params.each { count.(_1.upper_bound) if _1.upper_bound }
128
+ next if uses > 1
129
+
130
+ add(member.location, "UnnecessaryTypeParameter",
131
+ "`#{member.name}` declares `[#{param.name}]` but uses it #{uses} time(s); it ties nothing together, so `untyped` or `top` says the same")
132
+ end
133
+ end
134
+
135
+ # @rbs decl: untyped
136
+ #: (untyped) -> void
137
+ def getter_setter(decl)
138
+ getters = {} #: Hash[Symbol, String]
139
+ setters = {} #: Hash[Symbol, [String, untyped]]
140
+ decl.members.each do |m|
141
+ case m
142
+ when RBS::AST::Members::AttrReader then getters[m.name] = m.type.to_s
143
+ when RBS::AST::Members::AttrWriter then setters[m.name] = [m.type.to_s, m]
144
+ when RBS::AST::Members::AttrAccessor then next
145
+ when RBS::AST::Members::MethodDefinition
146
+ next unless m.kind == :instance && m.overloads.size == 1
147
+
148
+ fn = m.overloads[0].method_type.type
149
+ next unless fn.is_a?(RBS::Types::Function)
150
+
151
+ if m.name.end_with?("=") && fn.required_positionals.size == 1
152
+ setters[m.name.to_s.chomp("=").to_sym] = [fn.required_positionals[0].type.to_s, m]
153
+ elsif fn.required_positionals.empty? && fn.optional_positionals.empty?
154
+ getters[m.name] = fn.return_type.to_s
155
+ end
156
+ end
157
+ end
158
+ setters.each do |name, (type, m)|
159
+ getter = getters[name] or next
160
+ next if getter == type
161
+
162
+ add(m.location, "GetterSetterMismatch", "`#{name}` returns `#{getter}` but `#{name}=` takes `#{type}`")
163
+ end
164
+ end
165
+ end
166
+ end