project-analyzer

References (archive): 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:

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)
Identify project root:
- Directory containing primary package manager file
- Handle monorepos (multiple package.json files)
- Detect workspace configuration
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:

Frontend Projects:
- Indicators: React, Vue, Angular, Svelte dependencies
- Directory:
```
src/components/
```
  ,
```
public/
```
  ,
```
assets/
```
- Frameworks: Next.js, Nuxt.js, Gatsby, Vite
Backend Projects:
- Indicators: Express, FastAPI, Django, Flask, Gin dependencies
- Directory:
```
routes/
```
  ,
```
controllers/
```
  ,
```
models/
```
  ,
```
api/
```
- Frameworks: Next.js API routes, FastAPI, Express
Fullstack Projects:
- Indicators: Both frontend and backend frameworks
- Directory: Combined frontend + backend structure
- Frameworks: Next.js, Remix, SvelteKit, Nuxt.js
Library/Package Projects:
- Indicators: No application-specific directories
- Files:
```
index.ts
```
  ,
```
lib/
```
  ,
```
dist/
```
  ,
```
build/
```
- Manifests:
```
library
```
  field in package.json
CLI Projects:
- Indicators:
```
bin
```
  field in package.json
- Files: CLI entry points, command parsers
- Dependencies: Commander, Yargs, Inquirer
Mobile Projects:
- Indicators: React Native, Flutter, Ionic dependencies
- Files:
```
android/
```
  ,
```
ios/
```
  ,
```
mobile/
```
- Frameworks: React Native, Expo, Flutter
Monorepo Projects:
- Indicators:
```
workspaces
```
  in package.json,
```
pnpm-workspace.yaml
```
- Structure: Multiple packages in subdirectories
- Tools: Turborepo, Nx, Lerna
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:

Read package.json dependencies (Node.js):
- Parse
```
dependencies
```
  and
```
devDependencies
```
- Detect framework versions
- Categorize by type (framework, ui-library, testing, etc.)
Read requirements.txt (Python):
- Parse Python dependencies
- Detect FastAPI, Django, Flask
- Identify version constraints
Analyze imports (optional deep scan):
- Scan source files for import statements
- Detect used vs declared dependencies
- Identify framework-specific patterns
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
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:

Count files by type:
- Use glob patterns for common extensions
- Exclude:
```
node_modules/
```
  ,
```
.git/
```
  ,
```
dist/
```
  ,
```
build/
```
- Group by language/file type
Count lines of code:
- Read source files and count lines
- Exclude empty lines and comments (optional)
- Calculate total LOC per language
Identify largest files:
- Track file sizes (line count)
- Report top 10 largest files
- Flag files > 1000 lines (violates micro-service principle)
Calculate averages:
- Average file size (lines)
- Average directory depth
- Files per directory
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:

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/
```

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/
```

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/
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:

Count dependencies:
- Production dependencies
- Development dependencies
- Total dependency count
Check for outdated packages (optional):
- Run
```
npm outdated
```
  or equivalent
- Parse output for outdated packages
- Identify major version updates (breaking changes)
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:

Linting Configuration:
- Detect:
```
.eslintrc.json
```
  ,
```
eslint.config.js
```
  ,
```
ruff.toml
```
- Tool: ESLint, Ruff, Flake8, Pylint
- Run linter if configured (optional)
Formatting Configuration:
- Detect:
```
.prettierrc
```
  ,
```
pyproject.toml
```
  (Black/Ruff)
- Tool: Prettier, Black, Ruff
Testing Framework:
- Detect: Jest, Vitest, Pytest, Cypress
- Count test files
- Check for coverage configuration
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:

Good Practices:
- Modular component structure
- Comprehensive test coverage
- TypeScript strict mode enabled
- CI/CD configuration present
Anti-Patterns:
- Large files (> 1000 lines)
- Missing tests
- Outdated dependencies
- No linting configuration
Neutral Patterns:
- Specific architecture choices
- Framework-specific patterns

Step 9: Technical Debt Analysis

Calculate technical debt score:

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
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
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:

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
Prioritize by Impact:
- P0: Critical security, blocking production
- P1: High impact, affects reliability
- P2: Medium impact, improves quality
- P3: Low impact, nice-to-have
Estimate Effort and Impact:
- Effort: trivial, minor, moderate, major, massive
- Impact: low, medium, high, critical

