proffesor-for-testing__agentic-qe/docs/implementation/ddd/code-intelligence.md

Code Intelligence Domain

Bounded Context Overview

Domain: Code Intelligence Responsibility: Knowledge Graph construction, semantic search, and impact analysis Location: src/domains/code-intelligence/

The Code Intelligence domain builds and maintains a Knowledge Graph of the codebase, enabling O(log n) semantic search via HNSW indexing and accurate change impact analysis.

Ubiquitous Language

Term	Definition
Knowledge Graph	Graph representation of code relationships
Semantic Search	Natural language code search
Impact Analysis	Determining affected code from changes
Dependency Map	Graph of code dependencies
Index	Searchable representation of codebase
KG Node	Entity in the Knowledge Graph
KG Edge	Relationship between nodes

Domain Model

Aggregates

IndexResult (Aggregate Root)

Result of codebase indexing operation.

interface IndexResult {
  filesIndexed: number;
  nodesCreated: number;
  edgesCreated: number;
  duration: number;
  errors: IndexError[];
}

ImpactAnalysis (Aggregate Root)

Complete change impact assessment.

interface ImpactAnalysis {
  directImpact: ImpactedFile[];
  transitiveImpact: ImpactedFile[];
  impactedTests: string[];
  riskLevel: Severity;
  recommendations: string[];
}

Entities

DependencyNode

Node in the dependency graph.

interface DependencyNode {
  id: string;
  path: string;
  type: 'module' | 'class' | 'function' | 'file';
  inDegree: number;
  outDegree: number;
}

KGNode

Entity in the Knowledge Graph.

interface KGNode {
  id: string;
  label: string;
  properties: Record<string, unknown>;
}

SearchResult

Individual search match.

interface SearchResult {
  file: string;
  line?: number;
  snippet: string;
  score: number;
  highlights: string[];
  metadata?: Record<string, unknown>;
}

Value Objects

ImpactedFile

Immutable representation of affected file.

interface ImpactedFile {
  readonly file: string;
  readonly reason: string;
  readonly distance: number;        // Graph distance from change
  readonly riskScore: number;
}

DependencyEdge

Immutable dependency relationship.

interface DependencyEdge {
  readonly source: string;
  readonly target: string;
  readonly type: 'import' | 'call' | 'extends' | 'implements';
}

DependencyMetrics

Aggregate dependency statistics.

interface DependencyMetrics {
  readonly totalNodes: number;
  readonly totalEdges: number;
  readonly avgDegree: number;
  readonly maxDepth: number;
  readonly cyclomaticComplexity: number;
}

SearchFilter

Search constraint specification.

interface SearchFilter {
  readonly field: string;
  readonly operator: 'eq' | 'contains' | 'gt' | 'lt';
  readonly value: unknown;
}

Domain Services

CodeIntelligenceAPI

Primary API for the domain.

interface CodeIntelligenceAPI {
  index(request: IndexRequest): Promise<Result<IndexResult, Error>>;
  search(request: SearchRequest): Promise<Result<SearchResults, Error>>;
  analyzeImpact(request: ImpactRequest): Promise<Result<ImpactAnalysis, Error>>;
  mapDependencies(request: DependencyRequest): Promise<Result<DependencyMap, Error>>;
  queryKG(request: KGQueryRequest): Promise<Result<KGQueryResult, Error>>;
}

Domain Events

Event	Trigger	Payload
IndexCompletedEvent	Indexing finished	{ filesIndexed, nodesCreated, edgesCreated }
ImpactAnalyzedEvent	Impact analysis done	{ changedFiles, impactedFiles, riskLevel }
CycleDetectedEvent	Dependency cycle found	{ cycle, severity }
HotspotIdentifiedEvent	High-coupling node found	{ node, inDegree, outDegree }

Knowledge Graph Schema

Node Types

Type	Properties	Description
File	path, language, size, lastModified	Source file
Module	name, path, exports	ES/CJS module
Class	name, file, methods, properties	Class definition
Function	name, file, params, async, exported	Function definition
Interface	name, file, properties	TypeScript interface
Test	name, file, type, assertions	Test case

Edge Types

Type	From	To	Description
IMPORTS	Module	Module	Import relationship
CALLS	Function	Function	Function call
EXTENDS	Class	Class	Inheritance
IMPLEMENTS	Class	Interface	Implementation
TESTS	Test	Function/Class	Test target
CONTAINS	File	Class/Function	File contents

Search Capabilities

Search Types

Type	Use Case	Algorithm
semantic	Natural language queries	HNSW + embeddings
exact	Precise string match	Inverted index
fuzzy	Approximate match	Levenshtein distance

Query Examples

// Semantic search
const results = await api.search({
  query: "function that handles user authentication",
  type: 'semantic',
  limit: 10,
});

// Exact search with filters
const results = await api.search({
  query: "handleLogin",
  type: 'exact',
  filters: [
    { field: 'language', operator: 'eq', value: 'typescript' },
    { field: 'type', operator: 'eq', value: 'function' },
  ],
});

// Knowledge Graph query (Cypher)
const results = await api.queryKG({
  query: "MATCH (f:Function)-[:CALLS]->(g:Function) WHERE f.name = 'processOrder' RETURN g",
  type: 'cypher',
});

// Natural language KG query
const results = await api.queryKG({
  query: "What functions call the authentication service?",
  type: 'natural-language',
});

Context Integration

Upstream Dependencies

• AST parsers (ts-morph, babel, tree-sitter)
• Embedding models (transformers)

Downstream Consumers

• Test Generation: Import paths, function signatures
• Coverage Analysis: File complexity
• Defect Intelligence: Dependency analysis
• All Domains: Semantic code search

Anti-Corruption Layer

The domain abstracts different languages through language-specific AST parsers, exposing a unified Knowledge Graph interface.

Task Handlers

Task Type	Handler	Description
index-codebase	index()	Build/update Knowledge Graph
semantic-search	search()	O(log n) code search
analyze-impact	analyzeImpact()	Change impact analysis
map-dependencies	mapDependencies()	Dependency graph
query-kg	queryKG()	Knowledge Graph queries

Impact Analysis Algorithm

async function analyzeImpact(changedFiles: string[], depth: number): Promise<ImpactAnalysis> {
  const directImpact: ImpactedFile[] = [];
  const transitiveImpact: ImpactedFile[] = [];
  const visited = new Set<string>();

  // BFS to find impacted files
  const queue: Array<{ file: string; distance: number }> =
    changedFiles.map(f => ({ file: f, distance: 0 }));

  while (queue.length > 0) {
    const { file, distance } = queue.shift()!;

    if (visited.has(file) || distance > depth) continue;
    visited.add(file);

    const dependents = await getDependents(file);

    for (const dependent of dependents) {
      const impact: ImpactedFile = {
        file: dependent,
        reason: `Depends on ${file}`,
        distance: distance + 1,
        riskScore: calculateRiskScore(dependent, distance + 1),
      };

      if (distance === 0) {
        directImpact.push(impact);
      } else {
        transitiveImpact.push(impact);
      }

      queue.push({ file: dependent, distance: distance + 1 });
    }
  }

  return {
    directImpact,
    transitiveImpact,
    impactedTests: await findImpactedTests(visited),
    riskLevel: calculateOverallRisk(directImpact, transitiveImpact),
    recommendations: generateRecommendations(directImpact, transitiveImpact),
  };
}

ADR References

• ADR-006: Unified Memory Service (KG storage)
• ADR-009: Hybrid Memory Backend (HNSW indexing)