guillaumearm/cc-libs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
325a4327b9
cc-libs/DEVELOPMENT.md
Guillaume ARM 325a4327b9 docs: document git hook verification split
2026-06-08 16:36:07 +02:00

3.2 KiB
Raw Blame History

Development

Requirements:

  • just
  • jq
  • luacheck
  • CraftOS-PC ≥ v2.8.3 — local harness for the CC:Tweaked sandbox; see docs/craftos_pc_glossary.md for CLI flags, mounting, periphemu, save data, and troubleshooting references.

After cloning the repository, run:

just install

This creates .env from .env.sample when needed and installs the local Git hooks: pre-commit runs just test, and pre-push runs just ci.

just ci is the full local verification entry point. Today it verifies that craftos --version reports v2.8.3 or newer, runs just check for luacheck, runs just test for CraftOS-PC headless tests, and runs the harness timeout regression guard. Use just craftos to launch CraftOS-PC with repo-local save data under .craftos and read-only mounts for /trapos, /apis, /programs, /servers, and /startup. just repl opens the same environment with --cli for human interactive use only; LLM agents must not run it. Use the CraftOS-PC glossary when adjusting --headless, --exec, --script, --rom, or --mount-* usage.

When asking an agent to commit and/or push, rely on these hooks instead of duplicating just test manually before Git operations: pre-commit owns just test, and pre-push owns just ci. Manual just test and just ci remain appropriate when validating changes outside a commit/push workflow.

Tests live under tests/ and run inside CraftOS-PC through just test, which launches /programs/runtest.lua. API-level tests should use require('/apis/libtest')({ ... }), register cases with testlib.test(name, fn), and call testlib.run() at the end. libtest tests remain normal ComputerCraft programs; the runner handles suite discovery, grouped output, and the __TRAPOS_TEST_OK__ shell success contract. Pass --pretty to just test for grouped colored [OK]/[KO] statuses, or --verbose for additional runner/debug detail.

Test timeouts run in two independent layers (see docs/adrs/adr-0009-layered-test-timeouts.md):

  • libtest per-case timeout (primary). Each libtest case is cancelled after 3 seconds by default, failing with a distinct libtest timeout message. Override with --timeout <seconds>, or disable with --no-timeout (both forwarded by runtest to each case). This catches a single hung case quickly without taking down the whole run.
  • Shell watchdog (backstop). The whole CraftOS-PC process is killed if it does not finish within TRAP_CCLIBS_TEST_TIMEOUT_SECONDS (.env.sample ships 7; the recipe falls back to 7). Keep it above the 3s libtest default so libtest fires first; the watchdog only catches what Lua cannot interrupt. Override in .env for slower local probes.

just test-timeout is a self-asserting regression guard for these layers and runs automatically as part of just ci. It chains just test-timeout-lua (proves libtest cancels a slow case at 0.1s, before a 2s shell backstop) and just test-timeout-shell (proves the 1s shell watchdog kills a slow case run with --no-timeout). Both drive the tests/harness/slow-case.lua fixture, which is never picked up by the normal just test suite (runtest skips tests/ subdirectories).