From f1cd4b164d75cec822544aafdaec3ec7a5cace8d Mon Sep 17 00:00:00 2001 From: Heewon Oh Date: Sun, 15 Nov 2026 06:43:53 +0900 Subject: [PATCH] fix(integrations): paginate and globally bound Linear sync, backlog pick and registry helpers (AGT-3421) Port of the remaining parts of b159fa8 (sprint/cycle5-30pt), which never reached main; the taskSource part already landed in #794. - Linear inbound sync applies its limit to the total imported count across pages and reports the durable created/updated count when it fails partway. - drainLinearConnection rejects a missing or repeated endCursor instead of looping or duplicating nodes. It moves to linearPagination.ts with the page constants (re-exported from linear.ts) to keep linear.ts under its size base. - getNextBacklogIssue ranks over every drained page (bounded), not page one. - fetchIssue bounds comments/labels reads (first: 50); the change originally targeted linearTasks.ts, which has since been folded into linear.ts. - Registry risk/status helpers take limit/offset (cap 200); entities by issue id are batch-loaded with a per-issue cap of 200. - Row mapping moved to sqliteStoreRows.ts to keep sqliteStore.ts small. --- src/issues/linearBridge.test.ts | 146 +++++++++++++++ src/issues/linearBridge.ts | 169 +++++++++++++---- src/linear/linear.test.ts | 76 ++++++-- src/linear/linear.ts | 73 ++++---- src/linear/linearPagination.ts | 60 ++++++ src/registry/sqliteStore.test.ts | 85 ++++++++- src/registry/sqliteStore.ts | 306 ++++++++----------------------- src/registry/sqliteStoreRows.ts | 256 ++++++++++++++++++++++++++ 8 files changed, 845 insertions(+), 326 deletions(-) create mode 100644 src/issues/linearBridge.test.ts create mode 100644 src/linear/linearPagination.ts create mode 100644 src/registry/sqliteStoreRows.ts diff --git a/src/issues/linearBridge.test.ts b/src/issues/linearBridge.test.ts new file mode 100644 index 00000000..73faa425 --- /dev/null +++ b/src/issues/linearBridge.test.ts @@ -0,0 +1,146 @@ +// ============================================ +// OpenSwarm - Linear bridge inbound sync pagination tests (AGT-3421) +// ============================================ + +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; +import { SqliteIssueStore } from './sqliteStore.js'; +import { drainLinearIssuesToStore, LINEAR_SYNC_MAX_PAGES, type LinearIssuePage } from './linearBridge.js'; + +function linearNode(id: string, priority = 3): Record { + return { + id, + identifier: `INT-${id}`, + title: `Linear issue ${id}`, + url: `https://linear.app/i/${id}`, + description: 'desc', + priority, + state: Promise.resolve({ name: 'Todo' }), + }; +} + +function page(nodes: unknown[], opts?: { hasNextPage?: boolean; endCursor?: string }): LinearIssuePage { + return { + nodes: nodes as any[], + hasNextPage: opts?.hasNextPage ?? false, + endCursor: opts?.endCursor, + }; +} + +describe('drainLinearIssuesToStore', () => { + let store: SqliteIssueStore; + let consoleError: ReturnType; + let consoleWarn: ReturnType; + + beforeEach(() => { + store = new SqliteIssueStore(':memory:'); + consoleError = vi.spyOn(console, 'error').mockImplementation(() => {}); + consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + }); + + afterEach(() => { + consoleError.mockRestore(); + consoleWarn.mockRestore(); + store.close(); + }); + + it('applies the limit to the TOTAL imported count across pages, not per page', async () => { + // Two pages of 30 with a total limit of 50: 50 must be imported and the + // run must stop there (the old code capped each page at `limit`). + const pages = [ + page(Array.from({ length: 30 }, (_, i) => linearNode(`a${i}`)), { hasNextPage: true, endCursor: 'c1' }), + page(Array.from({ length: 30 }, (_, i) => linearNode(`b${i}`)), { hasNextPage: false }), + ]; + let calls = 0; + const fetchPage = async () => pages[calls++] ?? page([]); + + const progress = await drainLinearIssuesToStore(store, 'proj', fetchPage, 50); + + expect(progress.created).toBe(50); + expect(progress.updated).toBe(0); + expect(progress.truncated).toBe(true); + expect(progress.failed).toBeUndefined(); + expect(calls).toBe(2); // never fetched a third page + // Durable: the 50th imported issue is queryable by its linear id. + expect(store.getIssueByLinearId('b19')).not.toBeNull(); + expect(store.listIssues({ source: 'linear', limit: 500, offset: 0 }).total).toBe(50); + }); + + it('bails with an explicit error on a cursor that never advances (repeated)', async () => { + const fetchPage = async (after?: string) => + page(Array.from({ length: 3 }, (_, i) => linearNode(`n${after ?? '0'}-${i}`)), { + hasNextPage: true, + endCursor: 'stuck', + }); + + const progress = await drainLinearIssuesToStore(store, 'proj', fetchPage, 1000); + + // Terminated BEFORE applying the re-served window: only page one is durable. + expect(progress.failed?.message).toMatch(/repeated cursor/); + expect(progress.created).toBe(3); + expect(store.listIssues({ source: 'linear', limit: 500, offset: 0 }).total).toBe(3); + expect(consoleError).toHaveBeenCalledWith( + expect.stringContaining('created 3, updated 0'), + expect.any(Error), + ); + }); + + it('bails with an explicit error on a missing cursor', async () => { + const fetchPage = async () => + page([linearNode('only')], { hasNextPage: true, endCursor: undefined }); + + const progress = await drainLinearIssuesToStore(store, 'proj', fetchPage, 1000); + + // The first page already claims more data but offers no cursor to continue + // with — refuse to apply it rather than import an unverifiable window. + expect(progress.failed?.message).toMatch(/missing cursor/); + expect(progress.created).toBe(0); + }); + + it('reports the durable import count when an issue fails mid-run', async () => { + // First issue creates fine; the second (an existing local issue) fails to + // update. Everything before the failure is committed and reported. + store.createIssue({ projectId: 'proj', title: 'existing', source: 'linear', linearId: 'lin-2' }); + vi.spyOn(store, 'updateIssue').mockImplementation(() => { + throw new Error('update exploded'); + }); + + const fetchPage = async () => + page([linearNode('lin-1'), linearNode('lin-2'), linearNode('lin-3')], { hasNextPage: false }); + + const progress = await drainLinearIssuesToStore(store, 'proj', fetchPage, 1000); + + expect(progress.created).toBe(1); + expect(progress.updated).toBe(0); + expect(progress.failed).toBeInstanceOf(Error); + expect(progress.failed?.message).toBe('update exploded'); + expect(store.getIssueByLinearId('lin-1')).not.toBeNull(); // durable + expect(store.getIssueByLinearId('lin-3')).toBeNull(); // never reached + expect(consoleError).toHaveBeenCalledWith( + expect.stringContaining('created 1, updated 0'), + expect.anything(), + ); + }); + + it('stops deterministically at the page cap even with an endless connection', async () => { + let cursor = 0; + const fetchPage = async () => page([linearNode(`p${cursor}`)], { + hasNextPage: true, + endCursor: `c${++cursor}`, + }); + + const progress = await drainLinearIssuesToStore(store, 'proj', fetchPage, Number.MAX_SAFE_INTEGER); + + expect(cursor).toBe(LINEAR_SYNC_MAX_PAGES); + expect(progress.created).toBe(LINEAR_SYNC_MAX_PAGES); + expect(progress.truncated).toBe(true); + expect(consoleWarn).toHaveBeenCalledWith(expect.stringContaining('페이지 상한')); + }); + + it('reports a clean end when the connection terminates on its own', async () => { + const fetchPage = async () => page([linearNode('a')], { hasNextPage: false }); + + const progress = await drainLinearIssuesToStore(store, 'proj', fetchPage, 50); + + expect(progress).toEqual({ created: 1, updated: 0, truncated: false }); + }); +}); diff --git a/src/issues/linearBridge.ts b/src/issues/linearBridge.ts index 4bbee884..f0b8b0db 100644 --- a/src/issues/linearBridge.ts +++ b/src/issues/linearBridge.ts @@ -161,6 +161,111 @@ export function initLinearBridge(apiKey: string, teamId: string): Promise return linearInitPromise; } +/** + * Page size for the inbound sync cursor loop. Linear reliably serves pages of + * 50; the sync limit is applied to the TOTAL across pages, not per page. + */ +const LINEAR_SYNC_PAGE_SIZE = 50; +/** + * Hard page cap for one sync run (50 × 20 = 1000 issues). Bounds worst-case + * API work when the workspace has far more matching issues than the limit: + * the run stops deterministically and reports what it committed. + */ +export const LINEAR_SYNC_MAX_PAGES = 20; + +/** One page of the Linear issue connection, adapted from the SDK response. */ +export interface LinearIssuePage { + nodes: any[]; + hasNextPage: boolean; + endCursor?: string; +} + +/** Durable outcome of an inbound sync run. */ +export interface LinearSyncProgress { + created: number; + updated: number; + /** True when the run stopped at the total limit or page cap with data left. */ + truncated: boolean; + /** The error that aborted the run; everything before it is already committed. */ + failed?: Error; +} + +/** + * Drain a Linear issue connection page by page, applying each issue to the + * local store. `maxItems` caps the TOTAL imported count across pages (never + * per page). Termination is deterministic: total limit, page cap, or an + * exhausted connection. A missing/repeated cursor aborts the run with an + * explicit error instead of looping forever. + * + * Never throws: a per-issue failure (or cursor anomaly) is returned as + * `failed` alongside the counts that were durably committed before it. + */ +export async function drainLinearIssuesToStore( + store: SqliteIssueStore, + projectId: string, + fetchPage: (after: string | undefined) => Promise, + maxItems: number, +): Promise { + let created = 0; + let updated = 0; + let after: string | undefined; + + try { + for (let page = 0; page < LINEAR_SYNC_MAX_PAGES; page++) { + const conn = await fetchPage(after); + // Cursor sanity BEFORE applying: a response whose endCursor is absent or + // identical to the cursor we just used re-served the same window — bail + // instead of double-applying its nodes or looping forever. (AGT-3421) + if (conn.hasNextPage === true && (!conn.endCursor || conn.endCursor === after)) { + throw new Error( + `Linear inbound sync pagination returned a ${conn.endCursor ? 'repeated' : 'missing'} cursor on page ${page + 1}`, + ); + } + for (const issue of conn.nodes) { + // The limit is global: stop as soon as the total across all pages is met. + if (created + updated >= maxItems) { + return { created, updated, truncated: true }; + } + const existing = findByLinearId(store, issue.id); + const linearData = await mapLinearToLocal(issue, projectId); + + if (existing) { + // 이미 존재 → 업데이트 + store.updateIssue(existing.id, linearData); + updated++; + } else { + // 새 이슈 → 생성 + store.createIssue({ + ...linearData, + source: 'linear', + linearId: issue.id, + linearIdentifier: issue.identifier, + linearUrl: issue.url, + }); + created++; + } + } + + if (conn.hasNextPage !== true) { + return { created, updated, truncated: false }; + } + after = conn.endCursor; + } + + // Page cap exhausted while the connection still reported more pages. + console.warn(`[LinearBridge] 페이지 상한 ${LINEAR_SYNC_MAX_PAGES}개 도달 — 이번 동기화는 여기서 멈춥니다.`); + return { created, updated, truncated: true }; + } catch (err) { + const failed = err instanceof Error ? err : new Error(String(err)); + // Partial failure: everything applied so far is durable — say so. + console.error( + `[LinearBridge] 동기화 중단 — 지금까지 커밋됨: created ${created}, updated ${updated}`, + failed, + ); + return { created, updated, truncated: false, failed }; + } +} + /** * Linear → 로컬: Linear 이슈를 로컬 DB에 동기화 */ @@ -178,46 +283,36 @@ export async function syncFromLinear( const states = options?.states ?? ['In Progress', 'Todo', 'Backlog', 'In Review', 'Done', 'Canceled', 'Cancelled']; const limit = options?.limit ?? 50; - let created = 0; - let updated = 0; - - try { - const issues = await linearClient.issues({ - filter: { - team: { id: { eq: linearTeamId } }, - state: { name: { in: states } }, - }, - first: limit, - orderBy: 'updatedAt', - }); - - for (const issue of issues.nodes) { - const existing = findByLinearId(store, issue.id); - const linearData = await mapLinearToLocal(issue, projectId); - - if (existing) { - // 이미 존재 → 업데이트 - store.updateIssue(existing.id, linearData); - updated++; - } else { - // 새 이슈 → 생성 - store.createIssue({ - ...linearData, - source: 'linear', - linearId: issue.id, - linearIdentifier: issue.identifier, - linearUrl: issue.url, - }); - created++; - } - } + const progress = await drainLinearIssuesToStore( + store, + projectId, + async (after) => { + const conn = await linearClient.issues({ + filter: { + team: { id: { eq: linearTeamId } }, + state: { name: { in: states } }, + }, + first: LINEAR_SYNC_PAGE_SIZE, + after, + orderBy: 'updatedAt', + }); + return { + nodes: conn.nodes, + hasNextPage: conn.pageInfo?.hasNextPage === true, + endCursor: conn.pageInfo?.endCursor, + }; + }, + limit, + ); - console.log(`[LinearBridge] 동기화 완료 — created: ${created}, updated: ${updated}`); - } catch (err) { - console.error('[LinearBridge] 동기화 실패:', err); + if (progress.failed) { + console.error('[LinearBridge] 동기화 실패:', progress.failed); + } else { + const truncatedNote = progress.truncated ? ` (limit ${limit} 도달)` : ''; + console.log(`[LinearBridge] 동기화 완료 — created: ${progress.created}, updated: ${progress.updated}${truncatedNote}`); } - return { created, updated }; + return { created: progress.created, updated: progress.updated }; } /** diff --git a/src/linear/linear.test.ts b/src/linear/linear.test.ts index d2179a04..6672ed67 100644 --- a/src/linear/linear.test.ts +++ b/src/linear/linear.test.ts @@ -10,8 +10,8 @@ vi.mock('@linear/sdk', () => ({ LinearClient: vi.fn() })); describe('active/backlog inventory bounds', () => { function installIssueClient(opts: { - nodes: Array>; - fetchNextNodes?: Array>; + /** pages[0] is served by the initial issues() call; the rest via fetchNext(). */ + pages: Array>>; expectedFirst: number; }) { clearLinearCache(); @@ -30,11 +30,13 @@ describe('active/backlog inventory bounds', () => { }); const connection = { - nodes: opts.nodes.map(makeIssue), - pageInfo: { hasNextPage: Boolean(opts.fetchNextNodes?.length) }, + nodes: opts.pages[0].map(makeIssue), + pageInfo: { hasNextPage: opts.pages.length > 1, endCursor: 'cursor-0' }, fetchNext: async () => { - connection.nodes.push(...(opts.fetchNextNodes ?? []).map(makeIssue)); - connection.pageInfo.hasNextPage = false; + const next = opts.pages.splice(1, 1)[0]; + connection.nodes.push(...next.map(makeIssue)); + connection.pageInfo.hasNextPage = opts.pages.length > 1; + connection.pageInfo.endCursor = `cursor-${opts.pages.length}`; return connection; }, }; @@ -68,8 +70,7 @@ describe('active/backlog inventory bounds', () => { priority: 3, })); const { fakeClient } = installIssueClient({ - nodes: page1, - fetchNextNodes: page2, + pages: [page1, page2], expectedFirst: LINEAR_ACTIVE_PAGE_SIZE, }); @@ -91,7 +92,7 @@ describe('active/backlog inventory bounds', () => { priority: i === 0 ? 0 : 1, })); const { fakeClient } = installIssueClient({ - nodes, + pages: [nodes], expectedFirst: LINEAR_BACKLOG_PAGE_SIZE, }); const next = await getNextBacklogIssue('worker'); @@ -100,6 +101,39 @@ describe('active/backlog inventory bounds', () => { })); expect(next?.identifier).toBe('AGT-BL-1'); }); + + it('ranks the backlog pick over ALL pages, not just the first (AGT-3421)', async () => { + // The globally best issue (priority 1) sits on the LAST page; page one + // holds only priority-3 fillers. A first-page-only ranking would miss it. + const filler = (i: number) => ({ + id: `fill-${i}`, + identifier: `AGT-F-${i}`, + title: `Filler ${i}`, + url: `https://linear.app/i/f${i}`, + description: null, + priority: 3, + }); + const winner = { + id: 'winner', + identifier: 'AGT-WIN', + title: 'Real next issue', + url: 'https://linear.app/i/win', + description: null, + priority: 1, + }; + const { fakeClient } = installIssueClient({ + pages: [ + Array.from({ length: LINEAR_BACKLOG_PAGE_SIZE }, (_, i) => filler(i)), + Array.from({ length: LINEAR_BACKLOG_PAGE_SIZE }, (_, i) => filler(100 + i)), + [winner, filler(200)], + ], + expectedFirst: LINEAR_BACKLOG_PAGE_SIZE, + }); + + const next = await getNextBacklogIssue('worker'); + expect(fakeClient.issues).toHaveBeenCalledTimes(1); + expect(next?.identifier).toBe('AGT-WIN'); + }); }); describe('effectCommentId', () => { @@ -201,15 +235,17 @@ describe('parseBlockerIdentifiers', () => { describe('drainLinearConnection', () => { function connection(pages: Array>) { // Mirrors the SDK contract: fetchNext() appends the next page onto the - // same connection's nodes and resolves the connection itself. + // same connection's nodes and resolves the connection itself, with an + // advancing pagination cursor per page. let page = 0; const conn = { nodes: [...pages[0]], - pageInfo: { hasNextPage: pages.length > 1 }, + pageInfo: { hasNextPage: pages.length > 1, endCursor: 'cursor-0' }, fetchNext: async () => { page += 1; conn.nodes.push(...pages[page]); conn.pageInfo.hasNextPage = page < pages.length - 1; + conn.pageInfo.endCursor = `cursor-${page}`; return conn; }, }; @@ -229,13 +265,25 @@ describe('drainLinearConnection', () => { await expect(drainLinearConnection(connection([[{ id: 'only' }]]))).resolves.toEqual([{ id: 'only' }]); }); - it('stops on a pagination cursor that never terminates', async () => { + it('rejects a pagination cursor that never advances (missing cursor)', async () => { + // AGT-3421: a page whose endCursor is absent means the API re-served the + // same window — bail with an explicit error instead of looping forever. const conn = { nodes: [{ id: 'x' }], pageInfo: { hasNextPage: true }, - fetchNext: async () => conn, + fetchNext: async () => ({ nodes: [{ id: 'x' }], pageInfo: { hasNextPage: true } }), + }; + await expect(drainLinearConnection(conn)).rejects.toThrow(/missing cursor/); + }); + + it('rejects a pagination cursor that never advances (repeated cursor)', async () => { + const page = { nodes: [{ id: 'x' }], pageInfo: { hasNextPage: true, endCursor: 'stuck' } }; + const conn = { + nodes: [{ id: 'first' }], + pageInfo: { hasNextPage: true, endCursor: 'stuck' }, + fetchNext: async () => page, }; - await expect(drainLinearConnection(conn)).resolves.toEqual([{ id: 'x' }]); + await expect(drainLinearConnection(conn)).rejects.toThrow(/repeated cursor/); }); it('honors an explicit maxPages cap for active-inventory drains', async () => { diff --git a/src/linear/linear.ts b/src/linear/linear.ts index 30ccfdde..de3e880a 100644 --- a/src/linear/linear.ts +++ b/src/linear/linear.ts @@ -9,6 +9,16 @@ import { formatAutomationComment, formatPairDialogue, type CommentSection } from import { completionTargetState, type PairCompleteStats } from '../automation/taskSource.js'; import { setLinearClient } from './projectUpdater.js'; import { withRateLimit } from '../support/rateLimiter.js'; +import { + drainLinearConnection, + LINEAR_ACTIVE_ENRICH_CAP, + LINEAR_ACTIVE_MAX_PAGES, + LINEAR_ACTIVE_PAGE_SIZE, + LINEAR_BACKLOG_MAX_CANDIDATES, + LINEAR_BACKLOG_MAX_PAGES, + LINEAR_BACKLOG_PAGE_SIZE, + LINEAR_RELATED_PAGE_SIZE, +} from './linearPagination.js'; import { c, status } from '../support/colors.js'; import { readFile } from 'node:fs/promises'; import { homedir, tmpdir } from 'node:os'; @@ -392,40 +402,16 @@ export async function listTeams(cred?: LinearCredential): Promise ({ id: t.id, key: t.key, name: t.name })); } -/** Soft page guard for SDK connection drains (teams/projects pickers). */ -const DRAIN_PAGE_GUARD = 40; - -/** - * Hard caps for direct active/backlog SDK list paths. These paths still do - * per-issue enrichment, so both page count and aggregate enrichment work must - * be bounded (unlike the nested GraphQL fetchIssuesForStates path). - */ -export const LINEAR_ACTIVE_PAGE_SIZE = 50; -export const LINEAR_ACTIVE_MAX_PAGES = 4; -export const LINEAR_ACTIVE_ENRICH_CAP = LINEAR_ACTIVE_PAGE_SIZE * LINEAR_ACTIVE_MAX_PAGES; -export const LINEAR_BACKLOG_PAGE_SIZE = 10; -export const LINEAR_RELATED_PAGE_SIZE = 50; - -/** - * Follow a Linear SDK connection to its last page and return every node. - * The SDK's fetchNext() appends each fetched page onto the same connection, - * so a single `first: N` read silently truncates larger workspaces. The page - * guard only bounds a misbehaving pagination cursor, not real data. - */ -export async function drainLinearConnection( - connection: any, // cxt-ignore: type_safety — SDK connection - maxPages = DRAIN_PAGE_GUARD, -): Promise { - let conn: any = connection; - // `maxPages` counts the page already present on the connection. - let pages = 1; - const pageCap = Math.max(1, Math.min(DRAIN_PAGE_GUARD, Math.trunc(maxPages) || DRAIN_PAGE_GUARD)); - while (conn?.pageInfo?.hasNextPage && typeof conn.fetchNext === 'function' && pages < pageCap) { - conn = await withRateLimit('linear', () => conn.fetchNext()); - pages += 1; - } - return conn?.nodes ?? []; -} +export { + drainLinearConnection, + LINEAR_ACTIVE_ENRICH_CAP, + LINEAR_ACTIVE_MAX_PAGES, + LINEAR_ACTIVE_PAGE_SIZE, + LINEAR_BACKLOG_MAX_CANDIDATES, + LINEAR_BACKLOG_MAX_PAGES, + LINEAR_BACKLOG_PAGE_SIZE, + LINEAR_RELATED_PAGE_SIZE, +} from './linearPagination.js'; /** * List projects within a team — for the `openswarm init` picker. Accepts an @@ -534,11 +520,16 @@ export async function getNextBacklogIssue( state: { name: { in: ['Backlog', 'Todo'] } }, labels: { name: { eq: agentLabel } }, }, - first: LINEAR_BACKLOG_PAGE_SIZE, // Fetch a bounded window and sort by priority + first: LINEAR_BACKLOG_PAGE_SIZE, // page size — the pick ranks over every drained page })); + // Rank over ALL pages (bounded): the first page alone can hold only low + // priority fillers while the true next issue sits pages deep. + const candidates = (await drainLinearConnection(issues, LINEAR_BACKLOG_MAX_PAGES)) + .slice(0, LINEAR_BACKLOG_MAX_CANDIDATES); + // Sort by priority (lower = higher priority: 1=Urgent, 4=Low, 0=None) - const sorted = [...issues.nodes].slice(0, LINEAR_BACKLOG_PAGE_SIZE).sort((a, b) => { + const sorted = [...candidates].sort((a, b) => { // Push priority 0 (None) to the end const pa = a.priority === 0 ? 999 : a.priority; const pb = b.priority === 0 ? 999 : b.priority; @@ -563,8 +554,8 @@ export async function getNextBacklogIssue( description: issue.description ?? undefined, state: state?.name ?? 'Unknown', priority: issue.priority, - labels: labels.nodes.map((l) => l.name), - comments: comments.nodes.map((c) => ({ + labels: labels.nodes.map((l: { name: string }) => l.name), + comments: comments.nodes.map((c: { id: string; body: string; createdAt: Date }) => ({ id: c.id, body: c.body, createdAt: c.createdAt.toISOString(), @@ -886,9 +877,11 @@ async function fetchIssue(issueIdOrIdentifier: string): Promise { + let conn: any = connection; + // `maxPages` counts the page already present on the connection. + let pages = 1; + // A page whose endCursor is absent or identical to the previous one means the + // API re-served the same page — bail explicitly instead of looping (or + // duplicating nodes) until the page guard trips. (AGT-3421) + let lastCursor: string | undefined = conn?.pageInfo?.endCursor ?? undefined; + const pageCap = Math.max(1, Math.min(DRAIN_PAGE_GUARD, Math.trunc(maxPages) || DRAIN_PAGE_GUARD)); + while (conn?.pageInfo?.hasNextPage && typeof conn.fetchNext === 'function' && pages < pageCap) { + conn = await withRateLimit('linear', () => conn.fetchNext()); + pages += 1; + const cursor = conn?.pageInfo?.endCursor; + if (!cursor || cursor === lastCursor) { + throw new Error( + `Linear pagination returned a ${cursor ? 'repeated' : 'missing'} cursor after ${pages - 1} fetched page(s)`, + ); + } + lastCursor = cursor; + } + return conn?.nodes ?? []; +} diff --git a/src/registry/sqliteStore.test.ts b/src/registry/sqliteStore.test.ts index a207efb0..e4422e71 100644 --- a/src/registry/sqliteStore.test.ts +++ b/src/registry/sqliteStore.test.ts @@ -2,7 +2,7 @@ import { afterEach, describe, expect, it } from 'vitest'; import { mkdtempSync, rmSync } from 'node:fs'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; -import { LIST_ENTITIES_MAX_LIMIT, SqliteRegistryStore } from './sqliteStore.js'; +import { HELPER_QUERY_MAX_LIMIT, ISSUE_LINK_MAX_ENTITIES, LIST_ENTITIES_MAX_LIMIT, SqliteRegistryStore } from './sqliteStore.js'; let dir: string | undefined; let store: SqliteRegistryStore | undefined; @@ -23,7 +23,7 @@ describe('SqliteRegistryStore safe queries', () => { it('treats malformed FTS and LIKE metacharacters as literal input', () => { const registry = createStore(); registry.registerEntity({ projectId: 'p', kind: 'function', name: 'alpha%_\\beta', filePath: 'src/a.ts' }); - expect(() => registry.listEntities({ search: '" OR NOT (' })).not.toThrow(); + expect(() => registry.listEntities({ search: '" OR NOT (', limit: 20, offset: 0 })).not.toThrow(); expect(() => registry.searchEntities('%_\\')).not.toThrow(); expect(registry.searchEntities('%_\\').map((entity) => entity.name)).toContain('alpha%_\\beta'); }); @@ -35,7 +35,7 @@ describe('SqliteRegistryStore safe queries', () => { for (const entity of [a, b]) { registry.linkIssue(entity.id, 'INT-1'); registry.addTag(entity.id, 'layer', 'api'); - registry.addWarning(entity.id, 'warning', 'complexity', 'warning'); + registry.addWarning(entity.id, 'warning', 'correctness', 'warning'); } expect(registry.getEntitiesByIssueId('INT-1', 'a').map((entity) => entity.id)).toEqual([a.id]); expect(registry.entitiesByTag('layer', 'api', 'b').map((entity) => entity.id)).toEqual([b.id]); @@ -164,3 +164,82 @@ describe('SqliteRegistryStore.getStats (AGT-4668)', () => { expect(registry.getStats('q', { maxAgeMs: 60_000 }).total).toBe(1); }); }); + +// AGT-3421: the risk/status helpers and issue-link lookups were unbounded +// full scans with an N+1 per row — bound and batch them. +describe('bounded helper and issue-link queries (AGT-3421)', () => { + it('paginates the risk/status helper queries', () => { + const registry = createStore(); + for (let i = 0; i < 6; i++) { + registry.registerEntity({ + projectId: 'p', kind: 'function', name: `dep${i}`, filePath: `src/dep${i}.ts`, status: 'deprecated', + }); + } + for (let i = 0; i < 4; i++) { + registry.registerEntity({ + projectId: 'p', kind: 'function', name: `risk${i}`, filePath: `src/risk${i}.ts`, + hasTests: false, riskLevel: 'high', + }); + } + registry.registerEntity({ projectId: 'p', kind: 'function', name: 'good', filePath: 'src/g.ts', hasTests: true }); + + const deprecatedPage1 = registry.deprecatedEntities('p', 4, 0); + const deprecatedPage2 = registry.deprecatedEntities('p', 4, 4); + expect(deprecatedPage1).toHaveLength(4); + expect(deprecatedPage2).toHaveLength(2); + const page1Ids = new Set(deprecatedPage1.map(e => e.id)); + expect(deprecatedPage2.every(e => !page1Ids.has(e.id))).toBe(true); + + const untestedPage1 = registry.untestedEntities('p', 2, 0); + const untestedPage2 = registry.untestedEntities('p', 2, 2); + expect(untestedPage1).toHaveLength(2); + expect(untestedPage2).toHaveLength(2); + expect(new Set([...untestedPage1, ...untestedPage2]).size).toBe(4); + + expect(registry.highRiskEntities('p')).toHaveLength(4); + expect(registry.highRiskEntities('p', 2, 2)).toHaveLength(2); + // Small limit pages do not lose data across offsets. + expect(registry.deprecatedEntities('p', 1000, 0)).toHaveLength(6); + }); + + it('clamps helper page sizes and caps the entities loaded per issue id', () => { + const registry = createStore(); + // HELPER_QUERY_MAX_LIMIT + 5 high-risk entities, 3 more links than + // ISSUE_LINK_MAX_ENTITIES: both answers must be capped, not full scans. + const total = HELPER_QUERY_MAX_LIMIT + 5; + for (let i = 0; i < total; i++) { + const entity = registry.registerEntity({ + projectId: 'p', kind: 'function', name: `cap${i}`, filePath: `src/cap${i}.ts`, riskLevel: 'high', + }); + if (i < ISSUE_LINK_MAX_ENTITIES + 3) registry.linkIssue(entity.id, 'INT-CAP'); + } + + expect(registry.highRiskEntities('p', 1_000_000, 0)).toHaveLength(HELPER_QUERY_MAX_LIMIT); + const linked = registry.getEntitiesByIssueId('INT-CAP'); + expect(linked).toHaveLength(ISSUE_LINK_MAX_ENTITIES); + // Batch path keeps relation hydration intact. + expect(linked.every(e => e.projectId === 'p')).toBe(true); + }); + + it('batch-loads entities by issue id and preserves link coverage across projects', () => { + const registry = createStore(); + const a1 = registry.registerEntity({ projectId: 'a', kind: 'function', name: 'a1', filePath: 'src/a1.ts' }); + const a2 = registry.registerEntity({ projectId: 'a', kind: 'function', name: 'a2', filePath: 'src/a2.ts' }); + const a3 = registry.registerEntity({ projectId: 'a', kind: 'function', name: 'a3', filePath: 'src/a3.ts' }); + const b1 = registry.registerEntity({ projectId: 'b', kind: 'function', name: 'b1', filePath: 'src/b1.ts' }); + for (const entity of [a1, a2, a3, b1]) { + registry.linkIssue(entity.id, 'INT-9'); + registry.addTag(entity.id, 'layer', 'api'); + registry.addWarning(entity.id, 'warning', 'correctness', 'w'); + } + + const linked = registry.getEntitiesByIssueId('INT-9', 'a'); + expect(new Set(linked.map(e => e.id))).toEqual(new Set([a1.id, a2.id, a3.id])); + expect(linked.every(e => e.projectId === 'a')).toBe(true); + // Relations arrive through the batch loaders, not the per-row path. + expect(linked.every(e => e.tags.length === 1 && e.warnings.length === 1 && e.linkedIssueIds.includes('INT-9'))).toBe(true); + + expect(registry.getEntitiesByIssueId('INT-9', 'b').map(e => e.id)).toEqual([b1.id]); + expect(registry.getEntitiesByIssueId('INT-404')).toEqual([]); + }); +}); diff --git a/src/registry/sqliteStore.ts b/src/registry/sqliteStore.ts index 97edf05e..44dcb0d3 100644 --- a/src/registry/sqliteStore.ts +++ b/src/registry/sqliteStore.ts @@ -17,14 +17,37 @@ import type { WarningSeverity, WarningCategory, RelationType, FileBrief, RegistryStats, } from './schema.js'; +import { + SQLITE_IN_CHUNK_SIZE, + rowToEntity as mapRowToEntity, + rowToEvent as mapRowToEvent, + rowToWarning as mapRowToWarning, + rowsToEntities as mapRowsToEntities, + type EntityRow, type EventRow, type IssueLinkRow, type RelationRow, type WarningRow, + type CountRow, type TagRow, type MemoryLinkRow, +} from './sqliteStoreRows.js'; const DEFAULT_DB_PATH = resolve(homedir(), '.openswarm', 'registry.db'); -const SQLITE_IN_CHUNK_SIZE = 500; /** Store-level page cap for listEntities — callers must paginate with this size. */ export const LIST_ENTITIES_MAX_LIMIT = 5_000; export const LIST_ENTITIES_DEFAULT_LIMIT = 50; +/** + * Store-level page cap for the risk/status helper queries (deprecated, + * untested, high-risk). These were unbounded full-table scans; callers that + * need more must paginate with limit/offset (the GraphQL resolvers route + * through the bounded listEntities instead). (AGT-3421) + */ +export const HELPER_QUERY_MAX_LIMIT = 200; + +/** + * Cap on entities loaded per issue-id lookup. A scanner that links every + * entity to one issue must not drag the whole registry (with its tags, + * warnings, and links) into memory; callers needing more must chunk by issue. + */ +export const ISSUE_LINK_MAX_ENTITIES = 200; + function clampInteger(value: number, fallback: number, maximum = Number.MAX_SAFE_INTEGER): number { if (!Number.isFinite(value)) return fallback; return Math.min(maximum, Math.max(0, Math.trunc(value))); @@ -83,81 +106,6 @@ export interface EventData { actor?: string; } -// ============ DB Row 타입 (better-sqlite3 반환값) ============ - -interface EntityRow { - id: string; - project_id: string; - kind: string; - name: string; - qualified_name: string; - file_path: string; - line_start: number | null; - line_end: number | null; - signature: string | null; - status: string; - deprecated_at: string | null; - deprecated_reason: string | null; - has_tests: number; - test_file: string | null; - author: string | null; - maintainer: string | null; - complexity_score: number | null; - risk_level: string; - description: string | null; - notes: string | null; - knowledge_node_id: string | null; - created_at: string; - updated_at: string; -} - -interface WarningRow { - id: string; - entity_id: string; - severity: string; - category: string; - message: string; - resolved: number; - resolved_at: string | null; - created_at: string; -} - -interface EventRow { - id: string; - entity_id: string; - type: string; - old_value: string | null; - new_value: string | null; - content: string | null; - actor: string; - created_at: string; -} - -interface TagRow { - tag: string; - value: string | null; -} - -interface RelationRow { - target_id: string; - target_name: string; - relation_type: string; -} - -interface CountRow { - cnt: number; -} - -interface IssueLinkRow { - entity_id: string; - issue_id: string; -} - -interface MemoryLinkRow { - entity_id: string; - memory_id: string; -} - // ============ Store 구현 ============ export class SqliteRegistryStore { @@ -731,20 +679,32 @@ export class SqliteRegistryStore { ).all(entityId) as IssueLinkRow[]).map(r => r.issue_id); } - /** 이슈 ID로 연결된 엔티티 ID 목록 반환 (역방향 조회) */ + /** 이슈 ID로 연결된 엔티티 목록 반환 (역방향 조회 — 배치 로딩 + 상한 적용) */ getEntitiesByIssueId(issueId: string, projectId?: string): CodeEntity[] { - const rows = this.db.prepare( + const linkRows = this.db.prepare( `SELECT l.entity_id, l.issue_id FROM code_entity_issue_links l JOIN code_entities e ON e.id = l.entity_id - WHERE l.issue_id = ? ${projectId ? 'AND e.project_id = ?' : ''}` - ).all(...(projectId ? [issueId, projectId] : [issueId])) as IssueLinkRow[]; - - const entities: CodeEntity[] = []; - for (const row of rows) { - const entity = this.getEntity(row.entity_id); - if (entity) entities.push(entity); + WHERE l.issue_id = ? ${projectId ? 'AND e.project_id = ?' : ''} + LIMIT ?` + ).all(...(projectId ? [issueId, projectId] : [issueId]), ISSUE_LINK_MAX_ENTITIES) as IssueLinkRow[]; + + if (linkRows.length === 0) return []; + + // Batch-load the linked entities (chunked IN) instead of one getEntity() + // call per row; preserve the linked_at order of the link rows. + const orderedIds = [...new Set(linkRows.map(r => r.entity_id))]; + const rows: EntityRow[] = []; + for (let i = 0; i < orderedIds.length; i += SQLITE_IN_CHUNK_SIZE) { + const chunk = orderedIds.slice(i, i + SQLITE_IN_CHUNK_SIZE); + rows.push(...this.db.prepare( + `SELECT * FROM code_entities WHERE id IN (${chunk.map(() => '?').join(',')})` + ).all(...chunk) as EntityRow[]); } - return entities; + const entityById = new Map(this.rowsToEntities(rows).map(e => [e.id, e])); + return orderedIds.flatMap((id) => { + const entity = entityById.get(id); + return entity ? [entity] : []; + }); } linkMemory(entityId: string, memoryId: string): void { @@ -830,19 +790,27 @@ export class SqliteRegistryStore { }; } - deprecatedEntities(projectId?: string): CodeEntity[] { + deprecatedEntities( + projectId?: string, + limit = HELPER_QUERY_MAX_LIMIT, + offset = 0, + ): CodeEntity[] { const where = projectId ? "WHERE status = 'deprecated' AND project_id = ?" : "WHERE status = 'deprecated'"; const params = projectId ? [projectId] : []; const rows = this.db.prepare( - `SELECT * FROM code_entities ${where} ORDER BY deprecated_at DESC` - ).all(...params) as EntityRow[]; + `SELECT * FROM code_entities ${where} ORDER BY deprecated_at DESC LIMIT ? OFFSET ?` + ).all(...params, clampInteger(limit, HELPER_QUERY_MAX_LIMIT, HELPER_QUERY_MAX_LIMIT), clampInteger(offset, 0)) as EntityRow[]; return this.rowsToEntities(rows); } - untestedEntities(projectId?: string): CodeEntity[] { + untestedEntities( + projectId?: string, + limit = HELPER_QUERY_MAX_LIMIT, + offset = 0, + ): CodeEntity[] { const where = projectId ? "WHERE has_tests = 0 AND status = 'active' AND project_id = ?" : "WHERE has_tests = 0 AND status = 'active'"; @@ -851,20 +819,25 @@ export class SqliteRegistryStore { const rows = this.db.prepare( `SELECT * FROM code_entities ${where} ORDER BY CASE risk_level WHEN 'high' THEN 0 WHEN 'medium' THEN 1 ELSE 2 END, - complexity_score DESC NULLS LAST` - ).all(...params) as EntityRow[]; + complexity_score DESC NULLS LAST + LIMIT ? OFFSET ?` + ).all(...params, clampInteger(limit, HELPER_QUERY_MAX_LIMIT, HELPER_QUERY_MAX_LIMIT), clampInteger(offset, 0)) as EntityRow[]; return this.rowsToEntities(rows); } - highRiskEntities(projectId?: string): CodeEntity[] { + highRiskEntities( + projectId?: string, + limit = HELPER_QUERY_MAX_LIMIT, + offset = 0, + ): CodeEntity[] { const where = projectId ? "WHERE risk_level = 'high' AND project_id = ?" : "WHERE risk_level = 'high'"; const params = projectId ? [projectId] : []; const rows = this.db.prepare( - `SELECT * FROM code_entities ${where} ORDER BY complexity_score DESC NULLS LAST` - ).all(...params) as EntityRow[]; + `SELECT * FROM code_entities ${where} ORDER BY complexity_score DESC NULLS LAST LIMIT ? OFFSET ?` + ).all(...params, clampInteger(limit, HELPER_QUERY_MAX_LIMIT, HELPER_QUERY_MAX_LIMIT), clampInteger(offset, 0)) as EntityRow[]; return this.rowsToEntities(rows); } @@ -1005,143 +978,12 @@ export class SqliteRegistryStore { this.db.close(); } - /** 단일 엔티티 변환 (개별 서브쿼리 — 단건 조회용) */ - private rowToEntity(row: EntityRow): CodeEntity { - const id = row.id; - return this.buildEntity(row, this.getTags(id), this.getWarnings(id), this.getLinkedIssues(id), this.getLinkedMemories(id)); - } - - /** 배치 엔티티 변환 (N+1 방지 — 리스트 조회용) */ - private rowsToEntities(rows: EntityRow[]): CodeEntity[] { - if (rows.length === 0) return []; - - const ids = rows.map(r => r.id); - const loadByIds = (sqlForPlaceholders: (placeholders: string) => string): T[] => { - const loaded: T[] = []; - for (let i = 0; i < ids.length; i += SQLITE_IN_CHUNK_SIZE) { - const chunk = ids.slice(i, i + SQLITE_IN_CHUNK_SIZE); - const placeholders = chunk.map(() => '?').join(','); - loaded.push(...this.db.prepare(sqlForPlaceholders(placeholders)).all(...chunk) as T[]); - } - return loaded; - }; - - // 배치 태그 로딩 - const tagRows = loadByIds( - placeholders => `SELECT entity_id, tag, value FROM code_entity_tags WHERE entity_id IN (${placeholders})` - ); - const tagsByEntity = new Map(); - for (const r of tagRows) { - const list = tagsByEntity.get(r.entity_id) ?? []; - list.push({ tag: r.tag, value: r.value ?? undefined }); - tagsByEntity.set(r.entity_id, list); - } - - // 배치 경고 로딩 - const warningRows = loadByIds( - placeholders => `SELECT * FROM code_entity_warnings WHERE entity_id IN (${placeholders}) ORDER BY created_at DESC` - ); - const warningsByEntity = new Map(); - for (const r of warningRows) { - const list = warningsByEntity.get(r.entity_id) ?? []; - list.push(this.rowToWarning(r)); - warningsByEntity.set(r.entity_id, list); - } - - // 배치 이슈 링크 로딩 - const issueRows = loadByIds( - placeholders => `SELECT entity_id, issue_id FROM code_entity_issue_links WHERE entity_id IN (${placeholders}) ORDER BY linked_at` - ); - const issuesByEntity = new Map(); - for (const r of issueRows) { - const list = issuesByEntity.get(r.entity_id) ?? []; - list.push(r.issue_id); - issuesByEntity.set(r.entity_id, list); - } - - // 배치 메모리 링크 로딩 - const memoryRows = loadByIds( - placeholders => `SELECT entity_id, memory_id FROM code_entity_memory_links WHERE entity_id IN (${placeholders}) ORDER BY linked_at` - ); - const memorysByEntity = new Map(); - for (const r of memoryRows) { - const list = memorysByEntity.get(r.entity_id) ?? []; - list.push(r.memory_id); - memorysByEntity.set(r.entity_id, list); - } - - return rows.map(row => this.buildEntity( - row, - tagsByEntity.get(row.id) ?? [], - warningsByEntity.get(row.id) ?? [], - issuesByEntity.get(row.id) ?? [], - memorysByEntity.get(row.id) ?? [], - )); - } - - private buildEntity( - row: EntityRow, - tags: EntityTag[], - warnings: EntityWarning[], - linkedIssueIds: string[], - linkedMemoryIds: string[], - ): CodeEntity { - return { - id: row.id, - projectId: row.project_id, - kind: row.kind as EntityKind, - name: row.name, - qualifiedName: row.qualified_name, - filePath: row.file_path, - lineStart: row.line_start ?? undefined, - lineEnd: row.line_end ?? undefined, - signature: row.signature ?? undefined, - status: row.status as EntityStatus, - deprecatedAt: row.deprecated_at ?? undefined, - deprecatedReason: row.deprecated_reason ?? undefined, - hasTests: row.has_tests === 1, - testFile: row.test_file ?? undefined, - author: row.author ?? undefined, - maintainer: row.maintainer ?? undefined, - complexityScore: row.complexity_score ?? undefined, - riskLevel: row.risk_level as RiskLevel, - description: row.description ?? '', - notes: row.notes ?? '', - knowledgeNodeId: row.knowledge_node_id ?? undefined, - tags, - warnings, - linkedIssueIds, - linkedMemoryIds, - createdAt: row.created_at, - updatedAt: row.updated_at, - }; - } - - private rowToWarning(row: WarningRow): EntityWarning { - return { - id: row.id, - entityId: row.entity_id, - severity: row.severity as WarningSeverity, - category: row.category as WarningCategory, - message: row.message, - resolved: row.resolved === 1, - resolvedAt: row.resolved_at ?? undefined, - createdAt: row.created_at, - }; - } - - private rowToEvent(row: EventRow): EntityEvent { - return { - id: row.id, - entityId: row.entity_id, - type: row.type as EntityEventType, - oldValue: row.old_value ?? undefined, - newValue: row.new_value ?? undefined, - content: row.content ?? undefined, - actor: row.actor, - createdAt: row.created_at, - }; - } + // Row conversion lives in sqliteStoreRows.ts (AGT-3421 LOC split); these + // delegators keep the class call sites unchanged. + private rowToEntity(row: EntityRow): CodeEntity { return mapRowToEntity(this.db, row, this); } + private rowsToEntities(rows: EntityRow[]): CodeEntity[] { return mapRowsToEntities(this.db, rows); } + private rowToWarning(row: WarningRow) { return mapRowToWarning(row); } + private rowToEvent(row: EventRow) { return mapRowToEvent(row); } } // 싱글톤 diff --git a/src/registry/sqliteStoreRows.ts b/src/registry/sqliteStoreRows.ts new file mode 100644 index 00000000..8b474446 --- /dev/null +++ b/src/registry/sqliteStoreRows.ts @@ -0,0 +1,256 @@ +// ============================================ +// OpenSwarm - Registry SQLite row mapping helpers +// ============================================ +// +// Row shapes and conversion logic extracted from sqliteStore.ts (AGT-3421 +// LOC split) — pure mapping over better-sqlite3 rows, no store state. + +import type { Database } from 'better-sqlite3'; +import type { + CodeEntity, EntityEvent, EntityEventType, EntityKind, EntityStatus, EntityTag, EntityWarning, + RiskLevel, WarningCategory, WarningSeverity, +} from './schema.js'; + +/** Chunk size for `IN (...)` batch loads — SQLite's host-parameter cap is 999. */ +export const SQLITE_IN_CHUNK_SIZE = 500; + +// ============ DB Row 타입 (better-sqlite3 반환값) ============ + +export interface EntityRow { + id: string; + project_id: string; + kind: string; + name: string; + qualified_name: string; + file_path: string; + line_start: number | null; + line_end: number | null; + signature: string | null; + status: string; + deprecated_at: string | null; + deprecated_reason: string | null; + has_tests: number; + test_file: string | null; + author: string | null; + maintainer: string | null; + complexity_score: number | null; + risk_level: string; + description: string | null; + notes: string | null; + knowledge_node_id: string | null; + created_at: string; + updated_at: string; +} + +export interface WarningRow { + id: string; + entity_id: string; + severity: string; + category: string; + message: string; + resolved: number; + resolved_at: string | null; + created_at: string; +} + +export interface EventRow { + id: string; + entity_id: string; + type: string; + old_value: string | null; + new_value: string | null; + content: string | null; + actor: string; + created_at: string; +} + +export interface TagRow { + tag: string; + value: string | null; +} + +export interface RelationRow { + target_id: string; + target_name: string; + relation_type: string; +} + +export interface CountRow { + cnt: number; +} + +export interface KindCountRow { + kind: string; + cnt: number; +} + +export interface StatusCountRow { + status: string; + cnt: number; +} + +export interface IssueLinkRow { + entity_id: string; + issue_id: string; +} + +export interface MemoryLinkRow { + entity_id: string; + memory_id: string; +} + +/** Relation loaders the single-row conversion needs (satisfied by the store). */ +export interface EntityRelationLoaders { + getTags(entityId: string): EntityTag[]; + getWarnings(entityId: string): EntityWarning[]; + getLinkedIssues(entityId: string): string[]; + getLinkedMemories(entityId: string): string[]; +} + +export function rowToWarning(row: WarningRow): EntityWarning { + return { + id: row.id, + entityId: row.entity_id, + severity: row.severity as WarningSeverity, + category: row.category as WarningCategory, + message: row.message, + resolved: row.resolved === 1, + resolvedAt: row.resolved_at ?? undefined, + createdAt: row.created_at, + }; +} + +export function rowToEvent(row: EventRow): EntityEvent { + return { + id: row.id, + entityId: row.entity_id, + type: row.type as EntityEventType, + oldValue: row.old_value ?? undefined, + newValue: row.new_value ?? undefined, + content: row.content ?? undefined, + actor: row.actor, + createdAt: row.created_at, + }; +} + +export function buildEntity( + row: EntityRow, + tags: EntityTag[], + warnings: EntityWarning[], + linkedIssueIds: string[], + linkedMemoryIds: string[], +): CodeEntity { + return { + id: row.id, + projectId: row.project_id, + kind: row.kind as EntityKind, + name: row.name, + qualifiedName: row.qualified_name, + filePath: row.file_path, + lineStart: row.line_start ?? undefined, + lineEnd: row.line_end ?? undefined, + signature: row.signature ?? undefined, + status: row.status as EntityStatus, + deprecatedAt: row.deprecated_at ?? undefined, + deprecatedReason: row.deprecated_reason ?? undefined, + hasTests: row.has_tests === 1, + testFile: row.test_file ?? undefined, + author: row.author ?? undefined, + maintainer: row.maintainer ?? undefined, + complexityScore: row.complexity_score ?? undefined, + riskLevel: row.risk_level as RiskLevel, + description: row.description ?? '', + notes: row.notes ?? '', + knowledgeNodeId: row.knowledge_node_id ?? undefined, + tags, + warnings, + linkedIssueIds, + linkedMemoryIds, + createdAt: row.created_at, + updatedAt: row.updated_at, + }; +} + +/** 단일 엔티티 변환 (개별 서브쿼리 — 단건 조회용) */ +export function rowToEntity( + db: Database, + row: EntityRow, + loaders: EntityRelationLoaders, +): CodeEntity { + const id = row.id; + return buildEntity( + row, + loaders.getTags(id), + loaders.getWarnings(id), + loaders.getLinkedIssues(id), + loaders.getLinkedMemories(id), + ); +} + +/** 배치 엔티티 변환 (N+1 방지 — 리스트 조회용) */ +export function rowsToEntities(db: Database, rows: EntityRow[]): CodeEntity[] { + if (rows.length === 0) return []; + + const ids = rows.map(r => r.id); + const loadByIds = (sqlForPlaceholders: (placeholders: string) => string): T[] => { + const loaded: T[] = []; + for (let i = 0; i < ids.length; i += SQLITE_IN_CHUNK_SIZE) { + const chunk = ids.slice(i, i + SQLITE_IN_CHUNK_SIZE); + const placeholders = chunk.map(() => '?').join(','); + loaded.push(...db.prepare(sqlForPlaceholders(placeholders)).all(...chunk) as T[]); + } + return loaded; + }; + + // 배치 태그 로딩 + const tagRows = loadByIds( + placeholders => `SELECT entity_id, tag, value FROM code_entity_tags WHERE entity_id IN (${placeholders})` + ); + const tagsByEntity = new Map(); + for (const r of tagRows) { + const list = tagsByEntity.get(r.entity_id) ?? []; + list.push({ tag: r.tag, value: r.value ?? undefined }); + tagsByEntity.set(r.entity_id, list); + } + + // 배치 경고 로딩 + const warningRows = loadByIds( + placeholders => `SELECT * FROM code_entity_warnings WHERE entity_id IN (${placeholders}) ORDER BY created_at DESC` + ); + const warningsByEntity = new Map(); + for (const r of warningRows) { + const list = warningsByEntity.get(r.entity_id) ?? []; + list.push(rowToWarning(r)); + warningsByEntity.set(r.entity_id, list); + } + + // 배치 이슈 링크 로딩 + const issueRows = loadByIds( + placeholders => `SELECT entity_id, issue_id FROM code_entity_issue_links WHERE entity_id IN (${placeholders}) ORDER BY linked_at` + ); + const issuesByEntity = new Map(); + for (const r of issueRows) { + const list = issuesByEntity.get(r.entity_id) ?? []; + list.push(r.issue_id); + issuesByEntity.set(r.entity_id, list); + } + + // 배치 메모리 링크 로딩 + const memoryRows = loadByIds( + placeholders => `SELECT entity_id, memory_id FROM code_entity_memory_links WHERE entity_id IN (${placeholders}) ORDER BY linked_at` + ); + const memorysByEntity = new Map(); + for (const r of memoryRows) { + const list = memorysByEntity.get(r.entity_id) ?? []; + list.push(r.memory_id); + memorysByEntity.set(r.entity_id, list); + } + + return rows.map(row => buildEntity( + row, + tagsByEntity.get(row.id) ?? [], + warningsByEntity.get(row.id) ?? [], + issuesByEntity.get(row.id) ?? [], + memorysByEntity.get(row.id) ?? [], + )); +}