agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/content/plugins/refactoring/skills/agileflow-refactor/references/refactoring-patterns.md

@@ -0,0 +1,405 @@
+# Refactoring Patterns Reference
+
+**Load this when:** choosing a refactoring pattern for a specific smell, or implementing a specific pattern with correct before/after structure.
+
+---
+
+## Pattern 1: Extract Function
+
+**When:** A section of a function has a clear single purpose, or a function is > 20–30 lines.
+
+**Signal:** You can describe a block of code with a phrase ("calculate tax", "validate email format", "format the response").
+
+```js
+// Before — 40-line function doing multiple things
+async function processOrder(orderId, userId) {
+  const order = await Order.findById(orderId);
+  if (!order) throw new Error("Order not found");
+  if (order.userId !== userId) throw new Error("Forbidden");
+
+  // calculate total with discounts
+  let total = order.lineItems.reduce(
+    (sum, item) => sum + item.price * item.qty,
+    0,
+  );
+  const coupon = await Coupon.findByCode(order.couponCode);
+  if (coupon && coupon.isValid) {
+    total = total * (1 - coupon.discountPct / 100);
+  }
+  total = total * 1.1; // tax
+
+  // send confirmation
+  await Email.send({
+    to: order.customerEmail,
+    subject: `Order ${orderId} confirmed`,
+    body: `Your total is $${total.toFixed(2)}`,
+  });
+
+  return { orderId, total };
+}
+
+// After — extracted functions, each with one responsibility
+async function processOrder(orderId, userId) {
+  const order = await fetchAndAuthoriseOrder(orderId, userId);
+  const total = await calculateOrderTotal(order);
+  await sendOrderConfirmation(order, total);
+  return { orderId, total };
+}
+
+async function fetchAndAuthoriseOrder(orderId, userId) {
+  const order = await Order.findById(orderId);
+  if (!order) throw new OrderNotFoundError(orderId);
+  if (order.userId !== userId) throw new ForbiddenError();
+  return order;
+}
+
+async function calculateOrderTotal(order) {
+  const subtotal = order.lineItems.reduce(
+    (sum, item) => sum + item.price * item.qty,
+    0,
+  );
+  const discounted = await applyDiscount(subtotal, order.couponCode);
+  return discounted * 1.1; // apply tax
+}
+```
+
+---
+
+## Pattern 2: Replace Nested Conditionals with Guard Clauses
+
+**When:** The happy path is deeply nested inside multiple if/else blocks; early exit conditions are buried.
+
+**Signal:** Code looks like an arrow pointing right, with the main logic at the deepest indentation level.
+
+```js
+// Before — arrow anti-pattern
+function getShippingCost(order) {
+  if (order !== null) {
+    if (order.isEligible) {
+      if (order.total > 100) {
+        return 0; // free shipping
+      } else {
+        return 5.99;
+      }
+    } else {
+      return null; // not eligible
+    }
+  } else {
+    return null;
+  }
+}
+
+// After — guard clauses; happy path last, exceptions first
+function getShippingCost(order) {
+  if (!order) return null;
+  if (!order.isEligible) return null;
+  if (order.total > 100) return 0;
+  return 5.99;
+}
+```
+
+---
+
+## Pattern 3: Extract Class (Single Responsibility)
+
+**When:** A class has grown to handle multiple concerns; it is hard to describe what it does without using "and".
+
+**Signal:** "This class manages users **and** sends emails **and** generates reports."
+
+```js
+// Before — UserService doing too much
+class UserService {
+  async createUser(data) {
+    /* create in DB */
+  }
+  async deleteUser(id) {
+    /* delete from DB */
+  }
+  async sendWelcomeEmail(user) {
+    /* call email provider */
+  }
+  async sendPasswordResetEmail(user) {
+    /* call email provider */
+  }
+  async generateMonthlyReport() {
+    /* query + format report */
+  }
+  async exportUsersCsv() {
+    /* query + format CSV */
+  }
+}
+
+// After — separated by responsibility
+class UserService {
+  async createUser(data) {
+    /* create in DB */
+  }
+  async deleteUser(id) {
+    /* delete from DB */
+  }
+}
+
+class UserEmailService {
+  async sendWelcomeEmail(user) {
+    /* call email provider */
+  }
+  async sendPasswordResetEmail(user) {
+    /* call email provider */
+  }
+}
+
+class UserReportService {
+  async generateMonthlyReport() {
+    /* query + format report */
+  }
+  async exportUsersCsv() {
+    /* query + format CSV */
+  }
+}
+```
+
+---
+
+## Pattern 4: Replace Magic Number/String with Named Constant
+
+**When:** A numeric or string literal is used without explanation.
+
+```js
+// Before
+if (user.subscriptionTier === 3) {
+  applyDiscount(0.15);
+}
+setTimeout(retryRequest, 5000);
+
+// After
+const ENTERPRISE_TIER = 3;
+const ENTERPRISE_DISCOUNT = 0.15;
+const RETRY_DELAY_MS = 5_000;
+
+if (user.subscriptionTier === ENTERPRISE_TIER) {
+  applyDiscount(ENTERPRISE_DISCOUNT);
+}
+setTimeout(retryRequest, RETRY_DELAY_MS);
+```
+
+---
+
+## Pattern 5: Introduce Parameter Object
+
+**When:** A function takes more than 4 parameters, especially if several are related.
+
+```js
+// Before
+function createBooking(userId, roomId, checkIn, checkOut, guestCount, notes) {}
+
+// After
+function createBooking({
+  userId,
+  roomId,
+  checkIn,
+  checkOut,
+  guestCount,
+  notes,
+}) {}
+
+// Caller — reads like documentation
+await createBooking({
+  userId: currentUser.id,
+  roomId: selectedRoom.id,
+  checkIn: dates.start,
+  checkOut: dates.end,
+  guestCount: form.guests,
+  notes: form.specialRequests,
+});
+```
+
+---
+
+## Pattern 6: Extract Variable
+
+**When:** A complex expression is used inline; it's hard to understand what it computes.
+
+```js
+// Before
+if (
+  user.plan === "premium" &&
+  Date.now() - user.lastLoginMs < 86400000 &&
+  user.emailVerified
+) {
+  showPremiumContent();
+}
+
+// After
+const isPremium = user.plan === "premium";
+const isActiveToday = Date.now() - user.lastLoginMs < ONE_DAY_MS;
+const isVerified = user.emailVerified;
+
+if (isPremium && isActiveToday && isVerified) {
+  showPremiumContent();
+}
+```
+
+---
+
+## Pattern 7: Consolidate Duplicate Code
+
+**When:** The same logic appears in 2+ places (copy-paste code). Bugs get fixed in one place but not the other.
+
+```js
+// Before — same validation in two places
+// In user-controller.js:
+if (!email || !email.includes("@")) throw new ValidationError("Invalid email");
+
+// In admin-controller.js:
+if (!email || !email.includes("@")) throw new ValidationError("Invalid email");
+
+// After — extracted to a shared utility
+// In utils/validation.js:
+export function validateEmail(email) {
+  if (!email || !email.includes("@"))
+    throw new ValidationError("Invalid email");
+}
+
+// Both controllers import and use it
+import { validateEmail } from "../utils/validation.js";
+validateEmail(req.body.email);
+```
+
+---
+
+## Pattern 8: Replace Inheritance with Composition
+
+**When:** A subclass uses only a small fraction of the parent's interface, or "is-a" doesn't semantically make sense.
+
+```js
+// Before — awkward inheritance
+class Animal {
+  eat() {}
+  sleep() {}
+  fly() {} // not all animals fly
+  swim() {} // not all animals swim
+}
+
+class Dog extends Animal {
+  fly() {
+    throw new Error("Dogs can't fly");
+  } // Violates Liskov
+}
+
+// After — composition with mixins or interfaces
+class Dog {
+  constructor() {
+    this.locomotion = new GroundLocomotion(); // can run
+    this.feeding = new CarnivoreDiet();
+  }
+  move() {
+    return this.locomotion.move();
+  }
+}
+```
+
+---
+
+## Pattern 9: Strangler Fig (incremental large-scale refactoring)
+
+**When:** A large module or system needs a full redesign but can't be replaced all at once.
+
+**Concept:** Build the new implementation alongside the old one; gradually route traffic to the new version until the old one can be deleted.
+
+```js
+// Phase 1: new implementation exists but old one still runs
+class LegacyPaymentProcessor {
+  /* old implementation */
+}
+class NewPaymentProcessor {
+  /* new implementation */
+}
+
+// Phase 2: add a feature flag / router
+class PaymentProcessorAdapter {
+  constructor() {
+    this.legacy = new LegacyPaymentProcessor();
+    this.modern = new NewPaymentProcessor();
+  }
+
+  async charge(amount, card) {
+    if (featureFlags.useNewPaymentProcessor) {
+      return this.modern.charge(amount, card);
+    }
+    return this.legacy.charge(amount, card);
+  }
+}
+
+// Phase 3: once confidence is high, remove the legacy processor
+```
+
+---
+
+## Pattern 10: Parallel Change (expand, migrate, contract)
+
+**When:** Changing a function signature or data structure that has many callers — you need to migrate safely without breaking everything at once.
+
+```
+Step 1 — Expand: Add the new parameter alongside the old one
+  function getUser(id, options = {}) { ... }
+
+Step 2 — Migrate: Update all callers to use the new signature
+  getUser(id, { includeProfile: true })
+
+Step 3 — Contract: Remove the old parameter once all callers are updated
+  function getUser(id, options) { ... }
+```
+
+---
+
+## Pattern 11: Dead Code Removal
+
+**When:** Functions, variables, or branches are never reached.
+
+**Detection:**
+
+```bash
+# Find unused exports (TypeScript)
+npx ts-prune
+
+# Find unused variables
+eslint --rule 'no-unused-vars: error'
+
+# Find unreachable code after return
+# Most linters catch this; look for ESLint 'no-unreachable'
+```
+
+**Before removing:**
+
+1. Confirm with a search: is this truly never called? (Dynamic calls, reflection, string interpolation can fool static analysis)
+2. Check git history: was this disabled recently for a reason?
+3. Check if it's used in tests only — that's still "used" but warrants a discussion
+
+---
+
+## Pattern 12: Replace if/else chain with lookup table
+
+**When:** A long if/else or switch that maps values to actions or results.
+
+```js
+// Before — hard to extend, easy to miss a case
+function getStatusLabel(status) {
+  if (status === "pending") return "Awaiting approval";
+  else if (status === "approved") return "Approved";
+  else if (status === "rejected") return "Rejected";
+  else if (status === "cancelled") return "Cancelled";
+  else return "Unknown";
+}
+
+// After — lookup table; adding a new status is one line
+const STATUS_LABELS = {
+  pending: "Awaiting approval",
+  approved: "Approved",
+  rejected: "Rejected",
+  cancelled: "Cancelled",
+};
+
+function getStatusLabel(status) {
+  return STATUS_LABELS[status] ?? "Unknown";
+}
+```

