From 6f72eb9683fcfcbbd219cc85a0d234fa033e8341 Mon Sep 17 00:00:00 2001
From: Jie <jie.gillet@gmail.com>
Date: Fri, 17 May 2024 22:31:56 +0900
Subject: [PATCH] Sync docs, metadata and tests (#690)

* sync docs and metadata

* add missing tests
---
 exercises/practice/anagram/.meta/tests.toml   |  6 ++++
 exercises/practice/anagram/tests/Tests.elm    |  9 +++--
 .../practice/custom-set/.meta/tests.toml      |  3 ++
 exercises/practice/custom-set/tests/Tests.elm |  6 ++++
 .../matching-brackets/.docs/instructions.md   |  3 +-
 .../matching-brackets/.docs/introduction.md   |  8 +++++
 .../practice/raindrops/.meta/config.json      |  2 +-
 .../practice/reverse-string/.meta/tests.toml  | 11 +++++++
 .../practice/reverse-string/tests/Tests.elm   |  6 ++++
 .../practice/roman-numerals/.meta/tests.toml  | 33 ++++++++++---------
 .../practice/roman-numerals/tests/Tests.elm   |  5 +++
 exercises/practice/say/.docs/instructions.md  |  2 --
 .../practice/space-age/.docs/instructions.md  | 31 +++++++++--------
 .../practice/space-age/.docs/introduction.md  | 20 +++++++++++
 exercises/practice/strain/.meta/config.json   |  2 +-
 .../practice/two-bucket/.docs/instructions.md |  2 +-
 16 files changed, 112 insertions(+), 37 deletions(-)
 create mode 100644 exercises/practice/matching-brackets/.docs/introduction.md
 create mode 100644 exercises/practice/space-age/.docs/introduction.md

diff --git a/exercises/practice/anagram/.meta/tests.toml b/exercises/practice/anagram/.meta/tests.toml
index 4f43811d..4d905627 100644
--- a/exercises/practice/anagram/.meta/tests.toml
+++ b/exercises/practice/anagram/.meta/tests.toml
@@ -78,3 +78,9 @@ include = false
 [33d3f67e-fbb9-49d3-a90e-0beb00861da7]
 description = "words other than themselves can be anagrams"
 reimplements = "a0705568-628c-4b55-9798-82e4acde51ca"
+
+[a6854f66-eec1-4afd-a137-62ef2870c051]
+description = "handles case of greek letters"
+
+[fd3509e5-e3ba-409d-ac3d-a9ac84d13296]
+description = "different characters may have the same bytes"
diff --git a/exercises/practice/anagram/tests/Tests.elm b/exercises/practice/anagram/tests/Tests.elm
index e5f62513..8a04d713 100644
--- a/exercises/practice/anagram/tests/Tests.elm
+++ b/exercises/practice/anagram/tests/Tests.elm
@@ -103,10 +103,10 @@ tests =
                     Expect.equal []
                         (detect "mass" [ "last" ])
         , skip <|
-            test "detects unicode anagrams" <|
+            test "handles case of greek letters" <|
                 \() ->
                     Expect.equal [ "ΒΓΑ", "γβα" ]
-                        (detect "ΑΒΓ" [ "ΒΓΑ", "ΒΓΔ", "γβα" ])
+                        (detect "ΑΒΓ" [ "ΒΓΑ", "ΒΓΔ", "γβα", "αβγ" ])
         , skip <|
             test "eliminates misleading unicode anagrams" <|
                 \() ->
@@ -117,4 +117,9 @@ tests =
                 \() ->
                     Expect.equal []
                         (detect "patter" [ "tapper" ])
+        , skip <|
+            test "different characters may have the same bytes" <|
+                \() ->
+                    Expect.equal []
+                        (detect "a⬂" [ "€a" ])
         ]
