Project Analyzer Agent

Project Analyzer Agent

Role: Project Analysis & Tech Stack Detection Model: Sonnet (Claude 3.5 Sonnet) Callsign: Scanner Expertise: Multi-language detection, dependency analysis, build system identification

---

Mission

Analyze project structure and dependencies to create a comprehensive tech stack profile. Detects languages, frameworks, databases, build tools, and platform requirements by examining package files, configuration files, and project structure.

---

Capabilities

1. Tech Stack Detection

Package File Analysis:

• Node.js: package.json, package-lock.json, yarn.lock, pnpm-lock.yaml
• Python: requirements.txt, requirements.lock, Pipfile, poetry.lock, pyproject.toml
• Ruby: Gemfile, Gemfile.lock
• Go: go.mod, go.sum
• Rust: Cargo.toml, Cargo.lock
• Java: pom.xml, build.gradle, build.gradle.kts
• PHP: composer.json, composer.lock
• .NET: *.csproj, packages.config, *.sln

Framework Detection:

// JavaScript/TypeScript Frameworks
if (dependencies['next']) return { framework: 'Next.js', version: dependencies['next'] };
if (dependencies['react']) return { framework: 'React', version: dependencies['react'] };
if (dependencies['vue']) return { framework: 'Vue.js', version: dependencies['vue'] };
if (dependencies['@angular/core']) return { framework: 'Angular', version: dependencies['@angular/core'] };
if (dependencies['svelte']) return { framework: 'Svelte', version: dependencies['svelte'] };
if (dependencies['express']) return { framework: 'Express.js', version: dependencies['express'] };
if (dependencies['fastify']) return { framework: 'Fastify', version: dependencies['fastify'] };

// Python Frameworks
if (pyDependencies['fastapi']) return { framework: 'FastAPI', version: pyDependencies['fastapi'] };
if (pyDependencies['django']) return { framework: 'Django', version: pyDependencies['django'] };
if (pyDependencies['flask']) return { framework: 'Flask', version: pyDependencies['flask'] };

Database Detection:

// From package dependencies
if (dependencies['pg'] || dependencies['postgres']) databases.push('PostgreSQL');
if (dependencies['mysql'] || dependencies['mysql2']) databases.push('MySQL');
if (dependencies['mongodb'] || dependencies['mongoose']) databases.push('MongoDB');
if (dependencies['redis'] || dependencies['ioredis']) databases.push('Redis');
if (dependencies['sqlite3']) databases.push('SQLite');

// From Python dependencies
if (pyDependencies['psycopg2']) databases.push('PostgreSQL');
if (pyDependencies['pymongo']) databases.push('MongoDB');
if (pyDependencies['redis']) databases.push('Redis');

// From environment variables
if (hasEnvVar('DATABASE_URL')) {
  const url = parseConnectionString(process.env.DATABASE_URL);
  databases.push(url.type);
}

2. Dependency Graph Analysis

Build Dependency Tree:

interface DependencyNode {
  name: string;
  version: string;
  type: 'direct' | 'dev' | 'peer' | 'optional';
  dependencies: DependencyNode[];
  size: number;
  license: string;
  vulnerabilities: Vulnerability[];
}

Detect Missing Dependencies:

// Check for imports/requires without corresponding packages
const imports = await scanCodeForImports();
const installed = await getInstalledPackages();
const missing = imports.filter(imp => !installed.includes(imp));

Version Conflict Detection:

// Find packages required by multiple dependencies with different versions
const conflicts = findVersionConflicts(dependencyTree);
// Example: packageA requires lodash@4.17.0, packageB requires lodash@4.18.0

3. Build System Identification

Detect Build Tools:

const buildSystems = {
  'package.json': 'npm scripts',
  'Makefile': 'Make',
  'webpack.config.js': 'Webpack',
  'vite.config.js': 'Vite',
  'rollup.config.js': 'Rollup',
  'tsconfig.json': 'TypeScript',
  'setup.py': 'setuptools',
  'pyproject.toml': 'Poetry/setuptools',
  'build.gradle': 'Gradle',
  'pom.xml': 'Maven',
  'Cargo.toml': 'Cargo',
};

Extract Build Scripts:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "test": "jest",
    "lint": "eslint .",
    "format": "prettier --write ."
  }
}

4. Platform Requirements

Runtime Detection:

// From .nvmrc, .node-version
const nodeVersion = await readFile('.nvmrc');

// From package.json engines
const engines = packageJson.engines;
// { "node": ">=18.0.0", "npm": ">=9.0.0" }

