devflow-kit 0.9.0 → 1.1.0

package/plugins/devflow-code-review/skills/dependencies-patterns/references/patterns.md

@@ -0,0 +1,225 @@
+# Correct Dependency Patterns
+
+Best practices for dependency management.
+
+---
+
+## Secure Version Pinning
+
+### Exact Pinning (Most Secure)
+
+```json
+{
+  "dependencies": {
+    "express": "4.18.2",
+    "lodash": "4.17.21"
+  }
+}
+```
+
+**When to use**: Production apps, security-critical dependencies
+
+### Caret with Lockfile (Balanced)
+
+```json
+{
+  "dependencies": {
+    "express": "^4.18.2",
+    "typescript": "^5.3.0"
+  }
+}
+```
+
+**When to use**: Most projects, allows patch updates
+
+### Tilde for Patch-Only (Conservative)
+
+```json
+{
+  "dependencies": {
+    "critical-lib": "~1.2.3"
+  }
+}
+```
+
+**When to use**: When you need bug fixes but not new features
+
+---
+
+## Lockfile Management
+
+### Commit Lockfile
+
+```bash
+# Always commit your lockfile
+git add package-lock.json
+git add yarn.lock
+git add pnpm-lock.yaml
+
+# CI should use frozen installs
+npm ci          # Not npm install
+yarn --frozen-lockfile
+pnpm install --frozen-lockfile
+```
+
+### Renovate/Dependabot Config
+
+```json
+// renovate.json
+{
+  "extends": ["config:base"],
+  "schedule": ["before 9am on Monday"],
+  "packageRules": [
+    {
+      "matchPackagePatterns": ["*"],
+      "groupName": "all dependencies",
+      "groupSlug": "all"
+    },
+    {
+      "matchUpdateTypes": ["patch", "minor"],
+      "automerge": true
+    }
+  ]
+}
+```
+
+---
+
+## Dependency Auditing
+
+### Regular Audit Workflow
+
+```bash
+# Weekly audit
+npm audit
+
+# Fix automatically what's safe
+npm audit fix
+
+# Manual review for breaking changes
+npm audit fix --dry-run
+```
+
+### Pre-commit Hook
+
+```json
+// package.json
+{
+  "scripts": {
+    "preinstall": "npm audit --audit-level=high"
+  }
+}
+```
+
+### CI Pipeline Check
+
+```yaml
+# GitHub Actions
+- name: Security audit
+  run: npm audit --audit-level=high
+```
+
+---
+
+## Minimal Dependencies
+
+### Native Alternatives
+
+| Instead of | Use Native |
+|------------|------------|
+| `moment` | `Intl.DateTimeFormat`, `date-fns` |
+| `lodash` (full) | Native methods, `lodash-es` (tree-shake) |
+| `left-pad` | `String.prototype.padStart()` |
+| `is-array` | `Array.isArray()` |
+| `is-number` | `typeof x === 'number'` |
+
+### Tree-Shaking Imports
+
+```typescript
+// AVOID: Imports entire library
+import _ from 'lodash';
+_.debounce(fn, 100);
+
+// BETTER: Import only what you need
+import debounce from 'lodash/debounce';
+debounce(fn, 100);
+
+// BEST: Use ESM for tree-shaking
+import { debounce } from 'lodash-es';
+debounce(fn, 100);
+```
+
+---
+
+## License Compliance
+
+### License Whitelist
+
+```json
+// .licensrc.json
+{
+  "whitelist": [
+    "MIT",
+    "ISC",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "Apache-2.0"
+  ],
+  "blacklist": [
+    "GPL-3.0",
+    "AGPL-3.0"
+  ]
+}
+```
+
+### CI License Check
+
+```bash
+# Check licenses in CI
+npx license-checker --failOn "GPL-3.0;AGPL-3.0"
+```
+
+---
+
+## Supply Chain Security
+
+### Package Verification
+
+```bash
+# Verify package integrity
+npm pack <package-name> --dry-run
+
+# Check package signatures (npm v8.12+)
+npm audit signatures
+
+# Review before install
+npm view <package-name>
+```
+
+### Minimal Attack Surface
+
+```json
+// Use optional dependencies wisely
+{
+  "dependencies": {
+    "core-lib": "^1.0.0"
+  },
+  "optionalDependencies": {
+    "platform-specific": "^1.0.0"
+  },
+  "devDependencies": {
+    "test-utils": "^1.0.0"
+  }
+}
+```
+
+### Dependency Review for PRs
+
+```yaml
+# GitHub Actions - dependency review
+- name: Dependency Review
+  uses: actions/dependency-review-action@v3
+  with:
+    fail-on-severity: high
+    deny-licenses: GPL-3.0, AGPL-3.0
+```

package/plugins/devflow-code-review/skills/dependencies-patterns/references/violations.md

