testsAndMisc/.github/skills/code-quality-rules/SKILL.md

name	description
code-quality-rules	Mandatory code quality, linting, and test coverage rules for ALL languages in this monorepo. Use BEFORE writing or modifying ANY code. Covers Python, C/C++, TypeScript, Dart/Flutter, and shell. Enforces 100% test coverage, zero lint suppressions, and pre-commit compliance.

Code Quality Rules — All Languages

Every agent working in this repository MUST follow these rules. Non-compliance causes pre-commit/pre-push hooks to fail and PRs to be rejected.

Universal Rules (All Languages)

1. 100% test coverage is required for every project in every language — no exceptions. Do not exclude packages, files, or lines from coverage.
2. Zero lint suppressions — never add # noqa, # type: ignore, // ignore:, // ignore_for_file:, // NOLINT, @ts-ignore, eslint-disable, or equivalent without explicit user approval. Fix the underlying issue instead.
3. Pre-commit hooks must pass — run pre-commit run --files <changed-files> after every change. Never use --no-verify on git commit or push.
4. No binary files in the workspace — move to ../testsAndMisc_binaries/. See scripts/check_no_binaries.sh.
5. No secrets in code — patterns in .secret-patterns are scanned on every commit.

Python (python_pkg/)

Linters (ALL enabled, maximum strictness)

Tool	Config	Key Settings
ruff	pyproject.toml [tool.ruff]	select = ["ALL"], Google docstrings, ban-relative-imports = "all"
mypy	pyproject.toml [tool.mypy]	strict = true, all disallow_* and warn_* flags enabled
pylint	pyproject.toml [tool.pylint]	enable = "all", disable = [], fail-under = 8.0
bandit	pyproject.toml [tool.bandit]	Security scanner, high severity, medium confidence
ruff-format	pyproject.toml [tool.ruff.format]	Double quotes, spaces, auto line endings

Ruff Rules

• ALL rule categories enabled — every ruff rule fires unless explicitly ignored in pyproject.toml.
• Only these rules are globally ignored (with justification):
  • D203 (conflicts with D211), D213 (conflicts with D212)
  • COM812, ISC001 (formatter conflicts)
  • S603 (subprocess false positives with validated input)
• Per-file ignores exist ONLY for test files and a handful of files with documented technical justifications (lazy imports, camelCase overrides, thesis scripts). Check [tool.ruff.lint.per-file-ignores] before adding any new ones.
• fixable = ["ALL"] — auto-fix is enabled for all rules.

Mypy Rules

• strict = true mode with additional flags:
  • disallow_untyped_defs, disallow_incomplete_defs, disallow_untyped_decorators
  • disallow_any_unimported, disallow_any_generics, disallow_subclassing_any
  • warn_return_any, warn_redundant_casts, warn_unused_ignores, warn_unreachable
  • strict_equality, extra_checks, no_implicit_optional
• Type hints required on ALL functions.

Pylint Rules

• All checks enabled, nothing disabled (enable = "all", disable = []).
• min-public-methods = 0, max-attributes = 10, max-module-lines = 1000.

Test Coverage

• 100% branch coverage enforced via [tool.coverage.report] fail_under = 100.
• Branch coverage is mandatory (branch = true).
• Run: python -m pytest python_pkg/<subpackage>/tests/ --cov=python_pkg.<subpackage> --cov-branch --cov-fail-under=100
• The pre-push hook (scripts/pytest_changed_packages.py) runs tests only for changed subpackages.

Style Requirements

• from __future__ import annotations in every file.
• Google docstring convention.
• Absolute imports only (ban-relative-imports = "all").
• Double quotes everywhere.
• Private functions prefixed with _.

C / C++ (C/, CPP/)

Linters

Tool	Trigger	Key Settings
clang-format	Pre-commit hook	Formatting enforced on all .c/.cpp files
cppcheck	Pre-commit hook	--enable=warning,portability, --std=c11, --error-exitcode=1
flawfinder	Pre-commit hook	--error-level=5 — security scanner for C/C++
clang-tidy	C/lint_all.sh	Uses compile_commands.json when available

Build Requirements

• Every C/C++ directory MUST have a Makefile and run.sh (enforced by scripts/check_c_cpp_build_files.sh).
• Exceptions: CPP/mini_browser/ (CMake), horatio/.

Test Coverage

• 100% line coverage is required for all C/C++ projects.
• Use gcov + lcov to measure coverage. Compile with -fprofile-arcs -ftest-coverage (--coverage shorthand), run the test binary, then check coverage:

  gcc --coverage -o test_foo test_foo.c foo.c && ./test_foo
  lcov --capture --directory . --output-file coverage.info
  lcov --remove coverage.info '/usr/*' --output-file coverage.info
  genhtml coverage.info --output-directory coverage_html
  

