specguard-rspec 0.2.1

data/Rakefile

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# The fixtures under spec/fixtures/ are linter *input* that happens to be named
+# `*_spec.rb` — exactly what RSpec's default pattern loads. `.rspec` excludes
+# them, and that is the source of truth for a bare `rspec` run.
+#
+# The rake task has to repeat it. RSpec::Core::RakeTask always puts an explicit
+# `--pattern` on the command line, and a command-line `--pattern` discards the
+# `--exclude-pattern` that came from `.rspec` — so the stock task loads the
+# fixtures as examples and the suite dies with
+# "cannot load such file -- rails_helper". Passing the exclusion on the command
+# line too is what makes the two invocations agree. (Clearing `t.pattern`
+# instead does not work: the task then passes an empty argument and matches
+# nothing.)
+#
+# Keep this in step with `.rspec` — `rake` and `rspec` must select the same
+# files. spec/spec_helper.rb fails the suite loudly if a fixture ever does get
+# loaded as an example.
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = %(--exclude-pattern "spec/fixtures/**/*_spec.rb")
+end
+
+# `rake` with no arguments used to do nothing at all, which made it a useless
+# CI entrypoint. It now means "run the suite".
+task default: %i[spec]

data/bin/specguard-lint

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# specguard-lint — the SpecGuard annotation linter entrypoint.
+#
+# Selects spec files, finds every `@intent:` annotation in them, validates each
+# against the vendored OpenTestIntent schema, and reports every violation. Exit
+# codes are the contract (SPGD-12 §1):
+#
+#   0  all annotations valid, or there were none ("lint, don't require")
+#   1  one or more annotations are malformed
+#   2  the linter could not do its job — misuse, or the tool itself broken
+#
+# SpecGuard::RSpec::CLI#run is written to *return* one of those three and never
+# to raise; see its class comment for why that takes deliberate effort in Ruby.
+# The `require` below is the one thing outside its reach, so it gets the same
+# treatment here: a gem that cannot even load is the linter being broken, which
+# is a 2. Left bare, Ruby would exit 1 and CI would report a malformed
+# annotation nobody wrote.
+
+# Allow running from a source checkout without bundler by putting the local
+# lib/ on the load path. When the gem is installed (or run under
+# `bundle exec`), specguard/rspec resolves through the normal load path.
+source_lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(source_lib) unless $LOAD_PATH.include?(source_lib)
+
+begin
+  require "specguard/rspec"
+rescue ScriptError, StandardError => e
+  warn "specguard-lint: error: could not load specguard-rspec: #{e.class}: #{e.message}"
+  exit 2
+end
+
+exit SpecGuard::RSpec::CLI.new.run(ARGV)

