specguard-ruby 0.3.1

data/lib/specguard/rspec/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Back-compat alias. The version number itself lives in `SpecGuard::VERSION`
+# (lib/specguard/version.rb) since the gem became `specguard-ruby`; this
+# constant is kept because released `specguard-rspec` versions exposed it and
+# a consumer reaching for it should not break on the rename. It is the same
+# number, not a second one — `script/bump-version.sh` edits only the source.
+require_relative "../version"
+
+module SpecGuard
+  module RSpec
+    VERSION = SpecGuard::VERSION
+  end
+end

data/lib/specguard/rspec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "rspec/version"
+
+module SpecGuard
+  module RSpec
+    # The Ruby client for SpecGuard.
+    #
+    # The linter is complete end to end: it finds `@intent:` annotations in
+    # spec files, captures each payload string-aware, normalizes PROTOCOL.md
+    # §1's permissive syntax into strict JSON, validates the result against the
+    # vendored OpenTestIntent schema, and reports violations in the reference
+    # tool's own grammar under the 0/1/2 exit contract (see {CLI}).
+    #
+    # The RSpec formatter (`SpecGuard::RSpecFormatter`) is the other half of
+    # the client, and it is deliberately **not** required from here: `rspec` is
+    # a development dependency of this gem, not a runtime one, and
+    # `bin/specguard-lint` loads this file on machines that may have no RSpec
+    # at all. Requiring `rspec/core` from this chain would turn a missing test
+    # framework into a broken linter. Load it by its own path when you want it
+    # — `require "specguard/rspec/formatter"` — and see that file for the
+    # opt-in wiring.
+    class Error < StandardError; end
+
+    # A source line could not be scanned (unterminated string or object
+    # literal). Internal to the scanner: it is caught and turned into a
+    # {Finding}'s `problem` rather than reaching a caller.
+    class ScanError < Error; end
+
+    # The tool was invoked in a way that cannot work — `--changed` outside a git
+    # repository, say. Distinct from "the annotations are bad": the exit-code
+    # contract makes this a 2, and it is typed here so the CLI can map it
+    # without re-deriving the distinction from an error message.
+    class UsageError < Error; end
+
+    # The opt-in Go validator backend could not produce a verdict — the binary
+    # named by `SPECGUARD_VALIDATE_INTENT` is missing, will not execute, exited
+    # with a code that is not a verdict, or emitted something this cannot read
+    # as a report.
+    #
+    # Typed separately from {UsageError} because the two are different
+    # accusations ("you invoked me wrongly" vs "the tool I was told to use is
+    # broken"), and rescued *beside* it in {CLI#run} because the answer to both
+    # is the same and non-negotiable: exit 2, never 1. See {ValidatorBackend}.
+    class ValidatorError < Error; end
+
+    # The vendored canonical OpenTestIntent schema, copied byte-for-byte from
+    # open-test-intent so this gem has **no cross-repo runtime dependency**.
+    # It ships packaged (it lives under `lib/`, which the gemspec includes);
+    # the spec fixtures deliberately do not, so nothing here may be
+    # load-bearing at runtime.
+    #
+    # Since the SPGD-867 cutover nothing VALIDATES against this copy — every
+    # verdict comes from the `validate-intent` binary's own compiled-in
+    # schema. It survives because {ValidatorBackend}'s schema-contract check
+    # digests it at runtime and refuses a binary that would enforce different
+    # bytes: the two halves of the seam must keep meeting somewhere, and this
+    # file is where the gem's half lives.
+    SCHEMA_PATH = File.expand_path("rspec/schemas/open-test-intent.v1.json", __dir__).freeze
+  end
+end
+
+require_relative "rspec/finding"
+require_relative "rspec/annotation_scanner"
+require_relative "rspec/payload_normalizer"
+require_relative "rspec/scanner"
+require_relative "rspec/file_selector"
+require_relative "rspec/linter"
+require_relative "rspec/json_reporter"
+require_relative "rspec/validator_backend"
+require_relative "rspec/cli"

data/lib/specguard/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# The version of the `specguard-ruby` gem — one number for every adapter the
+# gem ships. It lived in `SpecGuard::RSpec::VERSION` while the gem itself was
+# `specguard-rspec` and rspec was the only adapter; the rename to a
+# language-scoped client (mirroring `specguard-ts` and `specguard-go`) made a
+# framework-scoped version constant a lie, so the number moved here and the
+# rspec module now points at it for back-compat.
+module SpecGuard
+  VERSION = "0.3.1"
+end