diff --git a/exercises/practice/custom-set/.meta/tests.toml b/exercises/practice/custom-set/.meta/tests.toml
index 8c450e0b..430c139e 100644
--- a/exercises/practice/custom-set/.meta/tests.toml
+++ b/exercises/practice/custom-set/.meta/tests.toml
@@ -114,6 +114,9 @@ description = "Difference (or Complement) of a set is a set of all elements that
 [c5ac673e-d707-4db5-8d69-7082c3a5437e]
 description = "Difference (or Complement) of a set is a set of all elements that are only in the first set -> difference of two non-empty sets is a set of elements that are only in the first set"
 
+[20d0a38f-7bb7-4c4a-ac15-90c7392ecf2b]
+description = "Difference (or Complement) of a set is a set of all elements that are only in the first set -> difference removes all duplicates in the first set"
+
 [c45aed16-5494-455a-9033-5d4c93589dc6]
 description = "Union returns a set of all elements in either set -> union of empty sets is an empty set"
 
diff --git a/exercises/practice/custom-set/tests/Tests.elm b/exercises/practice/custom-set/tests/Tests.elm
index db916576..c2704634 100644
--- a/exercises/practice/custom-set/tests/Tests.elm
+++ b/exercises/practice/custom-set/tests/Tests.elm
@@ -211,6 +211,12 @@ tests =
                             |> CustomSet.toList
                             |> List.sort
                             |> Expect.equalLists [ 1, 3 ]
+            , skip <|
+                test "difference removes all duplicates in the first set" <|
+                    \() ->
+                        CustomSet.diff (CustomSet.fromList [ 1, 1 ]) (CustomSet.fromList [ 1 ])
+                            |> CustomSet.toList
+                            |> Expect.equalLists []
             ]
         , describe "A set is a subset if all of its elements are contained in the other set"
             [ skip <|
diff --git a/exercises/practice/matching-brackets/.docs/instructions.md b/exercises/practice/matching-brackets/.docs/instructions.md
index 544daa96..ea170842 100644
--- a/exercises/practice/matching-brackets/.docs/instructions.md
+++ b/exercises/practice/matching-brackets/.docs/instructions.md
@@ -1,4 +1,5 @@
 # Instructions
 
 Given a string containing brackets `[]`, braces `{}`, parentheses `()`, or any combination thereof, verify that any and all pairs are matched and nested correctly.
-The string may also contain other characters, which for the purposes of this exercise should be ignored.
+Any other characters should be ignored.
+For example, `"{what is (42)}?"` is balanced and `"[text}"` is not.
diff --git a/exercises/practice/matching-brackets/.docs/introduction.md b/exercises/practice/matching-brackets/.docs/introduction.md
new file mode 100644
index 00000000..0618221b
--- /dev/null
+++ b/exercises/practice/matching-brackets/.docs/introduction.md
@@ -0,0 +1,8 @@
+# Introduction
+
+You're given the opportunity to write software for the Bracketeer™, an ancient but powerful mainframe.
+The software that runs on it is written in a proprietary language.
+Much of its syntax is familiar, but you notice _lots_ of brackets, braces and parentheses.
+Despite the Bracketeer™ being powerful, it lacks flexibility.
+If the source code has any unbalanced brackets, braces or parentheses, the Bracketeer™ crashes and must be rebooted.
+To avoid such a scenario, you start writing code that can verify that brackets, braces, and parentheses are balanced before attempting to run it on the Bracketeer™.
diff --git a/exercises/practice/raindrops/.meta/config.json b/exercises/practice/raindrops/.meta/config.json
index e7827d4b..78005d6e 100644
--- a/exercises/practice/raindrops/.meta/config.json
+++ b/exercises/practice/raindrops/.meta/config.json
@@ -18,7 +18,7 @@
       ".meta/src/Raindrops.example.elm"
     ]
   },
-  "blurb": "Convert a number to a string, the content of which depends on the number's factors.",
+  "blurb": "Convert a number into its corresponding raindrop sounds - Pling, Plang and Plong.",
   "source": "A variation on FizzBuzz, a famous technical interview question that is intended to weed out potential candidates. That question is itself derived from Fizz Buzz, a popular children's game for teaching division.",
   "source_url": "https://en.wikipedia.org/wiki/Fizz_buzz"
 }
