stylelint-plugin-rhythmguard 3.19.0 → 3.20.0
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/CHANGELOG.md +37 -0
- package/README.md +3 -3
- package/SECURITY.md +2 -1
- package/agents/claude-code/SKILL.md +1 -1
- package/package.json +1 -1
- package/src/audit/args.js +30 -8
- package/src/audit/baseline.js +37 -3
- package/src/audit/codemod.js +2 -0
- package/src/audit/config.js +7 -0
- package/src/audit/contract.js +124 -14
- package/src/audit/next-steps.js +3 -1
- package/src/audit/non-authored.js +1 -0
- package/src/audit/render-github.js +16 -11
- package/src/audit/render-markdown.js +8 -2
- package/src/audit/render-text.js +41 -2
- package/src/audit/render-utils.js +14 -0
- package/src/audit/report.js +230 -10
- package/src/audit/scan/files.js +5 -0
- package/src/audit/scan/stylesheets.js +48 -53
- package/src/audit/scan/templates.js +2 -0
- package/src/audit/shared.js +7 -1
- package/src/audit/token-chains.js +1 -0
- package/src/cli/audit.js +2 -2
- package/src/cli/doctor.js +853 -237
- package/src/cli/first-run.js +210 -0
- package/src/cli/index.js +25 -1
- package/src/cli/index.mjs +3 -0
- package/src/cli/init.js +39 -11
- package/src/cli/quickstart.js +53 -102
- package/src/cli/scale.js +223 -0
- package/src/configs/recommended.js +3 -1
- package/src/configs/strict.js +3 -1
- package/src/configs/tailwind.js +15 -0
- package/src/core/decisions.js +18 -5
- package/src/core/fs-cache.js +1 -0
- package/src/core/options.js +2 -1
- package/src/core/scale-inference.js +72 -52
- package/src/core/tailwind-class-analysis.js +56 -13
- package/src/core/token-index.js +55 -14
- package/src/core/token-map.js +136 -28
- package/src/core/token-sources.js +461 -40
- package/src/core/value-nodes.js +4 -2
- package/src/eslint/class-context.js +330 -0
- package/src/eslint/literal-spans.js +5 -4
- package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
- package/src/presets/default-scale.js +42 -0
- package/src/presets/scales.js +6 -1
- package/src/rules/no-offscale-transform/index.js +17 -5
- package/src/rules/prefer-token/index.js +51 -15
- package/src/rules/use-scale/index.js +7 -4
- package/types/__checks__/consumer.ts +17 -0
- package/types/__checks__/eslint-config.ts +5 -0
- package/types/audit.d.ts +40 -3
- package/types/cli.d.ts +77 -1
- package/types/shared.d.ts +10 -0
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
const { getAllFindings } = require('./baseline');
|
|
3
|
+
const { getAllFindings, isTokenDebtFinding } = require('./baseline');
|
|
4
|
+
const { newFindingsPhrase } = require('./render-utils');
|
|
4
5
|
|
|
5
6
|
/**
|
|
6
7
|
* GitHub shows at most 10 error and 10 warning annotations per step and drops
|
|
7
8
|
* the rest without a word, so the one line a pull request added was annotation
|
|
8
9
|
* 4,695 of 5,987 (ci-03). The summary comes first; with a baseline only the
|
|
9
|
-
* new findings are annotated, as errors
|
|
10
|
-
* notice that says how many were left out.
|
|
10
|
+
* new findings are annotated, drift as errors and token debt as warnings;
|
|
11
|
+
* each type stops at the cap with a notice that says how many were left out.
|
|
12
|
+
* Arrays are walked, not spread:
|
|
11
13
|
* spreading 150,000 findings into push() overflowed the stack (cq-04).
|
|
12
14
|
*/
|
|
13
15
|
const ANNOTATIONS_PER_TYPE = 10;
|
|
@@ -24,7 +26,7 @@ function renderGithub(report) {
|
|
|
24
26
|
const fileWord = report.filesWithIssues === 1 ? 'file' : 'files';
|
|
25
27
|
const lines = [
|
|
26
28
|
`::notice title=Rhythmguard audit::${escapeGithubData([
|
|
27
|
-
...(baseline ? [`Since baseline: ${baseline.resolvedFindingsCount} resolved, ${baseline
|
|
29
|
+
...(baseline ? [`Since baseline: ${baseline.resolvedFindingsCount} resolved, ${newFindingsPhrase(baseline)}.`] : []),
|
|
28
30
|
`${findings.length} ${findingWord} across ${report.filesWithIssues} ${fileWord}, ${report.scaleCleanliness}% scale cleanliness`,
|
|
29
31
|
].join(' '))}`,
|
|
30
32
|
];
|
|
@@ -34,14 +36,17 @@ function renderGithub(report) {
|
|
|
34
36
|
for (const finding of parseErrors) {
|
|
35
37
|
errors.push(annotation('error', { ...finding, rule: finding.rule || 'CssSyntaxError' }, `Not audited: ${finding.text || ''}`));
|
|
36
38
|
}
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
const
|
|
40
|
-
|
|
41
|
-
|
|
39
|
+
// New drift is an error. New token debt is a warning: it is not drift and
|
|
40
|
+
// fails no gate unless --fail-on-new-token-debt is set (dx-08).
|
|
41
|
+
const errorLines = [...errors];
|
|
42
|
+
const warningLines = [];
|
|
43
|
+
for (const finding of baseline ? baseline.newFindings || [] : findings) {
|
|
44
|
+
if (baseline && !isTokenDebtFinding(finding)) {
|
|
45
|
+
errorLines.push(annotation('error', finding, `New since the baseline: ${finding.text || ''}`));
|
|
46
|
+
} else {
|
|
47
|
+
warningLines.push(annotation('warning', finding, `${baseline ? 'New since the baseline: ' : ''}${finding.text || ''}`));
|
|
48
|
+
}
|
|
42
49
|
}
|
|
43
|
-
const errorLines = level === 'error' ? [...errors, ...rest] : errors;
|
|
44
|
-
const warningLines = level === 'warning' ? rest : [];
|
|
45
50
|
|
|
46
51
|
for (const group of [errorLines, warningLines]) {
|
|
47
52
|
for (const line of group.slice(0, ANNOTATIONS_PER_TYPE)) {
|
|
@@ -3,9 +3,12 @@
|
|
|
3
3
|
const { sortCountMap } = require('./contract');
|
|
4
4
|
const { auditCommand } = require('./next-steps');
|
|
5
5
|
const { nothingAudited, nothingAuditedReasons } = require('./render-text');
|
|
6
|
-
const { escapeMarkdown, markdownCode, tableCode } = require('./render-utils');
|
|
6
|
+
const { escapeMarkdown, markdownCode, newFindingsPhrase, tableCode } = require('./render-utils');
|
|
7
7
|
|
|
8
8
|
function describeScaleSource(scale) {
|
|
9
|
+
if (scale.rejected && scale.rejected.source === 'token-sources') {
|
|
10
|
+
return `${scale.source} (token sources gave no scale; see the warnings)`;
|
|
11
|
+
}
|
|
9
12
|
if (scale.rejected) {
|
|
10
13
|
return `${scale.source} (${scale.rejected.source} rejected: ${scale.rejected.reasons.join(', ')})`;
|
|
11
14
|
}
|
|
@@ -24,7 +27,7 @@ function renderMarkdown(report, options = {}) {
|
|
|
24
27
|
const lines = [
|
|
25
28
|
'# Rhythmguard Design-System Audit',
|
|
26
29
|
'',
|
|
27
|
-
...(report.baseline ? [`**Since baseline:** ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline
|
|
30
|
+
...(report.baseline ? [`**Since baseline:** ${report.baseline.resolvedFindingsCount} resolved, ${newFindingsPhrase(report.baseline)}.`, ''] : []),
|
|
28
31
|
`Directory: ${markdownCode(report.directory)}`,
|
|
29
32
|
'',
|
|
30
33
|
];
|
|
@@ -54,6 +57,9 @@ function renderMarkdown(report, options = {}) {
|
|
|
54
57
|
if (report.scale) {
|
|
55
58
|
lines.push(`| Scale | ${report.scale.values.join(', ')} |`);
|
|
56
59
|
lines.push(`| Scale source | ${escapeMarkdown(describeScaleSource(report.scale))} |`);
|
|
60
|
+
if (report.scale.classStrings) {
|
|
61
|
+
lines.push(`| Class-string scale | ${escapeMarkdown(report.scale.classStrings.name)} |`);
|
|
62
|
+
}
|
|
57
63
|
}
|
|
58
64
|
|
|
59
65
|
if (report.decisions) {
|
package/src/audit/render-text.js
CHANGED
|
@@ -7,6 +7,7 @@ const {
|
|
|
7
7
|
const { auditCommand, shellQuote } = require('./next-steps');
|
|
8
8
|
const {
|
|
9
9
|
histBar,
|
|
10
|
+
newFindingsPhrase,
|
|
10
11
|
scoreBar,
|
|
11
12
|
truncate,
|
|
12
13
|
} = require('./render-utils');
|
|
@@ -38,14 +39,27 @@ function renderText(report, options = {}) {
|
|
|
38
39
|
if (report.scale) {
|
|
39
40
|
lines.push(` Scale ${report.scale.values.join(', ')}`);
|
|
40
41
|
const files = report.scale.files.length > 0 ? ` (${report.scale.files.join(', ')})` : '';
|
|
41
|
-
|
|
42
|
+
// Configured token sources that gave no scale: their warnings are printed under the token contract.
|
|
43
|
+
const rejected = !report.scale.rejected ? ''
|
|
44
|
+
: report.scale.rejected.source === 'token-sources' ? ' (token sources gave no scale; see the warnings)'
|
|
45
|
+
: ` (${report.scale.rejected.source} rejected: ${report.scale.rejected.reasons.join(', ')})`;
|
|
42
46
|
lines.push(` Scale source ${report.scale.source}${files}${rejected}`);
|
|
47
|
+
// Warnings that belong to no token source, such as a Tailwind config that could not be loaded (cq-05).
|
|
48
|
+
const sourceWarnings = new Set(((report.tokenContract && report.tokenContract.sources) || []).flatMap((source) => source.warnings || []));
|
|
49
|
+
for (const warning of new Set(report.tokenSourceWarnings || [])) {
|
|
50
|
+
if (!sourceWarnings.has(warning)) {
|
|
51
|
+
lines.push(` ! ${warning}`);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
if (report.scale.classStrings) {
|
|
55
|
+
lines.push(` Class-string scale ${report.scale.classStrings.name} (${report.scale.classStrings.values.join(', ')})`);
|
|
56
|
+
}
|
|
43
57
|
}
|
|
44
58
|
if (report.decisions) {
|
|
45
59
|
lines.push(` Decisions ${report.decisions.adopt + report.decisions.allow + report.decisions.snap + report.decisions.undecided} (${report.decisions.adopt} adopt, ${report.decisions.allow} allow, ${report.decisions.snap} snap, ${report.decisions.undecided} undecided); ${report.decisions.suppressed} findings suppressed`);
|
|
46
60
|
}
|
|
47
61
|
if (report.baseline) {
|
|
48
|
-
lines.push(` Since baseline ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline
|
|
62
|
+
lines.push(` Since baseline ${report.baseline.resolvedFindingsCount} resolved, ${newFindingsPhrase(report.baseline)}`);
|
|
49
63
|
}
|
|
50
64
|
lines.push('');
|
|
51
65
|
|
|
@@ -54,6 +68,8 @@ function renderText(report, options = {}) {
|
|
|
54
68
|
appendHistogram(lines, 'CSS TOKEN OPPORTUNITIES', report.tokenOpportunities);
|
|
55
69
|
appendHistogram(lines, 'TAILWIND CLASS-STRING DRIFT', report.tailwindArbitraryValues);
|
|
56
70
|
appendHistogram(lines, 'MOTION RHYTHM DRIFT', report.motion.values);
|
|
71
|
+
appendFindingList(lines, 'MISSING TOKENS IN USE', report.findings.css.filter((finding) => finding.type === 'missing-token'));
|
|
72
|
+
appendFindingList(lines, 'UNCLASSIFIED WARNINGS', report.findings.css.filter((finding) => finding.type === 'unclassified'));
|
|
57
73
|
appendTokenContractText(lines, report.tokenContract);
|
|
58
74
|
if (report.tokenContract.chains && report.tokenContract.chains.summary.total > 0) {
|
|
59
75
|
const { summary } = report.tokenContract.chains;
|
|
@@ -209,6 +225,9 @@ function appendBaselineText(lines, report) {
|
|
|
209
225
|
lines.push('');
|
|
210
226
|
lines.push(` Baseline findings ${String(report.baseline.baselineFindings).padStart(4)}`);
|
|
211
227
|
lines.push(` New findings ${String(report.baseline.newFindingsCount).padStart(4)}`);
|
|
228
|
+
if (report.baseline.newTokenDebtCount > 0) {
|
|
229
|
+
lines.push(` of which token debt ${String(report.baseline.newTokenDebtCount).padStart(4)} (not drift; --fail-on-new-token-debt gates it)`);
|
|
230
|
+
}
|
|
212
231
|
lines.push(` Resolved findings ${String(report.baseline.resolvedFindingsCount).padStart(4)}`);
|
|
213
232
|
lines.push('');
|
|
214
233
|
}
|
|
@@ -219,6 +238,26 @@ function appendBaselineText(lines, report) {
|
|
|
219
238
|
}
|
|
220
239
|
}
|
|
221
240
|
|
|
241
|
+
/**
|
|
242
|
+
* Findings that have no value to count by: missing-token uses (with
|
|
243
|
+
* --report-missing-tokens) and Stylelint warnings the audit could not read
|
|
244
|
+
* (cq-02). Ten lines, then a count.
|
|
245
|
+
*/
|
|
246
|
+
function appendFindingList(lines, title, findings) {
|
|
247
|
+
if (findings.length === 0) {
|
|
248
|
+
return;
|
|
249
|
+
}
|
|
250
|
+
lines.push(` ── ${title} ── ${findings.length} total`);
|
|
251
|
+
lines.push('');
|
|
252
|
+
for (const finding of findings.slice(0, 10)) {
|
|
253
|
+
lines.push(` ${finding.file}:${finding.line}:${finding.column} ${finding.text}`);
|
|
254
|
+
}
|
|
255
|
+
if (findings.length > 10) {
|
|
256
|
+
lines.push(` ${findings.length - 10} more in --format json`);
|
|
257
|
+
}
|
|
258
|
+
lines.push('');
|
|
259
|
+
}
|
|
260
|
+
|
|
222
261
|
function appendHistogram(lines, title, counts = {}) {
|
|
223
262
|
const entries = sortCountMap(counts || {});
|
|
224
263
|
const total = sumCounts(counts || {});
|
|
@@ -57,11 +57,25 @@ function escapeHtml(value) {
|
|
|
57
57
|
.replace(/"/g, '"');
|
|
58
58
|
}
|
|
59
59
|
|
|
60
|
+
/**
|
|
61
|
+
* "N new", and when some of them are token debt, how many are drift and how
|
|
62
|
+
* many token debt: --fail-on-new-drift counts only the drift (dx-08).
|
|
63
|
+
*/
|
|
64
|
+
function newFindingsPhrase(baseline) {
|
|
65
|
+
const total = baseline.newFindingsCount;
|
|
66
|
+
const debt = Number.isInteger(baseline.newTokenDebtCount) ? baseline.newTokenDebtCount : 0;
|
|
67
|
+
if (debt === 0) {
|
|
68
|
+
return `${total} new`;
|
|
69
|
+
}
|
|
70
|
+
return `${total} new (${total - debt} drift, ${debt} token debt)`;
|
|
71
|
+
}
|
|
72
|
+
|
|
60
73
|
module.exports = {
|
|
61
74
|
escapeHtml,
|
|
62
75
|
escapeMarkdown,
|
|
63
76
|
histBar,
|
|
64
77
|
markdownCode,
|
|
78
|
+
newFindingsPhrase,
|
|
65
79
|
tableCode,
|
|
66
80
|
scoreBar,
|
|
67
81
|
truncate,
|
package/src/audit/report.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
+
const fs = require('node:fs');
|
|
3
4
|
const path = require('node:path');
|
|
4
5
|
|
|
5
6
|
const {
|
|
@@ -18,11 +19,33 @@ const {
|
|
|
18
19
|
} = require('./config');
|
|
19
20
|
const { buildReport, collectTokenDefinitions } = require('./contract');
|
|
20
21
|
const { DEFAULT_SCALE, formatPath } = require('./shared');
|
|
22
|
+
const { TAILWIND_SCALE_NAME, TAILWIND_SPACING_UNIT_REM, tailwindSpacingLadder } = require('../presets/default-scale');
|
|
23
|
+
|
|
24
|
+
const TAILWIND_CONFIG_FILES = ['tailwind.config.js', 'tailwind.config.cjs', 'tailwind.config.mjs', 'tailwind.config.ts'];
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Whether the project in `cwd` uses Tailwind: a `tailwindcss` or
|
|
28
|
+
* `@tailwindcss/*` dependency, or a Tailwind config file (found, not loaded).
|
|
29
|
+
* Its `--scale auto` fallback is then Tailwind's ladder, as in configs/tailwind.
|
|
30
|
+
*/
|
|
31
|
+
function isTailwindProject(cwd) {
|
|
32
|
+
try {
|
|
33
|
+
const pkg = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
|
|
34
|
+
const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies, ...pkg.peerDependencies });
|
|
35
|
+
if (deps.some((name) => name === 'tailwindcss' || name.startsWith('@tailwindcss/'))) {
|
|
36
|
+
return true;
|
|
37
|
+
}
|
|
38
|
+
} catch {
|
|
39
|
+
// No readable package.json: decide by the config file alone.
|
|
40
|
+
}
|
|
41
|
+
return TAILWIND_CONFIG_FILES.some((file) => fs.existsSync(path.join(cwd, file)));
|
|
42
|
+
}
|
|
21
43
|
const {
|
|
22
44
|
assessScale,
|
|
23
45
|
discoverTokenPackages,
|
|
24
46
|
inferScaleFromDefinitions,
|
|
25
47
|
scaleFromDefinitions,
|
|
48
|
+
scaleFromTailwindConfig,
|
|
26
49
|
} = require('../core/scale-inference');
|
|
27
50
|
const { buildGroupScales } = require('../core/options');
|
|
28
51
|
const { applyDecisions, buildDecisionPlan } = require('./decisions');
|
|
@@ -33,14 +56,19 @@ const { nonAuthoredReason } = require('./non-authored');
|
|
|
33
56
|
const { collectCssFindings, runStylelintAudit } = require('./scan/stylesheets');
|
|
34
57
|
const { collectTailwindFindings, collectTailwindMotionFindings } = require('./scan/templates');
|
|
35
58
|
|
|
36
|
-
|
|
37
|
-
|
|
59
|
+
/**
|
|
60
|
+
* What an audit run reads before it lints anything: the files, the token
|
|
61
|
+
* sources and the one resolved scale. `rhythmguard scale` prints the scale
|
|
62
|
+
* from here, so it always names the scale the audit would check against.
|
|
63
|
+
* `parsed` is the options after normalizeCreateAuditOptions.
|
|
64
|
+
*/
|
|
65
|
+
function prepareAuditRun(parsed) {
|
|
38
66
|
const resolvedDir = assertDirectory(parsed.dir);
|
|
39
67
|
const ignorePatterns = resolveIgnorePatterns(parsed);
|
|
40
68
|
|
|
41
69
|
const scanFiles = getScanFiles(resolvedDir, ignorePatterns, parsed);
|
|
42
70
|
|
|
43
|
-
const {
|
|
71
|
+
const { templateFiles } = scanFiles;
|
|
44
72
|
// A --staged run reads each changed file as the index holds it.
|
|
45
73
|
const readSource = scanFiles.readSource || readSourceFromDisk;
|
|
46
74
|
|
|
@@ -63,6 +91,12 @@ async function createAuditReport(options) {
|
|
|
63
91
|
warnWhenEmpty: true,
|
|
64
92
|
});
|
|
65
93
|
|
|
94
|
+
// A configured Tailwind config that does not exist is a configuration error,
|
|
95
|
+
// as a missing token source is (the CLI exits 2 on either).
|
|
96
|
+
if (parsed.tailwindConfigPath && !fs.existsSync(path.resolve(process.cwd(), parsed.tailwindConfigPath))) {
|
|
97
|
+
tokenSourceResult.warnings.push(`Tailwind config not found: ${parsed.tailwindConfigPath}`);
|
|
98
|
+
}
|
|
99
|
+
|
|
66
100
|
// The spacing scale always reads spacing tokens; --token-kind shapes the token contract only (issue #260).
|
|
67
101
|
const spacingSourceResult = parsed.tokenKind === 'spacing'
|
|
68
102
|
? tokenSourceResult
|
|
@@ -72,15 +106,109 @@ async function createAuditReport(options) {
|
|
|
72
106
|
// against, so it is the scale the report names and prefer-token reads (#283).
|
|
73
107
|
const groupScales = buildGroupScales(parsed.scales);
|
|
74
108
|
const spacingOverride = groupScales.spacing && Array.isArray(groupScales.spacing.scale) ? groupScales.spacing.scale : null;
|
|
109
|
+
const isNonAuthored = (file) => nonAuthored.has(file);
|
|
75
110
|
const scale = resolveAuditScale({
|
|
76
111
|
baseFontSize: parsed.baseFontSize,
|
|
77
112
|
cssFiles,
|
|
78
|
-
isNonAuthored
|
|
113
|
+
isNonAuthored,
|
|
79
114
|
readSource,
|
|
80
115
|
requested: spacingOverride || parsed.scale,
|
|
116
|
+
tailwindConfigPath: parsed.tailwindConfigPath,
|
|
81
117
|
tokenSourceResult: spacingSourceResult,
|
|
118
|
+
// Loader warnings (a Tailwind config that throws) join the token source warnings (cq-05).
|
|
119
|
+
warnings: tokenSourceResult.warnings,
|
|
82
120
|
});
|
|
83
121
|
|
|
122
|
+
// Class strings follow the ESLint rule: with no scale of the project's own
|
|
123
|
+
// (the default, or "auto" finding none), they are judged by Tailwind's
|
|
124
|
+
// default ladder, so the audit and `tailwind-class-use-scale` agree (cs-05).
|
|
125
|
+
const classScale = classStringScale(scale, templateFiles, parsed.baseFontSize);
|
|
126
|
+
if (classScale) {
|
|
127
|
+
scale.classStrings = classScale;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
return {
|
|
131
|
+
classScale,
|
|
132
|
+
cssFiles,
|
|
133
|
+
groupScales,
|
|
134
|
+
isNonAuthored,
|
|
135
|
+
nonAuthored,
|
|
136
|
+
nonAuthoredSkipped,
|
|
137
|
+
readSource,
|
|
138
|
+
resolvedDir,
|
|
139
|
+
scale,
|
|
140
|
+
scanFiles,
|
|
141
|
+
spacingSourceResult,
|
|
142
|
+
templateFiles,
|
|
143
|
+
tokenSourceResult,
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The places the audit knows spacing tokens from, as `scaleSources` entries
|
|
149
|
+
* for prefer-token: the configured token sources that exist, then every
|
|
150
|
+
* authored stylesheet that declares a spacing custom property or Sass token.
|
|
151
|
+
* prefer-token then names the token that holds a raw value, and the file it
|
|
152
|
+
* comes from, as the token contract does (dx-08, ci-01). A token declared in
|
|
153
|
+
* a component block or under a media query in another file is never offered
|
|
154
|
+
* outside it: the rule's token index keeps each declaration's scope.
|
|
155
|
+
*/
|
|
156
|
+
function tokenScaleSources({ baseFontSize, cssFiles, isNonAuthored, readSource, tokenSources }) {
|
|
157
|
+
const entries = [];
|
|
158
|
+
for (const source of tokenSources || []) {
|
|
159
|
+
if (!source || typeof source !== 'object' || !source.path) {
|
|
160
|
+
continue;
|
|
161
|
+
}
|
|
162
|
+
const resolved = path.resolve(source.baseDir || process.cwd(), source.path);
|
|
163
|
+
if (!fs.existsSync(resolved)) {
|
|
164
|
+
continue;
|
|
165
|
+
}
|
|
166
|
+
entries.push({
|
|
167
|
+
format: source.format || 'auto',
|
|
168
|
+
path: resolved,
|
|
169
|
+
...(source.tokenPattern ? { tokenPattern: source.tokenPattern } : {}),
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
const matchesKind = createTokenKindMatcher('spacing');
|
|
174
|
+
for (const filePath of cssFiles) {
|
|
175
|
+
if (isNonAuthored(filePath)) {
|
|
176
|
+
continue;
|
|
177
|
+
}
|
|
178
|
+
let text;
|
|
179
|
+
try {
|
|
180
|
+
text = readSource(filePath);
|
|
181
|
+
} catch {
|
|
182
|
+
// Unreadable since the scan (deleted, permissions): this pass reads only what it can.
|
|
183
|
+
continue;
|
|
184
|
+
}
|
|
185
|
+
const definitions = new Map();
|
|
186
|
+
collectTokenDefinitions(text, formatPath(filePath), definitions, matchesKind, baseFontSize);
|
|
187
|
+
if (definitions.size > 0) {
|
|
188
|
+
entries.push({ format: 'css', path: path.resolve(filePath) });
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
return entries;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
async function createAuditReport(options) {
|
|
195
|
+
const parsed = normalizeCreateAuditOptions(options);
|
|
196
|
+
const run = prepareAuditRun(parsed);
|
|
197
|
+
const {
|
|
198
|
+
classScale,
|
|
199
|
+
cssFiles,
|
|
200
|
+
groupScales,
|
|
201
|
+
nonAuthored,
|
|
202
|
+
nonAuthoredSkipped,
|
|
203
|
+
readSource,
|
|
204
|
+
resolvedDir,
|
|
205
|
+
scale,
|
|
206
|
+
scanFiles,
|
|
207
|
+
templateFiles,
|
|
208
|
+
tokenSourceResult,
|
|
209
|
+
} = run;
|
|
210
|
+
const { scanScope } = scanFiles;
|
|
211
|
+
|
|
84
212
|
const lintOptions = {
|
|
85
213
|
baseFontSize: parsed.baseFontSize,
|
|
86
214
|
checkMathBounds: parsed.checkMathBounds,
|
|
@@ -88,8 +216,17 @@ async function createAuditReport(options) {
|
|
|
88
216
|
readSource: scanFiles.readSource,
|
|
89
217
|
scale: scale.values,
|
|
90
218
|
scales: parsed.scales,
|
|
219
|
+
tokenScaleSources: tokenScaleSources({
|
|
220
|
+
baseFontSize: parsed.baseFontSize,
|
|
221
|
+
cssFiles,
|
|
222
|
+
isNonAuthored: run.isNonAuthored,
|
|
223
|
+
readSource,
|
|
224
|
+
tokenSources: parsed.tokenSources,
|
|
225
|
+
}),
|
|
91
226
|
};
|
|
92
227
|
|
|
228
|
+
const classOptions = classScale ? { ...lintOptions, scale: classScale.values } : lintOptions;
|
|
229
|
+
|
|
93
230
|
const cssResults = await runStylelintAudit(cssFiles, lintOptions);
|
|
94
231
|
const collectedCssFindings = collectCssFindings(cssResults, readSource);
|
|
95
232
|
// A stylesheet that failed to parse was not audited; it is reported apart
|
|
@@ -100,7 +237,7 @@ async function createAuditReport(options) {
|
|
|
100
237
|
baseFontSize: parsed.baseFontSize,
|
|
101
238
|
cssFindings: stylelintFindings.filter((finding) => !finding.type.startsWith('motion-')),
|
|
102
239
|
decisions: parsed.decisions || [],
|
|
103
|
-
tailwindFindings: collectTailwindFindings(templateFiles,
|
|
240
|
+
tailwindFindings: collectTailwindFindings(templateFiles, classOptions),
|
|
104
241
|
});
|
|
105
242
|
const cssFindings = decided.cssFindings;
|
|
106
243
|
const motionFindings = [
|
|
@@ -108,6 +245,9 @@ async function createAuditReport(options) {
|
|
|
108
245
|
...collectTailwindMotionFindings(templateFiles, lintOptions),
|
|
109
246
|
];
|
|
110
247
|
|
|
248
|
+
// Every token a chain can end in: token sources of any kind and installed
|
|
249
|
+
// token packages. Read once, for the chains and for missing tokens.
|
|
250
|
+
const knownDefinitions = chainDefinitions(parsed);
|
|
111
251
|
const report = buildReport({
|
|
112
252
|
baseFontSize: parsed.baseFontSize,
|
|
113
253
|
config: parsed.config,
|
|
@@ -116,11 +256,15 @@ async function createAuditReport(options) {
|
|
|
116
256
|
dir: parsed.dir,
|
|
117
257
|
externalTokenDefinitions: tokenSourceResult.definitions,
|
|
118
258
|
includeMotion: parsed.includeMotion,
|
|
259
|
+
knownTokens: parsed.reportMissingTokens === true
|
|
260
|
+
? knownTokenNames(knownDefinitions, nonAuthoredSkipped, readSource)
|
|
261
|
+
: new Set(),
|
|
119
262
|
linksOutsideRoot: scanFiles.linksOutsideRoot || [],
|
|
120
263
|
motionFindings,
|
|
121
264
|
nonAuthoredFiles: nonAuthoredSkipped.map((file) => ({ file: formatPath(file), reason: nonAuthored.get(file) })),
|
|
122
265
|
parseErrorFindings,
|
|
123
266
|
readSource,
|
|
267
|
+
reportMissingTokens: parsed.reportMissingTokens === true,
|
|
124
268
|
scale,
|
|
125
269
|
scanScope,
|
|
126
270
|
scssFiles: cssResults.scssFiles || 0,
|
|
@@ -133,6 +277,10 @@ async function createAuditReport(options) {
|
|
|
133
277
|
tokenKind: parsed.tokenKind,
|
|
134
278
|
tokenSourceReports: tokenSourceResult.sources,
|
|
135
279
|
tokenSourceWarnings: tokenSourceResult.warnings,
|
|
280
|
+
unauditedFiles: new Set([
|
|
281
|
+
...(cssResults.unauditedFiles || []),
|
|
282
|
+
...parseErrorFindings.map((finding) => path.resolve(process.cwd(), finding.file)),
|
|
283
|
+
]),
|
|
136
284
|
});
|
|
137
285
|
|
|
138
286
|
// The files this run scanned, for the CLI's next-step commands (lint globs,
|
|
@@ -148,7 +296,7 @@ async function createAuditReport(options) {
|
|
|
148
296
|
report.tokenContract.chains = toChainsContract(resolveTokenChains({
|
|
149
297
|
baseFontSize: parsed.baseFontSize,
|
|
150
298
|
declarations,
|
|
151
|
-
references: collectDeclarations({ cssFiles: [], externalDefinitions:
|
|
299
|
+
references: collectDeclarations({ cssFiles: [], externalDefinitions: knownDefinitions }),
|
|
152
300
|
scale: scale.values,
|
|
153
301
|
}));
|
|
154
302
|
report.tokenContract.ladders = toLaddersContract(resolveTokenLadders({
|
|
@@ -163,7 +311,7 @@ async function createAuditReport(options) {
|
|
|
163
311
|
groupScales,
|
|
164
312
|
offScaleFindings: [
|
|
165
313
|
...stylelintFindings.filter((finding) => finding.type === 'off-scale'),
|
|
166
|
-
...collectTailwindFindings(templateFiles,
|
|
314
|
+
...collectTailwindFindings(templateFiles, classOptions),
|
|
167
315
|
],
|
|
168
316
|
scale: scale.values,
|
|
169
317
|
});
|
|
@@ -195,6 +343,31 @@ async function createAuditReport(options) {
|
|
|
195
343
|
return report;
|
|
196
344
|
}
|
|
197
345
|
|
|
346
|
+
/**
|
|
347
|
+
* Token names defined outside the token contract's own definitions: token
|
|
348
|
+
* sources of any kind, installed token packages, and the vendored or built
|
|
349
|
+
* stylesheets the audit skips. A `var()` of one of these is not a missing token.
|
|
350
|
+
*/
|
|
351
|
+
function knownTokenNames(knownDefinitions, skippedCssFiles, readSource) {
|
|
352
|
+
const names = new Set(knownDefinitions.keys());
|
|
353
|
+
const matchesAll = createTokenKindMatcher('all');
|
|
354
|
+
for (const filePath of skippedCssFiles) {
|
|
355
|
+
let text;
|
|
356
|
+
try {
|
|
357
|
+
text = readSource(filePath);
|
|
358
|
+
} catch {
|
|
359
|
+
// Unreadable since the scan (deleted, permissions): this pass reads only what it can.
|
|
360
|
+
continue;
|
|
361
|
+
}
|
|
362
|
+
const definitions = new Map();
|
|
363
|
+
collectTokenDefinitions(text, formatPath(filePath), definitions, matchesAll, 16);
|
|
364
|
+
for (const token of definitions.keys()) {
|
|
365
|
+
names.add(token);
|
|
366
|
+
}
|
|
367
|
+
}
|
|
368
|
+
return names;
|
|
369
|
+
}
|
|
370
|
+
|
|
198
371
|
/**
|
|
199
372
|
* Every custom property a chain can end in: all tokens in the token sources,
|
|
200
373
|
* whatever --token-kind says and whatever name pattern a source sets, plus
|
|
@@ -229,12 +402,28 @@ function classifyNonAuthored(cssFiles, rootDir, readSource) {
|
|
|
229
402
|
return classified;
|
|
230
403
|
}
|
|
231
404
|
|
|
405
|
+
/**
|
|
406
|
+
* The scale class strings are checked against when it differs from the
|
|
407
|
+
* stylesheet scale: Tailwind's default ladder, when the stylesheet scale is the
|
|
408
|
+
* built-in default or the fallback and there are template files to check.
|
|
409
|
+
*/
|
|
410
|
+
function classStringScale(scale, templateFiles, baseFontSize) {
|
|
411
|
+
if (templateFiles.length === 0 || (scale.source !== 'default' && scale.source !== 'fallback')) {
|
|
412
|
+
return null;
|
|
413
|
+
}
|
|
414
|
+
return {
|
|
415
|
+
name: TAILWIND_SCALE_NAME,
|
|
416
|
+
source: 'tailwind-default',
|
|
417
|
+
values: tailwindSpacingLadder(baseFontSize * TAILWIND_SPACING_UNIT_REM),
|
|
418
|
+
};
|
|
419
|
+
}
|
|
420
|
+
|
|
232
421
|
/**
|
|
233
422
|
* One project-level scale for the whole audit, with provenance.
|
|
234
423
|
* "auto": external token sources, then spacing custom properties across the scanned
|
|
235
424
|
* CSS, then the default scale. First source that yields values wins.
|
|
236
425
|
*/
|
|
237
|
-
function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false, readSource = readSourceFromDisk, requested, tokenSourceResult }) {
|
|
426
|
+
function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false, readSource = readSourceFromDisk, requested, tailwindConfigPath = null, tokenSourceResult, warnings = [] }) {
|
|
238
427
|
if (Array.isArray(requested)) {
|
|
239
428
|
return {
|
|
240
429
|
files: [],
|
|
@@ -256,7 +445,18 @@ function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false
|
|
|
256
445
|
}
|
|
257
446
|
}
|
|
258
447
|
|
|
448
|
+
// Configured token sources that gave no scale are a rejection with reasons,
|
|
449
|
+
// as an inferred set is, not a silent fallback (tf-02).
|
|
259
450
|
let rejected = null;
|
|
451
|
+
if (tokenSourceResult.sources.length > 0) {
|
|
452
|
+
const reasons = tokenSourceResult.sources.flatMap((source) => source.warnings || []);
|
|
453
|
+
rejected = {
|
|
454
|
+
files: tokenSourceResult.sources.map((source) => source.file),
|
|
455
|
+
reasons: reasons.length > 0 ? reasons : ['no spacing token carries a length'],
|
|
456
|
+
source: 'token-sources',
|
|
457
|
+
values: [],
|
|
458
|
+
};
|
|
459
|
+
}
|
|
260
460
|
const definitions = new Map();
|
|
261
461
|
const matchesKind = createTokenKindMatcher('spacing');
|
|
262
462
|
for (const filePath of cssFiles) {
|
|
@@ -269,6 +469,7 @@ function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false
|
|
|
269
469
|
try {
|
|
270
470
|
text = readSource(filePath);
|
|
271
471
|
} catch {
|
|
472
|
+
// Unreadable since the scan (deleted, permissions): this pass reads only what it can.
|
|
272
473
|
continue;
|
|
273
474
|
}
|
|
274
475
|
collectTokenDefinitions(text, formatPath(filePath), definitions, matchesKind, baseFontSize);
|
|
@@ -294,7 +495,15 @@ function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false
|
|
|
294
495
|
values,
|
|
295
496
|
};
|
|
296
497
|
}
|
|
297
|
-
rejected = { files: sortedFiles, reasons: assessment.reasons, source: 'scanned-css', values };
|
|
498
|
+
rejected = rejected || { files: sortedFiles, reasons: assessment.reasons, source: 'scanned-css', values };
|
|
499
|
+
}
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
// A Tailwind v3 config, only when one is configured: loading it runs it (tf-06).
|
|
503
|
+
if (tailwindConfigPath && fs.existsSync(path.resolve(process.cwd(), tailwindConfigPath))) {
|
|
504
|
+
const values = scaleFromTailwindConfig(path.resolve(process.cwd(), tailwindConfigPath), baseFontSize, { warnings });
|
|
505
|
+
if (values) {
|
|
506
|
+
return { files: [formatPath(path.resolve(process.cwd(), tailwindConfigPath))], source: 'tailwind', tokenCount: values.length - 1, values };
|
|
298
507
|
}
|
|
299
508
|
}
|
|
300
509
|
|
|
@@ -312,7 +521,16 @@ function resolveAuditScale({ baseFontSize, cssFiles, isNonAuthored = () => false
|
|
|
312
521
|
}
|
|
313
522
|
}
|
|
314
523
|
|
|
315
|
-
|
|
524
|
+
// The fallback the rules use: configs/tailwind falls back to Tailwind's ladder, the rest to DEFAULT_SCALE.
|
|
525
|
+
const tailwind = isTailwindProject(process.cwd());
|
|
526
|
+
return {
|
|
527
|
+
files: [],
|
|
528
|
+
preset: tailwind ? 'tailwind' : 'rhythmic-4',
|
|
529
|
+
...(rejected ? { rejected } : {}),
|
|
530
|
+
source: 'fallback',
|
|
531
|
+
tokenCount: 0,
|
|
532
|
+
values: tailwind ? tailwindSpacingLadder(baseFontSize * TAILWIND_SPACING_UNIT_REM) : DEFAULT_SCALE,
|
|
533
|
+
};
|
|
316
534
|
}
|
|
317
535
|
|
|
318
536
|
function normalizeCreateAuditOptions(rawOptions) {
|
|
@@ -348,4 +566,6 @@ function normalizeCreateAuditOptions(rawOptions) {
|
|
|
348
566
|
module.exports = {
|
|
349
567
|
createAuditReport,
|
|
350
568
|
normalizeCreateAuditOptions,
|
|
569
|
+
prepareAuditRun,
|
|
570
|
+
tokenScaleSources,
|
|
351
571
|
};
|
package/src/audit/scan/files.js
CHANGED
|
@@ -59,6 +59,7 @@ function walkFiles(rootDir, ignorePatterns = []) {
|
|
|
59
59
|
try {
|
|
60
60
|
kind = fs.statSync(fullPath);
|
|
61
61
|
} catch {
|
|
62
|
+
// A dangling symbolic link: nothing to scan.
|
|
62
63
|
continue;
|
|
63
64
|
}
|
|
64
65
|
}
|
|
@@ -123,6 +124,7 @@ function realPathOf(filePath) {
|
|
|
123
124
|
try {
|
|
124
125
|
return fs.realpathSync(filePath);
|
|
125
126
|
} catch {
|
|
127
|
+
// A path that cannot be resolved has no real path.
|
|
126
128
|
return null;
|
|
127
129
|
}
|
|
128
130
|
}
|
|
@@ -247,6 +249,7 @@ function isFileOnDisk(filePath) {
|
|
|
247
249
|
try {
|
|
248
250
|
return fs.statSync(filePath).isFile();
|
|
249
251
|
} catch {
|
|
252
|
+
// Absent or unreadable: not a file.
|
|
250
253
|
return false;
|
|
251
254
|
}
|
|
252
255
|
}
|
|
@@ -255,6 +258,7 @@ function isSymbolicLink(filePath) {
|
|
|
255
258
|
try {
|
|
256
259
|
return fs.lstatSync(filePath).isSymbolicLink();
|
|
257
260
|
} catch {
|
|
261
|
+
// Absent: not a link.
|
|
258
262
|
return false;
|
|
259
263
|
}
|
|
260
264
|
}
|
|
@@ -351,6 +355,7 @@ function findGitTopLevel(dir) {
|
|
|
351
355
|
}).replace(/\r?\n$/, '');
|
|
352
356
|
return output ? path.resolve(output) : null;
|
|
353
357
|
} catch {
|
|
358
|
+
// Not a git repository, or no git: there is no repository root.
|
|
354
359
|
return null;
|
|
355
360
|
}
|
|
356
361
|
}
|