feat(#71): implement graph data API
Implemented three new API endpoints for knowledge graph visualization: 1. GET /api/knowledge/graph - Full knowledge graph - Returns all entries and links with optional filtering - Supports filtering by tags, status, and node count limit - Includes orphan detection (entries with no links) 2. GET /api/knowledge/graph/stats - Graph statistics - Total entries and links counts - Orphan entries detection - Average links per entry - Top 10 most connected entries - Tag distribution across entries 3. GET /api/knowledge/graph/:slug - Entry-centered subgraph - Returns graph centered on specific entry - Supports depth parameter (1-5) for traversal distance - Includes all connected nodes up to specified depth New Files: - apps/api/src/knowledge/graph.controller.ts - apps/api/src/knowledge/graph.controller.spec.ts Modified Files: - apps/api/src/knowledge/dto/graph-query.dto.ts (added GraphFilterDto) - apps/api/src/knowledge/entities/graph.entity.ts (extended with new types) - apps/api/src/knowledge/services/graph.service.ts (added new methods) - apps/api/src/knowledge/services/graph.service.spec.ts (added tests) - apps/api/src/knowledge/knowledge.module.ts (registered controller) - apps/api/src/knowledge/dto/index.ts (exported new DTOs) - docs/scratchpads/71-graph-data-api.md (implementation notes) Test Coverage: 21 tests (all passing) - 14 service tests including orphan detection, filtering, statistics - 7 controller tests for all three endpoints Follows TDD principles with tests written before implementation. All code quality gates passed (lint, typecheck, tests). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
@@ -69,6 +69,43 @@ describe("GraphService", () => {
|
||||
expect(service).toBeDefined();
|
||||
});
|
||||
|
||||
describe("getEntryGraphBySlug", () => {
|
||||
it("should throw NotFoundException if entry does not exist", async () => {
|
||||
mockPrismaService.knowledgeEntry.findUnique.mockResolvedValue(null);
|
||||
|
||||
await expect(service.getEntryGraphBySlug("workspace-1", "non-existent", 1)).rejects.toThrow(
|
||||
NotFoundException
|
||||
);
|
||||
});
|
||||
|
||||
it("should call getEntryGraph with entry ID", async () => {
|
||||
const mockEntry = {
|
||||
id: "entry-1",
|
||||
workspaceId: "workspace-1",
|
||||
slug: "test-entry",
|
||||
tags: [],
|
||||
outgoingLinks: [],
|
||||
incomingLinks: [],
|
||||
};
|
||||
|
||||
mockPrismaService.knowledgeEntry.findUnique
|
||||
.mockResolvedValueOnce(mockEntry) // First call in getEntryGraphBySlug
|
||||
.mockResolvedValueOnce(mockEntry) // Second call in getEntryGraph validation
|
||||
.mockResolvedValueOnce(mockEntry); // Third call in getEntryGraph BFS
|
||||
|
||||
await service.getEntryGraphBySlug("workspace-1", "test-entry", 1);
|
||||
|
||||
expect(mockPrismaService.knowledgeEntry.findUnique).toHaveBeenCalledWith({
|
||||
where: {
|
||||
workspaceId_slug: {
|
||||
workspaceId: "workspace-1",
|
||||
slug: "test-entry",
|
||||
},
|
||||
},
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("getEntryGraph", () => {
|
||||
it("should throw NotFoundException if entry does not exist", async () => {
|
||||
mockPrismaService.knowledgeEntry.findUnique.mockResolvedValue(null);
|
||||
@@ -150,4 +187,195 @@ describe("GraphService", () => {
|
||||
expect(result.stats.totalEdges).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("getFullGraph", () => {
|
||||
beforeEach(() => {
|
||||
// Add findMany mock
|
||||
mockPrismaService.knowledgeEntry.findMany = vi.fn();
|
||||
mockPrismaService.knowledgeLink = {
|
||||
findMany: vi.fn(),
|
||||
};
|
||||
});
|
||||
|
||||
it("should return full graph with all entries and links", async () => {
|
||||
const entries = [
|
||||
{ ...mockEntry, id: "entry-1", slug: "entry-1", tags: [] },
|
||||
{
|
||||
...mockEntry,
|
||||
id: "entry-2",
|
||||
slug: "entry-2",
|
||||
title: "Entry 2",
|
||||
tags: [],
|
||||
},
|
||||
];
|
||||
|
||||
const links = [
|
||||
{
|
||||
id: "link-1",
|
||||
sourceId: "entry-1",
|
||||
targetId: "entry-2",
|
||||
linkText: "link text",
|
||||
resolved: true,
|
||||
},
|
||||
];
|
||||
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue(entries);
|
||||
mockPrismaService.knowledgeLink.findMany.mockResolvedValue(links);
|
||||
|
||||
const result = await service.getFullGraph("workspace-1");
|
||||
|
||||
expect(result.nodes).toHaveLength(2);
|
||||
expect(result.edges).toHaveLength(1);
|
||||
expect(result.stats.totalNodes).toBe(2);
|
||||
expect(result.stats.totalEdges).toBe(1);
|
||||
expect(result.stats.orphanCount).toBe(0);
|
||||
});
|
||||
|
||||
it("should detect orphan entries (entries with no links)", async () => {
|
||||
const entries = [
|
||||
{ ...mockEntry, id: "entry-1", slug: "entry-1", tags: [] },
|
||||
{
|
||||
...mockEntry,
|
||||
id: "entry-2",
|
||||
slug: "entry-2",
|
||||
title: "Entry 2",
|
||||
tags: [],
|
||||
},
|
||||
{
|
||||
...mockEntry,
|
||||
id: "entry-3",
|
||||
slug: "entry-3",
|
||||
title: "Entry 3 (orphan)",
|
||||
tags: [],
|
||||
},
|
||||
];
|
||||
|
||||
const links = [
|
||||
{
|
||||
id: "link-1",
|
||||
sourceId: "entry-1",
|
||||
targetId: "entry-2",
|
||||
linkText: "link text",
|
||||
resolved: true,
|
||||
},
|
||||
];
|
||||
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue(entries);
|
||||
mockPrismaService.knowledgeLink.findMany.mockResolvedValue(links);
|
||||
|
||||
const result = await service.getFullGraph("workspace-1");
|
||||
|
||||
expect(result.stats.orphanCount).toBe(1);
|
||||
const orphanNode = result.nodes.find((n) => n.id === "entry-3");
|
||||
expect(orphanNode?.isOrphan).toBe(true);
|
||||
});
|
||||
|
||||
it("should filter by status", async () => {
|
||||
const entries = [
|
||||
{ ...mockEntry, id: "entry-1", status: "PUBLISHED", tags: [] },
|
||||
];
|
||||
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue(entries);
|
||||
mockPrismaService.knowledgeLink.findMany.mockResolvedValue([]);
|
||||
|
||||
await service.getFullGraph("workspace-1", { status: "PUBLISHED" });
|
||||
|
||||
expect(mockPrismaService.knowledgeEntry.findMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: expect.objectContaining({
|
||||
status: "PUBLISHED",
|
||||
}),
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("should filter by tags", async () => {
|
||||
const entries = [{ ...mockEntry, id: "entry-1", tags: [] }];
|
||||
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue(entries);
|
||||
mockPrismaService.knowledgeLink.findMany.mockResolvedValue([]);
|
||||
|
||||
await service.getFullGraph("workspace-1", { tags: ["tag-1", "tag-2"] });
|
||||
|
||||
expect(mockPrismaService.knowledgeEntry.findMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: expect.objectContaining({
|
||||
tags: {
|
||||
some: {
|
||||
tag: {
|
||||
slug: {
|
||||
in: ["tag-1", "tag-2"],
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}),
|
||||
})
|
||||
);
|
||||
});
|
||||
|
||||
it("should limit number of nodes", async () => {
|
||||
const entries = [
|
||||
{ ...mockEntry, id: "entry-1", slug: "entry-1", tags: [] },
|
||||
{ ...mockEntry, id: "entry-2", slug: "entry-2", tags: [] },
|
||||
];
|
||||
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue(entries);
|
||||
mockPrismaService.knowledgeLink.findMany.mockResolvedValue([]);
|
||||
|
||||
await service.getFullGraph("workspace-1", { limit: 1 });
|
||||
|
||||
expect(mockPrismaService.knowledgeEntry.findMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
take: 1,
|
||||
})
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("getGraphStats", () => {
|
||||
beforeEach(() => {
|
||||
mockPrismaService.knowledgeEntry.count = vi.fn();
|
||||
mockPrismaService.knowledgeEntry.findMany = vi.fn();
|
||||
mockPrismaService.knowledgeLink = {
|
||||
count: vi.fn(),
|
||||
groupBy: vi.fn(),
|
||||
};
|
||||
mockPrismaService.$queryRaw = vi.fn();
|
||||
});
|
||||
|
||||
it("should return graph statistics", async () => {
|
||||
mockPrismaService.knowledgeEntry.count.mockResolvedValue(10);
|
||||
mockPrismaService.knowledgeLink.count.mockResolvedValue(15);
|
||||
mockPrismaService.$queryRaw.mockResolvedValue([
|
||||
{ id: "entry-1", slug: "entry-1", title: "Entry 1", link_count: "5" },
|
||||
{ id: "entry-2", slug: "entry-2", title: "Entry 2", link_count: "3" },
|
||||
]);
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue([
|
||||
{ id: "orphan-1" },
|
||||
]);
|
||||
|
||||
const result = await service.getGraphStats("workspace-1");
|
||||
|
||||
expect(result.totalEntries).toBe(10);
|
||||
expect(result.totalLinks).toBe(15);
|
||||
expect(result.averageLinks).toBe(1.5);
|
||||
expect(result.mostConnectedEntries).toHaveLength(2);
|
||||
expect(result.mostConnectedEntries[0].linkCount).toBe(5);
|
||||
});
|
||||
|
||||
it("should calculate orphan entries correctly", async () => {
|
||||
mockPrismaService.knowledgeEntry.count.mockResolvedValue(5);
|
||||
mockPrismaService.knowledgeLink.count.mockResolvedValue(2);
|
||||
mockPrismaService.$queryRaw.mockResolvedValue([]);
|
||||
mockPrismaService.knowledgeEntry.findMany.mockResolvedValue([
|
||||
{ id: "orphan-1" },
|
||||
{ id: "orphan-2" },
|
||||
]);
|
||||
|
||||
const result = await service.getGraphStats("workspace-1");
|
||||
|
||||
expect(result.orphanEntries).toBe(2);
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,7 +1,20 @@
|
||||
import { Injectable, NotFoundException } from "@nestjs/common";
|
||||
import { PrismaService } from "../../prisma/prisma.service";
|
||||
import type { EntryGraphResponse, GraphNode, GraphEdge } from "../entities/graph.entity";
|
||||
import type {
|
||||
EntryGraphResponse,
|
||||
GraphNode,
|
||||
GraphEdge,
|
||||
FullGraphResponse,
|
||||
GraphStatsResponse,
|
||||
} from "../entities/graph.entity";
|
||||
import { KnowledgeCacheService } from "./cache.service";
|
||||
import { Prisma } from "@prisma/client";
|
||||
|
||||
interface GraphFilterOptions {
|
||||
tags?: string[];
|
||||
status?: string;
|
||||
limit?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Service for knowledge graph operations
|
||||
@@ -13,6 +26,32 @@ export class GraphService {
|
||||
private readonly cache: KnowledgeCacheService
|
||||
) {}
|
||||
|
||||
/**
|
||||
* Get entry-centered graph view by slug
|
||||
* Helper method that looks up the entry ID first
|
||||
*/
|
||||
async getEntryGraphBySlug(
|
||||
workspaceId: string,
|
||||
slug: string,
|
||||
maxDepth = 1
|
||||
): Promise<EntryGraphResponse> {
|
||||
// Find entry by slug
|
||||
const entry = await this.prisma.knowledgeEntry.findUnique({
|
||||
where: {
|
||||
workspaceId_slug: {
|
||||
workspaceId,
|
||||
slug,
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
if (!entry) {
|
||||
throw new NotFoundException("Entry not found");
|
||||
}
|
||||
|
||||
return this.getEntryGraph(workspaceId, entry.id, maxDepth);
|
||||
}
|
||||
|
||||
/**
|
||||
* Get entry-centered graph view
|
||||
* Returns the entry and all connected nodes up to specified depth
|
||||
@@ -187,4 +226,245 @@ export class GraphService {
|
||||
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* Get full knowledge graph with optional filtering
|
||||
* Returns all entries and links in the workspace
|
||||
*/
|
||||
async getFullGraph(
|
||||
workspaceId: string,
|
||||
filters?: GraphFilterOptions
|
||||
): Promise<FullGraphResponse> {
|
||||
// Build where clause for entries
|
||||
const where: Prisma.KnowledgeEntryWhereInput = {
|
||||
workspaceId,
|
||||
};
|
||||
|
||||
if (filters?.status) {
|
||||
where.status = filters.status as Prisma.EnumEntryStatusFilter;
|
||||
}
|
||||
|
||||
if (filters?.tags && filters.tags.length > 0) {
|
||||
where.tags = {
|
||||
some: {
|
||||
tag: {
|
||||
slug: {
|
||||
in: filters.tags,
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// Build query options
|
||||
const queryOptions: {
|
||||
where: Prisma.KnowledgeEntryWhereInput;
|
||||
include: {
|
||||
tags: {
|
||||
include: {
|
||||
tag: true;
|
||||
};
|
||||
};
|
||||
};
|
||||
take?: number;
|
||||
orderBy: {
|
||||
updatedAt: "desc";
|
||||
};
|
||||
} = {
|
||||
where,
|
||||
include: {
|
||||
tags: {
|
||||
include: {
|
||||
tag: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
orderBy: {
|
||||
updatedAt: "desc",
|
||||
},
|
||||
};
|
||||
|
||||
if (filters?.limit !== undefined) {
|
||||
queryOptions.take = filters.limit;
|
||||
}
|
||||
|
||||
// Fetch entries
|
||||
const entries = await this.prisma.knowledgeEntry.findMany(queryOptions);
|
||||
|
||||
// Get entry IDs for link filtering
|
||||
const entryIds = entries.map((e) => e.id);
|
||||
|
||||
// Fetch all links between these entries
|
||||
const links = await this.prisma.knowledgeLink.findMany({
|
||||
where: {
|
||||
sourceId: { in: entryIds },
|
||||
targetId: { in: entryIds },
|
||||
resolved: true,
|
||||
},
|
||||
});
|
||||
|
||||
// Build nodes
|
||||
const nodes: GraphNode[] = entries.map((entry) => ({
|
||||
id: entry.id,
|
||||
slug: entry.slug,
|
||||
title: entry.title,
|
||||
summary: entry.summary,
|
||||
status: entry.status,
|
||||
tags: entry.tags.map(
|
||||
(et: { tag: { id: string; name: string; slug: string; color: string | null } }) => ({
|
||||
id: et.tag.id,
|
||||
name: et.tag.name,
|
||||
slug: et.tag.slug,
|
||||
color: et.tag.color,
|
||||
})
|
||||
),
|
||||
depth: 0, // Full graph has no depth concept
|
||||
isOrphan: false, // Will be calculated next
|
||||
}));
|
||||
|
||||
// Build edges
|
||||
const edges: GraphEdge[] = links.map((link) => ({
|
||||
id: link.id,
|
||||
sourceId: link.sourceId,
|
||||
targetId: link.targetId,
|
||||
linkText: link.linkText,
|
||||
}));
|
||||
|
||||
// Detect orphans (entries with no incoming or outgoing links)
|
||||
const connectedIds = new Set<string>();
|
||||
for (const edge of edges) {
|
||||
connectedIds.add(edge.sourceId);
|
||||
connectedIds.add(edge.targetId);
|
||||
}
|
||||
|
||||
let orphanCount = 0;
|
||||
for (const node of nodes) {
|
||||
if (!connectedIds.has(node.id)) {
|
||||
node.isOrphan = true;
|
||||
orphanCount++;
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
nodes,
|
||||
edges,
|
||||
stats: {
|
||||
totalNodes: nodes.length,
|
||||
totalEdges: edges.length,
|
||||
orphanCount,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Get graph statistics including orphan detection
|
||||
*/
|
||||
async getGraphStats(workspaceId: string): Promise<GraphStatsResponse> {
|
||||
// Get total counts
|
||||
const [totalEntries, totalLinks] = await Promise.all([
|
||||
this.prisma.knowledgeEntry.count({
|
||||
where: { workspaceId },
|
||||
}),
|
||||
this.prisma.knowledgeLink.count({
|
||||
where: {
|
||||
source: { workspaceId },
|
||||
resolved: true,
|
||||
},
|
||||
}),
|
||||
]);
|
||||
|
||||
// Calculate average links per entry
|
||||
const averageLinks = totalEntries > 0 ? totalLinks / totalEntries : 0;
|
||||
|
||||
// Find most connected entries using raw query for better performance
|
||||
const mostConnected = await this.prisma.$queryRaw<
|
||||
{
|
||||
id: string;
|
||||
slug: string;
|
||||
title: string;
|
||||
link_count: string;
|
||||
}[]
|
||||
>`
|
||||
SELECT
|
||||
e.id,
|
||||
e.slug,
|
||||
e.title,
|
||||
COUNT(DISTINCT l.id) as link_count
|
||||
FROM knowledge_entries e
|
||||
LEFT JOIN knowledge_links l ON (l.source_id = e.id OR l.target_id = e.id)
|
||||
WHERE e.workspace_id = ${workspaceId}::uuid
|
||||
AND (l.resolved = true OR l.id IS NULL)
|
||||
GROUP BY e.id, e.slug, e.title
|
||||
ORDER BY link_count DESC
|
||||
LIMIT 10
|
||||
`;
|
||||
|
||||
const mostConnectedEntries = mostConnected.map((entry) => ({
|
||||
id: entry.id,
|
||||
slug: entry.slug,
|
||||
title: entry.title,
|
||||
linkCount: parseInt(entry.link_count, 10),
|
||||
}));
|
||||
|
||||
// Find orphan entries (entries with no links)
|
||||
const orphanEntries = await this.prisma.knowledgeEntry.findMany({
|
||||
where: {
|
||||
workspaceId,
|
||||
AND: [
|
||||
{
|
||||
outgoingLinks: {
|
||||
none: {
|
||||
resolved: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
incomingLinks: {
|
||||
none: {
|
||||
resolved: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
select: {
|
||||
id: true,
|
||||
},
|
||||
});
|
||||
|
||||
// Get tag distribution
|
||||
const tagGroups = await this.prisma.$queryRaw<
|
||||
{
|
||||
tag_id: string;
|
||||
tag_name: string;
|
||||
entry_count: string;
|
||||
}[]
|
||||
>`
|
||||
SELECT
|
||||
t.id as tag_id,
|
||||
t.name as tag_name,
|
||||
COUNT(DISTINCT et.entry_id) as entry_count
|
||||
FROM knowledge_tags t
|
||||
LEFT JOIN knowledge_entry_tags et ON et.tag_id = t.id
|
||||
WHERE t.workspace_id = ${workspaceId}::uuid
|
||||
GROUP BY t.id, t.name
|
||||
ORDER BY entry_count DESC
|
||||
LIMIT 20
|
||||
`;
|
||||
|
||||
const tagDistribution = tagGroups.map((tag) => ({
|
||||
tagId: tag.tag_id,
|
||||
tagName: tag.tag_name,
|
||||
entryCount: parseInt(tag.entry_count, 10),
|
||||
}));
|
||||
|
||||
return {
|
||||
totalEntries,
|
||||
totalLinks,
|
||||
orphanEntries: orphanEntries.length,
|
||||
averageLinks,
|
||||
mostConnectedEntries,
|
||||
tagDistribution,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user