@netoalmanca/advpl-sensei 1.1.0

package/skills/embedded-sql/SKILL.md

@@ -0,0 +1,379 @@
+---
+name: embedded-sql
+description: Use when writing SQL queries in ADVPL/TLPP using BeginSQL/EndSQL blocks, %table%, %notDel%, %xfilial%, %exp% macros, or when choosing between Embedded SQL and TCQuery string concatenation
+---
+
+# Embedded SQL in ADVPL/TLPP
+
+## Overview
+
+Embedded SQL allows writing SQL queries directly in ADVPL/TLPP code using `BeginSQL ... EndSQL` blocks with special macro expressions. It replaces error-prone string concatenation (`cQuery += "SELECT..."`) with readable, type-safe, and maintainable SQL blocks.
+
+## When to Use
+
+- Writing any SQL query in ADVPL/TLPP (prefer over string concatenation)
+- Need to query with proper filial filtering, deletion handling, and table naming
+- Building reports with complex SELECT, JOIN, GROUP BY
+- Any situation where `TCQuery` with concatenated strings is currently used
+- When readability and maintainability of SQL code matters
+
+## BeginSQL vs TCQuery (String Concatenation)
+
+| Aspect | BeginSQL (Modern) | TCQuery + Strings (Legacy) |
+|--------|-------------------|---------------------------|
+| Readability | SQL written naturally | SQL buried in string concat |
+| Table names | `%table:SE2%` automatic | `RetSqlName("SE2")` manual |
+| Filial filter | `%xfilial:SE2%` automatic | `xFilial("SE2")` manual |
+| Deletion filter | `%notDel%` automatic | `D_E_L_E_T_ = ' '` manual |
+| Variable binding | `%exp:cVar%` | `"'" + cVar + "'"` (SQL injection risk) |
+| Column types | `column X as Date` | `TCSetField` manual |
+| Maintenance | Easy to read and modify | Hard to find errors in strings |
+| SQL Injection | Protected via macros | Vulnerable if not careful |
+
+**Always prefer BeginSQL for new code.**
+
+## Core Syntax
+
+```advpl
+BeginSQL Alias cAlias
+    SELECT columns
+    FROM %table:ALIAS% ALIAS
+    WHERE ALIAS.%notDel%
+    AND ALIAS.FIELD_FILIAL = %xfilial:ALIAS%
+    AND ALIAS.FIELD = %exp:cVariable%
+    ORDER BY %Order:ALIAS%
+EndSQL
+```
+
+**Important:** The alias parameter can be a string literal or `GetNextAlias()`:
+
+```advpl
+Local cAlias := GetNextAlias()
+
+BeginSQL Alias cAlias
+    SELECT A1_COD, A1_LOJA, A1_NOME
+    FROM %table:SA1% SA1
+    WHERE SA1.%notDel%
+    AND SA1.A1_FILIAL = %xfilial:SA1%
+EndSQL
+
+DbSelectArea(cAlias)
+While !Eof()
+    Conout(cAlias->A1_NOME)
+    DbSkip()
+EndDo
+DbCloseArea()
+```
+
+## Special Macro Expressions
+
+### %table:TABLE%
+
+Resolves the physical table name with proper database schema/owner.
+
+```advpl
+-- Input:
+FROM %table:SA1% SA1
+
+-- Expands to (example):
+FROM SA1010 SA1
+-- (where 010 = company code, depends on environment)
+```
+
+### %xfilial:TABLE%
+
+Returns the current branch (filial) value for the table.
+
+```advpl
+-- Input:
+AND SA1.A1_FILIAL = %xfilial:SA1%
+
+-- Expands to:
+AND SA1.A1_FILIAL = '01'
+-- (or '' if table is not branch-filtered)
+```
+
+### %notDel%
+
+Filters out logically deleted records.
+
+```advpl
+-- Input:
+WHERE SA1.%notDel%
+
+-- Expands to:
+WHERE SA1.D_E_L_E_T_ <> '*'
+```
+
+**Always include this.** Protheus uses logical deletion, not physical.
+
+### %exp:EXPRESSION%
+
+Binds ADVPL variables, expressions, or function results into the SQL.
+
+```advpl
+Local cCodCli := "000001"
+Local cLoja   := "01"
+Local dDataIni := CtoD("01/01/2026")
+
+BeginSQL Alias cAlias
+    SELECT E2_PREFIXO, E2_NUM, E2_VALOR, E2_EMISSAO
+    FROM %table:SE2% SE2
+    WHERE SE2.%notDel%
+    AND SE2.E2_FILIAL  = %xfilial:SE2%
+    AND SE2.E2_FORNECE = %exp:cCodCli%
+    AND SE2.E2_LOJA    = %exp:cLoja%
+    AND SE2.E2_EMISSAO >= %exp:DtoS(dDataIni)%
+EndSQL
+```
+
+**Note:** `%exp:%` handles quoting automatically for character fields. For dates, use `DtoS()` to convert.
+
+### %Order:TABLE%
+
+Returns the primary key ordering for the table.
+
+```advpl
+-- Input:
+ORDER BY %Order:SE2%
+
+-- Expands to the primary key columns of SE2
+```
+
+## Column Type Declaration
+
+Declare result column types to avoid manual `TCSetField` calls:
+
+```advpl
+BeginSQL Alias cAlias
+    column E2_EMISSAO as Date
+    column E2_VENCTO  as Date
+    column E2_VALOR   as Numeric(16,2)
+
+    SELECT E2_PREFIXO, E2_NUM, E2_EMISSAO, E2_VENCTO, E2_VALOR
+    FROM %table:SE2% SE2
+    WHERE SE2.%notDel%
+    AND SE2.E2_FILIAL = %xfilial:SE2%
+EndSQL
+
+// Columns are automatically typed - no TCSetField needed
+DbSelectArea(cAlias)
+While !Eof()
+    Local dEmissao := (cAlias)->E2_EMISSAO   // Already Date type
+    Local nValor   := (cAlias)->E2_VALOR      // Already Numeric
+    DbSkip()
+EndDo
+```
+
+**Without `column` declaration**, all fields return as Character and need manual conversion.
+
+## JOIN Patterns
+
+### INNER JOIN
+
+```advpl
+BeginSQL Alias cAlias
+    SELECT SE2.E2_PREFIXO, SE2.E2_NUM, SE2.E2_VALOR,
+           SA2.A2_NOME, SA2.A2_CGC
+    FROM %table:SE2% SE2
+    INNER JOIN %table:SA2% SA2
+        ON SE2.E2_FORNECE = SA2.A2_COD
+        AND SE2.E2_LOJA   = SA2.A2_LOJA
+        AND SA2.A2_FILIAL = %xfilial:SA2%
+        AND SA2.%notDel%
+    WHERE SE2.%notDel%
+    AND SE2.E2_FILIAL = %xfilial:SE2%
+    AND SE2.E2_EMISSAO >= %exp:DtoS(dDataIni)%
+    ORDER BY SE2.E2_EMISSAO
+EndSQL
+```
+
+### LEFT JOIN
+
+```advpl
+BeginSQL Alias cAlias
+    SELECT SC5.C5_NUM, SC5.C5_CLIENTE, SC5.C5_LOJACLI,
+           SA1.A1_NOME
+    FROM %table:SC5% SC5
+    LEFT JOIN %table:SA1% SA1
+        ON SC5.C5_CLIENTE = SA1.A1_COD
+        AND SC5.C5_LOJACLI = SA1.A1_LOJA
+        AND SA1.A1_FILIAL = %xfilial:SA1%
+        AND SA1.%notDel%
+    WHERE SC5.%notDel%
+    AND SC5.C5_FILIAL = %xfilial:SC5%
+EndSQL
+```
+
+**Best practice:** Always use explicit JOIN syntax, not comma-separated FROM.
+
+## Aggregation Patterns
+
+### SUM / COUNT / AVG
+
+```advpl
+BeginSQL Alias cAlias
+    column TOTAL as Numeric(16,2)
+    column QTD   as Numeric(10,0)
+
+    SELECT SE2.E2_FORNECE, SE2.E2_LOJA,
+           SUM(SE2.E2_VALOR) AS TOTAL,
+           COUNT(*) AS QTD
+    FROM %table:SE2% SE2
+    WHERE SE2.%notDel%
+    AND SE2.E2_FILIAL = %xfilial:SE2%
+    AND SE2.E2_EMISSAO BETWEEN %exp:DtoS(dDataIni)% AND %exp:DtoS(dDataFim)%
+    GROUP BY SE2.E2_FORNECE, SE2.E2_LOJA
+    HAVING SUM(SE2.E2_VALOR) > 0
+    ORDER BY TOTAL DESC
+EndSQL
+```
+
+### Subquery
+
+```advpl
+BeginSQL Alias cAlias
+    SELECT SA1.A1_COD, SA1.A1_NOME
+    FROM %table:SA1% SA1
+    WHERE SA1.%notDel%
+    AND SA1.A1_FILIAL = %xfilial:SA1%
+    AND SA1.A1_COD IN (
+        SELECT SC5.C5_CLIENTE
+        FROM %table:SC5% SC5
+        WHERE SC5.%notDel%
+        AND SC5.C5_FILIAL = %xfilial:SC5%
+        AND SC5.C5_EMISSAO >= %exp:DtoS(dDataIni)%
+    )
+EndSQL
+```
+
+## Complete Pattern: Query with Cursor Iteration
+
+```advpl
+#Include "TOTVS.CH"
+#Include "TopConn.ch"
+
+User Function QueryEx()
+    Local cAlias := GetNextAlias()
+    Local aArea  := GetArea()
+    Local aResult := {}
+    Local dDataIni := Date() - 30
+
+    BeginSQL Alias cAlias
+        column E2_EMISSAO as Date
+        column E2_VENCTO  as Date
+        column E2_VALOR   as Numeric(16,2)
+        column SALDO      as Numeric(16,2)
+
+        SELECT SE2.E2_PREFIXO, SE2.E2_NUM, SE2.E2_PARCELA,
+               SE2.E2_FORNECE, SE2.E2_LOJA,
+               SE2.E2_EMISSAO, SE2.E2_VENCTO,
+               SE2.E2_VALOR,
+               (SE2.E2_VALOR - SE2.E2_PAGO) AS SALDO,
+               SA2.A2_NOME
+        FROM %table:SE2% SE2
+        INNER JOIN %table:SA2% SA2
+            ON SE2.E2_FORNECE = SA2.A2_COD
+            AND SE2.E2_LOJA   = SA2.A2_LOJA
+            AND SA2.A2_FILIAL = %xfilial:SA2%
+            AND SA2.%notDel%
+        WHERE SE2.%notDel%
+        AND SE2.E2_FILIAL = %xfilial:SE2%
+        AND SE2.E2_EMISSAO >= %exp:DtoS(dDataIni)%
+        AND (SE2.E2_VALOR - SE2.E2_PAGO) > 0
+        ORDER BY SE2.E2_VENCTO
+    EndSQL
+
+    DbSelectArea(cAlias)
+    While !(cAlias)->(Eof())
+        aAdd(aResult, {;
+            (cAlias)->E2_PREFIXO,;
+            (cAlias)->E2_NUM,;
+            (cAlias)->E2_VALOR,;
+            (cAlias)->SALDO,;
+            (cAlias)->A2_NOME;
+        })
+        (cAlias)->(DbSkip())
+    EndDo
+    (cAlias)->(DbCloseArea())
+
+    RestArea(aArea)
+Return aResult
+```
+
+## Restrictions and Gotchas
+
+| Rule | Why |
+|------|-----|
+| Do NOT start a line with `*` inside BeginSQL | ADVPL pre-compiler treats `*` at line start as comment |
+| Always include `%notDel%` | Protheus uses logical deletion, never rely on physical |
+| Always include `%xfilial%` or filial filter | Multi-branch environments will return wrong data |
+| Use `GetNextAlias()` for the alias | Avoids alias name conflicts with open work areas |
+| Always `DbCloseArea()` after done | Prevents work area leaks (limited number of aliases) |
+| Do NOT use `SELECT *` | Specify columns explicitly for performance and clarity |
+| Date values must use `DtoS()` | Database stores dates as YYYYMMDD strings |
+| `column` declarations go BEFORE the SELECT | They define result types, not query columns |
+
+## DML Operations
+
+For INSERT, UPDATE, DELETE use `TCSqlExec` instead of BeginSQL:
+
+```advpl
+// INSERT
+Local cSql := "INSERT INTO " + RetSqlName("ZZ1") + " "
+cSql += "(ZZ1_FILIAL, ZZ1_CODIGO, ZZ1_DESCRI, D_E_L_E_T_, R_E_C_N_O_) "
+cSql += "VALUES ('" + xFilial("ZZ1") + "', '001', 'Teste', ' ', " + cValToChar(GetSxeNum("ZZ1","ZZ1_CODIGO")) + ")"
+nRet := TCSqlExec(cSql)
+
+// UPDATE
+cSql := "UPDATE " + RetSqlName("ZZ1") + " SET "
+cSql += "ZZ1_DESCRI = 'Novo Valor' "
+cSql += "WHERE ZZ1_FILIAL = '" + xFilial("ZZ1") + "' "
+cSql += "AND ZZ1_CODIGO = '001' "
+cSql += "AND D_E_L_E_T_ = ' '"
+nRet := TCSqlExec(cSql)
+
+If nRet < 0
+    Conout("SQL Error: " + TCSqlError())
+EndIf
+```
+
+**BeginSQL is for SELECT only.** Use `TCSqlExec` for DML (INSERT/UPDATE/DELETE).
+
+## Performance Tips
+
+1. **Use `column` declarations** to avoid post-query type conversions
+2. **Use JOINs** instead of subqueries when possible
+3. **Filter early** with WHERE, not after reading all rows in ADVPL
+4. **Use NOLOCK** hint for read-only queries (SQL Server): `FROM %table:SA1% SA1 WITH(NOLOCK)`
+5. **Use TOP N** when you only need limited results
+6. **Close aliases** immediately after use to free work areas
+7. **Avoid loops with BeginSQL inside** - build one query that returns all needed data
+
+## Migration from TCQuery to BeginSQL
+
+**Before (string concatenation):**
+```advpl
+Local cQuery := ""
+cQuery += "SELECT A1_COD, A1_NOME "
+cQuery += "FROM " + RetSqlName("SA1") + " SA1 "
+cQuery += "WHERE SA1.D_E_L_E_T_ = ' ' "
+cQuery += "AND A1_FILIAL = '" + xFilial("SA1") + "' "
+cQuery += "AND A1_TIPO = '" + cTipo + "'"
+TCQuery cQuery New Alias "QRY_CLI"
+```
+
+**After (Embedded SQL):**
+```advpl
+Local cAlias := GetNextAlias()
+
+BeginSQL Alias cAlias
+    SELECT A1_COD, A1_NOME
+    FROM %table:SA1% SA1
+    WHERE SA1.%notDel%
+    AND SA1.A1_FILIAL = %xfilial:SA1%
+    AND SA1.A1_TIPO = %exp:cTipo%
+EndSQL
+```
+
+Benefits: No manual `RetSqlName`, no `D_E_L_E_T_`, no `xFilial()`, no string quoting, no SQL injection risk.

