@ebowwa/knowledge-graph

Knowledge graph schema and types for code analysis, dependency tracking, and impact analysis.

Features

• Code Module Types: Files, functions, classes, interfaces, types, variables, enums, namespaces, generics
• Relationship Types: Imports, extends, implements, calls, references, depends-on, instantiates, overrides, parameterized-by, member-of
• Query Operations: Search, traversal, impact analysis, shortest path, cycle detection, and more
• Type Safety: Full TypeScript types with Zod schemas for runtime validation
• Language Support: TypeScript, JavaScript, Python, Rust, Go, Java, C/C++

Installation

bun add @ebowwa/knowledge-graph

Usage

Creating Entities

import { Entity, CodeModuleType, CodeLanguage } from '@ebowwa/knowledge-graph';

const fileEntity: Entity = {
  id: '550e8400-e29b-41d4-a716-446655440000',
  module: {
    type: CodeModuleType.FILE,
    path: 'src/users.ts',
    language: CodeLanguage.TYPESCRIPT,
    hash: 'abc123',
    lastModified: Date.now(),
    size: 1024
  }
};

const functionEntity: Entity = {
  id: '660e8400-e29b-41d4-a716-446655440001',
  module: {
    type: CodeModuleType.FUNCTION,
    name: 'getUserById',
    async: true,
    parameters: ['id: string'],
    returnType: 'Promise<User>',
    location: {
      file: 'src/users.ts',
      line: 10,
      column: 0
    }
  }
};

Creating Relationships

import { Relationship, RelationshipType } from '@ebowwa/knowledge-graph';

const importRelationship: Relationship = {
  id: '770e8400-e29b-41d4-a716-446655440002',
  from: functionEntity.id,
  to: 'some-other-entity-id',
  type: RelationshipType.IMPORTS,
  weight: 1.0
};

const extendsRelationship: Relationship = {
  id: '880e8400-e29b-41d4-a716-446655440003',
  from: 'subclass-id',
  to: 'baseclass-id',
  type: RelationshipType.EXTENDS
};

Using Zod Schemas

import { EntitySchema, RelationshipSchema } from '@ebowwa/knowledge-graph/schemas';

// Validate entities at runtime
const validatedEntity = EntitySchema.parse(rawEntity);

// Validate relationships
const validatedRelationship = RelationshipSchema.parse(rawRelationship);

Query Types

import {
  QueryType,
  SearchQuery,
  TraversalQuery,
  ImpactAnalysisQuery
} from '@ebowwa/knowledge-graph';

// Search for entities
const searchQuery: SearchQuery = {
  type: QueryType.SEARCH,
  name: 'User*',
  moduleType: CodeModuleType.CLASS,
  limit: 100
};

// Traverse relationships
const traversalQuery: TraversalQuery = {
  type: QueryType.TRAVERSAL,
  from: 'entity-id',
  direction: 'outgoing',
  relationshipTypes: [RelationshipType.IMPORTS, RelationshipType.CALLS],
  maxDepth: 5
};

// Impact analysis
const impactQuery: ImpactAnalysisQuery = {
  type: QueryType.IMPACT_ANALYSIS,
  entityId: 'entity-id',
  direction: 'outgoing',
  maxDepth: 10
};

API

Types

• CodeModuleType - Enum of module types (file, function, class, interface, type, variable, enum, namespace, generic)
• CodeLanguage - Enum of supported languages
• RelationshipType - Enum of relationship types (imports, extends, implements, calls, references, depends-on, instantiates, overrides, parameterized-by, member-of)
• QueryType - Enum of query types
• TraversalDirection - Enum of traversal directions (outgoing, incoming, both)

Core Interfaces

• Entity - A code construct with unique ID and module data
• Relationship - A directed relationship between two entities
• KnowledgeGraph - Collection of entities and relationships with indexes
• CodeModule - Union type for all module types
• Query - Union type for all query types

Query Interfaces

• SearchQuery - Find entities matching criteria
• TraversalQuery - Navigate relationships from a starting entity
• ImpactAnalysisQuery - Analyze impact of changing an entity
• ShortestPathQuery - Find shortest path between two entities
• AllPathsQuery - Find all paths between two entities
• CycleDetectionQuery - Find circular dependencies
• ByTypeQuery - Get entities by type
• RelationshipsQuery - Get relationships for an entity
• BatchQuery - Execute multiple queries

Result Interfaces

• SearchResult - Search query results with entities
• TraversalResult - Traversal paths and visited entities
• ImpactAnalysisResult - Affected entities with severity scores
• ShortestPathResult - Path and relationship chain
• AllPathsResult - All paths between entities
• CycleDetectionResult - Detected cycles
• ByTypeResult - Entities of specified type
• RelationshipsResult - Relationships for entity
• BatchResult - Results for batch queries

Zod Schemas

All types have corresponding Zod schemas for runtime validation:

• EntitySchema
• RelationshipSchema
• KnowledgeGraphSchema
• QuerySchema (discriminated union)
• QueryResultSchema (discriminated union)
• CodeModuleSchema (discriminated union)

License

MIT

Author

Ebowwa Labs [email protected]