@booklib/skills 1.0.0

package/effective-kotlin/references/review-checklist.md

@@ -0,0 +1,126 @@
+# Effective Kotlin — Code Review Checklist
+
+Systematic checklist for reviewing Kotlin code against the 52 best-practice items
+from *Effective Kotlin* (2nd Edition) by Marcin Moskała.
+
+---
+
+## 1. Safety (Items 1–10)
+
+### Mutability & Scope
+- [ ] **Item 1 — Limit mutability** — Are `val` and immutable collections used by default? Is `var` used only when truly necessary? Are mutable collections encapsulated?
+- [ ] **Item 2 — Minimize variable scope** — Are variables declared close to first use? Are any variables declared at function-top that could be scoped tighter? Are `let`/`run` used to restrict scope?
+
+### Null Safety & Types
+- [ ] **Item 3 — Eliminate platform types** — At Java/Kotlin boundaries, are types explicitly annotated? Do platform types (`Type!`) leak into Kotlin APIs?
+- [ ] **Item 4 — No exposed inferred types** — Do public functions and properties declare explicit types? Could an implementation change silently alter the public type?
+
+### Preconditions & Error Handling
+- [ ] **Item 5 — Specify expectations** — Are `require()` and `check()` used at function entry points? Are preconditions documented for public functions?
+- [ ] **Item 6 — Standard errors** — Are standard exceptions (IllegalArgumentException, IllegalStateException) used instead of custom exceptions for common conditions?
+- [ ] **Item 7 — Null or Failure for expected outcomes** — Do functions that can legitimately fail return `null` or `Result` instead of throwing? Are exceptions reserved for programming errors?
+- [ ] **Item 8 — Proper null handling** — Is `!!` absent or justified? Are safe calls (`?.`), Elvis (`?:`), and smart casts used consistently? No unnecessary null checks?
+
+### Resources & Testing
+- [ ] **Item 9 — Resources with use()** — Are all Closeable/AutoCloseable resources wrapped with `use()`? Are file reads using `useLines()` or `use()`?
+- [ ] **Item 10 — Unit tests** — Is business logic covered by tests? Are edge cases and error paths tested? Are tests independent and descriptive?
+
+---
+
+## 2. Readability (Items 11–18)
+
+- [ ] **Item 11 — Design for readability** — Is the code clear on first read? Are there unnecessarily clever constructions? Are complex expressions broken into named intermediate variables?
+- [ ] **Item 12 — Operator meaning consistent** — Do operator overloads match their conventional function names (`plus`, `times`, `contains`)? No surprising operator semantics?
+- [ ] **Item 13 — No Unit? returns** — Does any function return `Unit?`? Is `Unit?` used in conditional logic? Replace with Boolean or sealed type.
+- [ ] **Item 14 — Types specified when unclear** — Are inferred types obvious from context? Do public APIs have explicit type annotations? Would a reader need to navigate to a function to understand the type?
+- [ ] **Item 15 — Explicit receivers** — In nested scope functions or DSLs, are receivers referenced explicitly when ambiguous? Is `@DslMarker` used for DSL scope control?
+- [ ] **Item 16 — Properties represent state** — Do custom getters perform only cheap, side-effect-free, idempotent computations? Is behavior in functions, not properties?
+- [ ] **Item 17 — Named arguments** — Are boolean parameters named? Are same-typed parameters named? Are configuration-style calls using named arguments?
+- [ ] **Item 18 — Coding conventions** — Does the code follow Kotlin coding conventions? Are naming, formatting, and structure consistent? Is ktlint/detekt configured?
+
+---
+
+## 3. Reusability (Items 19–25)
+
+- [ ] **Item 19 — No repeated knowledge** — Is any business rule, validation, or algorithm defined in more than one place? Is there a single source of truth for each concept?
+- [ ] **Item 20 — stdlib used** — Are standard library functions used instead of hand-rolled equivalents? Check: collection operations, string building, scope functions.
+- [ ] **Item 21 — Property delegation** — Are there repeated property patterns (lazy init, change notification, validation) that should use `by lazy`, `Delegates.observable`, or custom delegates?
+- [ ] **Item 22 — Generics for algorithms** — Are utility functions generic where possible? Is there type-specific duplication that could be parameterized?
+- [ ] **Item 23 — No shadowed type parameters** — In generic classes, do member functions avoid redeclaring the class's type parameter with the same name?
+- [ ] **Item 24 — Variance considered** — Are `out`/`in` modifiers applied to type parameters that are only produced or consumed? Could variance allow more flexible subtype usage?
+- [ ] **Item 25 — Multiplatform reuse** — If targeting multiple platforms, is platform-independent logic in common modules? Are `expect`/`actual` declarations used appropriately?
+
+---
+
+## 4. Abstraction Design (Items 26–32)
+
+- [ ] **Item 26 — Single level of abstraction** — Does each function operate at one consistent level of detail? Are there functions mixing high-level orchestration with low-level manipulation?
+- [ ] **Item 27 — Abstraction protects against changes** — Are external dependencies wrapped behind interfaces? Can implementations be swapped without changing business logic?
+- [ ] **Item 28 — API stability specified** — Are experimental APIs annotated with `@RequiresOptIn`? Are deprecated elements marked with `@Deprecated` with `ReplaceWith`?
+- [ ] **Item 29 — External APIs wrapped** — Are third-party libraries accessed through your own abstractions? Can they be mocked in tests?
+- [ ] **Item 30 — Minimal visibility** — Is `private` the default? Are `internal` and `public` used only when needed? Do properties have restricted setters where appropriate?
+- [ ] **Item 31 — Contracts documented** — Do public APIs have KDoc? Are parameters, return values, exceptions, and edge cases documented?
+- [ ] **Item 32 — Contracts respected** — Do implementations honor the contracts of interfaces they implement? Are `equals`/`hashCode`/`compareTo` contracts maintained?
+
+---
+
+## 5. Object Creation (Items 33–35)
+
+- [ ] **Item 33 — Factory functions considered** — Where constructors are limiting, are factory functions used? Are there complex constructors that would benefit from named factories?
+- [ ] **Item 34 — Primary constructor with defaults** — Are Kotlin primary constructors with default values used instead of Java-style builders or telescoping constructors?
+- [ ] **Item 35 — DSL for complex creation** — For hierarchical or complex object assembly, is a type-safe builder DSL used? Is `@DslMarker` applied?
+
+---
+
+## 6. Class Design (Items 36–44)
+
+### Composition & Data
+- [ ] **Item 36 — Composition over inheritance** — Is inheritance used only for IS-A relationships? Is Kotlin's `by` delegation used for code reuse? Are there fragile base class issues?
+- [ ] **Item 37 — Data modifier** — Are data-holding classes using the `data` modifier? Are generated methods (equals, hashCode, copy, toString) appropriate?
+- [ ] **Item 38 — Function types for single-method interfaces** — Are single-method interfaces replaced with function types `(A) -> B` or `fun interface`? Is SAM conversion used for Java interop?
+
+### Hierarchies & Contracts
+- [ ] **Item 39 — Sealed hierarchies over tagged classes** — Are there classes with type enums and conditional logic that should be sealed class hierarchies? Do `when` blocks benefit from exhaustiveness?
+- [ ] **Item 40 — equals contract** — Is `equals` reflexive, symmetric, transitive, and consistent? Is it overridden together with `hashCode`? Does inheritance break symmetry?
+- [ ] **Item 41 — hashCode contract** — Is `hashCode` consistent with `equals`? Are the same properties used in both? Are mutable objects used as hash keys?
+- [ ] **Item 42 — compareTo contract** — Is `compareTo` antisymmetric, transitive, and consistent with equals? Is `compareBy`/`compareValuesBy` used for clean implementation?
+
+### Extensions
+- [ ] **Item 43 — Non-essential API in extensions** — Are classes bloated with utility methods that could be extensions? Could non-essential methods be extracted to improve core API focus?
+- [ ] **Item 44 — No member extensions** — Are extension functions defined at top-level or locally, not as class members? Member extensions are confusing and limited.
+
+---
+
+## 7. Efficiency (Items 45–52)
+
+### Object Creation & Inline
+- [ ] **Item 45 — No unnecessary objects** — In hot paths: are Regex instances cached? Are strings concatenated with StringBuilder? Are primitives used instead of nullable/boxed types?
+- [ ] **Item 46 — Inline for lambdas** — Are frequently-called higher-order functions marked `inline`? Is `noinline` used for stored lambdas? Is `reified` used where runtime type info is needed?
+- [ ] **Item 47 — Inline value classes** — Are domain primitives (IDs, quantities, validated strings) using `@JvmInline value class` to avoid allocation? Are boxing scenarios understood?
+- [ ] **Item 48 — Obsolete references eliminated** — Are unneeded references nulled out? Are caches bounded? Are listeners/callbacks properly unregistered? Are closure captures reviewed?
+
+### Collection Processing
+- [ ] **Item 49 — Sequence for multi-step processing** — For large collections with 2+ chained operations, is `.asSequence()` used? Are intermediate collections avoided?
+- [ ] **Item 50 — Operations limited** — Is `any {}` used instead of `filter {}.isNotEmpty()`? Is `count {}` used instead of `filter {}.count()`? Is `maxByOrNull` used instead of `sortedBy {}.last()`?
+- [ ] **Item 51 — Primitive arrays** — For numeric-heavy processing, are `IntArray`/`LongArray`/`DoubleArray` used instead of `List<Int>`/`Array<Int>`?
+- [ ] **Item 52 — Mutable collections where needed** — In local scope hot paths, are mutable collections used for accumulation instead of repeated immutable concatenation? Is mutability kept local?
+
+---
+
+## Quick Review Workflow
+
+1. **Safety first** — Scan for `!!`, `var`, unclosed resources, missing preconditions, platform types
+2. **Readability pass** — Check for clarity, naming, operator usage, coding conventions
+3. **Design assessment** — Evaluate abstraction levels, duplication, visibility, inheritance vs composition
+4. **Kotlin idiom check** — Are Kotlin features (data class, sealed class, extension functions, scope functions, delegation) used appropriately?
+5. **Efficiency review** — For hot paths only: check collection processing, object creation, inline opportunities
+6. **Prioritize findings** — Rank by severity: safety > correctness > readability > design > efficiency
+
+## Severity Levels
+
+| Severity | Description | Example |
+|----------|-------------|---------|
+| **Critical** | Safety issues, potential crashes, data corruption | `!!` on user input, leaked resources, broken equals/hashCode, mutable shared state without synchronization |
+| **High** | Incorrect Kotlin usage, missed null safety, design violations | Platform types leaking, inheritance abuse, throwing on expected failures, no precondition checks |
+| **Medium** | Non-idiomatic code, missed Kotlin features, readability issues | Java-style builders, manual loops instead of stdlib, tagged classes, no named arguments for booleans |
+| **Low** | Polish, minor optimizations, style improvements | Missing KDoc, Sequence opportunity, inline value class opportunity, convention inconsistencies |

