@booklib/skills 1.2.0 → 1.3.0

package/effective-python/scripts/lint.py

@@ -0,0 +1,173 @@
+#!/usr/bin/env python3
+"""
+lint.py — Ruff linter tuned to Effective Python items.
+Usage: python lint.py <path>
+
+Runs ruff with rules that map directly to Effective Python advice,
+then annotates each violation with the relevant item number and title.
+"""
+
+import json
+import subprocess
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+# Maps ruff rule code prefixes/exact codes -> (Item number, short description)
+RULE_TO_ITEM = {
+    "E711": ("Item 2",  "PEP 8: use 'is None' / 'is not None', not == None"),
+    "E712": ("Item 2",  "PEP 8: use 'is True' / 'is False', not == True/False"),
+    "B006": ("Item 24", "Avoid mutable default arguments"),
+    "B007": ("Item 7",  "Unused loop variable — use _ for throwaway"),
+    "B008": ("Item 24", "Do not call mutable objects as default arguments"),
+    "C400": ("Item 27", "Rewrite map() as a list comprehension"),
+    "C401": ("Item 27", "Rewrite set() with a comprehension"),
+    "C402": ("Item 27", "Rewrite dict() with a dict comprehension"),
+    "C403": ("Item 27", "Rewrite list() with a list comprehension"),
+    "C404": ("Item 27", "Rewrite list of tuples as dict comprehension"),
+    "C405": ("Item 27", "Rewrite set literal — unnecessary literal call"),
+    "C406": ("Item 27", "Rewrite dict literal — unnecessary literal call"),
+    "C408": ("Item 27", "Rewrite dict()/list()/tuple() with literal"),
+    "C409": ("Item 28", "Unnecessary literal in tuple()"),
+    "C410": ("Item 28", "Unnecessary literal in list()"),
+    "C411": ("Item 27", "Unnecessary list() call"),
+    "C413": ("Item 27", "Unnecessary list/reversed() around sorted()"),
+    "C414": ("Item 27", "Unnecessary double cast in comprehension"),
+    "C415": ("Item 29", "Unnecessary subscript reversal in comprehension"),
+    "C416": ("Item 27", "Unnecessary list comprehension — use list()"),
+    "C417": ("Item 27", "Unnecessary map() — use generator/comprehension"),
+    "SIM101": ("Item 7",  "Merge duplicate isinstance() checks with tuple"),
+    "SIM102": ("Item 7",  "Collapse nested if into single if"),
+    "SIM103": ("Item 7",  "Return condition directly, not if/else True/False"),
+    "SIM105": ("Item 35", "Use contextlib.suppress instead of try/except/pass"),
+    "SIM108": ("Item 7",  "Use ternary operator instead of if/else block"),
+    "SIM110": ("Item 27", "Use comprehension instead of for-loop with append"),
+    "SIM115": ("Item 66", "Use context manager for open()"),
+    "SIM117": ("Item 66", "Merge nested with statements"),
+    "UP001": ("Item 2",  "pyupgrade: use modern Python syntax"),
+    "UP003": ("Item 2",  "pyupgrade: use type() instead of deprecated form"),
+    "UP006": ("Item 90", "Use 'list' instead of 'List' for type hints (3.9+)"),
+    "UP007": ("Item 90", "Use 'X | Y' instead of 'Optional[X]' (3.10+)"),
+    "UP008": ("Item 90", "Use 'super()' without arguments"),
+    "UP009": ("Item 2",  "pyupgrade: UTF-8 encoding declaration unnecessary"),
+    "UP010": ("Item 2",  "pyupgrade: unnecessary __future__ import"),
+    "UP032": ("Item 4",  "Use f-string instead of .format()"),
+    "UP034": ("Item 2",  "pyupgrade: extraneous parentheses"),
+}
+
+RUFF_CONFIG = textwrap.dedent("""\
+    [lint]
+    select = [
+        "E711", "E712",
+        "B006", "B007", "B008",
+        "C4",
+        "SIM",
+        "UP",
+    ]
+    ignore = []
+""")
+
+
+def find_item(code: str):
+    if code in RULE_TO_ITEM:
+        return RULE_TO_ITEM[code]
+    # Try prefix match (e.g. SIM, UP, C4xx)
+    for prefix_len in (5, 4, 3, 2):
+        prefix = code[:prefix_len]
+        if prefix in RULE_TO_ITEM:
+            return RULE_TO_ITEM[prefix]
+    return None
+
+
+def run_ruff(target: Path, config_path: Path):
+    cmd = [
+        "ruff", "check",
+        "--config", str(config_path),
+        "--output-format", "json",
+        str(target),
+    ]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        return result.stdout, result.stderr, result.returncode
+    except FileNotFoundError:
+        return None, "NOT_FOUND", 1
+    except subprocess.TimeoutExpired:
+        return None, "TIMEOUT", 1
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python lint.py <path>")
+        sys.exit(1)
+
+    target = Path(sys.argv[1])
+    if not target.exists():
+        print(f"Error: path not found: {target}")
+        sys.exit(1)
+
+    with tempfile.NamedTemporaryFile(
+        mode="w", suffix=".toml", prefix="ruff_ep_", delete=False
+    ) as tmp:
+        tmp.write(RUFF_CONFIG)
+        config_path = Path(tmp.name)
+
+    try:
+        stdout, stderr, returncode = run_ruff(target, config_path)
+    finally:
+        config_path.unlink(missing_ok=True)
+
+    if stdout is None:
+        if stderr == "NOT_FOUND":
+            print("Error: ruff is not installed.")
+            print("Install it with:  pip install ruff")
+            print("Or globally:      pipx install ruff")
+        elif stderr == "TIMEOUT":
+            print("Error: ruff timed out.")
+        else:
+            print(f"Error running ruff: {stderr}")
+        sys.exit(1)
+
+    print(f"Effective Python lint report — {target}")
+    print("-" * 70)
+
+    try:
+        violations = json.loads(stdout) if stdout.strip() else []
+    except json.JSONDecodeError:
+        print("Raw ruff output:")
+        print(stdout)
+        sys.exit(returncode)
+
+    if not violations:
+        print("No violations found. Code aligns well with Effective Python.")
+        sys.exit(0)
+
+    # Group by item
+    by_item: dict[str, list] = {}
+    for v in violations:
+        code = v.get("code", "?")
+        mapping = find_item(code)
+        item_key = mapping[0] if mapping else "Other"
+        by_item.setdefault(item_key, []).append((v, mapping))
+
+    total = 0
+    for item_key in sorted(by_item):
+        entries = by_item[item_key]
+        item_desc = entries[0][1][1] if entries[0][1] else "ruff violation"
+        print(f"\n[{item_key}] {item_desc}")
+        for v, _ in entries:
+            loc = v.get("location", {})
+            row, col = loc.get("row", "?"), loc.get("column", "?")
+            filename = Path(v.get("filename", str(target))).name
+            message = v.get("message", "")
+            code = v.get("code", "?")
+            print(f"  {filename}:{row}:{col}  [{code}] {message}")
+            total += 1
+
+    print(f"\n{'-' * 70}")
+    print(f"Total violations: {total}")
+    sys.exit(1 if violations else 0)
+
+
+if __name__ == "__main__":
+    main()

