@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/cap/cdl-syntax.md

@@ -0,0 +1,247 @@
+# CDL Syntax — CDS Entity and Type Definitions
+
+## Entity Definitions
+
+```cds
+namespace my.bookshop;
+
+entity Books {
+  key ID    : UUID;
+  title     : String(255) not null;
+  descr     : String(5000);
+  stock     : Integer default 0;
+  price     : Decimal(10,2);
+  available : Boolean default true;
+}
+```
+
+## Types and Structured Elements
+
+```cds
+type Address {
+  street  : String;
+  city    : String;
+  zipCode : String(10);
+  country : String(3);
+}
+
+entity Customers {
+  homeAddress : Address;
+  workAddress : Address;
+}
+
+// Arrayed types
+entity Contacts {
+  emails : many String;
+  phones : array of String(20);
+  tags   : many { name: String };
+}
+```
+
+## Enumerations
+
+```cds
+type Status : String enum {
+  draft;
+  submitted;
+  approved;
+  rejected = 'REJ';
+}
+
+type Priority : Integer enum {
+  low = 1;
+  medium = 2;
+  high = 3;
+}
+
+entity Orders {
+  status   : Status default #draft;
+  priority : Priority default #medium;
+}
+```
+
+## Calculated and Virtual Elements
+
+```cds
+entity Employees {
+  firstName : String;
+  lastName  : String;
+  // On-read (computed during queries)
+  fullName  : String = firstName || ' ' || lastName;
+  // Stored (persisted in DB)
+  stored    : String = (firstName || ' ' || lastName) stored;
+  // Virtual (not persisted, set in handler)
+  virtual displayName : String @Core.Computed;
+}
+```
+
+## Associations
+
+```cds
+// Managed to-one (CAP auto-generates FK: author_ID)
+entity Books {
+  author : Association to Authors;
+}
+
+// Unmanaged (explicit FK + ON condition required)
+entity Books {
+  author    : Association to Authors on author.ID = author_ID;
+  author_ID : UUID;
+}
+
+// To-many
+entity Authors {
+  books : Association to many Books on books.author = $self;
+}
+
+// Many-to-many via link entity
+entity Books {
+  categories : Association to many Book2Category on categories.book = $self;
+}
+entity Book2Category {
+  key book     : Association to Books;
+  key category : Association to Categories;
+}
+```
+
+## Compositions
+
+```cds
+// Standard composition
+entity Orders {
+  key ID : UUID;
+  Items  : Composition of many OrderItems on Items.order = $self;
+}
+entity OrderItems {
+  key ID : UUID;
+  order  : Association to Orders;
+  product : Association to Products;
+  quantity : Integer;
+}
+
+// Inline managed composition (auto-creates Orders.Items entity)
+entity Orders {
+  key ID : UUID;
+  Items  : Composition of many {
+    key pos : Integer;
+    product : Association to Products;
+    quantity : Integer;
+  };
+}
+```
+
+## Aspects and Extend
+
+```cds
+aspect tracked {
+  createdAt  : Timestamp @cds.on.insert: $now;
+  createdBy  : String(255) @cds.on.insert: $user;
+  modifiedAt : Timestamp @cds.on.insert: $now @cds.on.update: $now;
+  modifiedBy : String(255) @cds.on.insert: $user @cds.on.update: $user;
+}
+
+// Apply via include syntax
+entity Books : tracked {
+  key ID : UUID;
+  title  : String;
+}
+
+// Extend existing entity
+extend Books with {
+  newField : String;
+}
+extend Books with tracked;
+```
+
+## Annotations
+
+```cds
+// Grouped annotation syntax
+@(
+  title: 'Books',
+  description: 'All books',
+  UI.HeaderInfo: { TypeName: 'Book' }
+)
+entity Books { ... }
+
+// Element-level
+entity Books {
+  @title: 'Book Title'
+  @mandatory
+  title : String;
+}
+
+// Separate annotate directive
+annotate Books with @title: 'Books';
+annotate Books with {
+  title @title: 'Book Title';
+  price @Measures.Unit: currency_code;
+};
+```
+
+## Services with Actions
+
+```cds
+service CatalogService @(path: '/catalog') {
+  entity Books as projection on my.Books;
+
+  // Bound actions (entity-level)
+  entity Orders { ... } actions {
+    action confirm();
+    action cancel(reason: String);
+    function getTotal() returns Decimal;
+  };
+
+  // Unbound actions (service-level)
+  action sendNotification(to: String, message: String);
+  function calculateTax(amount: Decimal, region: String) returns Decimal;
+}
+```
+
+## Views and Projections
+
+```cds
+entity PublicBooks as projection on Books {
+  ID, title, descr, author
+} excluding { createdBy, modifiedBy };
+
+entity BooksList as select from Books {
+  ID, title, author.name as authorName,
+  stock * price as value : Decimal
+} where stock > 0 order by title;
+
+// Parameterized view
+entity FilteredBooks(minStock: Integer, maxPrice: Decimal)
+  as select from Books
+  where stock >= :minStock and price <= :maxPrice;
+```
+
+## Imports
+
+```cds
+using my.bookshop.Books from './db/schema';
+using { Authors, Genres } from './db/schema';
+using { Books as MyBooks } from './db/schema';
+```
+
+## Rules
+
+- Keywords are case-insensitive; identifiers are case-sensitive
+- Managed associations auto-generate FK columns (e.g., `author` creates `author_ID`)
+- Compositions cascade deep CRUD; associations do not
+- `@cds.on.insert: $now` and `$user` only work in aspects/annotations, not default values
+- Use `extend` to add fields; use `annotate` to add annotations without changing structure
+- Enums use `#value` syntax for defaults: `default #draft`
+- `many` and `array of` are equivalent for arrayed types
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Pattern |
+|---|---|
+| Manual FK for managed association: `author_ID : UUID; author : Association to Authors;` | `author : Association to Authors;` (FK auto-generated) |
+| `Composition of Authors` (independent entity) | `Composition of OrderItems` (dependent/child entity only) |
+| `default $now` on plain field | `@cds.on.insert: $now` via aspect |
+| Putting business logic in CDS | CDS is declarative; logic goes in handlers |
+| `entity Items { order : Composition of Orders; }` | Composition is parent-to-child only |
+| Circular compositions | Use associations for non-hierarchical relationships |
+| `String` without length for large text | `String(5000)` or `LargeString` for long content |

