specguard-ruby 0.3.1

data/lib/specguard/rspec/payload_normalizer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SpecGuard
+  module RSpec
+    # Relaxes PROTOCOL.md §1's permissive annotation syntax into strict JSON.
+    #
+    # §1 promises "the linter normalizes before validating" and lists three
+    # equivalent forms. This converts all of them:
+    #
+    #   * unquoted keys         `{entity:"Order"}`   -> `{"entity":"Order"}`
+    #   * single-quoted strings `{'entity':'Order'}` -> `{"entity":"Order"}`
+    #   * arbitrary whitespace  (`JSON.parse` already tolerates it)
+    #
+    # plus a trailing comma before `}`/`]` as a courtesy.
+    #
+    # == Why this is a character scanner, not a `gsub`
+    #
+    # It is a character-scanner rather than a regex substitution **so quoted
+    # content is never rewritten** — a `behavior` sentence containing `it's` or
+    # `{` is passed through untouched. Any `gsub`-then-`JSON.parse` port
+    # corrupts exactly those values; the examples under "quoted content is
+    # never rewritten" in `payload_normalizer_spec.rb` pin them.
+    #
+    # The payload is *never* `eval`'d. It is attacker-controllable text taken
+    # from a comment in someone's spec file, so it only ever reaches
+    # `JSON.parse`, which cannot execute anything.
+    #
+    # == The bare-word rule
+    #
+    # A bare word is quoted **only in key position**. A bare word used as a
+    # value (`{layer: request}`) is left alone so it still fails downstream —
+    # the protocol relaxes keys and quote style, never value quoting.
+    #
+    # Ported from open-test-intent's `bin/validate-intent`
+    # (`normalize_payload` / `_requote`).
+    module PayloadNormalizer
+      # Anchored at the scan position (`\G`), so it matches AT i rather than
+      # searching from it. Explicit ASCII ranges, per PROTOCOL.md §1 — a Unicode
+      # word class would make the accepted surface syntax depend on the regex
+      # engine, which is what one specification exists to prevent.
+      BARE_WORD = /\G[A-Za-z_$][A-Za-z0-9_$]*/.freeze
+
+      module_function
+
+      # @param raw [String] the object literal as written in the source
+      # @return [String] strict JSON, ready for `JSON.parse`
+      # @raise [ScanError] on an unterminated string literal
+      def normalize(raw)
+        out = +""
+        i = 0
+        length = raw.length
+
+        while i < length
+          char = raw[i]
+
+          # Already-strict double-quoted string: copy verbatim, contents and all.
+          if char == '"'
+            finish = AnnotationScanner.scan_string(raw, i, '"')
+            out << raw[i...finish]
+            i = finish
+            next
+          end
+
+          # Single-quoted string: re-emit its body as a JSON string.
+          if char == "'"
+            finish = AnnotationScanner.scan_string(raw, i, "'")
+            out << requote(raw[(i + 1)...(finish - 1)])
+            i = finish
+            next
+          end
+
+          if (match = BARE_WORD.match(raw, i))
+            word = match[0]
+            after = match.end(0)
+            out << (key_position?(raw, after) ? JSON.generate(word) : word)
+            i = after
+            next
+          end
+
+          # Trailing comma before a closing bracket: drop it.
+          if char == "," && closes_after?(raw, i + 1)
+            i += 1
+            next
+          end
+
+          out << char
+          i += 1
+        end
+
+        out
+      end
+
+      # Re-emits the body of a single-quoted string as a double-quoted JSON
+      # string, preserving every escape that JSON understands.
+      #
+      # @param body [String] the string's contents, without its surrounding quotes
+      # @return [String] a complete JSON string literal, quotes included
+      def requote(body)
+        out = +""
+        i = 0
+        length = body.length
+
+        while i < length
+          char = body[i]
+
+          if char == "\\"
+            nxt = i + 1 < length ? body[i + 1] : ""
+            # `\'` is meaningless in JSON — unescape it; keep every other escape.
+            out << (nxt == "'" ? "'" : char + nxt)
+            i += 2
+            next
+          end
+
+          out << (char == '"' ? '\"' : char)
+          i += 1
+        end
+
+        %("#{out}")
+      end
+
+      # True when the next non-space character after `pos` is a `:`, i.e. the
+      # bare word just scanned is a key rather than a value.
+      def key_position?(raw, pos)
+        probe = skip_space(raw, pos)
+        probe < raw.length && raw[probe] == ":"
+      end
+
+      # True when the next non-space character at or after `pos` closes a
+      # bracket, i.e. the comma just scanned was a trailing comma.
+      def closes_after?(raw, pos)
+        probe = skip_space(raw, pos)
+        probe < raw.length && (raw[probe] == "}" || raw[probe] == "]")
+      end
+
+      def skip_space(raw, pos)
+        pos += 1 while pos < raw.length && raw[pos].match?(/\s/)
+        pos
+      end
+    end
+  end
+end

