GHCP — Crawl Track v2.3.1: Exercises 0–10 (bksw_format + bookshelf hygiene)

[lbakerchef]

Summary

GHCP Crawl Track v2.3.1 — Exercises 0–10 on the chef/chef-server repository.

This PR documents an AI-assisted learning track using the real production codebase.
Exercises progress from scaffolding and orientation through refactoring, validation,
docs, perf measurement, dependency audit, security hygiene, structured logging,
and CI baseline work. The chosen practice module is src/bookshelf/src/bksw_format.erl
— a pure utility module with no runtime side-effects and no downstream dependencies
inside bookshelf.

---

Review Focus

These are the areas that warrant the most reviewer attention.

Area	File(s)	Why it needs eyes
Input validation guards	src/bookshelf/src/bksw_format.erl	when is_binary(Bin) guards added to to_hex/1 and to_base64/1; verify guard placement doesn't break existing callers passing non-binary
Structured logging	src/bookshelf/src/bksw_wm_sql_object.erl	3 error log lines updated to include req_id; verify pattern match on #context{reqid = ReqId} is exhaustive
Security hygiene	.gitignore, spec/fixtures/pivotal.pem	New *.pem/*.key/.env* gitignore entries; PEM header prepended — confirm header doesn't break any PEM parser that reads the fixture
Test coverage	src/bookshelf/test/bksw_format_tests.erl	8 tests total (5 positive + 3 negative); confirm negative tests use ?assertException pattern correctly
Local test script	scripts/test-bookshelf-unit.sh	Verify ERL_LIBS and erlc -I include paths are portable across different dev setups

---

Changes by Exercise

Ex	Title	Files changed	Type
0	Bootstrap scaffolding	ai-track-docs/, .copilot-track/crawl/	docs
1+2	Repo orientation + deterministic tests	SYSTEM-OVERVIEW.md, build-test.md, bksw_format_tests.erl	docs + tests
3	Readability refactor	bksw_format.erl	refactor
4	Docstrings + extending guide	bksw_format.erl, extending-bksw_format.md	docs + comments
5	Input validation + negative tests	bksw_format.erl, bksw_format_tests.erl	validation + tests
6	Performance baseline	perf-baseline.md	docs
7	Dependency audit	dependencies.md	docs
8	Security hygiene	.gitignore, pivotal.pem, setup_helper.erl, security-hygiene.md	hygiene
9	Structured logging	bksw_wm_sql_object.erl, logging.md	improvement
10	CI baseline + local script	scripts/test-bookshelf-unit.sh, build-test.md	tooling + docs

---

Risk & Rollback

Risk tiers

Risk	Items	Severity
Behaviour change	bksw_format.erl guards (when is_binary)	🟡 Low — existing callers in bksw_xml.erl, bksw_req.erl, bksw_wm_sql_object.erl, bksw_wm_object.erl all pass binary() values; no non-binary caller exists in the codebase
Log format change	bksw_wm_sql_object.erl 3 lines	🟡 Low — format change only; no logic change; operators parsing old log format for alerting rules should update regex
PEM file header	spec/fixtures/pivotal.pem	🟢 Minimal — text before -----BEGIN is valid PEM; test suite still passes
gitignore	.gitignore new patterns	🟢 Minimal — already-tracked .pem files remain tracked; only blocks future untracked files
Docs/scripts	All other files	🟢 None — additive only

Rollback

# Revert entire branch (safest — one command)
git revert --no-commit c289a28f3..HEAD && git commit -m "revert: crawl track exercises 0-10"

# Revert only the behaviour-change commits (surgical)
git revert c833ab19d  # ex5 — remove is_binary guards
git revert 062633d1d  # ex9 — revert log line changes

# Revert only the gitignore change
git revert 67ad2fed4  # ex8 — remove secret file patterns

---

Verification Steps

# 1. Run bksw_format unit tests (all 8 must pass)
bash scripts/test-bookshelf-unit.sh verbose

# Expected last line:
#   All 8 tests passed.

# 2. Confirm is_binary guards reject non-binary inputs
erl -noshell -pa /tmp -eval '
  catch bksw_format:to_hex("string"),
  catch bksw_format:to_hex(42),
  io:format("guards ok~n"),
  init:stop()
'

# 3. Confirm req_id appears in error log format
grep -n "req_id" src/bookshelf/src/bksw_wm_sql_object.erl

# 4. Confirm no real credentials in tracked files
git grep -n "BEGIN RSA PRIVATE KEY" -- "*.erl" "*.rb"
# Expected: only itest/ and spec/ paths

# 5. Confirm gitignore does not un-track existing .pem files
git ls-files src/chef-server-ctl/spec/fixtures/pivotal.pem
git ls-files src/chef-server-ctl/habitat/config/pivotal.pem
# Both must print the path (still tracked)

---

Evidence

All 8 unit tests passing

======================== EUnit ========================
module 'bksw_format_tests'
  to_hex_produces_lowercase_hex_string_test...[0.003 s] ok
  to_hex_empty_binary_produces_empty_string_test...ok
  to_hex_rejects_string_input_test...ok
  to_hex_rejects_integer_input_test...ok
  to_base64_encodes_binary_test...[0.014 s] ok
  to_base64_rejects_string_input_test...ok
  to_etag_wraps_hex_in_quotes_test...ok
  to_date_undefined_returns_epoch_test...ok
  [done in 0.041 s]
=======================================================
  All 8 tests passed.

Performance baseline (key numbers)

Function	Input	avg latency
to_hex/1	16 B	20 µs
to_hex/1	1 024 B	1 485 µs
to_base64/1	1 024 B	23 µs

No optimization action required.

Security audit summary

• ✅ No hardcoded production credentials
• ✅ Bookshelf uses chef_secrets:get/2 at runtime
• ✅ oc_chef_action redacts "password" field from audit logs
• 🟡 4 deps branch-tracked in rebar.lock (see ai-track-docs/dependencies.md)
• 🟡 Ruby 3.1 and Redis 5.x are EOL (noted, out of scope for this track)

---

Proposed Commit Message Improvements

Two commits have suboptimal messages. Proposed rewrites (for reference — not
amended in this PR since history is already pushed):

c289a28f3 — missing exercise prefix:

# Current
ghcp(crawl): ex0 bootstrap scaffolding

# Proposed
exercise 0 — ghcp(crawl): bootstrap scaffolding for Crawl track

Added ai-track-docs/ (SYSTEM-OVERVIEW, build-test, architecture.mmd)
and .copilot-track/crawl/README.md with chain-PR conventions and
evidence block template.

d83daa927 — says "exercise 2" but covers exercises 1 and 2:

# Current
exercise 2 — ghcp(crawl): ex1+ex2 repo orientation, low-risk module, deterministic tests

# Proposed
exercise 1+2 — ghcp(crawl): repo orientation, module selection, deterministic tests

- Ex1: service map, language table, entry points, test approach in SYSTEM-OVERVIEW.md
- Ex2: verified bookshelf build commands, bksw_format chosen as low-risk module,
  bksw_format_tests.erl with 5 deterministic EUnit tests (all passing)

Future exercises: the exercise N — ghcp(crawl): <verb> <what> pattern is
working well; keep subject line under 72 chars and use the body for why.

---

Track

• Level: Crawl
• Version: v2.3.1
• Exercises completed: 0–10 of 15
• Branch: learn/crawl/lbaker-ex0-bootstrap
• Practice module: src/bookshelf/src/bksw_format.erl

[netlify]

👷 Deploy Preview for chef-server processing.

Name	Link
🔨 Latest commit	a6bc5d6
🔍 Latest deploy log	https://app.netlify.com/projects/chef-server/deploys/6a0b940078ef25000887411f