data/lib/specguard/rspec/annotation_lookup.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+# Answers one question, for one example at a time: *is this test annotated, and
+# with what?*
+#
+# It is the formatter's half of the annotation story. The linter's half already
+# exists and is not duplicated here — {SpecGuard::RSpec::Scanner} finds every
+# `@intent:` in a file, captures its payload string-aware and parses it, and
+# {SpecGuard::RSpec::Schema} decides whether the result is valid. This class
+# consumes both. Writing a second extractor would guarantee that the tool
+# telling an author their annotation is wrong and the tool reporting it to the
+# platform eventually disagree about what an annotation *is*.
+#
+# Requiring the linter's chain from here is safe in the direction that matters:
+# `lib/specguard/rspec.rb` does not require `rspec/core`, so pulling it in from
+# the formatter's side keeps `bin/specguard-lint` loadable on a machine with no
+# RSpec installed. spec/specguard/rspec/formatter_loading_spec.rb pins that in
+# both directions.
+require_relative "../rspec"
+
+module SpecGuard
+  module RSpec
+    # == The lookback rule (SPGD-12 §2)
+    #
+    # `example.metadata[:line_number]` is the line the `it` is on. An annotation
+    # counts as this example's when it sits on that line (the trailing form) or
+    # on the line immediately above it (the preceding-comment form):
+    #
+    #   # @intent: { entity: "Order", ... }    <- line above
+    #   it "restores stock on refund" do       <- metadata[:line_number]
+    #
+    #   it "surfaces the decline reason" do # @intent: { ... }   <- same line
+    #
+    # One line of lookback, no more. Multi-line annotations are unsupported in
+    # v1 (PROTOCOL.md §1 requires an annotation to fit on one line), so a wider
+    # window could only ever attach an annotation to the wrong example.
+    #
+    # == Only the comment form is inherited by the line below
+    #
+    # The two forms are not symmetric, and the difference is not cosmetic. A
+    # comment-only line hosts no example, so an annotation written there has
+    # exactly one possible claimant — the line under it. An annotation written
+    # in the trailing form is on a line that *is* an example's, so it has two,
+    # and one-liner specs make the second one ordinary rather than exotic:
+    #
+    #   it { is_expected.to eq(1) } # @intent: { entity: "Order", ... }
+    #   it { is_expected.to be_positive }
+    #
+    # Lookback that did not distinguish the forms would report **both** of those
+    # as annotated, carrying the same intent — so the platform would store the
+    # second example's declared purpose as something nobody declared, and count
+    # it in `annotated_specs_count`. That is worse than reporting it
+    # unannotated: a missing annotation is a visible gap, an invented one is
+    # confident false telemetry, and it inflates the very ratio `status` exists
+    # to keep honest.
+    #
+    # So a Finding is claimable by the line below it only when its own line is
+    # comment-only ({COMMENT_LINE}). Deciding that needs the source line, which
+    # is why {#build_index} reads the file itself and calls {Scanner.scan_text}
+    # rather than {Scanner.scan_file} — the read is the same single read either
+    # way, and the alternative was a second one per file purely to re-derive
+    # what the first one already had in hand.
+    #
+    # == Why a malformed annotation is reported as *unannotated*
+    #
+    # {AnnotationScanner} states, correctly, that a typo'd annotation "must fail
+    # loudly rather than silently counting as unannotated". That is the
+    # **linter's** stance, and the linter already acts on it: it prints the
+    # file:line and exits 1. It cannot bind the formatter, which is under the
+    # never-block-CI contract and has no way to be loud that is not also a way
+    # to be in someone's build output.
+    #
+    # The alternative is worse than it looks. `Ingest::Payload` is
+    # all-or-nothing — it collects errors globally and `valid?` requires the
+    # list to be empty — so shipping one schema-invalid intent does not lose
+    # that annotation, it loses **the whole run**: a 400, and no telemetry for
+    # any of the other twenty thousand examples. Downgrading one annotation to
+    # `unannotated` costs one row's metadata. The example's name, duration and
+    # outcome still ship either way.
+    #
+    # So every one of these produces the same answer — `nil`, meaning
+    # unannotated:
+    #
+    #   * no `@intent:` on either candidate line;
+    #   * an `@intent:` on the line above that is *not* a comment-only line —
+    #     the trailing form belongs to its own example and lends itself to
+    #     nobody;
+    #   * an `@intent:` whose payload could not be captured or parsed
+    #     ({Finding#problem?} — `KIND_EXTRACTION` / `KIND_PARSE`);
+    #   * a file that could not be read at all (`KIND_READ`);
+    #   * a syntactically fine annotation the schema rejects;
+    #   * the schema itself failing to load.
+    #
+    # == Cost
+    #
+    # {AnnotationScanner.each_intent} walks every line of the file it is handed.
+    # Scanning per *example* would make a 20,000-example suite read and walk its
+    # spec files 20,000 times, on the critical path of somebody's test run. So
+    # each file is read and scanned at most once and reduced to an {Index}:
+    # O(files), not O(examples). Schema validation is memoized on the same
+    # principle — per distinct annotation, not per example carrying it.
+    class AnnotationLookup
+      # Findings at line 0 are {Finding::KIND_READ} — "this file was never
+      # read", not "there is an annotation on line 0". Keeping the sentinel out
+      # of the index is what makes {Index#finding_for}'s unconditional
+      # `line - 1` lookback safe for an example on line 1.
+      FIRST_REAL_LINE = 1
+
+      # A line whose only content is a comment: the preceding-comment form, and
+      # the only form an example on the next line may claim. Leading whitespace
+      # is allowed because annotations are indented with the examples they
+      # describe.
+      COMMENT_LINE = /\A\s*#/
+
+      # One file's annotations, split by who is allowed to claim them.
+      #
+      #   own          every annotation, by the line it was written on
+      #   inheritable  only those in the comment form, by that same line
+      #
+      # A line's own annotation always wins: the trailing form is written *on*
+      # the example, so when a file somehow carries both it is the more specific
+      # of the two, and a malformed trailing annotation is not quietly
+      # backfilled from the comment above it — that would attach an intent its
+      # author had already stopped meaning.
+      #
+      # `line - 1` is 0 for an example on line 1, and {AnnotationLookup#build_index}
+      # is what guarantees that reads back as "no annotation": line 0 is never a
+      # key, because the only Finding produced there is the KIND_READ sentinel.
+      Index = Struct.new(:own, :inheritable) do
+        # @return [Finding, nil]
+        def finding_for(line)
+          own[line] || inheritable[line - 1]
+        end
+      end
+
+      # The answer for a file nothing could be read out of. Its own constant so
+      # the pessimistic pre-scan cache in {#index_for} and the unreadable-file
+      # path cannot drift apart.
+      EMPTY_INDEX = Index.new({}.freeze, {}.freeze).freeze
+
+      # @param schema_path [String] the vendored OpenTestIntent schema. Injected
+      #   so a spec can point at a broken one without stubbing the loader.
+      def initialize(schema_path: SCHEMA_PATH)
+        @schema_path = schema_path
+        @indexes = {}
+        @verdicts = {}
+      end
+
+      # The intent to attach to one example, or nil when it is unannotated.
+      #
+      # Nothing here is rescued: a caller that cannot survive an exception must
+      # say so itself, and the formatter does — it wraps this in the same
+      # `never_fail_the_run` envelope as everything else, so a blow-up costs the
+      # example its annotation and not the suite its exit code. The memoization
+      # below is deliberately written so that a failure is cached too, which is
+      # what keeps "warns once" from becoming "warns once but rescans the file
+      # for every one of the remaining examples".
+      #
+      # @param file [String, nil] the example's file, as the payload records it
+      # @param line [Integer, nil] `example.metadata[:line_number]`
+      # @return [Hash, nil] the parsed, schema-valid annotation
+      def intent_for(file:, line:)
+        finding = finding_for(file: file, line: line)
+
+        # {Finding#extracted?} is the discovery layer's own word for "this
+        # yielded a Hash" — and, pointedly, "not a claim that it is valid".
+        # Everything it excludes (KIND_EXTRACTION, KIND_PARSE, KIND_READ) is an
+        # annotation the linter fails the build over and this half must not.
+        return nil unless finding&.extracted?
+
+        validated(finding.intent)
+      end
+
+      private
+
+      def finding_for(file:, line:)
+        return nil unless file.is_a?(String) && !file.empty?
+        return nil unless line.is_a?(Integer) && line >= FIRST_REAL_LINE
+
+        index_for(file).finding_for(line)
+      end
+
+      # @return [Index]
+      def index_for(file)
+        return @indexes[file] if @indexes.key?(file)
+
+        # Cache the pessimistic answer *before* the scan, not after. If the scan
+        # raises, the raise still reaches the formatter (which warns once and
+        # moves on) but the empty index stays behind, so the next example in the
+        # same file is answered from the cache instead of re-raising and
+        # re-reading. Without this, "warns once" would still mean "re-reads a
+        # broken file once per example" — the O(examples) cost this class exists
+        # to remove, reappearing on exactly the unhappy path where somebody's CI
+        # is already having a bad day.
+        @indexes[file] = EMPTY_INDEX
+        @indexes[file] = build_index(file)
+      end
+
+      # @return [Index]
+      def build_index(file)
+        text = read(file)
+        return EMPTY_INDEX if text.nil?
+
+        lines = nil
+        own = {}
+        inheritable = {}
+
+        Scanner.scan_text(text, file: file).each do |finding|
+          line = finding.line
+          next unless line.is_a?(Integer) && line >= FIRST_REAL_LINE
+
+          # First wins. `each_intent` resumes scanning after each captured
+          # payload, so trailing prose containing a second `@intent:` yields a
+          # second Finding on the same line. The annotation is the one the
+          # author wrote first; the rest of the line is commentary. Stated here
+          # rather than left to Hash-insertion order.
+          next if own.key?(line)
+
+          own[line] = finding
+          # Materialized only once a real annotation has been found, and never
+          # for a file `scan_text` refused: its invalid-UTF-8 answer is a single
+          # line-0 Finding, filtered out above, and splitting such a string is
+          # itself an ArgumentError waiting to happen.
+          lines ||= text.lines
+          inheritable[line] = finding if COMMENT_LINE.match?(lines[line - 1].to_s)
+        end
+
+        Index.new(own, inheritable)
+      end
+
+      # {Scanner.scan_file} would do this read, but it hands back only Findings
+      # and the form of an annotation is a property of the *line* it sits on. So
+      # the read happens here and {Scanner.scan_text} — the same pipeline, one
+      # stage lower — does the extracting. Nothing about what an annotation *is*
+      # is re-implemented; a second extractor is how the tool that tells an
+      # author their annotation is wrong and the tool that reports it to the
+      # platform end up disagreeing.
+      #
+      # The rescue mirrors `scan_file`'s own, and the two agree on the answer: it
+      # turns an unreadable file into a line-0 KIND_READ Finding, which this
+      # class filters out, and nil here becomes {EMPTY_INDEX}. Either way, every
+      # example in a file that could not be read is unannotated.
+      #
+      # @return [String, nil]
+      def read(file)
+        File.read(file, encoding: "UTF-8")
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      # Keyed by the intent itself, so an annotation repeated across a suite is
+      # compiled against the schema once rather than once per example that
+      # carries it. json_schemer is not free, and this class is explicitly about
+      # not paying O(examples) for work that is O(annotations).
+      #
+      # @return [Hash, nil] the intent when the schema accepts it
+      def validated(intent)
+        return @verdicts[intent] if @verdicts.key?(intent)
+
+        @verdicts[intent] = validate(intent)
+      end
+
+      def validate(intent)
+        loaded = schema
+        return nil if loaded.nil?
+
+        loaded.violations(intent).empty? ? intent : nil
+      end
+
+      # Loaded on first use, and at most once — including when loading fails.
+      #
+      # {Schema.load} raises {SchemaError} when the vendored document cannot be
+      # read, parsed or compiled. Under the linter that is a deliberate exit 2.
+      # Here it must not be an exit anything, so the raise is left to the
+      # formatter's envelope and the nil that gets cached in its place turns
+      # every subsequent annotation into an honest `unannotated` — the same
+      # answer this class gives for every other thing it could not verify.
+      def schema
+        return @schema if defined?(@schema)
+
+        @schema = nil
+        @schema = Schema.load(@schema_path)
+      end
+    end
+  end
+end

