@h2loop/safe-c-coding-plugin 0.1.0

package/.hydron-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "engines": {
+    "hydron": "^1.0.0"
+  }
+}

package/README.md

@@ -0,0 +1,44 @@
+# safe-c-coding-plugin
+
+A [Hydron](https://hydron.h2loop.ai) plugin that ships defensive C/C++ coding discipline —
+**MISRA C:2012-aligned** guidelines for writing reliable, deterministic, undefined-behaviour-free
+C for embedded, automotive, medical, aerospace, and other safety-critical or resource-constrained
+targets.
+
+It bundles two surfaces:
+
+- **`safe-c-coding` skill** — an always-on domain layer. Its description auto-triggers whenever
+  you write, generate, modify, or review C/C++ (`.c`, `.h`, `.cpp`, `.hpp`), so Hydron produces
+  compliant code the first time instead of relying on a later review pass. The full guideline
+  catalogue lives in [`skills/safe-c-coding/guidelines.md`](skills/safe-c-coding/guidelines.md).
+- **`safe-c-reviewer` subagent** — an on-demand reviewer that audits a file, diff, or range
+  against the guidelines and reports findings as `severity — file:line — what's wrong -> safe fix`,
+  Critical (must fix) separated from Standard (fix or justify).
+
+## Layout
+
+```
+.hydron-plugin/plugin.json   # engines manifest (hydron ^1.0.0)
+skills/safe-c-coding/
+  SKILL.md                   # skill entry — severity model, preferred patterns, review format
+  guidelines.md              # full MISRA C:2012-aligned guideline catalogue
+agents/safe-c-reviewer.md    # subagent that reviews C/C++ against the guidelines
+```
+
+## Install
+
+```
+# From the marketplace once published, or directly from this checkout:
+hydron plugin validate .
+hydron plugin add .
+```
+
+Once added, the skill loads automatically on C/C++ work. To run a review explicitly, ask Hydron
+to review a file with the safe-c-reviewer (e.g. "review `foo.c` with the safe-c reviewer").
+
+## Scope note
+
+These guidelines paraphrase well-established critical-systems C practice (aligned with the intent
+of MISRA C:2012) in original wording. They are an engineering aid, **not** a formal compliance
+certification and not affiliated with or endorsed by MISRA. For formal compliance and authoritative
+guidance, consult the official MISRA C:2012 publication.

package/agents/safe-c-reviewer.md

@@ -0,0 +1,58 @@
+---
+mode: subagent
+displayName: Safe-C Reviewer
+description: >-
+  Reviews C / C++ (.c, .h, .cpp, .hpp) against the safe-c-coding (MISRA C:2012-aligned)
+  guidelines and reports findings by severity. Given a file, diff, or code range, it scans
+  for undefined behaviour, dynamic allocation, unchecked returns, implicit conversions,
+  missing switch defaults, recursion, and other hazardous constructs, and reports each as
+  "severity — file:line — what's wrong -> safe fix". Use it to audit hand-written or
+  generated C/C++ before it lands, especially for embedded / safety-critical targets.
+permission:
+  # deny-all FIRST, then allow specifics: PermissionNext resolves with findLast
+  # (last matching rule wins), so "*": deny MUST precede the allows or it overrides them.
+  "*": deny
+  read: allow
+  grep: allow
+  glob: allow
+  list: allow
+  bash: allow
+  skill: { "*": deny, "safe-c-coding": allow }
+---
+You are a safe-C code reviewer. Your only job is to audit C / C++ against the
+`safe-c-coding` guidelines and report findings — you do not modify code, and you do not
+review anything outside these safety guidelines (style, architecture, and performance are
+out of scope unless they cause undefined behaviour or non-determinism).
+
+Procedure:
+
+1. **Load the rules first.** Invoke the `safe-c-coding` skill and read its `guidelines.md`
+   catalogue before you look at any code. Review against the catalogue, not from memory.
+2. **Get the code.** You are given a file, a diff, or a line range. Read exactly that scope
+   with `read`/`grep`; do not wander into unrelated files. If the scope is a diff, judge the
+   changed lines and the code they directly touch.
+3. **Scan section by section** against the guidelines: undefined behaviour, dynamic memory
+   (`malloc`/`free`/VLAs), unchecked return values, implicit / narrowing conversions,
+   signed-unsigned mixing, uninitialised reads, missing `default` in `switch`, recursion,
+   unbraced bodies, `goto`/`longjmp`/`exit`/`abort`, multiple points of exit, etc.
+4. **Every finding gets a safe fix.** A finding without the corrective idiom is incomplete —
+   name the safe replacement (static buffer / fixed-size pool, checked status return, explicit
+   cast, added `default`, single point of exit) and, where useful, the substitute pattern from
+   the skill.
+
+Report exactly in this format, Critical (must fix) separated from Standard (fix or justify):
+
+```
+Safe-C findings
+  Critical:
+    foo.c:42   `x` read before assignment -> initialise at declaration
+    foo.c:27   double free of `buf` -> free once, then set to NULL
+  Standard:
+    foo.c:12   malloc used -> use a static buffer or fixed-size pool
+    foo.c:30   switch has no default -> add a default clause
+  Advisory:
+    foo.c:8    magic number 4096 -> name it with a #define / const
+```
+
+If a scanned scope is clean, say so explicitly rather than inventing findings. Bias toward
+citing the exact rule and the concrete fix over vague warnings.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@h2loop/safe-c-coding-plugin",
+  "version": "0.1.0",
+  "description": "Safe-C coding plugin for Hydron — MISRA C:2012-aligned defensive C/C++ guidelines as an always-on skill plus a safe-c-reviewer subagent",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "keywords": [
+    "hydron",
+    "hydron-plugin",
+    "misra",
+    "misra-c-2012",
+    "embedded",
+    "safety-critical",
+    "c",
+    "cpp"
+  ],
+  "files": [
+    ".hydron-plugin",
+    "skills",
+    "agents",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/h2loop/safe-c-misra-skill-plugin.git"
+  },
+  "homepage": "https://github.com/h2loop/safe-c-misra-skill-plugin#readme"
+}

