abapgit-agent 1.5.0 → 1.6.1

package/abap/guidelines/04_cds.md

@@ -0,0 +1,136 @@
+# 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.
+
+### File Naming
+
+CDS views require **two files**:
+
+| File | Description |
+|------|-------------|
+| `zc_my_view.ddls.asddls` | DDL source code |
+| `zc_my_view.ddls.xml` | XML metadata |
+
+**Important:** Do NOT use `.ddls.abap` extension - use `.ddls.asddls` for the source.
+
+### DDL Source File (`.ddls.asddls`)
+
+```abap
+@AbapCatalog.sqlViewName: 'ZCMYVIEW'
+@AbapCatalog.compiler.compareFilter: true
+@AccessControl.authorizationCheck: #NOT_REQUIRED
+@EndUserText.label: 'My CDS View'
+define view ZC_My_View as select from tdevc
+{
+  key devclass as Devclass,
+      parentcl as ParentPackage,
+      ctext    as Description
+}
+where devclass not like '$%'
+```
+
+### XML Metadata File (`.ddls.xml`)
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_DDLS" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DDLS>
+    <DDLNAME>ZC_MY_VIEW</DDLNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>My CDS View</DDTEXT>
+   </DDLS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+### Key Points
+
+1. **Avoid reserved words** - Field names like `PACKAGE`, `CLASS`, `INTERFACE` are reserved in CDS. Use alternatives like `PackageName`, `ClassName`.
+
+2. **Pull all files to activate** - When activating CDS views, use `abapgit-agent pull` (not single file) to ensure proper activation:
+   ```bash
+   abapgit-agent pull  # Pull all files
+   ```
+
+3. **System support** - CDS views require SAP systems with CDS capability (S/4HANA, SAP BW/4HANA, or ABAP 7.51+). Older systems will show error: "Object type DDLS is not supported by this system"
+
+### Debugging Activation Errors
+
+When pull shows generic errors like "Activation cancelled. Check the inactive objects":
+
+1. **Check in ADT/Eclipse** - Open the DDL source in ADT and run syntax check for detailed errors
+2. **Pull all files** - Sometimes `abapgit-agent pull` (all files) works better than single file for CDS views
+
+## Creating CDS View Entities
+
+CDS View Entities (`define view entity`) are the modern replacement for CDS Views with additional features like **associations for OData navigation**.
+
+### Differences from CDS Views
+
+| Aspect | CDS View | View Entity |
+|--------|----------|-------------|
+| Syntax | `define view` | `define view entity` |
+| Associations | No | Yes (exposed for navigation) |
+| OData/Navigation | Requires separate service | Auto-exposes associations |
+| ABAP Version | 7.40+ | 7.55+ / S/4HANA Cloud |
+
+### DDL Source File with Association
+
+```abap
+@EndUserText.label: 'Package Hierarchy'
+@AccessControl.authorizationCheck: #NOT_REQUIRED
+define view entity ZC_Pkg_Hierarchy_VE
+  as select from tdevc
+  association [0..1] to tdevc as _Parent
+    on _Parent.devclass = $projection.ParentPackage
+{
+  key devclass                           as PackageName,
+      parentcl                           as ParentPackage,
+      ctext                              as Description,
+      dlvunit                           as SoftwareComponent,
+
+      // Exposed associations
+      _Parent
+}
+where devclass not like '$%'
+```
+
+### Key Points for View Entities
+
+1. **Association syntax**: Use `$projection` to reference fields in the current entity
+2. **Association cardinality**: `[0..1]`, `[1..1]`, `[0..n]`, `[1..n]`
+3. **Expose associations**: Add the association name at the end of the SELECT to expose it for OData navigation
+4. **Activation warnings**: Search help warnings are informational and don't block activation
+
+## CDS Syntax Reference
+
+When working with CDS view syntax (arithmetic, built-in functions, aggregations, etc.):
+
+1. Run `abapgit-agent ref --topic cds` to see available topics and example files
+2. Check the example files in `abap-cheat-sheets/src/`:
+   - `zdemo_abap_cds_ve_sel.ddls.asddls` - Arithmetic expressions, built-in functions (division, cast, etc.)
+   - `zdemo_abap_cds_ve_agg_exp.ddls.asddls` - Aggregate expressions (SUM, AVG, COUNT)
+   - `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

@@ -0,0 +1,58 @@
+# 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
+
+## ABAP Class Definition - Must Use PUBLIC
+
+**CRITICAL**: Global ABAP classes MUST use `PUBLIC` in the class definition:
+
+```abap
+" Correct - global class
+CLASS zcl_my_class DEFINITION PUBLIC.
+  ...
+ENDCLASS.
+
+" Wrong - treated as local class, will fail activation
+CLASS zcl_my_class DEFINITION.
+  ...
+ENDCLASS.
+```
+
+**Error symptom**: `Error updating where-used list for CLAS ZCL_MY_CLASS`
+
+**Fix**: Add `PUBLIC` keyword:
+```abap
+CLASS zcl_my_class DEFINITION PUBLIC.  " <- PUBLIC required
+```
+
+## Interface Method Implementation
+
+When implementing interface methods in ABAP classes, use the interface prefix:
+
+```abap
+" Interface definition
+INTERFACE zif_my_interface PUBLIC.
+  METHODS do_something IMPORTING iv_param TYPE string.
+ENDINTERFACE.
+
+" Class implementation - use interface prefix
+CLASS zcl_my_class DEFINITION PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES zif_my_interface.
+ENDCLASS.
+
+CLASS zcl_my_class IMPLEMENTATION.
+  METHOD zif_my_interface~do_something.  " <- Use interface prefix
+    " Implementation here
+  ENDMETHOD.
+ENDCLASS.
+```
+
+**Wrong**: `METHOD do_something.` - parameter `iv_param` will be unknown
+**Correct**: `METHOD zif_my_interface~do_something.` - parameters recognized

package/abap/guidelines/06_objects.md

@@ -0,0 +1,110 @@
+# ABAP Objects
+
+**Searchable keywords**: naming convention, Z prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS, XML metadata, .abapGit.xml
+
+## TOPICS IN THIS FILE
+1. XML Metadata Required - line 3
+2. Naming Conventions - line 30
+3. Object Types - line 60
+
+## Creating New ABAP Objects - XML Metadata Required
+
+**CRITICAL CHECKLIST - Never Forget!**
+
+When creating ANY new ABAP object file, you MUST also create its XML metadata file:
+
+| 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` |
+
+**Without XML files**, abapGit will NOT recognize the objects during pull, and they won't be activated.
+
+### XML Metadata Format for CLAS
+
+For `zcl_abgagt_util.clas.abap`, create `zcl_abgagt_util.clas.xml`:
+
+```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 Format for INTF
+
+For `zif_abgagt_util.intf.abap`, create `zif_abgagt_util.intf.xml`:
+
+```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>
+```
+
+### 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
+
+```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)
+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

