Hands-on lab — Day 37: Debuggers, Linters, and Formatters

#!/usr/bin/env bash
# quality_check.sh — a tiny, editor-agnostic quality gate for shell scripts.
#
# Runs three checks on a target script and prints a report:
#   1. Syntax check with `bash -n` (the shell's own built-in check).
#   2. Lint with `shellcheck` IF it is installed; otherwise it reports that
#      clearly and describes what shellcheck would catch (graceful degrade).
#   3. Formatting check with `grep`: trailing whitespace and tab indentation.
#
# It is a REPORT, not a gate: it always exits 0 so it never blocks your work.
# Usage:  bash quality_check.sh [path/to/script.sh]
set -u

target="${1:-examples/samples/buggy.sh}"

if [ ! -f "$target" ]; then
  echo "Error: file not found: $target" >&2
  echo "Usage: bash quality_check.sh [path/to/script.sh]" >&2
  exit 2
fi

tab="$(printf '\t')"
syntax_state="OK"
lint_state="reported"
fmt_state="clean"

echo "=== Quality check: ${target} ==="
echo

# ---- 1. Syntax ------------------------------------------------------------
echo "[1/3] Syntax check (bash -n)..."
syntax_err="$(bash -n "$target" 2>&1)"
if [ -z "$syntax_err" ]; then
  echo "  ok: script is syntactically valid."
else
  echo "  FAIL: syntax error(s):"
  printf '%s\n' "$syntax_err" | sed 's/^/    /'
  syntax_state="errors"
fi
echo

# ---- 2. Lint --------------------------------------------------------------
echo "[2/3] Lint check (shellcheck)..."
if command -v shellcheck >/dev/null 2>&1; then
  if shellcheck "$target"; then
    echo "  ok: shellcheck found no issues."
    lint_state="clean"
  else
    echo "  (shellcheck findings above — each SCxxxx code links to an explanation.)"
    lint_state="findings"
  fi
else
  echo "  SKIP: shellcheck is not installed on this machine."
  echo "        Install it (free) to catch bugs like:"
  echo "        - SC2086: unquoted \$variable may word-split or glob"
  echo "        - SC2034: variable appears unused"
  echo "        - using [ ] where [[ ]] is safer"
  echo "        See requirements/README.md for install instructions."
  lint_state="skipped (shellcheck absent)"
fi
echo

# ---- 3. Formatting --------------------------------------------------------
echo "[3/3] Formatting check (trailing whitespace / tabs)..."
ws_hits="$(grep -nE '[[:space:]]+$' "$target" || true)"
tab_hits="$(grep -n "$tab" "$target" || true)"

if [ -n "$ws_hits" ]; then
  count="$(printf '%s\n' "$ws_hits" | grep -c .)"
  echo "  FAIL: found ${count} line(s) with trailing whitespace."
  printf '%s\n' "$ws_hits" | sed 's/^/    /'
  fmt_state="issues found"
else
  echo "  ok: no trailing whitespace."
fi

if [ -n "$tab_hits" ]; then
  count="$(printf '%s\n' "$tab_hits" | grep -c .)"
  echo "  FAIL: found ${count} line(s) containing tab indentation."
  printf '%s\n' "$tab_hits" | sed 's/^/    /'
  fmt_state="issues found"
else
  echo "  ok: no tab indentation."
fi
echo

echo "Summary: syntax ${syntax_state}; lint ${lint_state}; formatting ${fmt_state}."
exit 0

#!/bin/bash
# buggy.sh - a deliberately flawed sample for the Day 37 lab.
# It is syntactically valid (bash -n passes) and it runs, yet a linter
# finds real bugs. Treat it as an exhibit to inspect, not code to trust.

name=$1
unused_greeting="Hello there"

if [ $name = "admin" ]; then
  echo "Welcome, admin"
fi

echo "Hi, $name"   
	echo "all done"

lesson_id: D037
day: 37
kind: command-line-inspection
languages: [bash]
setup_commands:
  - cd labs/sections/computing-foundations/day-037-debuggers-linters-and-formatters
run_commands:
  - bash examples/quality_check.sh examples/samples/buggy.sh
  - bash starter/quality_check.sh examples/samples/buggy.sh
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'git checkout -- examples/samples/buggy.sh  # optional: restore the intentional flaws if your editor stripped them'
requires_network: false
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-12'
executed_on: 'macOS (Apple Silicon), shellcheck NOT installed — bash tests/run_tests.sh → 9 checks, 0 failure(s); lint step degraded gracefully (SKIP)'

# Dependencies — Day 37 lab

**Required: a POSIX shell only.** The lab runs on tools that ship with your OS:

- `bash` ≥ 3.2 (preinstalled on macOS and every mainstream Linux distribution)
- Standard utilities: `grep`, `sed`, `printf`, `mktemp` — all part of the base system

