@finedesign/cli 0.4.0 → 0.5.1

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.
@@ -2,15 +2,15 @@
2
2
  "schemaVersion": 1,
3
3
  "version": "1.25.0",
4
4
  "sourceKind": "repository-snapshot",
5
- "sourceRevision": "f3b3f5e7beeab4daa6b50769926aefeb7307397c",
5
+ "sourceRevision": "a88c1a76dc006929aa6ab9ce4f9de4ad0e926d0c",
6
6
  "sourceDirty": false,
7
- "contentHash": "03496e7d7b1884c260875186dc5ab970406b841e2efb4392ad8cbacb61cc7e3b",
8
- "catalogSha256": "c05adc6576ace248890df647a8ba1c6f3730b1548c37429ce7d7d72cdab77f21",
7
+ "contentHash": "c2edf1d31c61e83fa7996dca770a5e9ef87a5e67ce5fd55ccd4922a6e6bfe450",
8
+ "catalogSha256": "4b911bc129ea5a13070e2fcfac3a2f8d61087beb2758d2ae50b46e99180bba18",
9
9
  "skillFiles": {
10
10
  "references/component-guide.md": "612948840948e65f250998231eaa16fc41e8e27b9c03b19af32571422ca8185a",
11
11
  "references/docs-slug-map.md": "440ce5cf137fd22eabfcc5b51c3f55b85174aa643773ef0cedd5df542e77bbc2",
12
- "references/imports-and-setup.md": "5bd9024770a77ddeb0f4dce94ebd103f327c2513b52f165e371da9c4dbdcd98f",
12
+ "references/imports-and-setup.md": "9a404ad7243f0fa734d34c5fd0106287ededf36bbc1693812917ce9cb9780e40",
13
13
  "references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
14
- "SKILL.md": "b8ef63aa9aef7cf6cb8f83556b6c09760fc4707f0466d25eb1fac8f2fed6b2a9"
14
+ "SKILL.md": "512ecee9c5208436cda70c56cd691354ab83e2d85115c4bc6f3c1e0658e458ba"
15
15
  }
16
16
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.4.0",
3
+ "version": "0.5.1",
4
4
  "description": "Read-only, versioned Fine Design documentation for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {
@@ -13,9 +13,9 @@ Use `/fine-design` for component pages, fixes, and reviews. This folder guides A
13
13
 
14
14
  1. Identify the deliverable and runtime: existing package-based project, standalone browser page, fix, or read-only review. Standalone HTML and embedded pages may use the public CDN runtime without npm or private-registry credentials. Preserve compatible existing components and explicit user choices; follow [imports-and-setup.md](references/imports-and-setup.md) for runtime selection.
15
15
  2. In a package-based project, resolve Fine Design and React versions from installed packages or the lockfile; in this repository use the checked-out package and sources. In browser mode, use the selected runtime manifest and its compatibility evidence rather than requiring an installed package. State unknown versions instead of inventing them or upgrading dependencies to fit examples.
16
- 3. When matching-version data is available, prefer the connected Fine Design MCP tools; otherwise use the local `fine-design` CLI with `--format json` and the exact target component version. Query only the components and examples needed (`list`, `search`, `info <component>` for API tables, `token [component]` for Design Tokens, `doc <component> --toc`, `example <component> <id>`). Check the installed tool's help before using optional commands such as `doctor`, `info`, `token`, `lint`, `diff`, or `doc --toc`; older releases do not provide them. If the version is unknown or unsupported, use matching local documentation/public declarations or verify browser exports and behavior; do not substitute another catalog version. Resolve website pages through [docs-slug-map.md](references/docs-slug-map.md), with remaining compatibility gaps stated.
17
- 4. For ordinary component work, read the relevant sections of [component-guide.md](references/component-guide.md). Consult other references only for the conditions below.
18
- 5. Run the existing build/type check appropriate to the change (plus `fine-design lint <file>` when available) and verify an affected interaction with local test data. Fix introduced failures and recheck. Report actual results and unverified behavior; reviews remain read-only.
16
+ 3. Query only the components needed at the exact target version. Prefer connected Fine Design MCP tools when matching-version data is available, or use the local CLI with `--format json`. Start with `info <component>` or `doc <component> --toc`. Fetch `example <component> <id>` source only when needed. Use `search` for unknown component names and `token` for theming. Check the installed CLI's help for supported commands. If the version is unknown or unsupported, consult matching local declarations/docs or verify browser exports and behavior. Resolve website pages through [docs-slug-map.md](references/docs-slug-map.md).
17
+ 4. Use the relevant sections of [component-guide.md](references/component-guide.md) for component selection and API traps. Consult other references only for the conditions below.
18
+ 5. Run the existing build/type check (plus `fine-design lint <file>` when available) and verify the affected interaction with local test data. Report verified and unverified behavior. Reviews remain read-only.
19
19
 
