@netoalmanca/advpl-sensei 1.1.0

package/skills/advpl-refactoring/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: advpl-refactoring
+description: Use when refactoring ADVPL/TLPP code - extract functions, simplify logic, remove dead code, improve naming
+---
+
+# ADVPL/TLPP Refactoring
+
+## Overview
+
+Patterns and rules for safe refactoring of ADVPL/TLPP code on TOTVS Protheus. Focuses on improving code structure without changing behavior.
+
+## When to Use
+
+- Functions too long (>100 lines)
+- Duplicated code across files or functions
+- Complex nested conditionals (>3 levels deep)
+- Variables with unclear names
+- Dead code (unreachable blocks, unused variables/functions)
+- God functions that do too many things
+
+## Refactoring Patterns
+
+### RF-001: Extract Function (Complexity: LOW)
+
+**Detect:** Function body > 100 lines with identifiable logical blocks
+**Action:** Extract logical block into a new Static Function
+**Rule:** The extracted function must receive all needed data as parameters (no shared Private/Public)
+
+Before:
+```advpl
+User Function ProcessaPedido()
+    // ... 40 lines validating data ...
+    // ... 30 lines calculating totals ...
+    // ... 50 lines saving to database ...
+Return
+```
+
+After:
+```advpl
+User Function ProcessaPedido()
+    If !fValidaDados(cCodPed)
+        Return .F.
+    EndIf
+    nTotal := fCalculaTotais(cCodPed)
+    lOk := fGravaPedido(cCodPed, nTotal)
+Return lOk
+
+Static Function fValidaDados(cCodPed)
+    // 40 lines
+Return lValido
+
+Static Function fCalculaTotais(cCodPed)
+    // 30 lines
+Return nTotal
+
+Static Function fGravaPedido(cCodPed, nTotal)
+    // 50 lines
+Return lOk
+```
+
+### RF-002: Simplify Conditionals (Complexity: LOW)
+
+**Detect:** Nested If > 3 levels deep, or long If/ElseIf chains
+**Action:** Use early return, guard clauses, or Do Case
+
+Before:
+```advpl
+If lCondicao1
+    If lCondicao2
+        If lCondicao3
+            // codigo principal
+        EndIf
+    EndIf
+EndIf
+```
+
+After:
+```advpl
+If !lCondicao1
+    Return
+EndIf
+If !lCondicao2
+    Return
+EndIf
+If !lCondicao3
+    Return
+EndIf
+// codigo principal
+```
+
+### RF-003: Remove Dead Code (Complexity: LOW)
+
+**Detect:** Variables declared but never used, unreachable code after Return, commented-out blocks
+**Action:** Remove the dead code entirely
+**Rule:** Use Grep to verify the variable/function is not called from other files before removing
+
+### RF-004: Improve Naming (Complexity: LOW)
+
+**Detect:** Variables without Hungarian notation, single-letter names (except loop counters), unclear names
+**Action:** Rename following Hungarian notation convention
+
+| Type | Prefix | Example |
+|------|--------|---------|
+| Character | c | cNomeCli, cCodProd |
+| Numeric | n | nValor, nQtde |
+| Logical | l | lOk, lContinua |
+| Date | d | dDataIni, dEmissao |
+| Array | a | aDados, aItens |
+| Object | o | oModel, oReport |
+| Block | b | bBloco, bFiltro |
+
+### RF-005: Eliminate Duplication (Complexity: MEDIUM)
+
+**Detect:** Two or more code blocks with >5 similar lines
+**Action:** Extract common logic into a shared function
+**Rule:** Only extract if the logic is truly identical, not just visually similar
+
+### RF-006: Reduce Function Parameters (Complexity: MEDIUM)
+
+**Detect:** Functions with >5 parameters
+**Action:** Group related parameters into a JSON object or array
+**Rule:** Only apply if parameters are logically related
+
+## Refactoring Process
+
+1. **Analyze** — Read the file, identify refactoring opportunities
+2. **Prioritize** — Order by impact: dead code removal first, then naming, then extraction
+3. **Present plan** — Show each refactoring with before/after
+4. **Wait for approval** — User must approve before changes are applied
+5. **Apply changes** — One refactoring at a time
+6. **Verify** — Ensure the code structure is correct after each change
+
+## Safety Rules
+
+- NEVER change business logic during refactoring
+- NEVER rename Public/Private variables that might be used externally
+- ALWAYS check for external callers before removing functions (use Grep)
+- ALWAYS preserve the function signature (parameters and return type)
+- If unsure whether behavior will change, DO NOT refactor — flag it as a suggestion only

