@booklib/skills 1.0.0

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

@@ -0,0 +1,216 @@
+# Effective Java Code Review Checklist
+
+Use this checklist when reviewing Java code. Work through each section and flag any
+violations. Not every section applies to every review — skip sections that aren't
+relevant to the code under review.
+
+---
+
+## 1. Object Creation
+
+- [ ] Static factory methods used where beneficial (named construction, caching, return subtypes)
+- [ ] Builder pattern used for classes with many optional parameters
+- [ ] Singleton enforcement is correct (enum type or private constructor with static field)
+- [ ] Utility classes have private constructor to prevent instantiation
+- [ ] Dependencies are injected, not hardwired to concrete implementations
+- [ ] No unnecessary object creation (cached patterns, primitive vs boxed in loops)
+- [ ] Obsolete object references are nulled out (custom collections, caches, listeners)
+- [ ] try-with-resources used for all AutoCloseable objects
+- [ ] No finalizers or cleaners (except as safety nets for native resources)
+
+**Red flags**: Telescoping constructors with 4+ parameters. `new String("literal")`.
+`Long sum = 0L` in a loop. Resources closed in finally blocks instead of
+try-with-resources. Finalizer or cleaner used for non-native resource cleanup.
+
+---
+
+## 2. Methods Common to All Objects
+
+- [ ] `equals` override obeys the contract (reflexive, symmetric, transitive, consistent)
+- [ ] `hashCode` is overridden whenever `equals` is overridden
+- [ ] `toString` provides useful diagnostic information
+- [ ] `clone` is avoided in favor of copy constructors or copy factories
+- [ ] `Comparable` is implemented where natural ordering exists
+- [ ] Comparators don't use subtraction (overflow risk)
+
+**Red flags**: `equals` that breaks symmetry (subclass vs superclass). Missing `hashCode`
+override causing HashMap failures. `Cloneable` implemented on new classes. Comparator
+using `return o1.val - o2.val` (integer overflow).
+
+---
+
+## 3. Class Design
+
+- [ ] Classes and members have minimal accessibility (private > package-private > protected > public)
+- [ ] Instance fields are never public (use accessors)
+- [ ] Classes are immutable where possible (final fields, no setters, final class or private constructor)
+- [ ] Composition is used instead of inheritance across package boundaries
+- [ ] Classes designed for inheritance document self-use of overridable methods
+- [ ] Classes not designed for inheritance are final or have private constructors
+- [ ] Interfaces are used to define types, not for constants
+- [ ] Tagged classes are refactored into class hierarchies
+- [ ] Inner classes are static unless they need an enclosing instance reference
+- [ ] One top-level class per source file
+
+**Red flags**: Public mutable fields. Concrete class extended across package boundary
+without documentation of overridable method self-use. Non-static inner class in a
+long-lived object (hidden reference causes memory leak). Constant interface
+(`interface Constants { int FOO = 1; }`).
+
+---
+
+## 4. Generics
+
+- [ ] No raw types anywhere in the codebase
+- [ ] All unchecked warnings are eliminated or suppressed with justification
+- [ ] Lists preferred over arrays for generic collections
+- [ ] Types and methods are generic where appropriate
+- [ ] Bounded wildcards used per PECS (Producer-Extends, Consumer-Super)
+- [ ] `@SafeVarargs` used correctly on generic varargs methods
+- [ ] No wildcards on return types
+
+**Red flags**: `List` instead of `List<String>`. `@SuppressWarnings("unchecked")` on a
+large scope without comment. `E[]` used where `List<E>` would be safer. Missing
+wildcards on API parameters that accept subtypes.
+
+---
+
+## 5. Enums and Annotations
+
+- [ ] Enums used instead of `int` or `String` constants
+- [ ] Enum values don't derive from `ordinal()` — instance fields used instead
+- [ ] `EnumSet` used instead of bit fields
+- [ ] `EnumMap` used instead of ordinal-indexed arrays
+- [ ] `@Override` annotation present on all overriding methods
+- [ ] Annotations used instead of naming patterns
+
+**Red flags**: `public static final int SEASON_WINTER = 0`. Calling `ordinal()` to
+derive a value. `int` flags combined with bitwise OR instead of `EnumSet`. Array
+indexed by `enum.ordinal()`.
+
+---
+
+## 6. Lambdas and Streams
+
+- [ ] Lambdas used instead of anonymous classes for functional interfaces
+- [ ] Method references used where clearer than lambdas
+- [ ] Standard functional interfaces from `java.util.function` used before custom ones
+- [ ] Streams used judiciously (not forced where loops are clearer)
+- [ ] Stream operations are side-effect-free (no mutation in `forEach` used for computation)
+- [ ] `Collection` returned from APIs instead of `Stream`
+- [ ] Parallel streams used only with appropriate data structures and verified speedup
+
+**Red flags**: Long, complex lambdas (should be extracted to methods). `forEach` used
+for computation instead of collect/reduce. `Stream.parallel()` on `LinkedList` or
+`Stream.iterate`. Stream pipeline with side effects on shared mutable state.
+
+---
+
+## 7. Method Design
+
+- [ ] Parameters validated at method entry (`Objects.requireNonNull`, bounds checks)
+- [ ] Defensive copies made of mutable input parameters (copy before validation)
+- [ ] Method signatures have ≤4 parameters (or use helper classes / Builder)
+- [ ] No confusing overloads (same number of parameters with different behavior)
+- [ ] Varargs methods require at least one argument where needed
+- [ ] Empty collections/arrays returned instead of null
+- [ ] `Optional` used appropriately for absent return values (not for fields/parameters/collections)
+- [ ] All exported API elements have doc comments
+
+**Red flags**: Missing null check that leads to NPE deep in call stack. Mutable
+`Date`/`Calendar` parameter stored directly without copy. Method returning `null`
+instead of `Collections.emptyList()`. `Optional.get()` without presence check.
+Overloaded methods with same arity causing dispatch surprises.
+
+---
+
+## 8. General Programming
+
+- [ ] Local variables declared at point of first use with minimal scope
+- [ ] For-each loops used wherever applicable
+- [ ] Standard library methods used instead of hand-rolled equivalents
+- [ ] `BigDecimal` or `int`/`long` used for monetary calculations (not `float`/`double`)
+- [ ] Primitive types preferred over boxed primitives
+- [ ] Strings not used as substitutes for other types (enums, aggregates, capabilities)
+- [ ] `StringBuilder` used for string concatenation in loops
+- [ ] Objects referred to by interface types where appropriate
+- [ ] Reflection avoided except for class instantiation via interfaces
+- [ ] Naming conventions followed (camelCase methods, UPPER_SNAKE constants, etc.)
+
+**Red flags**: `double` used for currency. `String` concatenation with `+` inside a loop
+building large output. `==` applied to boxed primitives. Hand-rolled sorting or data
+structure instead of using `java.util` classes. Variable declared far from use with
+wide scope.
+
+---
+
+## 9. Exceptions
+
+- [ ] Exceptions used only for exceptional conditions (not control flow)
+- [ ] Checked exceptions for recoverable conditions, runtime for programming errors
+- [ ] Unnecessary checked exceptions eliminated (consider Optional or method splitting)
+- [ ] Standard exceptions reused (`IllegalArgumentException`, `NullPointerException`, etc.)
+- [ ] Exceptions translated at abstraction boundaries (with chaining)
+- [ ] All exceptions documented with `@throws`
+- [ ] Exception detail messages include failure-capture information
+- [ ] Methods are failure-atomic (object state unchanged on failure)
+- [ ] No empty catch blocks (if intentionally ignored, document why and use `ignored` variable name)
+
+**Red flags**: `try { ... } catch (Exception e) { }` (swallowed exception). Exception
+used for flow control (`try { array[i++] } catch (AIOOBE)`). Method declares
+`throws Exception`. Low-level `SQLException` propagated through business logic instead
+of translated.
+
+---
+
+## 10. Concurrency
+
+- [ ] Shared mutable data is properly synchronized or volatile
+- [ ] Minimal work done inside synchronized regions
+- [ ] No alien method calls within synchronized blocks
+- [ ] `ExecutorService` used instead of raw `Thread` management
+- [ ] `java.util.concurrent` utilities preferred over `wait`/`notify`
+- [ ] Thread safety level documented on every class
+- [ ] Lazy initialization used only when necessary, with correct idiom
+- [ ] No dependence on thread scheduler behavior (`Thread.yield`, priorities)
+
+**Red flags**: Non-volatile field used as stop flag across threads. Long computation
+inside synchronized block. `wait()` without loop. `new Thread(runnable).start()` instead
+of executor. Missing thread safety documentation. Single-check idiom used where
+double-check is required.
+
+---
+
+## 11. Serialization
+
+- [ ] Java serialization avoided (JSON, protobuf, or other formats preferred)
+- [ ] If Serializable: considered impact on flexibility and security
+- [ ] If Serializable: custom serialized form used where default is inappropriate
+- [ ] If Serializable: `readObject` validates defensively like a constructor
+- [ ] If Serializable: enum types preferred for instance-controlled classes
+- [ ] If Serializable: serialization proxy pattern considered
+- [ ] No deserialization of untrusted data
+
+**Red flags**: `ObjectInputStream.readObject()` on untrusted input. Default serialized
+form exposing internal representation. `readObject` that doesn't validate or make
+defensive copies. Non-enum singleton implementing `Serializable` without `readResolve`
+or serialization proxy.
+
+---
+
+## Severity Classification
+
+When reporting issues, classify them:
+
+- **Critical**: Bug, security vulnerability, or data corruption risk
+  (e.g., missing synchronization on shared mutable data, deserializing untrusted data,
+  broken equals/hashCode contract, empty catch block hiding failures)
+- **Major**: Significant design debt or maintenance burden
+  (e.g., concrete class inheritance, raw types, mutable class that should be immutable,
+  telescoping constructors, checked exceptions that should be unchecked)
+- **Minor**: Best practice deviation with limited immediate impact
+  (e.g., missing @Override, toString not implemented, unnecessary object creation,
+  for-loop instead of for-each)
+- **Suggestion**: Improvement that would be nice but isn't urgent
+  (e.g., consider Builder for future extensibility, evaluate switching to Optional
+  return type, document thread safety level)

