abapgit-agent 1.13.6 → 1.14.0

package/README.md

@@ -97,14 +97,17 @@ abapgit-agent health                  # Verify ABAP connection
 
 ```bash
 # Install dependencies
-cd abapgit-agent
 npm install
 
-# Run from package directory (auto-detects from git)
-node bin/abapgit-agent pull
+# Run unit tests (no ABAP system needed)
+npm test
 
-# Or use npm script
-npm run pull -- --url <git-url> --branch main
+# Test a command manually
+node bin/abapgit-agent --help
+node bin/abapgit-agent syntax --files src/zcl_my_class.clas.abap
+
+# Run integration tests against a real ABAP system (requires .abapGitAgent)
+npm run test:integration
 ```
 
 ## Documentation

package/abap/CLAUDE.md

@@ -211,6 +211,21 @@ abapgit-agent pull --files src/<intf_name>.intf.abap,src/<class_name>.clas.abap
 
 → See `guidelines/object-creation.md` — run: `abapgit-agent ref --topic object-creation`
 
+**XML metadata when adding test classes:**
+
+```
+Adding .clas.testclasses.abap to an existing class?
+  └── Update the .clas.xml → set WITH_UNIT_TESTS flag:
+        <clas:abapClassProperties ... abpUnitTestable="true" ... />
+      WITHOUT this flag, abapGit will not push/activate the test include.
+
+Adding .clas.locals_def.abap (local type definitions)?
+  └── Update the .clas.xml → set CLSCCINCL flag:
+        <CLSCCINCL>X</CLSCCINCL>
+```
+
+→ For exact XML flag placement: `abapgit-agent ref --topic abapgit` (search "WITH_UNIT_TESTS")
+
 ---
 
 ### 6. Use `guide`, `ref`, `view` and `where` Commands to Learn About Unknown Classes/Methods
@@ -299,7 +314,47 @@ Use `CL_CDS_TEST_ENVIRONMENT` for unit tests that read CDS views.
 
 ---
 
-### 8. Use `unit` Command for Unit Tests
+### 8. Writing and Running Unit Tests
+
+#### Writing tests — use ABAP Test Double Framework by default
+
+```
+❌ WRONG: Write a manual test double class (ltd_mock_xxx) when the framework can do it
+✅ CORRECT: Use cl_abap_testdouble=>create / configure_call for all interface mocking
+```
+
+**Decision — which double pattern to use:**
+
+```
+Does the mock need stateful behaviour (e.g. count calls, vary results per call, complex logic)?
+  └── YES → manual test double class (ltd_mock_xxx DEFINITION FOR TESTING)
+  └── NO  → ABAP Test Double Framework (cl_abap_testdouble=>create / configure_call)
+             This covers 90 %+ of cases — simple return value / exception mocking
+```
+
+**ABAP Test Double Framework — quick pattern:**
+
+```abap
+" 1. Create double (declare with interface type)
+DATA lo_agent TYPE REF TO zif_abgagt_agent.
+lo_agent ?= cl_abap_testdouble=>create( 'ZIF_ABGAGT_AGENT' ).
+
+" 2. Configure return value
+cl_abap_testdouble=>configure_call( lo_agent )->returning( ls_result ).
+lo_agent->pull( iv_url = 'https://...' ).   " registers config for these params
+
+" 3. Inject and call
+DATA(lo_cut) = NEW zcl_my_class( io_agent = lo_agent ).
+DATA(ls_actual) = lo_cut->execute( ).
+```
+
+→ Full API reference (EXPORT params, exceptions, inherited methods, common mistakes):
+  `abapgit-agent ref --topic unit-testable-code`
+
+→ For class design rules (constructor injection, interfaces for dependencies):
+  `abapgit-agent ref --topic unit-testable-code`
+
+#### Running tests — use `unit` command
 
 **Use `abapgit-agent unit` to run ABAP unit tests (AUnit).**
 
@@ -399,6 +454,56 @@ abapgit-agent debug step --type continue --json     # 4. release
 
 ---
 
