abapgit-agent 1.6.0 → 1.7.0

package/abap/guidelines/00_index.md

@@ -14,6 +14,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
 | `06_objects.md` | Object Naming Conventions |
 | `07_json.md` | JSON Handling |
 | `08_abapgit.md` | abapGit XML Metadata Templates |
+| `09_unit_testable_code.md` | Unit Testable Code Guidelines (Dependency Injection) |
 
 ## Usage
 

package/abap/guidelines/01_sql.md

@@ -1,7 +1,16 @@
 # ABAP SQL Best Practices
 
+**Searchable keywords**: SELECT, FROM, WHERE, ABAP SQL, Open SQL, host variable, @ prefix, range table, INTO, UP TO, OFFSET, GROUP BY, JOIN
+
 When writing ABAP SQL (Open SQL) queries, follow these rules:
 
+## TOPICS IN THIS FILE
+1. Host Variables (@ prefix) - line 5
+2. Range Tables (IN clause) - line 17
+3. SELECT Clause Order - line 35
+4. Fixed Point Arithmetic - line 52
+5. Field Separation - line 62
+
 ## 1. Host Variables - Use @ Prefix
 
 Use `@` prefix for host variables in ABAP SQL:
@@ -70,3 +79,10 @@ SELECT object, obj_name FROM tadir ...
 " Wrong - missing comma
 SELECT object obj_name FROM tadir ...
 ```
+
+---
+
+## See Also
+- **Constructor Expressions** (05_classes.md) - for VALUE #(), FILTER, FOR loops
+- **Internal Tables** - for filtering and iteration patterns
+- **abapGit** (08_abapgit.md) - for XML metadata templates

package/abap/guidelines/02_exceptions.md

@@ -1,5 +1,15 @@
 # Exception Handling - Classical vs Class-Based
 
+**Searchable keywords**: exception, RAISING, TRY, CATCH, cx_static_check, cx_dynamic_check, EXCEPTIONS, sy-subrc, class-based exception, classical exception
+
+## TOPICS IN THIS FILE
+1. Quick Identification - line 5
+2. Classical Exceptions - line 12
+3. Class-Based Exceptions - line 25
+4. Method Signatures - line 50
+5. Best Practices - line 80
+6. Interface vs Class Methods - line 118
+
 ABAP has two exception handling mechanisms. Using the wrong one causes silent failures.
 
 ## Quick Identification
@@ -106,3 +116,85 @@ Or search the cheat sheets:
 ```bash
 abapgit-agent ref --topic exceptions
 ```
+
+## Interface vs Class Methods
+
+### Interface Methods
+
+Cannot add RAISING clause in the implementing class. Options:
+
+1. Add RAISING to interface definition
+2. Use TRY-CATCH in the implementation
+
+```abap
+" Interface definition - can add RAISING here
+INTERFACE zif_example.
+  methods execute
+    importing is_param type data optional
+    returning value(rv_result) type string
+    raising cx_static_check.
+ENDINTERFACE.
+
+" Implementation - CANNOT add RAISING here
+CLASS zcl_example DEFINITION.
+  INTERFACES zif_example.
+ENDCLASS.
+
+CLASS zcl_example IMPLEMENTATION.
+  METHOD zif_example~execute.
+    " Must handle cx_static_check here with TRY-CATCH
+    " or declare it in interface, not here
+  ENDMETHOD.
+ENDCLASS.
+```
+
+### Class Methods
+
+Can add RAISING clause to declare exceptions, allowing caller to handle in one place:
+
+```abap
+" Class method with RAISING clause
+METHODS process_data
+  importing iv_data type string
+  returning value(rv_result) type string
+  raising cx_static_check.
+
+" Caller can handle in one place
+TRY.
+    lv_result = lo_obj->process_data( iv_data = 'test' ).
+  CATCH cx_static_check.
+    " Handle exception
+ENDTRY.
+```
+
+### When to Use Each
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Multiple callers need to handle exception | Add RAISING to method definition |
+| Exception should be handled internally | Use TRY-CATCH in implementation |
+| Interface method | Add RAISING to interface, or use TRY-CATCH in class |
+
+### RAISING Clause in Method Calls
+
+The `RAISING` clause **cannot be used in method call statements**. It can only be used in method definitions.
+
+```abap
+" WRONG - syntax error
+lo_handler->read( ... ) RAISING cx_dd_ddl_check.
+
+" CORRECT - use TRY-CATCH
+TRY.
+    lo_handler->read( ... ).
+  CATCH cx_dd_ddl_check.
+    " Handle error
+ENDTRY.
+```
+
+**Correct usage in method definitions:**
+```abap
+" Interface/Class method definition
+METHODS read
+  IMPORTING iv_name TYPE string
+  RAISING   cx_static_check.
+``` |

package/abap/guidelines/03_testing.md

@@ -1,5 +1,15 @@
 # Unit Testing
 
+**Searchable keywords**: unit test, AUnit, test class, cl_abap_unit_assert, FOR TESTING, setup, teardown, RISK LEVEL, DURATION, CDS test double, CL_CDS_TEST_ENVIRONMENT
+
+## TOPICS IN THIS FILE
+1. Local Test Classes - line 3
+2. File Structure - line 5
+3. Required Elements - line 16
+4. Naming Conventions - line 48
+5. CDS Test Doubles - line 94
+6. CDS with Aggregations - line 178
+
 ## Unit Testing with Local Test Classes
 
 ### File Structure
@@ -69,6 +79,25 @@ Examples of compliant names:
 - `test_exec_files` (16 chars)
 - `test_interface` (15 chars)
 
+### Test Methods and RAISING Clause
+
+If a test method calls methods that raise exceptions, add `RAISING` to the method definition:
+
+```abap
+" CORRECT - declare that method can raise exceptions
+METHODS test_validate_ddls FOR TESTING RAISING cx_static_check.
+METHODS test_read_data FOR TESTING RAISING cx_dd_ddl_check.
+
+" Then implement with TRY-CATCH if needed
+METHOD test_validate_ddls.
+  TRY.
+      mo_cut->some_method( ).
+    CATCH cx_static_check.
+      " Handle exception
+  ENDTRY.
+ENDMETHOD.
+```
+
 ### Common Assertions
 
 ```abap
