Skip to content

Glossary

Karandash uses specific terminology for its plugin architecture and configuration system. This glossary clarifies key terms and resolves ambiguities between code and configuration terminology.


Core Concepts

Plugin

In code: The base interface for all Karandash extensions (io.karandash.sdk.Plugin).

Umbrella term: Any component that extends Karandash functionality, including: - Structured modules (rules, reporters, providers) - Script-based plugins (JavaScript .mjs via QuickJS, available on JVM and Native) - WebAssembly plugins (.wasm via Chicory on JVM and Chasm on Native) - Native plugins (.dylib/.so/.dll via dlopen/JNA) - Other extension types

In config: The plugins: block is reserved for external third-party plugins only. Built-in plugins use domain-specific blocks (rules:, platforms:, reporters:).

Example:

plugins:
  - id: "com.example.custom-validator"
    version: "1.0.0"

See also: Module, plugins/sdk/src/commonMain/kotlin/io/karandash/sdk/Plugin.kt


Module

In code: A structured plugin with lifecycle management (io.karandash.sdk.Module).

Definition: A specialized Plugin that implements: - Type system: Categorized as rule, reporter, platform-service, enrichment-provider, etc. - Lifecycle: initialize() and shutdown() callbacks - Configuration: Declares schema via configSchema(), provides defaults via defaultConfig() - Self-description: Metadata for tooling (description, DSL name, config key)

Types of modules: - RuleModule - Validators - FormatModule - Output formatters - OutputModule - Output delivery - PlatformServiceModule - Platform integrations (fetch MR, post comments, apply mutations)

Why "Module" not "Plugin"? The name distinguishes structured plugins (with lifecycle and type system) from other plugin types like JavaScript scripts (QuickJS), WebAssembly modules (Chicory/Chasm), and native shared libraries.

NOT related to Gradle modules: This term refers to runtime plugin components, not build system subprojects (:plugins:modules:rules:title-format).

See also: Plugin, plugins/sdk/src/commonMain/kotlin/io/karandash/sdk/Module.kt


RuleModule

Interface: io.karandash.sdk.RuleModule extends Module

Purpose: Validates merge requests and returns validation findings.

Config block: rules:

Example:

rules:
  title-format:
    pattern: "^(feat|fix|chore):"
    max-length: 120

Built-in rule modules: - title-format - Title format validation - commit-messages - Commit message validation - jira-ticket - JIRA ticket reference validation - branch-naming - Branch naming conventions - file-changes - File change restrictions - codeowners - CODEOWNERS coverage - approval - Approval requirements - reviewer - Reviewer assignment - cicd-status - CI/CD pipeline status - conflict - Merge conflict detection - draft - Draft/WIP detection - labels - Label requirements - size-limits - MR size limits - security - Security pattern detection - ai - AI-powered validation rules - jira - Jira ticket validation and enrichment - description-format - MR description format validation - cross-entity-consistency - Cross-entity consistency checks - context-tag - Context tag validation - language-policy - Language policy enforcement


Policy

Config block: policies: (top-level array, parsed by PolicyConfigParser into PolicyConfig)

Purpose: Applies conditional changes to already-configured modules. Each policy carries a when: condition expression evaluated against the merge request; when it matches, the policy can toggle the modules listed in modules: (enabled:), deep-merge per-module config from override:, override finding severity:, and gate the autoApprove / autoFix / scripts / dangerfile stages. Policies never add rules - they modify rules that already exist in rules:.

There is no conditional module: policy evaluation happens in the config pipeline, not in a plugin. A single rule can also carry an inline when: block for a condition that concerns only that rule.

Example:

policies:
  - when: 'target_branch_matches("^main$")'
    modules: [approval]
    override:
      approval:
        minApprovals: 2

See Conditional Rules (Policies).


FormatModule

Interface: io.karandash.sdk.FormatModule extends Module

Purpose: Transforms validation findings into a specific output format.