+### 12. abaplint — Static Analysis (Optional, Project-Controlled)
+
+abaplint is **optional**. Only run it if `.abaplint.json` exists in the project root.
+Each project defines its own rules — never assume which rules are active.
+
+**Detection:**
+```bash
+# Check whether this project uses abaplint
+ls .abaplint.json 2>/dev/null && echo "abaplint enabled" || echo "no abaplint"
+```
+
+**When to run:**
+
+Run abaplint as step 4b — after `syntax`, before `git commit`:
+
+```bash
+# Only if .abaplint.json exists
+abapgit-agent lint
+```
+
+Fix any reported issues, then commit.
+
+**Before applying any quickfix:**
+
+```
+❌ WRONG: Accept abaplint quickfixes without checking
+✅ CORRECT: Run abapgit-agent ref --topic abaplint FIRST, then decide
+```
+
+The `prefer_inline` quickfix is known to introduce a **silent type truncation bug**
+when applied to variables that are later extended with `&&`. Read the guidelines
+before applying it.
+
+**When abaplint flags an issue you don't understand:**
+```bash
+abapgit-agent ref --topic abaplint        # bundled rule guidance
+abapgit-agent ref "prefer_inline"         # search for specific rule
+abapgit-agent ref "no_inline"             # search by keyword
+```
+
+**Project-specific rule guidance:**
+
+Projects can add their own abaplint notes to `guidelines/abaplint-local.md` in the
+project repository. After running `abapgit-agent ref export`, the `ref` command
+surfaces both bundled and project-specific guidance together.
+
+→ See `guidelines/abaplint.md` — run: `abapgit-agent ref --topic abaplint`
+
+---
+
 ## Development Workflow
 
 This project's workflow mode is configured in `.abapGitAgent` under `workflow.mode`.
@@ -434,6 +539,21 @@ See **AI Tool Guidelines** below for how to react to each setting.
 ### Branch Workflow (`"mode": "branch"`)
 
 Always work on feature branches. Before every `pull`: rebase to default branch. On completion: create PR with squash merge.
+
+```bash
+git checkout main  # or master/develop (auto-detected)
+git pull origin main
+git checkout -b feature/my-change
+# edit your ABAP file (name from objects.local.md)
+abapgit-agent syntax --files src/<name>.clas.abap
+ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
+git add . && git commit -m "feat: description"
+git push origin feature/my-change
+git fetch origin main && git rebase origin/main
+git push origin feature/my-change --force-with-lease
+abapgit-agent pull --files src/<name>.clas.abap --sync-xml
+```
+
 → See `guidelines/branch-workflow.md` — run: `abapgit-agent ref --topic branch-workflow`
 
 ### Trunk Workflow (`"mode": "trunk"`)
@@ -445,6 +565,7 @@ git checkout main  # or master/develop (auto-detected)
 git pull origin main
 # edit your ABAP file (name from objects.local.md)
 abapgit-agent syntax --files src/<name>.clas.abap
+ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
 git add . && git commit -m "feat: description"
 git push origin main
 abapgit-agent pull --files src/<name>.clas.abap --sync-xml
@@ -535,14 +656,17 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml
 Modified ABAP files?
 ├─ CLAS/INTF/PROG/DDLS files?
 │  ├─ Independent files (no cross-dependencies)?
-│  │  └─ ✅ Use: syntax → commit → push → pull --sync-xml
+│  │  └─ ✅ Use: syntax → [abaplint] → commit → push → pull --sync-xml
 │  └─ Dependent files (interface + class, class uses class)?
-│     └─ ✅ Use: skip syntax → commit → push → pull --sync-xml
+│     └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml
 └─ Other types (FUGR, TABL, STRU, DTEL, TTYP, etc.)?
    ├─ XML-only objects (TABL, STRU, DTEL, TTYP)?
-   │  └─ ✅ Use: skip syntax → commit → push → pull --files abap/ztable.tabl.xml --sync-xml
+   │  └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --files abap/ztable.tabl.xml --sync-xml
    └─ FUGR and other complex objects?
