ruact 0.0.10 → 0.0.12

data/spec/readme_spec.rb

@@ -1,282 +0,0 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-require "nokogiri"
-require "pathname"
-
-# Story 5.14 — the README gate that lives INSIDE this repository.
-#
-# `README.md` is not an ordinary readme: GitHub renders it on the gem's own
-# repository page, `source_code_uri` points at it, and `spec.files` packages it
-# *inside* the built `.gem`. Until this story it was still `bundle gem`
-# boilerplate ("TODO: Delete this and the text below"), and that boilerplate had
-# already shipped to RubyGems.
-#
-# The planning monorepo has a command-spine gate
-# (`docs/examples/getting-started/scripts/check-commands.mjs`) that reads this
-# file through the `gem/` submodule and checks its quick start against ONE
-# canonical greenfield sequence — the SPINE, which is the single source of
-# truth. But a merge in THIS repository fires nothing over there, so a
-# README-only PR here would stay unchecked until somebody bumped the submodule
-# pointer.
-#
-# Hence the deliberate duplication below: `expected_quick_start` is a literal
-# copy of the quick-start block, owned by this spec, and the monorepo gate
-# verifies that literal against the canonical SPINE. The dependency runs one way
-# only — this spec reads nothing outside the gem repository, because a public
-# artifact that cannot be verified in its own repository is not verifiable.
-RSpec.describe "README.md", :story_5_14 do
-  subject(:readme) { root.join("README.md").read }
-
-  let(:root) { Pathname.new(File.expand_path("..", __dir__)) }
-
-  # Every literal `bundle gem` leaves behind. Each one was present before this
-  # story; any of them coming back means the scaffolding was re-pasted.
-  let(:boilerplate) do
-    [
-      "TODO:",
-      "UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG",
-      "[USERNAME]",
-      "Welcome to your new gem",
-      "Put your Ruby code in the file",
-      "bin/console",
-      "bundle exec rake release"
-    ]
-  end
-
-  # Harness-only gem sources. They exist so the monorepo's playgrounds can test
-  # the working tree; a reader who copies one installs nothing.
-  let(:path_gem_sources) do
-    [
-      /(^|\s)gem\s+["']ruact["']\s*,\s*path:/,
-      /--path(\s|=)/
-    ]
-  end
-
-  # The quick-start block, byte for byte. Changing it here without changing the
-  # monorepo SPINE (or the other way round) turns the monorepo gate red.
-  let(:expected_quick_start) do
-    <<~BASH
-      # 1. A throwaway app to try it in
-      rails new myapp --skip-javascript && cd myapp
-
-      # 2. Add the gem
-      bundle add ruact
-
-      # 3. Write the config, the layout wiring and an AGENTS.md — then run npm install
-      rails generate ruact:install
-
-      # 4. Rails + Vite, one command
-      bin/dev
-    BASH
-  end
-
-  # `[text](target)` and `![alt](target)`, inline-title form allowed.
-  def markdown_link_targets(markdown)
-    markdown.scan(/\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/).flatten
-  end
-
-  # Story 5.2 — the demo reference, pinned BYTE FOR BYTE.
-  #
-  # The first version of this gate hand-rolled HTML and CommonMark recognition
-  # out of regexes, and review corrected it in three consecutive rounds:
-  # `\bsrc=` matched `data-src=`, a literal `>` inside an attribute ended the
-  # tag early, fences were only recognised at column 0, then unterminated
-  # fences were not recognised at all, then unquoted attribute values were
-  # invisible. Those are not five bugs. Neither HTML nor CommonMark is a
-  # regular language, so that list has no end, and a gate whose coverage is
-  # "whatever the regex happens to know this week" is not a gate.
-  #
-  # Replaced by three statements that are TOTAL:
-  #
-  #   1. the reference is pinned literally — the same move `expected_quick_start`
-  #      above already makes for the quick start;
-  #   2. the file is allowed EXACTLY ONE raw `<img>`, counted at the byte level;
-  #      and
-  #   3. the parsed document holds exactly one LIVE `<img>` element, equal to
-  #      the pinned one attribute for attribute.
-  #
-  # (1) and (2) together say something the old scanner could only approximate:
-  # every raw image reference in this README is the pinned one. A second `<img>`
-  # anywhere — including inside a fenced example, terminated or not — turns
-  # this red and has to be gated deliberately rather than slipping through a
-  # blind spot. (3) says the thing bytes cannot: that it renders. The pinned
-  # block wrapped in an HTML comment satisfies (1) and (2) and shows nothing.
-  #
-  # Attributes are then read with Nokogiri, already a runtime dependency of this
-  # gem (see the gemspec), so unquoted values, `>` inside a value and `data-src`
-  # are PARSED rather than pattern-matched. What that scope does and does not
-  # promise is written down in the monorepo's gate inventory,
-  # docs/examples/getting-started/README.md § "What is still outside both gates".
-  def expected_demo_img
-    <<~HTML
-      <img src="https://ruact.dev/readme-write-verify.gif" width="800"
-           alt="An ERB template holding a &lt;LikeButton likes=&#123;@likes&#125; /&gt; tag, and the &quot;use client&quot; React component that tag resolves to. The component renders in a browser and its count changes when it is clicked. Children are then put inside the tag — the JSX habit — and the next request stops server-side with Ruact::ChildrenNotSupportedError, which names the component, the template file and line, and the fix. The children come out again and the page renders." />
-    HTML
-  end
-
-  def demo_src
-    "https://ruact.dev/readme-write-verify.gif"
-  end
-
-  # Parsed from the pinned literal, exactly as `expected_quick_start` is the
-  # authority for the quick start: one example asserts the README contains
-  # these bytes, and the rest read meaning off them. The chain is
-  # README -> literal -> parser, and the first link is what makes it honest.
-  def demo_node
-    Nokogiri::HTML5.fragment(expected_demo_img).at_css("img")
-  end
-
-  # Byte-level and case-insensitive on purpose: no parser, no markdown, nothing
-  # to have a blind spot. `<IMG`, `<img\n`, an `<img` inside a fence — all count.
-  def raw_img_count(markdown)
-    markdown.scan(/<img\b/i).length
-  end
-
-  # …and the same parser turned on the README ITSELF, because the two byte-level
-  # facts above are about bytes, not about rendering: wrap the pinned block in
-  # an HTML comment and the literal is still present and the raw count is still
-  # one, while GitHub shows nothing at all (verified — `include`=true, raw=1,
-  # live nodes=0). Nokogiri is what decides whether a tag is an element or a
-  # comment, so it is what the "it renders" half of this gate has to ask.
-  def readme_img_nodes
-    Nokogiri::HTML5.fragment(readme).css("img")
-  end
-
-  # Absolute URLs, anchors and mailto: links are somebody else's problem; on-disk
-  # targets are ours.
-  def relative(targets)
-    targets.reject { |target| target.start_with?("http://", "https://", "#", "mailto:") }
-  end
-
-  def bash_blocks(markdown)
-    markdown.scan(/^```bash[ \t]*\n(.*?)^```/m).flatten
-  end
-
-  it "carries none of the `bundle gem` boilerplate" do
-    present = boilerplate.select { |literal| readme.include?(literal) }
-
-    expect(present).to be_empty,
-                       "README.md still carries bundler scaffolding: #{present.inspect}"
-  end
-
-  it "links only to files that exist in this repository" do
-    targets = relative(markdown_link_targets(readme) + [demo_node["src"]])
-    missing = targets.reject { |target| root.join(target.split("#").first.to_s).exist? }
-
-    expect(targets).not_to be_empty, "expected the README to link at least one repo-relative file"
-    expect(missing).to be_empty,
-                       "README.md links files that do not exist in the gem repository: #{missing.inspect}"
-  end
-
-  # Story 5.2 — the demo GIF is a documentation asset hosted with the site, so
-  # this repository stays free of binaries: no `.gem` download and no clone
-  # pays for it. The consequence is that the reference is an absolute URL, and
-  # an absolute URL cannot be resolved on disk here — the monorepo puts it in
-  # `website/scripts/verify-urls.mjs`'s PATHS, checked against the deployed
-  # site, so a dead image goes red there instead of rotting silently.
-  it "carries the write→verify demo reference, byte for byte" do
-    expect(readme).to include(expected_demo_img),
-                      "the demo reference in README.md drifted from the literal this spec pins. " \
-                      "Change both or neither — and if the recording itself changed, see " \
-                      "readme_demo_message_spec.rb."
-  end
-
-  # The other half of the pin: because there is exactly ONE raw `<img>` and the
-  # example above proves it is the pinned one, "the pinned literal is present"
-  # and "every raw image in this file is checked" are the same statement.
-  it "carries exactly one raw <img>, so the pin covers every raw image in the file" do
-    expect(raw_img_count(readme)).to eq(1),
-                                     "README.md has #{raw_img_count(readme)} raw <img> tags. This gate is " \
-                                     "written for exactly one — the demo, pinned literally. A second image " \
-                                     "must be gated deliberately, not left to a scanner's blind spots."
-  end
-
-  # And the demo is LIVE, not merely present. Bytes inside an HTML comment
-  # satisfy both statements above and render nothing; only a parser can tell
-  # the difference, so the README itself is parsed and the node it yields must
-  # be the pinned one, attribute for attribute.
-  it "renders the demo as a real element, not as bytes inside a comment" do
-    nodes = readme_img_nodes
-
-    expect(nodes.length).to eq(1),
-                            "README.md parses to #{nodes.length} live <img> element(s); the demo must be " \
-                            "exactly one, and must not be commented out."
-    expect(nodes.first.attributes.transform_values(&:value))
-      .to eq(demo_node.attributes.transform_values(&:value))
-  end
-
-  it "keeps the demo hosted with the site rather than committed here" do
-    expect(demo_node["src"]).to eq(demo_src)
-
-    # `git ls-files` and not a filesystem glob, because that is precisely what
-    # `spec.files` packages (ruact.gemspec) — untracked build output is not the
-    # question here, and coverage/ is full of it.
-    tracked = IO.popen(%w[git ls-files -z], chdir: root.to_s, err: IO::NULL) do |ls|
-      ls.readlines("\x0", chomp: true)
-    end
-    committed_media = tracked.grep(/\.(gif|mp4|webm|webp)\z/i)
-
-    expect(committed_media).to be_empty,
-                               "media committed under gem/ ships inside every `.gem` and stays in the " \
-                               "clone history forever: #{committed_media.inspect}"
-  end
-
-  # The alt text is the only thing a screen-reader user — or an agent reading
-  # the README as text — gets. "demo" is not a description.
-  it "describes the demo's arc in its alt text" do
-    # Nokogiri resolves the entities, so this reads what a screen reader reads:
-    # `&lt;LikeButton` is the tag the demo shows, not four literal characters.
-    alt = demo_node["alt"].to_s
-
-    expect(alt.split.length).to be > 40, "the demo's alt text does not describe the arc: #{alt.inspect}"
-    expect(alt).to include("Ruact::ChildrenNotSupportedError")
-    expect(alt).not_to match(/\bbuild\b/i),
-                       "the failure the demo shows happens server-side at render, not at build — " \
-                       "see Story 5.2 AC4"
-  end
-
-  # Story 5.2, learned the expensive way: YARD parses README.md as the docs'
-  # main file and read `{@likes}` in the demo's alt text as a link macro it
-  # could not resolve — and `--fail-on-warning` turned that into a red REQUIRED
-  # check, for a README edit, in a job whose output says nothing about READMEs.
-  # Braces belong in prose as `&#123;`/`&#125;`: GitHub renders them, YARD never
-  # sees them.
-  #
-  # SCOPE, deliberately: this checks the pinned demo block, not the whole file.
-  # Knowing which parts of a markdown document YARD linkifies means knowing
-  # where the fenced blocks are, and this gate no longer recognises fences —
-  # that is the trade this redesign makes. `yard --fail-on-warning` in this
-  # repository's own CI is the TOTAL gate; this example exists so the one line
-  # that actually tripped it fails locally, in the suite that owns the README,
-  # naming the cause.
-  it "keeps YARD link macros out of the demo block, which is what reddened the docs job" do
-    # `{@ivar}`, `{Class}`, `{Class::Nested}`, `{Class#method}`, `{Class.method}`
-    # — the shapes YARD resolves. It does not try to resolve anything with a
-    # space in it, which is why the prose's `{ post: … }` elsewhere is safe.
-    macros = expected_demo_img.scan(/\{(?:@\w+|[A-Z][\w:.#]*)\}/)
-
-    expect(macros).to be_empty,
-                      "the demo block contains #{macros.inspect}, which YARD tries to resolve as a " \
-                      "link and `yard --fail-on-warning` fails on. Use &#123; / &#125;."
-  end
-
-  it "shows no harness-only `path:` gem source a reader could copy" do
-    offenders = path_gem_sources.filter_map { |pattern| pattern.source if readme.match?(pattern) }
-
-    expect(offenders).to be_empty,
-                         "README.md shows a harness-only gem source (#{offenders.inspect}) — " \
-                         "a reader who copies it installs nothing"
-  end
-
-  it "pins the quick start to the canonical greenfield sequence" do
-    expect(bash_blocks(readme).first).to eq(expected_quick_start),
-                                         "the README quick start drifted. It is checked against the monorepo's " \
-                                         "canonical SPINE (docs/examples/getting-started/scripts/" \
-                                         "check-commands.mjs); change both or neither."
-  end
-
-  it "keeps the quick start in a ```bash fence, the only language the monorepo gate reads" do
-    expect(readme).to include("```bash\n#{expected_quick_start}```")
-  end
-end

data/spec/ruact/client_manifest_spec.rb

@@ -1,270 +0,0 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-require "tempfile"
-
-module Ruact
-  RSpec.describe ClientManifest do
-    let(:manifest_data) do
-      {
-        "LikeButton" => {
-          "id" => "/LikeButton.jsx",
-          "name" => "LikeButton",
-          "chunks" => ["/LikeButton.jsx"]
-        }
-      }
-    end
-
-    let(:dual_manifest_data) do
-      {
-        "LikeButton" => {
-          "id" => "/LikeButton.jsx",
-          "name" => "LikeButton",
-          "chunks" => ["/LikeButton.jsx"]
-        },
-        "posts/_like_button" => {
-          "id" => "/posts/_like_button.jsx",
-          "name" => "default",
-          "chunks" => ["/posts/_like_button.jsx"]
-        }
-      }
-    end
-
-    describe "#include?" do
-      let(:manifest) { described_class.from_hash(manifest_data) }
-
-      it "returns true for a key present in the manifest" do
-        expect(manifest.include?("LikeButton")).to be true
-      end
-
-      it "returns false for a key absent from the manifest" do
-        expect(manifest.include?("posts/_like_button")).to be false
-      end
-    end
-
-    describe "#reference_for with controller_path:" do
-      let(:shared_only_manifest) { described_class.from_hash(manifest_data) }
-      let(:dual_manifest)        { described_class.from_hash(dual_manifest_data) }
-
-      it "uses shared key when no controller_path given (AC#1)" do
-        ref = shared_only_manifest.reference_for("LikeButton")
-        expect(ref.module_id).to eq("/LikeButton.jsx")
-      end
-
-      it "uses co-located key when it exists in the manifest (AC#2)" do
-        ref = dual_manifest.reference_for("LikeButton", controller_path: "posts")
-        expect(ref.module_id).to eq("/posts/_like_button.jsx")
-      end
-
-      it "co-located takes precedence over shared when both exist (AC#3)" do
-        ref = dual_manifest.reference_for("LikeButton", controller_path: "posts")
-        expect(ref.module_id).to eq("/posts/_like_button.jsx")
-        expect(ref.module_id).not_to eq("/LikeButton.jsx")
-      end
-
-      it "falls back to shared when co-located key absent (AC#4)" do
-        ref = dual_manifest.reference_for("LikeButton", controller_path: "articles")
-        expect(ref.module_id).to eq("/LikeButton.jsx")
-      end
-
-      it "looks in comments/ first, finds none, uses shared (AC#5)" do
-        ref = dual_manifest.reference_for("LikeButton", controller_path: "comments")
-        expect(ref.module_id).to eq("/LikeButton.jsx")
-      end
-
-      it "returns the same object for repeated calls (dedup by object_id)" do
-        ref1 = dual_manifest.reference_for("LikeButton", controller_path: "posts")
-        ref2 = dual_manifest.reference_for("LikeButton", controller_path: "posts")
-        expect(ref1).to equal(ref2)
-      end
-
-      it "shared and co-located references are different objects" do
-        shared = dual_manifest.reference_for("LikeButton")
-        co_loc = dual_manifest.reference_for("LikeButton", controller_path: "posts")
-        expect(shared).not_to equal(co_loc)
-      end
-    end
-
-    describe ".load" do
-      let(:loaded_manifest) do
-        Tempfile.create(["manifest", ".json"]) do |f|
-          f.write(manifest_data.to_json)
-          f.flush
-          described_class.load(f.path)
-        end
-      end
-
-      it "returns a frozen manifest (AC#5)" do
-        expect(loaded_manifest).to be_frozen
-      end
-
-      it "allows reference_for on a frozen manifest without raising (AC#5)" do
-        expect { loaded_manifest.reference_for("LikeButton") }.not_to raise_error
-      end
-
-      it "resolves the correct ClientReference from a frozen manifest (AC#5)" do
-        ref = loaded_manifest.reference_for("LikeButton")
-        expect(ref).to be_a(Flight::ClientReference)
-        expect(ref.module_id).to eq("/LikeButton.jsx")
-      end
-
-      it "raises ManifestError for unknown component with actionable message (AC#1)" do
-        expect { loaded_manifest.reference_for("Unknown") }
-          .to raise_error(Ruact::ManifestError, /Unknown/)
-        expect { loaded_manifest.reference_for("Unknown") }
-          .to raise_error(Ruact::ManifestError, /Did you run the Vite build\?/)
-      end
-    end
-
-    describe ".from_hash" do
-      it "returns a mutable manifest (not frozen)" do
-        manifest = described_class.from_hash(manifest_data)
-        expect(manifest).not_to be_frozen
-      end
-    end
-
-    describe "#contract_for (Story 13.5)", :story_13_5 do
-      let(:contract) { { "props" => { "postId" => "required" } } }
-
-      it "returns the optional contract Hash when present" do
-        manifest = described_class.from_hash(
-          "LikeButton" => manifest_data["LikeButton"].merge("contract" => contract)
-        )
-        expect(manifest.contract_for("LikeButton")).to eq(contract)
-      end
-
-      it "returns nil when the component declares no contract (back-compat)" do
-        manifest = described_class.from_hash(manifest_data)
-        expect(manifest.contract_for("LikeButton")).to be_nil
-      end
-
-      it "returns nil for an unknown component (never raises — fail open)" do
-        manifest = described_class.from_hash(manifest_data)
-        expect(manifest.contract_for("Nope")).to be_nil
-      end
-
-      it "honors the co-located/shared resolve_key precedence" do
-        data = dual_manifest_data.dup
-        data["posts/_like_button"] = data["posts/_like_button"].merge("contract" => contract)
-        manifest = described_class.from_hash(data)
-        expect(manifest.contract_for("LikeButton", controller_path: "posts")).to eq(contract)
-        expect(manifest.contract_for("LikeButton")).to be_nil
-      end
-
-      it "reads cleanly from a frozen manifest" do
-        manifest = described_class.from_hash(
-          "LikeButton" => manifest_data["LikeButton"].merge("contract" => contract)
-        ).freeze
-        expect(manifest.contract_for("LikeButton")).to eq(contract)
-      end
-    end
-
-    describe "#reference_for closest-match suggestion (Story 7.4)" do
-      let(:shared_only_manifest) { described_class.from_hash(manifest_data) }
-      let(:dual_manifest)        { described_class.from_hash(dual_manifest_data) }
-
-      it "suggests the shared key for a one-character typo" do
-        expect { shared_only_manifest.reference_for("LikeButtonn") }
-          .to raise_error(Ruact::ManifestError, /Did you mean "LikeButton"\?/)
-      end
-
-      it "suggests the shared key for a two-character typo (boundary)" do
-        # "LiekButtoon" is the AC7 spec 13 boundary case (transposition + one
-        # insertion); under Damerau-Levenshtein its distance from "LikeButton"
-        # is 2, so the suggestion fires.
-        expect { shared_only_manifest.reference_for("LiekButtoon") }
-          .to raise_error(Ruact::ManifestError, /Did you mean "LikeButton"\?/)
-      end
-
-      it "falls back to the file-path hint when the typo is over distance 2" do
-        expect { shared_only_manifest.reference_for("LkkButttn") }
-          .to raise_error(Ruact::ManifestError) do |error|
-            expect(error.message)
-              .to match(%r{Did you mean to add app/javascript/components/LkkButttn\.jsx and rebuild Vite\?})
-            expect(error.message).not_to match(/Did you mean "LikeButton"\?/)
-          end
-      end
-
-      it "falls back to the file-path hint for a totally unrelated name" do
-        expect { shared_only_manifest.reference_for("Whatever") }
-          .to raise_error(Ruact::ManifestError,
-                          %r{Did you mean to add app/javascript/components/Whatever\.jsx and rebuild Vite\?})
-      end
-
-      it "suggests a co-located key (with original key shown) when it is the closest match" do
-        co_located_only = described_class.from_hash(
-          "posts/_like_button" => {
-            "id" => "/posts/_like_button.jsx",
-            "name" => "default",
-            "chunks" => ["/posts/_like_button.jsx"]
-          }
-        )
-        expect { co_located_only.reference_for("LikeButtoon") }
-          .to raise_error(Ruact::ManifestError, %r{Did you mean "posts/_like_button"\?})
-      end
-
-      it "biases the suggestion toward co-located keys when controller_path is given" do
-        # Both "LikeButton" (shared) and "posts/_like_button" (co-located) tie
-        # at distance 1 from "LikeButtoon". Without controller_path the first
-        # one encountered wins (hash-iteration order); with controller_path:"posts"
-        # the co-located key is preferred so the suggestion is contextual.
-        expect { dual_manifest.reference_for("LikeButtoon", controller_path: "posts") }
-          .to raise_error(Ruact::ManifestError, %r{Did you mean "posts/_like_button"\?})
-      end
-
-      it "preserves the existing 'Did you run the Vite build?' hint in every variant" do
-        vite_hint = /Did you run the Vite build\? Run 'npm run build' or start the Vite dev server\./
-        expect { shared_only_manifest.reference_for("LikeButtonn") }
-          .to raise_error(Ruact::ManifestError, vite_hint)
-        expect { shared_only_manifest.reference_for("Whatever") }
-          .to raise_error(Ruact::ManifestError, vite_hint)
-      end
-
-      it "uses the AC3 verbatim multi-line 'ruact:' message shape" do
-        expect { shared_only_manifest.reference_for("LikeButtonn") }
-          .to raise_error(Ruact::ManifestError) do |error|
-            expect(error.message).to eq(<<~MSG.strip)
-              ruact: Component "LikeButtonn" not found in manifest.
-                Did you mean "LikeButton"?
-                Did you run the Vite build? Run 'npm run build' or start the Vite dev server.
-            MSG
-          end
-      end
-    end
-
-    describe "edge cases (Story 7.4)" do
-      it "does not raise FrozenError when an empty loaded manifest looks up an unknown component" do
-        empty_manifest = Tempfile.create(["empty_manifest", ".json"]) do |f|
-          f.write("{}")
-          f.flush
-          described_class.load(f.path)
-        end
-
-        expect(empty_manifest).to be_frozen
-        expect { empty_manifest.reference_for("LikeButton") }
-          .to raise_error(Ruact::ManifestError, /not found in manifest/)
-      end
-
-      it "uses entry['name'] (not the lookup key) for ClientReference#export_name" do
-        manifest = described_class.from_hash(
-          "LikeButton" => {
-            "id" => "/LikeButton.jsx",
-            "name" => "LikeButton",
-            "chunks" => ["/LikeButton.jsx"]
-          },
-          "posts/_like_button" => {
-            "id" => "/posts/_like_button.jsx",
-            "name" => "default",
-            "chunks" => ["/posts/_like_button.jsx"]
-          }
-        )
-
-        shared_ref     = manifest.reference_for("LikeButton")
-        co_located_ref = manifest.reference_for("LikeButton", controller_path: "posts")
-
-        expect(shared_ref.export_name).to eq("LikeButton")
-        expect(co_located_ref.export_name).to eq("default")
-      end
-    end
-  end
-end

data/spec/ruact/component_contract_spec.rb

@@ -1,119 +0,0 @@
-# frozen_string_literal: true
-
-require "spec_helper"
-
-module Ruact
-  RSpec.describe ComponentContract, :story_13_5 do
-    def validate(prop_names, contract)
-      described_class.validate(
-        component_name: "LikeButton", prop_names: prop_names, contract: contract,
-        at: { file: "app/views/posts/show.html.erb", line: 7, snippet: "<LikeButton ... />" }
-      )
-    end
-
-    describe "fail open" do
-      it "is a no-op when the contract is nil (opt-in)" do
-        expect { validate(%w[anything goes], nil) }.not_to raise_error
-      end
-    end
-
-    describe "missing required prop (AC#1, AC#3)" do
-      let(:contract) { { "props" => { "postId" => "required", "size" => "optional" } } }
-
-      it "raises ComponentContractError naming the component, file:line, prop, and a fix" do
-        expect { validate(["size"], contract) }.to raise_error(ComponentContractError) do |e|
-          expect(e.message).to include("LikeButton")
-          expect(e.message).to include("app/views/posts/show.html.erb:7")
-          expect(e.message).to include("postId")
-          expect(e.message).to include("add the required prop")
-        end
-      end
-
-      it "is a PreprocessorError (NFR30 overlay lineage)" do
-        expect { validate([], contract) }.to raise_error(PreprocessorError)
-      end
-
-      it "passes when the required prop is present" do
-        expect { validate(%w[postId size], contract) }.not_to raise_error
-      end
-    end
-
-    describe "unknown prop with did-you-mean (AC#1, AC#3)" do
-      let(:contract) { { "props" => { "postId" => "required", "initialCount" => "optional" } } }
-
-      it "raises with a Damerau-Levenshtein closest-match suggestion for a near typo" do
-        expect { validate(%w[postId postID], contract) }.to raise_error(ComponentContractError) do |e|
-          expect(e.message).to include("unknown prop")
-          expect(e.message).to include("postID")
-          expect(e.message).to include('did you mean "postId"?')
-        end
-      end
-
-      it "raises without a suggestion when nothing is close" do
-        expect { validate(%w[postId zzzzzzzz], contract) }.to raise_error(ComponentContractError) do |e|
-          expect(e.message).to include("zzzzzzzz")
-          expect(e.message).not_to include("did you mean")
-        end
-      end
-
-      it "allows undeclared props when passthrough is true" do
-        open = contract.merge("passthrough" => true)
-        expect { validate(%w[postId whatever], open) }.not_to raise_error
-      end
-
-      # Codex review (Patch 1) — a typo OF a required prop (the required name is
-      # therefore "missing") must surface the did-you-mean, not the less-helpful
-      # "missing required" message. FR100's canonical postID/postId case.
-      it "prefers the did-you-mean when the only prop is a typo of a missing required prop" do
-        expect { validate(%w[postID], contract) }.to raise_error(ComponentContractError) do |e|
-          expect(e.message).to include("unknown prop")
-          expect(e.message).to include('did you mean "postId"?')
-          expect(e.message).not_to include("missing required")
-        end
-      end
-
-      it "still reports the missing required prop when the unknown prop is NOT a near typo" do
-        expect { validate(%w[zzzzzzzz], contract) }.to raise_error(ComponentContractError) do |e|
-          expect(e.message).to include("missing required prop")
-          expect(e.message).to include("postId")
-        end
-      end
-    end
-
-    describe "slots (AC#5)" do
-      let(:contract) do
-        { "props" => { "title" => "required" }, "slots" => { "header" => "required", "footer" => "optional" } }
-      end
-
-      it "raises when a required slot is omitted" do
-        expect { validate(%w[title], contract) }.to raise_error(ComponentContractError) do |e|
-          expect(e.message).to include("missing required slot")
-          expect(e.message).to include("header")
-        end
-      end
-
-      it "treats a declared slot name as a valid attribute (not unknown)" do
-        expect { validate(%w[title header], contract) }.not_to raise_error
-      end
-
-      it "accepts the array form (all optional) and is a no-op when slots are absent" do
-        arr = { "props" => { "title" => "required" }, "slots" => %w[header footer] }
-        expect { validate(%w[title], arr) }.not_to raise_error
-      end
-
-      it "does nothing when the contract declares no slots" do
-        expect { validate(%w[title], { "props" => { "title" => "required" } }) }.not_to raise_error
-      end
-    end
-
-    describe "location formatting" do
-      it "degrades gracefully when file/line are absent" do
-        expect do
-          described_class.validate(
-            component_name: "X", prop_names: [], contract: { "props" => { "a" => "required" } }
-          )
-        end.to raise_error(ComponentContractError, /unknown location/)
-      end
-    end
-  end
-end