package/skills/safe-c-coding/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: safe-c-coding
+description: Use when writing, generating, modifying, or reviewing C or C++ code (.c, .h, .cpp, .hpp), especially for embedded, automotive, medical, aerospace, or other safety-critical or resource-constrained targets where reliability, determinism, and freedom from undefined behaviour matter.
+---
+
+# Safe C Coding
+
+## Overview
+
+A set of defensive coding guidelines for writing C (and C-style C++) that is reliable, deterministic, and free of undefined behaviour — the qualities required in safety-critical and embedded systems. These guidelines are aligned with the intent of the MISRA C:2012 guidelines for critical-systems C, expressed here as plain engineering practice.
+
+**Core principle:** write the safe form by default. Avoid the language's hazardous corners (dynamic memory, undefined behaviour, implicit conversions, unbounded operations) instead of relying on review to catch them later.
+
+> **Apply this as you write.** Whenever you write, generate, or modify C or C++ — even a one-line snippet or a quick example — follow these MISRA C:2012-aligned guidelines proactively, without waiting to be asked to review. Produce compliant code the first time; do not emit a hazardous construct now and plan to fix it later. If a guideline genuinely cannot be met, flag it and justify the deviation rather than silently violating it.
+
+The full guideline catalogue is in **[guidelines.md](guidelines.md)**. Consult it rather than working from memory.
+
+## Severity
+
+- **Critical** — never violate. These guard against undefined behaviour and memory corruption.
+- **Standard** — follow as the default; deviate only deliberately, with a documented reason, scope, and risk note.
+- **Advisory** — recommended for clarity, maintainability, and portability; apply with engineering judgement. Listed at the end of guidelines.md.
+
+## When writing or modifying C/C++
+
+1. Choose the safe pattern from the start: static allocation over `malloc`, braced bodies, explicit types, checked return values, a `default` in every `switch`, no recursion.
+2. After producing code, scan it against guidelines.md and fix anything before presenting it.
+3. If a hazardous construct is genuinely unavoidable, don't hide it — call it out and explain why, with a documented justification.
+
+## Preferred patterns
+
+When the task tempts a banned construct, reach for these idioms instead of improvising. Copy and adapt them. Each uses a **single point of exit** (one `return` at the end, via a status variable and structured nesting) per Rule 15.5 — prefer this over early-return guard clauses.
+
+**Caller-provided output buffer** — never return allocated memory; the caller owns storage, the function returns a status.
+
+```c
+typedef enum { OK = 0, ERR_ARG = 1, ERR_RANGE = 2 } status_t;
+
+/* Bounded copy into a caller-owned buffer. Never allocates, never overflows.
+ * Single point of exit. */
+status_t copy_label(char *out, size_t out_size, const char *src)
+{
+    status_t st = ERR_ARG;
+    if ((out != NULL) && (src != NULL) && (out_size != 0U)) {
+        size_t len = strnlen(src, out_size);   /* bounded scan */
+        if (len < out_size) {                   /* room for NUL */
+            (void)memcpy(out, src, len);
+            out[len] = '\0';
+            st = OK;
+        } else {
+            st = ERR_RANGE;
+        }
+    }
+    return st;
+}
+```
+
+**Fixed-size pool** — deterministic object reuse instead of `malloc`/`free`.
+
+```c
+#define POOL_SIZE 8U
+
+typedef struct {
+    uint8_t  used[POOL_SIZE];
+    widget_t slot[POOL_SIZE];
+} pool_t;
+
+static pool_t pool;   /* static storage, internal linkage — no heap */
+
+widget_t *widget_acquire(void)
+{
+    widget_t *found = NULL;
+    for (size_t i = 0U; (i < POOL_SIZE) && (found == NULL); ++i) {
+        if (pool.used[i] == 0U) {
+            pool.used[i] = 1U;
+            found = &pool.slot[i];   /* loop condition stops the scan */
+        }
+    }
+    return found;      /* single exit; NULL if pool exhausted */
+}
+
+void widget_release(widget_t *w)
+{
+    for (size_t i = 0U; i < POOL_SIZE; ++i) {
+        if (&pool.slot[i] == w) {
+            pool.used[i] = 0U;
+            break;
+        }
+    }
+}
+```
+
+**Error propagation, not `exit`/`abort`/`longjmp`** — return status codes up the call chain to a defined fault handler.
+
+```c
+status_t process(const config_t *cfg)
+{
+    status_t st = ERR_ARG;
+    if (cfg != NULL) {
+        st = validate(cfg);
+        if (st == OK) {
+            st = run(cfg);   /* only run once validation passed */
+        }
+    }
+    return st;               /* single exit; propagate status, no abort()/longjmp() */
+}
+```
+
+See guidelines.md for the full substitute list (banned facility → safe replacement).
+
+## When reviewing C/C++
+
+1. Read guidelines.md, then scan the code section by section.
+2. Report each finding as: **severity — file:line — what's wrong → safe fix**.
+3. Separate Critical findings (must fix) from Standard findings (fix or justify).
+
+## Reporting format
+
+```
+Safe-C findings
+  Critical:
+    foo.c:42   `x` read before assignment → initialise at declaration
+    foo.c:27   double free of `buf` → free once, then set to NULL
+  Standard:
+    foo.c:12   malloc used → use a static buffer or fixed-size pool
+    foo.c:30   switch has no default → add a default clause
+```
+
+## Common mistakes
+
+- Flagging a problem without giving the safe fix.
+- Allowing dynamic allocation, recursion, or VLAs "just this once" without a documented justification.
+- Letting implicit narrowing or signed/unsigned mixing slip through.
+
+## Scope note
+
+These guidelines paraphrase well-established critical-systems C practice (aligned with the intent of MISRA C:2012) in original wording. They are an engineering aid, not a formal compliance certification and not affiliated with or endorsed by MISRA. For formal compliance and authoritative guidance, consult the official MISRA C:2012 publication.

