# `@as-pect/transform`

AssemblyScript transform for `as-pect` reflection support.

This package implements the Class reflection transform. It injects the generated class reflection shape that the runtime helpers in `@as-pect/assembly` depend on when tests compare class instances or print reflected object values.

## Generated shape

For each class declaration found in source files and namespaces, the transform appends two public instance methods:

- `__aspectStrictEquals(rawRef: Object, stack: usize[], cache: usize[], ignore: StaticArray<i64>): bool`
- `__aspectAddReflectedValueKeyValuePairs(reflectedValue: i32, seen: Map<usize, i32>, ignore: StaticArray<i64>): void`

These method names are compatibility-sensitive. `packages/assembly/assembly/internal/Reflect.ts` calls them directly when it cannot use a built-in comparison or reflected-value path.

## ClassReflectionTransform

`ClassReflectionTransform` is the module that owns the shared Class-member plan for generated class reflection behavior. It inspects each class once and records the instance members that should participate in both strict equality and reflected key/value generation.

The member plan includes, in source order:

- instance fields
- instance getters

The member plan excludes:

- static members
- regular instance methods
- inherited members, which are handled by generated `super` calls

Each planned member carries its name, source range, getter/field kind, and `djb2` name hash. Generated methods pass these hashes through `ignore: StaticArray<i64>` when calling `super` so inherited generated methods do not duplicate members overridden by a child class.

Hash values intentionally remain the compatibility seam with existing generated code. If two inherited member names ever collide under `djb2`, the generated ignore list treats them as the same inherited member and suppresses the parent entry deterministically; the transform does not rename members or attempt a runtime fallback.

## Generation responsibilities

Class reflection generation is split across a few narrow responsibilities:

- `index.ts` walks parsed sources and namespaces, then delegates class and interface declarations to the generation module.
- `appendGeneratedClassReflectionMembers.ts` orchestrates which generated members or interface contracts should be appended, including idempotence checks and user-authored collision errors.
- `ClassReflectionTransform.ts` owns compatibility-sensitive generated member names, generated-member marking, class/interface collision checks, local equality-operator detection, and the Class-member plan.
- `createStrictEqualsMember.ts`, `createAddReflectedValueKeyValuePairsMember.ts`, and `createInterfaceReflectionMembers.ts` build the generated AssemblyScript AST for each runtime method shape.

This keeps traversal, planning, collision policy, and AST construction separate enough that a change to one generated method does not require re-learning every transform rule.

## Runtime relationship

`@as-pect/assembly` uses the generated methods in two places:

1. `Reflect.equals()` calls `__aspectStrictEquals` to compare class instances structurally.
2. `Reflect.toReflectedValue()` calls `__aspectAddReflectedValueKeyValuePairs` to add reflected object keys and values.

The transform and runtime therefore share a seam: the transform owns the generated method shape, and the runtime assumes that shape exists after compilation with `@as-pect/transform`.

## Compatibility expectations

- Keep both generated method names unchanged unless a coordinated runtime migration is planned.
- Keep the `ignore` hash behavior stable so inherited and overridden members are not reported twice.
- Keep generated behavior dependency-free; this package should remain a small local transform.
- Preserve source order when adding reflected/equality-relevant members so reporter output remains stable.
- Keep transform generation idempotent for the same parsed source; repeated passes should not append duplicate generated members.
- Reject user-authored `__aspectStrictEquals` or `__aspectAddReflectedValueKeyValuePairs` members with a clear transform error instead of silently overwriting them.
