abapgit-agent 1.18.1 → 1.19.0

package/abap/CLAUDE.md

@@ -511,8 +511,7 @@ Never assume — wait for the user's answer before proceeding.
 1. **Always use `--json`** for ALL debug commands (`attach`, `vars`, `stack`, `step`) — human output is not machine-parseable. This is non-negotiable.
 2. **Attach BEFORE trigger** — start `debug attach --json` in background first, wait for `"Listener active"`, THEN fire the trigger (`unit`/`pull`/`run`)
 3. **Never pull to trigger** if a simpler trigger works — use `unit` when a test exists, `run` for a class runner; use `pull` only when the bug is specifically in the pull flow
-4. **Never pass `--session`** to `step/vars/stack` — it bypasses the daemon and causes errors
-5. **Always finish with `step --type continue --json`** — releases the frozen ABAP work process
+4. **Always finish with `step --type continue --json`** — releases the frozen ABAP work process
 
 **Finding the right line number for a breakpoint:**
 
@@ -700,7 +699,7 @@ abapgit-agent pull --files src/<name>.clas.abap --sync-xml  # --sync-xml amends
 ```
 
 <!-- AI-CONDENSED-START -->
-# AI Agent Instructions
+# AI Agent Quick Reference
 
 ## Step 1: Read project config before doing anything
 

package/abap/guidelines/abapgit-xml-only.md

@@ -6,9 +6,9 @@ parent: ABAP Coding Guidelines
 grand_parent: ABAP Development
 ---
 
-# abapGit XML Metadata — XML-Only Objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG)
+# abapGit XML Metadata — XML-Only Objects (TABL, STRU, DTEL, TTYP, DOMA, MSAG, SUSO)
 
-XML templates for ABAP Dictionary objects that have no `.abap` source file — TABL, STRU, DTEL, TTYP, DOMA, and message classes (MSAG).
+XML templates for ABAP Dictionary objects that have no `.abap` source file — TABL, STRU, DTEL, TTYP, DOMA, message classes (MSAG), and authorization objects (SUSO).
 
 > **CRITICAL: Always write XML files with a UTF-8 BOM (`\ufeff`) as the very first character**, before `<?xml ...`.
 > Without the BOM, abapGit shows the object as **"M" (modified)** after every pull.
@@ -19,7 +19,7 @@ XML templates for ABAP Dictionary objects that have no `.abap` source file — T
 > **For CLAS, INTF, PROG, DDLS, DCLS, FUGR** (have source files): see `abapgit-agent ref --topic abapgit`
 > **For DDLS, DCLS** (CDS — have source files): also see `abapgit-agent ref --topic abapgit`
 
-**Searchable keywords**: table xml, structure xml, data element xml, table type xml, domain xml, message class xml, tabl, stru, dtel, ttyp, doma, msag, dictionary
+**Searchable keywords**: table xml, structure xml, data element xml, table type xml, domain xml, message class xml, tabl, stru, dtel, ttyp, doma, msag, suso, authorization object, dictionary
 
 ---
 
@@ -451,3 +451,63 @@ abapGit uses the view `DD01V` as the root element (not `DD01L`). The serializer
 - `T100/TEXT`: Message text — use `&1`–`&4` for placeholders (serialized as `&amp;1`–`&amp;4` in XML)
 
 **Note**: The `<T100>` wrapper contains repeated `<T100>` child elements — one per message.
+
+---
+
+### Authorization Object (SUSO)
+
+**Filename**: `src/zmy_suso.suso.xml`
+
+> Pull with: `pull --files src/zmy_suso.suso.xml`
+>
+> View with: `view --objects ZMY_SUSO --type SUSO`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<abapGit version="v1.0.0" serializer="LCL_OBJECT_SUSO" serializer_version="v1.0.0">
+ <asx:abap xmlns:asx="http://www.sap.com/abapxml" version="1.0">
+  <asx:values>
+   <TOBJ>
+    <OBJCT>ZMY_SUSO</OBJCT>
+    <FIEL1>ACTVT</FIEL1>
+    <FIEL2>ZMY_FIELD</FIEL2>
+    <OCLSS>ZMY</OCLSS>
+   </TOBJ>
+   <TOBJT>
+    <LANGU>E</LANGU>
+    <OBJECT>ZMY_SUSO</OBJECT>
+    <TTEXT>My authorization object description</TTEXT>
+   </TOBJT>
+   <TOBJVORFLG>
+    <OBJCT>ZMY_SUSO</OBJCT>
+   </TOBJVORFLG>
+   <TACTZ>
+    <TACTZ>
+     <BROBJ>ZMY_SUSO</BROBJ>
+     <ACTVT>01</ACTVT>
+    </TACTZ>
+    <TACTZ>
+     <BROBJ>ZMY_SUSO</BROBJ>
+     <ACTVT>02</ACTVT>
+    </TACTZ>
+    <TACTZ>
+     <BROBJ>ZMY_SUSO</BROBJ>
+     <ACTVT>03</ACTVT>
+    </TACTZ>
+   </TACTZ>
+  </asx:values>
+ </asx:abap>
+</abapGit>
+```
+
+**Key Fields**:
+- `TOBJ/OBJCT`: Authorization object name — same as the filename stem
+- `TOBJ/FIEL1`–`FIEL0`: Up to 10 authorization fields (from SU20) that make up this object
+- `TOBJ/OCLSS`: Object class (4 chars) — groups related authorization objects (e.g. `AAAB`, `BC_A`)
+- `TOBJT/TTEXT`: Description text
+- `TOBJVORFLG`: Flags record — include with just `OBJCT` when no flags are set
+- `TACTZ`: Allowed activity values — one `<TACTZ>` entry per permitted `ACTVT` value
+
+**Note**: Authorization objects (SUSO) are the SU21 objects that group authorization fields (AUTH/SU20)
+together. An object like `AUD_SCOPEM` uses fields `ACTVT`, `BO_SERVICE`, and `AUD_GROUP`.
+