-      └─ ✅ Use: skip syntax → commit → push → pull --sync-xml → (if errors: inspect)
+      └─ ✅ Use: skip syntax → [abaplint] → commit → push → pull --sync-xml → (if errors: inspect)
+
+[abaplint] = run abapgit-agent lint only if .abaplint.json exists in repo root
+             before applying any quickfix: run abapgit-agent ref --topic abaplint
 ```
 
 → For creating new objects (what files to write): `abapgit-agent ref --topic object-creation`
@@ -583,6 +707,7 @@ Detailed guidelines are available in the `guidelines/` folder:
 | `guidelines/workflow-detailed.md` | Development Workflow (Detailed) |
 | `guidelines/object-creation.md` | Object Creation (XML metadata, local classes) |
 | `guidelines/cds-testing.md` | CDS Testing (Test Double Framework) |
+| `guidelines/abaplint.md` | abaplint Rule Guidelines (prefer_inline trap, safe patterns) |
 
 These guidelines are automatically searched by the `ref` command.
 

package/abap/guidelines/abaplint-local.md

@@ -0,0 +1,111 @@
+---
+layout: default
+title: abaplint Local Rules
+nav_order: 18
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# abaplint Local Rules — abapgit-agent project
+
+**Searchable keywords**: naming, local_variable_names, method_parameter_names,
+prefix, lv, lt, ls, lo, li, lx, iv, it, is, io, rv, rs, rt, ro
+
+This project enforces **type-specific Hungarian notation** via `local_variable_names`
+and `method_parameter_names` in `.abaplint.json`.
+
+---
+
+## Variable Naming — Required Prefixes
+
+### Local Variables (inside methods)
+
+| Prefix | Type | Example |
+|--------|------|---------|
+| `lv_` | Scalar / value (i, string, char, …) | `lv_count TYPE i` |
+| `lt_` | Internal table | `lt_files TYPE ty_files` |
+| `ls_` | Structure | `ls_result TYPE ty_result` |
+| `lo_` | Object reference | `lo_agent TYPE REF TO zcl_abgagt_agent` |
+| `li_` | Interface reference | `li_repo TYPE REF TO zif_abapgit_repo` |
+| `lx_` | Exception reference | `lx_error TYPE REF TO cx_static_check` |
+| `lr_` | Data reference | `lr_data TYPE REF TO data` |
+| `lc_` | Constant | `lc_max TYPE i VALUE 100` |
+
+### Field-Symbols (inside methods)
+
+| Prefix | Example |
+|--------|---------|
+| `<lv_>`, `<lt_>`, `<ls_>`, `<lo_>`, `<li_>` | `FIELD-SYMBOLS <ls_item> TYPE ty_item` |
+| `<comp>` | Allowed for generic component iteration |
+
+### Method Parameters
+
+| Direction | Prefix | Type |
+|-----------|--------|------|
+| IMPORTING | `iv_` | scalar |
+| IMPORTING | `it_` | table |
+| IMPORTING | `is_` | structure |
+| IMPORTING | `io_` | object ref |
+| IMPORTING | `ii_` | interface ref |
+| IMPORTING | `ix_` | exception ref |
+| RETURNING | `rv_` | scalar |
+| RETURNING | `rs_` | structure |
+| RETURNING | `rt_` | table |
+| RETURNING | `ro_` | object ref |
+| RETURNING | `ri_` | interface ref |
+| RETURNING | `rr_` | data ref |
+| EXPORTING | `ev_`, `es_`, `et_` | scalar / structure / table |
+| CHANGING  | `cv_`, `cs_`, `ct_` | scalar / structure / table |
+
+---
+
+## Quick Reference
+
+```abap
+" Local variables
+DATA lv_name    TYPE string.
+DATA lt_files   TYPE ty_files.
+DATA ls_result  TYPE ty_result.
+DATA lo_agent   TYPE REF TO zcl_abgagt_agent.
+DATA li_repo    TYPE REF TO zif_abapgit_repo.
+DATA lx_error   TYPE REF TO cx_static_check.
+FIELD-SYMBOLS <ls_item> TYPE ty_item.
+
+" Method signature
+METHODS process
+  IMPORTING
+    iv_url    TYPE string
+    it_files  TYPE ty_files
+    is_config TYPE ty_config
+    io_agent  TYPE REF TO zcl_abgagt_agent
+    ii_repo   TYPE REF TO zif_abapgit_repo
+  RETURNING
+    VALUE(rv_result) TYPE string.
+
+METHODS get_repo
+  RETURNING
+    VALUE(ro_repo) TYPE REF TO zcl_abgagt_agent.
+```
+
+---
+
+## Rule: Never Use Generic `lv_` for Objects, Tables, or Structures
+
+```abap
+" WRONG — abaplint will flag these
+DATA lv_repo    TYPE REF TO zcl_abgagt_agent.   " use lo_
+DATA lv_files   TYPE ty_files.                   " use lt_
+DATA lv_result  TYPE ty_result.                  " use ls_
+
+" CORRECT
+DATA lo_repo    TYPE REF TO zcl_abgagt_agent.
+DATA lt_files   TYPE ty_files.
+DATA ls_result  TYPE ty_result.
+```
+
+---
+
+## See Also
+
+- `.abaplint.json` — rule definitions (`local_variable_names`, `method_parameter_names`)
+- `guidelines/abaplint.md` — bundled guidance on `prefer_inline` trap

package/abap/guidelines/abaplint.md

@@ -0,0 +1,224 @@
+---
+layout: default
+title: abaplint Rule Guidelines
+nav_order: 17
+parent: ABAP Coding Guidelines
+grand_parent: ABAP Development
+---
+
+# abaplint Rule Guidelines
+
+**Searchable keywords**: abaplint, prefer_inline, inline declaration, char literal, string truncation,
+no_inline_in_optional_branches, fully_type_constants, linting, static analysis,
+run abaplint locally, check changed file, abapgit-agent lint,
+keyword_case, sequential_blank, double_space, use_new, local_variable_names
+
+This file covers rules that have **non-obvious or dangerous implications** — cases where applying
+a rule mechanically (or accepting its quickfix) can introduce subtle bugs.
+
+For project-specific rule guidance, add a `guidelines/abaplint-local.md` file to the project
+repository. The `ref` command searches both bundled and project guidelines automatically.
+
+---
+
+## prefer_inline — Inline Declarations
+
+### What the rule does
+
+Flags up-front `DATA` declarations and suggests replacing them with inline `DATA(var) = expr`:
+
+```abap
+* Bad (flagged by rule)
+DATA lv_count TYPE i.
+lv_count = lines( lt_table ).
+
+* Good (preferred by rule)
+DATA(lv_count) = lines( lt_table ).
+```
+
+This is safe when the RHS expression is a **function call, method call, or constructor
+operator** — because the return type is fully defined.
+
+### The char-literal trap — NEVER apply the quickfix here
+
+```
+❌ DANGEROUS: DATA(var) = 'literal'.
+```
+
+When the RHS is a quoted string literal, ABAP infers type `C LENGTH N` where N equals
+the exact character count of the literal. Any subsequent `&&` concatenation computes the
+correct longer string but **silently truncates it back to N characters**. The variable
+never grows beyond the length of its initial value.
+
+**This is the most dangerous quickfix the rule offers — it changes the runtime type.**
+
+```abap
+* WRONG — produced by prefer_inline quickfix, causes silent truncation
+DATA(lv_response) = '{"success":"X",'.      " → TYPE C LENGTH 16
+lv_response = lv_response && '"key":"val"'. " computed correctly, truncated to 16 chars
+" lv_response is STILL '{"success":"X",' — the && had no effect
+
+* CORRECT — use a string template to build the full value in one step
+DATA(lv_key) = condense( val = CONV string( li_repo->get_key( ) ) ).
+rv_result = |\{"success":"X","key":"{ lv_key }"\}|.
+
+* ALSO CORRECT — explicit TYPE string, safe to concatenate
+DATA lv_response TYPE string.
+lv_response = '{"success":"X",'.
+lv_response = lv_response && '"key":"val"}'.
+```
+
+### Safe vs unsafe patterns
+
+| Pattern | Safe? | Why |
+|---|---|---|
+| `DATA(n) = lines( lt_tab ).` | ✅ | Return type `I` — no truncation risk |
+| `DATA(lo) = NEW zcl_foo( ).` | ✅ | Object reference — fully typed |
+| `DATA(ls) = CORRESPONDING #( ls_src ).` | ✅ | Inherits structure type |
+| `DATA(lv) = lv_other.` | ✅ | Inherits type from source variable |
+| `SELECT ... INTO TABLE @DATA(lt).` | ✅ | Type from DB dictionary |
+| `DATA(lv) = 'literal'.` followed by `&&` | ❌ | Infers `C LENGTH N`, truncates |
+| `DATA(lv) = 'literal'.` used only in `\|{ lv }\|` | ⚠️ | Technically works but misleading — prefer explicit type |
+| `DATA(lv) = 'X'.` used as abap_bool flag | ✅ | `C LENGTH 1` is correct for flags |
+
+### Rule of thumb
+
+> If the inline-declared variable will ever appear on the left side of `&&`,
+> or be passed to a parameter typed `TYPE string`, declare it explicitly:
+> `DATA lv_foo TYPE string.`
+
+---
+
+## no_inline_in_optional_branches
+
+### What the rule does
+
+Flags inline `DATA(var)` declarations inside `IF`, `CASE/WHEN`, `LOOP`, `WHILE`, `DO`,
+and `SELECT` loops — branches that may not execute, leaving the variable uninitialized
+when code after the branch reads it.
+
+```abap
+* Bad (flagged)
+LOOP AT lt_items INTO DATA(ls_item).
+  DATA(lv_key) = ls_item-key.   " declared inside LOOP — only set when loop runs
+ENDLOOP.
+WRITE lv_key.                   " undefined if lt_items was empty
+
+* Good
+DATA lv_key TYPE string.
+LOOP AT lt_items INTO DATA(ls_item).
+  lv_key = ls_item-key.
+ENDLOOP.
+WRITE lv_key.
+```
+
+**Exception**: `TRY/CATCH/CLEANUP` is explicitly NOT considered an optional branch by
+the rule — inline declarations inside `TRY` are allowed.
+
+### When you see this rule triggered
+
+Move the `DATA(var)` declaration out of the branch to the top of the method, giving it
+an explicit type:
+
+```abap
+* Before (flagged)
+IF condition.
+  DATA(lv_result) = compute( ).
+ENDIF.
+
+* After (clean)
+DATA lv_result TYPE string.
+IF condition.
+  lv_result = compute( ).
+ENDIF.
+```
+
+---
+
+## Project-Specific Rule Overrides
+
+Each project can add its own abaplint guidance by creating a file in the `guidelines/`
+folder of the project repository:
+
+```
+guidelines/
+  abaplint-local.md    ← project-specific rule notes
+```
+
+After creating the file, export it so the `ref` command can find it:
+
+```bash
+abapgit-agent ref export
+```
+
+Then `abapgit-agent ref "prefer_inline"` will surface both this bundled guidance
+and the project-specific notes together.
+
+**Example `guidelines/abaplint-local.md`:**
+
+```markdown
+## prefer_inline — project rules
+
+This project's .abaplint.json enables prefer_inline.
+
+Additional constraint: never inline-declare response-building variables.
+All JSON response strings must use string templates (| ... |) directly
+on rv_result — no intermediate lv_response variable at all.
+```
+
+---
+
+## Running abaplint Locally Against Changed Files
+
+Run this before pushing to catch issues early, matching what CI does.
+
+```bash
+abapgit-agent lint
+```
+
+This automatically detects changed `.abap` files (via `git diff`), creates a scoped
+abaplint config for just those files, runs the check, and cleans up.
+
+### Options
+
+```bash
+# Diff against a specific base branch (useful on a feature branch)
+abapgit-agent lint --base main
+
+# Check specific files explicitly
+abapgit-agent lint --files src/zcl_foo.clas.abap,src/zcl_foo.clas.testclasses.abap
+
+# Use a different abaplint config (default: .abaplint.json)
+abapgit-agent lint --config .abaplint.json
+```
+
+Run repeatedly after each fix until you see:
+
+```
+abaplint: 0 issue(s) found, 1 file(s) analyzed
+```
+
+---
+
+### Common Issues and Fixes
+
+| Rule | Error message | Fix |
+|------|--------------|-----|
+| `keyword_case` | `Keyword should be upper case: "class"` | Uppercase the keyword: `CLASS` |
+| `sequential_blank` | `Remove sequential blank lines` | Max 1 blank line between blocks |
+| `local_variable_names` | `<fs_data> does not match pattern` | Use `l`-prefixed name: `<ls_data>` |
+| `double_space` | `Remove double space` | Single space around `=` in parameters |
+| `use_new` | `Use NEW #() to instantiate` | Replace `CREATE OBJECT mo_foo` → `mo_foo = NEW #( )` |
+| `method_parameter_names` | `Parameter name does not match pattern` | Use `iv_`, `it_`, `is_`, `io_` etc. prefixes |
+
+See **abaplint-local.md** for the full naming convention prefix reference.
+
+---
+
+
+## See Also
+
+- **common-errors.md** — char-literal truncation listed as a known error pattern
+- **json.md** — safe patterns for building JSON strings in ABAP
+- **workflow-detailed.md** — where abaplint fits in the development workflow
+- **abaplint-local.md** — naming convention reference (prefixes for variables, parameters, field-symbols)

