project-analyzer（项目分析器）

References (archive): SCAFFOLD_SKILLS_ARCHIVE_MAP.md — ProjectAnalyzer monorepo/service detection from Auto-Claude-develop analysis/analyzers.

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)

1. Identify project root:

- Directory containing primary package manager file - Handle monorepos (multiple package.json files) - Detect workspace configuration

1. 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

1. Backend Projects:

- Indicators: Express, FastAPI, Django, Flask, Gin dependencies - Directory: routes/, controllers/, models/, api/ - Frameworks: Next.js API routes, FastAPI, Express

1. Fullstack Projects:

- Indicators: Both frontend and backend frameworks - Directory: Combined frontend + backend structure - Frameworks: Next.js, Remix, SvelteKit, Nuxt.js

1. Library/Package Projects:

- Indicators: No application-specific directories - Files: index.ts, lib/, dist/, build/ - Manifests: library field in package.json

1. CLI Projects:

- Indicators: bin field in package.json - Files: CLI entry points, command parsers - Dependencies: Commander, Yargs, Inquirer

1. Mobile Projects:

- Indicators: React Native, Flutter, Ionic dependencies - Files: android/, ios/, mobile/ - Frameworks: React Native, Expo, Flutter

1. Monorepo Projects:

- Indicators: workspaces in package.json, pnpm-workspace.yaml - Structure: Multiple packages in subdirectories - Tools: Turborepo, Nx, Lerna

1. 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.)

1. Read requirements.txt (Python):

- Parse Python dependencies - Detect FastAPI, Django, Flask - Identify version constraints

1. Analyze imports (optional deep scan):

- Scan source files for import statements - Detect used vs declared dependencies - Identify framework-specific patterns

1. 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

1. 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

1. Count lines of code:

- Read source files and count lines - Exclude empty lines and comments (optional) - Calculate total LOC per language

1. Identify largest files:

- Track file sizes (line count) - Report top 10 largest files - Flag files > 1000 lines (violates micro-service principle)

1. Calculate averages:

- Average file size (lines) - Average directory depth - Files per directory

1. 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/

1. 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/

1. 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/

1. 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

1. Check for outdated packages (optional):

- Run npm outdated or equivalent - Parse output for outdated packages - Identify major version updates (breaking changes)

1. 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)

1. Formatting Configuration:

- Detect: .prettierrc, pyproject.toml (Black/Ruff) - Tool: Prettier, Black, Ruff

1. Testing Framework:

- Detect: Jest, Vitest, Pytest, Cypress - Count test files - Check for coverage configuration

1. 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

1. Anti-Patterns:

- Large files (> 1000 lines) - Missing tests - Outdated dependencies - No linting configuration

1. 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

1. 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

1. 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

1. Prioritize by Impact:

- P0: Critical security, blocking production - P1: High impact, affects reliability - P2: Medium impact, improves quality - P3: Low impact, nice-to-have

1. 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

1. Output Metadata:

- Analyzer version - Analysis duration (ms) - Files analyzed count - Files skipped count - Errors encountered

</execution_process>

• 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

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

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

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

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:

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:

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.