data/script/bump-version.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Bump the patch version, commit, push to main, and tag vX.Y.Z on what landed.
+#
+# Mirrors yatfa's script/bump-version.sh, adapted for a gem:
+#   - the version source is lib/specguard/version.rb (the gemspec reads
+#     SpecGuard::VERSION from it; lib/specguard/rspec/version.rb is a back-compat
+#     alias that follows it), not a VERSION file
+#   - release is tag-based like warden's: the GitHub Release and the pushed gem
+#     both correspond to vX.Y.Z. There is no `prod` deploy-mirror branch —
+#     nothing here is deployed to a cluster.
+#
+# Strategy carried over verbatim: must be on main with a clean tree, patch-only
+# bump, commit "bump: X -> Y", pull --rebase + push with up to 3 retries.
+#
+# When run inside GitHub Actions (GITHUB_OUTPUT set), exports `version` and
+# `tag` to the step's job outputs. Locally it just prints the new version.
+set -e
+
+VERSION_FILE="lib/specguard/version.rb"
+
+# Ensure we're on the main branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+if [ "$CURRENT_BRANCH" != "main" ]; then
+    echo "Error: Not on main branch. Current branch: $CURRENT_BRANCH"
+    exit 1
+fi
+
+# Check that no TRACKED file has uncommitted changes. Untracked files are not
+# a reason to refuse: this runs in CI right after the suite, where
+# ruby/setup-ruby's bundler-cache rewrites Gemfile.lock (untracked here, see
+# .gitignore) and the suite itself may leave artefacts behind. What must be
+# clean is the content the bump is about to commit on top of.
+if [ -n "$(git status --porcelain --untracked-files=no)" ]; then
+    echo "Error: tracked files have uncommitted changes:"
+    git status --porcelain --untracked-files=no
+    exit 1
+fi
+
+if [ ! -f "$VERSION_FILE" ]; then
+    echo "Error: $VERSION_FILE not found"
+    exit 1
+fi
+
+CURRENT_VERSION=$(ruby -e 'require "./lib/specguard/rspec/version"; print SpecGuard::RSpec::VERSION')
+echo "Current version: $CURRENT_VERSION"
+
+# Bump patch version (0.2.0 -> 0.2.1)
+IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
+echo "New version: $NEW_VERSION"
+
+# A published gem version is immutable — RubyGems refuses a re-push and yanking
+# does not free the number. Refuse locally rather than discovering it after a
+# build, and refuse a reused tag for the same reason the release does.
+if git rev-parse -q --verify "refs/tags/v$NEW_VERSION" >/dev/null || \
+   git ls-remote --exit-code --tags origin "refs/tags/v$NEW_VERSION" >/dev/null 2>&1; then
+    echo "Error: tag v$NEW_VERSION already exists — the version file and the tags disagree"
+    exit 1
+fi
+if command -v curl >/dev/null 2>&1; then
+    if curl -fsS --max-time 10 "https://rubygems.org/api/v1/versions/specguard-rspec.json" 2>/dev/null \
+       | grep -q "\"number\":\"$NEW_VERSION\""; then
+        echo "Error: specguard-rspec $NEW_VERSION is already published on RubyGems"
+        exit 1
+    fi
+fi
+
+# Rewrite the VERSION constant in place. A targeted sed on the one line, so the
+# surrounding file (frozen_string_literal, module nesting) is untouched.
+sed -i.bak -E "s/(VERSION = \")[0-9]+\.[0-9]+\.[0-9]+(\")/\1$NEW_VERSION\2/" "$VERSION_FILE"
+rm -f "$VERSION_FILE.bak"
+WROTE=$(ruby -e 'load "./lib/specguard/rspec/version.rb"; print SpecGuard::RSpec::VERSION')
+if [ "$WROTE" != "$NEW_VERSION" ]; then
+    echo "Error: $VERSION_FILE still reports $WROTE after the rewrite"
+    exit 1
+fi
+
+# Create commit
+git add "$VERSION_FILE"
+git commit -m "bump: $CURRENT_VERSION -> $NEW_VERSION"
+
+# Pull with rebase to incorporate any commits that landed on main since checkout,
+# then push the branch and the tag. Retry up to 3 times to handle concurrent pushes.
+#
+# The tag is created INSIDE the loop, after `git push origin main` succeeds, and
+# never before the rebase. `git pull --rebase` replays the bump commit onto the
+# advanced main and gives it a new SHA; tags do not follow a rebase, so a tag
+# created beforehand would name an abandoned object that is not an ancestor of
+# main — while the workflow builds the gem from the post-rebase tree. A published
+# gem version is immutable, so that divergence would be permanent.
+#
+# `-f` makes a retry idempotent when an earlier attempt created the local tag but
+# failed to push it. It cannot clobber a published tag: the tag-reuse guard above
+# already refused that case before any work started.
+MAX_RETRIES=3
+RETRY_COUNT=0
+PUSH_SUCCESS=false
+
+while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
+    if git pull --rebase origin main; then
+        # HEAD is now the rebased bump commit — the object the tag must name.
+        if git push origin main; then
+            git tag -f "v$NEW_VERSION" HEAD
+            if git push origin "v$NEW_VERSION"; then
+                PUSH_SUCCESS=true
+                break
+            fi
+        fi
+    fi
+    RETRY_COUNT=$((RETRY_COUNT + 1))
+    if [ $RETRY_COUNT -lt $MAX_RETRIES ]; then
+        echo "Push failed, retrying ($RETRY_COUNT/$MAX_RETRIES)..."
+        sleep 5
+    fi
+done
+
+if [ "$PUSH_SUCCESS" = false ]; then
+    echo "Error: Failed to push version bump after $MAX_RETRIES attempts"
+    exit 1
+fi
+
+echo "Version bumped to $NEW_VERSION and pushed to main with tag v$NEW_VERSION"
+
+# Export to GitHub Actions job outputs when run in CI
+if [ -n "$GITHUB_OUTPUT" ]; then
+    echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+    echo "tag=v$NEW_VERSION" >> "$GITHUB_OUTPUT"
+fi

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: specguard-ruby
+version: !ruby/object:Gem::Version
+  version: 0.3.1
+platform: ruby
+authors:
+- specguard Agent
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.21'
+description: SpecGuard's Ruby client — every Ruby test framework, one gem. Ships an
+  additive RSpec formatter and a Minitest reporter that post test-run telemetry to
+  SpecGuard's ingest endpoint, a CLI linter (specguard-lint) that validates OpenTestIntent
+  @intent annotations in *_spec.rb files, and a replayer (specguard-ingest) that re-delivers
+  a run saved when the endpoint could not be reached. Telemetry never blocks CI; the
+  linter blocks only on malformed annotations.
+email:
+- specguard-agent@noreply.yatfa.com
+executables:
+- specguard-lint
+- specguard-ingest
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- LICENSE
+- README.md
+- Rakefile
+- assets/built-with-yatfa.png
+- bin/specguard-ingest
+- bin/specguard-lint
+- lib/minitest/specguard_plugin.rb
+- lib/specguard/minitest/reporter.rb
+- lib/specguard/rspec.rb
+- lib/specguard/rspec/annotation_lookup.rb
+- lib/specguard/rspec/annotation_scanner.rb
+- lib/specguard/rspec/cli.rb
+- lib/specguard/rspec/configuration.rb
+- lib/specguard/rspec/file_selector.rb
+- lib/specguard/rspec/finding.rb
+- lib/specguard/rspec/formatter.rb
+- lib/specguard/rspec/ingest_cli.rb
+- lib/specguard/rspec/ingest_reporter.rb
+- lib/specguard/rspec/json_reporter.rb
+- lib/specguard/rspec/linter.rb
+- lib/specguard/rspec/payload_normalizer.rb
+- lib/specguard/rspec/scanner.rb
+- lib/specguard/rspec/schemas/open-test-intent.v1.json
+- lib/specguard/rspec/transport.rb
+- lib/specguard/rspec/validator_backend.rb
+- lib/specguard/rspec/version.rb
+- lib/specguard/version.rb
+- script/bump-version.sh
+homepage: https://github.com/yatfa-ai/specguard-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yatfa-ai/specguard-ruby
+  bug_tracker_uri: https://github.com/yatfa-ai/specguard-ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: RSpec formatter, Minitest reporter and @intent annotation linter for SpecGuard.
+test_files: []