@efolusi/meridian-guard 1.21.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.
- package/LICENSE +21 -0
- package/README.md +54 -0
- package/bin/meridian-guard.js +7 -0
- package/package.json +40 -0
- package/src/cli.mjs +55 -0
- package/src/generated/meridian-rules.json +1902 -0
- package/src/index.mjs +2 -0
- package/src/reporter.mjs +26 -0
- package/src/rules.mjs +37 -0
- package/src/scanner.mjs +266 -0
package/src/index.mjs
ADDED
package/src/reporter.mjs
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import path from 'node:path';
|
|
2
|
+
|
|
3
|
+
export function formatPretty(result, cwd = process.cwd()) {
|
|
4
|
+
const lines = result.diagnostics.map(diagnostic => {
|
|
5
|
+
const file = path.relative(cwd, diagnostic.file) || path.basename(diagnostic.file);
|
|
6
|
+
return `${file}:${diagnostic.line}:${diagnostic.column} ${diagnostic.severity} ${diagnostic.ruleId}\n ${diagnostic.message}`;
|
|
7
|
+
});
|
|
8
|
+
const errors = result.diagnostics.filter(item => item.severity === 'error').length;
|
|
9
|
+
const warnings = result.diagnostics.length - errors;
|
|
10
|
+
lines.push(
|
|
11
|
+
result.diagnostics.length
|
|
12
|
+
? `\nMeridian Guard found ${errors} error(s) and ${warnings} warning(s) in ${result.filesScanned} file(s).`
|
|
13
|
+
: `Meridian Guard passed ${result.filesScanned} file(s).`,
|
|
14
|
+
);
|
|
15
|
+
return `${lines.join('\n')}\n`;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export function formatJson(result) {
|
|
19
|
+
return `${JSON.stringify({
|
|
20
|
+
version: 1,
|
|
21
|
+
filesScanned: result.filesScanned,
|
|
22
|
+
errors: result.diagnostics.filter(item => item.severity === 'error').length,
|
|
23
|
+
warnings: result.diagnostics.filter(item => item.severity === 'warning').length,
|
|
24
|
+
diagnostics: result.diagnostics,
|
|
25
|
+
}, null, 2)}\n`;
|
|
26
|
+
}
|
package/src/rules.mjs
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
export const RULES = Object.freeze({
|
|
2
|
+
parse: {
|
|
3
|
+
id: 'MDG000',
|
|
4
|
+
severity: 'error',
|
|
5
|
+
description: 'Source could not be parsed, so Guard could not validate it.',
|
|
6
|
+
},
|
|
7
|
+
unknownComponent: {
|
|
8
|
+
id: 'MDG001',
|
|
9
|
+
severity: 'error',
|
|
10
|
+
description: 'Imported Meridian component does not exist.',
|
|
11
|
+
},
|
|
12
|
+
unknownIcon: {
|
|
13
|
+
id: 'MDG002',
|
|
14
|
+
severity: 'error',
|
|
15
|
+
description: 'Icon name does not exist in the Meridian icon set.',
|
|
16
|
+
},
|
|
17
|
+
rawColor: {
|
|
18
|
+
id: 'MDG003',
|
|
19
|
+
severity: 'warning',
|
|
20
|
+
description: 'Raw colors bypass Meridian semantic tokens.',
|
|
21
|
+
},
|
|
22
|
+
deprecatedApi: {
|
|
23
|
+
id: 'MDG004',
|
|
24
|
+
severity: 'warning',
|
|
25
|
+
description: 'Deprecated Meridian API should be replaced by its canonical API.',
|
|
26
|
+
},
|
|
27
|
+
accessibility: {
|
|
28
|
+
id: 'MDG005',
|
|
29
|
+
severity: 'error',
|
|
30
|
+
description: 'Meridian accessibility contract is incomplete.',
|
|
31
|
+
},
|
|
32
|
+
unknownToken: {
|
|
33
|
+
id: 'MDG006',
|
|
34
|
+
severity: 'error',
|
|
35
|
+
description: 'Referenced Meridian design token does not exist.',
|
|
36
|
+
},
|
|
37
|
+
});
|
package/src/scanner.mjs
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { parse } from '@babel/parser';
|
|
4
|
+
import { RULES } from './rules.mjs';
|
|
5
|
+
import defaultContracts from './generated/meridian-rules.json' with { type: 'json' };
|
|
6
|
+
|
|
7
|
+
const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx']);
|
|
8
|
+
const IGNORED_DIRECTORIES = new Set([
|
|
9
|
+
'.git',
|
|
10
|
+
'.next',
|
|
11
|
+
'.nuxt',
|
|
12
|
+
'.open-next',
|
|
13
|
+
'.output',
|
|
14
|
+
'.svelte-kit',
|
|
15
|
+
'.turbo',
|
|
16
|
+
'.vercel',
|
|
17
|
+
'.wrangler',
|
|
18
|
+
'__fixtures__',
|
|
19
|
+
'__tests__',
|
|
20
|
+
'build',
|
|
21
|
+
'coverage',
|
|
22
|
+
'dist',
|
|
23
|
+
'fixtures',
|
|
24
|
+
'node_modules',
|
|
25
|
+
'out',
|
|
26
|
+
'target',
|
|
27
|
+
'vendor',
|
|
28
|
+
]);
|
|
29
|
+
const HEX_COLOR = /#[0-9a-fA-F]{3,8}\b/g;
|
|
30
|
+
const RADIUS_TOKEN = /var\(\s*--(radius-[a-z0-9-]+)\b/gi;
|
|
31
|
+
|
|
32
|
+
function ignoredSourceFile(target) {
|
|
33
|
+
const name = path.basename(target);
|
|
34
|
+
return /\.min\.(?:[cm]?[jt]sx?)$/i.test(name) || /\.(?:spec|test)\.[cm]?[jt]sx?$/i.test(name);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
function diagnostic(file, node, rule, message) {
|
|
38
|
+
return {
|
|
39
|
+
file,
|
|
40
|
+
line: node?.loc?.start?.line || 1,
|
|
41
|
+
column: (node?.loc?.start?.column || 0) + 1,
|
|
42
|
+
ruleId: rule.id,
|
|
43
|
+
severity: rule.severity,
|
|
44
|
+
message,
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
async function collectFiles(targets) {
|
|
49
|
+
const files = [];
|
|
50
|
+
async function visit(target) {
|
|
51
|
+
const stat = await fs.lstat(target);
|
|
52
|
+
if (stat.isSymbolicLink()) return;
|
|
53
|
+
if (stat.isFile()) {
|
|
54
|
+
if (SOURCE_EXTENSIONS.has(path.extname(target)) && !ignoredSourceFile(target)) files.push(path.resolve(target));
|
|
55
|
+
return;
|
|
56
|
+
}
|
|
57
|
+
if (!stat.isDirectory()) return;
|
|
58
|
+
const entries = await fs.readdir(target, { withFileTypes: true });
|
|
59
|
+
for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
|
|
60
|
+
if (entry.isSymbolicLink()) continue;
|
|
61
|
+
if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name)) continue;
|
|
62
|
+
await visit(path.join(target, entry.name));
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
for (const target of targets) await visit(target);
|
|
66
|
+
return [...new Set(files)].sort();
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function jsxName(node) {
|
|
70
|
+
if (!node) return null;
|
|
71
|
+
if (node.type === 'JSXIdentifier') return node.name;
|
|
72
|
+
if (node.type === 'JSXMemberExpression') return `${jsxName(node.object)}.${jsxName(node.property)}`;
|
|
73
|
+
return null;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function attribute(element, name) {
|
|
77
|
+
return element.openingElement.attributes.find(item =>
|
|
78
|
+
item.type === 'JSXAttribute' && item.name?.name === name,
|
|
79
|
+
);
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function staticAttributeValue(item) {
|
|
83
|
+
if (!item?.value) return null;
|
|
84
|
+
if (item.value.type === 'StringLiteral') return item.value.value;
|
|
85
|
+
if (item.value.type === 'JSXExpressionContainer' && item.value.expression.type === 'StringLiteral') {
|
|
86
|
+
return item.value.expression.value;
|
|
87
|
+
}
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function walk(node, visitor, ancestors = []) {
|
|
92
|
+
if (!node || typeof node !== 'object') return;
|
|
93
|
+
visitor(node, ancestors);
|
|
94
|
+
const next = [...ancestors, node];
|
|
95
|
+
for (const [key, value] of Object.entries(node)) {
|
|
96
|
+
if (key === 'loc' || key === 'start' || key === 'end' || key === 'extra') continue;
|
|
97
|
+
if (Array.isArray(value)) {
|
|
98
|
+
for (const child of value) walk(child, visitor, next);
|
|
99
|
+
} else if (value && typeof value === 'object' && typeof value.type === 'string') {
|
|
100
|
+
walk(value, visitor, next);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
function isMeridianImport(source) {
|
|
106
|
+
return source === '@efolusi/meridian' || source.startsWith('@efolusi/meridian/');
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
function canonicalName(rawName, imports, namespaces) {
|
|
110
|
+
if (imports.has(rawName)) return imports.get(rawName);
|
|
111
|
+
const [namespace, member] = rawName.split('.');
|
|
112
|
+
if (member && namespaces.has(namespace)) return member;
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function hasDescendant(element, expected, imports, namespaces) {
|
|
117
|
+
let found = false;
|
|
118
|
+
for (const child of element.children || []) {
|
|
119
|
+
walk(child, node => {
|
|
120
|
+
if (node.type !== 'JSXOpeningElement') return;
|
|
121
|
+
if (canonicalName(jsxName(node.name), imports, namespaces) === expected) found = true;
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
return found;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function rawColorContext(node, ancestors) {
|
|
128
|
+
const jsxAttribute = [...ancestors].reverse().find(parent => parent.type === 'JSXAttribute');
|
|
129
|
+
if (jsxAttribute) return ['style', 'color', 'background', 'fill', 'stroke'].includes(jsxAttribute.name?.name);
|
|
130
|
+
if (node.type === 'TemplateElement') {
|
|
131
|
+
if (ancestors.some(parent => parent.type === 'TaggedTemplateExpression')) return true;
|
|
132
|
+
const declaration = [...ancestors].reverse().find(parent => parent.type === 'VariableDeclarator');
|
|
133
|
+
const name = declaration?.id?.name || '';
|
|
134
|
+
return /(?:css|style|theme)$/i.test(name);
|
|
135
|
+
}
|
|
136
|
+
const property = [...ancestors].reverse().find(parent => parent.type === 'ObjectProperty');
|
|
137
|
+
if (property) {
|
|
138
|
+
const key = property.key?.name || property.key?.value || '';
|
|
139
|
+
return /color|background|border|shadow|fill|stroke|outline/i.test(String(key));
|
|
140
|
+
}
|
|
141
|
+
return false;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
export function scanSource(source, file, contracts) {
|
|
145
|
+
let ast;
|
|
146
|
+
try {
|
|
147
|
+
ast = parse(source, {
|
|
148
|
+
sourceType: 'unambiguous',
|
|
149
|
+
errorRecovery: false,
|
|
150
|
+
plugins: ['jsx', 'typescript', 'importAttributes'],
|
|
151
|
+
});
|
|
152
|
+
} catch (error) {
|
|
153
|
+
return [diagnostic(file, error, RULES.parse, `Could not parse source: ${error.message}`)];
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
const diagnostics = [];
|
|
157
|
+
const validComponents = new Set(contracts.components.map(item => item.name));
|
|
158
|
+
const validIcons = new Set(contracts.icons);
|
|
159
|
+
const validTokens = new Set(contracts.tokens);
|
|
160
|
+
const imports = new Map();
|
|
161
|
+
const namespaces = new Set();
|
|
162
|
+
|
|
163
|
+
for (const statement of ast.program.body) {
|
|
164
|
+
if (statement.type !== 'ImportDeclaration' || !isMeridianImport(statement.source.value)) continue;
|
|
165
|
+
for (const specifier of statement.specifiers) {
|
|
166
|
+
if (statement.importKind === 'type' || specifier.importKind === 'type' || specifier.importKind === 'typeof') continue;
|
|
167
|
+
if (specifier.type === 'ImportNamespaceSpecifier') {
|
|
168
|
+
namespaces.add(specifier.local.name);
|
|
169
|
+
continue;
|
|
170
|
+
}
|
|
171
|
+
const deepDefault = specifier.type === 'ImportDefaultSpecifier' && statement.source.value !== '@efolusi/meridian';
|
|
172
|
+
const deepBasename = path.basename(statement.source.value);
|
|
173
|
+
if (deepDefault && !/^[A-Z][A-Za-z0-9_$]*\.(?:jsx?|tsx?)$/.test(deepBasename)) continue;
|
|
174
|
+
const imported = specifier.type === 'ImportDefaultSpecifier'
|
|
175
|
+
? deepBasename.replace(/\.(?:jsx?|tsx?)$/, '')
|
|
176
|
+
: specifier.imported.name || specifier.imported.value;
|
|
177
|
+
if (!validComponents.has(imported)) {
|
|
178
|
+
diagnostics.push(diagnostic(file, specifier, RULES.unknownComponent,
|
|
179
|
+
`"${imported}" is not a Meridian component. Check the component registry or the import path.`));
|
|
180
|
+
continue;
|
|
181
|
+
}
|
|
182
|
+
imports.set(specifier.local.name, imported);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
const deprecated = new Map(contracts.deprecated.map(item => [`${item.component}:${item.prop}`, item]));
|
|
187
|
+
walk(ast.program, (node, ancestors) => {
|
|
188
|
+
if (node.type === 'StringLiteral' || node.type === 'TemplateElement') {
|
|
189
|
+
const value = node.type === 'StringLiteral' ? node.value : node.value.raw;
|
|
190
|
+
if (HEX_COLOR.test(value) && rawColorContext(node, ancestors)) {
|
|
191
|
+
HEX_COLOR.lastIndex = 0;
|
|
192
|
+
diagnostics.push(diagnostic(file, node, RULES.rawColor,
|
|
193
|
+
`Raw color ${JSON.stringify(value.match(HEX_COLOR)?.[0])} bypasses Meridian semantic tokens. Use var(--token-name).`));
|
|
194
|
+
}
|
|
195
|
+
HEX_COLOR.lastIndex = 0;
|
|
196
|
+
if (rawColorContext(node, ancestors)) {
|
|
197
|
+
for (const match of value.matchAll(RADIUS_TOKEN)) {
|
|
198
|
+
if (!validTokens.has(match[1])) {
|
|
199
|
+
diagnostics.push(diagnostic(file, node, RULES.unknownToken,
|
|
200
|
+
`Unknown Meridian token "--${match[1]}". Choose a radius token from the generated token contract.`));
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
if (node.type !== 'JSXElement') return;
|
|
206
|
+
const raw = jsxName(node.openingElement.name);
|
|
207
|
+
const component = canonicalName(raw, imports, namespaces);
|
|
208
|
+
if (!component) return;
|
|
209
|
+
const [rawNamespace] = raw.split('.');
|
|
210
|
+
if (raw.includes('.') && namespaces.has(rawNamespace) && !validComponents.has(component)) {
|
|
211
|
+
diagnostics.push(diagnostic(file, node.openingElement, RULES.unknownComponent,
|
|
212
|
+
`"${component}" is not a Meridian component. Check the component registry.`));
|
|
213
|
+
return;
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
if (component === 'Icon' || component === 'IconButton') {
|
|
217
|
+
const propName = component === 'Icon' ? 'name' : 'icon';
|
|
218
|
+
const iconAttribute = attribute(node, propName);
|
|
219
|
+
const iconName = staticAttributeValue(iconAttribute);
|
|
220
|
+
if (iconName && !validIcons.has(iconName)) {
|
|
221
|
+
diagnostics.push(diagnostic(file, iconAttribute, RULES.unknownIcon,
|
|
222
|
+
`"${iconName}" is not a Meridian icon. Choose a name from the icon registry.`));
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
for (const item of node.openingElement.attributes) {
|
|
227
|
+
if (item.type !== 'JSXAttribute') continue;
|
|
228
|
+
const contract = deprecated.get(`${component}:${item.name.name}`);
|
|
229
|
+
if (!contract) continue;
|
|
230
|
+
diagnostics.push(diagnostic(file, item, RULES.deprecatedApi,
|
|
231
|
+
contract.replacement
|
|
232
|
+
? `<${component}> prop "${contract.prop}" is deprecated; use "${contract.replacement}".`
|
|
233
|
+
: `<${component}> prop "${contract.prop}" is deprecated. ${contract.message}`));
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
if (component === 'IconButton' && !attribute(node, 'label')) {
|
|
237
|
+
diagnostics.push(diagnostic(file, node.openingElement, RULES.accessibility,
|
|
238
|
+
'<IconButton> requires a descriptive "label" prop for its accessible name.'));
|
|
239
|
+
}
|
|
240
|
+
if (component === 'Dialog' && !attribute(node, 'title') && !hasDescendant(node, 'DialogTitle', imports, namespaces)) {
|
|
241
|
+
diagnostics.push(diagnostic(file, node.openingElement, RULES.accessibility,
|
|
242
|
+
'<Dialog> requires a "title" prop or a <DialogTitle> descendant for its accessible name.'));
|
|
243
|
+
}
|
|
244
|
+
if (component === 'DialogContent' && !hasDescendant(node, 'DialogTitle', imports, namespaces)) {
|
|
245
|
+
diagnostics.push(diagnostic(file, node.openingElement, RULES.accessibility,
|
|
246
|
+
'<DialogContent> requires a <DialogTitle> descendant.'));
|
|
247
|
+
}
|
|
248
|
+
if (component === 'AlertDialogContent' && !hasDescendant(node, 'AlertDialogTitle', imports, namespaces)) {
|
|
249
|
+
diagnostics.push(diagnostic(file, node.openingElement, RULES.accessibility,
|
|
250
|
+
'<AlertDialogContent> requires an <AlertDialogTitle> descendant.'));
|
|
251
|
+
}
|
|
252
|
+
});
|
|
253
|
+
|
|
254
|
+
return diagnostics;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
export async function guard(targets, { contracts = defaultContracts } = {}) {
|
|
258
|
+
const files = await collectFiles(targets);
|
|
259
|
+
const diagnostics = [];
|
|
260
|
+
for (const file of files) {
|
|
261
|
+
const source = await fs.readFile(file, 'utf8');
|
|
262
|
+
diagnostics.push(...scanSource(source, file, contracts));
|
|
263
|
+
}
|
|
264
|
+
diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId));
|
|
265
|
+
return { filesScanned: files.length, diagnostics };
|
|
266
|
+
}
|