Step 11: Validate Output

Validate analysis output against schema:

Schema Validation:
- Validate against
```
project-analysis.schema.json
```
- Ensure all required fields present
- Check data types and formats
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>

Progressive Disclosure: Start with manifest analysis, add deep scans if needed
Performance First: Skip expensive operations for large projects
Fail Gracefully: Handle missing files, parse errors
Validate Output: Always validate against schema
Cache Results: Store analysis output for reuse
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

</usage_example>

<formatting_example> Sample Output (

.claude/context/artifacts/project-analysis.json

json

{
  "analysis_id": "analysis-llm-rules-20250115",
  "project_type": "fullstack",
  "analyzed_at": "2025-01-15T10:30:00.000Z",
  "project_root": "C:\\dev\\projects\\LLM-RULES",
  "stats": {
    "total_files": 1243,
    "total_lines": 125430,
    "languages": {
      "JavaScript": 45230,
      "TypeScript": 38120,
      "Markdown": 25680,
      "JSON": 12400,
      "YAML": 4000
    },
    "file_types": {
      ".js": 234,
      ".mjs": 156,
      ".ts": 89,
      ".md": 312,
      ".json": 145
    },
    "directories": 87,
    "avg_file_size_lines": 101,
    "largest_files": [
      {
        "path": ".claude/tools/enforcement-gate.mjs",
        "lines": 1520
      }
    ]
  },
  "frameworks": [
    {
      "name": "nextjs",
      "version": "14.0.0",
      "category": "framework",
      "confidence": 1.0,
      "source": "package.json"
    },
    {
      "name": "react",
      "version": "18.2.0",
      "category": "framework",
      "confidence": 1.0,
      "source": "package.json"
    }
  ],
  "structure": {
    "root_directories": [
      {
        "name": ".claude",
        "purpose": "config",
        "file_count": 543
      },
      {
        "name": "conductor-main",
        "purpose": "source",
        "file_count": 234
      }
    ],
    "entry_points": [
      {
        "path": "conductor-main/src/index.ts",
        "type": "main"
      }
    ],
    "architecture_pattern": "modular",
    "module_system": "esm"
  },
  "dependencies": {
    "production": 45,
    "development": 23
  },
  "code_quality": {
    "linting": {
      "configured": true,
      "tool": "eslint"
    },
    "formatting": {
      "configured": true,
      "tool": "prettier"
    },
    "testing": {
      "framework": "vitest",
      "test_files": 89,
      "coverage_configured": true
    },
    "type_safety": {
      "typescript": true,
      "strict_mode": true
    }
  },
  "tech_debt": {
    "score": 35,
    "indicators": [
      {
        "category": "complexity",
        "severity": "medium",
        "description": "3 files exceed 1000 lines",
        "remediation_effort": "moderate"
      }
    ]
  },
  "recommendations": [
    {
      "priority": "P1",
      "category": "maintainability",
      "title": "Refactor large files",
      "description": "Break down files > 1000 lines into smaller modules",
      "effort": "moderate",
      "impact": "high"
    }
  ],
  "metadata": {
    "analyzer_version": "1.0.0",
    "analysis_duration_ms": 2340,
    "files_analyzed": 1243,
    "files_skipped": 3420,
    "errors": []
  }
}

</formatting_example> </examples>

References

For additional detection patterns extracted from the Auto-Claude analysis framework, see:

```
references/auto-claude-patterns.md
```
- Monorepo indicators, SERVICE_INDICATORS, SERVICE_ROOT_FILES, infrastructure detection, convention detection
```
references/service-patterns.md
```
- Service type detection (frontend, backend, library), framework-specific patterns, entry point detection
```
references/database-patterns.md
```
- Database configuration file patterns, ORM detection (Prisma, SQLAlchemy, TypeORM, Drizzle, Mongoose), connection string patterns
```
references/route-patterns.md
```
- Express, FastAPI, Flask, Django, Next.js, Go, Rust API route detection patterns

These references provide comprehensive regex patterns and detection logic for brownfield codebase analysis.

Memory Protocol (MANDATORY)

Before starting: Read

.claude/context/memory/learnings.md

After completing:

New pattern ->
```
.claude/context/memory/learnings.md
```
Issue found ->
```
.claude/context/memory/issues.md
```
Decision made ->
```
.claude/context/memory/decisions.md
```

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.