actions/.serena/memories/code_style_conventions.md

Code Style and Conventions

Critical Prevention Guidelines

1. ALWAYS add id: when step outputs will be referenced

   • Missing IDs cause steps.*.outputs.* to be undefined at runtime
   • Example: id: detect-version required before steps.detect-version.outputs.version

2. ALWAYS check tool availability before use

   • Not all tools (jq, bc, terraform) are available on all runner types
   • Pattern: if command -v jq >/dev/null 2>&1; then ... else fallback; fi

3. ALWAYS sanitize user input before writing to $GITHUB_OUTPUT

   • Malicious inputs with newlines can inject additional outputs
   • Use printf '%s\n' "$value" or heredoc instead of echo "$value"

4. ALWAYS pin external actions to commit SHAs, not branches

   • @main or @v1 tags can change, breaking reproducibility
   • Use full SHA: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

5. ALWAYS quote shell variables to handle spaces

   • Unquoted variables cause word splitting and globbing
   • Example: "$variable" not $variable, basename -- "$path" not basename $path

6. ALWAYS use SHA-pinned references for internal actions in action.yml

   • Security: immutable, auditable, portable when used externally
   • Pattern: uses: ivuorinen/actions/common-cache@7061aafd35a2f21b57653e34f2b634b2a19334a9
   • Test workflows use local: uses: ./common-cache (within repo only)

7. ALWAYS test regex patterns against edge cases

   • Include prerelease tags (1.0.0-rc.1), build metadata (1.0.0+build.123)
   • Version validation should support full semver/calver formats

8. ALWAYS use POSIX shell (set -eu) for all scripts

   • Maximum portability: works on Alpine, busybox, all shells
   • Use #!/bin/sh not #!/usr/bin/env bash
   • Use set -eu not set -euo pipefail (pipefail not POSIX)

9. Avoid nesting ${{ }} expressions inside quoted strings in specific contexts

   • In hashFiles(): "${{ inputs.value }}" breaks cache key generation - use unquoted or extract to variable
   • In most other contexts, quoting is required for safety (e.g., shell commands with spaces)
   • General rule: Quote for shell safety, unquote for YAML expressions in functions like hashFiles

10. NEVER assume tools are available across all runner types

    • macOS/Windows runners may lack Linux tools (jq, bc, specific GNU utils)
    • Always provide fallbacks or explicit installation steps

EditorConfig Rules (.editorconfig)

CRITICAL: EditorConfig violations are blocking errors and must be fixed always.

• Charset: UTF-8
• Line Endings: LF (Unix style)
• Indentation: 2 spaces globally
  • Python override: 4 spaces (indent_size=4 for *.py)
  • Makefile override: Tabs (indent_style=tab for Makefile)
• Final Newline: Required
• Max Line Length: 200 characters (120 for Markdown)
• Trailing Whitespace: Trimmed
• Tab Width: 2 spaces

Python Style (Ruff Configuration)

• Target Version: Python 3.8+
• Line Length: 100 characters
• Indent Width: 4 spaces
• Quote Style: Double quotes
• Import Style: isort with forced sorting within sections
• Docstring Convention: Google style

Enabled Rule Sets

Comprehensive linting with 30+ rule categories including:

• pycodestyle, Pyflakes, isort, pep8-naming
• Security (bandit), bugbear, comprehensions
• Performance optimizations, refactoring suggestions
• Type checking, logging best practices

Relaxed Rules for GitHub Actions Scripts

Scope: These relaxed rules apply ONLY to Python scripts running as GitHub Actions steps (composite action scripts). They override specific zero-tolerance rules for those files.

Precedence: For GitHub Actions scripts, allowed ignores take precedence over repository zero-tolerance rules; all other rules remain enforced.

Allowed Ignore Codes:

• T201 - Allow print statements (GitHub Actions logging)
• S603, S607 - Allow subprocess calls (required for shell integration)
• S101 - Allow assert statements (validation assertions)
• BLE001 - Allow broad exception catches (workflow error handling)
• D103, D100 - Relaxed docstring requirements for simple scripts
• PLR0913 - Allow many function arguments (GitHub Actions input patterns)

Example: # ruff: noqa: T201, S603 for action step scripts only

Shell Script Standards (POSIX)

