@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 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 CJS. It is a focused
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@efolusi/meridian-guard",
3
- "version": "1.21.4",
3
+ "version": "1.21.5",
4
4
  "description": "Static compliance checks for React applications built with the Meridian design system.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://meridian.efolusi.com",
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 TypeScript source files found; check the target path or pass --allow-empty');
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;
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "1.21.4",
3
+ "version": "1.21.5",
4
4
  "components": [
5
5
  {
6
6
  "name": "Accordion",
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 SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
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(...scanSource(source, file, contracts));
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 };