hrw4u: Adds sandbox protection feature for the compiler

[zwoop]

A new sandbox mechanism allows administrators to restrict which hrw4u language features are available at compile time. Policy is defined in a YAML configuration file that can deny specific sections, functions, conditions, operators, and language constructs such as break and variables. Violations are reported as compilation errors with a configurable policy message, and per-input sandbox overrides are also supported for testing purposes.

Co-author and ideas: Miles Libbey

[Copilot]

Pull request overview

Adds a sandbox policy mechanism to the hrw4u compiler (and LSP) so admins can deny specific language features at compile time via a YAML config, with consistent error reporting and a configurable policy message.

Changes:

• Introduces SandboxConfig / SandboxDenialError and threads sandbox checks through the compiler visitor and symbol resolver.
• Adds CLI/LSP support for loading a sandbox YAML file and adds a JSON Schema + admin docs for policy authoring.
• Adds a dedicated sandbox test suite (compiler + LSP) and accompanying sandbox test data.

Reviewed changes

Copilot reviewed 57 out of 57 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/hrw4u/tests/utils.py	Adds sandbox test discovery and runner helpers.
tools/hrw4u/tests/test_sandbox.py	New pytest module to validate sandbox allow/deny behavior.
tools/hrw4u/tests/test_lsp.py	Adds diagnostics-wait helper + sandbox-related LSP tests.
tools/hrw4u/tests/data/sandbox/sandbox.yaml	Shared sandbox policy used by tests.
tools/hrw4u/tests/data/sandbox/per-test-sandbox.sandbox.yaml	Per-test sandbox override example.
tools/hrw4u/tests/data/sandbox/per-test-sandbox.input.txt	Sandbox denial input (section).
tools/hrw4u/tests/data/sandbox/per-test-sandbox.error.txt	Expected denial text for per-test override.
tools/hrw4u/tests/data/sandbox/multiple-denials.input.txt	Input triggering multiple denials.
tools/hrw4u/tests/data/sandbox/multiple-denials.error.txt	Expected summary content for multiple denials.
tools/hrw4u/tests/data/sandbox/multiple-denials.ast.txt	AST baseline for multiple-denials input.
tools/hrw4u/tests/data/sandbox/exceptions.txt	Marks sandbox cases that should be skipped by other harnesses.
tools/hrw4u/tests/data/sandbox/denied-section.input.txt	Input using a denied section.
tools/hrw4u/tests/data/sandbox/denied-section.error.txt	Expected denial text for denied section.
tools/hrw4u/tests/data/sandbox/denied-section.ast.txt	AST baseline for denied section.
tools/hrw4u/tests/data/sandbox/denied-modifier-or.sandbox.yaml	Sandbox config denying OR modifier.
tools/hrw4u/tests/data/sandbox/denied-modifier-or.input.txt	Input using `
tools/hrw4u/tests/data/sandbox/denied-modifier-or.error.txt	Expected OR modifier denial text.
tools/hrw4u/tests/data/sandbox/denied-modifier-or.ast.txt	AST baseline for OR modifier case.
tools/hrw4u/tests/data/sandbox/denied-modifier-nocase.sandbox.yaml	Sandbox config denying NOCASE modifier.
tools/hrw4u/tests/data/sandbox/denied-modifier-nocase.input.txt	Input using with NOCASE.
tools/hrw4u/tests/data/sandbox/denied-modifier-nocase.error.txt	Expected NOCASE modifier denial text.
tools/hrw4u/tests/data/sandbox/denied-modifier-nocase.ast.txt	AST baseline for NOCASE modifier case.
tools/hrw4u/tests/data/sandbox/denied-language-in.sandbox.yaml	Sandbox config denying in.
tools/hrw4u/tests/data/sandbox/denied-language-in.input.txt	Input using in [...].
tools/hrw4u/tests/data/sandbox/denied-language-in.error.txt	Expected in denial text.
tools/hrw4u/tests/data/sandbox/denied-language-in.ast.txt	AST baseline for in case.
tools/hrw4u/tests/data/sandbox/denied-language-else.sandbox.yaml	Sandbox config denying else.
tools/hrw4u/tests/data/sandbox/denied-language-else.input.txt	Input using else.
tools/hrw4u/tests/data/sandbox/denied-language-else.error.txt	Expected else denial text.
tools/hrw4u/tests/data/sandbox/denied-language-else.ast.txt	AST baseline for else case.
tools/hrw4u/tests/data/sandbox/denied-language-elif.sandbox.yaml	Sandbox config denying elif.
tools/hrw4u/tests/data/sandbox/denied-language-elif.input.txt	Input using elif.
tools/hrw4u/tests/data/sandbox/denied-language-elif.error.txt	Expected elif denial text.
tools/hrw4u/tests/data/sandbox/denied-language-elif.ast.txt	AST baseline for elif case.
tools/hrw4u/tests/data/sandbox/denied-language-break.input.txt	Input using break.
tools/hrw4u/tests/data/sandbox/denied-language-break.error.txt	Expected break denial text.
tools/hrw4u/tests/data/sandbox/denied-language-break.ast.txt	AST baseline for break case.
tools/hrw4u/tests/data/sandbox/denied-function.input.txt	Input using a denied function.
tools/hrw4u/tests/data/sandbox/denied-function.error.txt	Expected function denial text.
tools/hrw4u/tests/data/sandbox/denied-function.ast.txt	AST baseline for denied function.
tools/hrw4u/tests/data/sandbox/allowed.output.txt	Expected output for allowed sandbox compilation.
tools/hrw4u/tests/data/sandbox/allowed.input.txt	Input that should compile under sandbox.
tools/hrw4u/tests/data/sandbox/allowed.ast.txt	AST baseline for allowed input.
tools/hrw4u/src/visitor_base.py	Captures sandbox message in trap() and adds modifier sandbox checks in shared op-tail parsing.
tools/hrw4u/src/visitor.py	Adds sandbox checks for sections/language/modifiers and passes sandbox into symbol resolver.
tools/hrw4u/src/symbols_base.py	Adds sandbox plumbing to the symbol resolver base.
tools/hrw4u/src/symbols.py	Enforces sandbox denies for operators/conditions/functions during resolution.
tools/hrw4u/src/sandbox.py	New sandbox config loader and denial-check helpers.
tools/hrw4u/src/errors.py	Adds support for appending a single sandbox policy message to the error summary.
tools/hrw4u/src/common.py	Adds generic hooks to pass extra args and visitor kwargs (used for sandbox CLI).
tools/hrw4u/scripts/hrw4u-lsp	Adds --sandbox flag and initialization option to load sandbox policy for diagnostics.
tools/hrw4u/scripts/hrw4u	Adds --sandbox flag and passes sandbox config into the visitor.
tools/hrw4u/schema/sandbox.schema.json	New JSON Schema for sandbox YAML authoring/validation.
tools/hrw4u/pyproject.toml	Adds PyYAML dependency and a pytest marker for sandbox tests.
tools/hrw4u/Makefile	Includes sandbox.py in build inputs; switches PyInstaller builds to --onedir.
tools/hrw4u/.gitignore	Ignores PyInstaller .spec files.
doc/admin-guide/configuration/hrw4u.en.rst	Adds admin documentation for sandbox policy enforcement.

Comments suppressed due to low confidence (1)

doc/admin-guide/configuration/hrw4u.en.rst:528

• Docs say “An empty or missing sandbox file permits everything”, but SandboxConfig.load() requires a top-level sandbox mapping and will raise on an empty file (YAML null) or {}. Either treat missing/empty as SandboxConfig.empty() in the loader, or update this text to clarify that omitting --sandbox permits everything but a provided file must contain sandbox:.

     ...
   }

[zwoop]

I addressed all but one of CoPilot's review comments; One is a FP, the documentation is correct, it just looked in the wrong place.