aalekh-model/com.aalekh.aalekh.model

Package-level declarations

The full serializable model: ModuleDependencyGraph, ModuleNode, DependencyEdge, ModuleType, Severity, and Violation, together with the richer analysis carriers (ArchitectureSnapshot, MainSequence, AffectedModules, BuildInventory, CycleBreakSuggestion, CustomMetric) and the Provenance marker (OBSERVED / COMPUTED / INFERRED / SUGGESTED) that records whether a value was declared, derived, or guessed. AalekhBuildConfig exposes the build-stamped VERSION.

Types

AalekhBuildConfig

object AalekhBuildConfig

AffectedModules

data class AffectedModules(val totalModules: Int, val changed: List<String> = emptyList(), val affected: List<String> = emptyList())

The modules impacted by a set of changed files - the affected graph of a diff.

ArchitectureDiff

data class ArchitectureDiff(val addedModules: List<String> = emptyList(), val removedModules: List<String> = emptyList(), val addedEdges: List<String> = emptyList(), val removedEdges: List<String> = emptyList(), val newCycles: List<String> = emptyList(), val resolvedCycles: List<String> = emptyList(), val layerChanges: Map<String, LayerChange> = emptyMap(), val metricDeltas: Map<String, MetricDelta> = emptyMap())

What changed between two snapshots of an architecture.

ArchitectureSnapshot

data class ArchitectureSnapshot(val modules: List<String> = emptyList(), val edges: List<String> = emptyList(), val cycles: List<String> = emptyList(), val entryPoints: List<String> = emptyList(), val layers: Map<String, String> = emptyMap(), val metrics: MetricSnapshot = MetricSnapshot(), val aalekhVersion: String = "")

A compact, committable record of a project's architecture at one point in time.

data class BuildInventory(val modules: List<ModuleBuildInfo> = emptyList(), val catalogs: List<VersionCatalog> = emptyList(), val toolVersions: Map<String, String> = emptyMap(), val codeowners: Map<String, List<String>> = emptyMap(), val declaredMetadata: Map<String, ModuleMetadata> = emptyMap())

Everything Aalekh knows about how the project is built, as opposed to how it is wired together.

data class CatalogEntry(val alias: String, val coordinates: String, val version: String? = null)

A version-catalog entry: an alias, what it points at, and the version it resolves to.

data class CoChange(val moduleA: String, val moduleB: String, val sharedCommits: Int, val degree: Double, val declared: Boolean)

Two modules that changed together (co-changed) across the analysed commit window.

enum Confidence : Enum<Confidence>

How much Aalekh trusts an Provenance.INFERRED or Provenance.SUGGESTED finding.

data class CustomMetric(val providerId: String, val displayName: String, val description: String = "", val unit: String = "", val systemValue: Double? = null, val moduleValues: Map<String, Double> = emptyMap())

One metric contributed by a third-party MetricProvider (the metrics extension point of the Aalekh SPI). A metric can be system-wide (systemValue), per-module (moduleValues), or both - a provider populates whichever dimensions make sense for it.

CustomMetricReport

data class CustomMetricReport(val metrics: List<CustomMetric> = emptyList(), val providerFailures: List<String> = emptyList())

The result of running every discovered MetricProvider against the graph.

CycleBreakSuggestion

data class CycleBreakSuggestion(val from: String, val to: String, val configuration: String, val buildFilePath: String? = null, val declarationLine: Int? = null, val cycleSize: Int)

A concrete, actionable suggestion for breaking a dependency cycle: the single edge to remove.

DeclaredEdgeRef

data class DeclaredEdgeRef(val from: String, val to: String)

A declared production dependency edge, referenced by its endpoints.

data class DependencyEdge(val from: String, val to: String, val configuration: String, val sourceSet: String? = null, val declarationLine: Int? = null, val reason: String? = null, val adrUrl: String? = null)

A directed dependency from one module to another.

data class Evidence(val label: String, val value: String, val howObtained: Provenance)

One piece of the reasoning behind a Finding - the "how do you know?" a reader can check.

ExternalDependency

data class ExternalDependency(val module: String, val group: String, val name: String, val version: String? = null, val configuration: String, val sourceSet: String? = null)

A declared external (third-party) dependency of a single module.

data class Finding(val id: String, val category: FindingCategory, val severity: Severity, val title: String, val detail: String, val evidence: List<Evidence> = emptyList(), val subjects: List<String> = emptyList(), val provenance: Provenance = Provenance.COMPUTED, val confidence: Confidence? = null, val action: String? = null)

