From f9789b01101805339e8e6c5413a2c0f0eaddcafa Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:48:27 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 + README.md | 3 + commands/review_history.md | 43 ++ plugin.lock.json | 93 +++ skills/dependency-evaluator/COMMANDS.md | 355 +++++++++++ .../dependency-evaluator/ECOSYSTEM_GUIDES.md | 460 ++++++++++++++ skills/dependency-evaluator/ERROR_HANDLING.md | 456 ++++++++++++++ skills/dependency-evaluator/EXAMPLES.md | 359 +++++++++++ skills/dependency-evaluator/SCRIPT_USAGE.md | 333 ++++++++++ skills/dependency-evaluator/SIGNAL_DETAILS.md | 486 +++++++++++++++ skills/dependency-evaluator/SKILL.md | 246 ++++++++ skills/dependency-evaluator/WORKFLOW.md | 570 ++++++++++++++++++ .../scripts/dependency_evaluator.py | 419 +++++++++++++ skills/git-workflow-patterns/SKILL.md | 282 +++++++++ skills/workflow-analyzer/SKILL.md | 137 +++++ .../scripts/workflow_analyzer.py | 459 ++++++++++++++ 16 files changed, 4715 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/review_history.md create mode 100644 plugin.lock.json create mode 100644 skills/dependency-evaluator/COMMANDS.md create mode 100644 skills/dependency-evaluator/ECOSYSTEM_GUIDES.md create mode 100644 skills/dependency-evaluator/ERROR_HANDLING.md create mode 100644 skills/dependency-evaluator/EXAMPLES.md create mode 100644 skills/dependency-evaluator/SCRIPT_USAGE.md create mode 100644 skills/dependency-evaluator/SIGNAL_DETAILS.md create mode 100644 skills/dependency-evaluator/SKILL.md create mode 100644 skills/dependency-evaluator/WORKFLOW.md create mode 100755 skills/dependency-evaluator/scripts/dependency_evaluator.py create mode 100644 skills/git-workflow-patterns/SKILL.md create mode 100644 skills/workflow-analyzer/SKILL.md create mode 100644 skills/workflow-analyzer/scripts/workflow_analyzer.py diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e6d2754 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "learnfrompast", + "description": "Analyzes your shell command history, git workflows, Claude usage patterns, and evaluates dependencies to identify productivity improvements, automation opportunities, and help make informed decisions about package adoption", + "version": "1.5.1", + "author": { + "name": "Anthony Barbieri" + }, + "skills": [ + "./skills" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8d01f8d --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# learnfrompast + +Analyzes your shell command history, git workflows, Claude usage patterns, and evaluates dependencies to identify productivity improvements, automation opportunities, and help make informed decisions about package adoption diff --git a/commands/review_history.md b/commands/review_history.md new file mode 100644 index 0000000..ffba4de --- /dev/null +++ b/commands/review_history.md @@ -0,0 +1,43 @@ +--- +description: Analyzes your zsh or bash command history to identify usage patterns, productivity improvements, automation opportunities, and skill development areas based on your actual shell workflows. +--- + +This command provides personalized insights into your command-line habits by analyzing your zsh history to reveal patterns, inefficiencies, and opportunities for improvement. + + +## Instructions + +Read `~/.zsh_history` or `~/.bash_history` and analyze command patterns to generate a concise, actionable report. + +### Analysis Focus + +**Command Patterns**: +- Identify top 10-15 most frequent commands +- Categorize by purpose (version control, package management, file ops, development tools, etc.) +- Find repeated command sequences that could be automated + +**Productivity Opportunities**: +- Long/repetitive commands suitable for aliasing (prioritize by frequency × length) +- Command chains executed together frequently +- Excessive directory navigation patterns + +**Deliverables**: +- 3-4 high-impact improvement opportunities with Impact/Effort ratings +- Ready-to-use aliases and shell functions (copy-pasteable) +- 2-3 quick wins (< 5 min to implement) +- Brief skill development suggestions + +### Report Structure + +Keep the report focused and scannable: +1. **Summary**: Brief overview of command patterns and workflow (2-3 sentences) +2. **Top Commands**: List 10-15 most frequent with counts +3. **Improvement Opportunities**: 3-4 specific recommendations with before/after examples +4. **Suggested Aliases & Functions**: Copy-pasteable code block for ~/.zshrc +5. **Quick Wins**: 2-3 one-liner improvements + +**Guidelines**: +- Be concise but specific - use actual counts from history +- Prioritize by impact (frequency × time saved) +- Provide working code, not templates +- Keep encouraging tone, highlight existing strengths diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..10ec425 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,93 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:princespaghetti/claude-marketplace:learnfrompast", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "b12d35bdc34fd917a28bb2994faf6823d99909b7", + "treeHash": "2bd99677cf811521286c435b659be75eeea101c1fa15c1a1b8a4c552ed0300cf", + "generatedAt": "2025-11-28T10:27:41.189542Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "learnfrompast", + "description": "Analyzes your shell command history, git workflows, Claude usage patterns, and evaluates dependencies to identify productivity improvements, automation opportunities, and help make informed decisions about package adoption", + "version": "1.5.1" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "fdebccc90a6be931665009d5e9537a11c25666b7e5cc55b4d12b64d04b119a81" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "313cda0f25092c839d26c6a0566ed76784d287d1445eb3273991d4cb9e6210d9" + }, + { + "path": "commands/review_history.md", + "sha256": "80431e3c11257b4b59a40077410f8540b598c02589217db0b79cb64f4fbe8c05" + }, + { + "path": "skills/workflow-analyzer/SKILL.md", + "sha256": "6b5b098f589da7c6e630e8ecd80915416a368975137e14e39a26bec9785ed2d9" + }, + { + "path": "skills/workflow-analyzer/scripts/workflow_analyzer.py", + "sha256": "533070fcaa52468c31f637ed6eee1e331ed405d55a7ac96782002946e9cec3d7" + }, + { + "path": "skills/dependency-evaluator/EXAMPLES.md", + "sha256": "947520a31558ae4dc6c0669f802299c41e77a4412543abad5d35affc2a918eb3" + }, + { + "path": "skills/dependency-evaluator/ERROR_HANDLING.md", + "sha256": "dd9834efe2e3548ee76f12b12e766bedb9ad9e98e1b4e9358b50c955dba1a792" + }, + { + "path": "skills/dependency-evaluator/COMMANDS.md", + "sha256": "2c5b31169a535163ce41fbb97fde4a2b1227e597aa9a10b764a936572aabcfa7" + }, + { + "path": "skills/dependency-evaluator/WORKFLOW.md", + "sha256": "bfe08babaf4a28094ec991574fde862fa3cc8816a8a85637fa5c9940ae990512" + }, + { + "path": "skills/dependency-evaluator/SIGNAL_DETAILS.md", + "sha256": "61789b74ce21324ab0f60e0e67fba2c2d1d3189dfdb21b815e0571e4c76ccc6f" + }, + { + "path": "skills/dependency-evaluator/SCRIPT_USAGE.md", + "sha256": "331de35483a72b2c33d89f0f09181c948751585b166bb2d04c870a9456f4315c" + }, + { + "path": "skills/dependency-evaluator/SKILL.md", + "sha256": "569b5ed30175c46b4f3c89e106d45c02987efd691fb83c27068fe400a83d750d" + }, + { + "path": "skills/dependency-evaluator/ECOSYSTEM_GUIDES.md", + "sha256": "94f2c9268b348f3b4efc02bc013c198190cdd21b454dd27d9fa813a8a69281e6" + }, + { + "path": "skills/dependency-evaluator/scripts/dependency_evaluator.py", + "sha256": "48f76e7d2dbe48d22fd38fff7fd7007d7c648466dfe784159243498400b54326" + }, + { + "path": "skills/git-workflow-patterns/SKILL.md", + "sha256": "0d4d7cf400b47a6bf48b4a26c9af237b325246a5305dc5c6f7a8cb0a9e3e8053" + } + ], + "dirSha256": "2bd99677cf811521286c435b659be75eeea101c1fa15c1a1b8a4c552ed0300cf" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/dependency-evaluator/COMMANDS.md b/skills/dependency-evaluator/COMMANDS.md new file mode 100644 index 0000000..0305904 --- /dev/null +++ b/skills/dependency-evaluator/COMMANDS.md @@ -0,0 +1,355 @@ +# Dependency Evaluation Commands Reference + +This file contains all ecosystem-specific commands for gathering dependency information. Organize your investigation by the signals you're evaluating, then run the appropriate commands for your package's ecosystem. + +## Table of Contents + +### By Signal +- [1. Activity and Maintenance Patterns](#1-activity-and-maintenance-patterns) +- [2. Security Posture](#2-security-posture) +- [3. Community Health](#3-community-health) +- [4. Documentation Quality](#4-documentation-quality) +- [5. Dependency Footprint](#5-dependency-footprint) +- [6. Production Adoption](#6-production-adoption) +- [7. License Compatibility](#7-license-compatibility) +- [8-10. Other Signals](#8-10-other-signals) + +### By Ecosystem +- [Node.js / npm Complete Checklist](#nodejs--npm-complete-checklist) +- [Python / PyPI Complete Checklist](#python--pypi-complete-checklist) +- [Rust / Cargo Complete Checklist](#rust--cargo-complete-checklist) +- [Go Complete Checklist](#go-complete-checklist) +- [Java / Maven Complete Checklist](#java--maven-complete-checklist) + +### Tips +- [Command Usage Tips](#tips-for-effective-command-usage) + +--- + +## Quick Command Lookup by Signal + +### 1. Activity and Maintenance Patterns + +#### Node.js / npm +```bash +# Check publish dates and version history +npm view time + +# List all published versions +npm view versions --json +``` + +#### Python / PyPI +```bash +# Check available versions +pip index versions +``` + +#### Rust / Cargo +```bash +# Search for crate information +cargo search --limit 1 +``` + +#### Go +```bash +# Check module versions +go list -m -versions +``` + +#### GitHub (all ecosystems) +```bash +# Get repository activity (requires gh CLI) +gh api repos/{owner}/{repo} --jq '.pushed_at, .open_issues_count' + +# Get latest commit date +gh api repos/{owner}/{repo}/commits --jq '.[0].commit.author.date' +``` + +### 2. Security Posture + +#### Node.js / npm +```bash +# Run built-in security audit +npm audit --json +``` + +#### GitHub Security +```bash +# Check security advisories for a repository +gh api repos/{owner}/{repo}/security-advisories --jq '.[].summary' + +# Check for CVEs via GitHub Advisory Database +gh api graphql -f query='{ securityVulnerabilities(first: 5, package: "") { nodes { advisory { summary severity } } } }' +``` + +#### Manual Investigation +- Search for CVEs: `"" CVE` +- Check OSV database: https://osv.dev +- Look for security badges in README (Snyk, Dependabot) +- Review GitHub Security tab + +### 3. Community Health + +#### GitHub Community Metrics +```bash +# Get community health score and files (returns health_percentage 0-100) +gh api repos/{owner}/{repo}/community/profile --jq '{health_percentage, description, files}' + +# Check if security policy exists +gh api repos/{owner}/{repo}/contents/SECURITY.md --jq '.name' 2>/dev/null || echo "No SECURITY.md" + +# Get contributor count +gh api repos/{owner}/{repo}/contributors --jq 'length' + +# Get top contributors +gh api repos/{owner}/{repo}/stats/contributors --jq 'sort_by(.total) | reverse | .[0:5] | .[].author.login' + +# Check recent issue activity (are maintainers responding?) +gh api repos/{owner}/{repo}/issues --jq '[.[] | select(.pull_request == null)] | .[0:5] | .[] | {title, created_at, comments}' + +# Check PR merge velocity +gh api repos/{owner}/{repo}/pulls?state=closed --jq '.[0:10] | .[] | {title, created_at, merged_at}' +``` + +#### Interpreting Community Health Metrics +- `health_percentage` > 70 is good; < 50 suggests missing community files +- Multiple contributors (not just 1-2) indicates healthier bus factor +- Issues with comments show maintainer engagement; many 0-comment issues is a red flag +- PRs merged within days/weeks is healthy; months suggests slow maintenance + +### 4. Documentation Quality + +No specific commands - manually review: +- README comprehensiveness +- API documentation site +- Migration guides between versions +- Working examples and tutorials +- TypeScript type definitions (for JS/TS packages) + +### 5. Dependency Footprint + +#### Node.js / npm +```bash +# View full dependency tree +npm ls --all + +# Check package size (dry-run of pack) +npm pack --dry-run +``` + +#### Python / PyPI +```bash +# Shows direct dependencies in Requires field +pip show +``` + +#### Rust / Cargo +```bash +# Display dependency tree +cargo tree -p +``` + +#### Go +```bash +# Show module dependency graph +go mod graph | grep +``` + +#### Java / Maven +```bash +# Display dependency tree +mvn dependency:tree +``` + +#### Interpreting Dependency Trees +**What to look for:** +- **Total count**: Flag packages with >50 transitive dependencies for simple functionality +- **Duplicate versions**: Multiple versions of the same package (e.g., `lodash@4.17.21` and `lodash@4.17.15`) indicate potential conflicts +- **Deep nesting**: Dependencies 5+ levels deep are harder to audit and update +- **Abandoned dependencies**: Transitive deps that haven't been updated in years +- **Size vs. function**: A 500KB+ package for a simple utility is a smell + +### 6. Production Adoption + +#### Package Statistics +- **npm**: Check weekly downloads on npmjs.com or via `npm view ` +- **PyPI**: Check download stats on pypi.org package page +- **crates.io**: View download counts on crates.io +- **GitHub**: Check "Used by" count on repository page + +#### Investigation Methods +```bash +# GitHub dependents (who uses this package) +# Visit: https://github.com/{owner}/{repo}/network/dependents + +# Search for production usage mentions +# Web search: " production" or " case study" +``` + +### 7. License Compatibility + +#### GitHub License +```bash +# Get license information +gh api repos/{owner}/{repo}/license --jq '.license.spdx_id' + +# Check full dependency tree licenses via SBOM +gh api repos/{owner}/{repo}/dependency-graph/sbom --jq '.sbom.packages[].licenseConcluded' +``` + +#### Node.js / npm +```bash +# Check package.json license field +npm view license +``` + +#### Python / PyPI +```bash +# Shows License field +pip show +``` + +#### Rust / Cargo +```bash +# Check license from Cargo.toml +cargo metadata --format-version 1 | jq '.packages[] | {name, license}' +``` + +### 8. API Stability + +No specific commands - manually review: +- CHANGELOG.md or GitHub releases +- Version history for breaking change patterns +- Adherence to semantic versioning +- Deprecation warnings before removal + +### 9. Bus Factor and Funding + +No specific commands - manually investigate: +- Check for sponsor badges in README +- Look for OpenCollective or GitHub Sponsors links +- Search " funding" or " sponsor" +- Check for organizational backing (CNCF, Apache, company sponsorship) +- Review contributor affiliations in GitHub profile + +### 10. Ecosystem Momentum + +No specific commands - research: +- Check if ecosystem is migrating to alternatives +- Verify framework/platform alignment +- Search for ecosystem trend discussions +- Review plugin/extension ecosystem activity + +## Command Reference by Ecosystem + +### Node.js / npm Complete Checklist + +```bash +# Package metadata and history +npm view time +npm view versions --json +npm view license + +# Dependency analysis +npm ls --all +npm pack --dry-run + +# Security +npm audit --json + +# If GitHub repo is known +gh api repos/{owner}/{repo} --jq '.pushed_at, .open_issues_count' +gh api repos/{owner}/{repo}/community/profile +gh api repos/{owner}/{repo}/license --jq '.license.spdx_id' +``` + +### Python / PyPI Complete Checklist + +```bash +# Package information +pip index versions +pip show + +# If GitHub repo is known +gh api repos/{owner}/{repo} --jq '.pushed_at, .open_issues_count' +gh api repos/{owner}/{repo}/community/profile +gh api repos/{owner}/{repo}/security-advisories +``` + +### Rust / Cargo Complete Checklist + +```bash +# Crate information +cargo search --limit 1 +cargo tree -p +cargo metadata --format-version 1 | jq '.packages[] | select(.name=="") | {name, license, version}' + +# If GitHub repo is known +gh api repos/{owner}/{repo} --jq '.pushed_at, .open_issues_count' +gh api repos/{owner}/{repo}/community/profile +``` + +### Go Complete Checklist + +```bash +# Module information +go list -m -versions +go mod graph | grep + +# If GitHub repo is known (most Go modules are on GitHub) +gh api repos/{owner}/{repo} --jq '.pushed_at, .open_issues_count' +gh api repos/{owner}/{repo}/community/profile +gh api repos/{owner}/{repo}/security-advisories +``` + +### Java / Maven Complete Checklist + +```bash +# Dependency tree +mvn dependency:tree + +# If GitHub repo is known +gh api repos/{owner}/{repo} --jq '.pushed_at, .open_issues_count' +gh api repos/{owner}/{repo}/community/profile +gh api repos/{owner}/{repo}/license --jq '.license.spdx_id' +``` + +## Tips for Effective Command Usage + +### Run Commands in Parallel +When gathering data for multiple signals, run independent commands simultaneously to save time: +```bash +# Example: Run these in parallel +gh api repos/{owner}/{repo} & +gh api repos/{owner}/{repo}/community/profile & +gh api repos/{owner}/{repo}/contributors & +wait +``` + +### Save Command Output +For complex evaluations, save output to files for reference: +```bash +npm view time > /tmp/npm-history.json +gh api repos/{owner}/{repo}/issues > /tmp/github-issues.json +``` + +### Handle Errors Gracefully +Some commands may fail if data isn't available: +```bash +# Use || to provide fallback messages +gh api repos/{owner}/{repo}/contents/SECURITY.md 2>/dev/null || echo "No security policy found" +``` + +### Find GitHub Repository +If you only have a package name, find its repository: +```bash +# For npm packages +npm view repository.url + +# For PyPI packages +pip show | grep "Home-page" + +# For cargo crates +# Visit crates.io and check the repository link +``` diff --git a/skills/dependency-evaluator/ECOSYSTEM_GUIDES.md b/skills/dependency-evaluator/ECOSYSTEM_GUIDES.md new file mode 100644 index 0000000..c3c016c --- /dev/null +++ b/skills/dependency-evaluator/ECOSYSTEM_GUIDES.md @@ -0,0 +1,460 @@ +# Ecosystem-Specific Evaluation Guides + +Different language ecosystems have different norms, risks, and best practices. Use this guide to adjust your evaluation criteria based on the package ecosystem. + +## Table of Contents + +- [Ecosystem Baselines](#ecosystem-baselines) +- [Node.js / npm](#nodejs--npm) +- [Python / PyPI](#python--pypi) +- [Rust / Cargo](#rust--cargo) +- [Go](#go) +- [Ruby / RubyGems](#ruby--rubygems) +- [Java / Maven Central](#java--maven-central) +- [Cross-Ecosystem Patterns](#cross-ecosystem-patterns) +- [Adjusting Your Evaluation](#adjusting-your-evaluation) + +--- + +## Ecosystem Baselines + +Use these baselines for ecosystem-relative comparisons. These represent typical patterns as of 2025; use as context not rigid rules. + +### Release Cadence Norms + +| Ecosystem | Actively Developed | Mature/Stable | Concerning | +|-----------|-------------------|---------------|------------| +| npm | Monthly+ releases | Quarterly releases | >6 months no release | +| PyPI | Monthly-quarterly | Bi-annual releases | >9 months no release | +| Cargo | Bi-monthly to quarterly | Annual releases OK | >12 months no release | +| Go | Quarterly typical | Annual releases OK | >12 months no release | +| RubyGems | Monthly for Rails-related | Quarterly for utilities | >6 months no release | +| Maven | Quarterly typical | Bi-annual for mature | >9 months no release | + +**Key:** "Concerning" means outlier for actively developed packages; mature packages may legitimately have longer gaps. + +### Dependency Count Norms + +| Ecosystem | Light | Typical | Heavy | Extreme | +|-----------|-------|---------|-------|---------| +| npm | <10 | 20-50 | 100-150 | 200+ | +| PyPI | <5 | 10-30 | 50-80 | 100+ | +| Cargo | <10 | 20-40 | 60-80 | 100+ | +| Go | <5 | 5-20 | 30-40 | 50+ | +| RubyGems | <5 | 10-25 | 40-60 | 80+ | +| Maven | <10 | 20-50 | 80-120 | 150+ | + +**Counts are total transitive dependencies.** Adjust expectations based on package type (frameworks have more). + +### Download Thresholds (Weekly) + +| Ecosystem | Niche | Moderate | Popular | Very Popular | +|-----------|-------|----------|---------|--------------| +| npm | <500 | 1k-10k | 50k-100k | 500k+ | +| PyPI | <100 | 500-5k | 20k-50k | 200k+ | +| Cargo | <50 | 200-2k | 10k-30k | 100k+ | +| RubyGems | <100 | 500-5k | 20k-50k | 200k+ | + +**Note:** Downloads alone don't indicate quality. Niche packages can be excellent; popular packages can be deprecated. + +### Issue Response Time Norms + +| Ecosystem | Excellent | Good | Acceptable | Concerning | +|-----------|-----------|------|------------|------------| +| npm (popular) | Hours-1 day | 2-7 days | 2-4 weeks | >1 month | +| npm (smaller) | 1-3 days | 1-2 weeks | 1 month | >2 months | +| PyPI | 1-3 days | 1-2 weeks | 3-4 weeks | >1 month | +| Cargo | 1-2 days | 3-7 days | 2-3 weeks | >1 month | +| Go | 1-3 days | 1-2 weeks | 3-4 weeks | >1 month | + +**For security issues:** Expect 24-48hr acknowledgment regardless of ecosystem. + +### Documentation Expectations + +| Ecosystem | Minimum Expected | Excellent | +|-----------|------------------|-----------| +| npm | README with examples, TypeScript types | Dedicated docs site, migration guides, playground | +| PyPI | README with examples, type hints | ReadTheDocs site, Sphinx docs, examples repo | +| Cargo | README with examples, rustdoc | docs.rs complete, examples in repo, book/guide | +| Go | README with examples, godoc | pkg.go.dev complete, examples, design docs | +| RubyGems | README with examples | RDoc/YARD docs, Rails integration guide | + +### Comparative Assessment Guidelines + +**Use these baselines to ask:** +- Is this package's release cadence below the norm for its ecosystem and maturity level? +- Is the dependency count in the top quartile for similar packages in this ecosystem? +- Is the issue response time significantly slower than ecosystem expectations? +- Are downloads declining while ecosystem overall is growing? + +**Example application:** +- npm package with 150 transitive deps → "Heavy" but not extreme; acceptable for framework, concerning for utility +- Cargo crate with no release in 10 months → Not yet concerning for mature stable crate +- PyPI package with 200 deps → Extreme; investigate why so many +- Go module with 40 deps → Unusual for Go (stdlib-first culture); investigate + +--- + +## Node.js / npm + +### Ecosystem Characteristics +- **Philosophy**: Micropackages are common; many tiny single-purpose modules +- **Package count**: Over 2 million packages (largest ecosystem) +- **Dependency culture**: Deep dependency trees are normalized +- **Versioning**: Semver is standard but not always followed strictly + +### Unique Risks + +**Left-pad Risk** +The infamous "left-pad incident" (2016) highlighted npm's vulnerability to tiny, critical packages being removed. Characteristics: +- Single-function packages with disproportionate usage +- High download counts but minimal functionality +- Supply chain risk when widely used packages are yanked + +**npm-specific Supply Chain Attacks** +- Typosquatting is common (react vs. reakt) +- Package name confusion attacks +- Malicious install scripts in postinstall hooks +- Maintainer account compromises + +### What to Watch For +- Packages with hundreds of transitive dependencies for simple tasks +- Postinstall scripts that download external code +- Packages that wrap simple native functionality unnecessarily +- Extremely high download counts but minimal GitHub activity (bot inflation) + +### Preferred Patterns +- Packages with minimal dependencies +- Well-established micro-utilities from trusted authors +- Scoped packages (@organization/package) from known orgs +- Packages with verified publishers + +### Recommended Tools +```bash +npm ls --all # Visualize full dependency tree +npm audit # Security vulnerability scanning +npm pack --dry-run # Check bundle size +``` + +### Ecosystem-Specific Red Flags +- Packages requiring sudo or elevated permissions +- Packages with network calls in postinstall +- Packages with native dependencies when pure JS would suffice +- Suspicious similarity to popular package names + +### Ecosystem-Specific Green Flags +- TypeScript type definitions included +- ES modules support +- Tree-shakeable exports +- Zero dependencies for utility packages + +## Python / PyPI + +### Ecosystem Characteristics +- **Philosophy**: "Batteries included" - stdlib-first approach +- **Package count**: Over 400,000 packages +- **Dependency culture**: Lighter dependency trees than npm +- **Versioning**: Mix of semver and date-based versioning + +### Unique Risks + +**PyPI Supply Chain Attacks** +- Notable typosquatting incidents (e.g., python3-dateutil vs. dateutil) +- Malicious packages targeting data scientists (fake ML libraries) +- Native code in wheels may contain malware +- setup.py can execute arbitrary code during install + +**Dependency Confusion** +- Public PyPI packages with same names as private packages +- pip installs public version instead of intended private one + +### What to Watch For +- Packages with names very similar to popular packages +- Unusual wheel distributions without source code +- Packages targeting specific communities (ML, data science) with suspicious features +- setup.py files with network calls or obfuscated code + +### Preferred Patterns +- Packages from known maintainers and organizations +- Packages with signed releases (GPG signatures) +- Pure Python packages (no compiled extensions) when possible +- Packages maintained by Python Software Foundation or sub-projects + +### Recommended Tools +```bash +pip show # View package metadata +pip index versions # Check version history +# Use pip-audit for security scanning (install separately) +``` + +### Ecosystem-Specific Red Flags +- Packages requesting unnecessary permissions in setup +- Typosquatting of popular packages (reqeusts vs. requests) +- Obfuscated code in setup.py +- Wheels only (no source distribution) + +### Ecosystem-Specific Green Flags +- Listed in Python Packaging Authority (PyPA) +- Type hints (PEP 484) included +- Both source distributions and wheels available +- Active maintenance by known Python community members + +## Rust / Cargo + +### Ecosystem Characteristics +- **Philosophy**: Safety and correctness-first; explicit is better than implicit +- **Package count**: Over 100,000 crates +- **Dependency culture**: Moderate dependencies; emphasis on correctness +- **Versioning**: Strict semver adherence is cultural norm + +### Unique Strengths +- Strong compile-time guarantees reduce certain vulnerability classes +- Cargo's built-in tooling is excellent (cargo tree, cargo metadata) +- Culture of good documentation (docs.rs) +- `#![forbid(unsafe_code)]` for packages avoiding unsafe blocks + +### What to Watch For +- Crates pulling in many proc-macro dependencies (slow compile times) +- Heavy use of `unsafe` blocks without justification +- Transitive dependencies with unsafe code when unnecessary +- Version conflicts in dependency tree (Cargo is strict about this) + +### Preferred Patterns +- Crates with `#![forbid(unsafe_code)]` for non-performance-critical code +- Well-documented use of unsafe with safety invariants explained +- Minimal proc-macro dependencies +- Idiomatic Rust patterns + +### Recommended Tools +```bash +cargo tree -p # Dependency tree visualization +cargo metadata --format-version 1 # Machine-readable metadata +cargo audit # Security vulnerability scanning (install separately) +``` + +### Ecosystem-Specific Red Flags +- Excessive unsafe code without documentation +- Non-idiomatic Rust (indicates unfamiliarity) +- Proc-macro heavy for simple functionality +- Breaking semver (very rare in Rust ecosystem) + +### Ecosystem-Specific Green Flags +- Published on docs.rs with comprehensive documentation +- `#![forbid(unsafe_code)]` or well-justified unsafe usage +- Fast compile times relative to functionality +- Active maintenance by Rust community members +- Inclusion in "awesome-rust" lists + +## Go + +### Ecosystem Characteristics +- **Philosophy**: Simplicity, minimalism, stdlib-first +- **Package count**: Smaller than npm/PyPI (by design) +- **Dependency culture**: Fewer dependencies is idiomatic +- **Versioning**: Go modules with semantic versioning + +### Unique Strengths +- Strong standard library reduces dependency needs +- Built-in dependency management (go mod) +- Static linking produces standalone binaries +- Import paths explicitly reference source repositories + +### What to Watch For +- Packages that wrap stdlib with minimal added value +- Deep dependency trees (unusual in Go) +- Packages that violate Go idioms and conventions +- Module paths not matching repository structure + +### Preferred Patterns +- Prefer stdlib solutions when available +- Minimal external dependencies +- Clear, simple APIs following Go conventions +- Well-structured module paths (github.com/org/project) + +### Recommended Tools +```bash +go list -m -versions # List module versions +go mod graph # Dependency graph +go mod why # Why is this dependency included +``` + +### Ecosystem-Specific Red Flags +- Wrapping stdlib unnecessarily +- Complex APIs when simple would suffice +- Not following Go Project Layout +- Vendoring dependencies (uncommon with go mod) + +### Ecosystem-Specific Green Flags +- Minimal dependencies (< 5 direct deps) +- Follows effective Go guidelines +- Clear documentation and examples +- Used in prominent Go projects + +## Ruby / RubyGems + +### Ecosystem Characteristics +- **Philosophy**: Convention over configuration, developer happiness +- **Package count**: Over 175,000 gems +- **Dependency culture**: Moderate; gems often do a lot +- **Versioning**: Generally follows semver + +### Unique Characteristics +- Gems often monkey-patch core classes (can cause conflicts) +- Rails ecosystem dominates Ruby gem ecosystem +- Strong community conventions + +### What to Watch For +- Gems that extensively monkey-patch core classes +- Dependencies that conflict with Rails (if using Rails) +- Gems that override standard library behavior +- Unmaintained gems for Rails version compatibility + +### Preferred Patterns +- Well-documented gems with clear upgrade paths +- Gems that minimize monkey-patching +- Rails-compatible versioning (if applicable) +- Active maintenance matching Rails release cycles + +### Recommended Tools +```bash +gem list # List installed versions +gem dependency # Show dependencies +bundle outdated # Check for updates (in bundler projects) +``` + +### Ecosystem-Specific Red Flags +- Extensive monkey-patching without documentation +- Incompatibility with major Rails versions +- Gems requiring old Ruby versions +- No Bundler compatibility + +### Ecosystem-Specific Green Flags +- Rails-compatible (if relevant) +- Minimal monkey-patching or well-documented overrides +- Active maintenance matching Ruby version releases +- Listed in awesome-ruby or Ruby Toolbox + +## Java / Maven Central + +### Ecosystem Characteristics +- **Philosophy**: Enterprise-ready, battle-tested +- **Package count**: Over 500,000 artifacts +- **Dependency culture**: Can be heavy; mature dependency resolution +- **Versioning**: Mix of semver and date-based + +### Unique Strengths +- Mature ecosystem with established governance +- Strong backward compatibility culture +- Extensive enterprise adoption and vetting +- Maven Central has quality standards + +### What to Watch For +- Dependency version conflicts (dependency hell) +- Transitive dependencies pulling in multiple versions +- Large artifact sizes +- Complex dependency trees + +### Preferred Patterns +- Well-maintained artifacts from reputable organizations +- Clear compatibility matrices (Java version, framework version) +- Semantic versioning adherence +- Artifacts hosted on Maven Central (not random repos) + +### Recommended Tools +```bash +mvn dependency:tree # Dependency tree visualization +mvn dependency:analyze # Unused dependency analysis +mvn versions:display-dependency-updates # Check for updates +``` + +### Ecosystem-Specific Red Flags +- Artifacts only in obscure Maven repos +- Complex dependency resolution issues +- No Java version compatibility documented +- Transitive dependencies with licensing issues + +### Ecosystem-Specific Green Flags +- Published to Maven Central +- Apache or Eclipse Foundation backing +- Clear Java version support policy +- Spring ecosystem compatibility (if relevant) +- OSGi bundle metadata (for OSGi projects) + +## Cross-Ecosystem Patterns + +### Supply Chain Security Varies by Ecosystem + +**Highest Risk:** +- npm (largest attack surface, numerous incidents) +- PyPI (targeted attacks on data scientists) + +**Medium Risk:** +- Maven (occasional but usually caught quickly) +- RubyGems (smaller ecosystem, fewer incidents) + +**Lower Risk:** +- Cargo (newer, security-conscious culture) +- Go (stdlib-first reduces attack surface) + +### Dependency Tree Norms + +**Expect Heavier Trees:** +- npm (100+ transitive deps can be normal) +- Maven (enterprise frameworks bring many deps) + +**Expect Lighter Trees:** +- Go (< 20 transitive deps typical) +- Rust (20-50 deps common) +- Python (30-60 deps typical) + +### Versioning Discipline + +**Strict Semver:** +- Rust/Cargo (breaking semver is rare) +- npm (expected but not always followed) + +**Flexible Versioning:** +- Maven (mix of approaches) +- Python (mix of semver and datever) + +### Documentation Culture + +**Excellent Documentation Expected:** +- Rust (docs.rs standard) +- Python (ReadTheDocs common) + +**Variable Documentation:** +- npm (ranges from excellent to none) +- Maven (often enterprise-focused docs) + +## Adjusting Your Evaluation + +### For npm Packages +- **Increase weight on**: Dependency Footprint, Security Posture +- **Be more lenient on**: Single maintainer (common for utilities) +- **Extra scrutiny for**: Packages with < 50 lines of code but high usage + +### For Python Packages +- **Increase weight on**: Security Posture (typosquatting risk) +- **Be more lenient on**: Lower download counts (smaller ecosystem) +- **Extra scrutiny for**: Packages targeting data scientists/ML engineers + +### For Rust Crates +- **Increase weight on**: API Stability, Documentation Quality +- **Be more lenient on**: Compile-time dependencies (proc-macros) +- **Extra scrutiny for**: Excessive unsafe code usage + +### For Go Modules +- **Increase weight on**: Simplicity, Minimal Dependencies +- **Be more lenient on**: Lower GitHub stars (smaller community) +- **Extra scrutiny for**: Packages wrapping stdlib unnecessarily + +### For Ruby Gems +- **Increase weight on**: Rails compatibility (if applicable) +- **Be more lenient on**: Monkey-patching (if well-documented) +- **Extra scrutiny for**: Core class modifications + +### For Java Artifacts +- **Increase weight on**: Enterprise Adoption, Backward Compatibility +- **Be more lenient on**: Larger dependency trees (framework norm) +- **Extra scrutiny for**: Artifacts not on Maven Central diff --git a/skills/dependency-evaluator/ERROR_HANDLING.md b/skills/dependency-evaluator/ERROR_HANDLING.md new file mode 100644 index 0000000..d410cb0 --- /dev/null +++ b/skills/dependency-evaluator/ERROR_HANDLING.md @@ -0,0 +1,456 @@ +# Error Handling and Fallback Strategies + +This guide provides fallback strategies when commands fail, data is unavailable, or tools are missing. The goal is to complete evaluations with available information rather than blocking on missing data. + +## Table of Contents + +- [Using the Automated Script](#using-the-automated-script) +- [Missing GitHub Repository](#missing-github-repository) +- [GitHub CLI (`gh`) Not Available](#github-cli-gh-not-available) +- [Package Not Found in Registry](#package-not-found-in-registry) +- [Private/Enterprise Package Registries](#privateenterprise-package-registries) +- [Command Failures](#command-failures) +- [Incomplete or Missing Data](#incomplete-or-missing-data) +- [Network/API Rate Limiting](#networkapi-rate-limiting) + +--- + +## Using the Automated Script + +**Scenario:** The `dependency_evaluator.py` script is available and can automate error handling. + +### When Script Helps + +The automated script (see [SCRIPT_USAGE.md](./SCRIPT_USAGE.md)) handles many common errors automatically: +- **Missing commands**: Warns and continues with available data +- **Network errors**: Retries with fallback strategies (gh CLI → direct API) +- **Rate limiting**: Reports issue clearly in warnings array +- **Malformed data**: Catches JSON parsing errors gracefully + +### Script as First Step + +For supported ecosystems (npm, pypi, cargo, go), try the script first: + +```bash +python3 scripts/dependency_evaluator.py > data.json +``` + +**Review the output:** +```json +{ + "errors": ["Critical issues that blocked evaluation"], + "warnings": ["Non-critical issues, evaluation continued"] +} +``` + +**If errors present:** Handle based on error type (see sections below) +**If only warnings:** Proceed with evaluation, noting limitations in report + +### Fallback to Manual + +If script fails completely or for unsupported ecosystems, use manual workflow with command-specific fallbacks below. + +--- + +## Missing GitHub Repository + +**Scenario:** Package metadata doesn't include GitHub repository link, or link is broken. + +### Fallback Strategy + +1. **Try registry metadata first:** + ```bash + # npm + npm view repository.url + npm view homepage + + # PyPI + pip show | grep "Home-page" + pip show | grep "Project-URL" + + # Cargo + cargo metadata --format-version 1 | jq '.packages[] | select(.name=="") | .repository' + ``` + +2. **Web search as backup:** + - Search: `"" github` + - Search: `"" source code repository` + - Check package's documentation site for repository link + +3. **If repository truly doesn't exist:** + - **Mark affected signals as "Unable to Assess":** + - Community Health → Cannot assess contributor diversity, PR velocity + - Maintenance (partial) → Can assess releases, cannot assess commit frequency + - Security (partial) → Can check CVEs, cannot verify security policy + - **Note limitation prominently in report:** + ```markdown + **⚠️ Limited Evaluation**: No source repository found. GitHub-based signals (community health, commit activity) could not be assessed. Evaluation based on registry data and public CVE databases only. + ``` + - **Reduce confidence in recommendation:** + - Strong ADOPT becomes EVALUATE FURTHER + - EVALUATE FURTHER may become AVOID (lack of transparency is concerning) + +4. **Red flag considerations:** + - Closed-source package in open-source ecosystem is unusual + - No source repository reduces auditability significantly + - Consider if this is acceptable for your use case + +--- + +## GitHub CLI (`gh`) Not Available + +**Scenario:** `gh` command not installed or not authenticated. + +### Fallback Strategy + +1. **Use package registry commands only:** + ```bash + # npm - still provides rich data + npm view time + npm view versions + npm view maintainers + npm audit + + # PyPI + pip show + pip index versions + + # Cargo + cargo search + cargo metadata + ``` + +2. **Manual checks for GitHub data:** + - Visit repository URL directly in browser + - Check: Stars, forks, last commit date, open issues count + - Review: README, SECURITY.md, CONTRIBUTING.md + - Manually note findings + +3. **Web-based alternatives:** + - Use https://libraries.io to查看 package stats + - Check ecosystem-specific sites: + - npm: npmjs.com package page + - PyPI: pypi.org package page + - Cargo: crates.io package page + - Review security databases: https://osv.dev + +4. **Note limitation in report:** + ```markdown + **Note**: GitHub API data unavailable (gh CLI not installed). Community health metrics based on manual review and registry data. + ``` + +5. **Recommendation:** + - Include installation instructions: `brew install gh` / `apt install gh` + - For complete analysis, installing `gh` is recommended + +--- + +## Package Not Found in Registry + +**Scenario:** `npm view ` or equivalent returns "package not found." + +### Diagnosis Steps + +1. **Verify package name:** + - Check for typos + - Verify correct ecosystem (npm vs PyPI vs Cargo) + - Check if package uses scope: `@org/package-name` + +2. **Check if package was removed/yanked:** + ```bash + # npm - check if ever existed + npm view --json 2>&1 | grep "404" + + # PyPI - yanked versions show in history + pip index versions + + # Cargo - yanked crates still visible + cargo search + ``` + +3. **Possible causes:** + - **Typo in package name** → Correct and retry + - **Wrong ecosystem** → Verify it's npm not PyPI, etc. + - **Package removed/unpublished** → **MAJOR RED FLAG** + - **Private package** → See Private/Enterprise section below + - **Pre-release/beta only** → Check version tags + +### If Package Was Removed + +**This is a critical finding:** + +```markdown +## Dependency Evaluation: + +**Recommendation**: AVOID +**Risk Level**: Critical +**Blockers Found**: Yes + +### Blockers +⛔ **Package has been unpublished from registry** + +This is an extremely serious red flag. Possible causes: +- Security incident (compromised package) +- Maintainer protest or dispute +- Legal/licensing issue +- Malware discovery + +**Do NOT use this package.** Investigate why it was removed before considering any alternatives. +``` + +--- + +## Private/Enterprise Package Registries + +**Scenario:** Package is in private registry, company npm registry, etc. + +### Approach + +1. **Acknowledge evaluation limits:** + ```markdown + **Note**: This is a private/enterprise package. Public ecosystem data (download counts, public dependents) not available. Evaluation based on: + - Internal repository access + - Company security policies + - Internal usage metrics (if available) + ``` + +2. **Focus on accessible signals:** + - ✅ **Maintenance**: If you have repo access, assess commit history + - ✅ **Security**: Check internal security scan results + - ✅ **Community**: Assess internal team size, responsiveness + - ✅ **Documentation**: Review internal docs + - ❌ **Production Adoption**: Public data unavailable; use internal metrics + - ❌ **Ecosystem Momentum**: Not applicable for private packages + +3. **Adjust weighting:** + - Increase weight on: Internal security scans, maintainer responsiveness, documentation + - Decrease weight on: Public production adoption, ecosystem momentum + +4. **Company-specific considerations:** + - Internal packages may have lower documentation standards (acceptable if team is accessible) + - Security may be handled by company-wide scanning (acceptable if robust) + - Bus factor more critical (if sole maintainer leaves company, what happens?) + +--- + +## Command Failures + +### npm Commands Fail + +**Scenario:** `npm view ` returns errors. + +**Possible causes:** +- Network issues → Retry with `--registry` flag +- npm not installed → Install npm +- Package truly doesn't exist → See "Package Not Found" section + +**Fallback:** +```bash +# Try alternative registry +npm view --registry=https://registry.npmjs.org + +# Use npms.io API +curl https://api.npms.io/v2/package/ +``` + +### GitHub API Rate Limiting + +**Scenario:** `gh api` returns 403 rate limit error. + +**Fallback:** +```bash +# Check rate limit status +gh api rate_limit + +# Wait for reset (shown in rate_limit response) +# OR authenticate to get higher limits +gh auth login +``` + +**If blocked:** +- Note in report: "GitHub API rate limited; data gathered from alternative sources" +- Use web UI for manual checks +- Use https://libraries.io as alternative data source + +### Python pip Commands Fail + +**Scenario:** `pip show ` fails or hangs. + +**Fallbacks:** +```bash +# Try with different Python version +python3 -m pip show + +# Use PyPI JSON API directly +curl https://pypi.org/pypi//json + +# Check installed packages +pip list | grep +``` + +--- + +## Incomplete or Missing Data + +### Handling Partial Data + +When some data is unavailable, proceed with available signals: + +**Assessment approach:** +1. **Clearly mark unavailable signals** in your evaluation +2. **Weight available signals more heavily** +3. **Note data limitations** in final recommendation +4. **Adjust confidence level:** + - Missing 1-2 signals → Proceed with note + - Missing 3-5 signals → Lower confidence, more cautious recommendation + - Missing 6+ signals → Insufficient data for recommendation + +**Example report structure:** +```markdown +### Evaluation Scores + +| Signal (Weight) | Score | Evidence | +|-----------------|-------|----------| +| Maintenance (H) | 4/5 | Last release 2 weeks ago... | +| Security (H) | Unable to Assess | No source repository found | +| Community (M) | Unable to Assess | No source repository found | +| Documentation (M) | 3/5 | README present but minimal... | +... + +**Note**: Unable to assess Community Health and Security Posture due to missing source repository. Recommendation confidence: Medium. +``` + +### When Data Is Too Limited + +**If 6+ signals cannot be assessed:** + +```markdown +## Dependency Evaluation: + +**Recommendation**: INSUFFICIENT DATA +**Risk Level**: Unknown +**Blockers Found**: Data unavailable + +Unable to complete evaluation due to insufficient data: +- No source repository found +- Package registry data minimal +- No public security scan results +- No community metrics available + +**Recommendation**: Request more information from package maintainers or choose alternative with better transparency. +``` + +--- + +## Network/API Rate Limiting + +### GitHub API Rate Limits + +**Unauthenticated:** 60 requests/hour +**Authenticated:** 5,000 requests/hour + +**When rate limited:** +1. Authenticate: `gh auth login` +2. Check reset time: `gh api rate_limit` +3. Prioritize most important API calls +4. Use conditional requests (ETags) to save quota + +### npm Registry Rate Limits + +npm registry typically doesn't rate limit, but: +- If experiencing issues, use `--registry` flag +- Consider using npm's v2 API for programmatic access +- Check network/VPN isn't blocking registry + +### Working Within Limits + +**Efficient API usage:** +```bash +# Batch requests where possible +# Good: Single call with jq to extract multiple fields +gh api repos/{owner}/{repo} --jq '{stars: .stargazers_count, forks: .forks_count, updated: .updated_at}' + +# Avoid: Multiple calls for same data +gh api repos/{owner}/{repo} --jq '.stargazers_count' +gh api repos/{owner}/{repo} --jq '.forks_count' # Wasteful +``` + +**Prioritize calls:** +1. Critical: Security advisories, CVE history +2. High: Maintenance activity, release dates +3. Medium: Contributor counts, PR metrics +4. Low: Star counts, fork counts + +--- + +## General Error Handling Principles + +### 1. Degrade Gracefully +- Partial data is better than no evaluation +- Clearly document what's missing +- Adjust confidence levels appropriately + +### 2. Be Transparent +- Always note data limitations in report +- Explain which signals couldn't be assessed and why +- Don't guess or fill in missing data + +### 3. Provide Alternatives +- If tool missing, provide installation instructions +- If data unavailable, suggest manual verification steps +- If evaluation incomplete, recommend next steps + +### 4. Fail Safely +- When in doubt about data quality, recommend EVALUATE FURTHER not ADOPT +- Missing security data should increase caution, not be ignored +- Lack of transparency is itself a red flag + +### 5. Document for User +Always include a "Data Collection Summary" in reports when errors occurred: + +```markdown +## Data Collection Summary + +**Commands executed successfully:** +- ✅ npm view (version, license, maintainers) +- ✅ npm audit (security scan) + +**Commands failed/unavailable:** +- ❌ gh api (GitHub CLI not installed) → Manual GitHub review performed +- ⚠️ npm ls (package not installed) → Analyzed published dependency tree + +**Data limitations:** +- Community metrics based on manual review, not API data +- Contributor diversity not quantitatively assessed + +**Recommendation confidence:** Medium (due to missing API data) +``` + +--- + +## Quick Reference: Command Failure Matrix + +| Failure | Cause | Fallback | Impact | +|---------|-------|----------|--------| +| `npm view` fails | Package not found | Verify name, check if removed | CRITICAL if removed | +| `gh api` fails | CLI not installed | Manual GitHub review, libraries.io | Reduces accuracy | +| `gh api` 403 | Rate limited | Wait for reset, authenticate | Temporary delay | +| `pip show` fails | Package not installed | `pip index versions`, PyPI web | Minor - use API | +| No repository found | Closed source | Registry data only | Lower confidence | +| CVE search empty | No vulnerabilities OR no scans | Assume no known CVEs, note uncertainty | Acceptable | +| Download stats unavailable | Private package | Internal metrics | Expected for private | + +--- + +## Summary + +**Key principle:** Never let missing data completely block an evaluation. Provide best assessment with available information, clearly document limitations, and adjust recommendation confidence accordingly. + +Missing data handling priority: +1. **Security data missing** → Increase caution significantly +2. **Maintenance data missing** → Hard to recommend ADOPT +3. **Community data missing** → Note but less critical +4. **Documentation data missing** → Can assess manually +5. **Ecosystem momentum missing** → Least critical + +**When absolutely stuck:** Recommend EVALUATE FURTHER with specific next steps for user to investigate manually. diff --git a/skills/dependency-evaluator/EXAMPLES.md b/skills/dependency-evaluator/EXAMPLES.md new file mode 100644 index 0000000..78e90bc --- /dev/null +++ b/skills/dependency-evaluator/EXAMPLES.md @@ -0,0 +1,359 @@ +# Dependency Evaluation Examples + +This file contains concrete worked examples demonstrating the evaluation framework in action. Each example shows the complete evaluation process, scoring rationale, and final recommendation. + +**Important:** These are hypothetical packages created for teaching purposes. They illustrate evaluation methodology, not real package recommendations. + +## Table of Contents + +- [Example 1: ExampleCo HTTP Client (npm) - ADOPT](#example-1-exampleco-http-client-npm---adopt) +- [Example 2: legacy-parser (PyPI) - AVOID](#example-2-legacy-parser-pypi---avoid) +- [Example 3: fast-compute (Rust) - ADOPT with Nuance](#example-3-fast-compute-rust---adopt-with-nuance) +- [Example 4: mega-framework (npm) - EVALUATE FURTHER](#example-4-mega-framework-npm---evaluate-further) +- [Key Takeaways](#key-takeaways-from-examples) + +--- + +## Example 1: ExampleCo HTTP Client (npm) - ADOPT + +**User Request:** "Should I use exampleco-http for making API requests in my Node.js application?" + +**Package Context:** +- Name: exampleco-http (npm) +- Dependency Type: Standard (HTTP client) +- Use Case: REST API calls in backend service + +### Summary +ExampleCo HTTP Client is a well-maintained, production-ready HTTP library with corporate backing, excellent security practices, and clean dependencies. Strong positive signals across all evaluation criteria make this a low-risk adoption. + +**Recommendation**: ADOPT +**Risk Level**: Low +**Blockers Found**: No + +### Evaluation Scores + +| Signal (Weight) | Score | Evidence | +|-----------------|-------|----------| +| Maintenance (H) | 5/5 | Last release v2.4.1 on 2025-01-10. Weekly commits. 47 releases over 2 years. | +| Security (H) | 5/5 | SECURITY.md present. 2 historical CVEs patched <48hrs. Dependabot enabled. | +| Community (M) | 5/5 | 5 active maintainers from ExampleCo Inc. 89 contributors. PRs merged 2-4 days. | +| Documentation (M) | 4/5 | Comprehensive docs site. API reference complete. TypeScript types. Minor: advanced examples limited. | +| Dependency Footprint (M) | 5/5 | 8 total deps (2 direct, 6 transitive). Bundle: 45KB. No security issues. | +| Production Adoption (M) | 5/5 | 50k weekly downloads. 1,200+ dependents. Featured in Node.js blog. | +| License (H) | 5/5 | MIT. All deps MIT or Apache-2.0. No conflicts. | +| API Stability (M) | 5/5 | Strict semver. v2.x stable 18 months. Deprecation warnings 6mo before removal. | +| Funding (H) | 5/5 | Backed by ExampleCo Inc (series B). 3 full-time maintainers. | +| Ecosystem Momentum (L) | 4/5 | Growing adoption. Ecosystem shifting to native fetch, but package adds value. | + +**Weighted Score**: 48/50 + +### Key Findings + +**Strengths:** +- Corporate backing with 3 dedicated full-time engineers +- Fast security response (48hr CVE patches historically) +- Clean dependency tree (only 8 total packages) +- Production-proven (50k weekly downloads, major adopters) + +**Concerns:** +- Ecosystem gradual shift to native `fetch` API (2-3 year horizon) +- Advanced use case documentation could be more comprehensive + +### Alternatives Considered +- **Native fetch**: Zero dependencies but lacks retry/timeout/interceptor features +- **axios**: Higher downloads but heavier deps (15+) and slower maintenance +- **node-fetch**: Lightweight but minimal features + +### Recommendation Details +Exemplary well-maintained package. Corporate backing, responsive security, clean dependencies, and strong community make this low-risk for production use. While the ecosystem is moving toward native `fetch`, this package provides significant value-adds that native fetch lacks (retries, interceptors, transforms). ExampleCo has committed to maintenance through 2027+. + +### If You Proceed +- Pin to `^2.4.0` for patches/minors +- Monitor for ExampleCo native fetch migration plans +- Enable Dependabot/GitHub security alerts +- Review dependencies annually + +--- + +## Example 2: legacy-parser (PyPI) - AVOID + +**User Request:** "I need to parse legacy data format files. Should I use legacy-parser?" + +**Package Context:** +- Name: legacy-parser (PyPI) +- Dependency Type: Standard (data parsing) +- Use Case: Parsing proprietary legacy format + +### Summary +legacy-parser is an abandoned package with critical unpatched security vulnerabilities and zero maintainer activity for 3 years. Active CVEs including RCE make this completely unsuitable for any use. + +**Recommendation**: AVOID +**Risk Level**: High +**Blockers Found**: Yes + +### Blockers +⛔ **Active unpatched CVEs**: CVE-2023-12345 (RCE) and CVE-2024-67890 (DoS) public for 1+ year with no patches +⛔ **Complete abandonment**: Zero activity for 3 years, no security response +⛔ **Python 3.12 compatibility unknown**: No testing on modern Python + +### Evaluation Scores + +| Signal (Weight) | Score | Evidence | +|-----------------|-------|----------| +| Maintenance (H) | 1/5 | Last commit 2022-03-15 (3 years ago). Last release v0.4.2 on 2022-03-10. | +| Security (H) | 1/5 | 2 open CVEs (High RCE, Medium DoS). No security policy. No patches. | +| Community (M) | 1/5 | Single maintainer (jsmith). 47 open issues, no responses 2+ years. | +| Documentation (M) | 3/5 | Clear README with examples. Uses outdated Python 3.8 syntax. | +| Dependency Footprint (M) | 4/5 | 3 direct, 8 total deps. Lightweight. One transitive dep unmaintained. | +| Production Adoption (M) | 2/5 | 850 downloads/month (low). 12 dependents. Downloads declining -40% YoY. | +| License (H) | 5/5 | MIT. Clean licensing. | +| API Stability (M) | 2/5 | v0.4.x after 5+ years. Breaking changes in minors. No semver. | +| Funding (L) | 1/5 | No funding. Abandoned volunteer project. | +| Ecosystem Momentum (L) | 1/5 | Community migrated to alternatives. No Python 3.12 support verified. | + +**Weighted Score**: 18/50 + +### Key Findings + +**Strengths:** +- Clear basic documentation +- Lightweight dependencies +- Permissive MIT license + +**Concerns:** +- Critical: CVE-2023-12345 RCE vulnerability unpatched +- Complete abandonment (3 years zero activity) +- No modern Python support verified +- Declining usage (-40% YoY) +- Unmaintained transitive dependency (old-xml-lib) + +### Recommended Alternatives +- **modern-parser** (PyPI): Active fork with CVE patches. Same API. 5k downloads/month. 3-person team. +- **fast-parse** (PyPI): Different API, supports same format. Well-maintained. 12k downloads/month. +- **format-tools** (PyPI): Comprehensive legacy format tools. Larger but production-ready. 50k downloads/month. + +### Recommendation Details +**Do not use legacy-parser.** Critical RCE vulnerability (CVE-2023-12345) with no patch. Project abandoned in 2022. Using this package exposes your application to known exploitable vulnerabilities. + +Use **modern-parser** instead—API-compatible drop-in replacement with CVE patches: + +```python +# Before +from legacy_parser import Parser + +# After +from modern_parser import Parser # API-compatible +``` + +### Migration Path +1. Replace with `modern-parser` (API-compatible) +2. Test parsing behavior thoroughly +3. Run `pip-audit` to verify no other vulnerable deps +4. Monitor modern-parser security advisories + +--- + +## Example 3: fast-compute (Rust) - ADOPT with Nuance + +**User Request:** "I need a fast computation library for my Rust project. Is fast-compute good?" + +**Package Context:** +- Name: fast-compute (crates.io) +- Dependency Type: Standard (performance-critical) +- Use Case: High-performance numerical computations + +### Summary +Excellent single-maintainer library with outstanding code quality, documentation, and performance. Single maintainer is highly skilled and responsive. The bus factor of 1 is the only significant concern, but overall quality justifies adoption with proper risk mitigation. + +**Recommendation**: ADOPT (with monitoring) +**Risk Level**: Medium +**Blockers Found**: No + +### Evaluation Scores + +| Signal (Weight) | Score | Evidence | +|-----------------|-------|----------| +| Maintenance (H) | 4/5 | Last release v1.8.2 on 2025-01-05. Bi-monthly releases. Commits 2-3x/week. | +| Security (H) | 5/5 | Zero CVEs. 95% `#![forbid(unsafe_code)]`. 5% unsafe well-documented. Passes cargo-audit. | +| Community (M) | 3/5 | Single maintainer (asmith) but very responsive. 12 contributors for small PRs. Issues answered 24-48hr. | +| Documentation (M) | 5/5 | Excellent docs.rs. Comprehensive examples. API reference with math explanations. | +| Dependency Footprint (M) | 5/5 | 3 total deps (num-traits, rayon, serde). All tier-1 crates. | +| Production Adoption (M) | 4/5 | 52k downloads. 60+ crate dependents. In awesome-rust list. 2 known production users. | +| License (H) | 5/5 | MIT/Apache-2.0 dual (Rust standard). Clean dep licenses. | +| API Stability (M) | 5/5 | v1.x stable 2 years. Strict semver. 1 breaking change (well-communicated). | +| Funding (M) | 2/5 | No corporate backing. GitHub Sponsors: 3 sponsors, $50/mo. No sustainability plan. | +| Ecosystem Momentum (M) | 4/5 | Growing adoption in Rust scientific computing. Active community discussion. | + +**Weighted Score**: 42/50 + +### Key Findings + +**Strengths:** +- Exceptional performance (3-5x faster than alternatives) +- Outstanding docs.rs documentation with mathematical proofs +- Minimal unsafe code (95% safe, 5% expertly justified) +- Highly responsive maintainer (24-48hr triage) +- Clean dependencies (tier-1 crates only) + +**Concerns:** +- Bus factor = 1 (single maintainer, no succession plan) +- Limited funding ($50/month) +- Project depends entirely on one person's availability + +### Alternatives Considered +- **compute-rs**: More contributors but slower performance, less complete docs +- **sci-compute**: Corporate backing but heavier deps, less idiomatic Rust +- **nalgebra**: More general-purpose, well-maintained, less specialized + +### Recommendation Details +fast-compute demonstrates how one skilled maintainer can produce outstanding software. Code quality, documentation, and performance are all excellent. The maintainer (asmith) has shown 2+ years of consistent, responsive maintenance. + +**Single-maintainer risk is real but manageable.** This pattern is common in Rust—many excellent crates have one primary maintainer. The question is whether benefits outweigh risks. + +**Choose this when:** +- Performance advantage (3-5x) is significant for your use case +- Your team can fork/maintain if needed +- Rust expertise available to maintain fork +- Specialized functionality justifies risk + +**Choose alternative when:** +- Organization requires multi-maintainer policy +- Cannot maintain a fork +- compute-rs or sci-compute meet performance needs + +### If You Proceed +- **Sponsor the project**: $20-50/month helps sustainability +- **Monitor actively**: Watch for maintenance velocity changes +- **Build relationship**: Engage constructively in issues/PRs +- **Fork strategy**: Ensure team can fork if needed +- **Consider contributing**: Reduces bus factor, builds familiarity +- **Vendor dependency**: `cargo vendor` for production +- **Pin carefully**: `fast-compute = "1.8"` for patches only + +--- + +## Example 4: mega-framework (npm) - EVALUATE FURTHER + +**User Request:** "Should I use mega-framework for my new web application?" + +**Package Context:** +- Name: mega-framework (npm) +- Dependency Type: Critical (application framework) +- Use Case: Full-stack SaaS application + +### Summary +Comprehensive, well-maintained framework with excellent community and corporate backing. However, 203-dependency footprint with some unmaintained transitive deps and 2.4MB bundle size create significant concerns. Decision depends heavily on specific project requirements and constraints. + +**Recommendation**: EVALUATE FURTHER +**Risk Level**: Medium +**Blockers Found**: No (but significant concerns) + +### Evaluation Scores + +| Signal (Weight) | Score | Evidence | +|-----------------|-------|----------| +| Maintenance (H) | 4/5 | Last release v5.2.0 on 2025-01-15. Monthly releases. 200+ contributors. | +| Security (H) | 4/5 | SECURITY.md present. 3 CVEs in 2024, patched 7-14 days. Large attack surface concern. | +| Community (M) | 5/5 | 200+ contributors, 15 core team. PRs merged quickly. Discord 5k+ members. health_percentage: 92. | +| Documentation (M) | 5/5 | Excellent docs site. Comprehensive tutorials, API reference, guides. Active blog. | +| Dependency Footprint (L) | 2/5 | **Heavy**: 203 total deps (15 direct, 188 transitive). 3 unmaintained 2+ years. Bundle: 2.4MB. | +| Production Adoption (M) | 5/5 | 350k weekly downloads. Used by TechCorp, DataCo, CloudSystems. Case studies available. | +| License (H) | 5/5 | MIT. 2 deps Apache-2.0, rest MIT/BSD. No conflicts. | +| API Stability (M) | 3/5 | Major versions (v4→v5) required substantial refactoring. Deprecation warnings provided. | +| Funding (H) | 5/5 | Backed by Mega Corp (public). 10 full-time engineers. OpenCollective: $45k/mo. | +| Ecosystem Momentum (M) | 4/5 | Strong momentum, competitors emerging. Top-3 in category. 500+ plugins. | + +**Weighted Score**: 39/50 + +### Key Findings + +**Strengths:** +- Comprehensive batteries-included framework +- Excellent docs and active community +- Well-funded with dedicated team +- Production-proven at major companies +- Active development and security response + +**Concerns:** +- **203 total dependencies** (extreme) +- **3 unmaintained transitive deps**: old-event-emitter (2yr), legacy-promisify (3yr), util-deprecated (2yr) +- **2.4MB bundle size** significant weight +- **Complex migrations**: v4→v5 required substantial refactoring +- **High lock-in**: Switching frameworks very costly + +### Unmaintained Transitive Dependencies +1. **old-event-emitter** (2 years) - via router-lib +2. **legacy-promisify** (3 years) - via async-helpers → data-layer +3. **util-deprecated** (2 years) - via build-tools + +Mega Corp aware (issue #4521) but hasn't prioritized replacement. + +### Alternatives Considered +- **slim-framework**: 45 total deps, modular, growing. Less mature. +- **modern-stack**: Newer, 80 deps, lighter. Less production-proven. +- **Build-your-own**: Use focused libraries (react-router, redux, vite). More work, more flexibility. + +### Recommendation Details +mega-framework is **mixed**. Well-maintained and production-ready with strong backing. For teams valuing comprehensive solutions and accepting the weight, it's viable. + +**The 203-dependency footprint is concerning**, especially with unmaintained transitive deps. This is technical debt and potential security risk. + +### Decision Framework + +**Choose mega-framework if:** +- You value comprehensive integration over modularity +- Have security resources to monitor 200+ deps +- Need full feature set (SSR, routing, state, build, testing) +- Bundle size not critical (internal tools, admin dashboards) +- Can handle complex major version migrations + +**Choose alternative if:** +- Minimize dependencies/bundle size is priority +- Prefer modular, focused libraries +- Performance critical (public web, mobile) +- Want component flexibility + +**Recommendation: Evaluate slim-framework first.** Similar DX with 1/5 the dependencies. If insufficient, mega-framework acceptable *with monitoring*. + +### If You Proceed +- **Monitor deps**: `npm audit` in CI, Dependabot for 203 deps +- **Security advisories**: Critical given attack surface +- **Budget migrations**: Plan 2-4 weeks for major versions +- **Track unmaintained deps**: Monitor old-event-emitter, legacy-promisify, util-deprecated +- **Tree-shaking**: Use modular imports +- **Measure bundle impact**: Profile before committing +- **Use LTS versions**: v5 LTS for stability + +--- + +## Key Takeaways from Examples + +### Pattern Recognition + +1. **Single maintainer ≠ automatic rejection** (fast-compute): Assess quality, responsiveness, track record +2. **Abandonment + CVEs = AVOID** (legacy-parser): Security vulns without patches are dealbreakers +3. **Corporate backing ≠ perfect** (mega-framework): Well-funded projects can have concerning dependencies +4. **Multiple strong signals overcome weaknesses** (ExampleCo): Excellence across signals builds confidence + +### Evaluation Best Practices + +- **Weight appropriately**: Security and maintenance > documentation +- **Context matters**: Heavy framework may be fine for internal tools, not public sites +- **Provide alternatives**: Always suggest alternatives for AVOID or EVALUATE FURTHER +- **Be specific**: Cite versions, dates, CVEs, metrics +- **Acknowledge trade-offs**: Few packages are perfect + +### Recommendation Clarity + +- **ADOPT**: Clear benefits, low/acceptable risk, concerns don't outweigh strengths +- **AVOID**: Dealbreaker issues (security, abandonment, licensing) + alternatives +- **EVALUATE FURTHER**: Mixed signals, decision depends on user context/priorities + +## How to Use These Examples + +1. **Template evaluations**: Follow structure (Summary, Scores, Findings, Alternatives, Recommendation) +2. **Gather real data**: These are hypothetical—run actual commands for real evaluations +3. **Adapt weighting**: Adjust signal weights for dependency type (critical vs dev) +4. **Cite evidence**: Include specific versions, dates, metrics, command outputs +5. **Consider context**: Risk tolerance varies by project +6. **Think critically**: Don't mechanically score—understand nuances diff --git a/skills/dependency-evaluator/SCRIPT_USAGE.md b/skills/dependency-evaluator/SCRIPT_USAGE.md new file mode 100644 index 0000000..f3273de --- /dev/null +++ b/skills/dependency-evaluator/SCRIPT_USAGE.md @@ -0,0 +1,333 @@ +# Dependency Evaluator Script Usage + +This document describes how to use the `dependency_evaluator.py` script for automated package data gathering. + +## Overview + +The dependency evaluator script automates the tedious parts of dependency evaluation: +- Running ecosystem-specific commands (npm, pip, cargo, go) +- Fetching data from package registries and GitHub +- Parsing and structuring the results +- Handling errors and edge cases gracefully + +**Recommended approach**: Use the script as your default data gathering method for npm, PyPI, Cargo, and Go packages. It saves time, ensures consistency, and reduces the chance of missing important data points. + +**Manual fallback**: The skill works perfectly fine without the script using the manual workflow described in [WORKFLOW.md](./WORKFLOW.md) - use this for unsupported ecosystems or if the script fails. + +## Prerequisites + +### Required +- Python 3.7 or higher (uses only standard library) + +### Optional (for enhanced functionality) +- **npm** - For evaluating Node.js packages +- **pip** - For evaluating Python packages +- **cargo** - For evaluating Rust crates +- **go** - For evaluating Go modules +- **gh CLI** - For richer GitHub data (falls back to API if not available) + +## Installation + +No installation required! The script uses only Python standard library. + +Location: `learnfrompast/skills/dependency-evaluator/scripts/dependency_evaluator.py` + +## Basic Usage + +```bash +python3 dependency_evaluator.py +``` + +### Examples + +**Evaluate an npm package**: +```bash +python3 dependency_evaluator.py lodash npm +``` + +**Evaluate a Python package**: +```bash +python3 dependency_evaluator.py requests pypi +``` + +**Evaluate a Rust crate**: +```bash +python3 dependency_evaluator.py serde cargo +``` + +**Evaluate a Go module**: +```bash +python3 dependency_evaluator.py github.com/gorilla/mux go +``` + +## Supported Ecosystems + +| Ecosystem | Value | Data Sources | +|-----------|-------|--------------| +| npm (Node.js) | `npm` | npm registry, npm view, GitHub | +| PyPI (Python) | `pypi` | PyPI JSON API, pip, GitHub | +| Cargo (Rust) | `cargo` | crates.io API, GitHub | +| Go | `go` | go list, pkg.go.dev, GitHub | + +## Output Format + +The script outputs structured JSON to stdout: + +```json +{ + "package": "lodash", + "ecosystem": "npm", + "timestamp": "2025-01-26T10:30:00Z", + "registry_data": { + "latest_version": "4.17.21", + "license": "MIT", + "description": "Lodash modular utilities", + "repository_url": "https://github.com/lodash/lodash", + "versions_count": 115, + "publish_history": {...}, + "all_versions": [...] + }, + "github_data": { + "repository_url": "https://github.com/lodash/lodash", + "pushed_at": "2024-12-15T10:30:00Z", + "open_issues_count": 42, + "stargazers_count": 58000, + "contributors_count": 123, + "community_health": {...} + }, + "security_data": {}, + "dependency_footprint": { + "direct_dependencies": 0, + "total_dependencies": 0, + "tree_depth": 1 + }, + "errors": [], + "warnings": [ + "npm audit requires package.json context - skipping" + ] +} +``` + +## Saving Output to File + +```bash +python3 dependency_evaluator.py lodash npm > lodash-data.json +``` + +Then analyze the data file separately. + +## Exit Codes + +- **0**: Success (no errors, warnings are OK) +- **1**: Errors encountered (check `errors` array in output) + +## What the Script Does + +### For npm Packages +1. Runs `npm view --json` for metadata +2. Runs `npm view time --json` for version history +3. Runs `npm view versions --json` for all versions +4. Extracts GitHub repository URL +5. Fetches GitHub API data (stars, issues, contributors, etc.) +6. Notes limitations (npm audit, npm ls require additional context) + +### For PyPI Packages +1. Fetches `https://pypi.org/pypi//json` API +2. Parses package metadata and release history +3. Extracts GitHub repository URL if present +4. Fetches GitHub API data + +### For Cargo Packages +1. Fetches `https://crates.io/api/v1/crates/` API +2. Fetches `https://crates.io/api/v1/crates//versions` API +3. Parses crate metadata and downloads stats +4. Fetches GitHub API data + +### For Go Modules +1. Runs `go list -m -json ` +2. Parses module metadata +3. Fetches GitHub API data if module is hosted on GitHub + +### GitHub Data Gathering +- **Preferred**: Uses `gh` CLI if available (faster, authenticated) +- **Fallback**: Direct GitHub API calls via urllib (rate-limited to 60/hour) +- **Data collected**: Stars, forks, issues, last push, contributors, community health + +## Limitations + +### Commands Requiring Context +Some operations require additional context that the script cannot provide in isolation: + +**npm audit**: Requires `package.json` and installed dependencies +``` +Warning: "npm audit requires package.json context - skipping" +``` + +**npm ls**: Requires package to be installed locally +``` +Warning: "npm ls requires package installation - skipping" +``` + +**Workaround**: Run these commands manually in your project directory after installing the package. + +### GitHub API Rate Limiting +- **Unauthenticated**: 60 requests/hour +- **With gh CLI** (authenticated): 5000 requests/hour + +If you hit rate limits: +``` +Warning: "Access forbidden (rate limit?): https://api.github.com/..." +``` + +**Workaround**: Install and authenticate `gh` CLI, or wait for rate limit reset. + +### Network Dependence +The script requires network access for: +- Package registry APIs (PyPI, crates.io) +- GitHub API + +If offline or network issues occur, you'll see: +``` +Warning: "Network error fetching https://...: ..." +``` + +## Error Handling + +The script is designed to be resilient: + +### Command Not Found +``` +Warning: "Command not found: npm" +``` +**Action**: Install the missing tool or use a different ecosystem + +### Package Not Found +``` +Error: "Resource not found: https://pypi.org/pypi/nonexistent-package/json" +``` +**Action**: Check package name spelling + +### Malformed Data +``` +Warning: "Failed to parse npm view output" +``` +**Action**: Check command output manually, may indicate tool version incompatibility + +## Tips for Best Results + +### 1. Install Ecosystem Tools +Install the tools for ecosystems you frequently evaluate: +```bash +# npm (comes with Node.js) +brew install node + +# pip (comes with Python) +brew install python + +# cargo (Rust) +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# go +brew install go + +# GitHub CLI (optional but recommended) +brew install gh +gh auth login +``` + +### 2. Use with Claude Code Workflow +The script integrates seamlessly with the dependency-evaluator skill: + +```bash +# Gather data first +python3 scripts/dependency_evaluator.py lodash npm > data.json + +# Then ask Claude to analyze it +# "Please analyze the dependency data in data.json and provide an evaluation report" +``` + +### 3. Batch Evaluations +Evaluate multiple packages: +```bash +for pkg in lodash react vue; do + python3 dependency_evaluator.py $pkg npm > "$pkg-data.json" +done +``` + +### 4. Integrate with Scripts +Use in shell scripts or automation: +```bash +#!/bin/bash +OUTPUT=$(python3 dependency_evaluator.py "$1" npm 2>&1) +EXIT_CODE=$? + +if [ $EXIT_CODE -ne 0 ]; then + echo "Evaluation failed for $1" + echo "$OUTPUT" | jq '.errors' +else + echo "Package: $(echo "$OUTPUT" | jq -r '.registry_data.latest_version')" +fi +``` + +## Interpreting Output + +### Registry Data +- **latest_version**: Current stable version +- **license**: Package license (check compatibility) +- **versions_count**: Total number of releases (many = active, few = early/abandoned) +- **publish_history**: Dates of each version (check release cadence) + +### GitHub Data +- **pushed_at**: Last commit date (recent = active maintenance) +- **open_issues_count**: Number of open issues (high = potential problems or popularity) +- **stargazers_count**: GitHub stars (popularity indicator) +- **contributors_count**: Number of contributors (bus factor assessment) +- **community_health.health_percentage**: 0-100 score (>70 is good) + +### Warnings vs Errors +- **Warnings**: Non-critical issues, evaluation continues (e.g., "npm audit skipped") +- **Errors**: Critical failures, data may be incomplete (e.g., "package not found") + +## Troubleshooting + +### "Command not found: npm" +**Problem**: npm is not installed or not in PATH +**Solution**: Install Node.js or add npm to PATH + +### "Access forbidden (rate limit?)" +**Problem**: GitHub API rate limit exceeded +**Solution**: Install and authenticate gh CLI, or wait 1 hour + +### "Failed to parse npm view output" +**Problem**: npm output format changed or npm version incompatible +**Solution**: Update npm (`npm install -g npm@latest`) or report issue + +### Output shows empty registry_data +**Problem**: Package doesn't exist or command failed +**Solution**: Check package name, review warnings/errors array + +### Script hangs/times out +**Problem**: Network issue or slow API response +**Solution**: Check internet connection, script timeout is 30s per command + +## Next Steps + +After gathering data with the script: +1. Review the JSON output for completeness +2. Use the [SIGNAL_DETAILS.md](./SIGNAL_DETAILS.md) guide to interpret each signal +3. Apply the scoring framework from [SKILL.md](./SKILL.md) +4. Generate your evaluation report following [WORKFLOW.md](./WORKFLOW.md) + +## Reporting Issues + +If you encounter bugs or have suggestions: +1. Check the `errors` and `warnings` arrays in the output +2. Verify the issue isn't covered in Troubleshooting above +3. Report with: package name, ecosystem, full output, Python version, OS + +## See Also + +- [SKILL.md](./SKILL.md) - Main evaluation framework +- [WORKFLOW.md](./WORKFLOW.md) - Step-by-step evaluation process +- [COMMANDS.md](./COMMANDS.md) - Manual command reference +- [ERROR_HANDLING.md](./ERROR_HANDLING.md) - Fallback strategies diff --git a/skills/dependency-evaluator/SIGNAL_DETAILS.md b/skills/dependency-evaluator/SIGNAL_DETAILS.md new file mode 100644 index 0000000..73173dc --- /dev/null +++ b/skills/dependency-evaluator/SIGNAL_DETAILS.md @@ -0,0 +1,486 @@ +# Evaluation Signal Details + +This file provides deep guidance for each of the 10 evaluation signals used in dependency assessment. For each signal, you'll find what it measures, how to investigate it, how to interpret results, and what constitutes red vs. green flags. + +## Assessment Philosophy: Ecosystem-Relative Evaluation + +**Use comparative assessment rather than absolute thresholds.** What's "normal" varies significantly by: +- **Ecosystem**: npm vs PyPI vs Cargo vs Go have different cultural norms +- **Package type**: Frameworks vs utilities vs libraries have different expectations +- **Maturity**: New packages vs mature stable packages have different activity patterns + +**Throughout this guide:** +- Red/green flags are framed as comparisons to ecosystem norms +- Specific numbers provide context, not rigid cutoffs +- "Significantly below/above norm" means outlier for package category in its ecosystem +- Always compare package to similar packages in same ecosystem before scoring + +See [ECOSYSTEM_GUIDES.md](./ECOSYSTEM_GUIDES.md) for ecosystem-specific baselines and norms. + +## 1. Activity and Maintenance Patterns + +### What This Signal Measures +The frequency and consistency of package updates, bug fixes, and maintainer responsiveness. Active maintenance indicates the package is being improved and issues are being addressed. + +### What to Check +- Commit history and release cadence +- Time since last release +- How quickly critical bugs and security issues get addressed +- Issue triage responsiveness +- Consistency of maintenance over time + +### Ecosystem-Relative Assessment + +**Compare package activity against ecosystem norms rather than absolute thresholds.** What's "normal" varies significantly by language, package type, and maturity. + +**Release Cadence Comparison:** +- **Red flag**: Release cadence significantly below ecosystem norm for similar packages + - npm actively-developed packages: Most release monthly or more; quarterly is typical minimum + - Rust crates: Bi-monthly to quarterly is common; annual can be acceptable for stable crates + - Python packages: Monthly to quarterly for active development + - Go modules: Quarterly common; infrequent releases normal due to stdlib-first culture +- **Assessment**: Is this package's release pattern an outlier for its category within its ecosystem? + +**Commit Activity Comparison:** +- **Red flag**: Commit activity has ceased while similar packages maintain activity + - Look at comparable packages in same ecosystem/category + - Mature stable libraries may legitimately have low commit frequency + - New/actively-developed tools should show regular activity +- **Green flag**: Inactivity with zero open security issues may indicate package is "done" (complete, not abandoned) +- **Context**: Protocol implementations, math utilities, stable APIs may need few updates + +**Issue Response Comparison:** +- **Red flag**: Issue response time significantly slower than ecosystem norm + - npm: Hours to days typical for popular packages; weeks acceptable + - Smaller ecosystems: Days to weeks is normal + - Compare: Are issues being triaged, or ignored completely? +- **Critical**: Unaddressed security issues override all activity metrics + +**Backlog Assessment:** +- **Red flag**: Issue backlog growing while similar packages maintain healthy triage + - npm popular packages: 20-50 open issues may be normal if being triaged + - Smaller projects: 10+ untriaged issues concerning + - Key: Are maintainers responding, even if not immediately fixing? + +### Red Flags (Ecosystem-Relative) +- Release cadence significantly below ecosystem median for package category +- Commit activity ceased while comparable packages remain active +- Issue response time far slower than ecosystem norm +- Growing backlog with zero maintainer engagement +- Unaddressed security issues (absolute red flag regardless of ecosystem) + +### Green Flags (Ecosystem-Relative) +- Release cadence at or above ecosystem median +- Commit activity appropriate for package maturity and ecosystem +- Issue triage responsiveness comparable to or better than ecosystem norm +- Active PR review and merging +- Security issues addressed promptly even if feature development is slow + +### Common False Positives +- **Low activity in mature libraries**: A date library or cryptography implementation that hasn't changed in years might be complete, not abandoned. Check if issues are triaged and security updates still happen. +- **Seasonal patterns**: Academic or side-project packages may have irregular but acceptable maintenance patterns +- **Small scope packages**: A package that does one thing well may legitimately need few updates + +## 2. Security Posture + +### What This Signal Measures +How the project handles security vulnerabilities, whether it has established security practices, and its history of security issues. + +### What to Check +- Security policy existence (SECURITY.md) +- Vulnerability disclosure process +- History of security advisories and CVEs +- Response time to past vulnerabilities +- Automated security scanning (Dependabot, Snyk badges) +- Proactive security measures + +### How to Investigate +- Search for CVE history: `"" CVE` +- Look for security badges in README (Snyk, Dependabot) +- Review GitHub Security tab +- Check OSV database: https://osv.dev +- Run ecosystem security tools (npm audit, etc.) + +### Red Flags +- No security policy or disclosure process documented +- Slow CVE response time (30+ days from disclosure to patch) +- Multiple unpatched vulnerabilities +- No security scanning in CI/CD +- History of severe vulnerabilities +- Dismissive attitude toward security reports + +### Green Flags +- Published SECURITY.md with clear reporting process +- Quick CVE patches (< 7 days for critical issues) +- Security scanning enabled (Dependabot, Snyk) +- Bug bounty program +- Security-focused documentation +- Proactive security audits + +### Common False Positives +- **Old, fixed vulnerabilities**: Past CVEs that were quickly patched show good response, not poor security +- **Reported but not exploitable**: Some CVE reports may be theoretical or non-exploitable in practice + +## 3. Community Health + +### What This Signal Measures +The breadth and engagement of the project's community, contributor diversity, and the "bus factor" (what happens if the main maintainer leaves). + +### What to Check +- Contributor diversity (single maintainer vs. team) +- PR merge rates and issue response times +- Stack Overflow activity +- Community forum engagement +- Maintainer communication style +- Organizational backing + +### How to Interpret +- `health_percentage` (from GitHub API) > 70 is good; < 50 suggests missing community files +- Multiple contributors (not just 1-2) indicates healthier bus factor +- Issues with comments show maintainer engagement; many 0-comment issues is a red flag +- PRs merged within days/weeks is healthy; months suggests slow maintenance + +### Red Flags +- Single maintainer with no backup or succession plan +- PRs sitting for months unreviewed +- Hostile or dismissive responses to issues +- No community engagement (Discord, Slack, forums) +- Maintainer burnout signals +- All recent activity from a single contributor + +### Green Flags +- Multiple active maintainers (3+ regular contributors) +- PRs reviewed within days +- Active Discord/Slack/forum community +- "Good first issue" labels for newcomers +- Welcoming, constructive communication +- Clear governance model or code of conduct +- Corporate or foundation backing + +### Common False Positives +- **Single maintainer**: Many excellent packages have one dedicated maintainer. This is higher risk but not automatically disqualifying if the maintainer is responsive and the codebase is simple enough to fork. +- **Low community activity for niche tools**: Specialized packages may have small but high-quality communities + +## 4. Documentation Quality + +### What This Signal Measures +How well the package is documented, including API references, usage examples, migration guides, and architectural decisions. + +### What to Check +- Comprehensive API documentation +- Migration guides between major versions +- Real-world usage examples that work +- Architectural decision records (ADRs) +- TypeScript types / type definitions +- Inline code documentation +- Getting started tutorials + +### Red Flags +- Minimal or outdated README +- No API reference documentation +- No migration guides for breaking changes +- Examples that don't work with current version +- Missing type definitions for TypeScript +- No explanation of key concepts +- Documentation and code out of sync + +### Green Flags +- Comprehensive documentation site (e.g., Docusaurus, MkDocs) +- Versioned documentation matching releases +- Clear upgrade guides with examples +- Working examples and tutorials +- Interactive playgrounds or demos +- Architecture diagrams +- Searchable API reference +- Contribution guidelines + +### Common False Positives +- **Self-documenting APIs**: Very simple, intuitive APIs may not need extensive docs +- **Code-focused projects**: Some low-level libraries may have minimal prose but excellent code comments + +## 5. Dependency Footprint + +### What This Signal Measures +The size and complexity of the dependency tree, including transitive dependencies and overall bundle size impact. + +### What to Check +- Number of direct dependencies +- Number of transitive dependencies +- Total dependency tree depth +- Quality and maintenance of transitive dependencies +- Bundle size impact +- Presence of native/binary dependencies + +### Interpreting Dependency Trees (Ecosystem-Relative) + +**Compare dependency counts against ecosystem norms:** + +**Total Count Assessment:** +- **npm**: 20-50 transitive deps common; 100+ raises concerns; 200+ is extreme +- **Python/PyPI**: 10-30 transitive deps typical; 50+ concerning for utilities +- **Rust/Cargo**: 20-40 transitive deps common (proc-macros inflate counts); 80+ heavy +- **Go**: 5-20 deps typical (stdlib-first culture); 40+ unusual +- **Key**: Compare functionality complexity to dependency count—simple utility with ecosystem-high dep count is red flag + +**Duplicate Versions:** +- Multiple versions of same package indicate potential conflicts +- More concerning in npm (version resolution complex) than Cargo (strict resolution) + +**Tree Depth:** +- Deep nesting (5+ levels) harder to audit regardless of ecosystem +- Rust proc-macro deps often add depth without adding risk + +**Abandoned Transitive Dependencies:** +- Assess transitive deps using same maintenance criteria as direct deps +- One abandoned transitive dep may not be blocker; many suggests poor dep hygiene + +**Bundle Size vs. Functionality:** +- npm: Compare to similar packages—is this outlier for what it does? +- Rust: Compile-time deps don't affect binary size, only build time +- Assess: Does bundle size match functionality provided? + +### Red Flags (Ecosystem-Relative) +- Dependency count in top quartile for package's functionality and ecosystem +- Transitive dependencies with known vulnerabilities +- Bundle size significantly above ecosystem norm for similar functionality +- Multiple unmaintained transitive dependencies +- Conflicting dependency version requirements +- Native dependencies when ecosystem-standard pure implementation available + +### Green Flags (Ecosystem-Relative) +- Dependency count at or below ecosystem median for package type +- All dependencies well-maintained and reputable +- Tree-shakeable / modular imports (npm, modern JS) +- Native deps only when necessary for performance/functionality +- Flat, shallow dependency structure +- Dependencies regularly updated + +### Common False Positives +- **Framework packages**: Full frameworks (React, Vue, Angular) legitimately have more dependencies +- **Native performance**: Some packages legitimately need native bindings for performance + +## 6. Production Adoption + +### What This Signal Measures +Real-world usage of the package in production environments, indicating battle-tested reliability and community trust. + +### What to Check +- Download statistics and trends +- GitHub "Used by" count (dependents) +- Notable companies/projects using it +- Tech blog case studies +- Production deployment mentions +- Community recommendations + +### How to Investigate +- Check weekly/monthly download counts (npm, PyPI, crates.io) +- Review GitHub dependents graph +- Search " production" in tech blogs +- Look for case studies from reputable companies +- Check framework/platform official recommendations + +### Red Flags +- High download counts but no visible production usage (bot inflation) +- Only tutorial/example usage, no production mentions +- Declining download trends over time +- No notable adopters despite being old +- All usage from forks or abandoned projects + +### Green Flags +- Used by large, reputable organizations +- Growing or stable download trends +- Featured in production case studies +- Part of major frameworks' recommended ecosystems +- Referenced in official platform documentation +- Active "Who's using this" list + +### Common False Positives +- **New packages**: Legitimately new packages may have low downloads but high quality +- **Niche tools**: Specialized packages may have low downloads but be essential for their domain +- **Internal tooling**: Some excellent packages are used primarily internally + +## 7. License Compatibility + +### What This Signal Measures +Whether the package's license and its dependencies' licenses are compatible with your project's license and intended use. + +### What to Check +- Package license type (MIT, Apache-2.0, GPL, etc.) +- License compatibility with your project +- License stability (no recent unexpected changes) +- Transitive dependency licenses +- Patent grants (especially Apache-2.0) + +### Red Flags +- Copyleft licenses (GPL, AGPL) for proprietary projects +- No license specified (all rights reserved by default) +- Recent license changes without notice +- Conflicting transitive dependency licenses +- Licenses with advertising clauses +- Ambiguous or custom licenses + +### Green Flags +- Permissive licenses (MIT, Apache-2.0, BSD-3-Clause) +- Clear LICENSE file in repository +- Consistent licensing across all dependencies +- SPDX identifiers used +- Patent grants (Apache-2.0) +- Well-understood, OSI-approved licenses + +### Common False Positives +- **GPL for standalone tools**: GPL is fine for CLI tools and dev dependencies that don't link into your code +- **Dual licensing**: Some projects offer both commercial and open-source licenses + +## 8. API Stability + +### What This Signal Measures +How frequently the API changes in breaking ways, adherence to semantic versioning, and the deprecation process. + +### What to Check +- Changelog for breaking changes +- Semantic versioning adherence +- Deprecation policy and process +- Frequency of breaking changes in minor versions +- Migration tooling (codemods) for major upgrades +- Version number progression + +### How to Investigate +- Review CHANGELOG.md or GitHub releases +- Check version history for breaking change patterns +- Look for semver violations (breaking changes in patches/minors) +- Check for deprecation warnings before removal + +### Red Flags +- Frequent breaking changes in minor/patch versions +- No changelog or release notes +- No deprecation warnings before API removal +- Stuck at 0.x version for years +- Breaking changes without major version bumps +- No migration guides for major versions + +### Green Flags +- Strict semantic versioning adherence +- Clear, multi-release deprecation cycle +- Stable API (1.x+ with rare breaking changes) +- Migration codemods for major upgrades +- Detailed changelogs with examples +- Beta/RC releases before major versions +- Long-term support (LTS) versions + +### Common False Positives +- **Pre-1.0 experimentation**: 0.x versions are expected to have breaking changes +- **Rapid iteration by design**: Some frameworks intentionally move fast and document it clearly + +## 9. Bus Factor and Funding + +### What This Signal Measures +The sustainability of the project if key contributors leave, and whether there's financial support for ongoing maintenance. + +### What to Check +- Organizational backing (CNCF, Apache Foundation, company sponsorship) +- OpenCollective or GitHub Sponsors presence +- Corporate contributor presence +- Full-time vs. volunteer maintainers +- Succession planning +- Funding transparency + +### How to Investigate +- Check for sponsor badges in README +- Look for corporate affiliations in contributor profiles +- Search " funding" or " sponsor" +- Check foundation membership (Linux Foundation, Apache, etc.) +- Review OpenCollective or GitHub Sponsors pages + +### Red Flags +- Solo volunteer maintainer for critical infrastructure +- No funding mechanism or sponsorship +- Maintainer burnout signals in issues/discussions +- Company backing withdrawn recently +- Underfunded relative to usage scale +- No succession plan + +### Green Flags +- Foundation backing (Linux Foundation, Apache, CNCF) +- Active sponsorship program with multiple sponsors +- Corporate maintainers (paid full-time) +- Sustainable funding model +- Multiple organizations contributing +- Clear governance structure +- Successor maintainers identified + +### Common False Positives +- **Passion projects**: Some maintainers prefer unfunded projects and sustain them long-term +- **Mature, low-maintenance tools**: Stable packages may not need significant funding + +## 10. Ecosystem Momentum + +### What This Signal Measures +Whether the technology and ecosystem around the package is growing, stable, or declining. + +### What to Check +- Is the ecosystem migrating to alternatives? +- Framework/platform official support and alignment +- Technology trend direction +- Competitor activity +- Conference talks and blog posts +- Job market demand + +### How to Investigate +- Search for ecosystem discussions and trends +- Check if framework docs recommend alternatives +- Review technology radar reports (ThoughtWorks, etc.) +- Monitor competitor package growth +- Check conference talk mentions + +### Red Flags +- Ecosystem actively migrating to alternatives +- Deprecated by the framework it supports +- Based on sunset technology (Flash, CoffeeScript) +- No mentions at recent conferences +- Declining search trends +- Framework removed official support + +### Green Flags +- Growing ecosystem adoption +- Aligned with platform direction and roadmap +- Active plugin/extension ecosystem +- Regular conference mentions +- Increasing search and job trends +- Framework official recommendation +- Standards body involvement + +### Common False Positives +- **Stable, mature ecosystems**: Not every package needs to be trendy; stability can be valuable +- **Niche domains**: Specialized tools may have small but stable ecosystems + +## General Interpretation Guidelines + +### Context Matters +Always adjust signal interpretation based on: +- **Dependency criticality**: Auth libraries need stricter standards than dev tools +- **Project scale**: Enterprise projects have lower risk tolerance +- **Domain complexity**: Cryptography packages need different evaluation than UI libraries +- **Ecosystem norms**: Rust culture emphasizes different values than npm culture + +### Weighted Scoring +Not all signals are equally important: +- **Critical dependencies**: Prioritize Security, Maintenance, Funding +- **Standard dependencies**: Balance all signals +- **Dev dependencies**: Prioritize Maintenance, API Stability + +### Blocker Override +Any critical red flag (supply chain risk, security exploitation, license violation) should result in AVOID recommendation regardless of other scores. + +### Evidence-Based Assessment +Always cite specific data: +- Version numbers and dates +- Actual download counts or GitHub stars +- Specific CVE numbers +- Named organizations using the package +- Measured bundle sizes + +### Nuanced Judgment +Avoid purely mechanical scoring: +- A 3/5 in one signal with concerning details may be worse than 2/5 with clear mitigation +- Consider trajectory: improving vs. declining +- Weight recent data more than historical diff --git a/skills/dependency-evaluator/SKILL.md b/skills/dependency-evaluator/SKILL.md new file mode 100644 index 0000000..3c303d6 --- /dev/null +++ b/skills/dependency-evaluator/SKILL.md @@ -0,0 +1,246 @@ +--- +name: dependency-evaluator +description: Evaluates whether a programming language dependency should be used by analyzing maintenance activity, security posture, community health, documentation quality, dependency footprint, production adoption, license compatibility, API stability, and funding sustainability. Use when users are considering adding a new dependency, evaluating an existing dependency, or asking about package/library recommendations. +allowed-tools: + - Read + - Bash + - Grep + - Glob + - WebFetch + - WebSearch +--- + +# Dependency Evaluator Skill + +This skill helps evaluate whether a programming language dependency should be added to a project by analyzing multiple quality signals and risk factors. + +## Purpose + +Making informed decisions about dependencies is critical for project health. A poorly chosen dependency can introduce security vulnerabilities, maintenance burden, and technical debt. This skill provides a systematic framework for evaluating dependencies before adoption. + +## When to Use + +Activate this skill when users: +- Ask about whether to use a specific package/library +- Want to evaluate a dependency before adding it +- Need to compare alternative packages +- Ask "should I use X library?" +- Want to assess the health of a dependency +- Mention adding a new npm/pip/cargo/gem/etc. package +- Ask about package recommendations for a use case + +## Reference Files + +This skill uses progressive disclosure - core framework below, detailed guidance in reference files: + +| File | When to Consult | +|------|-----------------| +| **[WORKFLOW.md](./WORKFLOW.md)** | Detailed step-by-step evaluation process, performance tips, pitfalls | +| **[SCRIPT_USAGE.md](./SCRIPT_USAGE.md)** | Automated data gathering script (optional efficiency tool) | +| **[COMMANDS.md](./COMMANDS.md)** | Ecosystem-specific commands (npm, PyPI, Cargo, Go, etc.) | +| **[SIGNAL_DETAILS.md](./SIGNAL_DETAILS.md)** | Deep guidance for scoring each of the 10 signals | +| **[ECOSYSTEM_GUIDES.md](./ECOSYSTEM_GUIDES.md)** | Ecosystem-specific norms and considerations | +| **[EXAMPLES.md](./EXAMPLES.md)** | Worked evaluation examples (ADOPT, AVOID, EVALUATE FURTHER) | +| **[ERROR_HANDLING.md](./ERROR_HANDLING.md)** | Fallback strategies when data unavailable or commands fail | + +**Quick navigation by ecosystem:** +- **npm** → COMMANDS.md § Node.js + ECOSYSTEM_GUIDES.md § npm +- **PyPI** → COMMANDS.md § Python + ECOSYSTEM_GUIDES.md § PyPI +- **Cargo** → COMMANDS.md § Rust + ECOSYSTEM_GUIDES.md § Cargo +- **Go** → COMMANDS.md § Go + ECOSYSTEM_GUIDES.md § Go +- **Other** → COMMANDS.md for ecosystem-specific commands + +## Evaluation Framework + +Evaluate dependencies using these ten key signals: + +1. **Activity and Maintenance Patterns** - Commit history, release cadence, issue responsiveness +2. **Security Posture** - CVE history, security policies, vulnerability response time +3. **Community Health** - Contributor diversity, PR merge rates, bus factor +4. **Documentation Quality** - API docs, migration guides, examples +5. **Dependency Footprint** - Transitive dependencies, bundle size +6. **Production Adoption** - Download stats, notable users, trends +7. **License Compatibility** - License type, transitive license obligations +8. **API Stability** - Breaking change frequency, semver adherence +9. **Bus Factor and Funding** - Organizational backing, sustainability +10. **Ecosystem Momentum** - Framework alignment, technology trends + +**For detailed investigation guidance**, see [SIGNAL_DETAILS.md](./SIGNAL_DETAILS.md). +**For ecosystem-specific commands**, see [COMMANDS.md](./COMMANDS.md). +**For ecosystem considerations**, see [ECOSYSTEM_GUIDES.md](./ECOSYSTEM_GUIDES.md). + +## Evaluation Approach + +**Goal:** Provide evidence-based recommendations (ADOPT / EVALUATE FURTHER / AVOID) by systematically assessing 10 quality signals. + +**Process:** Quick assessment → Data gathering → Scoring → Report generation + +See **[WORKFLOW.md](./WORKFLOW.md)** for detailed step-by-step guidance, performance tips, and workflow variants. + +### Automated Data Gathering (Recommended) + +A Python script (`scripts/dependency_evaluator.py`) automates initial data gathering for supported ecosystems (npm, pypi, cargo, go). The script: +- Runs ecosystem commands automatically +- Fetches GitHub API data +- Outputs structured JSON +- Uses only Python standard library (no external dependencies) +- Saves 10-15 minutes per evaluation + +**Default approach:** Try the script first - it provides more complete and consistent data gathering. Only fall back to manual workflow if the script is unavailable or fails. + +**Use the script when:** Evaluating npm, PyPI, Cargo, or Go packages (most common ecosystems) +**Use manual workflow when:** Unsupported ecosystem, Python unavailable, or script errors occur + +See **[SCRIPT_USAGE.md](./SCRIPT_USAGE.md)** for complete documentation. The skill works perfectly fine without the script using manual workflow. + +## Before You Evaluate: Is a Dependency Needed? + +**Write it yourself if:** Functionality is <50 lines of straightforward code, or you only need a tiny subset of features. + +**Use a dependency if:** Problem is complex (crypto, dates, parsing), correctness is critical, or ongoing maintenance would be significant. + +See **[WORKFLOW.md](./WORKFLOW.md)** § Pre-Evaluation for detailed decision framework. + +## Output Format + +Structure your evaluation report as: + +```markdown +## Dependency Evaluation: + +### Summary +[2-3 sentence overall assessment with recommendation] + +**Recommendation**: [ADOPT / EVALUATE FURTHER / AVOID] +**Risk Level**: [Low / Medium / High] +**Blockers Found**: [Yes/No] + +### Blockers (if any) +[List any dealbreaker issues - these override all scores] +- ⛔ [Blocker description with specific evidence] + +### Evaluation Scores + +| Signal | Score | Weight | Notes | +|--------|-------|--------|-------| +| Maintenance | X/5 | [H/M/L] | [specific evidence with dates/versions] | +| Security | X/5 | [H/M/L] | [specific evidence] | +| Community | X/5 | [H/M/L] | [specific evidence] | +| Documentation | X/5 | [H/M/L] | [specific evidence] | +| Dependency Footprint | X/5 | [H/M/L] | [specific evidence] | +| Production Adoption | X/5 | [H/M/L] | [specific evidence] | +| License | X/5 | [H/M/L] | [specific evidence] | +| API Stability | X/5 | [H/M/L] | [specific evidence] | +| Funding/Sustainability | X/5 | [H/M/L] | [specific evidence] | +| Ecosystem Momentum | X/5 | [H/M/L] | [specific evidence] | + +**Weighted Score**: X/50 (adjusted for dependency criticality) + +### Key Findings + +#### Strengths +- [Specific strength with evidence] +- [Specific strength with evidence] + +#### Concerns +- [Specific concern with evidence] +- [Specific concern with evidence] + +### Alternatives Considered +[If applicable, mention alternatives worth evaluating] + +### Recommendation Details +[Detailed reasoning for the recommendation with specific evidence] + +### If You Proceed (for ADOPT recommendations) +[Specific advice tailored to risks found] +- Version pinning strategy +- Monitoring recommendations +- Specific precautions based on identified concerns +``` + +## Scoring Weights + +Adjust signal weights based on dependency type: + +| Signal | Critical Dep | Standard Dep | Dev Dep | +|--------|-------------|--------------|---------| +| Security | High | Medium | Low | +| Maintenance | High | Medium | Medium | +| Funding | High | Low | Low | +| License | High | High | Medium | +| API Stability | Medium | Medium | High | +| Documentation | Medium | Medium | Medium | +| Community | Medium | Medium | Low | +| Dependency Footprint | Medium | Low | Low | +| Production Adoption | Medium | Medium | Low | +| Ecosystem Momentum | Low | Medium | Low | + +**Critical Dependencies**: Auth, security, data handling - require higher bar for all signals + +**Standard Dependencies**: Utilities, formatting - balance all signals + +**Development Dependencies**: Testing, linting - lower security concerns, focus on maintainability + +### Score Interpretation Rules + +**Blocker Override**: Any blocker issue → AVOID recommendation regardless of scores + +**Critical Thresholds**: +- Security or Maintenance score ≤ 2 → Strongly reconsider regardless of other scores +- Any High-weight signal ≤ 2 → Flag as significant concern in report +- Overall weighted score < 25 → Default to EVALUATE FURTHER or AVOID +- Overall weighted score ≥ 35 → Generally safe to ADOPT (if no blockers) + +**Weighting Priority**: Security and Maintenance typically matter more than Documentation or Ecosystem Momentum. A well-documented but unmaintained package is riskier than a poorly-documented but actively maintained one. + +## Critical Red Flags (Dealbreakers) + +These issues trigger automatic AVOID recommendation: + +### Supply Chain Risks +- ⛔ Typosquatting: Package name suspiciously similar to popular package +- ⛔ Compiled binaries without source: Binary blobs without build instructions +- ⛔ Sudden ownership transfer: Recent transfer to unknown maintainer +- ⛔ Install scripts with network calls: Postinstall scripts downloading external code + +### Maintainer Behavior +- ⛔ Ransom behavior: Maintainer demanding payment to fix security issues +- ⛔ Protest-ware: Code performing actions based on political/geographic conditions +- ⛔ Intentional sabotage history: Any history of deliberately breaking the package + +### Security Issues +- ⛔ Active exploitation: Known vulnerability being actively exploited in wild +- ⛔ Credentials in source: API keys, passwords, or secrets in repository +- ⛔ Disabled security features: Package disables security without clear reason + +### Legal Issues +- ⛔ License violation: Package includes code violating its stated license +- ⛔ No license: No license file means all rights reserved (legally risky) +- ⛔ License change without notice: Recent sneaky change to restrictive terms + + +## Self-Validation Checklist + +Before presenting your report, verify: + +- [ ] Cited specific versions and dates for all claims? +- [ ] Ran actual commands rather than making assumptions? +- [ ] All scores supported by evidence in "Notes" column? +- [ ] If Security or Maintenance ≤ 2, flagged prominently? +- [ ] If any blocker exists, recommendation is AVOID? +- [ ] Provided at least 2 alternatives if recommending AVOID? +- [ ] "If You Proceed" section tailored to specific risks found? +- [ ] Recommendation aligns with weighted score and blocker rules? + +## Evaluation Principles + +**Be Evidence-Based:** Cite specific versions, dates, and metrics. Run commands to gather data, never assume. + +**Be Balanced:** Acknowledge strengths AND weaknesses. Single issues rarely disqualify (unless blocker). + +**Be Actionable:** Provide clear ADOPT/EVALUATE FURTHER/AVOID with alternatives and risk mitigation. + +**Be Context-Aware:** Auth libraries need stricter scrutiny than dev tools. Adjust for ecosystem norms (see ECOSYSTEM_GUIDES.md). + +See **[WORKFLOW.md](./WORKFLOW.md)** § Common Pitfalls and § Guidelines for detailed best practices. diff --git a/skills/dependency-evaluator/WORKFLOW.md b/skills/dependency-evaluator/WORKFLOW.md new file mode 100644 index 0000000..3b903b2 --- /dev/null +++ b/skills/dependency-evaluator/WORKFLOW.md @@ -0,0 +1,570 @@ +# Dependency Evaluation Workflow + +This file provides detailed workflow guidance for conducting systematic dependency evaluations. The main SKILL.md file provides the framework overview; this file provides step-by-step operational guidance. + +## Table of Contents + +- [Overview](#overview) +- [Pre-Evaluation: Should You Add Any Dependency?](#pre-evaluation-should-you-add-any-dependency) +- [Phase 1: Quick Assessment](#phase-1-quick-assessment) +- [Phase 2: Data Gathering](#phase-2-data-gathering) +- [Phase 3: Scoring & Analysis](#phase-3-scoring--analysis) +- [Phase 4: Report Generation](#phase-4-report-generation) +- [Performance Tips](#performance-tips) +- [Common Pitfalls to Avoid](#common-pitfalls-to-avoid) + +--- + +## Overview + +Follow this systematic process for thorough, efficient dependency evaluation. Not every evaluation requires all steps—use judgment based on complexity. + +**For simple single-package evaluations:** Proceed directly through phases. +**For complex scenarios** (comparing 3+ packages, contradictory signals, critical dependencies): Take extra care in each phase. + +--- + +## Pre-Evaluation: Should You Add Any Dependency? + +Before evaluating a specific package, ask: **Is a dependency actually needed?** + +### Write It Yourself If: +- The functionality is < 50 lines of straightforward code +- You only need a small subset of the package's features +- The package adds significant weight for minimal functionality +- Example: Don't add a 500KB package to pad strings or check if a number is odd + +### Use a Dependency If: +- The problem domain is complex (crypto, date/time, parsing) +- Correctness is critical and well-tested implementations exist +- The functionality would require significant ongoing maintenance +- You need the full feature set, not just one function + +**If you're unsure:** Prototype the functionality yourself (30-60 minutes). If it's trivial, you have your answer. If it's complex, you've confirmed a dependency is justified. + +--- + +## Phase 1: Quick Assessment + +**Goal:** Identify immediate dealbreakers before investing time in full evaluation. + +### Steps + +1. **Identify package ecosystem** + - npm, PyPI, Cargo, Go, Maven, RubyGems, etc. + - See [ECOSYSTEM_GUIDES.md](./ECOSYSTEM_GUIDES.md) for ecosystem-specific considerations + +2. **Verify package identity** + ```bash + # Check package name carefully + # Watch for typosquatting: react vs reakt, requests vs reqeusts + ``` + - **Red flag:** Name suspiciously similar to popular package + - **Red flag:** Package created very recently with popular-sounding name + +3. **Check for immediate dealbreakers** (see SKILL.md § Critical Red Flags) + - Supply chain risks (typosquatting, sudden ownership transfer) + - Maintainer behavior issues (ransom-ware, protest-ware) + - Active exploitation of known vulnerabilities + - Legal issues (no license, license violations) + +4. **Locate source repository** + ```bash + # npm + npm view repository.url + + # PyPI + pip show | grep "Home-page" + + # Cargo + cargo metadata | jq '.packages[] | select(.name=="") | .repository' + ``` + - If no repository found → See [ERROR_HANDLING.md](./ERROR_HANDLING.md) § Missing GitHub Repository + +5. **Quick license check** + ```bash + # npm + npm view license + + # GitHub + gh api repos/{owner}/{repo}/license --jq '.license.spdx_id' + ``` + - **Blocker if:** GPL for proprietary project, no license, incompatible license + +### Decision Point + +**If blocker found:** +→ Skip to Phase 4, generate AVOID recommendation with alternatives + +**If no blockers:** +→ **Default:** Proceed to Phase 1.5 (Automated Data Gathering Script) +→ **Fallback:** Skip to Phase 2 (Manual Data Gathering) only if script unavailable + +--- + +## Phase 1.5: Automated Data Gathering (Recommended) + +**Goal:** Use the dependency evaluator script to quickly gather baseline data. + +**Default approach:** Try the script first for supported ecosystems (npm, pypi, cargo, go). It saves 10-15 minutes of manual command execution and provides structured, complete data automatically. + +**Skip the script only if:** +- Python 3.7+ is not available in your environment +- Unsupported ecosystem (Maven, RubyGems, NuGet, etc.) +- Script fails or produces errors (then fall back to manual workflow) +- Specific network/firewall restrictions prevent API access + +### Using the Script + +```bash +cd learnfrompast/skills/dependency-evaluator +python3 scripts/dependency_evaluator.py > data.json +``` + +**Examples:** +```bash +# npm package +python3 scripts/dependency_evaluator.py lodash npm > lodash-data.json + +# PyPI package +python3 scripts/dependency_evaluator.py requests pypi > requests-data.json + +# Cargo crate +python3 scripts/dependency_evaluator.py serde cargo > serde-data.json +``` + +### What the Script Provides + +The script automatically gathers: +- ✓ Registry metadata (version, license, description) +- ✓ Version history and release count +- ✓ GitHub repository data (stars, issues, contributors) +- ✓ Community health metrics +- ✓ Structured error/warning messages + +The script has limitations: +- ✗ npm audit (requires package.json context) +- ✗ Dependency tree analysis (requires installation) +- ✗ Manual investigation (documentation quality, ecosystem trends) + +See [SCRIPT_USAGE.md](./SCRIPT_USAGE.md) for detailed documentation. + +### Interpreting Script Output + +Review the JSON output: + +```json +{ + "registry_data": { ... }, // Use for Signals 1, 6, 7 + "github_data": { ... }, // Use for Signals 1, 2, 3, 9 + "security_data": { ... }, // Use for Signal 2 (often limited) + "dependency_footprint": { ... }, // Use for Signal 5 (often limited) + "warnings": [ ... ], // Note data limitations + "errors": [ ... ] // Critical issues found +} +``` + +**If errors are present:** Verify package name, check network, review error messages + +**If warnings are present:** Note limitations in your final report + +### Decision Point + +**If script succeeded:** +→ Proceed to Phase 2 to fill gaps (documentation, manual investigation) + +**If script failed:** +→ Proceed to Phase 2 (Manual Data Gathering) using commands from COMMANDS.md + +--- + +## Phase 2: Data Gathering + +**Goal:** Collect evidence for all 10 evaluation signals efficiently. + +> **Note:** If you skipped Phase 1.5 or the script provided incomplete data, use this phase to manually gather remaining information. If you used the script successfully, use this phase to fill gaps the script couldn't cover (documentation quality, manual investigation, ecosystem trends). + +### General Strategy + +1. **Run commands in parallel where possible** (see Performance Tips below) +2. **Gather at least 2 data points per signal** for evidence-based scoring +3. **Save command outputs** with timestamps for citation in report + +### Data Gathering by Signal + +Refer to [COMMANDS.md](./COMMANDS.md) for specific commands. General approach: + +**1. Maintenance & Activity** +```bash +# Package registry: version history, release dates +npm view time versions + +# GitHub: recent activity +gh api repos/{owner}/{repo} --jq '{pushed_at, open_issues_count}' +gh api repos/{owner}/{repo}/commits --jq '.[0].commit.author.date' +``` + +**2. Security Posture** +```bash +# Ecosystem security tools +npm audit --json # (npm) +# cargo audit # (Rust, requires separate install) +# pip-audit # (Python, requires separate install) + +# GitHub security +gh api repos/{owner}/{repo}/security-advisories +``` + +**3. Community Health** +```bash +# GitHub community metrics +gh api repos/{owner}/{repo}/community/profile --jq '{health_percentage, files}' +gh api repos/{owner}/{repo}/contributors --jq 'length' + +# Issue/PR activity +gh api repos/{owner}/{repo}/issues --jq '[.[] | select(.pull_request == null)] | .[0:5]' +``` + +**4. Documentation Quality** +- Manual review: README, docs site, API reference +- Check for: Migration guides, examples, TypeScript types (for JS) + +**5. Dependency Footprint** +```bash +# View full dependency tree +npm ls --all # npm +cargo tree -p # Rust +go mod graph | grep # Go +``` + +**6. Production Adoption** +- Check weekly downloads on package registry site +- GitHub "Used by" count: https://github/{owner}/{repo}/network/dependents +- Web search: " production" for case studies + +**7. License Compatibility** +```bash +# Package license +npm view license + +# Dependency licenses (if SBOM available) +gh api repos/{owner}/{repo}/dependency-graph/sbom --jq '.sbom.packages[].licenseConcluded' +``` + +**8. API Stability** +- Manual review: CHANGELOG.md, GitHub Releases +- Check for: Semver adherence, breaking change frequency, deprecation policy + +**9. Bus Factor & Funding** +- Check for: GitHub Sponsors, OpenCollective, corporate backing +- Review: Contributor affiliations, organizational support +- Search: " funding" or " sponsor" + +**10. Ecosystem Momentum** +- Research: Ecosystem migration patterns, framework recommendations +- Check: Recent conference mentions, blog posts, technology radar reports + +### Handling Missing Data + +If commands fail or data is unavailable, see [ERROR_HANDLING.md](./ERROR_HANDLING.md) for fallback strategies. + +--- + +## Phase 3: Scoring & Analysis + +**Goal:** Translate gathered data into numerical scores and identify key findings. + +### Scoring Process + +1. **Score each signal 1-5 based on evidence** + - See [SIGNAL_DETAILS.md](./SIGNAL_DETAILS.md) for detailed scoring guidance + - Use ecosystem-relative assessment (compare to ecosystem norms) + - **1/5:** Major red flags, well below ecosystem standards + - **2/5:** Below expectations, concerning patterns + - **3/5:** Acceptable, meets minimum standards + - **4/5:** Good, above average for ecosystem + - **5/5:** Excellent, significantly exceeds norms + +2. **Apply weights based on dependency type** + - See SKILL.md § Scoring Weights table + - **Critical dependencies** (auth, security, data): High weight on Security, Maintenance, Funding + - **Standard dependencies** (utilities, formatting): Balanced weights + - **Dev dependencies** (testing, linting): Lower security weight, higher API stability + +3. **Note critical concerns** + - **If Security or Maintenance ≤ 2:** Flag as significant concern regardless of other scores + - **If any High-weight signal ≤ 2:** Highlight prominently in report + - **Overall weighted score < 25:** Default to EVALUATE FURTHER or AVOID + - **Overall weighted score ≥ 35:** Generally safe to ADOPT (if no blockers) + +4. **Calculate weighted score** + - Multiply each signal score by its weight (H=3, M=2, L=1) + - Sum weighted scores + - Maximum possible: 50 (if all signals 5/5 with high weight) + - Typical good package: 35-45 + +### Analysis Process + +1. **Identify patterns:** + - Are weaknesses clustered (e.g., all community signals low)? + - Do strengths compensate for weaknesses? + - Is there a trajectory (improving vs declining)? + +2. **Consider context:** + - Package purpose (critical vs utility) + - Project scale (enterprise vs startup) + - Team capabilities (can you fork if needed?) + - Risk tolerance + +3. **Weigh trade-offs:** + - Heavy dependencies but excellent maintenance + - Single maintainer but outstanding code quality + - Lower popularity but superior architecture + +4. **Check score interpretation rules:** + - **Blocker override:** Any Critical Red Flag → AVOID regardless of scores + - **Critical thresholds:** Security or Maintenance ≤ 2 → Strongly reconsider + - **Weighting priority:** Security and Maintenance > Documentation or Ecosystem Momentum + +--- + +## Phase 4: Report Generation + +**Goal:** Create clear, actionable evaluation report using standard format. + +### Report Structure + +Use the Output Format template from SKILL.md: + +```markdown +## Dependency Evaluation: + +### Summary +[2-3 sentence assessment with recommendation] + +**Recommendation**: [ADOPT / EVALUATE FURTHER / AVOID] +**Risk Level**: [Low / Medium / High] +**Blockers Found**: [Yes/No] + +### Blockers (if any) +- ⛔ [Specific blocker with evidence] + +### Evaluation Scores +[Score table with evidence] + +### Key Findings +#### Strengths +- [Specific strength with evidence] + +#### Concerns +- [Specific concern with evidence] + +### Alternatives Considered +[If applicable] + +### Recommendation Details +[Detailed reasoning] + +### If You Proceed (for ADOPT/EVALUATE FURTHER) +- [Specific risk mitigation advice] +``` + +### Report Quality Checklist + +Before presenting report, verify: + +- [ ] Cited specific versions and dates for all claims? +- [ ] Ran actual commands rather than making assumptions? +- [ ] All scores supported by evidence in "Evidence" column? +- [ ] If Security or Maintenance ≤ 2, flagged prominently? +- [ ] If any blocker exists, recommendation is AVOID? +- [ ] Provided at least 2 alternatives if recommending AVOID? +- [ ] "If You Proceed" section tailored to specific risks found? +- [ ] Recommendation aligns with weighted score and blocker rules? + +### Writing Recommendations + +**ADOPT:** Clear benefits, low/acceptable risk, minor concerns don't outweigh strengths +- Must have: No blockers, Security & Maintenance ≥ 3, weighted score typically ≥ 35 +- Include: Specific version pinning strategy, monitoring recommendations + +**EVALUATE FURTHER:** Mixed signals, decision depends on user's specific context +- Use when: Trade-offs exist, user priorities matter, some concerning but not blocking issues +- Include: Decision framework, specific questions for user to consider + +**AVOID:** Dealbreaker issues present, risks outweigh benefits +- Must include: Specific reasons why (blockers, critical scores ≤ 2, security concerns) +- Must include: 2+ alternative recommendations with brief comparison + +--- + +## Performance Tips + +### Run Commands in Parallel + +Independent commands can run simultaneously to save time: + +```bash +# Example: Parallel execution +npm view time & +npm view versions & +gh api repos/{owner}/{repo} & +gh api repos/{owner}/{repo}/community/profile & +wait # Wait for all background jobs to complete +``` + +**What to parallelize:** +- Different API endpoints (npm + GitHub) +- Multiple GitHub API calls to different endpoints +- Security scans + dependency tree analysis + +**What NOT to parallelize:** +- Commands that depend on each other +- Avoid excessive parallel GitHub API calls (rate limits) + +### Early Exit on Blockers + +If Critical Red Flags found in Phase 1: +- Skip detailed scoring +- Generate AVOID recommendation immediately +- Focus time on finding good alternatives + +### Save Common Data + +If evaluating multiple packages in same ecosystem: +- Note ecosystem norms once, reference in all evaluations +- Save common baseline data (e.g., typical npm dependency counts) +- Reuse ecosystem-specific guidance + +### Batch Similar Evaluations + +When comparing 3+ alternatives: +1. Gather data for all packages first +2. Score all packages using consistent criteria +3. Generate comparison table +4. Write individual reports referencing comparison + +--- + +## Common Pitfalls to Avoid + +### Don't: + +1. **Rely on download counts alone** + - Bot traffic inflates npm stats + - New packages may be high quality with low downloads + - Old packages may have high downloads but be deprecated + +2. **Dismiss single-maintainer projects automatically** + - Many excellent tools have one dedicated maintainer + - Assess maintainer quality, responsiveness, track record + - Single maintainer with 5-year track record may be lower risk than 10 inactive contributors + +3. **Penalize stable libraries for low commit frequency** + - Low activity may indicate "done" not "abandoned" + - Check if security issues are still addressed + - Cryptography, date libraries, protocols may legitimately need few updates + +4. **Assume high GitHub stars = good quality** + - Stars can be gamed or reflect hype, not quality + - Use stars as one signal among many + - Production adoption more valuable than stars + +5. **Make assumptions without running commands** + - Always gather actual data + - Don't guess about security, dependencies, or maintenance + - If data unavailable, note it explicitly + +6. **Ignore transitive dependencies** + - Security vulnerabilities often in transitive deps + - Unmaintained transitive deps are technical debt + - Always check full dependency tree, not just direct deps + +7. **Apply npm norms to other ecosystems** + - Rust, Go, Python have different cultural expectations + - What's normal for npm may be unusual for Cargo + - Always use ecosystem-relative assessment + +### Do: + +1. **Verify package identity before installing** + - Check for typosquatting (react vs reakt) + - Verify package is the intended one + - Be suspicious of new packages with popular-sounding names + +2. **Check transitive dependencies** + - Run full dependency tree analysis + - Assess maintenance of transitive deps + - Security issues often hide deep in tree + +3. **Consider the user's specific use case** + - CLI tool has different requirements than web library + - Internal tool vs public-facing app affects risk tolerance + - Enterprise vs startup affects acceptable bus factor + +4. **Cite specific versions, dates, and metrics** + - "Last release v2.4.1 on 2025-01-10" not "recently updated" + - "50k weekly downloads" not "popular" + - "CVE-2023-12345 patched in 48 hours" not "good security" + +5. **Provide alternatives when recommending AVOID** + - Always suggest 2+ alternatives + - Briefly compare alternatives + - Help user find a better option + +6. **Run commands rather than assuming** + - Don't guess dependency counts + - Don't assume security based on popularity + - Verify everything with actual data + +--- + +## Workflow Variants + +### Quick Evaluation (< 15 minutes) + +For low-risk dev dependencies or quick checks: +1. Run blocker check only +2. Check maintenance (last release, commit activity) +3. Quick security scan (npm audit) +4. Brief recommendation + +**Use when:** Dev dependency, low criticality, time-constrained + +### Standard Evaluation (30-45 minutes) + +Full 10-signal evaluation as described above. + +**Use when:** Standard dependencies, moderate criticality + +### Thorough Evaluation (1-2 hours) + +Standard evaluation plus: +- Compare 3+ alternatives side-by-side +- Deep-dive into transitive dependencies +- Review issue history and maintainer responses +- Check multiple security databases +- Research production case studies + +**Use when:** Critical dependencies (auth, security, data handling), large investment + +### Comparison Evaluation (Multiple Packages) + +When comparing alternatives: +1. Run Phase 1-2 for all packages in parallel +2. Create comparison matrix with all scores +3. Identify trade-offs between packages +4. Recommend based on user priorities + +--- + +## Summary + +**Key workflow principles:** +1. **Systematic:** Follow phases to ensure thoroughness +2. **Evidence-based:** Always cite specific data +3. **Efficient:** Parallelize where possible, early-exit on blockers +4. **Transparent:** Note limitations, missing data, assumptions +5. **Actionable:** Provide clear recommendations with next steps + +**Remember:** The goal is informed decision-making, not perfect information. Provide best assessment with available data, clearly document limitations, and adjust recommendation confidence accordingly. diff --git a/skills/dependency-evaluator/scripts/dependency_evaluator.py b/skills/dependency-evaluator/scripts/dependency_evaluator.py new file mode 100755 index 0000000..3fa307e --- /dev/null +++ b/skills/dependency-evaluator/scripts/dependency_evaluator.py @@ -0,0 +1,419 @@ +#!/usr/bin/env python3 +""" +Dependency evaluator script for gathering package ecosystem data. +Automates command execution and data collection for dependency analysis. + +Uses only Python standard library - no external dependencies required. +""" + +import argparse +import json +import subprocess +import sys +import urllib.request +import urllib.error +from datetime import datetime +from typing import Dict, List, Any, Optional, Tuple + + +class DependencyEvaluator: + """Main class for evaluating dependencies across package ecosystems.""" + + def __init__(self, package_name: str, ecosystem: str): + """ + Initialize the dependency evaluator. + + Args: + package_name: Name of the package to evaluate + ecosystem: Package ecosystem (npm, pypi, cargo, go) + """ + self.package_name = package_name + self.ecosystem = ecosystem.lower() + self.errors: List[str] = [] + self.warnings: List[str] = [] + + def run_command(self, cmd: List[str], timeout: int = 30) -> Tuple[bool, str, str]: + """ + Execute a shell command and return results. + + Args: + cmd: Command and arguments as list + timeout: Command timeout in seconds + + Returns: + Tuple of (success, stdout, stderr) + """ + try: + result = subprocess.run( + cmd, + capture_output=True, + text=True, + timeout=timeout + ) + return (result.returncode == 0, result.stdout, result.stderr) + except subprocess.TimeoutExpired: + self.warnings.append(f"Command timed out after {timeout}s: {' '.join(cmd)}") + return (False, "", f"Timeout after {timeout}s") + except FileNotFoundError: + self.warnings.append(f"Command not found: {cmd[0]}") + return (False, "", f"Command not found: {cmd[0]}") + except Exception as e: + self.warnings.append(f"Command failed: {' '.join(cmd)} - {str(e)}") + return (False, "", str(e)) + + def fetch_url(self, url: str, timeout: int = 10) -> Optional[Dict[str, Any]]: + """ + Fetch JSON data from a URL. + + Args: + url: URL to fetch + timeout: Request timeout in seconds + + Returns: + Parsed JSON data or None on failure + """ + try: + req = urllib.request.Request(url) + req.add_header('User-Agent', 'dependency-evaluator/1.0') + + with urllib.request.urlopen(req, timeout=timeout) as response: + data = response.read().decode('utf-8') + return json.loads(data) + except urllib.error.HTTPError as e: + if e.code == 404: + self.errors.append(f"Resource not found: {url}") + elif e.code == 403: + self.warnings.append(f"Access forbidden (rate limit?): {url}") + else: + self.warnings.append(f"HTTP {e.code} error fetching {url}") + return None + except urllib.error.URLError as e: + self.warnings.append(f"Network error fetching {url}: {str(e)}") + return None + except json.JSONDecodeError as e: + self.warnings.append(f"Invalid JSON from {url}: {str(e)}") + return None + except Exception as e: + self.warnings.append(f"Error fetching {url}: {str(e)}") + return None + + def gather_npm_data(self) -> Dict[str, Any]: + """Gather data for npm packages.""" + data = {} + + # Get package metadata + success, stdout, stderr = self.run_command(['npm', 'view', self.package_name, '--json']) + if success and stdout: + try: + npm_data = json.loads(stdout) + data['latest_version'] = npm_data.get('version', '') + data['license'] = npm_data.get('license', '') + data['description'] = npm_data.get('description', '') + data['homepage'] = npm_data.get('homepage', '') + data['repository_url'] = npm_data.get('repository', {}).get('url', '') if isinstance(npm_data.get('repository'), dict) else npm_data.get('repository', '') + data['maintainers'] = npm_data.get('maintainers', []) + data['keywords'] = npm_data.get('keywords', []) + except json.JSONDecodeError: + self.warnings.append("Failed to parse npm view output") + + # Get version history + success, stdout, stderr = self.run_command(['npm', 'view', self.package_name, 'time', '--json']) + if success and stdout: + try: + time_data = json.loads(stdout) + data['publish_history'] = time_data + data['versions_count'] = len([k for k in time_data.keys() if k not in ['created', 'modified']]) + except json.JSONDecodeError: + self.warnings.append("Failed to parse npm time output") + + # Get all versions + success, stdout, stderr = self.run_command(['npm', 'view', self.package_name, 'versions', '--json']) + if success and stdout: + try: + versions = json.loads(stdout) + data['all_versions'] = versions if isinstance(versions, list) else [versions] + except json.JSONDecodeError: + self.warnings.append("Failed to parse npm versions output") + + return data + + def gather_pypi_data(self) -> Dict[str, Any]: + """Gather data for PyPI packages.""" + data = {} + + # Use PyPI JSON API + pypi_url = f"https://pypi.org/pypi/{self.package_name}/json" + pypi_data = self.fetch_url(pypi_url) + + if pypi_data: + info = pypi_data.get('info', {}) + data['latest_version'] = info.get('version', '') + data['license'] = info.get('license', '') + data['description'] = info.get('summary', '') + data['homepage'] = info.get('home_page', '') + data['repository_url'] = info.get('project_urls', {}).get('Source', info.get('project_url', '')) + data['author'] = info.get('author', '') + data['keywords'] = info.get('keywords', '').split(',') if info.get('keywords') else [] + + # Get release history + releases = pypi_data.get('releases', {}) + data['versions_count'] = len(releases) + data['publish_history'] = { + version: release_list[0].get('upload_time', '') if release_list else '' + for version, release_list in releases.items() + } + + return data + + def gather_cargo_data(self) -> Dict[str, Any]: + """Gather data for Cargo/Rust crates.""" + data = {} + + # Use crates.io API + crates_url = f"https://crates.io/api/v1/crates/{self.package_name}" + crate_data = self.fetch_url(crates_url) + + if crate_data and 'crate' in crate_data: + crate = crate_data['crate'] + data['latest_version'] = crate.get('max_version', '') + data['license'] = ', '.join(crate.get('license', '').split(' OR ')) + data['description'] = crate.get('description', '') + data['homepage'] = crate.get('homepage', '') + data['repository_url'] = crate.get('repository', '') + data['downloads'] = crate.get('downloads', 0) + data['recent_downloads'] = crate.get('recent_downloads', 0) + + # Get versions + versions_url = f"https://crates.io/api/v1/crates/{self.package_name}/versions" + versions_data = self.fetch_url(versions_url) + if versions_data and 'versions' in versions_data: + data['versions_count'] = len(versions_data['versions']) + data['all_versions'] = [v.get('num', '') for v in versions_data['versions']] + + return data + + def gather_go_data(self) -> Dict[str, Any]: + """Gather data for Go modules.""" + data = {} + + # Try go list command + success, stdout, stderr = self.run_command(['go', 'list', '-m', '-json', self.package_name]) + if success and stdout: + try: + go_data = json.loads(stdout) + data['module_path'] = go_data.get('Path', '') + data['latest_version'] = go_data.get('Version', '') + data['time'] = go_data.get('Time', '') + except json.JSONDecodeError: + self.warnings.append("Failed to parse go list output") + + return data + + def extract_github_repo(self, repo_url: str) -> Optional[Tuple[str, str]]: + """ + Extract owner and repo name from GitHub URL. + + Args: + repo_url: GitHub repository URL + + Returns: + Tuple of (owner, repo) or None + """ + if not repo_url: + return None + + # Handle various GitHub URL formats + import re + patterns = [ + r'github\.com[:/]([^/]+)/([^/\.]+)', + r'github\.com/([^/]+)/([^/\.]+)', + ] + + for pattern in patterns: + match = re.search(pattern, repo_url) + if match: + owner, repo = match.groups() + # Remove .git suffix if present + repo = repo.replace('.git', '') + return (owner, repo) + + return None + + def gather_github_data(self, repo_url: str) -> Dict[str, Any]: + """ + Gather data from GitHub repository. + + Args: + repo_url: GitHub repository URL + + Returns: + Dictionary of GitHub data + """ + data = {} + + github_info = self.extract_github_repo(repo_url) + if not github_info: + self.warnings.append(f"Could not parse GitHub URL: {repo_url}") + return data + + owner, repo = github_info + data['repository_url'] = f"https://github.com/{owner}/{repo}" + + # Try using gh CLI first + success, stdout, stderr = self.run_command(['gh', 'api', f'repos/{owner}/{repo}']) + if success and stdout: + try: + repo_data = json.loads(stdout) + data['pushed_at'] = repo_data.get('pushed_at', '') + data['open_issues_count'] = repo_data.get('open_issues_count', 0) + data['stargazers_count'] = repo_data.get('stargazers_count', 0) + data['forks_count'] = repo_data.get('forks_count', 0) + data['watchers_count'] = repo_data.get('watchers_count', 0) + data['default_branch'] = repo_data.get('default_branch', '') + except json.JSONDecodeError: + self.warnings.append("Failed to parse gh api output") + else: + # Fallback to direct API call + api_url = f"https://api.github.com/repos/{owner}/{repo}" + repo_data = self.fetch_url(api_url) + if repo_data: + data['pushed_at'] = repo_data.get('pushed_at', '') + data['open_issues_count'] = repo_data.get('open_issues_count', 0) + data['stargazers_count'] = repo_data.get('stargazers_count', 0) + data['forks_count'] = repo_data.get('forks_count', 0) + data['watchers_count'] = repo_data.get('watchers_count', 0) + data['default_branch'] = repo_data.get('default_branch', '') + + # Get community health + success, stdout, stderr = self.run_command(['gh', 'api', f'repos/{owner}/{repo}/community/profile']) + if success and stdout: + try: + community_data = json.loads(stdout) + data['community_health'] = { + 'health_percentage': community_data.get('health_percentage', 0), + 'files': community_data.get('files', {}) + } + except json.JSONDecodeError: + pass + + # Get contributors count + success, stdout, stderr = self.run_command(['gh', 'api', f'repos/{owner}/{repo}/contributors', '--jq', 'length']) + if success and stdout.strip().isdigit(): + data['contributors_count'] = int(stdout.strip()) + + # Get license + success, stdout, stderr = self.run_command(['gh', 'api', f'repos/{owner}/{repo}/license', '--jq', '.license.spdx_id']) + if success and stdout.strip(): + data['license_info'] = {'spdx_id': stdout.strip()} + + return data + + def gather_security_data(self) -> Dict[str, Any]: + """Gather security-related data.""" + data = {} + + if self.ecosystem == 'npm': + # Note: npm audit requires package.json, which we don't have in isolation + # This is a limitation - would need to create temp package.json + self.warnings.append("npm audit requires package.json context - skipping") + + return data + + def gather_dependency_footprint(self) -> Dict[str, Any]: + """Gather dependency tree information.""" + data = { + 'direct_dependencies': 0, + 'total_dependencies': 0, + 'tree_depth': 1 + } + + if self.ecosystem == 'npm': + # npm ls requires the package to be installed + self.warnings.append("npm ls requires package installation - skipping") + + return data + + def evaluate(self) -> Dict[str, Any]: + """ + Run the full evaluation and return structured results. + + Returns: + Dictionary containing all gathered data + """ + result = { + 'package': self.package_name, + 'ecosystem': self.ecosystem, + 'timestamp': datetime.utcnow().isoformat() + 'Z', + 'registry_data': {}, + 'github_data': {}, + 'security_data': {}, + 'dependency_footprint': {}, + 'errors': [], + 'warnings': [] + } + + # Gather ecosystem-specific data + if self.ecosystem == 'npm': + result['registry_data'] = self.gather_npm_data() + elif self.ecosystem == 'pypi': + result['registry_data'] = self.gather_pypi_data() + elif self.ecosystem == 'cargo': + result['registry_data'] = self.gather_cargo_data() + elif self.ecosystem == 'go': + result['registry_data'] = self.gather_go_data() + else: + self.errors.append(f"Unsupported ecosystem: {self.ecosystem}") + result['errors'] = self.errors + result['warnings'] = self.warnings + return result + + # Gather GitHub data if repository URL found + repo_url = result['registry_data'].get('repository_url', '') + if repo_url and 'github.com' in repo_url: + result['github_data'] = self.gather_github_data(repo_url) + + # Gather security data + result['security_data'] = self.gather_security_data() + + # Gather dependency footprint + result['dependency_footprint'] = self.gather_dependency_footprint() + + # Add errors and warnings + result['errors'] = self.errors + result['warnings'] = self.warnings + + return result + + +def main(): + """Main entry point for the script.""" + parser = argparse.ArgumentParser( + description='Evaluate a package dependency across different ecosystems' + ) + parser.add_argument( + 'package', + help='Package name to evaluate' + ) + parser.add_argument( + 'ecosystem', + choices=['npm', 'pypi', 'cargo', 'go'], + help='Package ecosystem' + ) + + args = parser.parse_args() + + evaluator = DependencyEvaluator(args.package, args.ecosystem) + result = evaluator.evaluate() + + # Output JSON to stdout + print(json.dumps(result, indent=2)) + + # Exit with non-zero code if there were errors + if result['errors']: + sys.exit(1) + else: + sys.exit(0) + + +if __name__ == '__main__': + main() diff --git a/skills/git-workflow-patterns/SKILL.md b/skills/git-workflow-patterns/SKILL.md new file mode 100644 index 0000000..9a41335 --- /dev/null +++ b/skills/git-workflow-patterns/SKILL.md @@ -0,0 +1,282 @@ +--- +name: git-workflow-patterns +description: Analyzes git history to identify commit patterns, branching habits, workflow inefficiencies, and collaboration opportunities. Use when users mention git workflows, commits, branches, rebasing, merge conflicts, PR strategy, force push, git aliases, or express frustration with git operations. +allowed-tools: + - Read + - Bash + - Grep +--- + +# Git Workflow Patterns Analysis + +This skill analyzes your git history to identify patterns in your workflow and suggest improvements. It learns from your past git behavior to provide personalized recommendations for efficiency, safety, and consistency. + +## How to Use This Skill + +When activated, analyze the user's git history to identify patterns and provide actionable insights. The analysis should be: +- **Personalized**: Based on actual patterns in their git history +- **Actionable**: Include specific commands, aliases, or workflow changes +- **Evidence-based**: Reference actual data from their history +- **Privacy-conscious**: Analyze locally, don't store raw commit messages or sensitive data + +## Analysis Process + +### 1. Gather Git History Data + +Run these commands to collect pattern data: + +```bash +# Get comprehensive commit history +git log --all --pretty=format:"%h|%an|%ae|%ai|%s" --numstat --no-merges + +# Get branch information +git for-each-ref --format='%(refname:short)|%(authorname)|%(authordate:iso8601)|%(upstream:short)' refs/heads/ + +# Get reflog for error recovery patterns +git reflog --pretty=format:"%h|%gd|%gs" -n 500 + +# Get stash list +git stash list + +# Get merge/rebase patterns +git log --all --merges --pretty=format:"%h|%ai|%s" + +# Get remote branch information +git branch -r +``` + +### 2. Identify Key Patterns + +Analyze the data for: + +#### Commit Patterns +- **Message consistency**: Do they follow conventional commits? Consistent format? +- **Commit size**: Average lines changed per commit (small/focused vs. large batches) +- **Commit frequency**: Time between commits (batching behavior) +- **WIP/fixup commits**: Frequency of temporary commits that should be squashed +- **Test commits**: Separate test commits vs. code+test together + +#### Branch Patterns +- **Naming conventions**: Identify different formats used (feature/*, feat/JIRA-*, user/*) +- **Branch lifespan**: Average time from creation to merge +- **Abandoned branches**: Branches created but never merged +- **Branch size**: Average commits per branch +- **Long-lived branches**: Branches with 20+ commits (potential for splitting) + +#### Collaboration Patterns +- **Solo vs. co-authored**: Frequency of pair programming +- **Merge strategy**: Merge commits vs. rebase preference +- **Force push frequency**: How often and to which branches +- **PR patterns**: Can infer from branch merge frequency + +#### Error Recovery Patterns +- **Reflog usage**: Frequent reflog = frequent mistakes/uncertainty +- **Reset/revert**: Hard resets vs. reverts +- **Cherry-pick**: Frequency and context +- **Stash accumulation**: Unretrieved stashes indicate workflow issues + +#### Workflow Efficiency +- **Repeated sequences**: Commands run together frequently (alias opportunities) +- **Manual cleanups**: Patterns suggesting missing automation +- **Conflict patterns**: Files that frequently conflict +- **Context switching**: Branch checkout frequency + +### 3. Generate Report + +Structure the report similarly to the shell history analysis: + +```markdown +## Git Workflow Analysis Summary +[2-3 sentence overview of their git workflow patterns] + +## Commit Patterns +- Total commits analyzed: X +- Average commit size: Y lines +- Commit message format: [detected pattern or inconsistency] +- Most active hours: [time patterns] + +## Top Workflow Patterns +1. [Pattern 1]: Frequency and context +2. [Pattern 2]: Frequency and context +... + +## Improvement Opportunities + +### High Impact +**[Issue 1]**: [Description with evidence] +- **Current state**: [What they do now] +- **Impact**: [Why it's inefficient/risky] +- **Recommendation**: [Specific fix] +- **Implementation**: + ```bash + [Copy-pasteable commands/aliases] + ``` + +### Medium Impact +[Similar structure] + +### Quick Wins +1. [One-liner improvement 1] +2. [One-liner improvement 2] + +## Suggested Git Aliases & Config + +```bash +# Add to ~/.gitconfig + +[alias] + # [Description of what this solves] + alias-name = "command based on their patterns" + + # [Another pattern-based alias] + another-alias = "..." + +[merge] + # [Config to prevent common conflicts they experience] + conflictstyle = diff3 + +[Other recommended configs based on patterns] +``` + +## Workflow Recommendations + +### Branch Strategy +[Recommendations based on their branching patterns] + +### Commit Strategy +[Recommendations based on commit patterns] + +### Safety Improvements +[Recommendations for preventing errors they've made] +``` + +## Common Scenarios & Examples + +### Scenario 1: Rebase Anxiety +**When to activate**: User mentions rebasing, or git history shows reflog activity after rebases + +**What to analyze**: +- Frequency of `git reflog` usage after rebase operations +- Reset/revert patterns following rebases +- Success rate of interactive rebases + +**What to suggest**: +- Backup branch workflow before rebasing +- Git aliases for safe rebasing +- Alternative strategies if rebasing causes consistent issues + +### Scenario 2: Large PRs / Long-Lived Branches +**When to activate**: User is working on a branch with 20+ commits + +**What to analyze**: +- Historical PR sizes and review times +- Correlation between PR size and merge time +- Natural logical split points in commit history + +**What to suggest**: +- Breaking into smaller PRs +- Stacked PR workflow +- Commit organization strategies + +### Scenario 3: Inconsistent Commit Messages +**When to activate**: User commits code, or asks about git best practices + +**What to analyze**: +- Commit message formats used +- Consistency over time +- Team patterns (if multiple authors) + +**What to suggest**: +- Conventional commits format +- Commit message templates +- Git hooks for enforcement + +### Scenario 4: Merge Conflict Patterns +**When to activate**: User mentions merge conflicts or is resolving conflicts + +**What to analyze**: +- Which files conflict most frequently +- Common conflict types (dependency files, migrations, etc.) +- Their typical resolution strategy + +**What to suggest**: +- Merge strategies for specific file types +- Git configuration to auto-resolve certain conflicts +- Workflow changes to reduce conflict frequency + +### Scenario 5: Stash Hoarding +**When to activate**: User says "I had some changes but lost them" or has many stashes + +**What to analyze**: +- Number of stashes +- How often stashes are applied vs. abandoned +- Time stashes remain unapplied + +**What to suggest**: +- Using WIP branches instead of stashes +- Stash cleanup workflow +- Better branch management + +### Scenario 6: Force Push Safety +**When to activate**: User is about to force push or mentions force pushing + +**What to analyze**: +- Frequency of force pushes +- Branches force-pushed to (solo vs. shared) +- Historical issues caused by force pushes + +**What to suggest**: +- `--force-with-lease` instead of `--force` +- Git aliases with safety checks +- Team communication protocols + +## Guidelines + +### Be Specific and Evidence-Based +- Always reference actual data: "You've created 23 branches in the last month" +- Show frequency: "This happens in 73% of your commits" +- Compare to best practices with context, not judgment + +### Prioritize by Impact +- Focus on patterns that waste the most time +- Address safety issues (force pushes to shared branches) with urgency +- Quick wins first, then deeper workflow changes + +### Provide Working Solutions +- All suggestions should include copy-pasteable commands +- Test that aliases and configs are syntactically correct +- Include both short-term fixes and long-term improvements + +### Respect Privacy +- Never include actual commit messages in analysis (just patterns) +- Don't reference specific code changes +- Focus on workflow metadata, not content +- Analyze locally, don't send git history to external services + +### Encourage and Highlight Strengths +- Note good patterns: "Your commit sizes are consistently small and focused" +- Frame suggestions as optimization, not criticism +- Acknowledge learning curve for git complexity + +## Technical Notes + +### Performance Considerations +- Limit history analysis to last 500-1000 commits for initial analysis +- Cache pattern data to avoid re-analyzing on every activation +- Use `--no-merges` and `--no-walk` flags appropriately to reduce data + +### Error Handling +- Check if in a git repository before running commands +- Handle repositories with no commits gracefully +- Account for repositories with unconventional setups (multiple remotes, submodules) + +### Integration with Shell History Analysis +When both skills are available, cross-reference: +- Shell history shows git commands run frequently +- Git patterns show the results of those commands +- Combined insights reveal automation opportunities + +Example: +- Shell: `git add . && git commit -m "..." && git push` (typed 200x) +- Git: Commits average 3 files, 50 lines, always pushed immediately +- Combined insight: Create single alias for the entire workflow diff --git a/skills/workflow-analyzer/SKILL.md b/skills/workflow-analyzer/SKILL.md new file mode 100644 index 0000000..7f2a766 --- /dev/null +++ b/skills/workflow-analyzer/SKILL.md @@ -0,0 +1,137 @@ +--- +name: workflow-analyzer +description: Analyzes Claude Code session history to identify repeated workflows and suggest slash commands to automate them +invocation: Ask Claude to "analyze my workflows" or "find repeated patterns in my Claude Code usage" +--- + +# Workflow Analyzer Skill + +## Purpose + +This skill analyzes your Claude Code usage patterns by examining session transcripts to identify workflows you repeat frequently. It suggests specific slash commands you could create to automate these patterns, complete with time savings estimates and implementation priorities. + +## When to Use + +Use this skill when you want to: +- Identify repeated workflows in your Claude Code sessions +- Discover automation opportunities +- Get specific recommendations for slash commands to create +- Understand your development patterns and time investment +- Optimize your Claude Code workflow efficiency + +## How It Works + +This skill includes a pre-built Python analysis script that: +1. Parses session JSONL files from `~/.claude/projects/*/` +2. Identifies repeated patterns in user requests across sessions +3. Detects common workflows (git operations, documentation updates, testing cycles, etc.) +4. Generates a comprehensive report with automation recommendations + +## Parameters + +- **days** (optional): Number of days to analyze, defaults to 30 + - Examples: "analyze my workflows from the last 7 days", "analyze my workflows from the last 60 days" + +## Analysis Criteria + +The skill considers a pattern significant if it: +- Appears 3+ times in the analyzed period +- Has consistent structure across occurrences +- Represents meaningful time investment +- Could be automated as a single slash command + +## Patterns Detected + +The skill identifies these common workflow patterns: + +1. **Git workflows**: add/commit/push sequences, branch operations, PR creation +2. **Version/publish sequences**: version bumps, plugin/marketplace updates, releases +3. **Documentation updates**: README changes, consistency checks, sync operations +4. **Implementation cycles**: plan → build → test patterns, phase-based development +5. **Test/fix cycles**: test execution, error fixing, validation loops + +## Usage Instructions + +When the user requests workflow analysis: + +1. **Calculate date range**: + - Use the `days` parameter if provided, otherwise default to 30 + - Calculate cutoff timestamp: `date -v-{days}d +%s` (macOS) or `date -d "{days} days ago" +%s` (Linux) + +2. **Locate session files**: + ```bash + find ~/.claude/projects -name "*.jsonl" -type f -mtime -{days} 2>/dev/null + ``` + +3. **Run analysis and generate report**: + ```bash + find ~/.claude/projects -name "*.jsonl" -type f -mtime -{days} 2>/dev/null | \ + python3 /scripts/workflow_analyzer.py + ``` + +4. **Present findings**: + - Display the complete markdown report to the user + - Highlight top 3 automation opportunities + - Include specific time savings estimates + - Provide concrete next steps + +## Report Deliverables + +The generated report includes: + +### Analysis Summary +- Time period analyzed (date range) +- Number of sessions reviewed +- Number of user prompts examined +- Total patterns detected + +### High-Priority Patterns (ranked by impact) +For each pattern: +- Pattern name and description +- Frequency of occurrence +- Example user request sequences (actual prompts from sessions) +- Suggested command name (verb-noun format) +- Estimated time per occurrence and total time spent +- Potential time savings with automation + +### Project-Specific Insights +- Which projects show the most repeated workflows +- Project-specific automation opportunities +- Activity distribution across projects + +### Recommendations +- Which commands to create first (ranked by ROI) +- Estimated time savings for top suggestions +- Implementation complexity assessment +- Next steps for the user + +## Privacy + +- All analysis is performed **locally only** +- No data is sent to external services +- Session transcripts never leave the user's machine +- All processing happens in-memory with no temporary files created + +## Success Criteria + +This skill is successful if it: +- Accurately identifies patterns the user actually repeats +- Provides specific, actionable automation suggestions +- Shows clear time savings estimates +- Presents findings in a scannable, useful format +- Completes in reasonable time (< 2 minutes for 30 days of data) + +## Example Invocations + +- "Analyze my workflows" +- "What workflows am I repeating in Claude Code?" +- "Analyze my workflows from the last 60 days" +- "Find automation opportunities in my Claude Code usage" +- "Show me what I'm doing repeatedly" + +## Notes + +- The skill focuses on user prompts, not system messages or command outputs +- Patterns must appear 3+ times to be considered significant +- Time estimates are based on typical workflow execution times +- Suggested command names follow verb-noun convention (e.g., `/ship-git`, `/publish-plugin`) diff --git a/skills/workflow-analyzer/scripts/workflow_analyzer.py b/skills/workflow-analyzer/scripts/workflow_analyzer.py new file mode 100644 index 0000000..81602c1 --- /dev/null +++ b/skills/workflow-analyzer/scripts/workflow_analyzer.py @@ -0,0 +1,459 @@ +#!/usr/bin/env python3 +""" +Unified workflow analyzer for Claude Code session history. +Parses JSONL session files, identifies repeated workflow patterns, +and generates a comprehensive markdown report with automation recommendations. +""" + +import json +import sys +from pathlib import Path + + +def analyze_sessions(session_files): + """ + Analyze session files and extract workflow patterns. + + Args: + session_files: List of session file paths + + Returns: + Dictionary containing analysis results + """ + all_prompts = [] + sessions_data = [] + + # Process each session + for session_file in session_files: + try: + project_name = Path(session_file).parent.name + session_id = Path(session_file).stem + prompts = [] + + with open(session_file, 'r') as f: + for line in f: + try: + data = json.loads(line.strip()) + + if data.get('type') == 'user': + msg = data.get('message', {}) + if msg.get('role') == 'user' and not data.get('isMeta', False): + content = msg.get('content', '') + + # Skip meta messages and command outputs + if isinstance(content, str): + if not content.startswith(' 20: + prompts.append(content) + all_prompts.append({ + 'text': content, + 'lower': content.lower(), + 'project': project_name, + 'session': session_id + }) + except (json.JSONDecodeError, KeyError): + continue + + if prompts: + sessions_data.append({ + 'project': project_name, + 'session': session_id, + 'prompts': prompts, + 'count': len(prompts) + }) + + except Exception: + continue + + # Detect patterns with examples + patterns_found = {} + + # 1. Git commit + push workflow + git_patterns = [] + for session in sessions_data: + combined = ' '.join([p.lower() for p in session['prompts']]) + has_commit = 'commit' in combined or 'committed' in combined + has_push = 'push' in combined + + if (has_commit and has_push) or (combined.count('git') >= 2): + git_patterns.append({ + 'session': session['session'], + 'project': session['project'], + 'prompts': session['prompts'][:5] + }) + + patterns_found['git_commit_push'] = { + 'count': len(git_patterns), + 'examples': git_patterns[:5] + } + + # 2. Version bump + publish workflow + version_patterns = [] + for session in sessions_data: + combined = ' '.join([p.lower() for p in session['prompts']]) + has_version = 'version' in combined or 'bump' in combined + has_publish = 'publish' in combined or 'release' in combined or 'update' in combined + has_plugin = 'plugin' in combined or 'marketplace' in combined + + if (has_version and has_publish) or (has_plugin and (has_version or has_publish)): + version_patterns.append({ + 'session': session['session'], + 'project': session['project'], + 'prompts': session['prompts'][:5] + }) + + patterns_found['version_publish'] = { + 'count': len(version_patterns), + 'examples': version_patterns[:5] + } + + # 3. Documentation/README updates + doc_patterns = [] + for session in sessions_data: + combined = ' '.join([p.lower() for p in session['prompts']]) + if 'readme' in combined or 'documentation' in combined or ('doc' in combined and ('update' in combined or 'write' in combined)): + doc_patterns.append({ + 'session': session['session'], + 'project': session['project'], + 'prompts': session['prompts'][:5] + }) + + patterns_found['documentation_updates'] = { + 'count': len(doc_patterns), + 'examples': doc_patterns[:5] + } + + # 4. Test/fix cycles + test_fix_patterns = [] + for session in sessions_data: + combined = ' '.join([p.lower() for p in session['prompts']]) + has_test = 'test' in combined or 'testing' in combined + has_fix = 'fix' in combined or 'error' in combined or 'bug' in combined + + if has_test and has_fix: + test_fix_patterns.append({ + 'session': session['session'], + 'project': session['project'], + 'prompts': session['prompts'][:5] + }) + + patterns_found['test_fix_cycles'] = { + 'count': len(test_fix_patterns), + 'examples': test_fix_patterns[:5] + } + + # 5. Implementation workflow + implementation_patterns = [] + for session in sessions_data: + combined = ' '.join([p.lower() for p in session['prompts']]) + has_impl = 'implement' in combined or 'implementation' in combined or 'build' in combined + + if (has_impl or (session['count'] >= 5 and ('add' in combined or 'create' in combined))): + implementation_patterns.append({ + 'session': session['session'], + 'project': session['project'], + 'prompts': session['prompts'][:5] + }) + + patterns_found['implementation_workflows'] = { + 'count': len(implementation_patterns), + 'examples': implementation_patterns[:5] + } + + # Build project activity summary + project_activity = {} + for session in sessions_data: + project = session['project'] + project_activity[project] = project_activity.get(project, 0) + 1 + + return { + 'summary': { + 'total_sessions_analyzed': len(session_files), + 'sessions_with_user_prompts': len(sessions_data), + 'total_user_prompts': len(all_prompts), + 'date_range': 'Last 30 days' + }, + 'project_activity': project_activity, + 'patterns': patterns_found + } + + +def generate_report(analysis_data): + """ + Generate a comprehensive markdown report from analysis data. + + Args: + analysis_data: Dictionary containing analysis results + + Returns: + Formatted markdown report string + """ + summary = analysis_data['summary'] + patterns = analysis_data['patterns'] + projects = analysis_data['project_activity'] + + report = f"""# Claude Code Workflow Analysis Report + +## Analysis Summary + +**Period Analyzed:** {summary['date_range']} +**Sessions Reviewed:** {summary['sessions_with_user_prompts']} sessions with user activity (from {summary['total_sessions_analyzed']} total) +**User Prompts Examined:** {summary['total_user_prompts']} prompts +**Patterns Detected:** 5 high-value automation opportunities + +--- + +## High-Priority Patterns + +### 1. Plugin/Marketplace Publish Workflow +**Frequency:** {patterns['version_publish']['count']} occurrences +**Estimated Time per Occurrence:** 10-15 minutes +**Total Time Spent:** ~{patterns['version_publish']['count'] * 12.5 / 60:.1f} hours +**Potential Savings:** 8-10 minutes per run (automated sequence) + +**What you do:** +""" + + # Add version publish examples + if patterns['version_publish']['examples']: + example = patterns['version_publish']['examples'][0] + report += f"\n*Example from {example['project'].replace('-Users-ant-code-', '')}:*\n" + for i, prompt in enumerate(example['prompts'][:3], 1): + preview = prompt[:120].replace('\n', ' ') + report += f"{i}. \"{preview}...\"\n" + + report += f""" +**Suggested Command:** `/publish-plugin [version]` + +**What it automates:** +1. Update version in plugin.json and marketplace.json +2. Update README with version notes +3. Run any validation/tests +4. Git add, commit with conventional message +5. Git push +6. Optionally create GitHub release + +**Time savings:** ~10 min/occurrence = **{patterns['version_publish']['count'] * 10 / 60:.1f} hours saved over 30 days** + +--- + +### 2. Git Commit + Push Workflow +**Frequency:** {patterns['git_commit_push']['count']} occurrences +**Estimated Time per Occurrence:** 5-8 minutes +**Total Time Spent:** ~{patterns['git_commit_push']['count'] * 6.5 / 60:.1f} hours +**Potential Savings:** 3-5 minutes per run + +**What you do:** +- Review changes with git status/diff +- Stage files selectively +- Write commit message +- Push to remote +- Often involves back-and-forth about commit message format + +**Suggested Command:** `/ship-git [message]` + +**What it automates:** +1. Run git status and git diff for review +2. Stage all changes (or prompt for selection) +3. Create commit with your preferred format +4. Push to current branch +5. Show summary of what was shipped + +**Time savings:** ~4 min/occurrence = **{patterns['git_commit_push']['count'] * 4 / 60:.1f} hours saved over 30 days** + +--- + +### 3. Documentation Updates +**Frequency:** {patterns['documentation_updates']['count']} occurrences +**Estimated Time per Occurrence:** 8-12 minutes +**Total Time Spent:** ~{patterns['documentation_updates']['count'] * 10 / 60:.1f} hours +**Potential Savings:** 5-8 minutes per run + +**What you do:** +- Update README files after feature changes +- Keep plugin docs in sync with marketplace.json +- Review and refine documentation formatting +- Ensure consistency across multiple README files + +**Suggested Command:** `/sync-docs` + +**What it automates:** +1. Check for version mismatches between files +2. Update README files with latest plugin metadata +3. Validate documentation structure +4. Check for broken links or references +5. Ensure consistent formatting +6. Optionally commit documentation changes + +**Time savings:** ~6 min/occurrence = **{patterns['documentation_updates']['count'] * 6 / 60:.1f} hours saved over 30 days** + +--- + +### 4. Implementation Workflows (Plan → Build → Test) +**Frequency:** {patterns['implementation_workflows']['count']} occurrences +**Estimated Time per Occurrence:** 20-45 minutes +**Total Time Spent:** ~{patterns['implementation_workflows']['count'] * 32.5 / 60:.1f} hours +**Potential Savings:** 5-10 minutes per run (setup/teardown phases) + +**What you do:** +""" + + if patterns['implementation_workflows']['examples']: + example = patterns['implementation_workflows']['examples'][0] + report += f"\n*Example from {example['project'].replace('-Users-ant-code-', '')}:*\n" + for i, prompt in enumerate(example['prompts'][:2], 1): + preview = prompt[:120].replace('\n', ' ') + report += f"{i}. \"{preview}...\"\n" + + report += f""" +**Suggested Command:** `/do-phase [phase-name]` + +**What it automates:** +- Common development phase transitions +- Reads @PLAN.md or similar planning documents +- Sets up context for each phase +- Runs phase-specific validations +- Updates progress tracking + +**Example usage:** +- `/do-phase planning` - Review requirements, create/update PLAN.md +- `/do-phase implementation` - Load plan, track progress, implement features +- `/do-phase review` - Run tests, check quality, prepare for commit + +**Time savings:** ~7 min/occurrence = **{patterns['implementation_workflows']['count'] * 7 / 60:.1f} hours saved over 30 days** + +--- + +## Medium-Priority Patterns + +### 5. Test + Fix Cycles +**Frequency:** {patterns['test_fix_cycles']['count']} occurrences +**Suggested Command:** `/test-and-fix` + +**What it automates:** +1. Run test suite +2. Analyze failures +3. Fix identified issues +4. Re-run tests +5. Report results + +**Time savings:** ~3 min/occurrence = **{patterns['test_fix_cycles']['count'] * 3 / 60:.1f} hours saved over 30 days** + +--- + +## Project-Specific Insights + +**Most Active Projects:** +""" + + # Sort projects by activity + sorted_projects = sorted(projects.items(), key=lambda x: x[1], reverse=True) + total_sessions = sum(projects.values()) + for project, session_count in sorted_projects[:5]: + clean_name = project.replace('-Users-ant-code-', '').replace('-Users-ant-', '') + percentage = (session_count / total_sessions * 100) if total_sessions > 0 else 0 + report += f"- **{clean_name}**: {session_count} sessions ({percentage:.0f}% of activity)\n" + + most_active_project = sorted_projects[0] if sorted_projects else ('unknown', 0) + + report += f""" +**Key Observation:** Your workflow patterns suggest you'd benefit from **project-aware commands** that adapt to context. + +**Pattern:** You frequently work on: +1. Plugin/skill development +2. Application development ({most_active_project[0].replace('-Users-ant-code-', '')} is your most active project) +3. Testing/setup tooling + +--- + +## Recommendations + +### Commands to Create First (Ranked by Impact) + +1. **`/publish-plugin`** - Highest time savings, very repetitive workflow + - Priority: **HIGHEST** + - Complexity: Medium + - ROI: Excellent + +2. **`/ship-git`** - Second highest savings, used across all projects + - Priority: **HIGH** + - Complexity: Low + - ROI: Excellent + +3. **`/sync-docs`** - High savings, prevents consistency errors + - Priority: **HIGH** + - Complexity: Medium + - ROI: Very Good + +4. **`/do-phase`** - Good savings, improves workflow structure + - Priority: **MEDIUM-HIGH** + - Complexity: Medium-High + - ROI: Good + +5. **`/test-and-fix`** - Moderate savings, good for iteration speed + - Priority: **MEDIUM** + - Complexity: Medium + - ROI: Good + +### Estimated Total Time Savings + +**If you implement the top 3 commands:** ~{(patterns['version_publish']['count'] * 10 + patterns['git_commit_push']['count'] * 4 + patterns['documentation_updates']['count'] * 6) / 60:.1f} hours saved per month +**If you implement all 5 commands:** ~{(patterns['version_publish']['count'] * 10 + patterns['git_commit_push']['count'] * 4 + patterns['documentation_updates']['count'] * 6 + patterns['implementation_workflows']['count'] * 7 + patterns['test_fix_cycles']['count'] * 3) / 60:.1f} hours saved per month + +### Next Steps + +1. **Start with `/ship-git`** - Lowest complexity, immediate benefit, used everywhere +2. **Add `/publish-plugin`** - Highest savings for your current focus area +3. **Create `/sync-docs`** - Prevents documentation drift in marketplace work +4. Consider project-specific variants that detect current project context + +### User Preference Observations + +Based on your workflow patterns: +- ✓ You prefer structured, multi-step workflows +- ✓ You work with @PLAN.md and reference files frequently +- ✓ You iterate on naming and documentation carefully +- ✓ You value consistency across plugin/marketplace files +- ✓ Git commit messages appear to use conventional format + +**Commands should:** +- Support reading from @-referenced files (like @PLAN.md) +- Provide clear progress tracking +- Allow refinement/iteration before final execution +- Maintain file consistency as a primary goal +- Use your preferred commit message conventions + +--- + +## Appendix: Analysis Metadata + +**Sessions Analyzed:** {summary['total_sessions_analyzed']} +**Sessions with User Activity:** {summary['sessions_with_user_prompts']} +**User Prompts Parsed:** {summary['total_user_prompts']} +**Pattern Detection Method:** Keyword analysis + session structure analysis +**Privacy:** All analysis performed locally, no data sent externally +""" + + return report + + +def main(): + """ + Main entry point for the workflow analyzer. + Reads session file paths from stdin, analyzes patterns, and generates report. + """ + # Read session files from stdin + session_files = [line.strip() for line in sys.stdin if line.strip()] + + # Analyze sessions to extract patterns + analysis_results = analyze_sessions(session_files) + + # Generate markdown report from analysis + report = generate_report(analysis_results) + + # Output final report to stdout + print(report) + + +if __name__ == '__main__': + main()