From 69940bf18b6d63ceafda940972f450a6716c05e5 Mon Sep 17 00:00:00 2001
From: toto <antitbone@jefaismonrhum.sdv.fr>
Date: Tue, 7 Apr 2026 21:42:54 +0200
Subject: [PATCH] docs: update copilot-instructions with integration tests,
 gotchas, comment standard

- Add make test-integration* commands
- Add SKIP_TESTS=true fast build flag
- Add 'Comments standard' section referencing docs/commenting-standard.md
- Add 'Known gotchas' section with 6 non-obvious issues:
  * go.work build context must include both sentinel + correlator
  * YAML does not expand env vars in Go (hardcode DSN)
  * REGEXP_TREE dict requires >=1 rule or inserts fail
  * pcap only captures non-loopback traffic
  * ClickHouse init needs 120s timeout
  * RPM builds must use Rocky Linux (libpcap.so.1 vs .so.0.8)
  * FLAT() layout requires numeric keys (use COMPLEX_KEY_HASHED for strings)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/copilot-instructions.md | 40 +++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 8aa4498..3d3c6cf 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -32,9 +32,17 @@ docker run --rm -v $(pwd):/build -w /build/services/correlator golang:1.24 \
 docker build -f services/dashboard/Dockerfile.tests -t dash-tests .
 docker run --rm dash-tests pytest backend/tests/test_metrics.py -v -k test_health
 
+# Faster correlator build (skip tests):
+docker build --target builder --build-arg SKIP_TESTS=true -f services/correlator/Dockerfile .
+
 # Linting (Go only — no Python linter configured)
 cd services/sentinel && go vet ./... && gofmt -l .
 cd services/correlator && go vet ./... && gofmt -l .
+
+# Full-stack integration tests (Docker Compose, resets DB each run)
+make test-integration          # runs tests/integration/run-tests.sh → down -v + up + traffic + verify
+make test-integration-keep     # same but leaves stack running after
+make test-integration-down     # tear down integration stack
 ```
 
 ## Architecture
@@ -136,3 +144,35 @@ Services communicate via **Unix sockets**, not HTTP:
 
 ### Sentinel requires elevated privileges
 Tests need `--cap-add=NET_RAW --cap-add=NET_ADMIN` for packet capture (pcap).
+
+## Comments standard
+
+All code is commented in **French** (identifiers stay in English). Standard defined in `docs/commenting-standard.md`:
+- **Go**: godoc `// FuncName does X`, package-level `// Package foo fournit...`
+- **Python**: PEP-257 triple-quoted French docstrings on all functions/classes/modules
+- **C**: Doxygen `/** @brief ... @param ... @return ... */` before every function, `/* ====== Section ====== */` banners
+- **Bash**: standardized header block with `Usage:` and `Variables d'environnement:`
+- **SQL**: `-- === filename.sql — description ===` banner + `-- --- Table ---` section headers
+
+## Known gotchas
+
+### go.work and Docker build contexts
+When building either `sentinel` or `correlator` in Docker, the build context must include **both** service directories because `go.work` references them both. The root-level Makefiles always use `.` (repo root) as context — don't change this.
+
+### Correlator YAML does not expand env vars
+Go's YAML parser reads `${VAR:-default}` as a **literal string**. Use hardcoded values or pass values directly in the YAML file. This is why `tests/integration/platform/correlator.yml` has a hardcoded DSN.
+
+### REGEXP_TREE dictionary requires ≥1 rule
+`dict_anubis_ua` uses `LAYOUT(REGEXP_TREE)`. If `anubis_ua_rules` is empty, **every INSERT into `http_logs_raw` fails** because the materialized view `mv_http_logs` calls `dictGet()` on it. The integration test init script seeds a catch-all rule.
+
+### TLS/pcap capture needs non-loopback traffic
+`sentinel` listens on a network interface (e.g., `eth0`), not loopback. Traffic sent to `localhost` or `127.0.0.1` from the same container is invisible to pcap. In integration tests, traffic must come from a separate container crossing the Docker bridge network.
+
+### ClickHouse initialization timing
+ClickHouse takes ~15-20s to initialize all 10 SQL files. Integration health checks use a 120s timeout (not the default 60s).
+
+### RPM builds must use Rocky Linux
+All `Dockerfile.package` files use `rockylinux:9` (or `rockylinux:8`/`almalinux:10`) as the build base — never Debian-based images. Reason: Rocky provides `libpcap.so.1`; Debian provides `libpcap.so.0.8`. Building sentinel on Debian and running on Rocky produces a missing library error at runtime.
+
+### ClickHouse `FLAT()` layout requires numeric keys
+If adding a new dictionary with a `String` primary key, use `COMPLEX_KEY_HASHED()` not `FLAT()`.