@@ -0,0 +1,247 @@
+# Extended Violation Examples
+
+Detailed examples of dependency violations by category.
+
+---
+
+## Security Vulnerability Violations
+
+### Known CVEs - Extended Examples
+
+```bash
+# Check for known vulnerabilities
+npm audit
+# or
+yarn audit
+# or
+pnpm audit
+
+# Output example:
+# High: Prototype Pollution in lodash
+# Package: lodash
+# Dependency of: my-package
+# Path: my-package > lodash
+# More info: https://github.com/advisories/GHSA-xxx
+```
+
+### Vulnerable Version Ranges
+
+```json
+// PROBLEM: Wide version range includes vulnerable versions
+{
+  "dependencies": {
+    "lodash": "^4.0.0"  // Includes vulnerable 4.17.0-4.17.20
+  }
+}
+
+// SOLUTION: Pin to safe version or use range excluding vulnerable
+{
+  "dependencies": {
+    "lodash": "^4.17.21"  // First safe version
+  }
+}
+```
+
+### Malicious Package Red Flags
+
+```json
+// RED FLAGS for potentially malicious packages:
+{
+  "dependencies": {
+    "loadsh": "1.0.0",           // Typosquat of "lodash"
+    "event-stream": "3.3.6",     // Known compromised version
+    "random-unknown-pkg": "0.0.1" // No downloads, no repo
+  }
+}
+
+// VERIFY packages:
+// - Check npm page for download counts
+// - Verify repository link
+// - Check maintainer history
+// - Look for typosquatting
+```
+
+---
+
+## Version Management Violations
+
+### Unpinned Versions
+
+```json
+// PROBLEM: Can get different versions on each install
+{
+  "dependencies": {
+    "express": "*",           // Any version!
+    "lodash": "latest",       // Whatever is latest
+    "moment": ""              // Empty = latest
+  }
+}
+
+// SOLUTION: Pin exact or use caret with lockfile
+{
+  "dependencies": {
+    "express": "4.18.2",      // Exact pin
+    "lodash": "^4.17.21",     // Caret + lockfile
+    "moment": "~2.29.4"       // Tilde for patch only
+  }
+}
+```
+
+### Missing Lockfile
+
+```bash
+# PROBLEM: No lockfile committed
+.gitignore:
+package-lock.json  # Don't ignore this!
+yarn.lock          # Don't ignore this!
+
+# SOLUTION: Commit lockfile
+git add package-lock.json  # or yarn.lock
+git commit -m "Add lockfile for reproducible builds"
+```
+
+### Dependency Conflicts
+
+```bash
+# PROBLEM: Multiple versions of same package
+npm ls react
+# my-app
+# +-- react@18.2.0
+# \-- some-library
+#     \-- react@17.0.2  # Conflict!
+
+# SOLUTION: Use resolutions/overrides
+# package.json (yarn)
+{
+  "resolutions": {
+    "react": "18.2.0"
+  }
+}
+
+# package.json (npm)
+{
+  "overrides": {
+    "react": "18.2.0"
+  }
+}
+```
+
+---
+
+## Dependency Health Violations
+
+### Outdated Packages
+
+```bash
+# Check for outdated
+npm outdated
+
+# Package          Current  Wanted  Latest
+# lodash           4.17.15  4.17.21 4.17.21  # Security update!
+# typescript       4.9.5    4.9.5   5.3.2    # Major version
+# @types/node      18.0.0   18.19.0 20.10.0  # Minor updates
+
+# Prioritize:
+# 1. Security patches (lodash)
+# 2. Bug fixes (minor updates)
+# 3. Major versions (careful review)
+```
+
+### Unused Dependencies
+
+```bash
+# Find unused dependencies
+npx depcheck
+
+# Unused dependencies:
+# * moment           # Listed but never imported
+# * lodash           # Listed but never imported
+
+# SOLUTION: Remove unused
+npm uninstall moment lodash
+```
+
+### Unnecessary Heavy Dependencies
+
+```json
+// PROBLEM: Heavy dependencies for simple tasks
+{
+  "dependencies": {
+    "moment": "^2.29.4",     // 300KB for date formatting
+    "lodash": "^4.17.21",    // 70KB for one function
+    "left-pad": "^1.3.0"     // 1KB for string padding
+  }
+}
+
+// SOLUTION: Use native or lighter alternatives
+// Native date formatting
+new Date().toLocaleDateString();
+
+// Native array methods instead of lodash
+array.filter(x => x.active);
+
+// Native string padding
+'5'.padStart(2, '0');
+
+// Or import only what you need
+import { debounce } from 'lodash/debounce';
+```
+
+---
+
+## License Violations
+
+### Incompatible Licenses
+
+```bash
+# Check licenses
+npx license-checker --summary
+
+# Watch for incompatible combinations:
+# - GPL in MIT project (viral license)
+# - Commercial-only licenses
+# - AGPL in SaaS (requires source disclosure)
+
+# Example problematic output:
+# GPL-3.0: some-package  # Requires your code to be GPL too!
+```
+
+### Missing License
+
+```bash
+# Find packages without license
+npx license-checker --onlyunknown
+
+# Packages with unknown license:
+# - internal-company-pkg@1.0.0  # Verify this is intentional
+```
+
+---
+
+## Supply Chain Violations
+
+### Transitive Dependencies
+
+```bash
+# Check dependency tree depth
+npm ls --all | wc -l
+# If > 1000, high supply chain risk
+
+# Audit transitive deps
+npm audit --all
+
+# SOLUTION: Minimize dependencies, audit regularly
+```
+
+### Maintainer Concerns
+
+```json
+// RED FLAGS:
+// - Package with 1 maintainer who's inactive
+// - No recent releases but many open issues
+// - Repository archived or deleted
+// - Maintainer account compromised (check news)
+
+// Check package health:
+// https://snyk.io/advisor/npm-package/{package-name}
+```

