Sync documentation of main branch

Author: actions-user

_data/versioned/main/index/quarkus.yaml

@@ -417,7 +417,7 @@ types:
     url: /guides/opentelemetry
   - title: Using transactions in Quarkus
     filename: transaction.adoc
-    summary: "The quarkus-narayana-jta extension provides a Transaction Manager that coordinates and expose transactions to your applications as described in the link: Jakarta Transactions specification, formerly known as Java Transaction API (JTA)."
+    summary: "The quarkus-narayana-jta extension provides a Transaction Manager that coordinates and expose transactions to your applications as described in the Jakarta Transactions specification, formerly known as Java Transaction API (JTA)."
     categories: "data, getting-started"
     topics:
     - data
@@ -2343,6 +2343,19 @@ types:
     - reactive
     type: guide
     url: /guides/quarkus-reactive-architecture
+  - title: Quarkus Signals
+    filename: signals.adoc
+    summary: Learn more about how application components can interact in a loosely coupled fashion
+    categories: miscellaneous
+    topics:
+    - events
+    - signals
+    - messages
+    extensions:
+    - io.quarkus:quarkus-signals
+    type: guide
+    status: experimental
+    url: /guides/signals
   - title: Quarkus Virtual Thread support for gRPC services
     filename: grpc-virtual-threads.adoc
     summary: This guide explains how to benefit from Java virtual threads when implementing a gRPC service.

_generated-doc/main/infra/quarkus-all-build-items.adoc

@@ -178,17 +178,6 @@ _No Javadoc found_
 
 
 
-a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/sbom/ApplicationManifestsBuildItem.java[`io.quarkus.deployment.sbom.ApplicationManifestsBuildItem`, window="_blank"]
-[.description]
---
-Application manifests collected in a build
--- a|`java.util.Collection<ApplicationManifest> manifests` 
-
-_No Javadoc found_
-
-
-
-
 a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/builditem/ApplicationStartBuildItem.java[`io.quarkus.deployment.builditem.ApplicationStartBuildItem`, window="_blank"]
 [.description]
 --
@@ -237,7 +226,7 @@ _No Javadoc found_
 
 _No Javadoc found_
 
-`io.quarkus.sbom.ApplicationManifestConfig manifestConfig` 
+`io.quarkus.sbom.CoreSbomContributionConfig coreSbomConfig` 
 
 _No Javadoc found_
 
@@ -1426,7 +1415,7 @@ _No Javadoc found_
 
 _No Javadoc found_
 
-`io.quarkus.sbom.ApplicationManifestConfig manifestConfig` 
+`io.quarkus.sbom.CoreSbomContributionConfig coreSbomConfig` 
 
 _No Javadoc found_
 
@@ -2668,6 +2657,20 @@ _No Javadoc found_
 
 
 
