feat: Add preserveComments flag to preserve comment tags in output

Multi-pass rendering scenarios may need to preserve Jinjava comment tags
({# comment #}) for later processing stages. This adds a context flag
that, when enabled, outputs comments as-is instead of stripping them.

PreserveUndefinedExecutionMode now enables this flag by default.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: hs-lsong

preserve-undefined-execution-mode.md

@@ -59,6 +59,16 @@ Set tags are preserved with their evaluated RHS values, enabling the variable to
 | Set with known RHS | `{% set x = name %}{{ x }}` | `{name: "World"}` | `{% set x = 'World' %}World` |
 | Set with unknown RHS | `{% set x = unknown %}{{ x }}` | `{}` | `{% set x = unknown %}{{ x }}` |
 
+### Comments
+
+Comment tags are preserved in output for multi-pass scenarios where comments may contain instructions for later processing stages:
+
+| Feature | Input | Context | Output |
+|---------|-------|---------|--------|
+| Simple comment | `{# this is a comment #}` | `{}` | `{# this is a comment #}` |
+| Inline comment | `Hello {# comment #} World` | `{}` | `Hello {# comment #} World` |
+| Comment with variables | `Hello {{ name }}{# comment #}!` | `{name: "World"}` | `Hello World{# comment #}!` |
+
 ### Macros
 
 Macros are executed and their output is rendered, with only undefined variables within the macro output being preserved:
@@ -109,6 +119,7 @@ String secondPass = jinjava.render(firstPass, dynamicContext, defaultConfig);
 2. **DynamicVariableResolver** - Returns `DeferredValue.instance()` for undefined variables, triggering preservation
 3. **PartialMacroEvaluation** - Allows macros to execute and return partial results with undefined parts preserved
 4. **PreserveResolvedSetTags** - Preserves set tags even when RHS is fully resolved, enabling multi-pass variable binding
+5. **PreserveComments** - Outputs comment tags (`{# ... #}`) as-is instead of stripping them
 
 ### New Context Flag: `isPreserveResolvedSetTags`
 
@@ -126,11 +137,28 @@ context.setPreserveResolvedSetTags(true);
 
 This flag is checked in `EagerSetTagStrategy` to determine whether fully resolved set tags should be preserved in output or consumed during rendering.
 
+### Context Flag: `isPreserveComments`
+
+A context configuration flag to preserve comment tags in output:
+
+```java
+// In ContextConfigurationIF
+default boolean isPreserveComments() {
+    return false;
+}
+
+// Usage in Context
+context.setPreserveComments(true);
+```
+
+This flag is checked in `TreeParser` when processing note tokens. When enabled, comments are output as `TextNode` instead of being discarded.
+
 ## Files Changed
 
 - `PreserveUndefinedExecutionMode.java` - Main execution mode implementation
 - `PreserveUndefinedExpressionStrategy.java` - Expression strategy for preserving original syntax
-- `ContextConfigurationIF.java` - Added `isPreserveResolvedSetTags` flag
-- `Context.java` - Added getter/setter for new flag
-- `EagerSetTagStrategy.java` - Modified to check new flag
-- `PreserveUndefinedExecutionModeTest.java` - Comprehensive test coverage
+- `ContextConfigurationIF.java` - Added `isPreserveResolvedSetTags` and `isPreserveComments` flags
+- `Context.java` - Added getter/setter for new flags
+- `EagerSetTagStrategy.java` - Modified to check `isPreserveResolvedSetTags` flag
+- `TreeParser.java` - Modified to check `isPreserveComments` flag
+- `PreserveUndefinedExecutionModeTest.java` - Test coverage

src/main/java/com/hubspot/jinjava/interpret/Context.java

@@ -892,6 +892,14 @@ public void setUnwrapRawOverride(boolean unwrapRawOverride) {
     contextConfiguration = contextConfiguration.withUnwrapRawOverride(unwrapRawOverride);
   }
 
+  public boolean isPreserveComments() {
+    return contextConfiguration.isPreserveComments();
+  }
+
+  public void setPreserveComments(boolean preserveComments) {
+    contextConfiguration = contextConfiguration.withPreserveComments(preserveComments);
+  }
+
   public TemporaryValueClosable<Boolean> withUnwrapRawOverride() {
     TemporaryValueClosable<Boolean> temporaryValueClosable = new TemporaryValueClosable<>(
       isUnwrapRawOverride(),

src/main/java/com/hubspot/jinjava/interpret/ContextConfigurationIF.java

@@ -48,6 +48,11 @@ default boolean isUnwrapRawOverride() {
     return false;
   }
 
+  @Default
+  default boolean isPreserveComments() {
+    return false;
+  }
+
   @Default
   default ErrorHandlingStrategy getErrorHandlingStrategy() {
     return ErrorHandlingStrategy.of();

src/main/java/com/hubspot/jinjava/mode/PreserveUndefinedExecutionMode.java

@@ -42,5 +42,6 @@ public void prepareContext(Context context) {
     context.setDynamicVariableResolver(varName -> DeferredValue.instance());
     context.setPartialMacroEvaluation(true);
     context.setPreserveResolvedSetTags(true);
+    context.setPreserveComments(true);
   }
 }

src/main/java/com/hubspot/jinjava/tree/TreeParser.java

@@ -147,6 +147,17 @@ private Node nextNode() {
           )
         );
       }
+      if (interpreter.getContext().isPreserveComments()) {
+        TextToken commentAsText = new TextToken(
+          token.getImage(),
+          token.getLineNumber(),
+          token.getStartPosition(),
+          symbols
+        );
+        TextNode n = new TextNode(commentAsText);
+        n.setParent(parent);
+        return n;
+      }
     } else {
       interpreter.addError(
         TemplateError.fromException(

src/test/java/com/hubspot/jinjava/mode/PreserveUndefinedExecutionModeTest.java

@@ -221,4 +221,82 @@ public void itPreservesUndefinedInFromImportMacro() {
     // Macro executes, but undefined variables are preserved
     assertThat(output).isEqualTo("Hello {{ unknown }}!");
   }
+
+  @Test
+  public void itRendersExtendsTagWithStaticPath() {
+    jinjava.setResourceLocator((fullName, encoding, interpreter) -> {
+      if (fullName.equals("base.html")) {
+        return "Base: {% block content %}default{% endblock %}";
+      }
+      return "";
+    });
+
+    String template =
+      "{% extends 'base.html' %}{% block content %}child content{% endblock %}";
+    String output = render(template);
+    assertThat(output).isEqualTo("Base: child content");
+  }
+
+  @Test
+  public void itRendersExtendsTagWithDefinedVariablePath() {
+    jinjava.setResourceLocator((fullName, encoding, interpreter) -> {
+      if (fullName.equals("base.html")) {
+        return "Base: {% block content %}default{% endblock %}";
+      }
+      return "";
+    });
+
+    Map<String, Object> context = new HashMap<>();
+    context.put("templatePath", "base.html");
+    String template =
+      "{% extends templatePath %}{% block content %}child content{% endblock %}";
+    String output = render(template, context);
+    assertThat(output).isEqualTo("Base: child content");
+  }
+
+  @Test
+  public void itPreservesExtendsTagWithUndefinedVariablePath() {
+    String template =
+      "{% extends templatePath %}{% block content %}child content{% endblock %}";
+    String output = render(template);
+    assertThat(output)
+      .isEqualTo(
+        "{% extends templatePath %}{% block content %}child content{% endblock %}"
+      );
+  }
+
+  @Test
+  public void itPreservesUndefinedVariablesInExtendedTemplate() {
+    jinjava.setResourceLocator((fullName, encoding, interpreter) -> {
+      if (fullName.equals("base.html")) {
+        return "Title: {{ title }} - {% block content %}default{% endblock %}";
+      }
+      return "";
+    });
+
+    String template =
+      "{% extends 'base.html' %}{% block content %}{{ message }}{% endblock %}";
+    String output = render(template);
+    assertThat(output).isEqualTo("Title: {{ title }} - {{ message }}");
+  }
+
+  @Test
+  public void itPreservesComments() {
+    String output = render("{# this is a comment #}");
+    assertThat(output).isEqualTo("{# this is a comment #}");
+  }
+
+  @Test
+  public void itPreservesCommentsWithSurroundingContent() {
+    String output = render("Hello {# inline comment #} World");
+    assertThat(output).isEqualTo("Hello {# inline comment #} World");
+  }
+
+  @Test
+  public void itPreservesCommentsWithVariables() {
+    Map<String, Object> context = new HashMap<>();
+    context.put("name", "World");
+    String output = render("Hello {{ name }}{# comment #}!", context);
+    assertThat(output).isEqualTo("Hello World{# comment #}!");
+  }
 }