package/abap/guidelines/branch-workflow.md

@@ -21,6 +21,7 @@ edit src/zcl_auth_handler.clas.abap
 
 # 3. Check syntax (CLAS/INTF/PROG/DDLS only, if independent)
 abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
+ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
 
 # 4. Commit
 git add src/zcl_auth_handler.clas.abap
@@ -112,6 +113,7 @@ git checkout main && git pull origin main
 git checkout -b feature/user-authentication
 edit src/zcl_auth_handler.clas.abap
 abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
+ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
 git add . && git commit -m "wip: add basic auth logic"
 git push origin feature/user-authentication
 git fetch origin main && git rebase origin/main
@@ -123,6 +125,8 @@ git fetch origin main && git rebase origin/main
 # If conflicts: resolve, git add, git rebase --continue
 git push origin feature/user-authentication --force-with-lease
 edit src/zcl_auth_handler.clas.abap
+abapgit-agent syntax --files src/zcl_auth_handler.clas.abap
+ls .abaplint.json 2>/dev/null && abapgit-agent lint   # abaplint (if configured)
 git add . && git commit -m "feat: complete auth logic"
 git push origin feature/user-authentication
 git fetch origin main && git rebase origin/main

package/abap/guidelines/cds-testing.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: CDS Testing
-nav_order: 17
+nav_order: 19
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/common-errors.md

