UDF Attributes

CLAUDE.md

@@ -0,0 +1,141 @@
+# 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 C# implementation used across Microsoft Power Platform. The codebase contains a complete compiler and interpreter.
+
+## Build Commands
+
+```bash
+# Build (from repo root)
+dotnet build src/Microsoft.PowerFx.sln
+
+# Build specific configuration (Debug, Release, DebugAll, ReleaseAll, Debug462, Debug70)
+dotnet build src/Microsoft.PowerFx.sln -p:Configuration=Release
+
+# Run all tests
+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 src/Microsoft.PowerFx.sln --filter "FullyQualifiedName~YourTestName"
+
+# Run tests by category
+dotnet test src/Microsoft.PowerFx.sln --filter "Category=ExpressionTest"
+
+# Build local NuGet packages (from src/ directory, outputs to src/outputpackages/)
+.\src\buildLocalPackages.cmd [Configuration]
+
+# Run tests on both net462 and net7.0 via VSTest (from src/ directory)
+.\src\runLocalTests.cmd [Configuration]
+```
+
+**Build configurations**: `Debug`/`Release` (single-target), `Debug462`/`Release462` (net462 only), `Debug70`/`Release70` (net7.0 only), `DebugAll`/`ReleaseAll` (multi-target, used by local build scripts).
+
+## Architecture
+
+### Compiler Pipeline
+
+```
+Expression Text -> [Lexer] -> Tokens -> [Parser] -> AST -> [Binder] -> Typed AST -> [IR Translator] -> IR -> [Interpreter/Backend] -> Result
+```
+
+### Core Libraries
+
+1. **Microsoft.PowerFx.Core** - Compiler only (no evaluation)
+   - `Lexer/` - Tokenization with culture-aware parsing
+   - `Parser/` - Recursive descent parser producing AST nodes (`Syntax/Nodes/`)
+   - `Binding/Binder.cs` (~240KB) - Heart of semantic analysis, symbol resolution, type checking
+   - `Types/DType.cs` (~160KB) - Internal discriminated union type representation (via `DKind` enum)
+   - `IR/` - Intermediate Representation with explicit coercion nodes, normalized operators
+   - `Texl/Builtins/` - Function signatures and type checking only (no implementations)
+   - `Public/Engine.cs` - Main entry point for compilation
+   - `Public/CheckResult.cs` - Lazy compilation pipeline result
+
+2. **Microsoft.PowerFx.Interpreter** - Execution engine
+   - `EvalVisitor.cs` - Walks IR tree to compute results
+   - `Functions/Library*.cs` (~144KB) - Function implementations
+   - `RecalcEngine.cs` - Extends `Engine` with evaluation and reactive formulas
+
+3. **Microsoft.PowerFx.Connectors** - OpenAPI connector support for external APIs
+4. **Microsoft.PowerFx.Json** - JSON serialization/deserialization
+5. **Microsoft.PowerFx.LanguageServerProtocol** - LSP for IDE integration
+6. **Microsoft.PowerFx.Repl** - Read-Eval-Print-Loop
+
+### Key Architecture Patterns
+
+**Separation of Compilation and Execution**: Core compiles to IR with zero evaluation code. Multiple backends (JavaScript, SQL, etc.) can consume the same IR independently.
+
+**Symbol Table Composition**: Layered symbol tables (Config -> Engine -> Parameters) for flexible scoping:
+- `SymbolTable` (mutable) / `ReadOnlySymbolTable` (immutable, composable) for definitions
+- `SymbolValues` for runtime values paired with a SymbolTable
+
+**CheckResult Workflow**:
+```csharp
+var check = engine.Check(expressionText, parameterType);
+check.ThrowOnErrors();
+var result = check.Eval();  // Interpreter only
+```
+
+**Type System**: `DType` is the internal representation, `FormulaType` is the public API wrapper. `CoercionMatrix.cs` defines valid conversions, `BinaryOpMatrix.cs` defines operator type rules.
+
+**Display Names vs Logical Names**: Dual tracking throughout - display names are user-facing/localized (e.g., "First Name"), logical names are internal identifiers (e.g., "nwind_firstname").
+
+### Naming: "Texl" = Power Fx
+
+"Texl" is the internal codename (from Excel heritage). `TexlFunction`, `TexlLexer`, `TexlParser` all refer to Power Fx components.
+
+## Adding a New Built-in Function
+
+1. **Define signature** in `src/libraries/Microsoft.PowerFx.Core/Texl/Builtins/NewFunction.cs`:
+   - Extend `TexlFunction`, implement `CheckInvocation` for type checking
+   - Register in `BuiltinFunctionsCore._library`
+
+2. **Implement logic** in `src/libraries/Microsoft.PowerFx.Interpreter/Functions/Library*.cs`:
+   - Return `FormulaValue` results
+   - Register in appropriate `Library` category
+
+3. **Add tests** in `src/tests/Microsoft.PowerFx.Core.Tests.Shared/ExpressionTestCases/NewFunction.txt`
+
+## Expression Test Cases
+
+Tests use a `.txt` format in `tests/Microsoft.PowerFx.Core.Tests.Shared/ExpressionTestCases/`:
+
+```
+>> If(true, "yes", "no")
+"yes"
+
+>> 1+1
+2
+
+>> 1/0
+Error({Kind:ErrorKind.Div0})
+```
+
+- `BaseRunner.cs` is the test harness infrastructure
+- Tests run across multiple backends/configurations
+- Special markers: `#skip`, `#error`, `#novalue`
+- 60-second timeout per test
+
+## Important Concepts
+
+- **Cooperative Cancellation**: Interpreter checks `CancellationToken` and calls `Governor.Poll()` in loops to prevent runaway evaluation.
+- **Immutability**: Most core data structures (DType, IR nodes, bound trees) are immutable. Symbol tables are mutable but have version hashes to detect concurrent mutations.
+- **DPath**: Represents paths through type structure (e.g., "record.field.subfield"), used for type navigation and error reporting.
+- **GuardSingleThreaded**: Detects concurrent mutations of mutable structures in development builds.
+- **Feature Flags**: `Features` class controls language behavior. `Features.PowerFxV1` is the current standard. Configured via `PowerFxConfig`.
+- **UDFs**: User-defined functions support recursion with stack depth tracking. Added via `Engine.AddUserDefinedFunction()`.
+
+## Code Quality
+
+- **StyleCop analyzers** enforce code style (configured in `src/PowerFx.ruleset`, relaxed in `src/PowerFx.Tests.ruleset`)
+- **Warnings treated as errors** in Release builds
+- C# 10.0 language version, .editorconfig enforces formatting (4-space indent, CRLF, UTF-8 BOM)
+- Multi-targets: .NET Standard 2.0, .NET Framework 4.6.2, .NET 7.0
+- Tests use **xUnit** with aggressive parallelization
+- Test projects organized into `.Net4.6.2/` and `.Net7.0/` folders with `.Shared/` projects for shared code
+- Versioning via Nerdbank.GitVersioning (NBGV), config in `version.json` (base version: 1.8)

