Sync crypto-square (#866)

Author: tomasnorre

exercises/practice/crypto-square/.docs/instructions.md

@@ -4,11 +4,10 @@ Implement the classic method for composing secret messages called a square code.
 
 Given an English text, output the encoded version of that text.
 
-First, the input is normalized: the spaces and punctuation are removed
-from the English text and the message is downcased.
+First, the input is normalized: the spaces and punctuation are removed from the English text and the message is down-cased.
 
-Then, the normalized characters are broken into rows.  These rows can be
-regarded as forming a rectangle when printed with intervening newlines.
+Then, the normalized characters are broken into rows.
+These rows can be regarded as forming a rectangle when printed with intervening newlines.
 
 For example, the sentence
 
@@ -22,13 +21,16 @@ is normalized to:
 "ifmanwasmeanttostayonthegroundgodwouldhavegivenusroots"
 ```
 
-The plaintext should be organized in to a rectangle.  The size of the
-rectangle (`r x c`) should be decided by the length of the message,
-such that `c >= r` and `c - r <= 1`, where `c` is the number of columns
-and `r` is the number of rows.
+The plaintext should be organized into a rectangle as square as possible.
+The size of the rectangle should be decided by the length of the message.
 
-Our normalized text is 54 characters long, dictating a rectangle with
-`c = 8` and `r = 7`:
+If `c` is the number of columns and `r` is the number of rows, then for the rectangle `r` x `c` find the smallest possible integer `c` such that:
+
+- `r * c >= length of message`,
+- and `c >= r`,
+- and `c - r <= 1`.
+
+Our normalized text is 54 characters long, dictating a rectangle with `c = 8` and `r = 7`:
 
 ```text
 "ifmanwas"
@@ -40,26 +42,22 @@ Our normalized text is 54 characters long, dictating a rectangle with
 "sroots  "
 ```
 
-The coded message is obtained by reading down the columns going left to
-right.
+The coded message is obtained by reading down the columns going left to right.
 
 The message above is coded as:
 
 ```text
 "imtgdvsfearwermayoogoanouuiontnnlvtwttddesaohghnsseoau"
 ```
 
-Output the encoded text in chunks that fill perfect rectangles `(r X c)`,
-with `c` chunks of `r` length, separated by spaces. For phrases that are
-`n` characters short of the perfect rectangle, pad each of the last `n`
-chunks with a single trailing space.
+Output the encoded text in chunks that fill perfect rectangles `(r X c)`, with `c` chunks of `r` length, separated by spaces.
+For phrases that are `n` characters short of the perfect rectangle, pad each of the last `n` chunks with a single trailing space.
 
 ```text
 "imtgdvs fearwer mayoogo anouuio ntnnlvt wttddes aohghn  sseoau "
 ```
 
-Notice that were we to stack these, we could visually decode the
-ciphertext back in to the original message:
+Notice that were we to stack these, we could visually decode the ciphertext back in to the original message:
 
 ```text
 "imtgdvs"

exercises/practice/crypto-square/.meta/example.php

@@ -1,27 +1,5 @@
 <?php
 
-/*
- * By adding type hints and enabling strict type checking, code can become
- * easier to read, self-documenting and reduce the number of potential bugs.
- * By default, type declarations are non-strict, which means they will attempt
- * to change the original type to match the type specified by the
- * type-declaration.
- *
- * In other words, if you pass a string to a function requiring a float,
- * it will attempt to convert the string value to a float.
- *
- * To enable strict mode, a single declare directive must be placed at the top
- * of the file.
- * This means that the strictness of typing is configured on a per-file basis.
- * This directive not only affects the type declarations of parameters, but also
- * a function's return type.
- *
- * For more info review the Concept on strict type checking in the PHP track
- * <link>.
- *
- * To disable strict typing, comment out the directive below.
- */
-
 declare(strict_types=1);
 
 function crypto_square($plaintext)

exercises/practice/crypto-square/.meta/tests.toml

@@ -1,10 +1,20 @@
-# This is an auto-generated file. Regular comments will be removed when this
-# file is regenerated. Regenerating will not touch any manually added keys,
-# so comments can be added in a "comment" key.
+# This is an auto-generated file.
+#
+# Regenerating this file via `configlet sync` will:
+# - Recreate every `description` key/value pair
+# - Recreate every `reimplements` key/value pair, where they exist in problem-specifications
+# - Remove any `include = true` key/value pair (an omitted `include` key implies inclusion)
+# - Preserve any other key/value pair
+#
+# As user-added comments (using the # character) will be removed when this file
+# is regenerated, comments can be added via a `comment` key.
 
 [407c3837-9aa7-4111-ab63-ec54b58e8e9f]
 description = "empty plaintext results in an empty ciphertext"
 
+[aad04a25-b8bb-4304-888b-581bea8e0040]
+description = "normalization results in empty plaintext"
+
 [64131d65-6fd9-4f58-bdd8-4a2370fb481d]
 description = "Lowercase"
 

exercises/practice/crypto-square/CryptoSquareTest.php

@@ -1,27 +1,5 @@
 <?php
 
-/*
- * By adding type hints and enabling strict type checking, code can become
- * easier to read, self-documenting and reduce the number of potential bugs.
- * By default, type declarations are non-strict, which means they will attempt
- * to change the original type to match the type specified by the
- * type-declaration.
- *
- * In other words, if you pass a string to a function requiring a float,
- * it will attempt to convert the string value to a float.
- *
- * To enable strict mode, a single declare directive must be placed at the top
- * of the file.
- * This means that the strictness of typing is configured on a per-file basis.
- * This directive not only affects the type declarations of parameters, but also
- * a function's return type.
- *
- * For more info review the Concept on strict type checking in the PHP track
- * <link>.
- *
- * To disable strict typing, comment out the directive below.
- */
-
 declare(strict_types=1);
 
 class CryptoSquareTest extends PHPUnit\Framework\TestCase
@@ -31,36 +9,73 @@ public static function setUpBeforeClass(): void
         require_once 'CryptoSquare.php';
     }
 
