feat: New public method for ApplicationAccess - readManifest, readFlexChanges, readAnnotationFiles (#3854)

815are · Klaus-Keller · web-flow · commit 7c09c8e29983 · 2025-11-24T12:16:56.000+02:00
* feat: new public methods for application access

new public methods for application access

* changeset

changeset

* fix: review comments

review comments

---------

Co-authored-by: Klaus Keller &lt;66327622+Klaus-Keller@users.noreply.github.com&gt;
diff --git a/.changeset/great-rivers-lick.md b/.changeset/great-rivers-lick.md
@@ -0,0 +1,8 @@
+---
+'@sap-ux/project-access': patch
+---
+
+New public method for `ApplicationAccess`
+- `readManifest` - reads and returns the parsed `manifest.json` file for the application.
+- `readFlexChanges` - reads and returns all Flex Changes (`*.change` files) associated with the application.
+- `readAnnotationFiles` - reads and returns all annotation files associated with the application's main service.
diff --git a/packages/project-access/src/project/access.ts b/packages/project-access/src/project/access.ts
@@ -11,7 +11,8 @@ import type {
     ProjectType,
     ApplicationStructure,
     Package,
-    Manifest
+    Manifest,
+    AnnotationFile
 } from '../types';
 
 import {
@@ -27,9 +28,11 @@ import { getProject } from './info';
 import { findAllApps } from './search';
 
 import type { Editor } from 'mem-fs-editor';
-import { updateManifestJSON, updatePackageJSON } from '../file';
+import { readFile, readJSON, updateManifestJSON, updatePackageJSON } from '../file';
 import { FileName } from '../constants';
 import { getSpecification } from './specification';
+import { readFlexChanges } from './flex-changes';
+import { readCapServiceMetadataEdmx } from './cap';
 
 /**
  *
@@ -202,6 +205,72 @@ class ApplicationAccessImp implements ApplicationAccess {
         await updateManifestJSON(this.app.manifest, manifest, memFs ?? this.options?.fs);
     }
 
+    /**
+     * Reads and returns the parsed `manifest.json` file for the application.
+     *
+     * @param memFs - optional mem-fs-editor instance
+     * @returns A promise resolving to the parsed `manifest.json` content.
+     */
+    async readManifest(memFs?: Editor): Promise<Manifest> {
+        return readJSON<Manifest>(this.app.manifest, memFs ?? this.options?.fs);
+    }
+
+    /**
+     * Reads and returns all Flex Changes (`*.change` files) associated with the application.
+     *
+     * @param memFs - optional mem-fs-editor instance
+     * @returns A promise that resolves to an array of flex change files.
+     */
+    async readFlexChanges(memFs?: Editor): Promise<{
+        [key: string]: string;
+    }> {
+        return readFlexChanges(this.app.changes, memFs ?? this.options?.fs);
+    }
+
+    /**
+     * Reads and returns all annotation files associated with the application's main service.
+     *
+     * @param memFs - optional mem-fs-editor instance
+     * @returns A promise resolving to an array of annotation file descriptors.
+     */
+    async readAnnotationFiles(memFs?: Editor): Promise<AnnotationFile[]> {
+        const annotationData: AnnotationFile[] = [];
+        const mainServiceName = this.app.mainService ?? 'mainService';
+        const mainService = this.app?.services?.[mainServiceName];
+        if (!mainService) {
+            return [];
+        }
+        if (mainService.uri && (this.projectType === 'CAPJava' || this.projectType === 'CAPNodejs')) {
+            const serviceUri = mainService?.uri ?? '';
+            if (serviceUri) {
+                const edmx = await readCapServiceMetadataEdmx(this.root, serviceUri);
+                annotationData.push({
+                    fileContent: edmx,
+                    dataSourceUri: serviceUri
+                });
+            }
+        } else {
+            if (mainService.local) {
+                const serviceFile = await readFile(mainService.local, memFs ?? this.options?.fs);
+                annotationData.push({
+                    dataSourceUri: mainService.local,
+                    fileContent: serviceFile.toString()
+                });
+            }
+            const { annotations = [] } = mainService;
+            for (const annotation of annotations) {
+                if (annotation.local) {
+                    const annotationFile = await readFile(annotation.local, memFs ?? this.options?.fs);
+                    annotationData.push({
+                        dataSourceUri: annotation.local,
+                        fileContent: annotationFile.toString()
+                    });
+                }
+            }
+        }
+        return annotationData;
+    }
+
     /**
      * Project structure.
      *
diff --git a/packages/project-access/src/types/access/index.ts b/packages/project-access/src/types/access/index.ts
@@ -4,7 +4,7 @@ import type { I18nBundles } from '../i18n';
 import type { ApplicationStructure, I18nPropertiesPaths, Project, ProjectType } from '../info';
 import type { Editor } from 'mem-fs-editor';
 import type { Package } from '../package';
-import type { Manifest } from '../webapp';
+import type { AnnotationFile, Manifest } from '../webapp';
 
 interface BaseAccess {
     readonly project: Project;
@@ -118,6 +118,32 @@ export interface ApplicationAccess extends BaseAccess {
      * @param memFs - optional mem-fs-editor instance
      */
     updateManifestJSON(manifest: Manifest, memFs?: Editor): Promise<void>;
+
+    /**
+     * Reads and returns the parsed `manifest.json` file for the application.
+     *
+     * @param memFs - optional mem-fs-editor instance
+     * @returns A promise resolving to the parsed `manifest.json` content.
+     */
+    readManifest(memFs?: Editor): Promise<Manifest>;
+
+    /**
+     * Reads and returns all Flex Changes (`*.change` files) associated with the application.
+     *
+     * @param memFs - optional mem-fs-editor instance
+     * @returns A promise that resolves to an array of flex change files.
+     */
+    readFlexChanges(memFs?: Editor): Promise<{
+        [key: string]: string;
+    }>;
+
+    /**
+     * Reads and returns all annotation files associated with the application's main service.
+     *
+     * @param memFs - optional mem-fs-editor instance
+     * @returns A promise resolving to an array of annotation file descriptors.
+     */
+    readAnnotationFiles(memFs?: Editor): Promise<AnnotationFile[]>;
 }
 
 export interface ProjectAccessOptions {
diff --git a/packages/project-access/src/types/webapp/index.ts b/packages/project-access/src/types/webapp/index.ts
@@ -2,3 +2,8 @@ import type * as ManifestNamespace from '@ui5/manifest/types/manifest';
 
 export { ManifestNamespace };
 export type Manifest = ManifestNamespace.SAPJSONSchemaForWebApplicationManifestFile;
+
+export interface AnnotationFile {
+    dataSourceUri: string;
+    fileContent: string;
+}
diff --git a/packages/project-access/test/project/access.test.ts b/packages/project-access/test/project/access.test.ts
@@ -3,9 +3,11 @@ import type { Manifest, Package } from '../../src';
 import { createApplicationAccess, createProjectAccess } from '../../src';
 import * as i18nMock from '../../src/project/i18n/write';
 import * as specMock from '../../src/project/specification';
+import * as capMock from '../../src/project/cap';
 import { create as createStorage } from 'mem-fs';
 import { create } from 'mem-fs-editor';
 import { promises } from 'node:fs';
+import { readFile, readJSON } from '../../src/file';
 
 describe('Test function createApplicationAccess()', () => {
     const memFs = create(createStorage());
@@ -373,6 +375,165 @@ describe('Test function createApplicationAccess()', () => {
             expect(error.message).toContain('non-existing-app');
         }
     });
+
+    test('Read manifest.json of standalone app without mem-fs', async () => {
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot);
+        const manifest = await appAccess.readManifest();
+        // Result check
+        expect(manifest).toEqual(await readJSON(join(appRoot, 'webapp/manifest.json')));
+    });
+
+    test('Read manifest.json of standalone app with mem-fs', async () => {
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        const manifestPath = join(appRoot, 'webapp/manifest.json');
+        const newManifest = await readJSON<{ dummy: boolean }>(join(appRoot, 'webapp/manifest.json'), memFs);
+        newManifest.dummy = true;
+        memFs.writeJSON(manifestPath, newManifest, undefined, 4);
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot);
+        const manifest = await appAccess.readManifest(memFs);
+        // Result check
+        expect('dummy' in manifest ? manifest.dummy : undefined).toEqual(true);
+    });
+
+    test('Read manifest.json of standalone app with mem-fs(mem-fs is passed on creation)', async () => {
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        const manifestPath = join(appRoot, 'webapp/manifest.json');
+        const newManifest = await readJSON<{ dummy: string }>(join(appRoot, 'webapp/manifest.json'), memFs);
+        newManifest.dummy = 'Test';
+        memFs.writeJSON(manifestPath, newManifest, undefined, 4);
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot, memFs);
+        const manifest = await appAccess.readManifest();
+        // Result check
+        expect('dummy' in manifest ? manifest.dummy : undefined).toEqual('Test');
+    });
+
+    test('Read flex changes of standalone app without mem-fs - without flex changes', async () => {
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot);
+        const changes = await appAccess.readFlexChanges();
+        // Result check
+        expect(Object.keys(changes)).toEqual([]);
+    });
+
+    test('Read flex changes of standalone app without mem-fs - with flex changes', async () => {
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot);
+        // Mock changes folder
+        appAccess.app.changes = join(__dirname, '../test-data/project/flex-changes/webapp/changes');
+        const changes = await appAccess.readFlexChanges();
+        // Result check
+        expect(Object.keys(changes)).toEqual([
+            'id_1761320220775_1_propertyChange.change',
+            'id_1761320220775_2_propertyChange.change'
+        ]);
+    });
+
+    test('Read flex changes with mem-fs', async () => {
+        const changeFileName = 'id_1761320220775_1_propertyChange.change';
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        const changesPath = join(__dirname, '../test-data/project/flex-changes/webapp/changes');
+        const changeFilePath = join(changesPath, changeFileName);
+        memFs.write(changeFilePath, '{"dummy": true}');
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot);
+        appAccess.app.changes = changesPath;
+        const changes = await appAccess.readFlexChanges(memFs);
+        // Result check
+        expect(changes[changeFileName]).toEqual('{"dummy": true}');
+    });
+
+    test('Read flex changes with mem-fs(mem-fs is passed on creation)', async () => {
+        const changeFileName = 'id_1761320220775_1_propertyChange.change';
+        const appRoot = join(sampleRoot, 'fiori_elements');
+        const changesPath = join(__dirname, '../test-data/project/flex-changes/webapp/changes');
+        const changeFilePath = join(changesPath, changeFileName);
+        memFs.write(changeFilePath, '{"dummy": "test"}');
+        // Test execution
+        const appAccess = await createApplicationAccess(appRoot, memFs);
+        appAccess.app.changes = changesPath;
+        const changes = await appAccess.readFlexChanges();
+        // Result check
+        expect(changes[changeFileName]).toEqual('{"dummy": "test"}');
+    });
+
+    describe('readAnnotationFiles', () => {
+        test('Read annotation files of standalone EDMX app without mem-fs', async () => {
+            const appRoot = join(sampleRoot, 'fiori_elements');
+            // Test execution
+            const appAccess = await createApplicationAccess(appRoot);
+            const annotationFiles = await appAccess.readAnnotationFiles();
+            // Result check
+            expect(annotationFiles.map((annotationFile) => annotationFile.dataSourceUri)).toEqual([
+                join(appRoot, 'webapp/localService/metadata.xml'),
+                join(appRoot, 'webapp/annotations/annotation.xml')
+            ]);
+            expect(annotationFiles[0].fileContent.includes('Alias="Measures"')).toBeTruthy();
+            expect(annotationFiles[1].fileContent.includes('/catalog-admin-noauth/$metadata')).toBeTruthy();
+        });
+
+        test('Read annotation files of standalone EDMX app with mem-fs', async () => {
+            const appRoot = join(sampleRoot, 'fiori_elements');
+            const expectedFiles = [
+                join(appRoot, 'webapp/localService/metadata.xml'),
+                join(appRoot, 'webapp/annotations/annotation.xml')
+            ];
+            memFs.write(expectedFiles[0], 'Test metadata.xml');
+            memFs.write(expectedFiles[1], 'Test annotation.xml');
+            // Test execution
+            const appAccess = await createApplicationAccess(appRoot);
+            const annotationFiles = await appAccess.readAnnotationFiles(memFs);
+            // Result check
+            expect(annotationFiles.map((annotationFile) => annotationFile.dataSourceUri)).toEqual(expectedFiles);
+            expect(annotationFiles[0].fileContent).toEqual('Test metadata.xml');
+            expect(annotationFiles[1].fileContent).toEqual('Test annotation.xml');
+        });
+
+        test('Read annotation files of standalone EDMX app with mem-fs(mem-fs is passed on creation)', async () => {
+            const appRoot = join(sampleRoot, 'fiori_elements');
+            const expectedFiles = [
+                join(appRoot, 'webapp/localService/metadata.xml'),
+                join(appRoot, 'webapp/annotations/annotation.xml')
+            ];
+            memFs.write(expectedFiles[0], 'Test2 metadata.xml');
+            memFs.write(expectedFiles[1], 'Test2 annotation.xml');
+            // Make sure manifest.json has original content in mem-fs
+            const manifestPath = join(appRoot, 'webapp/manifest.json');
+            const originalManifest = await readJSON<{ dummy: string }>(join(appRoot, 'webapp/manifest.json'));
+            memFs.writeJSON(manifestPath, originalManifest, undefined, 4);
+            // Test execution
+            const appAccess = await createApplicationAccess(appRoot, memFs);
+            const annotationFiles = await appAccess.readAnnotationFiles();
+            // Result check
+            expect(annotationFiles.map((annotationFile) => annotationFile.dataSourceUri)).toEqual(expectedFiles);
+            expect(annotationFiles[0].fileContent).toEqual('Test2 metadata.xml');
+            expect(annotationFiles[1].fileContent).toEqual('Test2 annotation.xml');
+        });
+
+        test('Read annotation files of CAP app', async () => {
+            // Mock setup
+            const mockedMetadata = await readFile(
+                join(sampleRoot, 'fiori_elements', 'webapp/localService/metadata.xml')
+            );
+            jest.spyOn(capMock, 'readCapServiceMetadataEdmx').mockResolvedValue(mockedMetadata);
+
+            const projectRoot = join(sampleRoot, 'cap-project');
+            const appRoot = join(projectRoot, 'apps/two');
+            // Test execution
+            const appAccess = await createApplicationAccess(appRoot);
+            const annotationFiles = await appAccess.readAnnotationFiles();
+            // Result check
+            expect(annotationFiles.map((annotationFile) => annotationFile.dataSourceUri)).toEqual([
+                '/sap/opu/odata4/dmo/ODATA_SERVICE/'
+            ]);
+            expect(annotationFiles[0].fileContent.includes('Alias="Measures"')).toBeTruthy();
+        });
+    });
 });
 
 describe('Test function createProjectAccess()', () => {
diff --git a/packages/project-access/test/test-data/project/info/fiori_elements/webapp/annotations/annotation.xml b/packages/project-access/test/test-data/project/info/fiori_elements/webapp/annotations/annotation.xml
@@ -0,0 +1,18 @@
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
+    <edmx:Reference Uri="/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/Vocabularies(TechnicalName='%2FIWBEP%2FVOC_COMMON',Version='0001',SAP__Origin='LOCAL')/$value">
+        <edmx:Include Namespace="com.sap.vocabularies.Common.v1" Alias="Common"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/Vocabularies(TechnicalName='%2FIWBEP%2FVOC_UI',Version='0001',SAP__Origin='LOCAL')/$value">
+        <edmx:Include Namespace="com.sap.vocabularies.UI.v1" Alias="UI"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="/sap/opu/odata/IWFND/CATALOGSERVICE;v=2/Vocabularies(TechnicalName='%2FIWBEP%2FVOC_COMMUNICATION',Version='0001',SAP__Origin='LOCAL')/$value">
+        <edmx:Include Namespace="com.sap.vocabularies.Communication.v1" Alias="Communication"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="/catalog-admin-noauth/$metadata">
+        <edmx:Include Namespace="sap.capire.officesupplies.CatalogAdminNoauth" Alias="sap.capire.officesupplies.CatalogAdminNoauth"/>
+    </edmx:Reference>
+    <edmx:DataServices>
+        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Namespace1">
+        </Schema>
+    </edmx:DataServices>
+</edmx:Edmx>
diff --git a/packages/project-access/test/test-data/project/info/fiori_elements/webapp/localService/metadata.xml b/packages/project-access/test/test-data/project/info/fiori_elements/webapp/localService/metadata.xml
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
+    <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.xml">
+        <edmx:Include Alias="Capabilities" Namespace="Org.OData.Capabilities.V1"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/Common.xml">
+        <edmx:Include Alias="Common" Namespace="com.sap.vocabularies.Common.v1"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/Communication.xml">
+        <edmx:Include Alias="Communication" Namespace="com.sap.vocabularies.Communication.v1"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml">
+        <edmx:Include Alias="Core" Namespace="Org.OData.Core.V1"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Measures.V1.xml">
+        <edmx:Include Alias="Measures" Namespace="Org.OData.Measures.V1"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/UI.xml">
+        <edmx:Include Alias="UI" Namespace="com.sap.vocabularies.UI.v1"/>
+    </edmx:Reference>
+    <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Validation.V1.xml">
+        <edmx:Include Alias="Validation" Namespace="Org.OData.Validation.V1"/>
+    </edmx:Reference>
+    <edmx:DataServices>
+        <Schema Namespace="sap.officesupplies.Catalog" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+        </Schema>
+    </edmx:DataServices>
+</edmx:Edmx>
diff --git a/packages/project-access/test/test-data/project/info/fiori_elements/webapp/manifest.json b/packages/project-access/test/test-data/project/info/fiori_elements/webapp/manifest.json
