mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 11:43:26 +08:00
522 lines
16 KiB
JavaScript
Executable File
522 lines
16 KiB
JavaScript
Executable File
#!/usr/bin/env node
|
|
|
|
/**
|
|
* SLDS Quality Analyzer
|
|
*
|
|
* Analyzes CSS and HTML files for SLDS quality issues beyond what the linter catches.
|
|
*
|
|
* Usage: node analyze-quality.cjs <component-path> [--hooks-index <path>]
|
|
*
|
|
* Output: JSON with findings categorized by severity
|
|
*/
|
|
|
|
const fs = require('fs');
|
|
const path = require('path');
|
|
|
|
function resolveHooksIndexPath(args) {
|
|
const idx = args.indexOf('--hooks-index');
|
|
if (idx !== -1 && idx + 1 < args.length) {
|
|
return path.resolve(args[idx + 1]);
|
|
}
|
|
return null;
|
|
}
|
|
|
|
let HOOKS_INDEX_PATH = null;
|
|
|
|
// Severity levels
|
|
const CRITICAL = 'critical';
|
|
const WARNING = 'warning';
|
|
const INFO = 'info';
|
|
|
|
// Detection patterns
|
|
// NOTE: Checks that the SLDS linter already handles are excluded here to avoid
|
|
// double-counting. The linter covers: slds/class-override (L001),
|
|
// slds/lwc-token-to-slds-hook (L002), slds/no-hardcoded-values (L003).
|
|
// This script focuses on what the linter does NOT catch.
|
|
const PATTERNS = {
|
|
// CSS patterns (linter-complementary only)
|
|
css: {
|
|
missingFallback: {
|
|
pattern: /var\(--slds-g-[^,)]+\)/g,
|
|
severity: CRITICAL,
|
|
id: 'T002',
|
|
message: 'SLDS hook without fallback value',
|
|
recommendation: 'Add fallback: var(--slds-g-color-surface-1, #fff)'
|
|
},
|
|
important: {
|
|
pattern: /!important/g,
|
|
severity: WARNING,
|
|
id: 'Q001',
|
|
message: '!important declaration found',
|
|
recommendation: 'Remove !important, use proper specificity'
|
|
},
|
|
magicPixels: {
|
|
pattern: /\b(?:margin(?:-[a-z-]+)?|padding(?:-[a-z-]+)?|gap|row-gap|column-gap)\s*:\s*(\d+)px\b(?![^;]*var\()/g,
|
|
severity: WARNING,
|
|
id: 'T021',
|
|
message: 'Magic pixel value not using spacing hook',
|
|
recommendation: 'Use var(--slds-g-spacing-*) or utility class'
|
|
},
|
|
highZindex: {
|
|
pattern: /z-index\s*:\s*(\d{3,})/g,
|
|
severity: WARNING,
|
|
id: 'Q021',
|
|
message: 'High z-index value',
|
|
recommendation: 'Use defined z-index scale'
|
|
},
|
|
outlineNone: {
|
|
pattern: /outline\s*:\s*none/g,
|
|
severity: WARNING,
|
|
id: 'A021',
|
|
message: 'Focus outline removed without alternative',
|
|
recommendation: 'Provide alternative focus indicator'
|
|
}
|
|
},
|
|
// JS patterns (inline styles and dynamic class manipulation)
|
|
js: {
|
|
inlineStyleJS: {
|
|
pattern: /\.style\.\w+\s*=/g,
|
|
severity: WARNING,
|
|
id: 'Q025',
|
|
message: 'Inline style manipulation in JavaScript',
|
|
recommendation: 'Use CSS classes instead of direct style property assignment'
|
|
},
|
|
classListManipulation: {
|
|
pattern: /\.classList\.(add|remove|toggle)\(\s*['"]slds-/g,
|
|
severity: WARNING,
|
|
id: 'Q012',
|
|
message: 'Dynamic SLDS class manipulation in JavaScript',
|
|
recommendation: 'Prefer declarative class bindings; avoid manipulating slds-* classes directly'
|
|
}
|
|
},
|
|
// HTML patterns
|
|
html: {
|
|
inlineStyle: {
|
|
pattern: /style\s*=\s*["'][^"']+["']/gi,
|
|
severity: WARNING,
|
|
id: 'Q002',
|
|
message: 'Inline style attribute',
|
|
recommendation: 'Move styles to CSS file'
|
|
},
|
|
lightningInputNoLabel: {
|
|
pattern: /<lightning-input(?![^>]*\blabel\b)[^>]*>/gi,
|
|
severity: CRITICAL,
|
|
id: 'A001',
|
|
message: 'Lightning input without label attribute',
|
|
recommendation: 'Add label attribute to lightning-input'
|
|
},
|
|
iconNoAlt: {
|
|
pattern: /<lightning-icon(?![^>]*alternative-text)[^>]*>/gi,
|
|
severity: CRITICAL,
|
|
id: 'A004',
|
|
message: 'Icon without alternative-text',
|
|
recommendation: 'Add alternative-text (or empty string for decorative)'
|
|
},
|
|
imgNoAlt: {
|
|
pattern: /<img(?![^>]*\balt\b)[^>]*>/gi,
|
|
severity: CRITICAL,
|
|
id: 'A005',
|
|
message: 'Image without alt attribute',
|
|
recommendation: 'Add alt attribute'
|
|
},
|
|
positiveTabindex: {
|
|
pattern: /tabindex\s*=\s*["']([1-9]\d*)["']/gi,
|
|
severity: WARNING,
|
|
id: 'A020',
|
|
message: 'Positive tabindex value',
|
|
recommendation: 'Use tabindex="0" or "-1" only'
|
|
},
|
|
clickableDiv: {
|
|
pattern: /<div[^>]*onclick[^>]*>/gi,
|
|
severity: WARNING,
|
|
id: 'A022',
|
|
message: 'Div with click handler instead of button',
|
|
recommendation: 'Use <button> or <lightning-button> for interactive elements'
|
|
},
|
|
nativeInput: {
|
|
pattern: /<input\s/gi,
|
|
severity: WARNING,
|
|
id: 'C001',
|
|
message: 'Native input element',
|
|
recommendation: 'Consider <lightning-input> for built-in labeling and validation'
|
|
},
|
|
nativeButton: {
|
|
pattern: /<button\s(?![^>]*class\s*=\s*["'][^"']*slds-button)/gi,
|
|
severity: WARNING,
|
|
id: 'C002',
|
|
message: 'Native button element',
|
|
recommendation: 'Consider <lightning-button> for SLDS styling consistency (suppressed if slds-button class present)'
|
|
},
|
|
nativeSelect: {
|
|
pattern: /<select\s/gi,
|
|
severity: WARNING,
|
|
id: 'C004',
|
|
message: 'Native select element',
|
|
recommendation: 'Consider <lightning-combobox> for consistency'
|
|
}
|
|
}
|
|
};
|
|
|
|
/**
|
|
* Find all files with given extensions in directory
|
|
*/
|
|
function findFiles(dir, extensions) {
|
|
const files = [];
|
|
|
|
function walk(currentDir) {
|
|
try {
|
|
const items = fs.readdirSync(currentDir);
|
|
for (const item of items) {
|
|
const fullPath = path.join(currentDir, item);
|
|
const stat = fs.statSync(fullPath);
|
|
|
|
if (stat.isDirectory() && !item.startsWith('.') && item !== 'node_modules') {
|
|
walk(fullPath);
|
|
} else if (stat.isFile()) {
|
|
const ext = path.extname(item).toLowerCase();
|
|
if (extensions.includes(ext)) {
|
|
files.push(fullPath);
|
|
}
|
|
}
|
|
}
|
|
} catch (err) {
|
|
// Skip directories we can't read
|
|
}
|
|
}
|
|
|
|
walk(dir);
|
|
return files;
|
|
}
|
|
|
|
/**
|
|
* Analyze a single file
|
|
*/
|
|
function analyzeFile(filePath, patterns) {
|
|
const findings = [];
|
|
const content = fs.readFileSync(filePath, 'utf-8');
|
|
const lines = content.split('\n');
|
|
|
|
for (const [name, config] of Object.entries(patterns)) {
|
|
const regex = new RegExp(config.pattern.source, config.pattern.flags);
|
|
let match;
|
|
|
|
while ((match = regex.exec(content)) !== null) {
|
|
// Find line number
|
|
const beforeMatch = content.substring(0, match.index);
|
|
const lineNumber = beforeMatch.split('\n').length;
|
|
const lineContent = lines[lineNumber - 1] || '';
|
|
|
|
findings.push({
|
|
id: config.id,
|
|
severity: config.severity,
|
|
file: filePath,
|
|
line: lineNumber,
|
|
column: match.index - beforeMatch.lastIndexOf('\n'),
|
|
match: match[0].substring(0, 50),
|
|
message: config.message,
|
|
recommendation: config.recommendation,
|
|
context: lineContent.trim().substring(0, 80)
|
|
});
|
|
}
|
|
}
|
|
|
|
return findings;
|
|
}
|
|
|
|
/**
|
|
* Analyze heading hierarchy in HTML
|
|
*/
|
|
function analyzeHeadings(filePath) {
|
|
const findings = [];
|
|
const content = fs.readFileSync(filePath, 'utf-8');
|
|
const headingRegex = /<h([1-6])[^>]*>/gi;
|
|
const headings = [];
|
|
let match;
|
|
|
|
while ((match = headingRegex.exec(content)) !== null) {
|
|
headings.push({
|
|
level: parseInt(match[1]),
|
|
index: match.index
|
|
});
|
|
}
|
|
|
|
// Check for skipped levels
|
|
for (let i = 1; i < headings.length; i++) {
|
|
const prev = headings[i - 1].level;
|
|
const curr = headings[i].level;
|
|
|
|
if (curr > prev + 1) {
|
|
const beforeMatch = content.substring(0, headings[i].index);
|
|
const lineNumber = beforeMatch.split('\n').length;
|
|
|
|
findings.push({
|
|
id: 'A010',
|
|
severity: WARNING,
|
|
file: filePath,
|
|
line: lineNumber,
|
|
message: `Skipped heading level: h${prev} to h${curr}`,
|
|
recommendation: `Use h${prev + 1} instead of h${curr}`
|
|
});
|
|
}
|
|
}
|
|
|
|
return findings;
|
|
}
|
|
|
|
/**
|
|
* Load valid hook tokens from hooks-index.json
|
|
*/
|
|
let _validHooks = null;
|
|
function loadValidHooks() {
|
|
if (_validHooks) return _validHooks;
|
|
if (!HOOKS_INDEX_PATH) return null;
|
|
try {
|
|
const data = JSON.parse(fs.readFileSync(HOOKS_INDEX_PATH, 'utf-8'));
|
|
_validHooks = new Set(data.hooks.map(h => h.token));
|
|
} catch {
|
|
console.error(`WARNING: Could not load hooks-index.json at ${HOOKS_INDEX_PATH}`);
|
|
console.error('Invented-hook detection (T051) will be skipped.');
|
|
_validHooks = null;
|
|
}
|
|
return _validHooks;
|
|
}
|
|
|
|
/**
|
|
* Check for invented hooks (T051) — hooks referenced in CSS that don't exist in metadata
|
|
*/
|
|
function analyzeInventedHooks(filePath) {
|
|
const findings = [];
|
|
const validHooks = loadValidHooks();
|
|
if (!validHooks) return findings; // skip if metadata unavailable
|
|
|
|
const content = fs.readFileSync(filePath, 'utf-8');
|
|
const lines = content.split('\n');
|
|
const hookRef = /var\((--slds-g-[^,)]+)/g;
|
|
let match;
|
|
|
|
while ((match = hookRef.exec(content)) !== null) {
|
|
const hookName = match[1].trim();
|
|
if (!validHooks.has(hookName)) {
|
|
const beforeMatch = content.substring(0, match.index);
|
|
const lineNumber = beforeMatch.split('\n').length;
|
|
const lineContent = lines[lineNumber - 1] || '';
|
|
|
|
findings.push({
|
|
id: 'T051',
|
|
severity: CRITICAL,
|
|
file: filePath,
|
|
line: lineNumber,
|
|
match: hookName,
|
|
message: `Invented hook — "${hookName}" does not exist in hooks-index.json`,
|
|
recommendation: 'Verify the hook exists via: node scripts/search-hooks.cjs --prefix "' + hookName + '"',
|
|
context: lineContent.trim().substring(0, 80)
|
|
});
|
|
}
|
|
}
|
|
|
|
return findings;
|
|
}
|
|
|
|
/**
|
|
* Check for hook pairing issues
|
|
*/
|
|
function analyzeHookPairing(filePath) {
|
|
const findings = [];
|
|
const content = fs.readFileSync(filePath, 'utf-8');
|
|
|
|
// Find all background hooks
|
|
const bgHookRegex = /--slds-g-color-(surface|accent|success|warning|error|info)(?:-container)?-\d/g;
|
|
const textHookRegex = /--slds-g-color-on-(surface|accent|success|warning|error|info)(?:-container)?-\d/g;
|
|
|
|
const bgHooks = content.match(bgHookRegex) || [];
|
|
const textHooks = content.match(textHookRegex) || [];
|
|
|
|
// Extract families
|
|
const bgFamilies = new Set(bgHooks.map(h => {
|
|
const match = h.match(/--slds-g-color-(\w+(?:-container)?)-\d/);
|
|
return match ? match[1] : null;
|
|
}).filter(Boolean));
|
|
|
|
const textFamilies = new Set(textHooks.map(h => {
|
|
const match = h.match(/--slds-g-color-on-(\w+(?:-container)?)-\d/);
|
|
return match ? match[1] : null;
|
|
}).filter(Boolean));
|
|
|
|
// Check for mismatches
|
|
for (const bgFamily of bgFamilies) {
|
|
const expectedTextFamily = bgFamily.replace('-container', '');
|
|
if (!textFamilies.has(expectedTextFamily) && !textFamilies.has(bgFamily)) {
|
|
findings.push({
|
|
id: 'T010',
|
|
severity: WARNING,
|
|
file: filePath,
|
|
message: `Background hook family '${bgFamily}' may lack matching text hook`,
|
|
recommendation: `Pair with --slds-g-color-on-${expectedTextFamily}-*`
|
|
});
|
|
}
|
|
}
|
|
|
|
return findings;
|
|
}
|
|
|
|
/**
|
|
* Calculate scores from findings
|
|
*/
|
|
function calculateScores(findings) {
|
|
const weights = {
|
|
[CRITICAL]: 10,
|
|
[WARNING]: 3,
|
|
[INFO]: 1
|
|
};
|
|
|
|
// NOTE: Linter findings (L001, L002, L003) come from the SLDS linter output,
|
|
// not from this script. They should be merged in by the calling agent.
|
|
// This script only produces findings for the other categories.
|
|
const categories = {
|
|
theming: { issues: 0, ids: ['T002', 'T010', 'T011', 'T021', 'T051'] },
|
|
accessibility: { issues: 0, ids: ['A001', 'A004', 'A005', 'A010', 'A020', 'A021', 'A022'] },
|
|
codeQuality: { issues: 0, ids: ['Q001', 'Q002', 'Q012', 'Q021', 'Q025'] },
|
|
componentUsage: { issues: 0, ids: ['C001', 'C002', 'C004'] }
|
|
};
|
|
|
|
// Count weighted issues per category
|
|
for (const finding of findings) {
|
|
const weight = weights[finding.severity];
|
|
for (const [category, config] of Object.entries(categories)) {
|
|
if (config.ids.includes(finding.id)) {
|
|
config.issues += weight;
|
|
break;
|
|
}
|
|
}
|
|
}
|
|
|
|
// Calculate scores
|
|
const scores = {};
|
|
for (const [category, config] of Object.entries(categories)) {
|
|
scores[category] = Math.max(0, 100 - config.issues);
|
|
}
|
|
|
|
return scores;
|
|
}
|
|
|
|
/**
|
|
* Get grade from score
|
|
*/
|
|
function getGrade(score) {
|
|
if (score >= 90) return 'A';
|
|
if (score >= 80) return 'B';
|
|
if (score >= 70) return 'C';
|
|
if (score >= 60) return 'D';
|
|
return 'F';
|
|
}
|
|
|
|
/**
|
|
* Main analysis function
|
|
*/
|
|
function analyze(componentPath) {
|
|
const resolvedPath = path.resolve(componentPath);
|
|
|
|
if (!fs.existsSync(resolvedPath)) {
|
|
console.error(`Error: Path does not exist: ${resolvedPath}`);
|
|
process.exit(1);
|
|
}
|
|
|
|
const findings = [];
|
|
|
|
// Find and analyze CSS files
|
|
const cssFiles = findFiles(resolvedPath, ['.css']);
|
|
for (const file of cssFiles) {
|
|
findings.push(...analyzeFile(file, PATTERNS.css));
|
|
findings.push(...analyzeHookPairing(file));
|
|
findings.push(...analyzeInventedHooks(file));
|
|
}
|
|
|
|
// Find and analyze HTML files
|
|
const htmlFiles = findFiles(resolvedPath, ['.html']);
|
|
for (const file of htmlFiles) {
|
|
findings.push(...analyzeFile(file, PATTERNS.html));
|
|
findings.push(...analyzeHeadings(file));
|
|
}
|
|
|
|
// Find and analyze JS files
|
|
const jsFiles = findFiles(resolvedPath, ['.js']);
|
|
for (const file of jsFiles) {
|
|
findings.push(...analyzeFile(file, PATTERNS.js));
|
|
}
|
|
|
|
// Calculate scores
|
|
const scores = calculateScores(findings);
|
|
|
|
// Organize findings by severity
|
|
const organized = {
|
|
critical: findings.filter(f => f.severity === CRITICAL),
|
|
warning: findings.filter(f => f.severity === WARNING),
|
|
info: findings.filter(f => f.severity === INFO)
|
|
};
|
|
|
|
// Calculate total lines for complexity classification
|
|
let totalLines = 0;
|
|
for (const file of [...cssFiles, ...htmlFiles, ...jsFiles]) {
|
|
totalLines += fs.readFileSync(file, 'utf-8').split('\n').length;
|
|
}
|
|
const totalFiles = cssFiles.length + htmlFiles.length + jsFiles.length;
|
|
let complexity = 'small';
|
|
if (totalFiles >= 7 || totalLines >= 500) complexity = 'large';
|
|
else if (totalFiles >= 3 || totalLines >= 100) complexity = 'medium';
|
|
|
|
// Build result
|
|
const result = {
|
|
component: path.basename(resolvedPath),
|
|
path: resolvedPath,
|
|
timestamp: new Date().toISOString(),
|
|
complexity: {
|
|
classification: complexity,
|
|
totalFiles,
|
|
totalLines
|
|
},
|
|
note: "These are automated category scores only. Combine them with SLDS linter results and the required Step 3 manual review gate in SKILL.md before making a final ship recommendation.",
|
|
scores: {
|
|
theming: { score: scores.theming, grade: getGrade(scores.theming) },
|
|
accessibility: { score: scores.accessibility, grade: getGrade(scores.accessibility) },
|
|
codeQuality: { score: scores.codeQuality, grade: getGrade(scores.codeQuality) },
|
|
componentUsage: { score: scores.componentUsage, grade: getGrade(scores.componentUsage) }
|
|
},
|
|
findings: organized,
|
|
summary: {
|
|
filesAnalyzed: totalFiles,
|
|
cssFiles: cssFiles.length,
|
|
htmlFiles: htmlFiles.length,
|
|
jsFiles: jsFiles.length,
|
|
totalLines,
|
|
critical: organized.critical.length,
|
|
warnings: organized.warning.length,
|
|
info: organized.info.length
|
|
}
|
|
};
|
|
|
|
return result;
|
|
}
|
|
|
|
// CLI entry point
|
|
if (require.main === module) {
|
|
const args = process.argv.slice(2);
|
|
const positionalArgs = args.filter((a, i) => !a.startsWith('--') && (i === 0 || !args[i - 1].startsWith('--')));
|
|
|
|
if (positionalArgs.length === 0) {
|
|
console.log('SLDS Quality Analyzer');
|
|
console.log('Usage: node analyze-quality.cjs <component-path> [--hooks-index <path>]');
|
|
console.log('');
|
|
console.log('Options:');
|
|
console.log(' --hooks-index <path> Path to hooks-index.json (optional; enables T051 invented-hook detection)');
|
|
console.log('');
|
|
console.log('Output: JSON analysis of SLDS quality issues');
|
|
process.exit(0);
|
|
}
|
|
|
|
HOOKS_INDEX_PATH = resolveHooksIndexPath(args);
|
|
const result = analyze(positionalArgs[0]);
|
|
console.log(JSON.stringify(result, null, 2));
|
|
}
|
|
|
|
module.exports = { analyze, PATTERNS };
|