E10: Static Analysis and MISRA

[DavidCozens]

Coding standard, static analysis tooling, and MISRA C:2012 conformance
for the SolidSyslog source tree.

This epic owns three intertwined concerns:

1. Naming convention — a per-tier identifier scheme that satisfies
   MISRA C:2012 rules 5.1–5.9 and reads consistently across the codebase
   (see docs/NAMING.md).
2. Static analysis tooling — clang-tidy readability-identifier-naming
   for naming shape, cppcheck-misra for MISRA rules, with a clean split so
   the two tools cannot disagree on the same name.
3. MISRA C:2012 conformance — informed compliance per tier rather than
   blanket conformance; per-tier rule subset with documented deviations.

Scope tiers

Tier	Naming	MISRA	Directories
Strict	Full Tier 1–4	Full chosen subset	Core/Interface/, Core/Source/, Platform/*/Interface/
Pragmatic	Tier 1–4 applied; third-party-API-shaped locals exempt; 5.3 shadowing relaxed around third-party identifiers	Full chosen subset; per-file deviations where third-party APIs force them	Platform/*/Source/
Consistency-only	New code follows conventions; CppUTest macros used as-is; no rename sweep of existing tests	Excluded	Tests/
Out of scope	Not enforced	Not enforced	Bdd/, ci/, docs/, .github/, .devcontainer/

Enforcement gates run per tier — clang-tidy and cppcheck-misra are invoked
with different rule sets for Strict, Pragmatic, and Consistency-only paths.

Approach

Foundations first (commit standards + wire tools in warning mode), then
audit and decision, then cross-cutting sweeps and per-group conformance,
then flip to error-mode enforcement.

Soft freeze on feature work during conformance: new code must comply
with the rules from day 1 (caught by tooling); existing code converges via
controlled refactor PRs in parallel. Feature work continues.

Stories

Foundations — done

• S10.01 — Commit docs/NAMING.md + initial docs/misra-deviations.md (5.1 → 63 chars deviation). Cross-reference from CLAUDE.md / SKILL.md.
• S10.02 — Tier-model .clang-tidy files (Strict / Pragmatic / Consistency-only / Disabled). Warning mode in CI.
• S10.03 — cppcheck-misra addon wired into CI. Warning mode.
• S10.04 — .clang-format review (line length, brace style, MISRA-helpful settings — trailing comma rules, no single-line if, etc.). Format-the-tree commit as part of the same PR.

Audit & decide — done

• S10.05 — Generate naming + MISRA violation reports; commit a categorised backlog under docs/misra-conformance.md.
• S10.06 — Curate the MISRA rule subset (enable now / minor fix / deviate / parked) and finalise docs/misra-deviations.md (D.002–D.010 + suppressions list).

Cross-cutting sweeps — done (each spans Strict + Pragmatic tiers)

