Merge pull request #17 from anand-testcompare/16-doc-list-tool-pagination-and-query-limit

fix: paginate list_all_docs

Author: anand-testcompare

.gitignore

@@ -17,3 +17,6 @@ data/*.parquet
 *.tgz
 
 .sisyphus/
+
+# Local OpenCode session transcripts (generated during manual testing)
+session-*.md

src/__tests__/index.test.ts

@@ -1,23 +1,10 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { mock } from 'bun:test';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { writeParquet } from '../docs/write-parquet.ts';
 import * as fetchModule from '../docs/fetch.ts';
 
-mock.module('@opencode-ai/plugin/tool', () => {
-  const mockSchema = {
-    string: () => ({
-      describe: (d: string) => ({ _type: 'string', _description: d }),
-    }),
-  };
-  const toolFn = Object.assign((input: Record<string, unknown>) => input, {
-    schema: mockSchema,
-  });
-  return { tool: toolFn };
-});
-
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const plugin = (await import('../index.ts')).default as any;
 
@@ -39,15 +26,15 @@ describe('Plugin', () => {
     await writeParquet(
       [
         {
-          url: '/docs/foundry/ontology/overview/',
+          url: '/foundry/ontology/overview/',
           title: 'Ontology Overview',
           content: 'This is the ontology overview content.',
           wordCount: 6,
           meta: {},
           fetchedAt: '2025-01-01T00:00:00.000Z',
         },
         {
-          url: '/docs/foundry/actions/',
+          url: '/foundry/actions/',
           title: 'Actions',
           content: 'Actions documentation content.',
           wordCount: 3,
@@ -59,6 +46,67 @@ describe('Plugin', () => {
     );
   }
 
+  async function seedDatabaseMany(): Promise<void> {
+    fs.mkdirSync(path.join(tmpDir, 'data'), { recursive: true });
+
+    const rows: Array<{
+      url: string;
+      title: string;
+      content: string;
+      wordCount: number;
+      meta: Record<string, unknown>;
+      fetchedAt: string;
+    }> = [];
+
+    // Intentionally unsorted URL insertion to prove deterministic ordering.
+    rows.push({
+      url: '/apollo/zzz/',
+      title: 'Apollo ZZZ',
+      content: 'apollo content',
+      wordCount: 2,
+      meta: {},
+      fetchedAt: '2025-01-01T00:00:00.000Z',
+    });
+    rows.push({
+      url: '/foundry/zzz/',
+      title: 'Foundry ZZZ',
+      content: 'foundry content',
+      wordCount: 2,
+      meta: {},
+      fetchedAt: '2025-01-01T00:00:00.000Z',
+    });
+    rows.push({
+      url: '/gotham/aaa/',
+      title: 'Gotham AAA',
+      content: 'gotham content',
+      wordCount: 2,
+      meta: {},
+      fetchedAt: '2025-01-01T00:00:00.000Z',
+    });
+
+    rows.push({
+      url: '/foundry/compute-modules/overview/',
+      title: 'Compute modules',
+      content: 'Compute modules overview content.',
+      wordCount: 4,
+      meta: {},
+      fetchedAt: '2025-01-01T00:00:00.000Z',
+    });
+
+    for (let i = 0; i < 60; i += 1) {
+      rows.push({
+        url: `/foundry/many/${String(i).padStart(2, '0')}/`,
+        title: `Foundry Many ${i}`,
+        content: 'foundry many content',
+        wordCount: 3,
+        meta: {},
+        fetchedAt: '2025-01-01T00:00:00.000Z',
+      });
+    }
+
+    await writeParquet(rows, dbPath);
+  }
+
   it('returns Hooks with tool property containing exactly 2 tools', async () => {
     const hooks = await plugin({ worktree: tmpDir });
 
@@ -76,6 +124,8 @@ describe('Plugin', () => {
     expect(getDocPage.description).toBeTruthy();
     expect(getDocPage.description).toContain('documentation page');
     expect(getDocPage.args).toHaveProperty('url');
+    expect(getDocPage.args).toHaveProperty('query');
+    expect(getDocPage.args).toHaveProperty('scope');
   });
 
   it('list_all_docs tool has description and no required args', async () => {
@@ -84,15 +134,16 @@ describe('Plugin', () => {
 
     expect(listAllDocs.description).toBeTruthy();
     expect(listAllDocs.description).toContain('documentation');
-    expect(Object.keys(listAllDocs.args)).toHaveLength(0);
+    const keys = Object.keys(listAllDocs.args).sort((a, b) => a.localeCompare(b));
+    expect(keys).toEqual(['limit', 'offset', 'query', 'scope']);
   });
 
   it('get_doc_page execute returns page content when DB exists', async () => {
     await seedDatabase();
     const hooks = await plugin({ worktree: tmpDir });
 
     const result = await hooks.tool['get_doc_page'].execute(
-      { url: '/docs/foundry/ontology/overview/' },
+      { url: '/foundry/ontology/overview/' },
       {}
     );
 
@@ -115,9 +166,127 @@ describe('Plugin', () => {
 
     const result = await hooks.tool['list_all_docs'].execute({}, {});
 
-    expect(result).toContain('Available Palantir Foundry Documentation (2 pages)');
-    expect(result).toContain('- Ontology Overview (/docs/foundry/ontology/overview/)');
-    expect(result).toContain('- Actions (/docs/foundry/actions/)');
+    expect(result).toContain('Available Palantir Documentation Pages');
+    expect(result).toContain('scope=foundry');
+    expect(result).toContain('query=');
+    expect(result).toContain('total=2');
+    expect(result).toContain('- Ontology Overview (/foundry/ontology/overview/)');
+    expect(result).toContain('- Actions (/foundry/actions/)');
+  });
+
+  it('list_all_docs defaults to bounded results and foundry scope', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const result = await hooks.tool['list_all_docs'].execute({}, {});
+
+    expect(result).toContain('scope=foundry');
+    expect(result).toContain('limit=50');
+    expect(result).toContain('Next: call list_all_docs');
+    expect(result).not.toContain('/apollo/');
+    expect(result).not.toContain('/gotham/');
+
+    const lineCount = result.split('\n').filter((l) => l.startsWith('- ')).length;
+    expect(lineCount).toBeLessThanOrEqual(50);
+  });
+
+  it('list_all_docs pagination is deterministic (sorted by url)', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const first = await hooks.tool['list_all_docs'].execute(
+      { scope: 'all', limit: 1, offset: 0 },
+      {}
+    );
+    const second = await hooks.tool['list_all_docs'].execute(
+      { scope: 'all', limit: 1, offset: 1 },
+      {}
+    );
+
+    const getOnlyUrl = (text: string): string => {
+      const line = text.split('\n').find((l) => l.startsWith('- ') && l.includes('(/'));
+      expect(line).toBeTruthy();
+      const match = line?.match(/\((\/[^)]+)\)/);
+      expect(match?.[1]).toBeTruthy();
+      return match?.[1] as string;
+    };
+
+    const url0 = getOnlyUrl(first);
+    const url1 = getOnlyUrl(second);
+    expect(url0).not.toBe(url1);
+
+    // Because ordering is by URL, /apollo/... sorts before /foundry/... and /gotham/...
+    expect(url0).toBe('/apollo/zzz/');
+    expect(url1).toBe('/foundry/compute-modules/overview/');
+  });
+
+  it('list_all_docs scope=all includes non-foundry URLs', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const result = await hooks.tool['list_all_docs'].execute(
+      { scope: 'all', limit: 5, offset: 0 },
+      {}
+    );
+
+    expect(result).toContain('scope=all');
+    expect(result).toContain('/apollo/zzz/');
+  });
+
+  it('list_all_docs query filters and ranks results', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const result = await hooks.tool['list_all_docs'].execute(
+      { query: 'compute modules', scope: 'foundry', limit: 10, offset: 0 },
+      {}
+    );
+
+    expect(result).toContain('scope=foundry');
+    expect(result).toContain('query=compute modules');
+    expect(result).toContain('/foundry/compute-modules/overview/');
+  });
+
+  it('get_doc_page accepts common URL variants (missing /docs prefix, missing trailing slash)', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const result = await hooks.tool['get_doc_page'].execute(
+      { url: '/docs/foundry/compute-modules/overview' },
+      {}
+    );
+
+    expect(result).toContain('Compute modules overview content.');
+  });
+
+  it('get_doc_page can resolve a page from a free-text query', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const result = await hooks.tool['get_doc_page'].execute(
+      { query: 'compute modules', scope: 'foundry' },
+      {}
+    );
+
+    expect(result).toContain('Matched:');
+    expect(result).toContain('/foundry/compute-modules/overview/');
+    expect(result).toContain('Compute modules overview content.');
+  });
+
+  it('list_all_docs invalid args fail safely', async () => {
+    await seedDatabaseMany();
+    const hooks = await plugin({ worktree: tmpDir });
+
+    const badLimit = await hooks.tool['list_all_docs'].execute({ limit: 0 } as never, {});
+    expect(badLimit).toContain('[ERROR]');
+    expect(badLimit).toContain('limit');
+
+    const badOffset = await hooks.tool['list_all_docs'].execute({ offset: -1 } as never, {});
+    expect(badOffset).toContain('[ERROR]');
+    expect(badOffset).toContain('offset');
+
+    const badScope = await hooks.tool['list_all_docs'].execute({ scope: 'nope' } as never, {});
+    expect(badScope).toContain('[ERROR]');
   });
 
   it('tools return helpful message when docs.db does not exist', async () => {
@@ -185,6 +354,6 @@ describe('Plugin', () => {
 
     // Second call reuses cached DB — list_all_docs also works
     const listResult = await hooks.tool['list_all_docs'].execute({}, {});
-    expect(listResult).toContain('2 pages');
+    expect(listResult).toContain('total=2');
   });
 });

src/__tests__/palantirMcpRescan.test.ts

@@ -1,5 +1,4 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { mock } from 'bun:test';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -29,18 +28,6 @@ function getFirstTextPart(output: CommandHookOutput): string {
   return part.text;
 }
 
-mock.module('@opencode-ai/plugin/tool', () => {
-  const mockSchema = {
-    string: () => ({
-      describe: (d: string) => ({ _type: 'string', _description: d }),
-    }),
-  };
-  const toolFn = Object.assign((input: Record<string, unknown>) => input, {
-    schema: mockSchema,
-  });
-  return { tool: toolFn };
-});
-
 const plugin = (await import('../index.ts')).default as unknown as MinimalPlugin;
 
 describe('/rescan-palantir-mcp-tools', () => {

src/__tests__/palantirMcpSetup.test.ts

@@ -1,5 +1,4 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { mock } from 'bun:test';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -43,18 +42,6 @@ function getFirstTextPart(output: CommandHookOutput): string {
   return part.text;
 }
 
-mock.module('@opencode-ai/plugin/tool', () => {
-  const mockSchema = {
-    string: () => ({
-      describe: (d: string) => ({ _type: 'string', _description: d }),
-    }),
-  };
-  const toolFn = Object.assign((input: Record<string, unknown>) => input, {
-    schema: mockSchema,
-  });
-  return { tool: toolFn };
-});
-
 const plugin = (await import('../index.ts')).default as unknown as MinimalPlugin;
 
 describe('/setup-palantir-mcp', () => {