@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap-cds/annotations.md

@@ -0,0 +1,331 @@
+# CDS Annotations — view entity, element, header
+
+## Syntax
+
+```sql
+-- Header level (before define)
+@AnnotationName: value
+
+-- Element level (before field)
+@AnnotationName.property: value
+
+-- Array
+@AnnotationName: [{ property1: value1, property2: value2 }]
+```
+
+## AccessControl
+
+```sql
+@AccessControl.authorizationCheck: #CHECK
+define view entity ZI_Order as select from ztab_order
+```
+
+| Value | Effect |
+|-------|--------|
+| `#NOT_REQUIRED` | No DCL needed |
+| `#CHECK` | Warning if DCL missing |
+| `#MANDATORY` | Syntax error if DCL missing |
+| `#NOT_ALLOWED` | DCL ignored |
+
+## Metadata
+
+```sql
+@Metadata.allowExtensions: true
+define view entity ZI_Order as select from ztab_order
+```
+
+Allows Metadata Extensions (DDLX) to add UI annotations separately.
+
+## EndUserText
+
+```sql
+@EndUserText.label: 'Sales Order'
+define view entity ZI_SalesOrder as select from vbak
+{
+  @EndUserText.label: 'Order Number'
+  @EndUserText.quickInfo: 'Unique sales document identifier'
+  vbeln as SalesOrder
+}
+```
+
+## Semantics — Currency and Amount
+
+```sql
+{
+  @Semantics.currencyCode: true
+  currency_code as CurrencyCode,
+
+  @Semantics.amount.currencyCode: 'CurrencyCode'
+  total_price as TotalPrice
+}
+```
+
+## Semantics — Quantity and Unit
+
+```sql
+{
+  @Semantics.unitOfMeasure: true
+  unit as Unit,
+
+  @Semantics.quantity.unitOfMeasure: 'Unit'
+  quantity as Quantity
+}
+```
+
+## Semantics — Administrative Fields (RAP)
+
+```sql
+{
+  @Semantics.user.createdBy: true
+  created_by            as CreatedBy,
+
+  @Semantics.systemDateTime.createdAt: true
+  created_at            as CreatedAt,
+
+  @Semantics.user.localInstanceLastChangedBy: true
+  last_changed_by       as LastChangedBy,
+
+  @Semantics.systemDateTime.localInstanceLastChangedAt: true
+  last_changed_at       as LastChangedAt,
+
+  @Semantics.systemDateTime.lastChangedAt: true
+  local_last_changed_at as LocalLastChangedAt
+}
+```
+
+- `lastChangedAt` → etag master (per-record)
+- `localInstanceLastChangedAt` → total etag (per-BO, includes child changes)
+
+## Semantics — Boolean, Language, Text
+
+```sql
+  @Semantics.booleanIndicator: true
+  is_active as IsActive,
+
+  @Semantics.language: true
+  language as Language,
+
+  @Semantics.text: true
+  description as Description
+```
+
+## UI — List Report (lineItem + selectionField)
+
+```sql
+{
+  @UI.lineItem: [{ position: 10, importance: #HIGH }]
+  @UI.selectionField: [{ position: 10 }]
+  SalesOrder,
+
+  @UI.lineItem: [{ position: 20 }]
+  CreatedAt,
+
+  @UI.hidden: true
+  InternalID
+}
+```
+
+## UI — Object Page (headerInfo + facets + fieldGroup)
+
+```sql
+@UI.headerInfo: {
+  typeName: 'Sales Order',
+  typeNamePlural: 'Sales Orders',
+  title: { value: 'SalesOrder' },
+  description: { value: 'CustomerName' }
+}
+
+@UI.facet: [
+  { id: 'General', type: #IDENTIFICATION_REFERENCE, label: 'General', position: 10 },
+  { id: 'Items',   type: #LINEITEM_REFERENCE,       label: 'Items',   position: 20,
+    targetElement: '_Item' },
+  { id: 'Details', type: #FIELDGROUP_REFERENCE,      label: 'Details', position: 30,
+    targetQualifier: 'DetailInfo' }
+]
+
+{
+  @UI.identification: [{ position: 10 }]
+  SalesOrder,
+
+  @UI.identification: [{ position: 20 }]
+  CustomerName,
+
+  @UI.fieldGroup: [{ qualifier: 'DetailInfo', position: 10 }]
+  PaymentTerms,
+
+  @UI.dataPoint: { qualifier: 'Status', title: 'Order Status' }
+  @UI.textArrangement: #TEXT_ONLY
+  OverallStatus
+}
+```
+
+`#TEXT_FIRST` | `#TEXT_LAST` | `#TEXT_ONLY` | `#TEXT_SEPARATE`
+
+## Consumption — Value Help
+
+```sql
+@Consumption.valueHelpDefinition: [{
+  entity: { name: 'I_Currency', element: 'Currency' },
+  additionalBinding: [{
+    localElement: 'CompanyCode',
+    element: 'CompanyCode',
+    usage: #FILTER_AND_RESULT
+  }]
+}]
+CurrencyCode;
+```
+
+→ see fiori-valuelist.md for complete reference
+
+## Consumption — Filter
+
+```sql
+@Consumption.filter: {
+  selectionType: #RANGE,
+  multipleSelections: true,
+  mandatory: true
+}
+CompanyCode;
+```
+
+## ObjectModel
+
+```sql
+  @ObjectModel.text.element: ['StatusText']
+  OverallStatus,
+
+  @ObjectModel.text.association: '_StatusText'
+  OverallStatus,
+
+  @ObjectModel.foreignKey.association: '_Customer'
+  CustomerID,
+
+  @ObjectModel.composition: true
+  _Item
+```
+
+## Search
+
+```sql
+@Search.searchable: true
+define view entity ZC_Order as projection on ZI_Order
+{
+  @Search.defaultSearchElement: true
+  @Search.fuzzinessThreshold: 0.8
+  @Search.ranking: #HIGH
+  SalesOrder,
+
+  @Search.defaultSearchElement: true
+  @Search.ranking: #MEDIUM
+  Description
+}
+```
+
+## Analytics
+
+```sql
+@Analytics.dataCategory: #FACT
+define view entity ZI_SalesFact as select from vbap
+{
+  @DefaultAggregation: #SUM
+  total_price as TotalPrice,
+
+  @DefaultAggregation: #COUNT
+  item_number as ItemCount
+}
+```
+
+`#DIMENSION` | `#FACT` | `#CUBE`
+`#SUM` | `#MIN` | `#MAX` | `#AVG` | `#COUNT`
+
+## Environment — Parameter Defaults
+
+```sql
+define view entity ZI_WithDefaults
+  with parameters
+    @Environment.systemField: #SYSTEM_DATE
+    p_date : abap.dats,
+    @Environment.systemField: #SYSTEM_LANGUAGE
+    p_lang : spras,
+    @Environment.systemField: #USER
+    p_user : syuname
+  as select from ztab
+```
+
+## Full Annotated View Entity Example
+
+```sql
+@AccessControl.authorizationCheck: #CHECK
+@EndUserText.label: 'Sales Order'
+@Metadata.allowExtensions: true
+@Search.searchable: true
+define view entity ZI_SalesOrder
+  as select from vbak as h
+  composition [0..*] of ZI_SalesOrderItem as _Item
+  association [0..1] to kna1 as _Customer
+    on $projection.CustomerID = _Customer.kunnr
+  association [0..1] to I_Currency as _Currency
+    on $projection.CurrencyCode = _Currency.Currency
+{
+      @UI.lineItem: [{ position: 10, importance: #HIGH }]
+      @UI.selectionField: [{ position: 10 }]
+      @Search.defaultSearchElement: true
+  key h.vbeln as SalesOrder,
+
+      @UI.lineItem: [{ position: 20 }]
+      @UI.selectionField: [{ position: 20 }]
+      @ObjectModel.foreignKey.association: '_Customer'
+      h.kunnr as CustomerID,
+
+      @UI.lineItem: [{ position: 30 }]
+      h.erdat as CreatedAt,
+
+      @Semantics.currencyCode: true
+      h.waers as CurrencyCode,
+
+      @UI.lineItem: [{ position: 40 }]
+      @Semantics.amount.currencyCode: 'CurrencyCode'
+      h.netwr as NetAmount,
+
+      @Semantics.user.createdBy: true
+      h.ernam as CreatedBy,
+
+      @ObjectModel.text.element: ['CustomerName']
+      _Customer.name1 as CustomerName,
+
+      _Item,
+      _Customer,
+      _Currency
+}
+```
+
+## Annotation Placement
+
+| Level | Position | Example |
+|-------|----------|---------|
+| Header | Before `define view entity` | `@AccessControl.authorizationCheck` |
+| Element | Before field in projection | `@UI.lineItem` |
+| Parameter | Before parameter definition | `@Environment.systemField` |
+
+## Rules
+
+- Always set `@AccessControl.authorizationCheck` on every view entity
+- Always annotate CURR fields with `@Semantics.amount.currencyCode`
+- Always annotate QUAN fields with `@Semantics.quantity.unitOfMeasure`
+- Number `position` values by 10s for easy insertion
+- Use `@ObjectModel.text.element` for code-text field pairs
+- Use `@Metadata.allowExtensions: true` to enable Metadata Extensions (DDLX)
+- Use `define view entity` (not legacy `define view`) for new development
+- `@AbapCatalog.sqlViewName` is NOT needed for view entities (only legacy `define view`)
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct |
+|---|---|
+| Missing `@Semantics.amount.currencyCode` on CURR field | Always pair amount with currency reference |
+| `@AccessControl.authorizationCheck: #NOT_REQUIRED` on sensitive data | Use `#CHECK` or `#MANDATORY` |
+| `@UI.lineItem` position: 1, 2, 3 | Use 10, 20, 30 for insertion gaps |
+| Skipping `@Semantics.unitOfMeasure` on QUAN field | Always pair quantity with unit reference |
+| Using `@UI.hidden` when field is never needed | Omit from projection entirely |
+| Using `define view` with `@AbapCatalog.sqlViewName` for new development | Use `define view entity` (no sqlViewName needed) |
+| UI annotations in interface CDS (ZI_*) | Use `@Metadata.allowExtensions` + Metadata Extension (DDLX) |

