@booklib/skills 1.5.2 → 1.6.0

package/benchmark/order-processing.skill-router.js

@@ -0,0 +1,271 @@
+// code-after-custom.js
+// Rewritten applying: clean-code-reviewer + design-patterns (via skill-router)
+//
+// Patterns applied (design-patterns skill):
+//   Strategy  — payment methods (GoF: encapsulate interchangeable algorithms)
+//   Strategy  — discount tiers  (GoF: data-driven, open for extension)
+//   State     — order lifecycle (GoF: each status owns its valid transitions)
+//   Singleton — stats           (GoF: deliberate, clean, no accidental shared state)
+//   Observer  — side effects    (GoF: email/stats decoupled from business logic)
+//   Facade    — module API      (GoF: single clean surface, internals hidden)
+//   Template Method — validation (GoF: fixed skeleton, variable steps)
+//
+// Principles applied (clean-code-reviewer skill):
+//   N1/N2  — intention-revealing names at the right abstraction level
+//   F1/F2  — small functions, one responsibility each
+//   G5     — DRY: no duplicated confirmation block
+//   G25    — named constants, no magic numbers
+//   G23    — data-driven lookup, not if-chain
+//   G28    — encapsulated predicates
+//   G30    — functions do one thing
+//   Ch.7   — throw with context, never silent return false
+//   G4     — parameterised queries, no eval, no safety overrides
+
+'use strict';
+
+const db     = require('./db');
+const mailer = require('./mailer');
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const TAX_RATE = 0.23;
+
+// Strategy: discount tiers — add a new tier here, nothing else changes (G23, G25)
+const DISCOUNT_BY_TIER = Object.freeze({
+  standard: 0,
+  premium:  0.10,
+  vip:      0.20,
+  staff:    0.50,
+});
+
+// Strategy: payment processors — add a new method here, nothing else changes
+const PAYMENT_PROCESSORS = Object.freeze({
+  card: {
+    charge(user, amount) {
+      // TODO: integrate real payment gateway
+      console.log(`Charging card (...${String(user.card).slice(-4)}) for ${formatMoney(amount)}`);
+      return true;
+    },
+  },
+  paypal: {
+    charge(user, amount) {
+      // TODO: integrate PayPal SDK
+      console.log(`Charging PayPal ${user.paypal} for ${formatMoney(amount)}`);
+      return true;
+    },
+  },
+  crypto: {
+    charge() {
+      throw new Error('Crypto payments are not yet implemented');
+    },
+  },
+});
+
+// ─── State: order lifecycle ───────────────────────────────────────────────────
+// Each state owns its own transition rules.
+// Adding a new status = adding one object. No existing guards change.
+
+const ORDER_STATES = Object.freeze({
+  pending: {
+    canCancel: () => true,
+    canRefund: () => false,
+  },
+  paid: {
+    canCancel: () => true,
+    canRefund: () => true,
+  },
+  shipped: {
+    canCancel: () => false,
+    canRefund: () => false,
+  },
+  delivered: {
+    canCancel: () => false,
+    canRefund: () => true,
+  },
+  cancelled: {
+    canCancel: () => false,
+    canRefund: () => false,
+  },
+  refunded: {
+    canCancel: () => false,
+    canRefund: () => false,
+  },
+});
+
+function getOrderState(status) {
+  const state = ORDER_STATES[status];
+  if (!state) throw new Error(`Unknown order status: ${status}`);
+  return state;
+}
+
+// ─── Singleton: stats ─────────────────────────────────────────────────────────
+// Deliberate, clean singleton. Not an accidental module-scope variable.
+
+const Stats = (() => {
+  const data = { orders: 0, revenue: 0, cancelled: 0 };
+  return {
+    recordPlaced(total)    { data.orders++; data.revenue += total; },
+    recordCancelled(total) { data.cancelled++; data.revenue -= total; },
+    recordRefunded(total)  { data.cancelled++; data.revenue -= total; },
+    snapshot()             { return { ...data }; },
+  };
+})();
+
+// ─── Observer: event bus ──────────────────────────────────────────────────────
+// Business logic emits events. Side effects (email, stats) register as listeners.
+// Adding SMS or audit log = one new listener. Core functions unchanged.
+
+const EventBus = (() => {
+  const listeners = {};
+  return {
+    on(event, fn)   { (listeners[event] = listeners[event] || []).push(fn); },
+    emit(event, payload) { (listeners[event] || []).forEach(fn => fn(payload)); },
+  };
+})();
+
+// Register observers at startup — not inside business functions
+EventBus.on('order.placed', ({ user, total }) => {
+  mailer.send(user.email, 'Order confirmed', `Your order total is ${formatMoney(total)}.`);
+  Stats.recordPlaced(total);
+});
+
+EventBus.on('order.cancelled', ({ order, total }) => {
+  mailer.send(order.user_email, 'Order cancelled', 'Your order has been cancelled.');
+  Stats.recordCancelled(total);
+});
+
+EventBus.on('order.refunded', ({ order, total }) => {
+  mailer.send(order.user_email, 'Refund processed', `Your refund of ${formatMoney(total)} is on its way.`);
+  Stats.recordRefunded(total);
+});
+
+// ─── Validation (Template Method skeleton) ────────────────────────────────────
+// Fixed skeleton: check preconditions, then run action. (G28, Ch.7)
+
+function assertActiveUser(user) {
+  if (!user)        throw new Error('user is required');
+  if (!user.active) throw new Error(`User ${user.id} is not active`);
+}
+
+function assertValidOrder(order) {
+  if (!order?.items?.length) throw new Error('order must contain at least one item');
+}
+
+function assertSupportedPayment(method) {
+  if (!PAYMENT_PROCESSORS[method]) throw new Error(`Unsupported payment method: ${method}`);
+}
+
+// ─── Calculation (F1: one responsibility each) ────────────────────────────────
+
+function calculateSubtotal(items) {
+  return items
+    .filter(item => item.qty > 0 && item.price > 0)
+    .reduce((sum, item) => sum + item.qty * item.price, 0);
+}
+
+function applyTierDiscount(amount, userTier) {
+  const rate = DISCOUNT_BY_TIER[userTier] ?? 0; // G25: named table, not magic number
+  return amount * (1 - rate);
+}
+
+function applyTax(amount) {
+  return amount * (1 + TAX_RATE);
+}
+
+// ─── Persistence ──────────────────────────────────────────────────────────────
+// Each function does one thing. Parameterised queries throughout (G4).
+
+async function persistOrder(order, user, total) {
+  await db.query(
+    'INSERT INTO orders (id, user_id, total, status) VALUES (?, ?, ?, ?)',
+    [order.id, user.id, total, 'paid'],
+  );
+}
+
+async function fetchOrder(orderId) {
+  const order = await db.query('SELECT * FROM orders WHERE id = ?', [orderId]);
+  if (!order) throw new Error(`Order not found: ${orderId}`);
+  return order;
+}
+
+async function persistCancellation(orderId, reason) {
+  await db.query(
+    'UPDATE orders SET status = ?, reason = ? WHERE id = ?',
+    ['cancelled', reason, orderId],
+  );
+}
+
+async function persistRefund(orderId) {
+  await db.query('UPDATE orders SET status = ? WHERE id = ?', ['refunded', orderId]);
+}
+
+// ─── Formatting ───────────────────────────────────────────────────────────────
+
+function formatMoney(amount) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount);
+}
+
+// ─── Facade: public API ───────────────────────────────────────────────────────
+// Callers import one clean surface. All internals (strategies, state,
+// observer, singleton) are hidden and can evolve independently.
+
+async function processOrder(order, user, paymentMethod) {
+  // Template Method: validate → calculate → charge → persist → notify (via Observer)
+  assertActiveUser(user);
+  assertValidOrder(order);
+  assertSupportedPayment(paymentMethod);
+
+  const subtotal   = calculateSubtotal(order.items);
+  const discounted = applyTierDiscount(subtotal, user.type);
+  const total      = applyTax(discounted);
+
+  // Strategy pattern: dispatch to the right processor, one confirmation path
+  PAYMENT_PROCESSORS[paymentMethod].charge(user, total);
+  await persistOrder(order, user, total);
+
+  // Observer: emit event — email and stats handled by listeners, not here
+  EventBus.emit('order.placed', { user, order, total });
+}
+
+async function getUserOrders(userId) {
+  return db.query('SELECT * FROM orders WHERE user_id = ?', [userId]);
+}
+
+async function cancelOrder(orderId, userId, reason) {
+  const order = await fetchOrder(orderId);
+
+  if (order.userId !== userId) throw new Error('Order does not belong to this user');
+
+  // State pattern: the status object decides whether cancellation is legal
+  if (!getOrderState(order.status).canCancel()) {
+    throw new Error(`Order ${orderId} cannot be cancelled (status: ${order.status})`);
+  }
+
+  await persistCancellation(orderId, reason);
+  EventBus.emit('order.cancelled', { order, total: order.total });
+}
+
+async function refundOrder(orderId) {
+  const order = await fetchOrder(orderId);
+
+  // State pattern: the status object decides whether refund is legal
+  if (!getOrderState(order.status).canRefund()) {
+    throw new Error(`Order ${orderId} cannot be refunded (status: ${order.status})`);
+  }
+
+  await persistRefund(orderId);
+  EventBus.emit('order.refunded', { order, total: order.total });
+}
+
+function getStats() {
+  return Stats.snapshot(); // Singleton: clean access, defensive copy
+}
+
+// Facade export: one coherent interface
+module.exports = {
+  processOrder,
+  getUserOrders,
+  cancelOrder,
+  refundOrder,
+  getStats,
+};

