From aa23b4dd82fca049b6e3177088f407dc3d1b89f7 Mon Sep 17 00:00:00 2001
From: Erik Schierboom <erik_schierboom@hotmail.com>
Date: Wed, 2 Jun 2021 09:51:44 +0200
Subject: [PATCH] sync: write fuller `description` for nested test cases (#301)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Some exercises in the `problem-specifications` repo have a
`canonical-data.json` file that uses nesting, meaning that there is more
than one `cases` property.

`configlet` handled these nicely, but each `description` in each
`tests.toml` file contained only the description of the test case
itself. This could be unclear, and was especially confusing when test
cases in different nested objects had the same description. Each
`description` is purely for humans to read - it isn't used otherwise.

With this commit, `configlet sync` writes the "full description" to the
`tests.toml` file. For example, a `tests.toml` for the `triangle`
exercise might previously contain (omitting other test cases for
clarity):

```toml
[3022f537-b8e5-4cc1-8f12-fd775827a00c]
description = "sides may be floats"

[adb4ee20-532f-43dc-8d31-e9271b7ef2bc]
description = "sides may be floats"

[26d9d59d-f8f1-40d3-ad58-ae4d54123d7d]
description = "sides may be floats"
```

But with this commit:

```toml
[3022f537-b8e5-4cc1-8f12-fd775827a00c]
description = "equilateral triangle → sides may be floats"

[adb4ee20-532f-43dc-8d31-e9271b7ef2bc]
description = "isosceles triangle → sides may be floats"

[26d9d59d-f8f1-40d3-ad58-ae4d54123d7d]
description = "scalene triangle → sides may be floats"
```

For the canonical data for this exercise, see:
https://github.com/exercism/problem-specifications/blob/f17f457fdc06/exercises/triangle/canonical-data.json

We decided that putting everything in `description` is better than:
- adding extra key/value pair(s) named e.g. `category` or `super`
- adding TOML comments
- using sub-tables

While working on this PR, we noticed that 18 exercises in
`problem-specifications` had unnecessary nesting. We simplified them in
https://github.com/exercism/problem-specifications/pull/1798

Closes: #202

Co-authored-by: ee7 <45465154+ee7@users.noreply.github.com>
---
 src/sync/probspecs.nim | 16 ++++++++--
 tests/test_binary.nim  | 68 +++++++++++++++++++++++++++---------------
 2 files changed, 57 insertions(+), 27 deletions(-)

diff --git a/src/sync/probspecs.nim b/src/sync/probspecs.nim
index 7dac9fbb..c8492cc6 100644
--- a/src/sync/probspecs.nim
+++ b/src/sync/probspecs.nim
@@ -56,13 +56,23 @@ func isReimplementation*(testCase: ProbSpecsTestCase): bool =
 func reimplements*(testCase: ProbSpecsTestCase): string =
   testCase["reimplements"].getStr()
 
-proc initProbSpecsTestCases(node: JsonNode): seq[ProbSpecsTestCase] =
-  ## Returns a seq of every individual test case in `node` (flattening).
+proc initProbSpecsTestCases(node: JsonNode, prefix = ""): seq[ProbSpecsTestCase] =
+  ## Returns a seq of every individual test case in `node` (flattening). We
+  ## alter each `description` value to indicate any nesting, which is OK because
+  ## we only use the `description` for writing `tests.toml`.
   if node.hasKey("uuid"):
+    if node.hasKey("description"):
+      if node["description"].kind == JString:
+        node["description"].str = &"""{prefix}{node["description"].getStr()}"""
     result.add ProbSpecsTestCase(node)
   elif node.hasKey("cases"):
+    let prefix =
+      if node.hasKey("description"):
+        &"""{prefix}{node["description"].getStr()} → """
+      else:
+        prefix
     for childNode in node["cases"].getElems():
-      result.add initProbSpecsTestCases(childNode)
+      result.add initProbSpecsTestCases(childNode, prefix)
 
 proc grainsWorkaround(grainsPath: string): JsonNode =
   ## Parses the canonical data file for `grains`, replacing the too-large
diff --git a/tests/test_binary.nim b/tests/test_binary.nim
index 0756ca59..3adfaf12 100644
--- a/tests/test_binary.nim
+++ b/tests/test_binary.nim
@@ -79,19 +79,19 @@ Checking exercises...
        - disallow right empty strand (920cd6e3-18f4-4143-b6b8-74270bb8f8a3)
        - disallow empty second strand (9ab9262f-3521-4191-81f5-0ed184a5aa89)
 [warn] high-scores: missing 2 test cases
-       - Latest score after personal top scores (2df075f9-fec9-4756-8f40-98c52a11504f)
-       - Scores after personal top scores (809c4058-7eb1-4206-b01e-79238b9b71bc)
+       - Top 3 scores → Latest score after personal top scores (2df075f9-fec9-4756-8f40-98c52a11504f)
+       - Top 3 scores → Scores after personal top scores (809c4058-7eb1-4206-b01e-79238b9b71bc)
 [warn] isogram: missing 1 test cases
        - word with duplicated character and with two hyphens (0d0b8644-0a1e-4a31-a432-2b3ee270d847)
 [warn] kindergarten-garden: missing 8 test cases
-       - for Charlie (566b621b-f18e-4c5f-873e-be30544b838c)
-       - for David (3ad3df57-dd98-46fc-9269-1877abf612aa)
-       - for Eve (0f0a55d1-9710-46ed-a0eb-399ba8c72db2)
-       - for Fred (a7e80c90-b140-4ea1-aee3-f4625365c9a4)
-       - for Ginny (9d94b273-2933-471b-86e8-dba68694c615)
-       - for Harriet (f55bc6c2-ade8-4844-87c4-87196f1b7258)
-       - for Ileana (759070a3-1bb1-4dd4-be2c-7cce1d7679ae)
-       - for Joseph (78578123-2755-4d4a-9c7d-e985b8dda1c6)
+       - full garden → for Charlie (566b621b-f18e-4c5f-873e-be30544b838c)
+       - full garden → for David (3ad3df57-dd98-46fc-9269-1877abf612aa)
+       - full garden → for Eve (0f0a55d1-9710-46ed-a0eb-399ba8c72db2)
+       - full garden → for Fred (a7e80c90-b140-4ea1-aee3-f4625365c9a4)
+       - full garden → for Ginny (9d94b273-2933-471b-86e8-dba68694c615)
+       - full garden → for Harriet (f55bc6c2-ade8-4844-87c4-87196f1b7258)
+       - full garden → for Ileana (759070a3-1bb1-4dd4-be2c-7cce1d7679ae)
+       - full garden → for Joseph (78578123-2755-4d4a-9c7d-e985b8dda1c6)
 [warn] luhn: missing 1 test cases
        - non-numeric, non-space char in the middle with a sum that's divisible by 10 isn't allowed (8b72ad26-c8be-49a2-b99c-bcc3bf631b33)
 [warn] prime-factors: missing 5 test cases
@@ -252,12 +252,22 @@ All exercises are synced!
 +#
 +# As regular comments will be removed when this file is regenerated, comments
 +# can be added in a "comment" key.
+-description = "Personal top three from a list of scores"
++description = "Top 3 scores → Personal top three from a list of scores"
+-description = "Personal top highest to lowest"
++description = "Top 3 scores → Personal top highest to lowest"
+-description = "Personal top when there is a tie"
++description = "Top 3 scores → Personal top when there is a tie"
+-description = "Personal top when there are less than 3"
++description = "Top 3 scores → Personal top when there are less than 3"
+-description = "Personal top when there is only one"
++description = "Top 3 scores → Personal top when there is only one"
 +
 +[2df075f9-fec9-4756-8f40-98c52a11504f]
-+description = "Latest score after personal top scores"
++description = "Top 3 scores → Latest score after personal top scores"
 +
 +[809c4058-7eb1-4206-b01e-79238b9b71bc]
-+description = "Scores after personal top scores"
++description = "Top 3 scores → Scores after personal top scores"
 --- exercises/practice/isogram/.meta/tests.toml
 +++ exercises/practice/isogram/.meta/tests.toml
 -# This is an auto-generated file. Regular comments will be removed when this
@@ -293,38 +303,48 @@ All exercises are synced!
 +#
 +# As regular comments will be removed when this file is regenerated, comments
 +# can be added in a "comment" key.
+-description = "garden with single student"
++description = "partial garden → garden with single student"
+-description = "different garden with single student"
++description = "partial garden → different garden with single student"
+-description = "garden with two students"
++description = "partial garden → garden with two students"
+-description = "second student's garden"
++description = "partial garden → multiple students for the same garden with three students → second student's garden"
+-description = "third student's garden"
++description = "partial garden → multiple students for the same garden with three students → third student's garden"
 -description = "first student's garden"
-+description = "for Alice, first student's garden"
++description = "full garden → for Alice, first student's garden"
 -description = "second student's garden"
-+description = "for Bob, second student's garden"
++description = "full garden → for Bob, second student's garden"
 +
 +[566b621b-f18e-4c5f-873e-be30544b838c]
-+description = "for Charlie"
++description = "full garden → for Charlie"
 +
 +[3ad3df57-dd98-46fc-9269-1877abf612aa]
-+description = "for David"
++description = "full garden → for David"
 +
 +[0f0a55d1-9710-46ed-a0eb-399ba8c72db2]
-+description = "for Eve"
++description = "full garden → for Eve"
 +
 +[a7e80c90-b140-4ea1-aee3-f4625365c9a4]
-+description = "for Fred"
++description = "full garden → for Fred"
 +
 +[9d94b273-2933-471b-86e8-dba68694c615]
-+description = "for Ginny"
++description = "full garden → for Ginny"
 +
 +[f55bc6c2-ade8-4844-87c4-87196f1b7258]
-+description = "for Harriet"
++description = "full garden → for Harriet"
 +
 +[759070a3-1bb1-4dd4-be2c-7cce1d7679ae]
-+description = "for Ileana"
++description = "full garden → for Ileana"
 +
 +[78578123-2755-4d4a-9c7d-e985b8dda1c6]
-+description = "for Joseph"
++description = "full garden → for Joseph"
 -description = "second to last student's garden"
-+description = "for Kincaid, second to last student's garden"
++description = "full garden → for Kincaid, second to last student's garden"
 -description = "last student's garden"
-+description = "for Larry, last student's garden"
++description = "full garden → for Larry, last student's garden"
 --- exercises/practice/luhn/.meta/tests.toml
 +++ exercises/practice/luhn/.meta/tests.toml
 -# This is an auto-generated file. Regular comments will be removed when this