Add an option to open source FE writer generate to enable writing annotations.

.changeset/sweet-games-raise.md

@@ -0,0 +1,5 @@
+---
+'@sap-ux/fiori-elements-writer': minor
+---
+
+Add an option to open source FE writer to enable writing annotations.

packages/fiori-elements-writer/package.json

@@ -38,6 +38,8 @@
         "@sap-ux/ui5-test-writer": "workspace:*",
         "@sap-ux/fiori-generator-shared": "workspace:*",
         "@sap-ux/cap-config-writer": "workspace:*",
+        "@sap-ux/annotation-generator": "workspace:*",
+        "@sap-ux/logger": "workspace:*",
         "ejs": "3.1.10",
         "i18next": "20.6.1",
         "lodash": "4.17.21",

packages/fiori-elements-writer/src/data/templateAttributes.ts

@@ -139,6 +139,8 @@ type TemplateAttributes = {
         minimumUi5Version: {
             [V in OdataVersion]?: string; // Minimum UI5 Versions required for the specific OdataVersion
         };
+        // Function to determine if annotations can be generated for the specific template type
+        supportsAnnotations: (odataServiceVersion?: OdataVersion) => boolean;
     };
 };
 
@@ -148,39 +150,45 @@ export const TemplateTypeAttributes: TemplateAttributes = {
         minimumUi5Version: {
             [OdataVersion.v2]: minSupportedUI5Version,
             [OdataVersion.v4]: '1.99.0'
-        }
+        },
+        supportsAnnotations: (odataServiceVersion?: OdataVersion) => odataServiceVersion === OdataVersion.v4 && true
     },
     [TemplateType.ListReportObjectPage]: {
         supportedODataVersions: [OdataVersion.v2, OdataVersion.v4],
         minimumUi5Version: {
             [OdataVersion.v2]: minSupportedUI5Version,
             [OdataVersion.v4]: '1.84.0'
-        }
+        },
+        supportsAnnotations: (odataServiceVersion?: OdataVersion) => odataServiceVersion === OdataVersion.v4 && true
     },
     [TemplateType.AnalyticalListPage]: {
         supportedODataVersions: [OdataVersion.v2, OdataVersion.v4],
         minimumUi5Version: {
             [OdataVersion.v2]: minSupportedUI5Version,
             [OdataVersion.v4]: '1.90.0'
-        }
+        },
+        supportsAnnotations: () => false
     },
     [TemplateType.OverviewPage]: {
         supportedODataVersions: [OdataVersion.v2, OdataVersion.v4],
         minimumUi5Version: {
             [OdataVersion.v2]: minSupportedUI5Version,
             [OdataVersion.v4]: '1.96.8'
-        }
+        },
+        supportsAnnotations: () => false
     },
     [TemplateType.FormEntryObjectPage]: {
         supportedODataVersions: [OdataVersion.v4],
         minimumUi5Version: {
             [OdataVersion.v4]: '1.90.0'
-        }
+        },
+        supportsAnnotations: () => true
     },
     [TemplateType.FlexibleProgrammingModel]: {
         supportedODataVersions: [OdataVersion.v4],
         minimumUi5Version: {
             [OdataVersion.v4]: '1.94.0'
-        }
+        },
+        supportsAnnotations: () => false
     }
 };

packages/fiori-elements-writer/src/index.ts

@@ -22,6 +22,8 @@ import { initI18n } from './i18n';
 import { getBootstrapResourceUrls, getPackageScripts } from '@sap-ux/fiori-generator-shared';
 import { generateFpmConfig } from './fpmConfig';
 import { applyCAPUpdates, type CapProjectSettings } from '@sap-ux/cap-config-writer';