src/libraries/Microsoft.PowerFx.Core/Functions/PartialAttributeDefinition.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+using System.Collections.Generic;
+using Microsoft.PowerFx.Core.Errors;
+
+namespace Microsoft.PowerFx
+{
+    /// <summary>
+    /// Built-in attribute definition for the "Partial" attribute,
+    /// which allows splitting a named formula across multiple definitions.
+    /// </summary>
+    internal sealed class PartialAttributeDefinition : IAttributeDefinition
+    {
+        public string Name => "Partial";
+
+        public int MinArgCount => 1;
+
+        public int MaxArgCount => 1;
+
+        public IEnumerable<TexlError> Validate(AttributeValidationContext context) => null;
+    }
+}

src/libraries/Microsoft.PowerFx.Core/Functions/UserDefinedFunction.cs

@@ -25,6 +25,7 @@
 using Microsoft.PowerFx.Syntax;
 using Microsoft.PowerFx.Types;
 using static Microsoft.PowerFx.Core.Localization.TexlStrings;
+using Attribute = Microsoft.PowerFx.Core.Parser.Attribute;
 using CallNode = Microsoft.PowerFx.Syntax.CallNode;
 
 namespace Microsoft.PowerFx.Core.Functions
@@ -40,6 +41,9 @@ internal class UserDefinedFunction : TexlFunction, IExternalPageableSymbol
         private readonly IEnumerable<UDFArg> _args;
         private TexlBinding _binding;
         private readonly IdentToken _returnTypeName;
+        private readonly IReadOnlyList<Attribute> _attributes;
+
+        internal IReadOnlyList<Attribute> Attributes => _attributes;
 
         public override bool IsAsync => _binding.IsAsync(UdfBody);
 
@@ -84,6 +88,18 @@ public override bool SupportsPaging(CallNode callNode, TexlBinding binding)
 
         public TexlBinding Binding => _binding;
 
