Feat: add sap-description-column-label ESLint rule

.changeset/rich-meals-shake.md

@@ -0,0 +1,7 @@
+---
+'@sap-ux/xml-odata-annotation-converter': minor
+'@sap-ux/odata-annotation-core-types': minor
+'@sap-ux/eslint-plugin-fiori-tools': minor
+---
+
+[rule] Add rule to check that a Common.Text description property has a meaningful Common.Label

packages/eslint-plugin-fiori-tools/README.md

@@ -120,7 +120,8 @@ npx --yes @sap-ux/create@latest convert eslint-config --help
 
 |   Since   | Rule | Description | Recommended | Recommended for S/4HANA |
 |:---------:|------|-------------|:-----------:|:-----------------------:|
-|  new      | [sap-text-arrangement-hidden](docs/rules/sap-text-arrangement-hidden.md) | Ensures that the text property referenced by a `UI.TextArrangement` annotation using the `Common.Text` annotation is not hidden by the `UI.Hidden` annotation | | ✅ |
+|  new      | [sap-description-column-label](docs/rules/sap-description-column-label.md) | Ensures that the description (text) property referenced via `Common.Text` has a meaningful `Common.Label` — not a generic value such as `"Name"` or `"Description"`, and not the same label as the ID property. | | ✅ |
+|  9.12.0   | [sap-text-arrangement-hidden](docs/rules/sap-text-arrangement-hidden.md) | Ensures that the text property referenced by a `UI.TextArrangement` annotation using the `Common.Text` annotation is not hidden by the `UI.Hidden` annotation | | ✅ |
 |  9.11.0   | [sap-no-data-field-intent-based-navigation](docs/rules/sap-no-data-field-intent-based-navigation.md) | Ensures neither `DataFieldForIntentBasedNavigation` nor `DataFieldWithIntentBasedNavigation` are used in tables or form fields in SAP Fiori elements applications. | | ✅ |
 |  9.10.0   | [sap-condensed-table-layout](docs/rules/sap-condensed-table-layout.md) | Requires `condensedTableLayout` to be enabled when using a grid table, analytical table, or tree table. | | ✅ |
 |   9.9.0   | [sap-strict-uom-filtering](docs/rules/sap-strict-uom-filtering.md) | Ensures that `disableStrictUomFiltering` is not set to `true` in `sap.fe.app` manifest configuration | | ✅ |

packages/eslint-plugin-fiori-tools/docs/rules/sap-description-column-label.md

