feat(analyzer): Add initial analyzer models

Signed-off-by: Helio Chissini de Castro <heliocastro@gmail.com>

Author: heliocastro

src/ort/models/analyzer_result.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from _pytest.python import Package
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.dependency_graph import DependencyGraph
+from ort.models.identifier import Identifier
+from ort.models.issue import Issue
+from ort.models.project import Project
+
+
+class AnalyzerResult(BaseModel):
+    """
+    A class that merges all information from individual [ProjectAnalyzerResult]s created for each found definition file.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    projects: set[Project] = Field(
+        description="Sorted set of the projects, as they appear in the individual analyzer results.",
+    )
+    packages: set[Package] = Field(
+        description="The set of identified packages for all projects.",
+    )
+    issues: dict[Identifier, list[Issue]] = Field(
+        description="The lists of Issue objects that occurred within the analyzed projects themselves. Issues related"
+        "to project dependencies are contained in the dependencies of the project's scopes. This property is not"
+        "serialized if the map is empty to reduce the size of the result file.",
+    )
+    dependency_graphs: dict[str, DependencyGraph] = Field(
+        description="A map with DependencyGraph objects keyed by the name of the package manager that created this"
+        "graph. Package managers supporting this feature can construct a shared DependencyGraph over all projects and"
+        "store it in this map.",
+    )

src/ort/models/analyzer_run.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.analyzer_result import AnalyzerResult
+from ort.models.config.analyzer_configuration import AnalyzerConfiguration
+from ort.utils.environment import Environment
+
+
+class AnalyzerRun(BaseModel):
+    """
+    The summary of a single run of the analyzer.
+
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    start_time: datetime = Field(
+        description="The time the analyzer was started.",
+    )
+    end_time: datetime = Field(
+        description="The time the analyzer has finished.",
+    )
+    environment: Environment = Field(
+        description="The [Environment] in which the analyzer was executed.",
+    )
+    config: AnalyzerConfiguration = Field(
+        description="The [AnalyzerConfiguration] used for this run.",
+    )
+    result: AnalyzerResult | None = Field(
+        default=None,
+        description="The result of this run.",
+    )

src/ort/models/config/analyzer_configuration.py