@@ -250,3 +279,10 @@ ENDMETHOD.
 abapgit-agent ref "cl_cds_test_environment"
 abapgit-agent ref --topic unit-tests
 ```
+
+---
+
+## See Also
+- **CDS Views** (04_cds.md) - for CDS view definitions and syntax
+- **abapGit** (08_abapgit.md) - for WITH_UNIT_TESTS in XML metadata
+- **ABAP SQL** (01_sql.md) - for SELECT statements in tests

package/abap/guidelines/04_cds.md

@@ -1,5 +1,14 @@
 # Creating CDS Views
 
+**Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption
+
+## TOPICS IN THIS FILE
+1. File Naming - line 7
+2. DDL Source (.ddls.asddls) - line 18
+3. Annotations - line 50
+4. Associations - line 75
+5. CDS Test Doubles - see 03_testing.md
+
 ## Creating CDS Views (DDLS)
 
 CDS views (Data Definition Language Source) require specific file naming and structure for abapGit.
@@ -118,3 +127,10 @@ When working with CDS view syntax (arithmetic, built-in functions, aggregations,
    - `zdemo_abap_cds_ve_assoc.ddls.asddls` - Associations
 
 **Note**: This requires `abap-cheat-sheets` to be in the reference folder (configured in `.abapGitAgent`).
+
+---
+
+## See Also
+- **Unit Testing** (03_testing.md) - for CDS Test Double Framework
+- **abapGit** (08_abapgit.md) - for CDS XML metadata templates
+- **ABAP SQL** (01_sql.md) - for SQL functions used in CDS

package/abap/guidelines/05_classes.md

@@ -1,5 +1,16 @@
 # ABAP Classes and Objects
 
+**Searchable keywords**: CLASS, DEFINITION, PUBLIC, CREATE OBJECT, NEW, METHOD, INTERFACES, inheritance, FINAL, ABSTRACT
+
+## TOPICS IN THIS FILE
+1. Class Definition (PUBLIC) - line 3
+2. Constructor - line 20
+3. Interfaces - line 35
+4. Inline Declaration - line 50
+5. Abstract Methods - line 99
+6. FINAL Class Limitation - line 117
+7. Working with TYPE any - line 135
+
 ## ABAP Class Definition - Must Use PUBLIC
 
 **CRITICAL**: Global ABAP classes MUST use `PUBLIC` in the class definition:
@@ -48,3 +59,111 @@ ENDCLASS.
 
 **Wrong**: `METHOD do_something.` - parameter `iv_param` will be unknown
 **Correct**: `METHOD zif_my_interface~do_something.` - parameters recognized
+
+## Use Interface Type for References
+
+When a class implements an interface, use the **interface type** instead of the class type for references:
+
+```abap
+" Interface definition
+INTERFACE zif_my_interface PUBLIC.
+  METHODS do_something RETURNING VALUE(rv_result) TYPE string.
+ENDINTERFACE.
+
+" Class implements interface
+CLASS zcl_my_class DEFINITION PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES zif_my_interface.
+    CLASS-METHODS get_instance RETURNING VALUE(ro_instance) TYPE REF TO zif_my_interface.
+ENDCLASS.
+
+" Caller - use interface type, not class type
+CLASS zcl_consumer DEFINITION PUBLIC.
+  PRIVATE SECTION.
+    DATA mo_instance TYPE REF TO zif_my_interface.  " <- Use interface type
+ENDCLASS.
+
+METHOD zcl_consumer->do_something.
+  mo_instance = zcl_my_class=>get_instance( ).
+
+  " Call without interface prefix - cleaner code
+  DATA(lv_result) = mo_instance->do_something( ).
+ENDMETHOD.
+```
+
+**Benefits:**
+- Cleaner code: `mo_instance->method( )` instead of `mo_instance->zif_my_interface~method( )`
+- Flexibility: Can swap implementation class without changing caller (dependency inversion)
+- Consistency: All callers use the same interface type
+
+**Key rule:** Always use `REF TO zif_xxx` not `REF TO zcl_xxx` for instance variables and parameters.
+
+## Abstract Methods
+
+The ABSTRACT keyword must come immediately after the method name:
+
+```abap
+" ✅ Correct - ABSTRACT right after method name
+METHODS get_name ABSTRACT
+  RETURNING VALUE(rv_name) TYPE string.
+
+" ❌ Wrong - ABSTRACT after parameters (syntax error)
+METHODS get_name
+  RETURNING VALUE(rv_name) TYPE string
+  ABSTRACT.
+```
+
+## FINAL Class Limitation
+
+A FINAL class cannot have abstract methods. Use plain REDEFINITION instead:
+
+```abap
+" ❌ Wrong in FINAL class - syntax error
+CLASS zcl_my_class DEFINITION PUBLIC FINAL.
+  METHODS parse_request ABSTRACT REDEFINITION.
+ENDCLASS.
+
+" ✅ Correct in FINAL class - use REDEFINITION only
+CLASS zcl_my_class DEFINITION PUBLIC FINAL.
+  METHODS parse_request REDEFINITION.
+ENDCLASS.
+```
+
+## Working with TYPE any
+
+TYPE any cannot be used with CREATE DATA. When a base class defines parameters with TYPE any, use a typed local variable in the subclass:
+
+```abap
+" Base class defines:
+CLASS zcl_base DEFINITION PUBLIC ABSTRACT.
+  PROTECTED SECTION.
+    METHODS parse_request
+      IMPORTING iv_json TYPE string
+      EXPORTING es_request TYPE any.
+ENDCLASS.
+
+" Subclass implementation:
+CLASS zcl_subclass DEFINITION PUBLIC FINAL.
+  INHERITING FROM zcl_base.
+  PROTECTED SECTION.
+    METHODS parse_request REDEFINITION.
+ENDCLASS.
+
+CLASS zcl_subclass IMPLEMENTATION.
+  METHOD parse_request.
+    " Use typed local variable
+    DATA: ls_request TYPE ty_my_params.
+
+    /ui2/cl_json=>deserialize(
+      EXPORTING json = iv_json
+      CHANGING data = ls_request ).
+
+    es_request = ls_request.  " Assign typed to generic
+  ENDMETHOD.
+ENDCLASS.
+```
+
+**Key points:**
+- Declare a local variable with the concrete type
+- Deserialize JSON into the typed local variable
+- Assign to the generic TYPE any parameter

package/abap/guidelines/06_objects.md

@@ -1,103 +1,63 @@
-# ABAP Objects
+# ABAP Object Naming Conventions
 
-## Creating New ABAP Objects - XML Metadata Required
+**Searchable keywords**: naming convention, Z prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS
 
-**CRITICAL CHECKLIST - Never Forget!**
+## TOPICS IN THIS FILE
+1. Naming Conventions
+2. ABAP Object Types
+3. XML Metadata (see guidelines/08_abapgit.md)
 
-When creating ANY new ABAP object file, you MUST also create its XML metadata file:
+## Naming Conventions
 
-| ABAP File | Required XML File |
-|-----------|------------------|
-| `zcl_my_class.clas.abap` | `zcl_my_class.clas.xml` |
-| `zif_my_intf.intf.abap` | `zif_my_intf.intf.xml` |
+Use `Z_` or `Y_` prefix for custom objects:
+
+| Object Type | Prefix | Example |
+|-------------|--------|---------|
+| Class | ZCL_ | ZCL_MY_CLASS |
+| Interface | ZIF_ | ZIF_MY_INTERFACE |
+| Program | Z | ZMY_PROGRAM |
+| Package | $ | $MY_PACKAGE |
+| Table | Z | ZMY_TABLE |
+| CDS View | ZC | ZC_MY_VIEW |
+| CDS Entity | ZE | ZE_MY_ENTITY |
+| Data Element | Z | ZMY_ELEMENT |
+| Structure | Z | ZMY_STRUCTURE |
+| Table Type | Z | ZMY_TABLE_TYPE |
 
-**Without XML files**, abapGit will NOT recognize the objects during pull, and they won't be activated.
+## ABAP Object Types
 
-### XML Metadata Format for CLAS
+Common object types in this project:
 
-For `zcl_abgagt_util.clas.abap`, create `zcl_abgagt_util.clas.xml`:
+| Type | Description | File Suffix |
+|------|-------------|-------------|
+| CLAS | Classes | .clas.abap |
+| PROG | Programs | .prog.abap |
+| FUGR | Function Groups | .fugr.abap |
+| INTF | Interfaces | .intf.abap |
+| TABL | Tables | .tabl.abap |
+| STRU | Structures | .stru.abap |
+| DTEL | Data Elements | .dtel.abap |
+| TTYP | Table Types | .ttyp.abap |
+| DDLS | CDS Views | .ddls.asddls |
+| DDLX | CDS Entities | .ddlx.asddlx |
 
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<abapGit version="v1.0.0" serializer="LCL_OBJECT_CLAS" serializer_version="v1.0.0">
- <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
-  <asx:values>
-   <VSEOCLASS>
-    <CLSNAME>ZCL_ABGAGT_UTIL</CLSNAME>
-    <LANGU>E</LANGU>
-    <DESCRIPT>Description</DESCRIPT>
-    <EXPOSURE>2</EXPOSURE>
-    <STATE>1</STATE>
-    <UNICODE>X</UNICODE>
-   </VSEOCLASS>
-  </asx:values>
- </asx:abap>
-</abapGit>
-```
+## XML Metadata
 
