Plugin SDK API Reference
Complete reference for the Karandash Plugin SDK interfaces and types. Use these interfaces to create custom rule validators, reporters, and providers.
Package: io.karandash.sdk (interfaces), io.karandash.models (data types)
Dependency:
// build.gradle.kts
dependencies {
implementation("ru.kode.karandash:sdk:<version>")
}
Core Interfaces
Module
Base interface for all plugin modules. Every plugin must implement this interface (typically through RuleModule, ReporterModule, or by implementing Module directly for provider modules).
Package: io.karandash.sdk
interface Module {
val id: String
val name: String
val version: String
val type: ModuleType
val description: String get() = name
val dslName: String get() = id
val configKey: String get() = dslName
suspend fun initialize(context: PluginContext): Boolean
suspend fun shutdown() {}
fun defaultConfig(): JsonElement = JsonObject(emptyMap())
fun configSchema(): List<ConfigProperty> = emptyList()
}
| Member | Type | Description |
|---|---|---|
id |
String |
Unique module identifier (e.g., "my-rules") |
name |
String |
Human-readable display name |
version |
String |
Semantic version string (e.g., "1.0.0") |
type |
ModuleType |
Module category: RULE, REPORTER, PLATFORM_SERVICE, etc. |
description |
String |
One-line human-readable description. Defaults to name. |
dslName |
String |
DSL block name in .karandash.kts (camelCase). Defaults to id. |
configKey |
String |
YAML/JSON config key (kebab-case). Defaults to dslName. |
initialize(context) |
Boolean |
Called once at startup (suspend). Return true if initialization succeeded. |
shutdown() |
Unit |
Called on cleanup (suspend). Override to release resources. Default is no-op. |
defaultConfig() |
JsonElement |
Returns the module's default configuration. Default is empty JsonObject. |
configSchema() |
List<ConfigProperty> |
Declares accepted config properties for LSP and docs. |
RuleModule
Interface for modules that contribute validation rules.
Package: io.karandash.sdk
interface RuleModule : Module {
override val type: ModuleType get() = ModuleType.RULE
fun contributedRules(): Set<String>
fun ruleExplanation(ruleId: String): String? = null
suspend fun validate(ruleId: String, mr: MergeRequest, configElement: JsonElement): List<Finding>
}
| Member | Return Type | Description |
|---|---|---|
type |
ModuleType |
Always ModuleType.RULE |
contributedRules() |
Set<String> |
Returns the set of rule IDs this module provides (e.g., setOf("titleFormat", "myCustomRule")) |
defaultEnabled (from Module) |
Boolean |
Whether this rule is enabled without explicit config. Default false - rules require explicit listing in config or a profile to activate. Only the zero-config profile (MinimalProfileModule) selectively enables rules. |
ruleExplanation(ruleId) |
String? |
Human-readable explanation for --explain mode. |
validate(ruleId, mr, configElement) |
List<Finding> |
Validate the given MR for the specified rule. Returns a list of findings (empty list means the rule passed). |
Parameters for validate:
| Parameter | Type | Description |
|---|---|---|
ruleId |
String |
The rule being evaluated (from contributedRules()) |
mr |
MergeRequest |
The merge request data to validate |
configElement |
JsonElement |
Plugin-specific configuration as a JSON element from the config file |
Example implementation:
class MyRuleModule : RuleModule {
override val id = "my-rules"
override val name = "My Custom Rules"
override val version = "1.0.0"
override suspend fun initialize(context: PluginContext): Boolean {
context.log("MyRuleModule initialized")
return true
}
override fun contributedRules(): Set<String> = setOf("maxTitleLength")
override suspend fun validate(
ruleId: String,
mr: MergeRequest,
configElement: JsonElement
): List<Finding> {
val config = configElement as? JsonObject ?: JsonObject(emptyMap())
return when (ruleId) {
"maxTitleLength" -> {
val maxLen = (config["maxLength"] as? JsonPrimitive)?.content?.toIntOrNull() ?: 100
if (mr.title.length > maxLen) {
listOf(Finding(
severity = Severity.ERROR,
message = "Title exceeds $maxLen characters",
rule = "maxTitleLength"
))
} else emptyList()
}
else -> emptyList()
}
}
}
ReporterModule
Interface for modules that output validation results in custom formats.
Package: io.karandash.sdk
interface ReporterModule : Module {
override val type: ModuleType get() = ModuleType.REPORTER
val formatId: String
val requiresPlatformContext: Boolean get() = false
suspend fun report(findings: List<Finding>, passed: Boolean, config: JsonElement): String?
}
| Member | Type | Description |
|---|---|---|
type |
ModuleType |
Always ModuleType.REPORTER |
formatId |
String |
Format identifier (e.g., "json", "webhook", "slack") |
defaultEnabled (from Module) |
Boolean |
Whether this reporter is active by default. |
requiresPlatformContext |
Boolean |
Whether this reporter needs platform context (platform, project, MR id). Default false. |
report(findings, passed, config) |
String? |
Format and output findings. Return a string for file-based output, or null for side-effect reporters (e.g., webhook). |
Parameters for report:
| Parameter | Type | Description |
|---|---|---|
findings |
List<Finding> |
All validation findings |
passed |
Boolean |
Whether validation passed overall |
config |
JsonElement |
Reporter-specific configuration as a JSON element |
Example implementation:
class WebhookReporter : ReporterModule {
override val id = "webhook-reporter"
override val name = "Webhook Reporter"
override val version = "1.0.0"
override val formatId = "webhook"
override suspend fun initialize(context: PluginContext): Boolean = true
override suspend fun report(
findings: List<Finding>,
passed: Boolean,
config: JsonElement
): String? {
val configObj = config as? JsonObject ?: return null
val url = (configObj["webhookUrl"] as? JsonPrimitive)?.contentOrNull ?: return null
// Send HTTP POST to webhook URL...
return null // Side-effect reporter, no file output
}
}
PluginContext
Execution context provided to plugins during initialization.
Package: io.karandash.sdk
interface PluginContext {
val pluginConfig: JsonElement
fun log(message: String)
fun warn(message: String)
fun env(name: String): String?
val hostVersion: String
val workingDirectory: String
val allowLocalhost: Boolean get() = false
}
| Member | Type | Description |
|---|---|---|
pluginConfig |
JsonElement |
Plugin-specific configuration as a JSON element from the config file |
log(message) |
Unit |
Log an informational message |
warn(message) |
Unit |
Log a warning message |
env(name) |
String? |
Read an environment variable by name |
hostVersion |
String |
Karandash host version (e.g., "0.1.0") |
workingDirectory |
String |
Current working directory path |
ModuleType
Enum classifying plugin module types.
Package: io.karandash.sdk
enum class ModuleType {
RULE,
REPORTER,
PLATFORM_SERVICE,
ENRICHMENT_PROVIDER,
PIPELINE_EXTENSION,
// ... and additional types for AI, CLI, config format, etc.
}
| Value | Description |
|---|---|
RULE |
Validation rule module |
REPORTER |
Output reporter module |
PLATFORM_SERVICE |
Unified platform integration (fetch MR, post comments, mutate state) |
ENRICHMENT_PROVIDER |
Data enrichment provider |
PIPELINE_EXTENSION |
Pre/post validation hooks |
Data Models
MergeRequest
Core data model representing a merge/pull request.
Package: io.karandash.models
data class MergeRequest(
val id: String,
val iid: Int,
val title: String,
val description: String?,
val sourceBranch: String,
val targetBranch: String,
val author: User,
val state: String,
val draft: Boolean,
val labels: List<String>,
val commits: List<Commit>,
val changes: List<FileChange>,
val approvals: List<Approval> = emptyList(),
val reviewers: List<User> = emptyList()
)
| Field | Type | Description |
|---|---|---|
id |
String |
Unique global identifier |
iid |
Int |
Internal (project-scoped) ID |
title |
String |
MR/PR title |
description |
String? |
MR/PR description body (nullable) |
sourceBranch |
String |
Source branch name |
targetBranch |
String |
Target branch name |
author |
User |
MR/PR author |
state |
String |
Current state (e.g., "opened", "merged") |
draft |
Boolean |
Whether the MR is a draft/WIP |
labels |
List<String> |
Applied labels |
commits |
List<Commit> |
Commits in the MR |
changes |
List<FileChange> |
Files changed in the MR |
approvals |
List<Approval> |
Approvals received |
reviewers |
List<User> |
Assigned reviewers |
Finding
A single validation result produced by a rule.
Package: io.karandash.models
data class Finding(
val severity: Severity,
val message: String,
val rule: String,
val location: Location? = null,
val suggestion: String? = null,
val explanation: String? = null,
val metadata: Map<String, String> = emptyMap(),
val fixSuggestions: List<FixSuggestion> = emptyList(),
)
| Field | Type | Description |
|---|---|---|
severity |
Severity |
Finding severity: ERROR, WARNING, or INFO |
message |
String |
Human-readable finding message |
rule |
String |
Rule ID that produced the finding |
location |
Location? |
Optional file/line location |
suggestion |
String? |
Short actionable hint shown to the MR author inline (in comments and console output) |
explanation |
String? |
Longer explanation of why the rule exists (shown with --explain) |
metadata |
Map<String, String> |
Arbitrary key-value metadata |
fixSuggestions |
List<FixSuggestion> |
Structured fix suggestions for auto-fixer (see FixSuggestion) |
Built-in rules populate suggestion and explanation from the suggestion and explanation fields in the rule's config block. Custom plugins can set these fields directly when constructing Finding objects.
message holds the problem only; suggestion holds the imperative fix. Pattern-based rules can add a structured fix
hint through well-known metadata keys, which every reporter renders under the labels Where, How to fix and
Format:
Key (WellKnownMetadataKeys) |
Value | Accessor |
|---|---|---|
EXPECTED_FORMAT (expectedFormat) |
Required format as Pomsky source | Finding.expectedFormat(): String? |
MISMATCH (mismatch) |
JSON {"value","position","expected","group"?} |
Finding.mismatch(): Mismatch?, write with Mismatch.toMetadataValue() |
FORMAT_EXPLAIN (formatExplain) |
Plain-text explanation of the format | - |
FORMAT_DIAGRAM (formatDiagram) |
ASCII diagram of the format | - |
Finding.fixHintLines(language) returns the labelled plain-text lines; FIX_HINT_METADATA_KEYS lists the four keys so
text reporters can leave them out of a generic metadata dump.
Rules that produce auto-fixable findings should include structured fixSuggestions so the auto-fixer can apply fixes generically without parsing message text.
Example:
Finding(
severity = Severity.ERROR,
message = "Missing required label: 'bug'",
rule = "labels",
suggestion = "Add the required label via the MR sidebar.",
explanation = "Labels help categorize and route MRs through review workflows.",
fixSuggestions = listOf(FixSuggestion.AddLabel("bug")),
)
FixSuggestion
Structured fix suggestion emitted by rules alongside findings. The auto-fixer processes these generically without inspecting rule IDs or message text.
Package: io.karandash.models
sealed class FixSuggestion {
data class AddLabel(val label: String) : FixSuggestion()
data class RemoveLabel(val label: String) : FixSuggestion()
data class SetDraft(val draft: Boolean) : FixSuggestion()
data class SetTitle(val title: String) : FixSuggestion()
data class SetDescription(val description: String) : FixSuggestion()
}
| Subtype | Fields | Description |
|---|---|---|
AddLabel |
label: String |
Add a label to the merge request |
RemoveLabel |
label: String |
Remove a label from the merge request |
SetDraft |
draft: Boolean |
Set or unset draft/WIP status |
SetTitle |
title: String |
Update the merge request title |
SetDescription |
description: String |
Update the merge request description |
Severity
Finding severity levels.
Package: io.karandash.models
enum class Severity {
ERROR,
WARNING,
INFO
}
| Value | Effect | Description |
|---|---|---|
ERROR |
Exit code 1 |
Rule violation. Blocks merge. |
WARNING |
Exit code 5 (strict only) |
Advisory. Blocks only with --strict. |
INFO |
No effect | Informational. Never affects exit code. |
Location
Optional source location for a finding. Implemented as a sealed class with two variants.
Package: io.karandash.models
sealed class Location {
data class FileRef(
val path: String,
val line: Int? = null
) : Location()
data class CommitRef(
val sha: String
) : Location()
}
| Subtype | Fields | Description |
|---|---|---|
FileRef |
path: String, line: Int? |
A location within a source file, optionally at a specific line |
CommitRef |
sha: String |
A reference to a specific commit by its SHA hash |
User
Represents a user (author, reviewer, approver).
Package: io.karandash.models
data class User(
val username: String,
val name: String,
val email: String? = null
)
| Field | Type | Description |
|---|---|---|
username |
String |
Platform username/handle |
name |
String |
Display name |
email |
String? |
Email address (nullable) |
Commit
A single commit in the MR.
Package: io.karandash.models
data class Commit(
val sha: String,
val message: String,
val author: CommitAuthor,
val timestamp: String
)
| Field | Type | Description |
|---|---|---|
sha |
String |
Commit SHA hash |
message |
String |
Full commit message |
author |
CommitAuthor |
Commit author info |
timestamp |
String |
Commit timestamp (ISO 8601) |
CommitAuthor
data class CommitAuthor(
val name: String,
val email: String
)
FileChange
A single file change in the MR.
Package: io.karandash.models
data class FileChange(
val path: String,
val changeType: ChangeType,
val additions: Int = 0,
val deletions: Int = 0,
val diffContent: String? = null
)
| Field | Type | Description |
|---|---|---|
path |
String |
File path relative to repository root |
changeType |
ChangeType |
Type of change |
additions |
Int |
Number of added lines |
deletions |
Int |
Number of deleted lines |
diffContent |
String? |
Raw diff content (nullable) |
ChangeType
enum class ChangeType {
ADDED,
MODIFIED,
DELETED,
RENAMED
}
Approval
A single approval on the MR.
Package: io.karandash.models
data class Approval(
val user: User,
val approvedAt: String? = null
)
| Field | Type | Description |
|---|---|---|
user |
User |
The approving user |
approvedAt |
String? |
ISO 8601 timestamp of approval |
Provider Interfaces
MergeRequestProvider
Interface for fetching MR data from platform APIs.
Package: io.karandash.providers
interface MergeRequestProvider {
fun fetchMergeRequest(projectId: String, mrId: String): MergeRequest
fun fetchMergeRequestByUrl(url: String): MergeRequest
fun close() {}
}
| Method | Description |
|---|---|
fetchMergeRequest(projectId, mrId) |
Fetch MR by project ID and MR ID |
fetchMergeRequestByUrl(url) |
Fetch MR by its full URL |
close() |
Release resources (HTTP clients, connections). Default is no-op. |
MergeRequestMutator
Interface for providers that support modifying MR properties. Used by the --fix flag.
Package: io.karandash.providers
interface MergeRequestMutator {
fun addLabels(projectId: String, mrId: String, labels: List<String>)
fun removeLabels(projectId: String, mrId: String, labels: List<String>)
fun setDraft(projectId: String, mrId: String, draft: Boolean)
fun updateTitle(projectId: String, mrId: String, title: String)
fun updateDescription(projectId: String, mrId: String, description: String)
}
| Method | Description |
|---|---|
addLabels(projectId, mrId, labels) |
Add labels to a MR |
removeLabels(projectId, mrId, labels) |
Remove labels from a MR |
setDraft(projectId, mrId, draft) |
Set draft status of a MR |
updateTitle(projectId, mrId, title) |
Update the title of a MR |
updateDescription(projectId, mrId, description) |
Update the description body of a MR |
CommentPoster
Interface for posting and managing MR comments.
Package: io.karandash.providers
interface CommentPoster {
fun postComment(projectId: String, mrId: String, body: String): String
fun updateComment(projectId: String, mrId: String, commentId: String, body: String)
fun findExistingComment(projectId: String, mrId: String, marker: String): String?
}
| Method | Return | Description |
|---|---|---|
postComment(projectId, mrId, body) |
String |
Post a comment. Returns the comment ID. |
updateComment(projectId, mrId, commentId, body) |
Unit |
Update an existing comment. |
findExistingComment(projectId, mrId, marker) |
String? |
Find a comment containing a marker string. Returns comment ID or null. |
Validator
Internal interface for built-in validators.
Package: io.karandash.validators
interface Validator {
fun validate(mr: MergeRequest): List<Finding>
}
Plugin authors typically implement RuleModule rather than Validator directly.
Plugin Registration
Plugins are discovered via Java ServiceLoader. Create the service declaration file:
File: src/main/resources/META-INF/services/io.karandash.sdk.Module
com.example.MyRuleModule
Each line is a fully-qualified class name implementing Module (or a sub-interface like RuleModule).
See Also
- Configuration Schema -- plugin configuration options
- CLI Reference --
plugin createandgeneratecommands - Error Codes -- exit codes for plugin errors