@abapify/acds 0.4.15 → 0.4.16

package/README.md

@@ -8,13 +8,27 @@ Parses `.acds` (ABAP CDS DDL) source code into a fully typed Abstract Syntax Tre
 
 ### Supported Definitions
 
-| CDS Construct | AST Node               | Example                              |
-| ------------- | ---------------------- | ------------------------------------ |
-| Table         | `TableDefinition`      | `define table ztable { ... }`        |
-| Structure     | `StructureDefinition`  | `define structure zstruct { ... }`   |
-| Simple type   | `SimpleTypeDefinition` | `define type ztype : abap.char(10);` |
-| Service       | `ServiceDefinition`    | `define service zsvc { ... }`        |
-| Metadata ext. | `MetadataExtension`    | `annotate entity ZView with { ... }` |
+| CDS Construct   | AST Node                   | Example                                                                       |
+| --------------- | -------------------------- | ----------------------------------------------------------------------------- |
+| Table           | `TableDefinition`          | `define table [entity] ztable { ... }`                                        |
+| Root table ent. | `TableDefinition`          | `define root table entity ztable { ... }`                                     |
+| Structure       | `StructureDefinition`      | `define structure zstruct { ... }`                                            |
+| Simple type     | `SimpleTypeDefinition`     | `define type ztype : abap.char(10);`                                          |
+| View entity     | `ViewEntityDefinition`     | `define [root] view entity zv as select ...`                                  |
+| Legacy view     | `ViewEntityDefinition`     | `define view zv as select ...` (`legacy`)                                     |
+| Abstract entity | `AbstractEntityDefinition` | `define abstract entity zae { ... }`                                          |
+| Custom entity   | `CustomEntityDefinition`   | `define custom entity zce { ... }`                                            |
+| External entity | `ExternalEntityDefinition` | `define external entity zee { ... } with federated data provided at runtime;` |
+| Table function  | `TableFunctionDefinition`  | `define table function ztf returns { ... }`                                   |
+| Scalar function | `ScalarFunctionDefinition` | `define scalar function zsf ...`                                              |
+| Hierarchy       | `HierarchyDefinition`      | `define hierarchy zh as parent child hierarchy(...) { ... }`                  |
+| Aspect          | `AspectDefinition`         | `define aspect za { ... }`                                                    |
+| Annotation      | `AnnotationDefinition`     | `define annotation za: Boolean;`                                              |
+| Access policy   | `AccessPolicyDefinition`   | `define accesspolicy zap { ... }`                                             |
+| Service         | `ServiceDefinition`        | `define service zsvc { ... }`                                                 |
+| Extension       | `ExtensionDefinition`      | `extend view entity zv with { ... }`                                          |
+| Metadata ext.   | `MetadataExtension`        | `annotate entity ZView with { ... }`                                          |
+| Role (DCL)      | `RoleDefinition`           | `define role zr { grant select ... }`                                         |
 
 ### Parser Features
 
@@ -23,7 +37,11 @@ Parses `.acds` (ABAP CDS DDL) source code into a fully typed Abstract Syntax Tre
 - **Built-in types** — `abap.char(10)`, `abap.dec(11,2)`, `abap.dats`, etc.
 - **Named types** — data element and qualified name references
 - **Include directives** — `include <structure>` with optional suffix
-- **Comments** — line (`//`) and block (`/* */`) comments are skipped
+- **Comments** — line (`//`, `--`) and block (`/* */`) comments are skipped
+- **Case-insensitive keywords** — `DEFINE VIEW ENTITY` and `define view entity` both parse; identifiers keep their original spelling
+- **FROM clause** — join chains, parameterized sources, FROM associations
+- **View flavours** — `define view entity <name>` and the legacy `define view <name>`
+- **Projection elements** — paths, calls (`coalesce(a, b)`, `sum(x)`) and `cast(x as type [preserving type])`
 
 ## Installation
 
@@ -83,10 +101,20 @@ type CdsDefinition =
   | TableDefinition
   | StructureDefinition
   | SimpleTypeDefinition
+  | ViewEntityDefinition
+  | AbstractEntityDefinition
+  | CustomEntityDefinition
+  | ExternalEntityDefinition
+  | TableFunctionDefinition
+  | ScalarFunctionDefinition
+  | HierarchyDefinition
+  | AspectDefinition
+  | AnnotationDefinition
+  | AccessPolicyDefinition
   | ServiceDefinition
+  | ExtensionDefinition
   | MetadataExtension
-  | RoleDefinition // Phase 2 placeholder
-  | ViewEntityDefinition; // Phase 3 placeholder
+  | RoleDefinition;
 ```
 
 #### Definitions
@@ -173,6 +201,117 @@ type AnnotationValue =
   | { kind: 'object'; properties: AnnotationProperty[] };
 ```
 
