stylelint-plugin-rhythmguard 3.19.0 → 3.20.1
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 +43 -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 +38 -4
- package/src/audit/codemod.js +4 -2
- 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 +14 -5
- 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 +42 -13
- 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 +138 -29
- 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
|
}
|
|
@@ -121,8 +122,11 @@ function preferPath(candidate, current) {
|
|
|
121
122
|
|
|
122
123
|
function realPathOf(filePath) {
|
|
123
124
|
try {
|
|
124
|
-
|
|
125
|
+
// The native call expands Windows 8.3 short names (C:\Users\RUNNER~1),
|
|
126
|
+
// which git never prints; the JS one does not, and nothing then matched (#174).
|
|
127
|
+
return fs.realpathSync.native(filePath);
|
|
125
128
|
} catch {
|
|
129
|
+
// A path that cannot be resolved has no real path.
|
|
126
130
|
return null;
|
|
127
131
|
}
|
|
128
132
|
}
|
|
@@ -143,14 +147,15 @@ function getScanFiles(rootDir, ignorePatterns, parsed) {
|
|
|
143
147
|
function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
|
|
144
148
|
// Git runs in the scanned directory, so the repository is the one that holds
|
|
145
149
|
// the files, whichever directory the command was started from.
|
|
146
|
-
const
|
|
150
|
+
const gitTopLevel = path.resolve(runGit(rootDir, ['rev-parse', '--show-toplevel']).replace(/\r?\n$/, ''));
|
|
151
|
+
const topLevel = realPathOf(gitTopLevel) || gitTopLevel;
|
|
147
152
|
const changed = parsed.staged
|
|
148
153
|
? listStagedFiles(rootDir)
|
|
149
154
|
: listFilesChangedSince(rootDir, parsed.since);
|
|
150
155
|
|
|
151
156
|
// git reports the top level with symlinks resolved (/private/var on macOS);
|
|
152
157
|
// compare in that form, then name files under the directory as it was given.
|
|
153
|
-
const realRootDir = fs.realpathSync(rootDir);
|
|
158
|
+
const realRootDir = fs.realpathSync.native(rootDir);
|
|
154
159
|
const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
|
|
155
160
|
const seen = new Set();
|
|
156
161
|
const found = [];
|
|
@@ -187,7 +192,8 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
|
|
|
187
192
|
}
|
|
188
193
|
|
|
189
194
|
seen.add(fullPath);
|
|
190
|
-
|
|
195
|
+
// A staged file gone from the working tree has no real path on disk; git's own path is the real form.
|
|
196
|
+
const fileRealPath = realPathOf(fullPath) || realPath;
|
|
191
197
|
// A link that resolves outside the scanned directory is not followed (#289).
|
|
192
198
|
if (!isPathInside(realRootDir, fileRealPath)) {
|
|
193
199
|
linksOutsideRoot.push(relativePath);
|
|
@@ -247,6 +253,7 @@ function isFileOnDisk(filePath) {
|
|
|
247
253
|
try {
|
|
248
254
|
return fs.statSync(filePath).isFile();
|
|
249
255
|
} catch {
|
|
256
|
+
// Absent or unreadable: not a file.
|
|
250
257
|
return false;
|
|
251
258
|
}
|
|
252
259
|
}
|
|
@@ -255,6 +262,7 @@ function isSymbolicLink(filePath) {
|
|
|
255
262
|
try {
|
|
256
263
|
return fs.lstatSync(filePath).isSymbolicLink();
|
|
257
264
|
} catch {
|
|
265
|
+
// Absent: not a link.
|
|
258
266
|
return false;
|
|
259
267
|
}
|
|
260
268
|
}
|
|
@@ -349,8 +357,9 @@ function findGitTopLevel(dir) {
|
|
|
349
357
|
encoding: 'utf8',
|
|
350
358
|
stdio: ['ignore', 'pipe', 'ignore'],
|
|
351
359
|
}).replace(/\r?\n$/, '');
|
|
352
|
-
return output ? path.resolve(output) : null;
|
|
360
|
+
return output ? realPathOf(path.resolve(output)) || path.resolve(output) : null;
|
|
353
361
|
} catch {
|
|
362
|
+
// Not a git repository, or no git: there is no repository root.
|
|
354
363
|
return null;
|
|
355
364
|
}
|
|
356
365
|
}
|