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

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

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

{
  "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>

Smart Categorization Scoring (Inspired by Skill_Seekers smart_categorize)

When classifying files, directories, or components into categories, use weighted keyword scoring instead of simple string matching to prevent false positives:

| Signal Source | Score Weight | Example | | -------------------- | ------------ | ----------------------------------------- | | File path/URL | 3 points | /api/routes/ matches "API" category | | File/class name | 2 points | AuthService.ts matches "Authentication" | | File content/imports | 1 point | import express matches "Backend" |

Threshold: Require 2+ total points before assigning a category. Falls back to "other" if no category scores above threshold. This prevents weak single-signal matches from misclassifying components.

Category keywords (extend per project type):

• API: route, endpoint, controller, handler, middleware, api, rest, graphql
• Auth: auth, login, session, jwt, oauth, token, credential, permission
• Database: model, schema, migration, seed, repository, entity, query
• Testing: test, spec, fixture, mock, stub, e2e, integration
• Config: config, env, setting, constant, option, feature-flag
• UI: component, view, page, layout, template, style, theme

Three-Stream Analysis (Inspired by Skill_Seekers unified_codebase_analyzer)

For comprehensive project understanding, analyze three parallel streams:

Stream 1 — Code Analysis: AST patterns, framework detection, dependency graph, architecture classification. This is the existing core workflow (Steps 1-11).

Stream 2 — Documentation: README quality, API docs existence, inline doc coverage, changelog maintenance, contribution guides. Score: docFiles / totalFiles weighted by type.

Stream 3 — Community/Operations: Git activity (commit frequency, contributor count), CI/CD configuration, issue templates, PR templates, release workflow, Docker/container setup.

Combine all three streams into the output JSON under analysis.streams:

{
  "streams": {
    "code": { "score": 0.85, "findings": [...] },
    "documentation": { "score": 0.60, "findings": [...] },
    "operations": { "score": 0.75, "findings": [...] }
  },
  "compositeHealth": 0.73
}

Design Pattern Recognition (Inspired by Skill_Seekers C3.1 PatternRecognizer)

Detect common design patterns with confidence scoring:

| Pattern | Detection Signal | Confidence Threshold | | ---------- | ------------------------------------------- | -------------------- | | Singleton | Private constructor + static instance | 0.80 | | Factory | create* methods returning interface types | 0.70 | | Observer | subscribe/on/emit/addEventListener | 0.70 | | Strategy | Interface + multiple implementations | 0.60 | | Decorator | Wrapper classes with same interface | 0.60 | | Repository | Data access layer abstraction | 0.70 | | Middleware | Chain-of-responsibility in request pipeline | 0.70 |

Output detected patterns in the analysis JSON with location, confidence, and evidence:

{
  "patterns": [
    {
      "type": "Factory",
      "category": "Creational",
      "confidence": 0.85,
      "location": "src/services/UserFactory.ts",
      "evidence": ["createUser method", "returns IUser interface"]
    }
  ]
}

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.