ALL scripts use POSIX shell (#!/bin/sh) for maximum portability.

Required POSIX Compliance Checklist

• ✅ Shebang: #!/bin/sh (POSIX-compliant, not bash)
• ✅ Error Handling: set -eu at script start (no pipefail - not POSIX)
• ✅ Defensive Expansion: Use ${var:-default} or ${var:?message} patterns
• ✅ Quote Everything: Always quote expansions: "$var", basename -- "$path"
• ✅ Tool Availability: command -v tool >/dev/null 2>&1 || { echo "Missing tool"; exit 1; }
• ✅ Portable Output: Use printf instead of echo -e
• ✅ Portable Sourcing: Use . file instead of source file
• ✅ POSIX Tests: Use [ ] instead of [[ ]]
• ✅ Parsing: Use cut, grep, pipes instead of here-strings <<<
• ✅ No Associative Arrays: Use temp files or line-based processing

Key POSIX Differences from Bash

Bash Feature	POSIX Replacement
#!/usr/bin/env bash	#!/bin/sh
set -euo pipefail	set -eu
[[ condition ]]	[ condition ]
[[ $var =~ regex ]]	echo "$var" | grep -qE 'regex'
<<< here-strings	echo | cut or pipes
source file	. file
$BASH_SOURCE	$0
((var++))	var=$((var + 1))
((var < 10))	[ "$var" -lt 10 ]
echo -e	printf '%b'
declare -A map	temp files + sort/uniq
Process substitution	pipes or temp files

Examples

#!/bin/sh
set -eu

# Defensive parameter expansion
config_file="${CONFIG_FILE:-config.yml}"           # Use default if unset
required_param="${REQUIRED_PARAM:?Missing value}" # Error if unset

# Always quote expansions
printf 'Processing: %s\n' "$config_file"
result=$(basename -- "$file_path")

# POSIX test conditions
if [ -f "$config_file" ]; then
  printf 'Found config\n'
fi

# Portable output
printf '%b' "Color: ${GREEN}text${NC}\n"

Why POSIX Shell

• Portability: Works on Alpine Linux, busybox, minimal containers, all POSIX shells
• Performance: POSIX shells are lighter and faster than bash
• CI-Friendly: Minimal dependencies, works everywhere
• Standards: Follows POSIX best practices
• Compatibility: Works with sh, dash, ash, bash, zsh

Additional Requirements

• Security: All external actions SHA-pinned
• Token Authentication: ${{ github.token }} fallback pattern
• Validation: shellcheck compliance required

YAML/GitHub Actions Style

• Indentation: 2 spaces consistent with EditorConfig
• Token Security: Proper GitHub expression syntax (unquoted when needed)
• Validation: actionlint and yaml-lint compliance
• Documentation: Auto-generated README.md via action-docs
• Expression Safety: Never nest ${{ }} inside quoted strings

Least-Privilege Permissions

Always scope permissions to minimum required. Set at workflow, workflow_call, or job level:

permissions:
  contents: read # Default for most workflows
  packages: write # Only if publishing packages
  pull-requests: write # Only if commenting on PRs
  # Omit unused permissions

Use GitHub-provided token: ${{ github.token }} over PATs when possible

Scoped secrets: ${{ secrets.MY_SECRET }} never hardcoded

Expression Context Examples

# Secrets context (always quote in run steps)
run: echo "${{ secrets.MY_SECRET }}" | tool

# Matrix context (quote when used as value)
run: echo "Testing ${{ matrix.version }}"

# Needs context (access outputs from dependent jobs)
run: echo "${{ needs.build.outputs.artifact-id }}"

# Steps context (access outputs from previous steps)
uses: action@v1
with:
  value: ${{ steps.build.outputs.version }}  # No quotes in 'with'

# Conditional expressions (no quotes)
if: github.event_name == 'push'

# NEVER interpolate untrusted input into expressions
# ❌ WRONG: run: echo "${{ github.event.issue.title }}"  # Injection risk
# ✅ RIGHT: Use env var: env: TITLE: ${{ github.event.issue.title }}

Quoting Rules:

• Quote in run: steps when embedding in shell strings
• Don't quote in with:, env:, if: - GitHub evaluates these
• Never nest expressions: "${{ inputs.value }}" inside hashFiles breaks caching

Internal Action References (SHA-Pinned)

CRITICAL: Action files (*/action.yml) use SHA-pinned references for security:

• ✅ CORRECT: uses: ivuorinen/actions/action-name@7061aafd35a2f21b57653e34f2b634b2a19334a9
• ❌ INCORRECT: uses: ./action-name (security risk, not portable when used externally)
• ❌ INCORRECT: uses: ivuorinen/actions/action-name@main (floating reference)

Rationale:

• Security: Immutable, auditable references
• Reproducibility: Exact version control
• Portability: Works when actions used externally (e.g., ivuorinen/f2b using ivuorinen/actions/pr-lint)
• Prevention: No accidental version drift

Test Workflows Exception:

Test workflows in _tests/ use local references since they run within the repo:

# ✅ Test workflows only
uses: ./validate-inputs

External Action References (SHA-Pinned)

# ✅ Correct - SHA-pinned
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683

# ❌ Incorrect - floating reference
uses: actions/checkout@main
uses: actions/checkout@v4

Step Output References

CRITICAL: Steps must have id: to reference their outputs:

# ❌ INCORRECT - missing id
- name: Detect Version
  uses: ivuorinen/actions/version-detect@<SHA>

- name: Setup
  with:
    version: ${{ steps.detect-version.outputs.version }} # UNDEFINED!

# ✅ CORRECT - id present
- name: Detect Version
  id: detect-version # Required for output reference
  uses: ivuorinen/actions/version-detect@<SHA>

- name: Setup
  with:
    version: ${{ steps.detect-version.outputs.version }} # Works

Security Standards

• No Secrets: Never commit secrets or keys to repository
• No Logging: Never expose or log secrets/keys in code
• SHA Pinning: All action references (internal + external) use SHA commits, not tags
• Input Validation: All actions import from shared validation library (validate-inputs/) - stateless validation functions, no inter-action dependencies
• Output Sanitization: Use printf or heredoc for $GITHUB_OUTPUT writes
• Injection Prevention: Validate inputs for command injection patterns (;, &&, |, backticks)

Naming Conventions

• Actions: kebab-case directory names (e.g., node-setup, docker-build)
• Files: kebab-case for action files, snake_case for Python modules
• Variables: snake_case in Python, kebab-case in YAML
• Functions: snake_case in Python, descriptive names in shell

Quality Gates

• Linting: Zero tolerance - all linting errors are blocking
• Testing: Comprehensive test coverage required
• Documentation: Auto-generated and maintained
• Validation: All inputs validated via shared utility library imports (actions remain self-contained)

Development Patterns

• Self-Contained Actions: No cross-dependencies between actions
• Modular Composition: Actions achieve functionality through composition
• Convention-Based: Automatic rule generation based on input naming patterns
• Error Handling: Comprehensive error messages and proper exit codes
• Defensive Programming: Check tool availability, validate inputs, handle edge cases
• POSIX Compliance: All scripts portable across POSIX shells

Pre-commit and Security Configuration

Pre-commit Hooks (.pre-commit-config.yaml)

Comprehensive tooling with 11 different integrations:

Local Integration:

• generate-docs-format-lint: Runs make all for comprehensive project maintenance

Core Quality Checks (pre-commit-hooks v6.0.0):

• File integrity: trailing whitespace, end-of-file-fixer, mixed line endings
• Syntax validation: check-ast, check-yaml (multiple documents), check-toml, check-xml
• Security: detect-private-key, executable shebangs
• JSON formatting: pretty-format-json with autofix

Language-Specific Linting:

• Markdown: markdownlint v0.45.0 with auto-fix
• YAML: yamllint v1.37.1 for validation
• Python: ruff v0.13.0 for linting (with fix) and formatting
• Shell: shfmt v3.12.0-2 and shellcheck v0.11.0 (exclude _tests/)

Infrastructure Tools:

• GitHub Actions: actionlint v1.7.7 for workflow validation
• Renovate: renovate-config-validator v41.113.3
• Security: checkov v3.2.471 (quiet mode), gitleaks v8.28.0

Gitleaks Configuration (.gitleaks.toml)

Secret Detection:

• Uses default gitleaks rules with smart exclusions
• Allowlisted paths: node_modules, .git, dist, lock files, _tests
• Dual-layer security with both pre-commit-hooks and gitleaks
• Test exclusion prevents false positives from test fixtures

Test Compatibility

ShellSpec Integration:

• Shell linting tools (shfmt, shellcheck) exclude _tests/ directory
• Prevents conflicts with ShellSpec test framework syntax
• Maintains code quality while preserving test functionality