abapgit-agent 1.7.2 → 1.8.0

package/README.md

@@ -25,7 +25,7 @@ git clone https://github.com/user/abap-project.git
 cd abap-project
 
 # 3. Initialize configuration
-abapgit-agent init --folder /abap/ --package ZMY_PACKAGE
+abapgit-agent init --folder /src/ --package ZMY_PACKAGE
 
 # 4. Edit .abapGitAgent with credentials
 
@@ -47,7 +47,7 @@ See [Creating New ABAP Projects](INSTALL.md#creating-new-abap-projects) to set u
 
 ```bash
 # Initialize local configuration for existing git repo
-abapgit-agent init --folder /abap/ --package ZMY_PACKAGE
+abapgit-agent init --folder /src/ --package ZMY_PACKAGE
 
 # Create online repository in ABAP
 abapgit-agent create
@@ -69,7 +69,7 @@ abapgit-agent pull
 abapgit-agent pull --branch develop
 
 # Pull specific files only (fast iteration)
-abapgit-agent pull --files zcl_my_class.clas.abap,zif_my_intf.intf.abap
+abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap
 
 # Override git URL if needed
 abapgit-agent pull --url https://github.com/user/repo --branch main
@@ -88,20 +88,20 @@ abapgit-agent import --message "feat: add new feature"
 
 ```bash
 # Inspect source file for issues
-abapgit-agent inspect --files abap/zcl_my_class.clas.abap
+abapgit-agent inspect --files src/zcl_my_class.clas.abap
 
 # Run AUnit tests for test classes
-abapgit-agent unit --files abap/zcl_my_test.clas.testclasses.abap
+abapgit-agent unit --files src/zcl_my_test.clas.testclasses.abap
 
 # Run tests for multiple test classes
-abapgit-agent unit --files abap/zcl_test1.clas.testclasses.abap,abap/zcl_test2.clas.testclasses.abap
+abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
 ```
 
 ### Explore Commands
 
 ```bash
 # Display package hierarchy tree
-abapgit-agent tree --package $MY_PACKAGE
+abapgit-agent tree --package '$MY_PACKAGE'
 
 # View object definitions from ABAP system (classes, interfaces, tables, data elements)
 abapgit-agent view --objects ZCL_MY_CLASS

package/abap/CLAUDE.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: ABAP Project Guidelines
+nav_order: 1
+parent: ABAP Development
+---
+
 # ABAP Project Guidelines - Template
 
 This file provides guidelines for **generating ABAP code** in abapGit repositories.
@@ -78,14 +85,48 @@ The folder is configured in `.abapGitAgent` (property: `folder`):
 
 ---
 
-### 4. NEVER Run Inspect Before Push/Pull (MOST IMPORTANT!)
+### 4. Use Syntax Command Before Commit (for CLAS, INTF, PROG)
 
 ```
-❌ WRONG: Make changes → Run inspect → Check errors → Repeat
-✅ CORRECT: Make changes → Commit → Push → Run pull → Then inspect ONLY if pull fails
+❌ WRONG: Make changes → Commit → Push → Pull → Find errors → Fix → Repeat
+✅ CORRECT: Make changes → Run syntax → Fix locally → Commit → Push → Pull → Done
 ```
 
-**Why**: Inspect runs against the ABAP system, not git. The code must be in git and pulled to ABAP first.
+**For CLAS, INTF, PROG files**: Run `syntax` command BEFORE commit to catch errors early.
+
+```bash
+# Check syntax of local code (no commit/push needed)
+abapgit-agent syntax --files src/zcl_my_class.clas.abap
+
+# Check multiple INDEPENDENT files
+abapgit-agent syntax --files src/zcl_utils.clas.abap,src/zcl_logger.clas.abap
+```
+
+**For other types (DDLS, FUGR, TABL, etc.)**: Skip syntax, proceed to commit/push/pull.
+
+**Why use syntax command?**
+- Catches syntax errors BEFORE polluting git history with fix commits
+- No broken inactive objects in ABAP system
+- Faster feedback loop - fix locally without commit/push/pull cycle
+- Works even for NEW objects that don't exist in ABAP system yet
+
+**⚠️ Important: Syntax checks files independently**
+
+When checking multiple files, each is validated in isolation:
+- ✅ **Use for**: Multiple independent files (bug fixes, unrelated changes)
+- ❌ **Don't use for**: Files with dependencies (interface + implementing class)
+
+**For dependent files, skip `syntax` and use `pull` instead:**
+```bash
+# ❌ BAD - Interface and implementing class (may show false errors)
+abapgit-agent syntax --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
+
+# ✅ GOOD - Use pull instead for dependent files
+git add . && git commit && git push
+abapgit-agent pull --files src/zif_my_intf.intf.abap,src/zcl_my_class.clas.abap
+```
+
+**Note**: `inspect` still runs against ABAP system (requires pull first). Use `syntax` for pre-commit checking.
 
 ---
 
@@ -219,48 +260,126 @@ abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.cla
 3. Write code → place in correct folder (e.g., src/zcl_*.clas.abap)
        │
        ▼
-4. Commit and push → git add . && git commit && git push
+4. Syntax check (for CLAS, INTF, PROG only)
        │
-       ▼
-5. Activate → abapgit-agent pull --files src/file.clas.abap
+       ├─► CLAS/INTF/PROG → abapgit-agent syntax --files <file>
+       │       │
+       │       ├─► Errors? → Fix locally (no commit needed), re-run syntax
+       │       │
+       │       └─► Clean ✅ → Proceed to commit
+       │
+       └─► Other types (DDLS, FUGR, TABL, etc.) → Skip syntax, go to commit
+               │
+               ▼
+5. Commit and push → git add . && git commit && git push
        │
        ▼
-6. Verify → Check pull output
-   - **Do NOT run inspect before commit/push/pull** - ABAP validates on pull
-   - **Do NOT run unit before pull** - Tests run against ABAP system, code must be activated first
-   - **"Error updating where-used list"** → This is a **SYNTAX ERROR** (check inspect for details)
-   - Objects NOT in "Activated Objects" but in "Failed Objects Log" → Syntax error (check inspect)
-   - Objects NOT appearing at all → XML metadata issue (check XML format in 08_abapgit.md)
+6. Activate → abapgit-agent pull --files src/file.clas.abap
        │
        ▼
-7. (Optional) Run unit tests → abapgit-agent unit --files src/zcl_test.clas.testclasses.abap (ONLY if test file exists, AFTER successful pull)
+7. Verify → Check pull output
+   - **"Error updating where-used list"** → SYNTAX ERROR (use inspect for details)
+   - Objects in "Failed Objects Log" → Syntax error (use inspect)
+   - Objects NOT appearing at all → XML metadata issue (check 08_abapgit.md)
        │
        ▼
-8. If needed → Use inspect to check syntax (runs against ABAP system)
+8. (Optional) Run unit tests → abapgit-agent unit --files <testclass> (AFTER successful pull)
 ```
 
+**Syntax Command - Supported Object Types:**
+
+| Object Type | Syntax Command | What to Do |
+|-------------|----------------|------------|
+| CLAS (classes) | ✅ Supported | Run `syntax` before commit |
+| CLAS (test classes: .testclasses.abap) | ✅ Supported | Run `syntax` before commit |
+| INTF (interfaces) | ✅ Supported | Run `syntax` before commit |
+| PROG (programs) | ✅ Supported | Run `syntax` before commit |
+| DDLS (CDS views) | ❌ Not supported | Skip syntax, use `pull` then `inspect` |
+| FUGR (function groups) | ❌ Not supported | Skip syntax, use `pull` then `inspect` |
+| TABL/DTEL/DOMA/MSAG/SHLP | ❌ Not supported | Skip syntax, just `pull` |
+| All other types | ❌ Not supported | Skip syntax, just `pull` |
+
 **IMPORTANT**:
+- **Use `syntax` BEFORE commit** for CLAS/INTF/PROG (including test classes) - catches errors early, no git pollution
+- **Syntax checks files INDEPENDENTLY** - no cross-file dependency support (e.g., interface definition not available when checking implementing class)
+- **For dependent files** (interface + class, class + using class): Skip `syntax`, use `pull` directly
 - **ALWAYS push to git BEFORE running pull** - abapGit reads from git
-- **Use inspect AFTER pull** to check syntax on objects already in ABAP
-- **Check pull output**:
-  - In "Failed Objects Log" → Syntax error (use inspect for details)
-  - Not appearing at all → XML metadata is wrong
+- **Use `inspect` AFTER pull** for unsupported types or if pull fails
+
+**Working with mixed file types:**
+When modifying multiple files of different types (e.g., 1 class + 1 CDS view):
+1. Run `syntax` on supported files only (CLAS, INTF, PROG) - **only if they're independent**
+2. Commit ALL files together (including unsupported types)
+3. Push and pull ALL files together
+
+Example:
+```bash
+# Check syntax on independent class and interface only (skip CDS, skip if dependent)
+abapgit-agent syntax --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap
+
+# Commit and push all files including CDS
+git add src/zcl_my_class.clas.abap src/zif_my_intf.intf.abap src/zc_my_view.ddls.asddls
+git commit -m "feat: add class, interface, and CDS view"
+git push
+
+# Pull all files together
+abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zif_my_intf.intf.abap,src/zc_my_view.ddls.asddls
+```
+
+**When to use syntax vs inspect vs view**:
+- **syntax**: Check LOCAL code BEFORE commit (CLAS, INTF, PROG only)
+- **inspect**: Check ACTIVATED code AFTER pull (all types, runs Code Inspector)
+- **view**: Understand object STRUCTURE (not for debugging errors)
+
+### Quick Decision Tree for AI
+
+**When user asks to modify/create ABAP code:**
 
-**When to use inspect vs view**:
-- **inspect**: Use when there are SYNTAX ERRORS (to find line numbers and details)
-- **view**: Use when you need to understand an object STRUCTURE (table fields, class methods)
-- Do NOT use view to debug syntax errors - view shows definitions, not errors
+```
+1. Identify file extension(s) AND dependencies
+   ├─ .clas.abap or .clas.testclasses.abap → CLAS ✅ syntax supported (if independent)
+   ├─ .intf.abap → INTF ✅ syntax supported (if independent)
+   ├─ .prog.abap → PROG ✅ syntax supported
+   ├─ .ddls.asddls → DDLS ❌ syntax not supported
+   └─ All other extensions → ❌ syntax not supported
+
+2. Check for dependencies:
+   ├─ Interface + implementing class? → Dependencies exist
+   ├─ Class A uses class B? → Dependencies exist
+   ├─ New objects that don't exist in ABAP system? → Check if they depend on each other
+   └─ Unrelated bug fixes across files? → No dependencies
+
+3. For SUPPORTED types (CLAS/INTF/PROG):
+   ├─ Independent files → Run syntax → Fix errors → Commit → Push → Pull
+   └─ Dependent files → Skip syntax → Commit → Push → Pull
+
+4. For UNSUPPORTED types (DDLS, FUGR, TABL, etc.):
+   Write code → Skip syntax → Commit → Push → Pull → (if errors: inspect)
+
+5. For MIXED types (some supported + some unsupported):
+   Write all code → Run syntax on independent supported files ONLY → Commit ALL → Push → Pull ALL
+```
+
+**Error indicators after pull:**
+- ❌ **"Error updating where-used list"** → SYNTAX ERROR - run `inspect` for details
+- ❌ **Objects in "Failed Objects Log"** → SYNTAX ERROR - run `inspect`
+- ❌ **Objects NOT appearing at all** → XML metadata issue (check `ref --topic abapgit`)
+- ⚠️ **"Activated with warnings"** → Code Inspector warnings - run `inspect` to see details
 
 ### Commands
 
 ```bash
-# 1. Pull/activate after pushing to git (abapGit reads from git!)
+# 1. Syntax check LOCAL code BEFORE commit (CLAS, INTF, PROG only)
+abapgit-agent syntax --files src/zcl_my_class.clas.abap
+abapgit-agent syntax --files src/zcl_class1.clas.abap,src/zif_intf1.intf.abap
+
+# 2. Pull/activate AFTER pushing to git
 abapgit-agent pull --files src/zcl_class1.clas.abap,src/zcl_class2.clas.abap
 
-# 2. Inspect AFTER pull to check syntax (runs against ABAP system)
+# 3. Inspect AFTER pull (for errors or unsupported types)
 abapgit-agent inspect --files src/zcl_class1.clas.abap
 
-# Run unit tests (multiple test classes)
+# Run unit tests (after successful pull)
 abapgit-agent unit --files src/zcl_test1.clas.testclasses.abap,src/zcl_test2.clas.testclasses.abap
 
 # View object definitions (multiple objects)

package/abap/guidelines/00_index.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Overview
+nav_order: 1
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # ABAP Coding Guidelines Index
 
 This folder contains detailed ABAP coding guidelines that can be searched using the `ref` command.

package/abap/guidelines/01_sql.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: SQL Best Practices
+nav_order: 2
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # 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

package/abap/guidelines/02_exceptions.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Exception Handling
+nav_order: 3
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # 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

package/abap/guidelines/03_testing.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Unit Testing
+nav_order: 4
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # 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

package/abap/guidelines/04_cds.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: CDS Views
+nav_order: 5
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # Creating CDS Views
 
 **Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption

package/abap/guidelines/05_classes.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Classes & Objects
+nav_order: 6
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # ABAP Classes and Objects
 
 **Searchable keywords**: CLASS, DEFINITION, PUBLIC, CREATE OBJECT, NEW, METHOD, INTERFACES, inheritance, FINAL, ABSTRACT

package/abap/guidelines/06_objects.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Naming Conventions
+nav_order: 7
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # ABAP Object Naming Conventions
 
 **Searchable keywords**: naming convention, Z prefix, namespace, object type, CLAS, INTF, PROG, TABL, DDLS

package/abap/guidelines/07_json.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: JSON Handling
+nav_order: 8
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # JSON Handling
 
 **Searchable keywords**: JSON, serialize, deserialize, /ui2/cl_json, REST API, API response

package/abap/guidelines/08_abapgit.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: abapGit XML Metadata
+nav_order: 9
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # 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.

package/abap/guidelines/09_unit_testable_code.md

@@ -1,3 +1,11 @@
+---
+layout: default
+title: Unit Testable Code
+nav_order: 10
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
 # ABAP Unit Testable Code Guidelines
 
 This document provides guidelines for creating ABAP OO classes/interfaces that can be easily unit tested with test doubles. These guidelines help AI coding tools understand how to design classes that are testable without requiring real dependencies.