@efolusi/meridian-guard 1.21.4 → 1.21.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -1
- package/package.json +1 -1
- package/src/cli.mjs +1 -1
- package/src/generated/meridian-rules.json +1 -1
- package/src/index.mjs +1 -1
- package/src/rules.mjs +30 -0
- package/src/scanner.mjs +109 -3
package/README.md
CHANGED
|
@@ -57,6 +57,12 @@ not shipped interface source.
|
|
|
57
57
|
| `MDG004` | warning | Deprecated props migrate to their canonical replacement. |
|
|
58
58
|
| `MDG005` | error | Required accessible names and dialog titles are present. |
|
|
59
59
|
| `MDG006` | error | Referenced Meridian radius tokens must exist in the generated token contract. |
|
|
60
|
+
| `MDG007` | warning | Non-zero interface radii use the shared Meridian radius hierarchy. |
|
|
61
|
+
| `MDG008` | warning | Box shadows use the warm Meridian elevation scale. |
|
|
62
|
+
| `MDG009` | warning | Interface animation and transition durations do not exceed 240 ms. |
|
|
63
|
+
| `MDG010` | warning | Font families use the Figtree, Bricolage, or JetBrains role tokens. |
|
|
64
|
+
| `MDG011` | warning | Font sizes use Meridian's named type scale. |
|
|
65
|
+
| `MDG012` | error | Consumer classes/styles do not repaint or reshape Button and IconButton chrome. |
|
|
60
66
|
|
|
61
67
|
Dynamic icon names cannot be proven statically and are left to the application.
|
|
62
68
|
Guard currently validates Meridian imports from the umbrella package and its
|
|
@@ -101,7 +107,7 @@ or `guard()` so they receive the packaged Meridian contract automatically.
|
|
|
101
107
|
|
|
102
108
|
## Scope and troubleshooting
|
|
103
109
|
|
|
104
|
-
- Guard parses JavaScript, JSX, TypeScript, TSX, MJS, and
|
|
110
|
+
- Guard parses JavaScript, JSX, TypeScript, TSX, MJS, CJS, and authored CSS. It is a focused
|
|
105
111
|
Meridian contract checker, not a replacement for ESLint or TypeScript.
|
|
106
112
|
- Dynamic component and icon names cannot be proven statically and are skipped.
|
|
107
113
|
- Test/spec files, fixtures, generated output, dependencies, minified files, and
|
package/package.json
CHANGED
package/src/cli.mjs
CHANGED
|
@@ -57,7 +57,7 @@ export async function main(argv, io = process) {
|
|
|
57
57
|
const targets = (options.paths.length ? options.paths : ['.']).map(target => path.resolve(cwd, target));
|
|
58
58
|
const result = await guard(targets, { contracts });
|
|
59
59
|
if (result.filesScanned === 0 && !options.allowEmpty) {
|
|
60
|
-
throw new Error('no supported JavaScript or
|
|
60
|
+
throw new Error('no supported JavaScript, TypeScript, or CSS source files found; check the target path or pass --allow-empty');
|
|
61
61
|
}
|
|
62
62
|
io.stdout.write(options.format === 'json' ? formatJson(result) : formatPretty(result, cwd));
|
|
63
63
|
if (result.diagnostics.length > 0) io.exitCode = 1;
|
package/src/index.mjs
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
export { guard, scanSource } from './scanner.mjs';
|
|
1
|
+
export { guard, scanSource, scanStyleSource } from './scanner.mjs';
|
|
2
2
|
export { RULES } from './rules.mjs';
|
package/src/rules.mjs
CHANGED
|
@@ -34,4 +34,34 @@ export const RULES = Object.freeze({
|
|
|
34
34
|
severity: 'error',
|
|
35
35
|
description: 'Referenced Meridian design token does not exist.',
|
|
36
36
|
},
|
|
37
|
+
rawRadius: {
|
|
38
|
+
id: 'MDG007',
|
|
39
|
+
severity: 'warning',
|
|
40
|
+
description: 'Non-zero radii use Meridian radius tokens.',
|
|
41
|
+
},
|
|
42
|
+
rawShadow: {
|
|
43
|
+
id: 'MDG008',
|
|
44
|
+
severity: 'warning',
|
|
45
|
+
description: 'Elevation uses Meridian shadow tokens.',
|
|
46
|
+
},
|
|
47
|
+
slowMotion: {
|
|
48
|
+
id: 'MDG009',
|
|
49
|
+
severity: 'warning',
|
|
50
|
+
description: 'Interface motion stays within Meridian\'s 240ms budget.',
|
|
51
|
+
},
|
|
52
|
+
rawFontFamily: {
|
|
53
|
+
id: 'MDG010',
|
|
54
|
+
severity: 'warning',
|
|
55
|
+
description: 'Typography uses Meridian font-family tokens.',
|
|
56
|
+
},
|
|
57
|
+
rawTypeSize: {
|
|
58
|
+
id: 'MDG011',
|
|
59
|
+
severity: 'warning',
|
|
60
|
+
description: 'Typography uses the Meridian type scale.',
|
|
61
|
+
},
|
|
62
|
+
componentChromeOverride: {
|
|
63
|
+
id: 'MDG012',
|
|
64
|
+
severity: 'error',
|
|
65
|
+
description: 'Consumer classes and inline styles must not override Meridian component paint or shape.',
|
|
66
|
+
},
|
|
37
67
|
});
|
package/src/scanner.mjs
CHANGED
|
@@ -4,7 +4,8 @@ import { parse } from '@babel/parser';
|
|
|
4
4
|
import { RULES } from './rules.mjs';
|
|
5
5
|
import defaultContracts from './generated/meridian-rules.json' with { type: 'json' };
|
|
6
6
|
|
|
7
|
-
const
|
|
7
|
+
const SCRIPT_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
|
|
8
|
+
const SOURCE_EXTENSIONS = new Set([...SCRIPT_EXTENSIONS, '.css']);
|
|
8
9
|
const IGNORED_DIRECTORIES = new Set([
|
|
9
10
|
'.git',
|
|
10
11
|
'.next',
|
|
@@ -31,7 +32,7 @@ const RADIUS_TOKEN = /var\(\s*--(radius-[a-z0-9-]+)\b/gi;
|
|
|
31
32
|
|
|
32
33
|
function ignoredSourceFile(target) {
|
|
33
34
|
const name = path.basename(target);
|
|
34
|
-
return /\.min\.(?:[cm]?[jt]sx?)$/i.test(name) || /\.(?:spec|test)\.[cm]?[jt]sx?$/i.test(name);
|
|
35
|
+
return /\.min\.(?:css|[cm]?[jt]sx?)$/i.test(name) || /\.(?:spec|test)\.[cm]?[jt]sx?$/i.test(name);
|
|
35
36
|
}
|
|
36
37
|
|
|
37
38
|
function diagnostic(file, node, rule, message) {
|
|
@@ -88,6 +89,16 @@ function staticAttributeValue(item) {
|
|
|
88
89
|
return null;
|
|
89
90
|
}
|
|
90
91
|
|
|
92
|
+
function inlineStyleKeys(item) {
|
|
93
|
+
if (item?.value?.type !== 'JSXExpressionContainer'
|
|
94
|
+
|| item.value.expression.type !== 'ObjectExpression') return [];
|
|
95
|
+
return item.value.expression.properties.flatMap(property => {
|
|
96
|
+
if (property.type !== 'ObjectProperty') return [];
|
|
97
|
+
const key = property.key?.name ?? property.key?.value;
|
|
98
|
+
return typeof key === 'string' ? [key] : [];
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
|
|
91
102
|
function walk(node, visitor, ancestors = []) {
|
|
92
103
|
if (!node || typeof node !== 'object') return;
|
|
93
104
|
visitor(node, ancestors);
|
|
@@ -174,6 +185,10 @@ export function scanSource(source, file, contracts) {
|
|
|
174
185
|
const imported = specifier.type === 'ImportDefaultSpecifier'
|
|
175
186
|
? deepBasename.replace(/\.(?:jsx?|tsx?)$/, '')
|
|
176
187
|
: specifier.imported.name || specifier.imported.value;
|
|
188
|
+
// The umbrella package also exposes lowercase helpers such as
|
|
189
|
+
// buttonVariants and toast. MDG001 validates React components, not every
|
|
190
|
+
// public JavaScript export.
|
|
191
|
+
if (!/^[A-Z]/.test(imported)) continue;
|
|
177
192
|
if (!validComponents.has(imported)) {
|
|
178
193
|
diagnostics.push(diagnostic(file, specifier, RULES.unknownComponent,
|
|
179
194
|
`"${imported}" is not a Meridian component. Check the component registry or the import path.`));
|
|
@@ -249,17 +264,108 @@ export function scanSource(source, file, contracts) {
|
|
|
249
264
|
diagnostics.push(diagnostic(file, node.openingElement, RULES.accessibility,
|
|
250
265
|
'<AlertDialogContent> requires an <AlertDialogTitle> descendant.'));
|
|
251
266
|
}
|
|
267
|
+
|
|
268
|
+
if (component === 'Button' || component === 'IconButton') {
|
|
269
|
+
const classAttribute = attribute(node, 'className');
|
|
270
|
+
const className = staticAttributeValue(classAttribute);
|
|
271
|
+
const chromeClass = className?.split(/\s+/).find(name =>
|
|
272
|
+
/^(?:(?:hover|focus|focus-visible|active|disabled|dark):)*(?:bg-|rounded(?:-|$)|text-(?:white|black|primary|secondary|muted|foreground|background|brand|danger|success|warning|\[))/.test(name),
|
|
273
|
+
);
|
|
274
|
+
if (chromeClass) {
|
|
275
|
+
diagnostics.push(diagnostic(file, classAttribute, RULES.componentChromeOverride,
|
|
276
|
+
`<${component}> class ${JSON.stringify(chromeClass)} overrides Meridian paint or radius. Use variant/size props and keep className structural.`));
|
|
277
|
+
}
|
|
278
|
+
const styleAttribute = attribute(node, 'style');
|
|
279
|
+
const chromeStyle = inlineStyleKeys(styleAttribute).find(key =>
|
|
280
|
+
['background', 'backgroundColor', 'borderRadius', 'boxShadow', 'color', 'fontFamily', 'fontSize'].includes(key),
|
|
281
|
+
);
|
|
282
|
+
if (chromeStyle) {
|
|
283
|
+
diagnostics.push(diagnostic(file, styleAttribute, RULES.componentChromeOverride,
|
|
284
|
+
`<${component}> inline style ${JSON.stringify(chromeStyle)} overrides Meridian component chrome. Use the component contract instead.`));
|
|
285
|
+
}
|
|
286
|
+
}
|
|
252
287
|
});
|
|
253
288
|
|
|
254
289
|
return diagnostics;
|
|
255
290
|
}
|
|
256
291
|
|
|
292
|
+
function lineAndColumn(source, offset) {
|
|
293
|
+
const before = source.slice(0, offset);
|
|
294
|
+
const lines = before.split('\n');
|
|
295
|
+
return { loc: { start: { line: lines.length, column: lines.at(-1).length } } };
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
function stripCssComments(source) {
|
|
299
|
+
return source.replace(/\/\*[\s\S]*?\*\//g, comment => comment.replace(/[^\n]/g, ' '));
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
function durationMs(value) {
|
|
303
|
+
const match = /(-?\d*\.?\d+)\s*(ms|s)\b/i.exec(value);
|
|
304
|
+
if (!match) return null;
|
|
305
|
+
const number = Number(match[1]);
|
|
306
|
+
return match[2].toLowerCase() === 's' ? number * 1000 : number;
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
export function scanStyleSource(source, file, contracts) {
|
|
310
|
+
const clean = stripCssComments(source);
|
|
311
|
+
const diagnostics = [];
|
|
312
|
+
const validTokens = new Set(contracts.tokens);
|
|
313
|
+
const declaration = /(^|[;{])\s*([a-z-]+)\s*:\s*([^;}]+)/gim;
|
|
314
|
+
for (const match of clean.matchAll(declaration)) {
|
|
315
|
+
const property = match[2].toLowerCase();
|
|
316
|
+
const value = match[3].trim();
|
|
317
|
+
const offset = match.index + match[0].indexOf(match[2]);
|
|
318
|
+
const node = lineAndColumn(source, offset);
|
|
319
|
+
|
|
320
|
+
const rawHex = value.match(HEX_COLOR)?.[0];
|
|
321
|
+
HEX_COLOR.lastIndex = 0;
|
|
322
|
+
if (rawHex) diagnostics.push(diagnostic(file, node, RULES.rawColor,
|
|
323
|
+
`Raw color ${JSON.stringify(rawHex)} bypasses Meridian semantic tokens. Use var(--token-name).`));
|
|
324
|
+
|
|
325
|
+
for (const tokenMatch of value.matchAll(RADIUS_TOKEN)) {
|
|
326
|
+
if (!validTokens.has(tokenMatch[1])) diagnostics.push(diagnostic(file, node, RULES.unknownToken,
|
|
327
|
+
`Unknown Meridian token "--${tokenMatch[1]}". Choose a radius token from the generated token contract.`));
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
if (/^(?:border-radius|border-(?:start|end)-(?:start|end)-radius|border-(?:top|right|bottom|left)-(?:left|right)-radius)$/.test(property)
|
|
331
|
+
&& !/var\(\s*--radius-/.test(value)
|
|
332
|
+
&& /(?:^|\s)(?!0(?:[\s/]|$))\d*\.?\d+(?:px|r?em)\b/i.test(value)) {
|
|
333
|
+
diagnostics.push(diagnostic(file, node, RULES.rawRadius,
|
|
334
|
+
`Raw ${property} value ${JSON.stringify(value)} bypasses the Meridian radius hierarchy.`));
|
|
335
|
+
}
|
|
336
|
+
if (property === 'box-shadow' && value !== 'none' && !/var\(\s*--shadow-/.test(value)) {
|
|
337
|
+
diagnostics.push(diagnostic(file, node, RULES.rawShadow,
|
|
338
|
+
`Raw box-shadow ${JSON.stringify(value)} bypasses Meridian elevation tokens.`));
|
|
339
|
+
}
|
|
340
|
+
if (/^(?:transition|transition-duration|animation|animation-duration)$/.test(property)) {
|
|
341
|
+
const durations = [...value.matchAll(/(-?\d*\.?\d+)\s*(ms|s)\b/gi)]
|
|
342
|
+
.map(item => durationMs(item[0])).filter(item => item !== null);
|
|
343
|
+
const slowest = Math.max(0, ...durations);
|
|
344
|
+
if (slowest > 240) diagnostics.push(diagnostic(file, node, RULES.slowMotion,
|
|
345
|
+
`Motion duration ${slowest}ms exceeds Meridian's 240ms interface budget.`));
|
|
346
|
+
}
|
|
347
|
+
if (property === 'font-family' && !/^(?:inherit|initial|unset)$/.test(value)
|
|
348
|
+
&& !/var\(\s*--font-(?:sans|display|mono)/.test(value)) {
|
|
349
|
+
diagnostics.push(diagnostic(file, node, RULES.rawFontFamily,
|
|
350
|
+
`Raw font-family ${JSON.stringify(value)} bypasses Meridian typography roles.`));
|
|
351
|
+
}
|
|
352
|
+
if (property === 'font-size' && !/var\(\s*--text-/.test(value)
|
|
353
|
+
&& /(?:\d*\.?\d+(?:px|r?em)\b|clamp\s*\()/i.test(value)) {
|
|
354
|
+
diagnostics.push(diagnostic(file, node, RULES.rawTypeSize,
|
|
355
|
+
`Raw font-size ${JSON.stringify(value)} bypasses the Meridian type scale.`));
|
|
356
|
+
}
|
|
357
|
+
}
|
|
358
|
+
return diagnostics;
|
|
359
|
+
}
|
|
360
|
+
|
|
257
361
|
export async function guard(targets, { contracts = defaultContracts } = {}) {
|
|
258
362
|
const files = await collectFiles(targets);
|
|
259
363
|
const diagnostics = [];
|
|
260
364
|
for (const file of files) {
|
|
261
365
|
const source = await fs.readFile(file, 'utf8');
|
|
262
|
-
diagnostics.push(...
|
|
366
|
+
diagnostics.push(...(path.extname(file) === '.css'
|
|
367
|
+
? scanStyleSource(source, file, contracts)
|
|
368
|
+
: scanSource(source, file, contracts)));
|
|
263
369
|
}
|
|
264
370
|
diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId));
|
|
265
371
|
return { filesScanned: files.length, diagnostics };
|