abapgit-agent 1.7.2 → 1.8.1

package/README.md

@@ -1,3 +1,9 @@
+---
+title: abapGit Agent
+nav_order: 1
+permalink: /
+---
+
 # abapGit Agent
 
 A local agent that enables AI coding tools (Claude, Copilot, etc.) to automatically pull and activate ABAP code from git repositories using REST API.
@@ -25,7 +31,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 +53,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 +75,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
@@ -87,21 +93,32 @@ abapgit-agent import --message "feat: add new feature"
 ### Validation Commands
 
 ```bash
-# Inspect source file for issues
-abapgit-agent inspect --files abap/zcl_my_class.clas.abap
+# Check syntax of local source files BEFORE commit (fast, no activation)
+# Supported: CLAS, INTF, PROG, DDLS (CDS Views)
+abapgit-agent syntax --files src/zcl_my_class.clas.abap
+abapgit-agent syntax --files src/zc_my_view.ddls.asddls
+
+# Syntax check with ABAP Cloud mode
+abapgit-agent syntax --files src/zcl_my_class.clas.abap --cloud
+
+# Syntax check multiple files
+abapgit-agent syntax --files src/zcl_class.clas.abap,src/zc_view.ddls.asddls
+
+# Inspect source file for issues (after activation)
+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
@@ -158,6 +175,7 @@ npm run pull -- --url <git-url> --branch main
 | delete Command | [docs/delete-command.md](docs/delete-command.md) |
 | import Command | [docs/import-command.md](docs/import-command.md) |
 | pull Command | [docs/pull-command.md](docs/pull-command.md) |
+| syntax Command | [docs/syntax-command.md](docs/syntax-command.md) |
 | inspect Command | [docs/inspect-command.md](docs/inspect-command.md) |
 | unit Command | [docs/unit-command.md](docs/unit-command.md) |
 | tree Command | [docs/tree-command.md](docs/tree-command.md) |

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,127 @@ 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) | ✅ Supported | Run `syntax` before commit (requires annotations) |
+| 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/DDLS - 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
+- **DDLS requires proper annotations** - CDS views need `@AbapCatalog.sqlViewName`, view entities don't
 - **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 supported (requires proper annotations)
+   └─ 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/DDLS):
+   ├─ Independent files → Run syntax → Fix errors → Commit → Push → Pull
+   └─ Dependent files → Skip syntax → Commit → Push → Pull
+
+4. For UNSUPPORTED types (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
@@ -82,6 +90,26 @@ SELECT object obj_name FROM tadir ...
 
 ---
 
+## 6. Modern ABAP SQL (with FIXPT)
+
+When `<FIXPT>X</FIXPT>` is in class XML (default for modern ABAP):
+
+```abap
+" ✅ Required syntax
+SELECT carrid, connid, fldate      " Commas required
+  FROM sflight
+  INTO TABLE @lt_result             " @ for host variables
+  WHERE carrid = @lv_carrier.       " @ for parameters
+```
+
+**Common errors**:
+- Missing commas → Add between all SELECT fields
+- Missing @ → Add to all ABAP variables (not DB columns)
+
+**Why FIXPT**: Without it, decimals treated as integers in calculations.
+
+---
+
 ## See Also
 - **Constructor Expressions** (05_classes.md) - for VALUE #(), FILTER, FOR loops
 - **Internal Tables** - for filtering and iteration patterns

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
@@ -13,6 +21,77 @@
 
 CDS views (Data Definition Language Source) require specific file naming and structure for abapGit.
 
+### CDS View vs View Entity: When to Use Which
+
+**IMPORTANT**: When creating CDS views, use **View Entity** by default unless explicitly requested otherwise.
+
+| User Request | Create Type | Why |
+|--------------|-------------|-----|
+| "Create CDS view" | CDS View Entity (modern) | Default for new development |
+| "Create CDS view for..." | CDS View Entity (modern) | Recommended approach |
+| "Create legacy CDS view" | CDS View (legacy) | Only if explicitly requested |
+| "Create CDS view with sqlViewName" | CDS View (legacy) | Explicit legacy request |
+
+### Key Differences
+
+| Aspect | CDS View (Legacy) | CDS View Entity (Modern) |
+|--------|-------------------|-------------------------|
+| **Syntax** | `define view` | `define view entity` |
+| **@AbapCatalog.sqlViewName** | ✅ Required | ❌ Not allowed (will fail) |
+| **Creates SQL View** | Yes (DDLS + SQL view) | No (DDLS only) |
+| **XML SOURCE_TYPE** | `V` | `W` |
+| **ABAP Version** | 7.40+ | 7.55+ / S/4HANA Cloud |
+| **Parameter Syntax** | `:param` or `$parameters.param` | `$parameters.param` only |
+| **Use For** | Legacy systems, existing code | New development, S/4HANA |
+
+### XML Metadata: The Key Difference
+
+The XML metadata differs only in the `SOURCE_TYPE` field:
+
+**CDS View Entity XML (RECOMMENDED - use by default):**
+```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_ENTITY</DDLNAME>
+    <DDLANGUAGE>E</DDLANGUAGE>
+    <DDTEXT>My CDS View Entity</DDTEXT>
+    <SOURCE_TYPE>W</SOURCE_TYPE>
+   </DDLS>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**CDS View XML (Legacy - only if explicitly requested):**
+```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>
+```
+
+**SOURCE_TYPE values:**
+- `W` = View Entity (modern, no SQL view created)
+- `V` = View (legacy, creates SQL view)
+
+---
+
+## 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**:
@@ -26,6 +105,20 @@ CDS views require **two files**:
 
 ### DDL Source File (`.ddls.asddls`)
 