20
20
  ## Core Contracts
21
21
 
@@ -2,7 +2,9 @@
2
2
 
3
3
  ## Version And Compatibility
4
4
 
5
- - Choose the runtime first: reuse package imports in an existing React project; use browser/CDN scripts for a requested standalone HTML or embedded page. A missing project `.npmrc` alone does not decide the runtime.
5
+ - Use the private `@fx-ui/fine-design` package for React projects with a build step and a lockfile. Reuse the project's component version, imports and stylesheet setup.
6
+ - Use the public UMD files for a standalone HTML deliverable, a no-build embed or a browser prototype. If a standalone page must keep a version long term, host the complete matching resource set yourself and keep its SRI checks.
7
+ - Use the public `@finedesign/cli` or its MCP for API lookup and lint. An explicit supported version allows queries before either component runtime is installed. A missing project `.npmrc` alone does not decide the runtime.
6
8
  - For package imports, resolve Fine Design, React, and ReactDOM versions from installed packages or the lockfile; a `package.json` range is not an exact version. For browser scripts, use the runtime manifest described below; no local npm installation is required.
7
9
  - In the Fine Design repository, use the checked-out docs, exports, and demos. In consuming projects, prefer matching-version docs and verify uncertain APIs against installed public declarations/exports. Current website content and skill defaults must not override that contract.
8
10
  - If docs are unavailable, use matching local declarations and examples; inspect only unresolved implementation details. State remaining uncertainty. Do not upgrade dependencies merely to fit an example, or infer full React-major compatibility from a permissive peer range.
package/src/cli.mjs CHANGED
@@ -3,6 +3,7 @@ import path from 'node:path';
3
3
  import { fileURLToPath } from 'node:url';
4
4
  import { parseArgs } from 'node:util';
5
5
  import { queryCatalog, getComponentInfo, getComponentTokens, diffCatalogs } from './core/catalog.mjs';
6
+ import { validateInput } from './core/contracts.mjs';
6
7
  import { loadCatalog, readIndex } from './core/data.mjs';
7
8
  import { resolveLintVersion, resolveVersion } from './core/version.mjs';
8
9
  import { ToolError, errorResult } from './core/errors.mjs';
@@ -17,7 +18,7 @@ Commands:
17
18
  info <component> Show component overview and API/props sections
18
19
  doc <component> Read component documentation
19
20
  token [component] [query] Inspect component or global Design Tokens
20
- example <component> <id> Read source files and asset metadata
21
+ example <component> [id] List examples or read one example's source and asset metadata
21
22
  lint [files-or-dirs...] Scan code for Fine Design API traps and invalid imports
22
23
  diff [fromVer] [toVer] Compare component changes and migrations between versions
23
24
  doctor Inspect detected version, available catalogs and bundled Skill
@@ -27,13 +28,14 @@ Commands:
27
28
  Options:
28
29
  --fd-version <version> Exact Fine Design component version
29
30
  --project <directory> Project used to detect the installed version
31
+ --component <name> Compare only this component (diff command only)
30
32
  --runtime-url <url> Runtime hosting base URL (runtime command only)
31
33
  --format <text|json|markdown|html> Output format (markdown: doc/info/token; html: runtime)
32
34
  --section <heading> Doc section heading (exact or case-insensitive)
33
35
  --toc, --summary Show only doc metadata, section headings and example IDs
34
36
  --offset <number> Search pagination offset
35
37
  --limit <number> Search page size (1..200, default 20)
36
- --include-assets Include binary base64 and oversized JSON fixture content
38
+ --include-assets Include binary base64 and oversized JSON fixtures (requires example ID)
37
39
  --help Show help
