hrw4u: type the AST and add a stage-inspection tool

tools/hrw4u/Makefile

@@ -32,6 +32,9 @@ SCRIPT_U4WRH=scripts/u4wrh
 SCRIPT_LSP=scripts/hrw4u-lsp
 SCRIPT_KG=scripts/hrw4u-kg
 
+# scripts/hrw4u-ast is dev-only — not packaged or shipped. Run it from the
+# source tree via `uv run scripts/hrw4u-ast` or `python scripts/hrw4u-ast`.
+
 # Shared source files (will go in hrw4u package)
 SHARED_FILES=src/common.py \
 	src/debugging.py \
@@ -56,7 +59,7 @@ SRC_FILES_HRW4U=src/visitor.py \
 	src/sandbox.py \
 	src/kg_visitor.py \
 	src/ast_nodes.py \
-	src/ast_visitor.py
+	src/ast_builder.py
 
 ALL_HRW4U_FILES=$(SHARED_FILES) $(UTILS_FILES) $(SRC_FILES_HRW4U)
 
@@ -191,7 +194,8 @@ coverage: gen
 coverage-open: coverage
 	uv run python -m webbrowser "file://$(shell pwd)/htmlcov/index.html"
 
-# Build standalone binaries (optional)
+# Build standalone binaries (optional). hrw4u-ast is intentionally
+# excluded — it's a dev-only inspection tool, not a shipped artifact.
 build: gen
 	uv run pyinstaller --onedir --name hrw4u --strip $(SCRIPT_HRW4U)
 	uv run pyinstaller --onedir --name u4wrh --strip $(SCRIPT_U4WRH)

tools/hrw4u/grammar/hrw4u.g4

@@ -88,6 +88,7 @@ AND           : '&&';
 OR            : '||';
 TILDE         : '~';
 NOT_TILDE     : '!~';
+BANG          : '!';
 COLON         : ':';
 COMMA         : ',';
 SEMICOLON     : ';';
@@ -217,7 +218,7 @@ term
     ;
 
 factor
-    : '!' factor
+    : BANG factor
     | LPAREN expression RPAREN
     | functionCall
     | comparison
@@ -230,9 +231,9 @@ comparison
     : comparable (EQUALS | NEQ | GT | LT) value modifier?
     | comparable (TILDE | NOT_TILDE) regex modifier?
     | comparable IN set modifier?
-    | comparable '!' IN set modifier?
+    | comparable BANG IN set modifier?
     | comparable IN iprange
-    | comparable '!' IN iprange
+    | comparable BANG IN iprange
     ;
 
 modifier

tools/hrw4u/scripts/hrw4u-ast

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+#
+#  Licensed to the Apache Software Foundation (ASF) under one
+#  or more contributor license agreements.  See the NOTICE file
+#  distributed with this work for additional information
+#  regarding copyright ownership.  The ASF licenses this file
+#  to you under the Apache License, Version 2.0 (the
+#  "License"); you may not use this file except in compliance
+#  with the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+"""hrw4u-ast - Inspect the HRW4U AST and the stages around it (CST, ...)."""
+
+from __future__ import annotations
+
+import argparse
+import pprint
+import sys
+from typing import Any, Callable
+
+from antlr4 import CommonTokenStream, InputStream
+
+from hrw4u.ast_builder import ASTBuilder
+from hrw4u.hrw4uLexer import hrw4uLexer
+from hrw4u.hrw4uParser import hrw4uParser
+
+
+def emit_cst(tree: Any, parser: hrw4uParser) -> None:
+    print(tree.toStringTree(recog=parser))
+
+
+def emit_ast(tree: Any, _parser: hrw4uParser) -> None:
+    ast = ASTBuilder().visit(tree)
+    pprint.pp(ast)
+
+
+# Stage registry. Adding a new stage (resolved, validated, ...) is a one-line
+# addition here plus its emit_* function above. Each emitter takes the parse
+# tree and the parser (some stages need the parser for token/rule names).
+STAGES: dict[str, Callable[[Any, hrw4uParser], None]] = {
+    "cst": emit_cst,
+    "ast": emit_ast,
+}
+
+DEFAULT_STAGE = "ast"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Inspect the HRW4U AST and surrounding stages.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="Stages:\n  cst  ANTLR concrete syntax tree (raw parse tree)\n  ast  dataclass AST built by ASTBuilder (default)\n")
+    parser.add_argument(
+        "input_file", nargs="?", type=argparse.FileType("r"), default=sys.stdin, help="HRW4U source file (default: stdin)")
+    parser.add_argument(
+        "--stage", choices=sorted(STAGES.keys()), default=DEFAULT_STAGE, help=f"Which stage to emit (default: {DEFAULT_STAGE})")
+    args = parser.parse_args()
+
+    content = args.input_file.read()
+    if args.input_file is not sys.stdin:
+        args.input_file.close()
+
+    token_stream = CommonTokenStream(hrw4uLexer(InputStream(content)))
+    antlr_parser = hrw4uParser(token_stream)
+    tree = antlr_parser.program()
+
+    if antlr_parser.getNumberOfSyntaxErrors() > 0:
+        print("Parse failed: syntax errors above.", file=sys.stderr)
+        return 1
+
+    STAGES[args.stage](tree, antlr_parser)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())