@digital-finance-ui/ui-kit-mcp 0.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +43 -0
- package/data/component-index.json +57735 -0
- package/dist/resolveIndex.js +145 -0
- package/dist/server.js +113 -0
- package/dist/tools/getComponent.js +98 -0
- package/dist/tools/getComponentExamples.js +27 -0
- package/dist/tools/getComponentProps.js +59 -0
- package/dist/tools/getFeature.js +18 -0
- package/dist/tools/getFeatureExamples.js +26 -0
- package/dist/tools/getInstallationGuide.js +7 -0
- package/dist/tools/getType.js +136 -0
- package/dist/tools/listCategories.js +18 -0
- package/dist/tools/listComponents.js +50 -0
- package/dist/tools/listFeatures.js +16 -0
- package/dist/tools/searchComponents.js +259 -0
- package/dist/tools/shared.js +38 -0
- package/dist/tools/truncate.js +80 -0
- package/dist/types.js +8 -0
- package/package.json +25 -0
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
/* eslint-disable no-underscore-dangle */
|
|
2
|
+
/* eslint-disable @typescript-eslint/naming-convention */
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import { createRequire } from 'node:module';
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
8
|
+
const BUNDLED_INDEX_PATH = path.resolve(__dirname, '../data/component-index.json');
|
|
9
|
+
const SIBLING_UI_KIT_PKG = path.resolve(__dirname, '../../ui-kit/package.json');
|
|
10
|
+
function readJson(filePath) {
|
|
11
|
+
try {
|
|
12
|
+
return JSON.parse(fs.readFileSync(filePath, 'utf8'));
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
return undefined;
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
const requireFromSelf = createRequire(import.meta.url);
|
|
19
|
+
/**
|
|
20
|
+
* Резолвит '@sber-digital-finance-ui/ui-kit/...' в проекте потребителя — сначала от его CWD,
|
|
21
|
+
* затем от места, где лежим мы сами.
|
|
22
|
+
*
|
|
23
|
+
* Второй заход обязателен: MCP-клиент волен запускать сервер с любым рабочим
|
|
24
|
+
* каталогом (Claude Code берёт корень проекта, а Claude Desktop и часть других
|
|
25
|
+
* клиентов — что угодно вплоть до '/'), и тогда резолв только от CWD не находит
|
|
26
|
+
* библиотеку, хотя она установлена. Раньше это молча уводило в ветку 'bundled'
|
|
27
|
+
* с сообщением «@sber-digital-finance-ui/ui-kit не установлен в этом проекте» — неправдой, из-за
|
|
28
|
+
* которой агент получал данные не той версии, что стоит у потребителя.
|
|
29
|
+
* При обычной установке мы и библиотека — соседи в одном node_modules, поэтому
|
|
30
|
+
* резолв от собственного файла её находит независимо от CWD.
|
|
31
|
+
*/
|
|
32
|
+
function resolveFromConsumer(specifier) {
|
|
33
|
+
try {
|
|
34
|
+
const req = createRequire(path.join(process.cwd(), 'package.json'));
|
|
35
|
+
return req.resolve(specifier);
|
|
36
|
+
}
|
|
37
|
+
catch {
|
|
38
|
+
// CWD не подошёл — пробуем от себя, см. комментарий выше.
|
|
39
|
+
}
|
|
40
|
+
try {
|
|
41
|
+
return requireFromSelf.resolve(specifier);
|
|
42
|
+
}
|
|
43
|
+
catch {
|
|
44
|
+
return undefined;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
function getInstalledLibVersion() {
|
|
48
|
+
const pkgPath = resolveFromConsumer('@sber-digital-finance-ui/ui-kit/package.json');
|
|
49
|
+
if (!pkgPath)
|
|
50
|
+
return undefined;
|
|
51
|
+
return readJson(pkgPath)?.version;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Индекс, у которого обвалился источник данных, а не просто «старая версия».
|
|
55
|
+
* Признаки бинарные и не зависят от размера каталога: `features` пустой либо
|
|
56
|
+
* нет `guides.installation`. И то, и другое приходит ТОЛЬКО из курированной
|
|
57
|
+
* меты, которая лежит в .gitignore — если её не сгенерировали перед сборкой,
|
|
58
|
+
* индекс собирается молча и без них (см. assertMetaAvailable).
|
|
59
|
+
*
|
|
60
|
+
* Проверять здесь пороги из checkCompleteness нельзя: они откалиброваны под
|
|
61
|
+
* текущий каталог, а установленная у потребителя библиотека может быть
|
|
62
|
+
* заметно старее и легитимно беднее. Обвал источника — другое.
|
|
63
|
+
*/
|
|
64
|
+
function isDegradedIndex(index) {
|
|
65
|
+
return index.features.length === 0 || !index.guides?.installation;
|
|
66
|
+
}
|
|
67
|
+
function buildDataVersionNotice(libNotInstalled, versionMismatch, libVersion, installedLibVersion) {
|
|
68
|
+
if (libNotInstalled) {
|
|
69
|
+
return `@sber-digital-finance-ui/ui-kit не установлен в этом проекте. Данные MCP соответствуют версии ${libVersion} — прочитайте ресурс sber-digital-finance-ui-ui-kit://catalog/installation-guide, чтобы подключить библиотеку.`;
|
|
70
|
+
}
|
|
71
|
+
if (versionMismatch) {
|
|
72
|
+
return `Данные MCP соответствуют @sber-digital-finance-ui/ui-kit@${libVersion}, у вас установлена ${installedLibVersion} — возможны расхождения в пропсах. Обновите @sber-digital-finance-ui/ui-kit для точных данных.`;
|
|
73
|
+
}
|
|
74
|
+
return undefined;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Трёхуровневый резолв индекса (см. план): workspace → installed → bundled.
|
|
78
|
+
* Обязателен для того, чтобы MCP работал даже у потребителей на версиях
|
|
79
|
+
* @sber-digital-finance-ui/ui-kit, опубликованных до появления mcp-data (сейчас вся история
|
|
80
|
+
* версий), или вообще без установленной библиотеки.
|
|
81
|
+
*/
|
|
82
|
+
export function resolveIndex() {
|
|
83
|
+
// 1. Workspace — сосед packages/ui-kit существует физически рядом с нами
|
|
84
|
+
// (значит мы запущены внутри самого монорепо sber-digital-finance-ui-ui-kit, а не как
|
|
85
|
+
// установленный npm-пакет где-то ещё).
|
|
86
|
+
if (fs.existsSync(SIBLING_UI_KIT_PKG)) {
|
|
87
|
+
const index = readJson(BUNDLED_INDEX_PATH);
|
|
88
|
+
if (index) {
|
|
89
|
+
return { index, source: 'workspace' };
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
const installedLibVersion = getInstalledLibVersion();
|
|
93
|
+
// 2. Installed — версия @sber-digital-finance-ui/ui-kit у потребителя уже содержит mcp-data
|
|
94
|
+
// (появилось в 1.14.0 — первом релизе, где publish-npm.yml кладёт индекс в
|
|
95
|
+
// тарбол библиотеки). Не зависит от CWD клиента, см. resolveFromConsumer.
|
|
96
|
+
const installedIndexPath = resolveFromConsumer('@sber-digital-finance-ui/ui-kit/mcp-data/component-index.json');
|
|
97
|
+
if (installedIndexPath) {
|
|
98
|
+
const index = readJson(installedIndexPath);
|
|
99
|
+
if (index && !isDegradedIndex(index)) {
|
|
100
|
+
return { index, source: 'installed', installedLibVersion };
|
|
101
|
+
}
|
|
102
|
+
// Индекс внутри библиотеки есть, но неполный. Так уехал @sber-digital-finance-ui/ui-kit@1.14.0
|
|
103
|
+
// — первая версия, куда индекс вообще начал класться: релизный шаг собирал
|
|
104
|
+
// его мимо `npm run meta`, и наружу отправился каталог без features, без
|
|
105
|
+
// guides и без full-code примеров. Раньше такой индекс выигрывал у
|
|
106
|
+
// запасного безусловно (проверялось только «файл есть и парсится»), то
|
|
107
|
+
// есть обновление библиотеки УХУДШАЛО данные MCP: до 1.14.0 работал
|
|
108
|
+
// bundled, с 1.14.0 включился заведомо худший installed.
|
|
109
|
+
//
|
|
110
|
+
// Откатываемся на запасной, только если он сам не деградировал — иначе
|
|
111
|
+
// менять шило на мыло, теряя совпадение по версии библиотеки.
|
|
112
|
+
const fallback = readJson(BUNDLED_INDEX_PATH);
|
|
113
|
+
if (index && fallback && !isDegradedIndex(fallback)) {
|
|
114
|
+
return {
|
|
115
|
+
index: fallback,
|
|
116
|
+
source: 'bundled',
|
|
117
|
+
installedLibVersion,
|
|
118
|
+
dataVersionNotice: `Индекс внутри установленного @sber-digital-finance-ui/ui-kit@${installedLibVersion} неполный ` +
|
|
119
|
+
'(нет features и гайда по установке — он собран до исправления релизного пайплайна), ' +
|
|
120
|
+
`поэтому используется запасной индекс версии ${fallback.libVersion} из @digital-finance-ui/ui-kit-mcp. ` +
|
|
121
|
+
'Возможны расхождения в пропсах, если версии не совпадают — обновите @sber-digital-finance-ui/ui-kit.',
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
if (index) {
|
|
125
|
+
return { index, source: 'installed', installedLibVersion };
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
// 3. Bundled — запасной индекс, вшитый в сам @digital-finance-ui/ui-kit-mcp. Нужен для
|
|
129
|
+
// старых версий библиотеки без mcp-data и для случая, когда библиотека
|
|
130
|
+
// вообще не установлена.
|
|
131
|
+
const index = readJson(BUNDLED_INDEX_PATH);
|
|
132
|
+
if (!index) {
|
|
133
|
+
throw new Error(`Не найден ни один источник индекса (workspace/installed/bundled). ` +
|
|
134
|
+
`Запасной индекс должен лежать в ${BUNDLED_INDEX_PATH} — похоже, пакет @digital-finance-ui/ui-kit-mcp собран некорректно.`);
|
|
135
|
+
}
|
|
136
|
+
const libNotInstalled = installedLibVersion === undefined;
|
|
137
|
+
const versionMismatch = !libNotInstalled && installedLibVersion !== index.libVersion;
|
|
138
|
+
return {
|
|
139
|
+
index,
|
|
140
|
+
source: 'bundled',
|
|
141
|
+
installedLibVersion,
|
|
142
|
+
libNotInstalled: libNotInstalled || undefined,
|
|
143
|
+
dataVersionNotice: buildDataVersionNotice(libNotInstalled, versionMismatch, index.libVersion, installedLibVersion),
|
|
144
|
+
};
|
|
145
|
+
}
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
3
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
4
|
+
import { z } from 'zod';
|
|
5
|
+
import { resolveIndex } from './resolveIndex.js';
|
|
6
|
+
import { getComponent } from './tools/getComponent.js';
|
|
7
|
+
import { getComponentExamples } from './tools/getComponentExamples.js';
|
|
8
|
+
import { getComponentProps } from './tools/getComponentProps.js';
|
|
9
|
+
import { getFeature } from './tools/getFeature.js';
|
|
10
|
+
import { getFeatureExamples } from './tools/getFeatureExamples.js';
|
|
11
|
+
import { getInstallationGuide } from './tools/getInstallationGuide.js';
|
|
12
|
+
import { getType } from './tools/getType.js';
|
|
13
|
+
import { listCategories } from './tools/listCategories.js';
|
|
14
|
+
import { listComponents } from './tools/listComponents.js';
|
|
15
|
+
import { listFeatures } from './tools/listFeatures.js';
|
|
16
|
+
import { searchComponents } from './tools/searchComponents.js';
|
|
17
|
+
import { truncateForResponse } from './tools/truncate.js';
|
|
18
|
+
function loadIndex() {
|
|
19
|
+
const resolved = resolveIndex();
|
|
20
|
+
// dataVersionNotice/libNotInstalled/source кладём прямо в index — тулзам
|
|
21
|
+
// так не нужно принимать второй аргумент на каждый вызов.
|
|
22
|
+
return {
|
|
23
|
+
...resolved.index,
|
|
24
|
+
dataVersionNotice: resolved.dataVersionNotice,
|
|
25
|
+
libNotInstalled: resolved.libNotInstalled,
|
|
26
|
+
indexSource: resolved.source,
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Явная аннотация возврата CallToolResult обязательна: без неё литерал
|
|
31
|
+
* 'text' расширяется до string и объект перестаёт подходить под
|
|
32
|
+
* дискриминированный union content-блоков SDK.
|
|
33
|
+
*/
|
|
34
|
+
function toToolResult(payload) {
|
|
35
|
+
return { content: [{ type: 'text', text: truncateForResponse(payload) }] };
|
|
36
|
+
}
|
|
37
|
+
/** То же самое для ресурсов (T8): один текстовый content-блок с тем же JSON-форматом, что и у тулов. */
|
|
38
|
+
function toResourceResult(uri, payload) {
|
|
39
|
+
return {
|
|
40
|
+
contents: [
|
|
41
|
+
{
|
|
42
|
+
uri: uri.href,
|
|
43
|
+
mimeType: 'application/json',
|
|
44
|
+
text: truncateForResponse(payload),
|
|
45
|
+
},
|
|
46
|
+
],
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Дженерик Shape нужен ровно для одного: чтобы TS проверил, что тип args
|
|
51
|
+
* хендлера согласован с переданной zod-схемой (иначе рассинхрон схемы и
|
|
52
|
+
* реализации ловится только в рантайме).
|
|
53
|
+
*
|
|
54
|
+
* В сам SDK схема уходит уже расширенной до ZodRawShapeCompat: ToolCallback —
|
|
55
|
+
* условный тип, и на нерезолвнутом Shape он остаётся отложенным, из-за чего
|
|
56
|
+
* ни одна конкретная функция под него не подходит (TS2352). На конкретном
|
|
57
|
+
* ZodRawShapeCompat он резолвится в (args: Record<string, any>) => …, и
|
|
58
|
+
* единственное сужение — as ShapeOutput<Shape> — стоит ровно на границе,
|
|
59
|
+
* где SDK уже провалидировал args настоящей zod-схемой.
|
|
60
|
+
*/
|
|
61
|
+
function registerJsonTool(server, index, name, description, inputSchema, handler) {
|
|
62
|
+
const widenedSchema = inputSchema;
|
|
63
|
+
const cb = async (args) => toToolResult(handler(index, args));
|
|
64
|
+
server.registerTool(name, { description, inputSchema: widenedSchema }, cb);
|
|
65
|
+
}
|
|
66
|
+
function main() {
|
|
67
|
+
const index = loadIndex();
|
|
68
|
+
const server = new McpServer({ name: '@digital-finance-ui/ui-kit-mcp', version: '0.1.0' });
|
|
69
|
+
registerJsonTool(server, index, 'list_components', 'Список компонентов @sber-digital-finance-ui/ui-kit с фильтрами по типу (wrapper/composition/standalone/form), категории ("Локальные компоненты" / "Композиции" / "Формы" — количество по типам см. в ресурсе sber-digital-finance-ui-ui-kit://catalog/categories), scope. По умолчанию — только самостоятельные компоненты (role: "primary", ~177 из 243): слоты вроде DrawerDFHeader и служебные примитивы вроде CanvasRect скрыты, они видны через relatedExports в карточке владельца (get_component) или напрямую по имени; role: "all" снимает фильтр. Без limit список бюджетируется автоматически (см. shown/total/truncationNotice в ответе); limit/offset — явная пагинация.', {
|
|
70
|
+
type: z.string().optional(),
|
|
71
|
+
category: z.string().optional(),
|
|
72
|
+
scope: z.string().optional(),
|
|
73
|
+
role: z.enum(['primary', 'part', 'internal', 'all']).optional(),
|
|
74
|
+
limit: z.number().int().positive().optional(),
|
|
75
|
+
offset: z.number().int().nonnegative().optional(),
|
|
76
|
+
}, listComponents);
|
|
77
|
+
registerJsonTool(server, index, 'search_components', 'Поиск по свободному запросу (рус/англ) сразу по трём сущностям: компоненты, их фичи и типы (в том числе по тексту определения типа — так находится нужное имя, когда оно заранее неизвестно: "отрисовать свою ячейку" → CellContent/ColumnConfig). Включает disambiguation-подсказки (например "таблица" → TableCanvas).', {
|
|
78
|
+
query: z.string(),
|
|
79
|
+
limit: z.number().int().positive().max(50).optional(),
|
|
80
|
+
}, searchComponents);
|
|
81
|
+
registerJsonTool(server, index, 'get_component', 'Компактная карточка компонента: тип, категория, hint, importStatement, имена пропсов, compound-части, список фичей. Для деталей используйте get_component_props/get_component_examples.', { name: z.string() }, getComponent);
|
|
82
|
+
registerJsonTool(server, index, 'get_component_props', 'Полные пропсы компонента (собственные + унаследованные от атомарного @salutejs/sdds-finai компонента). part — для compound-частей (например "Header" у DrawerDF).', { name: z.string(), part: z.string().optional() }, getComponentProps);
|
|
83
|
+
registerJsonTool(server, index, 'get_component_examples', 'Примеры кода компонента. Без title — список заголовков + первый пример; с title — конкретный пример.', { name: z.string(), title: z.string().optional() }, getComponentExamples);
|
|
84
|
+
registerJsonTool(server, index, 'get_type', 'Разворачивает именованный тип, встреченный в тексте пропса (например columnConfig: readonly ColumnConfig<Row>[] — get_component_props покажет только имя ColumnConfig, этот тул отдаёт само определение и готовый import). Некоторые имена неоднозначны (TableCanvas переиспользует общие имена типов) — тогда тул вернёт список квалифицированных ключей вида "TableCanvas.ColumnConfig" для уточнения.', { name: z.string() }, getType);
|
|
85
|
+
registerJsonTool(server, index, 'list_features', 'Список фичей компонента (актуально для TableCanvas/Table — десятки фичей вроде Filtering/Sorting/CopyPasteFill, недоступных иначе).', { component: z.string() }, listFeatures);
|
|
86
|
+
registerJsonTool(server, index, 'get_feature', 'Документация и API конкретной фичи компонента (без тел примеров). Регистронезависимо, понимает вложенные пути вроде "CanvasElements/CanvasText".', { component: z.string(), feature: z.string() }, getFeature);
|
|
87
|
+
registerJsonTool(server, index, 'get_feature_examples', 'Примеры кода конкретной фичи. Без title — список заголовков + первый пример.', {
|
|
88
|
+
component: z.string(),
|
|
89
|
+
feature: z.string(),
|
|
90
|
+
title: z.string().optional(),
|
|
91
|
+
}, getFeatureExamples);
|
|
92
|
+
/**
|
|
93
|
+
* list_categories и get_installation_guide не принимают аргументов и не
|
|
94
|
+
* зависят от них — это статический контент за один вызов на сессию, а не
|
|
95
|
+
* тул с параметрами выбора. Ресурсы (T8) не занимают слот в списке тулов,
|
|
96
|
+
* который агент читает при каждом запросе; значения category, которые
|
|
97
|
+
* раньше приходилось узнавать через list_categories(), теперь прямо в
|
|
98
|
+
* описании list_components (см. ниже).
|
|
99
|
+
*/
|
|
100
|
+
server.registerResource('categories', 'sber-digital-finance-ui-ui-kit://catalog/categories', {
|
|
101
|
+
title: 'Категории компонентов @sber-digital-finance-ui/ui-kit',
|
|
102
|
+
description: 'Категории каталога с количеством компонентов по типам (wrapper/composition/standalone/form).',
|
|
103
|
+
mimeType: 'application/json',
|
|
104
|
+
}, async (uri) => toResourceResult(uri, listCategories(index)));
|
|
105
|
+
server.registerResource('installation-guide', 'sber-digital-finance-ui-ui-kit://catalog/installation-guide', {
|
|
106
|
+
title: 'Гайд по установке @sber-digital-finance-ui/ui-kit',
|
|
107
|
+
description: 'Установка пакета и подключение стилей/токенов, использование компонентов и иконок.',
|
|
108
|
+
mimeType: 'application/json',
|
|
109
|
+
}, async (uri) => toResourceResult(uri, getInstallationGuide(index)));
|
|
110
|
+
const transport = new StdioServerTransport();
|
|
111
|
+
server.connect(transport);
|
|
112
|
+
}
|
|
113
|
+
main();
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { isOkComponent } from '../types.js';
|
|
2
|
+
import { findComponent, listComponentFeatures, summarizeProp, } from './shared.js';
|
|
3
|
+
/**
|
|
4
|
+
* Сколько необязательных пропсов с описанием показывать в компактной
|
|
5
|
+
* карточке сверх обязательных. У широких API (TableGlideInstance — 153
|
|
6
|
+
* своих пропса) весь список отдавать здесь бессмысленно — карточка
|
|
7
|
+
* задумана как дешёвый шаг выбора компонента, а не замена
|
|
8
|
+
* get_component_props.
|
|
9
|
+
*/
|
|
10
|
+
const MAX_OPTIONAL_OWN_PROPS_SHOWN = 10;
|
|
11
|
+
/**
|
|
12
|
+
* required-пропсы — всегда (без них компонент не собрать), плюс до
|
|
13
|
+
* MAX_OPTIONAL_OWN_PROPS_SHOWN "значимых" необязательных: с описанием и не
|
|
14
|
+
* deprecated (без описания в компактной карточке от пропса пользы ноль, а
|
|
15
|
+
* deprecated не должны конкурировать за место с живыми пропсами).
|
|
16
|
+
*/
|
|
17
|
+
function selectOwnProps(props) {
|
|
18
|
+
const required = props.filter((p) => p.required);
|
|
19
|
+
const significantOptional = props.filter((p) => !p.required && p.description && !p.deprecated);
|
|
20
|
+
return [
|
|
21
|
+
...required,
|
|
22
|
+
...significantOptional.slice(0, MAX_OPTIONAL_OWN_PROPS_SHOWN),
|
|
23
|
+
];
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* Компактная карточка компонента — без полных доков и без тел примеров.
|
|
27
|
+
* Замеры на существующем meta.json показали: полная запись TableCanvas
|
|
28
|
+
* весит 682k символов, что целиком исчерпало бы контекст агента одним
|
|
29
|
+
* вызовом. Здесь — только то, что нужно решить "это ли компонент" и куда
|
|
30
|
+
* идти дальше за деталями.
|
|
31
|
+
*/
|
|
32
|
+
export function getComponent(index, { name } = {}) {
|
|
33
|
+
const record = findComponent(index, name);
|
|
34
|
+
if (!record) {
|
|
35
|
+
return {
|
|
36
|
+
error: `Компонент "${name}" не найден. Используйте search_components или list_components.`,
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
if (!isOkComponent(record)) {
|
|
40
|
+
return { error: record.error };
|
|
41
|
+
}
|
|
42
|
+
const features = listComponentFeatures(index, record.name);
|
|
43
|
+
const exampleTitles = (record.examples || []).map((e) => e.displayName || e.exportName);
|
|
44
|
+
const allOwnProps = record.props || [];
|
|
45
|
+
const shownOwnProps = selectOwnProps(allOwnProps);
|
|
46
|
+
const hiddenOwnPropsCount = allOwnProps.length - shownOwnProps.length;
|
|
47
|
+
const { compoundPartOf } = record;
|
|
48
|
+
// Настоящих примеров нет (exampleTitles: []) — незачем звать инструмент,
|
|
49
|
+
// который вернёт то же самое, что уже есть в minimalUsage этой карточки.
|
|
50
|
+
const examplesHint = exampleTitles.length
|
|
51
|
+
? '; get_component_examples({name}) — примеры кода'
|
|
52
|
+
: '';
|
|
53
|
+
const nextSteps = compoundPartOf
|
|
54
|
+
? `Это одновременно compound-часть "${compoundPartOf.part}" у "${compoundPartOf.component}" — за пропсами идите туда: get_component_props({name: ${JSON.stringify(compoundPartOf.component)}, part: ${JSON.stringify(compoundPartOf.part)}})${examplesHint}${features.length ? '; list_features({component}) — фичи компонента' : ''}`
|
|
55
|
+
: `get_component_props({name}) — полные пропсы${hiddenOwnPropsCount > 0
|
|
56
|
+
? ` (в карточке показано ${shownOwnProps.length} из ${allOwnProps.length})`
|
|
57
|
+
: ''}${examplesHint}${features.length ? '; list_features({component}) — фичи компонента' : ''}`;
|
|
58
|
+
return {
|
|
59
|
+
name: record.name,
|
|
60
|
+
type: record.type,
|
|
61
|
+
category: record.category,
|
|
62
|
+
description: record.description || undefined,
|
|
63
|
+
hint: record.hint || undefined,
|
|
64
|
+
keywords: record.keywords,
|
|
65
|
+
importStatement: record.importStatement,
|
|
66
|
+
deprecated: record.deprecated || undefined,
|
|
67
|
+
deprecationReason: record.deprecationReason,
|
|
68
|
+
legacy: record.legacy || undefined,
|
|
69
|
+
supersededBy: record.supersededBy,
|
|
70
|
+
chooseWhen: record.chooseWhen,
|
|
71
|
+
gotchas: record.gotchas,
|
|
72
|
+
scope: record.scope,
|
|
73
|
+
formVariant: record.formVariant,
|
|
74
|
+
wrappedBy: record.wrappedBy,
|
|
75
|
+
role: record.role !== 'primary' ? record.role : undefined,
|
|
76
|
+
parentComponent: record.parentComponent,
|
|
77
|
+
relatedExports: record.relatedExports,
|
|
78
|
+
compoundPartOf,
|
|
79
|
+
atomicBase: record.atomicBase,
|
|
80
|
+
atomicDataMissing: record.atomicDataMissing || undefined,
|
|
81
|
+
...(compoundPartOf
|
|
82
|
+
? {}
|
|
83
|
+
: {
|
|
84
|
+
ownProps: shownOwnProps.map(summarizeProp),
|
|
85
|
+
ownPropsCount: allOwnProps.length,
|
|
86
|
+
inheritedPropsCount: (record.inheritedProps || []).length,
|
|
87
|
+
}),
|
|
88
|
+
compoundParts: (record.compoundParts || []).map((p) => p.name),
|
|
89
|
+
minimalUsage: record.minimalUsage,
|
|
90
|
+
exampleTitles,
|
|
91
|
+
features: features.map((f) => ({
|
|
92
|
+
feature: f.feature,
|
|
93
|
+
legacy: f.legacy || undefined,
|
|
94
|
+
})),
|
|
95
|
+
dataVersionNotice: index.dataVersionNotice,
|
|
96
|
+
nextSteps,
|
|
97
|
+
};
|
|
98
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { isOkComponent } from '../types.js';
|
|
2
|
+
import { findComponent } from './shared.js';
|
|
3
|
+
export function getComponentExamples(index, { name, title } = {}) {
|
|
4
|
+
const record = findComponent(index, name);
|
|
5
|
+
if (!record) {
|
|
6
|
+
return { error: `Компонент "${name}" не найден.` };
|
|
7
|
+
}
|
|
8
|
+
if (!isOkComponent(record)) {
|
|
9
|
+
return { error: record.error };
|
|
10
|
+
}
|
|
11
|
+
const examples = record.examples || [];
|
|
12
|
+
if (!title) {
|
|
13
|
+
return {
|
|
14
|
+
name: record.name,
|
|
15
|
+
titles: examples.map((e) => e.displayName || e.exportName),
|
|
16
|
+
example: examples[0],
|
|
17
|
+
};
|
|
18
|
+
}
|
|
19
|
+
const found = examples.find((e) => (e.displayName || '').toLowerCase() === title.toLowerCase() ||
|
|
20
|
+
(e.exportName || '').toLowerCase() === title.toLowerCase());
|
|
21
|
+
if (!found) {
|
|
22
|
+
return {
|
|
23
|
+
error: `Пример "${title}" не найден у "${record.name}". Доступные: ${examples.map((e) => e.displayName || e.exportName).join(', ') || '(нет)'}`,
|
|
24
|
+
};
|
|
25
|
+
}
|
|
26
|
+
return { name: record.name, example: found };
|
|
27
|
+
}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
import { isOkComponent } from '../types.js';
|
|
2
|
+
import { findComponent } from './shared.js';
|
|
3
|
+
/**
|
|
4
|
+
* Пустой props[] у generic-типа — не факт "у компонента нет пропсов", а
|
|
5
|
+
* иногда деградация индексера (структурный резолв генерика не прошёл
|
|
6
|
+
* эвристики безопасности, см. tryExtractGenericProps в parseComponent.ts,
|
|
7
|
+
* и откатился на сырой текст типа). Без явного сигнала агент, полагающийся
|
|
8
|
+
* только на MCP, не может отличить одно от другого и рискует придумать
|
|
9
|
+
* пропсы по общему паттерну (реальный кейс — FormMask до фикса индексера).
|
|
10
|
+
*/
|
|
11
|
+
function genericEmptyPropsWarning(isGeneric, propsLength) {
|
|
12
|
+
if (!isGeneric || propsLength > 0)
|
|
13
|
+
return undefined;
|
|
14
|
+
return ('Пропсы не резолвлены (сложный generic-тип) — пустой props[] не значит, ' +
|
|
15
|
+
'что у компонента их нет. Проверь rawType в этом же ответе, попробуй ' +
|
|
16
|
+
'get_component_examples, а для компонентов с wrappedBy/atomicBase — ' +
|
|
17
|
+
'get_component_props по этому имени.');
|
|
18
|
+
}
|
|
19
|
+
export function getComponentProps(index, { name, part } = {}) {
|
|
20
|
+
const record = findComponent(index, name);
|
|
21
|
+
if (!record) {
|
|
22
|
+
return { error: `Компонент "${name}" не найден.` };
|
|
23
|
+
}
|
|
24
|
+
if (!isOkComponent(record)) {
|
|
25
|
+
return { error: record.error };
|
|
26
|
+
}
|
|
27
|
+
if (part) {
|
|
28
|
+
const compoundPart = (record.compoundParts || []).find((p) => p.name.toLowerCase() === part.toLowerCase());
|
|
29
|
+
if (!compoundPart) {
|
|
30
|
+
return {
|
|
31
|
+
error: `Compound-часть "${part}" не найдена у "${record.name}". Доступные: ${(record.compoundParts || []).map((p) => p.name).join(', ') || '(нет)'}`,
|
|
32
|
+
};
|
|
33
|
+
}
|
|
34
|
+
const compoundPartProps = compoundPart.props || [];
|
|
35
|
+
return {
|
|
36
|
+
name: record.name,
|
|
37
|
+
part: compoundPart.name,
|
|
38
|
+
propsTypeName: compoundPart.typeName,
|
|
39
|
+
rawType: compoundPart.rawType,
|
|
40
|
+
isGeneric: compoundPart.isGeneric || undefined,
|
|
41
|
+
props: compoundPartProps,
|
|
42
|
+
warning: genericEmptyPropsWarning(compoundPart.isGeneric, compoundPartProps.length),
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
const props = record.props || [];
|
|
46
|
+
return {
|
|
47
|
+
name: record.name,
|
|
48
|
+
propsTypeName: record.propsTypeName,
|
|
49
|
+
rawType: record.rawType,
|
|
50
|
+
isGeneric: record.isGeneric || undefined,
|
|
51
|
+
props,
|
|
52
|
+
inheritedProps: record.inheritedProps || [],
|
|
53
|
+
atomicBase: record.atomicBase,
|
|
54
|
+
atomicDataMissing: record.atomicDataMissing || undefined,
|
|
55
|
+
compoundPartOf: record.compoundPartOf,
|
|
56
|
+
dataVersionNotice: index.dataVersionNotice,
|
|
57
|
+
warning: genericEmptyPropsWarning(record.isGeneric, props.length),
|
|
58
|
+
};
|
|
59
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { findFeature } from './shared.js';
|
|
2
|
+
export function getFeature(index, { component, feature } = {}) {
|
|
3
|
+
const found = findFeature(index, component, feature);
|
|
4
|
+
if (!found) {
|
|
5
|
+
return {
|
|
6
|
+
error: `Фича "${feature}" не найдена у "${component}". Используйте list_features({component}).`,
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
return {
|
|
10
|
+
component: found.component,
|
|
11
|
+
feature: found.feature,
|
|
12
|
+
legacy: found.legacy || undefined,
|
|
13
|
+
docs: found.docs,
|
|
14
|
+
apiDocs: found.apiDocs,
|
|
15
|
+
api: found.api || [],
|
|
16
|
+
exampleTitles: (found.stories || []).map((s) => s.displayName || s.exportName),
|
|
17
|
+
};
|
|
18
|
+
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { findFeature } from './shared.js';
|
|
2
|
+
export function getFeatureExamples(index, { component, feature, title } = {}) {
|
|
3
|
+
const found = findFeature(index, component, feature);
|
|
4
|
+
if (!found) {
|
|
5
|
+
return {
|
|
6
|
+
error: `Фича "${feature}" не найдена у "${component}". Используйте list_features({component}).`,
|
|
7
|
+
};
|
|
8
|
+
}
|
|
9
|
+
const stories = found.stories || [];
|
|
10
|
+
if (!title) {
|
|
11
|
+
return {
|
|
12
|
+
component: found.component,
|
|
13
|
+
feature: found.feature,
|
|
14
|
+
titles: stories.map((s) => s.displayName || s.exportName),
|
|
15
|
+
example: stories[0],
|
|
16
|
+
};
|
|
17
|
+
}
|
|
18
|
+
const story = stories.find((s) => (s.displayName || '').toLowerCase() === title.toLowerCase() ||
|
|
19
|
+
(s.exportName || '').toLowerCase() === title.toLowerCase());
|
|
20
|
+
if (!story) {
|
|
21
|
+
return {
|
|
22
|
+
error: `Пример "${title}" не найден у "${component}/${feature}". Доступные: ${stories.map((s) => s.displayName || s.exportName).join(', ') || '(нет)'}`,
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
return { component: found.component, feature: found.feature, example: story };
|
|
26
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { isOkComponent } from '../types.js';
|
|
2
|
+
/** Сколько похожих имён показывать при промахе — список подсказок, а не выгрузка индекса. */
|
|
3
|
+
const MAX_SUGGESTIONS = 8;
|
|
4
|
+
/** Опечатка в одну-две буквы — да; произвольно похожее имя — нет. */
|
|
5
|
+
const MAX_TYPO_DISTANCE = 2;
|
|
6
|
+
/** Расстояние Левенштейна на двух строках (итеративный вариант с одной строкой матрицы). */
|
|
7
|
+
function editDistance(a, b) {
|
|
8
|
+
if (Math.abs(a.length - b.length) > MAX_TYPO_DISTANCE) {
|
|
9
|
+
return MAX_TYPO_DISTANCE + 1;
|
|
10
|
+
}
|
|
11
|
+
let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
|
|
12
|
+
for (let i = 1; i <= a.length; i += 1) {
|
|
13
|
+
const current = [i];
|
|
14
|
+
for (let j = 1; j <= b.length; j += 1) {
|
|
15
|
+
const cost = a[i - 1] === b[j - 1] ? 0 : 1;
|
|
16
|
+
current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + cost);
|
|
17
|
+
}
|
|
18
|
+
previous = current;
|
|
19
|
+
}
|
|
20
|
+
return previous[b.length];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Имена типов длинные и составные (`ColumnsGroupingConfig`,
|
|
24
|
+
* `CellInfoGlideInstance`), поэтому промах чаще всего означает "агент угадал
|
|
25
|
+
* половину имени", а не "такого типа нет". Ищем по вхождению подстроки в обе
|
|
26
|
+
* стороны: и когда запрос — часть реального имени (`Cell` → `CellInfo`), и
|
|
27
|
+
* когда реальное имя — часть запроса (`TableCanvas.TableConfig` → `TableConfig`).
|
|
28
|
+
*/
|
|
29
|
+
function findSimilarKeys(index, lowerName) {
|
|
30
|
+
const substringHits = Object.keys(index.types)
|
|
31
|
+
.filter((key) => {
|
|
32
|
+
const lowerKey = key.toLowerCase();
|
|
33
|
+
const bare = index.types[key].name.toLowerCase();
|
|
34
|
+
return (lowerKey.includes(lowerName) ||
|
|
35
|
+
lowerName.includes(bare) ||
|
|
36
|
+
bare.includes(lowerName));
|
|
37
|
+
})
|
|
38
|
+
.slice(0, MAX_SUGGESTIONS);
|
|
39
|
+
if (substringHits.length > 0)
|
|
40
|
+
return substringHits;
|
|
41
|
+
// Подстрока не спасает от опечатки: "ColumnConfg" не является подстрокой
|
|
42
|
+
// "ColumnConfig" и наоборот, а именно опечатка — самый частый способ
|
|
43
|
+
// промахнуться мимо длинного составного имени. Расстояние ≤ 2 ловит
|
|
44
|
+
// пропущенную/лишнюю/переставленную букву и при этом не превращает подсказки
|
|
45
|
+
// в случайный список.
|
|
46
|
+
return Object.keys(index.types)
|
|
47
|
+
.map((key) => ({
|
|
48
|
+
key,
|
|
49
|
+
distance: editDistance(index.types[key].name.toLowerCase(), lowerName),
|
|
50
|
+
}))
|
|
51
|
+
.filter((c) => c.distance <= MAX_TYPO_DISTANCE)
|
|
52
|
+
.sort((a, b) => a.distance - b.distance)
|
|
53
|
+
.slice(0, MAX_SUGGESTIONS)
|
|
54
|
+
.map((c) => c.key);
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Кандидаты неоднозначного имени вместе с тем, чем они отличаются: без этого
|
|
58
|
+
* агент выбирает вслепую между `Table.ContentFormat` и
|
|
59
|
+
* `TableCanvas.ContentFormat` и вполне может уйти в легаси-ветку. Внутренние
|
|
60
|
+
* типы помечаются сразу — по ним второй вызов делать бессмысленно.
|
|
61
|
+
*/
|
|
62
|
+
function describeCandidate(key, record) {
|
|
63
|
+
if (record.internal)
|
|
64
|
+
return `${key} (внутренний, импортировать нельзя)`;
|
|
65
|
+
return `${key} (${record.importPath})`;
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* Тип пропсов компонента (`TableCanvasProps`, `ModalDFProps`) в индексе типов
|
|
69
|
+
* не лежит — он развёрнут в `props[]` записи компонента. Агент этого не знает
|
|
70
|
+
* и идёт за ним в get_type (в реальном логе — именно так), поэтому вместо
|
|
71
|
+
* "не найден" отправляем его туда, где ответ есть.
|
|
72
|
+
*/
|
|
73
|
+
function findComponentByPropsTypeName(index, name) {
|
|
74
|
+
const lowerName = name.toLowerCase();
|
|
75
|
+
return Object.values(index.components).find((record) => isOkComponent(record) &&
|
|
76
|
+
(record.propsTypeName || '').toLowerCase() === lowerName)?.name;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Разворачивает именованный тип, встреченный в тексте пропса компонента
|
|
80
|
+
* (например `columnConfig: readonly ColumnConfig<Row>[]` — get_component_props
|
|
81
|
+
* покажет только имя, этот тул — само определение и готовый import).
|
|
82
|
+
*
|
|
83
|
+
* Некоторые имена неоднозначны: TableCanvas активно переиспользует общие
|
|
84
|
+
* имена типов (свой ColumnConfig, отдельный от легаси-Table.ColumnConfig) —
|
|
85
|
+
* такие типы лежат в индексе под квалифицированным ключом "Папка.Имя". Если
|
|
86
|
+
* запрошено голое имя и оно неоднозначно, возвращаем не первый попавшийся
|
|
87
|
+
* вариант, а список кандидатов для уточнения — тихо угадать здесь хуже, чем
|
|
88
|
+
* спросить: `import { ColumnConfig } from '@sber-digital-finance-ui/ui-kit'` без разбора может
|
|
89
|
+
* оказаться совсем не тем ColumnConfig, который агент имел в виду.
|
|
90
|
+
*
|
|
91
|
+
* Промах не должен быть тупиком: индекс типов заведомо не полон (в нём типы
|
|
92
|
+
* пропсов и то, на что они ссылаются вглубь), а агент, получивший голое "не
|
|
93
|
+
* найдено", уходит читать node_modules руками. Поэтому при промахе отдаём
|
|
94
|
+
* похожие имена и, если спрашивали тип пропсов, — отсылку к нужному тулу.
|
|
95
|
+
*/
|
|
96
|
+
export function getType(index, { name } = {}) {
|
|
97
|
+
if (!name) {
|
|
98
|
+
return { error: 'Не указано имя типа.' };
|
|
99
|
+
}
|
|
100
|
+
const direct = index.types[name];
|
|
101
|
+
if (direct)
|
|
102
|
+
return direct;
|
|
103
|
+
const lowerName = name.toLowerCase();
|
|
104
|
+
const ciKeyMatch = Object.entries(index.types).find(([key]) => key.toLowerCase() === lowerName);
|
|
105
|
+
if (ciKeyMatch)
|
|
106
|
+
return ciKeyMatch[1];
|
|
107
|
+
const candidates = Object.entries(index.types).filter(([, t]) => t.name.toLowerCase() === lowerName);
|
|
108
|
+
if (candidates.length > 0) {
|
|
109
|
+
const keys = candidates
|
|
110
|
+
.map(([key, record]) => describeCandidate(key, record))
|
|
111
|
+
.join('; ');
|
|
112
|
+
return {
|
|
113
|
+
error: `Тип "${name}" неоднозначен — в ui-kit несколько разных типов с этим именем в разных модулях. Уточните одним из ключей: ${keys}.`,
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
const ownerComponent = findComponentByPropsTypeName(index, name);
|
|
117
|
+
if (ownerComponent) {
|
|
118
|
+
return {
|
|
119
|
+
error: `"${name}" — тип пропсов компонента ${ownerComponent}, в индексе типов его нет: ` +
|
|
120
|
+
`пропсы разобраны по полям. Используйте get_component_props({name: "${ownerComponent}"}).`,
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
const similar = findSimilarKeys(index, lowerName);
|
|
124
|
+
if (similar.length > 0) {
|
|
125
|
+
return {
|
|
126
|
+
error: `Тип "${name}" не найден в индексе. Похожие имена: ${similar.join(', ')}. ` +
|
|
127
|
+
'Если нужного нет и среди них — тип внутренний для ui-kit и наружу не экспортирован; ' +
|
|
128
|
+
'его форму можно увидеть в определении типа, который на него ссылается.',
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
return {
|
|
132
|
+
error: `Тип "${name}" не найден в индексе. В индекс попадают типы, названные в пропсах компонентов, ` +
|
|
133
|
+
'и то, на что они ссылаются вглубь. Проверьте имя через get_component_props нужного компонента — ' +
|
|
134
|
+
'там типы полей приведены ровно так, как их печатает тайпчекер.',
|
|
135
|
+
};
|
|
136
|
+
}
|