diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index d970f81..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,331 +0,0 @@ -# GitHub Copilot Guidance for bash-logger - -This document provides guidance for GitHub Copilot when contributing to the bash-logger project. Please follow these instructions when generating, modifying, or reviewing code. - -## Linting and Code Quality - -All code changes **MUST** pass the linting requirements defined in `.pre-commit-config.yaml`: - -### ShellCheck Linting - -* **Tool**: ShellCheck v0.11.0.1 -* **Configuration**: `--severity=warning --external-sources` -* **Scope**: All shell scripts (`.sh` files) -* **Requirements**: - * All shell scripts must pass ShellCheck with no warnings or errors - * External sources should be analyzed properly - * When ShellCheck flags an issue, fix it or add a justified `shellcheck disable` comment with explanation - * Example: `# shellcheck disable=SC2034` with comment explaining why - -### MarkdownLint - -* **Tool**: MarkdownLint v0.47.0 -* **Scope**: All Markdown documentation files -* **Requirements**: - * All Markdown files must follow MarkdownLint rules - * Auto-fix formatting issues when possible - * Maintain consistent formatting across documentation - * **CRITICAL: Use asterisks (*) for all unordered lists, never dashes (-)** - -### Test Suite - -* **Tool**: `tests/run_tests.sh` -* **Requirement**: All changes must not break existing tests -* **Scope**: Any code changes affecting core functionality must have tests added or updated -* **Contributor guide**: [docs/writing-tests.md](../docs/writing-tests.md) — read this before writing tests - -#### Test lifecycle - -Every test follows the same three-step lifecycle: - -```bash -test_feature_name() { - start_test "Human-readable description" # registers test, calls setup_test, re-sources logging.sh - - init_logger --level DEBUG --quiet - local log_file="$TEST_DIR/test.log" - LOG_FILE="$log_file" - - log_info "expected message" - - assert_file_contains "$log_file" "expected message" || return # || return is mandatory - - pass_test # only reached if all assertions passed -} - -test_feature_name # functions must be called explicitly at the bottom of the suite file -``` - -#### The `|| return` requirement - -`|| return` after every assertion is **not optional**. Without it, execution continues past a -failing assertion, later assertions run against an already-failed test, and `pass_test` may be -reached despite failures — masking the real problem. - -```bash -# CORRECT -assert_file_contains "$log_file" "text" || return - -# WRONG — execution continues after failure -assert_file_contains "$log_file" "text" -``` - -#### `$TEST_DIR` — always use it for file paths - -`$TEST_DIR` is a unique per-test subdirectory created by `setup_test`. The runner executes -suites in parallel; using a fixed path like `/tmp/test.log` causes races between parallel jobs. - -```bash -# CORRECT -local log_file="$TEST_DIR/test.log" - -# WRONG — shared path breaks parallel execution -local log_file="/tmp/test.log" -``` - -#### When to use file assertions vs output capture - -**Prefer `assert_file_contains`** for verifying log output. Point `LOG_FILE` at a path under -`$TEST_DIR` and assert against that file. This tests the real output path and leaves the file -available for inspection on failure. - -**Use subshell with stream redirects** only when testing *which stream* a message appears on -(e.g., stderr vs stdout): - -```bash -bash -c " - source '$PROJECT_ROOT/logging.sh' - init_logger - log_error 'message' -" >"$TEST_DIR/stdout" 2>"$TEST_DIR/stderr" - -assert_file_contains "$TEST_DIR/stderr" "message" || return -assert_file_not_contains "$TEST_DIR/stdout" "message" || return -``` - -#### Isolation: why `logging.sh` is re-sourced on every test - -`start_test` calls `setup_test`, which re-sources `logging.sh`. This resets all global logger -state (`LOG_FILE`, `LOG_LEVEL`, `QUIET_MODE`, etc.) before each test. Do not source -`logging.sh` at the top of a suite file — that runs before `$TEST_DIR` exists and before -per-test isolation is established. - -## Commit Message Standards - -All commit messages **MUST** comply with **Semantic Versioning (Semantic Release)** formatting to enable automated version management and release notes generation. - -### Commit Message Format - -``` -(): - - - -