Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude/workflows/write-behaviour-tests.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ Repo: the current workspace root (the projectMM checkout you're running in) —
- First line MUST be: \`// @module ${cls}\` (this is what the doc generator + MoonDeck read — the whole point is that this module becomes a documented, tested module). Add \`// @also X, Y\` only if the test genuinely also exercises another module.
- Each TEST_CASE gets a single \`//\` comment line ABOVE it describing the behaviour it pins (the generator turns that into the doc description). Write real, present-tense descriptions.
- Assert REAL BEHAVIOUR, not just "renders non-zero". Examples of the bar:
- SolidEffect → the whole buffer is ONE uniform colour (every light equals the configured colour).
- SolidEffect → the whole buffer is ONE uniform color (every light equals the configured color).
- FixedRectangleEffect → only lights inside the configured rect are lit; outside is black; defaults (0,0,0)+(15,15,15) light the origin corner.
- MirrorModifier → a coord and its mirror map to the same logical position; modifyLogicalSize halves the mirrored axis (study the .h for which axis/percentage).
- TransposeModifier → swaps axes (x↔y etc. per the .h); modifyLogicalSize swaps the corresponding size fields.
Expand Down
77 changes: 77 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
name: CodeQL

# POC (docs/history/plans/Plan-20260727): does CodeQL's stock C/C++ suite find anything
# real in this firmware? The question that motivated it: we parse six network packet
# formats (ArtNet, DDP, E1.31, WLED audio sync, MQTT, WLED) plus HTTP, doing ~22 memcpy
# operations on data arriving from the LAN, on a device with no MMU and no process
# isolation — and we run NO security analysis at all today. Nothing else in our toolchain
# looks for that class of bug: the compiler checks effects, lizard counts branches, our
# Python checks read text.
#
# `build-mode: none` (GA Oct 2025) scans C/C++ WITHOUT building it, inferring compile flags
# per file. That matters here because our real firmware build is an ESP-IDF cross-compile
# for Xtensa/RISC-V that a runner would have to reproduce; build-free skips that entirely.
# The trade is some extraction noise on macro/template-dense headers — acceptable for a POC
# whose question is "is there anything here", not "prove there is nothing".
#
# Free on public repos, so the cost is wall-clock only. Scheduled weekly + on demand rather
# than per-push: this is a sweep, not a gate, until the POC says otherwise.
#
# If this finds nothing actionable after a few runs, that is a RESULT — record it in the
# scorecard and delete this file.

on:
# Push-triggered on the POC branch, deliberately.
#
# `workflow_dispatch` alone would NOT work here: GitHub only offers the "Run workflow"
# button for workflows that exist on the DEFAULT branch, and this one lives on
# next-iteration until the POC is judged. A push trigger is the only way to get a first
# result without merging an unevaluated workflow into main.
#
# This is still not a gate: it does not run on pull_request, so it cannot block a merge.
# It runs, we read the findings, and we decide.
push:
branches:
- next-iteration
paths:
# Only when C/C++ or the workflow itself changes — a docs commit has nothing new to
# analyse and would just burn a runner.
- 'src/**'
- '.github/workflows/codeql.yml'
workflow_dispatch:
schedule:
# Monday 04:00 UTC. Weekly is enough for a codebase this size, and keeps the signal
# from becoming background noise nobody reads.
- cron: '0 4 * * 1'

permissions:
contents: read
# Required to upload results to the Security tab (this is what buys the alert lifecycle:
# open/fixed/dismissed tracked across runs, i.e. baselining we would otherwise build).
security-events: write

jobs:
analyze:
name: Analyze C/C++
runs-on: ubuntu-latest
timeout-minutes: 60

steps:
- uses: actions/checkout@v4
with:
persist-credentials: false

- name: Initialize CodeQL
uses: github/codeql-action/init@v3
with:
languages: c-cpp
build-mode: none
# security-and-quality is the widest stock set: the security queries answer the
# question above, and the quality ones tell us whether CodeQL sees anything our
# existing checks miss. Narrow it later if the noise is not worth it.
queries: security-and-quality

- name: Perform CodeQL analysis
uses: github/codeql-action/analyze@v3
with:
category: "/language:c-cpp"
Loading
Loading