@@ -0,0 +1,135 @@
+# Require Meaningful Labels for Description (Text) Properties (`sap-description-column-label`)
+
+Ensures that the property referenced as the description (text) value via the `Common.Text` annotation has a meaningful `Common.Label` annotation — not a generic value such as `"Name"` or `"Description"`, and not the same label as the ID property it describes.
+
+## Rule Details
+
+When a field uses the `Common.Text` annotation to associate a human-readable description property with a technical key property, the description property should carry a `Common.Label` annotation that clearly identifies its content. A generic label like `"Name"` or `"Description"` provides no useful context to the user in the UI (for example, as a column header in a table), and a label that is identical to the ID property's label creates ambiguity between the two columns.
+
+The rule checks every `Common.Text` annotation on a property that belongs to an entity type used in the application (i.e. linked to at least one page via the manifest). For each such annotation the rule:
+
+1. Resolves the path to the referenced text property (including navigation segments such as `category/name`).
+2. Reads the `Common.Label` annotation on that property.
+3. Flags the annotation if the label is `"Name"` or `"Description"` (case-insensitive) — **trivialLabel**.
+4. Flags the annotation if the label is identical (case-insensitive) to the `Common.Label` annotation of the ID property that carries the `Common.Text` annotation — **duplicateLabel**.
+
+If the text property has no `Common.Label` annotation, the rule does not flag it.
+
+> **OData V2**: The rule also applies to OData V2 services. In V2 metadata, the `sap:text` attribute on a `Property` element is treated as an implicit `Common.Text` annotation, and the `sap:label` attribute is treated as an implicit `Common.Label` annotation. The rule reports on the metadata file directly when these inline attributes produce a trivial or duplicate label.
+
+### Why Was This Rule Introduced?
+
+When a property is displayed using a description column (e.g. `TextArrangement/TextOnly`), the column header comes from the `Common.Label` annotation of the text property. A label of `"Name"` or `"Description"` is semantically meaningless in that context — it does not tell the user _which_ name or description is shown. Similarly, if the description column carries the exact same label as the ID column, the user cannot distinguish the two columns.
+
+### Warning Messages
+
+**trivialLabel**
+```
+The text property "{{textPropertyTarget}}" has a generic label "{{textPropertyLabel}}". Use a more descriptive label that distinguishes it from other properties.
+```
+
+**duplicateLabel**
+```
+The text property "{{textPropertyTarget}}" has the same label "{{textPropertyLabel}}" as the ID property "{{idPropertyTarget}}". The description column label should be different from the ID label.
+```
+
+## Examples
+
+### Incorrect Annotations
+
+**`trivialLabel` — the `Common.Label` annotation on the text property is too generic:**
+
+```xml
+<!-- ProductBaseUnit uses UnitOfMeasure_Text as its description column via Common.Text annotation -->
+<Annotations Target="MyService.MyEntity/ProductBaseUnit">
+    <Annotation Term="Common.Text" Path="to_BaseUnit/UnitOfMeasure_Text"/>
+</Annotations>
+
+<!-- The Common.Label annotation on the description property is "Name" — too generic -->
+<Annotations Target="MyService.BaseUnitType/UnitOfMeasure_Text">
+    <Annotation Term="Common.Label" String="Name"/>
+</Annotations>
+```
+
+**`duplicateLabel` — the `Common.Label` annotation on the text property is identical to the ID property label:**
+
+```xml
+<!-- Supplier uses CompanyName as its description column via Common.Text annotation, both properties have label "Supplier" -->
+<Annotations Target="MyService.MyEntity/Supplier">
+    <Annotation Term="Common.Text" Path="to_Supplier/CompanyName"/>
+    <Annotation Term="Common.Label" String="Supplier"/>
+</Annotations>
+
+<!-- Common.Label annotation identical to the ID property above — ambiguous column headers -->
+<Annotations Target="MyService.SupplierType/CompanyName">
+    <Annotation Term="Common.Label" String="Supplier"/>
+</Annotations>
+```
+
+**OData V2 `trivialLabel` — inline `sap:label` on the text property is too generic (reported on the metadata file):**
+
+```xml
+<!-- sap:text attribute acts as an implicit Common.Text annotation -->
+<Property Name="Product" Type="Edm.String" sap:text="ProductName" sap:label="Product ID" />
+<!-- sap:label="Name" acts as an implicit Common.Label annotation — too generic -->
+<Property Name="ProductName" Type="Edm.String" sap:label="Name" />
+```
+
+**OData V2 `duplicateLabel` — inline `sap:label` values on ID and text property are identical:**
+
+```xml
+<!-- Both properties carry sap:label="Quantity Unit" via inline sap:label attribute -->
+<Property Name="QuantityUnit" Type="Edm.String" sap:text="QuantityUnitT" sap:label="Quantity Unit" />
+<Property Name="QuantityUnitT" Type="Edm.String" sap:label="Quantity Unit" />
+```
+
+### Correct Annotations
+
+**Meaningful, distinct `Common.Label` annotation on the text property:**
+
+```xml
+<Annotations Target="MyService.MyEntity/ProductBaseUnit">
+    <Annotation Term="Common.Text" Path="to_BaseUnit/UnitOfMeasure_Text"/>
+</Annotations>
+
+<!-- Common.Label annotation with a descriptive value that distinguishes the column from the ID column -->
+<Annotations Target="MyService.BaseUnitType/UnitOfMeasure_Text">
+    <Annotation Term="Common.Label" String="Unit of Measure"/>
+</Annotations>
+```
+
+**Different `Common.Label` annotations on ID and text properties:**
+
+```xml
+<Annotations Target="MyService.MyEntity/Supplier">
+    <Annotation Term="Common.Text" Path="to_Supplier/CompanyName"/>
+    <Annotation Term="Common.Label" String="Supplier ID"/>
+</Annotations>
+
+<Annotations Target="MyService.SupplierType/CompanyName">
+    <Annotation Term="Common.Label" String="Company Name"/>
+</Annotations>
+```
+
+**OData V2 — distinct `sap:label` values on ID and text property:**
+
+```xml
+<Property Name="QuantityUnit" Type="Edm.String" sap:text="QuantityUnitT" sap:label="Quantity Unit" />
+<!-- Distinct sap:label — unambiguous column headers -->
+<Property Name="QuantityUnitT" Type="Edm.String" sap:label="Unit of Measure Text" />
+```
+
+## Bug Report
+
+If you encounter an issue with this rule, please open a [GitHub issue](https://github.com/SAP/open-ux-tools/issues).
+
+## When Not to Disable This Rule
+
+This rule should not be disabled unless you have a confirmed backend constraint that prevents renaming the label. In most cases the fix is straightforward: update the `Common.Label` annotation (or the `sap:label` attribute in OData V2 metadata) on the text property to something meaningful and distinct from the ID property label.
+
+## Further Reading
+
+- [UI5 Further Features of the Field - OData V4](https://ui5.sap.com/#/topic/f49a0f7eaafe444daf4cd62d48120ad0)
+- [UI5 Displaying Text and ID for Value Help Input Fields - OData V2](https://ui5.sap.com/#/topic/080886d8d4af4ac6a68a476beab17da3)
+- [OData Common Vocabulary - Text](https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/Common.md#Text)
+- [OData Common Vocabulary - Label](https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/Common.md#Label)

packages/eslint-plugin-fiori-tools/src/constants.ts

@@ -1,5 +1,6 @@
 export const UI_LINE_ITEM = 'com.sap.vocabularies.UI.v1.LineItem';
 export const COMMON_TEXT = 'com.sap.vocabularies.Common.v1.Text';
+export const COMMON_LABEL = 'com.sap.vocabularies.Common.v1.Label';
 export const UI_HIDDEN = 'com.sap.vocabularies.UI.v1.Hidden';
 export const UI_TEXT_ARRANGEMENT = 'com.sap.vocabularies.UI.v1.TextArrangement';
 export const UI_FIELD_GROUP = 'com.sap.vocabularies.UI.v1.FieldGroup';

packages/eslint-plugin-fiori-tools/src/index.ts

@@ -472,6 +472,7 @@ const fioriLanguageConfig: Linter.Config[] = [
             '@sap-ux/fiori-tools/sap-flex-enabled': 'warn',
             '@sap-ux/fiori-tools/sap-width-including-column-header': 'warn',
             '@sap-ux/fiori-tools/sap-copy-to-clipboard': 'warn',
+            '@sap-ux/fiori-tools/sap-description-column-label': 'warn',
             '@sap-ux/fiori-tools/sap-enable-export': 'warn',
             '@sap-ux/fiori-tools/sap-enable-paste': 'warn',
             '@sap-ux/fiori-tools/sap-creation-mode-for-table': 'warn',

packages/eslint-plugin-fiori-tools/src/language/diagnostics.ts

@@ -16,6 +16,7 @@ export const TEXT_ARRANGEMENT_HIDDEN = 'sap-text-arrangement-hidden';
 export const NO_DATA_FIELD_INTENT_BASED_NAVIGATION = 'sap-no-data-field-intent-based-navigation';
 export const CONDENSED_TABLE_LAYOUT = 'sap-condensed-table-layout';
 export const STRICT_UOM_FILTERING = 'sap-strict-uom-filtering';
+export const DESCRIPTION_COLUMN_LABEL = 'sap-description-column-label';
 
 export interface WidthIncludingColumnHeaderDiagnostic {
     type: typeof WIDTH_INCLUDING_COLUMN_HEADER_RULE_TYPE;
@@ -138,6 +139,23 @@ export interface StrictUomFiltering {
     manifest: ManifestPropertyDiagnosticData;
 }
 
+export type DescriptionColumnLabelMessageId =
+    | 'trivialLabel' // label is "Name" or "Description"
+    | 'duplicateLabel'; // label of text property matches label of ID property
+
+export interface DescriptionColumnLabel {
+    type: typeof DESCRIPTION_COLUMN_LABEL;
+    messageId: DescriptionColumnLabelMessageId;
+    pageNames: string[];
+    annotation: {
+        reference: AnnotationReference;
+        idPropertyTarget: string;
+        textPropertyTarget: string;
+        textPropertyLabel: string;
+        idPropertyLabel?: string;
+    };
+}
+
 export interface TextArrangementHidden {
     type: typeof TEXT_ARRANGEMENT_HIDDEN;
     pageNames: string[];
@@ -154,6 +172,7 @@ export type Diagnostic =
     | FlexEnabled
     | CopyToClipboard
     | CreationModeForTable
+    | DescriptionColumnLabel
     | EnableExport
     | EnablePaste
     | StatePreservationMode

packages/eslint-plugin-fiori-tools/src/project-context/parser/service.ts

@@ -1,16 +1,19 @@
-import type { Element, MetadataElement } from '@sap-ux/odata-annotation-core';
+import type { Element, MetadataElement, Range, Target } from '@sap-ux/odata-annotation-core';
 import {
     Edm,
     getAliasInformation,
     getAllNamespacesAndReferences,
     getElementAttribute,
     getElementAttributeValue,
     parseIdentifier,
-    toFullyQualifiedName
+    toFullyQualifiedName,
+    createAttributeNode,
+    createElementNode
 } from '@sap-ux/odata-annotation-core';
 import type { ServiceArtifacts } from '@sap-ux/fiori-annotation-api/src/types';
 
 import type { DocumentType } from '../types';
+import { COMMON_LABEL, COMMON_TEXT } from '../../constants';
 
 export interface ServiceIndex {
     entityContainer?: MetadataElement;
@@ -131,9 +134,105 @@ function processTargetAnnotations(
     }
 }
 
+/**
+ * Creates a minimal synthetic Element node carrying a single string attribute.
+ * Attaches an ESLint-compatible `loc` object when source range is available,
+ * enabling ESLint to report at the correct line/column in the metadata file.
+ *
+ * @param attrName - Attribute name on the Annotation element (e.g. "Path" or "String")
+ * @param attrValue - Attribute value
+ * @param sourceRange - Optional source range (0-indexed) used for ESLint reporting
+ * @returns A synthetic Element, optionally with position range
+ */
+function createSyntheticElement(attrName: string, attrValue: string, sourceRange?: Range): Element {
+    const element = createElementNode({
+        name: Edm.Annotation,
+        attributes: {
+            [attrName]: createAttributeNode(attrName, attrValue)
+        },
+        content: []
+    });
+    if (sourceRange) {
+        element.range = sourceRange;
+    }
+    return element;
+}
+
+/**
+ * Injects synthetic Common.Text and Common.Label annotation entries derived from OData V2
+ * inline `sap:text` and `sap:label` attributes on Property elements.
+ *
+ * For Common.Text: injects into both the annotation index AND the annotation file AST so
+ * that ESLint's `createAnnotations()` traversal can fire and report diagnostics.
+ * For Common.Label: injects into the annotation index only (read by getLabelForProperty).
+ *
+ * Only adds entries when no explicit vocabulary annotation already exists for that key.
+ *
+ * @param artifacts - Service artifacts whose metadata properties are to be inspected
+ * @param metadataUri - URI of the metadata file (used as the annotation source)
+ * @param index - The annotation index to inject into
+ */
+function injectV2InlineAnnotations(artifacts: ServiceArtifacts, metadataUri: string, index: AnnotationIndex): void {
+    if (artifacts.metadataService.ODataVersion !== '2.0') {
+        return;
+    }
+    const annotationFile = artifacts.annotationFiles[metadataUri];
+    if (!annotationFile) {
+        return;
+    }
+
+    artifacts.metadataService.visitMetadataElements((element) => {
+        if (element.kind !== Edm.Property) {
+            return;
+        }
+        const propertyTarget = element.path; // e.g. "Namespace.EntityType/PropertyName"
+
+        if (element.sapText) {
+            const textKey = buildAnnotationIndexKey(propertyTarget, COMMON_TEXT);
+            if (!index[textKey]) {
+                const syntheticElement = createSyntheticElement(Edm.Path, element.sapText, element.sapTextRange);
+                index[textKey] = {
+                    undefined: {
+                        source: metadataUri,
+                        target: propertyTarget,
+                        term: COMMON_TEXT,
+                        top: { uri: metadataUri, value: syntheticElement },
+                        layers: [{ uri: metadataUri, value: syntheticElement }]
+                    }
+                };
+                // Also inject into the annotation file AST so the traversal selector fires
+                const syntheticTarget: Target = {
+                    type: 'target',
+                    name: propertyTarget,
+                    terms: [syntheticElement]
+                };
+                annotationFile.targets.push(syntheticTarget);
+            }
+        }
+
+        if (element.sapLabel) {
+            const labelKey = buildAnnotationIndexKey(propertyTarget, COMMON_LABEL);
+            if (!index[labelKey]) {
+                const syntheticElement = createSyntheticElement(Edm.String, element.sapLabel, element.sapLabelRange);
+                index[labelKey] = {
+                    undefined: {
+                        source: metadataUri,
+                        target: propertyTarget,
+                        term: COMMON_LABEL,
+                        top: { uri: metadataUri, value: syntheticElement },
+                        layers: [{ uri: metadataUri, value: syntheticElement }]
+                    }
+                };
+            }
+        }
+    });
+}
+
 /**
  * Builds a service index from service artifacts.
  * Creates indexes for entity sets, entity containers, and annotations.
+ * For OData V2 services, also injects synthetic index entries and AST targets from
+ * inline sap:text/sap:label attributes so that annotation rules can report on metadata.xml.
  *
  * @param artifacts - Service artifacts to index
  * @param documents - Document map to populate with annotation files
@@ -150,14 +249,21 @@ export function buildServiceIndex(
 
     const annotationIndex = indexAnnotationsByAnnotationPath(artifacts);
     let entityContainer: MetadataElement | undefined;
+    let metadataUri = '';
     artifacts.metadataService.visitMetadataElements((element) => {
         // NOSONAR - TODO: check if we can handle CDS differences better
         if (element.kind === 'EntityContainer' || element.kind === 'service') {
             entityContainer = element;
         } else if (element.kind === 'EntitySet' || element.kind === 'entitySet') {
             entitySets[element.name] = element;
         }
+        if (!metadataUri && element.location?.uri) {
+            metadataUri = element.location.uri;
+        }
     });
+
+    injectV2InlineAnnotations(artifacts, metadataUri, annotationIndex);
+
     return {
         entitySets: entitySets,
         entityContainer,

packages/eslint-plugin-fiori-tools/src/rules/index.ts

@@ -6,6 +6,7 @@ import {
     WIDTH_INCLUDING_COLUMN_HEADER_RULE_TYPE,
     COPY_TO_CLIPBOARD,
     CREATION_MODE_FOR_TABLE,
+    DESCRIPTION_COLUMN_LABEL,
     ENABLE_EXPORT,
     ENABLE_PASTE,
     STATE_PRESERVATION_MODE,
@@ -74,6 +75,7 @@ import creationModeForTable from './sap-creation-mode-for-table';
 import statePreservationMode from './sap-state-preservation-mode';
 import strictUomFilteringRule from './sap-strict-uom-filtering';
 import copyToClipboard from './sap-copy-to-clipboard';
+import descriptionColumnLabel from './sap-description-column-label';
 import enableExport from './sap-enable-export';
 import enablePaste from './sap-enable-paste';
 import tablePersonalization from './sap-table-personalization';
@@ -137,6 +139,7 @@ export const rules: Record<string, Rule.RuleModule | FioriRuleDefinition | Fiori
     [FLEX_ENABLED]: flexEnabledRule,
     [WIDTH_INCLUDING_COLUMN_HEADER_RULE_TYPE]: requireWidthIncludingColumnHeader,
     [COPY_TO_CLIPBOARD]: copyToClipboard,
+    [DESCRIPTION_COLUMN_LABEL]: descriptionColumnLabel,
     [ENABLE_EXPORT]: enableExport,
     [ENABLE_PASTE]: enablePaste,
     [CREATION_MODE_FOR_TABLE]: creationModeForTable,