+import type { Logger } from '@sap-ux/logger';
+import { writeAnnotations } from './writeAnnotations';
 
 export const V2_FE_TYPES_AVAILABLE = '1.108.0';
 /**
@@ -50,15 +52,22 @@ function getTypeScriptIgnoreGlob<T extends {}>(feApp: FioriElementsApp<T>, coerc
     }
     return ignore;
 }
+
 /**
  * Generate a UI5 application based on the specified Fiori Elements floorplan template.
  *
  * @param basePath - the absolute target path where the application will be generated
  * @param data - configuration to generate the Fiori elements application
  * @param fs - an optional reference to a mem-fs editor
+ * @param log - optional logger instance
  * @returns Reference to a mem-fs-editor
  */
-async function generate<T extends {}>(basePath: string, data: FioriElementsApp<T>, fs?: Editor): Promise<Editor> {
+async function generate<T extends {}>(
+    basePath: string,
+    data: FioriElementsApp<T>,
+    fs?: Editor,
+    log?: Logger
+): Promise<Editor> {
     // Load i18n translations asynchronously to ensure proper initialization.
     // This addresses occasional issues where i18n is not initialized in time, causing tests to fail.
     await initI18n();
@@ -223,6 +232,7 @@ async function generate<T extends {}>(basePath: string, data: FioriElementsApp<T
         await applyCAPUpdates(fs, feApp.service.capService, settings);
     }
 
+    await writeAnnotations(basePath, feApp, fs, log);
     return fs;
 }
 

packages/fiori-elements-writer/src/translations/fiori-elements-writer.i18n.json

@@ -2,6 +2,9 @@
     "info": {
         "mockOnlyWarning": "This application was generated with a local metadata file and does not reference a live server. Please add the required server configuration or start this application with mock data using the target: npm run start-mock"
     },
+    "warn": {
+        "invalidTypeForAnnotationGeneration": "The provided option addAnnotations is not supported for the specified template '{{ templateType }}' and odata version '{{ odataVersion }}'. Generation will continue but additional annotations will not added."
+    },
     "error": {
         "unsupportedOdataVersion": "OData Version of the specified service: {{ serviceVersion }}, is not supported by the template type: {{ templateType }}",
         "unsupportedUI5Version": "Specified UI5 property '{{ versionProperty }}': {{ ui5Version }}, is not supported by the template type: {{ templateType }}. Please specify {{minRequiredUI5Version}} or above.",

packages/fiori-elements-writer/src/types.ts

@@ -120,6 +120,11 @@ export interface FioriElementsApp<T> extends Ui5App {
          * This will eventually move up to {@link Ui5App.appOptions}
          */
         addTests?: boolean;
+        /**
+         * If addAnnotations is true, annotations are enabled.
+         * However, annotations will only be written if the template type is lrop/worklist or formEntryObject; annotation genration is not uspported for other project types.
+         */
+        addAnnotations?: boolean;
     };
 }
 

packages/fiori-elements-writer/src/writeAnnotations.ts

@@ -0,0 +1,104 @@
+import { sep } from 'path';
+import { type CapServiceCdsInfo } from '@sap-ux/cap-config-writer';
+import { getCapFolderPathsSync } from '@sap-ux/fiori-generator-shared';
+import { TemplateType, type EntityConfig, type FioriElementsApp } from './types';
+import {
+    generateAnnotations,
+    type AnnotationServiceParameters,
+    type GenerateAnnotationsOptions
+} from '@sap-ux/annotation-generator';
+import type { Editor } from 'mem-fs-editor';
+import type { OdataVersion } from '@sap-ux/odata-service-writer';
+import { TemplateTypeAttributes } from './data/templateAttributes';
+import type { Logger } from '@sap-ux/logger';
+import { t } from './i18n';
+
+/**
+ * Generates the annotation file path based on whether the CAP service is available.
+ *
+ * @param {string} [appName] - The name of the application.
+ * @param {CapServiceCdsInfo} [capService] - The CAP service info.
+ * @returns {string} The annotation file path based on whether the CAP service is available.
+ */
+function getAnnotationFilePath(appName?: string, capService?: CapServiceCdsInfo): string {
+    if (capService) {
+        const appPath = capService.appPath ?? getCapFolderPathsSync(capService.projectPath).app;
+        return `${appPath}${sep}${appName}${sep}annotations.cds`;
+    }
+    return `webapp${sep}annotations${sep}annotation.xml`;
+}
+
+/**
+ * Determines if annotations can be generated for a given template.
+ *
+ * @param {OdataVersion} odataServiceVersion - The version of the OData service being used.
+ * @param {TemplateType} templateType - The type of the template being used by app.
+ * @param {boolean} [addAnnotations] - An optional flag indicating whether annotations should be enabled.
+ * @returns {boolean} - Returns `true` if annotations can be generated, otherwise `false`.
+ */
+export function canGenerateAnnotationsForTemplate(
+    odataServiceVersion: OdataVersion,
+    templateType: TemplateType,
+    addAnnotations: boolean = false
+): boolean | undefined {
+    return addAnnotations && TemplateTypeAttributes[templateType].supportsAnnotations(odataServiceVersion);
+}
+
+/**
+ * Writes annotation files for the given application configuration.
+ *
+ * @param basePath - The base directory path of the project.
+ * @param feApp -  to generate the Fiori elements application
+ * @param fs - The file system editor instance.
+ * @param log - Logger instance.
+ */
+export async function writeAnnotations<T extends {}>(
+    basePath: string,
+    feApp: FioriElementsApp<T>,
+    fs: Editor,
+    log?: Logger
+): Promise<void> {
+    // Check if annotations should be generated
+    if (
+        canGenerateAnnotationsForTemplate(feApp.service.version, feApp.template.type, feApp.appOptions?.addAnnotations)
+    ) {
+        const { settings } = feApp.template;
+        const { capService } = feApp.service;
+        const { name: packageName } = feApp.package ?? {};
+        const entitySetName = (settings as T & { entityConfig?: EntityConfig })?.entityConfig?.mainEntityName ?? '';
+
+        const addLineItems =
+            feApp.template.type === TemplateType.ListReportObjectPage || feApp.template.type === TemplateType.Worklist;
+
+        let serviceName = 'mainService';
+        let projectPath = basePath;
+
+        if (capService) {
+            serviceName = capService.serviceName;
+            projectPath = capService.projectPath;
+        }
+
+        const options: GenerateAnnotationsOptions = {
+            entitySetName: entitySetName,
+            annotationFilePath: getAnnotationFilePath(packageName, capService),
+            addFacets: true,
+            addLineItems,
+            addValueHelps: !!capService
+        };
+
+        const serviceParameters: AnnotationServiceParameters = {
+            serviceName,
+            appName: packageName,
+            project: projectPath
+        };
+
+        await generateAnnotations(fs, serviceParameters, options);
+    } else {
+        log?.warn(
+            t('warn.invalidTypeForAnnotationGeneration', {
+                templateType: feApp.template.type,
+                odataVersion: feApp.service.version
+            })
+        );
+    }
+}

packages/fiori-elements-writer/test/common.ts

@@ -10,12 +10,14 @@ import {
     type FEOPSettings,
     type FioriElementsApp,
     type LROPSettings,
-    type WorklistSettings
+    type WorklistSettings,
+    TemplateType
 } from '../src/types';
 import { promisify } from 'util';
 import { exec as execCP } from 'child_process';
 const exec = promisify(execCP);
 import { ServiceType } from '@sap-ux/odata-service-writer';
+import { type CapServiceCdsInfo } from '@sap-ux/cap-config-writer';
 
 export const testOutputDir = join(__dirname, 'test-output');
 
@@ -201,3 +203,43 @@ export const projectChecks = async (
         expect(error).toBeUndefined();
     }
 };
