codeforge-dev 1.5.8 → 1.8.0

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

@@ -0,0 +1,141 @@
+# Python Migration Patterns
+
+## Python Version Upgrades (3.8 → 3.12)
+
+### Typing Modernization
+
+| Old Pattern (3.8) | New Pattern (3.10+) | Search Pattern |
+|-------------------|---------------------|----------------|
+| `Optional[X]` | `X \| None` | `from typing import Optional` |
+| `Union[X, Y]` | `X \| Y` | `from typing import Union` |
+| `List[str]` | `list[str]` | `from typing import List` |
+| `Dict[str, int]` | `dict[str, int]` | `from typing import Dict` |
+| `Tuple[int, ...]` | `tuple[int, ...]` | `from typing import Tuple` |
+| `Set[str]` | `set[str]` | `from typing import Set` |
+| `FrozenSet[str]` | `frozenset[str]` | `from typing import FrozenSet` |
+| `Type[X]` | `type[X]` | `from typing import Type` |
+
+**Migration step**: Replace all `typing` imports of built-in generics with lowercase equivalents. Remove unused `typing` imports after replacement.
+
+### Deprecated / Removed Modules
+
+| Module | Removed In | Replacement |
+|--------|-----------|-------------|
+| `distutils` | 3.12 | `setuptools`, `shutil` |
+| `imp` | 3.12 | `importlib` |
+| `lib2to3` | 3.13 | `libcst` or manual |
+| `aifc` | 3.13 | Third-party audio libraries |
+| `cgi` | 3.13 | `urllib.parse`, `email.message` |
+| `cgitb` | 3.13 | `traceback` |
+
+### collections.abc Migration
+
+```python
+# Old (deprecated in 3.9, removed warning in 3.10+)
+from collections import MutableMapping, Sequence, Iterable
+
+# New
+from collections.abc import MutableMapping, Sequence, Iterable
+```
+
+Search for: `from collections import` and check if any imported names are ABCs.
+
+### asyncio Changes
+
+| Old Pattern | New Pattern (3.10+) | Version |
+|------------|---------------------|---------|
+| `asyncio.get_event_loop()` | `asyncio.get_running_loop()` (in async context) | 3.10 |
+| `@asyncio.coroutine` / `yield from` | `async def` / `await` | 3.8 (removed 3.11) |
+| `loop.create_task()` | `asyncio.create_task()` | 3.7 |
+| `asyncio.wait(tasks)` | `asyncio.wait(tasks)` (must pass set) | 3.11 |
+
+---
+
+## Pydantic v1 → v2
+
+### Complete API Mapping
+
+| Pydantic v1 | Pydantic v2 | Notes |
+|-------------|-------------|-------|
+| `@validator('field')` | `@field_validator('field')` | Import from `pydantic` |
+| `@validator('field', pre=True)` | `@field_validator('field', mode='before')` | `mode='before'` replaces `pre=True` |
+| `@validator('field', always=True)` | `@field_validator('field')` + `@model_validator` | `always` removed; use model validator for defaults |
+| `@root_validator` | `@model_validator` | Import from `pydantic` |
+| `@root_validator(pre=True)` | `@model_validator(mode='before')` | Mode parameter |
+| `.dict()` | `.model_dump()` | Method renamed |
+| `.json()` | `.model_dump_json()` | Method renamed |
+| `.parse_obj(data)` | `.model_validate(data)` | Class method renamed |
+| `.parse_raw(json_str)` | `.model_validate_json(json_str)` | Class method renamed |
+| `.schema()` | `.model_json_schema()` | Class method renamed |
+| `.construct()` | `.model_construct()` | Class method renamed |
+| `.copy()` | `.model_copy()` | Method renamed |
+| `class Config:` | `model_config = ConfigDict(...)` | Inline config dict |
+| `Config.schema_extra` | `model_config = ConfigDict(json_schema_extra=...)` | Renamed field |
+| `Config.orm_mode = True` | `model_config = ConfigDict(from_attributes=True)` | Renamed field |
+| `Config.allow_population_by_field_name` | `model_config = ConfigDict(populate_by_name=True)` | Renamed field |
+| `Field(regex=...)` | `Field(pattern=...)` | Parameter renamed |
+
+### Migration Steps
+
+1. Update `pydantic` version in manifest: `pydantic>=2.0`
+2. Convert `class Config:` blocks to `model_config = ConfigDict(...)` — add `from pydantic import ConfigDict`
+3. Convert `@validator` to `@field_validator` — update signatures (first arg is now `cls`, values accessed differently)
+4. Convert `@root_validator` to `@model_validator` — update mode parameter
+5. Replace `.dict()` → `.model_dump()`, `.json()` → `.model_dump_json()`
+6. Replace `.parse_obj()` → `.model_validate()`, `.parse_raw()` → `.model_validate_json()`
+7. Run `pytest` after each step
+
+### Validator Signature Change
+
+```python
+# v1
+@validator('name')
+def validate_name(cls, v, values):
+    return v.strip()
+
+# v2
+@field_validator('name')
+@classmethod
+def validate_name(cls, v: str, info: ValidationInfo) -> str:
+    return v.strip()
+```
+
+Note: In v2, `info.data` replaces `values` for accessing other fields.
+
+---
+
+## Django Version Upgrades
+
+### Common Breaking Changes by Version
+
+| Version | Key Changes |
+|---------|------------|
+| 3.2 → 4.0 | `default_app_config` removed, `USE_L10N` default changed to True |
+| 4.0 → 4.1 | Async view support expanded, `assertFormError` signature changed |
+| 4.1 → 4.2 | `CSRF_TRUSTED_ORIGINS` requires scheme, psycopg3 support |
+| 4.2 → 5.0 | `DEFAULT_AUTO_FIELD` required, `logout()` changed to POST-only |
+| 5.0 → 5.1 | `LoginRequiredMiddleware` added, `HttpResponse.content` stricter |
+
+### Migration Steps
+
+1. Run `python -m django check --deploy` to identify deprecation warnings.
+2. Read the release notes for each version between current and target.
+3. Upgrade one minor version at a time (4.0→4.1→4.2, not 4.0→4.2).
+4. Run `python manage.py migrate` and `python manage.py test` after each version bump.
+
+---
+
+## SQLAlchemy 1.x → 2.x
+
+### Key Changes
+
+| SQLAlchemy 1.x | SQLAlchemy 2.x | Notes |
+|----------------|----------------|-------|
+| `session.query(Model)` | `select(Model)` + `session.execute()` | New select() style |
+| `query.filter()` | `select().where()` | Method renamed |
+| `query.all()` | `session.execute(stmt).scalars().all()` | Execution separated from query building |
+| `Column(Integer)` | `mapped_column(Integer)` | New declarative style |
+| `relationship()` | `relationship()` | Mostly compatible |
+| `engine.execute()` | Removed | Use `with engine.connect() as conn: conn.execute()` |
+
+Run with `SQLALCHEMY_WARN_20=1` environment variable to get deprecation warnings for 1.x patterns before migrating.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/performance-profiling/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: performance-profiling
+description: >-
+  This skill should be used when the user asks to "profile this code",
+  "find the bottleneck", "optimize performance", "measure execution time",
+  "check memory usage", "create a flamegraph", "benchmark this function",
+  "find memory leaks", "reduce latency", "run a performance test",
+  or discusses profiling tools, flamegraphs, benchmarking methodology,
+  cProfile, py-spy, scalene, Chrome DevTools performance,
+  memory profiling, or hot path analysis.
+version: 0.1.0
+---
+
+# Performance Profiling
+
+## Mental Model
+
+Performance work follows one rule: **measure first, optimize second**. Bottlenecks are almost never where you think they are. Developers consistently misjudge performance by 10-100x -- the "obviously slow" nested loop is often fast, while the "simple" database query is the real bottleneck.
+
+The profiling workflow is:
+1. **Establish a baseline** -- measure current performance with a reproducible benchmark
+2. **Profile** -- identify where time and memory are actually spent
+3. **Hypothesize** -- form a specific theory about the bottleneck
+4. **Optimize** -- make one targeted change
+5. **Measure again** -- verify the optimization actually helped
+6. **Compare** -- did the change improve the baseline? By how much?
+
+Without this discipline, you'll waste time optimizing code that doesn't matter, introduce complexity without measurable benefit, and have no proof that your changes helped.
+
+**Amdahl's Law** sets the ceiling: if a function consumes 5% of total runtime, making it infinitely fast saves only 5%. Focus on the biggest bars in the profile first.
+
+---
+
+## Python Profiling
+
+### cProfile (built-in, deterministic)
+
+cProfile instruments every function call. It shows call count, cumulative time, and per-call time:
+
+```bash
+# Profile a script
+python -m cProfile -s cumtime myapp.py
+
+# Profile and save to a file for analysis
+python -m cProfile -o profile.prof myapp.py
+
+# Analyze the saved profile
+python -c "
+import pstats
+p = pstats.Stats('profile.prof')
+p.sort_stats('cumulative')
+p.print_stats(20)  # top 20 functions
+"
+```
+
+**Tradeoff:** cProfile adds ~30% overhead and measures wall-clock time. It's deterministic (traces every call) so it catches everything but distorts timing for very fast functions.
+
+### py-spy (sampling, no overhead)
+
+py-spy samples the call stack without modifying the target process. It can attach to running processes:
+
+```bash
+# Record a flamegraph (SVG)
+py-spy record -o flamegraph.svg -- python myapp.py
+
+# Attach to a running process
+py-spy record -o flamegraph.svg --pid 12345
+
+# Top-like live view
+py-spy top --pid 12345
+
+# Profile for a specific duration
+py-spy record --duration 30 -o flamegraph.svg --pid 12345
+```
+
+**Tradeoff:** Sampling misses very short functions but has near-zero overhead. Ideal for production profiling.
+
+### scalene (CPU + memory + GPU)
+
+Scalene profiles CPU time, memory allocation, and memory usage simultaneously. It distinguishes Python time from native (C) time:
+
+```bash
+# Profile a script
+scalene myapp.py
+
+# Profile with specific options
+scalene --cpu --memory --reduced-profile myapp.py
+
+# Profile a specific function (in code)
+# from scalene import scalene_profiler
+# scalene_profiler.start()
+# ... code to profile ...
+# scalene_profiler.stop()
+```
+
+### memory_profiler (line-by-line memory)
+
+```python
+from memory_profiler import profile
+import pandas as pd
+
+@profile
+def process_data() -> pd.DataFrame:
+    data = pd.read_csv("large.csv")     # Line 5: +500 MiB
+    filtered = data[data["active"]]      # Line 6: +200 MiB
+    result = filtered.groupby("region").sum()  # Line 7: +50 MiB
+    del data, filtered                   # Line 8: -700 MiB
+    return result
+```
+
+```bash
+python -m memory_profiler myapp.py
+```
+
+### line_profiler (line-by-line CPU)
+
+```python
+# Decorate functions to profile
+@profile
+def expensive_function():
+    result = []                     # 0.0%
+    for item in large_list:         # 2.1%
+        parsed = parse(item)        # 45.3%  <-- hot line
+        if validate(parsed):        # 12.7%
+            result.append(parsed)   # 0.4%
+    return result
+```
+
+```bash
+kernprof -l -v myapp.py
+```
+
+> **Deep dive:** See `references/tool-commands.md` for the full command reference per language and tool.
+
+---
+
+## JavaScript / Node.js Profiling
+
+### V8 Profiler (`--prof`)
+
+Node's built-in V8 profiler generates a log that can be processed into a human-readable report:
+
+```bash
+# Generate a V8 profile log
+node --prof app.js
+
+# Process the log into readable output
+node --prof-process isolate-*.log > processed.txt
+```
+
+### clinic.js
+
+A suite of profiling tools for Node.js:
+
+```bash
+# Install
+npm install -g clinic
+
+# Doctor: overall health check (event loop, GC, I/O)
+clinic doctor -- node app.js
+
+# Flame: flamegraph
+clinic flame -- node app.js
+
+# Bubbleprof: async flow visualization
+clinic bubbleprof -- node app.js
+```
+
+### Chrome DevTools
+
+For both browser and Node.js profiling:
+
+```bash
+# Start Node with inspector
+node --inspect app.js
+
+# Or break on first line
+node --inspect-brk app.js
+```
+
+Then open `chrome://inspect` in Chrome:
+- **Performance tab:** Record a profile, see flamechart, call tree, and bottom-up views
+- **Memory tab:** Take heap snapshots, record allocation timelines, detect leaks
+
+### Lighthouse (Web Performance)
+
+```bash
+# CLI audit
+npx lighthouse https://example.com --output json --output html
+
+# Key metrics: FCP, LCP, TTI, TBT, CLS
+# Target: Performance score > 90
+```
+
+---
+
+## System Profiling
+
+When the bottleneck isn't in your code but in the system:
+
+```bash
+# Wall-clock time, user CPU, system CPU
+time python myapp.py
+
+# Process-level resource usage (live)
+htop                    # interactive process viewer
+htop -p 12345           # monitor specific PID
+
+# I/O statistics
+iostat -x 1             # disk I/O per device, every 1 second
+
+# CPU performance counters (Linux)
+perf stat python myapp.py
+# Counts: cycles, instructions, cache misses, branch misses
+
+# System call tracing
+strace -c python myapp.py       # summary of syscall time
+strace -e trace=network app     # only network syscalls
+```
+
+**Interpreting `time` output:**
+- **real** > **user** + **sys** → I/O bound (waiting for disk, network, or sleep)
+- **user** >> **sys** → CPU bound in userspace (computation)
+- **sys** >> **user** → CPU bound in kernel (many syscalls, context switches)
+
+---
+
+## Benchmarking Methodology
+
+Benchmarks must be reproducible, statistically sound, and isolated from noise.
+
+### CLI Benchmarking with hyperfine
+
+```bash
+# Basic benchmark with warmup
+hyperfine --warmup 3 'python myapp.py'
+
+# Compare two implementations
+hyperfine --warmup 3 'python v1.py' 'python v2.py'
+
+# With parameter sweeps
+hyperfine --warmup 3 -P size 100,1000,10000 'python bench.py --size {size}'
+
+# Export results
+hyperfine --warmup 3 --export-json results.json 'python myapp.py'
+```
+
+hyperfine automatically detects outliers, calculates mean/median/stddev, and warns about statistical issues.
+
+### Python Benchmarking with pytest-benchmark
+
+```python
+# benchmark fixture is injected by pytest-benchmark — no import needed
+def test_sort_performance(benchmark) -> None:
+    data = list(range(10000, 0, -1))
+    result = benchmark(sorted, data)
+    assert result == list(range(1, 10001))
+
+
+def test_json_parse_performance(benchmark) -> None:
+    """Benchmark with setup to exclude data preparation from timing."""
+    import json
+    payload = json.dumps({"users": [{"id": i, "name": f"user_{i}"} for i in range(1000)]})
+    result = benchmark(json.loads, payload)
+    assert len(result["users"]) == 1000
+```
+
+```bash
+pytest --benchmark-only --benchmark-sort=mean
+pytest --benchmark-compare          # compare against saved baseline
+pytest --benchmark-save=baseline    # save current results
+```
+
+### Benchmarking Rules
+
+1. **Warmup runs** -- JIT compilers, caches, and OS page faults all affect the first run. Always include warmup.
+2. **Multiple iterations** -- A single measurement is noise. Run at least 10 iterations and report mean, median, and stddev.
+3. **Isolate variables** -- Change one thing at a time. Benchmark before and after each optimization.
+4. **Control the environment** -- Close other applications, disable turbo boost for CPU benchmarks, use consistent hardware.
+5. **Statistical significance** -- If the difference is less than 2x the standard deviation, it's probably noise.
+
+---
+
+## Interpreting Results
+
+### Reading Flamegraphs
+
+Flamegraphs show the call stack over time. The x-axis is **not** time -- it's alphabetically sorted stack frames. Width represents the proportion of total samples.
+
+- **Wide bars at the top** = functions that consume a lot of CPU directly
+- **Wide bars at the bottom** = functions that call expensive children
+- **Plateaus** (flat tops) = functions where time is spent in the function itself, not its children
+- **Look for:** the widest bars at the top of the graph -- these are your hot paths
+
+### Identifying Hot Paths
+
+A hot path is the sequence of function calls that consumes the most cumulative time:
+
+1. Sort by cumulative time (`cumtime` in cProfile)
+2. Find the top-level function with the highest cumulative time
+3. Follow its callees -- which child function consumes the most?
+4. Repeat until you reach a leaf function
+
+The hot path tells you where optimization effort will have the most impact.
+
+### Memory Leak Patterns
+
+Signs of a memory leak:
+- Memory usage grows linearly with time/requests
+- `gc.collect()` doesn't reclaim memory
+- Heap snapshots show growing object counts for a specific type
+
+Common causes:
+- **Unbounded caches** -- dictionaries that grow forever. Fix: use `functools.lru_cache(maxsize=N)` or TTL-based caching.
+- **Event listener accumulation** -- listeners added but never removed. Fix: use weak references or explicit cleanup.
+- **Circular references with `__del__`** -- Python's GC can't collect cycles that have finalizers. Fix: use `weakref` to break the cycle.
+- **Global state accumulation** -- appending to module-level lists. Fix: scope the collection to the request/session lifecycle.
+
+> **Deep dive:** See `references/interpreting-results.md` for annotated examples of profiler output and how to read them.
+
+---
+
+## Ambiguity Policy
+
+These defaults apply when the user does not specify a preference. State the assumption when making a choice:
+
+- **Profiler choice:** Default to py-spy for Python (low overhead, flamegraph output), clinic.js for Node.js, and Chrome DevTools for browser. Use cProfile when the user needs exact call counts.
+- **Benchmark iterations:** Default to at least 10 iterations with 3 warmup runs. Increase for sub-millisecond operations.
+- **Metric focus:** Default to wall-clock time. Switch to CPU time when I/O is deliberately excluded. Switch to memory when the user mentions "memory", "leak", or "OOM".
+- **Optimization scope:** Optimize only the identified hot path. Do not refactor surrounding code for "consistency" unless it's part of the hot path.
+- **Baseline requirement:** Always establish a baseline measurement before optimizing. Refuse to optimize without one -- "it feels slow" is not a baseline.
+- **Reporting:** Report absolute numbers (ms, MB) alongside relative improvements (%). A 50% improvement from 2ms to 1ms matters less than a 10% improvement from 10s to 9s.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/tool-commands.md` | Full command reference for Python, JavaScript, and system profiling tools with all flags and options |
+| `references/interpreting-results.md` | How to read profiler output: annotated cProfile tables, flamegraph walkthroughs, memory timeline interpretation, and benchmark result analysis |