starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-04-19 07:00:01 +02:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

Add flag to turn power assertions on/off (#1419)

Browse Source
This commit is contained in:
Islon Scherer
2026-02-03 09:35:16 +01:00
committed by GitHub
parent 7b7b51c0ae
commit f0449c8330
29 changed files with 345 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
pkl-core/src/main/java/org/pkl/core/Analyzer.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -120,7 +120,8 @@ public class Analyzer {
? null
: new ProjectDependenciesManager(
projectDependencies, moduleResolver, securityManager),
traceMode));
traceMode,
false));
});
}
}

18
pkl-core/src/main/java/org/pkl/core/EvaluatorBuilder.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -70,6 +70,8 @@ public final class EvaluatorBuilder {
private TraceMode traceMode = TraceMode.COMPACT;
private boolean powerAssertionsEnabled = false;
private EvaluatorBuilder() {}
/**
@@ -468,6 +470,17 @@ public final class EvaluatorBuilder {
return this.traceMode;
}
/** Sets whether power assertions are enabled. */
public EvaluatorBuilder setPowerAssertionsEnabled(boolean powerAssertions) {
this.powerAssertionsEnabled = powerAssertions;
return this;
}
/** Returns whether power assertions are enabled. */
public boolean getPowerAssertionsEnabled() {
return powerAssertionsEnabled;
}
/**
* Given a project, sets its dependencies, and also applies any evaluator settings if set.
*
@@ -578,6 +591,7 @@ public final class EvaluatorBuilder {
moduleCacheDir,
dependencies,
outputFormat,
traceMode);
traceMode,
powerAssertionsEnabled);
}
}

8
pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -86,7 +86,8 @@ public final class EvaluatorImpl implements Evaluator {
@Nullable Path moduleCacheDir,
@Nullable DeclaredDependencies projectDependencies,
@Nullable String outputFormat,
TraceMode traceMode) {
TraceMode traceMode,
boolean powerAssertions) {
securityManager = manager;
frameTransformer = transformer;
@@ -115,7 +116,8 @@ public final class EvaluatorImpl implements Evaluator {
? null
: new ProjectDependenciesManager(
projectDependencies, moduleResolver, securityManager),
traceMode));
traceMode,
powerAssertions));
});
this.timeout = timeout;
// NOTE: would probably make sense to share executor between evaluators

48
pkl-core/src/main/java/org/pkl/core/ast/type/TypeConstraintNode.java
View File

@@ -29,6 +29,7 @@ import org.pkl.core.ast.lambda.ApplyVmFunction1Node;
import org.pkl.core.runtime.BaseModule;
import org.pkl.core.runtime.VmContext;
import org.pkl.core.runtime.VmFunction;
import org.pkl.core.runtime.VmLanguage;
import org.pkl.core.runtime.VmUtils;
@NodeChild(value = "bodyNode", type = ExpressionNode.class)
@@ -54,13 +55,26 @@ public abstract class TypeConstraintNode extends PklNode {
if (!result) {
CompilerDirectives.transferToInterpreterAndInvalidate();
try (var valueTracker = VmContext.get(this).getValueTrackerFactory().create()) {
getBodyNode().executeGeneric(frame);
var vmContext = VmContext.get(this);
var localContext = VmLanguage.get(this).localContext.get();
// Use power assertions if enabled and not in type test or already instrumenting.
// This prevents `is` checks from triggering instrumentation, but allows them to
// participate if instrumentation is already active.
var usePowerAssertions =
vmContext.getPowerAssertionsEnabled()
&& (!localContext.isInTypeTest() || localContext.hasActiveTracker());
if (usePowerAssertions) {
try (var valueTracker = vmContext.getValueTrackerFactory().create()) {
getBodyNode().executeGeneric(frame);
throw new VmTypeMismatchException.Constraint(
sourceSection,
frame.getAuxiliarySlot(customThisSlot),
sourceSection,
valueTracker.values());
}
} else {
throw new VmTypeMismatchException.Constraint(
sourceSection,
frame.getAuxiliarySlot(customThisSlot),
sourceSection,
valueTracker.values());
sourceSection, frame.getAuxiliarySlot(customThisSlot), sourceSection, null);
}
}
}
@@ -76,10 +90,26 @@ public abstract class TypeConstraintNode extends PklNode {
var result = applyNode.executeBoolean(function, value);
if (!result) {
CompilerDirectives.transferToInterpreterAndInvalidate();
try (var valueTracker = VmContext.get(this).getValueTrackerFactory().create()) {
applyNode.executeBoolean(function, value);
var vmContext = VmContext.get(this);
var localContext = VmLanguage.get(this).localContext.get();
// Use power assertions if enabled and not in type test or already instrumenting.
// This prevents `is` checks from triggering instrumentation, but allows them to
// participate if instrumentation is already active.
var usePowerAssertions =
vmContext.getPowerAssertionsEnabled()
&& (!localContext.isInTypeTest() || localContext.hasActiveTracker());
if (usePowerAssertions) {
try (var valueTracker = vmContext.getValueTrackerFactory().create()) {
applyNode.executeBoolean(function, value);
throw new VmTypeMismatchException.Constraint(
sourceSection,
value,
function.getRootNode().getSourceSection(),
valueTracker.values());
}
} else {
throw new VmTypeMismatchException.Constraint(
sourceSection, value, function.getRootNode().getSourceSection(), valueTracker.values());
sourceSection, value, function.getRootNode().getSourceSection(), null);
}
}
}

8
pkl-core/src/main/java/org/pkl/core/ast/type/TypeTestNode.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -20,6 +20,7 @@ import com.oracle.truffle.api.frame.VirtualFrame;
import com.oracle.truffle.api.nodes.NodeInfo;
import com.oracle.truffle.api.source.SourceSection;
import org.pkl.core.ast.ExpressionNode;
import org.pkl.core.runtime.VmLanguage;
import org.pkl.core.util.Nullable;
@NodeInfo(shortName = "is")
@@ -55,11 +56,16 @@ public final class TypeTestNode extends ExpressionNode {
// TODO: throw if typeNode is FunctionTypeNode (it's impossible to check)
// https://github.com/apple/pkl/issues/639
Object value = valueNode.executeGeneric(frame);
var localContext = VmLanguage.get(this).localContext.get();
boolean wasInTypeTest = localContext.isInTypeTest();
localContext.setInTypeTest(true);
try {
typeNode.executeEagerly(frame, value);
return true;
} catch (VmTypeMismatchException e) {
return false;
} finally {
localContext.setInTypeTest(wasInTypeTest);
}
}
}

6
pkl-core/src/main/java/org/pkl/core/ast/type/VmTypeMismatchException.java
View File

@@ -171,13 +171,13 @@ public abstract class VmTypeMismatchException extends ControlFlowException {
public static final class Constraint extends VmTypeMismatchException {
private final SourceSection constraintBodySourceSection;
private final Map<Node, List<Object>> trackedValues;
private final @Nullable Map<Node, List<Object>> trackedValues;
public Constraint(
SourceSection sourceSection,
Object actualValue,
SourceSection constraintBodySourceSection,
Map<Node, List<Object>> trackedValues) {
@Nullable Map<Node, List<Object>> trackedValues) {
super(sourceSection, actualValue);
this.constraintBodySourceSection = constraintBodySourceSection;
this.trackedValues = trackedValues;
@@ -194,7 +194,7 @@ public abstract class VmTypeMismatchException extends ControlFlowException {
.append(indent)
.append("Value: ")
.append(VmValueRenderer.singleLine(80 - indent.length()).render(actualValue));
if (!withPowerAssertions) {
if (!withPowerAssertions || trackedValues == null) {
return;
}
builder.append("\n\n");

23
pkl-core/src/main/java/org/pkl/core/project/Project.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -81,7 +81,8 @@ public final class Project {
SecurityManager securityManager,
@Nullable java.time.Duration timeout,
StackFrameTransformer stackFrameTransformer,
Map<String, String> envVars) {
Map<String, String> envVars,
boolean powerAssertionsEnabled) {
try (var evaluator =
EvaluatorBuilder.unconfigured()
.setSecurityManager(securityManager)
@@ -92,11 +93,29 @@ public final class Project {
.addResourceReader(ResourceReaders.file())
.addEnvironmentVariables(envVars)
.setTimeout(timeout)
.setPowerAssertionsEnabled(powerAssertionsEnabled)
.build()) {
return load(evaluator, ModuleSource.path(path));
}
}
/**
* Loads Project data from the given {@link Path}.
*
* <p>Evaluates a module's {@code output.value} to allow for embedding a project within a
* template.
*
* @throws PklException if an error occurred while evaluating the project file.
*/
public static Project loadFromPath(
Path path,
SecurityManager securityManager,
@Nullable java.time.Duration timeout,
StackFrameTransformer stackFrameTransformer,
Map<String, String> envVars) {
return loadFromPath(path, securityManager, timeout, stackFrameTransformer, envVars, false);
}
/** Convenience method to load a project with the default stack frame transformer. */
public static Project loadFromPath(
Path path, SecurityManager securityManager, @Nullable java.time.Duration timeout) {

3
pkl-core/src/main/java/org/pkl/core/repl/ReplServer.java
View File

@@ -122,7 +122,8 @@ public class ReplServer implements AutoCloseable {
outputFormat,
packageResolver,
projectDependenciesManager,
traceMode));
traceMode,
true));
});
language = languageRef.get();
}

