@shaykec/bridge 0.4.24 → 0.4.26

package/modules/clean-code/exercises.md

@@ -0,0 +1,137 @@
+# Clean Code Exercises
+
+## Exercise 1: Name Refactor
+
+**Task:** Refactor this function with better names and structure:
+
+```javascript
+function proc(u, p) {
+  if (p.length < 8) return false;
+  const h = crypto.hash(p);
+  return u.pw === h;
+}
+```
+
+**Validation:**
+- [ ] All variables and the function have intent-revealing names
+- [ ] A reader can understand the logic without guessing
+- [ ] No abbreviations unless universally known (e.g., `id`)
+
+**Hints:**
+1. `proc` → what does it do? `validatePassword`, `checkCredentials`?
+2. `u` → `user`; `p` → `password`; `h` → `hashedPassword`
+3. Consider extracting the length check or the hash step
+
+---
+
+## Exercise 2: Extract Function
+
+**Task:** This function does several things. Extract at least two smaller functions:
+
+```javascript
+function processOrder(order) {
+  if (!order.items || order.items.length === 0) return { error: 'No items' };
+  if (!order.shippingAddress) return { error: 'No address' };
+  let total = 0;
+  for (const item of order.items) total += item.price * item.quantity;
+  const tax = total * 0.1;
+  const finalTotal = total + tax;
+  saveToDatabase({ ...order, total: finalTotal });
+  sendConfirmationEmail(order.customerEmail);
+  return { success: true, total: finalTotal };
+}
+```
+
+**Validation:**
+- [ ] At least 2 focused functions extracted
+- [ ] Original function orchestrates, doesn't contain low-level logic
+- [ ] Each extracted function has a clear name
+
+**Hints:**
+1. Extract validation into `validateOrder` or separate checks
+2. Extract total calculation into `calculateOrderTotal`
+3. Consider extracting `saveAndNotify` or keep save/email separate
+
+---
+
+## Exercise 3: Replace Magic Numbers
+
+**Task:** Identify and replace magic numbers in this code:
+
+```javascript
+function getPriceTier(customer) {
+  if (customer.orders < 5) return 'bronze';
+  if (customer.orders < 20) return 'silver';
+  return 'gold';
+}
+```
+
+Add constants for the thresholds. Consider: what if the thresholds change?
+
+**Validation:**
+- [ ] Thresholds (5, 20) are named constants
+- [ ] Tier names could also be constants if used elsewhere
+- [ ] Logic is unchanged, readability improved
+
+**Hints:**
+1. `const BRONZE_MIN_ORDERS = 0`, `SILVER_MIN_ORDERS = 5`, `GOLD_MIN_ORDERS = 20`
+2. Or `const TIER_THRESHOLDS = [5, 20]` for easier config
+3. Document the business rule if non-obvious
+
+---
+
+## Exercise 4: Reduce Nesting
+
+**Task:** Refactor this to use early returns:
+
+```javascript
+function findUser(id) {
+  if (id) {
+    const user = db.query('users', id);
+    if (user) {
+      if (user.isActive) {
+        return user;
+      } else {
+        return null;
+      }
+    } else {
+      return null;
+    }
+  } else {
+    return null;
+  }
+}
+```
+
+**Validation:**
+- [ ] No more than 2 levels of nesting
+- [ ] Early returns handle invalid cases
+- [ ] Happy path is clear at the end
+
+**Hints:**
+1. `if (!id) return null;` first
+2. `if (!user) return null;` next
+3. `if (!user.isActive) return null;` then return user
+
+---
+
+## Exercise 5: Self-Documenting Code
+
+**Task:** Remove the comment and make the code speak for itself:
+
+```javascript
+// Check if the user has reached the free tier limit
+if (users.filter(u => u.plan === 'free').length >= 10) {
+  showUpgradePrompt();
+}
+```
+
+**Validation:**
+- [ ] Comment removed
+- [ ] Intent clear from names and structure
+- [ ] Consider extracting to a named boolean variable
+
+**Hints:**
+1. `const freeUserCount = users.filter(u => u.plan === 'free').length;`
+2. `const FREE_TIER_LIMIT = 10;`
+3. `const hasReachedFreeTierLimit = freeUserCount >= FREE_TIER_LIMIT;`

package/modules/clean-code/game.yaml

@@ -0,0 +1,172 @@
+games:
+  - type: bug-hunt
+    title: "Code Smell Detective"
+    snippets:
+      - code: |
+          function process(d) {
+            if (d < 18) return "minor";
+            if (d < 65) return "adult";
+            return "senior";
+          }
+          const result = process(25);
+        bugLine: 2
+        explanation: "Magic number 18 — age thresholds should be named constants (e.g. MIN_ADULT_AGE) so intent is clear and changes are centralized."
+        hint: "What does the number 18 represent?"
+      - code: |
+          function doStuff(a, b, c, x, y) {
+            const t = a * x + b * y;
+            const r = c ? t * 1.1 : t;
+            return Math.round(r * 100) / 100;
+          }
+        bugLine: 2
+        explanation: "God function — does too much: computes a formula, applies a flag-based adjustment, and formats. Split into focused functions with descriptive names."
+        hint: "How many responsibilities does this function have?"
+      - code: |
+          const d = new Date();
+          const x = users.filter(u => u.active).length;
+          const discount = price > 100 ? 0.1 : 0.05;
+        bugLine: 1
+        explanation: "Unclear variable names — 'd', 'x' tell nothing. Use descriptive names: currentDate, activeUserCount, discountRate."
+        hint: "What does 'd' or 'x' convey to a reader?"
+      - code: |
+          function sendEmail(user, body, notify = true) {
+            if (notify) {
+              log("Sent to " + user.email);
+            }
+            return mailer.send(user.email, body);
+          }
+        bugLine: 2
+        explanation: "Boolean parameter — 'notify' obscures intent. Prefer separate methods (sendEmail vs sendEmailQuietly) or an options object."
+        hint: "What does notify=true mean at the call site?"
+      - code: |
+          function calcTotal(items) {
+            let t = 0;
+            for (let i = 0; i < items.length; i++) {
+              if (items[i].onSale) {
+                t += items[i].price * 0.8;
+              } else {
+                t += items[i].price;
+              }
+            }
+            return t;
+          }
+        bugLine: 5
+        explanation: "Magic number 0.8 — discount factor should be a named constant (e.g. SALE_DISCOUNT = 0.8) for clarity and easy maintenance."
+        hint: "What does 0.8 mean in this context?"
+      - code: |
+          function validateOrder(order) {
+            if (order.items) {
+              if (order.items.length > 0) {
+                if (order.shipping) {
+                  if (order.shipping.address) {
+                    return true;
+                  }
+                }
+              }
+            }
+            return false;
+          }
+        bugLine: 3
+        explanation: "Deeply nested conditionals — hard to follow. Use guard clauses or early returns to flatten and improve readability."
+        hint: "How many levels of nesting?"
+      - code: |
+          function fetchUser(id) {
+            const user = db.query("SELECT * FROM users WHERE id = ?", id);
+            return user;
+            console.log("Fetched user:", id);
+          }
+        bugLine: 4
+        explanation: "Dead code — the console.log is unreachable after the return statement. Remove it or move before the return."
+        hint: "Can this line ever execute?"
+      - code: |
+          const data = await fetch("/api/config");
+          const cfg = JSON.parse(data);
+          const t = cfg.timeout || 5000;
+          return t;
+        bugLine: 3
+        explanation: "Magic number 5000 — default timeout should be a named constant (e.g. DEFAULT_TIMEOUT_MS) so milliseconds intent is clear."
+        hint: "What unit is 5000? Is that obvious?"
+
+  - type: speed-round
+    title: "Clean Code Quick Fire"
+    rounds:
+      - question: "Which variable name is better for a user's email address?"
+        options:
+          - "e"
+          - "em"
+          - "userEmail"
+          - "ue"
+        answer: 2
+        timeLimit: 14
+      - question: "What code smell does a function with 8 parameters and 50 lines typically have?"
+        options:
+          - "Magic numbers"
+          - "Dead code"
+          - "God function / too many responsibilities"
+          - "Unclear naming"
+        answer: 2
+        timeLimit: 15
+      - question: "A literal number 86400000 appears in code. What should you do?"
+        options:
+          - "Leave it as is — it's self-explanatory"
+          - "Replace with a named constant (e.g. MS_PER_DAY)"
+          - "Add a comment explaining it"
+          - "Move it to a config file only"
+        answer: 1
+        timeLimit: 16
+      - question: "Which is the better practice for a boolean parameter like sendNotification?"
+        options:
+          - "Keep the boolean — it's clear"
+          - "Split into two functions (e.g. send vs sendQuietly)"
+          - "Use 0 or 1 instead"
+          - "Add more boolean parameters for related options"
+        answer: 1
+        timeLimit: 15
+      - question: "You find code that runs after a return statement. What is it?"
+        options:
+          - "A feature for logging"
+          - "Dead code"
+          - "A fallback path"
+          - "Defensive programming"
+        answer: 1
+        timeLimit: 12
+      - question: "What should you refactor first when improving readability?"
+        options:
+          - "Add more comments"
+          - "Rename unclear variables and extract magic numbers"
+          - "Increase indentation for clarity"
+          - "Split the file into more files"
+        answer: 1
+        timeLimit: 16
+      - question: "A function has 4 levels of nested if statements. What's the main issue?"
+        options:
+          - "Too many parameters"
+          - "Deep nesting reduces readability — use guard clauses"
+          - "Missing type annotations"
+          - "Wrong programming language"
+        answer: 1
+        timeLimit: 15
+      - question: "Which name better describes a function that formats a price for display?"
+        options:
+          - "doIt"
+          - "format"
+          - "formatPriceForDisplay"
+          - "fn"
+        answer: 2
+        timeLimit: 14
+      - question: "Code has numbers 30, 60, 90 scattered throughout. What smell is this?"
+        options:
+          - "Dead code"
+          - "Magic numbers — extract to named constants"
+          - "Bad naming"
+          - "Long function"
+        answer: 1
+        timeLimit: 14
+      - question: "A 200-line function validates input, transforms data, calls 5 APIs, and formats output. What's wrong?"
+        options:
+          - "Nothing — monoliths are fine"
+          - "God function — does too many things; should be split"
+          - "Needs more comments"
+          - "Should use a different framework"
+        answer: 1
+        timeLimit: 16

package/modules/clean-code/module.yaml

@@ -0,0 +1,44 @@
+slug: clean-code
+title: "Clean Code — Naming, Functions, and Readability That Scales"
+version: 1.0.0
+description: "Write code that humans can read — naming, function design, and refactoring habits."
+category: fundamentals
+tags: [clean-code, readability, refactoring, naming, functions]
+difficulty: beginner
+
+xp:
+  read: 10
+  walkthrough: 30
+  exercise: 20
+  quiz: 15
+  quiz-perfect-bonus: 10
+  game: 20
+  game-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 15
+  guided: 40
+
+prerequisites: []
+related: [solid-principles, code-review]
+
+triggers:
+  - "How do I write clean code?"
+  - "What makes code readable?"
+  - "How should I name variables and functions?"
+  - "When should I refactor?"
+
+visuals:
+  diagrams: [diagram-flow]
+  quiz-types: [quiz-fill-blank, quiz-timed-choice]
+  game-types: [bug-hunt, speed-round]
+  playground: javascript
+
+sources:
+  - url: "https://martinfowler.com/books/refactoring.html"
+    label: "Refactoring by Martin Fowler"
+    type: docs
+  - url: "https://www.oreilly.com/library/view/clean-code-a/9780136083238/"
+    label: "Clean Code by Robert Martin"
+    type: docs

package/modules/clean-code/quick-ref.md

@@ -0,0 +1,44 @@
+# Clean Code Quick Reference
+
+## Naming
+
+| Principle | Example |
+|-----------|---------|
+| Reveal intent | `secondsPerDay` not `d` |
+| Avoid disinformation | `accounts` not `accountList` if not a List |
+| Use pronounceable names | `generationTimestamp` not `genymdhms` |
+| Use searchable names | `MAX_ITEMS` not `7` |
+
+## Functions
+
+| Guideline | Target |
+|-----------|--------|
+| Do one thing | One level of abstraction |
+| Small | Fits on one screen |
+| Few args | 0–2 ideal; 3+ use object |
+| No side effects | Don't surprise callers |
+
+## Refactoring Quick Wins
+
+| Smell | Fix |
+|-------|-----|
+| Magic number | Named constant |
+| Long function | Extract functions |
+| Deep nesting | Early returns |
+| Unclear name | Rename |
+| Comment explaining what | Refactor code |
+
+## Comments
+
+| Good | Bad |
+|------|-----|
+| Why (business rule, workaround) | What (code already shows this) |
+| Legal, compliance | Obvious logic |
+| Non-obvious algorithm | Outdated info |
+
+## DRY vs YAGNI
+
+| DRY | YAGNI |
+|-----|-------|
+| Don't duplicate logic | Don't add speculative code |
+| Extract on 3rd repetition | Build for today's needs |

package/modules/clean-code/quiz.md

@@ -0,0 +1,105 @@
+# Clean Code Quiz
+
+## Question 1
+
+What is the primary benefit of intent-revealing names?
+
+A) Shorter code
+B) Less need for comments; code explains itself
+C) Faster execution
+D) Fewer bugs from the compiler
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Good names make code self-documenting. A reader can understand what the code does without comments. This reduces cognitive load and maintenance cost. -->
+
+## Question 2
+
+When should you extract a block of code into a separate function?
+
+A) Whenever a block is longer than 5 lines
+B) When it represents a distinct abstraction or single logical task
+C) Never — more functions mean more complexity
+D) Only when you reuse it in two places
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Extract when the block does one thing that can be named. Length alone isn't the criterion — a 20-line function that does one thing may be fine. Reuse is a bonus, not the only reason. -->
+
+## Question 3
+
+What does DRY stand for?
+
+A) Don't Repeat Yourself
+B) Do Recursive Yields
+C) Dynamic Run Yields
+D) Data Replication Yearly
+
+<!-- ANSWER: A -->
+<!-- EXPLANATION: DRY = Don't Repeat Yourself. The principle says every piece of knowledge should have a single representation. Duplication breeds inconsistency when one copy is updated and another isn't. -->
+
+## Question 4
+
+When is a comment preferable to self-documenting code?
+
+A) Never — comments are always bad
+B) When explaining *why* something is done, especially non-obvious business rules
+C) When the code is complex
+D) When the function is long
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Good comments explain *why* — business rules, workarounds, legal requirements. Bad comments explain *what* — that's the code's job. If code can be clear, prefer refactoring over comments. -->
+
+## Question 5
+
+What is a "guard clause"?
+
+A) A security check
+B) An early return that handles invalid/edge cases before the main logic
+C) A type check in TypeScript
+D) A unit test
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Guard clauses are early returns (e.g., if (!valid) return;) that handle edge cases first. They reduce nesting and make the happy path more prominent. -->
+
+## Question 6
+
+Which is a code smell indicating a function may do too much?
+
+A) The function has 2 parameters
+B) You need "and" to describe what it does
+C) The function returns a value
+D) The function uses a loop
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: If you can't describe the function without "and" (e.g., "validates and saves and sends email"), it likely has multiple responsibilities and should be split. -->
+
+## Question 7
+
+<!-- VISUAL: fill-blank -->
+
+Complete the refactored function with a guard clause:
+
+```javascript
+function processOrder(order) {
+  if (___0___) return null;
+  return calculateTotal(order.items);
+}
+```
+
+<!-- ANSWER: !order -->
+<!-- EXPLANATION: A guard clause checks for invalid input early and returns. !order handles null or undefined; it's the inverse of a validity check. -->
+
+## Question 8
+
+<!-- VISUAL: fill-blank -->
+
+Complete the intent-revealing name for a function that validates and formats a user's email:
+
+```javascript
+function ___0___(email) {
+  if (!email || !email.includes('@')) return null;
+  return email.trim().toLowerCase();
+}
+```
+
+<!-- ANSWER: validateAndFormatEmail -->
+<!-- EXPLANATION: The function both validates (returns null if invalid) and formats (trim, lowercase). The name should reveal both intents. Alternatives like normalizeEmail are valid if they convey the same. -->

package/modules/clean-code/resources.md

@@ -0,0 +1,40 @@
+# Clean Code — Resources
+
+## Videos
+
+- [Clean Code — Uncle Bob](https://www.youtube.com/watch?v=7EmboKQH8Ul) — Key principles in lecture form.
+- [Refactoring Code](https://www.youtube.com/watch?v=DC-pQPq0acs) — Web Dev Simplified. Practical refactoring examples.
+- [Clean Code Tutorial](https://www.youtube.com/watch?v=UjhX2sVf0eg) — Fireship. Quick overview.
+
+## Articles and Readings
+
+- [Refactoring.com](https://refactoring.com/) — Martin Fowler. Catalog of refactorings.
+- [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) — Conventions many teams follow.
+- [Clean Code JavaScript](https://github.com/ryanmcdermott/clean-code-javascript) — GitHub repo. JS-specific clean code guidelines.
+
+## Books
+
+- **Clean Code** by Robert C. Martin — Foundational text on readable, maintainable code.
+- **Refactoring** by Martin Fowler — Step-by-step refactoring patterns and smells.
+
+## Tools
+
+- [SonarQube](https://www.sonarsource.com/products/sonarqube/) — Static analysis for code quality.
+- [ESLint](https://eslint.org/) — Linting with rules for consistency and common mistakes.
+
+## Podcasts
+
+- [Changelog — Clean Code Episodes](https://changelog.com/topic/code-quality) — Discussions on readability, maintainability, and team conventions.
+- [Software Engineering Radio — Ep 463: Code Smells](https://www.se-radio.net/) — Technical analysis of when code needs refactoring.
+- [Syntax.fm — Code Quality](https://syntax.fm/) — Wes Bos & Scott Tolinski on JS/web code practices.
+
+## Interactive and Visual
+
+- [Refactoring Guru — Code Smells](https://refactoring.guru/refactoring/smells) — Visual catalog of code smells with before/after refactoring examples.
+- [JS Linter Playground](https://eslint.org/play/) — Try ESLint rules in the browser, see violations in real time.
+- [Sourcery](https://sourcery.ai/) — AI-powered refactoring suggestions shown inline.
+
+## Courses
+
+- [Clean Code (Udemy — Robert Martin)](https://www.udemy.com/course/writing-clean-code/) — Video course from the author of Clean Code.
+- [freeCodeCamp — JavaScript Best Practices](https://www.freecodecamp.org/news/tag/clean-code/) — Free articles and tutorials on writing clean JavaScript.

package/modules/clean-code/walkthrough.md

@@ -0,0 +1,78 @@
+# Clean Code Walkthrough — Learn by Doing
+
+## Before We Begin
+
+Clean code isn't about perfection—it's about code that others (and future-you) can read, change, and debug without unnecessary friction.
+
+**Diagnostic question:** Recall a time you struggled to understand someone else's code (or your own from months ago). What made it hard? Was it names, structure, length, or something else?
+
+**Checkpoint:** You can name at least one concrete frustration and guess what a "clean" version might have looked like.
+
+---
+
+## Step 1: Improving Names
+
+<!-- hint:code language="javascript" highlight="1,3" -->
+<!-- hint:card type="concept" title="Intent-revealing names" -->
+
+**Task:** Find a function or variable in your codebase (or use a sample) with an unclear name. Rename it to reveal intent. Before and after: what did the new name communicate that the old one didn't?
+
+**Question:** How do you decide when a name is "good enough"? What would make you choose a longer vs shorter name?
+
+**Checkpoint:** The user can articulate the difference between vague and intent-revealing names.
+
+---
+
+## Step 2: Extracting a Function
+
+**Task:** Take a block of code that does multiple things (e.g., validates input, transforms it, and saves it). Extract one logical piece into a separate function. Ensure the extracted function has a clear, single purpose.
+
+**Question:** How did you decide where to make the cut? What would have been a bad extraction?
+
+**Checkpoint:** The user has a smaller, focused function and can explain the extraction boundary.
+
+---
+
+## Step 3: Reducing Parameters
+
+**Task:** Find or write a function with 4+ parameters. Refactor it to accept a single object parameter. Update the call site.
+
+**Question:** When would you keep separate parameters instead of an object? (Hint: think about 1–2 parameters with distinct roles.)
+
+**Checkpoint:** The user understands when object parameters improve readability.
+
+---
+
+## Step 4: Eliminating Magic Numbers
+
+<!-- hint:card type="warning" title="Common mistake: over-naming obvious literals" -->
+
+**Task:** Find numeric or string literals in code that represent business concepts (status codes, limits, timeouts). Replace them with named constants. Ensure the meaning is now obvious.
+
+**Question:** Is every literal a "magic number"? When is `0` or `1` acceptable without a constant?
+
+**Checkpoint:** The user has replaced at least 2–3 magic values with named constants.
+
+---
+
+## Step 5: Simplifying Nesting
+
+<!-- hint:buttons type="single" prompt="When nesting is deep, which approach do you prefer?" options="Early returns,Extract functions,Both depending on context" -->
+
+**Task:** Take code with 3+ levels of nesting (if/else inside loops, etc.). Refactor using early returns or extracted functions to reduce nesting. Compare readability.
+
+**Question:** What's the "guard clause" pattern? How does returning early simplify the rest of the function?
+
+**Checkpoint:** The user can use early returns and reduced nesting effectively.
+
+---
+
+## Step 6: Comments vs Code
+
+**Task:** Find a comment that explains *what* the code does. Delete the comment and refactor the code so it's self-explanatory. If the comment explained *why*, keep it and ensure it's accurate.
+
+**Question:** When is a comment the right choice instead of refactoring?
+
+**Checkpoint:** The user distinguishes good vs bad comments and prefers self-documenting code when possible.
+
+<!-- hint:celebrate -->