Emit a warning if a result is implicitly ignored (#127)

Author: mandel

examples/callback/repair_prompt.pdl

@@ -1,11 +1,12 @@
-- |
-  Given the following code:
-  ```python
-  ${code_line}
-  ```
-  and the following error:
-  ${error_msg}
-  Please repair the code!
+- text: |
+    Given the following code:
+    ```python
+    ${code_line}
+    ```
+    and the following error:
+    ${error_msg}
+    Please repair the code!
+  contribute: [context]
 
 - def: raw_output
   model: watsonx/ibm/granite-34b-code-instruct

src/pdl/pdl_analysis.py

@@ -0,0 +1,105 @@
+import sys
+from dataclasses import dataclass
+from typing import Sequence
+
+from .pdl_ast import (
+    AdvancedBlockType,
+    ArrayBlock,
+    Block,
+    BlockType,
+    CallBlock,
+    CodeBlock,
+    ContributeTarget,
+    DataBlock,
+    EmptyBlock,
+    ErrorBlock,
+    ForBlock,
+    FunctionBlock,
+    GetBlock,
+    IfBlock,
+    IncludeBlock,
+    LastOfBlock,
+    MessageBlock,
+    ModelBlock,
+    ObjectBlock,
+    Program,
+    ReadBlock,
+    RepeatBlock,
+    RepeatUntilBlock,
+    TextBlock,
+)
+from .pdl_ast_utils import iter_block_children
+
+
+@dataclass
+class UnusedConfig:
+    implicit_ignore: bool
+
+    def with_implicit_ignore(self, b):
+        return UnusedConfig(implicit_ignore=b)
+
+
+_DISPLAY_UNUSED_HINT = True
+
+
+def unused_warning(block: BlockType):
+    global _DISPLAY_UNUSED_HINT  # pylint: disable= global-statement
+    print(f"Warning: the result of block `{block}` is not used.", file=sys.stderr)
+    if _DISPLAY_UNUSED_HINT:
+        _DISPLAY_UNUSED_HINT = False
+        print(
+            "         You might want to use a `text` block around the list or explicitly ignore the result with `contribute: [context]`.",
+            file=sys.stderr,
+        )
+
+
+def unused_program(prog: Program) -> None:
+    state = UnusedConfig(implicit_ignore=False)
+    unused_advanced_block(state, LastOfBlock(lastOf=prog.root))
+
+
+def unused_block(state, block: BlockType) -> None:
+    if not isinstance(block, Block):
+        if state.implicit_ignore:
+            unused_warning(block)
+        return
+    unused_advanced_block(state, block)
+
+
+def unused_advanced_block(state: UnusedConfig, block: AdvancedBlockType) -> None:
+    if block.assign is not None:
+        state = state.with_implicit_ignore(False)
+    if ContributeTarget.RESULT not in block.contribute:
+        state = state.with_implicit_ignore(False)
+    match block:
+        case LastOfBlock():
+            if not isinstance(block.lastOf, str) and isinstance(block.lastOf, Sequence):
+                state_with_ignore = state.with_implicit_ignore(True)
+                for b in block.lastOf[:-1]:
+                    unused_block(state_with_ignore, b)
+                unused_block(state, block.lastOf[-1])
+            else:
+                unused_block(state, block.lastOf)
+        # Leaf blocks without side effects
+        case DataBlock() | FunctionBlock() | GetBlock() | ModelBlock() | ReadBlock():
+            if state.implicit_ignore:
+                unused_warning(block)
+            return
+        # Leaf blocks with side effects
+        case CallBlock() | CodeBlock() | EmptyBlock() | ErrorBlock():
+            return
+        # Non-leaf blocks
+        case (
+            ArrayBlock()
+            | ForBlock()
+            | IfBlock()
+            | IncludeBlock()
+            | MessageBlock()
+            | ObjectBlock()
+            | RepeatBlock()
+            | RepeatUntilBlock()
+            | TextBlock()
+        ):
+            iter_block_children((lambda b: unused_block(state, b)), block)
+        case _:
+            assert False

src/pdl/pdl_parser.py

@@ -4,6 +4,7 @@
 import yaml
 from pydantic import ValidationError
 
+from .pdl_analysis import unused_program
 from .pdl_ast import LocationType, PDLException, Program
 from .pdl_location_utils import get_line_map
 from .pdl_schema_error_analyzer import analyze_errors
@@ -25,6 +26,7 @@ def parse_str(pdl_str: str, file_name: str = "") -> tuple[Program, LocationType]
     loc = LocationType(path=[], file=file_name, table=line_table)
     try:
         prog = Program.model_validate(prog_yaml)
+        unused_program(prog)
     except ValidationError as exc:
         pdl_schema_file = Path(__file__).parent / "pdl-schema.json"
         with open(pdl_schema_file, "r", encoding="utf-8") as schema_fp:

tests/test_examples_parse.py

@@ -1,5 +1,7 @@
 import pathlib
 
+from pytest import CaptureFixture
+
 from pdl.pdl_parser import PDLParseError, parse_file
 
 EXPECTED_INVALID = [
@@ -14,15 +16,20 @@
 ]
 
 
-def test_valid_programs() -> None:
+def test_valid_programs(capsys: CaptureFixture[str]) -> None:
     actual_invalid: set[str] = set()
+    with_warnings: set[str] = set()
     for yaml_file_name in pathlib.Path(".").glob("**/*.pdl"):
         try:
             _ = parse_file(yaml_file_name)
+            captured = capsys.readouterr()
+            if len(captured.err) > 0:
+                with_warnings |= {str(yaml_file_name)}
         except PDLParseError:
             actual_invalid |= {str(yaml_file_name)}
     expected_invalid = set(str(p) for p in EXPECTED_INVALID)
     unexpected_invalid = sorted(list(actual_invalid - expected_invalid))
     assert len(unexpected_invalid) == 0, unexpected_invalid
     unexpected_valid = sorted(list(expected_invalid - actual_invalid))
     assert len(unexpected_valid) == 0, unexpected_valid
+    assert len(with_warnings) == 0

tests/test_implicit_ignore.py

@@ -0,0 +1,57 @@
+from pdl.pdl import exec_str
+
+
+def do_test(capsys, test):
+    result = exec_str(test["prog"])
+    captured = capsys.readouterr()
+    warnings = {line.strip() for line in captured.err.split("\n")} - {
+        "You might want to use a `text` block around the list or explicitly ignore the result with `contribute: [context]`."
+    }
+    assert result == test["result"]
+    assert set(warnings) == set(test["warnings"])
+
+
+def test_strings(capsys):
+    test = {
+        "prog": """
+- Hello
+- How are you?
+- Bye
+""",
+        "result": "Bye",
+        "warnings": [
+            "Warning: the result of block `Hello` is not used.",
+            "Warning: the result of block `How are you?` is not used.",
+            "",
+        ],
+    }
+    do_test(capsys, test)
+
+
+def test_no_warning1(capsys):
+    test = {
+        "prog": """
+text:
+- Hello
+- How are you?
+- Bye
+""",
+        "result": "HelloHow are you?Bye",
+        "warnings": [""],
+    }
+    do_test(capsys, test)
+
+
+def test_no_warning2(capsys):
+    test = {
+        "prog": """
+- def: x
+  text: Hello
+- text: How are you?
+  contribute: []
+- Bye
+""",
+        "result": "Bye",
+        "warnings": [""],
+    }
+    do_test(capsys, test)