diff --git a/advisor/src/test/kotlin/AdvisorTest.kt b/advisor/src/test/kotlin/AdvisorTest.kt index 5376555b466ee..8697be5195319 100644 --- a/advisor/src/test/kotlin/AdvisorTest.kt +++ b/advisor/src/test/kotlin/AdvisorTest.kt @@ -131,7 +131,8 @@ class AdvisorTest : WordSpec({ ) val failingFactory = mockk { - every { descriptor } returns PluginDescriptor("failing-provider", "FailingProvider", "", emptyList()) + every { descriptor } returns + PluginDescriptor("failing-provider", "FailingProvider", "", options = emptyList()) every { create(any()) } throws IllegalStateException("Could not initialize provider") } @@ -259,7 +260,7 @@ private fun createPackage(index: Int): Package = private fun mockkAdviceProvider(displayName: String = "Provider"): AdviceProvider = mockk().apply { - every { descriptor } returns PluginDescriptor(displayName, displayName, "", emptyList()) + every { descriptor } returns PluginDescriptor(displayName, displayName, "", options = emptyList()) } private fun mockkAdvisorResult(): AdvisorResult = diff --git a/buildSrc/src/main/kotlin/GeneratePluginDocsTask.kt b/buildSrc/src/main/kotlin/GeneratePluginDocsTask.kt index 471882b91da5a..080a7aca1b8b1 100644 --- a/buildSrc/src/main/kotlin/GeneratePluginDocsTask.kt +++ b/buildSrc/src/main/kotlin/GeneratePluginDocsTask.kt @@ -88,9 +88,16 @@ abstract class GeneratePluginDocsTask : DefaultTask() { appendLine() appendLine("![${descriptor["id"]}](https://img.shields.io/badge/Plugin_ID-${descriptor["id"]}-gold)") appendLine() - appendLine(descriptor["description"]) + appendLine("***${descriptor["summary"]}***") appendLine() + descriptor["description"].takeIf { it != null && it != descriptor["summary"]}?.also { + appendLine("## Description") + appendLine() + appendLine(convertKdocLinks(it as String)) + appendLine() + } + val allOptions = ((descriptor["options"]) as List<*>).map { it as Map<*, *> } if (allOptions.isEmpty()) return@buildString @@ -231,3 +238,11 @@ abstract class GeneratePluginDocsTask : DefaultTask() { } } } + +private val KDOC_LINK_REGEX = Regex("""\[([^]]+)](?:\[([^]]+)])?(?!\()""") + +/** Convert KDoc symbol links into inline code blocks. */ +fun convertKdocLinks(input: String) = input.replace(KDOC_LINK_REGEX) { + val (text, target) = it.destructured + if (target.isNotEmpty()) "$text (`$target`)" else "`$text`" +} diff --git a/plugins/advisors/black-duck/src/main/kotlin/BlackDuck.kt b/plugins/advisors/black-duck/src/main/kotlin/BlackDuck.kt index eee4e77842689..41ad02c76a14c 100644 --- a/plugins/advisors/black-duck/src/main/kotlin/BlackDuck.kt +++ b/plugins/advisors/black-duck/src/main/kotlin/BlackDuck.kt @@ -52,12 +52,12 @@ import org.ossreviewtoolkit.utils.common.collectMessages /** * This advice provider by default retrieves vulnerabilities by the purl corresponding to the package. If a package has - * the label [BlackDuck.PACKAGE_LABEL_BLACK_DUCK_ORIGIN_ID] set, then the vulnerabilities are retrieved by that - * origin-id instead of by the purl. + * the label ["black-duck:origin-id"][BlackDuck.PACKAGE_LABEL_BLACK_DUCK_ORIGIN_ID] set, then the vulnerabilities are + * retrieved by that origin-id instead of by the purl. */ @OrtPlugin( displayName = "Black Duck", - description = "An advisor that retrieves vulnerability information from a Black Duck instance.", + summary = "An advisor that retrieves vulnerability information from a Black Duck instance.", factory = AdviceProviderFactory::class ) class BlackDuck( diff --git a/plugins/advisors/oss-index/src/main/kotlin/OssIndex.kt b/plugins/advisors/oss-index/src/main/kotlin/OssIndex.kt index a66e623100af2..417468e3c825b 100644 --- a/plugins/advisors/oss-index/src/main/kotlin/OssIndex.kt +++ b/plugins/advisors/oss-index/src/main/kotlin/OssIndex.kt @@ -59,7 +59,7 @@ private const val BULK_REQUEST_SIZE = 128 @OrtPlugin( id = "OSSIndex", displayName = "OSS Index", - description = "An advisor that uses Sonatype's OSS Index to determine vulnerabilities in dependencies.", + summary = "An advisor that uses Sonatype's OSS Index to determine vulnerabilities in dependencies.", factory = AdviceProviderFactory::class ) class OssIndex( diff --git a/plugins/advisors/osv/src/main/kotlin/Osv.kt b/plugins/advisors/osv/src/main/kotlin/Osv.kt index 58fd99fa8659c..af73e8146341f 100644 --- a/plugins/advisors/osv/src/main/kotlin/Osv.kt +++ b/plugins/advisors/osv/src/main/kotlin/Osv.kt @@ -44,12 +44,12 @@ import org.ossreviewtoolkit.utils.common.toUri import org.ossreviewtoolkit.utils.ort.OkHttpClientHelper /** - * An advice provider that obtains vulnerability information from Open Source Vulnerabilities (https://osv.dev/). + * An advice provider that obtains vulnerability information from [Open Source Vulnerabilities](https://osv.dev/). */ @OrtPlugin( id = "OSV", displayName = "OSV", - description = "An advisor that retrieves vulnerability information from the Open Source Vulnerabilities database.", + summary = "An advisor that retrieves vulnerability information from the Open Source Vulnerabilities database.", factory = AdviceProviderFactory::class ) class Osv( diff --git a/plugins/advisors/scanoss/src/main/kotlin/ScanOss.kt b/plugins/advisors/scanoss/src/main/kotlin/ScanOss.kt index 250d8ab9b80b2..b89ae8d54c5dd 100644 --- a/plugins/advisors/scanoss/src/main/kotlin/ScanOss.kt +++ b/plugins/advisors/scanoss/src/main/kotlin/ScanOss.kt @@ -53,11 +53,11 @@ import org.ossreviewtoolkit.utils.ort.okHttpClient /** * An [AdviceProvider] implementation that obtains security vulnerability information from a - * [SCANOSS][https://github.com/aboutcode-org/vulnerablecode] instance. + * [SCANOSS](https://github.com/aboutcode-org/vulnerablecode) instance. */ @OrtPlugin( displayName = "SCANOSS", - description = "An advisor that uses a SCANOSS instance to determine vulnerabilities in dependencies.", + summary = "An advisor that uses a SCANOSS instance to determine vulnerabilities in dependencies.", factory = AdviceProviderFactory::class ) class ScanOss( diff --git a/plugins/advisors/vulnerable-code/src/main/kotlin/VulnerableCode.kt b/plugins/advisors/vulnerable-code/src/main/kotlin/VulnerableCode.kt index 69f015f21aecc..191fe2b1ca25f 100644 --- a/plugins/advisors/vulnerable-code/src/main/kotlin/VulnerableCode.kt +++ b/plugins/advisors/vulnerable-code/src/main/kotlin/VulnerableCode.kt @@ -62,11 +62,11 @@ private const val MAX_SUMMARY_LENGTH = 64 /** * An [AdviceProvider] implementation that obtains security vulnerability information from a - * [VulnerableCode][https://github.com/aboutcode-org/vulnerablecode] instance. + * [VulnerableCode](https://github.com/aboutcode-org/vulnerablecode) instance. */ @OrtPlugin( displayName = "VulnerableCode", - description = "An advisor that uses a VulnerableCode instance to determine vulnerabilities in dependencies.", + summary = "An advisor that uses a VulnerableCode instance to determine vulnerabilities in dependencies.", factory = AdviceProviderFactory::class ) class VulnerableCode( diff --git a/plugins/api/README.md b/plugins/api/README.md index d2f8184388af1..d1cb8aa6d5c22 100644 --- a/plugins/api/README.md +++ b/plugins/api/README.md @@ -75,6 +75,16 @@ class ExampleAdvisor(override val descriptor: PluginDescriptor, val config: Exam } ``` +The KDoc of the plugin class is used as the description of the plugin when generating the `PluginDescriptor`. +Therefore, it should be written with the intention to be read by users of the plugin. +For example, for package managers, it should document requirements and limitations of the plugin, helping users to successfully analyze their projects. +As the description is also used for the website, certain limitations apply: + +* It should not use reference-style links (like `[some website][1]`). +* It should not use footnotes (like `[^1]`). +* It should only use headings of level 3 or higher (like `### Heading`). +* KDoc symbol references (like `[SomeClass]`) are replaced with inline-code blocks. + ### Plugin Configuration Class The configuration class must be a data class with a single constructor that takes all configuration options as arguments. diff --git a/plugins/api/src/main/kotlin/OrtPlugin.kt b/plugins/api/src/main/kotlin/OrtPlugin.kt index cb03165f672a6..43b573488dc8f 100644 --- a/plugins/api/src/main/kotlin/OrtPlugin.kt +++ b/plugins/api/src/main/kotlin/OrtPlugin.kt @@ -41,8 +41,8 @@ annotation class OrtPlugin( /** The display name of the plugin. */ val displayName: String, - /** The description of the plugin. */ - val description: String, + /** The short description of the plugin. */ + val summary: String, /** The factory class that represents the ORT extension point for this plugin. */ val factory: KClass<*> diff --git a/plugins/api/src/main/kotlin/OrtPluginOption.kt b/plugins/api/src/main/kotlin/OrtPluginOption.kt index 7d3cb5cc5fc26..9b0796f5cca3b 100644 --- a/plugins/api/src/main/kotlin/OrtPluginOption.kt +++ b/plugins/api/src/main/kotlin/OrtPluginOption.kt @@ -26,9 +26,7 @@ package org.ossreviewtoolkit.plugins.api @Target(AnnotationTarget.PROPERTY) @Retention(AnnotationRetention.SOURCE) annotation class OrtPluginOption( - /** - * The default value of the option. - */ + /** The default value of the option. */ val defaultValue: String = NO_DEFAULT_VALUE, /** diff --git a/plugins/api/src/main/kotlin/PluginConfig.kt b/plugins/api/src/main/kotlin/PluginConfig.kt index 82c62379e1563..d8728d0e074fc 100644 --- a/plugins/api/src/main/kotlin/PluginConfig.kt +++ b/plugins/api/src/main/kotlin/PluginConfig.kt @@ -23,13 +23,9 @@ import com.fasterxml.jackson.annotation.JsonIgnore import org.ossreviewtoolkit.utils.common.Options -/** - * The configuration of a plugin, used as input for [PluginFactory.create]. - */ +/** The configuration of a plugin, used as input for [PluginFactory.create]. */ data class PluginConfig( - /** - * The configuration options of the plugin. - */ + /** The configuration options of the plugin. */ val options: Options = emptyMap(), /** @@ -41,19 +37,13 @@ data class PluginConfig( val secrets: Options = emptyMap() ) { companion object { - /** - * Constant for an empty [PluginConfig]. - */ + /** Constant for an empty [PluginConfig]. */ val EMPTY = PluginConfig() } - /** - * Return a string representation that does not contain the [secrets]. - */ + /** Return a string representation that does not contain the [secrets]. */ override fun toString() = "${this::class.simpleName}(options=$options, secrets=[***])" } -/** - * Returns this [PluginConfig] if it is not `null`, or the [empty][PluginConfig.EMPTY] [PluginConfig] otherwise. - */ +/** Returns this [PluginConfig] if it is not `null`, or the [empty][PluginConfig.EMPTY] [PluginConfig] otherwise. */ fun PluginConfig?.orEmpty() = this ?: PluginConfig.EMPTY diff --git a/plugins/api/src/main/kotlin/PluginDescriptor.kt b/plugins/api/src/main/kotlin/PluginDescriptor.kt index b8b2e02e8ea7c..459de83435068 100644 --- a/plugins/api/src/main/kotlin/PluginDescriptor.kt +++ b/plugins/api/src/main/kotlin/PluginDescriptor.kt @@ -19,34 +19,25 @@ package org.ossreviewtoolkit.plugins.api -/** - * A descriptor holding the metadata of a plugin. - */ +/** A descriptor holding the metadata of a plugin. */ data class PluginDescriptor( - /** - * The id of the plugin class. Must be unique among all plugins for the same factory class. - */ + /** The id of the plugin class. Must be unique among all plugins for the same factory class. */ val id: String, - /** - * The display name of the plugin. - */ + /** The display name of the plugin. */ val displayName: String, - /** - * The description of the plugin. - */ - val description: String, + /** The short description of the plugin. */ + val summary: String, + + /** The detailed description of the plugin. */ + val description: String? = null, - /** - * The configuration options supported by the plugin. - */ + /** The configuration options supported by the plugin. */ val options: List = emptyList() ) -/** - * The supported types of plugin options. - */ +/** The supported types of plugin options. */ enum class PluginOptionType(val typeName: String) { /** A [Boolean] option. */ BOOLEAN("Boolean"), @@ -75,53 +66,33 @@ enum class PluginOptionType(val typeName: String) { override fun toString() = typeName } -/** - * A configuration option for a plugin. - */ +/** A configuration option for a plugin. */ data class PluginOption( - /** - * The name of the option. Must be unique among all options of the same plugin. - */ + /** The name of the option. Must be unique among all options of the same plugin. */ val name: String, - /** - * The description of the option. - */ + /** The description of the option. */ val description: String, - /** - * The [type][PluginOptionType] of the option. - */ + /** The [type][PluginOptionType] of the option. */ val type: PluginOptionType, - /** - * The enum type name if [type] is [PluginOptionType.ENUM] or [PluginOptionType.ENUM_LIST], `null` otherwise. - */ + /** The enum type name if [type] is [PluginOptionType.ENUM] or [PluginOptionType.ENUM_LIST], `null` otherwise. */ val enumType: String?, - /** - * The enum entries if [type] is [PluginOptionType.ENUM] or [PluginOptionType.ENUM_LIST], `null` otherwise. - */ + /** The enum entries if [type] is [PluginOptionType.ENUM] or [PluginOptionType.ENUM_LIST], `null` otherwise. */ val enumEntries: List?, - /** - * The default value of the option, or `null` if the option is required. - */ + /** The default value of the option, or `null` if the option is required. */ val defaultValue: String?, - /** - * A list of alternative names for the option. - */ + /** A list of alternative names for the option. */ val aliases: List, - /** - * Whether the option is nullable. - */ + /** Whether the option is nullable. */ val isNullable: Boolean, - /** - * Whether the option is required. - */ + /** Whether the option is required. */ val isRequired: Boolean ) @@ -137,9 +108,7 @@ data class EnumEntry( val aliases: List ) -/** - * A secret value that should not be printed in logs. - */ +/** A secret value that should not be printed in logs. */ @JvmInline value class Secret(val value: String) { override fun toString() = "***" diff --git a/plugins/api/src/main/kotlin/PluginFactory.kt b/plugins/api/src/main/kotlin/PluginFactory.kt index 7cbb32f60a6f7..24450bb126cad 100644 --- a/plugins/api/src/main/kotlin/PluginFactory.kt +++ b/plugins/api/src/main/kotlin/PluginFactory.kt @@ -27,9 +27,7 @@ import java.util.ServiceLoader */ interface PluginFactory { companion object { - /** - * Return all plugin factories of type [FACTORY]. - */ + /** Return all plugin factories of type [FACTORY]. */ inline fun , PLUGIN : Plugin> getAll() = getLoaderFor() .iterator() @@ -39,25 +37,17 @@ interface PluginFactory { } } - /** - * The descriptor of the plugin - */ + /** The descriptor of the plugin */ val descriptor: PluginDescriptor - /** - * Create a new instance of [PLUGIN] from [config]. - */ + /** Create a new instance of [PLUGIN] from [config]. */ fun create(config: PluginConfig): PLUGIN } -/** - * A plugin that ORT can use. Each plugin extension point of ORT must inherit from this interface. - */ +/** A plugin that ORT can use. Each plugin extension point of ORT must inherit from this interface. */ interface Plugin { val descriptor: PluginDescriptor } -/** - * Return a [ServiceLoader] that is capable of loading services of type [T]. - */ +/** Return a [ServiceLoader] that is capable of loading services of type [T]. */ inline fun getLoaderFor(): ServiceLoader = ServiceLoader.load(T::class.java) diff --git a/plugins/api/src/test/kotlin/OptionParsersTest.kt b/plugins/api/src/test/kotlin/OptionParsersTest.kt index 17a7401b3a884..1e48ae87bd0a3 100644 --- a/plugins/api/src/test/kotlin/OptionParsersTest.kt +++ b/plugins/api/src/test/kotlin/OptionParsersTest.kt @@ -628,7 +628,7 @@ private fun createFactory(option: PluginOption) = private val pluginDescriptor = PluginDescriptor( id = "test", displayName = "Test", - description = "Test plugin", + summary = "Test plugin", options = listOf(option) ) diff --git a/plugins/commands/advisor/src/main/kotlin/AdviseCommand.kt b/plugins/commands/advisor/src/main/kotlin/AdviseCommand.kt index 22d4b4a736ed2..b6d946a8c89d5 100644 --- a/plugins/commands/advisor/src/main/kotlin/AdviseCommand.kt +++ b/plugins/commands/advisor/src/main/kotlin/AdviseCommand.kt @@ -63,7 +63,7 @@ import org.ossreviewtoolkit.utils.ort.ortConfigDirectory @OrtPlugin( displayName = "Advise", - description = "Check dependencies for security vulnerabilities.", + summary = "Check dependencies for security vulnerabilities.", factory = OrtCommandFactory::class ) class AdviseCommand(descriptor: PluginDescriptor = AdviseCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/analyzer/src/main/kotlin/AnalyzeCommand.kt b/plugins/commands/analyzer/src/main/kotlin/AnalyzeCommand.kt index 36cea3f02dfbb..be27007d67d22 100644 --- a/plugins/commands/analyzer/src/main/kotlin/AnalyzeCommand.kt +++ b/plugins/commands/analyzer/src/main/kotlin/AnalyzeCommand.kt @@ -68,7 +68,7 @@ import org.ossreviewtoolkit.utils.ort.ortConfigDirectory @OrtPlugin( displayName = "Analyze", - description = "Determine dependencies of a software project.", + summary = "Determine dependencies of a software project.", factory = OrtCommandFactory::class ) class AnalyzeCommand(descriptor: PluginDescriptor = AnalyzeCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/api/src/main/kotlin/OrtCommand.kt b/plugins/commands/api/src/main/kotlin/OrtCommand.kt index 5de357c465d16..44831100930be 100644 --- a/plugins/commands/api/src/main/kotlin/OrtCommand.kt +++ b/plugins/commands/api/src/main/kotlin/OrtCommand.kt @@ -35,7 +35,7 @@ import org.ossreviewtoolkit.utils.ort.ORT_CONFIG_FILENAME * An interface for [CliktCommand]-based ORT commands that come as [Plugin]s. */ abstract class OrtCommand(override val descriptor: PluginDescriptor) : CliktCommand(), Plugin { - override fun help(context: Context) = descriptor.description + override fun help(context: Context) = descriptor.summary protected val ortConfig by requireObject() diff --git a/plugins/commands/compare/src/main/kotlin/CompareCommand.kt b/plugins/commands/compare/src/main/kotlin/CompareCommand.kt index 297d12ed01b44..98b2360d5906b 100644 --- a/plugins/commands/compare/src/main/kotlin/CompareCommand.kt +++ b/plugins/commands/compare/src/main/kotlin/CompareCommand.kt @@ -54,7 +54,7 @@ import org.ossreviewtoolkit.utils.ort.Environment @OrtPlugin( displayName = "Compare", - description = "Compare two ORT results with various methods.", + summary = "Compare two ORT results with various methods.", factory = OrtCommandFactory::class ) class CompareCommand(descriptor: PluginDescriptor = CompareCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/config/src/main/kotlin/ConfigCommand.kt b/plugins/commands/config/src/main/kotlin/ConfigCommand.kt index dfa7913f0e916..d8e5c702c2b91 100644 --- a/plugins/commands/config/src/main/kotlin/ConfigCommand.kt +++ b/plugins/commands/config/src/main/kotlin/ConfigCommand.kt @@ -43,7 +43,7 @@ import org.ossreviewtoolkit.utils.ort.ORT_REFERENCE_CONFIG_FILENAME @OrtPlugin( displayName = "Config", - description = "Show different ORT configurations.", + summary = "Show different ORT configurations.", factory = OrtCommandFactory::class ) class ConfigCommand(descriptor: PluginDescriptor = ConfigCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/downloader/src/main/kotlin/DownloadCommand.kt b/plugins/commands/downloader/src/main/kotlin/DownloadCommand.kt index 0ba3251cf87a8..7ac0edf84d79c 100644 --- a/plugins/commands/downloader/src/main/kotlin/DownloadCommand.kt +++ b/plugins/commands/downloader/src/main/kotlin/DownloadCommand.kt @@ -108,7 +108,7 @@ import org.ossreviewtoolkit.utils.spdxexpression.SpdxLicenseChoice @OrtPlugin( displayName = "Download", - description = "Fetch source code from a remote location.", + summary = "Fetch source code from a remote location.", factory = OrtCommandFactory::class ) class DownloadCommand(descriptor: PluginDescriptor = DownloadCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/evaluator/src/main/kotlin/EvaluateCommand.kt b/plugins/commands/evaluator/src/main/kotlin/EvaluateCommand.kt index cf5c61348b2d0..eee07dc793e69 100644 --- a/plugins/commands/evaluator/src/main/kotlin/EvaluateCommand.kt +++ b/plugins/commands/evaluator/src/main/kotlin/EvaluateCommand.kt @@ -88,7 +88,7 @@ import org.ossreviewtoolkit.utils.ort.ortConfigDirectory @OrtPlugin( displayName = "Evaluate", - description = "Evaluate ORT result files against policy rules.", + summary = "Evaluate ORT result files against policy rules.", factory = OrtCommandFactory::class ) class EvaluateCommand(descriptor: PluginDescriptor = EvaluateCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/migrate/src/main/kotlin/MigrateCommand.kt b/plugins/commands/migrate/src/main/kotlin/MigrateCommand.kt index ba6d37a480156..444e5b8a61a22 100644 --- a/plugins/commands/migrate/src/main/kotlin/MigrateCommand.kt +++ b/plugins/commands/migrate/src/main/kotlin/MigrateCommand.kt @@ -46,7 +46,7 @@ import org.ossreviewtoolkit.utils.common.safeMkdirs @OrtPlugin( displayName = "Migrate", - description = "Assist with migrating ORT configuration to newer ORT versions.", + summary = "Assist with migrating ORT configuration to newer ORT versions.", factory = OrtCommandFactory::class ) class MigrateCommand(descriptor: PluginDescriptor = MigrateCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/notifier/src/main/kotlin/NotifyCommand.kt b/plugins/commands/notifier/src/main/kotlin/NotifyCommand.kt index 391e3d70d4731..eba08a9bc325e 100644 --- a/plugins/commands/notifier/src/main/kotlin/NotifyCommand.kt +++ b/plugins/commands/notifier/src/main/kotlin/NotifyCommand.kt @@ -45,7 +45,7 @@ import org.ossreviewtoolkit.utils.ort.ortConfigDirectory @OrtPlugin( displayName = "Notify", - description = "Create notifications based on an ORT result.", + summary = "Create notifications based on an ORT result.", factory = OrtCommandFactory::class ) class NotifyCommand(descriptor: PluginDescriptor = NotifyCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/plugins/src/main/kotlin/PluginsCommand.kt b/plugins/commands/plugins/src/main/kotlin/PluginsCommand.kt index ac24cf6b46d9f..b90832cacc830 100644 --- a/plugins/commands/plugins/src/main/kotlin/PluginsCommand.kt +++ b/plugins/commands/plugins/src/main/kotlin/PluginsCommand.kt @@ -39,7 +39,7 @@ import org.ossreviewtoolkit.scanner.ScannerWrapperFactory @OrtPlugin( displayName = "Plugins", - description = "Print information about the installed ORT plugins.", + summary = "Print information about the installed ORT plugins.", factory = OrtCommandFactory::class ) class PluginsCommand(descriptor: PluginDescriptor = PluginsCommandFactory.descriptor) : OrtCommand(descriptor) { @@ -67,7 +67,7 @@ class PluginsCommand(descriptor: PluginDescriptor = PluginsCommandFactory.descri echo("ID: ${plugin.id}") echo() - echo("Description: ${plugin.description}") + echo("Summary: ${plugin.summary}") echo() if (plugin.options.isNotEmpty()) { diff --git a/plugins/commands/reporter/src/main/kotlin/ReportCommand.kt b/plugins/commands/reporter/src/main/kotlin/ReportCommand.kt index 251b8bf7ef3c6..9ad844b2b721b 100644 --- a/plugins/commands/reporter/src/main/kotlin/ReportCommand.kt +++ b/plugins/commands/reporter/src/main/kotlin/ReportCommand.kt @@ -88,7 +88,7 @@ import org.ossreviewtoolkit.utils.ort.showStackTrace @OrtPlugin( displayName = "Report", - description = "Present Analyzer, Scanner and Evaluator results in various formats.", + summary = "Present Analyzer, Scanner and Evaluator results in various formats.", factory = OrtCommandFactory::class ) class ReportCommand(descriptor: PluginDescriptor = ReportCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/requirements/src/main/kotlin/RequirementsCommand.kt b/plugins/commands/requirements/src/main/kotlin/RequirementsCommand.kt index d197b14c9aa8a..392a952801fae 100644 --- a/plugins/commands/requirements/src/main/kotlin/RequirementsCommand.kt +++ b/plugins/commands/requirements/src/main/kotlin/RequirementsCommand.kt @@ -46,7 +46,7 @@ private val SUCCESS_PREFIX = "\t${Theme.Default.success("*")} " @OrtPlugin( displayName = "Requirements", - description = "Check for the command line tools required by ORT.", + summary = "Check for the command line tools required by ORT.", factory = OrtCommandFactory::class ) class RequirementsCommand( diff --git a/plugins/commands/scanner/src/main/kotlin/ScanCommand.kt b/plugins/commands/scanner/src/main/kotlin/ScanCommand.kt index 4e352c7c3d2b2..18386708dcbd2 100644 --- a/plugins/commands/scanner/src/main/kotlin/ScanCommand.kt +++ b/plugins/commands/scanner/src/main/kotlin/ScanCommand.kt @@ -77,7 +77,7 @@ import org.ossreviewtoolkit.utils.ort.ortConfigDirectory @OrtPlugin( displayName = "Scan", - description = "Run external license / copyright scanners.", + summary = "Run external license / copyright scanners.", factory = OrtCommandFactory::class ) class ScanCommand(descriptor: PluginDescriptor = ScanCommandFactory.descriptor) : OrtCommand(descriptor) { diff --git a/plugins/commands/upload-curations/src/main/kotlin/UploadCurationsCommand.kt b/plugins/commands/upload-curations/src/main/kotlin/UploadCurationsCommand.kt index 03ec795f7a853..e029e26089fca 100644 --- a/plugins/commands/upload-curations/src/main/kotlin/UploadCurationsCommand.kt +++ b/plugins/commands/upload-curations/src/main/kotlin/UploadCurationsCommand.kt @@ -61,7 +61,7 @@ import org.ossreviewtoolkit.utils.ort.runBlocking @OrtPlugin( displayName = "Upload Curations", - description = "Upload ORT package curations to ClearlyDefined.", + summary = "Upload ORT package curations to ClearlyDefined.", factory = OrtCommandFactory::class ) class UploadCurationsCommand( diff --git a/plugins/commands/upload-result-to-postgres/src/main/kotlin/UploadResultToPostgresCommand.kt b/plugins/commands/upload-result-to-postgres/src/main/kotlin/UploadResultToPostgresCommand.kt index 81e53ca109c13..cf73a3a79ae02 100644 --- a/plugins/commands/upload-result-to-postgres/src/main/kotlin/UploadResultToPostgresCommand.kt +++ b/plugins/commands/upload-result-to-postgres/src/main/kotlin/UploadResultToPostgresCommand.kt @@ -52,7 +52,7 @@ import org.ossreviewtoolkit.utils.ort.showStackTrace @OrtPlugin( displayName = "Upload Result to Postgres", - description = "Upload an ORT result to a PostgreSQL database.", + summary = "Upload an ORT result to a PostgreSQL database.", factory = OrtCommandFactory::class ) class UploadResultToPostgresCommand( diff --git a/plugins/compiler/src/main/kotlin/JsonSpecGenerator.kt b/plugins/compiler/src/main/kotlin/JsonSpecGenerator.kt index dc0325cce1e6f..87e915e5eb540 100644 --- a/plugins/compiler/src/main/kotlin/JsonSpecGenerator.kt +++ b/plugins/compiler/src/main/kotlin/JsonSpecGenerator.kt @@ -43,6 +43,7 @@ class JsonSpecGenerator(private val codeGenerator: CodeGenerator) { putJsonObject("descriptor") { put("id", pluginSpec.descriptor.id) put("displayName", pluginSpec.descriptor.displayName) + put("summary", pluginSpec.descriptor.summary) put("description", pluginSpec.descriptor.description) putJsonArray("options") { diff --git a/plugins/compiler/src/main/kotlin/PluginFactoryGenerator.kt b/plugins/compiler/src/main/kotlin/PluginFactoryGenerator.kt index 1c62c704840f2..1cbff09548019 100644 --- a/plugins/compiler/src/main/kotlin/PluginFactoryGenerator.kt +++ b/plugins/compiler/src/main/kotlin/PluginFactoryGenerator.kt @@ -270,12 +270,14 @@ class PluginFactoryGenerator(private val codeGenerator: CodeGenerator) { PluginDescriptor( id = %S, displayName = %S, + summary = %S, description = %S, options = listOf( """.trimIndent(), descriptor.id, descriptor.displayName, + descriptor.summary, descriptor.description ) diff --git a/plugins/compiler/src/main/kotlin/PluginSpecFactory.kt b/plugins/compiler/src/main/kotlin/PluginSpecFactory.kt index 49ebf9e87b654..386f0e5abb8f3 100644 --- a/plugins/compiler/src/main/kotlin/PluginSpecFactory.kt +++ b/plugins/compiler/src/main/kotlin/PluginSpecFactory.kt @@ -74,7 +74,8 @@ class PluginSpecFactory { descriptor = PluginDescriptor( id = pluginId, displayName = ortPlugin.displayName, - description = ortPlugin.description, + summary = ortPlugin.summary, + description = pluginClass.docString?.trim(), options = pluginOptions ), packageName = pluginClass.packageName.asString(), diff --git a/plugins/license-fact-providers/api/src/main/kotlin/CompositeLicenseFactProvider.kt b/plugins/license-fact-providers/api/src/main/kotlin/CompositeLicenseFactProvider.kt index a379238b70a42..5b45702c3cadc 100644 --- a/plugins/license-fact-providers/api/src/main/kotlin/CompositeLicenseFactProvider.kt +++ b/plugins/license-fact-providers/api/src/main/kotlin/CompositeLicenseFactProvider.kt @@ -34,7 +34,7 @@ class CompositeLicenseFactProvider( override val descriptor = PluginDescriptor( id = "Composite", displayName = "Composite License Fact Provider", - description = "A license fact provider that aggregates multiple license fact providers." + summary = "A license fact provider that aggregates multiple license fact providers." ) override fun getLicenseText(licenseId: String) = providers.firstNotNullOfOrNull { it.getLicenseText(licenseId) } diff --git a/plugins/license-fact-providers/dir/src/main/kotlin/DirLicenseFactProvider.kt b/plugins/license-fact-providers/dir/src/main/kotlin/DirLicenseFactProvider.kt index 7fe0928c6a2cc..b038ca4aa167f 100644 --- a/plugins/license-fact-providers/dir/src/main/kotlin/DirLicenseFactProvider.kt +++ b/plugins/license-fact-providers/dir/src/main/kotlin/DirLicenseFactProvider.kt @@ -37,9 +37,13 @@ data class DirLicenseFactProviderConfig( val licenseTextDir: String ) +/** + * A license fact provider that reads license information from the default directory. The files must be named after the + * SPDX-conform license IDs, e.g., 'Apache-2.0' or 'LicenseRef-custom-license'. + */ @OrtPlugin( displayName = "Default Directory License Fact Provider", - description = "A license fact provider that reads license information from the default directory.", + summary = "A license fact provider that reads license information from the default directory.", factory = LicenseFactProviderFactory::class ) class DefaultDirLicenseFactProvider(descriptor: PluginDescriptor = DefaultDirLicenseFactProviderFactory.descriptor) : @@ -50,11 +54,14 @@ class DefaultDirLicenseFactProvider(descriptor: PluginDescriptor = DefaultDirLic ) ) +/** + * A license fact provider that reads license information from a local directory. The files must be named after the + * SPDX-conform license IDs, e.g., 'Apache-2.0' or 'LicenseRef-custom-license'. + */ @OrtPlugin( id = "Dir", displayName = "Directory License Fact Provider", - description = "A license fact provider that reads license information from a local directory. The files must be " + - "named after the SPDX-conform license IDs, e.g., 'Apache-2.0' or 'LicenseRef-custom-license'.", + summary = "A license fact provider that reads license information from a local directory.", factory = LicenseFactProviderFactory::class ) open class DirLicenseFactProvider( diff --git a/plugins/license-fact-providers/scancode/src/main/kotlin/ScanCodeLicenseFactProvider.kt b/plugins/license-fact-providers/scancode/src/main/kotlin/ScanCodeLicenseFactProvider.kt index 60a1ff5fc3234..b413e689b28f4 100644 --- a/plugins/license-fact-providers/scancode/src/main/kotlin/ScanCodeLicenseFactProvider.kt +++ b/plugins/license-fact-providers/scancode/src/main/kotlin/ScanCodeLicenseFactProvider.kt @@ -50,7 +50,7 @@ data class ScanCodeLicenseFactProviderConfig( @OrtPlugin( id = "ScanCode", displayName = "ScanCode License Fact Provider", - description = "A license fact provider that reads license information from a local ScanCode installation.", + summary = "A license fact provider that reads license information from a local ScanCode installation.", factory = LicenseFactProviderFactory::class ) class ScanCodeLicenseFactProvider( diff --git a/plugins/license-fact-providers/spdx/src/main/kotlin/SpdxLicenseFactProvider.kt b/plugins/license-fact-providers/spdx/src/main/kotlin/SpdxLicenseFactProvider.kt index b0e8808ebe763..80fb244f61604 100644 --- a/plugins/license-fact-providers/spdx/src/main/kotlin/SpdxLicenseFactProvider.kt +++ b/plugins/license-fact-providers/spdx/src/main/kotlin/SpdxLicenseFactProvider.kt @@ -30,7 +30,7 @@ import org.ossreviewtoolkit.plugins.licensefactproviders.api.LicenseText @OrtPlugin( id = "SPDX", displayName = "SPDX License Fact Provider", - description = "A provider for SPDX license facts.", + summary = "A provider for SPDX license facts.", factory = LicenseFactProviderFactory::class ) class SpdxLicenseFactProvider( diff --git a/plugins/package-configuration-providers/api/src/main/kotlin/CompositePackageConfigurationProvider.kt b/plugins/package-configuration-providers/api/src/main/kotlin/CompositePackageConfigurationProvider.kt index b021b8d51939a..425f675412aec 100644 --- a/plugins/package-configuration-providers/api/src/main/kotlin/CompositePackageConfigurationProvider.kt +++ b/plugins/package-configuration-providers/api/src/main/kotlin/CompositePackageConfigurationProvider.kt @@ -36,7 +36,7 @@ class CompositePackageConfigurationProvider( override val descriptor = PluginDescriptor( id = "Composite", displayName = "Composite Package Configuration Provider", - description = "A package configuration provider that combines multiple package configuration providers." + summary = "A package configuration provider that combines multiple package configuration providers." ) override fun getPackageConfigurations(packageId: Identifier, provenance: Provenance): List = diff --git a/plugins/package-configuration-providers/api/src/main/kotlin/SimplePackageConfigurationProvider.kt b/plugins/package-configuration-providers/api/src/main/kotlin/SimplePackageConfigurationProvider.kt index f7a6efdd3e8fd..14f2b179c07d3 100644 --- a/plugins/package-configuration-providers/api/src/main/kotlin/SimplePackageConfigurationProvider.kt +++ b/plugins/package-configuration-providers/api/src/main/kotlin/SimplePackageConfigurationProvider.kt @@ -32,7 +32,7 @@ import org.ossreviewtoolkit.plugins.api.PluginDescriptor private val pluginDescriptor = PluginDescriptor( id = "Simple", displayName = "Simple", - description = "A simple package configuration provider, which provides a fixed set of package configurations." + summary = "A simple package configuration provider, which provides a fixed set of package configurations." ) /** diff --git a/plugins/package-configuration-providers/dir/src/main/kotlin/DirPackageConfigurationProvider.kt b/plugins/package-configuration-providers/dir/src/main/kotlin/DirPackageConfigurationProvider.kt index 9dc8701a652ed..51ac8833a3cea 100644 --- a/plugins/package-configuration-providers/dir/src/main/kotlin/DirPackageConfigurationProvider.kt +++ b/plugins/package-configuration-providers/dir/src/main/kotlin/DirPackageConfigurationProvider.kt @@ -50,7 +50,7 @@ data class DirPackageConfigurationProviderConfig( @OrtPlugin( displayName = "Default Directory", - description = "A package configuration provider that loads package curations from the default directory.", + summary = "A package configuration provider that loads package curations from the default directory.", factory = PackageConfigurationProviderFactory::class ) class DefaultDirPackageConfigurationProvider(descriptor: PluginDescriptor) : DirPackageConfigurationProvider( @@ -67,7 +67,7 @@ class DefaultDirPackageConfigurationProvider(descriptor: PluginDescriptor) : Dir */ @OrtPlugin( displayName = "Directory", - description = "Provides package configurations from a directory.", + summary = "Provides package configurations from a directory.", factory = PackageConfigurationProviderFactory::class ) open class DirPackageConfigurationProvider( diff --git a/plugins/package-configuration-providers/dos/src/main/kotlin/DosPackageConfigurationProvider.kt b/plugins/package-configuration-providers/dos/src/main/kotlin/DosPackageConfigurationProvider.kt index ca233e277ec12..1e9344e977ae0 100644 --- a/plugins/package-configuration-providers/dos/src/main/kotlin/DosPackageConfigurationProvider.kt +++ b/plugins/package-configuration-providers/dos/src/main/kotlin/DosPackageConfigurationProvider.kt @@ -62,7 +62,7 @@ data class DosPackageConfigurationProviderConfig( @OrtPlugin( id = "DOS", displayName = "Double Open Server", - description = "A package configuration provider that loads package configurations from a Double Open Server " + + summary = "A package configuration provider that loads package configurations from a Double Open Server " + "instance.", factory = PackageConfigurationProviderFactory::class ) diff --git a/plugins/package-configuration-providers/ort-config/src/main/kotlin/OrtConfigPackageConfigurationProvider.kt b/plugins/package-configuration-providers/ort-config/src/main/kotlin/OrtConfigPackageConfigurationProvider.kt index be069a518da72..45b21c3ea5f1b 100644 --- a/plugins/package-configuration-providers/ort-config/src/main/kotlin/OrtConfigPackageConfigurationProvider.kt +++ b/plugins/package-configuration-providers/ort-config/src/main/kotlin/OrtConfigPackageConfigurationProvider.kt @@ -49,7 +49,7 @@ private const val PACKAGE_CONFIGURATIONS_DIR = "package-configurations" @OrtPlugin( id = "ORTConfig", displayName = "ORT Config Repository", - description = "A package configuration provider that loads package configurations from the ort-config repository.", + summary = "A package configuration provider that loads package configurations from the ort-config repository.", factory = PackageConfigurationProviderFactory::class ) class OrtConfigPackageConfigurationProvider( diff --git a/plugins/package-curation-providers/api/src/main/kotlin/SimplePackageCurationProvider.kt b/plugins/package-curation-providers/api/src/main/kotlin/SimplePackageCurationProvider.kt index 2cc366dffbe86..f0c5a11e1920f 100644 --- a/plugins/package-curation-providers/api/src/main/kotlin/SimplePackageCurationProvider.kt +++ b/plugins/package-curation-providers/api/src/main/kotlin/SimplePackageCurationProvider.kt @@ -30,7 +30,7 @@ import org.ossreviewtoolkit.plugins.api.PluginDescriptor private val pluginDescriptor = PluginDescriptor( id = "Simple", displayName = "Simple", - description = "A simple package curation provider, which provides a fixed set of package curations." + summary = "A simple package curation provider, which provides a fixed set of package curations." ) /** diff --git a/plugins/package-curation-providers/clearly-defined/src/main/kotlin/ClearlyDefinedPackageCurationProvider.kt b/plugins/package-curation-providers/clearly-defined/src/main/kotlin/ClearlyDefinedPackageCurationProvider.kt index e1386a0ba22ec..382b671c51a00 100644 --- a/plugins/package-curation-providers/clearly-defined/src/main/kotlin/ClearlyDefinedPackageCurationProvider.kt +++ b/plugins/package-curation-providers/clearly-defined/src/main/kotlin/ClearlyDefinedPackageCurationProvider.kt @@ -73,7 +73,7 @@ data class ClearlyDefinedPackageCurationProviderConfig( */ @OrtPlugin( displayName = "ClearlyDefined", - description = "Provides package curation data from the ClearlyDefined service.", + summary = "Provides package curation data from the ClearlyDefined service.", factory = PackageCurationProviderFactory::class ) class ClearlyDefinedPackageCurationProvider( diff --git a/plugins/package-curation-providers/file/src/main/kotlin/FilePackageCurationProvider.kt b/plugins/package-curation-providers/file/src/main/kotlin/FilePackageCurationProvider.kt index 631f435ad2e4c..c7bc9484c9bae 100644 --- a/plugins/package-curation-providers/file/src/main/kotlin/FilePackageCurationProvider.kt +++ b/plugins/package-curation-providers/file/src/main/kotlin/FilePackageCurationProvider.kt @@ -51,7 +51,7 @@ data class FilePackageCurationProviderConfig( @OrtPlugin( displayName = "Default File", - description = "A package curation provider that loads package curations from the default file.", + summary = "A package curation provider that loads package curations from the default file.", factory = PackageCurationProviderFactory::class ) class DefaultFilePackageCurationProvider(descriptor: PluginDescriptor) : FilePackageCurationProvider( @@ -64,7 +64,7 @@ class DefaultFilePackageCurationProvider(descriptor: PluginDescriptor) : FilePac @OrtPlugin( displayName = "Default Directory", - description = "A package curation provider that loads package curations from the default directory.", + summary = "A package curation provider that loads package curations from the default directory.", factory = PackageCurationProviderFactory::class ) class DefaultDirPackageCurationProvider(descriptor: PluginDescriptor) : FilePackageCurationProvider( @@ -81,7 +81,7 @@ class DefaultDirPackageCurationProvider(descriptor: PluginDescriptor) : FilePack */ @OrtPlugin( displayName = "File", - description = "A package curation provider that loads package curations from files.", + summary = "A package curation provider that loads package curations from files.", factory = PackageCurationProviderFactory::class ) open class FilePackageCurationProvider(descriptor: PluginDescriptor, vararg paths: File?) : diff --git a/plugins/package-curation-providers/ort-config/src/main/kotlin/OrtConfigPackageCurationProvider.kt b/plugins/package-curation-providers/ort-config/src/main/kotlin/OrtConfigPackageCurationProvider.kt index 0612ace09127e..96a3ae92098a9 100644 --- a/plugins/package-curation-providers/ort-config/src/main/kotlin/OrtConfigPackageCurationProvider.kt +++ b/plugins/package-curation-providers/ort-config/src/main/kotlin/OrtConfigPackageCurationProvider.kt @@ -50,7 +50,7 @@ private const val ORT_CONFIG_REPOSITORY_URL = "https://github.com/oss-review-too @OrtPlugin( id = "ORTConfig", displayName = "ORT Config Repository", - description = "A package curation provider that loads package curations from the ort-config repository.", + summary = "A package curation provider that loads package curations from the ort-config repository.", factory = PackageCurationProviderFactory::class ) open class OrtConfigPackageCurationProvider( diff --git a/plugins/package-curation-providers/spring/src/main/kotlin/SpringPackageCurationProvider.kt b/plugins/package-curation-providers/spring/src/main/kotlin/SpringPackageCurationProvider.kt index 74aa1792f55d1..180ea77e9b4dc 100644 --- a/plugins/package-curation-providers/spring/src/main/kotlin/SpringPackageCurationProvider.kt +++ b/plugins/package-curation-providers/spring/src/main/kotlin/SpringPackageCurationProvider.kt @@ -29,11 +29,11 @@ import org.ossreviewtoolkit.plugins.packagecurationproviders.api.PackageCuration import org.ossreviewtoolkit.plugins.packagecurationproviders.api.PackageCurationProviderFactory /** - * A [PackageCurationProvider] that provides [PackageCuration]s for Spring (https://spring.io/) packages. + * A [PackageCurationProvider] that provides [PackageCuration]s for [Spring](https://spring.io/) packages. */ @OrtPlugin( displayName = "Spring", - description = "A package curation provider for Spring packages.", + summary = "A package curation provider for Spring packages.", factory = PackageCurationProviderFactory::class ) open class SpringPackageCurationProvider( diff --git a/plugins/package-managers/bazel/src/main/kotlin/Bazel.kt b/plugins/package-managers/bazel/src/main/kotlin/Bazel.kt index 6aa6aeeffdcde..70a984df93364 100644 --- a/plugins/package-managers/bazel/src/main/kotlin/Bazel.kt +++ b/plugins/package-managers/bazel/src/main/kotlin/Bazel.kt @@ -157,7 +157,7 @@ internal object BuildozerCommand : CommandLineTool { */ @OrtPlugin( displayName = "Bazel", - description = "The Bazel package manager.", + summary = "The Bazel package manager.", factory = PackageManagerFactory::class ) class Bazel( diff --git a/plugins/package-managers/bower/src/main/kotlin/Bower.kt b/plugins/package-managers/bower/src/main/kotlin/Bower.kt index b9136b0e4153c..9fbdf92fc35de 100644 --- a/plugins/package-managers/bower/src/main/kotlin/Bower.kt +++ b/plugins/package-managers/bower/src/main/kotlin/Bower.kt @@ -54,7 +54,7 @@ internal object BowerCommand : CommandLineTool { */ @OrtPlugin( displayName = "Bower", - description = "The Bower package manager for JavaScript.", + summary = "The Bower package manager for JavaScript.", factory = PackageManagerFactory::class ) class Bower(override val descriptor: PluginDescriptor = BowerFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/bundler/src/main/kotlin/Bundler.kt b/plugins/package-managers/bundler/src/main/kotlin/Bundler.kt index e0525b8d31bc2..88d7e82258b6f 100644 --- a/plugins/package-managers/bundler/src/main/kotlin/Bundler.kt +++ b/plugins/package-managers/bundler/src/main/kotlin/Bundler.kt @@ -109,14 +109,12 @@ data class BundlerConfig( ) /** - * The [Bundler][1] package manager for Ruby. Also see [Clarifying the Roles of the .gemspec and Gemfile][2]. - * - * [1]: https://bundler.io/ - * [2]: http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/ + * The [Bundler](https://bundler.io/) package manager for Ruby. Also see [Clarifying the Roles of the .gemspec and + * Gemfile](http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/). */ @OrtPlugin( displayName = "Bundler", - description = "The Bundler package manager for Ruby.", + summary = "The Bundler package manager for Ruby.", factory = PackageManagerFactory::class ) class Bundler( diff --git a/plugins/package-managers/cargo/src/main/kotlin/Cargo.kt b/plugins/package-managers/cargo/src/main/kotlin/Cargo.kt index c2548fc65811a..435a2a0c11bc6 100644 --- a/plugins/package-managers/cargo/src/main/kotlin/Cargo.kt +++ b/plugins/package-managers/cargo/src/main/kotlin/Cargo.kt @@ -76,7 +76,7 @@ internal object CargoCommand : CommandLineTool { */ @OrtPlugin( displayName = "Cargo", - description = "The Cargo package manager for Rust.", + summary = "The Cargo package manager for Rust.", factory = PackageManagerFactory::class ) class Cargo(override val descriptor: PluginDescriptor = CargoFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/carthage/src/main/kotlin/Carthage.kt b/plugins/package-managers/carthage/src/main/kotlin/Carthage.kt index 45b440de70710..c26abfca2c400 100644 --- a/plugins/package-managers/carthage/src/main/kotlin/Carthage.kt +++ b/plugins/package-managers/carthage/src/main/kotlin/Carthage.kt @@ -55,7 +55,7 @@ internal const val PACKAGE_TYPE = "Carthage" */ @OrtPlugin( displayName = "Carthage", - description = "The Carthage package manager for Objective-C / Swift.", + summary = "The Carthage package manager for Objective-C / Swift.", factory = PackageManagerFactory::class ) class Carthage(override val descriptor: PluginDescriptor = CarthageFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/cocoapods/src/main/kotlin/CocoaPods.kt b/plugins/package-managers/cocoapods/src/main/kotlin/CocoaPods.kt index c819d9571e1ea..0792350cab886 100644 --- a/plugins/package-managers/cocoapods/src/main/kotlin/CocoaPods.kt +++ b/plugins/package-managers/cocoapods/src/main/kotlin/CocoaPods.kt @@ -74,7 +74,7 @@ internal object CocoaPodsCommand : CommandLineTool { */ @OrtPlugin( displayName = "CocoaPods", - description = "The CocoaPods package manager for Objective-C.", + summary = "The CocoaPods package manager for Objective-C.", factory = PackageManagerFactory::class ) class CocoaPods( diff --git a/plugins/package-managers/composer/src/main/kotlin/Composer.kt b/plugins/package-managers/composer/src/main/kotlin/Composer.kt index b5d09d5575270..c0d2b9639d375 100644 --- a/plugins/package-managers/composer/src/main/kotlin/Composer.kt +++ b/plugins/package-managers/composer/src/main/kotlin/Composer.kt @@ -90,7 +90,7 @@ internal object ComposerCommand : CommandLineTool { */ @OrtPlugin( displayName = "Composer", - description = "The Composer package manager for PHP.", + summary = "The Composer package manager for PHP.", factory = PackageManagerFactory::class ) class Composer(override val descriptor: PluginDescriptor = ComposerFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/conan/src/main/kotlin/Conan.kt b/plugins/package-managers/conan/src/main/kotlin/Conan.kt index 6f19de4fb17b9..044289e5469ad 100644 --- a/plugins/package-managers/conan/src/main/kotlin/Conan.kt +++ b/plugins/package-managers/conan/src/main/kotlin/Conan.kt @@ -115,7 +115,7 @@ data class ConanConfig( */ @OrtPlugin( displayName = "Conan", - description = "The Conan package manager for C / C++.", + summary = "The Conan package manager for C / C++.", factory = PackageManagerFactory::class ) @Suppress("TooManyFunctions") diff --git a/plugins/package-managers/gleam/src/main/kotlin/Gleam.kt b/plugins/package-managers/gleam/src/main/kotlin/Gleam.kt index c8824e4bc0b1b..d677df0449737 100644 --- a/plugins/package-managers/gleam/src/main/kotlin/Gleam.kt +++ b/plugins/package-managers/gleam/src/main/kotlin/Gleam.kt @@ -54,7 +54,7 @@ private const val MANIFEST_TOML = "manifest.toml" */ @OrtPlugin( displayName = "Gleam", - description = "The package manager for Gleam.", + summary = "The package manager for Gleam.", factory = PackageManagerFactory::class ) class Gleam internal constructor( diff --git a/plugins/package-managers/go/src/main/kotlin/GoMod.kt b/plugins/package-managers/go/src/main/kotlin/GoMod.kt index cc9226804e06d..a842422a798f5 100644 --- a/plugins/package-managers/go/src/main/kotlin/GoMod.kt +++ b/plugins/package-managers/go/src/main/kotlin/GoMod.kt @@ -86,15 +86,15 @@ data class GoModConfig( ) /** - * The [Go Modules](https://go.dev/ref/mod) package manager for Go. Also see the [usage and troubleshooting guide] - * (https://github.com/golang/go/wiki/Modules). + * The [Go Modules](https://go.dev/ref/mod) package manager for Go. Also see the + * [usage and troubleshooting guide](https://github.com/golang/go/wiki/Modules). * * Note: The file `go.sum` is not a lockfile as Go modules already allows for reproducible builds without that file. * Thus, no logic for handling the [AnalyzerConfiguration.allowDynamicVersions] is needed. */ @OrtPlugin( displayName = "GoMod", - description = "The Go Modules package manager for Go.", + summary = "The Go Modules package manager for Go.", factory = PackageManagerFactory::class ) class GoMod( diff --git a/plugins/package-managers/gradle-inspector/src/main/kotlin/GradleInspector.kt b/plugins/package-managers/gradle-inspector/src/main/kotlin/GradleInspector.kt index 7152b688b076a..a58022aa2eb95 100644 --- a/plugins/package-managers/gradle-inspector/src/main/kotlin/GradleInspector.kt +++ b/plugins/package-managers/gradle-inspector/src/main/kotlin/GradleInspector.kt @@ -112,7 +112,7 @@ data class GradleInspectorConfig( */ @OrtPlugin( displayName = "Gradle Inspector", - description = "The Gradle package manager for Java.", + summary = "The Gradle package manager for Java.", factory = PackageManagerFactory::class ) class GradleInspector( diff --git a/plugins/package-managers/gradle/src/main/kotlin/Gradle.kt b/plugins/package-managers/gradle/src/main/kotlin/Gradle.kt index e26b843e3ff0b..a539375f9c253 100644 --- a/plugins/package-managers/gradle/src/main/kotlin/Gradle.kt +++ b/plugins/package-managers/gradle/src/main/kotlin/Gradle.kt @@ -109,7 +109,7 @@ data class GradleConfig( */ @OrtPlugin( displayName = "Gradle", - description = "The Gradle package manager for Java.", + summary = "The Gradle package manager for Java.", factory = PackageManagerFactory::class ) class Gradle( diff --git a/plugins/package-managers/maven/src/main/kotlin/Maven.kt b/plugins/package-managers/maven/src/main/kotlin/Maven.kt index 4e602faa82352..23a628cce4572 100644 --- a/plugins/package-managers/maven/src/main/kotlin/Maven.kt +++ b/plugins/package-managers/maven/src/main/kotlin/Maven.kt @@ -54,7 +54,7 @@ internal const val PACKAGE_TYPE = "Maven" */ @OrtPlugin( displayName = "Maven", - description = "The Maven package manager for Java.", + summary = "The Maven package manager for Java.", factory = PackageManagerFactory::class ) class Maven(override val descriptor: PluginDescriptor = MavenFactory.descriptor, private val sbtMode: Boolean) : diff --git a/plugins/package-managers/maven/src/main/kotlin/tycho/Tycho.kt b/plugins/package-managers/maven/src/main/kotlin/tycho/Tycho.kt index b017ffdb52457..45cbf9f431804 100644 --- a/plugins/package-managers/maven/src/main/kotlin/tycho/Tycho.kt +++ b/plugins/package-managers/maven/src/main/kotlin/tycho/Tycho.kt @@ -94,7 +94,7 @@ import org.ossreviewtoolkit.utils.ort.createOrtTempFile */ @OrtPlugin( displayName = "Tycho", - description = "The Tycho package manager for Maven projects.", + summary = "The Tycho package manager for Maven projects.", factory = PackageManagerFactory::class ) class Tycho(override val descriptor: PluginDescriptor = TychoFactory.descriptor) : PackageManager("Tycho") { diff --git a/plugins/package-managers/mix/src/main/kotlin/Mix.kt b/plugins/package-managers/mix/src/main/kotlin/Mix.kt index 19ea30de851be..d7b2ab920ff9f 100644 --- a/plugins/package-managers/mix/src/main/kotlin/Mix.kt +++ b/plugins/package-managers/mix/src/main/kotlin/Mix.kt @@ -44,7 +44,7 @@ data class MixConfig( @OrtPlugin( displayName = "Mix", - description = "The Mix package manager for Elixir, using mix_sbom for SBOM generation.", + summary = "The Mix package manager for Elixir, using mix_sbom for SBOM generation.", factory = PackageManagerFactory::class ) class Mix( diff --git a/plugins/package-managers/node/src/main/kotlin/npm/Npm.kt b/plugins/package-managers/node/src/main/kotlin/npm/Npm.kt index f87b1bf98077a..b804f1818ebef 100644 --- a/plugins/package-managers/node/src/main/kotlin/npm/Npm.kt +++ b/plugins/package-managers/node/src/main/kotlin/npm/Npm.kt @@ -97,7 +97,7 @@ data class NpmConfig( @OrtPlugin( id = "NPM", displayName = "NPM", - description = "The Node package manager for Node.js.", + summary = "The Node package manager for Node.js.", factory = PackageManagerFactory::class ) class Npm(override val descriptor: PluginDescriptor = NpmFactory.descriptor, private val config: NpmConfig) : diff --git a/plugins/package-managers/node/src/main/kotlin/pnpm/Pnpm.kt b/plugins/package-managers/node/src/main/kotlin/pnpm/Pnpm.kt index 219c7dd9a91b2..1285fe346730a 100644 --- a/plugins/package-managers/node/src/main/kotlin/pnpm/Pnpm.kt +++ b/plugins/package-managers/node/src/main/kotlin/pnpm/Pnpm.kt @@ -74,7 +74,7 @@ internal object PnpmCommand : CommandLineTool { @OrtPlugin( id = "PNPM", displayName = "PNPM", - description = "The PNPM package manager for Node.js.", + summary = "The PNPM package manager for Node.js.", factory = PackageManagerFactory::class ) class Pnpm(override val descriptor: PluginDescriptor = PnpmFactory.descriptor) : diff --git a/plugins/package-managers/node/src/main/kotlin/yarn/Yarn.kt b/plugins/package-managers/node/src/main/kotlin/yarn/Yarn.kt index 9624a4366f6c3..09f4c9c07d220 100644 --- a/plugins/package-managers/node/src/main/kotlin/yarn/Yarn.kt +++ b/plugins/package-managers/node/src/main/kotlin/yarn/Yarn.kt @@ -83,7 +83,7 @@ internal object YarnCommand : CommandLineTool { */ @OrtPlugin( displayName = "Yarn", - description = "The Yarn package manager for Node.js.", + summary = "The Yarn package manager for Node.js.", factory = PackageManagerFactory::class ) class Yarn(override val descriptor: PluginDescriptor = YarnFactory.descriptor) : diff --git a/plugins/package-managers/node/src/main/kotlin/yarn2/Yarn2.kt b/plugins/package-managers/node/src/main/kotlin/yarn2/Yarn2.kt index b009c904a8de5..5d7ad233235e1 100644 --- a/plugins/package-managers/node/src/main/kotlin/yarn2/Yarn2.kt +++ b/plugins/package-managers/node/src/main/kotlin/yarn2/Yarn2.kt @@ -80,7 +80,7 @@ data class Yarn2Config( */ @OrtPlugin( displayName = "Yarn 2+", - description = "The Yarn 2+ package manager for Node.js.", + summary = "The Yarn 2+ package manager for Node.js.", factory = PackageManagerFactory::class ) class Yarn2(override val descriptor: PluginDescriptor = Yarn2Factory.descriptor, private val config: Yarn2Config) : diff --git a/plugins/package-managers/nuget/src/main/kotlin/NuGet.kt b/plugins/package-managers/nuget/src/main/kotlin/NuGet.kt index 3ec1d097e5cde..95c4958abef91 100644 --- a/plugins/package-managers/nuget/src/main/kotlin/NuGet.kt +++ b/plugins/package-managers/nuget/src/main/kotlin/NuGet.kt @@ -52,7 +52,7 @@ data class NuGetConfig( */ @OrtPlugin( displayName = "NuGet", - description = "The NuGet package manager for .NET.", + summary = "The NuGet package manager for .NET.", factory = PackageManagerFactory::class ) class NuGet(override val descriptor: PluginDescriptor = NuGetFactory.descriptor, config: NuGetConfig) : diff --git a/plugins/package-managers/ort-project-file/src/main/kotlin/OrtProjectFile.kt b/plugins/package-managers/ort-project-file/src/main/kotlin/OrtProjectFile.kt index a46b11606ddcf..4c45cc2e4948f 100644 --- a/plugins/package-managers/ort-project-file/src/main/kotlin/OrtProjectFile.kt +++ b/plugins/package-managers/ort-project-file/src/main/kotlin/OrtProjectFile.kt @@ -30,9 +30,172 @@ import org.ossreviewtoolkit.model.config.Includes import org.ossreviewtoolkit.plugins.api.OrtPlugin import org.ossreviewtoolkit.plugins.api.PluginDescriptor +/** + * The ORT Project package manager can be used to manually define projects in situations like: + * + * * Package manager is not supported by ORT yet. + * * Project is using a custom or in-house package manager. + * * Project has no package manager at all. + * * Project contains additional packages that are not detected by the main package manager. + * + * ### Definition file location, naming and format + * + * #### Location + * + * To use the ORT Project Package Manager, just place the definition file(s) in any directory of your project. + * If you have multiple projects in a mono-repo, it's possible to place multiple definition files in the project + * sub-directories. + * + * #### File naming + * + * The ORT Project definition file must be named, or end with `ortproject.yml`, `ortproject.yaml`, or `ortproject.json`. + * For example, all of the following names are valid: + * + * * `ortproject.yml` + * * `my.ortproject.yaml` + * * `custom-name.ortproject.json` + * + * ### Definition file format + * + * ORT Project package manager uses an ORT Project definition file to define projects and their dependencies. + * Example definition files can be found below: + * + * #### Example files + * + * ~~~yaml + * projectName: "Example ORT project" + * description: "Project description" + * homepageUrl: "https://project.example.com" + * declaredLicenses: + * - "Apache-2.0" + * authors: + * - "John Doe" + * - "Foo Bar" + * dependencies: + * - purl: "pkg:maven/com.example/full@1.1.0" + * description: "Package with fully elaborated model." + * vcs: + * type: "Mercurial" + * url: "https://example.com/hg/full" + * revision: "master" + * path: "/" + * sourceArtifact: + * url: "https://repo.example.com/m2/full-1.1.0-sources.jar" + * hash: + * value: "da39a3ee5e6b4b0d3255bfef95601890afd80709" + * algorithm: "SHA-1" + * declaredLicenses: + * - "Apache-2.0" + * - "MIT" + * homepageUrl: "https://project.example.com/full" + * labels: + * label: "value" + * label2: "value2" + * authors: + * - "Doe John" + * - "Bar Foo" + * scopes: + * - "main" + * - "some_scope" + * linkage: "DYNAMIC" + * isModified: false + * isMetadataOnly: false + * - purl: "pkg:maven/com.example/minimal@0.1.0" + * - id: "Maven:com.example:partial:1.0.1" + * ~~~ + * + * Minimal example file: + * + * ~~~yaml + * dependencies: + * - purl: "pkg:maven/com.example/full@1.1.0" + * ~~~ + * + * #### Definition file schema + * + * ##### Project schema + * + * The ORT Project definition file uses the following schema: + * + * ~~~yaml + * projectName: String (optional) Project name. + * description: String (optional) Project brief description. + * homepageUrl: String (optional) URL to the project homepage. + * # (optional) List of declared licenses for the project. + * declaredLicenses: + * - String list (optional) List of declared licenses in SPDX format (see remarks below). + * # (optional) List of authors of the project. + * authors: + * - String Author name. + * # (optional) List of dependency packages for the project. + * dependencies: + * - Dependency element schema (see below) + * ~~~ + * + * ##### Dependency element schema + * + * Single dependency package schema: + * + * ~~~yaml + * + * purl: String (mandatory at least one of the id or purl) Package URL in purl format (see remarks below). + * id: String (mandatory at least one of the purl or id) Package identifier in the "ORT" format (see remarks below). + * description: String (optional) Package brief description. + * # (optional) Definition of the package's version control system location. + * vcs: + * type: String (mandatory) VCS type, e.g., "Git", "Subversion", "Mercurial". + * url: String (mandatory) VCS repository URL. + * revision: String (mandatory) VCS revision (branch). + * path: String (optional) VCS path within the repository. Default is empty string. + * # (optional) The remote artifact where the source package can be downloaded. + * sourceArtifact: + * url: String (mandatory) URL to the source artifact. + * # (optional) Hash of the source artifact. + * hash: + * value: String (mandatory) hash value. + * algorithm: String (mandatory) hash algorithm. Check remarks below for supported algorithms. + * # (optional) List of declared licenses for the dependency. + * declaredLicenses: + * - String Declared license in SPDX format (see remarks below). + * homepageUrl: String (optional) URL to the package homepage. + * labels: (optional) User defined labels associated with this package. The labels are not interpreted by the core of + * ORT itself, but can be used in parts of ORT such as plugins, in evaluator rules, or in reporter templates. Labels + * are key-value pairs where both the key and value are strings. + * # (optional) List of authors of the dependency. + * authors: + * - String Author name. + * # (optional) List of scopes the package belongs to. + * scopes: + * - String Package's scope. + * linkage: String (optional) linkage type, if set must be either "STATIC" or "DYNAMIC". If not set defaults to + * "DYNAMIC". + * isModified: Boolean (optional) Flag indicating whether the source code of the package has been modified compared to + * the original source code, e.g., in case of a fork of an upstream Open Source project. Default is false. + * isMetadataOnly: Boolean (optional) Flag indicating whether the package is just metadata, like e.g. Maven BOM + * artifacts which only define constraints for dependency versions. Default is false. + * ~~~ + * + * #### Remarks + * + * * Each dependency package must at least define either a `purl` or an `id`. + * * The `purl` field must contain a valid package identifier in + * [PURL format](https://github.com/package-url/purl-spec). + * Only purls starting with `pkg:` are supported. + * Also, `qualifier` and `subpath` components are not supported. + * * The `id` field must contain a valid ORT package identifier in the format: + * `///`. + * * The following hash algorithms are supported in the `sourceArtifact.hash.algorithm` field: + * * `MD5` + * * `SHA-1` + * * `SHA-256` + * * `SHA-384` + * * `SHA-512` + * * `SHA-1-GIT` + * * All license names must be in [SPDX format](https://spdx.org/licenses/). + */ @OrtPlugin( displayName = "ORT Project File", - description = "A package manager that uses an ORT-specific file format as package list source.", + summary = "A package manager that uses an ORT-specific file format as package list source.", factory = PackageManagerFactory::class ) class OrtProjectFile(override val descriptor: PluginDescriptor = OrtProjectFileFactory.descriptor) : diff --git a/plugins/package-managers/pub/src/main/kotlin/Pub.kt b/plugins/package-managers/pub/src/main/kotlin/Pub.kt index 2a9883dd8b028..1f6f1dcf4f13e 100644 --- a/plugins/package-managers/pub/src/main/kotlin/Pub.kt +++ b/plugins/package-managers/pub/src/main/kotlin/Pub.kt @@ -166,7 +166,7 @@ data class PubConfig( */ @OrtPlugin( displayName = "Pub", - description = "The Pub package manager for Dart / Flutter.", + summary = "The Pub package manager for Dart / Flutter.", factory = PackageManagerFactory::class ) @Suppress("TooManyFunctions") diff --git a/plugins/package-managers/python/src/main/kotlin/Pip.kt b/plugins/package-managers/python/src/main/kotlin/Pip.kt index c6a86cb93d6ce..fe3b7821cd974 100644 --- a/plugins/package-managers/python/src/main/kotlin/Pip.kt +++ b/plugins/package-managers/python/src/main/kotlin/Pip.kt @@ -79,7 +79,7 @@ data class PipConfig( @OrtPlugin( id = "PIP", displayName = "PIP", - description = "The PIP package manager for Python.", + summary = "The PIP package manager for Python.", factory = PackageManagerFactory::class ) class Pip internal constructor( diff --git a/plugins/package-managers/python/src/main/kotlin/Pipenv.kt b/plugins/package-managers/python/src/main/kotlin/Pipenv.kt index 54ab4f585e6c8..c21759009c683 100644 --- a/plugins/package-managers/python/src/main/kotlin/Pipenv.kt +++ b/plugins/package-managers/python/src/main/kotlin/Pipenv.kt @@ -58,7 +58,7 @@ internal object PipenvCommand : CommandLineTool { @OrtPlugin( displayName = "Pipenv", - description = "The Pipenv package manager for Python.", + summary = "The Pipenv package manager for Python.", factory = PackageManagerFactory::class ) class Pipenv( diff --git a/plugins/package-managers/python/src/main/kotlin/Poetry.kt b/plugins/package-managers/python/src/main/kotlin/Poetry.kt index 127e31654a42e..f6efe1be0879a 100644 --- a/plugins/package-managers/python/src/main/kotlin/Poetry.kt +++ b/plugins/package-managers/python/src/main/kotlin/Poetry.kt @@ -62,11 +62,11 @@ internal object PoetryCommand : CommandLineTool { } /** - * [Poetry](https://python-poetry.org/) package manager for Python. + * The [Poetry](https://python-poetry.org/) package manager for Python. */ @OrtPlugin( displayName = "Poetry", - description = "The Poetry package manager for Python.", + summary = "The Poetry package manager for Python.", factory = PackageManagerFactory::class ) class Poetry( diff --git a/plugins/package-managers/rebar3/src/main/kotlin/Rebar3.kt b/plugins/package-managers/rebar3/src/main/kotlin/Rebar3.kt index 56dc5fa18550c..b4002bc48a187 100644 --- a/plugins/package-managers/rebar3/src/main/kotlin/Rebar3.kt +++ b/plugins/package-managers/rebar3/src/main/kotlin/Rebar3.kt @@ -38,7 +38,7 @@ private const val PROJECT_TYPE = "otp" @OrtPlugin( displayName = "Rebar3", - description = "The Rebar3 build tool for Erlang, using bombom for SBOM generation.", + summary = "The Rebar3 build tool for Erlang, using bombom for SBOM generation.", factory = PackageManagerFactory::class ) class Rebar3( diff --git a/plugins/package-managers/sbt/src/main/kotlin/Sbt.kt b/plugins/package-managers/sbt/src/main/kotlin/Sbt.kt index 0782810893885..5b9dfa1633d78 100644 --- a/plugins/package-managers/sbt/src/main/kotlin/Sbt.kt +++ b/plugins/package-managers/sbt/src/main/kotlin/Sbt.kt @@ -95,7 +95,7 @@ data class SbtConfig( @OrtPlugin( id = "SBT", displayName = "SBT", - description = "The SBT package manager for Scala.", + summary = "The SBT package manager for Scala.", factory = PackageManagerFactory::class ) class Sbt(override val descriptor: PluginDescriptor = SbtFactory.descriptor, private val config: SbtConfig) : diff --git a/plugins/package-managers/spdx-document-file/src/main/kotlin/SpdxDocumentFile.kt b/plugins/package-managers/spdx-document-file/src/main/kotlin/SpdxDocumentFile.kt index 882bd4a8cc5d7..b1f5b027b9887 100644 --- a/plugins/package-managers/spdx-document-file/src/main/kotlin/SpdxDocumentFile.kt +++ b/plugins/package-managers/spdx-document-file/src/main/kotlin/SpdxDocumentFile.kt @@ -91,7 +91,7 @@ data class SpdxDocumentFileConfig( */ @OrtPlugin( displayName = "SPDX Document File", - description = "A package manager that uses SPDX documents as definition files.", + summary = "A package manager that uses SPDX documents as definition files.", factory = PackageManagerFactory::class ) class SpdxDocumentFile( diff --git a/plugins/package-managers/spdx/src/main/kotlin/Spdx.kt b/plugins/package-managers/spdx/src/main/kotlin/Spdx.kt index aee914afbdd99..2f7253e8fc977 100644 --- a/plugins/package-managers/spdx/src/main/kotlin/Spdx.kt +++ b/plugins/package-managers/spdx/src/main/kotlin/Spdx.kt @@ -70,7 +70,7 @@ private const val PACKAGE_TYPE_SPDX = "SPDX" @OrtPlugin( displayName = "SPDX", - description = "A package manager that uses SPDX version 3 documents as definition files.", + summary = "A package manager that uses SPDX version 3 documents as definition files.", factory = PackageManagerFactory::class ) class Spdx(override val descriptor: PluginDescriptor = SpdxFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/stack/src/main/kotlin/Stack.kt b/plugins/package-managers/stack/src/main/kotlin/Stack.kt index fd71c602359f5..704a12e94bf4d 100644 --- a/plugins/package-managers/stack/src/main/kotlin/Stack.kt +++ b/plugins/package-managers/stack/src/main/kotlin/Stack.kt @@ -85,7 +85,7 @@ internal object StackCommand : CommandLineTool { */ @OrtPlugin( displayName = "Stack", - description = "The Stack package manager for Haskell.", + summary = "The Stack package manager for Haskell.", factory = PackageManagerFactory::class ) class Stack(override val descriptor: PluginDescriptor = StackFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/swiftpm/src/main/kotlin/SwiftPm.kt b/plugins/package-managers/swiftpm/src/main/kotlin/SwiftPm.kt index f72bb4999f2c6..f47558efdd641 100644 --- a/plugins/package-managers/swiftpm/src/main/kotlin/SwiftPm.kt +++ b/plugins/package-managers/swiftpm/src/main/kotlin/SwiftPm.kt @@ -75,7 +75,7 @@ internal object SwiftCommand : CommandLineTool { @OrtPlugin( id = "SwiftPM", displayName = "Swift Package Manager", - description = "The Swift Package Manager for Swift.", + summary = "The Swift Package Manager for Swift.", factory = PackageManagerFactory::class ) class SwiftPm(override val descriptor: PluginDescriptor = SwiftPmFactory.descriptor) : PackageManager(PROJECT_TYPE) { diff --git a/plugins/package-managers/unmanaged/src/main/kotlin/Unmanaged.kt b/plugins/package-managers/unmanaged/src/main/kotlin/Unmanaged.kt index c19ac3011d87d..15030e402c4ff 100644 --- a/plugins/package-managers/unmanaged/src/main/kotlin/Unmanaged.kt +++ b/plugins/package-managers/unmanaged/src/main/kotlin/Unmanaged.kt @@ -47,7 +47,7 @@ private const val PROJECT_TYPE = "Unmanaged" */ @OrtPlugin( displayName = "Unmanaged", - description = "The Unmanaged package manager for projects that do not use any package manager.", + summary = "The Unmanaged package manager for projects that do not use any package manager.", factory = PackageManagerFactory::class ) class Unmanaged( diff --git a/plugins/reporters/aosd/src/main/kotlin/Aosd21Reporter.kt b/plugins/reporters/aosd/src/main/kotlin/Aosd21Reporter.kt index f31c07b75fa5f..69aaaf1a63c00 100644 --- a/plugins/reporters/aosd/src/main/kotlin/Aosd21Reporter.kt +++ b/plugins/reporters/aosd/src/main/kotlin/Aosd21Reporter.kt @@ -39,7 +39,7 @@ import org.ossreviewtoolkit.utils.spdxexpression.nullOrBlankToSpdxNoassertionOrN @OrtPlugin( id = "AOSD2.1", displayName = "Audi Open Source Diagnostics 2.1", - description = "A reporter for the Audi Open Source Diagnostics (AOSD) 2.1 format.", + summary = "A reporter for the Audi Open Source Diagnostics (AOSD) 2.1 format.", factory = ReporterFactory::class ) class Aosd21Reporter(override val descriptor: PluginDescriptor = Aosd21ReporterFactory.descriptor) : Reporter { diff --git a/plugins/reporters/asciidoc/src/main/kotlin/DocBookTemplateReporter.kt b/plugins/reporters/asciidoc/src/main/kotlin/DocBookTemplateReporter.kt index e5d85dd1afb82..01dfaae236f86 100644 --- a/plugins/reporters/asciidoc/src/main/kotlin/DocBookTemplateReporter.kt +++ b/plugins/reporters/asciidoc/src/main/kotlin/DocBookTemplateReporter.kt @@ -25,14 +25,12 @@ import org.ossreviewtoolkit.reporter.Reporter import org.ossreviewtoolkit.reporter.ReporterFactory /** - * A [Reporter] that creates [DocBook][1] files from [Apache Freemarker][2] templates. - * - * [1]: https://docbook.org - * [2]: https://freemarker.apache.org + * A [Reporter] that creates [DocBook](https://docbook.org) files from + * [Apache Freemarker](https://freemarker.apache.org) templates. */ @OrtPlugin( displayName = "DocBook Template", - description = "Generates DocBook from AsciiDoc files from Apache Freemarker templates.", + summary = "Generates DocBook from AsciiDoc files from Apache Freemarker templates.", factory = ReporterFactory::class ) class DocBookTemplateReporter( diff --git a/plugins/reporters/asciidoc/src/main/kotlin/HtmlTemplateReporter.kt b/plugins/reporters/asciidoc/src/main/kotlin/HtmlTemplateReporter.kt index c4ff1a3408679..b1e81363de71a 100644 --- a/plugins/reporters/asciidoc/src/main/kotlin/HtmlTemplateReporter.kt +++ b/plugins/reporters/asciidoc/src/main/kotlin/HtmlTemplateReporter.kt @@ -25,13 +25,11 @@ import org.ossreviewtoolkit.reporter.Reporter import org.ossreviewtoolkit.reporter.ReporterFactory /** - * A [Reporter] that creates HTML files from [Apache Freemarker][1] templates. - * - * [1]: https://freemarker.apache.org + * A [Reporter] that creates HTML files from [Apache Freemarker](https://freemarker.apache.org) templates. */ @OrtPlugin( displayName = "HTML Template", - description = "Generates HTML from AsciiDoc files from Apache Freemarker templates.", + summary = "Generates HTML from AsciiDoc files from Apache Freemarker templates.", factory = ReporterFactory::class ) class HtmlTemplateReporter( diff --git a/plugins/reporters/asciidoc/src/main/kotlin/ManPageTemplateReporter.kt b/plugins/reporters/asciidoc/src/main/kotlin/ManPageTemplateReporter.kt index 2f250ac8fc054..4fca3818e41f0 100644 --- a/plugins/reporters/asciidoc/src/main/kotlin/ManPageTemplateReporter.kt +++ b/plugins/reporters/asciidoc/src/main/kotlin/ManPageTemplateReporter.kt @@ -25,13 +25,11 @@ import org.ossreviewtoolkit.reporter.Reporter import org.ossreviewtoolkit.reporter.ReporterFactory /** - * A [Reporter] that creates man pages from [Apache Freemarker][1] templates. - * - * [1]: https://freemarker.apache.org + * A [Reporter] that creates man pages from [Apache Freemarker](https://freemarker.apache.org) templates. */ @OrtPlugin( displayName = "Man Page Template", - description = "Generates manpages from AsciiDoc files from Apache Freemarker templates.", + summary = "Generates manpages from AsciiDoc files from Apache Freemarker templates.", factory = ReporterFactory::class ) class ManPageTemplateReporter( diff --git a/plugins/reporters/asciidoc/src/main/kotlin/PdfTemplateReporter.kt b/plugins/reporters/asciidoc/src/main/kotlin/PdfTemplateReporter.kt index 90dba63820729..482b46f2245a9 100644 --- a/plugins/reporters/asciidoc/src/main/kotlin/PdfTemplateReporter.kt +++ b/plugins/reporters/asciidoc/src/main/kotlin/PdfTemplateReporter.kt @@ -58,28 +58,23 @@ data class PdfTemplateReporterConfig( ) /** - * A [Reporter] that creates PDF files using a combination of [Apache Freemarker][1] templates and [AsciiDoc][2] - * with [AsciidoctorJ][3] as Java interface and [AsciidoctorJ PDF][4] as PDF file generator. + * A [Reporter] that creates PDF files using a combination of [Apache Freemarker](https://freemarker.apache.org) + * templates and [AsciiDoc](https://asciidoc.org/) with [AsciidoctorJ](https://github.com/asciidoctor/asciidoctorj) as + * Java interface and [AsciidoctorJ PDF](https://github.com/asciidoctor/asciidoctorj-pdf) as PDF file generator. * For each Freemarker template provided using the options described below, a separate intermediate file is created * that can be processed by AsciidoctorJ. If no options are provided, the "disclosure_document" template is used, and if * security vulnerability information is available also the "vulnerability_report" template. * * After the intermediate files are generated, they are processed by AsciidoctorJ PDF. * A PDF theme can be handed over to AsciidoctorJ PDF in which properties like fonts or images displayed in the PDF can - * be adjusted; see the [Theme Guide][5]. + * be adjusted; see the [Theme Guide](https://docs.asciidoctor.org/pdf-converter/latest/theme/). * The path to this theme can be set in the options as described below. * Note that only one theme can be set that is used for all given templates. If no theme is given, a default built-in * theme of AsciidoctorJ PDF is used. - * - * [1]: https://freemarker.apache.org - * [2]: https://asciidoc.org/ - * [3]: https://github.com/asciidoctor/asciidoctorj - * [4]: https://github.com/asciidoctor/asciidoctorj-pdf - * [5]: https://docs.asciidoctor.org/pdf-converter/latest/theme/ */ @OrtPlugin( displayName = "PDF Template", - description = "Generates PDF from AsciiDoc files from Apache Freemarker templates.", + summary = "Generates PDF from AsciiDoc files from Apache Freemarker templates.", factory = ReporterFactory::class ) class PdfTemplateReporter( diff --git a/plugins/reporters/ctrlx/src/main/kotlin/CtrlXAutomationReporter.kt b/plugins/reporters/ctrlx/src/main/kotlin/CtrlXAutomationReporter.kt index 7a38fe262b588..5305c832c1a45 100644 --- a/plugins/reporters/ctrlx/src/main/kotlin/CtrlXAutomationReporter.kt +++ b/plugins/reporters/ctrlx/src/main/kotlin/CtrlXAutomationReporter.kt @@ -46,7 +46,7 @@ data class CtrlXAutomationReporterConfig( @OrtPlugin( displayName = "CtrlX Automation", - description = "A reporter for the ctrlX Automation format.", + summary = "A reporter for the ctrlX Automation format.", factory = ReporterFactory::class ) class CtrlXAutomationReporter( diff --git a/plugins/reporters/cyclonedx/src/main/kotlin/CycloneDxReporter.kt b/plugins/reporters/cyclonedx/src/main/kotlin/CycloneDxReporter.kt index 45172ba0ccce5..28ef101ec4dd7 100644 --- a/plugins/reporters/cyclonedx/src/main/kotlin/CycloneDxReporter.kt +++ b/plugins/reporters/cyclonedx/src/main/kotlin/CycloneDxReporter.kt @@ -122,7 +122,7 @@ data class CycloneDxReporterConfig( @OrtPlugin( id = "CycloneDX", displayName = "CycloneDX SBOM", - description = "Creates software bills of materials (SBOM) in the CycloneDX format.", + summary = "Creates software bills of materials (SBOM) in the CycloneDX format.", factory = ReporterFactory::class ) class CycloneDxReporter( diff --git a/plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModelReporter.kt b/plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModelReporter.kt index a4882a72594d1..7b8d8cd31b503 100644 --- a/plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModelReporter.kt +++ b/plugins/reporters/evaluated-model/src/main/kotlin/EvaluatedModelReporter.kt @@ -61,7 +61,7 @@ data class EvaluatedModelReporterConfig( */ @OrtPlugin( displayName = "Evaluated Model", - description = "Generates an evaluated model of the ORT result.", + summary = "Generates an evaluated model of the ORT result.", factory = ReporterFactory::class ) class EvaluatedModelReporter( diff --git a/plugins/reporters/fossid/src/main/kotlin/FossIdReporter.kt b/plugins/reporters/fossid/src/main/kotlin/FossIdReporter.kt index 6caecc9a12dcb..75bed9ea35fb9 100644 --- a/plugins/reporters/fossid/src/main/kotlin/FossIdReporter.kt +++ b/plugins/reporters/fossid/src/main/kotlin/FossIdReporter.kt @@ -75,7 +75,7 @@ data class FossIdReporterConfig( @OrtPlugin( id = "FossID", displayName = "FossID", - description = "Export reports from FossID.", + summary = "Export reports from FossID.", factory = ReporterFactory::class ) class FossIdReporter( diff --git a/plugins/reporters/fossid/src/main/kotlin/FossIdSnippetReporter.kt b/plugins/reporters/fossid/src/main/kotlin/FossIdSnippetReporter.kt index 412fe18ec20d5..8623ad7be1cb8 100644 --- a/plugins/reporters/fossid/src/main/kotlin/FossIdSnippetReporter.kt +++ b/plugins/reporters/fossid/src/main/kotlin/FossIdSnippetReporter.kt @@ -31,7 +31,7 @@ import org.ossreviewtoolkit.reporter.ReporterInput @OrtPlugin( displayName = "FossID Snippet", - description = "Generates a detailed report of the FossID snippet findings.", + summary = "Generates a detailed report of the FossID snippet findings.", factory = ReporterFactory::class ) class FossIdSnippetReporter(override val descriptor: PluginDescriptor = FossIdSnippetReporterFactory.descriptor) : diff --git a/plugins/reporters/freemarker/src/main/kotlin/PlainTextTemplateReporter.kt b/plugins/reporters/freemarker/src/main/kotlin/PlainTextTemplateReporter.kt index c76a60133ce1f..afbbccd8c99f4 100644 --- a/plugins/reporters/freemarker/src/main/kotlin/PlainTextTemplateReporter.kt +++ b/plugins/reporters/freemarker/src/main/kotlin/PlainTextTemplateReporter.kt @@ -52,16 +52,15 @@ data class PlainTextTemplateReporterConfig( } /** - * A [Reporter] that creates plain text files using [Apache Freemarker][1] templates. For each template provided in the - * [config], a separate output file is created. If no templates are provided, the "NOTICE_DEFAULT" template is used. + * A [Reporter] that creates plain text files using [Apache Freemarker](https://freemarker.apache.org) templates. For + * each template provided in the [config], a separate output file is created. If no templates are provided, the + * "NOTICE_DEFAULT" template is used. * The name of the template id or template path (without extension) is used for the generated file, so be careful to not * use two different templates with the same name. - * - * [1]: https://freemarker.apache.org */ @OrtPlugin( displayName = "Plain Text Template", - description = "Generates plain text files using Apache Freemarker templates.", + summary = "Generates plain text files using Apache Freemarker templates.", factory = ReporterFactory::class ) class PlainTextTemplateReporter( diff --git a/plugins/reporters/opossum/src/main/kotlin/OpossumReporter.kt b/plugins/reporters/opossum/src/main/kotlin/OpossumReporter.kt index 453f5b9d89089..c30d3bb22f99d 100644 --- a/plugins/reporters/opossum/src/main/kotlin/OpossumReporter.kt +++ b/plugins/reporters/opossum/src/main/kotlin/OpossumReporter.kt @@ -84,7 +84,7 @@ data class OpossumReporterConfig( */ @OrtPlugin( displayName = "Opossum", - description = "Generates a report in the Opossum format.", + summary = "Generates a report in the Opossum format.", factory = ReporterFactory::class ) class OpossumReporter( diff --git a/plugins/reporters/spdx/src/main/kotlin/SpdxDocumentReporter.kt b/plugins/reporters/spdx/src/main/kotlin/SpdxDocumentReporter.kt index 2b2d432476736..843532023cfd1 100644 --- a/plugins/reporters/spdx/src/main/kotlin/SpdxDocumentReporter.kt +++ b/plugins/reporters/spdx/src/main/kotlin/SpdxDocumentReporter.kt @@ -109,7 +109,7 @@ data class SpdxDocumentReporterConfig( */ @OrtPlugin( displayName = "SPDX", - description = "Creates software bills of materials (SBOM) in the SPDX format.", + summary = "Creates software bills of materials (SBOM) in the SPDX format.", factory = ReporterFactory::class ) class SpdxDocumentReporter( diff --git a/plugins/reporters/static-html/src/main/kotlin/StaticHtmlReporter.kt b/plugins/reporters/static-html/src/main/kotlin/StaticHtmlReporter.kt index 1c0ef5c2f6124..0c8336b2c1b1d 100644 --- a/plugins/reporters/static-html/src/main/kotlin/StaticHtmlReporter.kt +++ b/plugins/reporters/static-html/src/main/kotlin/StaticHtmlReporter.kt @@ -67,7 +67,7 @@ private const val RULE_VIOLATION_TABLE_ID = "rule-violation-summary" @OrtPlugin( id = "StaticHTML", displayName = "Static HTML", - description = "Generates a static HTML report.", + summary = "Generates a static HTML report.", factory = ReporterFactory::class ) class StaticHtmlReporter(override val descriptor: PluginDescriptor = StaticHtmlReporterFactory.descriptor) : Reporter { diff --git a/plugins/reporters/trustsource/src/main/kotlin/TrustSourceReporter.kt b/plugins/reporters/trustsource/src/main/kotlin/TrustSourceReporter.kt index b34ba02f340dc..381e6ae08e5cf 100644 --- a/plugins/reporters/trustsource/src/main/kotlin/TrustSourceReporter.kt +++ b/plugins/reporters/trustsource/src/main/kotlin/TrustSourceReporter.kt @@ -35,7 +35,7 @@ import org.ossreviewtoolkit.utils.common.div @OrtPlugin( displayName = "TrustSource", - description = "Generates a report in the TrustSource format.", + summary = "Generates a report in the TrustSource format.", factory = ReporterFactory::class ) class TrustSourceReporter(override val descriptor: PluginDescriptor = TrustSourceReporterFactory.descriptor) : diff --git a/plugins/reporters/web-app/src/main/kotlin/WebAppReporter.kt b/plugins/reporters/web-app/src/main/kotlin/WebAppReporter.kt index a1ff177e707de..af44f907952a6 100644 --- a/plugins/reporters/web-app/src/main/kotlin/WebAppReporter.kt +++ b/plugins/reporters/web-app/src/main/kotlin/WebAppReporter.kt @@ -53,7 +53,7 @@ data class WebAppReporterConfig( */ @OrtPlugin( displayName = "WebApp", - description = "Generates a web application to browse an ORT result interactively.", + summary = "Generates a web application to browse an ORT result interactively.", factory = ReporterFactory::class ) class WebAppReporter( diff --git a/plugins/scanners/askalono/src/main/kotlin/Askalono.kt b/plugins/scanners/askalono/src/main/kotlin/Askalono.kt index 4a29950fc42f6..023f0243065fe 100644 --- a/plugins/scanners/askalono/src/main/kotlin/Askalono.kt +++ b/plugins/scanners/askalono/src/main/kotlin/Askalono.kt @@ -56,7 +56,7 @@ internal object AskalonoCommand : CommandLineTool { @OrtPlugin( displayName = "askalono", - description = "askalono is a library and command-line tool to help detect license texts. It's designed to be " + + summary = "askalono is a library and command-line tool to help detect license texts. It's designed to be " + "fast, accurate, and to support a wide variety of license texts.", factory = ScannerWrapperFactory::class ) diff --git a/plugins/scanners/dos/src/main/kotlin/DosScanner.kt b/plugins/scanners/dos/src/main/kotlin/DosScanner.kt index c2975226bcf8a..e09550d638bcd 100644 --- a/plugins/scanners/dos/src/main/kotlin/DosScanner.kt +++ b/plugins/scanners/dos/src/main/kotlin/DosScanner.kt @@ -59,16 +59,14 @@ import org.ossreviewtoolkit.utils.ort.createOrtTempDir import org.ossreviewtoolkit.utils.ort.runBlocking /** - * The DOS scanner wrapper is a client for the scanner API implemented as part of the Double Open Server project at - * https://github.com/doubleopen-project/dos. The server runs ScanCode in the backend and stores / reuses scan results - * on a per-file basis and thus uses its own scan storage. + * The DOS scanner wrapper is a client for the scanner API implemented as part of the + * [Double Open Server](https://github.com/doubleopen-project/dos). The server runs ScanCode in the backend and stores / + * reuses scan results on a per-file basis and thus uses its own scan storage. */ @OrtPlugin( id = "DOS", displayName = "Double Open Server", - description = "The DOS scanner wrapper is a client for the scanner API implemented as part of the Double Open " + - "Server project at https://github.com/doubleopen-project/dos. The server runs ScanCode in the backend and " + - "stores / reuses scan results on a per-file basis and thus uses its own scan storage.", + summary = "A wrapper for the [Double Open Server](https://github.com/doubleopen-project/dos).", factory = ScannerWrapperFactory::class ) class DosScanner( diff --git a/plugins/scanners/fossid/src/main/kotlin/FossId.kt b/plugins/scanners/fossid/src/main/kotlin/FossId.kt index e55fb0c7045ae..2e71edb0f6ee8 100644 --- a/plugins/scanners/fossid/src/main/kotlin/FossId.kt +++ b/plugins/scanners/fossid/src/main/kotlin/FossId.kt @@ -109,7 +109,7 @@ import org.semver4j.Semver */ @OrtPlugin( displayName = "FossID", - description = "The FossID scanner plugin.", + summary = "The FossID scanner plugin.", factory = ScannerWrapperFactory::class ) @Suppress("LargeClass", "TooManyFunctions") diff --git a/plugins/scanners/licensee/src/main/kotlin/Licensee.kt b/plugins/scanners/licensee/src/main/kotlin/Licensee.kt index 1aafa8b925220..1cfa31c8b220c 100644 --- a/plugins/scanners/licensee/src/main/kotlin/Licensee.kt +++ b/plugins/scanners/licensee/src/main/kotlin/Licensee.kt @@ -62,7 +62,7 @@ internal object LicenseeCommand : CommandLineTool { @OrtPlugin( displayName = "Licensee", - description = "Licensee is a command line tool to detect licenses in a given project.", + summary = "Licensee is a command line tool to detect licenses in a given project.", factory = ScannerWrapperFactory::class ) class Licensee( diff --git a/plugins/scanners/scancode/src/main/kotlin/Provenant.kt b/plugins/scanners/scancode/src/main/kotlin/Provenant.kt index c6458da9e3e63..d29bfa44f693b 100644 --- a/plugins/scanners/scancode/src/main/kotlin/Provenant.kt +++ b/plugins/scanners/scancode/src/main/kotlin/Provenant.kt @@ -54,7 +54,7 @@ internal object ProvenantCommand : CommandLineTool { */ @OrtPlugin( displayName = "Provenant", - description = "A wrapper for [Provenant](https://github.com/mstykow/provenant).", + summary = "A wrapper for [Provenant](https://github.com/mstykow/provenant).", factory = ScannerWrapperFactory::class ) class Provenant( diff --git a/plugins/scanners/scancode/src/main/kotlin/ScanCode.kt b/plugins/scanners/scancode/src/main/kotlin/ScanCode.kt index cb428934b84b2..42a654a171787 100644 --- a/plugins/scanners/scancode/src/main/kotlin/ScanCode.kt +++ b/plugins/scanners/scancode/src/main/kotlin/ScanCode.kt @@ -74,7 +74,7 @@ internal object ScanCodeCommand : CommandLineTool { */ @OrtPlugin( displayName = "ScanCode", - description = "A wrapper for [ScanCode](https://github.com/aboutcode-org/scancode-toolkit).", + summary = "A wrapper for [ScanCode](https://github.com/aboutcode-org/scancode-toolkit).", factory = ScannerWrapperFactory::class ) open class ScanCode( diff --git a/plugins/scanners/scanoss/src/main/kotlin/ScanOss.kt b/plugins/scanners/scanoss/src/main/kotlin/ScanOss.kt index 6ad031695b99a..9199386f37aa7 100644 --- a/plugins/scanners/scanoss/src/main/kotlin/ScanOss.kt +++ b/plugins/scanners/scanoss/src/main/kotlin/ScanOss.kt @@ -50,7 +50,7 @@ import org.ossreviewtoolkit.scanner.ScannerWrapperFactory @OrtPlugin( id = "SCANOSS", displayName = "SCANOSS", - description = "A wrapper for the SCANOSS snippet scanner.", + summary = "A wrapper for the SCANOSS snippet scanner.", factory = ScannerWrapperFactory::class ) class ScanOss( diff --git a/plugins/version-control-systems/git/src/main/kotlin/Git.kt b/plugins/version-control-systems/git/src/main/kotlin/Git.kt index 5f78bce93a78a..81a6b846a1b63 100644 --- a/plugins/version-control-systems/git/src/main/kotlin/Git.kt +++ b/plugins/version-control-systems/git/src/main/kotlin/Git.kt @@ -90,7 +90,7 @@ private val SHA1_REGEX = Regex("^[0-9a-fA-F]{40}$") */ @OrtPlugin( displayName = "Git", - description = "A VCS implementation to interact with Git repositories.", + summary = "A VCS implementation to interact with Git repositories.", factory = VersionControlSystemFactory::class ) class Git( diff --git a/plugins/version-control-systems/git/src/main/kotlin/GitRepo.kt b/plugins/version-control-systems/git/src/main/kotlin/GitRepo.kt index e2487bb2bd928..b2b59ab14a1e5 100644 --- a/plugins/version-control-systems/git/src/main/kotlin/GitRepo.kt +++ b/plugins/version-control-systems/git/src/main/kotlin/GitRepo.kt @@ -88,7 +88,7 @@ internal object GitRepoCommand : CommandLineTool { @OrtPlugin( displayName = "Git-Repo", - description = "A VCS implementation to interact with Git-Repo repositories.", + summary = "A VCS implementation to interact with Git-Repo repositories.", factory = VersionControlSystemFactory::class ) class GitRepo( diff --git a/plugins/version-control-systems/mercurial/src/main/kotlin/Mercurial.kt b/plugins/version-control-systems/mercurial/src/main/kotlin/Mercurial.kt index c469dc41e68fc..17535410f880c 100644 --- a/plugins/version-control-systems/mercurial/src/main/kotlin/Mercurial.kt +++ b/plugins/version-control-systems/mercurial/src/main/kotlin/Mercurial.kt @@ -52,7 +52,7 @@ internal fun MercurialWorkingTree.runHg(vararg args: String) = @OrtPlugin( displayName = "Mercurial", - description = "A VCS implementation to interact with Mercurial repositories.", + summary = "A VCS implementation to interact with Mercurial repositories.", factory = VersionControlSystemFactory::class ) class Mercurial(override val descriptor: PluginDescriptor = MercurialFactory.descriptor) : VersionControlSystem() { diff --git a/plugins/version-control-systems/subversion/src/main/kotlin/Subversion.kt b/plugins/version-control-systems/subversion/src/main/kotlin/Subversion.kt index d52e475e48ee6..66edc523bebf2 100644 --- a/plugins/version-control-systems/subversion/src/main/kotlin/Subversion.kt +++ b/plugins/version-control-systems/subversion/src/main/kotlin/Subversion.kt @@ -58,7 +58,7 @@ import org.tmatesoft.svn.util.Version @OrtPlugin( displayName = "Subversion", - description = "A VCS implementation to interact with Subversion repositories.", + summary = "A VCS implementation to interact with Subversion repositories.", factory = VersionControlSystemFactory::class ) class Subversion(override val descriptor: PluginDescriptor = SubversionFactory.descriptor) : VersionControlSystem() { diff --git a/scanner/src/testFixtures/kotlin/DummyPathScannerWrapper.kt b/scanner/src/testFixtures/kotlin/DummyPathScannerWrapper.kt index 84c79518c6d63..7e6a9bdfa7ae0 100644 --- a/scanner/src/testFixtures/kotlin/DummyPathScannerWrapper.kt +++ b/scanner/src/testFixtures/kotlin/DummyPathScannerWrapper.kt @@ -29,7 +29,7 @@ import org.ossreviewtoolkit.utils.common.VCS_DIRECTORIES import org.ossreviewtoolkit.utils.spdx.SpdxConstants class DummyPathScannerWrapper(id: String = "Dummy") : PathScannerWrapper { - override val descriptor = PluginDescriptor(id = id, displayName = id, description = "") + override val descriptor = PluginDescriptor(id = id, displayName = id, summary = "") override val version = "1.0.0" override val configuration = "" diff --git a/scanner/src/testFixtures/kotlin/FakePackageScannerWrapper.kt b/scanner/src/testFixtures/kotlin/FakePackageScannerWrapper.kt index f8f4eafb66eb4..bacf6751980b5 100644 --- a/scanner/src/testFixtures/kotlin/FakePackageScannerWrapper.kt +++ b/scanner/src/testFixtures/kotlin/FakePackageScannerWrapper.kt @@ -29,7 +29,7 @@ import org.ossreviewtoolkit.scanner.provenance.NestedProvenance */ @Suppress("RedundantNullableReturnType") class FakePackageScannerWrapper(id: String = "fake") : PackageScannerWrapper { - override val descriptor = PluginDescriptor(id = id, displayName = id, description = "") + override val descriptor = PluginDescriptor(id = id, displayName = id, summary = "") override val version = "1.0.0" override val configuration = "config" diff --git a/scanner/src/testFixtures/kotlin/FakePathScannerWrapper.kt b/scanner/src/testFixtures/kotlin/FakePathScannerWrapper.kt index d056914f3864f..fb8bfc06463db 100644 --- a/scanner/src/testFixtures/kotlin/FakePathScannerWrapper.kt +++ b/scanner/src/testFixtures/kotlin/FakePathScannerWrapper.kt @@ -30,7 +30,7 @@ import org.ossreviewtoolkit.plugins.api.PluginDescriptor * An implementation of [PathScannerWrapper] that creates scan results with one license finding for each file. */ class FakePathScannerWrapper : PathScannerWrapper { - override val descriptor = PluginDescriptor(id = "fake", displayName = "fake", description = "") + override val descriptor = PluginDescriptor(id = "fake", displayName = "fake", summary = "") override val version = "1.0.0" override val configuration = "config" diff --git a/scanner/src/testFixtures/kotlin/FakeProvenanceScannerWrapper.kt b/scanner/src/testFixtures/kotlin/FakeProvenanceScannerWrapper.kt index 65ebeabba9da0..4b1681dc2684f 100644 --- a/scanner/src/testFixtures/kotlin/FakeProvenanceScannerWrapper.kt +++ b/scanner/src/testFixtures/kotlin/FakeProvenanceScannerWrapper.kt @@ -27,7 +27,7 @@ import org.ossreviewtoolkit.plugins.api.PluginDescriptor * An implementation of [ProvenanceScannerWrapper] that creates empty scan results. */ class FakeProvenanceScannerWrapper : ProvenanceScannerWrapper { - override val descriptor = PluginDescriptor(id = "fake", displayName = "fake", description = "") + override val descriptor = PluginDescriptor(id = "fake", displayName = "fake", summary = "") override val version = "1.0.0" override val configuration = "config" diff --git a/utils/cyclonedx/src/test/kotlin/CycloneDxPackageManagerTest.kt b/utils/cyclonedx/src/test/kotlin/CycloneDxPackageManagerTest.kt index 8d1c7c4b5e129..701d1b2961666 100644 --- a/utils/cyclonedx/src/test/kotlin/CycloneDxPackageManagerTest.kt +++ b/utils/cyclonedx/src/test/kotlin/CycloneDxPackageManagerTest.kt @@ -47,7 +47,7 @@ private class TestCycloneDxPackageManager : CycloneDxPackageManager("TestCyclone override val descriptor = PluginDescriptor( id = "TestCycloneDX", displayName = "Test CycloneDX", - description = "Test implementation of CycloneDX package manager" + summary = "Test implementation of CycloneDX package manager" ) override val globsForDefinitionFiles = listOf("bom.cdx.json") diff --git a/website/docs/guides/ort-project-package-manager.md b/website/docs/guides/ort-project-package-manager.md deleted file mode 100644 index 4cd407de5b5d3..0000000000000 --- a/website/docs/guides/ort-project-package-manager.md +++ /dev/null @@ -1,161 +0,0 @@ -# Ort Project Package Manager - -The ORT Project package manager can be used to manually define projects in situations like: - -* Package manager is not supported by ORT yet. -* Project is using a custom or in-house package manager. -* Project has no package manager at all. -* Project contains additional packages that are not detected by the main package manager. - -## Definition file location, naming and format - -### Location - -To use the ORT Project Package Manager, just place the definition file(s) in any directory of your project. -If you have multiple projects in a mono-repo, it's possible to place multiple definition files in the project -sub-directories. - -### File naming - -The ORT Project definition file must be named, or end with `ortproject.yml`, `ortproject.yaml`, or `ortproject.json`. -For example, all of the following names are valid: - -* `ortproject.yml` -* `my.ortproject.yaml` -* `custom-name.ortproject.json` - -## Definition file format - -ORT Project package manager uses an ORT Project definition file to define projects and their dependencies. -Example definition files can be found below: - -### Example files - -~~~yaml -projectName: "Example ORT project" -description: "Project description" -homepageUrl: "https://project.example.com" -declaredLicenses: - - "Apache-2.0" -authors: - - "John Doe" - - "Foo Bar" -dependencies: - - purl: "pkg:maven/com.example/full@1.1.0" - description: "Package with fully elaborated model." - vcs: - type: "Mercurial" - url: "https://example.com/hg/full" - revision: "master" - path: "/" - sourceArtifact: - url: "https://repo.example.com/m2/full-1.1.0-sources.jar" - hash: - value: "da39a3ee5e6b4b0d3255bfef95601890afd80709" - algorithm: "SHA-1" - declaredLicenses: - - "Apache-2.0" - - "MIT" - homepageUrl: "https://project.example.com/full" - labels: - label: "value" - label2: "value2" - authors: - - "Doe John" - - "Bar Foo" - scopes: - - "main" - - "some_scope" - linkage: "DYNAMIC" - isModified: false - isMetadataOnly: false - - purl: "pkg:maven/com.example/minimal@0.1.0" - - id: "Maven:com.example:partial:1.0.1" -~~~ - -Minimal example file: - -~~~yaml -dependencies: - - purl: "pkg:maven/com.example/full@1.1.0" -~~~ - -### Definition file schema - -#### Project schema - -The ORT Project definition file uses the following schema: - -~~~yaml -projectName: String (optional) Project name. -description: String (optional) Project brief description. -homepageUrl: String (optional) URL to the project homepage. -# (optional) List of declared licenses for the project. -declaredLicenses: - - String list (optional) List of declared licenses in SPDX format (see remarks below). -# (optional) List of authors of the project. -authors: - - String Author name. -# (optional) List of dependency packages for the project. -dependencies: - - Dependency element schema (see below) -~~~ - -#### Dependency element schema - -Single dependency package schema: - -~~~yaml - -purl: String (mandatory at least one of the id or purl) Package URL in purl format (see remarks below). -id: String (mandatory at least one of the purl or id) Package identifier in the "ORT" format (see remarks below). -description: String (optional) Package brief description. -# (optional) Definition of the package's version control system location. -vcs: - type: String (mandatory) VCS type, e.g., "Git", "Subversion", "Mercurial". - url: String (mandatory) VCS repository URL. - revision: String (mandatory) VCS revision (branch). - path: String (optional) VCS path within the repository. Default is empty string. -# (optional) The remote artifact where the source package can be downloaded. -sourceArtifact: - url: String (mandatory) URL to the source artifact. - # (optional) Hash of the source artifact. - hash: - value: String (mandatory) hash value. - algorithm: String (mandatory) hash algorithm. Check remarks below for supported algorithms. -# (optional) List of declared licenses for the dependency. -declaredLicenses: - - String Declared license in SPDX format (see remarks below). -homepageUrl: String (optional) URL to the package homepage. -labels: (optional) User defined labels associated with this package. The labels are not interpreted by the core of ORT - itself, but can be used in parts of ORT such as plugins, in evaluator rules, or in reporter templates. Labels are key-value - pairs where both the key and value are strings. -# (optional) List of authors of the dependency. -authors: - - String Author name. -# (optional) List of scopes the package belongs to. -scopes: - - String Package's scope. -linkage: String (optional) linkage type, if set must be either "STATIC" or "DYNAMIC". If not set defaults to "DYNAMIC". -isModified: Boolean (optional) Flag indicating whether the source code of the package has been modified compared to - the original source code, e.g., in case of a fork of an upstream Open Source project. Default is false. -isMetadataOnly: Boolean (optional) Flag indicating whether the package is just metadata, like e.g. Maven BOM artifacts - which only define constraints for dependency versions. Default is false. -~~~ - -### Remarks - -* Each dependency package must at least define either a `purl` or an `id`. -* The `purl` field must contain a valid package identifier in [PURL format](https://github.com/package-url/purl-spec). - Only purls starting with `pkg:` are supported. - Also, `qualifier` and `subpath` components are not supported. -* The `id` field must contain a valid ORT package identifier in the format: - `///`. -* The following hash algorithms are supported in the `sourceArtifact.hash.algorithm` field: - * `MD5` - * `SHA-1` - * `SHA-256` - * `SHA-384` - * `SHA-512` - * `SHA-1-GIT` -* All license names must be in [SPDX format](https://spdx.org/licenses/). diff --git a/website/docs/tools/analyzer.md b/website/docs/tools/analyzer.md index 4ef350572ff90..4e965c9f09a2e 100644 --- a/website/docs/tools/analyzer.md +++ b/website/docs/tools/analyzer.md @@ -72,8 +72,8 @@ the generic fallbacks can be used: ### ORT Project package manager -The [ORT Project package manager](../guides/ort-project-package-manager.md) can be used to manually define projects and -their dependencies in an ORT Project definition file. +The [ORT Project package manager](../plugins/package-managers/ORT%20Project%20File.md) can be used to manually define +projects and their dependencies in an ORT Project definition file. ### SPDX