+
+export const sampleCapService: CapServiceCdsInfo = {
+    cdsUi5PluginInfo: {
+        isCdsUi5PluginEnabled: true,
+        hasMinCdsVersion: true,
+        isWorkspaceEnabled: true,
+        hasCdsUi5Plugin: true
+    },
+    projectPath: join('test'),
+    serviceName: 'mainService',
+    capType: 'Node.js',
+    appPath: join('test', 'path')
+};
+
+/**
+ *
+ * @param name name of the app
+ * @param templateType template type of the app
+ * @returns a Fiori Elements App of provided template type
+ */
+export const applyBaseConfigToFEApp = (name: string, templateType: TemplateType) => {
+    const addUi5Config = templateType === TemplateType.Worklist;
+    const appInfo = feBaseConfig(name, !addUi5Config);
+    return {
+        ...Object.assign(appInfo, {
+            template: {
+                type: templateType,
+                settings: v4TemplateSettings
+            }
+        }),
+        service: {
+            version: OdataVersion.v4,
+            capService: sampleCapService
+        },
+        package: {
+            ...appInfo.package,
+            sapuxLayer: 'CUSTOMER_BASE'
+        }
+    } as FioriElementsApp<LROPSettings>;
+};

packages/fiori-elements-writer/test/feop.test.ts