package/dist/knowledge/cap/cql-queries.md

@@ -0,0 +1,266 @@
+# CQL Queries — CAP Node.js Database Operations
+
+## SELECT
+
+```js
+const { Books, Authors } = cds.entities;
+
+// All columns
+const books = await SELECT.from(Books);
+
+// Specific columns
+const titles = await SELECT.from(Books).columns('ID', 'title', 'price');
+
+// Single record by key
+const book = await SELECT.from(Books, bookId);
+
+// Single record with WHERE
+const book = await SELECT.one.from(Books).where({ ID: bookId });
+
+// ALWAYS guard single-record results
+const book = await SELECT.one.from(Books).where({ ID: bookId });
+if (!book) return req.reject(404, 'Book not found');
+```
+
+## WHERE Clauses
+
+```js
+// Equality
+await SELECT.from(Books).where({ stock: 10 });
+
+// Comparison operators
+await SELECT.from(Books).where({ stock: { '>': 0 } });
+await SELECT.from(Books).where({ stock: { '>=': 10 } });
+await SELECT.from(Books).where({ price: { '<=': 50 } });
+await SELECT.from(Books).where({ status: { '!=': 'deleted' } });
+
+// IN, LIKE, BETWEEN
+await SELECT.from(Books).where({ genre: { in: ['fiction', 'drama'] } });
+await SELECT.from(Books).where({ title: { like: '%CAP%' } });
+await SELECT.from(Books).where({ price: { between: [10, 50] } });
+
+// NULL checks
+await SELECT.from(Books).where({ author_ID: { '=': null } });
+await SELECT.from(Books).where({ author_ID: { '!=': null } });
+
+// AND (multiple keys in object)
+await SELECT.from(Books).where({
+  stock: { '>': 0 },
+  price: { '<': 100 }
+});
+
+// OR
+await SELECT.from(Books).where({
+  or: [
+    { stock: { '>': 100 } },
+    { price: { '<': 10 } }
+  ]
+});
+
+// Nested AND/OR
+await SELECT.from(Books).where({
+  and: [
+    { genre: 'fiction' },
+    { or: [
+      { stock: { '>': 50 } },
+      { featured: true }
+    ]}
+  ]
+});
+```
+
+## ORDER BY, LIMIT, DISTINCT
+
+```js
+await SELECT.from(Books).orderBy('title asc');
+await SELECT.from(Books).orderBy({ genre: 'asc', price: 'desc' });
+
+// Pagination: 10 rows, skip 20
+await SELECT.from(Books).limit(10, 20);
+
+await SELECT.distinct.from(Books).columns('genre');
+```
+
+## Aggregations
+
+```js
+const count = await SELECT.one.from(Books).columns('count(*) as total');
+
+const stats = await SELECT.one.from(Books).columns(
+  'sum(stock) as totalStock',
+  'avg(price) as avgPrice',
+  'min(price) as minPrice',
+  'max(price) as maxPrice'
+);
+
+const byGenre = await SELECT.from(Books)
+  .columns('genre', 'count(*) as count', 'avg(price) as avgPrice')
+  .groupBy('genre')
+  .having({ 'count(*)': { '>': 5 } })
+  .orderBy('count desc');
+```
+
+## Associations and Expand
+
+```js
+// Path expressions
+await SELECT.from(Books).columns('title', 'author.name');
+await SELECT.from(Books).where({ 'author.name': 'John Doe' });
+
+// Expand with ref syntax
+await SELECT.from(Books)
+  .columns('ID', 'title', { ref: ['author'], expand: ['ID', 'name'] });
+
+// Lambda syntax (fluent)
+await SELECT.from(Books, b => {
+  b.ID,
+  b.title,
+  b.author(a => { a.ID, a.name })
+});
+
+// Nested expand
+await SELECT.from(Orders, o => {
+  o.ID,
+  o.customer(c => { c.name }),
+  o.items(i => {
+    i.quantity,
+    i.product(p => { p.name, p.price })
+  })
+});
+```
+
+## INSERT
+
+```js
+// Single entry
+await INSERT.into(Books).entries({
+  ID: cds.utils.uuid(),
+  title: 'New Book',
+  stock: 100,
+  price: 29.99
+});
+
+// Multiple entries
+await INSERT.into(Books).entries([
+  { title: 'Book 1', stock: 10 },
+  { title: 'Book 2', stock: 20 }
+]);
+
+// Deep insert (with compositions)
+await INSERT.into(Orders).entries({
+  ID: orderId,
+  customer_ID: customerId,
+  items: [
+    { product_ID: product1Id, quantity: 2 },
+    { product_ID: product2Id, quantity: 1 }
+  ]
+});
+
+// Insert from SELECT
+await INSERT.into(ArchivedBooks).as(
+  SELECT.from(Books).where({ stock: 0 })
+);
+```
+
+## UPDATE
+
+```js
+// By key
+await UPDATE(Books, bookId).set({ stock: 50 });
+
+// With WHERE
+await UPDATE(Books).set({ featured: true }).where({ stock: { '>': 100 } });
+
+// Increment/Decrement
+await UPDATE(Books, bookId).set({ stock: { '+=': 10 } });
+await UPDATE(Books, bookId).set({ stock: { '-=': 5 } });
+await UPDATE(Books, bookId).set({ price: { '*=': 1.1 } });
+
+// Conditional update (check affected rows)
+const result = await UPDATE(Books, bookId)
+  .set({ stock: { '-=': quantity } })
+  .where({ stock: { '>=': quantity } });
+if (result === 0) throw new Error('Insufficient stock');
+
+// Deep update
+await UPDATE(Orders, orderId).with({
+  status: 'confirmed',
+  items: [
+    { ID: item1Id, quantity: 5 },
+    { ID: item2Id, quantity: 3 }
+  ]
+});
+```
+
+## DELETE
+
+```js
+await DELETE.from(Books, bookId);
+await DELETE.from(Books).where({ stock: 0 });
+```
+
+## UPSERT
+
+```js
+// Insert if not exists, update if exists — key field REQUIRED
+await UPSERT.into(Books).entries({
+  ID: bookId,
+  title: 'Updated or New Title',
+  stock: 50
+});
+
+// Multiple
+await UPSERT.into(Books).entries([
+  { ID: id1, title: 'Book 1' },
+  { ID: id2, title: 'Book 2' }
+]);
+```
+
+## Subqueries
+
+```js
+await SELECT.from(Books).where({
+  author_ID: {
+    in: SELECT.from(Authors).columns('ID')
+      .where({ bookCount: { '>': 5 } })
+  }
+});
+```
+
+## Locking
+
+```js
+const book = await SELECT.from(Books, bookId).forUpdate();
+const book = await SELECT.from(Books, bookId).forShareLock();
+```
+
+## Raw SQL
+
+```js
+const results = await cds.db.run(
+  `SELECT * FROM my_bookshop_Books WHERE stock > ?`, [10]
+);
+```
+
+## Rules
+
+- `SELECT.one` returns a single object or `undefined`; `SELECT` returns an array
+- `UPDATE` returns number of affected rows (0 means nothing matched)
+- UPSERT requires key fields; does NOT support `.where()`; does NOT merge — all provided fields are set
+- Deep INSERT/UPDATE only works with compositions, not associations
+- Compositions automatically cascade deletes
+- `DELETE.from(Entity)` without WHERE deletes ALL records
+- Use `cds.utils.uuid()` for generating UUIDs in INSERT
+- `.set()` and `.with()` are equivalent on UPDATE
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Pattern |
+|---|---|
+| `SELECT.one.from(Books).where(...)` without null check | Always guard: `if (!book) req.reject(404, ...)` |
+| `DELETE.from(Books)` without WHERE (deletes all) | Always add `.where(...)` unless intentional |
+| UPSERT with `.where()` | UPSERT uses key fields only; use UPDATE for conditional |
+| Deep insert via association | Deep insert only works with compositions |
+| String concatenation for SQL | Use parameterized queries: `cds.db.run(sql, [params])` |
+| `await SELECT.from(Books, id)` without handling undefined | Check result before accessing properties |
+| Mixing CQL and raw SQL in same transaction | Stick to CQL; raw SQL only when CQL cannot express the query |