🤖 Auto-sync docs, metadata, and filepaths (#229)

Co-authored-by: glennj <122470+glennj@users.noreply.github.com>

exercises/practice/affine-cipher/.docs/instructions.md

@@ -20,7 +20,7 @@ Where:
 
 - `i` is the letter's index from `0` to the length of the alphabet - 1.
 - `m` is the length of the alphabet.
-  For the Roman alphabet `m` is `26`.
+  For the Latin alphabet `m` is `26`.
 - `a` and `b` are integers which make up the encryption key.
 
 Values `a` and `m` must be _coprime_ (or, _relatively prime_) for automatic decryption to succeed, i.e., they have number `1` as their only common factor (more information can be found in the [Wikipedia article about coprime integers][coprime-integers]).

exercises/practice/anagram/.docs/instructions.md

@@ -1,13 +1,12 @@
 # Instructions
 
-Your task is to, given a target word and a set of candidate words, to find the subset of the candidates that are anagrams of the target.
+Given a target word and one or more candidate words, your task is to find the candidates that are anagrams of the target.
 
 An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
 A word is _not_ its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
 
-The target and candidates are words of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
-Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `StoP` is not an anagram of `sTOp`.
-The anagram set is the subset of the candidate set that are anagrams of the target (in any order).
-Words in the anagram set should have the same letter case as in the candidate set.
+The target word and candidate words are made up of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
+Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `"StoP"` is not an anagram of `"sTOp"`.
+The words you need to find should be taken from the candidate words, using the same letter case.
 
-Given the target `"stone"` and candidates `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, `"Seton"`, the anagram set is `"tones"`, `"notes"`, `"Seton"`.
+Given the target `"stone"` and the candidate words `"stone"`, `"tones"`, `"banana"`, `"tons"`, `"notes"`, and `"Seton"`, the anagram words you need to find are `"tones"`, `"notes"`, and `"Seton"`.

exercises/practice/bottle-song/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Produce the lyrics to the popular children's repetitive song: Ten Green Bottles.",

exercises/practice/circular-buffer/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "A data structure that uses a single, fixed-size buffer as if it were connected end-to-end.",

exercises/practice/collatz-conjecture/.docs/instructions.md

@@ -1,29 +1,3 @@
 # Instructions
 
-The Collatz Conjecture or 3x+1 problem can be summarized as follows:
-
-Take any positive integer n.
-If n is even, divide n by 2 to get n / 2.
-If n is odd, multiply n by 3 and add 1 to get 3n + 1.
-Repeat the process indefinitely.
-The conjecture states that no matter which number you start with, you will always reach 1 eventually.
-
-Given a number n, return the number of steps required to reach 1.
-
-## Examples
-
-Starting with n = 12, the steps would be as follows:
-
-0. 12
-1. 6
-2. 3
-3. 10
-4. 5
-5. 16
-6. 8
-7. 4
-8. 2
-9. 1
-
-Resulting in 9 steps.
-So for input n = 12, the return value would be 9.
+Given a positive integer, return the number of steps it takes to reach 1 according to the rules of the Collatz Conjecture.

exercises/practice/collatz-conjecture/.docs/introduction.md

@@ -0,0 +1,28 @@
+# Introduction
+
+One evening, you stumbled upon an old notebook filled with cryptic scribbles, as though someone had been obsessively chasing an idea.
+On one page, a single question stood out: **Can every number find its way to 1?**
+It was tied to something called the **Collatz Conjecture**, a puzzle that has baffled thinkers for decades.
+
+The rules were deceptively simple.
+Pick any positive integer.
+
+- If it's even, divide it by 2.
+- If it's odd, multiply it by 3 and add 1.
+
+Then, repeat these steps with the result, continuing indefinitely.
+
+Curious, you picked number 12 to test and began the journey:
+
+12 ➜ 6 ➜ 3 ➜ 10 ➜ 5 ➜ 16 ➜ 8 ➜ 4 ➜ 2 ➜ 1
+
+Counting from the second number (6), it took 9 steps to reach 1, and each time the rules repeated, the number kept changing.
+At first, the sequence seemed unpredictable — jumping up, down, and all over.
+Yet, the conjecture claims that no matter the starting number, we'll always end at 1.
+
+It was fascinating, but also puzzling.
+Why does this always seem to work?
+Could there be a number where the process breaks down, looping forever or escaping into infinity?
+The notebook suggested solving this could reveal something profound — and with it, fame, [fortune][collatz-prize], and a place in history awaits whoever could unlock its secrets.
+
+[collatz-prize]: https://mathprize.net/posts/collatz-conjecture/

exercises/practice/collatz-conjecture/.meta/config.json

@@ -17,6 +17,6 @@
     ]
   },
   "blurb": "Calculate the number of steps to reach 1 using the Collatz conjecture.",
-  "source": "An unsolved problem in mathematics named after mathematician Lothar Collatz",
-  "source_url": "https://en.wikipedia.org/wiki/3x_%2B_1_problem"
+  "source": "Wikipedia",
+  "source_url": "https://en.wikipedia.org/wiki/Collatz_conjecture"
 }

exercises/practice/eliuds-eggs/.docs/introduction.md

@@ -58,7 +58,7 @@ The position information encoding is calculated as follows:
 
 ### Decimal number on the display
 
-16
+8
 
 ### Actual eggs in the coop
 

exercises/practice/flatten-array/.docs/instructions.md

@@ -1,11 +1,16 @@
 # Instructions
 
-Take a nested list and return a single flattened list with all values except nil/null.
+Take a nested array of any depth and return a fully flattened array.
 
-The challenge is to take an arbitrarily-deep nested list-like structure and produce a flattened structure without any nil/null values.
+Note that some language tracks may include null-like values in the input array, and the way these values are represented varies by track.
+Such values should be excluded from the flattened array.
 
-For example:
+Additionally, the input may be of a different data type and contain different types, depending on the track.
 
-input: [1,[2,3,null,4],[null],5]
+Check the test suite for details.
 
-output: [1,2,3,4,5]
+## Example
+
+input: `[1, [2, 6, null], [[null, [4]], 5]]`
+
+output: `[1, 2, 6, 4, 5]`

exercises/practice/flatten-array/.docs/introduction.md

@@ -0,0 +1,7 @@
+# Introduction
+
+A shipment of emergency supplies has arrived, but there's a problem.
+To protect from damage, the items — flashlights, first-aid kits, blankets — are packed inside boxes, and some of those boxes are nested several layers deep inside other boxes!
+
+To be prepared for an emergency, everything must be easily accessible in one box.
+Can you unpack all the supplies and place them into a single box, so they're ready when needed most?

exercises/practice/grains/.docs/instructions.md

@@ -1,15 +1,11 @@
 # Instructions
 
-Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.
+Calculate the number of grains of wheat on a chessboard.
 
-There once was a wise servant who saved the life of a prince.
-The king promised to pay whatever the servant could dream up.
-Knowing that the king loved chess, the servant told the king he would like to have grains of wheat.
-One grain on the first square of a chess board, with the number of grains doubling on each successive square.
+A chessboard has 64 squares.
+Square 1 has one grain, square 2 has two grains, square 3 has four grains, and so on, doubling each time.
 
-There are 64 squares on a chessboard (where square 1 has one grain, square 2 has two grains, and so on).
+Write code that calculates:
 
-Write code that shows:
-
-- how many grains were on a given square, and
+- the number of grains on a given square
 - the total number of grains on the chessboard

exercises/practice/grains/.docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+There once was a wise servant who saved the life of a prince.
+The king promised to pay whatever the servant could dream up.
+Knowing that the king loved chess, the servant told the king he would like to have grains of wheat.
+One grain on the first square of a chessboard, with the number of grains doubling on each successive square.

exercises/practice/grains/.meta/config.json

@@ -18,5 +18,5 @@
   },
   "blurb": "Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.",
   "source": "The CodeRanch Cattle Drive, Assignment 6",
-  "source_url": "https://coderanch.com/wiki/718824/Grains"
+  "source_url": "https://web.archive.org/web/20240908084142/https://coderanch.com/wiki/718824/Grains"
 }

exercises/practice/house/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Output the nursery rhyme 'This is the House that Jack Built'.",

exercises/practice/isbn-verifier/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Check if a given string is a valid ISBN-10 number.",

exercises/practice/leap/.meta/config.json

@@ -18,5 +18,5 @@
   },
   "blurb": "Determine whether a given year is a leap year.",
   "source": "CodeRanch Cattle Drive, Assignment 3",
-  "source_url": "https://coderanch.com/t/718816/Leap"
+  "source_url": "https://web.archive.org/web/20240907033714/https://coderanch.com/t/718816/Leap"
 }

exercises/practice/luhn/.docs/instructions.md

@@ -1,65 +1,68 @@
 # Instructions
 
-Given a number determine whether or not it is valid per the Luhn formula.
+Determine whether a number is valid according to the [Luhn formula][luhn].
 
-The [Luhn algorithm][luhn] is a simple checksum formula used to validate a variety of identification numbers, such as credit card numbers and Canadian Social Insurance Numbers.
+The number will be provided as a string.
 
-The task is to check if a given string is valid.
-
-## Validating a Number
+## Validating a number
 
 Strings of length 1 or less are not valid.
 Spaces are allowed in the input, but they should be stripped before checking.
 All other non-digit characters are disallowed.
 
-### Example 1: valid credit card number
+## Examples
 
-```text
-4539 3195 0343 6467
-```
+### Valid credit card number
 
-The first step of the Luhn algorithm is to double every second digit, starting from the right.
-We will be doubling
+The number to be checked is `4539 3195 0343 6467`.
+
+The first step of the Luhn algorithm is to start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 
 ```text
 4539 3195 0343 6467
 ↑ ↑  ↑ ↑  ↑ ↑  ↑ ↑  (double these)
 ```
 
-If doubling the number results in a number greater than 9 then subtract 9 from the product.
-The results of our doubling:
+If the result of doubling a digit is greater than 9, we subtract 9 from that result.
+We end up with:
 
 ```text
 8569 6195 0383 3437
 ```
 
-Then sum all of the digits:
+Finally, we sum all digits.
+If the sum is evenly divisible by 10, the original number is valid.
 
 ```text
 8 + 5 + 6 + 9 + 6 + 1 + 9 + 5 + 0 + 3 + 8 + 3 + 3 + 4 + 3 + 7 = 80
 ```
 
-If the sum is evenly divisible by 10, then the number is valid.
-This number is valid!
+80 is evenly divisible by 10, so number `4539 3195 0343 6467` is valid!
 
-### Example 2: invalid credit card number
+### Invalid Canadian SIN
+
+The number to be checked is `066 123 478`.
+
+We start at the end of the number and double every second digit, beginning with the second digit from the right and moving left.
 
 ```text
-8273 1232 7352 0569
+066 123 478
+ ↑  ↑ ↑  ↑  (double these)
 ```
 
-Double the second digits, starting from the right
+If the result of doubling a digit is greater than 9, we subtract 9 from that result.
+We end up with:
 
 ```text
-7253 2262 5312 0539
+036 226 458
 ```
 
-Sum the digits
+We sum the digits:
 
 ```text
-7+2+5+3+2+2+6+2+5+3+1+2+0+5+3+9 = 57
+0 + 3 + 6 + 2 + 2 + 6 + 4 + 5 + 8 = 36
 ```
 
-57 is not evenly divisible by 10, so this number is not valid.
+36 is not evenly divisible by 10, so number `066 123 478` is not valid!
 
 [luhn]: https://en.wikipedia.org/wiki/Luhn_algorithm

exercises/practice/luhn/.docs/introduction.md

@@ -0,0 +1,11 @@
+# Introduction
+
+At the Global Verification Authority, you've just been entrusted with a critical assignment.
+Across the city, from online purchases to secure logins, countless operations rely on the accuracy of numerical identifiers like credit card numbers, bank account numbers, transaction codes, and tracking IDs.
+The Luhn algorithm is a simple checksum formula used to help identify mistyped numbers.
+
+A batch of identifiers has just arrived on your desk.
+All of them must pass the Luhn test to ensure they're legitimate.
+If any fail, they'll be flagged as invalid, preventing mistakes such as incorrect transactions or failed account verifications.
+
+Can you ensure this is done right? The integrity of many services depends on you.

exercises/practice/meetup/.docs/instructions.md

@@ -2,7 +2,7 @@
 
 Your task is to find the exact date of a meetup, given a month, year, weekday and week.
 
-There are five week values to consider: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
+There are six week values to consider: `first`, `second`, `third`, `fourth`, `last`, `teenth`.
 
 For example, you might be asked to find the date for the meetup on the first Monday in January 2018 (January 1, 2018).
 

exercises/practice/phone-number/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-Clean up user-entered phone numbers so that they can be sent SMS messages.
+Clean up phone numbers so that they can be sent SMS messages.
 
 The **North American Numbering Plan (NANP)** is a telephone numbering system used by many countries in North America like the United States, Canada or Bermuda.
 All NANP-countries share the same international country code: `1`.

exercises/practice/phone-number/.docs/introduction.md

@@ -0,0 +1,12 @@
+# Introduction
+
+You've joined LinkLine, a leading communications company working to ensure reliable connections for everyone.
+The team faces a big challenge: users submit phone numbers in all sorts of formats — dashes, spaces, dots, parentheses, and even prefixes.
+Some numbers are valid, while others are impossible to use.
+
+Your mission is to turn this chaos into order.
+You'll clean up valid numbers, formatting them appropriately for use in the system.
+At the same time, you'll identify and filter out any invalid entries.
+
+The success of LinkLine's operations depends on your ability to separate the useful from the unusable.
+Are you ready to take on the challenge and keep the connections running smoothly?

exercises/practice/prime-factors/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Compute the prime factors of a given natural number.",

exercises/practice/protein-translation/.docs/instructions.md

@@ -1,36 +1,17 @@
 # Instructions
 
-Translate RNA sequences into proteins.
+Your job is to translate RNA sequences into proteins.
 
-RNA can be broken into three-nucleotide sequences called codons, and then translated to a protein like so:
+RNA strands are made up of three-nucleotide sequences called **codons**.
+Each codon translates to an **amino acid**.
+When joined together, those amino acids make a protein.
 
-RNA: `"AUGUUUUCU"` => translates to
-
-Codons: `"AUG", "UUU", "UCU"`
-=> which become a protein with the following sequence =>
-
-Protein: `"Methionine", "Phenylalanine", "Serine"`
-
-There are 64 codons which in turn correspond to 20 amino acids; however, all of the codon sequences and resulting amino acids are not important in this exercise.
-If it works for one codon, the program should work for all of them.
-However, feel free to expand the list in the test suite to include them all.
-
-There are also three terminating codons (also known as 'STOP' codons); if any of these codons are encountered (by the ribosome), all translation ends and the protein is terminated.
-
-All subsequent codons after are ignored, like this:
-
-RNA: `"AUGUUUUCUUAAAUG"` =>
-
-Codons: `"AUG", "UUU", "UCU", "UAA", "AUG"` =>
-
-Protein: `"Methionine", "Phenylalanine", "Serine"`
-
-Note the stop codon `"UAA"` terminates the translation and the final methionine is not translated into the protein sequence.
-
-Below are the codons and resulting amino acids needed for the exercise.
+In the real world, there are 64 codons, which in turn correspond to 20 amino acids.
+However, for this exercise, you’ll only use a few of the possible 64.
+They are listed below:
 
 | Codon              | Amino Acid    |
-| :----------------- | :------------ |
+| ------------------ | ------------- |
 | AUG                | Methionine    |
 | UUU, UUC           | Phenylalanine |
 | UUA, UUG           | Leucine       |
@@ -40,6 +21,18 @@ Below are the codons and resulting amino acids needed for the exercise.
 | UGG                | Tryptophan    |
 | UAA, UAG, UGA      | STOP          |
 
+For example, the RNA string “AUGUUUUCU” has three codons: “AUG”, “UUU” and “UCU”.
+These map to Methionine, Phenylalanine, and Serine.
+
+## “STOP” Codons
+
+You’ll note from the table above that there are three **“STOP” codons**.
+If you encounter any of these codons, ignore the rest of the sequence — the protein is complete.
+
+For example, “AUGUUUUCUUAAAUG” contains a STOP codon (“UAA”).
+Once we reach that point, we stop processing.
+We therefore only consider the part before it (i.e. “AUGUUUUCU”), not any further codons after it (i.e. “AUG”).
+
 Learn more about [protein translation on Wikipedia][protein-translation].
 
 [protein-translation]: https://en.wikipedia.org/wiki/Translation_(biology)

exercises/practice/queen-attack/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Given the position of two queens on a chess board, indicate whether or not they are positioned so that they can attack each other.",

exercises/practice/resistor-color-duo/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Convert color codes, as used on resistors, to a numeric value.",

exercises/practice/rna-transcription/.meta/config.json

@@ -16,7 +16,7 @@
       "libs/exercism/test"
     ]
   },
-  "blurb": "Given a DNA strand, return its RNA Complement Transcription.",
+  "blurb": "Given a DNA strand, return its RNA complement.",
   "source": "Hyperphysics",
   "source_url": "https://web.archive.org/web/20220408112140/http://hyperphysics.phy-astr.gsu.edu/hbase/Organic/transcription.html"
 }

exercises/practice/run-length-encoding/.meta/config.json

@@ -11,6 +11,9 @@
     ],
     "example": [
       ".meta/example.8th"
+    ],
+    "invalidator": [
+      "libs/exercism/test"
     ]
   },
   "blurb": "Implement run-length encoding and decoding.",

exercises/practice/sieve/.docs/instructions.md

@@ -6,37 +6,96 @@ A prime number is a number larger than 1 that is only divisible by 1 and itself.
 For example, 2, 3, 5, 7, 11, and 13 are prime numbers.
 By contrast, 6 is _not_ a prime number as it not only divisible by 1 and itself, but also by 2 and 3.
 
-To use the Sieve of Eratosthenes, you first create a list of all the numbers between 2 and your given number.
-Then you repeat the following steps:
+To use the Sieve of Eratosthenes, first, write out all the numbers from 2 up to and including your given number.
+Then, follow these steps:
 
-1. Find the next unmarked number in your list (skipping over marked numbers).
+1. Find the next unmarked number (skipping over marked numbers).
    This is a prime number.
 2. Mark all the multiples of that prime number as **not** prime.
 
-You keep repeating these steps until you've gone through every number in your list.
+Repeat the steps until you've gone through every number.
 At the end, all the unmarked numbers are prime.
 
 ~~~~exercism/note
-The tests don't check that you've implemented the algorithm, only that you've come up with the correct list of primes.
-To check you are implementing the Sieve correctly, a good first test is to check that you do not use division or remainder operations.
+The Sieve of Eratosthenes marks off multiples of each prime using addition (repeatedly adding the prime) or multiplication (directly computing its multiples), rather than checking each number for divisibility.
+
+The tests don't check that you've implemented the algorithm, only that you've come up with the correct primes.
 ~~~~
 
 ## Example
 
 Let's say you're finding the primes less than or equal to 10.
 
-- List out 2, 3, 4, 5, 6, 7, 8, 9, 10, leaving them all unmarked.
+- Write out 2, 3, 4, 5, 6, 7, 8, 9, 10, leaving them all unmarked.
+
+  ```text
+  2 3 4 5 6 7 8 9 10
+  ```
+
 - 2 is unmarked and is therefore a prime.
   Mark 4, 6, 8 and 10 as "not prime".
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] 9 [10]
+  ↑
+  ```
+
 - 3 is unmarked and is therefore a prime.
   Mark 6 and 9 as not prime _(marking 6 is optional - as it's already been marked)_.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+    ↑
+  ```
+
 - 4 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+       ↑
+  ```
+
 - 5 is unmarked and is therefore a prime.
   Mark 10 as not prime _(optional - as it's already been marked)_.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+          ↑
+  ```
+
 - 6 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+             ↑
+  ```
+
 - 7 is unmarked and is therefore a prime.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                ↑
+  ```
+
 - 8 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                   ↑
+  ```
+
 - 9 is marked as "not prime", so we skip over it.
+
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                       ↑
+  ```
+
 - 10 is marked as "not prime", so we stop as there are no more numbers to check.
 
-You've examined all numbers and found 2, 3, 5, and 7 are still unmarked, which means they're the primes less than or equal to 10.
+  ```text
+  2 3 [4] 5 [6] 7 [8] [9] [10]
+                           ↑
+  ```
+
+You've examined all the numbers and found that 2, 3, 5, and 7 are still unmarked, meaning they're the primes less than or equal to 10.