@atelier-ui/create-workspace 0.4.0 → 0.4.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 -3
- package/package.json +1 -1
- package/src/generators/preset/files/contracts/README.md +6 -6
- package/src/generators/preset/files/contracts/types.ts.template +9 -10
- package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/check-contracts.mjs +236 -223
- package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/figma-snapshot-contracts.mjs +107 -92
- package/src/generators/preset/files/tools/design-contracts/src/codespec.mjs +234 -0
- package/src/generators/preset/files/tools/design-contracts/src/config.mjs +63 -0
- package/src/generators/preset/files/tools/{scripts/lib → design-contracts/src}/docgen.mjs +78 -98
- package/src/generators/preset/files/tools/{scripts/lib/ts-eval.js → design-contracts/src/ts-eval.cjs} +3 -4
- package/src/generators/preset/preset.js +27 -11
- package/src/generators/preset/preset.js.map +1 -1
|
@@ -1,55 +1,45 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
|
-
* figma-snapshot-contracts
|
|
3
|
+
* figma-snapshot-contracts
|
|
4
4
|
*
|
|
5
5
|
* A snapshot generator whose roster is the contracts, not a hand-maintained
|
|
6
|
-
* master list.
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
* `<name>.contract.ts` files exist under the contracts directory (same
|
|
10
|
-
* resolution as `check-contracts.mjs`, Step 1 of ADR-0121 S4) and, for each
|
|
11
|
-
* one's `figmaNodeId`, writes exactly the master-entry fields `check-contracts.mjs`
|
|
6
|
+
* master list. It reads whichever `<name>.contract.ts` files exist under the
|
|
7
|
+
* contracts directory (the same settings as `check-contracts`) and, for each
|
|
8
|
+
* one's `figmaNodeId`, writes exactly the master-entry fields `check-contracts`
|
|
12
9
|
* consumes: `selector`, `nodeId`, `name`, `description`, `variantAxes`,
|
|
13
10
|
* `properties`, `variants`.
|
|
14
11
|
*
|
|
15
|
-
*
|
|
16
|
-
*
|
|
17
|
-
* from it, not shared, so this file stands alone when copied into a
|
|
18
|
-
* scaffolded workspace (ADR-0123's "the scaffold ships the check" — this is
|
|
19
|
-
* its Figma-refresh half).
|
|
12
|
+
* figma-snapshot-contracts --file <figmaFileKey> [--out <path>] [--contracts <dir>]
|
|
13
|
+
* figma-snapshot-contracts --file <figmaFileKey> --dry-run
|
|
20
14
|
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
15
|
+
* Settings: `--contracts` / `contracts` (required), `--out` / `snapshot`
|
|
16
|
+
* (required: where to write), `mcpConfig` (optional, default `.mcp.json`: the
|
|
17
|
+
* MCP client config, relative to the working directory, that pins the
|
|
18
|
+
* `figma-console` server version). All from CLI flags or `contracts.config.json`
|
|
19
|
+
* in the working directory — nothing is derived from where this package lives.
|
|
23
20
|
*
|
|
24
|
-
* Requirements
|
|
25
|
-
*
|
|
26
|
-
*
|
|
21
|
+
* Requirements: Figma Desktop running with the file open and the figma-console
|
|
22
|
+
* Desktop Bridge plugin connected. Fails loud (exit 2) if the bridge is not
|
|
23
|
+
* connected — never a silent/empty write.
|
|
27
24
|
*
|
|
28
25
|
* --dry-run prints the roster (selector -> nodeId) and the figma_execute
|
|
29
26
|
* plugin code that would run for the first master, then exits 0 WITHOUT
|
|
30
|
-
* connecting to Figma at all — the only mode
|
|
31
|
-
*
|
|
27
|
+
* connecting to Figma at all — the only mode that can run where there is no
|
|
28
|
+
* Figma Desktop Bridge.
|
|
32
29
|
*/
|
|
33
|
-
import { writeFileSync, readFileSync, existsSync } from 'node:fs';
|
|
34
|
-
import {
|
|
35
|
-
import { dirname, resolve, join } from 'node:path';
|
|
30
|
+
import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
|
|
31
|
+
import { resolve, dirname } from 'node:path';
|
|
36
32
|
import { createRequire } from 'node:module';
|
|
37
33
|
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
38
34
|
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
|
|
35
|
+
import { die, readConfigFile, CONFIG_FILE_NAME } from '../src/config.mjs';
|
|
39
36
|
|
|
40
|
-
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
41
|
-
// Portable the same way check-contracts.mjs is (ADR-0121 S4 Step 1): derived
|
|
42
|
-
// from THIS script's own location, so a byte-identical copy dropped into
|
|
43
|
-
// <scaffold>/tools/scripts/ defaults to the scaffold's own tree.
|
|
44
|
-
const ROOT = resolve(__dirname, '../..');
|
|
45
37
|
const CWD = process.cwd();
|
|
46
|
-
const MCP_CONFIG_PATH = resolve(ROOT, '.mcp.json');
|
|
47
38
|
|
|
48
|
-
// ts-eval.
|
|
49
|
-
//
|
|
50
|
-
// works unmodified wherever it is copied.
|
|
39
|
+
// ts-eval.cjs ships in this package and is loaded by a path relative to THIS
|
|
40
|
+
// file, so it works from node_modules and from a vendored copy alike.
|
|
51
41
|
const require = createRequire(import.meta.url);
|
|
52
|
-
const { parseExportedVars } = require('
|
|
42
|
+
const { parseExportedVars } = require('../src/ts-eval.cjs');
|
|
53
43
|
|
|
54
44
|
// ─── CLI args ───────────────────────────────────────────────────────────────
|
|
55
45
|
|
|
@@ -68,35 +58,36 @@ function parseArgs(argv) {
|
|
|
68
58
|
const args = parseArgs(process.argv.slice(2));
|
|
69
59
|
|
|
70
60
|
if (!args.file) {
|
|
71
|
-
|
|
72
|
-
'Usage:
|
|
61
|
+
die(
|
|
62
|
+
'Usage: figma-snapshot-contracts --file <figmaFileKey> [--out <path>] [--contracts <dir>] [--dry-run]',
|
|
73
63
|
);
|
|
74
|
-
process.exit(2);
|
|
75
64
|
}
|
|
76
65
|
|
|
77
|
-
// ───
|
|
78
|
-
//
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
if (
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
66
|
+
// ─── Settings (CLI flag > contracts.config.json in the working directory;
|
|
67
|
+
// no built-in locations) ────────────────────────────────────────────────
|
|
68
|
+
const fileConfig = readConfigFile(CWD);
|
|
69
|
+
|
|
70
|
+
const contractsSetting = args.contracts ?? fileConfig?.contracts;
|
|
71
|
+
if (!contractsSetting) {
|
|
72
|
+
die(
|
|
73
|
+
`No contracts directory set — pass --contracts <dir> or set "contracts" in ${CONFIG_FILE_NAME}.`,
|
|
74
|
+
);
|
|
75
|
+
}
|
|
76
|
+
const CONTRACTS_DIR = resolve(CWD, contractsSetting);
|
|
77
|
+
if (!existsSync(CONTRACTS_DIR)) {
|
|
78
|
+
die(`Contracts directory not found: ${CONTRACTS_DIR}`);
|
|
89
79
|
}
|
|
90
80
|
|
|
91
|
-
const
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
81
|
+
const outSetting = args.out ?? fileConfig?.snapshot;
|
|
82
|
+
if (!outSetting) {
|
|
83
|
+
die(
|
|
84
|
+
`No output path set — pass --out <file> or set "snapshot" in ${CONFIG_FILE_NAME}.`,
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
const OUT_PATH = resolve(CWD, outSetting);
|
|
96
88
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
: join(ROOT, 'tools/figma/snapshot.json');
|
|
89
|
+
// The MCP client config that pins the figma-console server version.
|
|
90
|
+
const MCP_CONFIG_PATH = resolve(CWD, fileConfig?.mcpConfig ?? '.mcp.json');
|
|
100
91
|
|
|
101
92
|
// ─── The roster: every contract's { component, figmaNodeId } ──────────────
|
|
102
93
|
|
|
@@ -141,12 +132,10 @@ if (roster.length === 0) {
|
|
|
141
132
|
}
|
|
142
133
|
|
|
143
134
|
// ─── The figma_execute plugin code, one master per call ────────────────────
|
|
144
|
-
//
|
|
135
|
+
// componentPropertyDefinitions
|
|
145
136
|
// for `properties`/`variantAxes`, and each variant child's `name` (the
|
|
146
137
|
// "axis=value, axis=value" convention) for `variants`. A single node lookup
|
|
147
|
-
// per master rather than
|
|
148
|
-
// has a roster of one to a handful of contracts, not 43 masters plus every
|
|
149
|
-
// child part.
|
|
138
|
+
// per master rather than a whole-file walk.
|
|
150
139
|
function pluginCodeFor(nodeId) {
|
|
151
140
|
return `
|
|
152
141
|
await figma.loadAllPagesAsync();
|
|
@@ -202,9 +191,9 @@ if (args.dryRun) {
|
|
|
202
191
|
process.exit(0);
|
|
203
192
|
}
|
|
204
193
|
|
|
205
|
-
// ─── Resolve the pinned figma-console-mcp package spec from
|
|
206
|
-
//
|
|
207
|
-
//
|
|
194
|
+
// ─── Resolve the pinned figma-console-mcp package spec from the MCP config ─
|
|
195
|
+
// The server version is pinned there rather than left to `@latest`, so a run
|
|
196
|
+
// is reproducible.
|
|
208
197
|
|
|
209
198
|
function resolveFigmaConsolePackageSpec() {
|
|
210
199
|
let config;
|
|
@@ -222,7 +211,7 @@ function resolveFigmaConsolePackageSpec() {
|
|
|
222
211
|
if (!spec) {
|
|
223
212
|
throw new Error(
|
|
224
213
|
`${MCP_CONFIG_PATH} has no mcpServers['figma-console'].args entry matching ` +
|
|
225
|
-
`/^figma-console-mcp@/ — refusing to fall back to @latest (
|
|
214
|
+
`/^figma-console-mcp@/ — refusing to fall back to @latest (the server version must be pinned).`,
|
|
226
215
|
);
|
|
227
216
|
}
|
|
228
217
|
return spec;
|
|
@@ -262,7 +251,7 @@ main().catch((err) => {
|
|
|
262
251
|
|
|
263
252
|
async function main() {
|
|
264
253
|
const client = new Client(
|
|
265
|
-
{ name: '
|
|
254
|
+
{ name: 'figma-snapshot-contracts', version: '1.0.0' },
|
|
266
255
|
{ capabilities: {} },
|
|
267
256
|
);
|
|
268
257
|
const figmaConsolePackageSpec = resolveFigmaConsolePackageSpec();
|
|
@@ -275,8 +264,8 @@ async function main() {
|
|
|
275
264
|
const reportedServerVersion = client.getServerVersion?.();
|
|
276
265
|
|
|
277
266
|
try {
|
|
278
|
-
// Probe the bridge — fail loud if the plugin is not connected.
|
|
279
|
-
//
|
|
267
|
+
// Probe the bridge — fail loud if the plugin is not connected. Retry:
|
|
268
|
+
// the plugin attaches ~0.5s after a
|
|
280
269
|
// freshly-spawned server starts.
|
|
281
270
|
let status = null;
|
|
282
271
|
for (let attempt = 0; attempt < 10; attempt++) {
|
|
@@ -300,42 +289,67 @@ async function main() {
|
|
|
300
289
|
status?.serverVersion ??
|
|
301
290
|
status?.details?.serverVersion ??
|
|
302
291
|
(declaredServerVersion
|
|
303
|
-
? `${declaredServerVersion} (declared in
|
|
292
|
+
? `${declaredServerVersion} (declared in ${MCP_CONFIG_PATH}; server did not report)`
|
|
304
293
|
: null);
|
|
305
294
|
|
|
306
|
-
// ───
|
|
307
|
-
// The Bridge
|
|
308
|
-
//
|
|
309
|
-
//
|
|
310
|
-
//
|
|
311
|
-
//
|
|
312
|
-
// the
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
295
|
+
// ─── Target --file among the connected files ───────────────────────────
|
|
296
|
+
// The Desktop Bridge keeps one connection per Figma file that has the
|
|
297
|
+
// plugin open, and `figma_execute` runs in whichever one is ACTIVE (the
|
|
298
|
+
// user's last selection). So the requested file is looked up in
|
|
299
|
+
// `figma_list_open_files`, and every read is sent through
|
|
300
|
+
// `figma_execute_across_files` with `fileKeys: [--file]`, which targets
|
|
301
|
+
// that file only and leaves the active file (and any target pin) alone.
|
|
302
|
+
// The file must be connected: a file that is merely open in Figma, without
|
|
303
|
+
// the plugin running in it, cannot be reached.
|
|
304
|
+
const open = await call(client, 'figma_list_open_files', {});
|
|
305
|
+
const connected = Array.isArray(open?.files) ? open.files : [];
|
|
306
|
+
if (!connected.some((f) => f.fileKey === args.file)) {
|
|
307
|
+
const list = connected.length
|
|
308
|
+
? connected.map((f) => ` ${f.fileKey} "${f.fileName}"`).join('\n')
|
|
309
|
+
: ' (none)';
|
|
310
|
+
console.error(
|
|
311
|
+
`✗ --file ${args.file} is not connected through the Desktop Bridge. Open that file in ` +
|
|
312
|
+
`Figma Desktop and run the figma-console Desktop Bridge plugin in it, then re-run.\n` +
|
|
313
|
+
` Connected files:\n${list}`,
|
|
314
|
+
);
|
|
315
|
+
process.exit(2);
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
async function executeInFile(code, timeout) {
|
|
319
|
+
const res = await call(client, 'figma_execute_across_files', {
|
|
320
|
+
code,
|
|
321
|
+
fileKeys: [args.file],
|
|
322
|
+
timeout,
|
|
323
|
+
});
|
|
324
|
+
const entry = res?.results?.[args.file];
|
|
325
|
+
if (!entry || entry.success === false) {
|
|
326
|
+
throw new Error(
|
|
327
|
+
`figma_execute_across_files failed for ${args.file}: ${entry?.error ?? res?.error ?? 'no result'}`,
|
|
328
|
+
);
|
|
329
|
+
}
|
|
330
|
+
return entry.result;
|
|
331
|
+
}
|
|
332
|
+
|
|
333
|
+
// figma.fileKey, reported from inside the plugin sandbox itself, confirms
|
|
334
|
+
// the answer came from the file that was asked.
|
|
335
|
+
const openFile = await executeInFile(
|
|
336
|
+
`
|
|
337
|
+
await figma.loadAllPagesAsync();
|
|
338
|
+
return { fileKey: figma.fileKey ?? null, fileName: figma.root.name };
|
|
339
|
+
`,
|
|
340
|
+
10000,
|
|
341
|
+
);
|
|
322
342
|
if (openFile?.fileKey && openFile.fileKey !== args.file) {
|
|
323
343
|
console.error(
|
|
324
|
-
`✗
|
|
325
|
-
`(
|
|
326
|
-
`snapshot, or pass --file ${openFile.fileKey}, and re-run.`,
|
|
344
|
+
`✗ asked file ${args.file}, but the plugin that answered reports ${openFile.fileKey} ` +
|
|
345
|
+
`("${openFile.fileName}"). Re-run; if it persists, close the other Figma windows.`,
|
|
327
346
|
);
|
|
328
347
|
process.exit(2);
|
|
329
348
|
}
|
|
330
349
|
|
|
331
350
|
const components = [];
|
|
332
351
|
for (const { selector, nodeId } of roster) {
|
|
333
|
-
const result = (
|
|
334
|
-
await call(client, 'figma_execute', {
|
|
335
|
-
code: pluginCodeFor(nodeId),
|
|
336
|
-
timeout: 15000,
|
|
337
|
-
})
|
|
338
|
-
)?.result;
|
|
352
|
+
const result = await executeInFile(pluginCodeFor(nodeId), 15000);
|
|
339
353
|
if (!result) {
|
|
340
354
|
console.warn(`⚠ skipped ${selector} (${nodeId}): node not found`);
|
|
341
355
|
continue;
|
|
@@ -362,6 +376,7 @@ async function main() {
|
|
|
362
376
|
},
|
|
363
377
|
components,
|
|
364
378
|
};
|
|
379
|
+
mkdirSync(dirname(OUT_PATH), { recursive: true });
|
|
365
380
|
writeFileSync(OUT_PATH, JSON.stringify(snapshot, null, 2) + '\n');
|
|
366
381
|
console.log(`✓ wrote ${components.length} master(s) to ${OUT_PATH}`);
|
|
367
382
|
} finally {
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The codeSpec fragment `check-contracts --emit` writes for figma-console's
|
|
3
|
+
* `figma_check_design_parity` (`componentAPI`, `metadata`, `tokens.usedTokens`).
|
|
4
|
+
*
|
|
5
|
+
* The parity tool (figma-console-mcp, `compareComponentAPI` in
|
|
6
|
+
* dist/core/design-code-tools.js) pairs the codeSpec's `componentAPI.props` with
|
|
7
|
+
* the master's `componentPropertyDefinitions` by NAME, compared lower-cased with
|
|
8
|
+
* every character outside `[a-z0-9]` removed, and reports:
|
|
9
|
+
* - a code prop with no Figma property of that name (minor),
|
|
10
|
+
* - a Figma property with no code prop of that name (info),
|
|
11
|
+
* - for a matching VARIANT, the values missing on either side (major / info).
|
|
12
|
+
* It has no notion of a deliberate difference. So the code's API is expressed
|
|
13
|
+
* here in FIGMA's terms, using the contract, and a deliberate difference simply
|
|
14
|
+
* does not appear as a mismatch:
|
|
15
|
+
*
|
|
16
|
+
* - `axisMap` a code prop is emitted under its Figma name (the axis, or the
|
|
17
|
+
* Boolean's key), with the Figma values when the entry maps
|
|
18
|
+
* values. The code name is not emitted a second time.
|
|
19
|
+
* - `codeOnly` the code prop is left out: Figma was never meant to have it.
|
|
20
|
+
* - `figmaOnly` a Figma property with no code prop is emitted under its
|
|
21
|
+
* Figma name, typed `figma-only` and carrying the reason, so
|
|
22
|
+
* the tool finds a partner for it. `state=<value>` entries,
|
|
23
|
+
* and a `state` axis made only of interaction states (CSS
|
|
24
|
+
* pseudo-classes, see INTERACTION_STATE_VALUES), are covered
|
|
25
|
+
* the same way.
|
|
26
|
+
*
|
|
27
|
+
* Figma keys Boolean, Text and Instance-swap properties as `Name#<id>`, and the
|
|
28
|
+
* tool's comparison keeps the id's digits, so a matching code prop is emitted
|
|
29
|
+
* under the master's full key (the snapshot keeps it).
|
|
30
|
+
*
|
|
31
|
+
* Anything the contract does not record stays a real mismatch and is still
|
|
32
|
+
* reported by the parity tool. Without a snapshot master there is nothing to
|
|
33
|
+
* translate to: the code's own names are emitted.
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Interaction values on a `state` axis: CSS pseudo-classes, not code-modelled
|
|
38
|
+
* state. Every OTHER value on a `state` axis must be covered by an `axisMap`
|
|
39
|
+
* entry or a `figmaOnly` entry named `state=<value>`.
|
|
40
|
+
*/
|
|
41
|
+
export const INTERACTION_STATE_VALUES = new Set([
|
|
42
|
+
'default',
|
|
43
|
+
'hover',
|
|
44
|
+
'focus',
|
|
45
|
+
'focus-visible',
|
|
46
|
+
'active',
|
|
47
|
+
'pressed',
|
|
48
|
+
]);
|
|
49
|
+
|
|
50
|
+
/** `Name#1:2` -> `Name`: a Figma property key without its id suffix. */
|
|
51
|
+
export function stripFigmaId(name) {
|
|
52
|
+
const i = name.indexOf('#');
|
|
53
|
+
return i === -1 ? name : name.slice(0, i);
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// The parity schema wants `defaultValue` as string | number | boolean.
|
|
57
|
+
function schemaDefault(value) {
|
|
58
|
+
if (value === undefined || value === null) return undefined;
|
|
59
|
+
return typeof value === 'object' ? JSON.stringify(value) : value;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function apiProp(p, overrides = {}) {
|
|
63
|
+
return {
|
|
64
|
+
name: p.name,
|
|
65
|
+
type: p.typeText || p.kind,
|
|
66
|
+
values: p.kind === 'enum' ? p.members.map(String) : undefined,
|
|
67
|
+
defaultValue: schemaDefault(p.default),
|
|
68
|
+
description: p.description,
|
|
69
|
+
required: p.required,
|
|
70
|
+
...overrides,
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function figmaOnlyProp(name, values, reason) {
|
|
75
|
+
return {
|
|
76
|
+
name,
|
|
77
|
+
type: 'figma-only',
|
|
78
|
+
values,
|
|
79
|
+
description: `Figma-only (contract figmaOnly): ${reason}`,
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* @param {object} input
|
|
85
|
+
* @param {string} input.name component selector
|
|
86
|
+
* @param {object} input.docgenResult `{ props, description, slots }` (the common docgen shape)
|
|
87
|
+
* @param {object|null} input.master the snapshot master, or null
|
|
88
|
+
* @param {object|null} input.contract the component's contract, or null
|
|
89
|
+
* @param {string[]} input.usedTokens
|
|
90
|
+
*/
|
|
91
|
+
export function buildCodeSpec({
|
|
92
|
+
name,
|
|
93
|
+
docgenResult,
|
|
94
|
+
master,
|
|
95
|
+
contract,
|
|
96
|
+
usedTokens,
|
|
97
|
+
}) {
|
|
98
|
+
const codeProps = docgenResult.props.filter((p) => !p.isOutput);
|
|
99
|
+
const events = docgenResult.props.filter((p) => p.isOutput);
|
|
100
|
+
const slots = (docgenResult.slots || []).map((s) =>
|
|
101
|
+
typeof s === 'string' ? s : s.name,
|
|
102
|
+
);
|
|
103
|
+
|
|
104
|
+
const props = master
|
|
105
|
+
? propsInFigmaTerms(codeProps, master, contract || {})
|
|
106
|
+
: codeProps.map((p) => apiProp(p));
|
|
107
|
+
|
|
108
|
+
return {
|
|
109
|
+
componentAPI: {
|
|
110
|
+
props,
|
|
111
|
+
// The parity schema takes event and slot NAMES (strings), not objects.
|
|
112
|
+
events: events.map((e) => e.name),
|
|
113
|
+
slots: slots.length ? slots : undefined,
|
|
114
|
+
},
|
|
115
|
+
metadata: { name, description: docgenResult.description },
|
|
116
|
+
tokens: { usedTokens },
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function propsInFigmaTerms(codeProps, master, contract) {
|
|
121
|
+
const codeByName = new Map(codeProps.map((p) => [p.name, p]));
|
|
122
|
+
const axes = master.variantAxes || {};
|
|
123
|
+
const figmaKeys = Object.keys(master.properties || {});
|
|
124
|
+
// Name without id -> the master's full key (what the parity tool sees).
|
|
125
|
+
const keyByName = new Map(figmaKeys.map((k) => [stripFigmaId(k), k]));
|
|
126
|
+
const figmaKey = (n) => keyByName.get(n) ?? n;
|
|
127
|
+
const isOnMaster = (n) =>
|
|
128
|
+
Object.hasOwn(axes, n) || keyByName.has(stripFigmaId(n));
|
|
129
|
+
|
|
130
|
+
const figmaOnly = contract.figmaOnly || [];
|
|
131
|
+
const stateExemptions = new Set(
|
|
132
|
+
figmaOnly
|
|
133
|
+
.map((e) => /^state=(.+)$/.exec(e.name))
|
|
134
|
+
.filter(Boolean)
|
|
135
|
+
.map((m) => m[1]),
|
|
136
|
+
);
|
|
137
|
+
const codeOnlyNames = new Set((contract.codeOnly || []).map((e) => e.name));
|
|
138
|
+
const axisMap = contract.axisMap || [];
|
|
139
|
+
const mappedCodeProps = new Set(axisMap.map((e) => e.codeProp));
|
|
140
|
+
|
|
141
|
+
const out = [];
|
|
142
|
+
const emitted = new Set();
|
|
143
|
+
const push = (prop) => {
|
|
144
|
+
if (emitted.has(prop.name)) return;
|
|
145
|
+
emitted.add(prop.name);
|
|
146
|
+
out.push(prop);
|
|
147
|
+
};
|
|
148
|
+
|
|
149
|
+
// axisMap: one prop per Figma axis / Boolean, under the Figma name.
|
|
150
|
+
const byFigmaAxis = new Map();
|
|
151
|
+
for (const e of axisMap) {
|
|
152
|
+
if (!byFigmaAxis.has(e.figmaAxis)) byFigmaAxis.set(e.figmaAxis, []);
|
|
153
|
+
byFigmaAxis.get(e.figmaAxis).push(e);
|
|
154
|
+
}
|
|
155
|
+
for (const [axis, entries] of byFigmaAxis) {
|
|
156
|
+
const values = new Set();
|
|
157
|
+
let hasValues = false;
|
|
158
|
+
for (const e of entries) {
|
|
159
|
+
const own = codeByName.get(e.codeProp); // undefined for `Child.prop`
|
|
160
|
+
if (e.values) {
|
|
161
|
+
hasValues = true;
|
|
162
|
+
for (const v of Object.keys(e.values)) values.add(v);
|
|
163
|
+
} else if (own?.kind === 'enum') {
|
|
164
|
+
hasValues = true;
|
|
165
|
+
for (const v of own.members) values.add(v);
|
|
166
|
+
} else if (own?.kind === 'boolean') {
|
|
167
|
+
// The tool only compares a VARIANT's values when the code prop has
|
|
168
|
+
// `values`; a boolean on a Figma axis states true/false so an axis
|
|
169
|
+
// with other values is reported (map them with `values` if intended).
|
|
170
|
+
hasValues = true;
|
|
171
|
+
values.add('true');
|
|
172
|
+
values.add('false');
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
if (axis === 'state' && hasValues) {
|
|
176
|
+
for (const v of axes.state || [])
|
|
177
|
+
if (INTERACTION_STATE_VALUES.has(v) || stateExemptions.has(v))
|
|
178
|
+
values.add(v);
|
|
179
|
+
}
|
|
180
|
+
const first = codeByName.get(entries[0].codeProp);
|
|
181
|
+
const single = entries.length === 1 ? entries[0] : null;
|
|
182
|
+
let defaultValue;
|
|
183
|
+
if (first && single) {
|
|
184
|
+
if (single.values) {
|
|
185
|
+
const hits = Object.entries(single.values).filter(
|
|
186
|
+
([, codeVal]) => String(codeVal) === String(first.default),
|
|
187
|
+
);
|
|
188
|
+
if (hits.length === 1) defaultValue = hits[0][0];
|
|
189
|
+
} else defaultValue = schemaDefault(first.default);
|
|
190
|
+
}
|
|
191
|
+
push({
|
|
192
|
+
name: figmaKey(axis),
|
|
193
|
+
type: first ? first.typeText || first.kind : 'string',
|
|
194
|
+
values: hasValues ? [...values] : undefined,
|
|
195
|
+
defaultValue,
|
|
196
|
+
description:
|
|
197
|
+
`Figma "${axis}" is code ${entries.map((e) => `"${e.codeProp}"`).join(', ')} ` +
|
|
198
|
+
`(contract axisMap): ${entries[0].reason}`,
|
|
199
|
+
required: first?.required,
|
|
200
|
+
});
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// figmaOnly: a Figma property with no code prop, on purpose.
|
|
204
|
+
for (const e of figmaOnly) {
|
|
205
|
+
if (/^state=/.test(e.name) || !isOnMaster(e.name)) continue;
|
|
206
|
+
push(figmaOnlyProp(figmaKey(e.name), axes[e.name], e.reason));
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// A `state` axis of interaction states only: CSS pseudo-classes in code.
|
|
210
|
+
const state = axes.state;
|
|
211
|
+
if (
|
|
212
|
+
state &&
|
|
213
|
+
!emitted.has('state') &&
|
|
214
|
+
!codeByName.has('state') &&
|
|
215
|
+
state.every(
|
|
216
|
+
(v) => INTERACTION_STATE_VALUES.has(v) || stateExemptions.has(v),
|
|
217
|
+
)
|
|
218
|
+
) {
|
|
219
|
+
push(
|
|
220
|
+
figmaOnlyProp(
|
|
221
|
+
'state',
|
|
222
|
+
state,
|
|
223
|
+
'interaction states are CSS pseudo-classes and `state=<value>` entries are figmaOnly, not code props.',
|
|
224
|
+
),
|
|
225
|
+
);
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
// The code's own props, under the Figma key when Figma has a property of that name.
|
|
229
|
+
for (const p of codeProps) {
|
|
230
|
+
if (mappedCodeProps.has(p.name) || codeOnlyNames.has(p.name)) continue;
|
|
231
|
+
push(apiProp(p, { name: figmaKey(p.name) }));
|
|
232
|
+
}
|
|
233
|
+
return out;
|
|
234
|
+
}
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared settings resolution for the `check-contracts` and
|
|
3
|
+
* `figma-snapshot-contracts` bins.
|
|
4
|
+
*
|
|
5
|
+
* Every setting comes from a CLI flag or from `contracts.config.json` in the
|
|
6
|
+
* current working directory — nothing is derived from where this package is
|
|
7
|
+
* installed. A relative path in the config (or on the command line) is
|
|
8
|
+
* relative to the working directory. A missing required setting is a usage
|
|
9
|
+
* error: the caller prints the message and exits 2.
|
|
10
|
+
*/
|
|
11
|
+
import fs from 'node:fs';
|
|
12
|
+
import path from 'node:path';
|
|
13
|
+
|
|
14
|
+
export const CONFIG_FILE_NAME = 'contracts.config.json';
|
|
15
|
+
|
|
16
|
+
/** The frameworks whose docgen this package knows how to read. */
|
|
17
|
+
export const FRAMEWORKS = ['angular', 'react', 'vue'];
|
|
18
|
+
|
|
19
|
+
/** Print a usage/configuration error and exit 2 (the "could not run" code, distinct from 1 = findings). */
|
|
20
|
+
export function die(message) {
|
|
21
|
+
console.error(message);
|
|
22
|
+
process.exit(2);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** Parsed `contracts.config.json` from `cwd`, or `null` when there is none. Invalid JSON exits 2. */
|
|
26
|
+
export function readConfigFile(cwd) {
|
|
27
|
+
const configPath = path.join(cwd, CONFIG_FILE_NAME);
|
|
28
|
+
if (!fs.existsSync(configPath)) return null;
|
|
29
|
+
try {
|
|
30
|
+
return JSON.parse(fs.readFileSync(configPath, 'utf-8'));
|
|
31
|
+
} catch (e) {
|
|
32
|
+
return die(`${configPath}: invalid JSON (${e.message})`);
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* A path-list setting that is either one list for every framework
|
|
38
|
+
* (`["src"]`) or a map per framework (`{ "angular": ["libs/a/src"] }`).
|
|
39
|
+
* Returns the absolute directories for `fw`, or `null` when the setting is
|
|
40
|
+
* absent / has nothing for that framework.
|
|
41
|
+
*/
|
|
42
|
+
export function dirsFor(setting, fw, cwd) {
|
|
43
|
+
if (setting == null) return null;
|
|
44
|
+
const list = Array.isArray(setting) ? setting : setting[fw];
|
|
45
|
+
if (!Array.isArray(list) || list.length === 0) return null;
|
|
46
|
+
return list.map((d) => path.resolve(cwd, d));
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** The settings the check needs that no flag exists for, validated once. */
|
|
50
|
+
export function readSharedPropsSetting(fileConfig, cwd) {
|
|
51
|
+
const s = fileConfig?.sharedPropsInterface;
|
|
52
|
+
if (s == null) return null;
|
|
53
|
+
if (
|
|
54
|
+
typeof s !== 'object' ||
|
|
55
|
+
typeof s.file !== 'string' ||
|
|
56
|
+
typeof s.name !== 'string'
|
|
57
|
+
) {
|
|
58
|
+
return die(
|
|
59
|
+
`${CONFIG_FILE_NAME}: "sharedPropsInterface" must be { "file": "<path>", "name": "<interface>" }`,
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
return { file: path.resolve(cwd, s.file), name: s.name };
|
|
63
|
+
}
|