Built-in format modules: - ConsoleFormatModule (console) - Human-readable ANSI terminal text - MarkdownFormatModule (markdown) - Markdown tables and sections - JsonReportFormatModule (json) - JSON document - SarifFormatModule (sarif) - SARIF 2.1.0 - HtmlFormatModule (html) - Standalone HTML report - JunitFormatModule (junit) - JUnit XML - RdjsonFormatModule (rdjson) - Reviewdog rdjson - RdjsonlFormatModule (rdjsonl) - Reviewdog rdjsonl (line-delimited, no envelope) - SlackFormatModule (slack) - Slack Block Kit JSON


OutputModule

Interface: io.karandash.sdk.OutputModule extends Module

Purpose: Delivers formatted output to a destination.

Built-in output modules: - StdoutOutputModule - Standard output (default) - FilesystemOutputModule - Local file (via --output flag) - PlatformOutputModule - MR/PR comment via platform API - WebhookOutputModule - HTTP POST to any endpoint - EmailOutputModule - SMTP email delivery - SlackOutputModule - Slack Incoming Webhook


Reporter

User-facing concept: The combination of a FormatModule and an OutputModule. Configured via the reporters: block.

Config block: reporters:

Example:

reporters:
  console: true       # ConsoleFormatModule + StdoutOutputModule
  markdown: true      # MarkdownFormatModule + PlatformOutputModule (auto on CI)
  sarif: true         # SarifFormatModule + StdoutOutputModule

Built-in reporters and their composition:

Config key FormatModule OutputModule
console ConsoleFormatModule StdoutOutputModule
markdown MarkdownFormatModule PlatformOutputModule / FilesystemOutputModule
json JsonReportFormatModule StdoutOutputModule / FilesystemOutputModule
sarif SarifFormatModule StdoutOutputModule / FilesystemOutputModule
html HtmlFormatModule FilesystemOutputModule
junit JunitFormatModule FilesystemOutputModule
reviewdog RdjsonFormatModule StdoutOutputModule / FilesystemOutputModule
slack SlackFormatModule SlackOutputModule
webhook JsonReportFormatModule WebhookOutputModule
email HtmlFormatModule EmailOutputModule

See also: Reporters documentation


PlatformServiceModule

Interface: io.karandash.sdk.PlatformServiceModule extends Module

Purpose: Unified platform integration: fetches merge request data, posts comments, and mutates MR state (labels, approvals, merge status).

Config block: platforms:

Example:

platforms:
  gitlab:
    url: "https://gitlab.com"
    token: "${GITLAB_TOKEN}"
  github:
    token: "${GITHUB_TOKEN}"

Built-in platform service modules: - gitlab - GitLab - github - GitHub - bitbucket - Bitbucket Cloud - azure-devops - Azure DevOps - gerrit - Gerrit Code Review - gitea - Gitea - aws-codecommit - AWS CodeCommit - jenkins - Jenkins (CI environment only)


Configuration Terminology

Domain-Specific Blocks

Definition: Top-level YAML/JSON config blocks for built-in modules.

Blocks: - rules: - Built-in RuleModules - platforms: - Built-in PlatformServiceModules - reporters: - Built-in FormatModules and OutputModules

Why domain-specific? This syntax is more intuitive than a generic plugins: block for common use cases.

Example:

rules:
  title-format: {}

platforms:
  gitlab: {}

reporters:
  console: true

External Plugin Block

Block: plugins:

Purpose: Configure external third-party plugins only.

Example:

plugins:
  - id: "com.example.jira-integration"
    version: "1.0.0"
    config:
      jira-url: "https://jira.example.com"
  - id: "custom-validator"

Note: Built-in modules do NOT go in the plugins: block - they use domain-specific blocks.


Comparison: Module vs Plugin

Aspect Module Plugin
In code Specific interface Umbrella interface
Purpose Structured plugin with lifecycle Any extension type
Examples RuleModule, FormatModule, OutputModule Module
Config Domain blocks (rules:, platforms:) plugins: block (external only)
When to use Most plugin authors New plugin types only

Key insight: All Modules are Plugins, but not all Plugins are Modules.