@@ -89,7 +89,38 @@ Find data elements: `abapgit-agent view --objects <TABLE> --type TABL`
 
 ---
 
+## Inline Declaration from String Literal — Silent Truncation
+
+**Symptom**: A `&&` concatenation has no effect; the variable retains its initial value.
+
+**Root cause**: `DATA(var) = 'literal'` infers type `C LENGTH N` (N = literal length).
+Any subsequent `&&` computes the correct longer string but truncates it back to N chars.
+The abaplint `prefer_inline` quickfix can introduce this bug automatically.
+
+```abap
+* WRONG — lv_response stays '{"success":"X",' after && (16 chars, always truncated)
+DATA(lv_response) = '{"success":"X",'.
+lv_response = lv_response && '"key":"value"}'.   " no effect!
+
+* CORRECT — use string template
+DATA(lv_key) = condense( val = CONV string( li_repo->get_key( ) ) ).
+rv_result = |\{"success":"X","key":"{ lv_key }"\}|.
+
+* ALSO CORRECT — explicit TYPE string
+DATA lv_response TYPE string.
+lv_response = '{"success":"X",'.
+lv_response = lv_response && '"key":"value"}'.   " works correctly
+```
+
+**Fix**: Replace the inline declaration + `&&` chain with a string template,
+or declare the variable explicitly with `TYPE string`.
+
+→ See `abaplint.md` for full guidance on the `prefer_inline` rule.
+
+---
+
 ## See Also
 - **ABAP SQL** (sql.md) - for SQL syntax rules
 - **CDS Views** (cds.md) - for CDS selection patterns
 - **abapGit** (abapgit.md) - for XML metadata templates
