Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
feat(core): add knowledge graph type system and validation tests
Lum110435d05451009c
diff --git a/packages/core/package.json b/packages/core/package.jsonnew file mode 100644index 00000000..8a97a80a--- /dev/null+++ b/packages/core/package.json@@ -0,0 +1,15 @@+{+ "name": "@understand-anything/core",+ "version": "0.1.0",+ "type": "module",+ "main": "dist/index.js",+ "types": "dist/index.d.ts",+ "scripts": {+ "build": "tsc",+ "test": "vitest run"+ },+ "devDependencies": {+ "typescript": "^5.7.0",+ "vitest": "^3.1.0"+ }+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsnew file mode 100644index 00000000..a0c4ebf2--- /dev/null+++ b/packages/core/src/index.ts@@ -0,0 +1 @@+export * from "./types.js";diff --git a/packages/core/src/types.test.ts b/packages/core/src/types.test.tsnew file mode 100644index 00000000..e155b8f1--- /dev/null+++ b/packages/core/src/types.test.ts@@ -0,0 +1,117 @@+import { describe, it, expect } from "vitest";+import type { KnowledgeGraph, GraphNode, GraphEdge } from "./types.js";++describe("KnowledgeGraph types", () => {+ it("should create a valid empty KnowledgeGraph", () => {+ const graph: KnowledgeGraph = {+ version: "1.0.0",+ project: {+ name: "test-project",+ languages: [],+ frameworks: [],+ description: "A test project",+ analyzedAt: new Date().toISOString(),+ gitCommitHash: "abc123",+ },+ nodes: [],+ edges: [],+ layers: [],+ tour: [],+ };++ expect(graph.version).toBe("1.0.0");+ expect(graph.project.name).toBe("test-project");+ expect(graph.nodes).toHaveLength(0);+ expect(graph.edges).toHaveLength(0);+ expect(graph.layers).toHaveLength(0);+ expect(graph.tour).toHaveLength(0);+ });++ it("should create valid GraphNodes with all fields", () => {+ const fileNode: GraphNode = {+ id: "node-1",+ type: "file",+ name: "index.ts",+ filePath: "src/index.ts",+ lineRange: [1, 50],+ summary: "Entry point of the application",+ tags: ["entry", "typescript"],+ complexity: "simple",+ languageNotes: "Uses ES module syntax",+ };++ expect(fileNode.id).toBe("node-1");+ expect(fileNode.type).toBe("file");+ expect(fileNode.filePath).toBe("src/index.ts");+ expect(fileNode.lineRange).toEqual([1, 50]);+ expect(fileNode.tags).toContain("entry");+ expect(fileNode.complexity).toBe("simple");++ const functionNode: GraphNode = {+ id: "node-2",+ type: "function",+ name: "processData",+ filePath: "src/utils.ts",+ lineRange: [10, 25],+ summary: "Processes raw data into structured format",+ tags: ["utility", "data"],+ complexity: "moderate",+ };++ expect(functionNode.type).toBe("function");+ expect(functionNode.complexity).toBe("moderate");+ expect(functionNode.languageNotes).toBeUndefined();++ const classNode: GraphNode = {+ id: "node-3",+ type: "class",+ name: "DataStore",+ summary: "Manages application state",+ tags: ["state", "core"],+ complexity: "complex",+ };++ expect(classNode.type).toBe("class");+ expect(classNode.filePath).toBeUndefined();+ expect(classNode.lineRange).toBeUndefined();+ });++ it("should create valid GraphEdges with weight bounds", () => {+ const edge: GraphEdge = {+ source: "node-1",+ target: "node-2",+ type: "imports",+ direction: "forward",+ description: "index.ts imports processData from utils.ts",+ weight: 0.8,+ };++ expect(edge.source).toBe("node-1");+ expect(edge.target).toBe("node-2");+ expect(edge.type).toBe("imports");+ expect(edge.direction).toBe("forward");+ expect(edge.weight).toBeGreaterThanOrEqual(0);+ expect(edge.weight).toBeLessThanOrEqual(1);++ const minWeightEdge: GraphEdge = {+ source: "node-1",+ target: "node-3",+ type: "related",+ direction: "bidirectional",+ weight: 0,+ };++ expect(minWeightEdge.weight).toBe(0);+ expect(minWeightEdge.description).toBeUndefined();++ const maxWeightEdge: GraphEdge = {+ source: "node-2",+ target: "node-3",+ type: "calls",+ direction: "forward",+ weight: 1,+ };++ expect(maxWeightEdge.weight).toBe(1);+ });+});diff --git a/packages/core/src/types.ts b/packages/core/src/types.tsnew file mode 100644index 00000000..d9884e33--- /dev/null+++ b/packages/core/src/types.ts@@ -0,0 +1,103 @@+// Edge types (17 total in 5 categories: Structural, Behavioral, Data flow, Dependencies, Semantic)+export type EdgeType =+ | "imports" | "exports" | "contains" | "inherits" | "implements" // Structural+ | "calls" | "subscribes" | "publishes" | "middleware" // Behavioral+ | "reads_from" | "writes_to" | "transforms" | "validates" // Data flow+ | "depends_on" | "tested_by" | "configures" // Dependencies+ | "related" | "similar_to"; // Semantic++// GraphNode with 5 types: file, function, class, module, concept+export interface GraphNode {+ id: string;+ type: "file" | "function" | "class" | "module" | "concept";+ name: string;+ filePath?: string;+ lineRange?: [number, number];+ summary: string;+ tags: string[];+ complexity: "simple" | "moderate" | "complex";+ languageNotes?: string;+}++// GraphEdge with rich relationship modeling+export interface GraphEdge {+ source: string;+ target: string;+ type: EdgeType;+ direction: "forward" | "backward" | "bidirectional";+ description?: string;+ weight: number; // 0-1+}++// Layer (logical grouping)+export interface Layer {+ id: string;+ name: string;+ description: string;+ nodeIds: string[];+}++// TourStep (for learn mode)+export interface TourStep {+ order: number;+ title: string;+ description: string;+ nodeIds: string[];+ languageLesson?: string;+}++// ProjectMeta+export interface ProjectMeta {+ name: string;+ languages: string[];+ frameworks: string[];+ description: string;+ analyzedAt: string;+ gitCommitHash: string;+}++// Root KnowledgeGraph+export interface KnowledgeGraph {+ version: string;+ project: ProjectMeta;+ nodes: GraphNode[];+ edges: GraphEdge[];+ layers: Layer[];+ tour: TourStep[];+}++// AnalysisMeta (for persistence)+export interface AnalysisMeta {+ lastAnalyzedAt: string;+ gitCommitHash: string;+ version: string;+ analyzedFiles: number;+}++// Plugin interfaces+export interface StructuralAnalysis {+ functions: Array<{ name: string; lineRange: [number, number]; params: string[]; returnType?: string }>;+ classes: Array<{ name: string; lineRange: [number, number]; methods: string[]; properties: string[] }>;+ imports: Array<{ source: string; specifiers: string[]; lineNumber: number }>;+ exports: Array<{ name: string; lineNumber: number }>;+}++export interface ImportResolution {+ source: string;+ resolvedPath: string;+ specifiers: string[];+}++export interface CallGraphEntry {+ caller: string;+ callee: string;+ lineNumber: number;+}++export interface AnalyzerPlugin {+ name: string;+ languages: string[];+ analyzeFile(filePath: string, content: string): StructuralAnalysis;+ resolveImports(filePath: string, content: string): ImportResolution[];+ extractCallGraph?(filePath: string, content: string): CallGraphEntry[];+}diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.jsonnew file mode 100644index 00000000..a086b149--- /dev/null+++ b/packages/core/tsconfig.json@@ -0,0 +1,8 @@+{+ "extends": "../../tsconfig.json",+ "compilerOptions": {+ "outDir": "dist",+ "rootDir": "src"+ },+ "include": ["src"]+}diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex c4b68583..e2e9acb8 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -15,6 +15,15 @@ importers:specifier: ^3.1.0version: 3.2.4+ packages/core:+ devDependencies:+ typescript:+ specifier: ^5.7.0+ version: 5.9.3+ vitest:+ specifier: ^3.1.0+ version: 3.2.4+packages:'@esbuild/[email protected]':