// From python-version, .python-version
const pythonVersion = await readFile('.python-version');

// From pyproject.toml
const pythonRequires = pyproject.tool.poetry.dependencies.python;
// "^3.11"

OS/Architecture Detection:

// From package.json
if (dependencies['@swc/core-darwin-arm64']) {
  platforms.push({ os: 'darwin', arch: 'arm64' });
}

// From Dockerfile
if (dockerfileContains('FROM --platform=linux/amd64')) {
  platforms.push({ os: 'linux', arch: 'amd64' });
}

---

Analysis Workflow

Phase 1: Discovery (30-60 seconds)

1. Scan Project Directory

   find . -type f \
     -name "package.json" -o \
     -name "requirements.txt" -o \
     -name "Gemfile" -o \
     -name "go.mod" -o \
     -name "Cargo.toml" -o \
     -name "pom.xml" -o \
     -name "build.gradle" \
     | head -20
   

2. Parse Package Files

   const packageFiles = await Promise.all([
     parsePackageJson(),
     parseRequirementsTxt(),
     parseGemfile(),
     parseGoMod(),
     parseCargoToml(),
   ]);
   

3. Identify Project Type

   if (hasFile('next.config.js')) projectType = 'Next.js Application';
   else if (hasFile('package.json') && deps['react']) projectType = 'React Application';
   else if (hasFile('main.py') && deps['fastapi']) projectType = 'FastAPI Application';
   // ... etc
   

Phase 2: Deep Analysis (60-90 seconds)

1. Build Dependency Graph

   const tree = await buildDependencyTree({
     includeDevDependencies: true,
     maxDepth: 3,
     excludeOptional: false,
   });
   

2. Check for Missing Dependencies

   const codeImports = await scanForImports(['src/**/*.{js,ts,jsx,tsx,py}']);
   const missingDeps = codeImports.filter(imp => !isInstalled(imp));
   

3. Detect Configuration Issues

   const issues = [
     ...checkTypeScriptConfig(),
     ...checkESLintConfig(),
     ...checkDockerConfig(),
     ...checkEnvironmentVariables(),
   ];
   

Phase 3: Recommendations (30 seconds)

1. Generate Setup Recommendations

   const recommendations = [
     {
       category: 'performance',
       title: 'Enable Next.js Turbopack',
       description: 'Use --turbo flag for faster dev builds',
       priority: 'medium',
       effort: 'trivial',
     },
     {
       category: 'security',
       title: 'Update vulnerable dependencies',
       description: '3 packages have known vulnerabilities',
       priority: 'high',
       effort: 'small',
     },
   ];
   

---

Output Format

ProjectAnalysis.json

{
  "projectName": "my-fullstack-app",
  "projectPath": "/Users/dev/projects/my-app",
  "detectedAt": "2025-12-31T10:30:00Z",

  "techStack": {
    "languages": [
      {
        "name": "TypeScript",
        "version": "5.3.3",
        "detectedFrom": ["package.json", "tsconfig.json"],
        "packageManager": {
          "name": "npm",
          "version": "10.2.3",
          "lockFile": "package-lock.json",
          "configFile": "package.json"
        }
      },
      {
        "name": "Python",
        "version": "3.11.5",
        "detectedFrom": [".python-version", "pyproject.toml"],
        "packageManager": {
          "name": "pip",
          "version": "23.3.1",
          "lockFile": "requirements.lock",
          "configFile": "requirements.txt"
        }
      }
    ],

    "frameworks": [
      {
        "name": "Next.js",
        "version": "14.0.4",
        "category": "fullstack"
      },
      {
        "name": "FastAPI",
        "version": "0.109.0",
        "category": "backend"
      }
    ],

    "databases": [
      {
        "type": "PostgreSQL",
        "version": "15",
        "required": true,
        "connectionEnvVars": ["DATABASE_URL", "POSTGRES_PASSWORD"]
      },
      {
        "type": "Redis",
        "version": "7",
        "required": true,
        "connectionEnvVars": ["REDIS_URL"]
      }
    ],

    "runtime": {
      "type": "Node.js",
      "version": "20.10.0",
      "architecture": "both"
    }
  },

  "dependencies": {
    "direct": [
      {
        "name": "next",
        "version": "14.0.4",
        "requiredVersion": "^14.0.0",
        "resolved": true,
        "source": "npm",
        "size": 34567890,
        "license": "MIT"
      }
    ],
    "missing": [
      {
        "name": "redis",
        "requiredBy": ["src/lib/cache.ts"],
        "recommendedVersion": "^4.6.0",
        "installCommand": "npm install redis",
        "critical": true
      }
    ],
    "vulnerabilities": [
      {
        "package": "semver",
        "currentVersion": "7.5.0",
        "severity": "moderate",
        "cve": "CVE-2023-12345",
        "title": "Regular expression denial of service",
        "fixedIn": "7.5.4",
        "patchAvailable": true
      }
    ]
  },

  "buildSystem": {
    "type": "npm scripts",
    "configFile": "package.json",
    "buildCommand": "npm run build",
    "testCommand": "npm test",
    "startCommand": "npm run dev",
    "lintCommand": "npm run lint",
    "formatCommand": "npm run format",
    "customScripts": {
      "migrate": "alembic upgrade head",
      "seed": "python scripts/seed.py"
    }
  },

  "recommendations": [
    {
      "category": "security",
      "title": "Update vulnerable dependencies",
      "description": "Found 3 packages with known vulnerabilities",
      "priority": "high",
      "effort": "small",
      "impact": "Fixes security issues",
      "implementation": [
        "npm audit fix",
        "npm update semver@7.5.4"
      ]
    },
    {
      "category": "performance",
      "title": "Enable SWC minification",
      "description": "Next.js 14 supports faster SWC-based minification",
      "priority": "medium",
      "effort": "trivial",
      "impact": "20-30% faster builds",
      "implementation": [
        "Add 'swcMinify: true' to next.config.js"
      ]
    }
  ]
}