+- **abaplint** (abaplint.md) - for abaplint rule guidance and known quickfix traps

package/abap/guidelines/index.md

@@ -30,6 +30,7 @@ This folder contains detailed ABAP coding guidelines that can be searched using
 | `workflow-detailed.md` | Development Workflow (Detailed) |
 | `object-creation.md` | Object Creation (XML metadata, local classes) |
 | `cds-testing.md` | CDS Testing (Test Double Framework) |
+| `abaplint.md` | abaplint Rule Guidelines (prefer_inline trap, safe patterns) |
 
 ## Usage
 

package/abap/guidelines/probe-poc.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Probe and PoC Guide
-nav_order: 19
+nav_order: 21
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/run-probe-classes.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: run Command Guide
-nav_order: 18
+nav_order: 20
 parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---

package/abap/guidelines/unit-testable-code.md

@@ -257,31 +257,11 @@ ENDMETHOD.
 
 ## Test Double Patterns
 
-### Manual Test Double (Local Class)
+**Prefer the ABAP Test Double Framework** (`cl_abap_testdouble`) over manual doubles.
+Use manual doubles only when stateful logic is required (e.g. call-count tracking, results that
+vary per call, or complex setup that configure_call cannot express).
 
-```abap
-" Create test double class
-CLASS ltd_mock_reader DEFINITION FOR TESTING.
-  PUBLIC SECTION.
-    INTERFACES zif_data_reader PARTIALLY IMPLEMENTED.
-    METHODS set_result_data
-      IMPORTING it_data TYPE ANY TABLE.
-  PRIVATE SECTION.
-    DATA mt_data TYPE ANY TABLE.
-ENDCLASS.
-
-CLASS ltd_mock_reader IMPLEMENTATION.
-  METHOD set_result_data.
-    mt_data = it_data.
-  ENDMETHOD.
-
-  METHOD zif_data_reader~read_all.
-    rt_data = mt_data.
-  ENDMETHOD.
-ENDCLASS.
-```
-
-### Using ABAP Test Double Framework
+### Using ABAP Test Double Framework (Recommended)
 
 ```abap
 " Step 1: Declare with correct interface type, then assign
@@ -315,6 +295,30 @@ lo_mock->my_method( ... ).
 - Use `returning(value = ...)` not `IMPORTING`
 - Call method after configure_call to register the configuration
 
+### Manual Test Double (Local Class — use only when stateful logic is needed)
+
+```abap
+" Create test double class
+CLASS ltd_mock_reader DEFINITION FOR TESTING.
+  PUBLIC SECTION.
+    INTERFACES zif_data_reader PARTIALLY IMPLEMENTED.
+    METHODS set_result_data
+      IMPORTING it_data TYPE ANY TABLE.
+  PRIVATE SECTION.
+    DATA mt_data TYPE ANY TABLE.
+ENDCLASS.
+
+CLASS ltd_mock_reader IMPLEMENTATION.
+  METHOD set_result_data.
+    mt_data = it_data.
+  ENDMETHOD.
+
+  METHOD zif_data_reader~read_all.
+    rt_data = mt_data.
+  ENDMETHOD.
+ENDCLASS.
+```
+
 ### Mocking EXPORT Parameters
 
 Some methods use EXPORT parameters instead of returning values. Use `set_parameter`:

package/abap/guidelines/workflow-detailed.md

@@ -24,9 +24,22 @@ grand_parent: ABAP Development
        │       │
        │       ├─► Errors? → Fix locally (no commit needed), re-run syntax
        │       │
+       │       └─► Clean ✅ → Proceed to 4b
+       │
+       └─► Other types (FUGR, TABL, etc.) → Skip syntax, go to 4b
+               │
+               ▼
+4b. abaplint (OPTIONAL — only if .abaplint.json exists in repo root)
+       │
+       ├─► .abaplint.json exists → npx @abaplint/cli .abaplint.json
+       │       │
+       │       ├─► Issues? → Fix locally, re-run abaplint
+       │       │   ⚠️  Before applying any quickfix: run abapgit-agent ref --topic abaplint
+       │       │       Quickfixes for prefer_inline can introduce silent type truncation bugs.
+       │       │
        │       └─► Clean ✅ → Proceed to commit
        │
-       └─► Other types (FUGR, TABL, etc.) → Skip syntax, go to commit
+       └─► No .abaplint.json → Skip, go to commit
                │
                ▼
 5. Commit and push → git add . && git commit && git push
@@ -140,8 +153,9 @@ git push
 abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zc_my_view.ddls.asddls
 ```
 