diff --git a/exercises/practice/reverse-string/.meta/tests.toml b/exercises/practice/reverse-string/.meta/tests.toml
index 0b04c4cd..3db9ea66 100644
--- a/exercises/practice/reverse-string/.meta/tests.toml
+++ b/exercises/practice/reverse-string/.meta/tests.toml
@@ -26,3 +26,14 @@ description = "a palindrome"
 
 [b9e7dec1-c6df-40bd-9fa3-cd7ded010c4c]
 description = "an even-sized word"
+
+[1bed0f8a-13b0-4bd3-9d59-3d0593326fa2]
+description = "wide characters"
+
+[93d7e1b8-f60f-4f3c-9559-4056e10d2ead]
+description = "grapheme cluster with pre-combined form"
+
+[1028b2c1-6763-4459-8540-2da47ca512d9]
+description = "grapheme clusters"
+include = false
+comment = "String.reverse cannot handle that one"
diff --git a/exercises/practice/reverse-string/tests/Tests.elm b/exercises/practice/reverse-string/tests/Tests.elm
index 86788611..7fff002a 100644
--- a/exercises/practice/reverse-string/tests/Tests.elm
+++ b/exercises/practice/reverse-string/tests/Tests.elm
@@ -25,4 +25,10 @@ tests =
         , skip <|
             test "an even-sized word" <|
                 \() -> Expect.equal "reward" (reverse "drawer")
+        , skip <|
+            test "wide characters" <|
+                \() -> Expect.equal "猫子" (reverse "子猫")
+        , skip <|
+            test "grapheme cluster with pre-combined form" <|
+                \() -> Expect.equal "dnatsnehctsrüW" (reverse "Würstchenstand")
         ]
diff --git a/exercises/practice/roman-numerals/.meta/tests.toml b/exercises/practice/roman-numerals/.meta/tests.toml
index ca142e9f..709011b5 100644
--- a/exercises/practice/roman-numerals/.meta/tests.toml
+++ b/exercises/practice/roman-numerals/.meta/tests.toml
@@ -30,6 +30,9 @@ description = "6 is VI"
 [ff3fb08c-4917-4aab-9f4e-d663491d083d]
 description = "9 is IX"
 
+[6d1d82d5-bf3e-48af-9139-87d7165ed509]
+description = "16 is XVI"
+
 [2bda64ca-7d28-4c56-b08d-16ce65716cf6]
 description = "27 is XXVII"
 
@@ -42,6 +45,9 @@ description = "49 is XLIX"
 [d5b283d4-455d-4e68-aacf-add6c4b51915]
 description = "59 is LIX"
 
+[4465ffd5-34dc-44f3-ada5-56f5007b6dad]
+description = "66 is LXVI"
+
 [46b46e5b-24da-4180-bfe2-2ef30b39d0d0]
 description = "93 is XCIII"
 
@@ -51,38 +57,35 @@ description = "141 is CXLI"
 [267f0207-3c55-459a-b81d-67cec7a46ed9]
 description = "163 is CLXIII"
 
+[902ad132-0b4d-40e3-8597-ba5ed611dd8d]
+description = "166 is CLXVI"
+
 [cdb06885-4485-4d71-8bfb-c9d0f496b404]
 description = "402 is CDII"
 
 [6b71841d-13b2-46b4-ba97-dec28133ea80]
 description = "575 is DLXXV"
 
+[dacb84b9-ea1c-4a61-acbb-ce6b36674906]
+description = "666 is DCLXVI"
+
 [432de891-7fd6-4748-a7f6-156082eeca2f]
 description = "911 is CMXI"
 
 [e6de6d24-f668-41c0-88d7-889c0254d173]
 description = "1024 is MXXIV"
 