+        internal IReadOnlyList<NamedFormulaType> GetPublicParameters()
+        {
+            var result = new List<NamedFormulaType>();
+            foreach (var arg in _args.OrderBy(a => a.ArgIndex))
+            {
+                var formulaType = FormulaType.Build(ParamTypes[arg.ArgIndex]);
+                result.Add(new NamedFormulaType(arg.NameIdent.Name.Value, formulaType));
+            }
+
+            return result;
+        }
+
         public bool TryGetExternalDataSource(out IExternalDataSource dataSource)
         {
             return ArgValidators.DelegatableDataSourceInfoValidator.TryGetValidValue(_binding.Top, _binding, out dataSource);
@@ -128,12 +144,14 @@ public override bool CheckTypes(CheckTypesContext context, TexlNode[] args, DTyp
         /// <param name="args"></param>
         /// <param name="argTypes">Array of argTypes in order.</param>
         /// <param name="returnTypeName">Name of the type in the decleration, used by error messages.</param>
-        public UserDefinedFunction(string functionName, DType returnType, TexlNode body, bool isImperative, ISet<UDFArg> args, DType[] argTypes, IdentToken returnTypeName)
+        /// <param name="attributes">Attributes applied to this UDF.</param>
+        public UserDefinedFunction(string functionName, DType returnType, TexlNode body, bool isImperative, ISet<UDFArg> args, DType[] argTypes, IdentToken returnTypeName, IReadOnlyList<Attribute> attributes = null)
         : base(DPath.Root, functionName, functionName, SG(functionName), FunctionCategories.UserDefined, returnType, 0, args.Count, args.Count, argTypes)
         {
             this._args = args;
             this._isImperative = isImperative;
             this._returnTypeName = returnTypeName;
+            this._attributes = attributes ?? Array.Empty<Attribute>();
 
             this.UdfBody = body;
         }
@@ -300,7 +318,7 @@ public UserDefinedFunction WithBinding(INameResolver nameResolver, IBinderGlue b
                 throw new ArgumentNullException(nameof(binderGlue));
             }
 
-            var func = new UserDefinedFunction(Name, ReturnType, UdfBody, _isImperative, new HashSet<UDFArg>(_args), ParamTypes, _returnTypeName);
+            var func = new UserDefinedFunction(Name, ReturnType, UdfBody, _isImperative, new HashSet<UDFArg>(_args), ParamTypes, _returnTypeName, _attributes);
             binding = func.BindBody(nameResolver, binderGlue, bindingConfig, features, rule, updateDisplayNames);
 
             return func;
@@ -369,7 +387,7 @@ public static IEnumerable<UserDefinedFunction> CreateFunctions(IEnumerable<UDF>
                     errors.Add(new TexlError(udf.Ident, DocumentErrorSeverity.Warning, TexlStrings.WrnUDF_ShadowingBuiltInFunction, udfName));
                 }
 
-                var func = new UserDefinedFunction(udfName.Value, returnType, udf.Body, udf.IsImperative, udf.Args, parameterTypes, udf.ReturnType);
+                var func = new UserDefinedFunction(udfName.Value, returnType, udf.Body, udf.IsImperative, udf.Args, parameterTypes, udf.ReturnType, udf.Attributes);
 
                 texlFunctionSet.Add(func);
                 userDefinedFunctions.Add(func);
@@ -427,7 +445,7 @@ internal static UserDefinedFunction CreatePartialFunction(UDF udf, INameResolver
 
             var dummyref = 0;
             var udfBody = udf.Body ?? new PowerFx.Syntax.ErrorNode(ref dummyref, new CommentToken("dummy token", new Span(0, 0)), "dummy error");
-            var func = new UserDefinedFunction(udfName.Value, returnType, udfBody, udf.IsImperative, udf.Args, parameterTypes, udf.ReturnType);
+            var func = new UserDefinedFunction(udfName.Value, returnType, udfBody, udf.IsImperative, udf.Args, parameterTypes, udf.ReturnType, udf.Attributes);
 
             return func;
         }
@@ -542,11 +560,12 @@ public bool HasSameDefintion(string definitionsScript, UserDefinedFunction targe
             Contracts.AssertValue(targetUDF);
 
             if (Name != targetUDF.Name ||
-                UdfBody.GetCompleteSpan().GetFragment(definitionsScript) != targetUDFbody || 
+                UdfBody.GetCompleteSpan().GetFragment(definitionsScript) != targetUDFbody ||
                 _args.Count() != targetUDF._args.Count() ||
                 ReturnType.AssociatedDataSources.SetEquals(targetUDF.ReturnType.AssociatedDataSources) == false ||
                 ReturnType != targetUDF.ReturnType ||
-                _isImperative != targetUDF._isImperative)
+                _isImperative != targetUDF._isImperative ||
+                !AttributesEqual(_attributes, targetUDF._attributes))
             {
                 return false;
             }
@@ -568,6 +587,40 @@ public bool HasSameDefintion(string definitionsScript, UserDefinedFunction targe
             return true;
         }
 
+        private static bool AttributesEqual(IReadOnlyList<Attribute> a, IReadOnlyList<Attribute> b)
+        {
+            if (a.Count != b.Count)
+            {
+                return false;
+            }
+
+            var matched = new bool[b.Count];
+
+            for (var i = 0; i < a.Count; i++)
+            {
+                var found = false;
+
+                for (var j = 0; j < b.Count; j++)
+                {
+                    if (!matched[j] &&
+                        a[i].Name.Name == b[j].Name.Name &&
+                        a[i].Arguments.SequenceEqual(b[j].Arguments))
+                    {
+                        matched[j] = true;
+                        found = true;
+                        break;
+                    }
+                }
+
+                if (!found)
+                {
+                    return false;
+                }
+            }
+
+            return true;
+        }
+
         /// <summary>
         /// NameResolver that combines global named resolver and params for user defined function.
         /// </summary>

src/libraries/Microsoft.PowerFx.Core/Localization/Strings.cs

@@ -915,6 +915,10 @@ internal static class TexlStrings
         public static ErrorResourceKey ErrOperationDoesntMatch = new ErrorResourceKey("ErrOperationDoesntMatch");
         public static ErrorResourceKey ErrUnknownPartialOp = new ErrorResourceKey("ErrUnknownPartialOp");
 
+        public static ErrorResourceKey ErrUnknownAttribute = new ErrorResourceKey("ErrUnknownAttribute");
+        public static ErrorResourceKey ErrAttributeArgCount = new ErrorResourceKey("ErrAttributeArgCount");
+        public static ErrorResourceKey ErrAttributesNotAllowed = new ErrorResourceKey("ErrAttributesNotAllowed");
+
         public static ErrorResourceKey ErrTruncatedArgWarning = new ErrorResourceKey("ErrTruncatedArgWarning");
 
         public static ErrorResourceKey ErrNeedPrimitive = new ErrorResourceKey("ErrNeedPrimitive");

src/libraries/Microsoft.PowerFx.Core/Parser/Attribute.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+using System.Collections.Generic;
+using System.Linq;
+using Microsoft.PowerFx.Syntax;
+
+namespace Microsoft.PowerFx.Core.Parser
+{
+    internal sealed class Attribute
+    {
+        public readonly IdentToken Name;
+
+        public readonly IReadOnlyList<string> Arguments;
+
+        public readonly IReadOnlyList<Token> ArgumentTokens;
+
+        public readonly Token OpenBracket;
+
+        public Attribute(IdentToken name, IReadOnlyList<Token> argumentTokens, Token openBracket)
+        {
+            Name = name;
+            Arguments = argumentTokens.Select(t => t is IdentToken ident ? ident.Name.Value : t.As<StrLitToken>().Value).ToList();
+            ArgumentTokens = argumentTokens;
+            OpenBracket = openBracket;
+        }
+    }
+}

src/libraries/Microsoft.PowerFx.Core/Parser/NamedFormula.cs

@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+using System;
+using System.Collections.Generic;
 using Microsoft.PowerFx.Core.Utils;
 using Microsoft.PowerFx.Syntax;
 
@@ -14,12 +16,12 @@ internal class NamedFormula
 
         internal int StartingIndex { get; }
 
-        internal PartialAttribute Attribute { get; }
+        internal IReadOnlyList<Attribute> Attributes { get; }
 
         // used by the pretty printer to get the proper operator in the output
         internal bool ColonEqual { get; }
 
-        public NamedFormula(IdentToken ident, Formula formula, int startingIndex, bool colonEqual, PartialAttribute attribute = null)
+        public NamedFormula(IdentToken ident, Formula formula, int startingIndex, bool colonEqual, IReadOnlyList<Attribute> attributes = null)
         {
             Contracts.AssertValue(ident);
             Contracts.AssertValue(formula);
@@ -28,7 +30,7 @@ public NamedFormula(IdentToken ident, Formula formula, int startingIndex, bool c
             Formula = formula;
             StartingIndex = startingIndex;
             ColonEqual = colonEqual;
-            Attribute = attribute;
+            Attributes = attributes ?? Array.Empty<Attribute>();
         }
     }
 }