+**CDS View Entity (RECOMMENDED - use by default):**
+```abap
+@AccessControl.authorizationCheck: #NOT_REQUIRED
+@EndUserText.label: 'My CDS View Entity'
+define view entity ZC_My_Entity as select from tdevc
+{
+  key devclass as Devclass,
+      parentcl as ParentPackage,
+      ctext    as Description
+}
+where devclass not like '$%'
+```
+
+**CDS View (Legacy - only if explicitly requested):**
 ```abap
 @AbapCatalog.sqlViewName: 'ZCMYVIEW'
 @AbapCatalog.compiler.compareFilter: true
@@ -40,55 +133,34 @@ define view ZC_My_View as select from tdevc
 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>
-```
+**Note the key differences:**
+- View Entity: No `@AbapCatalog.sqlViewName`, uses `define view entity`
+- View (legacy): Has `@AbapCatalog.sqlViewName`, uses `define view`
 
 ### 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
-   ```
+2. **Workflow for creating CDS views** - See `../CLAUDE.md` for complete workflow guidance:
+   - Independent CDS views: `syntax → commit → pull --files`
+   - Dependent CDS views (with associations to NEW views): Create underlying view first, then dependent view
+   - See CLAUDE.md section on "Working with dependent objects"
 
 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
+### Activating CDS Views
 
-When pull shows generic errors like "Activation cancelled. Check the inactive objects":
+**For standard workflow, see `../CLAUDE.md`**
 
-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
+**CDS-specific notes:**
+- Single independent DDLS file: `abapgit-agent pull --files src/zc_view.ddls.asddls`
+- CDS views with associations to OTHER NEW views: Create target view first (see `../CLAUDE.md` for workflow)
 
-## Creating CDS View Entities
+## CDS View Entity Features
 
-CDS View Entities (`define view entity`) are the modern replacement for CDS Views with additional features like **associations for OData navigation**.
+CDS View Entities are the modern replacement for CDS Views with enhanced 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
+### Associations in View Entities
 
 ```abap
 @EndUserText.label: 'Package Hierarchy'
@@ -130,6 +202,49 @@ When working with CDS view syntax (arithmetic, built-in functions, aggregations,
 
 ---
 
+## Selecting from CDS Views in Classes
+
+### Best Practice: Use CDS View Entity as Type
+
+```abap
+" ✅ RECOMMENDED - Use view entity directly
+TYPES ty_results TYPE STANDARD TABLE OF zc_my_view WITH DEFAULT KEY.
+
+METHOD get_data.
+  SELECT * FROM zc_my_view INTO TABLE @rt_results.
+ENDMETHOD.
+```
+
+**Benefits**: No field mismatches, 33% less code, auto-sync with CDS changes.
+
+---
+
+### Alternative: Manual Structure Definition
+
+Only when you need to hide/transform fields:
+
+```abap
+" Use data elements from underlying tables
+TYPES: BEGIN OF ty_custom,
+         carrierid TYPE s_carr_id,     " ✅ Data element
+         connid    TYPE s_conn_id,     " ✅ NOT: TYPE c LENGTH 3
+       END OF ty_custom.
+```
+
+**Find data elements**:
+```bash
+abapgit-agent view --objects SFLIGHT --type TABL
+```
+
+**Match field names**:
+```bash
+abapgit-agent preview --objects ZC_MY_VIEW --limit 1
+```
+
+**Calculated fields**: Use `TYPE decfloat34` for division/complex math.
+
+---
+
 ## See Also
 - **Unit Testing** (03_testing.md) - for CDS Test Double Framework
 - **abapGit** (08_abapgit.md) - for CDS XML metadata templates

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