fix(learn): generate starter files that are valid bash

CHANGELOG.md

@@ -6,6 +6,7 @@
 - `--verbose` warns on Bash 3.x that coverage does not count lines run inside a subshell, so a percentage that reads lower there than on Bash 4+ explains itself (#1112)
 
 ### Changed
+- `bashunit learn` generates starter files that are valid bash. A function body of only TODO comments is a syntax error, so 7 of the 10 lesson templates did not parse and a learner running the lesson saw `syntax error near unexpected token '}'` from a file bashunit itself wrote. Lesson verification also runs with `--fail-on-risky`, so an untouched template no longer completes a lesson — a test with no assertions is risky, and risky exits 0 (#1256)
 - The coverage HTML report handles filenames containing `|`, `<` or `&`. Rows were joined and split on `|`, so `src/a|b.sh` truncated to `a` in the index while the coverage numbers stayed right, and filenames went into the markup unescaped — `a<b>c.sh` was parsed as a tag and leaked into the document. The escaper now lives in `src/util/str.sh`, shared with the test report instead of duplicated (#1254)
 - The HTML report summary counts risky and flaky tests. A run with a risky test showed `2 total` against categories summing to 1, with nothing on the page saying where the second test went — the row was there with its own CSS class, but the summary never counted it. The console and the Markdown report both report it (#1252)
 - The HTML report says **why** a test failed. It listed name, status and duration only, while JUnit, JSON, TAP and Markdown all carry the message — and HTML is the format opened in a browser to find out what broke. A `Failures` section now gives each failure its name, `file:line` and message; a green run gains nothing (#1251)

src/learn/lessons/basics.sh

@@ -50,6 +50,7 @@ EOF
 function test_bashunit_works() {
   # TODO: Use assert_same to check if "hello" equals "hello"
   # Hint: assert_same "expected" "actual"
+  :
 }'
 
     bashunit::learn::create_example_file "$test_file" "$template"

src/learn/lessons/challenge.sh

@@ -69,14 +69,17 @@ function set_up() {
 
 function tear_down() {
   # TODO: Clean up test files
+  :
 }
 
 function test_successful_backup() {
   # TODO: Test backup creation
+  :
 }
 
 function test_backup_failure_when_source_missing() {
   # TODO: Test failure case
+  :
 }
 
 # Add more tests as needed:

src/learn/lessons/data_providers.sh

@@ -86,22 +86,26 @@ function set_up() {
 function data_provider_valid_emails() {
   # TODO: Echo valid email addresses, one per line
   # Example: echo "user@example.com"
+  :
 }
 
 function test_valid_emails() {
   # $1 contains the email from data provider
   # TODO: Assert is_valid_email succeeds
   # Hint: assert_successful_code "is_valid_email \"$1\""
+  :
 }
 
 function data_provider_invalid_emails() {
   # TODO: Echo invalid email addresses, one per line
   # Example: echo "not-an-email"
+  :
 }
 
 function test_invalid_emails() {
   # TODO: Assert is_valid_email fails
   # Hint: assert_general_error "is_valid_email \"$1\""
+  :
 }'
 
     bashunit::learn::create_example_file "$test_file" "$template"

src/learn/lessons/exit_codes.sh

@@ -99,11 +99,13 @@ function tear_down() {
 function test_existing_file_returns_success() {
   # TODO: Assert check_file succeeds with TEST_FILE
   # Hint: assert_successful_code "check_file '\''$TEST_FILE'\''"
+  :
 }
 
 function test_missing_file_returns_127() {
   # TODO: Assert check_file returns exit code 127 for missing file
   # Hint: assert_exit_code 127 "check_file '\''/nonexistent/file'\''"
+  :
 }'
 
     bashunit::learn::create_example_file "$test_file" "$template"

src/learn/lessons/functions.sh

@@ -69,18 +69,21 @@ EOF
 function set_up() {
   # TODO: Source calculator.sh from parent directory
   # Hint: source ../calculator.sh
+  :
 }
 
 function test_add_positive_numbers() {
   # TODO: Test that add 2 3 returns "5"
   # Hint: result=$(add 2 3)
   # Hint: assert_same "5" "$result"
+  :
 }
 
 function test_add_negative_numbers() {
   # TODO: Test that add -2 -3 returns "-5"
   # Hint: result=$(add -2 -3)
   # Hint: assert_same "-5" "$result"
+  :
 }'
 
     bashunit::learn::create_example_file "$test_file" "$template"

src/learn/lessons/lifecycle.sh

@@ -66,19 +66,23 @@ function set_up() {
   # Create a temp file before each test
   # TODO: export TEST_FILE="/tmp/test_$$"
   # TODO: echo "test content" > "$TEST_FILE"
+  :
 }
 
 function tear_down() {
   # Clean up after each test
   # TODO: rm -f "$TEST_FILE"
+  :
 }
 
 function test_file_exists() {
   # TODO: assert_file_exists "$TEST_FILE"
+  :
 }
 
 function test_file_has_content() {
   # TODO: assert_file_contains "test content" "$TEST_FILE"
+  :
 }'
 
     bashunit::learn::create_example_file "$test_file" "$template"

src/learn/lessons/scripts.sh

@@ -70,6 +70,7 @@ function test_default_greeting() {
 
   # TODO: Assert output contains "Hello, World!"
   # Hint: assert_contains "Hello, World!" "$output"
+  :
 }
 
 function test_custom_greeting() {
@@ -78,6 +79,7 @@ function test_custom_greeting() {
 
   # TODO: Assert output contains "Hello, Alice!"
   # Hint: assert_contains "Hello, Alice!" "$output"
+  :
 }'
 
     bashunit::learn::create_example_file "$test_file" "$template"

src/learn/session.sh

@@ -53,7 +53,11 @@ function bashunit::learn::run_lesson_test() {
   echo "${_BASHUNIT_COLOR_BOLD}Running your test...${_BASHUNIT_COLOR_DEFAULT}"
   echo ""
 
-  if "$BASHUNIT_ROOT_DIR/bashunit" "$test_file" --simple; then
+  # --fail-on-risky, or an untouched template completes the lesson: a test whose
+  # body is still only TODO comments records no assertions, which is *risky*,
+  # and risky exits 0 by default. The learner is told "Excellent!" for work they
+  # have not done (#1256).
+  if "$BASHUNIT_ROOT_DIR/bashunit" "$test_file" --simple --fail-on-risky; then
     echo ""
     printf "%s%s✓ Excellent! Lesson %s completed!%s\n" \
       "$_BASHUNIT_COLOR_PASSED" "$_BASHUNIT_COLOR_BOLD" "$lesson_number" "$_BASHUNIT_COLOR_DEFAULT"

tests/unit/project/learn_templates_test.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+
+# `bashunit learn` writes a starter file for each lesson. Seven of the ten
+# templates did not parse: a function body of only TODO comments is a bash
+# syntax error, and there were 28 such bodies. A learner who generated the file
+# and ran the lesson got
+#
+#   syntax error near unexpected token `}'
+#
+# from a file bashunit itself had written -- which says nothing about the
+# lesson and is a newcomer's first contact with the tool (#1256).
+#
+# Templates are heredoc-free string literals, so nothing else checks them:
+# ShellCheck sees a string, and no test sourced one. This does.
+
+function set_up_before_script() {
+  ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+}
+
+# Every `local template='…'` block in the lesson files, NUL-separated so an
+# embedded newline does not split one template into several.
+#
+# awk, not perl: Alpine ships without perl, and the snapshot placeholder tests
+# already skip there for that reason -- but template validity does not depend
+# on the platform, so this has to run everywhere rather than skip.
+#
+# The block ends at the first line whose last character is the closing quote.
+# That is safe because no line *inside* a template ends in one; the only such
+# line in these files sits in the `cat <<'EOF'` lesson text, outside any
+# template. Checked against a perl extractor: both find 10 templates and agree
+# on which parse.
+function _lesson_templates() { # $1 = lessons dir
+  local file
+  for file in "$1"/*.sh; do
+    awk '
+      index($0, "local template=\047") {
+        intpl = 1
+        sub(/^.*local template=\047/, "")
+      }
+      intpl {
+        if (substr($0, length($0), 1) == "\047") {
+          sub(/\047$/, "")
+          print
+          printf "%c", 0
+          intpl = 0
+          next
+        }
+        print
+      }
+    ' "$file"
+  done
+}
+
+function test_every_lesson_template_is_valid_bash() {
+  local invalid=""
+  local tpl
+  local tmp
+  tmp="$(bashunit::temp_file)"
+
+  while IFS= read -r -d '' tpl; do
+    printf '%s\n' "$tpl" >"$tmp"
+    if ! bash -n "$tmp" 2>/dev/null; then
+      invalid="$invalid$(printf '%s\n' "$tpl" | "$GREP" -m1 'function' || true) "
+    fi
+  done < <(_lesson_templates "$ROOT_DIR/src/learn/lessons")
+
+  assert_empty "$invalid"
+}
+
+# A check that cannot fail proves nothing: the templates are expected to parse,
+# so without this the scan above would keep passing if the extraction silently
+# stopped matching.
+function test_the_scan_flags_a_template_that_does_not_parse() {
+  local dir
+  dir="$(bashunit::temp_dir)"
+  {
+    printf '%s\n' '#!/usr/bin/env bash'
+    printf '%s\n' 'function bashunit::learn::lesson_probe() {'
+    printf '%s\n' "    local template='#!/usr/bin/env bash"
+    printf '%s\n' 'function test_probe() {'
+    printf '%s\n' '  # only a comment, which bash rejects'
+    printf '%s\n' "}'"
+    printf '%s\n' '}'
+  } >"$dir/probe.sh"
+
+  local found=false
+  local tpl tmp
+  tmp="$(bashunit::temp_file)"
+  while IFS= read -r -d '' tpl; do
+    printf '%s\n' "$tpl" >"$tmp"
+    bash -n "$tmp" 2>/dev/null || found=true
+  done < <(_lesson_templates "$dir")
+
+  assert_same "true" "$found"
+}
+
+# The other half of #1256: a template that parses but has no assertions must not
+# complete a lesson. `run_lesson_test` treats exit 0 as success, and a test
+# without assertions is risky, which exits 0 unless --fail-on-risky is passed.
+function test_the_lesson_runner_fails_a_test_with_no_assertions() {
+  assert_file_contains "$ROOT_DIR/src/learn/session.sh" "--fail-on-risky"
+}