proffesor-for-testing__agentic-qe/docs/implementation/ProjectMetadataAnalyzer-implementation.md

ProjectMetadataAnalyzer Implementation

Overview

The ProjectMetadataAnalyzer extracts project metadata from configuration files to generate C4 model diagrams. It analyzes package.json, docker-compose.yml, Dockerfile, and directory structure to infer system architecture and container composition.

File Location

• Source: /workspaces/agentic-qe-cf/src/code-intelligence/inference/ProjectMetadataAnalyzer.ts
• Tests: /workspaces/agentic-qe-cf/tests/code-intelligence/ProjectMetadataAnalyzer.test.ts
• Types: /workspaces/agentic-qe-cf/src/code-intelligence/inference/types.ts
• Index: /workspaces/agentic-qe-cf/src/code-intelligence/inference/index.ts

Features Implemented

1. Package.json Analysis

Extracts:

• System name (from name field)
• System description (from description field)
• Version (from version field)
• Repository URL (from repository field)
• Has binary/CLI (from bin field)
• Has main entry point (from main field)
• Has TypeScript types (from types field)
• Dependencies and dev dependencies

2. Docker Compose Analysis

Detects containers from docker-compose.yml:

• Service names
• Container types (application, database, cache, queue, service, api)
• Technologies (Node.js, PostgreSQL, Redis, RabbitMQ, etc.)
• Port mappings
• Service dependencies (from depends_on)

Container type detection logic:

• Database: Service name/image contains db, database, postgres, mysql, mongo, mariadb
• Cache: Service name/image contains redis, cache, memcached
• Queue: Service name/image contains queue, rabbitmq, kafka
• API: Service name/image contains api, gateway
• Service: Service name/image contains service, worker
• Application: Default fallback

3. Dockerfile Analysis

Parses Dockerfile to extract:

• Base image (from FROM instruction)
• Technology stack inference from base image

4. System Type Detection

Determines system type based on:

• CLI: Has bin field in package.json
• Library: Has main and types fields without bin
• Microservice: Multiple services in docker-compose.yml OR multiple service directories
• Monolith: Single service or no docker-compose

5. Technology Stack Detection

Detects:

• Primary language: TypeScript (if tsconfig.json exists), JavaScript, Python, Go, Rust
• Runtime: Node.js, Python, Go, Rust
• Frameworks: Express, Fastify, Koa, React, Vue, Angular, Next.js, NestJS
• Databases: PostgreSQL, MySQL, MongoDB, Redis, SQLite
• Infrastructure: Docker, Kubernetes, AWS

6. Layer Detection

Analyzes directory structure in src/ to detect architectural layers:

• controllers
• services
• repositories
• models
• routes
• middleware
• utils
• helpers
• views
• components
• domain
• infrastructure
• application
• presentation

Interfaces

ProjectMetadata

interface ProjectMetadata {
  name: string;                    // System name
  description?: string;            // System description
  systemType: 'microservice' | 'monolith' | 'library' | 'cli';
  technology: string;              // Primary technology (TypeScript, JavaScript, etc.)
  containers: Container[];         // Detected containers
  layers?: string[];               // Architectural layers
  version?: string;                // Project version
  repository?: string;             // Repository URL
}

Container

interface Container {
  id: string;                      // Unique container ID
  name: string;                    // Container name
  type: 'application' | 'database' | 'cache' | 'queue' | 'service' | 'api';
  technology: string;              // Technology (Node.js, PostgreSQL, etc.)
  description?: string;            // Optional description
  port?: number;                   // Primary port
  dependencies?: string[];         // Container dependencies
}

Usage Example

import { ProjectMetadataAnalyzer } from './src/code-intelligence/inference/ProjectMetadataAnalyzer';

const analyzer = new ProjectMetadataAnalyzer('/path/to/project');
const metadata = await analyzer.analyze();

console.log('System:', metadata.name);
console.log('Type:', metadata.systemType);
console.log('Technology:', metadata.technology);
console.log('Containers:', metadata.containers.length);
console.log('Layers:', metadata.layers);

Testing

The implementation includes 12 comprehensive tests covering:

1. Package.json parsing:

   • Basic metadata extraction
   • CLI type detection
   • Library type detection

2. Technology stack detection:

   • TypeScript detection
   • JavaScript fallback

3. Docker Compose parsing:

   • Container detection
   • Container type inference
   • Port extraction

4. System type detection:

   • Microservice architecture
   • Monolith architecture

5. Layer detection:

   • Directory structure analysis

6. Utility methods:

   • getRootDir/setRootDir

All tests pass successfully:

Test Suites: 1 passed, 1 total
Tests:       12 passed, 12 total

Integration with C4 Diagrams

The ProjectMetadata interface is designed to integrate seamlessly with C4 diagram builders:

• C4ContextDiagramBuilder: Uses name, description for system context
• C4ContainerDiagramBuilder: Uses containers array for container diagrams
• C4ComponentDiagramBuilder: Uses layers for component organization

Type Safety

Updated type definitions in /src/code-intelligence/inference/types.ts:

• Added Component interface with boundary field
• Added ComponentRelationship with from/to fields (matching C4 builder expectations)
• Added ComponentAnalysisResult with architecture field
• Added ExternalSystem purpose field for C4 diagram compatibility

Error Handling

The analyzer includes robust error handling:

• Gracefully handles missing configuration files
• Returns sensible defaults when files don't exist
• Catches and wraps parsing errors with descriptive messages
• Provides console warnings for non-critical parsing failures

Performance

Optimizations include:

• Content hashing for change detection (from IncrementalIndexer pattern)
• Efficient file existence checks with fs.pathExists
• Parallel async operations where possible
• Minimal file reads (only necessary configuration files)

Future Enhancements

Potential improvements:

1. Custom technology mapping configuration
2. Monorepo support (analyze multiple services)
3. Kubernetes manifest parsing
4. API endpoint detection from code analysis
5. Database schema extraction from migration files
6. Environment variable detection
7. CI/CD pipeline detection

Dependencies

External dependencies used:

• fs-extra: Enhanced file system operations
• yaml: YAML parsing for docker-compose.yml
• crypto: Hash generation for IDs

Build Verification

✅ TypeScript compilation passes ✅ All tests pass (12/12) ✅ No type errors ✅ Builds successfully with npm run build

Documentation

• Source code includes comprehensive JSDoc comments
• Each method has clear parameter and return type documentation
• Complex logic includes inline comments explaining the approach
• Interface definitions include field descriptions

---

Implementation Status: ✅ Complete Test Coverage: ✅ 100% of public methods Build Status: ✅ Passing Integration: ✅ Compatible with C4 diagram builders