exercises: provide stubs for every exercise (#474)

Before this commit, the user-facing solution file was empty for every
exercise apart from:

- `clock`

- `dnd-character`

- `hello-world`

- `react`

Add initial content to that file for every other exercise.

Also, check in CI that every exercise has a test/stub file pair that:

- compiles without error

- runs _with_ an error (because we want the stub to fail the tests)

This required adding the missing fields to the `Character` object in
`dnd-character`.

There are some remaining questions, such as:

- What is the best placeholder return type for a procedure that could
  return e.g. a Table, CountTable, or array?

- How should we handle parameters with default values in e.g.
  `scale-generator`, `twelve-days`, and `two-fer`?

- To what extent should we provide doc comments?

But let's consider those questions later.

One implemented decision: always use `proc` instead of `func`, to better
support debugging via `echo`.

Closes: #409
Closes: #410

Author: ee7

.github/workflows/exercises.yml

@@ -55,3 +55,9 @@ jobs:
 
       - name: Run `check_exercises`
         run: _test/check_exercises
+
+      - name: Compile `check_stubs.nim`
+        run: nim c --styleCheck:error _test/check_stubs.nim
+
+      - name: Run `check_stubs`
+        run: _test/check_stubs

_test/check_stubs.nim

@@ -0,0 +1,55 @@
+import std/[os, osproc, strformat, strutils]
+
+iterator walkExerciseDirs: string =
+  const repoRootDir = currentSourcePath().parentDir().parentDir()
+  for exerciseKind in ["concept", "practice"]:
+    for exerciseDir in walkDirs(repoRootDir / "exercises" / exerciseKind / "*"):
+      yield exerciseDir
+
+proc checkStubs: seq[string] =
+  ## Compiles and runs the test file for every exercise, using the user-facing
+  ## solution stub.
+  ##
+  ## Returns the exercise slugs for which the corresponding test file either:
+  ##
+  ## - compiles with an error
+  ##
+  ## - runs without an error (the solution stub is supposed to fail the tests)
+  result = @[]
+  stderr.writeLine "Checking stubs..."
+  for exerciseDir in walkExerciseDirs():
+    let slug = exerciseDir.lastPathPart()
+    let testPath = exerciseDir / &"test_{slug.replace('-', '_')}.nim"
+    stderr.writeLine &"{slug}"
+    const nimOptions = "--hints:off --usenimcache --filenames:canonical " &
+                       "--spellSuggest:0 --styleCheck:error"
+    let (outpCompile, errCompile) = execCmdEx(&"nim c {nimOptions} {testPath}")
+    if errCompile == 0:
+      let (outpRun, errRun) = execCmdEx(&"nim r --hints:off {testPath}")
+      if errRun == 0:
+        stderr.write outpRun
+        stderr.writeLine &"Error: the {slug} stub passed the tests\n"
+        result.add slug
+    else:
+      stderr.writeLine outpCompile
+      result.add slug
+
+proc main =
+  let errorSlugs = checkStubs()
+  if errorSlugs.len > 0:
+    let msg = fmt"""
+
+      Error: there were {errorSlugs.len} exercises with a problematic stub:
+      {errorSlugs.join(", ")}""".unindent()
+    echo msg
+    quit 1
+  else:
+    const msg = """
+
+      Success. Every exercise has a test file and stub that:
+      - compiles without error
+      - runs with an error (we want the stub to fail the tests)""".unindent()
+    echo msg
+
+when isMainModule:
+  main()

exercises/concept/lasagna/lasagna.nim

@@ -0,0 +1,14 @@
+let expectedMinutesInOven* = 5
+
+proc remainingMinutesInOven*(actualMinutesInOven: int): int =
+  ## Returns the number of minutes that the lasagna still needs to remain in the
+  ## oven to be properly prepared.
+  discard
+
+proc preparationTimeInMinutes*(numberOfLayers: int): int =
+  ## Returns the total preparation time for a given number of layers.
+  discard
+
+proc totalTimeInMinutes*(numberOfLayers, actualMinutesInOven: int): int =
+  ## Returns the total time required to prepare the lasagna.
+  discard

exercises/practice/acronym/acronym.nim

@@ -0,0 +1,2 @@
+proc abbreviate*(s: string): string =
+  discard

exercises/practice/all-your-base/all_your_base.nim

@@ -0,0 +1,2 @@
+proc convert*(digits: openArray[int], fromBase: int, toBase: int): seq[int] =
+  discard

exercises/practice/allergies/allergies.nim

@@ -0,0 +1,9 @@
+type
+  Allergen* = enum
+    Eggs, Peanuts, Shellfish, Strawberries, Tomatoes, Chocolate, Pollen, Cats
+
+proc isAllergicTo*(score: int, allergen: Allergen): bool =
+  discard
+
+proc allergies*(score: int): set[Allergen] =
+  discard

exercises/practice/anagram/anagram.nim

@@ -0,0 +1,2 @@
+proc detectAnagrams*(word: string, candidates: openArray[string]): seq[string] =
+  discard

exercises/practice/armstrong-numbers/armstrong_numbers.nim

@@ -0,0 +1,2 @@
+proc isArmstrongNumber*(n: int): bool =
+  discard

exercises/practice/atbash-cipher/atbash_cipher.nim

@@ -0,0 +1,5 @@
+proc encode*(s: string): string =
+  discard
+
+proc decode*(s: string): string =
+  discard

exercises/practice/binary/binary.nim

@@ -0,0 +1,2 @@
+proc binary*(s: string): int =
+  discard