[Minor Feature] Extend fuzz coverage to remaining public API surface #312

New issue

Open

opened 2026-04-17 03:25:19 +00:00 by john · 0 comments

john commented

2026-04-17 03:25:19 +00:00

Owner

Context

The libFuzzer+ASan harness shipped in #283 covers the core mcrfpy surface: Grid, Entity, EntityCollection, Frame, Caption, Sprite, TileLayer, ColorLayer, Color, Vector, Scene, Timer, animations, HeightMap, DiscreteMap, NoiseSource, BSP, compute_fov/is_in_fov, DijkstraMap, grid.step, entity behavior.

Several high-value areas are still uncovered. Based on a comparison to docs/api-audit-2026-04.md (93 public API items), the following gaps are in priority order of likely fault density:

Gaps to cover

Tier A (highest expected yield)

Tiled / LDtk import parsers — TileSetFile, TileMapFile, WangSet, LdtkProject, AutoRuleSet. External file parsers are historically the highest-yield fuzz target. Corpus: the existing fixture .tmx / .ldtk files plus random mutations.
Shader / PropertyBinding / CallableBinding / UniformCollection — lifetime-coupled to Drawables. Exactly the pattern that produced #270 / #271 / #277. Fuzz creation/destruction sequences with active uniform bindings that target Drawables which get destroyed mid-render.

Tier B

Audio DSP chain — SoundBuffer.pitch_shift, echo, reverb, distortion, bit_crush, concat, mix, slice, low_pass, high_pass, gain, normalize, reverse, sfxr_mutate. 14 methods of signal-processing math, none exercised. Likely UB in edge cases (empty buffers, extreme parameters, sample-rate mismatches).
Texture factory — Texture.from_bytes, composite, hsl_shift. Raw byte ingestion and pixel transforms.

Tier C (completeness)

Primitive shapes — Line, Circle, Arc have property setters the property-type fuzzer never touches.
Grid ops beyond FOV/pathfinding — at, entities_in_radius, center_camera, hovered_cell, apply_threshold, apply_ranges, apply_gradient (also on ColorLayer/TileLayer).
Perspective system — ColorLayer.apply_perspective / update_perspective / clear_perspective / draw_fov.
Collections at Scene.children level — insert/pop/index/count/find not exercised outside the grid_entity scope.
AStarPath iteration — walk, peek, len, iteration.
GridPoint dynamic attributes — the __getattr__ / __setattr__ for named-layer access.
Module functions — find, findAll, bresenham, lock, benchmark triplet.

Suggested implementation

Add one new fuzz target per Tier A / B area (so 4-5 new targets). Each follows the existing tests/fuzz/fuzz_<name>.py pattern with a matching entry in FUZZ_TARGETS in the Makefile. Tier C gaps can be folded into existing targets (e.g., extend fuzz_property_types to include Line / Circle / Arc).

Not in scope

3D / Experimental types (Viewport3D, Entity3D, VoxelGrid, etc.) — explicitly exempt from the 1.0 freeze per ROADMAP.md. Fuzz when/if they mature.

#283 (closed): the original harness
tests/fuzz/README.md: how to add a target
docs/api-audit-2026-04.md: authoritative API surface catalog

## Context The libFuzzer+ASan harness shipped in #283 covers the core mcrfpy surface: Grid, Entity, EntityCollection, Frame, Caption, Sprite, TileLayer, ColorLayer, Color, Vector, Scene, Timer, animations, HeightMap, DiscreteMap, NoiseSource, BSP, compute_fov/is_in_fov, DijkstraMap, grid.step, entity behavior. Several high-value areas are still uncovered. Based on a comparison to `docs/api-audit-2026-04.md` (93 public API items), the following gaps are in priority order of likely fault density: ## Gaps to cover ### Tier A (highest expected yield) 1. **Tiled / LDtk import parsers** — `TileSetFile`, `TileMapFile`, `WangSet`, `LdtkProject`, `AutoRuleSet`. External file parsers are historically the highest-yield fuzz target. Corpus: the existing fixture .tmx / .ldtk files plus random mutations. 2. **Shader / PropertyBinding / CallableBinding / UniformCollection** — lifetime-coupled to Drawables. Exactly the pattern that produced #270 / #271 / #277. Fuzz creation/destruction sequences with active uniform bindings that target Drawables which get destroyed mid-render. ### Tier B 3. **Audio DSP chain** — `SoundBuffer.pitch_shift`, `echo`, `reverb`, `distortion`, `bit_crush`, `concat`, `mix`, `slice`, `low_pass`, `high_pass`, `gain`, `normalize`, `reverse`, `sfxr_mutate`. 14 methods of signal-processing math, none exercised. Likely UB in edge cases (empty buffers, extreme parameters, sample-rate mismatches). 4. **Texture factory** — `Texture.from_bytes`, `composite`, `hsl_shift`. Raw byte ingestion and pixel transforms. ### Tier C (completeness) 5. **Primitive shapes** — Line, Circle, Arc have property setters the property-type fuzzer never touches. 6. **Grid ops beyond FOV/pathfinding** — `at`, `entities_in_radius`, `center_camera`, `hovered_cell`, `apply_threshold`, `apply_ranges`, `apply_gradient` (also on ColorLayer/TileLayer). 7. **Perspective system** — `ColorLayer.apply_perspective` / `update_perspective` / `clear_perspective` / `draw_fov`. 8. **Collections at `Scene.children` level** — insert/pop/index/count/find not exercised outside the grid_entity scope. 9. **AStarPath iteration** — `walk`, `peek`, `len`, iteration. 10. **GridPoint dynamic attributes** — the `__getattr__` / `__setattr__` for named-layer access. 11. **Module functions** — `find`, `findAll`, `bresenham`, `lock`, benchmark triplet. ## Suggested implementation Add one new fuzz target per Tier A / B area (so 4-5 new targets). Each follows the existing `tests/fuzz/fuzz_<name>.py` pattern with a matching entry in `FUZZ_TARGETS` in the Makefile. Tier C gaps can be folded into existing targets (e.g., extend `fuzz_property_types` to include Line / Circle / Arc). ## Not in scope 3D / Experimental types (Viewport3D, Entity3D, VoxelGrid, etc.) — explicitly exempt from the 1.0 freeze per `ROADMAP.md`. Fuzz when/if they mature. ## Related - #283 (closed): the original harness - `tests/fuzz/README.md`: how to add a target - `docs/api-audit-2026-04.md`: authoritative API surface catalog

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

john/McRogueFace#312

No description provided.

Rows
Columns