@booklib/skills 1.0.0

package/kotlin-in-action/references/practices-catalog.md

@@ -0,0 +1,436 @@
+# Kotlin In Action — Practices Catalog
+
+Comprehensive catalog of practices from *Kotlin In Action* (2nd Edition) by Roman Elizarov,
+Svetlana Isakova, Sebastian Aigner, and Dmitry Jemerov, organized by chapter.
+
+---
+
+## Part 1: Introducing Kotlin
+
+### Chapter 1 — Kotlin: What and Why
+
+**1.1 — Statically typed with type inference**
+Kotlin is statically typed but uses extensive type inference to reduce boilerplate. Declare types explicitly only when they add clarity (public APIs, complex expressions).
+
+**1.2 — Multi-paradigm: functional + object-oriented**
+Kotlin supports both functional and OOP styles. Use functional style (immutable data, pure functions, higher-order functions) for data transformations; OOP for domain modeling and encapsulation.
+
+**1.3 — Interoperable with Java**
+Kotlin compiles to JVM bytecode and has seamless Java interop. Call Java from Kotlin and vice versa. Be aware of platform types at boundaries.
+
+**1.4 — Safe by design**
+Kotlin's type system eliminates null pointer exceptions at compile time. Non-null types are the default; nullable types require explicit `?` annotation.
+
+**1.5 — Concise and expressive**
+Kotlin reduces boilerplate through data classes, type inference, default arguments, extension functions, and string templates. Prefer concise idioms over verbose patterns.
+
+---
+
+### Chapter 2 — Kotlin Basics
+
+**2.1 — Functions with expression bodies**
+For simple functions, use expression-body syntax (`= expression`) instead of block bodies with explicit return. This improves readability for one-expression functions.
+
+**2.2 — Variables: val vs var**
+Use `val` (immutable) by default. Use `var` (mutable) only when the value truly needs to change. This communicates intent and prevents accidental mutation.
+
+**2.3 — String templates**
+Use string templates (`"Hello, $name"` or `"Result: ${expr}"`) instead of string concatenation. They're more readable and efficient.
+
+**2.4 — Classes with properties**
+Kotlin classes declare properties directly in the class header or body. The compiler generates getters/setters automatically. Use custom accessors only when needed.
+
+**2.5 — Enum classes with properties and methods**
+Enum classes can have properties, methods, and implement interfaces. Use them for fixed sets of constants with associated behavior.
+
+**2.6 — when expression**
+Use `when` as a more powerful replacement for switch. It works with any type, supports pattern matching with smart casts, and can be used as an expression returning a value.
+
+**2.7 — Smart casts**
+After an `is` check, the compiler automatically casts the variable to the checked type. Combine with `when` for elegant type-based dispatching.
+
+**2.8 — Ranges and progressions**
+Use `..` operator, `downTo`, `step`, and `in` for ranges. Ranges work with any Comparable type. Use `until` for half-open ranges.
+
+**2.9 — Exceptions as expressions**
+`try` is an expression in Kotlin and returns a value. Kotlin has no checked exceptions. Use exceptions for programming errors, not for expected conditions.
+
+---
+
+### Chapter 3 — Defining and Calling Functions
+
+**3.1 — Named arguments**
+Use named arguments for clarity, especially with boolean parameters, multiple parameters of the same type, or when skipping default values. Named arguments serve as self-documentation.
+
+**3.2 — Default parameter values**
+Use default parameter values instead of method overloading. This reduces the number of functions while maintaining flexibility.
+
+**3.3 — Top-level functions and properties**
+Use top-level functions instead of Java-style utility classes with static methods. Top-level properties are useful for constants (`const val`).
+
+**3.4 — Extension functions**
+Add functions to existing classes without modifying them. Extensions are resolved statically (not virtual). Use them to enrich third-party APIs with domain-specific operations.
+
+**3.5 — Extension properties**
+Like extension functions but accessed as properties. Use for computed values that feel natural as properties of the extended type.
+
+**3.6 — Varargs and spread operator**
+Use `vararg` for functions accepting variable numbers of arguments. Use the spread operator (`*`) to pass arrays to vararg parameters.
+
+**3.7 — Infix functions**
+Mark single-parameter member/extension functions with `infix` for natural DSL-like syntax (e.g., `1 to "one"`, `route matches "/api"`).
+
+**3.8 — Destructuring declarations**
+Use destructuring to unpack data classes, maps, and other structures into individual variables. Works with `componentN()` operator functions.
+
+**3.9 — Triple-quoted strings**
+Use triple-quoted strings (`"""..."""`) for multi-line strings, regex patterns, and strings containing special characters. Use `trimMargin()` or `trimIndent()` for clean formatting.
+
+**3.10 — Local functions**
+Define functions inside other functions to encapsulate helper logic and reduce duplication. Local functions have access to the enclosing function's variables.
+
+---
+
+### Chapter 4 — Classes, Objects, and Interfaces
+
+**4.1 — Interfaces with default implementations**
+Kotlin interfaces can have default method implementations and properties (without backing fields). Use interfaces with defaults for mix-in behavior.
+
+**4.2 — Final by default (open/abstract)**
+Classes and methods are `final` by default. Mark as `open` only when designed for inheritance. Use `abstract` for classes that must be subclassed.
+
+**4.3 — Visibility modifiers**
+Kotlin has four visibility levels: `public` (default), `internal` (module), `protected` (subclass), `private` (class/file). Use the most restrictive visibility that works.
+
+**4.4 — Inner vs nested classes**
+Nested classes (default) don't hold a reference to the outer class. Use `inner` only when access to the outer instance is needed. Prefer nested to avoid memory leaks.
+
+**4.5 — Sealed classes and interfaces**
+Use `sealed` for restricted class hierarchies. The compiler enforces exhaustive `when` expressions. Subclasses must be defined in the same package (same file for sealed classes pre-1.5).
+
+**4.6 — Primary constructors and init blocks**
+Use the primary constructor for essential properties. Use `init` blocks for validation logic. Secondary constructors should delegate to the primary.
+
+**4.7 — Data classes**
+Use the `data` modifier for classes that primarily hold data. Automatically generates `equals()`, `hashCode()`, `toString()`, `copy()`, and `componentN()` functions. Use `val` properties.
+
+**4.8 — Class delegation with by**
+Use the `by` keyword to delegate interface implementation to a composed object. This replaces inheritance-based code reuse with composition.
+
+**4.9 — Object declarations (singletons)**
+Use `object` declarations for singletons. They're thread-safe and lazily initialized. Use for stateless utility objects, service locators, or named constants.
+
+**4.10 — Companion objects**
+Use `companion object` for factory methods and constants associated with a class. Companion objects can implement interfaces and have extension functions.
+
+**4.11 — Object expressions (anonymous objects)**
+Use object expressions to create anonymous implementations of interfaces or abstract classes. Unlike Java anonymous classes, they can access and modify local variables.
+
+---
+
+## Part 2: Embracing Kotlin
+
+### Chapter 5 — Programming with Lambdas
+
+**5.1 — Lambda syntax and conventions**
+Lambda expressions use `{ params -> body }` syntax. When a lambda is the last argument, move it outside parentheses. For single-parameter lambdas, use `it`.
+
+**5.2 — Member references**
+Use `::functionName` to pass existing functions as lambdas. Works with top-level functions, member functions, constructors, and extension functions. Prefer references when they're clearer than lambdas.
+
+**5.3 — Functional collection APIs**
+Use `filter`, `map`, `all`, `any`, `count`, `find`, `groupBy`, `flatMap`, `flatten`, `fold`, `reduce`, `associate`, `zip`, `windowed`, `chunked` instead of manual loops. Chain operations for declarative data processing.
+
+**5.4 — Lazy collection operations with Sequences**
+For collections with 2+ chained operations on large data, use `.asSequence()` to avoid creating intermediate collections. Sequences process elements lazily, one at a time.
+
+**5.5 — SAM conversion**
+When calling Java methods expecting single-abstract-method interfaces, pass a lambda directly. Kotlin automatically converts the lambda to the SAM interface. For Kotlin interfaces, use `fun interface`.
+
+**5.6 — Lambdas with receivers (with, apply, also)**
+- `with(obj) { ... }` — Group multiple calls on the same object; returns lambda result
+- `apply { ... }` — Configure an object; returns the receiver
+- `also { ... }` — Perform side effects; returns the receiver
+- `let { ... }` — Transform a value or null-check; returns lambda result
+- `run { ... }` — Scoped computation; returns lambda result
+- `buildString { ... }` — Build strings with StringBuilder receiver
+
+---
+
+### Chapter 6 — Working with Collections and Sequences
+
+**6.1 — Extended collection functional APIs**
+Beyond basic filter/map, use: `associate` for building maps, `groupBy` for categorization, `partition` for splitting by predicate, `zip` for pairing collections, `windowed` and `chunked` for sliding windows.
+
+**6.2 — Sequence operations in depth**
+Sequences have intermediate operations (lazy, return Sequence) and terminal operations (eager, trigger computation). Order matters: put `filter` before `map` to reduce processed elements. Use `generateSequence` for infinite sequences.
+
+---
+
+### Chapter 7 — Working with Nullable Values
+
+**7.1 — Nullable types**
+Append `?` to make a type nullable: `String?`. The compiler enforces null safety: you cannot call methods on nullable types without null checks.
+
+**7.2 — Safe call operator (?.) **
+Use `?.` to call methods on nullable values. Returns null if the receiver is null. Chain safe calls for deep navigation: `person?.address?.city`.
+
+**7.3 — Elvis operator (?:)**
+Use `?:` to provide a default value when an expression is null. Combine with `return` or `throw` for early exits: `val name = input ?: return`.
+
+**7.4 — Safe cast (as?)**
+Use `as?` for safe type casts that return null instead of throwing ClassCastException. Combine with Elvis for safe cast with fallback.
+
+**7.5 — Not-null assertion (!!)**
+Avoid `!!` whenever possible. It converts null to NPE. Use only when you can prove non-nullness but the compiler cannot. Document why it's safe.
+
+**7.6 — let for null checks**
+Use `?.let { ... }` to execute a block only when a value is non-null. The value is available as `it` (non-null) inside the block.
+
+**7.7 — lateinit properties**
+Use `lateinit var` for properties that are initialized after construction (e.g., dependency injection, test setup). Accessing before initialization throws. Cannot be used with primitive types.
+
+**7.8 — Extensions on nullable types**
+Extension functions can be defined on nullable types (e.g., `String?.isNullOrBlank()`). Inside the extension, `this` can be null. Use for utility functions that should handle null gracefully.
+
+**7.9 — Platform types**
+Types from Java without nullability annotations are platform types (`Type!`). They can be treated as nullable or non-null. Always add explicit nullability at Java/Kotlin boundaries to prevent runtime NPEs.
+
+---
+
+### Chapter 8 — Basic Types, Collections, and Arrays
+
+**8.1 — Primitive types**
+Kotlin maps basic types (Int, Long, Double, etc.) to Java primitives when possible. Nullable types (Int?) map to boxed types (Integer). Avoid nullable numeric types in performance-critical code.
+
+**8.2 — Number conversions**
+Kotlin does not auto-widen numbers. Use explicit conversion functions: `toInt()`, `toLong()`, `toDouble()`, etc. This prevents silent precision loss.
+
+**8.3 — Any, Unit, and Nothing**
+- `Any` — Root of the Kotlin type hierarchy (equivalent to Object)
+- `Unit` — Equivalent to void but is an actual type with a single value; use as generic type parameter
+- `Nothing` — No value; used for functions that never return (throw, infinite loop); is a subtype of every type
+
+**8.4 — Read-only vs mutable collections**
+Kotlin distinguishes `Collection` (read-only) from `MutableCollection`. Use read-only collections by default. Expose mutable collections only when mutation is part of the API contract.
+
+**8.5 — Arrays and primitive arrays**
+Use `IntArray`, `LongArray`, `DoubleArray`, etc. for primitive arrays (no boxing). Use `Array<T>` for reference type arrays. Use `intArrayOf()`, `arrayOf()` factory functions. Prefer collections over arrays in most cases.
+
+---
+
+### Chapter 9 — Operator Overloading and Other Conventions
+
+**9.1 — Arithmetic operator overloading**
+Define `plus`, `minus`, `times`, `div`, `rem` as operator functions. Operator meaning must match the conventional mathematical semantics. Can be defined as member or extension functions.
+
+**9.2 — Compound assignment operators**
+`plusAssign`, `minusAssign`, etc. are called for `+=`, `-=`. For mutable collections, these modify in place. For immutable collections, they create new instances.
+
+**9.3 — Unary operators**
+`unaryMinus`, `unaryPlus`, `not`, `inc`, `dec` for unary operations. Use for domain types where these operations have clear mathematical meaning.
+
+**9.4 — Comparison operators**
+Implement `Comparable<T>` to enable `<`, `>`, `<=`, `>=` comparisons. Use `compareValuesBy` for multi-field comparison. `==` calls `equals`, `===` checks reference identity.
+
+**9.5 — Collection conventions (get, set, in, rangeTo)**
+Define `get` operator for index access (`obj[key]`), `set` for mutation (`obj[key] = value`), `contains` for `in` checks, `rangeTo` for `..` operator.
+
+**9.6 — Destructuring declarations**
+Data classes automatically generate `component1()` through `componentN()`. Define `componentN` operators on other classes for destructuring. Works in for loops, lambda parameters, and variable declarations.
+
+**9.7 — Delegated properties**
+Use `by lazy { }` for lazy initialization (thread-safe by default). Use `Delegates.observable` for change notification. Use `by map` for storing properties in maps. Create custom delegates with `ReadOnlyProperty`/`ReadWriteProperty`.
+
+---
+
+### Chapter 10 — Higher-Order Functions: Lambdas as Parameters and Return Values
+
+**10.1 — Function types**
+Kotlin has first-class function types: `(Int, String) -> Boolean`. Use them as parameter types, return types, and variable types. Nullable function types: `((Int) -> Unit)?`.
+
+**10.2 — Calling functions passed as arguments**
+Higher-order functions accept function types as parameters. Use them for strategy pattern, callbacks, and customizable algorithms.
+
+**10.3 — Default values for function type parameters**
+Provide default implementations for function type parameters. This makes higher-order functions flexible without requiring callers to always pass a lambda.
+
+**10.4 — Returning functions**
+Functions can return other functions. Use for factory patterns, partial application, and creating specialized behavior at runtime.
+
+**10.5 — Inline functions**
+Mark higher-order functions as `inline` to eliminate lambda allocation overhead. The compiler inlines both the function body and the lambda at call sites. Use for frequently-called utility functions.
+
+**10.6 — noinline and crossinline**
+Use `noinline` for lambda parameters that should not be inlined (e.g., stored in a variable). Use `crossinline` for lambdas passed to other contexts where non-local returns are not allowed.
+
+**10.7 — Non-local returns**
+In inline functions, `return` inside a lambda returns from the enclosing function (non-local return). Use labeled returns (`return@functionName`) for local returns from lambdas.
+
+**10.8 — Anonymous functions**
+Use anonymous functions (`fun(x: Int): Int { ... }`) when you need local returns without labels. Anonymous functions use `return` to return from themselves, not the enclosing function.
+
+---
+
+### Chapter 11 — Generics
+
+**11.1 — Type parameters and constraints**
+Use generic type parameters for reusable algorithms. Apply upper bounds with `:` to constrain type parameters: `fun <T : Comparable<T>> sort(list: List<T>)`.
+
+**11.2 — Non-null type parameters**
+By default, `<T>` allows nullable types. Use `<T : Any>` to ensure non-null type parameters when null values would be invalid.
+
+**11.3 — Type erasure**
+Generic type information is erased at runtime on JVM. You cannot check `is List<String>` at runtime. Use star projection `is List<*>` for runtime type checks.
+
+**11.4 — Reified type parameters**
+Use `inline fun <reified T>` to preserve type information at runtime. Enables `is T` checks and `T::class` access. Only works with inline functions.
+
+**11.5 — Covariance (out)**
+Use `out` for type parameters that are only produced (returned). A `Producer<out T>` allows `Producer<Cat>` to be used where `Producer<Animal>` is expected. Read-only collections are covariant.
+
+**11.6 — Contravariance (in)**
+Use `in` for type parameters that are only consumed (accepted as arguments). A `Consumer<in T>` allows `Consumer<Animal>` to be used where `Consumer<Cat>` is expected.
+
+**11.7 — Declaration-site vs use-site variance**
+Declare variance at the class level (declaration-site) when it applies everywhere. Use use-site variance (type projection) when variance applies only at specific usage points.
+
+**11.8 — Star projection (*)**
+Use `*` when you don't care about or don't know the type argument. `List<*>` is like `List<out Any?>` — you can read Any? but can't write. Use for runtime type checks.
+
+---
+
+## Part 3: Expanding Kotlin
+
+### Chapter 12 — Annotations and Reflection
+
+**12.1 — Applying annotations**
+Annotations are applied with `@AnnotationName`. Can target classes, functions, properties, parameters, and expressions. Use annotation arguments for configuration.
+
+**12.2 — Annotation targets**
+Use site targets to specify where an annotation applies: `@get:Rule`, `@field:Inject`, `@file:JvmName`. Important for Java interop and annotation processing.
+
+**12.3 — Meta-annotations**
+Annotations on annotations control retention, targets, and repetition. `@Target` specifies allowed elements, `@Retention` controls availability at runtime.
+
+**12.4 — Classes as annotation parameters**
+Use `KClass` parameters in annotations to reference types: `@DeserializeInterface(CompanyImpl::class)`. Access with `::class` syntax.
+
+**12.5 — Kotlin Reflection API**
+Use `KClass` (via `::class` or `javaClass.kotlin`) for runtime class inspection. `KCallable`, `KFunction`, `KProperty` for accessing members. Use for serialization, dependency injection, and framework construction.
+
+**12.6 — Member access with reflection**
+Use `KProperty1<T, R>` for property references, `KFunction` for function references. Access `call()` for invocation, `get()` for property access. Handle visibility with `isAccessible = true`.
+
+---
+
+### Chapter 13 — DSL Construction
+
+**13.1 — From APIs to DSLs**
+DSLs provide more readable, domain-specific syntax than plain API calls. Kotlin's lambdas with receivers enable clean DSL construction. Compare chained method calls vs nested DSL blocks.
+
+**13.2 — Lambdas with receivers in DSLs**
+The receiver type in `T.() -> Unit` makes `this` refer to the receiver inside the lambda. This enables calling methods on the receiver without explicit qualification, creating a natural DSL syntax.
+
+**13.3 — @DslMarker for scope control**
+Use `@DslMarker` meta-annotation to prevent access to outer receivers from inner DSL blocks. This prevents bugs from accidentally calling methods on wrong receiver scopes.
+
+**13.4 — invoke convention in DSLs**
+Define `operator fun invoke()` to make objects callable like functions. Useful for DSL entry points and configurable function objects.
+
+**13.5 — Type-safe builders**
+Build hierarchical structures (HTML, XML, UI layouts) using nested lambdas with receivers. Each builder function creates a child node and adds it to the parent. Combine with extension functions for clean DSL APIs.
+
+---
+
+## Part 4: Kotlin for Concurrency
+
+### Chapter 14 — Structured Concurrency with Coroutines
+
+**14.1 — Coroutines as lightweight threads**
+Coroutines are lightweight, suspendable computations. Thousands can run concurrently without thread overhead. Use `suspend` functions for asynchronous operations.
+
+**14.2 — Coroutine builders**
+- `launch { }` — Fire-and-forget coroutine, returns Job
+- `async { }` — Coroutine with a result, returns Deferred<T>; use `await()` to get result
+- `runBlocking { }` — Bridges regular and coroutine world; blocks the current thread. Use only in main() or tests.
+
+**14.3 — Structured concurrency principles**
+Every coroutine must have a scope (CoroutineScope). Child coroutines are tied to their parent's lifecycle. When a parent is cancelled, all children are cancelled. When a child fails, the parent and siblings are cancelled.
+
+**14.4 — CoroutineScope and context**
+CoroutineScope defines the lifecycle for coroutines. CoroutineContext holds Job, Dispatcher, and other elements. Use `coroutineScope { }` for scoped concurrent operations within suspend functions.
+
+**14.5 — Dispatchers**
+- `Dispatchers.Default` — CPU-intensive work (shared thread pool)
+- `Dispatchers.IO` — Blocking I/O operations (expandable thread pool)
+- `Dispatchers.Main` — UI thread (Android/Swing)
+- `Dispatchers.Unconfined` — Starts in caller thread; resumes in whatever thread. Use with care.
+Use `withContext(dispatcher)` to switch dispatchers within a coroutine.
+
+**14.6 — Exception handling**
+Uncaught exceptions in `launch` propagate to the parent and cancel siblings. Use `CoroutineExceptionHandler` for top-level error handling. `async` stores exceptions and rethrows on `await()`. Use `supervisorScope` to prevent child failure from cancelling siblings.
+
+**14.7 — Cancellation and timeouts**
+Cancellation is cooperative: coroutines must check `isActive` or call suspending functions that check for cancellation. Use `withTimeout(ms)` or `withTimeoutOrNull(ms)` for time-limited operations. Use `ensureActive()` in computation-heavy loops.
+
+**14.8 — Sequential vs concurrent execution**
+By default, suspend function calls are sequential. Use `async { }` to run operations concurrently. Use `coroutineScope { }` + `async { }` for structured concurrent decomposition.
+
+**14.9 — Shared mutable state**
+Coroutines can share mutable state unsafely. Solutions: use thread-safe data structures (`AtomicInteger`, `ConcurrentHashMap`), confine state to a single thread with `newSingleThreadContext`, use `Mutex` for mutual exclusion, or use actors (channel-based).
+
+---
+
+### Chapter 15 — Flows
+
+**15.1 — Cold streams with Flow**
+Flow represents an asynchronous stream of values computed lazily. Unlike sequences, flows support suspension. Flow is cold: the producer code runs only when collected.
+
+**15.2 — Flow builders**
+- `flow { emit(value) }` — General-purpose flow builder with suspend block
+- `flowOf(1, 2, 3)` — Flow from fixed values
+- `.asFlow()` — Convert collections, sequences, or ranges to flows
+
+**15.3 — Flow operators**
+Intermediate operators (return Flow, lazy):
+- `map { }` — Transform each element
+- `filter { }` — Keep elements matching predicate
+- `transform { }` — General transformation; can emit multiple values
+- `take(n)` — Limit to first n elements
+- `drop(n)` — Skip first n elements
+
+**15.4 — Terminal operators**
+Terminal operators (trigger collection, suspend):
+- `collect { }` — Process each emitted value
+- `toList()` / `toSet()` — Collect into a collection
+- `first()` / `single()` — Get first/only element
+- `reduce { }` / `fold { }` — Accumulate values
+
+**15.5 — Flow context and flowOn**
+Flow preserves context: the collector's coroutine context is used by default. Use `flowOn(dispatcher)` to change the upstream execution context. Never use `withContext` inside a flow builder.
+
+**15.6 — Buffering and conflation**
+- `buffer()` — Run collector and emitter concurrently with a buffer
+- `conflate()` — Drop intermediate values when collector is slow
+- `collectLatest { }` — Cancel previous collection when new value arrives
+
+**15.7 — Combining flows**
+- `zip(otherFlow) { a, b -> }` — Pair elements from two flows
+- `combine(otherFlow) { a, b -> }` — Combine latest values from two flows
+
+**15.8 — Flattening flows**
+- `flatMapConcat { }` — Sequentially process inner flows
+- `flatMapMerge { }` — Concurrently process inner flows
+- `flatMapLatest { }` — Cancel previous inner flow on new emission
+
+**15.9 — Exception handling in flows**
+Use `catch { }` operator to handle upstream exceptions declaratively. Use `try/catch` around terminal operators for downstream exceptions. The `catch` operator can emit fallback values.
+
+**15.10 — Flow completion**
+Use `onCompletion { cause -> }` to perform actions when flow completes (normally or with exception). Works as a declarative alternative to try/finally.
+
+**15.11 — StateFlow and SharedFlow**
+- `StateFlow<T>` — Hot flow holding a single updatable value; always has a current value; replays latest to new collectors. Use for state management.
+- `SharedFlow<T>` — Hot flow for broadcasting events to multiple collectors; configurable replay; use for events that shouldn't be missed.
+- Convert cold Flow to SharedFlow with `shareIn(scope, started, replay)` or StateFlow with `stateIn(scope, started, initialValue)`.