There is deliberately no `requirements.txt` / `package.json`: the quality
check must run on a factory-fresh machine.

## Optional (recommended): ShellCheck

[ShellCheck](https://www.shellcheck.net/) is a free, open-source linter for
shell scripts. The lab **works without it** — the quality check detects its
absence and reports what it would have caught — but installing it turns the
lint step on and lets you see real findings. It is free and worth having.

Install (all free):

- **macOS (Homebrew):** `brew install shellcheck`
- **Debian / Ubuntu:** `sudo apt install shellcheck`
- **Fedora:** `sudo dnf install ShellCheck`
- **Windows:** install under WSL with the Ubuntu instructions, or use `scoop install shellcheck`

Verify with `shellcheck --version`. After installing, re-run
`bash examples/quality_check.sh examples/samples/buggy.sh` and step [2/3] will
show real SC-code findings instead of the SKIP block.

No account, API key, or network access is required for any part of this lab
(installing ShellCheck is the only step that uses the network, and it is
optional).

#!/usr/bin/env bash
# quality_check.sh — YOUR working file for the Day 37 lab.
#
# This starter already handles the plumbing: it takes a target script, checks
# the file exists, and prints the report headers. Your job is to fill in the
# four numbered exercises below with the exact command named in each comment.
# The completed reference version is examples/quality_check.sh — try the
# exercises yourself first, then compare.
set -u

target="${1:-examples/samples/buggy.sh}"

if [ ! -f "$target" ]; then
  echo "Error: file not found: $target" >&2
  echo "Usage: bash quality_check.sh [path/to/script.sh]" >&2
  exit 2
fi

tab="$(printf '\t')"

echo "=== Quality check: ${target} ==="
echo

# ---- 1. Syntax ------------------------------------------------------------
echo "[1/3] Syntax check (bash -n)..."
# Exercise 1: capture the output of `bash -n "$target" 2>&1` into syntax_err.
# `bash -n` checks syntax WITHOUT running the script; clean scripts print
# nothing. Replace the empty assignment below with the real command.
syntax_err=""   # <-- Exercise 1: syntax_err="$(bash -n "$target" 2>&1)"
if [ -z "$syntax_err" ]; then
  echo "  ok: script is syntactically valid."
else
  echo "  FAIL: syntax error(s):"
  printf '%s\n' "$syntax_err" | sed 's/^/    /'
fi
echo

# ---- 2. Lint --------------------------------------------------------------
echo "[2/3] Lint check (shellcheck)..."
# Exercise 2: detect shellcheck gracefully. Replace the word 'false' below
# with a real test for the command: command -v shellcheck >/dev/null 2>&1
if false; then   # <-- Exercise 2: if command -v shellcheck >/dev/null 2>&1; then
  shellcheck "$target" && echo "  ok: shellcheck found no issues."
else
  echo "  SKIP: shellcheck is not installed (or not detected)."
  echo "        Install it (free) to catch SC2086 (unquoted \$var),"
  echo "        SC2034 (unused variable), and [ ] vs [[ ]] issues."
  echo "        See requirements/README.md for install instructions."
fi
echo

# ---- 3. Formatting --------------------------------------------------------
echo "[3/3] Formatting check (trailing whitespace / tabs)..."
# Exercise 3: find trailing whitespace. Replace the empty assignment with:
#   grep -nE '[[:space:]]+$' "$target" || true
ws_hits=""      # <-- Exercise 3: ws_hits="$(grep -nE '[[:space:]]+$' "$target" || true)"
# Exercise 4: find tab indentation. Replace the empty assignment with:
#   grep -n "$tab" "$target" || true
tab_hits=""     # <-- Exercise 4: tab_hits="$(grep -n "$tab" "$target" || true)"

if [ -n "$ws_hits" ]; then
  echo "  FAIL: lines with trailing whitespace:"
  printf '%s\n' "$ws_hits" | sed 's/^/    /'
else
  echo "  ok: no trailing whitespace (or exercise 3 not yet done)."
fi
if [ -n "$tab_hits" ]; then
  echo "  FAIL: lines containing tab indentation:"
  printf '%s\n' "$tab_hits" | sed 's/^/    /'
else
  echo "  ok: no tab indentation (or exercise 4 not yet done)."
fi
echo

echo "Report complete (this script always exits 0 — it reports, it does not block)."
exit 0

# Quality worksheet — Day 37 lab

Fill this in for `examples/samples/buggy.sh` after running the quality check.
Record real line numbers from the output. Keep this file — it seeds the
Week 6 project (formatting and linting on every commit).

## 1. One issue `bash -n` catches (syntax)

`bash -n` only reports problems the shell cannot even parse. The sample as
shipped is syntactically valid, so to see this check *fire*, introduce a
syntax error on purpose (for example, delete the `fi` on line 11), run
`bash -n examples/samples/buggy.sh`, record the message, then undo the edit.

- Syntax error I introduced: `________________________________`
- What `bash -n` reported (message + line): `________________________________`

## 2. One issue ShellCheck catches — or would (lint / pattern)

If ShellCheck is installed, run it and record a real finding with its SC
code. If it is not installed, describe one bug from the lesson that it
*would* catch (the unquoted `$name` in the `[ ]` test, or the unused
`unused_greeting`).

- Rule code (if you have ShellCheck), e.g. `SC2086` or `SC2034`: `____________`
- The line and what is wrong with it: `________________________________`
- Why running the script does NOT reveal this bug: `____________________`

## 3. One formatting issue (whitespace check)

Run `bash examples/quality_check.sh examples/samples/buggy.sh` and read
section [3/3].

- Line number with trailing whitespace: `______`
- Line number with tab indentation: `______`

## 4. Short paragraph: why "it parses" is not "it's correct"

Write 4–6 sentences, in your own words, explaining why a script can pass the
syntax check (`bash -n`) yet still be full of the bugs a linter finds. Tie it
to the difference between "the shell can parse this" and "this will behave
correctly for every input."

```
(your paragraph here)
```

#!/usr/bin/env bash
# Tests for the Day 37 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# Verifies the quality-check pipeline behaves correctly:
#   - `bash -n` flags a broken variant of the sample
#   - the formatting check flags trailing whitespace in the buggy sample
#   - the quality check exits 0 whether or not shellcheck is installed
#     (lint is skipped, not failed, when shellcheck is absent)
# No network access is used anywhere.
set -u

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
sample="${lab_dir}/examples/samples/buggy.sh"
checker="${lab_dir}/examples/quality_check.sh"
tmp="$(mktemp -d "${TMPDIR:-/tmp}/day37.XXXXXX")"
trap 'rm -rf "${tmp}"' EXIT

failures=0
checks=0

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

echo "Testing the Day 37 quality pipeline ..."

# 0. Fixtures exist.
[ -f "${sample}" ] && check "buggy sample exists" "yes" || check "buggy sample exists" "no"
[ -f "${checker}" ] && check "quality_check.sh exists" "yes" || check "quality_check.sh exists" "no"

# 1. The shipped sample is syntactically valid (bash -n exits 0, no output).
if bash -n "${sample}" >/dev/null 2>&1; then
  check "bash -n accepts the valid sample" "yes"
else
  check "bash -n accepts the valid sample" "no"
fi

# 2. bash -n FLAGS a broken variant (missing 'fi' → parse error, non-zero).
broken="${tmp}/broken.sh"
grep -v '^fi$' "${sample}" > "${broken}"
if bash -n "${broken}" >/dev/null 2>&1; then
  check "bash -n flags a broken variant" "no"
else
  check "bash -n flags a broken variant" "yes"
fi

# 3. The quality check flags trailing whitespace in the buggy sample.
out="$(bash "${checker}" "${sample}" 2>&1)"
echo "${out}" | grep -q "trailing whitespace" && \
  check "formatting check flags trailing whitespace" "yes" || \
  check "formatting check flags trailing whitespace" "no"

# 4. The quality check flags the tab-indented line.
echo "${out}" | grep -q "tab indentation" && \
  check "formatting check flags tab indentation" "yes" || \
  check "formatting check flags tab indentation" "no"

# 5. The quality check exits 0 (report, not gate) regardless of shellcheck.
if bash "${checker}" "${sample}" >/dev/null 2>&1; then
  check "quality check exits 0" "yes"
else
  check "quality check exits 0" "no"
fi

# 6. Lint is skipped-not-failed when shellcheck is absent; run when present.
if command -v shellcheck >/dev/null 2>&1; then
  echo "${out}" | grep -qi "shellcheck" && \
    check "lint step runs shellcheck (installed)" "yes" || \
    check "lint step runs shellcheck (installed)" "no"
else
  echo "${out}" | grep -q "SKIP: shellcheck is not installed" && \
    check "lint step skips gracefully (shellcheck absent)" "yes" || \
    check "lint step skips gracefully (shellcheck absent)" "no"
fi

# 7. On a clean file, the formatting check reports no issues.
clean="${tmp}/clean.sh"
printf '#!/bin/bash\necho "clean"\n' > "${clean}"
clean_out="$(bash "${checker}" "${clean}" 2>&1)"
echo "${clean_out}" | grep -q "no trailing whitespace" && \
  check "clean file passes the whitespace check" "yes" || \
  check "clean file passes the whitespace check" "no"

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ]