codeforge-dev 1.5.8 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/git-forensics/references/investigation-playbooks.md

@@ -0,0 +1,319 @@
+# Git Investigation Playbooks
+
+Step-by-step playbooks for common git forensic investigations.
+
+## Contents
+
+- [Playbook 1: Finding When a Bug Was Introduced](#playbook-1-finding-when-a-bug-was-introduced)
+- [Playbook 2: Finding Deleted Code](#playbook-2-finding-deleted-code)
+- [Playbook 3: Tracing a Line's History](#playbook-3-tracing-a-lines-history)
+- [Playbook 4: Recovering Lost Work](#playbook-4-recovering-lost-work)
+- [Playbook 5: Identifying Hot Spots and Code Ownership](#playbook-5-identifying-hot-spots-and-code-ownership)
+- [Playbook 6: Understanding a Complex Merge Conflict](#playbook-6-understanding-a-complex-merge-conflict)
+
+---
+
+## Playbook 1: Finding When a Bug Was Introduced
+
+**Scenario:** A feature that used to work is now broken. You need to find the exact commit that introduced the regression.
+
+### Step 1: Establish the boundary
+
+```bash
+# Find a known-good commit (e.g., last release tag)
+git tag --list "v*" --sort=-version:refname | head -5
+
+# Verify the good commit is actually good
+git stash  # save current work
+git checkout v2.1.0
+# run the failing test or reproduce the bug manually
+# if it passes, this is your good commit
+```
+
+### Step 2: Start bisect
+
+```bash
+git bisect start
+git bisect bad HEAD           # current commit is bad
+git bisect good v2.1.0        # last known good commit
+```
+
+### Step 3: Test each checkout
+
+Git will check out a commit roughly in the middle. Test it:
+
+```bash
+# Option A: Manual testing
+pytest tests/test_feature.py -x
+# If it passes: git bisect good
+# If it fails: git bisect bad
+
+# Option B: Automated
+git bisect run pytest tests/test_feature.py -x
+```
+
+### Step 4: Analyze the result
+
+```bash
+# Git outputs the first bad commit
+# Example: abc1234 is the first bad commit
+
+# Examine the commit
+git show abc1234
+git show abc1234 --stat
+
+# Understand the context
+git log --oneline abc1234~5..abc1234
+```
+
+### Step 5: Clean up
+
+```bash
+git bisect reset
+git stash pop  # restore your work
+```
+
+---
+
+## Playbook 2: Finding Deleted Code
+
+**Scenario:** A function or class that used to exist has been deleted. You need to find when it was removed and why.
+
+### Step 1: Search for when the code was last present
+
+```bash
+# Find commits that changed the count of the string
+git log -S "def calculate_tax" --oneline
+
+# Output shows commits where the function was added or removed
+# The LAST commit in the list removed it; the FIRST added it
+```
+
+### Step 2: Examine the removal commit
+
+```bash
+# Show the commit that removed the function
+git show abc1234
+
+# See the full file at the commit BEFORE removal
+git show abc1234^:path/to/file.py
+
+# See the diff to understand what replaced it
+git diff abc1234^..abc1234 -- path/to/file.py
+```
+
+### Step 3: Find the file if it was renamed or moved
+
+```bash
+# If the file itself was deleted, find when
+git log --diff-filter=D --summary | grep "path/to/file.py"
+
+# If the function moved to another file, search with -G
+git log -G "def calculate_tax" --oneline --all
+```
+
+### Step 4: Recover the deleted code
+
+```bash
+# Get the file content from before the deletion
+git show abc1234^:path/to/file.py > recovered_file.py
+
+# Or cherry-pick just the function (manual extraction)
+git show abc1234^:path/to/file.py | grep -A 50 "def calculate_tax"
+```
+
+---
+
+## Playbook 3: Tracing a Line's History
+
+**Scenario:** You need to understand why a specific line of code exists -- who wrote it, when, and in what context.
+
+### Step 1: Initial blame
+
+```bash
+# Blame with whitespace and move detection
+git blame -w -M -C path/to/file.py
+
+# Focus on the specific line range
+git blame -w -M -C -L 42,42 path/to/file.py
+```
+
+### Step 2: Go deeper if the blame shows a bulk change
+
+If blame points to a formatting or refactoring commit:
+
+```bash
+# Blame at the commit BEFORE the bulk change
+git blame -w -M -C abc1234^ -- path/to/file.py -L 42,42
+
+# Or use .git-blame-ignore-revs to skip bulk commits automatically
+git blame --ignore-revs-file .git-blame-ignore-revs path/to/file.py
+```
+
+### Step 3: Read the full commit context
+
+```bash
+# See the full commit that introduced the line
+git show def5678
+
+# See the PR/issue if the commit message references one
+# e.g., "Fix #123" or "Closes #456"
+git log --format="%H %s" | grep "#123"
+```
+
+### Step 4: See all changes to this line over time
+
+```bash
+# Log of all commits that touched this line range
+git log -L 42,42:path/to/file.py
+
+# This shows the line's evolution across commits, including the diff at each step
+```
+
+---
+
+## Playbook 4: Recovering Lost Work
+
+**Scenario:** You accidentally ran `git reset --hard`, deleted a branch, or lost commits.
+
+### Step 1: Don't panic -- check the reflog
+
+```bash
+# See recent HEAD movements
+git reflog
+
+# Look for the commit you lost
+# Example output:
+# abc1234 HEAD@{0}: reset: moving to HEAD~3    ← the reset that lost your work
+# def5678 HEAD@{1}: commit: add user validation ← your lost commit
+# 789abcd HEAD@{2}: commit: fix login bug       ← another lost commit
+```
+
+### Step 2: Verify the lost commit
+
+```bash
+# Check the commit contents
+git show def5678
+git show def5678 --stat
+```
+
+### Step 3: Recover
+
+```bash
+# Option A: Create a branch at the lost commit (safest)
+git branch recovery def5678
+
+# Option B: Cherry-pick the commit onto your current branch
+git cherry-pick def5678
+
+# Option C: Reset to the lost commit (if you want to restore the full state)
+git reset --hard def5678
+```
+
+### Step 4: If reflog doesn't help
+
+```bash
+# Find unreachable objects (last resort)
+git fsck --unreachable --no-reflogs
+
+# This lists dangling commits, blobs, and trees
+# Look for "dangling commit" entries
+# Examine them with git show
+```
+
+---
+
+## Playbook 5: Identifying Hot Spots and Code Ownership
+
+**Scenario:** You're new to a codebase and need to understand which files change most and who knows them best.
+
+### Step 1: Find frequently changed files
+
+```bash
+# Most changed files in the last 6 months
+git log --since="6 months ago" --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20
+```
+
+### Step 2: Find who knows each area
+
+```bash
+# Top contributors overall
+git shortlog -sn --no-merges --since="6 months ago"
+
+# Top contributors for a specific directory
+git shortlog -sn --no-merges -- src/auth/
+
+# Who last touched each file in a directory
+for f in src/auth/*.py; do
+    echo "$f: $(git log -1 --format='%an (%ar)' -- "$f")"
+done
+```
+
+### Step 3: Find coupling (files that change together)
+
+```bash
+# Files that frequently appear in the same commit
+git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -30
+
+# Look for pairs: if file A and file B always change together,
+# they may have hidden coupling that should be made explicit
+```
+
+### Step 4: Identify aging code
+
+```bash
+# Files not modified in over a year
+git log --diff-filter=M --since="1 year ago" --pretty=format: --name-only | sort -u > recent.txt
+git ls-files | sort > all.txt
+comm -23 all.txt recent.txt | head -30
+rm recent.txt all.txt
+```
+
+---
+
+## Playbook 6: Understanding a Complex Merge Conflict
+
+**Scenario:** You have a merge conflict and need to understand the history of both sides before resolving.
+
+### Step 1: See what both branches changed
+
+```bash
+# Changes on your branch since diverging from main
+git log --oneline main..HEAD
+
+# Changes on main since your branch diverged
+git log --oneline HEAD..main
+
+# The common ancestor
+git merge-base HEAD main
+```
+
+### Step 2: Understand the conflicting file's history
+
+```bash
+# History on your branch
+git log --oneline main..HEAD -- path/to/conflicted/file.py
+
+# History on main
+git log --oneline HEAD..main -- path/to/conflicted/file.py
+```
+
+### Step 3: See the three-way diff
+
+```bash
+# During a merge conflict, git stores three versions:
+# :1: = common ancestor (base)
+# :2: = your version (ours)
+# :3: = their version (theirs)
+
+git show :1:path/to/file.py > base.py
+git show :2:path/to/file.py > ours.py
+git show :3:path/to/file.py > theirs.py
+
+# Compare
+diff3 ours.py base.py theirs.py
+```
+
+### Step 4: Resolve with context
+
+Understanding both sides' intent (from the commit messages in Step 1) helps you resolve the conflict correctly rather than just picking one side.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/migration-patterns/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: migration-patterns
+description: >-
+  This skill should be used when the user asks to "migrate from X to Y",
+  "upgrade to version N", "bump Python version", "upgrade pydantic",
+  "migrate express to fastify", "framework migration", "version upgrade",
+  "modernize the codebase", or discusses code migration, framework upgrades,
+  API version bumps, or dependency migration strategies.
+version: 0.1.0
+---
+
+# Migration Patterns
+
+## Mental Model
+
+Migrations are a sequence of **small, verifiable, rollback-safe transformations**. Each step must independently compile, pass tests, and leave the system in a valid state. The moment you batch changes or skip verification, you create a state that is harder to debug than the original problem.
+
+**Key principles:**
+- **One thing at a time.** Each migration step changes one category of code (imports, API calls, configuration, types). Mixing categories makes failures hard to isolate.
+- **Verify after every step.** Build → Test → Lint after each transformation. A broken intermediate state that goes undetected compounds into an undebuggable mess.
+- **Rollback is always an option.** Git checkpoints after each successful step. If step N fails, you can revert to step N-1 cleanly.
+- **Import mapping first.** Most framework migrations change import paths. Map all imports before modifying call sites — this gives you a complete inventory of affected code.
+- **Official guides are the source of truth.** Always fetch and read the official migration guide before planning. Community blog posts may be outdated or incomplete.
+
+---
+
+## Migration Planning Framework
+
+Follow this sequence for every migration:
+
+### 1. Assess Current State
+
+- Read manifest files to identify current version and all dependencies.
+- Use `Glob` and `Grep` to inventory usage of the APIs being migrated.
+- Count occurrences of each deprecated pattern to estimate effort.
+
+### 2. Read Official Guides
+
+- Use `WebFetch` to pull the official migration guide, changelog, and breaking changes list.
+- Note every breaking change that applies to the project.
+- Identify changes with no direct replacement — these need special handling.
+
+### 3. Inventory Affected Files
+
+- Map every file that uses a deprecated API or pattern.
+- Group files by change type (imports, API calls, configuration, types).
+- Count total changes per group to estimate per-step effort.
+
+### 4. Order Steps
+
+Sequence changes so each step is independently buildable:
+
+1. **Configuration** — Manifest files, build configs, tool configs
+2. **Core utilities and shared modules** — Changes here propagate to dependents
+3. **Business logic** — Module by module, starting with lowest dependency count
+4. **Route handlers / controllers** — Often the most numerous changes
+5. **Tests** — Updated last to match migrated source
+
+### 5. Risk Assessment
+
+Flag high-risk changes:
+- Behavioral changes (same API, different default behavior)
+- Removed APIs with no direct replacement
+- Database schema changes
+- Serialization format changes (affects stored data)
+
+### 6. Present Plan
+
+Output numbered steps with:
+- File count per step
+- Risk level (low / medium / high)
+- Verification command
+- Rollback command
+
+---
+
+## Step Verification Protocol
+
+After each migration step, run these checks in order:
+
+| Check | Command Examples | Purpose |
+|-------|-----------------|---------|
+| **Syntax** | `python -m py_compile`, `npx tsc --noEmit`, `node --check` | Code parses correctly |
+| **Build** | `npm run build`, `cargo build`, `go build ./...` | Project compiles |
+| **Tests** | `pytest`, `npm test`, `cargo test`, `go test ./...` | Behavior preserved |
+| **Lint** | `ruff check`, `npm run lint`, `cargo clippy` | Style and correctness |
+
+If any check fails:
+1. Identify which change in this step caused the failure.
+2. Fix within the current step — do not proceed to the next.
+3. If the fix is unclear, report the failure with full error output.
+4. Never fix forward by making changes intended for later steps.
+
+---
+
+## Rollback Strategy
+
+- **Before starting**: Verify the user has committed or stashed current work.
+- **After each step**: Suggest a commit checkpoint: "Step N complete — recommend committing now."
+- **On failure**: Provide exact `git checkout -- <files>` commands to revert to the last good state.
+- **Database migrations**: Always plan the down-migration alongside the up-migration.
+- **Feature flags**: For gradual migrations, consider feature flags to run old and new code paths in parallel.
+
+---
+
+## Import-First Strategy
+
+Most framework migrations change import paths. Map imports before modifying call sites:
+
+1. **Inventory**: `Grep` for all imports from the old framework/library.
+2. **Map**: Create a mapping of old import → new import.
+3. **Transform**: Change all imports in a single step.
+4. **Verify**: Build and test after import changes (some imports may have side effects).
+5. **Proceed**: With imports correct, modify call sites knowing the right modules are loaded.
+
+This approach gives you a complete inventory of affected code before making any behavioral changes.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Why It Fails | Prevention |
+|---------|-------------|------------|
+| Batching all changes | One failure breaks everything; can't isolate cause | One category per step |
+| Skipping verification | Errors compound silently | Build + test after every step |
+| Fixing forward | New changes mask existing failures | Fix in current step or revert |
+| Ignoring transitive deps | A dependency may not support the target version | Check compatibility first |
+| Mixing migration with refactoring | Two concerns, double the failure modes | Migrate first, refactor later |
+| Not reading the migration guide | Miss non-obvious behavioral changes | Official guide before planning |
+
+---
+
+## Ambiguity Policy
+
+| Ambiguity | Default |
+|-----------|---------|
+| **Verification depth** | Full suite: build + test + lint after every step |
+| **Step granularity** | One file category per step (imports, then API calls, then config) |
+| **Unknown migration path** | Fetch docs, analyze both APIs, present mapping for review |
+| **Partial migration requested** | Warn about inconsistency; verify the module's own tests pass |
+| **Target version not specified** | Migrate to the latest stable release |
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| [Python Migrations](references/python-migrations.md) | Python version upgrades (3.8→3.12), Pydantic v1→v2 API mapping, Django and SQLAlchemy migration patterns |
+| [JavaScript Migrations](references/javascript-migrations.md) | Express→Fastify mapping, React upgrade patterns, TypeScript version upgrades, CommonJS→ESM migration |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/migration-patterns/references/javascript-migrations.md

@@ -0,0 +1,179 @@
+# JavaScript / TypeScript Migration Patterns
+
+## Express → Fastify
+
+### Route Mapping
+
+| Express | Fastify | Notes |
+|---------|---------|-------|
+| `app.get('/path', handler)` | `fastify.get('/path', handler)` | Similar signature |
+| `app.post('/path', handler)` | `fastify.post('/path', handler)` | Similar signature |
+| `app.use(middleware)` | `fastify.register(plugin)` | Middleware → plugin model |
+| `app.use('/prefix', router)` | `fastify.register(plugin, { prefix: '/prefix' })` | Router → registered plugin |
+
+### Request / Response API
+
+| Express | Fastify | Notes |
+|---------|---------|-------|
+| `req.body` | `request.body` | Same concept, different naming convention |
+| `req.params.id` | `request.params.id` | Same |
+| `req.query.page` | `request.query.page` | Same |
+| `req.headers` | `request.headers` | Same |
+| `res.status(200).json(data)` | `reply.code(200).send(data)` | `status` → `code`, `json` → `send` |
+| `res.send('text')` | `reply.send('text')` | Same |
+| `res.redirect('/url')` | `reply.redirect('/url')` | Same |
+| `res.set('header', 'value')` | `reply.header('header', 'value')` | `set` → `header` |
+
+### Middleware → Plugin Conversion
+
+```javascript
+// Express middleware
+app.use((req, res, next) => {
+  req.startTime = Date.now();
+  next();
+});
+
+// Fastify equivalent (using hooks)
+fastify.addHook('onRequest', async (request, reply) => {
+  request.startTime = Date.now();
+});
+```
+
+### Error Handling
+
+```javascript
+// Express error handler
+app.use((err, req, res, next) => {
+  res.status(err.status || 500).json({ error: err.message });
+});
+
+// Fastify error handler
+fastify.setErrorHandler((error, request, reply) => {
+  reply.code(error.statusCode || 500).send({ error: error.message });
+});
+```
+
+### Migration Steps
+
+1. Install Fastify: `npm install fastify`
+2. Create Fastify app instance to replace Express app
+3. Convert middleware to Fastify plugins/hooks
+4. Convert route handlers (update request/response API calls)
+5. Convert error handling
+6. Update tests to use `fastify.inject()` instead of `supertest`
+7. Remove Express: `npm uninstall express`
+
+---
+
+## React Version Upgrades
+
+### React 17 → 18
+
+| Change | Action |
+|--------|--------|
+| `ReactDOM.render()` | Replace with `createRoot().render()` |
+| `ReactDOM.hydrate()` | Replace with `hydrateRoot()` |
+| Automatic batching | No code change — now batches all state updates by default |
+| `useId()` hook | New — use for accessible server/client IDs |
+| Strict Mode double-rendering | Now also double-invokes effects in dev mode |
+
+```javascript
+// React 17
+import ReactDOM from 'react-dom';
+ReactDOM.render(<App />, document.getElementById('root'));
+
+// React 18
+import { createRoot } from 'react-dom/client';
+const root = createRoot(document.getElementById('root'));
+root.render(<App />);
+```
+
+### React 18 → 19
+
+| Change | Action |
+|--------|--------|
+| `forwardRef` | No longer needed — `ref` is a regular prop |
+| `React.lazy` | Now supports server components |
+| Context | `<Context>` replaces `<Context.Provider>` |
+| `use()` hook | New — reads resources (promises, context) during render |
+| `ref` callbacks | Now support cleanup functions (return from callback) |
+| Metadata tags | `<title>`, `<meta>`, `<link>` in components hoist to `<head>` |
+
+---
+
+## TypeScript Version Upgrades
+
+### Key Changes by Version
+
+| Version | Notable Changes |
+|---------|----------------|
+| 4.7 → 4.8 | Stricter type narrowing in `in` operator |
+| 4.8 → 4.9 | `satisfies` operator |
+| 4.9 → 5.0 | Decorators (TC39 standard), `bundler` module resolution |
+| 5.0 → 5.1 | Easier implicit returns for `undefined`, linked cursors |
+| 5.1 → 5.2 | `using` declarations (explicit resource management) |
+| 5.2 → 5.3 | Import attributes, narrowing in `switch(true)` |
+| 5.3 → 5.4 | `NoInfer<T>` utility type, improved narrowing in closures |
+| 5.4 → 5.5 | Inferred type predicates, regex syntax checking |
+
+### tsconfig Changes
+
+| Old Option | New Option | Version |
+|-----------|-----------|---------|
+| `moduleResolution: "node"` | `moduleResolution: "bundler"` | 5.0+ (for bundled apps) |
+| `target: "es2020"` | `target: "es2022"` | 5.0+ (enables native decorators) |
+| `importsNotUsedAsValues` | `verbatimModuleSyntax` | 5.0 (consolidates 3 flags into 1) |
+
+---
+
+## CommonJS → ESM Migration
+
+### Step-by-Step
+
+1. **Update `package.json`**: Add `"type": "module"`
+2. **Rename if needed**: `.js` files become ESM by default; use `.cjs` for files that must stay CommonJS
+3. **Convert imports**:
+
+| CommonJS | ESM |
+|----------|-----|
+| `const x = require('pkg')` | `import x from 'pkg'` |
+| `const { a, b } = require('pkg')` | `import { a, b } from 'pkg'` |
+| `module.exports = x` | `export default x` |
+| `module.exports = { a, b }` | `export { a, b }` |
+| `exports.a = x` | `export const a = x` |
+
+4. **Fix path imports**: ESM requires file extensions in relative imports: `import x from './utils.js'` (not `'./utils'`)
+5. **Replace `__dirname` / `__filename`**:
+
+```javascript
+// CommonJS
+const dir = __dirname;
+const file = __filename;
+
+// ESM
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+```
+
+6. **Replace `require.resolve`**:
+
+```javascript
+// CommonJS
+const resolved = require.resolve('pkg');
+
+// ESM
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const resolved = require.resolve('pkg');
+```
+
+7. **Update tooling configs**: Jest, ESLint, and other tools may need config changes for ESM support.
+
+### Common Gotchas
+
+- JSON imports require import assertions: `import data from './data.json' with { type: 'json' }`
+- Dynamic imports (`import()`) return a module namespace object with a `.default` property
+- Top-level `await` is available in ESM (not in CommonJS)
+- Some packages only export CommonJS — use `import pkg from 'pkg'` (default import) or dynamic `import()`