feat(QTDI-2979): Add labelDisplayMode attribute to @suggestable (#1238)

thboileau · GitHub Copilot · web-flow · commit e1cc0de08817 · 2026-06-15T09:08:38.000+02:00
* feat(QTDI-2979): Add labelDisplayMode attribute to @suggestable Add a LabelDisplayMode enum (LABEL, LABEL_ID) and a labelDisplayMode() annotation attribute to @suggestable. The attribute defaults to LABEL, preserving full backward compatibility. When two or more suggestions share the same label, setting labelDisplayMode = LABEL_ID allows the front-end to show both the label and the opaque identifier so the user can make an unambiguous choice (e.g. 'Paris (fr-paris-01)'). The value is serialised as tcomp::action::suggestions::labelDisplayMode in the component metadata map by the existing ActionParameterEnricher, with no changes to component-server-model required. Also includes Spotless reformatting of several pre-existing violations caught during mvn spotless:apply, and a .gitignore update for ai-commons tooling files. Co-Authored-By: GitHub Copilot <ai@noreply> * fix(QTDI-2979): apply spotless * fix(QTDI-1979): take into account PR review comment --------- Co-authored-by: GitHub Copilot <ai@noreply>
diff --git a/.gitignore b/.gitignore
@@ -66,3 +66,10 @@ documentation/rebuildpdf.bat
 .envrc
 .env
 *.versionsBackup
+
+# ai-commons knowledge base (managed by ai-commons/setup.sh)
+.ai-commons/
+.ai-commons/sessions/
+.ai-commons/skills/manage-zephyr-test-cases/references/.env
+.claude/CLAUDE.md
+.github/copilot-instructions.md
diff --git a/component-api/src/main/java/org/talend/sdk/component/api/configuration/action/Suggestable.java b/component-api/src/main/java/org/talend/sdk/component/api/configuration/action/Suggestable.java
@@ -74,4 +74,32 @@
      * @return parameters for the validation.
      */
     String[] parameters() default { "." };
+
+    /**
+     * Controls how each suggestion option is rendered in the UI.
+     * Use {@link LabelDisplayMode#LABEL_ID} when option labels may not be unique,
+     * so that the identifier is shown alongside the label to allow unambiguous selection.
+     * Defaults to {@link LabelDisplayMode#LABEL} — preserves full backward compatibility.
+     *
+     * @return the display mode for suggestion options.
+     */
+    LabelDisplayMode labelDisplayMode() default LabelDisplayMode.LABEL;
+
+    /**
+     * Defines how suggestion options are displayed in the UI.
+     */
+    enum LabelDisplayMode {
+
+        /**
+         * Display the option label only.
+         * Default behaviour — use this when labels are unique.
+         */
+        LABEL,
+
+        /**
+         * Display both the label and the identifier, e.g. {@code Paris (fr-paris-01)}.
+         * Use this when labels may not be unique so that the user can make an unambiguous choice.
+         */
+        LABEL_ID
+    }
 }
diff --git a/component-runtime-impl/src/main/java/org/talend/sdk/component/runtime/reflect/Defaults.java b/component-runtime-impl/src/main/java/org/talend/sdk/component/runtime/reflect/Defaults.java
@@ -63,10 +63,11 @@ public class Defaults {
                     .invokeWithArguments(args);
         } else { // j > 8 - can need some --add-opens, we will add a module-info later to be clean when dropping j8
             final Method privateLookup = findPrivateLookup();
-            HANDLER = (clazz, method, proxy, args) -> ((MethodHandles.Lookup) privateLookup.invoke(null, clazz, constructor.newInstance(clazz)))
-                    .unreflectSpecial(method, clazz)
-                    .bindTo(proxy)
-                    .invokeWithArguments(args);
+            HANDLER = (clazz, method, proxy,
+                    args) -> ((MethodHandles.Lookup) privateLookup.invoke(null, clazz, constructor.newInstance(clazz)))
+                            .unreflectSpecial(method, clazz)
+                            .bindTo(proxy)
+                            .invokeWithArguments(args);
         }
     }
 