package/abap/guidelines/debug-session.md

@@ -148,7 +148,7 @@ abapgit-agent debug list    # confirm it was registered
 
 Best practice: individual sequential calls. Once the daemon is running and
 the session is saved to the state file, each `vars/stack/step` command is a
-plain standalone call — no `--session` flag needed.
+plain standalone call — the session is loaded automatically.
 
 ```bash
 # Start attach listener in background (spawns a daemon, saves session to state file)
@@ -183,7 +183,7 @@ done
 # "position" contains "line" and "isActive":true.  If position stays empty after the
 # trigger finishes, the breakpoint was missed — re-delete, re-set, re-attach, re-trigger.
 
-# Inspect and step — each is an individual call, no --session needed
+# Inspect and step — each is an individual call, session loaded automatically
 abapgit-agent debug stack --json
 abapgit-agent debug vars  --json
 abapgit-agent debug vars  --expand LS_OBJECT --json
@@ -202,7 +202,6 @@ rm -f /tmp/attach.json /tmp/trigger.json
 > 1. Wait for `"Listener active"` in the attach output before firing the trigger — this message is printed to stderr (captured in `attach.json`) the moment the listener POST is about to reach ADT. A blind `sleep` is not reliable under system load.
 > 2. **Always run the trigger in background (`&`)** — whether using `unit` or `run --class`. A foreground trigger blocks the terminal; if it is interrupted before the debug session completes, the ABAP work process is left frozen. The trigger must stay alive for the entire session.
 > 3. Always finish with `step --type continue` — this releases the frozen work process so the trigger can complete normally
-> 4. **Never pass `--session` to `step/vars/stack`** — it bypasses the daemon IPC and causes `noSessionAttached`. Omit it and let commands auto-load from the saved state file.
 
 **Step 3 — step through and inspect**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "files": [
     "bin/",
@@ -54,6 +54,7 @@
     "test:pull": "node tests/run-all.js --pull",
     "test:full-pull": "node tests/run-all.js --full-pull",
     "test:conflict": "node tests/run-all.js --conflict",
+    "test:async-pull": "node tests/run-all.js --async-pull",
     "pull": "node bin/abapgit-agent",
     "release": "node scripts/release.js",
     "unrelease": "node scripts/unrelease.js"

package/src/commands/debug.js

@@ -637,7 +637,6 @@ async function cmdDelete(args, config, adt) {
 // ─── Sub-command: attach ──────────────────────────────────────────────────────
 
 async function cmdAttach(args, config, adt) {
-  const sessionIdOverride = val(args, '--session');
   const jsonOutput = hasFlag(args, '--json');
   const pollTimeout = parseInt(val(args, '--timeout') || '30', 10);
   const maxListenSeconds = parseInt(val(args, '--max-listen') || '240', 10);
@@ -653,9 +652,8 @@ async function cmdAttach(args, config, adt) {
     process.stderr.write('\n  Waiting for breakpoint hit... (run your ABAP program in a separate window)\n');
   }
 
-  // Fresh session for attach flow. Don't set stateful here — CSRF fetch
-  // without stateful avoids tying up a dialog WP. Stateful is added per-call
-  // by debug-session.js STATEFUL_HEADER on attach/getStack/step/vars.
+  // Refresh session for the attach flow. Destroy the keepAlive agent to get
+  // a fresh TCP connection (old connections may carry stale server-side state).
   adt.clearSession();
   if (adt._axios) {
     const agent = adt._axios.defaults.httpsAgent || adt._axios.defaults.httpAgent;
@@ -669,30 +667,25 @@ async function cmdAttach(args, config, adt) {
   await adt.fetchCsrfToken();
 
   // Delete any stale listener registered under our terminalId from a previous
-  // (possibly crashed) run.  A frozen ABAP work process holding a listener for
-  // the same terminalId causes SAP ICM to return HTTP 400 "Service cannot be
-  // reached" for every new listener POST.  Deleting first clears that state.
-  // Ignore errors — there may be no stale listener to delete.
-  if (!sessionIdOverride) {
-    try {
-      const delUrl = `/sap/bc/adt/debugger/listeners` +
-        `?debuggingMode=user` +
-        `&requestUser=${encodeURIComponent((config.user || '').toUpperCase())}` +
-        `&terminalId=${encodeURIComponent(ADT_CLIENT_ID)}` +
-        `&ideId=${encodeURIComponent(ADT_CLIENT_ID)}` +
-        `&checkConflict=false` +
-        `&notifyConflict=true`;
-      await adt.delete(delUrl);
-      if (jsonOutput) process.stderr.write(`[debug-attach] deleted stale listener\n`);
-    } catch (e) {
-      if (jsonOutput) process.stderr.write(`[debug-attach] delete listener (cleanup): ${e.statusCode || e.message}\n`);
-    }
+  // (possibly crashed) run.
+  try {
+    const delUrl = `/sap/bc/adt/debugger/listeners` +
+      `?debuggingMode=user` +
+      `&requestUser=${encodeURIComponent((config.user || '').toUpperCase())}` +
+      `&terminalId=${encodeURIComponent(ADT_CLIENT_ID)}` +
+      `&ideId=${encodeURIComponent(ADT_CLIENT_ID)}` +
+      `&checkConflict=false` +
+      `&notifyConflict=true`;
+    await adt.delete(delUrl);
+    if (jsonOutput) process.stderr.write(`[debug-attach] deleted stale listener\n`);
+  } catch (e) {
+    if (jsonOutput) process.stderr.write(`[debug-attach] delete listener (cleanup): ${e.statusCode || e.message}\n`);
   }
 
   // Re-POST local breakpoints to refresh them on the server before listening.
   // Breakpoints expire when the SAP session or work process is restarted.
   // This ensures they are active regardless of when they were originally set.
-  if (!sessionIdOverride) {
+  {
     const localBps = _loadBpState ? _loadBpState(config) : [];
     if (localBps.length === 0) {
       console.error('\n  No breakpoints set. Use "debug set --object <name> --line <n>" first.\n');
@@ -700,6 +693,9 @@ async function cmdAttach(args, config, adt) {
     }
     const { valid, stale } = await refreshBreakpoints(config, adt, localBps);
     if (_saveBpState) _saveBpState(config, valid);
+    if (jsonOutput && valid.length > 0) {
+      process.stderr.write(`[debug-attach] refreshed ${valid.length} breakpoint(s)\n`);
+    }
     if (stale.length > 0 && !jsonOutput) {
       process.stderr.write(`  Warning: ${stale.length} breakpoint(s) could not be registered (invalid position):\n`);
       stale.forEach(({ object, line, error }) => {
@@ -711,11 +707,11 @@ async function cmdAttach(args, config, adt) {
       process.exit(1);
     }
   }
-  let sessionId = sessionIdOverride;
+  let sessionId = null;
   let positionResult = null;
   let session = null;
 
-  if (!sessionId) {
+  {
     // ADT listeners: POST long-polls until a breakpoint is hit (or timeout).
     // On breakpoint hit the response body contains <DEBUGGEE_ID>; on timeout
     // (no breakpoint) returns 200 with empty body — poll again.
@@ -845,8 +841,8 @@ async function cmdAttach(args, config, adt) {
             process.exit(1);
           }
           // attach() succeeded — skip getPosition() validation.
-          // With keepAlive, the connection is shared and getStack via the
-          // in-process daemon will use the same AdtHttp + same TCP socket.
+          // The in-process daemon shares the same AdtHttp instance, so
+          // getStack/vars/step via IPC use the identical TCP connection.
           positionResult = { position: {}, source: [] };
           session = candidateSession;
         }
@@ -881,20 +877,7 @@ async function cmdAttach(args, config, adt) {
     }
   }
 
-  // When using --session override (no listener), do attach+getPosition here.
-  if (sessionIdOverride) {
-    session = new DebugSession(adt, sessionId);
-    // getPosition is best-effort for --session override (e.g. human REPL recovery)
-    try {
-      positionResult = await session.getPosition();
-    } catch (e) {
-      positionResult = { position: {}, source: [] };
-    }
-  }
-
-  // session and positionResult are now set (either via listener loop or --session override)
   if (!session) {
-    // Should not reach here — listener loop either sets session or exits
     console.error('\n  Internal error: session not initialized after attach.\n');
     process.exit(1);
   }

package/src/commands/inspect.js

@@ -24,15 +24,17 @@ function escapeXml(str) {
  * Maps to JUnit schema:
  *   <testsuites>
  *     <testsuite name="CLAS ZCL_MY_CLASS" tests="N" failures="F" errors="0">
- *       <testcase name="Syntax check" classname="ZCL_MY_CLASS">
- *         <failure type="SyntaxError" message="...">line/col/method detail</failure>
+ *       <testcase name="Inspect / Syntax check" classname="ZCL_MY_CLASS"/>   ← clean
+ *       <testcase name="Inspect / CL_CI_TEST_EXCEPTION/UNHANDLED_01"         ← finding
+ *                classname="ZCL_MY_CLASS">
+ *         <failure type="SyntaxError" message="...">method/line/detail</failure>
  *       </testcase>
  *     </testsuite>
  *   </testsuites>
  *
- * One testsuite per object. Each error becomes a <failure>. Warnings become
- * a single <failure type="Warning"> so they are visible but don't fail the build
- * unless there are also hard errors (Jenkins distinguishes failure vs unstable).
+ * One testsuite per object. Each error/warning becomes its own testcase named
+ * after the SCI check rule (check_class/check_code) so Jenkins shows exactly
+ * which rule fired. Clean objects get a single passing testcase.
  */
 function buildInspectJUnit(results) {
   const suites = results.map(res => {
@@ -42,28 +44,30 @@ function buildInspectJUnit(results) {
     const warnings   = res.WARNINGS !== undefined ? res.WARNINGS : (res.warnings || []);
     const errorCount = errors.length;
     const warnCount  = warnings.length;
-    // One testcase per error/warning; at least one testcase for a clean object
     const testCount  = Math.max(1, errorCount + warnCount);
 
     const testcases = [];
 
     if (errorCount === 0 && warnCount === 0) {
-      testcases.push(`    <testcase name="Syntax check" classname="${escapeXml(objectName)}"/>`);
+      testcases.push(`    <testcase name="Inspect / Syntax check" classname="${escapeXml(objectName)}"/>`);
     }
 
     for (const err of errors) {
-      const line       = err.LINE       || err.line       || '?';
-      const column     = err.COLUMN     || err.column     || '?';
-      const text       = err.TEXT       || err.text       || 'Unknown error';
+      const line       = err.LINE        || err.line        || '?';
+      const column     = err.COLUMN      || err.column      || '?';
+      const text       = err.TEXT        || err.text        || 'Unknown error';
       const methodName = err.METHOD_NAME || err.method_name;
-      const sobjname   = err.SOBJNAME   || err.sobjname   || '';
+      const sobjname   = err.SOBJNAME    || err.sobjname    || '';
+      const checkClass = err.CHECK_CLASS || err.check_class || '';
+      const checkCode  = err.CHECK_CODE  || err.check_code  || '';
       const detail     = [
         methodName ? `Method: ${methodName}` : null,
         `Line ${line}, Column ${column}`,
         sobjname ? `Include: ${sobjname}` : null,
         text
       ].filter(Boolean).join('\n');
-      const caseName = methodName ? `${methodName} line ${line}` : `Line ${line}`;
+      const checkId  = checkClass && checkCode ? `${checkClass}/${checkCode}` : null;
+      const caseName = checkId ? `Inspect / ${checkId}` : (methodName ? `${methodName} line ${line}` : `Line ${line}`);
       testcases.push(
         `    <testcase name="${escapeXml(caseName)}" classname="${escapeXml(objectName)}">\n` +
         `      <failure type="SyntaxError" message="${escapeXml(text)}">${escapeXml(detail)}</failure>\n` +
@@ -72,17 +76,20 @@ function buildInspectJUnit(results) {
     }
 
     for (const warn of warnings) {
-      const line       = warn.LINE       || warn.line       || '?';
-      const text       = warn.MESSAGE    || warn.message    || warn.TEXT || warn.text || 'Warning';
+      const line       = warn.LINE        || warn.line        || '?';
+      const text       = warn.MESSAGE     || warn.message     || warn.TEXT || warn.text || 'Warning';
       const methodName = warn.METHOD_NAME || warn.method_name;
-      const sobjname   = warn.SOBJNAME   || warn.sobjname   || '';
+      const sobjname   = warn.SOBJNAME    || warn.sobjname    || '';
+      const checkClass = warn.CHECK_CLASS || warn.check_class || '';
+      const checkCode  = warn.CHECK_CODE  || warn.check_code  || '';
       const detail     = [
         methodName ? `Method: ${methodName}` : null,
         `Line ${line}`,
         sobjname ? `Include: ${sobjname}` : null,
         text
       ].filter(Boolean).join('\n');
-      const caseName = methodName ? `${methodName} line ${line} (warning)` : `Line ${line} (warning)`;
+      const checkId  = checkClass && checkCode ? `${checkClass}/${checkCode}` : null;
+      const caseName = checkId ? `Inspect / ${checkId}` : (methodName ? `${methodName} line ${line}` : `Line ${line}`);
       testcases.push(
         `    <testcase name="${escapeXml(caseName)}" classname="${escapeXml(objectName)}">\n` +
         `      <failure type="Warning" message="${escapeXml(text)}">${escapeXml(detail)}</failure>\n` +
@@ -107,8 +114,10 @@ function buildInspectJUnit(results) {
 }
 
 /**
- * Inspect all files in one request
+ * Inspect a single batch of files in one request (max CHUNK_SIZE files)
  */
+const CHUNK_SIZE = 10;
+
 async function inspectAllFiles(files, csrfToken, config, variant, http, verbose = false) {
   // Convert files to uppercase names
   const fileNames = files.map(f => {
@@ -152,6 +161,66 @@ async function inspectAllFiles(files, csrfToken, config, variant, http, verbose
   }
 }
 
+/**
+ * Apply inspect.suppress rules to a single result — downgrade matching errors/warnings to infos.
+ */
+function applySuppressRules(result, suppressRules) {
+  if (!suppressRules || suppressRules.length === 0) return;
+  const objName = (result.OBJECT_NAME || result.object_name || '').toUpperCase();
+  for (const rule of suppressRules) {
+    const objPattern = new RegExp('^' + (rule.object || '*').toUpperCase().replace(/\*/g, '.*') + '$');
+    if (!objPattern.test(objName)) continue;
+    const msgPattern = new RegExp((rule.message || '*').replace(/\*/g, '.*'), 'i');
+
+    const errors = result.ERRORS || result.errors || [];
+    const kept = [];
+    for (const err of errors) {
+      const text = err.TEXT || err.text || '';
+      if (msgPattern.test(text)) {
+        const infos = result.INFOS || result.infos || [];
+        infos.push({ ...err, MESSAGE: `[suppressed] ${text}`, message: `[suppressed] ${text}` });
+        if (result.INFOS !== undefined) result.INFOS = infos; else result.infos = infos;
+        const ec = result.ERROR_COUNT !== undefined ? 'ERROR_COUNT' : 'error_count';
+        result[ec] = Math.max(0, (result[ec] || 0) - 1);
+      } else {
+        kept.push(err);
+      }
+    }
+    if (result.ERRORS !== undefined) result.ERRORS = kept; else result.errors = kept;
+
+    const warnings = result.WARNINGS || result.warnings || [];
+    const keptW = [];
+    for (const warn of warnings) {
+      const text = warn.MESSAGE || warn.message || '';
+      if (msgPattern.test(text)) {
+        const infos = result.INFOS || result.infos || [];
+        infos.push({ ...warn, MESSAGE: `[suppressed] ${text}`, message: `[suppressed] ${text}` });
+        if (result.INFOS !== undefined) result.INFOS = infos; else result.infos = infos;
+      } else {
+        keptW.push(warn);
+      }
+    }
+    if (result.WARNINGS !== undefined) result.WARNINGS = keptW; else result.warnings = keptW;
+  }
+}
+
+/**
+ * Split files into chunks and inspect each sequentially, combining results.
+ * Calls onChunkResult(result) for each object result as chunks complete.
+ */
+async function inspectInChunks(files, csrfToken, config, variant, http, verbose = false, onChunkResult = null) {
+  const results = [];
+  for (let i = 0; i < files.length; i += CHUNK_SIZE) {
+    const chunk = files.slice(i, i + CHUNK_SIZE);
+    const chunkResults = await inspectAllFiles(chunk, csrfToken, config, variant, http, verbose);
+    for (const result of chunkResults) {
+      results.push(result);
+      if (onChunkResult) onChunkResult(result);
+    }
+  }
+  return results;
+}
+
 /**
  * Process a single inspect result
  */
@@ -181,6 +250,8 @@ async function processInspectResult(res) {
       const text = err.TEXT || err.text || 'Unknown error';
       const methodName = err.METHOD_NAME || err.method_name;
       const sobjname = err.SOBJNAME || err.sobjname;
+      const checkClass = err.CHECK_CLASS || err.check_class || '';
+      const checkCode  = err.CHECK_CODE  || err.check_code  || '';
 
       if (methodName) {
         console.log(`  Method: ${methodName}`);
@@ -190,6 +261,10 @@ async function processInspectResult(res) {
         console.log(`    Include: ${sobjname}`);
       }
       console.log(`    ${text}`);
+      if (checkCode) {
+        console.log(`    [${checkClass}/${checkCode}]`);
+        console.log(`    → abapgit-agent inspect --doc ${checkClass}/${checkCode}`);
+      }
       console.log('');
     }
 
@@ -202,6 +277,8 @@ async function processInspectResult(res) {
         const text = warn.MESSAGE || warn.message || 'Unknown warning';
         const methodName = warn.METHOD_NAME || warn.method_name;
         const sobjname = warn.SOBJNAME || warn.sobjname;
+        const checkClass = warn.CHECK_CLASS || warn.check_class || '';
+        const checkCode  = warn.CHECK_CODE  || warn.check_code  || '';
 
         if (methodName) {
           console.log(`  Method: ${methodName}`);
@@ -211,6 +288,10 @@ async function processInspectResult(res) {
           console.log(`    Include: ${sobjname}`);
         }
         console.log(`    ${text}`);
+        if (checkCode) {
+          console.log(`    [${checkClass}/${checkCode}]`);
+          console.log(`    → abapgit-agent inspect --doc ${checkClass}/${checkCode}`);
+        }
       }
     }
 
@@ -223,6 +304,8 @@ async function processInspectResult(res) {
         const text = info.MESSAGE || info.message || 'Unknown info';
         const methodName = info.METHOD_NAME || info.method_name;
         const sobjname = info.SOBJNAME || info.sobjname;
+        const checkClass = info.CHECK_CLASS || info.check_class || '';
+        const checkCode  = info.CHECK_CODE  || info.check_code  || '';
 
         if (methodName) {
           console.log(`  Method: ${methodName}`);
@@ -232,6 +315,10 @@ async function processInspectResult(res) {
           console.log(`    Include: ${sobjname}`);
         }
         console.log(`    ${text}`);
+        if (checkCode) {
+          console.log(`    [${checkClass}/${checkCode}]`);
+          console.log(`    → abapgit-agent inspect --doc ${checkClass}/${checkCode}`);
+        }
       }
     }
   } else if (success === true || success === 'X') {
@@ -254,25 +341,78 @@ module.exports = {
       console.log(`
 Usage:
   abapgit-agent inspect --files <file1>,<file2>,... [--variant <check-variant>] [--junit-output <file>] [--json]
