IntersectMBO / IntersectMBO/evolution-sdk

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

Ouverte
#155 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub
documentation enhancement
Langage dominant
TypeScript
Étoiles
22
Forks
30
Merge moyen
5 h 29 min
PR mergées (30 j)
12

Description

## 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

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Commencez par la référence générée automatiquement sous docs/content/docs/modules/blueprint/ et le point d’entrée generateFromBlueprint(), puis examinez les options de ParsedBlueprint et de CodegenConfig. Construisez le guide autour d’un workflow réel avec plutus.json, en incluant des exemples TypeScript générés et des vérifications twoslash. Le travail est terminé lorsque le guide couvre chaque option listée, les limitations, l’utilisation manuelle de TSchema et un exemple de bout en bout qui compile.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
typescript
Domaine
documentation
Type d'issue
Documentation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.