Contributor conventions
Technical rules for contributing to Karandash: build commands, module layout, architecture constraints, lint
policy and testing requirements. Lint rules are enforced by CI (ktlint, detekt, and the project's own
karandash detekt rule set); the rest is enforced by code review.
Commands
Always run from the repo root (this directory).
./gradlew build # full build: JVM + native target(s) for host OS
./gradlew jvmTest # JVM tests only (fast, ~10-30s)
./gradlew macosArm64Test # native tests (macOS ARM64); linuxX64Test on Linux
./gradlew ktlintCheck detekt # lint + static analysis (CI gate, zero issues)
bash tools/ci/gate.sh # pre-merge gate part 1: format, JVM tests, koverVerify, apiCheck, lint, native link, benchmark check, integration scripts
KARANDASH_PREV_JAR=prev.jar bash tools/ci/gate2.sh # gate part 2: isolation, extensibility, dokka, mkdocs, compat-diff vs a previous release jar
./gradlew ktlintFormat # auto-fix formatting - run before committing
./gradlew :plugins:sdk:apiCheck :core:api:apiCheck # public API binary-compatibility check
./gradlew koverXmlReport koverHtmlReport koverVerify # coverage; per-module floors in gradle/kover-floors.properties
./gradlew :cli:shadowJar # standalone fat JAR
Single test class/method (Gradle test filtering):
./gradlew :core:api:jvmTest --tests "io.karandash.SomeClassTest"
./gradlew :core:api:jvmTest --tests "io.karandash.SomeClassTest.someMethod"
Module paths mirror the directory structure (see Module Structure) - replace :core:api with the target module's Gradle path.
Module Structure
core/ holds fine-grained sub-modules under a parent (ls core/ for the current set). Gradle paths follow
the directory: :core:api, :core:models, :core:cache, etc.
Plugins are organized into three tiers - the tier decides whether a module is always shipped, opt-in, or part of the AI subsystem, which the directory names alone don't tell you:
plugins/
plugins-core/ - Tier 1: always required (GitLab/GitHub/Bitbucket platform services, console, 9 core rules, parsers, minimal profile)
plugins-extended/ - Tier 2: opt-in (niche platform services: Azure DevOps, Gerrit, Gitea, AWS, Jenkins; enrichment providers, extra reporters/rules/profiles, scripts)
plugins-ai/ - Tier 3: AI subsystem (ai-core, ~15 analyzers, LLM providers, reports, metrics)
integration-tests/ - Cross-tier integration tests (rules/, platforms/)
sdk/ - Public plugin API
builtin/ - factory registrations for all first-party modules (manifest: `builtin-modules.txt`)
bootstrap/ - `PluginBootstrap`: runs built-in + JAR/native/JS/WASM loaders into `ModuleRegistry` at CLI startup
inspector/ - reads/verifies plugin files without loading them (`plugin list`, install verify)
registry/ - public plugin registry client (`plugin install/update/list`, `generate`)
helpers/ - Shared HTTP helpers
loader/ - Plugin loading (JAR, JS, WASM, Native) + jar-bridge/
Additional modules:
- cli/ - command implementations; cli-ai/ - AI-tier commands (stats, calibrate, test-rule, verify-policy, mutate, explain) plus SuspendCliktCommand/ExitCodes, registered by cli (cli → cli-ai, never the reverse); cli-app/ - JVM main() entry point (karandash.jvm-application)
- projects/ - dogfooding config trees (base → base-kmp → wallet, etc.) exercising extends: inheritance; some are Gradle modules with tests
- tools/ - examples/ (canonical example plugins), ci/verify-plugin-isolation.sh, registry/, benchmarks/, templates/
- build-logic/ - convention plugins, GenerateBuiltInRegistryTask, dependency-guard
Plugin System Terminology
| Code Interface | Config Block | Purpose |
|---|---|---|
PipelineExtension |
(auto-discovered) | Pre/post validation hooks |
Full hierarchy: Plugin > Module > {RuleModule, ReporterModule, PlatformServiceModule, EnrichmentProviderModule, PipelineExtension}
Architecture
Kotlin Multiplatform
Convention plugins in build-logic/ are the source of truth for target set, expect/actual wiring, and Gradle DSL rules - read the relevant karandash.* plugin there before touching module build files.
New modules must use convention plugins. Every new KMP module's build.gradle.kts must apply karandash.kmp-library (or karandash.kmp-platform-service-module for PlatformServiceModule implementations, or karandash.jvm-application for JVM-only entry points). This automatically configures:
- All 4 native targets (macOS ARM64/x64, Linux x64, Windows MinGW) + JVM
- ktlint (via karandash.lint) and detekt - lint is active from the first build
- Source set completeness validation - all 4 target-specific source sets must be declared
Never apply raw kotlin("multiplatform") or configure ktlint/detekt manually in module build.gradle.kts files - the convention plugin handles it.
Target gating: On macOS, karandash.kmp-library only declares macosArm64 + macosX64 targets by default. Modules that are dependencies of plugins/sdk (or any module with karandash.ungatedTargets=true) must also set karandash.ungatedTargets=true in their own gradle.properties - otherwise Gradle cannot resolve linuxX64/mingwX64 variants and IDE sync fails.
commonMain is mandatory for all new code. Platform-specific source sets must contain only actual declarations and their direct platform helpers.
Dependency Direction
Dependencies form a strict DAG:
cli → core/* → core/api → stdlib
core/* → plugins/sdk (allowed; never the reverse)
cli → plugins/sdk → core/api + SDK-public core leaves
plugins/{plugins-core,plugins-extended,plugins-ai}/* → plugins/sdk
dsl/* → core/api
dsl/lsp-server → plugins/sdk, plugins/bootstrap, plugins/loader (registry access for hover and completion)
Hard rules:
- core/* must NOT depend on cli, dsl, or plugin tier modules - enforced at configuration time by the
guard in build-logic/.../karandash.kmp-library.gradle.kts (test configurations exempt; any known edge awaiting
removal goes in the DependencyDirection allowlist with its audit ID - currently empty)
- core/* may depend on plugins/sdk (core/config, core/state, core/validation, core/ai-pipeline do);
plugins/sdk must never depend back on them
- plugins/sdk must NOT depend on core/* other than core/api and the SDK-public core leaves it re-exports
via api() (core/logger, core/models, core/conditions, core/multipattern, core/common) - those are
public ABI and are covered by apiCheck; the one internal exception is core/regex-safety (pulls in
core/cache), an implementation() dependency backing SafeRegex and kept out of the SDK ABI on purpose;
never on cli or plugin tier modules
- Plugin tier modules must NOT depend on cli
- core/* and dsl/* must NOT import concrete SDK module types (use fun interface injection for cross-layer calls)
- Exception types must be defined in core/api or plugins/sdk only - never in leaf modules
// BAD - core importing a concrete plugin module
import io.karandash.plugins.modules.rules.ai.AiRuleModule
// GOOD - core depends on an interface; concrete type injected at CLI layer
fun interface RuleEvaluator {
suspend fun evaluate(mr: MergeRequest, config: JsonElement): List<Finding>
}
Validation Flow
CLI command → Config pipeline (JsonElement throughout)
→ PipelineExtension.fetchOptions / needsBlame / needsHeadContent (what the fetch must include)
→ PlatformServiceModule.fetchMergeRequest(url) → MergeRequest
→ PipelineExtension.onConfigured(env) (env.platformId = the provider that fetched)
→ PipelineExtension.onBaseFiles(files) (only for extensions whose baseFiles() is non-empty)
→ PipelineExtension.onPostFetch(mr, config)
→ ValidationEngine.validate(mr)
→ for each RuleModule: validate(ruleId, mr, configElement: JsonElement) → List<Finding>
→ PipelineExtension.afterValidation(findings, mr, config) → List<Finding>
→ ValidationResult
→ PipelineExtension.beforeReporting(findings, mr) → List<Finding>
→ for each ReporterModule: report(findings, config: JsonElement)
→ PipelineExtension.onPipelineComplete()
Object Lifecycle
Two lifecycle categories - mixing them causes subtle bugs.
Per-run (@lifecycle per-run): ValidationEngine, ValidationPipeline, ValidateCommandScope. New instance per CLI invocation; mutable fields permitted. Mark with KDoc:
/** @lifecycle per-run -- do not reuse across invocations */
class ValidationPipeline(...)
Application-scoped: ModuleRegistryImpl, CacheManager, GlobMatcher. Must be thread-safe and stateless between calls. Mutable fields require concurrency protection.
Per-run lifecycle is enforced by code review only.
Plugin System
All new functionality must be implemented as a plugin - including built-in features. Design new capability as a plugins/sdk module.
plugins/sdk is a public API - only add fields, never remove or rename. All plugins receive PluginContext (config as JsonElement, logging, env vars filtered by KarandashEnvSecurity.DENYLIST).
SDK API Evolution Rules
- New interface methods must have a default implementation so existing plugins continue to compile
- Signature changes: add new method with default → deprecate old → remove in next major version
api/*.apifiles are checked into git and reviewed on each PRbinary-compatibility-validatoris applied toplugins/sdkandcore/api- runapiDumpafter an intentional API change
Module Lifecycle & Statelessness
Lifecycle: initialize(ctx): Boolean (once; return false on bad config - never throw) → primary method (0+ times) → shutdown() (at most once, idempotent, must not throw, releases all resources). types() must return ALL types for multi-type modules.
Allowed fields: val config set in initialize(), HttpClient from initialize(), logger via sanctioned pattern:
private var logger: Logger = NoOpLogger
override suspend fun initialize(ctx: PluginContext): Boolean { logger = ctx.logger; return true }
lateinit var is permitted for resources created in initialize() that require construction arguments unavailable at class instantiation time (e.g. HttpClient needing a logger from PluginContext). These must be cleaned up in shutdown():
private lateinit var httpClient: HttpClient
override suspend fun initialize(ctx: PluginContext): Boolean {
httpClient = ProviderHttpClientFactory.create(logger = ctx.logger); return true
}
override suspend fun shutdown() { if (::httpClient.isInitialized) httpClient.close() }
Forbidden fields: lateinit var for storing PluginContext itself, var accumulating cross-call state, unprotected mutable collections.
Known violators: grep for lateinit var context: PluginContext and private var fields other than the sanctioned logger in module classes. Fix when touching those files.
Plugin Languages & Loading
- JVM: JAR via
ServiceLoader, native via JNA, JS via QuickJS, WASM via Chicory - Native: JAR via subprocess (
JarBridgeServer), native viadlopen, JS via QuickJS, WASM via Chasm (pure Kotlin, compiled in; 2.2.0, except the macOS x64 binary on 1.7.0, whose store cannot be interrupted) - Loader:
plugins/loadermodule (JarPluginLoader,NativePluginLoader,JsPluginLoader)
Bridge completeness is checked by BridgeAbiParityTest (plugins/loader/src/jvmTest/). Module contract tests live in plugins/integration-tests/{rules,providers}/ (*ContractTest).
Sanctioned runBlocking Sites
runBlocking is forbidden in production code except at tracked bridge boundaries (a non-suspend caller that must call a suspend method). Every usage requires a // bridge-boundary: <reason> comment within the 3 lines above it or as the first line of its block:
- CLI entry: KarandashCli.kt (runCli), SuspendCliktCommand.run(), the ValidateCommand watch callback
- JS/QuickJS: JsTransport, JsContextInjector
- CAbiBridge (C ABI exports), JarBridgeServer (blocking stdin/stdout subprocess)
- BridgeTransport.callSync default (non-suspend SDK members such as tokensConsumed, costSummary answered by a guest call)
- Host-service channel: HostServiceDispatcher.call (a guest's karandash_host_call on its own thread, never main; Dispatchers.Default)
- LSP: dsl/lsp-server Main.kt, CachedRegistryMetadata, ConfigPipelineDiagnostics
- On native targets: must use a dedicated coroutine context to avoid deadlocking the main dispatcher
detekt karandash:UnsanctionedRunBlocking (sanctionedFiles in detekt.yml) lists exactly these files and checks the comment; adding a site means adding it here and there.
The AI bridge methods AiRedactorModule.redact and AiTokenAllocatorModule.allocate are suspend, so the AI bridges need no runBlocking.
Example Plugin Canonicality
tools/examples/ must follow every rule in this file. Rule changes affecting module patterns must update example projects in the same commit. CI runs detekt on example projects.
Config Loading Pipeline
Formats (discovery order, first match wins):
1. .karandash/config.kts → Kotlin DSL (ANTLR4 via dsl/kts-parser)
2. .karandash/config.yaml / .karandash/config.yml → YAML
3. .karandash/config.json → JSON
Pipeline steps:
1. Detect via ConfigDiscovery; route via ConfigFormatRegistry (sorted by priority)
2. Parse to JsonElement; process as JsonObject throughout ConfigMapParser
3. Resolve { file: "..." } references via ExternalValueResolver in ConfigChainParser (paths relative to config file's directory; auth blocks excluded via security denylist)
4. Apply extends: inheritance via ConfigChainResolver.buildChain + ConfigChainParser.parseAndMerge (validate extends only prints the chain)
5. Interpolate ${ENV_VAR} via PlatformEnvironment (KarandashEnvSecurity.DENYLIST enforced)
6. Normalize keys once via deepNormalizeKeys() (kebab-case, snake_case → camelCase)
7. Validate schema → Config delivered to ValidationEngine
8. Zero-config fallback via ZeroConfigDefaults (queries registry for isDefaultZeroConfigProfile)
Note: ExternalValueResolver is called by ConfigChainParser, not ConfigMapParser - do not add a second resolution pass.
Config Schema Evolution Policy
- New optional fields with defaults: permitted
- New required fields: forbidden without a zero-config default
- Renamed fields: keep old name as alias with deprecation warning at
warnlevel - Removed fields: forbidden without a two-release deprecation window
- Any change to a golden under
cli/src/jvmTest/resources/compat/(effective config, output snapshots) is a behavior change: regenerate with-Dkarandash.updateGolden=trueand record it under CHANGELOG## [Unreleased]
HTTP
Ktor with platform-specific engines: CIO (JVM), curl (macOS/Linux native), WinHTTP (Windows). Always use ProviderHttpClientFactory - never create Ktor clients directly. No custom retry logic - use Ktor HttpRequestRetry plugin. Do not set per-request timeouts in module code.
Code Quality (Lint)
ktlint v1.5.0 + detekt 2.0.0-alpha.6 (dev.detekt). Zero issues: every rule is severity error and fails the task. Run ./gradlew ktlintFormat before committing.
Project conventions that need no type resolution are detekt rules too: the karandash rule set in
tools/detekt-rules (GenericCatchWithoutBoundary, SuspendCatchWithoutCancellation, ForbiddenRunCatching,
ForbiddenWithTimeout, UnsanctionedRunBlocking, UnownedCoroutineScope, RawConsoleOutput, InlineJsonBuilder,
DirectHttpClient, DirectGetenv, UntypedConfigMap, SuppressOutsidePolicy, DynamicRegex), applied to every module and
tools/examples; sanctioned files are rule config in detekt.yml.
Zero-tolerance for red builds. After any change, run lint and tests until all checks are green. Fix every failure - including pre-existing issues in files you touched. Do not leave known-broken tests or lint violations for later.
Write compliant code from the start
Do not write code that violates lint rules and fix it later - read the configs and write within the thresholds from the beginning. Before writing any new class or function, consult:
- detekt:
detekt.yml(repo root) - complexity thresholds (class size, method length, cyclomatic complexity, parameter counts, nesting depth, etc.) and active rule sets - ktlint:
.editorconfig(repo root) - code style, line length, import rules, indentation
Design classes and methods to fit within these limits from the start. If a class approaches the size threshold, decompose it immediately rather than writing a large class and refactoring later. Writing within these constraints from the start avoids fix-up cycles and keeps detekt at zero issues throughout development.
@Suppress Policy - Fix, Don't Suppress
@Suppress is forbidden by default. Never add class-level or file-level suppression. detekt karandash:SuppressOutsidePolicy rejects any id outside its allowedIds in detekt.yml (the categories below).
Permitted exceptions:
| Category | Example | Required condition |
|---|---|---|
| Kotlin compiler opt-in | @Suppress("EXPECT_ACTUAL_CLASSIFIERS_ARE_IN_BETA_WARNING"), @Suppress("OPT_IN_USAGE") |
No fix path until language feature stabilises |
| C-interop / native ABI stubs | @Suppress("EmptyFunctionBlock") on native plugin stub shutdown(), @Suppress("UnusedParameter") on a C callback |
Body structurally cannot be non-empty / the C signature fixes the parameters; add a // native-abi: <reason> comment |
expect/actual symmetry |
@Suppress("UnusedParameter") on actual constructors |
actual must mirror expect signature |
Boundary UNCHECKED_CAST |
YAML/JSON/KTS parser boundaries, untyped cache payloads | Parser library returns untyped map; no type-safe alternative; add a // parser-boundary: or // boundary: comment |
| Public API with no current callers | SDK extension functions, API overloads | Must add KDoc explaining retention |
TooGenericExceptionCaught at module boundaries |
Top-level of validate(), report(), fetchMergeRequest(), bridge, CLI entry |
Must add // boundary: <reason> comment |
Fix, don't suppress:
| Violation | Correct fix |
|---|---|
LargeClass (>500 lines) |
Extract responsibilities (Strategy, Stage, Adapter, Facade) |
LongMethod |
Extract private methods or a dedicated class |
CyclomaticComplexMethod |
Replace when chains with polymorphism or sealed class dispatch |
LongParameterList |
Group params into a dedicated options/config data class |
ThrowsCount |
Consolidate into sealed result type |
UnusedParameter (non-interface/non-actual) |
Remove; deprecation cycle for public API |
UseCheckOrError |
error(msg) |
UseRequire |
require(condition) { msg } |
CollapsibleIfStatements, ProtectedMemberInFinalClass, ReturnCount, SwallowedException |
Fix the code structure |
LargeClass threshold: 500 lines (detekt 2 counts KDoc lines too) (200 lines for LSP server - see LSP Server Rules).
Code Patterns & Style
Null Safety
No !! operator. Use checkNotNull(value) { "message" } or requireNotNull(value) { "message" }. Enforced by detekt UnsafeCallOnNullableType.
Error Handling
| Situation | Approach |
|---|---|
| Config parse failure | Throw ConfigParseException - caught and shown to user |
| Validator cannot evaluate | Return empty List<Finding> - log via context.warn(), never throw |
| Platform API failure | Result<T> and propagate |
| Domain errors with multiple cases | Sealed class hierarchy |
| Unexpected/programming error | error(msg) / require(condition) { msg } |
Exception Handling - Catch Specificity
Never catch generic Exception or Throwable - catch specific types:
| Context | Catch type |
|---|---|
| HTTP calls | IOException, HttpRequestTimeoutException |
| JSON parsing | SerializationException, IllegalArgumentException |
| Config loading | ConfigParseException, IOException |
Plugin initialize() |
ConfigParseException |
| Module boundary (validate/report/fetch) | Exception with // boundary: <reason> comment |
Never swallow exceptions silently - every catch must log at warn or rethrow as KarandashException subtype.
init {} blocks must not discard return values. If initialization can fail, use a companion factory returning Result<T>.
Immutability & Data Classes
var is forbidden except inside @lifecycle per-run classes. Every field/property/local must be val. Enforced by detekt VarCouldBeVal.
All data class declarations must be @Serializable. Only exception: runtime context holders (see @Serializable Contract).
- Use
copy()for all transformations - never mutate a model instance - Collections returned from functions:
List<T>(read-only), neverMutableList<T> MutableList/MutableMap/MutableSet: permitted only as local variables inside function bodies, never as class fields
Coroutines & Coroutine Safety
- Use
suspend fun-runBlockingonly atmain()incli-app/and in tests viarunTest {} - Use structured concurrency (
coroutineScope,supervisorScope) - neverGlobalScope - All plugin module interfaces use
suspend fun; blocking I/O useswithContext(Dispatchers.IO)
Dispatchers.IO KMP import - requires both imports or it resolves to JVM-only:
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.IO // required - common declaration
withContext(Dispatchers.IO) { readFile() }
CancellationException must always be rethrown. In every catch in a suspend fun, call e.rethrowCancellation() (defined in plugins/sdk) before handling. Enforced by the karandash detekt rule set (tools/detekt-rules): SuspendCatchWithoutCancellation flags an IllegalStateException/RuntimeException catch in a suspend fun that neither rethrows cancellation nor follows a CancellationException catch, and GenericCatchWithoutBoundary flags an Exception/Throwable catch without a // boundary: <reason> comment inside it.
safeCall {} wrapper must be suspend and rethrow CancellationException.
No PlatformLock / platformSynchronized. Use KMP primitives:
| Need | Solution |
|---|---|
| Mutual exclusion | Mutex from kotlinx.coroutines.sync |
| Observable state | MutableStateFlow |
| Hot-path primitives | AtomicInt, AtomicLong, AtomicBoolean, AtomicRef from atomicfu |
atomicfu already configured in build-logic. Never use java.util.concurrent.atomic.*.
No mutable shared collections as class fields. Use AtomicRef.update {} or Mutex.withLock {} + copy-on-write. Exception: read-only maps built once at initialize() as val.
Module ID & Cross-Module Constants
A module ID is defined exactly once - in the module's companion object. No other file may hardcode the same string.
If module B needs module A's ID but cannot depend on A, in priority order:
1. Decouple via SDK flags (ReporterModule.isDefaultInteractive, ProfileModule.isDefaultZeroConfigProfile) or fun interface
2. Define in core/config/src/commonMain/kotlin/io/karandash/config/keys/ (e.g., ModuleIds.GITLAB); both modules import from there
3. Never add a dependency just to read an ID
Core key objects: ModuleIds, PolicyKeys in core/config/src/commonMain/kotlin/io/karandash/config/keys/; EnrichmentKeys lives in plugins/sdk/…/sdk/enrichment/ and the EnrichmentGlobMatcher helper in core/glob. New shared string constants belong here.
Config & Data Layer - Mandatory Rules
All config data flows as JsonElement. Map<String, Any?> is forbidden in production code. The only exception is a
parser boundary (YAML/KTS parser output, the mapToJsonElement bridge), marked with a // parser-boundary: <reason>
comment on the line, within the two lines above it or on the line below; detekt karandash:UntypedConfigMap fails anything else in commonMain.
JsonElement-first
| Rule | Details |
|---|---|
SDK interfaces use JsonElement only |
PluginContext.pluginConfig: JsonElement, Module.defaultConfig(): JsonElement, ReporterModule.report(config: JsonElement), RuleModule.validate(configElement: JsonElement). Never add Map<String, Any?> to SDK interfaces. |
No toAnyMap() in production code |
Exists only for test code and parser boundaries. Never call in cli/src/commonMain/ or plugins/*/src/commonMain/. |
No ConfigSpec.fromMap() |
Use configSpec.fromJson(element). |
No MapBackedTypedConfig / asTypedConfig() |
Removed. Use TypedKey, TypedRuleModule, AbstractTypedSingleRuleModule (JsonElement-backed, in plugins/sdk). |
No flexField() / flexGet() |
Keys normalized at parse time via deepNormalizeKeys(). Use JsonObject["camelCaseKey"]. |
No mapToJsonElement() in hot paths |
Bridge for parser boundaries only; never for data that could be JsonElement from the start. |
Config data classes must be @Serializable |
Use @SerialName for kebab/snake-case keys. Deserialize via Json.decodeFromJsonElement(). |
No inline Json {} blocks |
Use KarandashJson.Default or KarandashJson.Strict from core-models. |
@Serializable Contract
Every data class must be @Serializable - domain models, config types, SDK types, internal DTOs, test fixtures.
Documented exception - runtime context holders. A data class that carries lambdas, Throwable, Regex,
Path, untyped Any or live services cannot be serialized and stays unannotated, with a KDoc line
Not @Serializable: <why>. directly above it (e.g. ModuleResult.Failure, ConditionContext,
PluginCommandSpec, AiAnalyzerContext, ReportContext, the dsl/kts-parser AST). A data class without either
the annotation or that line is a violation.
Checklist when adding any data class:
1. @Serializable annotation
2. @SerialName for fields whose JSON key differs from Kotlin name
3. Use KarandashJson.Default - no inline Json {} blocks
4. Verify with serializer<T>() call (SDK types checked by audit test in plugins/sdk/src/commonTest/)
Pipeline Decoupling
| Rule | Details |
|---|---|
ValidationPipeline must not import AI classes |
AI integration goes through PipelineExtension via ModuleRegistry. Zero import io.karandash.plugins.ai.* in ValidationPipeline.kt. |
AutoFixer must not parse finding messages |
Use finding.fixSuggestions (structured FixSuggestion sealed class), never finding.message.startsWith(...). |
| No hardcoded module IDs in generic pipeline code | Use SDK flags: ReporterModule.isDefaultInteractive, ProfileModule.isDefaultZeroConfigProfile, ConfigFormatModule.priority. |
New built-in modules go in plugins/builtin/builtin-modules.txt |
BuiltInPluginLoader factory list is generated from this manifest at build time. |
| No double-parse config paths | Config parsed once via ConfigChainParser. Do not re-parse JsonElement in module code. |
Key Conventions
- No magic strings for module IDs: use
companion objectconstants (e.g.,GitLabPlatformService.ID,ConsoleReporterModule.FORMAT_ID) - No magic strings for defaults: constants in companion objects or
core/config/src/commonMain/kotlin/io/karandash/config/keys/objects MergeRequestState.fromString(): normalize platform state strings to enumConfigParseException: throw for user-facing config parse errors indsl/kts-parserandcliGlobMatcher: useGlobMatcher.Default(sized per run byGlobMatcher.useManaged(cacheManager)); reuse instances, don't create per-callProviderResponseCache: built once per run byPipelineInfrastructureand passed throughPipelineRunResourcesSecretRedactor: always run diffs through this before sending to LLM inplugins/plugins-ai/rules/ai- Rule modules return empty list on failure; log via
context.warn() Finding.locationcarriesFileReforCommitReffor inline annotation supportFinding.fixSuggestionscarries structuredFixSuggestion(AddLabel, RemoveLabel, SetDraft, SetTitle, SetDescription)- No
println()/print()- useLoggerfromcore-loggeror Mordant. Enforced by detektkarandash:RawConsoleOutput(the stdout/stderr sinks are itsexcludesindetekt.yml). - Test fixtures: use factory functions, not builder classes
Testing
Default to commonTest (shared across all targets); jvmTest for JVM-only cases (mokkery). Assertions via kotlin.test, coroutines via runTest {}. No live API calls - use Ktor MockEngine for HTTP stubs.
Shared common test support lives in test-fixtures: GoldenFiles (golden assertions; -Dkarandash.updateGolden=true reaches every JVM and native test process as KARANDASH_UPDATE_GOLDEN, -Dkarandash.updateBaseline as KARANDASH_UPDATE_BASELINE - wired in karandash.kmp-library via build-logic/.../TestEnvironment.kt) and TestFiles (temp dirs, text I/O, findRepoRoot()). Native test processes get KARANDASH_EVAL_LIVE and provider tokens blanked, so they can never go live.
Backtick test names: letters, digits, spaces, - and _ only. No , . ; : / \ < > [ ] quotes - Kotlin/Native fails with Name contains illegal characters, while JVM accepts them, so only the native gate step catches it.
Additional tests required for this repo:
- Module contract tests: lifecycle invariants per module type (plugins/integration-tests/, *ContractTest)
- Bridge completeness test: BridgeAbiParityTest in plugins/loader/src/jvmTest/ - every guest-implementable SDK member needs a BridgeAbi op, a descriptor key or a NOT_BRIDGED reason
- SDK serialization audit test: plugins/sdk/src/commonTest/ - calls serializer<T>() for every public data class in io.karandash.models and io.karandash.sdk
KMP API Rules
All commonMain code must use KMP-compatible APIs. Most of the table below is enforced by code review only: detekt.yml ForbiddenImport bans just java.time.* and Ktor encodeBase64/decodeBase64 outside jvmMain, and the karandash detekt rules catch getenv( (DirectGetenv), HttpClient( (DirectHttpClient), inline Json {} (InlineJsonBuilder) and Map<String, Any?> in commonMain (UntypedConfigMap).
| Category | Must Use | Banned |
|---|---|---|
| Timestamps / Duration | kotlin.time.Clock, kotlin.time.Instant, kotlin.time.Duration |
java.time.*, java.util.Date, System.currentTimeMillis(), System.nanoTime() |
| Local dates / TZ | kotlinx-datetime (LocalDate, LocalDateTime, TimeZone) |
java.time.* |
| File I/O | kotlinx-io (Path, Source, Sink) |
java.io.File, java.io.*Stream, java.nio.* |
| Coroutines | kotlinx-coroutines-core |
java.lang.Thread, ExecutorService, Future |
| IO dispatcher | Dispatchers.IO + import kotlinx.coroutines.IO |
Dispatchers.IO without KMP import |
| Atomics | kotlinx-atomicfu |
java.util.concurrent.atomic.* |
| Concurrency | Mutex, MutableStateFlow, CompletableDeferred, kotlinx.coroutines.sync.Semaphore |
ConcurrentHashMap, CopyOnWriteArrayList, java.util.concurrent.locks.*, CountDownLatch, Semaphore (java) |
| Collections | mutableListOf(), mutableMapOf(), mutableSetOf(), ArrayDeque |
java.util.ArrayList, java.util.HashMap, java.util.Stack, java.util.Properties |
| UUID | com.benasher44:uuid |
java.util.UUID |
| Random | kotlin.random.Random |
java.util.Random |
| Base64 | kotlin.io.encoding.Base64 |
java.util.Base64, io.ktor.util.encodeBase64 |
| Math | kotlin.math.* |
java.lang.Math.* |
| Logging | Logger from core-logger |
java.util.logging.* |
| Env vars | PlatformEnvironment.getEnv() |
System.getenv(), platform.posix.getenv(), System.getProperty() |
| HTTP client | Ktor via ProviderHttpClientFactory |
Direct Ktor client creation |
Do not introduce JVM-only libraries (Apache Commons, Guava, etc.) in commonMain.
Security Conventions
Detekt enforces some rules at lint time (ForbiddenImport, karandash:DynamicRegex); the rest are convention-based.
- Regex: Never call
Regex()on user-supplied patterns. UseRegexHelper.tryCompile()(returnsRegex?, appendsFinding) orRegexHelper.compileOrNull()(forinitblocks). DirectRegex()/toRegex()only on a pattern written in the source (a literal, optionally with${Regex.escape(...)}pieces), enforced per call by detektkarandash:DynamicRegex; itsexcludesare the guarded compile points only. - URL validation: All user-configured outbound URLs must pass through
SsrfUrlValidator.validate()before HTTP requests. - Env vars: Never read directly. Use
PlatformEnvironment.getEnv(). It does not filter anything itself:KarandashEnvSecurity.DENYLISTis applied by config interpolation (ConfigMapParser.interpolate) and by the plugin context (BootstrapPluginContext), so code reading env for config or plugins must go through those paths. - Cache sizing: All in-memory caches must be bounded with LRU eviction. Follow
GlobMatcherpattern (fixed-sizeLinkedHashMapwithremoveEldestEntry). - Path normalization: Always normalize paths/URLs before equality checks. Follow
ConfigChainResolver.normalizeUrl()to prevent path traversal bypasses.
LSP Server Rules
dsl/lsp-server/ has stricter requirements than the rest of the repository (JVM-only, LSP4J).
- Class size: keep classes under 200 lines (stricter than the repo's 499-line detekt
LargeClasslimit, which is the only automatic check). Split by responsibility, asCompletionSupport,CompletionTablesandDiagnosticSupportdo. - Registry access: read module metadata (rule ids, providers, reporters, ...) through
CachedRegistryMetadata, which queries theModuleRegistryonce at construction. Do not query the registry per request. The one other registry consumer isConfigPipelineDiagnostics, which runs the CLI'sConfigCheckon the loadedPluginBootstrap. - Thread safety: LSP4J calls handlers from its thread pool. Providers hold only immutable state built at
construction; no shared mutable collections or
varfields. runBlocking: LSP4J handlers are synchronous while registry and parser APIs aresuspend. It is allowed only inMain.kt,CachedRegistryMetadata.ktandConfigPipelineDiagnostics.kt(the detektUnsanctionedRunBlockinglist), each with a// bridge-boundary: <reason>comment.- Diagnostics =
config validate:ConfigPipelineDiagnosticsrunsConfigCheck(:cli) with the editor buffer as the document's content, soextends:parents and{ file: }references resolve as on the command line. Positions come from each message's key path (first matching line per segment); do not add a second config check here.