-**When to use syntax vs inspect vs view**:
-- **syntax**: Check LOCAL code BEFORE commit (CLAS, INTF, PROG, DDLS)
+**When to use syntax vs abaplint vs inspect vs view**:
+- **syntax**: Check LOCAL ABAP syntax BEFORE commit (CLAS, INTF, PROG, DDLS)
+- **abaplint**: Check LOCAL code style/quality BEFORE commit (only if .abaplint.json present)
 - **inspect**: Check ACTIVATED code AFTER pull (all types, runs Code Inspector)
 - **view**: Understand object STRUCTURE (not for debugging errors)
 
@@ -164,22 +178,25 @@ abapgit-agent pull --files src/zcl_my_class.clas.abap,src/zc_my_view.ddls.asddls
    └─ Unrelated bug fixes across files? → INDEPENDENT
 
 3. For SUPPORTED types (CLAS/INTF/PROG/DDLS):
-   ├─ INDEPENDENT files → Run syntax → Fix errors → Commit → Push → Pull
+   ├─ INDEPENDENT files → Run syntax → [abaplint if enabled] → Fix errors → Commit → Push → Pull
    │
    └─ DEPENDENT files (NEW objects):
        ├─ RECOMMENDED: Create underlying object first (interface, base class, etc.)
-       │   1. Create underlying object → Syntax → Commit → Push → Pull
-       │   2. Create dependent object → Syntax (works!) → Commit → Push → Pull
+       │   1. Create underlying object → Syntax → [abaplint] → Commit → Push → Pull
+       │   2. Create dependent object → Syntax (works!) → [abaplint] → Commit → Push → Pull
        │   ✅ Benefits: Both syntax checks work, cleaner workflow
        │
        └─ ALTERNATIVE: If interface design uncertain, commit both together
-           → Skip syntax → Commit both → Push → Pull → (if errors: inspect)
+           → Skip syntax → [abaplint] → Commit both → Push → Pull → (if errors: inspect)
 
 4. For UNSUPPORTED types (FUGR, TABL, etc.):