@@ -38,11 +38,9 @@
 
 class AnalyzerConfiguration(BaseModel):
     """
-    Enable the analysis of projects that use version ranges to declare their dependencies. If set to true,
-    dependencies of exactly the same project might change with another scan done at a later time if any of the
-    (transitive) dependencies are declared using version ranges and a new version of such a dependency was
-    published in the meantime. If set to false, analysis of projects that use version ranges will fail. Defaults to
-    false.
+    The configuration model of the analyzer. This class is (de-)serialized in the following places:
+    - Deserialized from "config.yml" as part of [OrtConfiguration] (via Hoplite).
+    - (De-)Serialized as part of [org.ossreviewtoolkit.model.OrtResult] (via Jackson).
     """
 
     model_config = ConfigDict(

src/ort/models/dependency_graph.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.dependency_graph_edge import DependencyGraphEdge
+from ort.models.dependency_graph_node import DependencyGraphNode
+from ort.models.dependency_reference import DependencyReference
+from ort.models.identifier import Identifier
+from ort.models.root_dependency_index import RootDependencyIndex
+
+
+class DependencyGraph(BaseModel):
+    """
+    Represents the graph of dependencies of a project.
+
+    This class holds information about a project's scopes and their dependencies in a format that minimizes the
+    consumption of memory. In projects with many scopes there is often a high degree of duplication in the dependencies
+    of the scopes. To avoid this, this class aims to share as many parts of the dependency graph as possible between
+    the different scopes. Ideally, there is only a single dependency graph containing the dependencies used by all
+    scopes. This is not always possible due to inconsistencies in dependency relations, like a package using different
+    dependencies in different scopes. Then the dependency graph is split into multiple fragments, and each fragment has
+    a consistent view on the dependencies it contains.
+
+    When constructing a dependency graph the dependencies are organized as a connected structure of DependencyReference
+    objects in memory. Originally, the serialization format of a graph was based on this structure, but that turned out
+    to be not ideal: During serialization, sub graphs referenced from multiple nodes (e.g. libraries with transitive
+    dependencies referenced from multiple projects) get duplicated, which can cause a significant amount of redundancy.
+    Therefore, the data representation has been changed again to a form, which can be serialized without introducing
+    redundancy. It consists of the following elements:
+
+    - packages: A list with the coordinates of all the packages (free of duplication) that are referenced by the graph.
+      This allows extracting the packages directly, but also has the advantage that the package coordinates do not have
+      to be repeated over and over: All the references to packages are expressed by indices into this list.
+    - nodes: An ordered list with the nodes of the dependency graph. A single node represents a package, and therefore
+      has a reference into the list with package coordinates. It can, however, happen that packages occur multiple
+      times in the graph if they are in different subtrees with different sets of transitive dependencies. Then there
+      are multiple nodes for the packages affected, and a fragment_index is used to identify them uniquely. Nodes also
+      store information about issues of a package and their linkage.
+    - edges: Here the structure of the graph comes in. Each edge connects two nodes and represents a directed
+      depends-on relationship. The nodes are referenced by numeric indices into the list of nodes.
+    - scopes: This is a map that associates the scopes used by projects with their direct dependencies. A single
+      dependency graph contains the dependencies of all the projects processed by a specific package manager.
+      Therefore, the keys of this map are scope names qualified by the coordinates of a project; which makes them
+      unique. The values are references to the nodes in the graph that correspond to the packages the scopes depend on
+      directly.
+
+    To navigate this structure, start with a scope and gather the references to its direct dependency nodes. Then, by
+    following the edges starting from these nodes, the set of transitive dependencies can be determined. The numeric
+    indices can be resolved via the packages list.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    packages: list[Identifier] = Field(
+        ...,
+        description="A list with the identifiers of the packages that appear in the dependency graph. This list is "
+        "used to resolve the numeric indices contained in the dependency_graph_node objects.",
+    )
+
+    scope_roots: set[DependencyReference] = Field(
+        ...,
+        description="Stores the dependency graph as a list of root nodes for the direct dependencies referenced by "
+        "scopes. Starting with these nodes, the whole graph can be traversed. The nodes are constructed "
+        "from the direct dependencies declared by scopes that cannot be reached via other paths in the "
+        "dependency graph. Note that this property exists for backwards compatibility only; it is replaced "
+        "by the lists of nodes and edges.",
+    )
+
+    scopes: dict[str, list[RootDependencyIndex]] = Field(
+        ...,
+        description="A mapping from scope names to the direct dependencies of the scopes. Based on this information, "
+        "the set of scopes of a project can be constructed from the serialized form.",
+    )
+
+    nodes: list[DependencyGraphNode] = Field(
+        ...,
+        description="A list with the nodes of this dependency graph. Nodes correspond to packages, but in contrast to "
+        "the packages list, there can be multiple nodes for a single package. The order of nodes in this "
+        "list is relevant; the edges of the graph reference their nodes by numeric indices.",
+    )
+
+    edges: set[DependencyGraphEdge] = Field(
+        ...,
+        description="A set with the edges of this dependency graph. By traversing the edges, the dependencies of "
+        "packages can be determined.",
+    )

src/ort/models/dependency_graph_edge.py

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DependencyGraphEdge(BaseModel):
+    """
+    A data class representing an edge in the dependency graph.
+
+    An edge corresponds to a directed depends-on relationship between two packages. The packages are identified by the
+    numeric indices into the list of nodes.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    from_: int = Field(
+        ...,
+        alias="from",
+        description="The index of the source node of this edge.",
+    )
+    to_: int = Field(
+        ...,
+        alias="to",
+        description="The index of the destination node of this edge.",
+    )

src/ort/models/dependency_graph_node.py

@@ -0,0 +1,44 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.issue import Issue
+from ort.models.package_linkage import PackageLinkage
+
+
+class DependencyGraphNode(BaseModel):
+    """
+    A data class representing a node in the dependency graph.
+
+    A node corresponds to a package, which is referenced by a numeric index. A package may, however, occur multiple
+    times in the dependency graph with different transitive dependencies. In this case, different fragment indices are
+    used to distinguish between these occurrences.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    pkg: int = Field(
+        ...,
+        description="Stores the numeric index of the package dependency referenced by this object. The package behind "
+        "this index can be resolved by evaluating the list of identifiers stored in DependencyGraph at "
+        "this index.",
+    )
+    fragment: int = Field(
+        0,
+        description="Stores the index of the fragment in the dependency graph where the referenced dependency is "
+        "contained. This is needed to uniquely identify the target if the dependency occurs multiple times "
+        "in the graph.",
+    )
+    linkage: PackageLinkage = Field(
+        default=PackageLinkage.DYNAMIC,
+        description="The type of linkage used for the referred package from its dependent package. As most of ORT's "
+        "supported package managers / languages only support dynamic linking or at least default to it, "
+        "also use that as the default value here to not blow up ORT result files.",
+    )
+    issues: list[Issue] = Field(
+        default_factory=list, description="A list of Issue objects that occurred handling this dependency."
+    )

src/ort/models/dependency_reference.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.models.issue import Issue
+from ort.models.package_linkage import PackageLinkage
+
+
+class DependencyReference(BaseModel):
+    """
+    A class to model a tree-like structure to represent the dependencies of a project.
+
+    Instances of this class are used to store the relations between dependencies in fragments of dependency trees in an
+    Analyzer result. The main purpose of this class is to define an efficient serialization format, which avoids
+    redundancy as far as possible. Therefore, dependencies are represented by numeric indices into an external table.
+    As a dependency can occur multiple times in the dependency graph with different transitive dependencies, the class
+    defines another index to distinguish these cases.
+
+    Note: This is by intention no data class. Equality is tested via references and not via the values contained.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    pkg: int = Field(
+        ...,
+        description="Stores the numeric index of the package dependency referenced by this object. The package behind "
+        "this index can be resolved by evaluating the list of identifiers stored in DependencyGraph at "
+        "this index.",
+    )
+    fragment: int = Field(
+        default=0,
+        description="Stores the index of the fragment in the dependency graph where the referenced dependency is "
+        "contained. This is needed to uniquely identify the target if the dependency occurs multiple times "
+        "in the graph.",
+    )
+    dependencies: set["DependencyReference"] = Field(
+        default_factory=set,
+        description="A set with the references to the dependencies of this dependency. That way a tree-like structure "
+        "is established.",
+    )
+    linkage: PackageLinkage = Field(
+        default=PackageLinkage.DYNAMIC,
+        description="The type of linkage used for the referred package from its dependent package. As most of ORT's "
+        "supported package managers / languages only support dynamic linking or at least default to it, "
+        "also use that as the default value here to not blow up ORT result files.",
+    )
+    issues: list[Issue] = Field(..., description="A list of Issue objects that occurred handling this dependency.")

src/ort/models/issue.py

@@ -0,0 +1,36 @@
+# SPDX-FileCopyrightText: 2025 Helio Chissini de Castro <heliocastro@gmail.com>
+# SPDX-License-Identifier: MIT
+
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ort.severity import Severity
+
+
+class Issue(BaseModel):
+    """
+    An issue that occurred while executing ORT.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+
+    timestamp: datetime = Field(
+        description="The timestamp of the issue.",
+    )
+    source: str = Field(
+        description="A description of the issue source, e.g. the tool that caused the issue.",
+    )
+    message: str = Field(
+        description="The issue's message.",
+    )
+    severity: Severity = Field(
+        description="The issue's severity.",
+    )
+    affected_path: str | None = Field(
+        default=None,
+        description="The affected file or directory the issue is limited to, if any.",
+    )