codeforge-dev 1.7.0 → 1.8.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/documentation-patterns/references/docstring-formats.md

@@ -0,0 +1,296 @@
+# Docstring Format Reference
+
+Complete templates for inline documentation across languages. Detect the project's existing style before adding new docstrings.
+
+---
+
+## Python
+
+### Google-Style (Recommended Default)
+
+Detection pattern: `Grep: "Args:"` or `Grep: "Returns:"` in `.py` files.
+
+```python
+def process_payment(amount: float, currency: str, customer_id: str) -> PaymentResult:
+    """Process a payment for the given customer.
+
+    Validates the amount, charges the customer's default payment method,
+    and records the transaction in the payment ledger.
+
+    Args:
+        amount: Payment amount in the smallest currency unit (e.g., cents).
+            Must be positive.
+        currency: ISO 4217 currency code (e.g., "usd", "eur").
+        customer_id: The unique customer identifier from the auth system.
+
+    Returns:
+        PaymentResult with transaction ID, status, and timestamp.
+
+    Raises:
+        InvalidAmountError: If amount is negative or zero.
+        CustomerNotFoundError: If customer_id doesn't match any customer.
+        PaymentGatewayError: If the external payment provider is unreachable.
+
+    Example:
+        >>> result = process_payment(1500, "usd", "cust_abc123")
+        >>> result.status
+        'completed'
+    """
+```
+
+### NumPy-Style
+
+Detection pattern: `Grep: "Parameters\n----------"` (multiline) or `Grep: "----------"` in docstrings.
+
+```python
+def interpolate(x, y, method="linear"):
+    """Interpolate data points using the specified method.
+
+    Parameters
+    ----------
+    x : array_like
+        The x-coordinates of the data points.
+    y : array_like
+        The y-coordinates of the data points. Must have the same length as `x`.
+    method : str, optional
+        Interpolation method. One of 'linear', 'cubic', 'nearest'.
+        Default is 'linear'.
+
+    Returns
+    -------
+    callable
+        An interpolation function that accepts x values and returns
+        interpolated y values.
+
+    Raises
+    ------
+    ValueError
+        If `x` and `y` have different lengths.
+
+    Examples
+    --------
+    >>> f = interpolate([0, 1, 2], [0, 1, 4], method='cubic')
+    >>> f(1.5)
+    2.25
+    """
+```
+
+### Sphinx / reStructuredText
+
+Detection pattern: `Grep: ":param "` or `Grep: ":type "` in `.py` files.
+
+```python
+def connect(host, port, timeout=30):
+    """Connect to the remote server.
+
+    Establishes a TCP connection with configurable timeout.
+
+    :param host: Server hostname or IP address.
+    :type host: str
+    :param port: Server port number (1-65535).
+    :type port: int
+    :param timeout: Connection timeout in seconds. Defaults to 30.
+    :type timeout: int
+    :returns: Active connection handle.
+    :rtype: Connection
+    :raises ConnectionError: If the server is unreachable.
+    :raises ValueError: If port is out of valid range.
+    """
+```
+
+### Module and Class Docstrings
+
+```python
+"""Payment processing module.
+
+Handles payment creation, validation, and gateway communication.
+Supports Stripe and PayPal providers via the adapter pattern.
+
+See `src/payments/adapters/` for provider implementations.
+"""
+
+
+class PaymentProcessor:
+    """Orchestrates payment workflows across multiple providers.
+
+    Manages provider selection, retry logic, and transaction recording.
+    Uses the strategy pattern to delegate provider-specific logic.
+
+    Attributes:
+        default_provider: Name of the fallback payment provider.
+        max_retries: Maximum retry attempts for failed transactions.
+    """
+```
+
+---
+
+## TypeScript / JavaScript
+
+### JSDoc
+
+Detection pattern: `Grep: "@param "` or `Grep: "@returns"` in `.ts` or `.js` files.
+
+```typescript
+/**
+ * Process a payment for the given customer.
+ *
+ * Validates the amount, charges the customer's default payment method,
+ * and records the transaction.
+ *
+ * @param amount - Payment amount in cents (must be positive)
+ * @param currency - ISO 4217 currency code (e.g., "usd", "eur")
+ * @param customerId - The unique customer identifier
+ * @returns Payment result with transaction ID and status
+ * @throws {InvalidAmountError} If amount is negative or zero
+ * @throws {CustomerNotFoundError} If customerId doesn't match any customer
+ *
+ * @example
+ * ```typescript
+ * const result = await processPayment(1500, "usd", "cust_abc123");
+ * console.log(result.status); // "completed"
+ * ```
+ */
+async function processPayment(
+  amount: number,
+  currency: string,
+  customerId: string
+): Promise<PaymentResult> {
+```
+
+### TSDoc
+
+TSDoc is a stricter subset of JSDoc used by TypeScript-focused projects.
+
+Key differences from JSDoc:
+- Uses `{@link ClassName}` for references (not `{@see}`)
+- `@param name -` format (with dash separator)
+- `@throws` without type braces (types are in TypeScript)
+
+```typescript
+/**
+ * Fetches user data from the API.
+ *
+ * @param userId - The user's unique identifier
+ * @param options - Request configuration
+ * @returns The user object, or `undefined` if not found
+ *
+ * @remarks
+ * This method caches results for 5 minutes. Use {@link invalidateCache}
+ * to force a fresh fetch.
+ */
+```
+
+### Module / File Headers
+
+```typescript
+/**
+ * @module payments
+ *
+ * Payment processing module handling Stripe and PayPal integrations.
+ * Entry point: {@link PaymentProcessor.process}
+ */
+```
+
+---
+
+## Go (godoc)
+
+Detection pattern: Comments starting with the function/type name: `Grep: "^// [A-Z]"` before `func` or `type` declarations.
+
+```go
+// ProcessPayment charges the customer's default payment method.
+// Amount is in the smallest currency unit (e.g., cents for USD).
+// Currency must be a valid ISO 4217 code.
+//
+// Returns the transaction result or an error if the charge fails.
+// Possible errors: ErrInvalidAmount, ErrCustomerNotFound, ErrGatewayUnavailable.
+func ProcessPayment(amount int64, currency string, customerID string) (*PaymentResult, error) {
+```
+
+### Package Comments
+
+```go
+// Package payments provides payment processing across multiple providers.
+//
+// It supports Stripe and PayPal via pluggable adapters. Use NewProcessor
+// to create a processor with the desired provider configuration.
+//
+// Example:
+//
+//	p := payments.NewProcessor(payments.WithStripe(apiKey))
+//	result, err := p.Process(ctx, 1500, "usd", "cust_123")
+package payments
+```
+
+### godoc Conventions
+
+- First sentence starts with the name being documented: "ProcessPayment charges..."
+- Use complete sentences with proper punctuation.
+- Code examples use tab-indented blocks (no triple backticks).
+- Document exported (capitalized) identifiers only.
+
+---
+
+## Rust (rustdoc)
+
+Detection pattern: `Grep: "/// "` or `Grep: "//! "` in `.rs` files.
+
+```rust
+/// Process a payment for the given customer.
+///
+/// Validates the amount, charges the customer's default payment method,
+/// and records the transaction in the payment ledger.
+///
+/// # Arguments
+///
+/// * `amount` - Payment amount in cents (must be positive)
+/// * `currency` - ISO 4217 currency code (e.g., "usd", "eur")
+/// * `customer_id` - The unique customer identifier
+///
+/// # Returns
+///
+/// A `PaymentResult` with transaction ID, status, and timestamp.
+///
+/// # Errors
+///
+/// Returns `PaymentError::InvalidAmount` if the amount is zero or negative.
+/// Returns `PaymentError::CustomerNotFound` if the customer ID is invalid.
+///
+/// # Examples
+///
+/// ```
+/// let result = process_payment(1500, "usd", "cust_abc123")?;
+/// assert_eq!(result.status, PaymentStatus::Completed);
+/// ```
+///
+/// # Panics
+///
+/// Panics if the payment gateway client is not initialized. Call
+/// `init_gateway()` before using this function.
+pub fn process_payment(amount: u64, currency: &str, customer_id: &str) -> Result<PaymentResult, PaymentError> {
+```
+
+### Module Documentation
+
+```rust
+//! Payment processing module.
+//!
+//! Handles payment creation, validation, and gateway communication.
+//! Supports Stripe and PayPal providers via the adapter pattern.
+//!
+//! # Overview
+//!
+//! Use [`PaymentProcessor::new`] to create a processor, then call
+//! [`PaymentProcessor::process`] to execute a payment.
+```
+
+### Sections Convention
+
+| Section | When to Use |
+|---------|------------|
+| `# Arguments` | All public functions with parameters |
+| `# Returns` | Functions that return non-unit types |
+| `# Errors` | Functions that return `Result` |
+| `# Panics` | Functions that can panic |
+| `# Safety` | Unsafe functions — document invariants |
+| `# Examples` | Always for public API |

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()`