Extract stack allocator from easy_memory into standalone easy_stack library with test matrix and fuzzers

Author: gooderfreed

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug Report
+about: Report a crash, memory leak, or undefined behavior.
+title: '[BUG] '
+labels: 'bug'
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Environment:**
+ - OS:[e.g. Ubuntu 22.04, Windows 11, Bare-Metal ESP32]
+ - Compiler:[e.g. GCC 11, Clang 14, MSVC]
+ - Architecture:[e.g. x86_64, aarch64, s390x, 32-bit/64-bit]
+ - C Standard:[e.g. C99, C11, C17, GNU11]
+ - Optimization Flags:[e.g. -O0, -O2, -O3, -Os, -Oz]
+ - Safety Policy:[ESTACK_POLICY_DEFENSIVE or ESTACK_POLICY_CONTRACT]
+
+**To Reproduce**
+Please provide a minimal C snippet that reproduces the crash, OR paste the `libFuzzer` crash dump below:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+### Description
+<!-- Please briefly describe what this PR adds or fixes. -->
+
+### Contribution Checklist
+- [ ] I have read the `CONTRIBUTING.md` file.
+- [ ] I added a new test in the `tests/` directory (if applicable).
+- [ ] I ran `make tests` and everything passes locally.
+- [ ] I ran the fuzzers (`make fuzz_core` or custom) locally for at least 5 minutes to ensure no regressions.
+- [ ] The code complies with C99/C11 standards and `ESTACK_NO_MALLOC` constraints.

.github/codecov.yml

@@ -0,0 +1,20 @@
+# Codecov configuration
+
+coverage:
+  ignore:
+    - "tests/*"  # Ignore all files within the tests/ directory
+    - "fuzzers/*" # Ignore all files within the fuzzers/ directory
+
+  # Coverage status settings
+  status:
+    project:
+      default:
+        # Target coverage for the whole project
+        target: 80%
+        threshold: 0%
+    patch:
+      default:
+        # Target coverage for the changes in a PR
+        target: 80%
+        # Do not allow coverage to decrease in PRs
+        threshold: 0% 

.github/docker/Dockerfile.test-env

@@ -0,0 +1,17 @@
+ARG BASE_IMAGE=ubuntu:latest
+FROM ${BASE_IMAGE}
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    build-essential \
+    gcc \
+    make \
+    valgrind \
+    lcov \
+    git \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /workspace

.github/workflows/docker-build.yml

@@ -0,0 +1,54 @@
+name: build-docker-images
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - '.github/docker/**'
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      matrix:
+        include:
+          - arch: s390x
+            platform: linux/s390x
+            base_img: s390x/ubuntu:latest
+            tag_suffix: s390x
+          - arch: arm32
+            platform: linux/arm/v7
+            base_img: arm32v7/ubuntu:latest
+            tag_suffix: arm32
+
+    steps:
+      - name: checkout
+        uses: actions/checkout@v6
+
+      - name: setup-qemu
+        uses: docker/setup-qemu-action@v4
+
+      - name: setup-docker-buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: login-to-ghcr
+        if: github.repository == 'EasyMem/easy_stack'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: build-and-push-${{ matrix.arch }}
+        uses: docker/build-push-action@v6
+        with:
+          context: .github/docker
+          file: .github/docker/Dockerfile.test-env
+          platforms: ${{ matrix.platform }}
+          push: ${{ github.repository == 'EasyMem/easy_stack' }}
+          build-args: BASE_IMAGE=${{ matrix.base_img }}
+          tags: ghcr.io/easymem/easy_stack:${{ matrix.tag_suffix }}

.gitignore

@@ -0,0 +1,65 @@
+# Prerequisites
+*.d
+
+# Object files
+*.o
+*.ko
+*.obj
+*.elf
+
+# Linker output
+*.ilk
+*.map
+*.exp
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+
+# Debug files
+*.dSYM/
+*.su
+*.idb
+*.pdb
+
+# Kernel Module Compile Results
+*.mod*
+*.cmd
+.tmp_versions/
+modules.order
+Module.symvers
+Mkfile.old
+dkms.conf
+
+# Tests
+tests/stack_alloc_test_*
+
+build_matrix
+
+# Fuzzers
+fuzzers/*_fuzzer
+
+# Coverage files
+*.gcno
+*.gcda
+*.info

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+gooderfreed@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing to EasyMem
+
+First of all, thank you for being here! 
+
+I've been on the other side: you spend your weekend optimizing someone else's messy codebase, making it 10x faster, only to be hit with a 10-page contribution guide full of bureaucratic rules, strict commit formats, and formatting nitpicks. You close the tab and walk away. 
+
+**I don't do that here.** 
+
+At EasyMem, code quality and performance speak louder than bureaucracy. If you have an idea, a bug fix, or a massive optimization, I want to see your code. We can figure out the formatting details later.
+
+## The Golden Rules
+
+To keep EasyMem true to its philosophy, there are only a few architectural rules I strictly follow:
+
+1. **Header-Only (STB-style):** The core libraries must remain single-file headers. No `.c` files, no complex build systems required for the end-user.
+2. **Zero-Overhead Philosophy:** Performance is critical. Avoid adding internal locks, mutexes, or hidden allocations. 
+3. **Bare-Metal Friendly:** I do not assume the existence of a `libc` heap unless explicitly allowed. The code must perfectly respect the `ESTACK_NO_MALLOC` macro.
+4. **16-bit, 32-bit, and 64-bit Support:** The code must compile and run correctly across all pointer sizes. Be careful with bitwise operations, shifts, and alignment mathematics. The CI will test this, but keep it in mind.
+
+## The Workflow
+
+If you want to add a feature or fix a bug, here is the ideal pipeline:
+
+1. **Write the code.**
+2. **Add a test:** If you introduced a new feature or fixed an edge case, create a new test file in the `tests/` directory (name it `yourfeature_test.c`). The `Makefile` will automatically pick it up and generate the build targets for it—no need to edit the build scripts.
+3. **Run tests locally:** 
+   * Run `make tests`. 
+   * *(Note: `make tests_full` runs the exact same test suite, it just enables verbose debug output in the console. You can run `make` or `make list` to see all dynamically generated targets).*
+4. **Push to your fork and check CI:** The GitHub Actions workflow **must be green**. It automatically runs an aggressive matrix (Sanitizers, strict ARM alignment, Big Endian s390x, and 16-bit fallbacks). Let the robots do the heavy lifting.
+5. **Feed it to the Fuzzer:** Run the fuzzers locally for the standard 5 minutes each. 
+   * Just like tests, if you add a new `.c` file to the `fuzzers/` directory (name it `yourfeature_fuzzer.c`), the `Makefile` will automatically detect it. Check `make list` for your new `make fuzz_yourfeature` target. 
+   * *Tip: If you implemented new features or structural mechanics, please create a dedicated standalone fuzzer for it to test its specific boundary scenarios!*
+6. **Open the PR.** 
+
+*Don't worry about strict commit message formats (like `feat(core): ...`). Just write what you did in plain English.*
+
+## Code Style
+*   Try to match the surrounding code style.
+*   If you add a new API function, please add a small comment explaining *what* it does and *why*.
+*   If you implement a complex bit-manipulation hack, write a "WHY DOING THIS?" comment. I love reading about the physics of the code!
+
+## Let's make C memory management *easy*.
+If you're unsure about an architectural decision, just open a Draft PR or an Issue, and we'll discuss it. I'm always open to new ideas.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EasyMem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.