Centralize ScriptBlock validation to eliminate drift risk

[Copilot]

Centralize ScriptBlock validation to eliminate drift risk

Plan:

• Export Assert-IdleNoScriptBlock from IdLE.Core module for use by step implementations
• Replace local ScriptBlock validation in Invoke-IdleStepMailboxOutOfOfficeEnsure.ps1 with centralized helper
• Add unit tests for the exported helper in IdLE.Core tests
• Update existing test in Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1 to verify centralized validation
• Update documentation in docs/extend/steps.md to mandate centralized validation helper for step authors
• Run PSScriptAnalyzer and Pester tests to validate changes
• Final verification and review
• Remove duplicate implementation from Private folder (code review feedback)

Summary:

Successfully centralized ScriptBlock validation by:

1. Exporting Assert-IdleNoScriptBlock from IdLE.Core with proper comment-based help in Public folder
2. Removed duplicate implementation from Private folder (was causing function redefinition)
3. Replacing local validation in the Mailbox OutOfOffice step with centralized helper
4. Adding 17 comprehensive test cases for the validation helper
5. Updating documentation in docs/extend/steps.md and STYLEGUIDE.md
6. All 554 tests pass, PSScriptAnalyzer passes with no findings
7. Code review feedback addressed

Impact:

• Single canonical implementation in Public folder
• Reduced duplication and drift risk
• Consistent security enforcement across all steps
• No functional changes or breaking changes
• Clear guidance for future step authors

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Centralize ScriptBlock validation to avoid per-step drift</issue_title>
<issue_description>## Problem Statement

ScriptBlock validation is a security-critical guardrail. If individual steps implement their own ScriptBlock checks (even with good intentions), this introduces duplication and drift risk: different steps may validate differently over time, weakening consistency and maintainability.

Proposed Solution

• Identify any step implementations that perform local ScriptBlock validation on With / step input.
• Replace local validations with a centralized assertion/helper from Core (or a single shared helper in Steps.Common), so the rule is implemented once.
• If a step needs a narrower/specialized rule, document it explicitly and keep the specialized logic small and well-tested.

Requirements:

• Central helper name and location should match existing conventions (approved verbs, consistent naming).
• Ensure the central helper is used consistently across steps that need the check.
• Update relevant docs (developer guidance for step authors) to mandate the centralized helper.

Alternatives Considered

• Leave step-local validation in place.
  • Rejected: increases the chance of inconsistent enforcement and future security regressions.

Impact

• Does this affect existing workflows?
  • No functional change intended; this is a refactor/hardening.
• Any backward compatibility concerns?
  • None.

Acceptance Criteria:

• All ScriptBlock validation in steps is routed through a single canonical helper (unless explicitly documented exception).
• Pester tests cover:
  • The helper behavior (positive/negative cases)
  • At least one step using the helper (integration-style unit test)
• Docs for contributors/step authors reference the centralized approach.

Additional Context

Verification:

• Run PSScriptAnalyzer and Pester in a pwsh-capable environment.

Definition of Done:

• Reduced duplication.
• Consistent behavior across steps.
• No loosening of existing security guardrails.
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Centralize ScriptBlock validation to avoid per-step drift #182

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Pull request overview

This PR centralizes ScriptBlock validation into a single exported helper in IdLE.Core to reduce drift risk across step implementations and to keep “data-only” enforcement consistent (a key security boundary in IdLE).

Changes:

• Adds Assert-IdleNoScriptBlock as an exported IdLE.Core helper with recursive validation + Pester coverage.
• Replaces mailbox step’s local ScriptBlock checks with the centralized helper and updates the corresponding step test expectation.
• Updates step authoring guidance to mandate the centralized helper.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/Steps/Invoke-IdleStepMailboxOutOfOfficeEnsure.Tests.ps1	Updates expected error message pattern after switching to centralized validation.
tests/Core/Assert-IdleNoScriptBlock.Tests.ps1	Adds dedicated Pester coverage for the new centralized validator.
src/IdLE.Steps.Mailbox/Public/Invoke-IdleStepMailboxOutOfOfficeEnsure.ps1	Replaces step-local ScriptBlock validation with Assert-IdleNoScriptBlock.
src/IdLE.Core/Public/Assert-IdleNoScriptBlock.ps1	Introduces exported centralized validator with comment-based help.
src/IdLE.Core/IdLE.Core.psm1	Exports Assert-IdleNoScriptBlock from IdLE.Core.
src/IdLE.Core/IdLE.Core.psd1	Adds Assert-IdleNoScriptBlock to FunctionsToExport.
docs/extend/steps.md	Documents the “data-only” constraint and mandates centralized validation usage for steps.
STYLEGUIDE.md	Adds step authoring rule to use Assert-IdleNoScriptBlock instead of custom checks.