-### XML Metadata Format for INTF
+**See guidelines/08_abapgit.md for XML templates.**
 
-For `zif_abgagt_util.intf.abap`, create `zif_abgagt_util.intf.xml`:
+Each ABAP object requires an XML metadata file for abapGit. Quick reference:
 
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<abapGit version="v1.0.0" serializer="LCL_OBJECT_INTF" serializer_version="v1.0.0">
- <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
-  <asx:values>
-   <VSEOINTERF>
-    <CLSNAME>ZIF_ABGAGT_UTIL</CLSNAME>
-    <LANGU>E</LANGU>
-    <DESCRIPT>Description</DESCRIPT>
-    <EXPOSURE>2</EXPOSURE>
-    <STATE>1</STATE>
-    <UNICODE>X</UNICODE>
-   </VSEOINTERF>
-  </asx:values>
- </asx:abap>
-</abapGit>
+```
+Class:         zcl_*.clas.xml
+Interface:     zif_*.intf.xml
+Table:         z*.tabl.xml
+CDS View:      zc_*.ddls.xml
 ```
 
-### Important Notes
-
-1. **CRITICAL: Push to git BEFORE pulling into ABAP**
-   - Always commit and push ABAP files to git first
-   - Then run `abapgit-agent pull` to activate in ABAP
-   - Never run `abapgit-agent pull` without pushing changes first
-
-2. **Only pull ABAP files** - The XML metadata stays in git:
-   ```bash
-   abapgit-agent pull --files zcl_my_class.clas.abap
-   ```
-3. abapGit reads the XML from git to deserialize the ABAP code
-4. XML files are NOT activated in ABAP - they are only for abapGit
-
+**Important**: Always push to git BEFORE running pull:
 ```bash
-# After making changes to ABAP files
 git add .
-git commit -m "Describe changes"
-git push    # CRITICAL: Push BEFORE pulling
-
-# Then validate in ABAP system (single file - fast)
+git commit -m "Changes"
+git push           # CRITICAL: Push FIRST
 abapgit-agent pull --files abap/zcl_my_class.clas.abap
-
-# Or validate all files
-abapgit-agent pull
 ```