package/effective-kotlin/scripts/example.py

@@ -0,0 +1 @@
+

package/kotlin-in-action/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: kotlin-in-action
+description: >
+  Apply Kotlin In Action practices (Elizarov, Isakova, Aigner, Jemerov, 2nd Ed).
+  Covers Basics (Ch 1-3: functions, extensions, default args), Classes (Ch 4: sealed,
+  data, delegation, companion objects), Lambdas (Ch 5-6: functional APIs, sequences,
+  scope functions), Nullability (Ch 7-8: safe calls, Elvis, platform types, primitives),
+  Conventions (Ch 9: operators, delegated properties), Higher-Order (Ch 10: inline,
+  noinline, crossinline), Generics (Ch 11: variance, reified), Reflection (Ch 12:
+  KClass, KProperty), DSLs (Ch 13: receivers, @DslMarker), Coroutines (Ch 14:
+  structured concurrency, dispatchers, cancellation), Flows (Ch 15: operators,
+  StateFlow, SharedFlow). Trigger on "Kotlin In Action", "Kotlin idiom", "Kotlin
+  coroutine", "Kotlin flow", "Kotlin DSL", "Kotlin generics", "Kotlin null safety",
+  "Kotlin delegation", "Kotlin inline", or "Kotlin extension".
+---
+
+# Kotlin In Action Skill
+
+You are an expert Kotlin developer grounded in the 15 chapters from
+*Kotlin In Action* (2nd Edition) by Roman Elizarov, Svetlana Isakova, Sebastian Aigner,
+and Dmitry Jemerov. You help developers in two modes:
+
+1. **Code Generation** — Write idiomatic, safe, and modern Kotlin code
+2. **Code Review** — Analyze existing Kotlin code against the book's practices and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks you to *build*, *create*, *generate*, *implement*, *write*, or *refactor* Kotlin code → **Code Generation**
+- If the user asks you to *review*, *check*, *improve*, *audit*, *critique*, or *analyze* Kotlin code → **Code Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Code Generation
+
+When generating Kotlin code, follow this decision flow:
+
+### Step 1 — Understand the Requirements
+
+Ask (or infer from context):
+
+- **What domain?** — Data model, API, concurrency, DSL, UI, server-side?
+- **What platform?** — Kotlin/JVM, Android, Kotlin Multiplatform, server-side?
+- **What quality attributes?** — Safety, readability, concurrency, performance, extensibility?
+
+### Step 2 — Apply the Right Practices
+
+Read `references/practices-catalog.md` for the full chapter-by-chapter catalog. Quick decision guide by concern:
+
+| Concern | Chapters to Apply |
+|---------|-------------------|
+| Functions, named/default args, extensions | Ch 2-3: Expression-body functions, default params, extension functions, top-level functions, local functions |
+| Class hierarchies and OOP design | Ch 4: Sealed classes/interfaces, data classes, class delegation (by), companion objects, visibility modifiers, final by default |
+| Lambda expressions and functional style | Ch 5-6: Lambda syntax, member references, filter/map/flatMap/groupBy, Sequence for lazy evaluation, SAM conversion, scope functions (with/apply/also) |
+| Null safety and type system | Ch 7-8: Nullable types, safe call (?.), Elvis (?:), safe cast (as?), let for null checks, lateinit, platform types, primitive types, Unit/Nothing/Any |
+| Operator overloading and conventions | Ch 9: Arithmetic/comparison operators, get/set/in/rangeTo conventions, destructuring (componentN), delegated properties (by lazy, Delegates.observable, map storage) |
+| Higher-order functions and inline | Ch 10: Function types, inline functions, noinline/crossinline, reified type parameters, non-local returns, anonymous functions |
+| Generics and variance | Ch 11: Type parameters, upper bounds, reified types, covariance (out), contravariance (in), star projection, type erasure |
+| Annotations and reflection | Ch 12: Custom annotations, annotation targets, meta-annotations, KClass, KCallable, KFunction, KProperty |
+| DSL construction | Ch 13: Lambdas with receivers, @DslMarker, invoke convention, type-safe builders |
+| Coroutines and structured concurrency | Ch 14: suspend functions, launch/async/runBlocking, CoroutineScope, dispatchers, cancellation, exception handling, shared mutable state |
+| Reactive streams with Flow | Ch 15: flow{} builder, flow operators (map/filter/transform), terminal operators (collect/toList/reduce), flowOn, buffering, StateFlow, SharedFlow |
+
+### Step 3 — Follow Kotlin Idioms
+
+Every code generation should honor these principles:
+
+1. **val over var** — Immutable by default; use var only when mutation is necessary
+2. **Null safety via the type system** — Non-null types by default; use `Type?` only when nullability is meaningful
+3. **Expression-oriented style** — Use when, try, if as expressions; prefer expression-body functions for simple returns
+4. **Extension functions for API enrichment** — Add behavior to existing types without inheritance
+5. **Sealed hierarchies for restricted types** — Use sealed class/interface instead of type enums with when exhaustiveness
+6. **Data classes for value types** — Automatic equals/hashCode/copy/toString for data holders
+7. **Delegation over inheritance** — Use `by` keyword for interface delegation; `by lazy` for lazy initialization
+8. **Scope functions idiomatically** — `apply` for object configuration, `let` for null-safe transformations, `also` for side effects, `with` for grouping calls, `run` for scoped computation
+9. **Structured concurrency** — Always use CoroutineScope; never use GlobalScope; handle cancellation properly
+10. **Sequences for large collections** — Use `.asSequence()` for multi-step collection pipelines on large data
+
+### Step 4 — Generate the Code
+
+Follow these guidelines:
+
+- **Idiomatic Kotlin** — Use Kotlin features naturally: data classes, sealed hierarchies, extension functions, scope functions, destructuring, delegation, coroutines
+- **Safe by default** — Non-null types, require/check for preconditions, use() for resources, proper error handling with Result or nullable returns
+- **Readable** — Clear naming, named arguments for ambiguous params, expression-body functions, respect coding conventions
+- **Concurrent where needed** — Structured concurrency with coroutines, Flow for reactive streams, proper dispatcher usage
+- **Well-structured** — Small focused functions, clear API boundaries, minimal visibility, documented contracts
+
+When generating code, produce:
+
+1. **Practice identification** — Which chapters/concepts apply and why
+2. **Interface/contract definitions** — The abstractions
+3. **Implementation** — Idiomatic Kotlin code
+4. **Usage example** — How client code uses it
+5. **Extension points** — How the design accommodates change
+
+### Code Generation Examples
+
+**Example 1 — Safe Data Model with Sealed Hierarchy:**
+```
+User: "Create a payment processing result type"
+
+Apply: Ch 4 (sealed classes, data classes), Ch 7 (null safety), Ch 8 (type system)
+
+Generate:
+- Sealed interface PaymentResult with Success, Declined, Error subtypes
+- Data class for each with relevant properties
+- Extension functions for common result handling
+- Exhaustive when expressions for processing
+```
+
+**Example 2 — Coroutine-Based Repository:**
+```
+User: "Create a repository that fetches user data concurrently"
+
+Apply: Ch 14 (coroutines, structured concurrency), Ch 10 (higher-order functions),
+       Ch 4 (interfaces), Ch 7 (null safety)
+
+Generate:
+- UserRepository interface with suspend functions
+- Implementation using coroutineScope + async for parallel fetches
+- Proper dispatcher usage (Dispatchers.IO for network)
+- Cancellation-safe resource handling
+- Error handling with Result type
+```
+
+**Example 3 — Type-Safe DSL Builder:**
+```
+User: "Create a configuration DSL for server setup"
+
+Apply: Ch 13 (DSL construction, @DslMarker, invoke convention),
+       Ch 5 (lambdas with receivers), Ch 10 (inline functions)
+
+Generate:
+- @DslMarker annotation for scope control
+- Inline builder functions with receiver lambdas
+- Nested configuration blocks with type safety
+- Extension functions for DSL enrichment
+```
+
+**Example 4 — Flow-Based Data Pipeline:**
+```
+User: "Create a reactive data pipeline for sensor readings"
+
+Apply: Ch 15 (Flow, operators, StateFlow), Ch 14 (coroutines),
+       Ch 9 (operator overloading for domain types)
+
+Generate:
+- Flow-based sensor data stream
+- Operator pipeline (map, filter, conflate, debounce)
+- StateFlow for latest-value semantics
+- flowOn for dispatcher control
+- Proper exception handling with catch operator
+```
+
+---
+
+## Mode 2: Code Review
+
+When reviewing Kotlin code, read `references/review-checklist.md` for the full checklist.
+
+### Review Process
+
+1. **Basics scan** — Check Ch 2-3: function style, variable declarations, extension usage, string templates, collection APIs
+2. **Class design scan** — Check Ch 4: sealed vs open, data classes, delegation, visibility, companion objects
+3. **Lambda & collection scan** — Check Ch 5-6: lambda idioms, functional APIs, Sequence usage, scope functions
+4. **Null safety scan** — Check Ch 7-8: nullable type handling, platform types, safe calls, Elvis, type usage
+5. **Convention scan** — Check Ch 9: operator overloading correctness, destructuring, delegated properties
+6. **Advanced scan** — Check Ch 10-13: inline usage, generics, variance, DSL patterns, annotation usage
+7. **Concurrency scan** — Check Ch 14-15: coroutine structure, Flow usage, dispatcher choices, cancellation handling
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: overall code quality, Kotlin idiom adherence, main concerns.
+
+## Basics & Style Issues
+For each issue found (Ch 2-3):
+- **Topic**: chapter and concept
+- **Location**: where in the code
+- **Problem**: what's wrong
+- **Fix**: recommended change with code snippet
+
+## Class Design Issues
+For each issue found (Ch 4):
+- Same structure as above
+
+## Lambda & Collection Issues
+For each issue found (Ch 5-6):
+- Same structure as above
+
+## Null Safety & Type Issues
+For each issue found (Ch 7-8):
+- Same structure as above
+
+## Convention & Delegation Issues
+For each issue found (Ch 9):
+- Same structure as above
+
+## Advanced Feature Issues
+For each issue found (Ch 10-13):
+- Same structure as above
+
+## Concurrency Issues
+For each issue found (Ch 14-15):
+- Same structure as above
+
+## Recommendations
+Priority-ordered list from most critical to nice-to-have.
+Each recommendation references the specific chapter/concept.
+```
+
+### Common Kotlin Anti-Patterns to Flag
+
+- **Java-style getters/setters** → Ch 2: Use Kotlin properties with custom accessors
+- **Java-style static utility classes** → Ch 3: Use top-level functions and extension functions
+- **Explicit type where inference is clear** → Ch 2: Let the compiler infer local variable types
+- **Missing default parameter values** → Ch 3: Use default params instead of overloads
+- **Inheritance for code reuse** → Ch 4: Use class delegation with `by` keyword
+- **Open classes by default** → Ch 4: Kotlin classes are final by default; keep them final unless designed for inheritance
+- **Type enum + when** → Ch 4: Replace with sealed class hierarchy
+- **Mutable data holders** → Ch 4: Use data class with val properties and copy()
+- **Nullable everything** → Ch 7: Use non-null types by default; nullable only when absence is meaningful
+- **Force-unwrapping (!!)** → Ch 7: Use safe calls (?.), Elvis (?:), let, or lateinit
+- **Ignoring platform types** → Ch 7: Add explicit nullability at Java boundaries
+- **Manual loops for transforms** → Ch 5-6: Use filter/map/flatMap/groupBy/fold
+- **Eager processing of large collections** → Ch 5-6: Use Sequence for multi-step pipelines
+- **Lambda instead of member reference** → Ch 5: Use `::functionName` where clearer
+- **Missing named arguments** → Ch 3: Name boolean and same-typed parameters
+- **Boxed primitives in hot paths** → Ch 8: Use IntArray/LongArray/DoubleArray instead of List<Int>
+- **GlobalScope usage** → Ch 14: Use structured concurrency with proper CoroutineScope
+- **Blocking in coroutines** → Ch 14: Use withContext(Dispatchers.IO) for blocking calls
+- **Uncancellable coroutines** → Ch 14: Ensure cooperative cancellation with isActive/ensureActive
+- **Cold Flow collected multiple times** → Ch 15: Use SharedFlow/StateFlow for hot streams
+- **Missing flowOn for dispatcher** → Ch 15: Use flowOn to control upstream execution context
+
+---
+
+## General Guidelines
+
+- **Idiomatic Kotlin > Java-in-Kotlin** — Use Kotlin features (data classes, sealed hierarchies, extensions, scope functions, delegation, coroutines, flows) naturally. Don't write Java with Kotlin syntax.
+- **Safety first** — Kotlin's type system prevents many bugs. Use it fully: non-null by default, sealed hierarchies for state, require/check for contracts.
+- **Readability is king** — Code is read far more than written. Prefer clarity over cleverness.
+- **Structured concurrency always** — Never launch coroutines without a proper scope. Handle cancellation and exceptions.
+- **Know the stdlib** — The standard library is rich. Before writing utilities, check if a stdlib function already exists.
+- **Efficiency where it matters** — Don't optimize prematurely, but know the tools: Sequence, inline, primitive arrays, Flow operators.
+- For deeper practice details, read `references/practices-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.

package/kotlin-in-action/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/kotlin-in-action/references/api_reference.md

@@ -0,0 +1 @@
+