@atelier-ui/create-workspace 0.4.0 → 0.4.2

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.
Files changed (34) hide show
  1. package/CHANGELOG.md +27 -3
  2. package/package.json +1 -1
  3. package/src/generators/preset/files/claude/skills/figma-workspace-architect/SKILL.md +194 -0
  4. package/src/generators/preset/files/claude/skills/figma-workspace-architect/assets/audit-report-template.md +181 -0
  5. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-checklist.md +462 -0
  6. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/audit-verify-queries.md +414 -0
  7. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-from-code-contract.md +87 -0
  8. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/build-workflow.md +260 -0
  9. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-sync.md +218 -0
  10. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/code-verify.md +152 -0
  11. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/component-design.md +198 -0
  12. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/decision-heuristics.md +262 -0
  13. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/iconography.md +150 -0
  14. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-generation.md +433 -0
  15. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/inventory-payload.md +490 -0
  16. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/migration-playbook.md +182 -0
  17. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/naming-and-file-structure.md +161 -0
  18. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/plugin-api-gotchas.md +79 -0
  19. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/scaffold-payload.md +279 -0
  20. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/sync-workflow.md +98 -0
  21. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/token-architecture.md +177 -0
  22. package/src/generators/preset/files/claude/skills/figma-workspace-architect/references/tool-map.md +398 -0
  23. package/src/generators/preset/files/claude/skills/uianatomy-mcp/SKILL.md +160 -0
  24. package/src/generators/preset/files/contracts/README.md +6 -6
  25. package/src/generators/preset/files/contracts/types.ts.template +9 -10
  26. package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/check-contracts.mjs +236 -223
  27. package/src/generators/preset/files/tools/{scripts → design-contracts/bin}/figma-snapshot-contracts.mjs +107 -92
  28. package/src/generators/preset/files/tools/design-contracts/src/codespec.mjs +234 -0
  29. package/src/generators/preset/files/tools/design-contracts/src/config.mjs +63 -0
  30. package/src/generators/preset/files/tools/{scripts/lib → design-contracts/src}/docgen.mjs +78 -98
  31. package/src/generators/preset/files/tools/{scripts/lib/ts-eval.js → design-contracts/src/ts-eval.cjs} +3 -4
  32. package/src/generators/preset/files/tools/scripts/preflight.mjs +1 -1
  33. package/src/generators/preset/preset.js +79 -15
  34. 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.mjs
3
+ * figma-snapshot-contracts
4
4
  *
5
5
  * A snapshot generator whose roster is the contracts, not a hand-maintained
6
- * master list. `tools/scripts/figma-snapshot.mjs` (the monorepo's own refresh
7
- * step, ADR-0019) hardcodes all 43 Atelier master node ids; that list has no
8
- * meaning outside this repo. This script instead reads whichever
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
- * Deliberately does NOT import tools/scripts/figma-snapshot.mjs — the MCP
16
- * client boilerplate and the `.mcp.json`-version-resolver below are copied
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
- * node tools/scripts/figma-snapshot-contracts.mjs --file <figmaFileKey> [--out <path>]
22
- * node tools/scripts/figma-snapshot-contracts.mjs --file <figmaFileKey> --dry-run
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 (same as figma-snapshot.mjs): Figma Desktop running with the
25
- * file open and the figma-console Desktop Bridge plugin connected. Fails
26
- * loud (exit 2) if the bridge is not connected — never a silent/empty write.
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 this script's own test suite
31
- * can exercise in an environment with no Figma Desktop Bridge.
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 { fileURLToPath } from 'node:url';
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.js is required relative to THIS script's own directory (like
49
- // check-contracts.mjs does) so the canonical script + lib/ts-eval.js pair
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('./lib/ts-eval.js');
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
- console.error(
72
- 'Usage: node tools/scripts/figma-snapshot-contracts.mjs --file <figmaFileKey> [--out <path>] [--contracts <dir>] [--dry-run]',
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
- // ─── Contracts-dir resolution (same precedence as check-contracts.mjs's
78
- // Step 1: CLI flag > contracts.config.json at the cwd root > monorepo
79
- // default) ──────────────────────────────────────────────────────────────
80
- const CONFIG_PATH = join(CWD, 'contracts.config.json');
81
- let fileConfig = null;
82
- if (existsSync(CONFIG_PATH)) {
83
- try {
84
- fileConfig = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
85
- } catch (e) {
86
- console.error(`${CONFIG_PATH}: invalid JSON (${e.message})`);
87
- process.exit(2);
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 CONTRACTS_DIR = args.contracts
92
- ? resolve(CWD, args.contracts)
93
- : fileConfig?.contracts
94
- ? resolve(CWD, fileConfig.contracts)
95
- : join(ROOT, 'libs/spec/src/contracts');
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
- const OUT_PATH = args.out
98
- ? resolve(CWD, args.out)
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
- // Modelled on figma-snapshot.mjs's own probe: componentPropertyDefinitions
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 the monorepo probe's whole-file walk — this script
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 .mcp.json ─────
206
- // Copied from figma-snapshot.mjs (ADR-0110: pin the server the skills
207
- // hardcode) — deliberately not imported, so this file stands alone.
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 (ADR-0110 pins this server).`,
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: 'atelier-figma-snapshot-contracts', version: '1.0.0' },
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. Same
279
- // retry shape as figma-snapshot.mjs: the plugin attaches ~0.5s after a
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 .mcp.json; server did not report)`
292
+ ? `${declaredServerVersion} (declared in ${MCP_CONFIG_PATH}; server did not report)`
304
293
  : null);
305
294
 
306
- // ─── Verify --file actually names the open file ────────────────────────
307
- // The Bridge reads whichever file is open in Figma Desktop, regardless of
308
- // what --file claims — figma-snapshot.mjs never had to check this because it
309
- // always targets the hardcoded Atelier FILE_KEY, but this script's whole
310
- // point is a participant's own duplicate, so the open file cannot be
311
- // assumed to match. figma.fileKey is the ground truth reported from inside
312
- // the plugin sandbox itself.
313
- const openFile = (
314
- await call(client, 'figma_execute', {
315
- code: `
316
- await figma.loadAllPagesAsync();
317
- return { fileKey: figma.fileKey ?? null, fileName: figma.root.name };
318
- `,
319
- timeout: 10000,
320
- })
321
- )?.result;
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
- `✗ --file ${args.file} does not match the file open in Figma Desktop ` +
325
- `(${openFile.fileKey}, "${openFile.fileName}"). Open the file you meant to ` +
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
+ }