devflow-kit 0.8.1 → 1.0.0

package/shared/skills/dependencies-patterns/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: dependencies-patterns
+description: Dependency analysis patterns for code review. Detects known CVEs, outdated packages, license incompatibilities, and unnecessary transitive dependencies. Loaded by Reviewer agent when focus=dependencies.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Dependencies Patterns
+
+Domain expertise for dependency management and security analysis. Use alongside `review-methodology` for complete dependency reviews.
+
+## Iron Law
+
+> **EVERY DEPENDENCY IS AN ATTACK SURFACE**
+>
+> Each package you add is code you didn't write but must trust. Minimize dependencies.
+> Pin versions. Audit regularly. A single compromised transitive dependency can compromise
+> your entire application. "It's a popular package" is not a security review.
+
+---
+
+## Dependency Categories
+
+### 1. Security Vulnerabilities
+
+Known CVEs, vulnerable version ranges, malicious packages.
+
+**Violation**: Wide version range includes vulnerable versions
+```json
+{ "lodash": "^4.0.0" }  // Includes vulnerable 4.17.0-4.17.20
+```
+
+**Correct**: Pin to safe version
+```json
+{ "lodash": "^4.17.21" }  // First safe version
+```
+
+### 2. Version Management
+
+Unpinned versions, missing lockfiles, dependency conflicts.
+
+**Violation**: Unpinned allows any version
+```json
+{ "express": "*", "lodash": "latest" }
+```
+
+**Correct**: Pin with lockfile
+```json
+{ "express": "^4.18.2" }  // + committed lockfile
+```
+
+### 3. Dependency Health
+
+Outdated packages, unused dependencies, unnecessary heavy packages.
+
+**Violation**: Heavy dependency for simple task
+```json
+{ "moment": "^2.29.4" }  // 300KB for date formatting
+```
+
+**Correct**: Use native or lighter alternative
+```typescript
+new Date().toLocaleDateString();  // Native
+```
+
+### 4. License Issues
+
+Incompatible licenses (GPL in MIT project), missing licenses.
+
+**Violation**: GPL in proprietary code
+```bash
+# GPL-3.0: some-package  # Requires your code to be GPL too!
+```
+
+**Correct**: Use permissive licenses only
+```bash
+npx license-checker --failOn "GPL-3.0;AGPL-3.0"
+```
+
+### 5. Supply Chain Risks
+
+Deep transitive dependencies, unmaintained packages, typosquatting.
+
+**Violation**: Typosquatted package
+```json
+{ "loadsh": "1.0.0" }  // Typosquat of "lodash"
+```
+
+**Correct**: Verify package authenticity
+```bash
+npm view loadsh  # Check downloads, repo, maintainers
+```
+
+---
+
+## Extended References
+
+For extended examples and detection commands, see:
+- `references/violations.md` - Extended violation examples by category
+- `references/patterns.md` - Correct dependency management patterns
+- `references/detection.md` - Detection commands and CI integration
+
+---
+
+## Severity Guidelines
+
+| Severity | Indicators |
+|----------|------------|
+| **CRITICAL** | Known exploited CVEs (CISA KEV), confirmed malicious packages, typosquats |
+| **HIGH** | High severity CVEs, unmaintained packages, GPL in proprietary code |
+| **MEDIUM** | Medium CVEs, significantly outdated, wide version ranges, missing lockfile |
+| **LOW** | Unused dependencies, lighter alternatives available, minor version behind |
+
+---
+
+## Dependency Review Checklist
+
+Before approving dependency changes:
+
+- [ ] No known CVEs in added packages
+- [ ] Version ranges appropriate (not too wide)
+- [ ] Lockfile updated and committed
+- [ ] Package actively maintained
+- [ ] License compatible
+- [ ] Package from verified publisher
+- [ ] Transitive dependencies reviewed
+- [ ] Package name verified (not typosquat)
+- [ ] Bundle size impact considered
+- [ ] Native alternatives considered
+
+---
+
+## Common Vulnerability Sources
+
+| Registry | URL |
+|----------|-----|
+| npm Advisory | https://www.npmjs.com/advisories |
+| Snyk Vuln DB | https://snyk.io/vuln |
+| GitHub Advisory | https://github.com/advisories |
+| NVD | https://nvd.nist.gov/ |
+| CISA KEV | https://www.cisa.gov/known-exploited-vulnerabilities-catalog |

