apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-22 08:38:08 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(cli): improve search ranking output

Browse source
This commit is contained in:
Andrey Avtomonov 2026-05-17 01:59:21 +02:00
parent de72a10ffb
commit 855c0644ff
12 changed files with 267 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

7
packages/cli/src/commands/knowledge-commands.ts
View file

@ -1,5 +1,6 @@
import { type Command, Option } from '@commander-js/extra-typings';
import {
type CommandWithGlobalOptions,
type KtxCliCommandContext,
parsePositiveIntegerOption,
resolveCommandProjectDir,
@ -14,6 +15,11 @@ async function runKnowledgeArgs(context: KtxCliCommandContext, args: KtxKnowledg
context.setExitCode(await runner(args, context.io));
}
function isDebugEnabled(command: CommandWithGlobalOptions): boolean {
const options = (command.optsWithGlobals ? command.optsWithGlobals() : command.opts()) as { debug?: unknown };
return options.debug === true;
}
export function registerWikiCommands(program: Command, context: KtxCliCommandContext): void {
const wiki = program
.command('wiki')
@ -83,6 +89,7 @@ export function registerWikiCommands(program: Command, context: KtxCliCommandCon
userId: options.userId,
output: options.output,
json: options.json,
...(isDebugEnabled(command) ? { debug: true } : {}),
...(options.limit !== undefined ? { limit: options.limit } : {}),
});
},

16
packages/cli/src/index.test.ts
View file

