Skip to content

conventions.md

Latest commit

 

History

History
91 lines (67 loc) · 2.89 KB

conventions.md

File metadata and controls

91 lines (67 loc) · 2.89 KB
Raw

Crucible — Coding Conventions

This document defines the coding standards for all Crucible source files. All contributors and AI-assisted sessions must follow these conventions.

4.1 — Shell Style

  • Shebang: #!/usr/bin/env bash
  • Set options: set -euo pipefail at the top of every file
  • Indentation: 4 spaces (per .editorconfig)
  • Line length: 100 characters soft limit, 120 hard limit
  • Quoting: Always double-quote variables unless word splitting is intentional

4.2 — Naming Conventions

  • Functions: snake_case — prefixed by module name (e.g., tui_menu(), detect_distro(), state_save())
  • Local variables: snake_case, declared with local
  • Global/exported variables: UPPER_SNAKE_CASE, prefixed with CRUCIBLE_ (e.g., CRUCIBLE_DIR, CRUCIBLE_VERSION)
  • Constants: readonly UPPER_SNAKE_CASE
  • File names: kebab-case.sh for lib files, test_<module>.bats for tests (e.g., test_detect.bats)

4.3 — Function Documentation

Every public function gets a comment block:

# Brief description of what the function does.
#
# Arguments:
#   $1 — description (type)
#   $2 — description (type)
#
# Returns:
#   0 on success, 1 on failure
#   Outputs: description of stdout output (if any)
#
# @since 0.1.0
function_name() {

4.4 — Error Handling

  • Functions return 0 for success, non-zero for failure
  • Error messages go to stderr: echo "Error: message" >&2
  • Fatal errors use a common die() function (defined in the entrypoint or a common lib)
  • Never silently swallow errors — no empty catch blocks, no || true without a comment explaining why

4.5 — File Headers

Every .sh file starts with:

#!/usr/bin/env bash
# Crucible — [component description]
# Copyright (c) 2025 Marc Mironescu <marcm@fluxgear.io>
# SPDX-License-Identifier: MIT
# https://github.com/fluxgear/crucible

4.6 — Sourcing / Dependencies

  • Source paths relative to CRUCIBLE_DIR (resolved by the entrypoint)
  • Source guard pattern to prevent double-sourcing:
[[ -n "${_CRUCIBLE_TUI_LOADED:-}" ]] && return 0
readonly _CRUCIBLE_TUI_LOADED=1

4.7 — Security Conventions

  • # SECURITY: comment prefix on security-critical code
  • All user input validated before use
  • No eval, no unquoted command substitution with user data
  • Temp files created with mktemp in controlled directories

4.8 — Testing Conventions

  • BATS test files in tests/
  • Test file naming: test_<module>.bats (e.g., test_detect.bats)
  • Shared setup in tests/test_helper.bash
  • Each test function prefixed with @test
  • Tests must be self-contained — no dependency on system state

4.9 — Commit Format

<type>(<scope>): <short summary> with detailed body.

Types: feat, fix, docs, refactor, style, test, chore, security

Scopes: foundation, tui, detect, state, install, provision, webapp, harden, docker, test, system