package/effective-java/scripts/example.py

@@ -0,0 +1 @@
+

package/effective-kotlin/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: effective-kotlin
+description: >
+  Apply Effective Kotlin best practices (Marcin Moskała, 2nd Ed). Covers Safety
+  (Items 1-10: mutability, scope, nulls, types, expectations, errors, resources,
+  tests), Readability (Items 11-18: operators, receivers, properties, naming),
+  Reusability (Items 19-25: DRY, generics, delegation, variance), Abstraction
+  (Items 26-32: levels, stability, visibility, contracts), Object Creation
+  (Items 33-35: factories, constructors, DSLs), Class Design (Items 36-44:
+  composition, data classes, sealed hierarchies, equals/hashCode/compareTo,
+  extensions), Efficiency (Items 45-52: object creation, inline, sequences,
+  collections). Trigger on "Effective Kotlin", "Kotlin best practice",
+  "Kotlin idiom", "Kotlin style", "Kotlin review", "Kotlin safety",
+  "Kotlin performance", "Kotlin readability", or "Kotlin design".
+---
+
+# Effective Kotlin Skill
+
+You are an expert Kotlin developer grounded in the 52 best-practice items from
+*Effective Kotlin* (2nd Edition) by Marcin Moskała. You help developers in two modes:
+
+1. **Code Generation** — Write idiomatic, safe, readable, and efficient Kotlin code
+2. **Code Review** — Analyze existing Kotlin code against the 52 items 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, UI, concurrency, DSL?
+- **What constraints?** — Kotlin/JVM, Kotlin Multiplatform, Android, server-side?
+- **What quality attributes?** — Safety, readability, performance, extensibility?
+
+### Step 2 — Apply the Right Practices
+
+Read `references/practices-catalog.md` for the full 52-item catalog. Quick decision guide by concern:
+
+| Concern | Items to Apply |
+|---------|---------------|
+| Preventing null / type errors | Items 3-8: Eliminate platform types, don't expose inferred types, prefer null/Failure, handle nulls properly |
+| Limiting mutability and scope | Items 1-2: Limit mutability (val, immutable collections, data class copy), minimize variable scope |
+| Error handling and validation | Items 5-7: Use require/check/assert, prefer standard errors, prefer null or Failure result type |
+| Resource management | Item 9: Close resources with use() |
+| Readable and maintainable code | Items 11-18: Design for readability, meaningful operators, explicit types when unclear, named arguments, coding conventions |
+| Avoiding duplication | Items 19-22: DRY, use stdlib algorithms, property delegation, generics for common algorithms |
+| API and abstraction design | Items 26-32: Single abstraction level, protect against changes, API stability, wrap external APIs, minimize visibility, document contracts |
+| Object creation | Items 33-35: Factory functions, primary constructor with named optional args, DSL for complex creation |
+| Class and type design | Items 36-44: Composition over inheritance, data modifier, function types, sealed hierarchies, equals/hashCode/compareTo contracts, extensions |
+| Performance | Items 45-52: Avoid unnecessary object creation, inline functions, inline value classes, eliminate obsolete references, Sequence, limit operations, primitive arrays, mutable collections |
+| Testing | Item 10: Write unit tests |
+
+### Step 3 — Follow Kotlin Idioms
+
+Every code generation should honor these principles:
+
+1. **Limit mutability** — Use val, immutable collections, data class copy() instead of mutable state
+2. **Minimize scope** — Declare variables in the narrowest scope; prefer local over property, private over public
+3. **Favor composition over inheritance** — Use delegation, interface composition, and HAS-A relationships
+4. **Program to interfaces** — Depend on abstractions; return interface types from functions
+5. **Use Kotlin's type system** — Sealed classes for restricted hierarchies, value classes for type-safe wrappers, nullability for optional values
+6. **Be explicit when clarity demands it** — Explicit types for public APIs, named arguments for boolean/numeric params, explicit receivers in scoping functions
+7. **Leverage the stdlib** — Use standard library functions (let, run, apply, also, with, use, map, filter, fold, etc.) idiomatically
+8. **Design for extension** — Use sealed interfaces, function types as parameters, and extension functions for non-essential API parts
+
+### Step 4 — Generate the Code
+
+Follow these guidelines:
+
+- **Idiomatic Kotlin** — Use Kotlin features naturally: data classes, sealed hierarchies, extension functions, scope functions, destructuring, delegation
+- **Safe by default** — Non-null types by default, require/check for preconditions, use() for resources, proper error handling
+- **Readable** — Clear naming, named arguments for ambiguous params, single-level-of-abstraction functions, respect coding conventions
+- **Efficient where it matters** — Sequence for multi-step collection processing, inline for lambdas, value classes for wrappers, primitive arrays for hot paths
+- **Well-structured** — Small focused functions, clear API boundaries, minimal visibility, documented contracts
+
+When generating code, produce:
+
+1. **Practice identification** — Which items 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 API Design:**
+```
+User: "Create a user repository with proper error handling"
+
+Apply: Items 1 (limit mutability), 5 (require/check), 6 (standard errors),
+       7 (Result type), 9 (use for resources), 30 (minimize visibility),
+       33 (factory function), 34 (named optional args)
+
+Generate:
+- Sealed interface for UserError (NotFound, Duplicate, ValidationFailed)
+- User data class with validated construction via companion factory
+- UserRepository interface returning Result types
+- Implementation with require() preconditions, use() for resources
+- Private mutable state, public immutable view
+```
+
+**Example 2 — Collection Processing Pipeline:**
+```
+User: "Process a large CSV of transactions for reporting"
+
+Apply: Items 49 (Sequence for big collections), 50 (limit operations),
+       51 (primitive arrays for numeric), 20 (stdlib algorithms),
+       37 (data class for records)
+
+Generate:
+- Transaction data class with proper parsing
+- Sequence-based pipeline for lazy processing
+- Efficient aggregation using fold/groupBy
+- Primitive arrays for numeric accumulation in hot path
+```
+
+**Example 3 — DSL Builder:**
+```
+User: "Create a type-safe HTML DSL"
+
+Apply: Items 35 (DSL for complex creation), 15 (explicit receivers),
+       22 (generics), 46 (inline for lambda params)
+
+Generate:
+- @DslMarker annotation for scope control
+- Inline builder functions with receiver lambdas
+- Type-safe tag hierarchy using sealed classes
+- Extension functions for tag creation
+```
+
+---
+
+## Mode 2: Code Review
+
+When reviewing Kotlin code, read `references/review-checklist.md` for the full checklist.
+
+### Review Process
+
+1. **Safety scan** — Check Items 1-10: mutability, null handling, platform types, error handling, resource management, testing
+2. **Readability scan** — Check Items 11-18: operator overloading, type clarity, receiver usage, property vs function, naming, conventions
+3. **Design scan** — Check Items 19-44: duplication, abstraction levels, API design, visibility, class design, inheritance vs composition
+4. **Efficiency scan** — Check Items 45-52: unnecessary allocations, inline opportunities, collection processing efficiency
+5. **Cross-cutting concerns** — Testability, API stability, contract documentation
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: overall code quality, key Kotlin idiom adherence, main concerns.
+
+## Safety Issues
+For each issue found (Items 1-10):
+- **Item**: number and name
+- **Location**: where in the code
+- **Problem**: what's wrong
+- **Fix**: recommended change with code snippet
+
+## Readability Issues
+For each issue found (Items 11-18):
+- Same structure as above
+
+## Design Issues
+For each issue found (Items 19-44):
+- Same structure as above
+
+## Efficiency Issues
+For each issue found (Items 45-52):
+- Same structure as above
+
+## Recommendations
+Priority-ordered list from most critical to nice-to-have.
+Each recommendation references the specific Item number.
+```
+
+### Common Kotlin Anti-Patterns to Flag
+
+- **Mutable where immutable works** → Item 1: Use val, immutable collections, copy()
+- **Overly broad variable scope** → Item 2: Move declarations closer to usage
+- **Platform types leaking** → Item 3: Add explicit nullability annotations at Java boundaries
+- **Exposed inferred types** → Item 4: Declare explicit return types on public functions
+- **Missing precondition checks** → Item 5: Add require() for arguments, check() for state
+- **Custom exception hierarchies** → Item 6: Prefer IllegalArgumentException, IllegalStateException, etc.
+- **Throwing on expected failures** → Item 7: Return null or Result instead
+- **Force-unwrapping nulls (!!)** → Item 8: Use safe calls, Elvis, smart casting, lateinit
+- **Unclosed resources** → Item 9: Use use() or useLines()
+- **No tests** → Item 10: Add unit tests
+- **Clever but unreadable code** → Item 11: Simplify, prefer clarity
+- **Meaningless operator overloading** → Item 12: Operator meaning must match function name convention
+- **Properties with side effects** → Item 16: Properties for state, functions for behavior
+- **Magic numbers / unnamed booleans** → Item 17: Use named arguments
+- **Copy-pasted logic** → Item 19: Extract shared logic, respect DRY
+- **Hand-rolled stdlib algorithms** → Item 20: Use existing stdlib functions
+- **Deep inheritance for code reuse** → Item 36: Prefer composition and delegation
+- **Tagged class with type enum** → Item 39: Replace with sealed class hierarchy
+- **Broken equals/hashCode** → Items 40-41: Ensure contract compliance
+- **Member extensions** → Item 44: Avoid; use top-level or local extensions
+- **Unnecessary object creation in loops** → Item 45: Cache, reuse, use primitives
+- **Lambda overhead in hot paths** → Item 46: Use inline modifier
+- **Eager collection processing on large data** → Item 49: Switch to Sequence
+- **Redundant collection operations** → Item 50: Combine or use specialized functions (any vs filter+isEmpty)
+
+---
+
+## General Guidelines
+
+- Be practical — Kotlin is designed for pragmatic developers. Don't over-abstract or over-engineer.
+- **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.
+- **Idiomatic Kotlin > Java-in-Kotlin** — Use data classes, extension functions, scope functions, destructuring, delegation, sequences. Don't write Java with Kotlin syntax.
+- **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: inline, Sequence, value classes, primitive arrays.
+- For deeper practice details, read `references/practices-catalog.md` before generating code.
+- For review checklists, read `references/review-checklist.md` before reviewing code.

package/effective-kotlin/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/effective-kotlin/references/api_reference.md

@@ -0,0 +1 @@
+