sync: write tests.toml with reimplements (#317)

With this commit, `configlet sync` adds a `reimplements` key/value pair
to each relevant test case when writing the `tests.toml` file. This is
purely to help the reader to identify reimplemented test cases.

An example test case for the `hamming` exercise:

```toml
[b9228bb1-465f-4141-b40f-1f99812de5a8]
description = "disallow first strand longer"
reimplements = "919f8ef0-b767-4d1b-8516-6379d07fcb28"
```

This commit also tries to improve the comment at the start of the
`tests.toml` file.

Closes: #316

Co-authored-by: ee7 <[email protected]>

README.md

@@ -44,9 +44,16 @@ If a track implements an exercise for which test data exists in the [problem-spe
 A `tests.toml` file has this format:
 
 ```toml
-# 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 will:
+# - Update the `description` property
+# - Update the `reimplements` property
+# - Remove `include = true` properties
+# - Preserve any other properties
+#
+# As regular comments will be removed when this file is regenerated, comments
+# can be added in a "comment" key
 
 [1e22cceb-c5e4-4562-9afe-aef07ad1eaf4]
 description = "basic"

src/sync/exercises.nim

@@ -118,12 +118,19 @@ proc prettyTomlString(a: openArray[TomlValueRef]): string =
 proc toToml(exercise: Exercise, testsPath: string): string =
   ## Returns the new contents of a `tests.toml` file that corresponds to an
   ## `exercise`. This proc reads the previous contents at `testsPath` and
-  ## preserves every property apart from `description` and `include = true`.
+  ## updates the `description` and `reimplements` properties, removes any
+  ## `include = true` properties and preserves any other property.
   result = """
-# 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 will:
+# - Update the `description` property
+# - Update the `reimplements` property
+# - Remove `include = true` properties
+# - Preserve any other properties
+#
+# As regular comments will be removed when this file is regenerated, comments
+# can be added in a "comment" key.
 """
 
   for testCase in exercise.testCases:
@@ -137,12 +144,16 @@ proc toToml(exercise: Exercise, testsPath: string): string =
       if uuid in exercise.tests.excluded:
         result.add "include = false\n"
 
+      # Always add the `reimplements` property, if present
+      if testCase.reimplements.isSome():
+        result.add &"reimplements = \"{testCase.reimplements.get().uuid}\"\n"
+
       if fileExists(testsPath):
         let currContents = parsetoml.parseFile(testsPath)
         if currContents.hasKey(uuid):
           # Preserve custom properties
           for k, v in currContents[uuid].getTable():
-            if k notin ["description", "include"].toHashSet():
+            if k notin ["description", "include", "reimplements"].toHashSet():
               let vTomlString =
                 if v.kind == String:
                   prettyTomlString(v.stringVal)

tests/test_binary.nim

@@ -127,24 +127,82 @@ All exercises are synced!
     const expectedDiffOutput = """
 --- exercises/practice/diffie-hellman/.meta/tests.toml
 +++ exercises/practice/diffie-hellman/.meta/tests.toml
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 +[0d25f8d7-4897-4338-a033-2d3d7a9af688]
 +description = "can calculate public key when given a different private key"
 +
 --- exercises/practice/grade-school/.meta/tests.toml
 +++ exercises/practice/grade-school/.meta/tests.toml
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 +[c125dab7-2a53-492f-a99a-56ad511940d8]
 +description = "A student can't be in two different grades"
 +
 --- exercises/practice/hamming/.meta/tests.toml
 +++ exercises/practice/hamming/.meta/tests.toml
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 +[db92e77e-7c72-499d-8fe6-9354d2bfd504]
 +description = "disallow left empty strand"
++reimplements = "5dce058b-28d4-4ca7-aa64-adfe4e17784c"
 +
 +
 +[920cd6e3-18f4-4143-b6b8-74270bb8f8a3]
 +description = "disallow right empty strand"
++reimplements = "38826d4b-16fb-4639-ac3e-ba027dec8b5f"
 --- exercises/practice/high-scores/.meta/tests.toml
 +++ exercises/practice/high-scores/.meta/tests.toml
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 +
 +[2df075f9-fec9-4756-8f40-98c52a11504f]
 +description = "Latest score after personal top scores"
@@ -153,6 +211,20 @@ All exercises are synced!
 +description = "Scores after personal top scores"
 --- exercises/practice/kindergarten-garden/.meta/tests.toml
 +++ exercises/practice/kindergarten-garden/.meta/tests.toml
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 -description = "first student's garden"
 +description = "for Alice, first student's garden"
 -description = "second student's garden"
@@ -187,6 +259,20 @@ All exercises are synced!
 +description = "for Larry, last student's garden"
 --- exercises/practice/prime-factors/.meta/tests.toml
 +++ exercises/practice/prime-factors/.meta/tests.toml
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 +[238d57c8-4c12-42ef-af34-ae4929f94789]
 +description = "another prime number"
 +
@@ -204,7 +290,19 @@ All exercises are synced!
 +
 --- exercises/practice/react/.meta/tests.toml
 +++ exercises/practice/react/.meta/tests.toml
-+
+-# 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 will:
++# - Update the `description` property
++# - Update the `reimplements` property
++# - Remove `include = true` properties
++# - Preserve any other properties
++#
++# As regular comments will be removed when this file is regenerated, comments
++# can be added in a "comment" key.
 +[c51ee736-d001-4f30-88d1-0c8e8b43cd07]
 +description = "input cells have a value"
 +