-[bb550038-d4eb-4be2-a9ce-f21961ac3bc6]
-description = "3000 is MMM"
-
-[6d1d82d5-bf3e-48af-9139-87d7165ed509]
-description = "16 is XVI"
-
-[4465ffd5-34dc-44f3-ada5-56f5007b6dad]
-description = "66 is LXVI"
-
-[902ad132-0b4d-40e3-8597-ba5ed611dd8d]
-description = "166 is CLXVI"
-
-[dacb84b9-ea1c-4a61-acbb-ce6b36674906]
-description = "666 is DCLXVI"
-
 [efbe1d6a-9f98-4eb5-82bc-72753e3ac328]
 description = "1666 is MDCLXVI"
 
+[bb550038-d4eb-4be2-a9ce-f21961ac3bc6]
+description = "3000 is MMM"
+
 [3bc4b41c-c2e6-49d9-9142-420691504336]
 description = "3001 is MMMI"
 
+[2f89cad7-73f6-4d1b-857b-0ef531f68b7e]
+description = "3888 is MMMDCCCLXXXVIII"
+
 [4e18e96b-5fbb-43df-a91b-9cb511fe0856]
 description = "3999 is MMMCMXCIX"
diff --git a/exercises/practice/roman-numerals/tests/Tests.elm b/exercises/practice/roman-numerals/tests/Tests.elm
index aa8b160e..eb839a28 100644
--- a/exercises/practice/roman-numerals/tests/Tests.elm
+++ b/exercises/practice/roman-numerals/tests/Tests.elm
@@ -127,6 +127,11 @@ tests =
                 \() ->
                     Expect.equal "MMMI"
                         (toRoman 3001)
+        , skip <|
+            test "3888" <|
+                \() ->
+                    Expect.equal "MMMDCCCLXXXVIII"
+                        (toRoman 3888)
         , skip <|
             test "3999" <|
                 \() ->
diff --git a/exercises/practice/say/.docs/instructions.md b/exercises/practice/say/.docs/instructions.md
index fb4a6dfb..ad3d3477 100644
--- a/exercises/practice/say/.docs/instructions.md
+++ b/exercises/practice/say/.docs/instructions.md
@@ -30,8 +30,6 @@ Implement breaking a number up into chunks of thousands.
 
 So `1234567890` should yield a list like 1, 234, 567, and 890, while the far simpler `1000` should yield just 1 and 0.
 
-The program must also report any values that are out of range.
-
 ## Step 3
 
 Now handle inserting the appropriate scale word between those chunks.
diff --git a/exercises/practice/space-age/.docs/instructions.md b/exercises/practice/space-age/.docs/instructions.md
index fe938cc0..f23b5e2c 100644
--- a/exercises/practice/space-age/.docs/instructions.md
+++ b/exercises/practice/space-age/.docs/instructions.md
@@ -1,25 +1,28 @@
 # Instructions
 
-Given an age in seconds, calculate how old someone would be on:
+Given an age in seconds, calculate how old someone would be on a planet in our Solar System.
 
-- Mercury: orbital period 0.2408467 Earth years
-- Venus: orbital period 0.61519726 Earth years
-- Earth: orbital period 1.0 Earth years, 365.25 Earth days, or 31557600 seconds
-- Mars: orbital period 1.8808158 Earth years
-- Jupiter: orbital period 11.862615 Earth years
-- Saturn: orbital period 29.447498 Earth years
-- Uranus: orbital period 84.016846 Earth years
-- Neptune: orbital period 164.79132 Earth years
+One Earth year equals 365.25 Earth days, or 31,557,600 seconds.
+If you were told someone was 1,000,000,000 seconds old, their age would be 31.69 Earth-years.
 
-So if you were told someone were 1,000,000,000 seconds old, you should
-be able to say that they're 31.69 Earth-years old.
+For the other planets, you have to account for their orbital period in Earth Years:
 