package/kotlin-in-action/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-java-style-null-handling",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nclass OrderService(private val repo: OrderRepository) {\n\n    fun getShippingCity(orderId: String): String {\n        val order = repo.findById(orderId)\n        if (order != null) {\n            val address = order.shippingAddress\n            if (address != null) {\n                val city = address.city\n                if (city != null) {\n                    return city.uppercase()\n                }\n            }\n        }\n        return \"UNKNOWN\"\n    }\n\n    fun applyDiscount(orderId: String, percent: Double): Double {\n        val order = repo.findById(orderId)\n        var total = 0.0\n        if (order != null) {\n            total = order.total\n            val membership = order.customer.membership\n            if (membership != null) {\n                if (membership.isActive != null && membership.isActive == true) {\n                    total = total * (1.0 - percent / 100.0)\n                }\n            }\n        }\n        return total\n    }\n}\n```",
+      "expectations": [
+        "Flags the deeply nested null-checking pyramid in `getShippingCity` as Java-style; recommends replacing with safe call chaining: `repo.findById(orderId)?.shippingAddress?.city?.uppercase() ?: \"UNKNOWN\"` (Ch 7: safe calls and Elvis operator)",
+        "Flags the nested null checks in `applyDiscount` as Java-style; recommends safe calls and let for null-safe transformations (Ch 7)",
+        "Flags `membership.isActive == true` as redundant when `isActive` is nullable Boolean; recommends `membership.isActive == true` can be replaced with `membership.isActive ?: false` or smart cast after null check (Ch 7)",
+        "Notes that `var total = 0.0` followed by conditional assignment is a code smell; recommends using an expression: `val total = order?.total ?: 0.0` (Ch 2: val over var, expression style)",
+        "Recommends using `let` for null-safe scoping: `membership?.takeIf { it.isActive == true }?.let { ... }` (Ch 7: let for null checks)",
+        "Provides a refactored version using safe calls, Elvis operator, and let throughout"
+      ]
+    },
+    {
+      "id": "eval-02-missing-extension-functions-named-args",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nfun formatUserDisplay(firstName: String, lastName: String, email: String, isAdmin: Boolean): String {\n    val name = firstName + \" \" + lastName\n    val badge = if (isAdmin == true) \"[ADMIN] \" else \"\"\n    return badge + name + \" <\" + email + \">\"\n}\n\nfun truncate(text: String, maxLen: Int, suffix: String): String {\n    return if (text.length > maxLen) {\n        text.substring(0, maxLen) + suffix\n    } else {\n        text\n    }\n}\n\nclass UserDisplayHelper {\n    fun render(firstName: String, lastName: String, email: String, isAdmin: Boolean): String {\n        return formatUserDisplay(firstName, lastName, email, isAdmin)\n    }\n\n    fun renderTruncated(firstName: String, lastName: String, email: String, isAdmin: Boolean, maxLen: Int): String {\n        val display = formatUserDisplay(firstName, lastName, email, isAdmin)\n        return truncate(display, maxLen, \"...\")\n    }\n}\n```",
+      "expectations": [
+        "Flags string concatenation with `+` throughout; recommends string templates (Ch 2: string templates are idiomatic Kotlin)",
+        "Flags `isAdmin == true` comparison on a non-nullable Boolean; should be just `isAdmin` (Ch 7: unnecessary null comparison on non-nullable type)",
+        "Notes that `truncate` and `formatUserDisplay` are standalone utility functions that would be more idiomatic as extension functions on `String` (Ch 3: prefer extension functions over utility classes)",
+        "Flags `UserDisplayHelper` as an unnecessary Java-style utility class wrapping top-level functions; recommends converting to top-level functions or extension functions (Ch 3: top-level functions replace static utility classes)",
+        "Identifies that `renderTruncated` has many same-typed parameters in a row which are ambiguous at call sites; recommends named arguments or introducing a value class or data class (Ch 3: use named/default arguments for clarity)",
+        "Notes that `truncate` could use a default parameter value for `suffix` instead of requiring callers to pass `\"...\"` every time (Ch 3: default parameter values)",
+        "Provides a refactored version using extension functions on String, string templates, and named/default args"
+      ]
+    },
+    {
+      "id": "eval-03-clean-kotlin-coroutines-sealed",
+      "prompt": "Review this Kotlin code:\n\n```kotlin\nsealed interface PaymentResult {\n    data class Success(val transactionId: String, val amount: Double) : PaymentResult\n    data class Declined(val reason: String, val code: Int) : PaymentResult\n    data class NetworkError(val cause: Throwable) : PaymentResult\n}\n\ninterface PaymentGateway {\n    suspend fun charge(amount: Double, token: String): PaymentResult\n}\n\nclass PaymentProcessor(\n    private val gateway: PaymentGateway,\n    private val scope: CoroutineScope\n) {\n    suspend fun processOrder(orderId: String, amount: Double, token: String): PaymentResult {\n        return withContext(Dispatchers.IO) {\n            try {\n                gateway.charge(amount, token)\n            } catch (e: CancellationException) {\n                throw e\n            } catch (e: Exception) {\n                PaymentResult.NetworkError(e)\n            }\n        }\n    }\n\n    fun processOrderAsync(orderId: String, amount: Double, token: String) =\n        scope.async { processOrder(orderId, amount, token) }\n}\n\nfun renderResult(result: PaymentResult): String = when (result) {\n    is PaymentResult.Success -> \"Charged \\$${result.amount} — txn ${result.transactionId}\"\n    is PaymentResult.Declined -> \"Declined (${result.code}): ${result.reason}\"\n    is PaymentResult.NetworkError -> \"Network error: ${result.cause.message}\"\n}\n```",
+      "expectations": [
+        "Recognizes this is already idiomatic, well-structured Kotlin and says so explicitly",
+        "Praises the sealed interface hierarchy for `PaymentResult` providing exhaustive when expressions without a catch-all branch (Ch 4: sealed classes for restricted hierarchies)",
+        "Praises re-throwing `CancellationException` to maintain cooperative coroutine cancellation (Ch 14: structured concurrency, cancellation handling)",
+        "Praises using `withContext(Dispatchers.IO)` for the blocking gateway call rather than blocking on a non-IO dispatcher (Ch 14: dispatcher usage)",
+        "Praises use of `data class` subtypes giving automatic `equals`, `hashCode`, `copy`, and `toString` (Ch 4: data classes for value types)",
+        "Praises the exhaustive `when` expression in `renderResult` that the compiler enforces due to the sealed hierarchy (Ch 4)",
+        "Does NOT manufacture issues to appear thorough; any suggestions are explicitly framed as minor optional improvements",
+        "May note minor optional suggestions such as whether `processOrderAsync` is needed given `processOrder` is already suspend, but frames them as design questions, not violations"
+      ]
+    }
+  ]
+}

