IntersectMBO / IntersectMBO/evolution-sdk

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

オープン
#155 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る
documentation enhancement
主要言語
TypeScript
スター
22
フォーク
30
平均マージ
5時間 29分
マージ済み PR(30日)
12

説明

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

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

評価

技術スタック
typescript
領域
documentation
issue の種類
ドキュメント
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。