# Coding Standards

This page defines the coding standards used for KiCad MCP Pro contributions.

## General rules

- Keep public tool behavior deterministic, documented, and test-covered.
- Prefer small, typed functions with explicit error handling.
- Keep KiCad-driving behavior behind adapter seams so pure logic remains testable.
- Do not log credentials, private board data, customer-specific paths, or generated manufacturing files.
- Document heuristic or partial behavior honestly in code, docs, and tool verdicts.

## Python

- Use Python 3.13-compatible syntax.
- Format and lint with Ruff.
- Maintain type coverage with mypy-compatible annotations for public interfaces and non-trivial internal APIs.
- Keep filesystem, subprocess, and network behavior behind narrow utility functions or adapters.
- Add unit tests for pure logic and fixture-based tests for KiCad artifact parsing.

## TypeScript and JavaScript

- Use TypeScript for integration code where possible.
- Run formatter, linter, typecheck, and unit tests before opening a PR.
- Validate user-controlled paths with canonicalization and allowed-root checks.
- Avoid direct shell interpolation of untrusted values.

## Shell and workflow code

- Use `set -euo pipefail` in non-trivial shell scripts.
- Quote variables.
- Pass GitHub expressions through `env:` before shell use.
- Pin third-party GitHub Actions to full commit SHAs.
- Keep default workflow permissions to `contents: read` unless a job needs more.

## Documentation

- Update generated tool docs and metadata when public tool contracts change.
- Keep examples free of secrets and private board data.
- Link policy pages from the docs navigation when they are used as release or OpenSSF evidence.

## Enforcement

Coding standards are enforced through PR review, the pull request template, Ruff, mypy, TypeScript checks, CodeQL, Gitleaks, dependency audit, workflow-security checks, generated-doc checks, and CI.