-
-## Naming Conventions
-
-- Use `Z_` or `Y_` prefix for custom objects
-- Class names: `ZCL_<NAME>`
-- Interface names: `ZIF_<NAME>`
-- Programs: `Z<NAME>`
-- Package: `$<PROJECT_NAME>`
-
-## ABAP Object Types
-
-Common object types in this project:
-- `CLAS` - Classes
-- `PROG` - Programs
-- `FUGR` - Function Groups
-- `INTF` - Interfaces
-- `TABL` - Tables
-- `DDLS` - Data Definitions

package/abap/guidelines/07_json.md

@@ -1,5 +1,7 @@
 # JSON Handling
 
+**Searchable keywords**: JSON, serialize, deserialize, /ui2/cl_json, REST API, API response
+
 **CRITICAL**: Always use `/ui2/cl_json` for JSON serialization and deserialization.
 
 ## Correct Usage

package/abap/guidelines/08_abapgit.md

@@ -2,6 +2,36 @@
 
 Each ABAP object requires an XML metadata file for abapGit to understand how to serialize/deserialize it. This guide provides templates for common object types.
 
+## QUICK REFERENCE
+
+```
+File Type          | ABAP File                    | XML File
+-------------------|------------------------------|-------------------
+Class              | zcl_*.clas.abap              | zcl_*.clas.xml
+Test Class         | zcl_*.clas.testclasses.abap | zcl_*.clas.xml
+Interface          | zif_*.intf.abap             | zif_*.intf.xml
+Program            | z*.prog.abap                | z*.prog.xml
+Table              | z*.tabl.abap                | z*.tabl.xml
+CDS View           | zc_*.ddls.asddls            | zc_*.ddls.xml
+CDS Entity         | ze_*.ddlx.asddlx            | ze_*.ddlx.xml
+Data Element       | z*.dtel.abap                | z*.dtel.xml
+Structure          | z*.stru.abap                | z*.stru.xml
+Table Type         | z*.ttyp.abap                | z*.ttyp.xml
+```
+
+```
+Key XML Settings:
+  Class EXPOSURE:   2=Public, 3=Protected, 4=Private
+  Class STATE:      1=Active
+  Table TABCLASS:   TRANSP, POOL, CLUSTER
+  Table DELIVERY:   A=Application, C=Customizing
+  CDS SOURCE_TYPE:  V=View, C=Consumption
+  Test Class XML:   <WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>
+  Local Classes:    <CLSCCINCL>X</CLSCCINCL>
+```
+
+**Searchable keywords**: class xml, interface xml, table xml, cds xml, test class, exposure, serializer, abapgit
+
 ## Why XML Metadata?
 
 abapGit needs XML files to:
@@ -40,6 +70,16 @@ abapGit needs XML files to:
 - `STATE`: State (1 = Active)
 - `UNICODE`: Unicode encoding (X = Yes)
 
+**Local Classes**: If the class has local classes (e.g., test doubles), add:
+- `<WITH_UNIT_TESTS>X</WITH_UNIT_TESTS>` - for test classes
+- `<CLSCCINCL>X</CLSCCINCL>` - for local class definitions
+
+**Local Class Files**:
+| File | Purpose |
+|------|---------|
+| `zcl_xxx.clas.locals_def.abap` | Local class definitions |
+| `zcl_xxx.clas.locals_imp.abap` | Local class implementations |
+
 ---
 
 ### Interface (INTF)