+  abapgit-agent inspect --doc <check_class>/<check_code>
 
 Description:
   Run SAP Code Inspector checks on activated ABAP objects. Requires the objects
   to be already active in the ABAP system (run pull first).
 
+  Use --doc to fetch the SAP documentation for a specific check finding.
+  The check class and code are shown in brackets after each finding, e.g.:
+    [CL_CI_TEST_OMIT_BRACKETS/OMIT_01]
+
 Parameters:
-  --files <file1,...>       Comma-separated ABAP source files (required).
+  --files <file1,...>       Comma-separated ABAP source files (required for inspection).
   --variant <variant>       Code Inspector variant (default: system default).
   --junit-output <file>     Write results as JUnit XML to this file.
   --json                    Output as JSON.
+  --doc <class>/<code>      Fetch documentation for a check finding.
 
 Examples:
   abapgit-agent inspect --files src/zcl_my_class.clas.abap
   abapgit-agent inspect --files src/zcl_my_class.clas.abap --variant ALL_CHECKS
   abapgit-agent inspect --files src/zcl_my_class.clas.abap --junit-output reports/inspect.xml
+  abapgit-agent inspect --doc CL_CI_TEST_OMIT_BRACKETS/OMIT_01
 `);
       return;
     }
 
+    // --doc mode: fetch documentation for a check finding
+    const docArgIndex = args.indexOf('--doc');
+    if (docArgIndex !== -1) {
+      const docArg = args[docArgIndex + 1];
+      if (!docArg || !docArg.includes('/')) {
+        console.error('Error: --doc requires <check_class>/<check_code>');
+        console.error('Example: abapgit-agent inspect --doc CL_CI_TEST_OMIT_BRACKETS/OMIT_01');
+        process.exit(1);
+      }
+      const slashIdx = docArg.indexOf('/');
+      const checkClass = docArg.slice(0, slashIdx);
+      const checkCode  = docArg.slice(slashIdx + 1);
+
+      const config = loadConfig();
+      const http = new AbapHttp(config);
+      const csrfToken = await http.fetchCsrfToken();
+
+      try {
+        const result = await http.post('/sap/bc/z_abapgit_agent/insp_doc', {
+          check_class: checkClass,
+          check_code:  checkCode
+        }, { csrfToken });
+
+        const title = result.TITLE || result.title || '';
+        let   text  = result.TEXT  || result.text  || '';
+
+        // Strip ITF inline tags (<AB>, <EX>, </>, <DS:...>, etc.), HTML tags, and ITF placeholders (&...&)
+        text = text
+          .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+          .replace(/<[^>]+>/g, '')
+          .replace(/&[A-Z_]+&/g, '')
+          .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+          .replace(/&nbsp;/g, ' ').replace(/&#160;/g, ' ')
+          .replace(/\n{3,}/g, '\n\n')
+          .trim();
+
+        if (title) console.log(`\n${title}\n${'─'.repeat(Math.min(title.length, 60))}`);
+        console.log(`\n${text || 'No documentation available.'}\n`);
+      } catch (error) {
+        const { printHttpError } = require('../utils/format-error');
+        printHttpError(error, { verbose: args.includes('--verbose') });
+        process.exit(1);
+      }
+      return;
+    }
+
     const jsonOutput = args.includes('--json');
     const verbose = args.includes('--verbose');
     const filesArgIndex = args.indexOf('--files');
@@ -285,7 +425,7 @@ Examples:
       process.exit(1);
     }
 
-    let filesSyntaxCheck = args[filesArgIndex + 1].split(',').map(f => f.trim());
+    let filesSyntaxCheck = [...new Set(args[filesArgIndex + 1].split(',').map(f => f.trim()))];
 
     // Parse optional --variant parameter; fall back to project config
     const variantArgIndex = args.indexOf('--variant');
@@ -338,51 +478,23 @@ Examples:
     const http = new AbapHttp(config);
     const csrfToken = await http.fetchCsrfToken();
 
-    // Send all files in one request
-    const results = await inspectAllFiles(filesSyntaxCheck, csrfToken, config, variant, http, verbose);
-
-    // Apply inspect.suppress rules — downgrade matching errors/warnings to infos
     const suppressRules = inspectConfig.suppress || [];
-    if (suppressRules.length > 0) {
+    let hasErrors = false;
+
+    // Stream results: apply suppress and print each object as its chunk completes
+    const onChunkResult = jsonOutput ? null : async (result) => {
+      applySuppressRules(result, suppressRules);
+      await processInspectResult(result);
+      const errorCount = result.ERROR_COUNT !== undefined ? result.ERROR_COUNT : (result.error_count || 0);
+      if (errorCount > 0) hasErrors = true;
+    };
+
+    const results = await inspectInChunks(filesSyntaxCheck, csrfToken, config, variant, http, verbose, onChunkResult);
+
+    // For JSON mode, apply suppress rules now (they were skipped during streaming)
+    if (jsonOutput) {
       for (const result of results) {
-        const objName = (result.OBJECT_NAME || result.object_name || '').toUpperCase();
-        for (const rule of suppressRules) {
-          const objPattern = new RegExp('^' + (rule.object || '*').toUpperCase().replace(/\*/g, '.*') + '$');
-          if (!objPattern.test(objName)) continue;
-          const msgPattern = new RegExp((rule.message || '*').replace(/\*/g, '.*'), 'i');
-
-          // Downgrade matching errors → infos
-          const errors = result.ERRORS || result.errors || [];
-          const kept = [];
-          for (const err of errors) {
-            const text = err.TEXT || err.text || '';
-            if (msgPattern.test(text)) {
-              const infos = result.INFOS || result.infos || [];
-              infos.push({ ...err, MESSAGE: `[suppressed] ${text}`, message: `[suppressed] ${text}` });
-              if (result.INFOS !== undefined) result.INFOS = infos; else result.infos = infos;
-              const ec = result.ERROR_COUNT !== undefined ? 'ERROR_COUNT' : 'error_count';
-              result[ec] = Math.max(0, (result[ec] || 0) - 1);
-            } else {
-              kept.push(err);
-            }
-          }
-          if (result.ERRORS !== undefined) result.ERRORS = kept; else result.errors = kept;
-
-          // Downgrade matching warnings → infos
-          const warnings = result.WARNINGS || result.warnings || [];
-          const keptW = [];
-          for (const warn of warnings) {
-            const text = warn.MESSAGE || warn.message || '';
-            if (msgPattern.test(text)) {
-              const infos = result.INFOS || result.infos || [];
-              infos.push({ ...warn, MESSAGE: `[suppressed] ${text}`, message: `[suppressed] ${text}` });
-              if (result.INFOS !== undefined) result.INFOS = infos; else result.infos = infos;
-            } else {
-              keptW.push(warn);
-            }
-          }
-          if (result.WARNINGS !== undefined) result.WARNINGS = keptW; else result.warnings = keptW;
-        }
+        applySuppressRules(result, suppressRules);
       }
     }
 
@@ -408,14 +520,6 @@ Examples:
       return;
     }
 
-    // Process results
-    let hasErrors = false;
-    for (const result of results) {
-      await processInspectResult(result);
-      const errorCount = result.ERROR_COUNT !== undefined ? result.ERROR_COUNT : (result.error_count || 0);
-      if (errorCount > 0) hasErrors = true;
-    }
-
     if (hasErrors) {
       process.exit(1);
     }