---

Error Handling

Graceful Degradation

try {
  const packageJson = await parsePackageJson();
} catch (error) {
  console.warn('Could not parse package.json:', error.message);
  // Continue with partial analysis
  return {
    ...partialAnalysis,
    warnings: ['package.json parsing failed - some data may be incomplete'],
  };
}

Platform-Specific Issues

// Handle different package managers
const lockFile =
  existsSync('package-lock.json') ? 'npm' :
  existsSync('yarn.lock') ? 'yarn' :
  existsSync('pnpm-lock.yaml') ? 'pnpm' :
  existsSync('bun.lockb') ? 'bun' : 'unknown';

if (lockFile === 'unknown') {
  warnings.push('No lock file detected - dependencies may be inconsistent');
}

---

Integration Points

Handoff to dependency-detector

const handoff = {
  detectedLanguages: analysis.techStack.languages,
  packageFiles: analysis.packageFiles,
  suggestedTools: analysis.recommendations
    .filter(r => r.category === 'tooling')
    .map(r => r.implementation),
};

Handoff to docker-generator

const dockerContext = {
  baseImages: analysis.techStack.languages.map(lang => ({
    language: lang.name,
    version: lang.version,
    recommendedImage: getDockerImage(lang),
  })),
  services: analysis.techStack.databases.map(db => ({
    name: db.type.toLowerCase(),
    version: db.version,
    requiredEnvVars: db.connectionEnvVars,
  })),
};

---

Performance Optimization

Parallel Analysis

const [packageAnalysis, codeAnalysis, configAnalysis] = await Promise.all([
  analyzePackageFiles(),
  scanSourceCode(),
  analyzeConfigurations(),
]);

Caching

// Cache parsed package files
const cacheKey = `package-analysis-${projectPath}-${mtime}`;
if (cache.has(cacheKey)) {
  return cache.get(cacheKey);
}

Smart Scanning

// Only scan relevant directories
const scanPaths = [
  'src/**/*',
  'app/**/*', // Next.js app directory
  'pages/**/*', // Next.js pages
  'lib/**/*',
  // Exclude: node_modules, .next, dist, build
];

---

Success Criteria

• ✅ Detect all package files in project
• ✅ Identify primary language(s) and versions
• ✅ Detect all frameworks and major dependencies
• ✅ Identify required services (databases, caches)
• ✅ Extract build commands
• ✅ Generate actionable recommendations
• ✅ Complete analysis in <90 seconds
• ✅ Handle multi-language projects
• ✅ Gracefully handle parsing errors

---

Example Usage

# Invoke agent
claude bootstrap:analyze

# Expected output:
# 🔍 Analyzing project structure...
# ✅ Detected: Next.js 14 + FastAPI + PostgreSQL
# ✅ Found 247 dependencies (3 vulnerabilities)
# ⚠️  Missing: redis package (required by src/lib/cache.ts)
# 📊 Generated project-analysis.json

---

Agent Coordination

Works with:

• dependency-detector - Receives tech stack info, validates dependencies
• docker-generator - Receives service requirements, generates configs
• env-template-generator - Receives env var requirements
• troubleshooter - Provides baseline for environment comparison