package/kotlin-in-action/examples/after.md

@@ -0,0 +1,53 @@
+# After
+
+Idiomatic Kotlin using a sealed interface for channels, safe-call operators, named parameters, and extension functions — eliminating all manual null checks and string comparisons.
+
+```kotlin
+// Sealed interface models exactly the valid channels — exhaustive when is enforced
+sealed interface NotificationChannel {
+    data class Email(val address: String) : NotificationChannel
+    data class Sms(val phoneNumber: String) : NotificationChannel
+}
+
+// Extension function resolves the preferred channel from a User
+fun User.preferredChannel(): NotificationChannel? = when {
+    email != null       -> NotificationChannel.Email(email)
+    phoneNumber != null -> NotificationChannel.Sms(phoneNumber)
+    else                -> null
+}
+
+class NotificationService(
+    private val emailSender: EmailSender,
+    private val smsSender: SmsSender,
+) {
+
+    fun sendNotification(user: User, message: String, channel: NotificationChannel) {
+        require(message.isNotBlank()) { "Notification message must not be blank" }
+
+        when (channel) {
+            is NotificationChannel.Email -> {
+                val subject = "Notification for ${user.firstName} ${user.lastName}"
+                emailSender.send(to = channel.address, subject = subject, body = message)
+            }
+            is NotificationChannel.Sms -> {
+                smsSender.send(to = channel.phoneNumber, body = message)
+            }
+        }
+    }
+}
+
+// Usage — caller resolves channel; service focuses on delivery
+fun notifyUser(user: User, message: String, service: NotificationService) {
+    user.preferredChannel()
+        ?.let { channel -> service.sendNotification(user, message, channel) }
+        ?: logger.warn("No notification channel available for user ${user.id}")
+}
+```
+
+Key improvements:
+- `sealed interface NotificationChannel` replaces the `String` channel parameter — the compiler enforces exhaustive `when` and eliminates the "Unknown channel" else branch (Ch 4: Sealed classes)
+- `User?` parameter becomes non-null `User` — the caller is responsible for ensuring a valid user exists; null-safety is pushed to the boundary (Ch 7: Null safety)
+- `user.preferredChannel()` extension function encapsulates the channel-resolution logic outside the service class (Ch 3: Extension functions)
+- `require(message.isNotBlank())` replaces silent println for invalid input (Effective Kotlin Item 5: Specify your expectations on arguments)
+- Named parameters `to =`, `subject =`, `body =` make the send calls self-documenting (Ch 3: Named arguments)
+- String template `"${user.firstName} ${user.lastName}"` replaces concatenation (Ch 2: String templates)