package/skills/advpl-to-tlpp-migration/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: advpl-to-tlpp-migration
+description: Use when migrating ADVPL procedural code to TLPP object-oriented code, converting functions to classes, or modernizing legacy Protheus code
+---
+
+# ADVPL to TLPP Migration
+
+## Overview
+
+Systematic approach for converting legacy ADVPL procedural code to modern TLPP with object-oriented programming patterns. This skill guides the migration process from `.prw` files with User Functions and Static Functions to `.tlpp` files with namespaces, classes, and methods -- while preserving backward compatibility with existing callers.
+
+## When to Use
+
+- Converting procedural ADVPL functions to TLPP classes
+- Refactoring User Functions into object-oriented service classes
+- Replacing Private/Public variable scoping with class properties
+- Modernizing multiple `#Include` directives to TLPP `.th` includes (`tlpp-core.th`, `tlpp-rest.th`, etc.) and adding proper `namespace` declarations
+- Migrating Static Functions to private class methods
+- Wrapping legacy function calls for backward compatibility during gradual migration
+- Any `.prw` to `.tlpp` file conversion
+
+## Migration Strategy
+
+```dot
+digraph migration {
+    rankdir=TB;
+    node [shape=box];
+
+    analyze [label="Analyze source .prw file"];
+    identify [label="Identify functions\nand dependencies"];
+    map [label="Map to class structure\n(properties, methods, constructor)"];
+    approve [label="User approves\nclass design?" shape=diamond];
+    generate [label="Generate .tlpp file\nwith namespace and class"];
+    checklist [label="Run migration checklist\n(migration-checklist.md)"];
+    validate [label="Validate compilation\nand caller compatibility"];
+
+    analyze -> identify;
+    identify -> map;
+    map -> approve;
+    approve -> generate [label="yes"];
+    approve -> map [label="no - revise"];
+    generate -> checklist;
+    checklist -> validate;
+}
+```
+
+1. **Analyze** the source `.prw` file to understand all functions, variables, and external dependencies
+2. **Identify** each User Function and Static Function, their parameters, and shared state
+3. **Map** functions to a class structure -- methods, properties, constructor parameters
+4. **User approves** the proposed class design before code generation
+5. **Generate** the `.tlpp` file with proper namespace, class definition, and method implementations
+6. **Run checklist** from `migration-checklist.md` to verify completeness
+7. **Validate** that the code compiles and all existing callers still work
+
+## Core Conversion Rules
+
+| ADVPL Construct | TLPP Equivalent | Notes |
+|----------------|-----------------|-------|
+| `#Include "TOTVS.CH"` | `#Include "tlpp-core.th"` | Use the TLPP-specific includes (`.th` files); `Protheus.ch` is obsolete. Do NOT add `using namespace tlpp.core`, `tlpp.rest`, or `tlpp.log` -- use the `.th` includes instead |
+| `User Function Name()` | `namespace custom.module.service; class NameService; method execute()` | Main entry point becomes the primary public method. See namespace conventions below |
+| `Static Function Helper()` | `method helper() as private` | Internal functions become private methods |
+| `Private cVar := "x"` | `data cVar as character` (class property) | Private variables become class-level data declarations |
+| `Public nGlobal` | Remove -- pass via constructor/parameters | Public variables must be eliminated entirely |
+| `Local aArray := {}` | Unchanged inside methods | Local variables remain as-is within method bodies |
+
+See `migration-rules.md` for the complete mapping reference covering preprocessor directives, database operations, error handling, and UI elements.
+
+## TLPP Naming Conventions (Official TOTVS Standard)
+
+Follow the official TOTVS naming conventions from TDN (https://tdn.totvs.com/pages/releaseview.action?pageId=633537898).
+
+### Namespaces
+
+All names must be **lowercase**, separated by **dots**, with **no underscores**.
+
+**For TOTVS product code:**
+```
+totvs.protheus.<segmento>.<agrupador/servico>
+```
+
+Available segments: agrobusiness, backoffice, construction, distribution, educational, financial, health, hospitality, legal, manufacturing, retail, services
+
+Examples:
+- `totvs.protheus.backoffice.customer`
+- `totvs.protheus.backoffice.supplier`
+- `totvs.protheus.financial.payment.receive`
+- `totvs.protheus.manufacturing.material.balance`
+
+Exceptions: Framework team uses `framework`, Protheus Engineering uses `software.engineering`.
+
+**For client customizations (most common in migrations):**
+```
+custom.<agrupador>.<servico>
+```
+
+Start with `custom.`, the rest is free. Examples:
+- `custom.cadastros.cliente`
+- `custom.relatorios.customizados`
+- `custom.faturamento.pedido`
+
+### File Naming
+
+**For TOTVS product:** `<segmento>.<agrupador/servico>.<funcionalidade>.tlpp`
+- Examples: `backoffice.tgv.contact.controller.tlpp`, `financial.payment.receive.tlpp`
+
+**For client customizations:** `custom.<agrupador>.<funcionalidade>.tlpp`
+- Examples: `custom.cadastros.cliente.tlpp`, `custom.ma030inc.tlpp`
+
+### Classes, Functions, and Methods
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Classes | **PascalCase** | `ContactsController`, `PedidoService` |
+| Functions | **camelCase** | `contactsController()`, `calcTotal()` |
+| Methods | **camelCase** | `validName()`, `processOrder()` |
+
+**No underscores** in any identifier.
+
+### Deciding the Namespace
+
+When migrating, ask the user if the code is:
+1. **TOTVS product code** -> use `totvs.protheus.<segmento>.<agrupador>`
+2. **Client customization** -> use `custom.<agrupador>.<servico>` (this is the most common case)
+
+If the user does not specify, default to `custom.<module>.<service>` pattern.
+
+## Before/After Example
+
+### Before (ADVPL Procedural) -- `CalcPed.prw`
+
+```advpl
+#Include "TOTVS.CH"
+#Include "TopConn.ch"
+
+/*/{Protheus.doc} CalcPed
+Calcula o total de um pedido de venda
+@type User Function
+@author Dev
+@since 01/01/2024
+@param cPedido, Caractere, Numero do pedido
+@return nTotal, Numerico, Valor total do pedido
+/*/
+User Function CalcPed(cPedido)
+    Local nTotal := 0
+    Private cAliasPed := "SC5"
+    Private cAliasItens := "SC6"
+
+    Local aArea := GetArea()
+
+    Begin Sequence
+
+        DbSelectArea(cAliasPed)
+        DbSetOrder(1)
+
+        If !DbSeek(xFilial(cAliasPed) + cPedido)
+            Conout("Pedido nao encontrado: " + cPedido)
+            Break
+        EndIf
+
+        nTotal := fCalcTotal(cPedido)
+
+    Recover Using oError
+        Conout("Erro em CalcPed: " + oError:Description)
+        nTotal := 0
+    End Sequence
+
+    RestArea(aArea)
+Return nTotal
+
+Static Function fCalcTotal(cPedido)
+    Local nSoma := 0
+
+    DbSelectArea(cAliasItens)
+    DbSetOrder(1)
+
+    DbSeek(xFilial(cAliasItens) + cPedido)
+    While !Eof() .And. SC6->C6_NUM == cPedido
+        nSoma += SC6->C6_VALOR * SC6->C6_QTDVEN
+        DbSkip()
+    EndDo
+
+Return nSoma
+```
+
+### After (TLPP Object-Oriented) -- `custom.faturamento.pedido.tlpp`
+
+```tlpp
+#Include "tlpp-core.th"
+
+namespace custom.faturamento.pedido
+
+class PedidoService
+
+    data cAliasPed   as character
+    data cAliasItens as character
+
+    public method new() as object
+    public method calcTotal(cPedido as character) as numeric
+    private method somaItens(cPedido as character) as numeric
+
+endclass
+
+method new() class PedidoService
+    ::cAliasPed   := "SC5"
+    ::cAliasItens := "SC6"
+return self
+
+method calcTotal(cPedido as character) class PedidoService
+    local nTotal := 0
+    local aArea  := GetArea()
+
+    begin sequence
+
+        DbSelectArea(::cAliasPed)
+        DbSetOrder(1)
+
+        if !DbSeek(xFilial(::cAliasPed) + cPedido)
+            FWLogMsg("WARN", , "PedidoService", "calcTotal", , , ;
+                "Pedido nao encontrado: " + cPedido)
+            break
+        endif
+
+        nTotal := ::somaItens(cPedido)
+
+    recover using oError
+        FWLogMsg("ERROR", , "PedidoService", "calcTotal", , , ;
+            "Erro: " + oError:Description)
+        nTotal := 0
+    end sequence
+
+    RestArea(aArea)
+return nTotal
+
+method somaItens(cPedido as character) class PedidoService
+    local nSoma := 0
+
+    DbSelectArea(::cAliasItens)
+    DbSetOrder(1)
+
+    DbSeek(xFilial(::cAliasItens) + cPedido)
+    while !Eof() .And. (::cAliasItens)->(C6_NUM) == cPedido
+        nSoma += (::cAliasItens)->(C6_VALOR) * (::cAliasItens)->(C6_QTDVEN)
+        DbSkip()
+    enddo
+
+return nSoma
+```
+
+### Backward Compatibility Wrapper -- `CalcPed.prw` (preserved)
+
+```advpl
+#Include "TOTVS.CH"
+
+/*/{Protheus.doc} CalcPed
+Wrapper de compatibilidade - delega para PedidoService (TLPP)
+@type User Function
+@author Dev
+@since 01/01/2024
+@param cPedido, Caractere, Numero do pedido
+@return nTotal, Numerico, Valor total do pedido
+/*/
+User Function CalcPed(cPedido)
+    Local oService := custom.faturamento.pedido.PedidoService():new()
+Return oService:calcTotal(cPedido)
+```
+
+## Key Migration Decisions
+
+| Decision | Guideline |
+|----------|-----------|
+| One class per file | Each `.tlpp` file should contain a single class with a clear responsibility |
+| Namespace = official TOTVS convention | For customizations use `custom.<agrupador>.<servico>` (e.g., `custom.faturamento.pedido`). For TOTVS product use `totvs.protheus.<segmento>.<agrupador>`. All lowercase, no underscores, separated by dots |
+| User Function preserved as wrapper | Keep the original `.prw` User Function as a thin wrapper that delegates to the new class |
+| Gradual migration | Migrate one function group at a time; wrappers ensure existing callers are not broken |
+| Constructor for shared state | Values that were previously `Private`/`Public` variables shared across functions should be passed through the constructor or set as class properties |
+| Logging over Conout | Prefer `FWLogMsg()` or `FWLogError()` over raw `Conout()` in TLPP classes |
+
+## Common Mistakes
+
+| Mistake | Consequence | Fix |
+|---------|-------------|-----|
+| Removing User Function without wrapper | Breaks all external callers (`u_FuncName`) | Always keep a `.prw` wrapper during migration |
+| Using `Private` variables inside methods | Variables leak to called methods unexpectedly | Convert to class `data` properties or `Local` variables |
+| Forgetting `::` prefix for class properties | References undefined local variable instead of property | Always use `::propertyName` inside methods |
+| Putting multiple classes in one `.tlpp` file | Hard to maintain, namespace confusion | One class per file |
+| Not preserving `GetArea()`/`RestArea()` | Database cursor state corrupted for callers | Always save and restore area in methods that access DB |
+| Skipping `xFilial()` after migration | Multi-branch queries return wrong data | Always use `xFilial(cAlias)` in `DbSeek` operations |
+| Ignoring Static variables used across functions | Shared state lost when functions become methods | Convert `Static` variables to class `data` properties |
+
+## References
+
+- `migration-rules.md` -- Complete mapping of all ADVPL constructs to TLPP equivalents
+- `migration-checklist.md` -- Step-by-step checklist for executing and validating a migration

package/skills/advpl-to-tlpp-migration/migration-checklist.md

@@ -0,0 +1,122 @@
+# ADVPL to TLPP Migration Checklist
+
+Use this checklist for every migration from procedural ADVPL (`.prw`) to object-oriented TLPP (`.tlpp`). Complete each section in order.
+
+---
+
+## 1. Pre-Migration Analysis
+
+Perform this analysis before writing any TLPP code.
+
+- [ ] Identify all `User Function` definitions in the source `.prw` file
+- [ ] Identify all `Static Function` definitions in the source `.prw` file
+- [ ] Map function call dependencies (which functions call which)
+- [ ] Identify `Private` variables shared across multiple functions
+- [ ] Identify `Public` variables and all locations where they are read/written
+- [ ] Identify `Static` file-level variables and their usage patterns
+- [ ] List all external callers of each `User Function` (other `.prw` files, menus, jobs, schedules)
+- [ ] Identify all database aliases used (`DbSelectArea`, `RecLock`, direct alias references)
+- [ ] Document all `#Include` directives (they will be replaced by TLPP `.th` includes: `tlpp-core.th`, `tlpp-rest.th`, etc.)
+- [ ] Identify any code blocks (`{|| ...}`) that reference `Private`/`Static` variables
+- [ ] Check for `MV_*` parameter usage (`GetMV`, `SuperGetMV`) that may need class-level access
+- [ ] Note any UI elements (dialogs, buttons, gets) that will need a separate View class
+
+---
+
+## 2. Migration Execution
+
+Create the TLPP class structure and convert all functions.
+
+### Namespace and File Setup
+
+- [ ] Define the namespace following TOTVS convention: `custom.<agrupador>.<servico>` for customizations or `totvs.protheus.<segmento>.<agrupador>` for product code (all lowercase, dots, no underscores)
+- [ ] Create the `.tlpp` file with one class per file, named following convention: `custom.<agrupador>.<funcionalidade>.tlpp`
+- [ ] Add `#Include "tlpp-core.th"` at the top of the file (and `tlpp-rest.th` if using REST annotations)
+
+### Class Skeleton
+
+- [ ] Define the class name using PascalCase with a purpose suffix (e.g., `PedidoService`, `ClienteRepository`)
+- [ ] Declare all `data` properties (converted from `Private`/`Static` variables) with `as <type>`
+- [ ] Declare all `public method` signatures (from `User Function` conversions)
+- [ ] Declare all `private method` signatures (from `Static Function` conversions)
+- [ ] Add `endclass` at the end of the class definition
+
+### Constructor
+
+- [ ] Create `method new()` that initializes all class properties
+- [ ] Move any values that were `Public` variables into constructor parameters
+- [ ] Set default values for properties that had default `Private` variable values
+- [ ] Return `self` from the constructor
+
+### Convert Functions to Methods
+
+- [ ] Convert each `User Function` to a `public method` with proper parameter typing (`as character`, `as numeric`, etc.)
+- [ ] Convert each `Static Function` to a `private method`
+- [ ] Replace all references to `Private` variables with `::propertyName`
+- [ ] Replace all calls to `Static Function Helper()` with `::helper()`
+- [ ] Ensure every method that accesses the database calls `GetArea()` at the start and `RestArea()` before returning
+- [ ] Replace `Conout()` logging with `FWLogMsg()` where appropriate
+- [ ] Verify that `xFilial(cAlias)` is used in all `DbSeek` operations
+
+### Update Includes (in the `.tlpp` file)
+
+- [ ] Replace ADVPL `.ch` includes with TLPP `.th` includes: `#Include "tlpp-core.th"` (main), `#Include "tlpp-rest.th"` (REST annotations), `#Include "tlpp-object.th"` (advanced objects)
+- [ ] Add the `namespace` declaration for the project (e.g., `namespace custom.faturamento.pedido`)
+- [ ] Do NOT add `using namespace tlpp.core`, `tlpp.log`, `tlpp.rest`, `tlpp.data`, etc. -- these are NOT needed; use the `.th` includes instead
+
+### Backward Compatibility Wrapper (`.prw` file — uses `#Include "TOTVS.CH"`)
+
+- [ ] Create or update the `.prw` wrapper file that preserves the original `User Function` name
+- [ ] The wrapper must instantiate the TLPP class and delegate to the appropriate method
+- [ ] Verify the wrapper passes all original parameters correctly
+- [ ] Verify the wrapper returns the same type as the original function
+
+---
+
+## 3. Post-Migration Validation
+
+Verify that the migration is complete and correct.
+
+### Compilation
+
+- [ ] The `.tlpp` file compiles without errors
+- [ ] The `.prw` wrapper file compiles without errors
+- [ ] No warnings related to undefined variables or methods
+
+### Functional Validation
+
+- [ ] All external callers (other functions, menus, jobs) work correctly through the wrapper
+- [ ] Database operations produce the same results as the original code
+- [ ] Record locking and unlocking (`RecLock` / `MsUnlock`) work correctly
+- [ ] Error handling (`Begin Sequence` / `Recover`) catches and reports errors correctly
+- [ ] Return values match the original function's return type and behavior
+
+### Code Quality
+
+- [ ] No `Private` or `Public` variable declarations remain in the `.tlpp` file
+- [ ] No leaked variables -- all variables are either `Local`, `data`, or `static data`
+- [ ] Class properties use correct Hungarian notation prefixes (`cName`, `nValue`, `lFlag`, `aList`, `oObj`)
+- [ ] Method names follow camelCase convention
+- [ ] Class name follows PascalCase convention
+- [ ] Namespace follows TOTVS convention (`custom.<agrupador>.<servico>` or `totvs.protheus.<segmento>.<agrupador>`)
+- [ ] One class per `.tlpp` file
+- [ ] All `GetArea()` calls have matching `RestArea()` calls (no area leaks)
+- [ ] Code blocks that reference class state use `self` explicitly when evaluated externally
+
+### Documentation
+
+- [ ] Class-level `Protheus.doc` comment block is present with `@type class`
+- [ ] Each public method has a `Protheus.doc` comment block with `@param` and `@return`
+- [ ] The wrapper `.prw` file documents that it delegates to the TLPP class
+
+---
+
+## Quick Reference: File Checklist per Migration
+
+For each `.prw` file migrated, you should end up with:
+
+| File | Purpose | Status |
+|------|---------|--------|
+| `ClassName.tlpp` | New TLPP class with all logic | - [ ] Created |
+| `OriginalName.prw` | Wrapper preserving `User Function` signature | - [ ] Updated |
+| Original `.prw` | Archived or removed after full rollout | - [ ] Handled |