+#### FROM clause (view entities)
+
+```typescript
+interface ViewEntityDefinition {
+  kind: 'viewEntity';
+  name: string;
+  annotations: Annotation[];
+  legacy?: boolean; // true for the legacy `define view <name>` syntax
+  root?: boolean; // `define root view entity`
+  writable?: boolean; // `define writable view entity`
+  providerContract?: string; // `provider contract transactional_query`
+  sourceKind: DataSourceKind; // 'select' | 'projection'
+  distinct?: boolean; // `select distinct`
+  source: DataSource; // the root data source
+  joins: JoinClause[]; // ordered join chain — empty when there are no joins
+  fromAssociations?: AssociationDeclaration[]; // associations of the FROM region
+  aspectBindings?: AspectBinding[]; // `bind aspect` bindings
+  parameters: ParameterDefinition[];
+  members: ViewMember[];
+  where?: Expression;
+  groupBy?: string[];
+  having?: Expression;
+  setOperations?: SetOperation[]; // union/intersect/except branches
+}
+
+interface DataSource {
+  name: string;
+  alias?: string;
+  parameters?: DataSourceParameter[]; // parameterized source
+}
+
+interface DataSourceParameter {
+  name: string; // e.g. 'P_StartDate'
+  value: string; // raw binding: ':P_Key1StartDate', '$session.client', "'X'"
+}
+
+type JoinType = 'inner' | 'leftOuter' | 'rightOuter' | 'fullOuter' | 'cross';
+
+// Conditioned joins always carry an ON condition — the grammar enforces it.
+interface ConditionedJoinClause {
+  kind: 'join';
+  joinType: 'inner' | 'leftOuter' | 'rightOuter' | 'fullOuter';
+  source: JoinSource; // DataSource | JoinGroup
+  on: Expression; // the ON condition (opaque)
+  cardinality?: WordCardinality; // `many to one join` / `to one join`
+}
+
+// A cross join never carries an ON condition.
+interface CrossJoinClause {
+  kind: 'join';
+  joinType: 'cross';
+  source: JoinSource;
+}
+
+type JoinClause = ConditionedJoinClause | CrossJoinClause;
+
+// A join source is either a plain data source or a parenthesized group.
+type JoinSource = DataSource | JoinGroup;
+
+// `join (A join B on …) on …` — the group acts as a single join source.
+interface JoinGroup {
+  kind: 'joinGroup';
+  source: JoinSource; // nested — may itself be a group
+  joins: JoinClause[]; // the join chain inside the parentheses
+}
+```
+
+Supported join spellings (normalized to `JoinType`):
+
+| spelling           | `joinType`   | Notes                            |
+| ------------------ | ------------ | -------------------------------- |
+| `JOIN`             | `inner`      |                                  |
+| `INNER JOIN`       | `inner`      |                                  |
+| `LEFT JOIN`        | `leftOuter`  | `OUTER` is optional              |
+| `LEFT OUTER JOIN`  | `leftOuter`  |                                  |
+| `RIGHT JOIN`       | `rightOuter` | `OUTER` is optional              |
+| `RIGHT OUTER JOIN` | `rightOuter` |                                  |
+| `FULL JOIN`        | `fullOuter`  | `OUTER` is optional              |
+| `FULL OUTER JOIN`  | `fullOuter`  |                                  |
+| `CROSS JOIN`       | `cross`      | must not carry an `ON` condition |
+
+The `ON` condition is **required** for inner and outer joins and **not allowed**
+for a cross join — the grammar enforces this.
+
+The accepted join syntax is the same for every view flavour: a CDS view entity
+(`define view entity`) and a classic SQL view (`define view`) accept exactly the
+same spellings. `FULL [OUTER] JOIN` is the SQL-standard full outer join — it is
+not part of the ABAP CDS DDL join syntax, but it is supported so that HANA CDS /
+CAP CDS sources (which use the standard SQL join syntax) can be read with the
+same parser.
+
+Example:
+
+```typescript
+const { ast } = parse(`
+  define view entity ZC_Cube as select from I_Item as _Item
+    left outer join ZI_Other as _Other
+      on _Item.key = _Other.key
+    association [0..1] to I_Product as _Product
+      on $projection.Product = _Product.Product
+  {
+    key _Item.key
+  }
+`);
+
+const view = ast.definitions[0] as ViewEntityDefinition;
+view.joins[0].joinType; // 'leftOuter'
+view.joins[0].source.alias; // '_Other'
+view.fromAssociations?.[0].target; // 'I_Product'
+```
+
 #### Errors
 
 ```typescript
@@ -206,13 +345,13 @@ Source string
 
 ## Roadmap
 
-- ✅ **DDL**: tables, structures, simple types, view entities, projection views, abstract/custom entities, services (SRVD), metadata extensions (DDLX), parameters, associations, compositions
-- ✅ **DCL**: role definitions with grant-select + where clauses
+- ✅ **DDL**: tables, structures, simple types, view entities (`define [root] view entity`, projection views + `provider contract`), legacy `define view`, abstract/custom/table/external entities, table/scalar functions, hierarchies, aspects (DRAS), DDLA annotation definitions, access policies, services (SRVD), metadata extensions (DDLX), `extend view/entity` forms, parameters, associations, compositions
+- ✅ **DCL**: role definitions — `switchable`, grant-select + `where`, `with optional elements`, `combination mode and|or|redefinition`, `inherit`, `inheriting conditions`
 - ✅ **Annotations**: full value grammar (strings, enums, booleans, numbers, arrays, objects, dotted keys)
 - ✅ **Tooling**: AST walker helpers, semantic validators (`SemanticDiagnostic`), grammar coverage metadata
+- ✅ **FROM clause**: join chains (`inner`, `left [outer]`, `right [outer]`, `full [outer]`, `cross`) with word cardinalities and grouped joins, parameterized sources, FROM associations, path-expression data sources (`_assoc[ ... ]`), `bind aspect`
+- ✅ **Elements**: `case … end`, arithmetic, casts, calls (incl. `f()`), window `over (…)`, paths, `: localized`, `: redirected to`, `distinct`, `where`/`group by`/`having`, `union [all]`/`intersect`/`except`
 - 🔜 **Expression grammar** (structured `on`/`where` trees — currently opaque `{ source, tokens }`)
-- 🔜 **Joins** (`inner join`, `left outer join …`), CASE/CAST, aggregates, GROUP BY, UNION
-- 🔜 **`define aspect` (DRAS), `define hierarchy`, cache definitions (DTDC/DTSC), scalar functions (DSFD)**
 - 🔜 **BDEF / behavior definitions** (owned by epic E10)
 
 ## Dependencies