ts_schema_spec 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcc02f190a1fcbe41e89aaab3f8714c6cc5d189372297d4bfb716af2d7a97e8e
-  data.tar.gz: ac904c2a071466249b79f9b514b4f5c06ab8f746b17a00ac3703dae257ad93d3
+  metadata.gz: 1d8e48873074ac373b562a69c895679dc7afbe1a21d81df9910f8e9f766c2fcc
+  data.tar.gz: bdc53ec65a7c01ff8c63d9ce95525cf01587d25bbf0726b7566a129724401fff
 SHA512:
-  metadata.gz: b42d96309d3f9beaa23ac086f5057c0a87a281d18548aad96d7d24cb6695e84920301d5041a22a9c14f60f8193d4d99ae255dcc4b7262675a5b8d779ad49fc6b
-  data.tar.gz: 5c7ac0e02c49f4c363221e8569e510eb068ba780930a219080b339150a647dcb7dfc010cececa1cbde81e0378c59926ea2ca85742476a306df51bf2ca8d03db5
+  metadata.gz: 482f0478728009f5bc10ac65f2a9046c5c1d28393d394bddfbd3c59ad4f029a26d9b9eb9587006d4b065756c3b6e6fc59eea95fc60e4f136b8454760cc7eb0e7
+  data.tar.gz: 6a65b04776bd6c9eb5c12a6bf96b97cbd939d6e7215171e71e71c10f8fbee8f9c4925bb59444110714d262a05e4c0793d73c62da394b48798271bb689d56012c

data/README.md

@@ -8,7 +8,7 @@ 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`
+React is the case this gem was built for, not a requirement. `match_ts_schema`
 checks any payload against any exported TypeScript type, so a Stimulus
 controller or a plain fetch client works the same way.
 
@@ -101,7 +101,7 @@ it "matches AccountPayload" do
 
   expect(response).to be_successful
   expect(response.parsed_body["accounts"])
-    .to match_schema("app/javascript/types/account.ts", "AccountPayload")
+    .to match_ts_schema("app/javascript/types/account.ts", "AccountPayload")
 end
 ```
 
@@ -134,28 +134,31 @@ describe "the props handed to RoleMatrix" do
 
     expect(response).to be_successful
     props = react_component_props("RoleMatrix")
-    expect(props).to match_schema(role_matrix, "RoleMatrixProps")
+    expect(props).to match_ts_schema(role_matrix, "RoleMatrixProps")
   end
 end
 ```
 
-`match_schema` accepts a hash or an array of hashes. Given an array, it
+`match_ts_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
+`to_not match_ts_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.
+construction, `expect(props).to all match_ts_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                             |
+| Call                                  | Returns                                              |
+| ------------------------------------- | ---------------------------------------------------- |
+| `TsSchemaSpec.schema_for(path, type)` | a `JSONSchemer` schema scoped to that exported type  |
+| `match_ts_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                     |
+
+`match_ts_schema` was called `match_schema` before 0.6.1. The old name still
+works but is deprecated and will be removed.
 
 `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
@@ -208,8 +211,8 @@ 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
+**Pass the whole collection.** `match_ts_schema` validates every item and fails
+on an empty one. Avoid `expect(props).to all match_ts_schema(...)`, which
 passes on an empty array, hiding an issue with generation.
 
 **Assert the response is successful first.** Otherwise a redirect or a 500
@@ -243,14 +246,14 @@ 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        |
+| 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
 
@@ -260,7 +263,7 @@ Worth knowing before you rely on it.
 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
+**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.

data/lib/ts_schema_spec/rspec.rb

@@ -66,7 +66,7 @@ module TsSchemaSpec
   end
 end
 
-RSpec::Matchers.define :match_schema do |source, type|
+RSpec::Matchers.define :match_ts_schema do |source, type|
   def validation_errors(actual, source, type)
     schema = TsSchemaSpec.schema_for(source, type)
     @errors = TsSchemaSpec::Matching.errors(schema, actual)
@@ -81,7 +81,7 @@ RSpec::Matchers.define :match_schema do |source, type|
 
       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
+      meant to assert, use `be_empty` or `eq([])` — match_ts_schema on an empty
       collection checks nothing.
     MSG
   end
@@ -121,3 +121,12 @@ RSpec::Matchers.define :match_schema do |source, type|
     "expected the payload not to match #{type} (#{source}), but it did:\n#{JSON.pretty_generate(actual)}"
   end
 end
+
+module RSpec
+  module Matchers
+    def match_schema(...)
+      RSpec.deprecate("match_schema", replacement: "match_ts_schema")
+      match_ts_schema(...)
+    end
+  end
+end

data/lib/ts_schema_spec/version.rb

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

data/skills/ts-schema-spec/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ts-schema-spec
 description: >
-  Write or update RSpec tests that use match_schema to verify a Rails
+  Write or update RSpec tests that use match_ts_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
@@ -9,7 +9,7 @@ description: >
   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
+  component from an action that has no match_ts_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 /ts-schema-spec.
 ---
@@ -19,15 +19,15 @@ 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.
+  `react_component_props` returns every mount and `match_ts_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.
+Covered = the spec for **the action rendering it** has a `match_ts_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
 
@@ -65,13 +65,13 @@ implying the spec covers them.
 
 ## Step 4 — Write the test
 
-| Action | Data source |
-| ------ | ----------- |
-| `render json:` | `response.parsed_body["key"]` |
+| 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
+`render_views`. Pass it straight to `match_ts_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.
 
@@ -87,7 +87,7 @@ describe "the props handed to MyComponent" do
 
     expect(response).to be_successful
     props = react_component_props("MyComponent")
-    expect(props).to match_schema("app/javascript/MyComponent.tsx", "MyComponentProps")
+    expect(props).to match_ts_schema("app/javascript/MyComponent.tsx", "MyComponentProps")
   end
 end
 ```
@@ -100,12 +100,12 @@ 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.
+- Let `match_ts_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.
+  an existing `match_ts_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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ts_schema_spec
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Vernon Coffey