Extracting Built-in Modules
This guide covers how to extract a built-in Karandash module into a standalone plugin JAR, and documents which sealed types in the SDK are open for plugin-defined subtypes.
What Extraction Means
A built-in module ships inside the Karandash binary and is registered in plugins/builtin/builtin-modules.txt. Extracting it means:
- Moving the module's source into a standalone Gradle project
- Compiling it against
plugins/sdkonly (nocoredependency) - Distributing it as a JAR loaded via
ServiceLoaderor as a native shared library
The result is a module that any user can override, fork, or disable - and that the Karandash team can release on an independent versioning cadence.
Requirements for a Standalone Module
- Depend on
plugins/sdkonly. No imports fromio.karandash.core.*,io.karandash.cli.*, or any other internal package. - Use only public SDK types. No
internalclasses, no reflection tricks against internal APIs. - Register via
ServiceLoader. AddMETA-INF/services/io.karandash.sdk.Modulelisting the module's fully-qualified class name. - Be
@Serializable-clean. Config data classes must be@Serializable; never rely onMap<String, Any?>ortoAnyMap(). - Target all platforms. The module must compile for JVM, macOS ARM64/x64, Linux x64, and Windows MinGW if distributed as a KMP artifact, or ship as a JVM JAR loaded via the subprocess bridge on native.
Priority Candidates
| Module | Location | Primary coupling to resolve |
|---|---|---|
| AI rules | plugins/plugins-ai/rules/ai/ |
AiService is already in SDK; check for core imports |
| JIRA integration | plugins/plugins-extended/rules/jira-ticket/ |
HTTP client via ProviderHttpClientFactory (in plugins/helpers) - move helpers dep to SDK or replicate |
| Email output | plugins/plugins-extended/outputs/email-output/ |
JVM JavaMail vs native SMTP split - verify expect/actual boundary is clean |
Common Coupling Issues
- Direct
coreimports - e.g.,import io.karandash.core.config.Config. Replace withJsonElement-based config access. internalAPI usage - anyinternalsymbol is not part of the public SDK. Identify vialsp_find_referencesand replace with a public equivalent or request promotion.- Shared utilities not in SDK -
RegexHelper,GlobMatcher,SsrfUrlValidatorlive incore. Candidates for promotion toplugins/sdkorplugins/helpersbefore extraction. plugins/builtin/builtin-modules.txtregistration - remove the entry after extraction; add the external JAR to the user'splugins:block in config.
Extraction Checklist
- Audit imports - run
grep -r "io.karandash.core" <module>/src/and list every hit. - Resolve each
coreimport - either the type needs promotion to SDK, or the module must be refactored to useJsonElementaccessors directly. - Create standalone Gradle project - depend only on
plugins/sdk(andplugins/helpersif HTTP is needed). - Add
ServiceLoaderregistration -META-INF/services/io.karandash.sdk.Module. - Port tests to
commonTest- remove any test helpers that importcore. - Remove from
plugins/builtin/builtin-modules.txt- verify the binary builds and the module loads from the external JAR. - Publish and document - update
tools/registry/registry.jsonand add a note in the relevantdocs/rules/ordocs/reporters/page.
Sealed Class Extensibility Audit
The SDK uses sealed classes and enums to model core domain types. This section documents which are intentionally closed and which support plugin-defined subtypes.
| Type | Kind | Plugin subtypes? | Rationale |
|---|---|---|---|
FixSuggestion |
Sealed class | Yes - FixSuggestion.Custom added |
Plugins need to express domain-specific auto-fixes beyond the built-in set (AddLabel, RemoveLabel, SetDraft, SetTitle, SetDescription). |
Location (FileRef, CommitRef) |
Sealed class | No | Used in exhaustive when expressions throughout reporters and comment posters. Adding subtypes would silently break all existing when branches. |
Severity |
Enum | No | Fixed domain: ERROR, WARNING, INFO. Extending it would break severity-ordering logic and reporter thresholds. |
MergeRequestState |
Enum | No | Fixed domain tied to platform API mappings via fromString(). New states require platform provider changes, not plugin subtypes. |
ModuleType |
Enum | No - use fromString() |
The fromString() method accepts arbitrary strings for runtime module type discovery without requiring enum extension. |
Finding |
Data class | N/A - not sealed | Already open. Plugins return Finding instances directly; no subtyping needed. |
Decision rule for future types
Add a Custom subtype (or equivalent open extension point) when:
- External plugins need to return instances of the type from their own logic (as with FixSuggestion)
- The set of valid values is genuinely open-ended
Keep sealed / enum when:
- The type is consumed in exhaustive when expressions where an unknown subtype would silently fall through
- The domain is closed and controlled by platform integrations (states, severities)
- Extension is possible via a string-keyed registry pattern (as with ModuleType.fromString())