@linkup-ai/abap-ai 0.1.0

package/dist/knowledge/abap/amdp.md

@@ -0,0 +1,273 @@
+# AMDP — ABAP Managed Database Procedures (HANA SQLScript)
+
+## Basic AMDP Method
+
+```abap
+CLASS zcl_order_amdp DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES if_amdp_marker_hdb.  " marks class as AMDP-enabled for HANA
+
+    TYPES: BEGIN OF ty_order_summary,
+             customer_id   TYPE kunnr,
+             order_count   TYPE i,
+             total_amount  TYPE netwr,
+             currency_code TYPE waers,
+           END OF ty_order_summary.
+
+    METHODS get_order_summary
+      IMPORTING VALUE(iv_min_amount) TYPE netwr
+      EXPORTING VALUE(et_result) TYPE STANDARD TABLE OF ty_order_summary.
+
+ENDCLASS.
+
+CLASS zcl_order_amdp IMPLEMENTATION.
+
+  METHOD get_order_summary BY DATABASE PROCEDURE FOR HDB
+    LANGUAGE SQLSCRIPT OPTIONS READ-ONLY
+    USING ztab_order.
+
+    et_result = SELECT customer_id,
+                       COUNT(*) AS order_count,
+                       SUM( total_amount ) AS total_amount,
+                       currency_code
+                  FROM ztab_order
+                  WHERE total_amount >= :iv_min_amount
+                  GROUP BY customer_id, currency_code
+                  ORDER BY total_amount DESC;
+
+  ENDMETHOD.
+
+ENDCLASS.
+```
+
+## AMDP Function (Table Function for CDS)
+
+```abap
+CLASS zcl_order_amdp DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES if_amdp_marker_hdb.
+
+    CLASS-METHODS get_ranked_orders
+      FOR TABLE FUNCTION ZTF_RankedOrders.
+ENDCLASS.
+
+CLASS zcl_order_amdp IMPLEMENTATION.
+
+  METHOD get_ranked_orders BY DATABASE FUNCTION FOR HDB
+    LANGUAGE SQLSCRIPT OPTIONS READ-ONLY
+    USING ztab_order ztab_customer.
+
+    RETURN SELECT o.order_id,
+                  o.customer_id,
+                  c.name AS customer_name,
+                  o.total_amount,
+                  o.currency_code,
+                  ROW_NUMBER() OVER (
+                    PARTITION BY o.customer_id
+                    ORDER BY o.total_amount DESC
+                  ) AS rank
+             FROM ztab_order AS o
+             INNER JOIN ztab_customer AS c
+               ON o.customer_id = c.customer_id;
+
+  ENDMETHOD.
+
+ENDCLASS.
+```
+
+### CDS Table Function
+
+```abap
+@EndUserText.label: 'Ranked Orders'
+define table function ZTF_RankedOrders
+returns
+{
+  key order_id     : abap.numc(10);
+      customer_id  : kunnr;
+      customer_name : abap.char(40);
+      total_amount : abap.curr(17,2);
+      currency_code : abap.cuky(5);
+      rank         : abap.int4;
+}
+implemented by method zcl_order_amdp=>get_ranked_orders;
+```
+
+### Consume in CDS View
+
+```abap
+define view entity ZI_RankedOrders as select from ZTF_RankedOrders
+{
+  key order_id    as OrderID,
+      customer_id as CustomerID,
+      customer_name as CustomerName,
+      @Semantics.amount.currencyCode: 'CurrencyCode'
+      total_amount as TotalAmount,
+      currency_code as CurrencyCode,
+      rank        as Rank
+}
+where rank <= 10
+```
+
+## SQLScript Patterns
+
+### Variables and Control Flow
+
+```sql
+DECLARE lv_count INTEGER;
+DECLARE lv_threshold DECIMAL(17,2) := 1000.00;
+
+SELECT COUNT(*) INTO lv_count FROM ztab_order;
+
+IF lv_count > 0 THEN
+  -- process
+ELSEIF lv_count = 0 THEN
+  -- empty
+END IF;
+
+WHILE lv_count > 0 DO
+  lv_count := lv_count - 1;
+END WHILE;
+
+FOR i IN 1..10 DO
+  -- loop body
+END FOR;
+```
+
+### Temporary Tables (Table Variables)
+
+```sql
+lt_filtered = SELECT * FROM ztab_order WHERE status = 'O';
+
+lt_enriched = SELECT f.order_id,
+                     f.customer_id,
+                     c.name AS customer_name,
+                     f.total_amount
+                FROM :lt_filtered AS f
+                INNER JOIN ztab_customer AS c
+                  ON f.customer_id = c.customer_id;
+
+et_result = SELECT * FROM :lt_enriched WHERE total_amount > :iv_min;
+```
+
+### Window Functions
+
+```sql
+et_result = SELECT order_id,
+                   customer_id,
+                   total_amount,
+                   ROW_NUMBER() OVER (ORDER BY total_amount DESC) AS row_num,
+                   RANK() OVER (ORDER BY total_amount DESC) AS ranking,
+                   SUM(total_amount) OVER () AS grand_total,
+                   SUM(total_amount) OVER (PARTITION BY customer_id) AS customer_total,
+                   AVG(total_amount) OVER (
+                     ORDER BY created_at
+                     ROWS BETWEEN 2 PRECEDING AND CURRENT ROW
+                   ) AS moving_avg_3
+              FROM ztab_order;
+```
+
+### String Functions
+
+```sql
+CONCAT(first_name, ' ', last_name)
+UPPER(name)
+LOWER(name)
+LENGTH(description)
+SUBSTR(text, 1, 10)
+REPLACE(phone, '-', '')
+LPAD(order_id, 10, '0')
+TRIM(BOTH ' ' FROM name)
+LOCATE(email, '@')          -- position of @ (0 if not found)
+```
+
+### Date Functions
+
+```sql
+CURRENT_DATE
+CURRENT_TIMESTAMP
+ADD_DAYS(order_date, 7)
+ADD_MONTHS(order_date, 1)
+DAYS_BETWEEN(start_date, end_date)
+EXTRACT(YEAR FROM order_date)
+TO_DATE('2026-03-15', 'YYYY-MM-DD')
+```
+
+## AMDP with OUT Parameter (Scalar)
+
+```abap
+METHODS get_order_count
+  IMPORTING VALUE(iv_status) TYPE char1
+  EXPORTING VALUE(ev_count) TYPE i.
+
+METHOD get_order_count BY DATABASE PROCEDURE FOR HDB
+  LANGUAGE SQLSCRIPT OPTIONS READ-ONLY
+  USING ztab_order.
+
+  SELECT COUNT(*) INTO ev_count
+    FROM ztab_order
+    WHERE status = :iv_status;
+
+ENDMETHOD.
+```
+
+## AMDP with Multiple Results
+
+```abap
+METHODS get_order_report
+  IMPORTING VALUE(iv_year) TYPE numc4
+  EXPORTING VALUE(et_summary) TYPE tt_summary
+            VALUE(et_detail) TYPE tt_detail.
+
+METHOD get_order_report BY DATABASE PROCEDURE FOR HDB
+  LANGUAGE SQLSCRIPT OPTIONS READ-ONLY
+  USING ztab_order ztab_order_item.
+
+  et_summary = SELECT customer_id, COUNT(*) AS cnt, SUM(total_amount) AS total
+                 FROM ztab_order
+                 WHERE EXTRACT(YEAR FROM created_at) = :iv_year
+                 GROUP BY customer_id;
+
+  et_detail = SELECT o.order_id, o.customer_id, i.material, i.quantity, i.amount
+                FROM ztab_order AS o
+                INNER JOIN ztab_order_item AS i ON o.order_id = i.order_id
+                WHERE EXTRACT(YEAR FROM o.created_at) = :iv_year;
+
+ENDMETHOD.
+```
+
+## Calling AMDP from ABAP
+
+```abap
+DATA(lo_amdp) = NEW zcl_order_amdp( ).
+
+lo_amdp->get_order_summary(
+  EXPORTING iv_min_amount = 1000
+  IMPORTING et_result     = DATA(lt_summary) ).
+
+LOOP AT lt_summary INTO DATA(ls_sum).
+  " process
+ENDLOOP.
+```
+
+## Rules
+- Class MUST implement `if_amdp_marker_hdb`
+- Method signature: `BY DATABASE PROCEDURE FOR HDB LANGUAGE SQLSCRIPT`
+- `OPTIONS READ-ONLY` for read operations (enables parallel execution)
+- `USING <table1> <table2>` — list ALL DB tables accessed (mandatory)
+- Table function methods must be `CLASS-METHODS` (static)
+- Parameters: always `VALUE(...)` (pass by value required)
+- Use `:param_name` to reference ABAP parameters in SQLScript
+- Use `:lt_variable` to reference table variables
+- AMDP runs on HANA only — not available on other databases
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| Missing `if_amdp_marker_hdb` interface | Required for all AMDP classes |
+| Missing `USING` clause for accessed tables | List every table accessed |
+| `OPTIONS READ-ONLY` on methods that modify data | Remove for write operations |
+| Complex logic that could be CDS | Use CDS for simple joins/aggregations |
+| AMDP for simple SELECT | Use ABAP SQL — AMDP only for HANA-specific features |
+| Instance method for table function | Must be `CLASS-METHODS` (static) |
+| Passing internal table by reference | AMDP requires `VALUE(...)` |
+| Using AMDP on non-HANA system | AMDP is HANA-only |