data/lib/specguard/rspec/scanner.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SpecGuard
+  module RSpec
+    # Runs the discovery pipeline over source files and returns {Finding}s.
+    #
+    # Pipeline, per `@intent:` token:
+    #
+    #   {AnnotationScanner} -> {PayloadNormalizer} -> `JSON.parse`
+    #
+    # This is the whole of the *input* half of the linter. It deliberately stops
+    # at "an annotation is a Hash": nothing here loads or applies the
+    # OpenTestIntent schema, so a Finding with an `intent` is merely
+    # syntactically sound, not valid.
+    module Scanner
+      module_function
+
+      # @param paths [Enumerable<String>]
+      # @return [Array<Finding>] in file-then-line order
+      def scan_files(paths)
+        paths.flat_map { |path| scan_file(path) }
+      end
+
+      # @param path [String]
+      # @return [Array<Finding>] one per `@intent:` token; empty when the file
+      #   carries none. A file that cannot be read yields a single Finding at
+      #   line 0 rather than raising — one bad file must not abort the run.
+      #
+      #   RATIFIED DIFFERENCE from the binary, for a path that does not exist.
+      #   `validate-intent` expands its arguments as glob PATTERNS, so a name
+      #   matching nothing is a statement about the pattern —
+      #   `error: no file(s) match '<path>'`, on stderr, before any file is
+      #   opened. This linter does no globbing: explicit files are checked as
+      #   given and `--changed` derives its list from git, so every argument
+      #   here is a PATH, and an unopenable one is a read failure OF THAT PATH —
+      #   reported on stdout with the errno the binary never had occasion to
+      #   name. Adopting the binary's wording would mean giving this gem a
+      #   globber first, and changing what `specguard-lint 'foo*_spec.rb'` means
+      #   for everyone already using it.
+      #
+      #   Both tools exit 1 and both name the file; that much is asserted in
+      #   spec/specguard/rspec/validator_backend_spec.rb, along with the case
+      #   that matters more — a missing file does not stop either tool checking
+      #   the good files named beside it.
+      #
+      #   A path that exists and is NOT A REGULAR FILE lands in the same rescue
+      #   and is the same ratified difference one step further out: this rescue
+      #   has an errno and reports it (`Is a directory @ io_fread - <path>`),
+      #   while the binary's glob filters non-regular matches away and answers
+      #   exactly as it does for a name matching nothing. Ruby tells the two
+      #   apart and the backend cannot — asserted under "a path that is not a
+      #   regular file" in that same spec.
+      def scan_file(path)
+        begin
+          text = File.read(path, encoding: "UTF-8")
+        rescue SystemCallError, IOError => e
+          return [Finding.new(file: path, line: 0, problem: "could not read file: #{e.message}",
+                              kind: Finding::KIND_READ)]
+        end
+
+        scan_text(text, file: path)
+      end
+
+      # @param text [String] source of one file
+      # @param file [String] the path to record on each Finding
+      # @return [Array<Finding>]
+      def scan_text(text, file:)
+        # An invalid byte sequence would make every String operation below raise
+        # from deep inside the scanner. Report it as this file's one problem.
+        #
+        # RATIFIED DIFFERENCE from the binary, in the REASON TEXT only. Both
+        # refuse the file — PROTOCOL.md §1.1 makes UTF-8 part of what a JSON
+        # text IS, and neither side repairs the bytes — and both name the
+        # CONDITION rather than an offset: the binary says `input is not
+        # well-formed UTF-8 (PROTOCOL.md §1.1 requires it)`, this says
+        # `invalid UTF-8 byte sequence`. Neither wording is specified, so
+        # neither is wrong; what matters is that both classify it as a READ
+        # failure and neither substitutes U+FFFD and carries on.
+        #
+        # What is shared is asserted in spec/specguard/rspec/validator_backend_spec.rb,
+        # under "the not-well-formed-UTF-8 text is each backend's own": same
+        # classification, same file, same `FAIL <file> — could not read file: `
+        # prefix, a non-empty reason on both sides, and exit 1 — and the tails
+        # are asserted to still DIFFER, so converging them fails that file
+        # rather than leaving this comment stale.
+        unless text.valid_encoding?
+          return [Finding.new(file: file, line: 0, problem: "could not read file: invalid UTF-8 byte sequence",
+                              kind: Finding::KIND_READ)]
+        end
+
+        AnnotationScanner.each_intent(text).map do |line_no, raw, problem|
+          if problem
+            Finding.new(file: file, line: line_no, problem: problem, kind: Finding::KIND_EXTRACTION)
+          else
+            parse(raw, file: file, line: line_no)
+          end
+        end
+      end
+
+      # RATIFIED DIFFERENCE from the binary. Two of them, and only the first is
+      # a difference in reason TEXT.
+      #
+      # == (1) The wording, when both parsers reject the payload
+      #
+      # `PayloadNormalizer` rescues PROTOCOL.md §1's permissive syntax on both
+      # sides, so a payload it can fix renders identically. What reaches
+      # `JSON.parse` still broken — a bare-word VALUE, a key that is not a key
+      # — is described by whichever JSON parser is doing the parsing: this
+      # interpolates Ruby's `JSON::ParserError#message`, while the binary uses
+      # its own. So `{bad_key}` is `expected object key, got 'bad_key}' at line
+      # 1 column 2` here and `expected a double-quoted property name (line 1,
+      # column 2)` there.
+      #
+      # Reproducing that tail would mean carrying a second parser's diagnostics
+      # in a gem whose entire reason for vendoring the schema is to owe
+      # open-test-intent nothing at runtime — the argument `scan_text` makes
+      # about the DECODER, applied verbatim to the PARSER. PROTOCOL.md
+      # specifies the accepted LANGUAGE, not the prose a validator refuses in,
+      # so two spellings of one refusal are both conformant.
+      #
+      # What is shared is asserted in
+      # spec/specguard/rspec/validator_backend_spec.rb: same classification,
+      # same file, same LINE (unlike a read failure, this one is line-scoped and
+      # both agree on the line and even the column), same
+      # `could not parse annotation: ` prefix, same counts, and exit 1. Only the
+      # tail is unpinned.
+      #
+      # == (2) THE ACCEPTANCE SET: where the two parsers take different input
+      #
+      # (1) is about how the two spell the same refusal. This is about payloads
+      # where they do not both refuse — a bigger difference, and the generator
+      # (1) was hiding.
+      #
+      # This USED to be a three-member set in which the binary was the
+      # permissive side, because its parser reproduced a foreign runtime's
+      # grammar that `PROTOCOL.md` had never specified. PROTOCOL.md §1.1 states
+      # the grammar now: an RFC 8259 JSON text, with the three points that RFC
+      # leaves open settled explicitly. The binary refuses the non-finite
+      # literals (§1.1(b)), unpaired surrogate escapes (§1.1(a)) and nesting
+      # past 100 (§1.1(c)), and `JSON.parse` refuses or limits all three too, so
+      # those three have CONVERGED.
+      #
+      # WHAT SURVIVES RUNS THE OTHER WAY: this parser is now the permissive one.
+      #
+      # Read that as scoped to PARSING, which is all this register has ever
+      # covered. It is not a statement that the two backends agree everywhere
+      # else: the stage BEFORE this one diverged too, and in the opposite
+      # direction. Until SPGD-512 the binary's `@intent:` payload search was
+      # unbounded where {AnnotationScanner#payload_brace} bounds it at the next
+      # token, so a malformed token followed by a well-formed one was captured
+      # as valid by the binary and reported no-payload by this gem — binary
+      # permissive, gem strict. The Go port of that bound closed it. The lesson
+      # worth keeping is that a divergence can live at extraction as easily as
+      # at parse, so "what survives" below is the parser's list, not the
+      # backends' list.
+      #
+      #   * A LONE LOW surrogate escape (`\udc00`-`\udfff`). `JSON.parse`
+      #     accepts it; §1.1(a) refuses it, because a surrogate escape must form
+      #     a pair. Ruby refuses only the HIGH half, which is why the rule here
+      #     is narrower than "surrogate escapes diverge".
+      #   * The nesting BOUNDARY, by exactly one level and only for an EMPTY
+      #     container. §1.1(c) refuses any container deeper than 100. Ruby
+      #     checks the depth when it is about to parse a VALUE, so a container
+      #     sitting at depth 101 with nothing in it is never checked and is
+      #     accepted; put anything inside it and Ruby refuses too. Measured on
+      #     json 2.21.2 and pinned, both halves, in
+      #     `spec/specguard/rspec/validator_backend_spec.rb`.
+      #
+      # The surrogate one is not merely a verdict difference. What `JSON.parse`
+      # returns for `"\udc00"` is a String whose `valid_encoding?` is FALSE: it
+      # cannot be re-serialised and cannot cross the ingest transport, so a
+      # payload this parser calls valid is one the gem cannot send. That is the
+      # cost §1.1(a) exists to remove, and it is still paid on this path.
+      #
+      # It produces two shapes, depending on whether the payload this parser
+      # accepts then passes the schema. BOTH ARE REACHABLE, one per survivor:
+      #
+      #   (v)  NOT schema-valid — the CLASSIFICATION differs. The NESTING
+      #        survivor lands here and only here. A container at depth 101 is
+      #        a container, so it can never occupy a schema-legal slot: every
+      #        value the schema permits is a string or an array of strings. So
+      #        a payload deep enough to diverge is a payload the schema refuses,
+      #        and the two tools refuse it for different stated reasons —
+      #
+      #          binary: "kind": "parse"   nesting is deeper than 100 levels
+      #                                    (PROTOCOL.md §1.1(c))
+      #          gem:    "kind": "schema"  preconditions[0]: expected type
+      #                                    string, got array
+      #
+      #        The VERDICT agrees (both fail, both exit 1); only the `kind` and
+      #        the reason differ.
+      #   (vi) schema-valid — the VERDICT differs. The SURROGATE survivor lands
+      #        here: it lives inside a string, and a string is what the schema
+      #        permits. This path reports nothing and exits 0; the backend
+      #        reports a parse failure and exits 1.
+      #
+      # RATIFIED, and the reason is scope rather than preference. This gem's
+      # hand-rolled validation logic is slated for REMOVAL by the roadmap that
+      # owns the binary, not for repair; and closing the gap here would be a
+      # change to the DEFAULT path, which the slice that introduced
+      # `ValidatorBackend` explicitly holds fixed. Whoever removes this parser
+      # closes it by deletion.
+      #
+      # Asserted from both sides — what this parser accepts, the convergence,
+      # and both surviving divergences — in
+      # `spec/specguard/rspec/validator_backend_spec.rb` under "the JSON
+      # acceptance set".
+      #
+      # Note that `JSON::NestingError` is a subclass of `JSON::ParserError`, so
+      # a nesting refusal Ruby DOES make is already carried by the rescue below
+      # and needs no clause of its own. That is about the refusals the two
+      # share; it is not a claim that the classification always agrees, which
+      # at depth 101 it does not — see (v).
+      #
+      # @return [Finding]
+      def parse(raw, file:, line:)
+        intent = JSON.parse(PayloadNormalizer.normalize(raw))
+
+        # A bare `[...]` or scalar is syntactically fine JSON but is not an
+        # annotation. Reject it here so downstream stages can assume a Hash.
+        unless intent.is_a?(Hash)
+          return Finding.new(file: file, line: line, kind: Finding::KIND_PARSE,
+                             problem: "annotation payload is not an object")
+        end
+
+        Finding.new(file: file, line: line, intent: intent)
+      rescue ScanError, JSON::ParserError => e
+        Finding.new(file: file, line: line, kind: Finding::KIND_PARSE,
+                    problem: "could not parse annotation: #{e.message}")
+      end
+    end
+  end
+end

data/lib/specguard/rspec/schemas/open-test-intent.v1.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/yatfa-ai/open-test-intent/schema-v1.0/schemas/open-test-intent.v1.json",
+  "title": "OpenTestIntent v1",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "entity":        { "type": "string", "minLength": 2 },
+    "action":        { "type": "string", "minLength": 2 },
+    "behavior":      { "type": "string", "minLength": 15 },
+    "layer":         { "type": "string", "enum": ["unit", "integration", "request", "system"] },
+    "preconditions": { "type": "array", "items": { "type": "string" } }
+  },
+  "required": ["entity", "action", "behavior", "layer"]
+}