38
40
  --version Show tool version`;
39
41
 
@@ -58,7 +60,10 @@ function runDoctor(values) {
58
60
  }
59
61
  } catch (error) {
60
62
  if (error instanceof ToolError && error.code === 'VERSION_NOT_DETECTED') {
61
- suggestions = error.context?.suggestions || [];
63
+ suggestions = [
64
+ 'For standalone HTML or an online preview, run "fine-design runtime list --format json" first and use the hosted version for component lookups. Verify rendering in the target preview separately.',
65
+ ...(error.context?.suggestions || [])
66
+ ];
62
67
  } else {
63
68
  throw error;
64
69
  }
@@ -84,7 +89,7 @@ export async function main(argv) {
84
89
  help: { type: 'boolean' }, version: { type: 'boolean' }, 'fd-version': { type: 'string' }, project: { type: 'string' },
85
90
  format: { type: 'string' }, section: { type: 'string' }, toc: { type: 'boolean' }, summary: { type: 'boolean' },
86
91
  offset: { type: 'string' }, limit: { type: 'string' }, 'include-assets': { type: 'boolean' },
87
- 'runtime-url': { type: 'string' }
92
+ 'runtime-url': { type: 'string' }, component: { type: 'string' }
88
93
  }});
89
94
  format = values.format || 'text';
90
95
  if (!['text', 'json', 'markdown', 'html'].includes(format)) throw new ToolError('INVALID_ARGUMENT', 'Unknown output format.', 2);
@@ -94,6 +99,7 @@ export async function main(argv) {
94
99
  if (command === 'mcp' && args.length === 0 && argv.length === 1) { await (await import('./mcp.mjs')).startMcp(); return; }
95
100
  const summaryFlag = Boolean(values.toc || values.summary);
96
101
  if (command !== 'runtime' && (values['runtime-url'] !== undefined)) throw new ToolError('INVALID_ARGUMENT', 'Runtime options are only supported for runtime.', 2);
102
+ if (command !== 'diff' && values.component !== undefined) throw new ToolError('INVALID_ARGUMENT', '--component is only supported for diff.', 2);
97
103
  if (format === 'markdown' && !['doc', 'info', 'token'].includes(command)) {
98
104
  throw new ToolError('INVALID_ARGUMENT', 'Markdown output format is only supported for the doc, info and token commands.', 2);
99
105
  }
@@ -235,23 +241,29 @@ export async function main(argv) {
235
241
  }
236
242
  if (command === 'diff') {
237
243
  if (values.version || args.length > 2 || values.section !== undefined || summaryFlag || values.offset !== undefined || values.limit !== undefined || values['include-assets'] !== undefined || !['text', 'json'].includes(format)) {
238
- throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design diff [fromVersion] [toVersion] [--format text|json]', 2);
244
+ throw new ToolError('INVALID_ARGUMENT', 'Usage: fine-design diff [fromVersion] [toVersion] [--component <name>] [--format text|json]', 2);
239
245
  }
246
+ const { component } = validateInput('diff_catalogs', { component: values.component });
240
247
  const available = Object.keys(readIndex().versions).sort();
241
248
  const fromVer = args[0] || available[0];
242
249
  const toVer = args[1] || available.at(-1);
243
- const result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer));
250
+ const result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer), component);
244
251
  if (format === 'json') {
245
252
  console.log(JSON.stringify(result));
246
253
  } else {
247
254
  console.log([
248
- `Fine Design ${result.fromVersion} -> ${result.toVersion}`,
255
+ `Fine Design ${result.fromVersion} -> ${result.toVersion}${result.component ? ` (${result.component})` : ''}`,
249
256
  `Added components (${result.addedComponents.length}): ${result.addedComponents.map((c) => `${c.exports.join('/')} (${c.id})`).join(', ') || 'none'}`,
250
257
  `Removed components (${result.removedComponents.length}): ${result.removedComponents.map((c) => `${c.exports.join('/')} (${c.id})`).join(', ') || 'none'}`,
251
258
  `Updated components (${result.updatedComponents.length}):`,
252
- ...result.updatedComponents.map((c) => ` - ${c.exports.join('/')} (${c.id}):${c.addedSections.length ? ` +sections [${c.addedSections.join(', ')}]` : ''}${c.addedExamples.length ? ` +examples [${c.addedExamples.map((e) => e.id).join(', ')}]` : ''}${c.addedAliases?.length ? ` +aliases [${c.addedAliases.join(', ')}]` : ''}`),
253
- `Recommended migrations:`,
254
- ...result.migrations.map((m) => ` - ${m.legacy} -> ${m.recommended}: ${m.note}`)
259
+ ...result.updatedComponents.map(({ id, exports, ...changes }) => {
260
+ const details = Object.entries(changes).filter(([, items]) => items.length).map(([key, items]) => {
261
+ const label = key.replace(/[A-Z]/g, (letter) => ` ${letter.toLowerCase()}`);
262
+ return ` ${label}: ${items.map((item) => item.id ?? item).join(', ')}`;
263
+ });
264
+ return [` - ${exports.join('/')} (${id})`, ...details].join('\n');
265
+ }),
266
+ ...(result.migrations.length ? ['Recommended migrations:', ...result.migrations.map((m) => ` - ${m.legacy} -> ${m.recommended}: ${m.note}`)] : [])
255
267
  ].join('\n'));
256
268
  }
257
269
  return;
@@ -262,12 +274,12 @@ export async function main(argv) {
262
274
  values.version ||
263
275
  (command === 'search' && args.length > 1) ||
264
276
  (command === 'doc' && args.length !== 1) ||
265
- (command === 'example' && args.length !== 2) ||
277
+ (command === 'example' && (args.length < 1 || args.length > 2)) ||
266
278
  (values.section !== undefined && command !== 'doc') ||
267
279
  ((values.toc !== undefined || values.summary !== undefined) && command !== 'doc') ||
268
280
  (values.section !== undefined && summaryFlag) ||
269
281
  ((values.offset !== undefined || values.limit !== undefined) && command !== 'search') ||
270
- (values['include-assets'] !== undefined && command !== 'example')
282
+ (values['include-assets'] !== undefined && (command !== 'example' || args.length !== 2))
271
283
  ) {
272
284
  throw new ToolError('INVALID_ARGUMENT', 'Invalid command or arguments. Use --help for usage.', 2);
273
285
  }
@@ -289,7 +301,6 @@ export async function main(argv) {
289
301
  ...(command === 'example' && { exampleId: args[1], ...(values['include-assets'] !== undefined && { includeAssets: values['include-assets'] }) })
290
302
  })
291
303
  };
292
- const { validateInput } = await import('./core/contracts.mjs');
293
304
  validateInput(tools[command], input);
294
305
  const result = queryCatalog(loadCatalog(version), tools[command], input);
295
306
  if (format === 'json') {
@@ -329,6 +340,11 @@ ${result.sections ? `Sections: ${result.sections.join(', ') || 'none'}\n` : ''}E
329
340
  ...(result.suggestions || [])
330
341
  ];
331
342
  console.log(lines.join('\n'));
343
+ } else if (args[1] === undefined) {
344
+ console.log([
345
+ `Examples for ${result.component} (Fine Design ${result.version}):`,
346
+ ...(result.examples.length ? result.examples.map(({ id, title }) => ` ${id}: ${title}`) : [' none'])
347
+ ].join('\n'));
332
348
  } else {
333
349
  console.log(JSON.stringify(result, null, 2));
334
350
  }
@@ -1,3 +1,4 @@
1
+ import { isDeepStrictEqual } from 'node:util';
1
2
  import { ToolError } from './errors.mjs';
2
3
  import { validateInput } from './contracts.mjs';
3
4
  import { sha256 } from './data.mjs';
@@ -67,10 +68,10 @@ export function suggestSimilarComponents(catalog, rawQuery, limit = 3) {
67
68
  }
68
69
  }
69
70
 
70
- return candidates
71
+ const labels = candidates
71
72
  .sort((a, b) => b.score - a.score || a.label.localeCompare(b.label))
72
- .slice(0, limit)
73
73
  .map((item) => item.label);
74
+ return [...new Set(labels)].slice(0, limit);
74
75
  }
75
76
 
76
77
  function sourceMetadata(catalog) {
@@ -267,9 +268,20 @@ export function queryCatalog(catalog, tool, args) {
267
268
  };
268
269
  }
269
270
  if (tool === 'get_component_example') {
271
+ if (args.exampleId === undefined) {
272
+ return {
273
+ ...source,
274
+ component: component.id,
275
+ examples: component.examples.map(({ id, title }) => ({ id, title }))
276
+ };
277
+ }
270
278
  const example = component.examples.find((item) => item.id === args.exampleId);
271
- if (!example)
272
- throw new ToolError('EXAMPLE_NOT_FOUND', 'Unknown example.', 4, { availableExamples: component.examples.map((item) => item.id) });
279
+ if (!example) {
280
+ throw new ToolError('EXAMPLE_NOT_FOUND', 'Unknown example.', 4, {
281
+ availableExamples: component.examples.map((item) => item.id),
282
+ suggestions: [`Use example ${component.exports[0]} to list available example IDs.`]
283
+ });
284
+ }
273
285
  const files = example.files.map((file) => {
274
286
  if (file.encoding === 'base64') {
275
287
  const { content, ...metadata } = file;
@@ -405,31 +417,62 @@ export function getComponentTokens(catalog, { component: rawComponent, query = '
405
417
  };
406
418
  }
407
419
 
408
- export function diffCatalogs(fromCatalog, toCatalog) {
420
+ function comparableMarkdown(markdown) {
421
+ // Historical catalogs use aligned Markdown tables. Preserve whitespace in fenced examples.
422
+ return markdown.replace(/^(`{3,}|~{3,})[^\r\n]*\r?\n[\s\S]*?^\1[ \t]*$|^\|[^\r\n]*\|$/gm, (line, fence) => {
423
+ if (fence) return line;
424
+ if (/^\|(?:[ \t]*:?-+:?[ \t]*\|)+$/.test(line)) return line.replace(/[ \t]+/g, '').replace(/-+/g, '---');
425
+ return line.replace(/(?<!\\)\|[ \t]+/g, '|').replace(/[ \t]+(?=(?<!\\)\|)/g, '');
426
+ });
427
+ }
428
+
429
+ function sectionContent(sections, name) {
430
+ return sections.filter(({ heading }) => heading === name).map(({ markdown }) => comparableMarkdown(markdown));
431
+ }
432
+
433
+ export function diffCatalogs(fromCatalog, toCatalog, component) {
409
434
  const fromMap = new Map(fromCatalog.components.map((c) => [c.id, c]));
410
435
  const toMap = new Map(toCatalog.components.map((c) => [c.id, c]));
436
+ const componentId = component === undefined ? undefined : resolveComponentOrThrow({
437
+ components: [...toCatalog.components, ...fromCatalog.components]
438
+ }, component).id;
411
439
  const addedComponents = [];
412
440
  const removedComponents = [];
413
441
  const updatedComponents = [];
442
+ const exampleSummary = ({ id, title }) => ({ id, title });
414
443
 
415
444
  for (const [id, comp] of toMap) {
445
+ if (componentId && id !== componentId) continue;
416
446
  if (!fromMap.has(id)) {
417
447
  addedComponents.push({ id, exports: comp.exports, description: comp.description });
418
448
  continue;
419
449
  }
420
450
  const prev = fromMap.get(id);
421
- const prevSections = new Set(prev.sections.map((s) => s.heading));
422
- const addedSections = comp.sections.map((s) => s.heading).filter((h) => !prevSections.has(h));
423
- const prevExamples = new Set(prev.examples.map((e) => e.id));
424
- const addedExamples = comp.examples.filter((e) => !prevExamples.has(e.id)).map((e) => ({ id: e.id, title: e.title }));
425
- const prevAliases = new Set(prev.aliases || []);
426
- const addedAliases = (comp.aliases || []).filter((a) => !prevAliases.has(a));
427
- if (addedSections.length > 0 || addedExamples.length > 0 || addedAliases.length > 0) {
428
- updatedComponents.push({ id, exports: comp.exports, addedSections, addedExamples, addedAliases });
451
+ const prevSections = new Set(prev.sections.map(({ heading }) => heading));
452
+ const nextSections = new Set(comp.sections.map(({ heading }) => heading));
453
+ const prevExamples = new Map(prev.examples.map((example) => [example.id, example]));
454
+ const nextExamples = new Set(comp.examples.map((example) => example.id));
455
+ const prevAliases = prev.aliases || [];
456
+ const nextAliases = comp.aliases || [];
457
+ const changes = {
458
+ addedSections: [...nextSections].filter((heading) => !prevSections.has(heading)),
459
+ removedSections: [...prevSections].filter((heading) => !nextSections.has(heading)),
460
+ // The generated demo index changed format between snapshots; compare the underlying examples below.
461
+ changedSections: [...nextSections].filter((heading) => heading !== '代码演示' && prevSections.has(heading)
462
+ && !isDeepStrictEqual(sectionContent(prev.sections, heading), sectionContent(comp.sections, heading))),
463
+ addedExamples: comp.examples.filter((example) => !prevExamples.has(example.id)).map(exampleSummary),
464
+ removedExamples: prev.examples.filter((example) => !nextExamples.has(example.id)).map(exampleSummary),
465
+ changedExamples: comp.examples.filter((example) => prevExamples.has(example.id)
466
+ && !isDeepStrictEqual(prevExamples.get(example.id), example)).map(exampleSummary),
467
+ addedAliases: nextAliases.filter((alias) => !prevAliases.includes(alias)),
468
+ removedAliases: prevAliases.filter((alias) => !nextAliases.includes(alias))
469
+ };
470
+ if (Object.values(changes).some((items) => items.length)) {
471
+ updatedComponents.push({ id, exports: comp.exports, ...changes });
429
472
  }
430
473
  }
431
474
  for (const [id, comp] of fromMap) {
432
- if (!toMap.has(id)) {
475
+ if ((!componentId || id === componentId) && !toMap.has(id)) {
433
476
  removedComponents.push({ id, exports: comp.exports });
434
477
  }
435
478
  }
@@ -437,13 +480,15 @@ export function diffCatalogs(fromCatalog, toCatalog) {
437
480
  return {
438
481
  fromVersion: fromCatalog.version,
439
482
  toVersion: toCatalog.version,
483
+ ...(componentId ? { component: componentId } : {}),
440
484
  addedComponents,
441
485
  removedComponents,
442
486
  updatedComponents,
443
487
  migrations: [
444
- { legacy: 'Table / DataTable', recommended: 'NextTable', note: 'Use <NextTable> with declarative <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children.' },
445
- { legacy: 'Cascader', recommended: 'MCascader', note: 'Legacy Cascader has no online docs page; prefer MCascader for new pages.' },
446
- { legacy: 'Dialog.onCloseBtnClick', recommended: 'Dialog.onCancel', note: 'onCloseBtnClick is deprecated and fires alongside onCancel when clicking the close button.' }
447
- ]
488
+ { components: ['table', 'data-table', 'next-table'], legacy: 'Table / DataTable', recommended: 'NextTable', note: 'Use <NextTable> with declarative <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children.' },
489
+ { components: ['cascader', 'm-cascader'], legacy: 'Cascader', recommended: 'MCascader', note: 'Legacy Cascader has no online docs page; prefer MCascader for new pages.' },
490
+ { components: ['dialog'], legacy: 'Dialog.onCloseBtnClick', recommended: 'Dialog.onCancel', note: 'onCloseBtnClick is deprecated and fires alongside onCancel when clicking the close button.' }
491
+ ].filter(({ components }) => !componentId || components.includes(componentId))
492
+ .map(({ components, ...migration }) => migration)
448
493
  };
449
494
  }
@@ -28,7 +28,8 @@ export const schemas = {
28
28
  diff_catalogs: z.object({
29
29
  version: version.optional(),
30
30
  fromVersion: version.optional(),
31
- toVersion: version.optional()
31
+ toVersion: version.optional(),
32
+ component: component.optional().describe('Limit the comparison to one component, resolved by ID, export or alias.')
32
33
  }).strict(),
33
34
  lint_files: z.object({
34
35
  version: version.optional(),
@@ -41,9 +42,12 @@ export const schemas = {
41
42
  get_component_example: z.object({
42
43
  version,
43
44
  component,
44
- exampleId: z.string().min(1).max(200),
45
+ exampleId: z.string().min(1).max(200).optional().describe('Omit to list available example IDs and titles.'),
45
46
  includeAssets: z.boolean().optional().describe('Include binary asset content as base64 and full oversized JSON fixture content; default returns metadata/preview for large assets.')
46
- }).strict()
47
+ }).strict().refine(({ exampleId, includeAssets }) => exampleId !== undefined || includeAssets === undefined, {
48
+ path: ['includeAssets'],
49
+ message: 'includeAssets requires an example ID.'
50
+ })
47
51
  };
48
52
 
49
53
  export function validateInput(tool, input) {
package/src/core/lint.mjs CHANGED
@@ -138,6 +138,9 @@ function collectScopes(program) {
138
138
  const targetScope = node.kind === 'var' ? scope.varScope : scope;
139
139
  for (const declaration of node.declarations) {
140
140
  bindPattern(declaration.id, targetScope);
141
+ if (declaration.id.type === 'Identifier' && declaration.init) {
142
+ targetScope.bindings.set(declaration.id.name, { initializer: declaration.init, scope });
143
+ }
141
144
  if (declaration.id.type !== 'ObjectPattern') continue;
142
145
  for (const prop of declaration.id.properties) {
143
146
  if (prop.type !== 'ObjectProperty' || prop.computed) continue;
@@ -161,26 +164,47 @@ function findBinding(scope, name) {
161
164
  }
162
165
  }
163
166
 
167
+ function isGlobalMember(node, scope, object, property) {
168
+ return ['MemberExpression', 'JSXMemberExpression'].includes(node?.type) && !node.computed &&
169
+ node.object.name === object && node.property.name === property && findBinding(scope, object) === undefined;
170
+ }
171
+
164
172
  function isFineDesignNamespace(node, scope) {
165
- if (!node) return false;
166
- if (node.type === 'Identifier' || node.type === 'JSXIdentifier') {
173
+ if (node?.type === 'Identifier' || node?.type === 'JSXIdentifier') {
167
174
  const binding = findBinding(scope, node.name);
168
- return Boolean(binding?.namespace || (node.name === 'FineDesign' && binding === undefined));
175
+ return Boolean(binding?.namespace || (node.name === 'FineDesign' && binding === undefined) ||
176
+ isGlobalMember(binding?.initializer, binding?.scope, 'window', 'FineDesign'));
169
177
  }
170
- return ['MemberExpression', 'JSXMemberExpression'].includes(node.type) && !node.computed &&
171
- node.object.name === 'window' && node.property.name === 'FineDesign' && findBinding(scope, 'window') === undefined;
178
+ return isGlobalMember(node, scope, 'window', 'FineDesign');
172
179
  }
173
180
 
174
- // shortcut: resolve direct imports/destructuring only; add data-flow analysis if reassigned aliases need checking.
181
+ // shortcut: resolve imports and direct initializers in the same script, add data-flow analysis if reassigned or cross-script aliases need checking.
175
182
  function componentName(node, scope) {
176
- if (node.type === 'JSXIdentifier') {
183
+ if (node?.type === 'JSXIdentifier' || node?.type === 'Identifier') {
177
184
  const binding = findBinding(scope, node.name);
178
185
  if (binding?.component && (!Object.hasOwn(binding, 'source') || isFineDesignNamespace(binding.source, binding.scope))) return binding.component;
179
- } else if (node.type === 'JSXMemberExpression' && isFineDesignNamespace(node.object, scope)) {
186
+ node = binding?.initializer;
187
+ scope = binding?.scope;
188
+ }
189
+ if (['MemberExpression', 'JSXMemberExpression'].includes(node?.type) && !node.computed && isFineDesignNamespace(node.object, scope)) {
180
190
  return node.property.name;
181
191
  }
182
192
  }
183
193
 
194
+ function isReactCreateElement(node, scope) {
195
+ if (node.type === 'Identifier') {
196
+ const binding = findBinding(scope, node.name);
197
+ node = binding?.initializer;
198
+ scope = binding?.scope;
199
+ }
200
+ if (node?.type !== 'MemberExpression' || node.computed || node.property.name !== 'createElement') return false;
201
+ if (isGlobalMember(node.object, scope, 'window', 'React')) return true;
202
+ if (node.object.type !== 'Identifier') return false;
203
+ const binding = findBinding(scope, node.object.name);
204
+ return (node.object.name === 'React' && binding === undefined) ||
205
+ isGlobalMember(binding?.initializer, binding?.scope, 'window', 'React');
206
+ }
207
+
184
208
  export function lintFiles(catalog, targets = ['.']) {
185
209
  const files = [...new Set(targets.flatMap((t) => collectFiles(t)))];
186
210
  const validValueExports = new Set(EXTRA_VALUE_EXPORTS);
@@ -206,6 +230,12 @@ export function lintFiles(catalog, targets = ['.']) {
206
230
  const report = (node, rule, severity, message, suggestion) => diagnostics.push({
207
231
  file, line: node.loc.start.line, rule, severity, message, suggestion
208
232
  });
233
+ const checkButtonType = (node, value) => {
234
+ if (typeof value === 'string' && !BUTTON_TYPES.has(value)) {
235
+ report(node, 'invalid-button-type', 'error', `Invalid Button type="${value}".`,
236
+ 'Use type="primary" / "secondary" / "normal" / "negative" / "link" / "text" / "text-normal" / "bare", with the boolean danger prop for destructive actions.');
237
+ }
238
+ };
209
239
  const checkExport = (name, node, allowTypes = false, typeOnly = false) => {
210
240
  if (validValueExports.has(name) || (allowTypes && KNOWN_TYPE_EXPORTS.has(name))) return;
211
241
  if (typeOnly && name.endsWith('Props')) return;
@@ -232,6 +262,10 @@ export function lintFiles(catalog, targets = ['.']) {
232
262
  report(node, 'deep-or-foreign-icon-import', 'error', `Avoid importing icons from "${source}".`,
233
263
  'Import the 56 built-in icons or SvgIcon directly from "@fx-ui/fine-design".');
234
264
  }
265
+ if (source === '@fx-ui/fine-design/dist/fine-design.min.css') {
266
+ report(node, 'invalid-package-stylesheet', 'error', `"${source}" uses the hosted UMD filename as a package import.`,
267
+ 'Import "@fx-ui/fine-design/dist/fine_design.css" in React projects. For standalone HTML, load the stylesheet URL from the runtime manifest.');
268
+ }
235
269
  if (source === '@fx-ui/fine-design') {
236
270
  for (const spec of node.specifiers.filter((item) => item.type === 'ImportSpecifier')) {
237
271
  const typeOnly = node.importKind === 'type' || spec.importKind === 'type';
@@ -245,14 +279,18 @@ export function lintFiles(catalog, targets = ['.']) {
245
279
  if (prop.type === 'ObjectProperty' && !prop.computed) checkExport(String(prop.key.name ?? prop.key.value), prop);
246
280
  }
247
281
  }
282
+ } else if (node.type === 'CallExpression' && node.arguments[1]?.type === 'ObjectExpression' &&
283
+ isReactCreateElement(node.callee, scope) && componentName(node.arguments[0], scope) === 'Button') {
284
+ const type = node.arguments[1].properties.findLast((prop) =>
285
+ prop.type === 'SpreadElement' || prop.computed || (prop.key.name ?? prop.key.value) === 'type');
286
+ if (type?.type === 'ObjectProperty' && !type.computed) checkButtonType(type, type.value.value);
248
287
  } else if (node.type === 'JSXOpeningElement') {
249
288
  const component = componentName(node.name, scope);
250
289
  for (const attr of node.attributes.filter((item) => item.type === 'JSXAttribute')) {
251
290
  const name = attr.name.name;
252
291
  const value = (attr.value?.expression || attr.value)?.value;
253
- if (component === 'Button' && name === 'type' && typeof value === 'string' && !BUTTON_TYPES.has(value)) {
254
- report(attr, 'invalid-button-type', 'error', `Invalid Button type="${value}".`,
255
- 'Use type="primary" / "secondary" / "normal" / "negative" / "link" / "text" / "text-normal" / "bare", with the boolean danger prop for destructive actions.');
292
+ if (component === 'Button' && name === 'type') {
293
+ checkButtonType(attr, value);
256
294
  } else if (component === 'NextTable' && name === 'columns') {
257
295
  report(attr, 'next-table-columns-prop', 'error', 'NextTable does not accept a "columns" prop.',
258
296
  'Declare <NextTable.Column>, <NextTable.HeaderCell>, and <NextTable.Cell dataKey="..."> children instead.');
@@ -40,7 +40,12 @@ async function readRuntime(value = defaultRuntimeURL) {
40
40
  chunks.push(chunk);
41
41
  }
42
42
  manifest = JSON.parse(Buffer.concat(chunks).toString('utf8'));
43
- } catch (error) { throw new ToolError('RUNTIME_UNAVAILABLE', `Cannot read ${manifestURL}: ${error.message}. No other version was selected.`, 1); }
43
+ } catch (error) {
44
+ throw new ToolError('RUNTIME_UNAVAILABLE', `Cannot read ${manifestURL}: ${error.message}. No other version was selected.`, 1, {
45
+ manifestURL: manifestURL.href,
46
+ suggestions: ['Check access to the manifest from this environment or pass --runtime-url with a verified host.']
47
+ });
48
+ }
44
49
  return { runtimeURL: base.href, manifestURL: manifestURL.href, manifest: validateRuntimeManifest(manifest) };
45
50
  }
46
51
 
package/src/mcp.mjs CHANGED
@@ -25,9 +25,9 @@ export async function startMcp() {
25
25
  get_component_doc: 'Read component documentation, or pass summary: true to list section headings and example IDs first.',
26
26
  get_component_info: 'Show component overview, exports, aliases and API/props table sections.',
27
27
  get_component_tokens: 'Inspect component or global Design Tokens and their default values.',
28
- diff_catalogs: 'Compare component changes, new sections/examples/aliases and migrations between versions.',
28
+ diff_catalogs: 'Compare documentation sections, examples, aliases and migration guidance between versions, optionally for one component.',
29
29
  lint_files: 'Scan code for Fine Design API traps. Pass an exact version if it cannot be detected from the targets.',
30
- get_component_example: 'Read example source files, dependencies and asset metadata. Set includeAssets to include binary base64 and oversized JSON fixture content.',
30
+ get_component_example: 'List example IDs and titles, or pass exampleId to read source, dependencies and asset metadata. Set includeAssets with exampleId to include large assets.',
31
31
  list_browser_runtimes: 'Read the one currently hosted UMD version from its online manifest. Requires network access.',
32
32
  get_browser_runtime: 'Resolve an exact component version to versioned current UMD URLs and SRI loading tags. Requires network access; never falls back to another version.'
33
33
  };
@@ -53,7 +53,7 @@ export async function startMcp() {
53
53
  const available = Object.keys(readIndex().versions).sort();
54
54
  const fromVer = args.fromVersion || args.version || available[0];
55
55
  const toVer = args.toVersion || available.at(-1);
56
- result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer));
56
+ result = diffCatalogs(loadCatalog(fromVer), loadCatalog(toVer), args.component);
57
57
  } else if (toolName === 'lint_files') {
58
58
  const targets = args.paths?.length ? args.paths : args.files?.length ? args.files : args.path ? [args.path] : ['.'];
59
59
  const version = resolveLintVersion(args.version, targets);