Home /Modules/scripts/tutorial-check.sh

tutorial-check.sh

scripts/tutorial-check.sh · 152 line(s) · bash

#!/bin/bash

# =============================================================================
# tutorial-check.sh — Verify the tutorial and examples inventories
# =============================================================================
#
# Usage:
#   ./scripts/tutorial-check.sh        # run from the repository root
#   make tutorial-check                # via the root build dispatcher
#
# What it verifies (fail-closed, exit 1 on any problem):
#   1. tutorial/README.md exists and every lesson it links resolves to a file.
#   2. The tutorial lessons are a contiguous, zero-padded 01..NN sequence.
#   3. examples/ contains at least one .xml example.
#   4. Every example .xml is well-formed XML (xmllint, else Python fallback).
#   5. Every example family that examples/README.md says has expected evidence
#      has its matching .expected.* witness file on disk, and every .expected.*
#      file on disk has a corresponding .xml example (no orphans).
#
# Dependencies: bash, grep, sed, sort. XML well-formedness uses xmllint when
# present and falls back to the configured Python 3 launcher; if neither is available that check
# is skipped with a notice rather than failing the build.
# =============================================================================

set -u

# Resolve the repository root from this script's location so the check works
# regardless of the caller's current directory.
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
cd "$REPO_ROOT" || { echo "tutorial-check: FAIL - cannot cd to repo root" >&2; exit 1; }

TUT_DIR="tutorial"
EX_DIR="examples"
fail=0

fail_msg() { echo "tutorial-check: FAIL - $1" >&2; fail=1; }

# --- 1. tutorial/README.md and its linked lessons -------------------------
if [ ! -f "$TUT_DIR/README.md" ]; then
  fail_msg "missing $TUT_DIR/README.md inventory"
  linked=""
else
  # Markdown links of the form (NN-slug.md); de-duplicate, keep order.
  linked=$(grep -oE '\(([0-9]+-[a-z0-9-]+\.md)\)' "$TUT_DIR/README.md" \
             | tr -d '()' | awk '!seen[$0]++')
  if [ -z "$linked" ]; then
    fail_msg "no lesson links found in $TUT_DIR/README.md"
  fi
fi

tut_linked=0
for lesson in $linked; do
  tut_linked=$((tut_linked + 1))
  if [ ! -f "$TUT_DIR/$lesson" ]; then
    fail_msg "lesson linked in README is missing on disk: $TUT_DIR/$lesson"
  fi
done

# --- 2. contiguous, zero-padded lesson numbering --------------------------
nums=$(ls "$TUT_DIR"/[0-9][0-9]-*.md 2>/dev/null | sed -E 's#.*/([0-9]+)-.*#\1#' | sort -n | uniq)
tut_files=0
expected=1
for n in $nums; do
  tut_files=$((tut_files + 1))
  want=$(printf '%02d' "$expected")
  if [ "$n" != "$want" ]; then
    fail_msg "lesson numbering gap: expected $want, found $n"
  fi
  expected=$((expected + 1))
done
if [ "$tut_files" -eq 0 ]; then
  fail_msg "no numbered tutorial lessons ($TUT_DIR/NN-*.md) found"
fi

# --- 3. examples present --------------------------------------------------
ex_xml=$(ls "$EX_DIR"/*.xml 2>/dev/null | wc -l | tr -d ' ')
if [ "$ex_xml" -eq 0 ]; then
  fail_msg "no example projects ($EX_DIR/*.xml) found"
fi

# --- 4. XML well-formedness ----------------------------------------------
xml_checker=""
xml_python="${PYTHON:-}"
if command -v xmllint >/dev/null 2>&1; then
  xml_checker="xmllint"
elif [ -n "$xml_python" ] && command -v "${xml_python%% *}" >/dev/null 2>&1; then
  xml_checker="python"
elif command -v python3 >/dev/null 2>&1; then
  xml_python="python3"
  xml_checker="python"
elif command -v python >/dev/null 2>&1; then
  xml_python="python"
  xml_checker="python"
elif command -v py >/dev/null 2>&1; then
  xml_python="py -3"
  xml_checker="python"
fi

if [ -z "$xml_checker" ]; then
  echo "tutorial-check: FAIL - XML validation requires xmllint or Python 3" >&2
  fail=1
else
  for xml in "$EX_DIR"/*.xml; do
    [ -e "$xml" ] || continue
    if [ "$xml_checker" = "xmllint" ]; then
      if ! xmllint --noout "$xml" 2>/dev/null; then
        fail_msg "malformed XML: $xml"
      fi
    else
      if ! $xml_python -c 'import sys,xml.dom.minidom as m; m.parse(sys.argv[1])' "$xml" 2>/dev/null; then
        fail_msg "malformed XML: $xml"
      fi
    fi
  done
fi

# --- 5. expected-evidence pairing ----------------------------------------
# README families that declare an expected-evidence file: the README names the
# witness filename directly (e.g. `07-post.expected.txt`). Each named witness
# must exist, and each witness on disk must pair with a sibling .xml example.
if [ -f "$EX_DIR/README.md" ]; then
  declared=$(grep -oE '[0-9]+-[a-z0-9-]+\.expected\.[a-z0-9]+' "$EX_DIR/README.md" \
               | awk '!seen[$0]++')
  for w in $declared; do
    if [ ! -f "$EX_DIR/$w" ]; then
      fail_msg "README declares expected evidence that is missing: $EX_DIR/$w"
    fi
  done
fi

# Every .expected.* on disk must have a matching .xml example (no orphans).
exp_count=0
for exp in "$EX_DIR"/*.expected.*; do
  [ -e "$exp" ] || continue
  exp_count=$((exp_count + 1))
  base=$(basename "$exp")
  stem="${base%%.expected.*}"
  if [ ! -f "$EX_DIR/$stem.xml" ]; then
    fail_msg "expected-evidence file has no matching example: $exp (want $EX_DIR/$stem.xml)"
  fi
done

# --- Result ---------------------------------------------------------------
if [ "$fail" -ne 0 ]; then
  echo "tutorial-check: FAILED" >&2
  exit 1
fi

echo "tutorial-check: OK - $tut_files tutorial lesson(s) ($tut_linked linked in README), $ex_xml example(s), $exp_count expected-evidence witness(es)"
exit 0