package/skills/probat-testing/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: probat-testing
+description: Use when generating ProBat unit tests for TLPP classes and functions on TOTVS Protheus
+---
+
+# ProBat Testing
+
+## Overview
+
+ProBat is the native unit testing engine of tlppCore for creating and executing tests in TLPP programs on TOTVS Protheus. The name comes from Latin and means "proof/tests". It supports unit, functional, and integration tests, code coverage analysis, TDD workflows, and CI/CD integration.
+
+> **ProBat only works with TLPP.** Tests for ADVPL sources must also be written in TLPP. If the target code is `.prw`, the test file is still `.tlpp`.
+
+## Required Include
+
+Every test file must include the ProBat header:
+
+```tlpp
+#include "tlpp-probat.th"
+```
+
+If using tlppCore features (JsonObject, REST, etc.), also include:
+
+```tlpp
+#include "tlpp-core.th"
+#include "tlpp-probat.th"
+```
+
+## Namespace Convention
+
+Test namespaces follow the pattern `test.<module>` or `custom.tests.<module>`:
+
+```tlpp
+namespace test.financeiro
+namespace custom.tests.faturamento
+```
+
+## Annotations
+
+All annotations below are confirmed in the official TOTVS `tlpp-probat-samples` repository.
+
+### @TestFixture
+
+Marks a function or class as a test fixture. This is the **only** way ProBat discovers test code.
+
+```tlpp
+// Minimal
+@TestFixture()
+
+// With properties
+@TestFixture(owner='team_name')
+@TestFixture(owner='team_name', target='source_file.tlpp')
+@TestFixture(owner='team_name', suite='suite_name')
+@TestFixture(priority=1)
+@TestFixture(runWithAll=.F.)  // Exclude from "run all" mode
+@TestFixture(rwa=.F.)        // Short alias for runWithAll
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `owner` | Character | Team or author identifier |
+| `target` | Character | Source file being tested (for traceability) |
+| `suite` | Character | Suite name (for grouped execution) |
+| `priority` | Numeric | Execution order (lower = first) |
+| `runWithAll` / `rwa` | Logical | If `.F.`, test is excluded from "run all" mode |
+
+### @Test
+
+Marks a method in a `@TestFixture` class as a test to execute. The description parameter is **mandatory**.
+
+```tlpp
+@Test('description of what is being tested')
+public method myTestMethod()
+```
+
+> If a class has `@TestFixture` but no methods with `@Test`, the result will be SKIPPED.
+
+### @OneTimeSetUp (runs once before all tests)
+
+Marks a method to run **once** before all `@Test` methods in the class. Multiple `@OneTimeSetUp` methods are allowed.
+
+```tlpp
+@OneTimeSetUp()
+public method initDatabase()
+```
+
+### @Setup (runs before each test)
+
+Marks a method to run **before each** `@Test` method.
+
+```tlpp
+@Setup()
+public method resetState()
+```
+
+### @TearDown (runs after each test)
+
+Marks a method to run **after each** `@Test` method.
+
+```tlpp
+@TearDown()
+public method cleanupState()
+```
+
+### @OneTimeTearDown (runs once after all tests)
+
+Marks a method to run **once** after all `@Test` methods in the class.
+
+```tlpp
+@OneTimeTearDown()
+public method closeConnections()
+```
+
+### @Skip
+
+Skips an entire test fixture (function or class) or a specific method. Supports conditional filters.
+
+```tlpp
+// Skip unconditionally
+@Skip()
+
+// Skip with filters
+@Skip(system="windows")
+@Skip(appServerName="HARPIA")
+@Skip(tlppVersion=">= 01.02.10")
+@Skip(system="windows", appServerName="HARPIA", tlppVersion=">= 01.02.10")
+```
+
+### @ErrorLog
+
+Marks a test that is expected to produce an error. The test passes if the specified error occurs.
+
+```tlpp
+@Test('test that expects an error')
+@ErrorLog('type mismatch')
+public method testExpectedError()
+```
+
+### SKIPASSERT (inline command)
+
+Skips the next assertion only. Useful for conditional skipping inside a test.
+
+```tlpp
+SKIPASSERT
+assertError('this assert will be skipped')
+
+// With filters
+SKIPASSERT TLPPVERSION ">= 01.02.10"
+SKIPASSERT SYSTEM "windows"
+SKIPASSERT APPSERVERNAME "HARPIA"
+SKIPASSERT SYSTEM "windows" APPSERVERNAME "HARPIA" TLPPVERSION ">= 01.02.10"
+```
+
+## Assertion Functions
+
+All assertions belong to the `tlpp.probat` namespace. They can be called either by using the namespace directive or with the full qualified name.
+
+```tlpp
+// Option 1: using namespace
+using namespace tlpp.probat
+assertEquals(xValue, xExpected, 'description')
+
+// Option 2: full qualified name
+tlpp.probat.assertEquals(xValue, xExpected, 'description')
+```
+
+### Complete Assertion Reference
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `assertEquals` | `(xValue, xExpected [, cDesc])` | Values must be equal |
+| `assertNotEquals` | `(xValue, xExpected [, cDesc])` | Values must be different |
+| `assertTrue` | `(lValue [, cDesc])` | Value must be `.T.` |
+| `assertFalse` | `(lValue [, cDesc])` | Value must be `.F.` |
+| `assertGreater` | `(xValue, xCompare [, cDesc])` | Value must be greater than expected |
+| `assertGreaterOrEqual` | `(xValue, xCompare [, cDesc])` | Value must be greater than or equal to expected |
+| `assertLess` | `(xValue, xCompare [, cDesc])` | Value must be less than expected |
+| `assertLessOrEqual` | `(xValue, xCompare [, cDesc])` | Value must be less than or equal to expected |
+| `assertNil` | `(xValue [, cDesc])` | Value must be NIL |
+| `assertVector` | `(aValue, aExpected [, cDesc])` | Arrays must be equal |
+| `assertJson` | `(xValue, xExpected [, cDesc])` | JSON objects/strings must be equal |
+| `assertIsRegExFull` | `(cValue, cPattern [, cDesc])` | String must fully match regex |
+| `assertIsRegExPartial` | `(cValue, cPattern [, cDesc])` | String must partially match regex |
+| `assertIsContained` | `(cValue, cSearch [, cDesc])` | String must contain the search value |
+| `assertOK` | `(cDesc)` | Registers a positive result (always passes) |
+| `assertError` | `(cDesc)` | Registers a negative result (always fails) |
+| `assertWarning` | `(cDesc)` | Registers a warning (no pass/fail impact) |
+
+## Execution Lifecycle (Class-based)
+
+```
+Constructor (new)
+  |
+  +-- @OneTimeSetUp methods (once)
+        |
+        +-- @Setup methods (before each test)
+        |     |
+        |     +-- @Test method
+        |     |
+        |     +-- @TearDown methods (after each test)
+        |
+        +-- @Setup methods (before each test)
+        |     |
+        |     +-- @Test method
+        |     |
+        |     +-- @TearDown methods (after each test)
+        |
+        +-- @OneTimeTearDown methods (once)
+```
+
+## Test Execution
+
+### Via REST API (programmatic)
+
+Tests can be discovered and executed using ProBat's REST API or through the main runner. See the official `tlpp-probat-samples` repository for script-based execution examples.
+
+### Via VSCode Extension
+
+TOTVS provides a VSCode extension for ProBat that integrates test discovery and execution directly into the editor.
+
+## References
+
+- `patterns-unit-tests.md` - Templates and patterns for writing ProBat tests
+- [Official samples](https://github.com/totvs/tlpp-probat-samples) - TOTVS official ProBat examples repository
+- [TDN ProBat](https://tdn.totvs.com/display/tec/PROBAT) - Official documentation on TOTVS Developer Network
+- [TDN Asserts](https://tdn.totvs.com/display/tec/d+-+Asserts) - Assertion functions reference