modify-dart-language - SKILL.md Agent Skill

name: modify-dart-language description: Guide for modifying the Dart language — adding features, AST nodes, parser rules, CFE type inference, experimental flags, and diagnostics. Use when implementing or modifying Dart language features.

Modifying the Dart Language

Compiler pipeline

Source → _fe_analyzer_shared (scan+parse) → front_end (type-check) → kernel IR
                                                    ↓
              ┌─────────────────────────────────────┼───────────────────┐
              ↓                                     ↓                   ↓
    pkg/compiler (dart2js)              runtime/vm/compiler      pkg/dart2wasm
    → JavaScript                        → native code            → WebAssembly

All backends share the same front-end. Language changes typically touch:

Parser (pkg/_fe_analyzer_shared/)
CFE type inference (pkg/front_end/)
Analyzer AST (pkg/analyzer/)
Tests (tests/language/)

Key files by subsystem

Subsystem	Key file	Purpose
Experimental flags	`tools/experimental_features.yaml`	Gate new features
Scanner/tokens	`pkg/_fe_analyzer_shared/lib/src/scanner/`	Tokenization
Parser	`pkg/_fe_analyzer_shared/lib/src/parser/parser_impl.dart`	Parsing
Parser listener	`pkg/_fe_analyzer_shared/lib/src/parser/listener.dart`	Parser events
CFE body builder	`pkg/front_end/lib/src/kernel/body_builder.dart`	Type inference + Kernel IR
CFE messages	`pkg/front_end/messages.yaml`	Diagnostic messages
Analyzer AST	`pkg/analyzer/lib/src/dart/ast/ast.dart`	AST node definitions
Analyzer visitors	`pkg/analyzer/lib/dart/ast/visitor.dart`	AST traversal
Language tests	`tests/language/`	Language feature tests

Adding an experimental feature

Add entry to tools/experimental_features.yaml:

my-feature:
  help: "Short description of the feature."

Regenerate flags:

./tools/sdks/dart-sdk/bin/dart pkg/front_end/tool/cfe.dart generate-experimental-flags

Gate parser/CFE code with the experiment flag.

Subsystem reference docs

Analyzer AST patterns: ast-patterns.md — adding AST nodes, visitor methods
CFE patterns: cfe-patterns.md — body builder, diagnostics, Kernel IR
Parser patterns: parser-patterns.md — parser methods, listener events

Code generation steps

After modifying AST nodes or messages, run the appropriate generators:

# After editing messages.yaml
./tools/sdks/dart-sdk/bin/dart pkg/front_end/tool/generate_messages.dart

# After editing experimental_features.yaml
./tools/sdks/dart-sdk/bin/dart pkg/front_end/tool/cfe.dart generate-experimental-flags

# After editing analyzer AST (regenerate visitors etc.)
./tools/sdks/dart-sdk/bin/dart pkg/analyzer/tool/generate_nodes.dart

# After editing parser tests
./tools/sdks/dart-sdk/bin/dart pkg/front_end/tool/update_expectations.dart

Typical feature implementation order

Add experimental flag
Parser changes (scan, parse, listener events)
CFE changes (body builder, type inference, Kernel IR generation)
Analyzer AST changes (nodes, visitors, resolution)
Diagnostic messages
Language tests
Update static error test expectations