Review skipExcludes Analyzer option

[tsteenbe]

In the ORT community meeting of May 8th, 2025 there was some confusion of how skipExcludes works for the Analyzer as a question to 13960e9 / PR #10212. Propose we review the code in question and as needed make it clearer with code comments how the code works and improve user document to state for which package managers this Analyzer option is supported.

[sschuberth]

In particular, this logic should be reviewed:

ort/analyzer/src/main/kotlin/PackageManager.kt

Lines 194 to 201 in bca9510

	/**
	* Return an [Excludes] instance to be applied during analysis based on the given [repositoryConfiguration].
	* If this [AnalyzerConfiguration] has the [AnalyzerConfiguration.skipExcluded] flag set to true, the
	* excludes configured in [repositoryConfiguration] are actually applied. Otherwise, return an empty [Excludes]
	* object. This means that all dependencies are collected, and excludes are applied later on the report level.
	*/
	internal fun AnalyzerConfiguration.excludes(repositoryConfiguration: RepositoryConfiguration): Excludes =
	repositoryConfiguration.excludes.takeIf { skipExcluded } ?: Excludes.EMPTY

[sschuberth]

To me, this reads as if this option works very different compared to options of the same name in other tools, e.g. ScannerConfiguration.skipExcluded:

Instead of configuring whether analysis should be skipped, it configures whether excludes defined in the RepositoryConfiguration should be taken into account or not. Or am I misreading things, @oss-review-toolkit/kotlin-devs?

[oheger-bosch]

From my understanding, the feature works in this way:

• An Excludes object is used by the Analyzer to control which parts of the project should be analyzed. Based on this, Analyzer may for instance filter out definition files matched by path excludes.
• If the skipExcluded flag is true, this Excludes object is initialized from the exclusion rules defined in the repository configuration. So, everything marked as to be excluded there is going to be skipped.
• If the skipExcluded flag is false, an empty Excludes object is used. Then Analyzer will do a full analysis, and later pipeline steps can ignore parts of the result based on the exclusion rules from the repository configuration.

I assume, this is actually what this feature is supposed to do, right?

[sschuberth]

I think the behavior is indeed correct, but the naming / docs are partly misleading. For example the comment at

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

Lines 41 to 46 in c07420d

	/**
	* Defines which parts of the repository will be excluded. Note that excluded parts will still be analyzed and
	* scanned, but related errors will be marked as resolved in the reporter output.
	*/
	@JsonInclude(value = JsonInclude.Include.CUSTOM, valueFilter = ExcludesFilter::class)
	val excludes: Excludes = Excludes(),

says "Note that excluded parts will still be analyzed" which is not true e.g. for path excludes and skipExcluded enabled.

In general, path and scope excludes are handled quite differently, so that I'm thinking about having dedicated classes for each, actually. Path excludes are handled globally by findManagedFiles(), see

ort/analyzer/src/main/kotlin/PackageManager.kt

Lines 108 to 111 in bca9510

	excludes.isPathExcluded(rootPath, dirAsPath) -> {
	logger.info { "Not analyzing directory '$dir' as it is excluded." }
	false
	}

whereas scope excludes are sometimes handled directly in the package manager implementation, but are also handled by some (?) OrtResult helper functions / properties.