IntersectMBO / IntersectMBO/evolution-sdk

docs: Blueprint codegen has no guide page — workflow, CodegenConfig options, and generated output are undocumented

Abierto
#155 1 comentario 0 reacciones 0 asignados Ver en GitHub
documentation enhancement
Lenguaje dominante
TypeScript
Estrellas
22
Forks
30
Merge medio
5 h 29 min
PR fusionados (30 d)
12

Descripción

## Problem

There is no guide page for the Blueprint module. The only existing documentation is the auto-generated module reference under \`docs/content/docs/modules/blueprint/\`, which lists types and signatures but provides no explanation of the workflow, the codegen pipeline, or config options.

Blueprint codegen is one of the primary entry points for new users: they run Aiken, get a \`plutus.json\`, and need to generate TSchema definitions from it. There is no page explaining how to do this.

### What Needs to Be Written

**What a blueprint is** — The \`plutus.json\` file produced by Aiken. Its structure (preamble, validators, definitions). Why it is the source of truth for on-chain types.

**Parsing a blueprint** — How to load and parse \`plutus.json\` into a \`ParsedBlueprint\` using the SDK. Error cases when the blueprint is malformed.

**Running codegen** — The \`generateFromBlueprint()\` function: inputs, outputs, and where the generated code goes. End-to-end example from \`plutus.json\` to a usable \`TypeScript\` file.

**CodegenConfig in depth** — Each config option explained with before/after generated output:
- \`optionStyle\` — NullOr / UndefinedOr / Union
- \`unionStyle\` — Variant / TaggedStruct
- \`emptyConstructorStyle\` — Literal / Struct
- \`moduleStrategy\` — flat / namespaced with examples of both
- \`forceVariant\` and \`variantFieldNames\` — for overriding unnamed Aiken fields
- \`fieldNaming\` — \`singleFieldName\` and \`multiFieldPattern\`
- \`useSuspend\` — when and why to disable
- \`includeIndex\` — for constructors with non-zero-based indices

**Using generated code** — How to import and use the generated schemas and types in a transaction-building workflow.

**Known limitations and workarounds** — What the codegen cannot automatically infer (see companion issue about Credential/union translation), and how to configure around it today.

### Acceptance Criteria

- [ ] A new guide page (or section) is created — not in \`modules/\`
- [ ] An end-to-end example runs from a real \`plutus.json\` to a usable generated file
- [ ] Every \`CodegenConfig\` option is documented with a before/after code example showing effect on generated output
- [ ] The page explains when codegen is appropriate vs writing TSchema by hand
- [ ] All code examples use \`twoslash\` and compile

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Start with the auto-generated reference under docs/content/docs/modules/blueprint/ and the generateFromBlueprint() entry point, then inspect ParsedBlueprint and CodegenConfig options. Build the guide around a real plutus.json workflow, including generated TypeScript examples and twoslash checks. Done means the guide covers every listed option, limitations, manual TSchema use, and a compiling end-to-end example.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
typescript
Área
documentation
Tipo de issue
Documentación
Dificultad
5/5
Tiempo estimado
Más de una semana
Estado de actividad
Estancado
Claridad
Bastante claro
Aptitud para principiantes
35/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.