# Mapperly

> Mapperly is an Agent Skill for development published in the recyclarr/recyclarr repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when writing, editing, or reviewing Mapperly (`Riok.Mapperly`) mapper classes; adding or changing a `[Mapper]`-attributed partial class; configuring `RequiredMappingStrategy`, `[MapProperty]`, `[MapperIgnore]`, or other Mapperly attributes; mapping between nullable Refit/OpenAPI DTOs and non-nullable domain records; debugging null-handling in generated mapping code (positional records, `required init`, initializer defaults); investigating Mapperly diagnostics such as RMG001, RMG020, or RMG089; inspecting source-generated output under `obj/Debug/*/generated/Riok.Mapperly/`. Triggers on phrases like "add a Mapperly mapper", "Mapperly null handling", "DTO to domain mapping", "generated mapper", or edits to files ending in `*Mapper.cs` under `ServarrApi/`. Do NOT use for hand-written mapping code or AutoMapper.

- Skill name: `mapperly`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/recyclarr/recyclarr/blob/HEAD/.opencode/skills/mapperly/SKILL.md
- Repository: recyclarr/recyclarr (2,031 GitHub stars when collected)

## SKILL.md

# Mapperly

Conventions and null-handling semantics for Mapperly source-generated mappers.

## Mapper Conventions

- `[Mapper(RequiredMappingStrategy = RequiredMappingStrategy.None)]` on every mapper. Generated DTOs
  have many properties we don't map; this silences unmapped-property warnings.
- One mapper class per service (Sonarr/Radarr). Generated DTO types share names but are distinct
  types from separate packages.
- Namespace aliases disambiguate: `using SonarrApi = Recyclarr.Api.Sonarr`.
- Mappers are `internal static partial class`.

## Null Handling (nullable DTO -> non-nullable domain)

Generated Refit DTOs mark all properties as nullable (`T?`). Domain models use non-nullable types
for fields that should always have a value. Mapperly handles the mismatch differently depending on
the target shape.

### Constructor parameters (positional records)

Mapperly substitutes type-appropriate defaults when the source is null:

- `string?` -> `string`: `""` (empty string)
- `T?` where `T` has a parameterless constructor: `new T()`
- `T?` value type: `default(T)`

### Init properties without initializers

Mapperly generates `throw ArgumentNullException` when the source is null. This is hardcoded for
`required init` properties regardless of mapper settings.

### Init/setter properties with initializers (e.g. `= ""`, `= []`)

Mapperly skips the assignment when the source is null. The initializer value is preserved. This is
the safest pattern for "optional with sensible default" semantics.

### Setter properties without initializers

Mapperly skips the assignment. The property stays at `default(T)`, which for reference types is
`null`. This silently violates the non-nullable contract. Avoid this shape for non-nullable
reference types.

### Nullable target properties

Assigned directly, including null. No special handling.

## RMG089 Diagnostic

"Mapping nullable source property X to target property Y which is not nullable." Default severity:
Info. This diagnostic is informational; the generated code handles the mismatch using the rules
above. No suppression or severity promotion is needed.

## Inspecting Generated Code

To see what Mapperly actually generates, temporarily add to `Directory.Build.props`:

```xml
<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
```

Output appears in `obj/Debug/<tfm>/generated/Riok.Mapperly/Riok.Mapperly.MapperGenerator/`. Remove
the property when done.

---

Source: https://www.openparable.com/skill/development/mapperly (OpenParable). Cite the canonical URL above.