diff --git a/component-runtime-impl/src/test/java/org/talend/sdk/component/runtime/record/PluralRecordExtension.java b/component-runtime-impl/src/test/java/org/talend/sdk/component/runtime/record/PluralRecordExtension.java
@@ -58,7 +58,7 @@ private Jsonb getJsonb(Jsonb jsonb) {
         // create a Jsonb instance which is PojoJsonbProvider as in component-runtime-manager
         return (Jsonb) Proxy
                 .newProxyInstance(Thread.currentThread().getContextClassLoader(),
-                        new Class<?>[]{Jsonb.class, PojoJsonbProvider.class}, (proxy, method, args) -> {
+                        new Class<?>[] { Jsonb.class, PojoJsonbProvider.class }, (proxy, method, args) -> {
                             if (method.getDeclaringClass() == Supplier.class) {
                                 return jsonb;
                             }
diff --git a/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/ComponentManager.java b/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/ComponentManager.java
@@ -1924,7 +1924,8 @@ public void onPartitionMapper(final Class<?> type, final PartitionMapper partiti
                     () -> {
                         final List<ParameterMeta> params = parameterModelService
                                 .buildParameterMetas(constructor, getPackage(type),
-                                        new BaseParameterEnricher.Context((LocalConfiguration) services.getServices().get(LocalConfiguration.class)));
+                                        new BaseParameterEnricher.Context((LocalConfiguration) services.getServices()
+                                                .get(LocalConfiguration.class)));
                         if (infinite) {
                             if (partitionMapper.stoppable()) {
                                 addInfiniteMapperBuiltInParameters(type, params);
@@ -1977,7 +1978,8 @@ public void onEmitter(final Class<?> type, final Emitter emitter) {
             final Supplier<List<ParameterMeta>> parameterMetas = lazy(() -> executeInContainer(plugin,
                     () -> parameterModelService
                             .buildParameterMetas(constructor, getPackage(type),
-                                    new BaseParameterEnricher.Context((LocalConfiguration) services.getServices().get(LocalConfiguration.class)))));
+                                    new BaseParameterEnricher.Context((LocalConfiguration) services.getServices()
+                                            .get(LocalConfiguration.class)))));
             final Function<Map<String, String>, Object[]> parameterFactory =
                     createParametersFactory(plugin, constructor, services.getServices(), parameterMetas);
             final String name = of(emitter.name()).filter(n -> !n.isEmpty()).orElseGet(type::getName);
@@ -2161,7 +2163,8 @@ public void onDriverRunner(final Class<?> type, final DriverRunner processor) {
             final Supplier<List<ParameterMeta>> parameterMetas = lazy(() -> executeInContainer(plugin,
                     () -> parameterModelService
                             .buildParameterMetas(constructor, getPackage(type),
-                                    new BaseParameterEnricher.Context((LocalConfiguration) services.getServices().get(LocalConfiguration.class)))));
+                                    new BaseParameterEnricher.Context((LocalConfiguration) services.getServices()
+                                            .get(LocalConfiguration.class)))));
             final Function<Map<String, String>, Object[]> parameterFactory =
                     createParametersFactory(plugin, constructor, services.getServices(), parameterMetas);
             final String name = of(processor.name()).filter(n -> !n.isEmpty()).orElseGet(type::getName);
diff --git a/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/reflect/ParameterModelService.java b/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/reflect/ParameterModelService.java
@@ -254,10 +254,10 @@ private Stream<Annotation> getReflectionAnnotations(final Type genericType, fina
                 .concat(Stream.of(annotations),
                         // if a class concat its annotations
                         genericType instanceof Class
-                                        ? getClassAnnotations(genericType, annotations)
-                                        : (hasAClassFirstParameter(genericType) ? getClassAnnotations(
-                                                ((ParameterizedType) genericType).getActualTypeArguments()[0],
-                                                annotations) : Stream.empty()));
+                                ? getClassAnnotations(genericType, annotations)
+                                : (hasAClassFirstParameter(genericType) ? getClassAnnotations(
+                                        ((ParameterizedType) genericType).getActualTypeArguments()[0],
+                                        annotations) : Stream.empty()));
     }
 
     private boolean hasAClassFirstParameter(final Type genericType) {
@@ -297,7 +297,7 @@ private List<ParameterMeta> buildParametersMetas(final String name, final String
                 }
                 return Stream
                         .concat(buildParametersMetas(name + ".key[${index}]", prefix + "key[${index}].",
-                                        (Class) pt.getActualTypeArguments()[0], annotations, i18nPackages, ignoreI18n,
+                                (Class) pt.getActualTypeArguments()[0], annotations, i18nPackages, ignoreI18n,
                                 context).stream(),
                                 buildParametersMetas(name + ".value[${index}]", prefix + "value[${index}].",
                                         (Class) pt.getActualTypeArguments()[1], annotations, i18nPackages,
diff --git a/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/reflect/ReflectionService.java b/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/reflect/ReflectionService.java
@@ -524,10 +524,11 @@ private Object createObject(final ClassLoader loader, final Function<Supplier<Ob
                 if (arrayClass.isArray()) {
                     // we could use Array.newInstance but for now use the list, shouldn't impact
                     // much the perf
-                    final Collection<?> list = (Collection) createList(loader, contextualSupplier, prefix + enclosingName, List.class,
-                            arrayClass.getComponentType(), toList(), createObjectFactory(loader,
-                                    contextualSupplier, arrayClass.getComponentType(), metas, precomputed),
-                            new HashMap<>(listEntries), metas, precomputed);
+                    final Collection<?> list =
+                            (Collection) createList(loader, contextualSupplier, prefix + enclosingName, List.class,
+                                    arrayClass.getComponentType(), toList(), createObjectFactory(loader,
+                                            contextualSupplier, arrayClass.getComponentType(), metas, precomputed),
+                                    new HashMap<>(listEntries), metas, precomputed);
 
                     // we need that conversion to ensure the type matches
                     final Object array = Array.newInstance(arrayClass.getComponentType(), list.size());
diff --git a/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/service/InjectorImpl.java b/component-runtime-manager/src/main/java/org/talend/sdk/component/runtime/manager/service/InjectorImpl.java
@@ -128,7 +128,8 @@ private <T> void doInject(final Class<?> type, final T instance) {
                 })
                 .forEach(field -> {
                     try {
-                        final Class<?> configClass = (Class) ((ParameterizedType) field.getGenericType()).getActualTypeArguments()[0];
+                        final Class<?> configClass =
+                                (Class) ((ParameterizedType) field.getGenericType()).getActualTypeArguments()[0];
                         final ClassLoader loader = Thread.currentThread().getContextClassLoader();
                         final Supplier<?> supplier = () -> {
                             try {
diff --git a/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/ComponentManagerTest.java b/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/ComponentManagerTest.java
@@ -611,7 +611,8 @@ void testLocalConfigurationFromEnvironment(@TempDir final File temporaryFolder)
             manager.addPlugin(plugin.getAbsolutePath());
             final Container container = manager.getContainer().findAll().stream().findFirst().orElse(null);
             assertNotNull(container);
-            final LocalConfiguration envConf = (LocalConfiguration) container.get(AllServices.class).getServices().get(LocalConfiguration.class);
+            final LocalConfiguration envConf =
+                    (LocalConfiguration) container.get(AllServices.class).getServices().get(LocalConfiguration.class);
             // check translated env vars
             assertEquals("/home/user", envConf.get("USER_PATH"));
             assertEquals("/home/user", envConf.get("USER.PATH"));
diff --git a/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/ConfigurationMigrationTest.java b/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/ConfigurationMigrationTest.java
@@ -42,26 +42,30 @@ void run(@TempDir final Path temporaryFolder) throws Exception {
                 "META-INF/test/dependencies", "org.talend.test:type=plugin,value=%s")) {
             manager.addPlugin(jar.getAbsolutePath());
             {
-                final Object nested = ((ProcessorImpl) manager.findProcessor("chain", "configured1", 0, new HashMap<String, String>() {
+                final Object nested = ((ProcessorImpl) manager
+                        .findProcessor("chain", "configured1", 0, new HashMap<String, String>() {
 
-                    {
-                        put("config.__version", "-1");
-                    }
-                }).orElseThrow(IllegalStateException::new))
+                            {
+                                put("config.__version", "-1");
+                            }
+                        })
+                        .orElseThrow(IllegalStateException::new))
                         .getDelegate();
 
                 final Object config = get(nested, "getConfig");
                 assertNotNull(config);
                 assertEquals("ok", get(config, "getName"));
             }
             {
-                final Object nested = ((ProcessorImpl) manager.findProcessor("chain", "configured2", 0, new HashMap<String, String>() {
+                final Object nested = ((ProcessorImpl) manager
+                        .findProcessor("chain", "configured2", 0, new HashMap<String, String>() {
 
-                    {
-                        put("config.__version", "0");
-                        put("value.__version", "-1");
-                    }
-                }).orElseThrow(IllegalStateException::new))
+                            {
+                                put("config.__version", "0");
+                                put("value.__version", "-1");
+                            }
+                        })
+                        .orElseThrow(IllegalStateException::new))
                         .getDelegate();
                 assertEquals("set", get(nested, "getValue"));
 
@@ -70,13 +74,15 @@ void run(@TempDir final Path temporaryFolder) throws Exception {
                 assertEquals("ok", get(config, "getName"));
             }
             {
-                final Object nested = ((ProcessorImpl) manager.findProcessor("chain", "migrationtest", -1, new HashMap<String, String>() {
+                final Object nested = ((ProcessorImpl) manager
+                        .findProcessor("chain", "migrationtest", -1, new HashMap<String, String>() {
 
-                    {
-                        put("config.__version", "1");
-                        put("config.datastore.__version", "1");
-                    }
-                }).orElseThrow(IllegalStateException::new))
+                            {
+                                put("config.__version", "1");
+                                put("config.datastore.__version", "1");
+                            }
+                        })
+                        .orElseThrow(IllegalStateException::new))
                         .getDelegate();
 
                 final Object config = get(nested, "getConfig");
diff --git a/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/ReflectionServiceTest.java b/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/ReflectionServiceTest.java
@@ -450,8 +450,10 @@ void copiable() throws NoSuchMethodException {
                         new HttpClientFactoryImpl("test", reflectionService, JsonbBuilder.create(), emptyMap())
                                 .create(UserHttpClient.class, "http://foo"));
         final Method httpMtd = TableOwner.class.getMethod("http", UserHttpClient.class);
-        final HttpClient client1 = (HttpClient) reflectionService.parameterFactory(httpMtd, precomputed, null).apply(emptyMap())[0];
-        final HttpClient client2 = (HttpClient) reflectionService.parameterFactory(httpMtd, precomputed, null).apply(emptyMap())[0];
+        final HttpClient client1 =
+                (HttpClient) reflectionService.parameterFactory(httpMtd, precomputed, null).apply(emptyMap())[0];
+        final HttpClient client2 =
+                (HttpClient) reflectionService.parameterFactory(httpMtd, precomputed, null).apply(emptyMap())[0];
         assertNotSame(client1, client2);
         final InvocationHandler handler1 = Proxy.getInvocationHandler(client1);
         final InvocationHandler handler2 = Proxy.getInvocationHandler(client2);
diff --git a/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/reflect/parameterenricher/ActionParameterEnricherTest.java b/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/reflect/parameterenricher/ActionParameterEnricherTest.java
@@ -159,6 +159,7 @@ void suggestion() {
             {
                 put("tcomp::action::suggestions", "test");
                 put("tcomp::action::suggestions::parameters", ".,foo,/bar/dummy");
+                put("tcomp::action::suggestions::labelDisplayMode", "LABEL");
             }
         }, new ActionParameterEnricher().onParameterAnnotation("testParam", String.class, new Suggestable() {
 
@@ -172,13 +173,59 @@ public String[] parameters() {
                 return new String[] { ".", "foo", "/bar/dummy" };
             }
 
+            @Override
+            public LabelDisplayMode labelDisplayMode() {
+                return LabelDisplayMode.LABEL;
+            }
+
             @Override
             public Class<? extends Annotation> annotationType() {
                 return Suggestable.class;
             }
         }));
     }
 
+    @Test
+    void suggestionWithLabelId() {
+        assertEquals(new HashMap<String, String>() {
+
+            {
+                put("tcomp::action::suggestions", "test");
+                put("tcomp::action::suggestions::parameters", ".");
+                put("tcomp::action::suggestions::labelDisplayMode", "LABEL_ID");
+            }
+        }, new ActionParameterEnricher().onParameterAnnotation("testParam", String.class, new Suggestable() {
+
+            @Override
+            public String value() {
+                return "test";
+            }
+
+            @Override
+            public String[] parameters() {
+                return new String[] { "." };
+            }
+
+            @Override
+            public LabelDisplayMode labelDisplayMode() {
+                return LabelDisplayMode.LABEL_ID;
+            }
+
+            @Override
+            public Class<? extends Annotation> annotationType() {
+                return Suggestable.class;
+            }
+        }));
+    }
+
+    @Test
+    void suggestable_labelDisplayMode_defaultsToLabel() throws Exception {
+        Suggestable.LabelDisplayMode defaultMode = (Suggestable.LabelDisplayMode) Suggestable.class
+                .getDeclaredMethod("labelDisplayMode")
+                .getDefaultValue();
+        assertEquals(Suggestable.LabelDisplayMode.LABEL, defaultMode);
+    }
+
     @Test
     void condition() {
         assertEquals(new HashMap<String, String>() {
diff --git a/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/service/RecordServiceImplTest.java b/component-runtime-manager/src/test/java/org/talend/sdk/component/runtime/manager/service/RecordServiceImplTest.java
diff --git a/component-runtime-testing/component-runtime-junit/src/main/java/org/talend/sdk/component/junit5/ComponentExtension.java b/component-runtime-testing/component-runtime-junit/src/main/java/org/talend/sdk/component/junit5/ComponentExtension.java
diff --git a/component-tools/src/test/java/org/talend/sdk/component/tools/ComponentValidatorTest.java b/component-tools/src/test/java/org/talend/sdk/component/tools/ComponentValidatorTest.java
diff --git a/documentation/src/main/java/org/talend/runtime/documentation/Generator.java b/documentation/src/main/java/org/talend/runtime/documentation/Generator.java
diff --git a/singer-parent/component-kitap/src/main/java/org/talend/sdk/component/singer/kitap/RecordJsonMapper.java b/singer-parent/component-kitap/src/main/java/org/talend/sdk/component/singer/kitap/RecordJsonMapper.java

Original file line number	Diff line number	Diff line change
`@@ -58,7 +58,7 @@ private Jsonb getJsonb(Jsonb jsonb) {`
`58`	`58`	`// create a Jsonb instance which is PojoJsonbProvider as in component-runtime-manager`
`59`	`59`	`return (Jsonb) Proxy`
`60`	`60`	`.newProxyInstance(Thread.currentThread().getContextClassLoader(),`
`61`		`- new Class<?>[]{Jsonb.class, PojoJsonbProvider.class}, (proxy, method, args) -> {`
	`61`	`+ new Class<?>[] { Jsonb.class, PojoJsonbProvider.class }, (proxy, method, args) -> {`
`62`	`62`	`if (method.getDeclaringClass() == Supplier.class) {`
`63`	`63`	`return jsonb;`
`64`	`64`	`}`