package/content/plugins/refactoring/skills/agileflow-refactor/references/safety-checks.md

@@ -0,0 +1,177 @@
+# Refactoring Safety Checks
+
+**Load this when:** assessing the risk of a refactoring before starting, or verifying a refactoring is complete and safe to commit.
+
+---
+
+## Why safety matters
+
+Refactoring without adequate safety measures creates two common failure modes:
+
+1. **Behaviour changes silently** — the refactoring introduced a subtle difference (different error type, changed evaluation order, missing case) that wasn't caught
+2. **Tests weren't sufficient** — tests passed, but they weren't testing the right thing; the regression only shows up in production
+
+The checklists here mitigate both.
+
+---
+
+## Pre-refactoring checklist
+
+Work through this before touching any code.
+
+### 1. Tests exist and pass
+
+- [ ] There are tests for the code being refactored
+- [ ] The tests are passing right now (before any change)
+- [ ] The tests are in the correct layer (unit, integration) for the code being changed
+- [ ] If tests don't exist: STOP — write characterisation tests first
+
+**Minimum test coverage required before refactoring:**
+
+- All public method happy paths
+- At least one error/exception path
+- Any code paths that will be structurally affected by the refactoring
+
+### 2. Impact analysis
+
+- [ ] I know which callers/consumers use the code being changed
+- [ ] For functions: searched for all call sites with `grep -r "functionName"`
+- [ ] For modules: searched for all imports with `grep -r "from './module'"`
+- [ ] For types/interfaces: TypeScript compiler will catch violations; ESLint for JS
+- [ ] For exported symbols: not used by external packages/consumers
+
+### 3. Public API check
+
+Is the code being changed part of a public API (consumed externally)?
+
+| API type             | Risk      | Required action                             |
+| -------------------- | --------- | ------------------------------------------- |
+| Internal function    | Low       | Proceed with care                           |
+| Public module export | Medium    | Ensure same external interface is preserved |
+| HTTP endpoint        | High      | Ensure same request/response schema         |
+| SDK / library API    | Very high | Requires deprecation + major version bump   |
+| Database schema      | High      | Requires migration + backward compatibility |
+
+If changing a public API: use **Parallel Change** pattern (expand → migrate → contract) rather than a direct replacement.
+
+### 4. Scope check
+
+- [ ] This refactoring does only ONE type of change (extract, rename, restructure — not all three)
+- [ ] The change can be committed independently (doesn't depend on other uncommitted work)
+- [ ] The change is not bundled with a feature addition or bug fix
+
+If you find yourself doing more than one type of refactoring: split into separate commits.
+
+### 5. Risk assessment
+
+| Factor             | Low risk                     | High risk                                               |
+| ------------------ | ---------------------------- | ------------------------------------------------------- |
+| Code coverage      | > 80%                        | < 40%                                                   |
+| Callers            | Few (< 5)                    | Many (> 20)                                             |
+| Code age           | Recently written             | Legacy, rarely touched                                  |
+| Code clarity       | Easy to understand           | Hard to understand (which is why you're refactoring it) |
+| Team familiarity   | Author or recent contributor | Nobody remembers writing it                             |
+| Production traffic | Low                          | High (hot path)                                         |
+
+For high-risk refactoring: do it in a feature branch, get a review before merging.
+
+---
+
+## Post-refactoring checklist
+
+After every refactoring, confirm these before committing.
+
+### 1. Behaviour preservation
+
+- [ ] All existing tests pass with zero modifications to test expectations
+- [ ] Any test that needed to change: verify it's because the test was wrong, not because behaviour changed
+- [ ] No new linting errors introduced
+
+**Red flags — investigate before proceeding:**
+
+- A test now passes that was previously failing
+- A test needed to be deleted (not just reorganised)
+- A test expectation changed (not just the structure of the test)
+
+### 2. Performance (for hot paths)
+
+For code in a frequently-called code path:
+
+- [ ] No new synchronous I/O introduced
+- [ ] No N+1 query introduced (loop calling DB in each iteration)
+- [ ] No algorithm complexity regression (O(n) → O(n²))
+
+### 3. Error handling preserved
+
+- [ ] Error types thrown are the same (callers may catch specific error types)
+- [ ] Error messages still contain the same diagnostic information
+- [ ] No errors are now silently swallowed that were previously propagated
+
+### 4. Type correctness (TypeScript)
+
+- [ ] `tsc --noEmit` runs clean (no new type errors)
+- [ ] No `any` casts introduced to work around type issues
+
+### 5. API contract preserved
+
+If the refactoring touched an API handler:
+
+- [ ] Request schema unchanged
+- [ ] Response schema unchanged
+- [ ] HTTP status codes unchanged
+- [ ] Header behaviour unchanged
+
+### 6. Commit quality
+
+- [ ] Commit message describes the refactoring pattern: "refactor: extract calculateOrderTotal function"
+- [ ] Commit contains only the refactoring (no feature changes mixed in)
+- [ ] PR description explains what was refactored and why (technical debt? readability? preparation for a feature?)
+
+---
+
+## Characterisation tests (when tests don't exist)
+
+Before refactoring code with no tests, write **characterisation tests** — tests that document the current behaviour (even if that behaviour is wrong or ugly).
+
+```js
+// Characterisation test — tests what the code DOES NOW,
+// not necessarily what it SHOULD do
+describe("LegacyPricingEngine.compute — characterisation", () => {
+  it("returns the price with tax for a standard product", () => {
+    const result = engine.compute({ sku: "PROD-1", qty: 2 });
+    // The exact value — not ideal, but documents current behaviour
+    expect(result.total).toBe(24.2);
+  });
+
+  it("returns 0 for qty of 0", () => {
+    const result = engine.compute({ sku: "PROD-1", qty: 0 });
+    expect(result.total).toBe(0);
+  });
+
+  it("throws for negative qty (current behaviour)", () => {
+    // This might be wrong behaviour, but we document it before changing
+    expect(() => engine.compute({ sku: "PROD-1", qty: -1 })).toThrow();
+  });
+});
+```
+
+These tests protect you from accidentally changing observable behaviour during the refactoring. After the refactoring, you can improve the tests to reflect what the code should do.
+
+---
+
+## Rollback plan
+
+For high-risk refactoring:
+
+1. **Work in a branch** — you can discard without affecting main
+2. **Small commits** — each step can be reverted independently
+3. **Feature flag** — if refactoring a hot path, wrap with a flag to revert at runtime without a deploy
+
+```js
+// Feature flag for refactoring rollback
+const result = featureFlags.useRefactoredPricingEngine
+  ? newPricingEngine.compute(params)
+  : legacyPricingEngine.compute(params);
+```
+
+Remove the flag once confidence is established (after a few days in production with monitoring).