+    /**
+     * uuid 407c3837-9aa7-4111-ab63-ec54b58e8e9f
+     * @testdox empty plaintext results in an empty ciphertext
+     */
     public function testEmptyPlaintextResultsInAnEmptyCiphertext(): void
     {
         $this->assertEquals("", crypto_square(""));
     }
 
+    /**
+     * uuid aad04a25-b8bb-4304-888b-581bea8e0040
+     * @testdox normalization results in empty plaintext
+     */
+    public function testNormalizationResultsInEmptyPlaintext(): void
+    {
+        $this->assertEquals("", crypto_square("... --- ..."));
+    }
+
+    /**
+     * uuid 64131d65-6fd9-4f58-bdd8-4a2370fb481d
+     * @testdox Lowercase
+     */
     public function testLowercase(): void
     {
         $this->assertEquals("a", crypto_square("A"));
     }
 
+    /**
+     * uuid 63a4b0ed-1e3c-41ea-a999-f6f26ba447d6
+     * @testdox Remove spaces
+     */
     public function testRemoveSpaces(): void
     {
         $this->assertEquals("b", crypto_square("  b "));
     }
 
+    /**
+     * uuid 1b5348a1-7893-44c1-8197-42d48d18756c
+     * @testdox Remove punctuation
+     */
     public function testRemovePunctuation(): void
     {
         $this->assertEquals("1", crypto_square("@1,%!"));
     }
 
+    /**
+     * uuid 8574a1d3-4a08-4cec-a7c7-de93a164f41a
+     * @testdox 9 character plaintext results in 3 chunks of 3 characters
+     */
     public function test9CharacterPlaintextResultsIn3ChunksOf3Characters(): void
     {
         $this->assertEquals("tsf hiu isn", crypto_square("This is fun!"));
     }
 
+    /**
+     * uuid a65d3fa1-9e09-43f9-bcec-7a672aec3eae
+     * @testdox 8 character plaintext results in 3 chunks, the last one with a trailing space
+     */
     public function test8CharacterPlaintextResultsIn3ChunksTheLastOneWithATrailingSpace(): void
     {
         $this->assertEquals("clu hlt io ", crypto_square("Chill out."));
     }
 
+    /**
+     * uuid fbcb0c6d-4c39-4a31-83f6-c473baa6af80
+     * @testdox 54 character plaintext results in 7 chunks, the last two with trailing spaces
+     */
     public function test54CharacterPlaintextResultsIn7ChunksTheLastTwoWithTrailingSpaces(): void
     {
         $this->assertEquals(