Skip to content

Commit 4a79549

Browse files
authored
Invoke multi-argument-input functions positionally in PCL (#23571)
# Description A function declared with `multiArgumentInputs` is now invoked in PCL by passing its inputs **positionally** rather than as a single object argument: ```hcl # before invoke("pkg:index:fn", { p1 = arg1, p2 = arg2 }) # now invoke("pkg:index:fn", arg1, arg2) ``` The binder **rejects the object-argument form** for such functions with a clear diagnostic (*"function … is declared with multi-argument inputs and must be invoked with positional arguments…"*). The optional `invokeOptions` object is passed as a final positional argument, after one argument per input. To supply options while omitting an optional input, pass `null` for that input: ```hcl invoke("pkg:index:fn", arg1, null, { provider = p }) ``` Anything beyond one argument per input plus the options object is rejected. ## How it works Positional invokes bind against a per-input signature `(token, input₁, …, inputₙ, invokeOptions?)`, and a post-bind pass normalizes the call back into the object-argument form. As a result the rest of PCL and **every program generator continue to observe only the object form** — no generator changes are needed, and PCL itself round-trips the positional source. The `l2-invoke-multi-argument` conformance program is updated to the positional form (its PCL snapshots regenerate accordingly; TypeScript output is unchanged because the normalized object form is identical). The schema lookup shared by signature binding and the post-bind normalization is factored into `invokeTokenArgument` and the binder's `loadPackageSchema` helper. ## Testing - New unit tests in `pkg/codegen/pcl/invoke_positional_test.go`: object-argument form rejected, positional happy paths, optional-input omission, `invokeOptions` as a trailing argument (with and without a `null` placeholder), and too-many-arguments rejection. A `multiarg` test schema fixture is added. - `l2-invoke-multi-argument` conformance passes for PCL and TypeScript (Go and Python remain expected failures, unchanged). - `make lint_golang` is clean. ## Checklist - [x] I have run `make lint` to verify my code passes the lint check - [x] I have added tests that prove my fix is effective or that my feature works - [x] I have run `make changelog` and committed the `changelog/pending/<file>` documenting my change
1 parent 3212152 commit 4a79549

11 files changed

Lines changed: 436 additions & 21 deletions

File tree

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
component: programgen/pcl
2+
kind: feat
3+
body: Invoke functions declared with multi-argument inputs using positional arguments in PCL
4+
time: 2026-06-15T00:00:00+00:00
5+
custom:
6+
PR: "23571"

‎pkg/codegen/pcl/binder.go‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ import (
2020
"encoding/base64"
2121
"fmt"
2222
"io/fs"
23+
"maps"
2324
"net/url"
2425
"os"
2526
"path/filepath"
@@ -482,14 +483,10 @@ func BindProgram(files []*syntax.File, loader schema.Loader, opts ...BindOption)
482483
// Load package descriptors from the files
483484
descriptorMap, descriptorDiags := ReadAllPackageDescriptors(files)
484485
diagnostics = append(diagnostics, descriptorDiags...)
485-
for packageName, descriptor := range descriptorMap {
486-
b.packageDescriptors[packageName] = descriptor
487-
}
486+
maps.Copy(b.packageDescriptors, descriptorMap)
488487
// Caller-supplied descriptors (snippet bindings carry these structurally rather than as PCL syntax)
489488
// take precedence over any file-declared block for the same package.
490-
for packageName, descriptor := range options.extraPackageDescriptors {
491-
b.packageDescriptors[packageName] = descriptor
492-
}
489+
maps.Copy(b.packageDescriptors, options.extraPackageDescriptors)
493490

494491
// Sort files in source order, then declare all top-level nodes in each.
495492
sort.Slice(files, func(i, j int) bool {
@@ -512,6 +509,10 @@ func BindProgram(files []*syntax.File, loader schema.Loader, opts ...BindOption)
512509
return nil, diagnostics, diagnostics
513510
}
514511

512+
// Normalize positional multi-argument invokes into their object-argument form so that downstream
513+
// code only ever observes the object form. See invoke_positional.go.
514+
diagnostics = diagnostics.Extend(b.rewritePositionalInvokes())
515+
515516
return &Program{
516517
Nodes: b.nodes,
517518
files: files,

‎pkg/codegen/pcl/invoke.go‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,38 @@ func getInvokeToken(call *hclsyntax.FunctionCallExpr) (string, hcl.Range, bool)
4646
return literal.Val.AsString(), call.Args[0].Range(), true
4747
}
4848

49+
// invokeTokenArgument extracts the literal function token from a bound invoke call's first argument.
50+
// It returns the token, the literal expression holding it (so callers may canonicalize the token in
51+
// place), and the token's source range. ok is false if the first argument is not a single string
52+
// literal.
53+
func invokeTokenArgument(args []model.Expression) (
54+
token string, lit *model.LiteralValueExpression, tokenRange hcl.Range, ok bool,
55+
) {
56+
if len(args) < 1 {
57+
return "", nil, hcl.Range{}, false
58+
}
59+
template, isTemplate := args[0].(*model.TemplateExpression)
60+
if !isTemplate || len(template.Parts) != 1 {
61+
return "", nil, hcl.Range{}, false
62+
}
63+
literal, isLiteral := template.Parts[0].(*model.LiteralValueExpression)
64+
if !isLiteral || model.StringType.ConversionFrom(literal.Type()) == model.NoConversion {
65+
return "", nil, hcl.Range{}, false
66+
}
67+
return literal.Value.AsString(), literal, args[0].SyntaxNode().Range(), true
68+
}
69+
70+
// loadPackageSchema loads the schema for the named package, honoring a registered package descriptor
71+
// when present and otherwise loading the package's default version. The default version is loaded
72+
// (rather than failing) because the concrete version may not yet be known; see the note in
73+
// binder_resource.go.
74+
func (b *binder) loadPackageSchema(pkg string) (*packageSchema, error) {
75+
if descriptor, ok := b.packageDescriptors[pkg]; ok {
76+
return b.options.packageCache.loadPackageSchemaFromDescriptor(b.options.loader, descriptor)
77+
}
78+
return b.options.packageCache.loadPackageSchema(context.TODO(), b.options.loader, pkg, "", "")
79+
}
80+
4981
// annotateObjectProperties annotates the properties of an object expression with the
5082
// types of the corresponding properties in the schema. This is used to provide type
5183
// information for invoke calls that didn't have type annotations.
@@ -107,16 +139,11 @@ func (b *binder) bindInvokeSignature(args []model.Expression) (model.StaticFunct
107139
return b.zeroSignature(), nil
108140
}
109141

110-
template, ok := args[0].(*model.TemplateExpression)
111-
if !ok || len(template.Parts) != 1 {
112-
return b.zeroSignature(), hcl.Diagnostics{tokenMustBeStringLiteral(args[0])}
113-
}
114-
lit, ok := template.Parts[0].(*model.LiteralValueExpression)
115-
if !ok || model.StringType.ConversionFrom(lit.Type()) == model.NoConversion {
142+
token, lit, tokenRange, ok := invokeTokenArgument(args)
143+
if !ok {
116144
return b.zeroSignature(), hcl.Diagnostics{tokenMustBeStringLiteral(args[0])}
117145
}
118146

119-
token, tokenRange := lit.Value.AsString(), args[0].SyntaxNode().Range()
120147
pkg, _, _, diagnostics := DecomposeToken(token, tokenRange)
121148
if diagnostics.HasErrors() {
122149
return b.zeroSignature(), diagnostics
@@ -168,6 +195,20 @@ func (b *binder) bindInvokeSignature(args []model.Expression) (model.StaticFunct
168195
if len(args) < 2 {
169196
return b.zeroSignature(), hcl.Diagnostics{errorf(tokenRange, "missing second arg")}
170197
}
198+
199+
// A function declared with multiArgumentInputs must be invoked positionally, e.g.
200+
// invoke(token, a, b) rather than invoke(token, { p1 = a, p2 = b }). Reject the object-argument
201+
// form and bind positional calls against a per-input signature; rewritePositionalInvokes later
202+
// normalizes them to the object form. See invoke_positional.go.
203+
if fn.MultiArgumentInputs {
204+
if b.invokeUsesObjectArgument(fn, args) {
205+
return b.zeroSignature(), hcl.Diagnostics{errorf(tokenRange,
206+
"function %q is declared with multi-argument inputs and must be invoked with positional "+
207+
"arguments, e.g. invoke(%q, arg1, arg2), not a single object argument", token, token)}
208+
}
209+
return b.positionalInvokeSignature(fn), nil
210+
}
211+
171212
sig, err := b.signatureForArgs(fn, args[1].Type())
172213
if err != nil {
173214
diag := hcl.Diagnostics{errorf(tokenRange, "Invoke binding error: %v", err)}
Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
// Copyright 2026, Pulumi Corporation.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package pcl
16+
17+
import (
18+
"github.com/hashicorp/hcl/v2"
19+
"github.com/zclconf/go-cty/cty"
20+
21+
"github.com/pulumi/pulumi/pkg/v3/codegen/hcl2/model"
22+
"github.com/pulumi/pulumi/pkg/v3/codegen/hcl2/syntax"
23+
"github.com/pulumi/pulumi/pkg/v3/codegen/schema"
24+
"github.com/pulumi/pulumi/sdk/v3/go/common/util/contract"
25+
)
26+
27+
// A function declared with multiArgumentInputs must be invoked positionally, passing one argument
28+
// per input rather than wrapping them in a single object argument:
29+
//
30+
// invoke("pkg:index:fn", arg1, arg2) // required
31+
// invoke("pkg:index:fn", { p1 = arg1, p2 = arg2 }) // rejected by the binder
32+
//
33+
// The optional invokeOptions object is passed as a final positional argument, after one argument
34+
// per input. To supply invokeOptions while omitting an optional input, pass null for that input:
35+
//
36+
// invoke("pkg:index:fn", arg1, null, { provider = p })
37+
//
38+
// Positional invokes are bound against a per-input signature (see positionalInvokeSignature) and
39+
// then normalized to the object form by rewritePositionalInvokes, so that the rest of PCL and every
40+
// program generator only ever observe the object form.
41+
42+
// invokeUsesObjectArgument reports whether an invoke's second argument is a single object assignable
43+
// to the function's input object (in either its plain or its inputy shape), i.e. the object-argument
44+
// form rather than the positional form.
45+
func (b *binder) invokeUsesObjectArgument(fn *schema.Function, args []model.Expression) bool {
46+
if fn.Inputs == nil || len(args) < 2 {
47+
return false
48+
}
49+
plain := b.schemaTypeToType(fn.Inputs)
50+
inputy := b.schemaTypeToType(fn.Inputs.InputShape)
51+
argType := args[1].Type()
52+
return plain.ConversionFrom(argType) != model.NoConversion ||
53+
inputy.ConversionFrom(argType) != model.NoConversion
54+
}
55+
56+
// positionalInvokeSignature builds the signature for a positional multi-argument invoke:
57+
// (token, <input 1>, <input 2>, ..., invokeOptions?). The parameters follow the order declared by
58+
// the function's multiArgumentInputs. Optional inputs accept null, allowing a caller to skip them
59+
// while still supplying the trailing invokeOptions argument.
60+
func (b *binder) positionalInvokeSignature(fn *schema.Function) model.StaticFunctionSignature {
61+
params := make([]model.Parameter, 0, len(fn.Inputs.Properties)+2)
62+
params = append(params, model.Parameter{Name: "token", Type: model.StringType})
63+
for _, prop := range fn.Inputs.Properties {
64+
t := b.schemaTypeToType(prop.Type)
65+
if !prop.IsRequired() && !model.IsOptionalType(t) {
66+
t = model.NewOptionalType(t)
67+
}
68+
params = append(params, model.Parameter{Name: prop.Name, Type: t})
69+
}
70+
params = append(params, model.Parameter{
71+
Name: "invokeOptions",
72+
Type: model.NewOptionalType(invokeOptionsType()),
73+
})
74+
75+
var returnType model.Type
76+
if fn.ReturnType == nil {
77+
returnType = model.NewObjectType(map[string]model.Type{})
78+
} else {
79+
returnType = b.schemaTypeToType(fn.ReturnType)
80+
}
81+
82+
return model.StaticFunctionSignature{
83+
Parameters: params,
84+
ReturnType: model.NewPromiseType(returnType),
85+
MultiArgumentInputs: fn.MultiArgumentInputs,
86+
}
87+
}
88+
89+
// invokeFunction re-resolves the schema function referenced by an invoke call's arguments. It
90+
// mirrors the lookup performed during signature binding (sharing invokeTokenArgument and
91+
// loadPackageSchema) and relies on the package cache, so it is cheap to call again after binding.
92+
func (b *binder) invokeFunction(args []model.Expression) (*schema.Function, bool) {
93+
token, _, _, ok := invokeTokenArgument(args)
94+
if !ok {
95+
return nil, false
96+
}
97+
pkg, _, _, diags := DecomposeToken(token, hcl.Range{})
98+
if diags.HasErrors() {
99+
return nil, false
100+
}
101+
pkgSchema, err := b.loadPackageSchema(pkg)
102+
if err != nil {
103+
return nil, false
104+
}
105+
fn, _, found, err := pkgSchema.LookupFunction(token)
106+
if err != nil || !found {
107+
return nil, false
108+
}
109+
return fn, true
110+
}
111+
112+
// rewritePositionalInvokes normalizes every positional multi-argument invoke in the program into the
113+
// object-argument form, so that program generators only need to handle the object form.
114+
func (b *binder) rewritePositionalInvokes() hcl.Diagnostics {
115+
var diags hcl.Diagnostics
116+
for _, n := range b.nodes {
117+
diags = diags.Extend(n.VisitExpressions(nil, b.rewritePositionalInvoke))
118+
}
119+
return diags
120+
}
121+
122+
// rewritePositionalInvoke rewrites a single positional multi-argument invoke call into the object
123+
// form: invoke(token, v1, v2) becomes invoke(token, { p1 = v1, p2 = v2 }), preserving any trailing
124+
// invokeOptions argument. Non-invoke expressions and invokes already in object form are returned
125+
// unchanged.
126+
func (b *binder) rewritePositionalInvoke(expr model.Expression) (model.Expression, hcl.Diagnostics) {
127+
call, ok := expr.(*model.FunctionCallExpression)
128+
if !ok || call.Name != Invoke || !call.Signature.MultiArgumentInputs {
129+
return expr, nil
130+
}
131+
fn, ok := b.invokeFunction(call.Args)
132+
if !ok || fn.Inputs == nil {
133+
return expr, nil
134+
}
135+
// A successfully-bound multi-argument invoke is always positional; guard against re-processing a
136+
// call that is already in object form.
137+
if b.invokeUsesObjectArgument(fn, call.Args) {
138+
return expr, nil
139+
}
140+
141+
// The positional signature is (token, input₁ … inputₙ, invokeOptions?), and the binder rejects
142+
// any further arguments. So the arguments after the token are one value per input (with optional
143+
// inputs possibly null), optionally followed by a single invokeOptions object.
144+
numInputs := len(fn.Inputs.Properties)
145+
inputArgs := call.Args[1:]
146+
var optionsArg model.Expression
147+
if len(inputArgs) > numInputs {
148+
contract.Assertf(len(inputArgs) == numInputs+1,
149+
"positional invoke of %q bound with %d arguments for %d inputs", fn.Token, len(inputArgs), numInputs)
150+
optionsArg, inputArgs = inputArgs[numInputs], inputArgs[:numInputs]
151+
}
152+
153+
// Build the object argument, keyed by the input property names in declaration order.
154+
items := make([]model.ObjectConsItem, len(inputArgs))
155+
for i, value := range inputArgs {
156+
items[i] = model.ObjectConsItem{
157+
Key: &model.LiteralValueExpression{Value: cty.StringVal(fn.Inputs.Properties[i].Name)},
158+
Value: value,
159+
}
160+
}
161+
args := &model.ObjectConsExpression{
162+
Tokens: syntax.NewObjectConsTokens(len(items)),
163+
Items: items,
164+
}
165+
// Typecheck computes and caches the object's type from its items. The constructed object has
166+
// string-literal keys and already-bound values, so it cannot produce diagnostics.
167+
typecheckDiags := args.Typecheck(false)
168+
contract.Assertf(len(typecheckDiags) == 0,
169+
"constructing the invoke argument object for %q produced diagnostics: %v", fn.Token, typecheckDiags)
170+
annotateObjectProperties(args.Type(), fn.Inputs)
171+
172+
newArgs := []model.Expression{call.Args[0], args}
173+
if optionsArg != nil {
174+
newArgs = append(newArgs, optionsArg)
175+
}
176+
177+
sig, err := b.signatureForArgs(fn, args.Type())
178+
if err != nil {
179+
// Binding already succeeded against the positional signature; leave the call as-is.
180+
return expr, nil
181+
}
182+
sig.MultiArgumentInputs = fn.MultiArgumentInputs
183+
184+
return &model.FunctionCallExpression{
185+
Syntax: call.Syntax,
186+
Tokens: syntax.NewFunctionCallTokens(call.Name, len(newArgs)),
187+
Name: call.Name,
188+
Signature: sig,
189+
Args: newArgs,
190+
ExpandFinal: call.ExpandFinal,
191+
}, nil
192+
}

0 commit comments

Comments
 (0)