A CLAUDE.md is just a markdown file at the root of your repo. Copy the content below into your own project's CLAUDE.md to give your agent the same context.
npx versuz@latest install microsoft-power-fx --kind=claude-mdcurl -o CLAUDE.md https://raw.githubusercontent.com/microsoft/Power-Fx/HEAD/CLAUDE.md# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Overview
Power Fx is a low-code general-purpose programming language based on spreadsheet-like formulas. This is the open-source implementation of the language used across Microsoft Power Platform. The codebase contains a complete compiler and interpreter infrastructure written in C#.
## Build Commands
### Building the Solution
```bash
# From src/ directory
dotnet build Microsoft.PowerFx.sln
# Or using MSBuild directly
msbuild Microsoft.PowerFx.sln -p:Configuration=Debug
# Build specific configuration
msbuild Microsoft.PowerFx.sln -p:Configuration=Release
msbuild Microsoft.PowerFx.sln -p:Configuration=DebugAll # Multi-targeting (net462 + net7.0)
```
### Building NuGet Packages
```bash
# From src/ directory
.\buildLocalPackages.cmd [Configuration] # Windows
# Default configuration is DebugAll if not specified
# Output packages go to src/outputpackages/
```
### Running Tests
```bash
# From src/ directory
.\runLocalTests.cmd [Configuration] # Windows (uses VSTest)
# Or using dotnet CLI (from solution root)
dotnet test src/Microsoft.PowerFx.sln
# Run tests for a specific project
dotnet test src/tests/Microsoft.PowerFx.Core.Tests.Shared/Microsoft.PowerFx.Core.Tests.Shared.csproj
# Run a single test by name
dotnet test --filter "FullyQualifiedName~YourTestName"
# Run tests by category
dotnet test --filter "Category=ExpressionTest"
```
Note: The `runLocalTests.cmd` script runs tests for both .NET Framework 4.6.2 and .NET 7.0 configurations using VSTest.
### Code Analysis
```bash
# StyleCop analyzers are configured in PowerFx.ruleset
# Analysis runs automatically during build
# Warnings are treated as errors in Release builds
```
## Architecture Overview
### Core Components
The Power Fx implementation follows a classic multi-phase compiler architecture:
**Expression Text → [Lexer] → Tokens → [Parser] → AST → [Binder] → Typed AST → [IR Translator] → IR → [Interpreter/Backend] → Result**
1. **Microsoft.PowerFx.Core** - The language compiler (no evaluation)
- `Lexer/` - Tokenization with culture-aware parsing
- `Parser/` - Recursive descent parser producing AST (`Syntax/Nodes/`)
- `Binding/` - Semantic analysis, symbol resolution, type checking (`Binder.cs` is the core)
- `Types/` - Type system implementation (`DType.cs`, `FormulaType.cs`)
- `IR/` - Intermediate Representation for backend consumption
- `Texl/Builtins/` - Function signatures and type checking (no implementation)
2. **Microsoft.PowerFx.Interpreter** - Execution engine
- `EvalVisitor.cs` - Walks IR tree to compute results
- `Functions/Library*.cs` - Actual function implementations
- `RecalcEngine.cs` - Extends `Engine` with evaluation and reactive formulas
3. **Microsoft.PowerFx.Connectors** - OpenAPI connector support for external APIs
4. **Microsoft.PowerFx.LanguageServerProtocol** - LSP implementation for IDE integration
5. **Microsoft.PowerFx.Json** - JSON serialization/deserialization
### Key Architecture Patterns
**Separation of Compilation and Execution**: The Core library only compiles to IR with zero evaluation code. This allows multiple backends (JavaScript, SQL, etc.) to consume the same IR independently.
**Symbol Table Composition**: Multiple symbol tables can be layered (Config → Engine → Parameters), allowing flexible scoping:
- `SymbolTable` - Mutable, contains variables, functions, enums, user-defined types
- `ReadOnlySymbolTable` - Immutable view, composable
- `SymbolValues` - Runtime values paired with SymbolTable
**CheckResult Workflow**: Central to compilation, with lazy phase evaluation:
```csharp
var check = engine.Check(expressionText, parameterType);
check.ThrowOnErrors(); // Compilation errors
var result = check.Eval(); // Execution (Interpreter only)
```
**Type System**:
- `DType` - Internal discriminated union type representation (via `DKind` enum)
- `FormulaType` - Public API wrapper around DType
- `CoercionMatrix.cs` - Defines valid type conversions
- `BinaryOpMatrix.cs` - Type rules for operators
- Supports: primitives, records, tables, functions, polymorphic types
**Intermediate Representation (IR)**:
- Purpose: Makes it easier for backends to consume compiler output
- Explicit coercion nodes (backends don't reimplement coercion matrix)
- Normalized operators (And() as both operator and function → unified)
- Enums translated to backing values
- Simplified scope handling
- Located in `Microsoft.PowerFx.Core/IR/`
**Display Names vs Logical Names**: Throughout the codebase, dual tracking of:
- Display names: User-facing, localized (e.g., "First Name")
- Logical names: Internal identifiers (e.g., "nwind_firstname")
### Adding a New Built-in Function
Functions are split between Core (signatures/type checking) and Interpreter (implementation):
1. **Define signature** in `src/libraries/Microsoft.PowerFx.Core/Texl/Builtins/NewFunction.cs`:
- Extend `TexlFunction` base class
- Implement `CheckInvocation` for type checking
- Add to `BuiltinFunctionsCore._library`
2. **Implement logic** in `src/libraries/Microsoft.PowerFx.Interpreter/Functions/Library*.cs`:
- Add static method with `[TexlFunction]` attribute or similar pattern
- Use IR nodes as input parameters
- Return `FormulaValue` results
- Register in appropriate `Library` category
3. **Add tests** in `src/tests/Microsoft.PowerFx.Core.Tests.Shared/ExpressionTestCases/NewFunction.txt`:
```
>> NewFunction(arg1, arg2)
ExpectedResult
>> NewFunction("test", 42)
"test42"
```
### Expression Test Cases
Tests use a unique `.txt` file format in `tests/Microsoft.PowerFx.Core.Tests.Shared/ExpressionTestCases/`:
```
>> Expression
ExpectedResult
>> If(true, "yes", "no")
"yes"
>> 1+1
2
>> 1/0
Error({Kind:ErrorKind.Div0})
```
- `BaseRunner.cs` - Test harness infrastructure
- Tests run across multiple backends/configurations
- Special markers: `#skip`, `#error`, `#novalue`
- Fuzzy numeric comparisons for floating point
- 60-second timeout per test
### User-Defined Functions (UDFs)
- Parsed from Power Fx syntax
- `UserDefinedFunction.cs` in both Core and Interpreter
- Support for recursion with stack depth tracking
- Can be added via `Engine.AddUserDefinedFunction()`
### String Localization
- Resource files in `src/strings/PowerFxResources.*.resx`
- Embedded in assemblies
- Access via `StringResources` class
### Feature Flags
- `Features` class controls language behavior
- `Features.PowerFxV1` - Current standard
- Allows gradual feature rollout and compatibility modes
- Configured via `PowerFxConfig`
### Versioning
- Uses Nerdbank.GitVersioning (NBGV)
- Configuration in `version.json` at repository root
- Versions automatically derived from git tags/height
- Base version: 1.5
- Public releases from tags matching `v\d+\.\d+\.\d+$` or `release/\d+\.\d+$` branches
## Project Structure
```
src/
├── Microsoft.PowerFx.sln # Main solution file
├── libraries/ # Core libraries
│ ├── Microsoft.PowerFx.Core/ # Compiler (no evaluation)
│ ├── Microsoft.PowerFx.Interpreter/ # Execution engine
│ ├── Microsoft.PowerFx.Connectors/ # OpenAPI connectors
│ ├── Microsoft.PowerFx.Json/ # JSON integration
│ └── Microsoft.PowerFx.LanguageServerProtocol/ # LSP for IDE support
├── tests/ # Test projects
│ ├── Microsoft.PowerFx.Core.Tests.Shared/
│ │ └── ExpressionTestCases/ # .txt test files
│ └── Microsoft.PowerFx.Interpreter.Tests.Shared/
├── strings/ # Localized resource files
├── Directory.Build.props # Common MSBuild properties
├── PowerFx.ruleset # StyleCop configuration
└── nuget.config # NuGet feed configuration
docs/ # Language documentation
├── overview.md # Language design principles
├── data-types.md # Type system documentation
├── expression-grammar.md # Formal grammar
└── operators.md # Operator reference
```
## Key Files to Understand
- **`Microsoft.PowerFx.Core/Binding/Binder.cs`** (245KB) - Heart of semantic analysis
- **`Microsoft.PowerFx.Core/Types/DType.cs`** (167KB) - Core type representation
- **`Microsoft.PowerFx.Interpreter/Functions/Library.cs`** (146KB) - Main function implementations
- **`Microsoft.PowerFx.Core/Public/Engine.cs`** - Main entry point for compilation
- **`Microsoft.PowerFx.Interpreter/RecalcEngine.cs`** - Evaluation and reactive formulas
- **`Microsoft.PowerFx.Interpreter/EvalVisitor.cs`** - IR tree walker for evaluation
- **`Microsoft.PowerFx.Core/Public/CheckResult.cs`** - Lazy compilation pipeline result
## Important Concepts
### Texl vs Power Fx
"Texl" is the internal codename (from Excel heritage) that appears throughout the codebase. Terms like `TexlFunction`, `TexlLexer`, `TexlParser` all refer to Power Fx components.
### Cooperative Cancellation
The interpreter regularly checks `CancellationToken` and calls `Governor.Poll()` for cooperative cancellation, especially in loops. This prevents runaway evaluation.
### Immutability
Most core data structures are immutable (DType, IR nodes, bound trees). Symbol tables are mutable but have version hashes to detect concurrent mutations.
### DPath
Represents paths through type structure (e.g., "record.field.subfield"). Used extensively for type navigation and error reporting.
### Guard Single Threaded
Core uses `GuardSingleThreaded` to detect concurrent mutations of mutable structures in development builds, catching threading bugs early.
## Configuration Files
- **`Directory.Build.props`** - Shared MSBuild properties across all projects
- C# 10.0 language version
- StyleCop analyzers (strict code quality)
- Treat warnings as errors in Release
- Assembly signing configuration
- NuGet package metadata
- **`PowerFx.ruleset`** / **`PowerFx.Tests.ruleset`** - StyleCop rule configuration
- Strict code analysis for production code
- Relaxed rules for test code
- **`version.json`** - NBGV configuration for automatic versioning
## Development Notes
### Multiple .NET Targets
Projects multi-target:
- .NET Standard 2.0 (for broad compatibility)
- .NET Framework 4.6.2 (legacy support)
- .NET 7.0+ (modern runtime)
Test projects are organized into `.Net4.6.2/` and `.Net7.0/` folders with `.Shared/` projects containing shared test code.
### Build Configurations
- `Debug` / `Release` - Standard single-target builds
- `Debug462` / `Release462` - .NET Framework 4.6.2 specific
- `Debug70` / `Release70` - .NET 7.0 specific
- `DebugAll` / `ReleaseAll` - Multi-targeting (used by local build scripts)
### Code Quality
- StyleCop analyzers enforce consistent code style
- Warnings treated as errors in Release builds
- Code coverage configured in `CodeCoverage.runsettings`
- Performance tests in `Microsoft.PowerFx.Performance.Tests`
### Daily Builds
Daily packages published to Azure Artifacts:
```
https://pkgs.dev.azure.com/Power-Fx/7dd30b4a-31be-4ac9-a649-e6addd4d5b0a/_packaging/PowerFx/nuget/v3/index.json
```
See `dailyBuilds.md` for consumption details.
## Resources
- **Main Documentation**: `docs/overview.md` - Language design principles and philosophy
- **Samples Repository**: https://github.com/microsoft/power-fx-host-samples
- **Public NuGet Packages**: Search for "Microsoft.PowerFx.*" on nuget.org
- **Expression Grammar**: `docs/expression-grammar.md`
- **YAML Formula Grammar**: `docs/yaml-formula-grammar.md` (for source file storage)