feat(RepositoryConfiguration): Add a model for path includes

Add model classes for path includes. Path includes can be used to mark
files matched by a glob pattern as included.

Signed-off-by: Nicolas Nobelis <[email protected]>

Author: nnobelis

analyzer/src/main/kotlin/PackageManager.kt

@@ -207,6 +207,13 @@ abstract class PackageManager(val projectType: String) : Plugin {
         private fun Excludes.isPathExcluded(root: Path, path: Path): Boolean =
             isPathExcluded(root.relativize(path).invariantSeparatorsPathString)
 
+        /**
+         * Check whether the given [path] interpreted relatively against [root] is matched by a path include in this
+         * [Includes] object.
+         */
+        private fun Includes.isPathIncluded(root: Path, path: Path): Boolean =
+            isPathIncluded(root.relativize(path).invariantSeparatorsPathString)
+
         /**
          * Get a fallback project name from the [definitionFile] path relative to the [analysisRoot]. This function
          * should be used if the project name cannot be determined from the project's metadata.

integrations/schemas/repository-configuration-schema.json

@@ -8,6 +8,34 @@
     "analyzer": {
       "$ref": "https://raw.githubusercontent.com/oss-review-toolkit/ort/main/integrations/schemas/repository-configurations/analyzer-configuration-schema.json"
     },
+    "includes": {
+      "type": "object",
+      "description": "Defines which parts of a repository should be included.",
+      "properties": {
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "description": "A glob to match the path of the project definition file, relative to the root of the repository.",
+                "type": "string"
+              },
+              "reason": {
+                "$ref": "#/definitions/pathIncludeReason"
+              },
+              "comment": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "pattern",
+              "reason"
+            ]
+          }
+        }
+      }
+    },
     "excludes": {
       "type": "object",
       "description": "Defines which parts of a repository should be excluded.",
@@ -256,6 +284,11 @@
         "reason"
       ]
     },
+    "pathIncludeReason": {
+      "enum": [
+        "SOURCE_OF"
+      ]
+    },
     "pathExcludeReason": {
       "enum": [
         "BUILD_TOOL_OF",

model/src/main/kotlin/config/Includes.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2025 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config
+
+import com.fasterxml.jackson.annotation.JsonInclude
+
+import org.ossreviewtoolkit.model.OrtResult
+import org.ossreviewtoolkit.model.Project
+import org.ossreviewtoolkit.model.config.config.PathInclude
+
+class Includes(
+    /**
+     * Path includes.
+     */
+    @JsonInclude(JsonInclude.Include.NON_EMPTY)
+    val paths: List<PathInclude> = emptyList()
+) {
+    companion object {
+        /**
+         * A constant for an [Includes] instance that does not contain any includes: if no includes are defined,
+         * everything is included.
+         */
+        @JvmField
+        val EMPTY = Includes()
+    }
+
+    /**
+     * Return the [PathInclude]s matching the [definitionFilePath][Project.definitionFilePath].
+     */
+    fun findPathIncludes(project: Project, ortResult: OrtResult): List<PathInclude> {
+        val definitionFilePath = ortResult.getDefinitionFilePathRelativeToAnalyzerRoot(project)
+        return paths.filter { it.matches(definitionFilePath) }
+    }
+
+    /**
+     * True if any [path include][paths] matches [path] or if there is no path includes.
+     */
+    fun isPathIncluded(path: String) = paths.isEmpty() || paths.any { it.matches(path) }
+}

model/src/main/kotlin/config/RepositoryConfiguration.kt

@@ -23,6 +23,7 @@ import com.fasterxml.jackson.annotation.JsonInclude
 
 import org.ossreviewtoolkit.model.utils.CurationsFilter
 import org.ossreviewtoolkit.model.utils.ExcludesFilter
+import org.ossreviewtoolkit.model.utils.IncludesFilter
 import org.ossreviewtoolkit.model.utils.LicenseChoicesFilter
 import org.ossreviewtoolkit.model.utils.ResolutionsFilter
 import org.ossreviewtoolkit.utils.ort.ORT_REPO_CONFIG_FILENAME
