ts_schema_spec 0.5.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c8202e8af0fa27c82203f869cd593208ee48dd95bfe23f6ab53083c47442fc47
+  data.tar.gz: 3afcb839cc834657613896897ba454234a07facc8b0ffc3a9e8ce54abea5dffb
+SHA512:
+  metadata.gz: a4608416aebf93c1125f9df04126b44479f52bf95e7605f924aa14af04b18fbafef30f39e3cf0ff16c38b948d9f970b37fb552b867cb9725764d569b83cdb1d4
+  data.tar.gz: 8ff1849e182079b473b130922e9315dfc92766c5d84bad559d52e715c01e3ffbc86effafa971b445f2fc2ee307a6819be81f45266d9441c07333c0f658b38600

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vernon Coffey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,288 @@
+# ts_schema_spec
+
+Add tests to your Ruby test suite that assert a JSON payload generated in Ruby
+matches the TypeScript type of the consumer.
+
+Built for RSpec, but could be ported to other test frameworks (Minitest, etc.).
+
+`react_component_props`, an optional React-specific helper, reads props out of
+rendered mounts.
+
+React is the case this gem was built for, not a requirement. `match_schema`
+checks any payload against any exported TypeScript type, so a Stimulus
+controller or a plain fetch client works the same way.
+
+## Install
+
+```ruby
+# Gemfile
+gem "ts_schema_spec", github: "nitidbit/ts_schema_spec", tag: "v0.5.3", group: :test
+```
+
+This gem requires ts-json-schema-generator, resolved from your project's
+`node_modules`:
+
+```
+npm install --save-dev ts-json-schema-generator
+```
+
+Add the following to your test suite:
+
+```ruby
+# spec/rails_helper.rb
+require "ts_schema_spec/rspec"
+require "ts_schema_spec/react_component_props" # optional, for parsing props from rendered HTML. See below.
+
+RSpec.configure do |config|
+  config.include TsSchemaSpec::ReactComponentProps
+end
+```
+
+### Path aliases
+
+If your TypeScript imports through aliases (`@/components/Foo`), point the
+generator at your tsconfig:
+
+```ruby
+# spec/rails_helper.rb
+TsSchemaSpec.configure do |config|
+  config.tsconfig = Rails.root.join("tsconfig.json").to_s
+  config.generator_args = []  # anything else to pass through
+end
+```
+
+**This is not optional decoration.** An import the generator cannot resolve
+does not fail — it becomes an empty schema, and an empty schema validates
+anything:
+
+```json
+"role": {}
+```
+
+So an aliased type without a tsconfig gives you a green spec that accepts a
+string, a number or null where an object was declared. If any type you assert
+on imports through an alias, set this.
+
+### The agent skill
+
+The gem ships the skill that teaches an agent when one of these specs is owed
+and how to write it. Claude Code reads skills from the working tree, so it has
+to be copied in and committed:
+
+```
+RAILS_ENV=test bundle exec rake ts_schema_spec:install_skill
+```
+
+`RAILS_ENV=test` is required when the gem is in `group: :test`, as above.
+
+It lands in `.claude/skills/react-prop-type-spec/SKILL.md`, stamped with the
+gem version. To keep the skill in sync with the gem version:
+
+```ruby
+# spec/ts_schema_spec_skill_spec.rb
+it "has the skill matching the installed gem" do
+  expect { TsSchemaSpec::Skill.check!(Rails.root) }.to_not raise_error
+end
+```
+
+## Use
+
+### A JSON endpoint
+
+```ruby
+it "matches AccountPayload" do
+  create(:account, :with_roles)
+  create(:account, :unassigned)
+
+  get :index, format: :json
+
+  expect(response).to be_successful
+  expect(response.parsed_body["accounts"])
+    .to match_schema("app/javascript/types/account.ts", "AccountPayload")
+end
+```
+
+### Props from an HTML mount
+
+`react_component_props` parses the rendered `data-react-props` attributes and
+returns **an array** — one entry per mount of that component on the page. It
+needs `render_views`.
+
+It assumes [react-rails](https://github.com/reactjs/react-rails) conventions:
+`data-react-class` and `data-react-props` on the mount element. A namespaced
+class matches on its trailing segment, so `admin/SidebarNav` and
+`Admin.SidebarNav` both answer to `"SidebarNav"`.
+
+Other integrations mount differently — react_on_rails uses its own attributes
+— and against those it finds nothing and reports an empty collection rather
+than a missing-attribute error. Supporting another convention is a small
+change to one file; open a PR if you need it.
+
+```ruby
+describe "the props handed to RoleMatrix" do
+  render_views
+
+  role_matrix = "app/javascript/components/roles/RoleMatrix.tsx"
+
+  it "matches RoleMatrixProps" do
+    account = create(:account, :with_roles)
+
+    get :show, params: { id: account.id }
+
+    expect(response).to be_successful
+    props = react_component_props("RoleMatrix")
+    expect(props).to match_schema(role_matrix, "RoleMatrixProps")
+  end
+end
+```
+
+`match_schema` accepts a hash or an array of hashes. Given an array, it
+validates every item and fails on an empty one — in both directions, so
+`to_not match_schema` does not pass vacuously either. A page that stopped
+rendering the component fails rather than passing silently. The alternative
+construction, `expect(props).to all match_schema(...)`, would pass on an empty
+array.
+
+## API
+
+| Call                                    | Returns                                                     |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `TsSchemaSpec.schema_for(path, type)`   | a `JSONSchemer` schema scoped to that exported type          |
+| `match_schema(path, type)`              | matcher; validates a hash, or every item of an array         |
+| `react_component_props(name[, html])`   | array of props hashes, one per mount                         |
+| `TsSchemaSpec::Skill.check!(root)`      | raises if the installed skill is stale or missing            |
+| `TsSchemaSpec.configure`                | sets `tsconfig` and extra generator arguments                |
+| `TsSchemaSpec.clear_cache!`             | drops the generated-schema cache                             |
+
+`path` is resolved from wherever the suite runs, which is the Rails root in
+practice. Name the type at the assertion, so an example says which type it is
+checking. When several examples read the same source, bind the path to a local
+variable or a `let` — a constant assigned inside a `describe` block is global,
+so two spec files that both use one will collide.
+
+`schema_for` stays public, but is not needed when using the RSpec matcher,
+which calls it internally.
+
+## What a failure looks like
+
+```
+expected the payload to match Role (app/javascript/types/role.ts), but:
+ - /id: value at `/id` is not a number
+ - /created_at: object property at `/created_at` is a disallowed additional property
+ - (root): object at root is missing required properties: shortcode
+
+Payload was:
+{
+  "id": "1",
+  "name": "Nurse",
+  "created_at": "2026-09-11"
+}
+```
+
+## Best practices
+
+**Build records that cover the variations.** One response only exercises the
+branches it took. When the type has optional fields, enum values or nullable
+associations, create as many records, with as many different traits, as it
+takes to put those branches in the payload.
+
+**Tighten the type first.** A schema is only as strong as the type it comes
+from, and an all-optional type is satisfied by `{}` — asserting against one
+passes while catching nothing, which is worse than no spec, because it reads
+as coverage.
+
+- A field the server always sends: **required**.
+- A field that can be null: `string | null`, not `string?`.
+- A field with a fixed set of values: a literal union
+  (`"draft" | "published"`), not `string` — which catches a typo and a value
+  the consumer was never taught about.
+- An index signature or `Record<string, unknown>`: declare the keys the
+  component actually reads, required, alongside it.
+
+A literal union only stays honest while it tracks the Ruby enum it mirrors,
+which needs some way of sharing constants from Ruby into TypeScript — a
+generator, a shared JSON file, whatever suits your repo. That is outside this
+gem's scope, but with one in place, and a record for each value in the
+example, a drifted union fails here rather than in the browser.
+
+**Pass the whole collection.** `match_schema` validates every item and fails
+on an empty one. Avoid `expect(props).to all match_schema(...)`, which
+passes on an empty array, hiding an issue with generation.
+
+**Assert the response is successful first.** Otherwise a redirect or a 500
+arrives as a schema failure, and you debug the wrong thing.
+
+**Let the matcher do the shape checking.** Hand-written field assertions
+alongside it duplicate what the type already says, and go stale separately.
+
+**When it fails, fix Rails.** The type is the consumer's contract: if the
+component needs a field, the payload is wrong. Loosen the type only when the
+component genuinely does not need what it declares — loosening is always the
+quicker route to green, and it is how this stops catching anything.
+
+## Gotchas
+
+**Undeclared keys fail.** `ts-json-schema-generator` emits
+`additionalProperties: false`, so a payload carrying a key the TypeScript does
+not declare is an error, not a warning. That is deliberate — it catches Rails
+sending something nobody typed — but expect it when an `as_json` emits
+timestamps the React side ignores. Fix by declaring the field or narrowing the
+`only:`.
+
+## Cost
+
+One `npx ts-json-schema-generator` run per source file. Generated schemas are
+cached in memory, keyed by the file and the generator arguments, so reading
+three types out of one `.ts` costs one run rather than three, and changing
+`TsSchemaSpec.configure` regenerates rather than serving a stale schema.
+
+The cache lives in the process, so parallel test workers each pay for it once.
+
+## Troubleshooting
+
+| Symptom                                              | Cause                                                          |
+| ---------------------------------------------------- | -------------------------------------------------------------- |
+| `GenerationError: ... Is it exported?`               | the type has no `export`, or the name is misspelled             |
+| `GenerationError` listing a rerunnable command       | run it — the generator's own stderr is in the message           |
+| passes against an obviously wrong payload            | the type is all-optional, or an unresolved import became `{}`   |
+| `could not run npx ts-json-schema-generator`         | the generator is not in your `node_modules`                     |
+| `disallowed additional property`                     | see above — the payload sends what TypeScript does not declare  |
+| `has no data-react-props attribute`                  | hand-written markup, or a mount from another integration        |
+
+## What this can't catch
+
+Worth knowing before you rely on it.
+
+**Coverage is discipline-dependent.** This protects the actions somebody wrote
+a spec for; an uncovered endpoint is exactly as exposed as before. That is what
+the skill is for, and it is convention rather than enforcement.
+
+**It only checks what TypeScript declares.** If Rails *intends* to send a field
+nobody typed — say `as_json(only:)` carrying a misspelled attribute, which
+Rails drops silently — no generated schema requires it, so nothing fails. A
+structured serializer catches that class of mistake; this does not.
+
+## Alternatives
+
+An alternate methodology is to generate the TypeScript types from Ruby.
+
+[Typelizer](https://typelizer.dev/) and
+[types_from_serializers](https://github.com/ElMassimo/types_from_serializers)
+make Ruby canonical and generate the types, so drift becomes structurally
+impossible rather than something you test for. That beats this.
+
+They need serialization to exist somewhere nameable — they introspect Alba,
+AMS, Oj, Panko or oj_serializers. An app that is plain `as_json` and
+`render json:`, deciding payload shapes inline at each call site, has no
+artifact for a generator to read. This gem is for that case: if a shape only
+exists at its call site, the only way to learn it is to run the action and
+look.
+
+The other camp — [json_matchers](https://github.com/thoughtbot/json_matchers),
+committee, rswag — validates against a hand-maintained JSON Schema file. That
+is a third artifact to keep in sync with both sides, which is the same drift
+problem relocated.
+
+One gap stays open whichever you pick: `react_component` props. Typelizer
+types serializer output and knows nothing about the outer props object a view
+assembles, so nothing generated from your serializers covers it.

data/lib/ts_schema_spec/config.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TsSchemaSpec
+  # Repo-level generator settings. `tsconfig` matters more than it looks: an
+  # import the generator cannot resolve becomes an empty schema, which
+  # validates anything, so a repo using path aliases needs this set or its
+  # aliased types silently assert nothing.
+  class Config
+    attr_accessor :tsconfig, :generator_args
+
+    def initialize
+      @generator_args = []
+    end
+
+    def to_args
+      args = []
+      args += ["--tsconfig", tsconfig.to_s] if tsconfig
+      args + Array(generator_args)
+    end
+  end
+end

data/lib/ts_schema_spec/generator.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module TsSchemaSpec
+  module Generator
+    COMMAND = %w[npx ts-json-schema-generator].freeze
+
+    class << self
+      def generate(source)
+        command = command_for(source)
+        stdout, stderr, status = Open3.capture3(*command)
+
+        unless status.success?
+          raise GenerationError, failure(command, stderr)
+        end
+
+        JSON.parse(stdout)
+      rescue JSON::ParserError => e
+        raise GenerationError, failure(command, "#{e.message}\n\n#{stderr}")
+      rescue Errno::ENOENT
+        raise GenerationError, missing_generator(command)
+      end
+
+      def command_for(source)
+        COMMAND + ["--path", source.to_s, "--no-type-check"] + TsSchemaSpec.config.to_args
+      end
+
+      private
+
+      # npx's own phrasing for "the package is not installed". Anything looser
+      # — a bare "not found" — swallows the generator's real diagnostic.
+      MISSING_PACKAGE = /missing packages|could not determine executable|npx.*not found|not found.*npx/i
+
+      def missing_generator(command, stderr = nil)
+        message = <<~MSG
+          could not run #{COMMAND.join(" ")}.
+
+          The generator parses your app's TypeScript, so it resolves from your
+          node_modules rather than from the gem:
+
+            npm install --save-dev ts-json-schema-generator
+
+          Rerun: #{command.join(" ")}
+        MSG
+        return message if stderr.to_s.strip.empty?
+
+        "#{message}\n#{stderr.strip}\n"
+      end
+
+      def failure(command, stderr)
+        return missing_generator(command, stderr) if stderr.to_s.match?(MISSING_PACKAGE)
+
+        <<~MSG
+          ts-json-schema-generator failed.
+
+          Rerun: #{command.join(" ")}
+
+          #{stderr.strip}
+        MSG
+      end
+    end
+  end
+end

data/lib/ts_schema_spec/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module TsSchemaSpec
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/ts_schema_spec.rake", __dir__)
+    end
+  end
+end

data/lib/ts_schema_spec/react_component_props.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+require "nokogiri"
+
+require_relative "../ts_schema_spec"
+
+module TsSchemaSpec
+  # Pulls props out of react-rails mount points in rendered HTML, so an HTML
+  # action's props can be schema-checked the same way a JSON payload is.
+  # Needs `render_views`.
+  module ReactComponentProps
+    def react_component_props(component_name, html = nil)
+      html ||= response.body
+
+      Nokogiri::HTML(html).css("[data-react-class]").filter_map do |node|
+        next unless react_class_matches?(node["data-react-class"], component_name)
+
+        parse_props(node, component_name)
+      end
+    end
+
+    private
+
+    # react-rails namespaces a component either way: "admin/SidebarNav" from
+    # the asset path, "Admin.SidebarNav" from the global its UJS resolves.
+    NAMESPACE_SEPARATOR = %r{[./]}
+
+    def react_class_matches?(react_class, component_name)
+      react_class == component_name ||
+        react_class.to_s.split(NAMESPACE_SEPARATOR).last == component_name
+    end
+
+    def parse_props(node, component_name)
+      raw = node["data-react-props"]
+      raise Error, "the #{component_name} mount has no data-react-props attribute" if raw.nil?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise Error, "could not parse data-react-props for #{component_name}: #{e.message}"
+    end
+  end
+end

data/lib/ts_schema_spec/rspec.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require "rspec/expectations"
+
+require_relative "../ts_schema_spec"
+
+module TsSchemaSpec
+  # A payload is often a collection — every mount of a component on the page,
+  # every record in an index response. Validating each item against an object
+  # schema is the common case, so the matcher handles it rather than leaving
+  # callers to reach for `all`, which passes vacuously on an empty collection
+  # and so silently asserts nothing.
+  module Matching
+    EMPTY = :empty_collection
+
+    BRANCHES = %w[anyOf oneOf allOf].freeze
+
+    class << self
+      def errors(schema, actual)
+        return schema.validate(actual).to_a unless collection?(schema, actual)
+        return [EMPTY] if actual.empty?
+
+        actual.each_with_index.flat_map do |item, index|
+          schema.validate(item).to_a.map do |error|
+            error.merge("data_pointer" => "/#{index}#{error["data_pointer"]}")
+          end
+        end
+      end
+
+      def empty?(errors)
+        errors == [EMPTY]
+      end
+
+      private
+
+      def collection?(schema, actual)
+        actual.is_a?(Array) && !describes_array?(schema)
+      end
+
+      # A type can reach "array" through a union or an alias, so the literal
+      # `"type"` of the schema is not enough: `Role[] | null` and
+      # `type Roles = RoleList` both describe an array without saying so here.
+      def describes_array?(schema, value = schema.value, seen = [])
+        return false unless value.is_a?(Hash)
+
+        if (pointer = value["$ref"])
+          return false if seen.include?(pointer)
+
+          return describes_array?(schema, resolve(schema, pointer), seen + [pointer])
+        end
+
+        return true if Array(value["type"]).include?("array")
+
+        BRANCHES.any? do |branch|
+          Array(value[branch]).any? { |option| describes_array?(schema, option, seen) }
+        end
+      end
+
+      def resolve(schema, pointer)
+        schema.ref(pointer).value
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end
+
+RSpec::Matchers.define :match_schema do |source, type|
+  def validation_errors(actual, source, type)
+    schema = TsSchemaSpec.schema_for(source, type)
+    @errors = TsSchemaSpec::Matching.errors(schema, actual)
+  end
+
+  # Worded for both directions: this message is what an empty collection gets
+  # whichever way the assertion was written.
+  def empty_collection_message
+    <<~MSG
+      expected a non-empty collection, but it was empty, so nothing was
+      validated.
+
+      Usually the component was not rendered on the page, or no records
+      existed for the endpoint to serialize. If an empty result is what you
+      meant to assert, use `be_empty` or `eq([])` — match_schema on an empty
+      collection checks nothing.
+    MSG
+  end
+
+  match do |actual|
+    validation_errors(actual, source, type).empty?
+  end
+
+  # An empty collection fails either way round: negating the matcher would
+  # otherwise turn the vacuous pass back on.
+  match_when_negated do |actual|
+    errors = validation_errors(actual, source, type)
+    errors.any? && !TsSchemaSpec::Matching.empty?(errors)
+  end
+
+  failure_message do |actual|
+    next empty_collection_message if TsSchemaSpec::Matching.empty?(@errors)
+
+    details = @errors.map do |error|
+      pointer = error["data_pointer"]
+      pointer = "(root)" if pointer.nil? || pointer.empty?
+      " - #{pointer}: #{error["error"]}"
+    end
+
+    <<~MSG
+      expected the payload to match #{type} (#{source}), but:
+      #{details.join("\n")}
+
+      Payload was:
+      #{JSON.pretty_generate(actual)}
+    MSG
+  end
+
+  failure_message_when_negated do |actual|
+    next empty_collection_message if TsSchemaSpec::Matching.empty?(@errors)
+
+    "expected the payload not to match #{type} (#{source}), but it did:\n#{JSON.pretty_generate(actual)}"
+  end
+end

data/lib/ts_schema_spec/skill.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require_relative "../ts_schema_spec"
+
+module TsSchemaSpec
+  # The skill is instructions an agent follows to write these specs, so a
+  # silently outdated copy teaches the wrong API. The copy carries the gem
+  # version and `check!` fails when the two diverge.
+  module Skill
+    NAME = "react-prop-type-spec"
+    INSTALL_PATH = ".claude/skills/#{NAME}/SKILL.md"
+    SOURCE_PATH = File.expand_path("../../skills/#{NAME}/SKILL.md", __dir__)
+    STAMP = "ts_schema_spec_version"
+
+    class << self
+      def install(root = Dir.pwd)
+        destination = File.join(root, INSTALL_PATH)
+        FileUtils.mkdir_p(File.dirname(destination))
+        File.write(destination, stamped(File.read(SOURCE_PATH)))
+        destination
+      end
+
+      def installed_version(root = Dir.pwd)
+        contents = File.read(File.join(root, INSTALL_PATH))
+        contents[/^#{STAMP}: (.+)$/, 1]
+      rescue Errno::ENOENT
+        nil
+      end
+
+      def check!(root = Dir.pwd)
+        found = installed_version(root)
+        return true if found == TsSchemaSpec::VERSION
+
+        raise Error, <<~MSG
+          The #{NAME} skill in #{INSTALL_PATH} is #{found ? "stale (#{found})" : "not installed"};
+          the gem is #{TsSchemaSpec::VERSION}.
+
+          Run: bundle exec rake ts_schema_spec:install_skill
+        MSG
+      end
+
+      private
+
+      def stamped(contents)
+        body = contents.sub(/^#{STAMP}: .*\n/, "")
+        stamped = body.sub(/\A---\n/, "---\n#{STAMP}: #{TsSchemaSpec::VERSION}\n")
+
+        if stamped == body
+          raise Error, <<~MSG
+            #{SOURCE_PATH} does not open with YAML frontmatter, so there is
+            nowhere to put the version stamp that check! reads. Installing it
+            unstamped would fail that check for good.
+          MSG
+        end
+
+        stamped
+      end
+    end
+  end
+end

data/lib/ts_schema_spec/tasks/ts_schema_spec.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+namespace :ts_schema_spec do
+  desc "Copy the react-prop-type-spec agent skill into .claude/skills"
+  task :install_skill do
+    require "ts_schema_spec/skill"
+
+    destination = TsSchemaSpec::Skill.install(defined?(Rails) ? Rails.root.to_s : Dir.pwd)
+    puts "Installed #{TsSchemaSpec::Skill::NAME} v#{TsSchemaSpec::VERSION} to #{destination}"
+    puts "Commit it — Claude Code reads skills from the working tree."
+  end
+end

data/lib/ts_schema_spec/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TsSchemaSpec
+  VERSION = "0.5.4"
+end

data/lib/ts_schema_spec.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+
+require_relative "ts_schema_spec/version"
+require_relative "ts_schema_spec/config"
+require_relative "ts_schema_spec/generator"
+
+require_relative "ts_schema_spec/railtie" if defined?(Rails::Railtie)
+
+module TsSchemaSpec
+  class Error < StandardError; end
+  class GenerationError < Error; end
+
+  class << self
+    def schema_for(source, type)
+      validate_arguments!(source, type)
+      document = document_for(source)
+
+      unless document.fetch("definitions", {}).key?(type)
+        raise GenerationError, <<~MSG
+          #{source} does not define #{type.inspect}.
+
+          Generated definitions: #{document.fetch("definitions", {}).keys.sort.join(", ")}
+
+          Is it exported?
+        MSG
+      end
+
+      JSONSchemer.schema(document).ref("#/definitions/#{type}")
+    end
+
+    def clear_cache!
+      documents.clear
+    end
+
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config)
+      clear_cache!
+    end
+
+    def reset_config!
+      @config = nil
+      clear_cache!
+    end
+
+    private
+
+    PATH_LIKE = %r{/|\.tsx?\z}
+
+    def validate_arguments!(source, type)
+      raise ArgumentError, "expects a path and a type name, e.g. schema_for(\"app/javascript/Foo.tsx\", \"FooProps\")" if type.nil?
+
+      return unless type.to_s.match?(PATH_LIKE) && !source.to_s.match?(PATH_LIKE)
+
+      raise ArgumentError, <<~MSG
+        the arguments look reversed: #{source.inspect} was given as the source
+        file and #{type.inspect} as the type name. Expected (path, type).
+      MSG
+    end
+
+    def document_for(source)
+      documents[[File.expand_path(source.to_s), config.to_args]] ||= Generator.generate(source)
+    end
+
+    def documents
+      @documents ||= {}
+    end
+  end
+end

data/skills/react-prop-type-spec/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: react-prop-type-spec
+description: >
+  Write or update RSpec tests that use match_schema to verify a Rails
+  endpoint's payload matches the TypeScript type that consumes it. TRIGGER
+  automatically (without being asked) whenever data crossing from Ruby to
+  TypeScript is added or changed: adding a controller action; changing
+  serialization in an existing one (helper method, as_json fields, included
+  associations); adding or renaming a key in a render json: response or in
+  props handed to a component; converting a Rails-mounted component from .jsx
+  to .tsx; deleting a component's propTypes; or rendering an already-typed
+  component from an action that has no match_schema spec. React is the common
+  case, not a requirement — a Stimulus controller or a plain fetch client
+  reading the payload counts the same. Invoked as /react-prop-type-spec.
+---
+
+A spec is owed any time data is handed from Ruby to TypeScript — not only when
+something changes, and including where there is no Ruby diff at all. Two rules
+keep that from multiplying:
+
+- **Repeated mounts of one component are a single example.**
+  `react_component_props` returns every mount and `match_schema` checks each.
+- **Assert on the component Rails mounts.** A child receiving props from its
+  parent is covered transitively; use the parent's props type.
+
+## Step 0 — Already covered?
+
+Covered = the spec for **the action rendering it** has a `match_schema` example
+on that component. A sibling component, or the same component from another
+action, is not coverage. Covered → stop.
+
+## Step 1 — Find the TypeScript consumer
+
+- **JSON** (`render json:`): find the `fetch`/`axios` call and the type it
+  parses into.
+- **HTML** (`react_component`): find the view, the component it mounts, and its
+  props interface.
+
+React is the common case, not a requirement — a payload read by a Stimulus
+controller, a plain fetch client or any other TypeScript module is checked the
+same way, via `response.parsed_body`. Only `react_component_props` is
+React-specific.
+
+No TypeScript consumer at all → exit the skill.
+
+## Step 2 — Export the type
+
+`ts-json-schema-generator` only targets exported types. Add `export` if it is
+missing.
+
+## Step 3 — Tighten the type
+
+An all-optional type is satisfied by `{}`, so asserting on one asserts nothing.
+
+- A field the server always sends: **required**.
+- A field the server can send as null: `string | null`, not `string?`.
+- A field with a fixed set of values: a literal union (`"draft" | "published"`),
+  not `string`.
+- An index signature or `Record<string, unknown>`: keep the keys the component
+  actually reads **required alongside it**.
+
+This edits the app's TypeScript rather than the test, so say that you did it. If
+it cannot be tightened now, report which fields are unconstrained rather than
+implying the spec covers them.
+
+## Step 4 — Write the test
+
+| Action | Data source |
+| ------ | ----------- |
+| `render json:` | `response.parsed_body["key"]` |
+| `react_component` | `react_component_props("ComponentName")` |
+
+`react_component_props` returns **an array**, one entry per mount, and needs
+`render_views`. Pass it straight to `match_schema`: it validates every entry
+and fails on an empty collection. Never wrap it in `all`, which iterates zero
+times on an empty array and asserts nothing.
+
+```ruby
+describe "the props handed to MyComponent" do
+  render_views
+
+  it "matches MyComponentProps" do
+    record = create(:factory_name, trait_a: true)
+    create(:factory_name, :some_trait)
+
+    get :show, params: { id: record.id }
+
+    expect(response).to be_successful
+    props = react_component_props("MyComponent")
+    expect(props).to match_schema("app/javascript/MyComponent.tsx", "MyComponentProps")
+  end
+end
+```
+
+Name the file and type at the assertion. When several examples read the same
+source, bind the path to a constant or a let variable.
+
+Rules:
+
+- Build multiple records with different traits, so optional fields, enum values
+  and nil associations are actually exercised. Use existing factory traits.
+- Assert `response` is successful before asserting shape.
+- Let `match_schema` do the shape checking; no hand-written field assertions.
+- Several components in one action: an example each, or one example marked
+  `:aggregate_failures` if rendering the page is expensive — without it the
+  first mismatch hides the rest.
+- Do not write a spec that only checks `response.status`, and do not duplicate
+  an existing `match_schema` for the same action.
+- **When it fails, fix Rails.** The type is the consumer's contract: if the
+  component needs a field, the payload is wrong. Loosening the type is always
+  the quicker route to green, and it is how this stops catching anything.
+
+## Step 5 — Run it
+
+```
+bundle exec rspec spec/controllers/my_controller_spec.rb --example "MyComponent"
+```
+
+## When a rule here does not fit
+
+The gem's README carries the reasoning behind these rules, plus troubleshooting
+for generator errors. It ships inside the gem, so this reads the version the
+app actually has:
+
+```
+cat "$(bundle show ts_schema_spec)/README.md"
+```
+
+Sections: **Best practices**, **Gotchas**, **Troubleshooting**. If the command
+fails, carry on — the rules above stand on their own.

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: ts_schema_spec
+version: !ruby/object:Gem::Version
+  version: 0.5.4
+platform: ruby
+authors:
+- Vernon Coffey
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.10'
+email:
+- vccoffey@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/ts_schema_spec.rb
+- lib/ts_schema_spec/config.rb
+- lib/ts_schema_spec/generator.rb
+- lib/ts_schema_spec/railtie.rb
+- lib/ts_schema_spec/react_component_props.rb
+- lib/ts_schema_spec/rspec.rb
+- lib/ts_schema_spec/skill.rb
+- lib/ts_schema_spec/tasks/ts_schema_spec.rake
+- lib/ts_schema_spec/version.rb
+- skills/react-prop-type-spec/SKILL.md
+homepage: https://github.com/nitidbit/ts_schema_spec
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nitidbit/ts_schema_spec
+  source_code_uri: https://github.com/nitidbit/ts_schema_spec
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Assert that a Rails payload matches the TypeScript type the React side consumes.
+test_files: []