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 (0edfc10) to head (3e989d6).

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       2700    2926   +226     
======================================
- Misses      2700    2926   +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 not alter performance

✅ 14 untouched benchmarks

---

_{Comparing declarative (3e989d6) with main (0edfc10)}

[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.