package/kotlin-in-action/references/review-checklist.md

@@ -0,0 +1,204 @@
+# Kotlin In Action — Code Review Checklist
+
+Systematic checklist for reviewing Kotlin code against the 15 chapters
+from *Kotlin In Action* (2nd Edition) by Elizarov, Isakova, Aigner, and Jemerov.
+
+---
+
+## 1. Basics & Functions (Chapters 2–3)
+
+### Functions
+- [ ] **Ch 2 — Expression-body functions** — Are simple one-expression functions using `= expr` syntax instead of block bodies with explicit return?
+- [ ] **Ch 2 — val vs var** — Is `val` used by default? Is `var` used only when mutation is genuinely needed?
+- [ ] **Ch 2 — String templates** — Are string templates used instead of string concatenation? Are complex expressions wrapped in `${}`?
+- [ ] **Ch 2 — when expressions** — Are chains of if/else replaced with `when` where appropriate? Is `when` used as an expression to return values?
+- [ ] **Ch 2 — Smart casts** — Are smart casts leveraged after `is` checks instead of explicit casts?
+- [ ] **Ch 2 — Ranges** — Are `..`, `until`, `downTo`, `step` used instead of manual loop bounds?
+- [ ] **Ch 2 — try as expression** — Is `try` used as an expression where appropriate to assign results of error-handling logic?
+
+### Defining and Calling Functions
+- [ ] **Ch 3 — Named arguments** — Are boolean parameters named? Are same-typed adjacent parameters named? Are arguments named when skipping defaults?
+- [ ] **Ch 3 — Default parameter values** — Are default values used instead of function overloads? Are Java-style telescoping constructors replaced?
+- [ ] **Ch 3 — Top-level functions** — Are utility functions defined at top level instead of in Java-style static utility classes?
+- [ ] **Ch 3 — Extension functions** — Are extensions used to enrich existing types? Are they preferred over utility classes? Are they used appropriately (not for core class behavior)?
+- [ ] **Ch 3 — Infix functions** — Are single-parameter functions marked `infix` when it improves readability in DSL contexts?
+- [ ] **Ch 3 — Destructuring** — Are data class results destructured where it improves clarity? Are `_` used for unused components?
+- [ ] **Ch 3 — Local functions** — Are repeated validation/helper patterns extracted into local functions instead of duplicated?
+
+---
+
+## 2. Classes, Objects, and Interfaces (Chapter 4)
+
+### Inheritance Model
+- [ ] **Ch 4 — Final by default** — Are classes kept final unless explicitly designed for inheritance? Is `open` used intentionally?
+- [ ] **Ch 4 — Interface defaults** — Are interface default implementations used for shared behavior across unrelated types?
+- [ ] **Ch 4 — Sealed classes** — Are type hierarchies with fixed variants modeled as sealed classes/interfaces? Do `when` expressions benefit from exhaustiveness?
+- [ ] **Ch 4 — Abstract classes** — Is `abstract` used only for classes that define a template with some implementations?
+
+### Data and Delegation
+- [ ] **Ch 4 — Data classes** — Are data-holding classes using the `data` modifier? Are all properties in the primary constructor `val`? Is `copy()` used instead of mutation?
+- [ ] **Ch 4 — Class delegation (by)** — Is the `by` keyword used instead of inheritance for delegating interface implementation? Is composition preferred over inheritance for code reuse?
+
+### Visibility and Objects
+- [ ] **Ch 4 — Visibility modifiers** — Is the most restrictive visibility used? Is `internal` used for module-private APIs? Are implementation details `private`?
+- [ ] **Ch 4 — Nested vs inner classes** — Are nested classes preferred over `inner` to avoid holding outer references? Is `inner` used only when outer access is needed?
+- [ ] **Ch 4 — Companion objects** — Are companion objects used for factory methods instead of constructors? Do they implement interfaces where useful?
+- [ ] **Ch 4 — Object declarations** — Are singletons implemented with `object` instead of Java-style patterns? Are they used for stateless services and constants?
+
+---
+
+## 3. Lambdas & Collections (Chapters 5–6)
+
+### Lambda Expressions
+- [ ] **Ch 5 — Lambda syntax** — Are lambdas moved outside parentheses when they're the last argument? Is `it` used for single-parameter lambdas? Are multi-line lambdas readable?
+- [ ] **Ch 5 — Member references** — Are `::functionName` references used instead of wrapper lambdas (e.g., `list.map(::transform)` vs `list.map { transform(it) }`)?
+- [ ] **Ch 5 — SAM conversion** — When calling Java APIs expecting SAM interfaces, are lambdas passed directly? For Kotlin, are `fun interface` used for single-method interfaces?
+
+### Collection Processing
+- [ ] **Ch 5 — Functional APIs** — Are `filter`, `map`, `flatMap`, `groupBy`, `associate`, `fold`, `reduce` used instead of manual loops?
+- [ ] **Ch 5-6 — Sequence for large collections** — For 2+ chained operations on large collections, is `.asSequence()` used? Are intermediate collections avoided?
+- [ ] **Ch 6 — Specialized operations** — Is `any {}` used instead of `filter {}.isNotEmpty()`? Is `firstOrNull {}` used instead of `filter {}.firstOrNull()`? Is `count {}` used instead of `filter {}.size`?
+
+### Scope Functions
+- [ ] **Ch 5 — apply for configuration** — Is `apply { }` used for object initialization/configuration blocks?
+- [ ] **Ch 5 — let for null-safe transforms** — Is `?.let { }` used for null-safe transformations instead of if-not-null blocks?
+- [ ] **Ch 5 — also for side effects** — Is `also { }` used for logging/debugging side effects that shouldn't affect the chain?
+- [ ] **Ch 5 — with for grouped calls** — Is `with(obj) { }` used when making multiple calls on the same object?
+- [ ] **Ch 5 — Scope function overuse** — Are scope functions NOT nested excessively? Is readability maintained?
+
+---
+
+## 4. Null Safety & Types (Chapters 7–8)
+
+### Null Handling
+- [ ] **Ch 7 — Safe calls (?.)** — Are safe calls used for nullable navigation instead of explicit null checks? Are they chained for deep access?
+- [ ] **Ch 7 — Elvis (?:)** — Is Elvis used for default values? Is it combined with `return` or `throw` for early exits?
+- [ ] **Ch 7 — No !! (not-null assertion)** — Is `!!` absent or justified with a comment? Are safe alternatives (safe call, Elvis, let, lateinit) used instead?
+- [ ] **Ch 7 — let for null checks** — Is `?.let { }` used appropriately for null-safe blocks? Is it NOT overused where a simple `if` is clearer?
+- [ ] **Ch 7 — lateinit** — Is `lateinit` used for properties initialized after construction (DI, tests)? Is it NOT used where a nullable type or lazy init is more appropriate?
+- [ ] **Ch 7 — Platform types** — At Java/Kotlin boundaries, are types explicitly annotated? Do platform types (`Type!`) NOT leak into Kotlin APIs?
+- [ ] **Ch 7 — Nullable type design** — Are nullable types used only when absence is a meaningful part of the domain? Are non-null types the default?
+
+### Type System
+- [ ] **Ch 8 — Primitive types** — In hot paths, are nullable numeric types avoided to prevent boxing? Are `IntArray`/`LongArray`/`DoubleArray` used instead of `Array<Int>`/`List<Int>`?
+- [ ] **Ch 8 — Number conversions** — Are explicit conversion functions used instead of relying on implicit widening? No silent precision loss?
+- [ ] **Ch 8 — Unit type** — Is `Unit` used correctly as a return type for functions with side effects? Is it used as a generic type argument where needed?
+- [ ] **Ch 8 — Nothing type** — Is `Nothing` used for functions that never return? Are throw expressions and infinite loops typed as Nothing?
+- [ ] **Ch 8 — Read-only collections** — Are read-only collection types (List, Set, Map) used by default? Are mutable collections exposed only when mutation is part of the contract?
+
+---
+
+## 5. Conventions & Delegation (Chapter 9)
+
+- [ ] **Ch 9 — Operator overloading** — Do operator overloads match conventional mathematical/collection semantics? Are operators used only when their meaning is unambiguous in the domain?
+- [ ] **Ch 9 — Comparison via Comparable** — Is `Comparable<T>` implemented for natural ordering? Is `compareValuesBy` used for multi-field comparison?
+- [ ] **Ch 9 — Destructuring** — Are data class results destructured for clarity? Are `componentN` operators defined for non-data classes that benefit from destructuring?
+- [ ] **Ch 9 — by lazy** — Is `by lazy` used for expensive initializations that may not be needed? Is the thread safety mode appropriate (SYNCHRONIZED, PUBLICATION, NONE)?
+- [ ] **Ch 9 — Delegates.observable** — Are change-notification patterns using `Delegates.observable` or `Delegates.vetoable` instead of manual setter logic?
+- [ ] **Ch 9 — Map-backed properties** — For dynamic property storage (e.g., JSON deserialization), are map-delegated properties used?
+- [ ] **Ch 9 — Custom delegates** — For repeated property patterns, are custom property delegates created with `ReadOnlyProperty`/`ReadWriteProperty`?
+
+---
+
+## 6. Higher-Order Functions & Inline (Chapter 10)
+
+- [ ] **Ch 10 — Function types** — Are function types used for callbacks, strategies, and customizable behavior instead of single-method interfaces (in Kotlin code)?
+- [ ] **Ch 10 — Default function parameters** — Do higher-order functions provide sensible default lambdas where appropriate?
+- [ ] **Ch 10 — Inline functions** — Are frequently-called higher-order functions marked `inline`? Is inline NOT used for large function bodies?
+- [ ] **Ch 10 — noinline** — Are lambda parameters that are stored (not immediately invoked) marked `noinline`?
+- [ ] **Ch 10 — crossinline** — Are lambda parameters passed to other execution contexts marked `crossinline`?
+- [ ] **Ch 10 — Non-local returns** — Are non-local returns from inline lambdas used intentionally? Are labeled returns (`return@label`) used when only local return is intended?
+- [ ] **Ch 10 — Anonymous functions** — Are anonymous functions used instead of labeled returns when local returns are frequent?
+
+---
+
+## 7. Generics (Chapter 11)
+
+- [ ] **Ch 11 — Type parameter constraints** — Are upper bounds applied to restrict type parameters? Is `<T : Any>` used when non-null is required?
+- [ ] **Ch 11 — Reified type parameters** — Are inline functions with `reified T` used when runtime type information is needed instead of `Class<T>` parameters?
+- [ ] **Ch 11 — Covariance (out)** — Are type parameters that are only produced marked `out`? Are read-only interfaces covariant?
+- [ ] **Ch 11 — Contravariance (in)** — Are type parameters that are only consumed marked `in`?
+- [ ] **Ch 11 — Star projection** — Is `*` used for runtime type checks and when the specific type argument doesn't matter?
+- [ ] **Ch 11 — Type erasure awareness** — Is code aware that generic type information is erased at runtime? No runtime `is List<String>` checks?
+
+---
+
+## 8. Annotations & Reflection (Chapter 12)
+
+- [ ] **Ch 12 — Annotation targets** — Are annotation site targets (`@get:`, `@field:`, `@file:`) used correctly for Java interop?
+- [ ] **Ch 12 — Meta-annotations** — Are custom annotations properly annotated with `@Target` and `@Retention`?
+- [ ] **Ch 12 — Reflection usage** — Is reflection used sparingly and only where compile-time alternatives are insufficient? Is the Kotlin reflection API (`KClass`, `KProperty`) used instead of Java reflection?
+
+---
+
+## 9. DSL Construction (Chapter 13)
+
+- [ ] **Ch 13 — Lambdas with receivers** — Are DSL builder functions using receiver lambdas (`T.() -> Unit`) for natural syntax?
+- [ ] **Ch 13 — @DslMarker** — Is `@DslMarker` used to prevent outer receiver access from inner DSL blocks?
+- [ ] **Ch 13 — invoke convention** — Is the `invoke` operator used appropriately for callable objects in DSL contexts?
+- [ ] **Ch 13 — Type-safe builders** — Are hierarchical structures built with type-safe builder patterns? Is the builder pattern correct and not leaking mutable state?
+
+---
+
+## 10. Coroutines (Chapter 14)
+
+### Structure
+- [ ] **Ch 14 — Structured concurrency** — Are all coroutines launched within a proper CoroutineScope? Is GlobalScope avoided? Do parent-child relationships hold?
+- [ ] **Ch 14 — Coroutine builders** — Is `launch` used for fire-and-forget, `async` for results, `runBlocking` only in main/tests?
+- [ ] **Ch 14 — coroutineScope** — Is `coroutineScope { }` used in suspend functions to create structured scopes for parallel decomposition?
+
+### Dispatchers
+- [ ] **Ch 14 — Dispatcher selection** — Is `Dispatchers.Default` used for CPU work, `Dispatchers.IO` for blocking I/O, `Dispatchers.Main` for UI? Is `withContext` used to switch?
+- [ ] **Ch 14 — No blocking in Default** — Are blocking operations NOT running on `Dispatchers.Default`? Are they wrapped in `withContext(Dispatchers.IO)`?
+
+### Error Handling & Cancellation
+- [ ] **Ch 14 — Exception handling** — Are exceptions handled properly? Is `CoroutineExceptionHandler` used at top level? Is `supervisorScope` used when child failures should be independent?
+- [ ] **Ch 14 — Cancellation cooperation** — Do long-running coroutines check `isActive` or call `ensureActive()`? Are cancellation exceptions not swallowed?
+- [ ] **Ch 14 — Timeouts** — Is `withTimeout` or `withTimeoutOrNull` used for time-limited operations?
+
+### Shared State
+- [ ] **Ch 14 — Thread safety** — Is shared mutable state protected? Are `Mutex`, atomic types, or single-thread confinement used? No unprotected shared vars across coroutines?
+
+---
+
+## 11. Flows (Chapter 15)
+
+### Flow Basics
+- [ ] **Ch 15 — Flow builders** — Are `flow {}`, `flowOf()`, or `.asFlow()` used appropriately? Is `flow {}` used for suspend-based emission?
+- [ ] **Ch 15 — Flow context** — Is `flowOn` used to change upstream context instead of `withContext` inside flow builders?
+- [ ] **Ch 15 — Cold vs hot** — Are cold Flows used for on-demand data? Are StateFlow/SharedFlow used for state and events?
+
+### Operators
+- [ ] **Ch 15 — Intermediate operators** — Are `map`, `filter`, `transform`, `take`, `drop` used instead of manual collection loops?
+- [ ] **Ch 15 — Terminal operators** — Is `collect` used for side effects, `toList`/`toSet` for materialization, `first`/`reduce`/`fold` for aggregation?
+- [ ] **Ch 15 — Buffering** — Is `buffer()` used when collector is slower than emitter? Is `conflate()` used when only latest value matters?
+
+### Error Handling & Completion
+- [ ] **Ch 15 — catch operator** — Is `catch { }` used for upstream exception handling? Are downstream exceptions handled with try/catch around terminal operators?
+- [ ] **Ch 15 — onCompletion** — Is `onCompletion { }` used for cleanup and finalization logic?
+
+### Hot Flows
+- [ ] **Ch 15 — StateFlow** — Is `StateFlow` used for observable state with a current value? Is `value` property used for synchronous access?
+- [ ] **Ch 15 — SharedFlow** — Is `SharedFlow` used for broadcasting events? Is replay configured appropriately?
+- [ ] **Ch 15 — shareIn/stateIn** — Are cold flows converted to hot flows with proper `SharingStarted` strategy (Eagerly, Lazily, WhileSubscribed)?
+
+---
+
+## Quick Review Workflow
+
+1. **Basics pass** — Scan for Java-style code: utility classes, getter/setter methods, missing named args, string concatenation, manual loops
+2. **Class design pass** — Check for proper sealed hierarchies, data classes, delegation, visibility, final by default
+3. **Null safety pass** — Hunt for `!!`, unchecked platform types, nullable types where non-null works, missing safe calls
+4. **Collection pass** — Check for Sequence usage on large pipelines, proper functional APIs, scope function clarity
+5. **Concurrency pass** — Verify structured concurrency, proper dispatchers, cancellation cooperation, shared state protection
+6. **Flow pass** — Check for correct Flow usage, hot vs cold, buffering, exception handling, context preservation
+7. **Prioritize findings** — Rank by severity: concurrency bugs > null safety > class design > idioms > style
+
+## Severity Levels
+
+| Severity | Description | Example |
+|----------|-------------|---------|
+| **Critical** | Concurrency bugs, null safety violations, resource leaks | Unprotected shared state in coroutines, `!!` on user input, GlobalScope usage in production, missing cancellation cooperation |
+| **High** | Incorrect Kotlin usage, missed type safety, structural issues | Platform types leaking, eager collection processing on large data, blocking on Default dispatcher, missing structured concurrency |
+| **Medium** | Non-idiomatic code, missed Kotlin features, readability issues | Java-style utility classes, manual loops instead of functional APIs, inheritance instead of delegation, missing named arguments |
+| **Low** | Polish, minor optimizations, style improvements | Missing destructuring, sequence opportunity, infix function opportunity, scope function preference |

package/kotlin-in-action/scripts/example.py

@@ -0,0 +1 @@
+