package/skills/safe-c-coding/guidelines.md

@@ -0,0 +1,212 @@
+# Safe C Coding Guidelines
+
+Defensive C guidelines for safety-critical and embedded code, aligned with the intent of MISRA C:2012, in original wording. **Critical** = never violate (guards against undefined behaviour / memory corruption). **Standard** = default practice; deviate only with a documented justification. **Advisory** = recommended for clarity, maintainability, and portability; apply with engineering judgement (see the Advisory section at the end).
+
+---
+
+## Memory and resources
+
+- **(Critical)** Never read a local variable before it has been assigned a value. Initialise at declaration.
+- **(Critical)** Only free memory that was obtained from a standard allocator, and free it exactly once. After freeing, set the pointer to `NULL`. No double-free, no freeing stack or static pointers.
+- **(Critical)** Never copy or assign between objects whose storage overlaps (e.g. overlapping source/destination in a copy).
+- Do not use dynamic memory allocation (`malloc`, `calloc`, `realloc`, `free`). Prefer static allocation, fixed-size pools, or bounded stack objects.
+- Always explicitly release any resource (memory, file, handle) obtained at run time.
+- Validate arguments (range, sign, non-null, buffer size) before passing them to any library function.
+
+## Files and streams
+
+- **(Critical)** Never dereference a `FILE` pointer directly.
+- **(Critical)** Never use a `FILE` pointer after its stream has been closed.
+- **(Critical)** Never write to a stream that was opened read-only.
+- Do not open the same file for read and write at the same time on different streams.
+
+## Pointers and arrays
+
+- Keep pointer arithmetic within the bounds of a single array; a computed pointer must address an element of that array (or one past its end).
+- Subtract pointers only when both address elements of the same array.
+- Apply relational comparisons (`<`, `>`, `<=`, `>=`) to pointers only when they point into the same object.
+- Never let the address of a local (automatic) object outlive that object — don't return `&local` or store it somewhere persistent.
+- Do not declare flexible array members.
+- Do not use variable-length arrays.
+
+## Types and conversions
+
+- Always specify types explicitly; never rely on implicit `int`.
+- Do not assign a value to an object of narrower type or a different type category — no implicit narrowing.
+- Both operands of an arithmetic operator should share the same type category; don't mix signed/unsigned/float/character categories.
+- Don't assign or cast a composite (sub-)expression into a wider or different-category type, which hides where truncation or overflow occurs.
+- Use operators only on appropriate operand types — no bitwise operators on signed or Boolean values; no arithmetic on Boolean or enum values.
+- Use character-typed expressions in `+`/`-` only as `char ± integer` or `char - char`.
+- Keep a shift count within `0 .. width-1` of the promoted left operand.
+
+## Pointer conversions
+
+- Do not convert between a function pointer and any other type.
+- Do not convert between a pointer to an incomplete type and any other type.
+- Do not cast between pointers to different object types.
+- Do not cast between `void *` and an arithmetic type, or between an object pointer and a non-integer arithmetic type.
+- A cast must never strip `const` or `volatile` from the pointed-to type.
+- Use `NULL` as the only null-pointer constant.
+
+## Initialization and declarations
+
+- Enclose aggregate and union initialisers in braces.
+- Initialise arrays fully; do not leave them partially initialised, and do not initialise any element more than once.
+- When using designated initialisers for an array, state the array size explicitly.
+- Declare functions in prototype form with named parameters — no empty `()` or K&R style.
+- Use identical names and qualifiers across all declarations of the same object or function.
+- Declare each external object or function once, in a single header, with exactly one definition; ensure a compatible declaration is visible at the definition.
+- Mark internal-linkage objects and functions `static`; declare `inline` functions `static`.
+- Specify the size of an externally-linked array explicitly.
+- Ensure implicitly-valued enum constants don't collide with other values in the list.
+- Do not use the `restrict` qualifier.
+- Declare bit-fields only with an explicitly signed/unsigned integer type or `_Bool`; a single-bit named bit-field must not be signed.
+
+## Control flow
+
+- Always use braces for the body of an `if`, `else`, loop, or other selection/iteration statement — even a single statement.
+- Terminate every multi-branch `if … else if` chain with a final `else`. This applies only when at least one `else if` is present; a standalone `if` with no `else if` does not require an `else`.
+- A controlling expression of an `if` or loop should be genuinely Boolean — not a bare integer or pointer.
+- Avoid controlling expressions that are always true or always false.
+- A loop counter must not be a floating-point value.
+- Keep `for` loops well-formed: one clear loop counter, with predictable init/test/update, not altered unexpectedly in the body.
+- Use `goto` sparingly; if used, jump only forward to a label later in the same function and within an enclosing block.
+- Do not write recursive functions (direct or indirect).
+
+## Switch statements
+
+- Give every `switch` a `default` label, placed first or last.
+- Terminate every switch-clause with an unconditional `break`; no unintended fall-through.
+- A `switch` should have at least two clauses, and its labels must sit directly in the switch body.
+- Don't switch on an essentially Boolean expression — use `if`/`else`.
+
+## Functions
+
+- **(Critical)** Never call a function without a visible declaration.
+- **(Critical)** Every exit path of a non-void function must return a value explicitly.
+- **(Critical)** Do not place `static` between the `[ ]` of an array parameter.
+- Test the return/status value of any function that reports errors; use (or explicitly `(void)`-cast) the return value of a non-void function.
+- Do not use the variadic facilities of `<stdarg.h>`.
+
+## Expressions and side effects
+
+- **(Critical)** The operand of `sizeof` must not contain an expression with side effects (it is not evaluated).
+- An expression's value and side effects must be the same under any permitted evaluation order — avoid order-of-evaluation dependence.
+- The right operand of `&&` or `||` must not have persistent side effects (it may be skipped by short-circuiting).
+- Initialiser lists must not contain persistent side effects.
+
+## Preprocessor
+
+- Protect every header against multiple inclusion (include guard or `#pragma once`).
+- Wrap each macro-parameter use in parentheses, e.g. `#define SQ(x) ((x) * (x))`.
+- Do not define a macro with the same name as a keyword, or on/as a reserved identifier or reserved macro name.
+- Follow `#include` with `<filename>` or `"filename"` only; don't put `'`, `"`, `\`, `/*`, or `//` in a header name.
+- Keep `#else`, `#elif`, `#endif` in the same file as their opening `#if`/`#ifdef`/`#ifndef`.
+- A `#if`/`#elif` controlling expression must evaluate to 0 or 1, and every identifier in it must be `#define`d first.
+- A line beginning with `#` must be a valid preprocessing directive.
+- Observe the restrictions on `#`/`##` operators: don't follow a `#`-prefixed parameter immediately with `##`, and use a `#`/`##` operand subject to further expansion only as an operand of those operators.
+- Don't let tokens that look like preprocessing directives appear inside a macro argument.
+
+## Comments, literals, identifiers
+
+- Don't place `/*` or `//` inside a comment, and don't use line-continuation inside a `//` comment.
+- Avoid octal constants (leading-zero literals like `010`); terminate octal/hex escape sequences unambiguously.
+- Suffix unsigned integer constants with `u`/`U`; use uppercase `L` (never lowercase `l`) for long suffixes.
+- Assign a string literal only to a pointer-to-`const char`.
+- Keep identifiers distinct: external names, same-scope names, macro names, typedef names, and tag names must each be unique, and inner-scope names must not shadow outer-scope ones.
+
+## Banned standard-library facilities — and what to use instead
+
+A prohibition alone tends to get violated when the functionality is genuinely needed. Each banned facility below has a safe substitute — use it.
+
+| Don't use | Use instead |
+| --- | --- |
+| `malloc`, `calloc`, `realloc`, `free` | Static objects, a fixed-size pool, or a caller-provided buffer (see SKILL.md Preferred patterns). |
+| `sprintf`, `strcpy`, `strcat`, `gets` (unbounded) | A bounded copy: `memcpy`/`memmove` with a checked length, or a length-limited copy that always NUL-terminates. |
+| `<stdio.h>` I/O (`printf`, `scanf`, `fopen`, …) | A driver/BSP abstraction layer; move data via caller buffers and status codes. If formatted output is genuinely required, use a **bounded** `snprintf` with an explicit size — and treat it as a documented deviation, since `<stdio.h>` is itself restricted. Never `sprintf`. |
+| `atof`, `atoi`, `atol`, `atoll` | `strtol`, `strtoul`, `strtod` with explicit error and range checking (these are not on the banned list). |
+| `getenv`, `system` | Compile-time configuration, or configuration passed in by the caller. No environment or process access. |
+| `abort`, `exit` | Propagate a status code up the call chain to a defined fault handler (see SKILL.md Preferred patterns). |
+| `<setjmp.h>` (`setjmp`/`longjmp`) | Structured control flow with status-return error handling. |
+| `<signal.h>` | A platform/RTOS event or interrupt-handling mechanism provided by the BSP. |
+| `bsearch`, `qsort` | A bounded, type-specific search/sort over a known element count. |
+| `<time.h>` date/time routines | A platform timer/RTC abstraction provided by the BSP. |
+| `<tgmath.h>` | The explicitly-typed `<math.h>` functions (e.g. `sqrtf` for `float`, `sqrt` for `double`). |
+
+## General
+
+- All code should trace to a documented requirement; don't add unrequested functionality.
+- Every source file must compile cleanly with no errors and no reliance on undefined or critical unspecified behaviour.
+- Don't depend on implementation-defined behaviour unless it is identified and documented.
+- Remove unreachable and dead code.
+- Encapsulate and isolate any assembly language (in a dedicated function/macro/intrinsic), rather than scattering it inline.
+
+---
+
+# Advisory guidelines (recommended)
+
+Lower-priority recommendations that improve clarity, maintainability, and portability. Apply them by default, but they may be set aside with engineering judgement when a Critical or Standard guideline, or readability, is better served.
+
+## Types and naming
+
+- Use size- and signedness-indicating types (e.g. `uint32_t`, `int16_t`) in place of the plain numeric types (`int`, `long`, …).
+- Make a pointer point to a `const`-qualified type whenever the pointee is not modified through it.
+- Keep identifiers typographically unambiguous within a namespace — avoid names that differ only by case, or by easily-confused glyphs (`l`/`1`, `O`/`0`).
+- Keep internal-linkage identifiers unique across the project.
+- Don't cast a value to an inappropriate essential type (e.g. casting that misrepresents signedness or category).
+
+## Linkage and scope
+
+- Give a function or object internal linkage (`static`) if it is referenced in only one translation unit.
+- Define an object at block scope if its identifier is used within only a single function.
+- If a pointer to a struct/union is never dereferenced within a translation unit, hide the type's implementation (use an opaque/incomplete type in the header).
+
+## Unused declarations
+
+- Remove unused type, tag, and macro declarations.
+- Remove unused labels and unused function parameters.
+
+## Expressions and operators
+
+- Make operator precedence explicit with parentheses rather than relying on the reader to recall it.
+- Do not use the comma operator.
+- Do not rely on the result (value) of an assignment, e.g. avoid `x = (y = z);` or `if ((p = next()) != NULL)`.
+- A full expression containing `++` or `--` should have no other side effects.
+- Constant-expression evaluation should not cause unsigned integer wrap-around.
+
+## Pointers
+
+- Prefer array indexing over pointer arithmetic; avoid `+`, `-`, `+=`, `-=` applied directly to pointer-typed expressions.
+- Keep pointer nesting to at most two levels (e.g. avoid `int ***`).
+- Avoid converting between an object pointer and an integer type, and from `void *` into a pointer to object.
+
+## Control flow
+
+- Give each function a single point of exit at the end: one `return` statement, reached by structuring the body with a status variable and nested conditions rather than early returns. Prefer this over early-return guard clauses — see SKILL.md Preferred patterns for the idiom.
+- Avoid the `goto` statement.
+- Use at most one `break` or `goto` to terminate a given loop.
+
+## Functions
+
+- Do not modify a function parameter; copy it to a local first if a mutable working value is needed.
+- When a parameter is declared with an array type, ensure the supplied argument actually has enough elements.
+- Call functions that operate on a resource in the correct sequence (e.g. initialise before use, acquire before release).
+- Prefer a real function over a function-like macro where the two are interchangeable (functions give type checking and easier debugging).
+
+## Preprocessor
+
+- Precede `#include` directives only with other preprocessor directives or comments.
+- Avoid `#undef`.
+- Avoid the `#` (stringize) and `##` (token-paste) operators.
+
+## Language features and portability
+
+- Do not use non-standard language extensions; keep to standard C.
+- Do not use trigraphs.
+- Avoid the `union` keyword (overlapping members defeat type safety).
+- Do not use the floating-point exception features of `<fenv.h>`.
+
+## Style and process
+
+- Document every use of assembly language.
+- Don't leave blocks of code "commented out" — delete them and rely on version control, or use conditional compilation deliberately.