@ -171,6 +171,22 @@ describe('runKtxCli', () => {
},
searchIo.io,
);
const debugSearchIo = makeIo();
await expect(
runKtxCli(['--project-dir', tempDir, '--debug', 'wiki', 'search', 'revenue'], debugSearchIo.io, { knowledge }),
).resolves.toBe(0);
expect(knowledge).toHaveBeenLastCalledWith(
{
command: 'search',
projectDir: tempDir,
query: 'revenue',
userId: 'local',
json: false,
debug: true,
},
debugSearchIo.io,
);
});
it('rejects removed public wiki read and write commands', async () => {

24
packages/cli/src/io/print-list.test.ts
View file

@ -1,6 +1,6 @@
import { describe, expect, it } from 'vitest';
import type { KtxCliIo } from '../cli-runtime.js';
import { printList, type PrintListColumn } from './print-list.js';
import { createRankBadgeFormatter, printList, type PrintListColumn } from './print-list.js';
import { SYMBOLS } from './symbols.js';
function recorder(): { io: KtxCliIo; out: () => string; err: () => string } {
@ -239,26 +239,26 @@ describe('printList — pretty mode', () => {
expect(out).toContain('2 pages');
});
it('renders a leading badge column with prettyFormat in pretty mode', () => {
it('renders a leading rank badge column in pretty mode', () => {
const r = recorder();
interface SearchRow { score: number; scope: string; key: string; summary: string }
const rows: SearchRow[] = [
{ score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' },
{ score: 0.04, scope: 'GLOBAL', key: 'beta', summary: 'second' },
];
const SEARCH_COLUMNS: ReadonlyArray<PrintListColumn<SearchRow>> = [
{
key: 'score',
label: 'SCORE',
plain: 'score=',
role: 'badge',
prettyFormat: (v) => `${Math.round(Number(v) * 100)}%`,
prettyFormat: createRankBadgeFormatter(rows),
dim: true,
},
{ key: 'scope', label: 'SCOPE', plain: '' },
{ key: 'key', label: 'KEY', plain: '' },
{ key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
];
const rows: SearchRow[] = [
{ score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' },
{ score: 0.04, scope: 'GLOBAL', key: 'beta', summary: 'second' },
];
printList<SearchRow>({
rows,
columns: SEARCH_COLUMNS,
@ -270,20 +270,22 @@ describe('printList — pretty mode', () => {
io: r.io,
});
const out = stripAnsi(r.out());
expect(out).toMatch(/87%\s+alpha\s+/);
expect(out).toMatch(/4%\s+beta\s+/);
expect(out).toMatch(/#1\s+alpha\s+/);
expect(out).toMatch(/#2\s+beta\s+/);
expect(out).not.toContain('%');
});
it('emits the badge column in plain mode using its plain prefix', () => {
const r = recorder();
interface SearchRow { score: number; scope: string; key: string; summary: string }
const rows: SearchRow[] = [{ score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' }];
const SEARCH_COLUMNS: ReadonlyArray<PrintListColumn<SearchRow>> = [
{
key: 'score',
label: 'SCORE',
plain: 'score=',
role: 'badge',
prettyFormat: (v) => `${Math.round(Number(v) * 100)}%`,
prettyFormat: createRankBadgeFormatter(rows),
dim: true,
},
{ key: 'scope', label: 'SCOPE', plain: '' },
@ -291,7 +293,7 @@ describe('printList — pretty mode', () => {
{ key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
];
printList<SearchRow>({
rows: [{ score: 0.87, scope: 'GLOBAL', key: 'alpha', summary: 'first' }],
rows,
columns: SEARCH_COLUMNS,
groupBy: 'scope',
mode: 'plain',

12
packages/cli/src/io/print-list.ts
View file

@ -24,7 +24,7 @@ export interface PrintListColumn<Row> {
* - `'suffix'` — trailing em-dash optional value. Default: any column with `optional: true`.
*/
role?: 'name' | 'metric' | 'badge' | 'suffix';
/** Custom pretty-mode value formatter (e.g. score → "87%"). Plain/JSON unaffected. */
/** Custom pretty-mode value formatter (for example, score -> "#1"). Plain/JSON unaffected. */
prettyFormat?: (value: Row[keyof Row & string], row: Row) => string;
}
@ -67,6 +67,16 @@ export function printList<Row extends object>(args: PrintListArgs<Row>): void {
}
}
export function createRankBadgeFormatter<Row extends object>(
rows: ReadonlyArray<Row>,
): (_value: Row[keyof Row & string], row: Row) => string {
const ranks = new WeakMap<Row, number>();
rows.forEach((row, index) => {
ranks.set(row, index + 1);
});
return (_value, row) => `#${ranks.get(row) ?? rows.indexOf(row) + 1}`;
}
function isEmpty(value: unknown): boolean {
return value === undefined || value === null || value === '';
}

44
packages/cli/src/knowledge.test.ts
View file

@ -1,6 +1,7 @@
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { stripVTControlCharacters } from 'node:util';
import { initKtxProject, loadKtxProject } from '@ktx/context/project';
import type { KtxEmbeddingPort } from '@ktx/context';
import { writeLocalKnowledgePage } from '@ktx/context/wiki';
@ -90,6 +91,24 @@ describe('runKtxKnowledge', () => {
expect(searchIo.stdout()).toContain('metrics-revenue');
});
it('prints wiki search rank badges in pretty output', async () => {
const projectDir = join(tempDir, 'rank-project');
await initKtxProject({ projectDir });
await seedWikiPage(projectDir);
const searchIo = makeIo();
await expect(
runKtxKnowledge(
{ command: 'search', projectDir, query: 'paid order', userId: 'local', output: 'pretty' },
searchIo.io,
),
).resolves.toBe(0);
const stdout = stripVTControlCharacters(searchIo.stdout());
expect(stdout).toMatch(/#1\s+metrics-revenue/);
expect(stdout).not.toContain('%');
});
it('prints wiki list and search as public JSON envelopes', async () => {
const projectDir = join(tempDir, 'project');
await initKtxProject({ projectDir });
@ -156,4 +175,29 @@ describe('runKtxKnowledge', () => {
expect(searchIo.stdout()).toContain('active-contract-arr-open-tickets');
expect(searchIo.stderr()).toBe('');
});
it('writes wiki search lane diagnostics to stderr when debug is enabled', async () => {
const projectDir = join(tempDir, 'debug-project');
await initKtxProject({ projectDir });
await seedWikiPage(projectDir);
const searchIo = makeIo();
await expect(
runKtxKnowledge(
{ command: 'search', projectDir, query: 'paid order', userId: 'local', json: true, debug: true },
searchIo.io,
{ embeddingService: new FakeEmbeddingPort() },
),
).resolves.toBe(0);
expect(JSON.parse(searchIo.stdout())).toMatchObject({
kind: 'list',
data: { items: [expect.objectContaining({ key: 'metrics-revenue' })] },
meta: { command: 'wiki search' },
});
expect(searchIo.stderr()).toContain('[debug] wiki search mode=sqlite-fts5');
expect(searchIo.stderr()).toContain('embedding=configured');
expect(searchIo.stderr()).toContain('lane=lexical status=available');
expect(searchIo.stderr()).toContain('lane=semantic status=available');
});
});

65
packages/cli/src/knowledge.ts
View file

@ -11,7 +11,7 @@ import {
searchLocalKnowledgePages,
} from '@ktx/context/wiki';
import { resolveOutputMode } from './io/mode.js';
import { printList, type PrintListColumn } from './io/print-list.js';
import { createRankBadgeFormatter, printList, type PrintListColumn } from './io/print-list.js';
export type KtxKnowledgeArgs =
| { command: 'list'; projectDir: string; userId: string; output?: string; json?: boolean }
@ -23,6 +23,7 @@ export type KtxKnowledgeArgs =
output?: string;
json?: boolean;
limit?: number;
debug?: boolean;
};
type KtxKnowledgeIo = import('./cli-runtime.js').KtxCliIo;
@ -33,19 +34,23 @@ const WIKI_LIST_COLUMNS: ReadonlyArray<PrintListColumn<LocalKnowledgeSummary>> =
{ key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
];
const WIKI_SEARCH_COLUMNS: ReadonlyArray<PrintListColumn<LocalKnowledgeSearchResult>> = [
{
key: 'score',
label: 'SCORE',
plain: 'score=',
role: 'badge',
prettyFormat: (value) => `${Math.round(Number(value) * 100)}%`,
dim: true,
},
{ key: 'scope', label: 'SCOPE', plain: '' },
{ key: 'key', label: 'KEY', plain: '' },
{ key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
];
function wikiSearchColumns(
rows: ReadonlyArray<LocalKnowledgeSearchResult>,
): ReadonlyArray<PrintListColumn<LocalKnowledgeSearchResult>> {
return [
{
key: 'score',
label: 'SCORE',
plain: 'score=',
role: 'badge',
prettyFormat: createRankBadgeFormatter(rows),
dim: true,
},
{ key: 'scope', label: 'SCOPE', plain: '' },
{ key: 'key', label: 'KEY', plain: '' },
{ key: 'summary', label: 'SUMMARY', plain: '', optional: true, dim: true },
];
}
interface KtxKnowledgeDeps {
embeddingService?: KtxEmbeddingPort | null;
@ -65,6 +70,26 @@ function wikiSearchEmbeddingService(
return provider ? new KtxIngestEmbeddingPortAdapter(provider) : null;
}
function writeWikiSearchDebug(
io: KtxKnowledgeIo,
input: {
mode: string;
embeddingConfigured: boolean;
results: LocalKnowledgeSearchResult[];
},
): void {
io.stderr.write(
`[debug] wiki search mode=${input.mode} embedding=${input.embeddingConfigured ? 'configured' : 'unconfigured'} results=${input.results.length}\n`,
);
const lanes = input.results[0]?.lanes ?? [];
for (const lane of lanes) {
const reason = lane.reason ? ` reason=${lane.reason}` : '';
io.stderr.write(
`[debug] wiki search lane=${lane.lane} status=${lane.status} returned=${lane.returnedCandidateCount} weight=${lane.weight}${reason}\n`,
);
}
}
export async function runKtxKnowledge(
args: KtxKnowledgeArgs,
io: KtxKnowledgeIo = process,
@ -89,12 +114,20 @@ export async function runKtxKnowledge(
return 0;
}
if (args.command === 'search') {
const embeddingService = wikiSearchEmbeddingService(project, deps);
const results = await searchLocalKnowledgePages(project, {
query: args.query,
userId: args.userId,
embeddingService: wikiSearchEmbeddingService(project, deps),
embeddingService,
limit: args.limit,
});
if (args.debug) {
writeWikiSearchDebug(io, {
mode: project.config.storage.search,
embeddingConfigured: embeddingService !== null,
results,
});
}
const mode = resolveOutputMode({ explicit: args.output, json: args.json, io });
let emptyMessage = `No local wiki pages matched "${args.query}"`;
let emptyHint = 'Run `ktx wiki list` to inspect available pages.';
@ -107,7 +140,7 @@ export async function runKtxKnowledge(
}
printList<LocalKnowledgeSearchResult>({
rows: results,
columns: WIKI_SEARCH_COLUMNS,
columns: wikiSearchColumns(results),
groupBy: 'scope',
emptyMessage,
emptyHint,

18
packages/cli/src/sl.test.ts
View file

@ -1,6 +1,7 @@
import { mkdtemp, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { stripVTControlCharacters } from 'node:util';
import Database from 'better-sqlite3';
import { initKtxProject } from '@ktx/context/project';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@ -98,6 +99,23 @@ describe('runKtxSl', () => {
});
});
it('prints semantic-layer search rank badges in pretty output', async () => {
const projectDir = join(tempDir, 'rank-project');
await seedSlSource({ projectDir });
const searchIo = makeIo();
await expect(
runKtxSl(
{ command: 'search', projectDir, connectionId: 'warehouse', query: 'order', output: 'pretty' },
searchIo.io,
),
).resolves.toBe(0);
const stdout = stripVTControlCharacters(searchIo.stdout());
expect(stdout).toMatch(/#1\s+orders/);
expect(stdout).not.toContain('%');
});
it('prints semantic-layer list and search as public JSON envelopes', async () => {
const projectDir = join(tempDir, 'project');
await seedSlSource({

4
packages/cli/src/sl.ts
View file

@ -109,7 +109,7 @@ async function printSlSources(input: {
emptyHint?: string;
}): Promise<void> {
const { resolveOutputMode } = await import('./io/mode.js');
const { printList } = await import('./io/print-list.js');
const { createRankBadgeFormatter, printList } = await import('./io/print-list.js');
const mode = resolveOutputMode({ explicit: input.output, json: input.json, io: input.io });
if (input.command === 'sl search') {
@ -119,7 +119,7 @@ async function printSlSources(input: {
label: 'SCORE',
plain: 'score=',
role: 'badge',
prettyFormat: (value) => `${Math.round(Number(value) * 100)}%`,
prettyFormat: createRankBadgeFormatter(input.rows as ReadonlyArray<LocalSlSourceSearchResult>),
dim: true,
},
{ key: 'connectionId', label: 'CONNECTION', plain: '' },