package/dist/knowledge/abap-cds/associations.md

@@ -0,0 +1,254 @@
+# CDS Associations — Join-on-Demand Relationship Definitions
+
+## Syntax
+
+```sql
+define view Z_ORDER as select from vbak as h
+  association [cardinality] to target as _Alias
+    on condition
+{
+  key h.vbeln,
+      _Alias
+}
+```
+
+## Cardinality
+
+| Syntax | Meaning | Join |
+|--------|---------|------|
+| `[0..1]` | Zero or one | LEFT OUTER MANY TO ONE |
+| `[1]` | Shorthand for [0..1] | LEFT OUTER MANY TO ONE |
+| `[1..1]` | Exactly one | LEFT OUTER MANY TO ONE |
+| `[0..*]` | Zero or more | LEFT OUTER MANY TO MANY |
+| `[*]` | Shorthand for [0..*] | LEFT OUTER MANY TO MANY |
+| `[1..*]` | One or more | LEFT OUTER MANY TO MANY |
+| (omitted) | Default [0..1] | LEFT OUTER MANY TO ONE |
+
+### New Syntax (S/4HANA 2302+ / NW 7.57+)
+
+```sql
+association to one _Target on ...
+association to many _Targets on ...
+```
+
+## Cardinality Examples
+
+```sql
+-- Optional single record
+association [0..1] to kna1 as _Customer
+  on $projection.kunnr = _Customer.kunnr
+
+-- Required single record
+association [1..1] to t001 as _Company
+  on $projection.bukrs = _Company.bukrs
+
+-- Multiple records
+association [0..*] to vbap as _Items
+  on $projection.vbeln = _Items.vbeln
+
+-- At least one
+association [1..*] to spfli as _Flights
+  on $projection.carrid = _Flights.carrid
+```
+
+## Join Conditions
+
+### Using $projection
+
+```sql
+association [0..1] to makt as _Text
+  on $projection.matnr = _Text.matnr
+ and $projection.spras = _Text.spras
+```
+
+### Using Source Alias
+
+```sql
+define view Z_MAT as select from mara as m
+  association [0..1] to makt as _Text
+    on m.matnr = _Text.matnr
+```
+
+### Complex Condition
+
+```sql
+association [0..*] to zcond as _Prices
+  on $projection.matnr = _Prices.matnr
+ and $projection.vkorg = _Prices.vkorg
+ and _Prices.valid_from <= $session.system_date
+ and _Prices.valid_to  >= $session.system_date
+```
+
+## Exposing Associations
+
+### Direct
+
+```sql
+{ key vbeln, _Customer, _Items }
+```
+
+### Redirected
+
+```sql
+_Customer : redirected to Z_CUSTOMER_VIEW
+```
+
+### Filtered
+
+```sql
+_Items[Status = 'ACTIVE'] as _ActiveItems
+```
+
+## Using Associations — Field Access
+
+```sql
+{
+  key vbeln,
+  _Customer.name1 as CustomerName,
+  _Customer.ort01 as CustomerCity
+}
+```
+
+## Path Expressions
+
+```sql
+-- Multi-level navigation
+_Header._Customer._Country.name as CountryName
+
+-- Path filter with cardinality indicator
+_Items[1: ItemNumber = '000010'].Material as FirstItemMaterial
+```
+
+## Association vs Join
+
+### Association (join-on-demand)
+
+```sql
+define view Z_WITH_ASSOC as select from vbak
+  association [0..1] to kna1 as _Customer
+    on $projection.kunnr = _Customer.kunnr
+{
+  key vbeln,
+      kunnr,
+      _Customer   -- join NOT executed until fields accessed
+}
+-- SELECT vbeln, kunnr FROM z_with_assoc => no join
+```
+
+### Join (always executed)
+
+```sql
+define view Z_WITH_JOIN as select from vbak as v
+  left outer join kna1 as c on v.kunnr = c.kunnr
+{
+  key v.vbeln,
+      v.kunnr,
+      c.name1     -- join ALWAYS executed
+}
+-- SELECT vbeln, kunnr FROM z_with_join => join runs anyway
+```
+
+## Text Association Pattern
+
+```sql
+association [0..1] to makt as _Text
+  on $projection.matnr = _Text.matnr
+ and _Text.spras = $session.system_language
+{
+  key matnr,
+      _Text.maktx as MaterialDescription
+}
+```
+
+## Self-Reference / Hierarchy
+
+```sql
+define view Z_ORG as select from zorg_unit as o
+  association [0..1] to Z_ORG as _Parent
+    on $projection.parent_id = _Parent.org_id
+  association [0..*] to Z_ORG as _Children
+    on $projection.org_id = _Children.parent_id
+{
+  key org_id,
+      parent_id,
+      name,
+      _Parent,
+      _Children
+}
+```
+
+## Propagated Associations
+
+```sql
+-- Base view
+define view Z_BASE as select from mara
+  association [0..1] to makt as _Text on ...
+{ key matnr, _Text }
+
+-- Consumer: _Text propagated automatically
+define view Z_CONSUMER as select from Z_BASE
+{ key matnr, _Text }
+```
+
+Block propagation:
+
+```sql
+@Metadata.ignorePropagatedAnnotations: true
+define view Z_NO_PROP as select from Z_BASE
+{ key matnr }  -- _Text NOT available
+```
+
+## Composition (RAP)
+
+```sql
+define view entity Z_SO_HDR as select from vbak
+  composition [0..*] of Z_SO_ITEM as _Items
+{
+  key vbeln,
+      erdat,
+      _Items
+}
+
+define view entity Z_SO_ITEM as select from vbap
+  association to parent Z_SO_HDR as _Header
+    on $projection.vbeln = _Header.vbeln
+{
+  key vbeln,
+  key posnr,
+      matnr,
+      _Header
+}
+```
+
+## ABAP Consumption
+
+```abap
+SELECT
+  vbeln,
+  \_Customer-name1 AS customer_name,
+  \_Customer-ort01 AS city
+FROM z_sales_order
+INTO TABLE @DATA(lt_result).
+```
+
+## Rules
+
+- Prefix association aliases with underscore: `_Customer`, `_Items`
+- Use `[0..1]` for to-one, `[0..*]` for to-many
+- Set correct cardinality to avoid duplicate rows and enable HANA optimization
+- Use associations over joins when fields are optional or for OData/RAP
+- Use joins when all fields are always needed or for aggregation
+- Always expose associations in the projection list
+- Use `$projection` in ON conditions for reusability
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct |
+|---|---|
+| `association [0..*]` when target is always single record | Use `[0..1]` for HANA join pruning |
+| Not exposing association in field list | Always add `_Alias` to projection |
+| Deep path chains (5+ levels) | Flatten with intermediate views |
+| Using join for optional lookup | Use association for join-on-demand |
+| Missing `_Text.spras = $session.system_language` in text assoc | Always filter on language |
+| Association alias without underscore prefix | Use `_Customer` not `Customer` |
+| `association [1..1]` when data may not exist | Use `[0..1]` for nullable FKs |