pi-apexlang 0.1.0

package/skills/apexlang/templates/business-logic/validations/README.md

@@ -0,0 +1,24 @@
+# Validations Templates
+
+## Purpose
+Canonical validation documentation covering expression, SQL, item, interactive-grid, function-body, and PL/SQL error patterns.
+
+## Usage
+- Load `validations._common.md` first to align variable contracts, guardrails, and required inputs.
+- Prefer declarative validation patterns before function-body/error paths, and keep condition usage consistent with logic rules.
+- Use `validations.item.md` for declarative page-item and interactive-grid column checks.
+- Preserve canonical path references and markdown-first conventions when updating workflow or registry links.
+
+## Template Catalog
+- `validations._common.md`
+- `validations._index.md`
+- `validations.expression.md`
+- `validations.function-body.md`
+- `validations.item.md`
+- `validations.plsql-error.md`
+- `validations.sql.md`
+
+## Maintenance
+- Keep this README synchronized with actual files in the directory.
+- Update catalogs and usage notes whenever templates are added, removed, or renamed.
+- Keep validation guidance synchronized with canonical validation type catalog, interactive-grid support, and logic guardrails.

package/skills/apexlang/templates/business-logic/validations/validations._common.md

@@ -0,0 +1,118 @@
+---
+templateId: validations.common
+componentType: validation
+version: 1.0
+description: Canonical validation schema for all page validations.
+---
+
+# Purpose
+
+Define the shared variable contract, guardrails, and skeleton used by all validation templates.
+
+---
+
+# Generation Rules (MANDATORY)
+
+1. Load `references/policies/memory-bank/20-data/apex.logic.md` before drafting validations.
+2. Populate required variables from this contract; scenario files may only specialize optional sections.
+3. Wrap SQL/PLSQL bodies in triple backticks and keep them idempotent.
+4. Treat validations as the default home for user-correctable submit errors; only leave a rule in page-process PL/SQL when it cannot be safely pre-validated before DML.
+
+---
+
+# Variable Contract
+
+| Name | Required | Type | Notes |
+|------|----------|------|-------|
+| validationStaticId | yes | string | Static identifier (`VAL_<target>_<rule>`). |
+| validationName | yes | string | User-facing validation name. |
+| execution.sequence | yes | number | Execution order. |
+| validation.type | yes | string | Type of validation; valid values include `functionBody`, `functionBodyReturningBoolean`, `expression`, `itemIsNotNull`, `itemIsNotNullOrZero`, `itemIsNotZero`, `itemIsNumeric`, `itemIsAlphanumeric`, `itemContainsNoSpaces`, `itemIsAValidDate`, `itemIsAValidTimestamp`, `item=Value`, `item!=Value`, `itemIsContainedInValue`, `itemIsNotContainedInValue`, `itemContainsAtLeastOneOfCharsInValue`, `itemContainsOnlyCharsInValue`, `itemContainsNoneOfCharsInValue`, `itemMatchesRegexp`, `columnIsNotNull`, `columnIsNotNullOrZero`, `columnIsNotZero`, `columnIsNumeric`, `columnIsAlphanumeric`, `columnContainsNoSpaces`, `columnIsAValidDate`, `columnIsAValidTimestamp`, `noRowsReturned`, `rowsReturned`, `plsqlError` |
+| validation.language | optional | enum | Use `sql` when supplying `sqlExpression`. |
+| validation.plsqlExpression | conditional | plsql | Required for `type: expression`. |
+| validation.plsqlFunctionBody | conditional | plsql | Required for `type: functionBody` (return `NULL` on success). |
+| validation.plsqlFunctionBodyReturningBoolean | conditional | plsql | Required for boolean-returning function bodies. |
+| validation.sqlQuery | conditional | sql | Required for SQL-based validations (`noRowsReturned`, etc.). |
+| validation.sqlExpression | conditional | sql | Required when `language: sql`. |
+| validation.item | conditional | string | Required for item-based validations (including `itemIsAValidDate`). |
+| validation.editableRegion | conditional | string | Required for interactive grid validations; references the editable IG region static ID. |
+| validation.column | conditional | string | Required for declarative interactive grid column validations. |
+| validation.value | conditional | string | Required for list/comparison checks; omit for item-only checks such as `itemIsNotNull` and `itemIsAValidDate`. |
+| validation.regexp | conditional | string | Required for regexp validations. |
+| validation.plsqlCodeRaisingError | conditional | plsql | Required for `type: plsqlError`. |
+| validation.alwaysExecute | optional | boolean | Execute regardless of item changes. |
+| error.errorMessage | yes | string | Message shown on failure. |
+| error.associatedItem | conditional | string | Required for page-item validations; item alias (`@P1_ITEM`). |
+| error.associatedColumn | conditional | string | Required for interactive grid validations; target column alias (for example `TASK_TYPE`). |
+| serverSideCondition.whenButtonPressed | optional | string | Button alias gating execution. |
+| security.authorizationScheme | optional | string | Authorization scheme alias. |
+
+---
+
+# Output Template – Full
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: {{validation.type}}
+        item: {{validation.item}}
+        column: {{validation.column}}
+        value: {{validation.value}}
+        regexp: {{validation.regexp}}
+        language: {{validation.language}}
+        plsqlExpression:
+            ```plsql
+            {{validation.plsqlExpression}}
+            ```
+        sqlExpression:
+            ```sql
+            {{validation.sqlExpression}}
+            ```
+        sqlQuery:
+            ```sql
+            {{validation.sqlQuery}}
+            ```
+        plsqlFunctionBody:
+            ```plsql
+            {{validation.plsqlFunctionBody}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+    serverSideCondition {
+        whenButtonPressed: @{{serverSideCondition.whenButtonPressed}}
+    }
+    security {
+        authorizationScheme: @{{security.authorizationScheme}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Include only the validation body block(s) required for the selected `validation.type`.
+- Before adding user-facing `raise_application_error` logic to a process, first attempt these validation options in order:
+  - item / column validation
+  - expression validation
+  - SQL validation
+  - function-body validation only when the above cannot express the rule
+- Use validations for user-facing messages such as `Choose ...`, `Select ...`, `Enter ...`, `Fill ...`, `Must provide ...`, and similar correctable input prompts.
+- Reserve process-level raised errors for runtime or business failures that occur after validation scope, such as packaged API exceptions, optimistic-lock conflicts, or DML invariants that cannot be checked safely in advance.
+- Render `editableRegion` only for interactive grid validations.
+- Render `column` only for declarative interactive grid validations; render `item` only for page-item validations.
+- Render `associatedColumn` only for interactive grid validations; render `associatedItem` only for page-item validations.
+- For expression-style validations with explicit language and no `type`, document the relevant language attribute (for example `sqlExpression`).
+- For `itemIsAValidDate`, render `type` plus `item` only; do not render `value`.
+- For `columnIsAValidDate` and `columnIsAValidTimestamp`, render `editableRegion`, `type`, and `column` only; do not render `value`.
+- Remove `serverSideCondition` and `security` when not gating execution or access.
+- Ensure item aliases, editable region references, column aliases, and button references exist on the target page.
+- For SQL-based validations, submit dependent items before execution.

package/skills/apexlang/templates/business-logic/validations/validations._index.md

@@ -0,0 +1,60 @@
+---
+templateId: validations.index
+component: validation
+  - validations.common
+version: 1.0
+description: Base items and references for validation scenarios.
+---
+
+## Purpose
+Use as the entry point for validation templates; sets shared page items and references scenario templates.
+
+## Native-First Decision Rules
+- For validation prompts, prefer declarative/native validation templates before PL/SQL templates.
+- Use `validations.item.md` for required/no-space/simple declarative rules on page items and interactive grid columns, including `itemIsAValidDate` and `columnIsAValidDate`.
+- Use `validations.expression.md` for status gates and expression-based checks.
+- Use `validations.sql.md` for duplicate/existence checks.
+- Use `validations.function-body.md` or `validations.plsql-error.md` only when no native/declarative option can represent the requirement.
+- Never model a validation request as a page process.
+
+## Variables
+| Name | Required | Type | Description |
+|------|----------|------|-------------|
+| (none) | | | This index declares no dynamic variables; see scenario templates. |
+
+## Template
+```apexlang
+/*
+  Validation Templates Index
+  Multi-file breakdown to mirror authorization structure.
+  Common variables: @/business-logic/validations/validations._common.md
+*/
+
+// Base items shared across scenarios
+pageItem P1_EMPLOYEE_ID (
+    type: textField
+)
+
+pageItem P1_NEW (
+    type: textField
+)
+
+pageItem P1_DISPLAY (
+    type: textField
+)
+
+pageItem P1_DATE (
+    type: datePicker
+)
+
+region task-row-editor (
+    type: interactiveGrid
+)
+
+// Scenario templates
+// - @/business-logic/validations/validations.expression.md
+// - @/business-logic/validations/validations.function-body.md
+// - @/business-logic/validations/validations.item.md
+// - @/business-logic/validations/validations.sql.md
+// - @/business-logic/validations/validations.plsql-error.md
+```

package/skills/apexlang/templates/business-logic/validations/validations.expression.md

@@ -0,0 +1,106 @@
+---
+templateId: validations.expression
+componentType: validation
+version: 1.0
+imports:
+  - validations._common
+description: Expression validation template.
+---
+
+# Purpose
+
+Use for PL/SQL or SQL expression validations (`type: expression`).
+
+---
+
+# Output Template – Minimal
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: expression
+        plsqlExpression:
+            ```plsql
+            {{validation.plsqlExpression}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+---
+
+# Output Template – Full
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: expression
+        language: {{validation.language}}
+        plsqlExpression:
+            ```plsql
+            {{validation.plsqlExpression}}
+            ```
+        sqlExpression:
+            ```sql
+            {{validation.sqlExpression}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+    serverSideCondition {
+        whenButtonPressed: @{{serverSideCondition.whenButtonPressed}}
+    }
+)
+```
+
+---
+
+# Output Template – SQL Expression (Implicit Expression Type)
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        language: sql
+        sqlExpression:
+            ```sql
+            {{validation.sqlExpression}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Set `language: sql` and `sqlExpression` when using SQL expressions.
+- Use the implicit expression form when you need only `language: sql` + `sqlExpression`.
+- Render `editableRegion` only when the expression validation targets an interactive grid.
+- Use `associatedColumn` for interactive grid expression validations and `associatedItem` for page-item validations.
+- Remove `serverSideCondition` when the validation runs unconditionally.
+- Keep expressions side-effect free; raise errors through PL/SQL only when necessary.

package/skills/apexlang/templates/business-logic/validations/validations.function-body.md

@@ -0,0 +1,75 @@
+---
+templateId: validations.function-body
+componentType: validation
+version: 1.0
+imports:
+  - validations._common
+description: PL/SQL function body validation template.
+---
+
+# Purpose
+
+Use for PL/SQL function body validations that return `NULL` or raise errors.
+
+---
+
+# Output Template – Minimal
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: functionBody
+        plsqlFunctionBody:
+            ```plsql
+            {{validation.plsqlFunctionBody}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+---
+
+# Output Template – Boolean Return
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: functionBodyReturningBoolean
+        plsqlFunctionBody:
+            ```plsql
+            {{validation.plsqlFunctionBodyReturningBoolean}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Ensure the function returns `NULL` on success; raise custom errors via PL/SQL when needed.
+- Do not choose function-body validation if item, expression, or SQL validation can express the rule.
+- Do not leave user-correctable submit prompts in a page process just because PL/SQL can raise them there; move those checks into validations first.
+- Use `type: functionBodyReturningBoolean` when the PL/SQL function returns only `TRUE`/`FALSE`.
+- Render `editableRegion` only when the validation targets an interactive grid.
+- Use `associatedColumn` for interactive grid function-body validations and `associatedItem` for page-item validations.
+- Remove optional blocks when not required (e.g., `serverSideCondition`).
+- Keep logic side-effect free; use packages for heavy business rules.

package/skills/apexlang/templates/business-logic/validations/validations.item.md

@@ -0,0 +1,175 @@
+---
+templateId: validations.item
+componentType: validation
+version: 1.0
+imports:
+  - validations._common
+description: Item-level validation catalog.
+---
+
+# Purpose
+
+Use for declarative validations targeting either page items or interactive grid columns.
+
+---
+
+# Output Template – Minimal
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: {{validation.type}}
+        item: {{validation.item}}
+        column: {{validation.column}}
+        value: {{validation.value}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Supply `value` for comparisons (`item=value`, `item!=value`, etc.).
+- Supply `list` for list membership conditions (`itemIsInColonDelimitedList`, `itemIsNotInColonDelimitedList`).
+- Remove `value` for types that only require the item (e.g., `itemIsNotNull`, `itemIsAValidDate`).
+- When `editableRegion` is present, use the `columnIs...` declarative family and render `column` instead of `item`.
+- When `editableRegion` is present, the `error` block must use `associatedColumn` instead of `associatedItem`.
+- `itemIsAValidDate` requires `item` and must not include `value`.
+- `columnIsAValidDate` and `columnIsAValidTimestamp` require `editableRegion` plus `column` and must not include `value`.
+- Use `serverSideCondition` to limit validation to specific buttons when necessary.
+
+---
+
+# Explicit Type Examples
+
+## Item Only
+- `itemIsNotNull`
+- `itemIsNotNullOrZero`
+- `itemIsNotZero`
+- `itemIsNumeric`
+- `itemIsAlphanumeric`
+- `itemContainsNoSpaces`
+- `itemIsAValidDate`
+- `itemIsAValidTimestamp`
+
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        type: itemIsNotNullOrZero
+        item: {{validation.item}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+    }
+)
+```
+
+## Interactive Grid Column Only
+- `columnIsNotNull`
+- `columnIsNotNullOrZero`
+- `columnIsNotZero`
+- `columnIsNumeric`
+- `columnIsAlphanumeric`
+- `columnContainsNoSpaces`
+- `columnIsAValidDate`
+- `columnIsAValidTimestamp`
+
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: columnIsNotNull
+        column: {{validation.column}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+## Item + Value
+- `item=Value`
+- `item!=Value`
+- `itemIsContainedInValue`
+- `itemIsNotContainedInValue`
+- `itemContainsAtLeastOneOfCharsInValue`
+- `itemContainsOnlyCharsInValue`
+- `itemContainsNoneOfCharsInValue`
+
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        type: item!=Value
+        item: {{validation.item}}
+        value: {{validation.value}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+    }
+)
+```
+
+## Item + Regexp
+- `itemMatchesRegexp`
+
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        type: itemMatchesRegexp
+        item: {{validation.item}}
+        regexp: {{validation.regexp}}
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+    }
+)
+```
+
+## Interactive Grid Example
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @task-row-editor
+        type: columnIsNotNull
+        column: TASK_TYPE
+    }
+    error {
+        errorMessage: Task type must have some value
+        associatedColumn: TASK_TYPE
+    }
+)
+```

package/skills/apexlang/templates/business-logic/validations/validations.plsql-error.md

@@ -0,0 +1,42 @@
+---
+templateId: validations.plsql-error
+componentType: validation
+version: 1.0
+imports:
+  - validations._common
+description: PL/SQL raising error validation template.
+---
+
+# Purpose
+
+Use when implementing `type: plsqlError` validations that must raise custom errors.
+
+---
+
+# Output Template – Minimal
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: plsqlError
+        plsqlCodeRaisingError:
+            ```plsql
+            {{validation.plsqlCodeRaisingError}}
+            ```
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Raise errors via `raise_application_error` with documented error codes.
+- Render `editableRegion` only when the validation targets an interactive grid.
+- Add `associatedColumn` in an `error {}` block for interactive grid validations when the error should be pinned to a specific column; otherwise use `associatedItem` for page-item validations.
+- Prevent DML or side effects; validation should only validate state.
+- Add `error` block if custom messages are required beyond raised error text.

package/skills/apexlang/templates/business-logic/validations/validations.sql.md

@@ -0,0 +1,75 @@
+---
+templateId: validations.sql
+componentType: validation
+version: 1.0
+imports:
+  - validations._common
+description: SQL query validation template.
+---
+
+# Purpose
+
+Use for SQL validations that check row existence (`noRowsReturned`, `rowsReturned`).
+
+---
+
+# Output Template – Minimal
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: rowsReturned
+        sqlQuery:
+            ```sql
+            {{validation.sqlQuery}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+)
+```
+
+---
+
+# Output Template – Full
+```
+validation {{validationStaticId}} (
+    name: {{validationName}}
+    execution {
+        sequence: {{execution.sequence}}
+    }
+    validation {
+        editableRegion: @{{validation.editableRegion}}
+        type: {{validation.type}}
+        sqlQuery:
+            ```sql
+            {{validation.sqlQuery}}
+            ```
+    }
+    error {
+        errorMessage: {{error.errorMessage}}
+        associatedItem: @{{error.associatedItem}}
+        associatedColumn: {{error.associatedColumn}}
+    }
+    serverSideCondition {
+        whenButtonPressed: @{{serverSideCondition.whenButtonPressed}}
+    }
+)
+```
+
+---
+
+# Conditional Rendering Rules
+
+- Choose `type: rowsReturned` or `noRowsReturned` based on requirement.
+- Render `editableRegion` only when the SQL validation targets an interactive grid.
+- Use `associatedColumn` for interactive grid SQL validations and `associatedItem` for page-item validations.
+- Submit dependent items and bind variables before validation executes.
+- Remove `serverSideCondition` when not button-gated.