myriad-ast-conventions

name	myriad-ast-conventions
description	AST-construction conventions for Myriad's built-in generators (Fantomas.FCS.Syntax vs FSharp.Compiler.Service boundary, GeneratorHelpers idioms, config lookup pattern). Apply automatically when writing or reviewing code in src/Myriad.Plugins or src/Myriad.Core.
user-invocable	false

Background knowledge for working on Myriad's code generators. The failure mode that matters here isn't "code doesn't compile" — it's a generator that produces F# which compiles but is subtly wrong (bad range, wrong case order, silently non-idempotent output). Consistency with existing generators is the main defense against that.

Two AST worlds, don't mix them up

• Reading input: Myriad.Core.Ast (src/Myriad.Core/Ast.fs), built on FSharp.Compiler.Service, parses the user's source file and extracts typed declarations (Ast.extractDU, Ast.extractTypeDefn, Ast.hasAttribute<'A>, Ast.getAttribute<'A>).
• Writing output: Fantomas.FCS.Syntax (SynExpr, SynPat, SynModuleDecl, SynTypeDefn, …) is used to build the generated AST, which Fantomas.Core then pretty-prints back to source text. Don't hand-construct output as raw strings — build it as SynExpr/ SynModuleDecl nodes like the existing generators do, so formatting stays consistent and Fantomas can reformat it safely.

Shared idioms — use GeneratorHelpers, don't re-derive them

src/Myriad.Plugins/GeneratorHelpers.fs exists specifically because three generators used to duplicate the same destructuring and pipeline code (see the commit that extracted getCaseIdent to eliminate a 5-fold SynUnionCase destructure — that's the shape of bug this file prevents). Before writing a new AST helper, check whether one of these already covers it:

• getCaseIdent — extract the Ident from a SynUnionCase.
• resolveCaseIdent — fully-qualify a DU case name when RequireQualifiedAccess applies.
• createTypedNamedParen — build a (name: typ) parenthesised typed pattern.
• parseInputAst — parse the generator's input file.
• filterByAttribute<'A> — keep only namespaced types decorated with a given attribute.
• generateModules<'Attr> — the standard parse → extract → filter → build-per-type pipeline used by DUCasesGenerator and FieldsGenerator.

If a new generator needs a variant of one of these, extend the helper rather than copy-pasting it into the new generator file — that's exactly the duplication this module was created to avoid.

Range handling

Synthetic AST nodes (ones with no real source position, because they're generated) use range0 from Fantomas.FCS.Text.Range. Don't invent positions or reuse the input file's ranges for generated nodes.

Config lookup pattern

Attributes carry a configGroup: string. Generator.getConfigFromAttribute<'a> resolves that string against the configGetter (backed by the relevant myriad.toml section) into a (string * obj) seq. Read individual values with GeneratorConfig.tryGet<'T> or GeneratorConfig.getOrDefault<'T> — don't pattern-match the seq directly, the helpers already handle the missing-key case.

Naming convention

New generator files are <Name>Generator.fs, with an internal module Create<Name>Module for the AST-building logic and a public [<MyriadGenerator("configKey")>] type <Name>Generator() for the registration. See [[new-generator]] for the full scaffold.