@@ -9,15 +9,27 @@ import {
     v4TemplateSettings,
     v4Service,
     projectChecks,
-    updatePackageJSONDependencyToUseLocalPath
+    updatePackageJSONDependencyToUseLocalPath,
+    applyBaseConfigToFEApp,
+    sampleCapService
 } from './common';
 import type { FEOPSettings } from '../src/types';
+import type { CapServiceCdsInfo } from '@sap-ux/cap-config-writer';
+import { OdataVersion } from '@sap-ux/odata-service-writer';
+import { create as createStorage } from 'mem-fs';
+import { create } from 'mem-fs-editor';
+import { generateAnnotations } from '@sap-ux/annotation-generator';
 
 const TEST_NAME = 'feopTemplate';
 if (debug?.enabled) {
     jest.setTimeout(360000);
 }
 
+jest.mock('@sap-ux/annotation-generator', () => ({
+    ...jest.requireActual('@sap-ux/annotation-generator'),
+    generateAnnotations: jest.fn()
+}));
+
 describe(`Fiori Elements template: ${TEST_NAME}`, () => {
     const curTestOutPath = join(testOutputDir, TEST_NAME);
 
@@ -73,3 +85,52 @@ describe(`Fiori Elements template: ${TEST_NAME}`, () => {
         });
     });
 });
+
+describe('Should generate annotations correctly for FEOP projects', () => {
+    const curTestOutPath = join(testOutputDir, TEST_NAME);
+    const fs = create(createStorage());
+
+    afterEach(() => {
+        jest.clearAllMocks();
+        jest.resetAllMocks();
+    });
+
+    test('Should generate annotations for FEOP projects when addAnnotations is enabled, regardless of service availability', async () => {
+        const fioriElementsApp = {
+            ...applyBaseConfigToFEApp('fefeop1', TemplateType.FormEntryObjectPage),
+            appOptions: {
+                addAnnotations: true
+            }
+        };
+        await generate(curTestOutPath, fioriElementsApp, fs);
+        expect(generateAnnotations).toBeCalledTimes(1);
+
+        // ensure addLineItems is false for feop project
+        expect(generateAnnotations).toBeCalledWith(
+            fs,
+            {
+                serviceName: sampleCapService.serviceName,
+                appName: fioriElementsApp.package.name,
+                project: sampleCapService.projectPath
+            },
+            {
+                entitySetName: v4TemplateSettings?.entityConfig?.mainEntityName,
+                annotationFilePath: join('test', 'path', 'fefeop1', 'annotations.cds'),
+                addFacets: true,
+                addLineItems: false,
+                addValueHelps: true
+            }
+        );
+    });
+
+    test('Should generate annotations for FEOP projects when addAnnotations is disabled', async () => {
+        const fioriElementsApp = {
+            ...applyBaseConfigToFEApp('fefeop1', TemplateType.FormEntryObjectPage),
+            appOptions: {
+                addAnnotations: false
+            }
+        };
+        await generate(curTestOutPath, fioriElementsApp, fs);
+        expect(generateAnnotations).not.toBeCalled();
+    });
+});