-If you're wondering why Pluto didn't make the cut, go watch [this YouTube video][pluto-video].
+| Planet  | Orbital period in Earth Years |
+| ------- | ----------------------------- |
+| Mercury | 0.2408467                     |
+| Venus   | 0.61519726                    |
+| Earth   | 1.0                           |
+| Mars    | 1.8808158                     |
+| Jupiter | 11.862615                     |
+| Saturn  | 29.447498                     |
+| Uranus  | 84.016846                     |
+| Neptune | 164.79132                     |
 
-Note: The actual length of one complete orbit of the Earth around the sun is closer to 365.256 days (1 sidereal year).
+~~~~exercism/note
+The actual length of one complete orbit of the Earth around the sun is closer to 365.256 days (1 sidereal year).
 The Gregorian calendar has, on average, 365.2425 days.
 While not entirely accurate, 365.25 is the value used in this exercise.
 See [Year on Wikipedia][year] for more ways to measure a year.
 
-[pluto-video]: https://www.youtube.com/watch?v=Z_2gbGXzFbs
 [year]: https://en.wikipedia.org/wiki/Year#Summary
+~~~~
diff --git a/exercises/practice/space-age/.docs/introduction.md b/exercises/practice/space-age/.docs/introduction.md
new file mode 100644
index 00000000..014d7885
--- /dev/null
+++ b/exercises/practice/space-age/.docs/introduction.md
@@ -0,0 +1,20 @@
+# Introduction
+
+The year is 2525 and you've just embarked on a journey to visit all planets in the Solar System (Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus and Neptune).
+The first stop is Mercury, where customs require you to fill out a form (bureaucracy is apparently _not_ Earth-specific).
+As you hand over the form to the customs officer, they scrutinize it and frown.
+"Do you _really_ expect me to believe you're just 50 years old?
+You must be closer to 200 years old!"
+
+Amused, you wait for the customs officer to start laughing, but they appear to be dead serious.
+You realize that you've entered your age in _Earth years_, but the officer expected it in _Mercury years_!
+As Mercury's orbital period around the sun is significantly shorter than Earth, you're actually a lot older in Mercury years.
+After some quick calculations, you're able to provide your age in Mercury Years.
+The customs officer smiles, satisfied, and waves you through.
+You make a mental note to pre-calculate your planet-specific age _before_ future customs checks, to avoid such mix-ups.
+
+~~~~exercism/note
+If you're wondering why Pluto didn't make the cut, go watch [this YouTube video][pluto-video].
+
+[pluto-video]: https://www.youtube.com/watch?v=Z_2gbGXzFbs
+~~~~
diff --git a/exercises/practice/strain/.meta/config.json b/exercises/practice/strain/.meta/config.json
index e0541d1f..de56f15a 100644
--- a/exercises/practice/strain/.meta/config.json
+++ b/exercises/practice/strain/.meta/config.json
@@ -18,7 +18,7 @@
       ".meta/src/Strain.example.elm"
     ]
   },
-  "blurb": "Implement the `keep` and `discard` operation on collections. Given a collection and a predicate on the collection's elements, `keep` returns a new collection containing those elements where the predicate is true, while `discard` returns a new collection containing those elements where the predicate is false.",
+  "blurb": "Implement the `keep` and `discard` operation on collections.",
   "source": "Conversation with James Edward Gray II",
   "source_url": "http://graysoftinc.com/"
 }
diff --git a/exercises/practice/two-bucket/.docs/instructions.md b/exercises/practice/two-bucket/.docs/instructions.md
index 7249deb3..30d779aa 100644
--- a/exercises/practice/two-bucket/.docs/instructions.md
+++ b/exercises/practice/two-bucket/.docs/instructions.md
@@ -11,7 +11,7 @@ There are some rules that your solution must follow:
      b) the second bucket is full
   2. Emptying a bucket and doing nothing to the other.
   3. Filling a bucket and doing nothing to the other.
-- After an action, you may not arrive at a state where the starting bucket is empty and the other bucket is full.
+- After an action, you may not arrive at a state where the initial starting bucket is empty and the other bucket is full.
 
 Your program will take as input: