abapgit-agent 1.12.1 → 1.13.0

package/abap/guidelines/cds.md

@@ -8,7 +8,7 @@ grand_parent: ABAP Development
 
 # Creating CDS Views
 
-**Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption
+**Searchable keywords**: CDS, DDL, DDLS, CDS view, @AbapCatalog, @AccessControl, association, projection, consumption, GROUP BY, aggregation, subquery, JOIN
 
 ## TOPICS IN THIS FILE
 1. File Naming - line 96
@@ -145,20 +145,13 @@ where devclass not like '$%'
 
 1. **Avoid reserved words** - Field names like `PACKAGE`, `CLASS`, `INTERFACE` are reserved in CDS. Use alternatives like `PackageName`, `ClassName`.
 
-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"
+2. **Workflow for creating CDS views** — run: `abapgit-agent ref --topic workflow-detailed`
 
 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"
 
 ### Activating CDS Views
 
-**For standard workflow, see `../CLAUDE.md`**
-
-**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)
+→ See `abapgit-agent ref --topic workflow-detailed` for the complete workflow.
 
 ## CDS View Entity Features
 
@@ -196,6 +189,39 @@ where devclass not like '$%'
 
 ## CDS Best Practices and Common Patterns
 
+### No Inline Subqueries — Use JOIN + GROUP BY Instead
+
+**CDS view entities do NOT support inline subqueries in JOIN.** This is a hard syntax error:
+
+❌ **WRONG — inline subquery (syntax error)**:
+```abap
+define view entity ZC_MyView as select from zheader as Header
+  inner join (                          // ← NOT SUPPORTED
+    select docid, sum( amount ) as Total
+    from zitems
+    group by docid
+  ) as Items on Items.docid = Header.docid ...
+```
+
+✅ **CORRECT — JOIN base tables directly, use GROUP BY on the outer view**:
+```abap
+define view entity ZC_MyView
+  as select from zheader as Header
+    inner join zitems as Item
+      on Item.docid = Header.docid
+{
+  key Header.docid       as DocId,
+      Header.description as Description,
+      count(*)           as NumberOfItems,
+      sum(Item.amount)   as TotalAmount
+}
+group by Header.docid, Header.description
+```
+
+**This works.** CDS supports JOIN + GROUP BY + aggregation functions in a single view. Only inline subqueries in the FROM/JOIN clause are unsupported.
+
+---
+
 ### Key Field Ordering (STRICT RULE)
 
 CDS views enforce strict key field ordering that differs from regular SQL:
@@ -235,6 +261,8 @@ CDS views enforce strict key field ordering that differs from regular SQL:
 
 ### Currency/Amount Field Aggregation
 
+> **Design principle**: Prefer a **single CDS view** with JOIN + GROUP BY. Only split into multiple layered views when requirements specifically need reusable intermediate aggregations shared across different consumers.
+
 When aggregating currency or amount fields in CDS views, use semantic annotations instead of complex casting:
 
 ❌ **WRONG - Complex casting (will fail)**:

package/abap/guidelines/testing.md

@@ -290,6 +290,49 @@ METHOD test_aggregation.
 ENDMETHOD.
 ```
 
+### Testing CDS Views that Select from Another CDS View
+
+> **Note:** This pattern applies when your design **already has** a CDS view that selects from another CDS view. It does NOT mean you should split a single view into two — use a single CDS view with GROUP BY / JOIN when the business logic fits.
+
+When your CDS view selects from **another CDS view** (not a base table), `create` will raise `CX_CDS_FAILURE`. Use `create_for_multiple_cds` instead and list all CDS entities in the dependency chain.
+
+```abap
+METHOD class_setup.
+  " ZC_TopView selects from ZC_IntermediateView (another CDS view entity)
+  " → must use create_for_multiple_cds and list all CDS entities
+  mo_cds_env_static = cl_cds_test_environment=>create_for_multiple_cds(
+    i_for_entities = VALUE #(
+      ( 'ZC_TOPVIEW' )           " the view under test
+      ( 'ZC_INTERMEDIATEVIEW' )  " the CDS view it selects from
+    ) ).
+ENDMETHOD.
+```
+
+Insert test data into the intermediate CDS view (not the base tables), since that is what the top-level view reads:
+
+```abap
+METHOD test_read.
+  DATA lt_source TYPE TABLE OF zc_intermediateview WITH EMPTY KEY.
+  lt_source = VALUE #(
+    ( field1 = 'A' field2 = 100 )
+    ( field1 = 'B' field2 = 200 ) ).
+  mo_cds_env->insert_test_data( i_data = lt_source ).
+
+  SELECT * FROM zc_topview INTO TABLE @DATA(lt_result).
+
+  cl_abap_unit_assert=>assert_equals(
+    exp = 2  act = lines( lt_result )  msg = 'Expected 2 rows' ).
+ENDMETHOD.
+```
+
+**Rules:**
+- List the view under test **and all CDS views it depends on** in `i_for_entities`
+- Insert data into the **direct source** of the top-level view (the intermediate CDS view)
+- Order in `i_for_entities` does not matter
+- If you get `CX_CDS_FAILURE` when using `create`, switch to `create_for_multiple_cds`
+
+---
+
 ### Key Classes for CDS Testing
 
 | Item | Type/Usage |
@@ -304,7 +347,8 @@ ENDMETHOD.
 
 | Method | Purpose |
 |--------|---------|
-| `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Create test environment (returns `if_cds_test_environment`) |
+| `CL_CDS_TEST_ENVIRONMENT=>create( i_for_entity = ... )` | Create test environment for a CDS view over base tables |
+| `CL_CDS_TEST_ENVIRONMENT=>create_for_multiple_cds( i_for_entities = ... )` | Create test environment when the CDS view selects from another CDS view |
 | `insert_test_data( i_data = ... )` | Insert test data into test doubles |
 | `clear_doubles` | Clear test data before each test method |
 | `destroy` | Clean up after test class |
@@ -314,7 +358,7 @@ ENDMETHOD.
 1. **Use interface type**: `DATA mo_cds_env TYPE REF TO if_cds_test_environment` - the CREATE method returns an interface reference
 2. **CLASS-METHODS required**: `class_setup` and `class_teardown` must be declared with `CLASS-METHODS` (not `METHODS`)
 3. **Table type declaration**: Must declare `DATA lt_tab TYPE TABLE OF <type> WITH EMPTY KEY` before using `VALUE #()`
-4. **Auto-created dependencies**: CDS framework auto-creates test doubles for base tables - do not specify `i_dependency_list`
+4. **Auto-created dependencies**: When the CDS view selects only from **base tables**, the framework auto-creates test doubles — do not specify `i_dependency_list`. When the CDS view selects from **another CDS view**, use `create_for_multiple_cds` instead (see section below).
 5. **Aggregations**: For CDS views with SUM/COUNT/GROUP BY, insert test data into base tables (SFLIGHT, SCARR, etc.)
 6. **Clear doubles**: Call `clear_doubles` in `setup` method before each test
 7. **Enable associations**: Set `test_associations = 'X'` only if testing CDS associations

package/bin/abapgit-agent

@@ -54,6 +54,7 @@ async function main() {
     debug: require('../src/commands/debug'),
     run: require('../src/commands/run'),
     ref: require('../src/commands/ref'),
+    guide: require('../src/commands/guide'),
     init: require('../src/commands/init'),
     pull: require('../src/commands/pull'),
     upgrade: require('../src/commands/upgrade'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abapgit-agent",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "description": "ABAP Git Agent - Pull and activate ABAP code via abapGit from any git repository",
   "main": "src/index.js",
   "files": [
@@ -8,7 +8,9 @@
     "src/",
     "abap/guidelines/",
     "abap/CLAUDE.md",
+    "abap/CLAUDE.slim.md",
     "abap/.github/copilot-instructions.md",
+    "abap/.github/copilot-instructions.slim.md",
     ".abapGitAgent.example"
   ],
   "bin": {

package/src/commands/guide.js

@@ -0,0 +1,276 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// Marker present in the old full-guide CLAUDE.md (copied by init before this feature)
+const FULL_GUIDE_MARKER = 'Claude Code Instructions';
+
+// Marker present in the slim stub (so we can detect it's already migrated)
+const SLIM_STUB_MARKER = 'abapgit-agent guide';
+
+// Marker present in the old full copilot-instructions.md
+const COPILOT_FULL_MARKER = '# ABAP Development with abapGit';
+
+// Marker present in the slim copilot stub
+const COPILOT_SLIM_MARKER = 'abapgit-agent guide';
+
+module.exports = {
+  name: 'guide',
+  description: 'Show bundled ABAP development guide',
+  requiresAbapConfig: false,
+
+  _findBundledGuide() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', 'CLAUDE.md'),
+      path.join(__dirname, '..', '..', '..', 'abap', 'CLAUDE.md')
+    ];
+    return candidates.find(p => fs.existsSync(p)) || null;
+  },
+
+  _findSlimStub() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', 'CLAUDE.slim.md'),
+      path.join(__dirname, '..', '..', '..', 'abap', 'CLAUDE.slim.md')
+    ];
+    return candidates.find(p => fs.existsSync(p)) || null;
+  },
+
+  _findCopilotSlimStub() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', '.github', 'copilot-instructions.slim.md'),
+      path.join(__dirname, '..', '..', '..', 'abap', '.github', 'copilot-instructions.slim.md')
+    ];
+    return candidates.find(p => fs.existsSync(p)) || null;
+  },
+
+  _getBundledGuidelineNames() {
+    const candidates = [
+      path.join(__dirname, '..', '..', 'abap', 'guidelines'),
+      path.join(__dirname, '..', '..', '..', 'abap', 'guidelines')
+    ];
+    const guidelinesDir = candidates.find(p => fs.existsSync(p));
+    if (!guidelinesDir) return new Set();
+    return new Set(
+      fs.readdirSync(guidelinesDir).filter(f => f.endsWith('.md'))
+    );
+  },
+
+  async _confirm(question) {
+    return new Promise((resolve) => {
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(question, (answer) => {
+        rl.close();
+        const normalized = answer.trim().toLowerCase();
+        resolve(normalized === '' || normalized === 'y' || normalized === 'yes');
+      });
+    });
+  },
+
+  async _runMigrate(args) {
+    const dryRun = args.includes('--dry-run');
+    const yes = args.includes('--yes') || args.includes('-y');
+    const cwd = process.cwd();
+
+    const bundledNames = this._getBundledGuidelineNames();
+    const slimStubPath = this._findSlimStub();
+    const copilotSlimStubPath = this._findCopilotSlimStub();
+
+    // --- Scan guidelines/ ---
+    const guidelinesDir = path.join(cwd, 'guidelines');
+    const toDelete = [];    // standard files matching bundled names
+    const toKeep = [];      // *.local.md or other non-standard files
+
+    if (fs.existsSync(guidelinesDir)) {
+      for (const name of fs.readdirSync(guidelinesDir)) {
+        if (!name.endsWith('.md')) continue;
+        if (bundledNames.has(name)) {
+          toDelete.push(path.join(guidelinesDir, name));
+        } else {
+          toKeep.push(name);
+        }
+      }
+    }
+
+    // --- Scan CLAUDE.md ---
+    const claudeMdPath = path.join(cwd, 'CLAUDE.md');
+    let claudeMdAction = 'none'; // 'replace' | 'already-slim' | 'custom' | 'missing'
+    if (fs.existsSync(claudeMdPath)) {
+      const content = fs.readFileSync(claudeMdPath, 'utf8');
+      if (content.includes(SLIM_STUB_MARKER)) {
+        claudeMdAction = 'already-slim';
+      } else if (content.includes(FULL_GUIDE_MARKER)) {
+        claudeMdAction = 'replace';
+      } else {
+        claudeMdAction = 'custom';
+      }
+    } else {
+      claudeMdAction = 'missing';
+    }
+
+    // --- Scan .github/copilot-instructions.md ---
+    const copilotMdPath = path.join(cwd, '.github', 'copilot-instructions.md');
+    let copilotAction = 'none'; // 'replace' | 'already-slim' | 'custom' | 'missing'
+    if (fs.existsSync(copilotMdPath)) {
+      const content = fs.readFileSync(copilotMdPath, 'utf8');
+      if (content.includes(COPILOT_SLIM_MARKER)) {
+        copilotAction = 'already-slim';
+      } else if (content.includes(COPILOT_FULL_MARKER)) {
+        copilotAction = 'replace';
+      } else {
+        copilotAction = 'custom';
+      }
+    } else {
+      copilotAction = 'missing';
+    }
+
+    // --- Nothing to do? ---
+    const nothingToDo = toDelete.length === 0 && claudeMdAction !== 'replace' && copilotAction !== 'replace';
+    if (nothingToDo) {
+      console.log('');
+      console.log('✅ Already clean — nothing to migrate.');
+      if (claudeMdAction === 'already-slim') {
+        console.log('   CLAUDE.md is already the slim stub.');
+      } else if (claudeMdAction === 'custom') {
+        console.log('   CLAUDE.md has custom content — left untouched.');
+      } else if (claudeMdAction === 'missing') {
+        console.log('   No CLAUDE.md found.');
+      }
+      if (copilotAction === 'already-slim') {
+        console.log('   .github/copilot-instructions.md is already the slim stub.');
+      } else if (copilotAction === 'custom') {
+        console.log('   .github/copilot-instructions.md has custom content — left untouched.');
+      }
+      if (toDelete.length === 0 && fs.existsSync(guidelinesDir)) {
+        console.log('   No standard guideline files found in guidelines/.');
+      }
+      console.log('');
+      return;
+    }
+
+    // --- Preview ---
+    console.log('');
+    console.log('🔄 guide --migrate: switch to bundled guidelines');
+    console.log('');
+
+    if (toDelete.length > 0) {
+      console.log(`Files to remove (${toDelete.length} standard guideline file${toDelete.length > 1 ? 's' : ''}):`);
+      toDelete.forEach(f => console.log(`   ${path.relative(cwd, f)}`));
+      console.log('');
+    }
+
+    if (toKeep.length > 0) {
+      console.log('Files to keep (project-specific):');
+      toKeep.forEach(f => console.log(`   guidelines/${f}`));
+      console.log('');
+    }
+
+    if (claudeMdAction === 'replace') {
+      if (slimStubPath) {
+        console.log('CLAUDE.md: detected as full guide → will replace with slim stub');
+        console.log("   (run 'abapgit-agent guide' to read the full guide on demand)");
+      } else {
+        console.log('CLAUDE.md: detected as full guide → ⚠️  slim stub not found, will skip');
+      }
+      console.log('');
+    }
+
+    if (copilotAction === 'replace') {
+      if (copilotSlimStubPath) {
+        console.log('.github/copilot-instructions.md: detected as full guide → will replace with slim stub');
+        console.log('   (Copilot uses the slim stub; full guide available online)');
+      } else {
+        console.log('.github/copilot-instructions.md: detected as full guide → ⚠️  slim stub not found, will skip');
+      }
+      console.log('');
+    }
+
+    // After deletions, would guidelines/ be empty?
+    const dirWillBeEmpty = fs.existsSync(guidelinesDir) && toKeep.length === 0;
+    if (dirWillBeEmpty) {
+      console.log('guidelines/ will be removed (no project-specific files remain).');
+      console.log('');
+    }
+
+    if (dryRun) {
+      console.log('ℹ️  Dry run — no changes made.');
+      console.log('');
+      return;
+    }
+
+    // --- Confirm ---
+    if (!yes) {
+      const proceed = await this._confirm('Proceed? [y/N] ');
+      if (!proceed) {
+        console.log('Migration cancelled.');
+        console.log('');
+        return;
+      }
+    }
+
+    // --- Execute ---
+    console.log('');
+    let deletedCount = 0;
+
+    for (const filePath of toDelete) {
+      fs.unlinkSync(filePath);
+      console.log(`🗑️  Removed ${path.relative(cwd, filePath)}`);
+      deletedCount++;
+    }
+
+    if (dirWillBeEmpty) {
+      // Verify no other files remain before removing the directory
+      const remaining = fs.readdirSync(guidelinesDir);
+      if (remaining.length === 0) {
+        fs.rmdirSync(guidelinesDir);
+        console.log('🗑️  Removed guidelines/');
+      }
+    }
+
+    if (claudeMdAction === 'replace' && slimStubPath) {
+      const slimContent = fs.readFileSync(slimStubPath, 'utf8');
+      fs.writeFileSync(claudeMdPath, slimContent);
+      console.log('✅ Replaced CLAUDE.md with slim stub');
+    }
+
+    if (copilotAction === 'replace' && copilotSlimStubPath) {
+      const slimContent = fs.readFileSync(copilotSlimStubPath, 'utf8');
+      fs.writeFileSync(copilotMdPath, slimContent);
+      console.log('✅ Replaced .github/copilot-instructions.md with slim stub');
+    }
+
+    console.log('');
+    console.log('✅ Migration complete.');
+    console.log('   Standard guidelines are now read from the package automatically.');
+    console.log("   Run 'abapgit-agent ref \"<pattern>\"' or 'abapgit-agent ref --topic <topic>' to search them.");
+    console.log('');
+  },
+
+  async execute(args) {
+    if (args.includes('--migrate')) {
+      return this._runMigrate(args);
+    }
+
+    const filePath = this._findBundledGuide();
+
+    if (!filePath) {
+      console.error('❌ Bundled CLAUDE.md not found. Make sure abapgit-agent is properly installed.');
+      process.exit(1);
+    }
+
+    if (args.includes('--path')) {
+      console.log(filePath);
+      return;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    if (args.includes('--json')) {
+      console.log(JSON.stringify({ path: filePath, content }));
+      return;
+    }
+
+    console.log(content);
+  }
+};

package/src/commands/help.js

@@ -78,6 +78,19 @@ Commands:
     - Use full URL: https://github.com/user/repo.git
     - Or short name: user/repo or user/repo (assumes github.com)
 
+  guide [--path] [--json]
+    Show the full ABAP development guide bundled with the package.
+    Reads directly from the installed npm package — always up-to-date.
+    - Use --path to print only the file path (useful for pagers)
+    - Use --json for machine-readable output
+
+  guide --migrate [--dry-run] [--yes]
+    Migrate repo from locally-copied guidelines to bundled fallback.
+    Removes standard guideline files copied by old 'init', replaces full CLAUDE.md
+    with slim stub. Project-specific files (*.local.md) are never removed.
+    - Use --dry-run to preview changes without applying them
+    - Use --yes to skip confirmation prompt
+
   health
     Check if ABAP REST API is healthy
 
@@ -107,6 +120,8 @@ Examples:
   abapgit-agent dump --user DEVELOPER --detail 1             # Full detail of first result
   abapgit-agent ref "CORRESPONDING"                          # Search for pattern
   abapgit-agent ref --topic exceptions                       # View exceptions topic
+  abapgit-agent guide                                        # Full ABAP dev guide
+  abapgit-agent guide --path                                 # Path to guide file
   abapgit-agent health                                       # Health check
   abapgit-agent status                                       # Configuration status