8
pkl-core/src/main/java/org/pkl/core/runtime/PowerAssertions.java
View File

@@ -66,6 +66,14 @@ import org.pkl.parser.syntax.StringPart.StringInterpolation;
public class PowerAssertions {
private PowerAssertions() {}
/**
* Power assertions can be enabled/disabled via CLI flags (--power-assertions /
* --no-power-assertions) or via EvaluatorBuilder.setPowerAssertions().
*/
public static boolean isEnabled() {
return VmContext.get(null).getPowerAssertionsEnabled();
}
private static final VmValueRenderer vmValueRenderer = VmValueRenderer.singleLine(100);
private static final Parser parser = new Parser();

5
pkl-core/src/main/java/org/pkl/core/runtime/StdLibModule.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -51,7 +51,8 @@ public abstract class StdLibModule {
null,
null,
null,
TraceMode.COMPACT));
TraceMode.COMPACT,
false));
var language = VmLanguage.get(null);
var moduleKey = ModuleKeys.standardLibrary(uri);
var source = VmUtils.loadSource((ResolvedModuleKey) moduleKey);

49
pkl-core/src/main/java/org/pkl/core/runtime/TestRunner.java
View File

@@ -41,6 +41,7 @@ import org.pkl.core.util.AnsiTheme;
import org.pkl.core.util.EconomicMaps;
import org.pkl.core.util.MutableBoolean;
import org.pkl.core.util.MutableReference;
import org.pkl.core.util.Nullable;
/** Runs test results examples and facts. */
public final class TestRunner {
@@ -112,14 +113,20 @@ public final class TestRunner {
try {
var factValue = VmUtils.readMember(listing, idx);
if (factValue == Boolean.FALSE) {
try (var valueTracker = valueTrackerFactory.create()) {
listing.cachedValues.clear();
VmUtils.readMember(listing, idx);
if (PowerAssertions.isEnabled()) {
try (var valueTracker = valueTrackerFactory.create()) {
listing.cachedValues.clear();
VmUtils.readMember(listing, idx);
var failure =
factFailure(
member.getSourceSection(),
getDisplayUri(member),
valueTracker.values());
resultBuilder.addFailure(failure);
}
} else {
var failure =
factFailure(
member.getSourceSection(),
getDisplayUri(member),
valueTracker.values());
factFailure(member.getSourceSection(), getDisplayUri(member), null);
resultBuilder.addFailure(failure);
}
} else {
@@ -408,17 +415,25 @@ public final class TestRunner {
}
private Failure factFailure(
SourceSection sourceSection, String location, Map<Node, List<Object>> trackedValues) {
SourceSection sourceSection,
String location,
@Nullable Map<Node, List<Object>> trackedValues) {
var sb = new AnsiStringBuilder(useColor);
PowerAssertions.render(
sb,
"",
sourceSection,
trackedValues,
(it) -> {
it.append(" ");
appendLocation(it, location);
});
if (trackedValues != null) {
PowerAssertions.render(
sb,
"",
sourceSection,
trackedValues,
(it) -> {
it.append(" ");
appendLocation(it, location);
});
} else {
sb.append(sourceSection.getCharacters());
sb.append(" ");
appendLocation(sb, location);
}
return new Failure("Fact Failure", sb.toString());
}

12
pkl-core/src/main/java/org/pkl/core/runtime/VmContext.java
View File

@@ -38,7 +38,8 @@ public final class VmContext {
private final VmValueTrackerFactory valueTrackerFactory;
public VmContext(VmLanguage vmLanguage, Env env) {
this.valueTrackerFactory = new VmValueTrackerFactory(env.lookup(Instrumenter.class));
this.valueTrackerFactory =
new VmValueTrackerFactory(env.lookup(Instrumenter.class), vmLanguage);
}
@LateInit private Holder holder;
@@ -59,6 +60,7 @@ public final class VmContext {
private final @Nullable PackageResolver packageResolver;
private final @Nullable ProjectDependenciesManager projectDependenciesManager;
private final TraceMode traceMode;
private final boolean powerAssertions;
public Holder(
StackFrameTransformer frameTransformer,
@@ -73,7 +75,8 @@ public final class VmContext {
@Nullable String outputFormat,
@Nullable PackageResolver packageResolver,
@Nullable ProjectDependenciesManager projectDependenciesManager,
TraceMode traceMode) {
TraceMode traceMode,
boolean powerAssertions) {
this.frameTransformer = frameTransformer;
this.securityManager = securityManager;
@@ -95,6 +98,7 @@ public final class VmContext {
this.packageResolver = packageResolver;
this.projectDependenciesManager = projectDependenciesManager;
this.traceMode = traceMode;
this.powerAssertions = powerAssertions;
}
}
@@ -159,6 +163,10 @@ public final class VmContext {
return holder.traceMode;
}
public boolean getPowerAssertionsEnabled() {
return holder.powerAssertions;
}
public VmValueTrackerFactory getValueTrackerFactory() {
return valueTrackerFactory;
}

31
pkl-core/src/main/java/org/pkl/core/runtime/VmLocalContext.java
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2025-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -19,6 +19,15 @@ package org.pkl.core.runtime;
public class VmLocalContext {
private boolean shouldEagerTypecheck = false;
/** Whether we are currently inside a type test ({@code is} check). */
private boolean inTypeTest = false;
/**
* Number of active {@link VmValueTracker} instances. Used to determine if instrumentation is
* already active.
*/
private int activeTrackerDepth = 0;
public VmLocalContext() {}
public void shouldEagerTypecheck(boolean shouldEagerTypecheck) {
@@ -28,4 +37,24 @@ public class VmLocalContext {
public boolean shouldEagerTypecheck() {
return this.shouldEagerTypecheck;
}
public void setInTypeTest(boolean inTypeTest) {
this.inTypeTest = inTypeTest;
}
public boolean isInTypeTest() {
return inTypeTest;
}
public void enterTracker() {
activeTrackerDepth++;
}
public void exitTracker() {
activeTrackerDepth--;
}
public boolean hasActiveTracker() {
return activeTrackerDepth > 0;
}
}

6
pkl-core/src/main/java/org/pkl/core/runtime/VmValueTracker.java
View File

@@ -32,10 +32,13 @@ import org.pkl.core.util.Nullable;
public final class VmValueTracker implements AutoCloseable {
private final EventBinding<ExecutionEventNodeFactory> binding;
private final VmLocalContext localContext;
private final Map<Node, List<Object>> values = new IdentityHashMap<>();
public VmValueTracker(Instrumenter instrumenter) {
public VmValueTracker(Instrumenter instrumenter, VmLocalContext localContext) {
this.localContext = localContext;
localContext.enterTracker();
binding =
instrumenter.attachExecutionEventFactory(
SourceSectionFilter.newBuilder().tagIs(PklTags.Expression.class).build(),
@@ -61,6 +64,7 @@ public final class VmValueTracker implements AutoCloseable {
@Override
public void close() {
localContext.exitTracker();
binding.dispose();
}
}

6
pkl-core/src/main/java/org/pkl/core/runtime/VmValueTrackerFactory.java
View File

@@ -21,13 +21,15 @@ import com.oracle.truffle.api.instrumentation.Instrumenter;
public final class VmValueTrackerFactory {
private final Instrumenter instrumenter;
private final VmLanguage language;
public VmValueTrackerFactory(Instrumenter instrumenter) {
public VmValueTrackerFactory(Instrumenter instrumenter, VmLanguage language) {
this.instrumenter = instrumenter;
this.language = language;
}
@TruffleBoundary
public VmValueTracker create() {
return new VmValueTracker(instrumenter);
return new VmValueTracker(instrumenter, language.localContext.get());
}
}

2
pkl-core/src/test/kotlin/org/pkl/core/EvaluateTestsTest.kt
View File

@@ -28,7 +28,7 @@ import org.pkl.core.ModuleSource.*
class EvaluateTestsTest {
private val evaluator = Evaluator.preconfigured()
private val evaluator = EvaluatorBuilder.preconfigured().setPowerAssertionsEnabled(true).build()
@Test
fun `test successful module`() {

4
pkl-core/src/test/kotlin/org/pkl/core/LanguageSnippetTestsEngine.kt
View File

@@ -1,5 +1,5 @@
/*
* Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
* Copyright © 2024-2026 Apple Inc. and the Pkl project authors. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
@@ -178,6 +178,7 @@ class LanguageSnippetTestsEngine : AbstractLanguageSnippetTestsEngine() {
.addCertificates(FileTestUtils.selfSignedCertificate)
.buildLazily()
)
.setPowerAssertionsEnabled(true)
}
override val testClass: KClass<*> = LanguageSnippetTests::class
@@ -200,6 +201,7 @@ class LanguageSnippetTestsEngine : AbstractLanguageSnippetTestsEngine() {
null,
StackFrameTransformers.empty,
mapOf(),
true, // enable power assertions for tests
)
securityManager = null
applyFromProject(project)