data/lib/specguard/rspec/annotation_scanner.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module SpecGuard
+  module RSpec
+    # Finds `@intent:` annotations in test source and captures the object
+    # literal that follows each one.
+    #
+    # This is a *syntactic* pass only: it hands back the payload exactly as
+    # written (still in PROTOCOL.md §1's permissive syntax — see
+    # {PayloadNormalizer}) and never inspects its contents. Schema validation is
+    # a later stage entirely.
+    #
+    # The scan is **string-aware**: quoted content is skipped over wholesale, so
+    # a `behavior` sentence containing an apostrophe or an unbalanced `{` cannot
+    # terminate the capture early. Plain brace-counting gets that case wrong.
+    #
+    # Ported from open-test-intent's `bin/validate-intent`
+    # (`extract_intents` / `_scan_object` / `_scan_string`), which is the
+    # reference implementation of this algorithm.
+    module AnnotationScanner
+      INTENT_TOKEN = "@intent:"
+
+      # Closing bracket => the opener it must match.
+      OPENERS = { "}" => "{", "]" => "[" }.freeze
+
+      # The `{` at `start` was never closed on this line.
+      UNTERMINATED_OBJECT = "unterminated object literal (an annotation must fit on one line)"
+      UNBALANCED_BRACKETS = "unbalanced brackets in the annotation payload"
+      NO_PAYLOAD = "no '{...}' object literal follows the @intent: token"
+
+      module_function
+
+      # Yields `[line_no, raw_payload, problem]` for every `@intent:` token in
+      # `text`, in source order.
+      #
+      # `raw_payload` is the object literal as written; it is `nil` when
+      # `problem` explains why the annotation could not be captured.
+      #
+      # An `@intent:` token carrying no extractable payload is **reported, not
+      # skipped** — a typo'd annotation must fail loudly rather than silently
+      # counting as "this example is unannotated".
+      #
+      # @param text [String] the full source of one file
+      # @yieldparam line_no [Integer] 1-based line number
+      # @yieldparam raw_payload [String, nil]
+      # @yieldparam problem [String, nil]
+      # @return [Enumerator] when no block is given
+      def each_intent(text)
+        return enum_for(:each_intent, text) unless block_given?
+
+        text.each_line.with_index(1) do |raw_line, line_no|
+          line = raw_line.chomp
+          pos = 0
+
+          loop do
+            token_at = line.index(INTENT_TOKEN, pos)
+            break if token_at.nil?
+
+            brace_at = line.index("{", token_at + INTENT_TOKEN.length)
+            if brace_at.nil?
+              yield line_no, nil, NO_PAYLOAD
+              break
+            end
+
+            begin
+              finish = scan_object(line, brace_at)
+            rescue ScanError => e
+              yield line_no, nil, e.message
+              break
+            end
+
+            yield line_no, line[brace_at...finish], nil
+
+            # Resume *after* the captured payload so trailing prose containing
+            # another `@intent:` is still seen, but the payload's own contents
+            # are never rescanned.
+            pos = finish
+          end
+        end
+      end
+
+      # Returns the index just past the `}` matching the `{` at `text[start]`.
+      #
+      # Bracket-balanced and string-aware, so a brace inside a quoted value does
+      # not end the payload early. Annotations are single-line per PROTOCOL.md
+      # §1, so `text` is one line.
+      #
+      # @raise [ScanError] when the literal is unterminated or unbalanced
+      def scan_object(text, start)
+        stack = []
+        i = start
+        length = text.length
+
+        while i < length
+          char = text[i]
+
+          if char == '"' || char == "'"
+            i = scan_string(text, i, char)
+            next
+          end
+
+          if char == "{" || char == "["
+            stack.push(char)
+          elsif char == "}" || char == "]"
+            raise ScanError, UNBALANCED_BRACKETS if stack.empty? || stack.last != OPENERS[char]
+
+            stack.pop
+            return i + 1 if stack.empty?
+          end
+
+          i += 1
+        end
+
+        raise ScanError, UNTERMINATED_OBJECT
+      end
+
+      # Returns the index just past the closing `quote` of a string literal.
+      #
+      # `text[start]` must be the opening quote. Backslash escapes are honoured,
+      # so a quote or brace *inside* the string never terminates the scan.
+      #
+      # @raise [ScanError] when the string literal is unterminated
+      def scan_string(text, start, quote)
+        i = start + 1
+        length = text.length
+
+        while i < length
+          char = text[i]
+
+          if char == "\\"
+            i += 2 # skip the escape and whatever it escapes
+            next
+          end
+
+          return i + 1 if char == quote
+
+          i += 1
+        end
+
+        raise ScanError, "unterminated #{quote}-quoted string"
+      end
+    end
+  end
+end