package/dist/knowledge/abap/clean-code.md

@@ -0,0 +1,293 @@
+# ABAP Clean Code — naming, conventions, structure, readability
+
+## Naming Conventions — Prefixes
+
+### Objects (Repository)
+
+| Prefix | Object Type | Example |
+|--------|-------------|---------|
+| `Z` or `Y` | Customer namespace | `ZORDER`, `YHR_PAYROLL` |
+| `ZCL_` | Class | `ZCL_ORDER_PROCESSOR` |
+| `ZIF_` | Interface | `ZIF_ORDER_SERVICE` |
+| `ZCX_` | Exception class | `ZCX_ORDER_ERROR` |
+| `ZCM_` | RAP message class (behavior) | `ZCM_ORDER` |
+| `ZBP_` | RAP behavior pool | `ZBP_I_ORDER` |
+| `ZBP_BX_` | RAP behavior extension pool | `ZBP_BX_I_SALESORDER` |
+| `ZI_` | CDS Interface view (RAP) | `ZI_ORDER` |
+| `ZC_` | CDS Projection/Consumption view | `ZC_ORDER` |
+| `ZA_` | CDS Abstract entity | `ZA_REJECT_PARAMS` |
+| `ZR_` | CDS Restricted reuse view | `ZR_ORDER_BASE` |
+| `ZUI_` | Service Definition | `ZUI_ORDER` |
+| `ZTAB_` or `Z` | Database table | `ZTAB_ORDER` |
+| `ZS_` | Structure type (DDIC) | `ZS_ORDER_ITEM` |
+| `ZTT_` | Table type (DDIC) | `ZTT_ORDER_ITEMS` |
+| `ZDOM_` | Domain | `ZDOM_ORDER_STATUS` |
+| `ZDTEL_` | Data element | `ZDTEL_ORDER_ID` |
+
+### Variables (Local)
+
+| Prefix | Scope | Example |
+|--------|-------|---------|
+| `lv_` | Local variable | `lv_order_id` |
+| `lt_` | Local table | `lt_orders` |
+| `ls_` | Local structure | `ls_order` |
+| `lr_` | Local reference | `lr_data` |
+| `lo_` | Local object reference | `lo_processor` |
+| `lx_` | Local exception reference | `lx_error` |
+
+### Variables (Method Parameters)
+
+| Prefix | Direction | Example |
+|--------|-----------|---------|
+| `iv_` | IMPORTING value | `iv_order_id` |
+| `ir_` | IMPORTING reference | `ir_data` |
+| `io_` | IMPORTING object | `io_service` |
+| `ev_` | EXPORTING value | `ev_result` |
+| `et_` | EXPORTING table | `et_items` |
+| `es_` | EXPORTING structure | `es_header` |
+| `cv_` | CHANGING value | `cv_counter` |
+| `ct_` | CHANGING table | `ct_items` |
+| `rv_` | RETURNING value | `rv_success` |
+| `rt_` | RETURNING table | `rt_items` |
+| `rs_` | RETURNING structure | `rs_result` |
+| `ro_` | RETURNING object | `ro_instance` |
+
+### Variables (Class Attributes)
+
+| Prefix | Scope | Example |
+|--------|-------|---------|
+| `mv_` | Instance attribute (value) | `mv_order_id` |
+| `mt_` | Instance attribute (table) | `mt_items` |
+| `ms_` | Instance attribute (structure) | `ms_config` |
+| `mo_` | Instance attribute (object) | `mo_logger` |
+| `gv_` | Static attribute (value) | `gv_counter` |
+| `gt_` | Static attribute (table) | `gt_cache` |
+| `go_` | Static attribute (object) | `go_singleton` |
+
+### Constants
+
+| Prefix | Example |
+|--------|---------|
+| `c_` or `mc_` | `c_status_open`, `mc_max_retries` |
+| `gc_` | Static constant `gc_version` |
+
+### Field Symbols and Data References
+
+| Prefix | Example |
+|--------|---------|
+| `<ls_>` or `<fs_>` | `<ls_order>`, `<fs_item>` |
+| `lr_` | Data reference `lr_data` |
+
+## CDS Naming Conventions
+
+```
+Interface views:     ZI_OrderHeader, ZI_OrderItem
+Projection views:    ZC_OrderHeader, ZC_OrderItem
+Abstract entities:   ZA_RejectParams, ZA_OrderResult
+Service Definition:  ZUI_ORDER
+Service Binding:     ZUI_ORDER_O4 (V4), ZUI_ORDER_O2 (V2)
+Metadata Extension:  ZC_OrderHeader (same name as projection)
+Access Control:      ZI_OrderHeader (same name as CDS view)
+
+Field names:         CamelCase in CDS → OrderID, CustomerName, TotalAmount
+Association prefix:  _Customer, _Items, _Currency (underscore prefix)
+```
+
+## Method Design
+
+```abap
+" GOOD: focused, single responsibility, < 30 lines
+METHOD validate_customer.
+  IF iv_customer_id IS INITIAL.
+    RAISE EXCEPTION TYPE zcx_order_error
+      EXPORTING textid = zcx_order_error=>customer_required.
+  ENDIF.
+  IF NOT customer_exists( iv_customer_id ).
+    RAISE EXCEPTION TYPE zcx_order_error
+      EXPORTING textid         = zcx_order_error=>customer_not_found
+                mv_customer_id = iv_customer_id.
+  ENDIF.
+ENDMETHOD.
+
+" BAD: doing too much
+METHOD process_order.
+  " 200 lines: validates, calculates, saves, sends email, logs...
+ENDMETHOD.
+```
+
+```abap
+" Prefer RETURNING over EXPORTING for single outputs (enables chaining)
+" GOOD:
+METHODS get_status RETURNING VALUE(rv_status) TYPE char1.
+DATA(lv_status) = lo_order->get_status( ).
+
+" AVOID for single output:
+METHODS get_status EXPORTING ev_status TYPE char1.
+lo_order->get_status( IMPORTING ev_status = DATA(lv_status) ).
+```
+
+## Boolean Handling
+
+```abap
+" Use abap_bool / abap_true / abap_false
+DATA lv_valid TYPE abap_bool.
+lv_valid = abap_true.
+
+IF lv_valid = abap_true.
+" Or simply:
+IF lv_valid IS NOT INITIAL.
+
+" AVOID:
+DATA lv_flag TYPE c LENGTH 1 VALUE 'X'.
+IF lv_flag = 'X'.
+```
+
+## Modern ABAP Patterns
+
+```abap
+" Inline declarations — ALWAYS for local variables
+DATA(lv_count) = lines( lt_items ).
+DATA(lo_proc) = NEW zcl_processor( ).
+LOOP AT lt_items ASSIGNING FIELD-SYMBOL(<ls_item>).
+
+" NOT:
+DATA lv_count TYPE i.
+lv_count = lines( lt_items ).
+DATA lo_proc TYPE REF TO zcl_processor.
+CREATE OBJECT lo_proc.
+
+" Constructor expressions over imperative
+DATA(lt_filtered) = FILTER #( lt_items WHERE status = 'A' ).
+DATA(lv_label) = COND string( WHEN lv_type = 'A' THEN 'Active' ELSE 'Other' ).
+DATA(ls_copy) = CORRESPONDING zs_target( ls_source ).
+
+" NOT:
+LOOP AT lt_items INTO ls_item WHERE status = 'A'.
+  APPEND ls_item TO lt_filtered.
+ENDLOOP.
+
+" String templates over CONCATENATE
+DATA(lv_msg) = |Order { lv_id } for { lv_customer }|.
+" NOT:
+CONCATENATE 'Order' lv_id 'for' lv_customer INTO lv_msg SEPARATED BY space.
+```
+
+## Error Handling
+
+```abap
+" Specific exceptions, never cx_root
+TRY.
+    lo_service->process( iv_data ).
+  CATCH zcx_order_error INTO DATA(lx_order).
+    " Handle business error
+  CATCH cx_sy_move_cast_error INTO DATA(lx_cast).
+    " Handle technical error
+ENDTRY.
+
+" Never empty CATCH
+" BAD:
+TRY.
+    lo_service->process( ).
+  CATCH cx_root.  " Swallows everything silently
+ENDTRY.
+```
+
+## Class Structure
+
+```abap
+CLASS zcl_order_service DEFINITION PUBLIC FINAL CREATE PUBLIC.
+  PUBLIC SECTION.
+    " 1. Interfaces
+    INTERFACES zif_order_service.
+
+    " 2. Types and constants
+    TYPES ty_order_id TYPE numc10.
+    CONSTANTS c_max_items TYPE i VALUE 999.
+
+    " 3. Constructor
+    METHODS constructor IMPORTING io_repo TYPE REF TO zif_order_repo.
+
+    " 4. Public methods (business API)
+    METHODS create_order
+      IMPORTING is_order TYPE zs_order_data
+      RETURNING VALUE(rv_id) TYPE ty_order_id
+      RAISING   zcx_order_error.
+
+  PRIVATE SECTION.
+    " 5. Instance attributes
+    DATA mo_repo TYPE REF TO zif_order_repo.
+
+    " 6. Private methods (internal helpers)
+    METHODS validate IMPORTING is_order TYPE zs_order_data RAISING zcx_order_error.
+    METHODS calculate_total IMPORTING it_items TYPE ztt_items RETURNING VALUE(rv_total) TYPE netwr.
+ENDCLASS.
+```
+
+## RAP Naming
+
+```abap
+" Handler methods — match BDEF names
+METHODS validateDates FOR VALIDATE ON SAVE IMPORTING keys FOR Travel~validateDates.
+METHODS setTravelID FOR DETERMINE ON MODIFY IMPORTING keys FOR Travel~setTravelID.
+METHODS acceptTravel FOR MODIFY IMPORTING keys FOR ACTION Travel~acceptTravel.
+METHODS get_instance_features FOR INSTANCE FEATURES IMPORTING keys ... FOR Travel RESULT result.
+METHODS get_global_authorizations FOR GLOBAL AUTHORIZATION IMPORTING REQUEST ... FOR Travel RESULT result.
+
+" Local handler class naming
+CLASS lhc_travel DEFINITION INHERITING FROM cl_abap_behavior_handler.
+" lhc_ = local handler class
+" lsc_ = local saver class
+
+CLASS lsc_travel DEFINITION INHERITING FROM cl_abap_behavior_saver.
+```
+
+## Comments
+
+```abap
+" Comment WHAT, not HOW (code should be self-documenting)
+
+" GOOD:
+" Check credit limit before order confirmation
+IF ls_order-total > get_credit_limit( ls_order-customer ).
+
+" BAD:
+" If total is greater than credit limit
+IF ls_order-total > get_credit_limit( ls_order-customer ).
+
+" GOOD: explain WHY for non-obvious decisions
+" RFC module returns status in legacy format (1=open, 2=closed)
+" Must map to our domain values
+DATA(lv_status) = SWITCH #( lv_rfc_status WHEN 1 THEN 'O' WHEN 2 THEN 'C' ).
+
+" No comments needed for self-evident code:
+DATA(lv_total) = REDUCE netwr( INIT s = 0 FOR wa IN lt_items NEXT s = s + wa-amount ).
+```
+
+## Rules
+- BEFORE modifying existing objects, check version history (abap_object_versions) to verify alignment with PRD and detect pending transports from other developers
+- ALWAYS use Hungarian notation prefixes (lv_, lt_, iv_, mv_, etc.)
+- ALWAYS use `FINAL` on classes unless inheritance is explicitly needed
+- ALWAYS use inline declarations: `DATA( )`, `FIELD-SYMBOL( )`
+- ALWAYS use constructor expressions over imperative statements
+- ALWAYS use string templates `| |` over CONCATENATE
+- Methods: max ~30 lines, single responsibility
+- Prefer RETURNING over EXPORTING for single output
+- Prefer interfaces over concrete class references (dependency injection)
+- Use `abap_bool` / `abap_true` / `abap_false` for booleans
+- CDS: CamelCase fields, _Underscore associations
+
+## Anti-Patterns
+| Anti-Pattern | Correct |
+|---|---|
+| `DATA lv_x TYPE string. lv_x = 'hello'.` | `DATA(lv_x) = 'hello'.` |
+| `CREATE OBJECT lo_ref TYPE zcl_class` | `DATA(lo_ref) = NEW zcl_class( )` |
+| `MOVE-CORRESPONDING src TO tgt` | `tgt = CORRESPONDING #( src )` |
+| `CONCATENATE a b INTO c` | `c = \|{ a }{ b }\|` |
+| `IF lv_flag = 'X'` | `IF lv_flag = abap_true` |
+| Variable name `lv_x`, `lv_tmp`, `lv_data` | Descriptive: `lv_order_status`, `lv_total_amount` |
+| Method with 200+ lines | Split into focused helper methods |
+| Public attributes modified externally | Private attributes + getter/setter methods |
+| `CATCH cx_root` silently | Catch specific exceptions, always handle |
+| Comments describing WHAT code does | Comment WHY for non-obvious decisions |
+| `DATA lo_ref TYPE REF TO zcl_concrete` | `DATA lo_ref TYPE REF TO zif_interface` |
+| Class without FINAL | Add FINAL unless subclassing is explicitly needed |