package/plugins/devflow-code-review/skills/documentation-patterns/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: documentation-patterns
+description: Documentation analysis patterns for code review. Detects doc drift from code changes, missing documentation for public APIs, stale comments, and misleading README sections. Loaded by Reviewer agent when focus=documentation.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Documentation Patterns
+
+Domain expertise for documentation quality and alignment. Use alongside `review-methodology` for complete documentation reviews.
+
+## Iron Law
+
+> **DOCUMENTATION MUST MATCH REALITY**
+>
+> Outdated documentation is worse than no documentation. It actively misleads. Every code
+> change that affects behavior requires a documentation check. Comments that explain "what"
+> instead of "why" are noise. The best documentation is code that doesn't need documentation.
+
+---
+
+## Documentation Categories
+
+### 1. Code Documentation Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Missing docstrings | Complex functions without explanation | Add JSDoc with params, returns, throws |
+| Outdated comments | Comments that contradict code | Update or remove |
+| "What" comments | `// Loop through users` | Explain "why" instead |
+| Magic algorithms | Complex logic without explanation | Document algorithm and rationale |
+
+**Brief Example - Missing vs. Complete:**
+```typescript
+// BAD: No documentation on complex function
+export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
+
+// GOOD: Purpose, params, returns, edge cases documented
+/**
+ * Calculates prorated billing amount when switching plans mid-cycle.
+ * @param plan - The new plan to prorate to
+ * @returns Prorated amount in cents (can be negative for downgrades)
+ */
+export function calculateProratedAmount(plan: Plan, startDate: Date, endDate: Date): number;
+```
+
+### 2. API Documentation Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Missing params | Callers don't know valid values | Document all params with types and constraints |
+| Missing returns | Return shape unknown | Describe return structure and units |
+| Missing errors | Callers don't know what to catch | List all thrown error types |
+
+**Brief Example - Incomplete vs. Complete:**
+```typescript
+// BAD: No params, no errors documented
+/** Creates a subscription. */
+async function createSubscription(userId: string, planId: string): Promise<Subscription>;
+
+// GOOD: Full contract documented
+/**
+ * @param userId - User's unique identifier
+ * @param planId - Plan ID from /plans endpoint
+ * @throws {UserNotFoundError} If userId doesn't exist
+ * @throws {PlanNotFoundError} If planId doesn't exist
+ */
+async function createSubscription(userId: string, planId: string): Promise<Subscription>;
+```
+
+### 3. Alignment Issues
+
+| Issue | Problem | Fix |
+|-------|---------|-----|
+| Code-comment drift | Comment says 3 retries, code does 5 | Update comment or use constant |
+| Stale README | Examples use removed functions | Keep README in sync with code |
+| Missing changelog | Breaking changes undocumented | Document all notable changes |
+
+**Brief Example - Drift vs. Aligned:**
+```typescript
+// BAD: Comment doesn't match code
+// Retries up to 3 times
+for (let i = 0; i < 5; i++) { /* ... */ }
+
+// GOOD: Use constant to keep aligned
+const MAX_RETRIES = 5;
+for (let i = 0; i < MAX_RETRIES; i++) { /* ... */ }
+```
+
+---
+
+## Extended References
+
+For extended examples and detection commands:
+
+- **[references/violations.md](references/violations.md)** - Extended violation examples with explanations
+- **[references/patterns.md](references/patterns.md)** - Complete correct pattern examples
+- **[references/detection.md](references/detection.md)** - Bash commands for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **CRITICAL** | Actively misleading | Comments contradict code; API docs with wrong types; README with broken steps; Changelog missing breaking changes |
+| **HIGH** | Significant gaps | Public APIs undocumented; Complex algorithms unexplained; Errors not documented; Migration guides missing |
+| **MEDIUM** | Moderate issues | Some params undocumented; Examples could be clearer; "What" comments instead of "why" |
+| **LOW** | Minor improvements | Could add more examples; Formatting inconsistencies; Typos |
+
+---
+
+## Documentation Checklist
+
+Before approving changes:
+
+- [ ] All public APIs have JSDoc/docstrings
+- [ ] Parameters and return values documented
+- [ ] Error conditions documented
+- [ ] Complex algorithms explained
+- [ ] Comments explain "why", not "what"
+- [ ] README reflects current state
+- [ ] CHANGELOG updated for notable changes
+- [ ] No TODO comments for completed work
+- [ ] Examples work with current API