package/shared/skills/dependencies-patterns/references/detection.md

@@ -0,0 +1,181 @@
+# Detection Patterns
+
+Commands and patterns for detecting dependency issues.
+
+---
+
+## Vulnerability Detection
+
+```bash
+# npm audit (detailed)
+npm audit
+npm audit --json | jq '.vulnerabilities | keys'
+
+# Yarn audit
+yarn audit
+yarn audit --json
+
+# pnpm audit
+pnpm audit
+pnpm audit --json
+
+# Snyk (more comprehensive)
+npx snyk test
+npx snyk monitor  # Continuous monitoring
+```
+
+---
+
+## Outdated Package Detection
+
+```bash
+# List outdated packages
+npm outdated
+npm outdated --json
+
+# Yarn
+yarn outdated
+
+# pnpm
+pnpm outdated
+
+# Interactive update
+npx npm-check -u
+```
+
+---
+
+## Unused Dependency Detection
+
+```bash
+# depcheck (most comprehensive)
+npx depcheck
+npx depcheck --json
+
+# Alternatives
+npx unimported
+npx knip
+```
+
+---
+
+## Lockfile Verification
+
+```bash
+# Check lockfile exists
+[ -f package-lock.json ] && echo "npm lockfile found"
+[ -f yarn.lock ] && echo "yarn lockfile found"
+[ -f pnpm-lock.yaml ] && echo "pnpm lockfile found"
+
+# Check if lockfile is committed
+git ls-files package-lock.json yarn.lock pnpm-lock.yaml
+
+# Verify lockfile integrity
+npm ci --dry-run
+```
+
+---
+
+## Version Range Detection
+
+```bash
+# Find problematic version ranges
+grep -E '"[*~^]|": "latest|": ""' package.json
+
+# Find exact pins
+grep -E '": "[0-9]+\.[0-9]+\.[0-9]+"' package.json
+
+# Count dependencies
+jq '.dependencies | length' package.json
+jq '.devDependencies | length' package.json
+```
+
+---
+
+## License Detection
+
+```bash
+# List all licenses
+npx license-checker --summary
+
+# Find specific license types
+npx license-checker --onlyAllow "MIT;ISC;BSD-2-Clause;BSD-3-Clause;Apache-2.0"
+
+# Find unknown licenses
+npx license-checker --onlyunknown
+
+# Fail on problematic licenses
+npx license-checker --failOn "GPL-3.0;AGPL-3.0"
+```
+
+---
+
+## Supply Chain Analysis
+
+```bash
+# Dependency tree depth
+npm ls --all | wc -l
+
+# Flat dependency list
+npm ls --all --json | jq '.dependencies | keys | length'
+
+# Find duplicate packages
+npm dedupe --dry-run
+
+# Package metadata
+npm view <package-name>
+npm view <package-name> maintainers
+npm view <package-name> time
+```
+
+---
+
+## Typosquat Detection
+
+```bash
+# Common typosquats to check
+# lodash vs loadsh, lodasg
+# express vs exress, expres
+# react vs reakt, reactt
+
+# Manual check
+npm view <suspicious-package>
+# Look for:
+# - Low weekly downloads
+# - No or suspicious repository
+# - Recent creation date
+# - Unknown maintainer
+```
+
+---
+
+## CI Integration Commands
+
+```bash
+# Combined audit script
+audit_deps() {
+  echo "=== Checking vulnerabilities ==="
+  npm audit --audit-level=high || exit 1
+
+  echo "=== Checking lockfile ==="
+  [ -f package-lock.json ] || [ -f yarn.lock ] || exit 1
+
+  echo "=== Checking licenses ==="
+  npx license-checker --failOn "GPL-3.0;AGPL-3.0" || exit 1
+
+  echo "=== All checks passed ==="
+}
+```
+
+---
+
+## Quick Reference
+
+| Check | Command |
+|-------|---------|
+| Vulnerabilities | `npm audit` |
+| Outdated | `npm outdated` |
+| Unused | `npx depcheck` |
+| Licenses | `npx license-checker` |
+| Tree depth | `npm ls --all \| wc -l` |
+| Lockfile | `ls package-lock.json yarn.lock 2>/dev/null` |

package/shared/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
+```