+a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/sbom/SbomContributionBuildItem.java[`io.quarkus.deployment.sbom.SbomContributionBuildItem`, window="_blank"]
+[.description]
+--
+A build item that allows Quarkus extensions to contribute additional components to the application SBOM. 
+This build item carries an `SbomContribution` containing component descriptors and their dependency relationships from any package ecosystem (npm, Maven, etc.). 
+Extension contributions are merged with the core application contribution (assembled from the application's Maven dependency model and packaging output) by an SBOM generator. Extensions should not designate a main component — only the core contribution does that. 
+The API around this is still in development and will likely change in the near future.
+-- a|`io.quarkus.sbom.SbomContribution contribution` 
+
+_No Javadoc found_
+
+
+
+
 a| https://github.com/quarkusio/quarkus/blob/main/core/deployment/src/main/java/io/quarkus/deployment/builditem/nativeimage/ServiceProviderBuildItem.java[`io.quarkus.deployment.builditem.nativeimage.ServiceProviderBuildItem`, window="_blank"]
 [.description]
 --
@@ -9454,6 +9457,21 @@ Used to create the publisher for the graphql trafic log in dev ui
 _No Javadoc found_
 
 
+
+
+a| https://github.com/quarkusio/quarkus/blob/main/extensions/smallrye-graphql/deployment/src/main/java/io/quarkus/smallrye/graphql/deployment/SmallRyeGraphQLFinalIndexModifierBuildItem.java[`io.quarkus.smallrye.graphql.deployment.SmallRyeGraphQLFinalIndexModifierBuildItem`, window="_blank"]
+[.description]
+--
+Build item for modifying the final index used by SmallRye GraphQL. Extensions can produce this build item to apply custom modifications to the index before the GraphQL schema is built. Modifiers are applied in priority order (lower priority values are applied first). If multiple modifiers have the same priority, they are applied in the order they were produced (stable sort).
+-- a|`int priority` 
+
+_No Javadoc found_
+
+`io.quarkus.smallrye.graphql.deployment.SmallRyeGraphQLFinalIndexModifier modifier` 
+
+_No Javadoc found_
+
+
 |===
 == SmallRye GraphQL Client
 [.configuration-reference,cols=2*]

_versions/main/guides/cyclonedx.adoc

@@ -21,6 +21,7 @@ This guide covers:
 * <<sbom-endpoint,SBOM REST Endpoint>> — exposing embedded dependency SBOMs via a REST endpoint
 * <<distribution-sboms,Distribution SBOMs>> — generating SBOMs that manifest the final application distribution after a build
 * <<vulnerability-scanning,Vulnerability scanning>> — using generated SBOMs with tools such as Grype to identify known vulnerabilities
+* <<extension-sbom-contributions,Extension SBOM contributions>> — contributing additional components to the application SBOM from Quarkus extensions
 
 All SBOM generation in this guide follows the https://cyclonedx.org/[CycloneDX] specification.
 
@@ -474,3 +475,78 @@ This approach is useful for scanning applications that are already deployed, for
 |`quarkus:component:scope` |`runtime` or `development` |Indicates whether a component is a runtime or a build/development time dependency of an application.
 |`quarkus:component:location` |String representing a file system path using `/` as a path element |Used in SBOMs with schema versions 1.4 or older. Starting from schema 1.5, `evidence.occurrences.location` is used instead. This property is used only if a component is found in the distribution. The value is a relative path to a file pointing to the location of a component in a distribution using `/` as a path element separator.
 |===
+
+[[extension-sbom-contributions]]
+== Extension SBOM Contributions
+
+By default, Quarkus generates SBOMs from the application's Maven dependency model and the packaging output.
+Extensions that manage additional software components — for example, npm packages or other non-Maven artifacts — can contribute those components to the application SBOM by producing `SbomContributionBuildItem` instances from their `@BuildStep` methods.
+
+Extension contributions are merged with the core application contribution by the SBOM generator.
+Components marked as top-level will appear as direct dependencies of the main application component in the generated SBOM.
+
+=== API Overview
+
+Extension SBOM contributions are built from the following classes:
+
+* `io.quarkus.sbom.Purl` — identifies a software component using the https://github.com/package-url/purl-spec[Package URL] specification. Factory methods are provided for Maven, npm, and generic component types.
+* `io.quarkus.sbom.ComponentDescriptor` — describes a software component with its PURL, scope, integrity hash, and other metadata.
+* `io.quarkus.sbom.ComponentDependencies` — describes the dependency relationships of a component, referencing other components by their bom-ref.
+* `io.quarkus.sbom.SbomContribution` — groups component descriptors and their dependency relationships into a single contribution.
+* `io.quarkus.deployment.sbom.SbomContributionBuildItem` — a `MultiBuildItem` that carries an `SbomContribution` to the SBOM generator.
+
+=== Example
+
+The following example shows a `@BuildStep` method that contributes npm packages to the application SBOM:
+
+[source,java]
+----
+import io.quarkus.deployment.annotations.BuildStep;
+import io.quarkus.deployment.sbom.SbomContributionBuildItem;
+import io.quarkus.sbom.ComponentDependencies;
+import io.quarkus.sbom.ComponentDescriptor;
+import io.quarkus.sbom.Purl;
+import io.quarkus.sbom.SbomContribution;
+
+@BuildStep
+SbomContributionBuildItem contributeNpmComponents() {
+
+    // Describe an npm package
+    ComponentDescriptor react = ComponentDescriptor.builder()
+            .setPurl(Purl.npm(null, "react", "18.2.0"))
+            .setScope(ComponentDescriptor.SCOPE_RUNTIME)
+            .setIntegrity("sha512-...")  // SRI hash from package-lock.json
+            .setTopLevel(true)           // direct dependency of the application
+            .build();
+
+    // Describe a transitive npm dependency
+    ComponentDescriptor loosEnvify = ComponentDescriptor.builder()
+            .setPurl(Purl.npm(null, "loose-envify", "1.4.0"))
+            .setScope(ComponentDescriptor.SCOPE_RUNTIME)
+            .build();
+
+    // Describe the dependency relationship: react depends on loose-envify
+    ComponentDependencies reactDeps = ComponentDependencies.builder()
+            .setBomRef(react.getBomRef())
+            .addDependsOn(loosEnvify.getBomRef())
+            .build();
+
+    // Build the contribution
+    SbomContribution contribution = SbomContribution.builder()
+            .addComponent(react)
+            .addComponent(loosEnvify)
+            .addDependency(reactDeps)
+            .build();
+
+    return new SbomContributionBuildItem(contribution);
+}
+----
+
+=== Key Points
+
+* Extensions must not designate a main component — only the core application contribution does that.
+* Components from any package ecosystem can be contributed using the appropriate `Purl` type (e.g., `Purl.npm(...)`, `Purl.maven(...)`, `Purl.generic(...)`, or `Purl.of(type, ...)` for other ecosystems).
+* Set `topLevel(true)` on components that are direct dependencies of the application (e.g., packages declared in `package.json`). Transitive dependencies should not be marked as top-level.
+* The `scope` field classifies components as `runtime` or `development` dependencies, which is recorded in the SBOM as the `quarkus:component:scope` property.
+* The `integrity` field can carry an SRI-format hash (e.g., from lock files) for component verification.
+* Dependency relationships are optional. If you only need to list components without expressing their dependency graph, use `SbomContribution.ofComponents(...)`.

_versions/main/guides/jar-tree-shaking.adoc

@@ -184,9 +184,12 @@ When tree-shaking is enabled, the build log includes a one-line summary at info
 
 [source]
 ----
-Tree-shaking removed 2469 unreachable classes from 15 dependencies, saving 1.5 MB (20.0%)
+Tree-shaking removed 2469 unreachable classes from 15 dependencies, saving 1.5 MB (20.0%) of bytecode
 ----
 
+The reported savings represent raw (uncompressed) bytecode removed from dependency classes.
+The actual reduction in packaged application size will be smaller because JARs are ZIP-compressed and also contain non-class resources (such as `META-INF` entries) that tree-shaking does not affect.
+
 For a detailed per-dependency breakdown, enable debug logging for the tree shaker. The debug output includes total/reachable/removed class counts and a list of affected dependencies.
 
 If your application throws a `ClassNotFoundException` or `NoClassDefFoundError` at runtime after enabling tree-shaking, a needed class may have been incorrectly identified as unreachable.

_versions/main/guides/qute-reference.adoc

@@ -304,6 +304,23 @@ You can learn more about virtual methods in the <<virtual_methods,following sect
 <1> no namespace, two parts - `item`, `getLabels(1)`, the second part is a virtual method with name `getLabels` and params `1`
 <2> infix notation that can be used for virtual methods with single parameter, translated to `name.or('John')`; no namespace, two parts - `name`, `or('John')`
 
+An expression can also use a <<literals,literal>> value as the base, followed by property accessors or virtual method invocations.
+
+.Literal Base Expression Examples
+[source]
+----
+{='foo'.toUpperCase} <1>
+{=1.intValue} <2>
+{#let name=('foo'.toUpperCase)}{name}{/let} <3>
+{name.replace('foo'.toUpperCase)} <4>
+----
+<1> string literal as the base followed by a property accessor; outputs `FOO`
+<2> integer literal as the base followed by a property accessor; outputs `1`
+<3> in a <<let_section,let>> section parameter, a literal base can be used directly inside parentheses
+<4> a literal base can also be used in nested expressions passed as parameters of virtual methods
+
+NOTE: In a top-level output expression, a literal base requires a special syntax prefix (such as `=`) configured via `ParserConfig`.
+
 [[literals]]
 ==== Supported Literals
 
@@ -1019,7 +1036,7 @@ This section allows you to define named local variables.
 {/let} <3>
 ----
 <1> The local variable is initialized with an expression that can also represent a <<literals,literal>>, i.e. `isActive=false` and `age=10`.
-<2> The infix notation is only supported if parentheses are used for grouping, e.g. `price=(order.price + 10)` is equivalent to `price=order.price.plus(10)`.
+<2> The infix notation is only supported if parentheses are used for grouping, e.g. `price=(order.price + 10)` is equivalent to `price=order.price.plus(10)`. A literal value can also be used as the first operand, e.g. `price=('$' + item.price)`.
 <3> Variables are not available outside the `let` section.
 
 The variables are not available outside the defining `let` section.