Add declarative syntax

[Schamper]

This adds an optional declarative syntax for structure definitions, for when you want to write structures in a more Pythonic syntax.

>>> from dissect.cstruct.declarative import Struct, uint8, uint32, uint64
>>>
>>> class Header(Struct):
...     magic: uint8[4]
...     version: uint32
>>> class File(Struct):
...     header: Header  # structs can reference each other
...     size: uint64

Or to bring-your-own-cstruct:

>>> from dissect.cstruct import cstruct
>>> from dissect.cstruct.declarative import Struct
>>>
>>> cs = cstruct(endian=">")
>>>
>>> class Header(Struct, cs=cs):
...     magic: uint8[4]
...     version: uint32

The resulting classes are proper subclasses of Structure and have all the same behavior as regular cstruct structures.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 227 lines in your changes missing coverage. Please review.
✅ Project coverage is 0.00%. Comparing base (8fd1506) to head (d126209).

Files with missing lines	Patch %	Lines
dissect/cstruct/declarative.py	0.00%	220 Missing ⚠️
dissect/cstruct/types/base.py	0.00%	6 Missing ⚠️
dissect/cstruct/__init__.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff           @@
##            main    #161    +/-   ##
======================================
  Coverage   0.00%   0.00%            
======================================
  Files         22      23     +1     
  Lines       2773    2999   +226     
======================================
- Misses      2773    2999   +226     

Flag	Coverage Δ
unittests	0.00% <0.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codspeed-hq]

Merging this PR will improve performance by 12.19%

⚡ 1 improved benchmark
✅ 13 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_benchmark_getattr_types	12.1 µs	10.8 µs	+12.19%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing declarative (d126209) with main (8fd1506)}

[codspeed-hq]

Merging this PR will not alter performance

✅ 14 untouched benchmarks

---

_{Comparing declarative (a47fcc4) with main (7678a8f)}

[Copilot]

Pull request overview

Adds an optional “declarative” API for defining cstruct Structure/Union types using Python class syntax + type annotations, while keeping parity with existing cstruct behavior and allowing either auto-created or user-supplied cstruct instances.

Changes:

• Introduces dissect.cstruct.declarative with Struct / Union bases, unbound type references (e.g. uint32, uint8[4]), pointer/array helpers, and field(...) specs (including typing.Annotated support).
• Extends array subscripting (Type[...]) to accept string expressions (converted to Expression) for declarative string parsing.
• Adds comprehensive tests for the declarative feature and updates Ruff per-file ignores for the new test module.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
dissect/cstruct/declarative.py	New declarative structure/union definition layer built on annotations + metaclasses.
dissect/cstruct/types/base.py	Allows __getitem__ array sizes to be provided as str expressions (parsed as Expression).
dissect/cstruct/__init__.py	Exposes declarative Struct and field in the public package API.
tests/test_declarative.py	Adds test coverage for declarative structs/unions, forward refs, pointers, arrays, Annotated, alignment, etc.
pyproject.toml	Adds Ruff per-file ignores needed for declarative syntax test coverage.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Miauwkeru]

Some remarks when trying out to use this declarative version.
Currently the Struct instance will fail when you try to use dumps, print or initializing the structure.

Using the Header struct from the example, using it like this. it complains about the endianess of the attached cstruct instance, which doesn't exist.

E.g:

• Header().dumps()
• Header(b"heey0102")

Adding a cstruct instance in the class definition class Header(..., cs=cs): ... it cannot find the __fields__ attribute of the Struct.

---

Another thing I noticed is with an empty Struct instance, (e.g. Header()) where it creates an attribute error with the magic and version attributes.

Trying to print this Header instance will result into another error where it cannot find the fields attribute.

[Miauwkeru]

shouldn't there also be a note like in https://github.com/fox-it/flow.record/blob/d50435feffc7e13eb3a636e995a27e3e3418eeda/flow/record/declarative.py#L43 for ruff not put the Annotation and field things underneath TYPE_CHECKING?