package/kotlin-in-action/examples/before.md

@@ -0,0 +1,39 @@
+# Before
+
+Kotlin code written with Java-style null checks, no extension functions, and no use of sealed classes or safe-call operators.
+
+```kotlin
+class NotificationService(
+    private val emailSender: EmailSender,
+    private val smsSender: SmsSender
+) {
+
+    fun sendNotification(user: User?, message: String?, channel: String) {
+        if (user == null) {
+            println("User is null")
+            return
+        }
+        if (message == null || message.isEmpty()) {
+            println("Message is empty")
+            return
+        }
+
+        if (channel == "EMAIL") {
+            if (user.email != null) {
+                val subject = "Notification for " + user.firstName + " " + user.lastName
+                emailSender.send(user.email, subject, message)
+            } else {
+                println("No email for user " + user.id)
+            }
+        } else if (channel == "SMS") {
+            if (user.phoneNumber != null) {
+                smsSender.send(user.phoneNumber, message)
+            } else {
+                println("No phone for user " + user.id)
+            }
+        } else {
+            println("Unknown channel: " + channel)
+        }
+    }
+}
+```

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

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""
+setup_detekt.py - Set up Detekt with Kotlin-in-Action aligned rules.
+
+Usage:
+    python setup_detekt.py [--output-dir ./]
+
+Generates:
+    detekt.yml      - Detekt config with rules mapped to Kotlin in Action chapters
+    run_detekt.sh   - Shell script to run Detekt with this config
+
+Each rule includes a comment referencing the relevant chapter from
+"Kotlin in Action" by Dmitry Jemerov and Svetlana Isakova.
+"""
+
+import argparse
+import pathlib
+import stat
+
+DETEKT_YML = """\
+# detekt.yml
+# Detekt configuration aligned with "Kotlin in Action" by Jemerov & Isakova.
+# Each rule references the chapter that motivates it.
+
+build:
+  maxIssues: 0
+  excludeCorrectable: false
+
+config:
+  validation: true
+  warningsAsErrors: false
+
+complexity:
+  active: true
+
+  # Chapter 5 - Lambdas: keep lambdas and functions concise and readable.
+  LongMethod:
+    active: true
+    threshold: 20
+
+  # Chapter 3 - Functions: prefer functions with few, well-named parameters.
+  # Many parameters suggest the need for a data class or builder pattern.
+  LongParameterList:
+    active: true
+    functionThreshold: 4
+    constructorThreshold: 6
+    ignoreDefaultParameters: true
+
+  # Chapter 10 - Higher-order functions: avoid deep nesting; flatten with
+  # higher-order functions (map, filter, let, run) instead.
+  NestedBlockDepth:
+    active: true
+    threshold: 3
+
+  # Chapter 4 - Classes: classes should be focused and not overly complex.
+  TooManyFunctions:
+    active: true
+    thresholdInFiles: 20
+    thresholdInClasses: 15
+    thresholdInInterfaces: 10
+    thresholdInObjects: 10
+    thresholdInEnums: 5
+
+naming:
+  active: true
+
+  # Chapter 3 - Functions: Kotlin convention is camelCase for function names.
+  FunctionNaming:
+    active: true
+    functionPattern: '[a-z][a-zA-Z0-9]*'
+    excludes: ['**/test/**']
+
+  # Chapter 2 - Basics: variables follow camelCase; properties are idiomatic Kotlin.
+  VariableNaming:
+    active: true
+    variablePattern: '[a-z][a-zA-Z0-9]*'
+    privateVariablePattern: '(_)?[a-z][a-zA-Z0-9]*'
+
+  # Chapter 4 - Classes: class names are PascalCase per Kotlin convention.
+  ClassNaming:
+    active: true
+    classPattern: '[A-Z][a-zA-Z0-9]*'
+
+  # Chapter 8 - Generics: type parameter names should be single uppercase letters
+  # or descriptive PascalCase names.
+  TypeParameterNaming:
+    active: true
+    typeParameterPattern: '[A-Z][A-Za-z]*'
+
+style:
+  active: true
+
+  # Chapter 4 - Classes, Objects, Interfaces: abstract classes without abstract
+  # members should be interfaces or open classes instead.
+  UnnecessaryAbstractClass:
+    active: true
+
+  # Chapter 3 - Functions: Unit return type is implicit; declaring it is redundant.
+  OptionalUnit:
+    active: true
+
+  # Chapter 2 - Basics: val properties that can be const should be const
+  # for compile-time optimisation.
+  MayBeConst:
+    active: true
+
+  # Chapter 4 - Objects: use object declarations instead of classes with only
+  # static members.
+  UseDataClass:
+    active: true
+    allowVars: false
+
+  # Chapter 11 - DSL: trailing lambdas should be outside parentheses per convention.
+  UnnecessaryParentheses:
+    active: true
+
+potential-bugs:
+  active: true
+
+  # Chapter 6 - Null Safety: lateinit signals deferred initialisation, which
+  # makes nullability guarantees harder to reason about. Prefer constructor injection.
+  LateinitUsage:
+    active: true
+    excludes: ['**/test/**']
+    ignoreOnClassesPattern: ''
+
+  # Chapter 6 - Null Safety: the !! operator bypasses null safety and will
+  # throw NPE at runtime. Use safe calls (?.) or Elvis operator (?:) instead.
+  UnsafeCallOnNullableType:
+    active: true
+    excludes: ['**/test/**']
+
+  # Chapter 6 - Null Safety: explicit null checks with == null should be
+  # replaced with safe-call or let idioms.
+  NullableToStringCall:
+    active: true
+
+coroutines:
+  active: true
+
+  # Chapter 12 (Appendix) - Coroutines: GlobalScope couples coroutines to
+  # application lifetime and makes cancellation impossible. Use structured
+  # concurrency with a scoped CoroutineScope instead.
+  GlobalCoroutineUsage:
+    active: true
+
+  # Chapter 12 - Coroutines: suspend modifier on a function that contains no
+  # suspension points is misleading and adds unnecessary overhead.
+  RedundantSuspendModifier:
+    active: true
+
+  # Chapter 12 - Coroutines: use withContext for blocking calls rather than
+  # running them on the default dispatcher.
+  BlockingMethodInNonBlockingContext:
+    active: true
+"""
+
+RUN_SCRIPT = """\
+#!/usr/bin/env bash
+# run_detekt.sh
+# Runs Detekt with the Kotlin-in-Action aligned configuration.
+# Generated by setup_detekt.py
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CONFIG="${SCRIPT_DIR}/detekt.yml"
+SRC_DIR="${1:-src}"
+
+if ! command -v detekt &>/dev/null && ! command -v detekt-cli &>/dev/null; then
+  echo "ERROR: detekt not found on PATH."
+  echo ""
+  echo "Install options:"
+  echo "  brew install detekt          # macOS"
+  echo "  sdk install detekt           # SDKMAN"
+  echo "  # Or run via Gradle plugin - add to build.gradle.kts:"
+  echo "  #   plugins { id(\\"io.gitlab.arturbosch.detekt\\") version \\"1.23.5\\" }"
+  exit 1
+fi
+
+CMD="detekt"
+command -v detekt-cli &>/dev/null && CMD="detekt-cli"
+
+echo "Running Detekt on $SRC_DIR ..."
+$CMD --config "$CONFIG" --input "$SRC_DIR"
+echo "Done."
+"""
+
+
+def write_file(path: pathlib.Path, content: str, executable: bool = False) -> None:
+    path.write_text(content, encoding="utf-8")
+    if executable:
+        path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    print(f"Wrote: {path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Set up Detekt with Kotlin-in-Action aligned rules."
+    )
+    parser.add_argument(
+        "--output-dir",
+        default=".",
+        help="Directory to write config files (default: ./)",
+    )
+    args = parser.parse_args()
+
+    output_dir = pathlib.Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    write_file(output_dir / "detekt.yml", DETEKT_YML)
+    write_file(output_dir / "run_detekt.sh", RUN_SCRIPT, executable=True)
+
+    print()
+    print("Setup complete.")
+    print(f"  Config : {output_dir / 'detekt.yml'}")
+    print(f"  Runner : {output_dir / 'run_detekt.sh'}")
+    print()
+    print("Run Detekt:")
+    print(f"  cd {output_dir} && ./run_detekt.sh [src-dir]")
+
+
+if __name__ == "__main__":
+    main()

package/lean-startup/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-six-month-build-before-user-testing",
+      "prompt": "Review this product development plan:\n\n```\nProduct: TaskFlow — AI-powered project management for remote teams\nTeam: 4 engineers, 1 designer, 1 product manager\nTimeline: 6-month build before any user testing\n\nMonth 1-2: Core task management (create, assign, due dates, status)\nMonth 3: AI features (auto-prioritization, workload balancing)\nMonth 4: Integrations (Slack, GitHub, Jira, Google Calendar)\nMonth 5: Mobile apps (iOS and Android)\nMonth 6: Analytics dashboard and reporting\n\nSuccess criteria: Ship to beta users after 6 months\nMarketing plan: Product Hunt launch in month 7\n\nAssumptions we're making:\n- Remote teams struggle with task prioritization\n- AI suggestions will be trusted and acted on\n- Teams are willing to switch from their current PM tool\n- Integration with existing tools is a must-have on day one\n```",
+      "expectations": [
+        "Identifies the 6-month build before any user testing as a direct violation of the Build-Measure-Learn loop: validated learning cannot happen without users (Ch 3-4: validated learning, experimentation over planning)",
+        "Flags the listed assumptions ('remote teams struggle', 'AI suggestions will be trusted', 'willing to switch') as leap-of-faith assumptions that should be tested first, not assumed (Ch 5: identify and test leap-of-faith assumptions before building)",
+        "Flags the absence of any hypothesis or success metric beyond 'ship to beta': recommends defining a value hypothesis and growth hypothesis with measurable success criteria (Ch 5: value hypothesis and growth hypothesis)",
+        "Flags the absence of an MVP: 6 months of features is not an MVP — it is a v1.0 product launch; recommends identifying the single riskiest assumption and testing it with the minimum viable experiment (Ch 6: MVP is for learning, not launching)",
+        "Flags that integrations, mobile apps, and analytics are included before validating whether users even want the core task management and AI features; recommends cutting scope to the riskiest assumption (Ch 6: smallest experiment to test the riskiest assumption)",
+        "Flags the absence of innovation accounting: there are no cohort metrics, funnel metrics, or baseline measurements planned (Ch 7: innovation accounting)",
+        "Recommends concrete alternatives such as a concierge MVP (manually prioritize tasks for 5 teams for 2 weeks) or a Wizard of Oz test (fake AI powered by a human) to validate the AI trust assumption before building it"
+      ]
+    },
+    {
+      "id": "eval-02-feature-request-without-validated-learning",
+      "prompt": "Review this feature request and justification:\n\n```\nFeature Request: Advanced Filtering and Saved Views\n\nSubmitted by: Product Manager\nPriority: High\n\nRequest:\nAdd advanced filtering to the task list — filter by assignee, due date range,\ntag, project, and custom fields. Users should be able to save filter combinations\nas named views (e.g., \"My overdue tasks\", \"Sprint backlog\").\n\nJustification:\n- 3 customers mentioned filtering in support tickets last quarter\n- Our top competitor, Asana, has this feature\n- The engineering team estimates 3 sprints (6 weeks) to build\n- A customer on a discovery call said \"filtering would be great\"\n\nExpected outcome:\nImprove user retention and increase upsell conversion to Pro tier.\n\nApproval requested: Start sprint planning next week\n```",
+      "expectations": [
+        "Flags that 'customers mentioned in support tickets' and 'a customer said it would be great' are anecdotal, not validated learning — these are opinions, not measured behavior (Ch 3: validated learning requires empirical evidence, not opinions)",
+        "Flags competitor benchmarking ('Asana has this feature') as a reason to build without testing whether this feature drives retention or conversion for this specific user base (Ch 5: test your own value hypothesis, not competitors')",
+        "Flags that the expected outcome 'improve retention and increase upsell' is stated without a hypothesis, baseline metric, or success threshold; recommends defining a testable hypothesis before committing 6 weeks of engineering (Ch 7: innovation accounting — establish baseline, define success threshold)",
+        "Flags no mention of which leap-of-faith assumption is being tested: is the assumption that users can't find what they need, that they churn because of missing filters, or that Pro upsell is blocked by this feature? (Ch 5: identify the specific assumption)",
+        "Recommends a smaller experiment to validate before building: add a prominent 'Filter tasks' button that shows a 'Coming soon — join waitlist' modal and measure click rate to quantify demand (Ch 6: smallest experiment to validate the assumption)",
+        "Flags the absence of a pivot/persevere decision framework: what happens if the feature ships and retention does not improve? (Ch 8: define pivot/persevere criteria before building)"
+      ]
+    },
+    {
+      "id": "eval-03-well-structured-mvp-experiment",
+      "prompt": "Review this product experiment plan:\n\n```\nExperiment: Validate demand for AI-assisted code review summaries\n\nHypothesis:\nWe believe that engineering managers at companies with 10-50 engineers\nspend more than 2 hours per week reading through pull request diffs to\nstay informed. We believe they will pay for an automated daily digest\nthat summarizes what changed, why, and any risks flagged.\n\nRiskiest assumption: Managers will read and act on AI-generated summaries\nrather than skimming or ignoring them.\n\nMVP Design (Wizard of Oz — 3-week test):\n- Recruit 8 engineering managers via LinkedIn outreach\n- Each connects their GitHub repo (OAuth)\n- Every weekday morning, a human analyst (us) reads the day's PRs\n  and writes a 200-word summary email manually\n- We send it from a branded email: digest@codebrief.io\n- Participants do not know summaries are human-written\n\nSuccess metrics (measured after 3 weeks):\n- Primary: Open rate >= 70% across all 5 weekday sends\n- Secondary: At least 5 of 8 managers respond to exit survey saying\n  they found summaries 'useful' or 'very useful'\n- Conversion signal: At least 3 managers ask 'how do I keep this?'\n\nPivot/persevere criteria:\n- If primary AND secondary metrics are met: build v1 with real AI\n- If only one is met: run a second 2-week test with adjusted format\n- If neither is met: pivot to a different user segment or problem\n\nTimeline: Recruiting this week, experiment runs weeks 2-4, decision week 5\n```",
+      "expectations": [
+        "Recognizes this is a well-structured Lean Startup experiment and says so explicitly",
+        "Praises the falsifiable hypothesis that names a specific user segment, problem, and measurable behavior (Ch 3: validated learning with empirical evidence)",
+        "Praises identifying the riskiest assumption ('managers will act on summaries') separately from the general hypothesis — this is the correct application of leap-of-faith assumption identification (Ch 5: leap-of-faith assumptions)",
+        "Praises the Wizard of Oz MVP design that tests the value hypothesis without building any AI infrastructure (Ch 6: MVP is for learning, not launching — concierge/Wizard of Oz types)",
+        "Praises the quantified success metrics with specific thresholds (70% open rate, 5/8 satisfaction, 3 conversion signals) rather than vague goals (Ch 7: actionable metrics, not vanity metrics)",
+        "Praises the explicit pivot/persevere criteria defined before the experiment runs, making the decision data-driven rather than gut-driven (Ch 8: structured pivot/persevere decision)",
+        "Praises the tight 5-week timeline keeping the Build-Measure-Learn loop short (Ch 9: small batches, fast learning cycles)",
+        "Does NOT manufacture issues to appear thorough; any suggestions are explicitly framed as minor optional improvements"
+      ]
+    }
+  ]
+}