@@ -0,0 +1,24 @@
+# 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
+
+```abap
+" Deserialize JSON to ABAP structure
+DATA ls_data TYPE ty_request.
+ls_data = /ui2/cl_json=>deserialize( json = lv_json ).
+
+" Serialize ABAP structure to JSON
+lv_json = /ui2/cl_json=>serialize( data = ls_response ).
+```
+
+## Never Use
+
+- Manual string operations (CONCATENATE, SPLIT, etc.)
+- String templates for complex structures
+- Direct assignment without /ui2/cl_json
+
+This is enforced by ABAP - manual string operations for JSON parsing will cause type conflicts.

package/abap/guidelines/08_abapgit.md

@@ -0,0 +1,222 @@
+# abapGit Object XML Metadata
+
+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>
+```
+
+**Searchable keywords**: class xml, interface xml, table xml, cds xml, test class, exposure, serializer, abapgit
+
+## Why XML Metadata?
+
+abapGit needs XML files to:
+- Know the object type and serializer to use
+- Store object attributes (description, exposure, state, etc.)
+- Handle object-specific configurations
+
+## Object Types and XML Templates
+
+### Class (CLAS)
+
+**Filename**: `src/zcl_my_class.clas.xml`
+
+```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_MY_CLASS</CLSNAME>
+    <LANGU>E</LANGU>
+    <DESCRIPT>Description of the class</DESCRIPT>
+    <EXPOSURE>2</EXPOSURE>
+    <STATE>1</STATE>
+    <UNICODE>X</UNICODE>
+   </VSEOCLASS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `CLSNAME`: Class name (must match filename)
+- `DESCRIPT`: Class description
+- `EXPOSURE`: Exposure (2 = Public, 3 = Protected, 4 = Private)
+- `STATE`: State (1 = Active)
+- `UNICODE`: Unicode encoding (X = Yes)
+
+---
+
+### Interface (INTF)
+
+**Filename**: `src/zif_my_interface.intf.xml`
+
+```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_MY_INTERFACE</CLSNAME>
+    <LANGU>E</LANGU>
+    <DESCRIPT>Description of the interface</DESCRIPT>
+    <EXPOSURE>2</EXPOSURE>
+    <STATE>1</STATE>
+    <UNICODE>X</UNICODE>
+   </VSEOINTERF>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+---
+
+### Program (PROG)
+
+**Filename**: `src/zmy_program.prog.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_PROG" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <PROGDIR>
+    <NAME>ZMY_PROGRAM</NAME>
+    <SUBC>I</SUBC>
+    <RLOAD>E</RLOAD>
+    <FIXPT>X</FIXPT>
+    <UCCHECK>X</UCCHECK>
+   </PROGDIR>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `NAME`: Program name
+- `SUBC`: Subc (I = Include, 1 = Executable, F = Function Group, M = Module Pool, S = Subroutine Pool)
+- `RLOAD`: Rload (E = External, I = Internal)
+
+---
+
+### Table (TABL)
+
+**Filename**: `src/zmy_table.tabl.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_TABL" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD02V>
+    <TABNAME>ZMY_TABLE</TABNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <TABCLASS>TRANSP</TABCLASS>
+    <DDTEXT>Description of the table</DDTEXT>
+    <CONTFLAG>A</CONTFLAG>
+   </DD02V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `TABNAME`: Table name
+- `DDTEXT`: Description (NOT DESCRIPT)
+- `TABCLASS`: Table class (TRANSP = Transparent)
+- `CONTFLAG`: Delivery class (A = Application table)
+
+---
+
+### CDS View (DDLS)
+
+**Filename**: `src/zc_my_view.ddls.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_DDLS" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DDLS>
+    <DDLNAME>ZC_MY_VIEW</DDLNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>My CDS View</DDTEXT>
+    <SOURCE_TYPE>V</SOURCE_TYPE>
+   </DDLS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Points for CDS Views**:
+1. **ABAP file extension**: Use `.ddls.asddls` (NOT `.ddls.abap`)
+2. **XML file**: Use `.ddls.xml`
+3. **DDLNAME**: Must match the CDS view name in the source
+4. **SOURCE_TYPE**: V = View, C = Consumption
+5. **Serializer**: Use `LCL_OBJECT_DDLS`
+
+---
+
+### Data Element (DTEL)
+
+**Filename**: `src/zmy_dtel.dtel.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_DTEL" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <DD04V>
+    <ROLLNAME>ZMY_DTEL</ROLLNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>Description of data element</DDTEXT>
+    <REPTEXT>Description</REPTEXT>
+    <SCRTEXT_S>Short</SCRTEXT_S>
+    <SCRTEXT_M>Medium</SCRTEXT_M>
+    <SCRTEXT_L>Long Description</SCRTEXT_L>
+    <DTELMASTER>E</DTELMASTER>
+    <DATATYPE>CHAR</DATATYPE>
+    <LENG>000010</LENG>
+   </DD04V>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `ROLLNAME`: Data element name
+- `DDTEXT`: Description (NOT DESCRIPT)
+- `DATATYPE`: Data type (CHAR, NUMC, etc.)
+- `LENG`: Length (e.g., 000010 for 10 characters)
+
+---
+
+## Important Notes
+
+1. **ALWAYS push to git BEFORE running pull** - abapGit reads from git
+2. **Check pull output** to verify objects were recognized by abapGit
+3. **Use inspect AFTER pull** to check syntax on objects in ABAP