protostar 0.1.0.beta1

data/lib/protostar/lint/naming.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    # Case conversions as buf's naming rules apply them
+    module Naming
+      module_function
+
+      # @return [Array<String>] the words of a name in any case: "HTTPServer_v2" is HTTP, Server, v2
+      def words(name)
+        name.split(/_+/).flat_map { |part| part.scan(/[A-Z]+(?![a-z])|[A-Z]?[a-z]+|[0-9]+[a-z]*|[A-Z]+/) }
+          .reject(&:empty?)
+      end
+
+      # @return [String] "fooBar" as "foo_bar"
+      def lower_snake(name)
+        joined(name).downcase
+      end
+
+      # @return [String] "fooBar" as "FOO_BAR"
+      def upper_snake(name)
+        joined(name).upcase
+      end
+
+      # @return [String] "foo_bar" as "FooBar"
+      def pascal(name)
+        words(name).map { |w| w[0].upcase + w[1..] }.join
+      end
+
+      def lower_snake?(name)
+        name.match?(/\A[a-z][a-z0-9]*(?:_[a-z0-9]+)*\z/)
+      end
+
+      def upper_snake?(name)
+        name.match?(/\A[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*\z/)
+      end
+
+      def pascal?(name)
+        name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
+      end
+
+      # Words joined by underscores, a digit run kept on the word before it
+      def joined(name)
+        out = +""
+        words(name).each do |word|
+          out << "_" unless out.empty? || word.match?(/\A[0-9]/)
+          out << word
+        end
+        out
+      end
+      private_class_method :joined
+    end
+  end
+end

data/lib/protostar/lint/rule.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    # The base of every lint rule. A rule is a class under {Rules} named after
+    # its id (`FIELD_NOT_REQUIRED` is `Rules::FieldNotRequired`) with two
+    # constants, `REASON` (one line) and `EXPLANATION` (why, an example, the
+    # fix), and a {#check} that calls {#report} for every problem it finds.
+    #
+    #   class Rules::PackageDefined < Rule
+    #     REASON = "A file without a package puts its types in the global namespace."
+    #     EXPLANATION = "..."
+    #
+    #     def check
+    #       report(context.ast, :other, "file has no package") if context.file.package.empty?
+    #     end
+    #   end
+    #
+    # Rules read the compiled {Schema::File}, the AST positions and the source
+    # info through {Context}; none parses anything.
+    class Rule
+      # @return [String] e.g. "FIELD_NOT_REQUIRED"
+      def self.id
+        name.split("::").last.gsub(/(?<=[a-z0-9])(?=[A-Z])/, "_").upcase
+      end
+
+      # @return [String] e.g. "W0101"
+      def self.code
+        RULES.fetch(id)[0]
+      end
+
+      # @return [Symbol] the smallest set the rule is in
+      def self.tier
+        RULES.fetch(id)[1]
+      end
+
+      # @return [Symbol]
+      def self.category
+        RULES.fetch(id)[2]
+      end
+
+      # @return [String]
+      def self.reason
+        const_get(:REASON)
+      end
+
+      # @return [String]
+      def self.explanation
+        const_get(:EXPLANATION)
+      end
+
+      # The compiler codes whose warnings the rule reports as its own, so they
+      # are not printed twice
+      CLAIMS = [].freeze
+
+      # @return [Context]
+      attr_reader :context
+      # @return [Array<Compiler::Diagnostic>] what {#report} collected
+      attr_reader :diagnostics
+
+      # @param context [Context]
+      def initialize(context)
+        @context = context
+        @diagnostics = []
+      end
+
+      # Finds the rule's problems in {#context}
+      def check
+        raise NotImplementedError, "#{self.class} must define #check"
+      end
+
+      private
+
+      # Records a problem at a node's recorded position
+      # @param node [Compiler::AST::Node]
+      # @param kind [Symbol] the position kind: :name, :number, :type, ...
+      # @param message [String] the headline, lower case, no full stop
+      # @param label [String, nil] under the span
+      # @param help [String, nil] the concrete fix in words
+      # @param fix [Diagnostics::Fix, nil] when the fix is mechanical and safe
+      # @param related [Array<Array(Compiler::AST::Node, Symbol, String)>] other places
+      # @param span [Diagnostics::Span, nil] instead of the node's position
+      def report(node, kind, message, label: nil, help: nil, fix: nil, related: [], span: nil)
+        span ||= @context.span(node, kind, label: label)
+        span = span.with_label(label) if span && label && span.label.nil?
+        spans = span ? [span] : []
+        related.each do |other, other_kind, other_label|
+          extra = @context.span(other, other_kind, label: other_label, primary: false)
+          spans << extra if extra
+        end
+        add(message, spans, help: help, fix: fix)
+      end
+
+      # Records a problem at a span, or at none
+      def add(message, spans, help: nil, fix: nil)
+        first = spans.first
+        note = "rule #{self.class.id} (#{self.class.tier} set)"
+        @diagnostics << Compiler::Diagnostic.new(@context.name, first&.line, first&.column, message, :warning,
+          path: @context.path, spans: spans, code: self.class.code, title: message, help: [help].compact,
+          notes: [note], fix: fix, rule: self.class.id)
+      end
+
+      # @param numbers [Array<Integer>] sorted
+      # @return [String] "2, 4 to 6"
+      def numbers_text(numbers)
+        numbers.slice_when { |a, b| b != a + 1 }.map { |run| (run.size == 1) ? run[0].to_s : "#{run[0]} to #{run[-1]}" }.join(", ")
+      end
+
+      # A rename of the identifier under a span, offered only when the old
+      # name appears once in the file (no reference, option or comment would
+      # be left behind) and the new one not at all
+      # @return [Diagnostics::Fix, nil]
+      def rename(span, from, to)
+        return nil unless span && @context.renamable?(from, to)
+        Diagnostics::Fix.new("rename `#{from}` to `#{to}`",
+          [Diagnostics::Edit.new(span.line, span.column, span.end_line, span.end_column, to)])
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/comment_enum.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # COMMENT_ENUM: A enum without a comment
+      class CommentEnum < Rule
+        REASON = "Enums are API; the comment above one is its documentation, in the .proto and in generated code."
+        EXPLANATION = <<~TEXT
+          Comments in a `.proto` are carried into generated code and API documentation. A enum without one
+          leaves every reader to guess what it means and what values it takes. A comment on the line above counts,
+          and so does one after the opening brace.
+
+              enum Status {
+                STATUS_UNSPECIFIED = 0;
+              }
+
+          Fix: write what the enum is for in a `//` comment above it.
+        TEXT
+
+        def check
+          context.each(:enum) do |node, element|
+            next if context.comment(node)
+            report(node, :name, "enum `#{element.name}` has no comment", label: "undocumented",
+              help: "say what it is for in a `//` comment above it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/comment_enum_value.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # COMMENT_ENUM_VALUE: A enum value without a comment
+      class CommentEnumValue < Rule
+        REASON = "Enum values are API; the comment above one is its documentation, in the .proto and in generated code."
+        EXPLANATION = <<~TEXT
+          Comments in a `.proto` are carried into generated code and API documentation. A enum value without one
+          leaves every reader to guess what it means and what values it takes. A comment on the line above counts,
+          and so does one after the declaration on the same line.
+
+              enum Status {
+                STATUS_UNSPECIFIED = 0;
+                STATUS_ACTIVE = 1;
+              }
+
+          Fix: write what the enum value is for in a `//` comment above it.
+        TEXT
+
+        def check
+          context.each(:enum_value) do |node, element|
+            next if context.comment(node)
+            report(node, :name, "enum value `#{element.name}` has no comment", label: "undocumented",
+              help: "say what it is for in a `//` comment above it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/comment_field.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # COMMENT_FIELD: A field without a comment
+      class CommentField < Rule
+        REASON = "Fields are API; the comment above one is its documentation, in the .proto and in generated code."
+        EXPLANATION = <<~TEXT
+          Comments in a `.proto` are carried into generated code and API documentation. A field without one
+          leaves every reader to guess what it means and what values it takes. A comment on the line above counts,
+          and so does one after the declaration on the same line.
+
+              message User {
+                // Stable across renames; never reused.
+                string id = 1;
+                string name = 2;
+              }
+
+          Fix: write what the field is for in a `//` comment above it.
+        TEXT
+
+        def check
+          context.each(:field) do |node, element|
+            next if context.comment(node)
+            report(node, :name, "field `#{element.name}` has no comment", label: "undocumented",
+              help: "say what it is for in a `//` comment above it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/comment_message.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # COMMENT_MESSAGE: A message without a comment
+      class CommentMessage < Rule
+        REASON = "Messages are API; the comment above one is its documentation, in the .proto and in generated code."
+        EXPLANATION = <<~TEXT
+          Comments in a `.proto` are carried into generated code and API documentation. A message without one
+          leaves every reader to guess what it means and what values it takes. A comment on the line above counts,
+          and so does one after the opening brace.
+
+              message User {
+                string id = 1;
+              }
+
+          Fix: write what the message is for in a `//` comment above it.
+        TEXT
+
+        def check
+          context.each(:message) do |node, element|
+            next if context.comment(node)
+            report(node, :name, "message `#{element.name}` has no comment", label: "undocumented",
+              help: "say what it is for in a `//` comment above it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/comment_rpc.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # COMMENT_RPC: A rpc without a comment
+      class CommentRpc < Rule
+        REASON = "RPCs are API; the comment above one is its documentation, in the .proto and in generated code."
+        EXPLANATION = <<~TEXT
+          Comments in a `.proto` are carried into generated code and API documentation. A rpc without one
+          leaves every reader to guess what it means and what values it takes. A comment on the line above counts,
+          and so does one after the opening brace.
+
+              service UserService {
+                rpc GetUser(GetUserRequest) returns (GetUserResponse);
+              }
+
+          Fix: write what the rpc is for in a `//` comment above it.
+        TEXT
+
+        def check
+          context.each(:method) do |node, element|
+            next if context.comment(node)
+            report(node, :name, "rpc `#{element.name}` has no comment", label: "undocumented",
+              help: "say what it is for in a `//` comment above it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/comment_service.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # COMMENT_SERVICE: A service without a comment
+      class CommentService < Rule
+        REASON = "Services are API; the comment above one is its documentation, in the .proto and in generated code."
+        EXPLANATION = <<~TEXT
+          Comments in a `.proto` are carried into generated code and API documentation. A service without one
+          leaves every reader to guess what it means and what values it takes. A comment on the line above counts,
+          and so does one after the opening brace.
+
+              service UserService {
+                rpc GetUser(GetUserRequest) returns (GetUserResponse);
+              }
+
+          Fix: write what the service is for in a `//` comment above it.
+        TEXT
+
+        def check
+          context.each(:service) do |node, element|
+            next if context.comment(node)
+            report(node, :name, "service `#{element.name}` has no comment", label: "undocumented",
+              help: "say what it is for in a `//` comment above it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/edition_recommended.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # EDITION_RECOMMENDED: A proto2 or proto3 file
+      class EditionRecommended < Rule
+        REASON = "Editions replace proto2 and proto3; new features (and new defaults) only arrive there."
+        EXPLANATION = <<~TEXT
+          Editions express what `syntax` used to fix (presence, enum openness, encodings) as features that can be
+          set per file, message or field. proto2 and proto3 files keep working, but new behaviour is only added to
+          editions. A proto3 file moves to `edition = "2023"` with `option features.field_presence = IMPLICIT;`
+          to keep its semantics.
+
+              syntax = "proto3";
+
+          Fix: move to `edition = "2023";`, setting the features that keep the old semantics (see
+          https://protobuf.dev/editions/overview/).
+        TEXT
+
+        def check
+          syntax = context.file.syntax
+          return if syntax == :editions
+          add("file uses `syntax = \"#{syntax}\"` rather than an edition",
+            [context.span_at(Context::PATHS[:syntax], label: syntax.to_s)].compact,
+            help: "move to `edition = \"2023\";` with the features that keep #{syntax}'s behaviour")
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/enum_first_value_zero.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # ENUM_FIRST_VALUE_ZERO: An enum whose first value is not zero
+      class EnumFirstValueZero < Rule
+        REASON = "Readers fall back to the first value of a closed enum and to zero of an open one; both should be the \"unspecified\" value."
+        EXPLANATION = <<~TEXT
+          proto3 and open enums must start at zero, and protoc enforces it. proto2 enums are closed and may start
+          anywhere, but the first value is still the default of every field of that type, so it ends up meaning
+          "unset" whether you meant it to or not.
+
+              syntax = "proto2";
+              enum Status {
+                ACTIVE = 1;
+                SUSPENDED = 2;
+              }
+
+          Fix: add `STATUS_UNSPECIFIED = 0;` as the first value.
+        TEXT
+
+        def check
+          context.each(:enum) do |node, enum|
+            first = enum.values.first
+            next if first.nil? || first.number.zero?
+            report(node.value[0], :number, "first value `#{first.name}` of `#{enum.name}` is not zero", label: "not 0",
+              help: "add `#{Naming.upper_snake(enum.name)}_UNSPECIFIED = 0;` as the first value")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/enum_pascal_case.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # ENUM_PASCAL_CASE: An enum name that is not PascalCase
+      class EnumPascalCase < Rule
+        REASON = "Enums become types in generated code; PascalCase is what generators expect."
+        EXPLANATION = <<~TEXT
+              enum order_status { ORDER_STATUS_UNSPECIFIED = 0; }
+
+          Fix: `enum OrderStatus`, and update the fields that refer to it.
+        TEXT
+
+        def check
+          context.each(:enum) do |node, enum|
+            next if Naming.pascal?(enum.name)
+            report(node, :name, "enum `#{enum.name}` is not PascalCase", label: "not PascalCase",
+              help: "name it `#{Naming.pascal(enum.name)}` and update what refers to it")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/enum_value_prefix.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # ENUM_VALUE_PREFIX: An enum value not prefixed with its enum's name
+      class EnumValuePrefix < Rule
+        REASON = "Enum values are scoped to the enum's parent, not the enum, so unprefixed names clash across enums."
+        EXPLANATION = <<~TEXT
+          In protobuf (as in C++) enum values are siblings of their enum: `enum Color { RED = 0; }` defines
+          `acme.RED`, and a second enum in the package cannot have a `RED`. Prefixing each value with the enum's name
+          in UPPER_SNAKE_CASE avoids that for good.
+
+              enum Color {
+                UNSPECIFIED = 0;
+                RED = 1;
+              }
+
+          Fix: `COLOR_UNSPECIFIED = 0; COLOR_RED = 1;`. `--fix` renames a value when nothing else in the file
+          mentions it.
+        TEXT
+
+        def check
+          context.each(:enum) do |node, enum|
+            prefix = "#{Naming.upper_snake(enum.name)}_"
+            enum.values.each_with_index do |value, i|
+              next if value.name.start_with?(prefix)
+              wanted = prefix + Naming.upper_snake(value.name)
+              span = context.span(node.value[i], :name)
+              report(node.value[i], :name, "enum value `#{value.name}` is not prefixed with `#{prefix}`", span: span,
+                label: "no `#{prefix}` prefix", help: "name it `#{wanted}`", fix: rename(span, value.name, wanted))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/enum_value_upper_snake_case.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # ENUM_VALUE_UPPER_SNAKE_CASE: An enum value name that is not UPPER_SNAKE_CASE
+      class EnumValueUpperSnakeCase < Rule
+        REASON = "Enum values become constants; UPPER_SNAKE_CASE is the convention in every generator."
+        EXPLANATION = <<~TEXT
+              enum Color { color_unspecified = 0; colorRed = 1; }
+
+          Fix: `COLOR_UNSPECIFIED`, `COLOR_RED`. Renaming is wire-compatible but changes the JSON and text names.
+          `--fix` renames a value when nothing else in the file mentions it.
+        TEXT
+
+        def check
+          context.each(:enum_value) do |node, value|
+            next if Naming.upper_snake?(value.name)
+            wanted = Naming.upper_snake(value.name)
+            span = context.span(node, :name)
+            report(node, :name, "enum value `#{value.name}` is not UPPER_SNAKE_CASE", span: span,
+              label: "not UPPER_SNAKE_CASE", help: "name it `#{wanted}`", fix: rename(span, value.name, wanted))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/enum_zero_value_suffix.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # ENUM_ZERO_VALUE_SUFFIX: An enum whose zero value does not end in `_UNSPECIFIED`
+      class EnumZeroValueSuffix < Rule
+        REASON = "The zero value is what every reader sees for an unset or unknown enum, so it should mean \"unspecified\"."
+        EXPLANATION = <<~TEXT
+          A field that was never set reads as the enum's zero value, and so does, in proto3 and open enums, a number
+          the reader does not know. If zero is a real choice (`RED`), there is no way to tell "red" from "nobody
+          said". Naming it `COLOR_UNSPECIFIED` keeps zero free to mean exactly that.
+
+              enum Color {
+                RED = 0;
+                GREEN = 1;
+              }
+
+          Fix: add `COLOR_UNSPECIFIED = 0;` and renumber, in a new enum; in a released one, rename the zero value
+          to `COLOR_UNSPECIFIED` (the wire format does not change, the JSON and text names do). `--fix` renames it
+          when nothing else in the file mentions the old name.
+        TEXT
+
+        def check
+          context.each(:enum) do |node, enum|
+            index = enum.values.index { |v| v.number.zero? }
+            next unless index
+            value = enum.values[index]
+            next if value.name.end_with?("_UNSPECIFIED")
+            wanted = "#{Naming.upper_snake(enum.name)}_UNSPECIFIED"
+            value_node = node.value[index]
+            span = context.span(value_node, :name)
+            report(value_node, :name, "zero value `#{value.name}` of `#{enum.name}` does not end in `_UNSPECIFIED`",
+              span: span, label: "read for every unset field", help: "name it `#{wanted}`",
+              fix: rename(span, value.name, wanted))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/field_lower_snake_case.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # FIELD_LOWER_SNAKE_CASE: A field name that is not lower_snake_case
+      class FieldLowerSnakeCase < Rule
+        REASON = "Generators derive accessors and JSON names from field names on the assumption they are lower_snake_case."
+        EXPLANATION = <<~TEXT
+          The JSON name of `foo_bar` is `fooBar`, and generated accessors camelCase or PascalCase it as each
+          language wants. A field called `fooBar` or `FooBar` makes those conversions guess, and two such fields can
+          end up with the same JSON name.
+
+              message User {
+                string firstName = 1;
+              }
+
+          Fix: `string first_name = 1;`. Renaming is wire-compatible but changes generated accessors. `--fix`
+          renames the field when nothing else in the file mentions it.
+        TEXT
+
+        def check
+          context.each(:field) do |node, field|
+            next if node.type == :TYPE_GROUP || Naming.lower_snake?(field.name)
+            wanted = Naming.lower_snake(field.name)
+            span = context.span(node, :name)
+            report(node, :name, "field `#{field.name}` is not lower_snake_case", span: span, label: "not lower_snake_case",
+              help: "name it `#{wanted}`", fix: rename(span, field.name, wanted))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/protostar/lint/rules/field_not_required.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Protostar
+  module Lint
+    module Rules
+      # FIELD_NOT_REQUIRED: A proto2 `required` field, or an editions field with `LEGACY_REQUIRED` presence
+      class FieldNotRequired < Rule
+        REASON = "A required field can never be removed or made optional without breaking every reader that still checks it."
+        EXPLANATION = <<~TEXT
+          `required` looks like validation, but it is a promise about every message that will ever be written. A
+          reader built from the schema rejects a message without the field, so the field can never be removed, and
+          making it `optional` breaks every old reader that meets a message without it. Google's own style guide
+          calls required fields harmful, and proto3 dropped them.
+
+              syntax = "proto2";
+              message Order {
+                required string id = 1;
+              }
+
+          Fix: make the field `optional` and check that it is set where the message is used. In editions, drop
+          `features.field_presence = LEGACY_REQUIRED`.
+        TEXT
+
+        def check
+          context.each(:field) do |node, field|
+            next unless field.required?
+            if node.label == :LABEL_REQUIRED
+              report(node, :name, "field `#{field.name}` is required", span: context.span_at(node.path + [4]),
+                label: "required forever", help: "make it `optional` and check that it is set in code")
+            else
+              report(node, :name, "field `#{field.name}` has LEGACY_REQUIRED presence", label: "required forever",
+                help: "remove `features.field_presence = LEGACY_REQUIRED` and check that it is set in code")
+            end
+          end
+        end
+      end
+    end
+  end
+end