package/benchmark/review-report.md

@@ -0,0 +1,129 @@
+# skill-router benchmark: book-based review vs. native PR toolkit
+
+**skill-router** analyzes your code and picks the right book-based skill for the job — so instead of one AI trying to apply four books superficially, you get a deep, focused review from the correct authority. This benchmark runs the same intentionally broken JavaScript file through two parallel pipelines to compare what each finds.
+
+| | Native | skill-router |
+|---|---|---|
+| **Pipeline** | `pr-review-toolkit:code-reviewer` | `skill-router` → `clean-code-reviewer` + `design-patterns` |
+| **Output file** | `order-processing.pr-toolkit.js` | `order-processing.skill-router.js` |
+
+**Bottom line:** Native wins on security depth (catches PCI violation, highest confidence scores). skill-router wins on architectural insight and principle education — finds ~47% more unique issues when both pipelines are combined.
+
+---
+
+## The code under test
+
+`order-processing.original.js` — 157-line Node.js order processing module with: one god function (`process`), no error handling, SQL injection on every query, global mutable state shared across all requests, and `eval()` used to return a plain variable.
+
+---
+
+## How skill-router picks its skills
+
+The router commits to a routing decision before any review begins:
+
+```
+Primary:    clean-code-reviewer  — god function, cryptic names, magic numbers (Ch.2/3/7)
+Secondary:  design-patterns      — duplicated payment blocks = Strategy pattern
+Don't use:  domain-driven-design — implementation-level code, not a model design problem
+```
+
+This is the core value: rather than spreading one review thin across four books, the router picks the right lens and goes deep. The `Don't use` line matters — it avoids premature or irrelevant advice.
+
+---
+
+## Issues found
+
+> **Notation:** `C1`, `I9`, `S4` are clean-code-reviewer's severity tiers (Critical / Important / Suggestion). `G30`, `N1`, `Ch.7` etc. are chapter/guideline references from *Clean Code* by Robert C. Martin. `Strategy(1)`, `Singleton(4)` etc. are pattern references from *Head First Design Patterns*.
+
+### Critical / High severity
+
+| Issue | Native | clean-code | design-patterns |
+|---|---|---|---|
+| SQL injection — every query (7 locations) | ✅ Confidence 100 | ✅ C1 — G30 | — |
+| `eval("stats")` — unnecessary, disables JIT | ✅ Confidence 100 | ✅ C3 — G30 | ✅ Singleton(4) |
+| Global mutable `usr`/`items`/`total` — cross-request leak | ✅ Confidence 98 | ✅ C2 — G18 | ✅ Singleton(4) |
+| `items` unbounded memory leak | ✅ Confidence 95 | ⚠️ implied | — |
+| `refund()` null dereference crash | ✅ Confidence 95 | ✅ C4 — Ch.7 | — |
+| PCI violation — card data logged to stdout | ✅ Confidence 92 | ❌ missed | — |
+| Payment fall-through returns `undefined` not `false` | ✅ Confidence 91 | ✅ I9 | ✅ Strategy(1) |
+| Duplicated card/paypal confirmation block | ✅ Confidence 85 | ✅ C5 — G5 | ✅ Strategy(1) |
+| Wrong-recipient email via global `usr` in cancel/refund | ✅ Confidence 89 | ✅ C4/I7 | — |
+
+### Important / Improvement
+
+| Issue | Native | clean-code | design-patterns |
+|---|---|---|---|
+| `==` instead of `===` throughout | ✅ Confidence 82 | ✅ I5 — G15 | — |
+| `var` instead of `const`/`let` | ✅ Confidence 80 | ✅ I6 — G29 | — |
+| Magic discount numbers (0.1, 0.2, 0.5) | ✅ | ✅ I3 — G25 | ✅ Strategy(3) |
+| `discount` variable declared, never used | ✅ Confidence 88 | ✅ I3 | — |
+| Discount should be data-driven, not if-chain | — | ✅ I4 — G23 | ✅ Strategy(3) |
+| God function — 10 responsibilities | ⚠️ via nesting | ✅ I1 — F1/F2 | ✅ Template(5) |
+| Six-level arrow-head nesting | ✅ Confidence 82 | ✅ I2 | — |
+| No error handling on db/mailer calls | ✅ Confidence 85 | ✅ I8 — Ch.7 | — |
+| `cancel()` never updates stats | ✅ Confidence 80 | — | — |
+| Stats inconsistency — two separate objects | ✅ Confidence 82 | ✅ S4 | ✅ Singleton(4) |
+| Cryptic names (`o`, `u`, `pay`, `s`, `rsn`) | ✅ Confidence 80 | ✅ S1 — N1/N2 | — |
+| Noise/lying comments | — | ✅ S2 — C2/C3 | — |
+| `formatMoney` floating-point rounding bug | — | ✅ S3 | — |
+| Stubs always return `true` — lying | — | ✅ S5 — C3 | — |
+| State machine needed for order lifecycle | — | — | ✅ State(2) |
+| Side effects hardcoded — use Observer | — | — | ✅ Observer(6) |
+| Flat module export — use Facade | — | — | ✅ Facade(7) |
+
+### Totals
+
+| | Native | clean-code | design-patterns | Combined |
+|---|---|---|---|---|
+| Critical/High | 9 | 5 | 4 | **9 unique** |
+| Important/Improvement | 10 | 9 | 3 | **14 unique** |
+| Suggestion/Low | 0 | 5 | 0 | **5** |
+| **Total** | **19** | **19** | **7 patterns** | **~28 unique** |
+
+Overlap: ~89% of native issues were also found by skill-router.
+
+---
+
+## Pattern opportunities identified (skill-router only)
+
+The native pipeline finds bugs. The skill-router pipeline additionally surfaces structural opportunities — places where a known pattern *could* reduce complexity — and explains the problem each one solves. Whether to apply a pattern is a judgment call: the skill flags the opportunity and the reasoning; you decide if the trade-off is worth it in your context.
+
+| # | Pattern | Impact | Problem it would solve |
+|---|---|---|---|
+| 1 | Strategy — payments | HIGH | Copy-pasted if-block per payment method |
+| 2 | State — order lifecycle | HIGH | Status strings checked in every function |
+| 3 | Strategy — discounts | HIGH | Magic-number if-chain, no extensibility |
+| 4 | Singleton (broken) | HIGH | Module-scope mutable state crossing requests |
+| 5 | Template Method | MEDIUM | Arrow pyramid duplicated in process+cancel |
+| 6 | Observer | MEDIUM | Email/stats hardcoded into business logic |
+| 7 | Facade | MEDIUM | Unrelated concerns in one flat export |
+
+**Suggested refactor sequence if you choose to act:** 4 → 1 → 3 → 2 → 5 → 6 → 7
+
+---
+
+
+## Updates since this benchmark
+
+**skill-router now outputs severity tiers.** One gap this benchmark exposed was that native's confidence scores (≥80 threshold) act as a noise filter — skill-router had no equivalent. The router has since been updated to instruct selected skills to classify every finding as **HIGH** (correctness/security/data loss), **MEDIUM** (design/maintainability), or **LOW** (style/naming), and to skip LOW findings for standard code reviews. This closes the signal-to-noise gap without re-running the benchmark — detection quality hasn't changed, output actionability has.
+
+---
+
+## When to use each
+
+| Situation | Use |
+|---|---|
+| Pre-merge PR review, security audit | **Native** — pre-merge gate: fast, confidence-filtered, adapts to CLAUDE.md project conventions |
+| Larger refactor, architecture planning | **skill-router** — patterns, principles, refactor roadmap |
+| Both together | ~95% total issue coverage vs ~80% for either alone |
+
+---
+
+## Files in this benchmark
+
+| File | Description |
+|---|---|
+| `order-processing.original.js` | Original bad code — unchanged input |
+| `order-processing.pr-toolkit.js` | Rewritten applying all `pr-review-toolkit` findings |
+| `order-processing.skill-router.js` | Rewritten applying `clean-code-reviewer` + `design-patterns` |
+| `review-report.md` | This file |