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.
Files changed (55) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +3 -3
  3. package/SECURITY.md +2 -1
  4. package/agents/claude-code/SKILL.md +1 -1
  5. package/package.json +1 -1
  6. package/src/audit/args.js +30 -8
  7. package/src/audit/baseline.js +38 -4
  8. package/src/audit/codemod.js +4 -2
  9. package/src/audit/config.js +7 -0
  10. package/src/audit/contract.js +124 -14
  11. package/src/audit/next-steps.js +3 -1
  12. package/src/audit/non-authored.js +1 -0
  13. package/src/audit/render-github.js +16 -11
  14. package/src/audit/render-markdown.js +8 -2
  15. package/src/audit/render-text.js +41 -2
  16. package/src/audit/render-utils.js +14 -0
  17. package/src/audit/report.js +230 -10
  18. package/src/audit/scan/files.js +14 -5
  19. package/src/audit/scan/stylesheets.js +48 -53
  20. package/src/audit/scan/templates.js +2 -0
  21. package/src/audit/shared.js +7 -1
  22. package/src/audit/token-chains.js +1 -0
  23. package/src/cli/audit.js +2 -2
  24. package/src/cli/doctor.js +853 -237
  25. package/src/cli/first-run.js +210 -0
  26. package/src/cli/index.js +25 -1
  27. package/src/cli/index.mjs +3 -0
  28. package/src/cli/init.js +42 -13
  29. package/src/cli/quickstart.js +53 -102
  30. package/src/cli/scale.js +223 -0
  31. package/src/configs/recommended.js +3 -1
  32. package/src/configs/strict.js +3 -1
  33. package/src/configs/tailwind.js +15 -0
  34. package/src/core/decisions.js +18 -5
  35. package/src/core/fs-cache.js +1 -0
  36. package/src/core/options.js +2 -1
  37. package/src/core/scale-inference.js +72 -52
  38. package/src/core/tailwind-class-analysis.js +56 -13
  39. package/src/core/token-index.js +55 -14
  40. package/src/core/token-map.js +138 -29
  41. package/src/core/token-sources.js +461 -40
  42. package/src/core/value-nodes.js +4 -2
  43. package/src/eslint/class-context.js +330 -0
  44. package/src/eslint/literal-spans.js +5 -4
  45. package/src/eslint/rules/tailwind-class-use-scale.js +30 -9
  46. package/src/presets/default-scale.js +42 -0
  47. package/src/presets/scales.js +6 -1
  48. package/src/rules/no-offscale-transform/index.js +17 -5
  49. package/src/rules/prefer-token/index.js +51 -15
  50. package/src/rules/use-scale/index.js +7 -4
  51. package/types/__checks__/consumer.ts +17 -0
  52. package/types/__checks__/eslint-config.ts +5 -0
  53. package/types/audit.d.ts +40 -3
  54. package/types/cli.d.ts +77 -1
  55. 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; each type stops at the cap with a
10
- * notice that says how many were left out. Arrays are walked, not spread:
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.newFindingsCount} new.`] : []),
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
- const annotated = baseline ? baseline.newFindings || [] : findings;
38
- const level = baseline ? 'error' : 'warning';
39
- const rest = [];
40
- for (const finding of annotated) {
41
- rest.push(annotation(level, finding, `${baseline ? 'New since the baseline: ' : ''}${finding.text || ''}`));
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.newFindingsCount} new.`, ''] : []),
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) {
@@ -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
- const rejected = report.scale.rejected ? ` (${report.scale.rejected.source} rejected: ${report.scale.rejected.reasons.join(', ')})` : '';
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.newFindingsCount} new`);
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,
@@ -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
- async function createAuditReport(options) {
37
- const parsed = normalizeCreateAuditOptions(options);
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 { scanScope, templateFiles } = scanFiles;
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: (file) => nonAuthored.has(file),
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, lintOptions),
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: chainDefinitions(parsed) }),
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, lintOptions),
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
- return { files: [], ...(rejected ? { rejected } : {}), source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
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
  };
@@ -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
- return fs.realpathSync(filePath);
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 topLevel = runGit(rootDir, ['rev-parse', '--show-toplevel']).replace(/\r?\n$/, '');
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
- const fileRealPath = realPathOf(fullPath) || fullPath;
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
  }