One human-readable statement about the project - the unit every narrative, recommendation, and generated document is rendered from.

FindingCategory

enum FindingCategory : Enum<FindingCategory>

What a Finding is about - used to group the narrative into readable sections.

data class LayerChange(val before: String? = null, val after: String? = null)

A module's move between declared layers. null means it belonged to no layer at that point.

MainSequenceReport

data class MainSequenceReport(val modules: List<ModuleMainSequence>, val averageDistance: Double)

The main-sequence report for a whole project.

MainSequenceZone

enum MainSequenceZone : Enum<MainSequenceZone>

Where a module sits relative to Robert Martin's main sequence - the line A + I = 1 that balances abstractness against instability.

data class MetricDelta(val before: Double, val after: Double, val isWorse: Boolean)

A structural metric's movement between two snapshots.

data class MetricSnapshot(val cycleCount: Int = 0, val godModuleCount: Int = 0, val ccd: Long = 0, val tanglePercent: Double = 0.0, val averageInstability: Double = 0.0, val criticalPathLength: Int = 0)

A snapshot of the structural metrics that quality gates ratchet on.

ModuleBuildInfo

data class ModuleBuildInfo(val path: String, val plugins: List<ModulePlugin> = emptyList(), val javaToolchain: String? = null, val kmpTargets: List<String> = emptyList(), val testSourceSets: List<String> = emptyList())

Per-module build configuration that is not a dependency.

data class ModuleChurn(val module: String, val commits: Int)

How often a single module changed across the analysed commit window.

ModuleDependencyGraph

data class ModuleDependencyGraph(val projectName: String, val modules: List<ModuleNode>, val edges: List<DependencyEdge>, val externalDependencies: List<ExternalDependency> = emptyList(), val buildInventory: BuildInventory = BuildInventory.EMPTY, val metadata: Map<String, String> = emptyMap())

The complete module dependency graph for a Gradle project.

ModuleMainSequence

data class ModuleMainSequence(val path: String, val instability: Double, val abstractness: Double, val distance: Double, val zone: MainSequenceZone, val abstractTypes: Int, val concreteTypes: Int)

The main-sequence position of one module.

data class ModuleMetadata(val path: String, val purpose: String? = null, val owner: String? = null, val layer: String? = null, val status: String? = null, val links: Map<String, String> = emptyMap())

Metadata a team declares about a module, in a committed .aalekh/modules.json.

data class ModuleNode(val path: String, val name: String, val type: ModuleType, val plugins: Set<String> = emptySet(), val tags: Set<String> = emptySet(), val sourceSets: Set<String> = emptySet(), val buildFilePath: String? = null, val healthScore: Int? = null)

A single Gradle subproject in the dependency graph.

data class ModulePlugin(val id: String, val version: String? = null, val alias: String? = null, val source: PluginSource = PluginSource.BUILD_SCRIPT)

One Gradle plugin as applied to one module.

enum ModuleType : Enum<ModuleType>

The type of Gradle module, inferred from its applied plugin IDs.

NarrativeReport

data class NarrativeReport(val findings: List<Finding> = emptyList(), val readingOrder: List<ReadingStep> = emptyList(), val summary: String = "")

The full set of findings for one project, in reading order.

enum PluginSource : Enum<PluginSource>

How a plugin application was discovered.

enum Provenance : Enum<Provenance>

How Aalekh came to know a value - the accuracy contract attached to everything it reports.

data class ReadingStep(val position: Int, val module: String, val reason: String)

One step of the suggested reading order for a project a developer has never seen.

enum Severity : Enum<Severity>

TemporalCouplingReport

data class TemporalCouplingReport(val commitsAnalyzed: Int, val churn: List<ModuleChurn> = emptyList(), val coChanges: List<CoChange> = emptyList(), val hiddenCoupling: List<CoChange> = emptyList(), val deadStructure: List<DeclaredEdgeRef> = emptyList())

The result of a git temporal-coupling analysis over a window of recent commits.

data class VersionCatalog(val name: String, val plugins: List<CatalogEntry> = emptyList(), val libraries: List<CatalogEntry> = emptyList())

The version catalogs declared for the build.

data class Violation(val ruleId: String, val severity: Severity, val message: String, val source: String, val moduleHint: String? = null, val plainLanguageExplanation: String? = null)

A single architecture rule violation produced by the rule engine.