@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.
- package/CHANGELOG.md +16 -0
- package/README.md +11 -9
- package/data/1.25.0/catalog.json +1 -1
- package/data/1.25.0/manifest.json +5 -5
- package/package.json +1 -1
- package/skills/fine-design/SKILL.md +3 -3
- package/skills/fine-design/references/imports-and-setup.md +3 -1
- package/src/cli.mjs +29 -13
- package/src/core/catalog.mjs +63 -18
- package/src/core/contracts.mjs +7 -3
- package/src/core/lint.mjs +49 -11
- package/src/core/runtime.mjs +6 -1
- package/src/mcp.mjs +3 -3
|
@@ -2,15 +2,15 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"version": "1.25.0",
|
|
4
4
|
"sourceKind": "repository-snapshot",
|
|
5
|
-
"sourceRevision": "
|
|
5
|
+
"sourceRevision": "a88c1a76dc006929aa6ab9ce4f9de4ad0e926d0c",
|
|
6
6
|
"sourceDirty": false,
|
|
7
|
-
"contentHash": "
|
|
8
|
-
"catalogSha256": "
|
|
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": "
|
|
12
|
+
"references/imports-and-setup.md": "9a404ad7243f0fa734d34c5fd0106287ededf36bbc1693812917ce9cb9780e40",
|
|
13
13
|
"references/theme-and-dark-mode.md": "2eccae4930ea993e7088eee03a4b4a0f1c839033079db5f21f8c60e0fe8168d1",
|
|
14
|
-
"SKILL.md": "
|
|
14
|
+
"SKILL.md": "512ecee9c5208436cda70c56cd691354ab83e2d85115c4bc6f3c1e0658e458ba"
|
|
15
15
|
}
|
|
16
16
|
}
|
package/package.json
CHANGED
|
@@ -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.
|
|
17
|
-
4.
|
|
18
|
-
5. Run the existing build/type check
|
|
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
|
-
-
|
|
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>
|
|
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
|
|
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 =
|
|
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((
|
|
253
|
-
|
|
254
|
-
|
|
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
|
|
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
|
}
|
package/src/core/catalog.mjs
CHANGED
|
@@ -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
|
-
|
|
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, {
|
|
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
|
-
|
|
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((
|
|
422
|
-
const
|
|
423
|
-
const prevExamples = new
|
|
424
|
-
const
|
|
425
|
-
const prevAliases =
|
|
426
|
-
const
|
|
427
|
-
|
|
428
|
-
|
|
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
|
}
|
package/src/core/contracts.mjs
CHANGED
|
@@ -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 (
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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'
|
|
254
|
-
|
|
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.');
|
package/src/core/runtime.mjs
CHANGED
|
@@ -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) {
|
|
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
|
|
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: '
|
|
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);
|