-   Write code → Skip syntax → Commit → Push → Pull → (if errors: inspect)
+   Write code → Skip syntax → [abaplint] → 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
+   Write all code → Run syntax on independent supported files ONLY → [abaplint] → Commit ALL → Push → Pull ALL
+
+[abaplint] = run npx @abaplint/cli .abaplint.json only if .abaplint.json exists in repo root
+             before applying any quickfix: run abapgit-agent ref --topic abaplint
 ```
 
 **Example workflows:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.13.6",
+  "version": "1.14.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",

package/src/commands/index.js

@@ -29,5 +29,6 @@ module.exports = {
   init:      require('./init'),
   pull:      require('./pull'),
   upgrade:   require('./upgrade'),
-  transport: require('./transport')
+  transport: require('./transport'),
+  lint:      require('./lint')
 };

package/src/commands/lint.js

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * lint command - Run abaplint on changed ABAP files
+ *
+ * Detects files changed relative to a base branch (or HEAD~1),
+ * creates a scoped abaplint config for just those files, and runs the check.
+ *
+ * Usage:
+ *   abapgit-agent lint
+ *   abapgit-agent lint --config .abaplint.json
+ *   abapgit-agent lint --base main
+ *   abapgit-agent lint --files src/foo.clas.abap,src/foo.clas.testclasses.abap
+ *   abapgit-agent lint --outformat checkstyle --outfile reports/abaplint-results.xml
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawnSync } = require('child_process');
+
+module.exports = {
+  name: 'lint',
+  description: 'Run abaplint on changed ABAP files',
+  requiresAbapConfig: false,
+
+  execute(args) {
+    const configPath  = argValue(args, '--config')    || '.abaplint.json';
+    const baseBranch  = argValue(args, '--base');
+    const filesArg    = argValue(args, '--files');
+    const outformat   = argValue(args, '--outformat');
+    const outfile     = argValue(args, '--outfile');
+
+    // ── Resolve changed files ─────────────────────────────────────────────────
+    let abapFiles;
+    if (filesArg) {
+      abapFiles = filesArg.split(',').map(f => f.trim()).filter(f => f.endsWith('.abap'));
+    } else {
+      abapFiles = detectChangedAbapFiles(baseBranch);
+    }
+
+    if (abapFiles.length === 0) {
+      console.log('No changed .abap files found — nothing to lint.');
+      return;
+    }
+
+    if (!outfile) {
+      console.log(`\nLinting ${abapFiles.length} file(s):`);
+      abapFiles.forEach(f => console.log(`  ${f}`));
+      console.log('');
+    }
+
+    // ── Load and scope the abaplint config ────────────────────────────────────
+    if (!fs.existsSync(configPath)) {
+      console.error(`Error: abaplint config not found: ${configPath}`);
+      console.error('Run from the project root, or pass --config <path>.');
+      process.exit(1);
+    }
+
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    cfg.global.files = abapFiles.map(f => `/${f}`);
+
+    const scopedConfig = '.abaplint-local.json';
+    fs.writeFileSync(scopedConfig, JSON.stringify(cfg, null, 2));
+
+    // ── Run abaplint ──────────────────────────────────────────────────────────
+    try {
+      const formatArgs = outformat ? `--outformat ${outformat}` : '';
+      const fileArgs   = outfile   ? `--outfile ${outfile}`     : '';
+      const result = spawnSync(
+        `npx @abaplint/cli@latest ${scopedConfig} ${formatArgs} ${fileArgs}`,
+        { stdio: 'inherit', shell: true }
+      );
+      if (result.status !== 0) {
+        process.exitCode = result.status;
+      }
+    } finally {
+      fs.unlinkSync(scopedConfig);
+    }
+  }
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function argValue(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+/**
+ * Detect changed .abap files using git diff.
+ * - If on a PR branch (CHANGE_TARGET set, e.g. in CI): diffs against that target.
+ * - If --base is given: diffs against that branch.
+ * - Otherwise: diffs HEAD~1..HEAD (last commit).
+ */
+function detectChangedAbapFiles(baseBranch) {
+  const base = baseBranch
+    || (process.env.CHANGE_TARGET ? `origin/${process.env.CHANGE_TARGET}` : null);
+
+  let diffCmd;
+  if (base) {
+    diffCmd = `git diff --name-only ${base}...HEAD -- '*.abap'`;
+  } else {
+    // Fall back to uncommitted changes first, then last commit
+    const uncommitted = runGit('git diff --name-only HEAD -- *.abap').filter(Boolean);
+    if (uncommitted.length > 0) return filterAbapFiles(uncommitted);
+    diffCmd = `git diff --name-only HEAD~1 HEAD -- '*.abap'`;
+  }
+
+  return filterAbapFiles(runGit(diffCmd));
+}
+
+function runGit(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf8' }).trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Keep only files that look like ABAP source files
+ * (name.type.abap or name.type.subtype.abap).
+ */
+function filterAbapFiles(files) {
+  return files.filter(f => {
+    const parts = path.basename(f).split('.');
+    return (parts.length === 3 || parts.length === 4) &&
+           parts[parts.length - 1].toLowerCase() === 'abap';
+  });
+}

package/src/utils/git-utils.js

@@ -40,7 +40,18 @@ function getBranch() {
 
   const content = fs.readFileSync(headPath, 'utf8').trim();
   const match = content.match(/ref: refs\/heads\/(.+)/);
-  return match ? match[1] : 'main';
+  if (match) return match[1];
+
+  // Detached HEAD (e.g. Jenkins checkout) — use Jenkins env vars:
+  // CHANGE_BRANCH is set in PR builds (actual head branch name),
+  // BRANCH_NAME is set in all builds (branch name or "PR-N" for PRs).
+  // For PR builds BRANCH_NAME is "PR-N" so prefer CHANGE_BRANCH first.
+  if (process.env.CHANGE_BRANCH) return process.env.CHANGE_BRANCH;
+  if (process.env.BRANCH_NAME && !process.env.BRANCH_NAME.startsWith('PR-')) {
+    return process.env.BRANCH_NAME;
+  }
+
+  return 'main';
 }
 
 /**