@@ -45,6 +46,12 @@ data class RepositoryConfiguration(
     @JsonInclude(value = JsonInclude.Include.CUSTOM, valueFilter = ExcludesFilter::class)
     val excludes: Excludes = Excludes(),
 
+    /**
+     * Defines which parts of the repository will be included.
+     */
+    @JsonInclude(value = JsonInclude.Include.CUSTOM, valueFilter = IncludesFilter::class)
+    val includes: Includes = Includes.EMPTY,
+
     /**
      * Defines resolutions for issues with this repository.
      */

model/src/main/kotlin/config/config/PathInclude.kt

@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2017 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config.config
+
+import com.fasterxml.jackson.annotation.JsonInclude
+
+import org.ossreviewtoolkit.utils.common.FileMatcher
+
+/**
+ * Defines paths which should be included. Each file or directory that is matched by the [glob][pattern] is marked as
+ * included. If a project definition file is matched by the [pattern], the whole project is included. For details about
+ * the glob syntax see the [FileMatcher] implementation.
+ */
+data class PathInclude(
+    /**
+     * A glob to match the path of the project definition file, relative to the root of the repository.
+     */
+    val pattern: String,
+
+    /**
+     * The reason why the project is included, out of a predefined choice.
+     */
+    val reason: PathIncludeReason,
+
+    /**
+     * A comment to further explain why the [reason] is applicable here.
+     */
+    @JsonInclude(JsonInclude.Include.NON_EMPTY)
+    val comment: String = ""
+) {
+    /**
+     * Return true if and only if this [PathInclude] matches the given [path].
+     */
+    fun matches(path: String) =
+        FileMatcher.matches(
+            pattern = pattern.removePrefix("./"),
+            path = path
+        )
+}

model/src/main/kotlin/config/config/PathIncludeReason.kt

@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2025 The ORT Project Authors (see <https://github.com/oss-review-toolkit/ort/blob/main/NOTICE>)
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * License-Filename: LICENSE
+ */
+
+package org.ossreviewtoolkit.model.config.config
+
+enum class PathIncludeReason {
+    /**
+     * The path contains source code used to build distributed build artifacts.
+     */
+    SOURCE_OF,
+
+    /**
+     * Any other reason which cannot be represented by any other element of [PathIncludeReason].
+     */
+    OTHER
+}

model/src/main/kotlin/utils/JsonIncludeValueFilters.kt

@@ -22,6 +22,7 @@ package org.ossreviewtoolkit.model.utils
 import org.ossreviewtoolkit.model.PackageLinkage
 import org.ossreviewtoolkit.model.config.Curations
 import org.ossreviewtoolkit.model.config.Excludes
+import org.ossreviewtoolkit.model.config.Includes
 import org.ossreviewtoolkit.model.config.LicenseChoices
 import org.ossreviewtoolkit.model.config.Resolutions
 
@@ -36,6 +37,11 @@ internal class ExcludesFilter {
     override fun equals(other: Any?): Boolean = other is Excludes && other.paths.isEmpty() && other.scopes.isEmpty()
 }
 
+@Suppress("EqualsOrHashCode", "EqualsWithHashCodeExist") // The class is not supposed to be used with hashing.
+internal class IncludesFilter {
+    override fun equals(other: Any?): Boolean = other is Includes && other.paths.isEmpty()
+}
+
 @Suppress("EqualsOrHashCode", "EqualsWithHashCodeExist") // The class is not supposed to be used with hashing.
 internal class LicenseChoicesFilter {
     override fun equals(other: Any?): Boolean = other is LicenseChoices && other.isEmpty()

website/docs/configuration/ort-yml.md

@@ -4,6 +4,7 @@ The items below can be configured by adding an `.ort.yml` file to the root of th
 All configurations in this file apply only to this Project's context.
 Usually, the global context is preferred for an increased degree of automation, and local configurations should only be done if there are good reasons.
 
+* [includes](#includes) - Mark [files, directories](#including-paths) as included in released artifacts.
 * [excludes](#excludes) - Mark [files, directories](#excluding-paths) or [package manager scopes](#excluding-scopes) as not included in released artifacts.
 * [resolutions](#resolutions) - Resolve any issues or policy rule violations.
 * [curations](#curations) - Overwrite package metadata, set a concluded license, or correct license findings in the project.
@@ -14,6 +15,60 @@ The sections below explain each in further detail.
 Prefer to learn by example?
 See the [.ort.yml](https://github.com/oss-review-toolkit/ort/blob/main/.ort.yml) for the OSS Review Toolkit itself.
 
+## Includes
+
+### When to Use Includes
+
+Includes are used to define which OSS is distributed to third parties and which code is only used internally.
+
+Inclusions apply to paths (files/directories) only.
+Examples of currently supported inclusions:
+
+* all dependencies defined in `./src/pom.xml` in Maven-based projects.
+
+### Includes Basics
+
+ORT's default philosophy is to analyze and scan everything it can find to build a complete picture of a repository and its dependencies.
+
+However, in some cases, only a subset of the repository is relevant for the analysis, for example, if the repository is a monorepo containing multiple projects.
+While [excludes](#excludes) could be used to ignore the irrelevant parts, it is often more convenient to explicitly include only the relevant parts.
+
+To be able to show why a part is included, each include must have an explanation.
+The explanation consists of:
+
+* `reason` -- must be selected from a predefined list of options.
+* `comment` -- free text that provides an optional explanation.
+
+### Including Paths
+
+Path includes are used to mark a complete path as included.
+
+The code below shows the structure of a path include in the `.ort.yml` file:
+
+```yaml
+includes:
+  paths:
+  - pattern: "A glob pattern matching files or paths."
+    reason: "One of PathIncludeReason e.g. SOURCE_OF."
+    comment: "A comment further explaining why the path is included."
+```
+
+Where the list of available options for `reason` is defined in [PathIncludeReason.kt](https://github.com/oss-review-toolkit/ort/blob/main/model/src/main/kotlin/config/PathIncludeReason.kt).
+For how to write a glob pattern, please see the [AntPathMatcher documentation](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/util/AntPathMatcher.html).
+
+The path include below has the following effects:
+
+* All projects found below the `src` directory are marked as included.
+* License findings in files below the `src` directory are marked as included.
+
+```yaml
+excludes:
+  paths:
+  - pattern: "src/**"
+    reason: "SOURCE_OF"
+    comment: "This directory contains the source code of binaries that are distributed."
+```
+
 ## Excludes
 
 ### When to Use Excludes
@@ -149,6 +204,14 @@ import Yarn from '!!raw-loader!@site/../examples/yarn.ort.yml'
 <CodeBlock language="yml" title="Yarn">{Yarn}</CodeBlock>
 ```
 
+## Interaction between Includes and Excludes
+
+There is no priority when using both includes and excludes.
+The includes control what is included and excludes everything else.
+Excludes add extra exclusions.
+If includes and excludes overlap, excludes are stronger.
+This means that if a file is matched by both includes and excludes, it will be excluded.
+
 ## Resolutions
 
 ### When to Use Resolutions