project-analyzer

**References (archive):** [SCAFFOLD_SKILLS_ARCHIVE_MAP.md](../../docs/SCAFFOLD_SKILLS_ARCHIVE_MAP.md) — ProjectAnalyzer monorepo/service detection from Auto-Claude-develop analysis/analyzers. <identity> Project Analyzer - Automated brownfield codebase analysis for rapid project onboarding and understanding. </identity> <capabilities> - Detecting project type (frontend, backend, fullstack, library, cli, mobile, monorepo) - Identifying frameworks and libraries from manifests and structure - Generating file statistics and language breakdown - Mapping component relationships and module structure - Detecting architecture patterns (MVC, layered, microservices, etc.) - Analyzing dependency health and outdated packages - Identifying code quality indicators (linting, testing, type safety) - Detecting technical debt and anti-patterns - Generating prioritized improvement recommendations </capabilities> <instructions> <execution_process> ### Step 1: Identify Project Root Locate project root by finding manifest files: 1. **Search for package manager files**: - `package.json` (Node.js/JavaScript/TypeScript) - `requirements.txt`, `pyproject.toml`, `setup.py` (Python) - `go.mod` (Go) - `Cargo.toml` (Rust) - `pom.xml`, `build.gradle` (Java/Maven/Gradle) - `composer.json` (PHP) 2. **Identify project root**: - Directory containing primary package manager file - Handle monorepos (multiple package.json files) - Detect workspace configuration 3. **Validate project root**: - Check for `.git` directory - Verify source code directories exist - Ensure manifest files are parsable ### Step 2: Detect Project Type Classify project based on manifest files and directory structure: 1. **Frontend Projects**: - Indicators: React, Vue, Angular, Svelte dependencies - Directory: `src/components/`, `public/`, `assets/` - Frameworks: Next.js, Nuxt.js, Gatsby, Vite 2. **Backend Projects**: - Indicators: Express, FastAPI, Django, Flask, Gin dependencies - Directory: `routes/`, `controllers/`, `models/`, `api/` - Frameworks: Next.js API routes, FastAPI, Express 3. **Fullstack Projects**: - Indicators: Both frontend and backend frameworks - Directory: Combined frontend + backend structure - Frameworks: Next.js, Remix, SvelteKit, Nuxt.js 4. **Library/Package Projects**: - Indicators: No application-specific directories - Files: `index.ts`, `lib/`, `dist/`, `build/` - Manifests: `library` field in package.json 5. **CLI Projects**: - Indicators: `bin` field in package.json - Files: CLI entry points, command parsers - Dependencies: Commander, Yargs, Inquirer 6. **Mobile Projects**: - Indicators: React Native, Flutter, Ionic dependencies - Files: `android/`, `ios/`, `mobile/` - Frameworks: React Native, Expo, Flutter 7. **Monorepo Projects**: - Indicators: `workspaces` in package.json, `pnpm-workspace.yaml` - Structure: Multiple packages in subdirectories - Tools: Turborepo, Nx, Lerna 8. **Microservices Projects**: - Indicators: Multiple service directories - Files: `docker-compose.yml`, service configs - Structure: Service-based organization ### Step 3: Framework Detection Identify frameworks from manifest files and imports: 1. **Read package.json dependencies** (Node.js): - Parse `dependencies` and `devDependencies` - Detect framework versions - Categorize by type (framework, ui-library, testing, etc.) 2. **Read requirements.txt** (Python): - Parse Python dependencies - Detect FastAPI, Django, Flask - Identify version constraints 3. **Analyze imports** (optional deep scan): - Scan source files for import statements - Detect used vs declared dependencies - Identify framework-specific patterns 4. **Framework Categories**: - **Framework**: React, Next.js, FastAPI, Express - **UI Library**: Material-UI, Ant Design, Chakra UI - **State Management**: Redux, Zustand, Pinia - **Testing**: Jest, Vitest, Cypress, Playwright - **Build Tool**: Vite, Webpack, Rollup, esbuild - **Database**: Prisma, TypeORM, SQLAlchemy - **ORM**: Prisma, Sequelize, Mongoose - **API**: tRPC, GraphQL, REST - **Auth**: NextAuth, Auth0, Clerk - **Logging**: Winston, Pino, Bunyan - **Monitoring**: Sentry, Datadog, New Relic 5. **Confidence Scoring**: - **1.0**: Framework listed in dependencies - **0.8**: Framework detected from imports - **0.6**: Framework inferred from structure ### Step 4: File Statistics Generate quantitative project statistics: 1. **Count files by type**: - Use glob patterns for common extensions - Exclude: `node_modules/`, `.git/`, `dist/`, `build/` - Group by language/file type 2. **Count lines of code**: - Read source files and count lines - Exclude empty lines and comments (optional) - Calculate total LOC per language 3. **Identify largest files**: - Track file sizes (line count) - Report top 10 largest files - Flag files > 1000 lines (violates micro-service principle) 4. **Calculate averages**: - Average file size (lines) - Average directory depth - Files per directory 5. **Language Detection**: - Map extensions to languages: - `.ts`, `.tsx` → TypeScript - `.js`, `.jsx` → JavaScript - `.py` → Python - `.go` → Go - `.rs` → Rust - `.java` → Java - `.md` → Markdown - `.json` → JSON - `.yaml`, `.yml` → YAML ### Step 5: Structure Analysis Analyze project structure and architecture: 1. **Identify root directories**: - Classify directories by purpose: - **source**: `src/`, `app/`, `lib/` - **tests**: `test/`, `__tests__/`, `cypress/` - **config**: `config/`, `.config/` - **docs**: `docs/`, `documentation/` - **build**: `dist/`, `build/`, `out/` - **scripts**: `scripts/`, `bin/` - **assets**: `assets/`, `static/`, `public/` 2. **Detect entry points**: - Main entry: `index.ts`, `main.py`, `app.py` - App entry: `app.ts`, `server.ts`, `app/page.tsx` - Handler: `handler.ts`, `lambda.ts` - CLI: `cli.ts`, `bin/` 3. **Detect architecture pattern**: - **MVC**: `models/`, `views/`, `controllers/` - **Layered**: `presentation/`, `business/`, `data/` - **Hexagonal**: `domain/`, `application/`, `infrastructure/` - **Microservices**: Multiple service directories - **Modular**: Feature-based organization - **Flat**: All files in src/ 4. **Detect module system**: - Check `package.json` for `"type": "module"` (ESM) - Scan for `import`/`export` (ESM) vs `require` (CommonJS) - Identify mixed module systems ### Step 6: Dependency Analysis Analyze dependency health: 1. **Count dependencies**: - Production dependencies - Development dependencies - Total dependency count 2. **Check for outdated packages** (optional): - Run `npm outdated` or equivalent - Parse output for outdated packages - Identify major version updates (breaking changes) 3. **Security scan** (optional): - Run `npm audit` or equivalent - Identify vulnerabilities by severity - Flag critical security issues ### Step 7: Code Quality Indicators Detect code quality tooling: 1. **Linting Configuration**: - Detect: `.eslintrc.json`, `eslint.config.js`, `ruff.toml` - Tool: ESLint, Ruff, Flake8, Pylint - Run linter if configured (optional) 2. **Formatting Configuration**: - Detect: `.prettierrc`, `pyproject.toml` (Black/Ruff) - Tool: Prettier, Black, Ruff 3. **Testing Framework**: - Detect: Jest, Vitest, Pytest, Cypress - Count test files - Check for coverage configuration 4. **Type Safety**: - Detect TypeScript: `tsconfig.json` - Check strict mode: `"strict": true` - Detect Python typing: mypy, pyright ### Step 8: Pattern Detection Identify common patterns and anti-patterns: 1. **Good Practices**: - Modular component structure - Comprehensive test coverage - TypeScript strict mode enabled - CI/CD configuration present 2. **Anti-Patterns**: - Large files (> 1000 lines) - Missing tests - Outdated dependencies - No linting configuration 3. **Neutral Patterns**: - Specific architecture choices - Framework-specific patterns ### Step 9: Technical Debt Analysis Calculate technical debt score: 1. **Debt Indicators**: - **Outdated Dependencies**: Count outdated packages - **Missing Tests**: Low test file ratio - **Dead Code**: Unused imports/exports (optional) - **Complexity**: Large files, deep nesting - **Documentation**: Missing README, docs - **Security**: Known vulnerabilities - **Performance**: Bundle size, load time 2. **Debt Score** (0-100): - 0-20: Excellent health - 21-40: Good health, minor issues - 41-60: Moderate debt, needs attention - 61-80: High debt, refactoring recommended - 81-100: Critical debt, major overhaul needed 3. **Remediation Effort**: - **Trivial**: < 1 hour - **Minor**: 1-4 hours - **Moderate**: 1-3 days - **Major**: 1-2 weeks - **Massive**: > 2 weeks ### Step 10: Generate Recommendations Create prioritized improvement recommendations: 1. **Categorize Recommendations**: - **Security**: Critical vulnerabilities, outdated auth - **Performance**: Bundle optimization, lazy loading - **Maintainability**: Refactor large files, add tests - **Testing**: Increase coverage, add E2E tests - **Documentation**: Add README, API docs - **Architecture**: Improve modularity, separation of concerns - **Dependencies**: Update packages, remove unused 2. **Prioritize by Impact**: - **P0**: Critical security, blocking production - **P1**: High impact, affects reliability - **P2**: Medium impact, improves quality - **P3**: Low impact, nice-to-have 3. **Estimate Effort and Impact**: - Effort: trivial, minor, moderate, major, massive - Impact: low, medium, high, critical ### Step 11: Validate Output Validate analysis output against schema: 1. **Schema Validation**: - Validate against `project-analysis.schema.json` - Ensure all required fields present - Check data types and formats 2. **Output Metadata**: - Analyzer version - Analysis duration (ms) - Files analyzed count - Files skipped count - Errors encountered </execution_process> <performance> **Performance Requirements**: - **Target**: < 30 seconds for typical projects (< 10k files) - **Optimization**: - Skip large directories: `node_modules/`, `.git/`, `dist/` - Use parallel file processing - Cache results for incremental analysis - Limit deep scans to essential files - Use streaming for large file counts </performance> <integration> **Integration with Conductor**: - Provides automated project discovery - Eliminates manual context gathering - Enables 80% faster brownfield onboarding - Feeds project context to chat interface **Integration with Other Skills**: - **rule-selector**: Auto-select rules based on detected frameworks - **repo-rag**: Semantic search for architectural patterns - **dependency-analyzer**: Deep dependency analysis </integration> <best_practices> 1. **Progressive Disclosure**: Start with manifest analysis, add deep scans if needed 2. **Performance First**: Skip expensive operations for large projects 3. **Fail Gracefully**: Handle missing files, parse errors 4. **Validate Output**: Always validate against schema 5. **Cache Results**: Store analysis output for reuse 6. **Incremental Updates**: Re-analyze only changed files </best_practices> </instructions> <examples> <usage_example> **Programmatic Usage**: ```bash # Analyze current project node .claude/tools/analysis/project-analyzer/analyzer.mjs # Analyze specific directory node .claude/tools/analysis/project-analyzer/analyzer.mjs /path/to/project # Output to file node .claude/tools/analysis/project-analyzer/analyzer.mjs --output .claude/context/artifacts/project-analysis.json ``` **Agent Invocation**: ``` # Analyze current project Analyze this project # Generate comprehensive analysis Perform full project analysis and save to artifacts # Quick analysis (manifest only) Quick project type detection