• C projects under C/tests/ and C++ projects under CPP/tests/ — all tests must pass with 100% line coverage.
• When adding new C/C++ source files, add corresponding tests that cover every branch.

TypeScript (TS/)

Linters

Tool	Config	Key Settings
ESLint	eslint.config.mjs	eslint.configs.recommended + tseslint.configs.recommended
Prettier	Pre-commit (push)	Formats YAML, JSON, Markdown

ESLint Rules

• TypeScript-ESLint recommended ruleset applied to all TS/**/*.{ts,tsx}.
• @typescript-eslint/no-unused-vars set to "error" (args/vars prefixed _ are allowed).
• Ignores: node_modules, dist, build, *.d.ts, config files.

Pre-commit Integration

• ESLint runs on every commit for TS/ files: npx eslint --no-warn-ignored.

Test Coverage

• 100% statement and branch coverage is required for all TypeScript projects.
• Use a test runner (Jest, Vitest, or equivalent) with coverage enabled. Example with Vitest:

  npx vitest run --coverage --coverage.thresholds.statements=100 --coverage.thresholds.branches=100
  

• When adding new TS source files, add corresponding test files (*.test.ts / *.spec.ts) that cover every branch.
• Coverage reports must be generated and checked before considering work complete.

Dart / Flutter

Horatio (horatio/)

Tool	Config	Enforcement
dart analyze	horatio/analysis_options.yaml	--fatal-infos — infos are errors
dart format	melos format script	--set-exit-if-changed
flutter test	horatio/run.sh	100% line coverage enforced

Analysis Rules

The analysis_options.yaml enables strict everything:

• strict-casts: true, strict-inference: true, strict-raw-types: true
• missing_return: error, missing_required_param: error
• 100+ individual lint rules explicitly enabled (see file for full list)
• Key rules: always_use_package_imports, avoid_dynamic_calls, type_annotate_public_apis, prefer_single_quotes, require_trailing_commas, avoid_print

Test Coverage

• 100% coverage enforced for both horatio_core and horatio_app.
• Generated files (*.g.dart, tables/) are filtered from coverage.
• Run: cd horatio && bash run.sh test
• Pre-push hook: horatio-tests runs bash run.sh test.

Pomodoro App (pomodoro_app/)

• Must match Horatio's strictness. The analysis_options.yaml should be upgraded to the same level as horatio/analysis_options.yaml:
  • strict-casts: true, strict-inference: true, strict-raw-types: true
  • All 100+ lint rules from Horatio's config should be enabled
  • flutter analyze --fatal-infos — infos are treated as errors
• 100% test coverage enforced, matching Horatio's standard.
• Pre-push hook: flutter analyze && flutter test.
• Current baseline (package:flutter_lints/flutter.yaml) is insufficient — any agent modifying pomodoro_app/ should flag this gap and work toward parity with Horatio.

Shell Scripts

Linters

Tool	Config	Key Settings
ShellCheck	Pre-commit hook	--severity=warning — all warnings and above are errors

• All shell scripts are checked on every commit (except pomodoro_app/).
• Use set -euo pipefail in all bash scripts.

Pre-Commit Hook Summary

On Every Commit (fast, ~10s)

Hook	Scope
trailing-whitespace, end-of-file-fixer	All files
check-yaml, check-json, check-toml, check-xml	Config files
check-merge-conflict, detect-private-key	All files
name-tests-test (--pytest-test-first)	Python tests
no-binaries	All files
no-noqa, no-ruff-noqa	Python — blocks ALL suppression comments
ruff (lint + fix)	Python
ruff-format	Python
clang-format	C/C++
cppcheck	C/C++
flawfinder	C/C++
eslint	TypeScript
shellcheck	Shell scripts
codespell	All text files
check-c-cpp-build-files	C/C++ directories
check-python-location	Python must be under python_pkg/
check-no-secrets	All files

On Push Only (slow)

Hook	Scope
mypy	Python (strict type checking)
pylint	Python (comprehensive linting)
bandit	Python (security scanning)
pytest + 100% coverage	Python (changed subpackages)
prettier	YAML, JSON, Markdown
flutter analyze + test	pomodoro_app/
horatio run.sh test	horatio/ (100% coverage)

Verification Checklist

Before considering any code change complete:

1. pre-commit run --files <changed-files> passes
2. Tests pass with 100% branch coverage for the affected project
3. No new lint suppressions added without user approval
4. No binary files added to the workspace
5. Type hints on all new Python functions
6. Docstrings on all new public Python functions (Google convention)