• S10.07 — Enum constants and tags renamed to Class_PascalCase. Later reversed by S10.22 — see below.
• S10.08 — Static-function Class_ prefix sweep (~811 statics across Core/Source + Platform/*/Source; rule 5.9 cleared as a structural consequence).
• S10.09 — Data-member lowerCamelCase → PascalCase (Tier 4 sweep, ~186 sites). Surfaced when S10.05 flipped MemberCase to PascalCase; details in docs/misra-conformance.md.
• S10.10 — Mechanical MISRA sweep (~130 fixes across 10 rules: 10.4, 10.1, 15.7, 12.1, 5.6, 10.8, 2.5, 14.4, 7.1, 3.1 + Rule 5.6 _Static_assert polyfill). Two new deviations introduced as byproducts: D.010 (20.10 stringify) and D.011 (2.5 public-API macros).
• S10.11 — this-pointer convention: self for own-type pointers, base for base-class view at vtable boundaries; SelfFromBase / SelfFromStorage static-inline helpers per derived class; NAMING.md Tier 3 amendment + tree-wide sweep.
• S10.21 — Soften NAMING.md abbreviation rule (broaden the Tier 3 domain-term exemption to RFC-spec field names, protocol shorthands, POSIX/Win32 idioms; Tier 4 cross-reference added). Docs-only — replaces the wider abbreviation-purge originally planned as S10.09.
• S10.22 — Enum naming convention restoration: all enum constants reverted to SOLIDSYSLOG_SCREAMING_SNAKE (tagged or anonymous, public or TU-local). Single .clang-tidy EnumConstantCase: UPPER_CASE rule with no IgnoredRegexp escape. Settled after S10.16 review surfaced a third hybrid form that the post-S10.07 two-class system could not mechanically prevent.

Per-group conformance (pilot first, then in size order)

Per-group workflow established by the S10.12 pilot recipe: per-site review of every existing
suppression in scope (not blind extension), and per-site review of every new finding. Extending
already-documented deviations is allowed; new deviations are not introduced inside a per-group
story without explicit discussion.

• S10.12 — Pilot: Buffers (NullBuffer, CircularBuffer, PosixMessageQueueBuffer). Done.
• S10.13 — Security policies + CRC + Sync primitives. Done.
• S10.14 — Configuration types + Platform helpers (Endpoint, Transport, Tunables, StringFunction, Error/ErrorMessages, Clock, Hostname, ProcessId, SysUpTime). Done.
• S10.15 — Structured data (StructuredData, MetaSd, OriginSd, TimeQualitySd). Done.
• S10.16 — Senders (Sender, NullSender, UdpSender, StreamSender, SwitchingSender, UdpPayload, plus the E11 *Private.h / *Static.c split TUs). Done.
• S10.17 — Network primitives: Datagram, Stream, Resolver, Address, Sleep, plus their POSIX / Windows / FreeRTOS / OpenSSL impls. The biggest per-group story by file count. Done.
• S10.18 — Storage stack: Store, BlockStore, RecordStore, BlockSequence, BlockDevice, FileBlockDevice, File, plus POSIX / Windows / FatFs file impls. Done.
• S10.19 — Engine + Formatter: SolidSyslog.c, Config.h, Formatter, Prival, Utf8, plus any residual files not covered by S10.12–S10.18. Done.

Enforcement — close-out

• S10.20 (S10.20: Flip MISRA + naming gates to error mode and close E10 #437) — Flip from warning to error mode and close the epic. Bundle:
  • Widen non-MISRA cppcheck XML pass scope from Core/Source/ to Core/Source/ + Platform/*/Source/ (deferred from S10.03). Build-time cppcheck already gates Platform/ via CMAKE_C_CPPCHECK; this widens the artefact upload to match.
  • Add Platform/MbedTls/Source/ to the cppcheck-misra invocation (currently absent from CI scope; the MbedTLS adapter was developed against the warning-mode check locally so this is a verification step, not a sweep).
  • Flip cppcheck-misra --error-exitcode=0 → 1 on both the Run and Generate-XML steps so MISRA findings fail CI.
  • Flip clang-tidy readability-identifier-naming from warning to error (currently exempted in WarningsAsErrors).
  • Delete docs/misra-conformance.md (frozen since S10.12; live record is docs/misra-deviations.md + misra_suppressions.txt).
  • Widen analyze-format CI scope to include Platform/ (currently only checks Core/Interface Core/Source Tests Bdd/Targets).
  • Mop up the deferred Tests/DatagramFake.h comment nit from PR refactor: S10.22 enum naming convention restoration (SCREAMING_SNAKE) #391 (the misra-conformance.md nit goes away when the file is deleted above).

Deliverables

• docs/NAMING.md — naming convention reference
• docs/misra-deviations.md — documented rule deviations with rationale
• Per-tier .clang-tidy configurations
• misra_suppressions.txt — per-site cppcheck-misra suppressions, deviation-grouped
• Tier-clean source tree under Core/, Platform/*/Interface/, Platform/*/Source/
• CI gates: clang-tidy and cppcheck-misra in error mode over the full Strict + Pragmatic scope

[DavidCozens]

Candidate idea — re-enable magic-numbers clang-tidy rules

.clang-tidy currently disables -readability-magic-numbers and -cppcoreguidelines-avoid-magic-numbers alongside the other rules deemed too noisy. The reviewer-side preference in this project is the opposite — David has consistently asked for named constants in code review (per feedback_misra_style).

This is the same concern as MISRA Directive 4.9 (no function-like macros instead of inline constants) and Rules 5.4 / 8.13, so it is a natural fit for this epic.

Story would cover:

• Re-enable one or both rules in .clang-tidy
• Cleanup sweep across the codebase (extract named constants where the rules fire)
• Decide a project policy for unavoidable cases — e.g. byte sizes inside _STORAGE_SIZE macros, retry-budget literals, RFC-mandated ports

Surfaced during S04.05 (PR #263) when sweeping out clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling and noticing the magic-numbers suppressions in the same negation list.