feat(plugin): add failOnUnresolved validation mode

Author: OrionTheProgrammer

bpj-maven-plugin/src/main/java/io/github/bpj/maven/BpjPrepareMojo.java

@@ -37,6 +37,9 @@ public class BpjPrepareMojo extends AbstractMojo {
     @Parameter(defaultValue = "true")
     private boolean failOnError;
 
+    @Parameter(defaultValue = "false")
+    private boolean failOnUnresolved;
+
     @Parameter(defaultValue = "false")
     private boolean verbose;
 
@@ -74,7 +77,7 @@ public void execute() throws MojoExecutionException {
                 Files.createDirectories(target.getParent());
 
                 String original = Files.readString(source, StandardCharsets.UTF_8);
-                TransformationResult result = transformer.transform(source, original);
+                TransformationResult result = transformer.transform(source, original, failOnUnresolved);
                 changedCalls += result.replacements();
 
                 Files.writeString(target, result.source(), StandardCharsets.UTF_8);

bpj-maven-plugin/src/main/java/io/github/bpj/maven/transform/BpjSourceTransformer.java

@@ -4,12 +4,17 @@
 import com.sun.source.tree.IdentifierTree;
 import com.sun.source.tree.ImportTree;
 import com.sun.source.tree.LiteralTree;
+import com.sun.source.tree.LambdaExpressionTree;
 import com.sun.source.tree.MemberSelectTree;
+import com.sun.source.tree.MethodTree;
 import com.sun.source.tree.MethodInvocationTree;
 import com.sun.source.tree.Tree;
+import com.sun.source.tree.VariableTree;
 import com.sun.source.util.JavacTask;
 import com.sun.source.util.SourcePositions;
+import com.sun.source.util.TreePath;
 import com.sun.source.util.TreePathScanner;
+import com.sun.source.util.TreeScanner;
 import com.sun.source.util.Trees;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
@@ -62,11 +67,28 @@ public final class BpjSourceTransformer {
      * @return transformation result
      */
     public TransformationResult transform(Path sourcePath, String source) {
+        return transform(sourcePath, source, false);
+    }
+
+    /**
+     * Transforms one Java source file content.
+     *
+     * @param sourcePath source path used in parser diagnostics
+     * @param source source code content
+     * @param failOnUnresolved whether unresolved placeholder roots should fail transformation
+     * @return transformation result
+     */
+    public TransformationResult transform(Path sourcePath, String source, boolean failOnUnresolved) {
         Objects.requireNonNull(sourcePath, "sourcePath cannot be null");
         Objects.requireNonNull(source, "source cannot be null");
 
         ParseContext parse = parse(sourcePath, source);
-        List<Insertion> insertions = collectInsertions(sourcePath, parse.compilationUnit, parse.sourcePositions);
+        List<Insertion> insertions = collectInsertions(
+                sourcePath,
+                parse.compilationUnit,
+                parse.sourcePositions,
+                failOnUnresolved
+        );
         if (insertions.isEmpty()) {
             return new TransformationResult(source, 0);
         }
@@ -123,14 +145,23 @@ private void failIfParseErrors(Path sourcePath, DiagnosticCollector<JavaFileObje
     private List<Insertion> collectInsertions(
             Path sourcePath,
             CompilationUnitTree compilationUnit,
-            SourcePositions sourcePositions
+            SourcePositions sourcePositions,
+            boolean failOnUnresolved
     ) {
         List<Insertion> insertions = new ArrayList<>();
 
         new TreePathScanner<Void, Void>() {
             @Override
             public Void visitMethodInvocation(MethodInvocationTree invocation, Void unused) {
-                maybeCollect(sourcePath, invocation, compilationUnit, sourcePositions, insertions);
+                maybeCollect(
+                        sourcePath,
+                        getCurrentPath(),
+                        invocation,
+                        compilationUnit,
+                        sourcePositions,
+                        insertions,
+                        failOnUnresolved
+                );
                 return super.visitMethodInvocation(invocation, unused);
             }
         }.scan(compilationUnit, null);
@@ -140,10 +171,12 @@ public Void visitMethodInvocation(MethodInvocationTree invocation, Void unused)
 
     private void maybeCollect(
             Path sourcePath,
+            TreePath invocationPath,
             MethodInvocationTree invocation,
             CompilationUnitTree compilationUnit,
             SourcePositions sourcePositions,
-            List<Insertion> insertions
+            List<Insertion> insertions,
+            boolean failOnUnresolved
     ) {
         if (invocation.getArguments().size() != 1) {
             return;
@@ -173,6 +206,19 @@ private void maybeCollect(
             return;
         }
 
+        if (failOnUnresolved) {
+            List<String> unresolved = findUnresolvedRoots(roots, invocationPath);
+            if (!unresolved.isEmpty()) {
+                throw unresolvedPlaceholderException(
+                        sourcePath,
+                        compilationUnit,
+                        sourcePositions,
+                        invocation,
+                        unresolved
+                );
+            }
+        }
+
         long end = sourcePositions.getEndPosition(compilationUnit, argument);
         if (end < 0) {
             return;
@@ -257,6 +303,77 @@ private IllegalArgumentException invalidPlaceholderException(
         return new IllegalArgumentException(message);
     }
 
+    private List<String> findUnresolvedRoots(LinkedHashSet<String> roots, TreePath invocationPath) {
+        Set<String> availableRoots = collectAvailableRoots(invocationPath);
+        return roots.stream()
+                .filter(root -> !availableRoots.contains(root))
+                .toList();
+    }
+
+    private Set<String> collectAvailableRoots(TreePath invocationPath) {
+        LinkedHashSet<String> names = new LinkedHashSet<>();
+        names.add("this");
+        names.add("super");
+
+        for (TreePath current = invocationPath; current != null; current = current.getParentPath()) {
+            Tree leaf = current.getLeaf();
+            if (leaf instanceof MethodTree method) {
+                for (VariableTree parameter : method.getParameters()) {
+                    names.add(parameter.getName().toString());
+                }
+                if (method.getBody() != null) {
+                    collectVariableNames(method.getBody(), names);
+                }
+            } else if (leaf instanceof LambdaExpressionTree lambda) {
+                for (VariableTree parameter : lambda.getParameters()) {
+                    names.add(parameter.getName().toString());
+                }
+                collectVariableNames(lambda.getBody(), names);
+            } else if (leaf instanceof com.sun.source.tree.ClassTree classTree) {
+                for (Tree member : classTree.getMembers()) {
+                    if (member instanceof VariableTree field) {
+                        names.add(field.getName().toString());
+                    }
+                }
+            }
+        }
+
+        return names;
+    }
+
+    private void collectVariableNames(Tree tree, Set<String> names) {
+        new TreeScanner<Void, Set<String>>() {
+            @Override
+            public Void visitClass(com.sun.source.tree.ClassTree node, Set<String> collector) {
+                return null;
+            }
+
+            @Override
+            public Void visitVariable(VariableTree variable, Set<String> collector) {
+                collector.add(variable.getName().toString());
+                return super.visitVariable(variable, collector);
+            }
+        }.scan(tree, names);
+    }
+
+    private IllegalArgumentException unresolvedPlaceholderException(
+            Path sourcePath,
+            CompilationUnitTree compilationUnit,
+            SourcePositions sourcePositions,
+            MethodInvocationTree invocation,
+            List<String> unresolved
+    ) {
+        long start = sourcePositions.getStartPosition(compilationUnit, invocation);
+        long line = start >= 0 ? compilationUnit.getLineMap().getLineNumber(start) : -1;
+        String location = line > 0 ? sourcePath + ":" + line : sourcePath.toString();
+
+        String message = "Unresolved BPJ placeholder root(s) " + unresolved
+                + " at " + location
+                + ". Define these variables in scope or disable this validation with "
+                + "<failOnUnresolved>false</failOnUnresolved>.";
+        return new IllegalArgumentException(message);
+    }
+
     private String escapeBraces(String template) {
         return template
                 .replace("{{", ESCAPED_OPEN_TOKEN)

bpj-maven-plugin/src/test/java/io/github/bpj/maven/transform/BpjSourceTransformerTest.java

@@ -138,7 +138,66 @@ void run(String user) {
         assertTrue(exception.getMessage().contains("Demo.java:4"));
     }
 
+    @Test
+    void shouldFailOnUnresolvedRootsWhenEnabled() {
+        String source = """
+                import io.github.bpj.BPJ;
+                class Demo {
+                    void run(String name) {
+                        BPJ.println("Hello {missing}");
+                    }
+                }
+                """;
+
+        IllegalArgumentException exception = assertThrows(
+                IllegalArgumentException.class,
+                () -> transform(source, true)
+        );
+
+        assertTrue(exception.getMessage().contains("Unresolved BPJ placeholder root(s) [missing]"));
+        assertTrue(exception.getMessage().contains("Demo.java:4"));
+    }
+
+    @Test
+    void shouldNotFailOnUnresolvedRootsWhenValidationIsDisabled() {
+        String source = """
+                import io.github.bpj.BPJ;
+                class Demo {
+                    void run(String name) {
+                        BPJ.println("Hello {missing}");
+                    }
+                }
+                """;
+
+        BpjSourceTransformer.TransformationResult result = transform(source, false);
+
+        assertEquals(1, result.replacements());
+        assertTrue(result.source().contains("java.util.Map.of(\"missing\", missing)"));
+    }
+
+    @Test
+    void shouldResolveFieldNamesWhenFailOnUnresolvedIsEnabled() {
+        String source = """
+                import io.github.bpj.BPJ;
+                class Demo {
+                    private final String name = "Ana";
+                    void run() {
+                        BPJ.println("Hello {name}");
+                    }
+                }
+                """;
+
+        BpjSourceTransformer.TransformationResult result = transform(source, true);
+
+        assertEquals(1, result.replacements());
+        assertTrue(result.source().contains("java.util.Map.of(\"name\", name)"));
+    }
+
     private BpjSourceTransformer.TransformationResult transform(String source) {
         return transformer.transform(Path.of("Demo.java"), source);
     }
+
+    private BpjSourceTransformer.TransformationResult transform(String source, boolean failOnUnresolved) {
+        return transformer.transform(Path.of("Demo.java"), source, failOnUnresolved);
+    }
 }

docs/MAVEN_PLUGIN.md

@@ -96,6 +96,18 @@ Default: `true`
 If `true`, transformation errors fail the build.
 If `false`, plugin logs a warning and build continues.
 
+### `failOnUnresolved`
+
+Default: `false`
+
+When `true`, BPJ fails the build if a placeholder root cannot be resolved from the current source scope.
+
+Example:
+- Template: `"Hello {name} {missing}"`
+- In-scope variable: `name`
+- Missing variable: `missing`
+- Result with `failOnUnresolved=true`: plugin throws a clear error before compilation.
+
 ### `verbose`
 
 Default: `false`
@@ -120,6 +132,7 @@ Logs transformed files and replacement counts.
       </executions>
       <configuration>
         <verbose>true</verbose>
+        <failOnUnresolved>true</failOnUnresolved>
       </configuration>
     </plugin>
   </plugins>