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/writeAnnotations.ts

@@ -0,0 +1,102 @@
+import { sep } from 'path';
+import { type CapServiceCdsInfo } from '@sap-ux/cap-config-writer';
+import { getCapFolderPathsSync } from '@sap-ux/fiori-generator-shared';
+import { TemplateType } 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';
+
+/**
+ * The list of template types that support generation of annotations.
+ */
+export const annotationSupportedTemplateTypes: TemplateType[] = [
+    TemplateType.ListReportObjectPage,
+    TemplateType.Worklist,
+    TemplateType.FormEntryObjectPage
+];
+
+/**
+ * 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 {
+    return addAnnotations && annotationSupportedTemplateTypes.includes(templateType) && odataServiceVersion === '4';
+}
+
+/**
+ * Writes annotation files for the given application configuration.
+ *
+ * @param {string} basePath - The base directory path of the project.
+ * @param {object} appInfo - Information about the application.
+ * @param {Template} appInfo.templateType - The template type of the application.
+ * @param {string} appInfo.packageName - The package name of the application.
+ * @param {string} appInfo.entitySetName - The entity set name associated with the annotations.
+ * @param {CapServiceCdsInfo} [appInfo.capService] - Optional CAP service information.
+ * @param {Editor} fs - The file system editor instance.
+ * @returns {Promise<void>} A promise that resolves when the annotation files are successfully generated.
+ */
+export async function writeAnnotations(
+    basePath: string,
+    appInfo: {
+        templateType: TemplateType;
+        packageName?: string;
+        entitySetName: string;
+        capService?: CapServiceCdsInfo;
+    },
+    fs: Editor
+): Promise<void> {
+    let serviceName = 'mainService';
+    let projectPath = basePath;
+
+    // Determine whether to add line items
+    const addLineItems =
+        appInfo.templateType === TemplateType.ListReportObjectPage || appInfo.templateType === TemplateType.Worklist;
+
+    if (appInfo.capService) {
+        serviceName = appInfo.capService.serviceName;
+        projectPath = appInfo.capService.projectPath;
+    }
+
+    const options: GenerateAnnotationsOptions = {
+        entitySetName: appInfo.entitySetName,
+        annotationFilePath: getAnnotationFilePath(appInfo.packageName, appInfo.capService),
+        addFacets: true,
+        addLineItems,
+        addValueHelps: !!appInfo.capService
+    };
+
+    const serviceParameters: AnnotationServiceParameters = {
+        serviceName,
+        appName: appInfo.packageName,
+        project: projectPath
+    };
+
+    await generateAnnotations(fs, serviceParameters, options);
+}

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

@@ -6,7 +6,7 @@ import { generate as generateUi5Project } from '@sap-ux/ui5-application-writer';
 import { generate as addOdataService, OdataVersion, ServiceType } from '@sap-ux/odata-service-writer';
 import { generateOPAFiles } from '@sap-ux/ui5-test-writer';
 import cloneDeep from 'lodash/cloneDeep';
-import type { FioriElementsApp } from './types';
+import type { FioriElementsApp, EntityConfig } from './types';
 import { TemplateType } from './types';
 import { validateApp, validateRequiredProperties } from './validate';
 import { setAppDefaults, setDefaultTemplateSettings, getTemplateOptions } from './data/defaults';
@@ -18,10 +18,16 @@ import {
 } from './data/templateAttributes';
 import { extendManifestJson } from './data/manifestSettings';
 import semVer from 'semver';
-import { initI18n } from './i18n';
+import { initI18n, t } 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,
+    canGenerateAnnotationsForTemplate,
+    annotationSupportedTemplateTypes
+} from './data/writeAnnotations';
 
 export const V2_FE_TYPES_AVAILABLE = '1.108.0';
 /**
@@ -50,15 +56,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 +236,33 @@ async function generate<T extends {}>(basePath: string, data: FioriElementsApp<T
         await applyCAPUpdates(fs, feApp.service.capService, settings);
     }
 
+    // Handle annotation writing
+    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 ?? '';
+
+        await writeAnnotations(
+            basePath,
+            {
+                templateType: feApp.template.type,
+                packageName: packageName,
+                entitySetName: entitySetName,
+                capService: capService
+            },
+            fs
+        );
+    } else {
+        log?.warn(
+            t('warn.invalidTypeForAnnotationGeneration', {
+                templateType: feApp.template.type,
+                supportedTypes: annotationSupportedTemplateTypes
+            })
+        );
+    }
     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": "Invalid template type '{{ templateType }}' for annotation generation. Supported types are: {{ supportedTypes }}"
+    },
     "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/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();
+    });
+});