stylelint-plugin-rhythmguard 3.12.0 → 3.14.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.
Files changed (48) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +1 -1
  3. package/package.json +23 -1
  4. package/src/audit/args.js +23 -4
  5. package/src/audit/baseline.js +15 -2
  6. package/src/audit/codemod.js +56 -5
  7. package/src/audit/config.js +2 -1
  8. package/src/audit/contract.js +3 -0
  9. package/src/audit/decisions.js +45 -16
  10. package/src/audit/render-markdown.js +22 -21
  11. package/src/audit/render-text.js +4 -0
  12. package/src/audit/render-utils.js +28 -1
  13. package/src/audit/report.js +16 -2
  14. package/src/audit/scan/files.js +139 -30
  15. package/src/audit/token-chains.js +4 -1
  16. package/src/audit/token-ladders.js +23 -2
  17. package/src/cli/doctor.js +58 -6
  18. package/src/cli/fix.js +7 -6
  19. package/src/cli/index.js +2 -2
  20. package/src/cli/init.js +41 -5
  21. package/src/cli/quickstart.js +46 -8
  22. package/src/configs/embed.js +2 -0
  23. package/src/configs/motion.js +1 -0
  24. package/src/configs/recommended.js +1 -0
  25. package/src/configs/strict.js +1 -0
  26. package/src/configs/tailwind.js +1 -0
  27. package/src/core/decisions.js +2 -1
  28. package/src/core/json.js +25 -0
  29. package/src/core/length.js +11 -0
  30. package/src/core/options.js +39 -20
  31. package/src/core/scale-inference.js +78 -23
  32. package/src/core/tailwind-class-analysis.js +3 -2
  33. package/src/core/token-map.js +2 -1
  34. package/src/core/token-sources.js +143 -14
  35. package/src/eslint/index.js +14 -8
  36. package/src/eslint/rules/tailwind-class-use-motion-scale.js +1 -0
  37. package/src/eslint/rules/tailwind-class-use-scale.js +1 -0
  38. package/src/rules/no-offscale-transform/index.js +58 -53
  39. package/src/rules/prefer-token/index.js +31 -46
  40. package/src/rules/use-motion-scale/index.js +14 -1
  41. package/src/rules/use-scale/index.js +75 -102
  42. package/src/rules/validate.js +13 -4
  43. package/types/__checks__/consumer.ts +20 -1
  44. package/types/__checks__/eslint-config.ts +8 -0
  45. package/types/__checks__/shipped-configs.ts +96 -0
  46. package/types/audit.d.ts +103 -16
  47. package/types/index.d.ts +15 -0
  48. package/types/shared.d.ts +126 -20
@@ -1,7 +1,7 @@
1
1
  'use strict';
2
2
 
3
3
  const { sortCountMap } = require('./contract');
4
- const { escapeMarkdown } = require('./render-utils');
4
+ const { escapeMarkdown, markdownCode, tableCode } = require('./render-utils');
5
5
 
6
6
  function describeScaleSource(scale) {
7
7
  if (scale.rejected) {
@@ -17,7 +17,7 @@ function renderMarkdown(report) {
17
17
  '# Rhythmguard Design-System Audit',
18
18
  '',
19
19
  ...(report.baseline ? [`**Since baseline:** ${report.baseline.resolvedFindingsCount} resolved, ${report.baseline.newFindingsCount} new.`, ''] : []),
20
- `Directory: \`${report.directory}\``,
20
+ `Directory: ${markdownCode(report.directory)}`,
21
21
  '',
22
22
  '## Summary',
23
23
  '',
@@ -28,6 +28,7 @@ function renderMarkdown(report) {
28
28
  ...(report.scanned && report.scanned.scssFiles > 0 ? [`| SCSS files scanned | ${report.scanned.scssFiles - report.scanned.scssSkipped} |`] : []),
29
29
  ...(report.scanned && report.scanned.scssSkipped > 0 ? [`| SCSS files skipped (install postcss-scss) | ${report.scanned.scssSkipped} |`] : []),
30
30
  ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [`| Stylesheets ignored by .stylelintignore (not audited) | ${report.scanned.stylelintIgnored} |`] : []),
31
+ ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [`| Symbolic links not followed (they point outside the scanned directory) | ${report.scanned.linksOutsideRoot} |`] : []),
31
32
  ...(parseErrors(report).length > 0 ? [`| Stylesheets that failed to parse (not audited) | ${parseErrors(report).length} |`] : []),
32
33
  `| Files with issues | ${report.filesWithIssues} |`,
33
34
  `| Total findings | ${report.totalWarnings} |`,
@@ -36,7 +37,7 @@ function renderMarkdown(report) {
36
37
 
37
38
  if (report.scale) {
38
39
  lines.push(`| Scale | ${report.scale.values.join(', ')} |`);
39
- lines.push(`| Scale source | ${describeScaleSource(report.scale)} |`);
40
+ lines.push(`| Scale source | ${escapeMarkdown(describeScaleSource(report.scale))} |`);
40
41
  }
41
42
 
42
43
  if (report.decisions) {
@@ -66,7 +67,7 @@ function renderMarkdown(report) {
66
67
  lines.push('| File | Findings |');
67
68
  lines.push('| --- | ---: |');
68
69
  for (const { file, count } of report.topAffectedFiles) {
69
- lines.push(`| \`${escapeMarkdown(file)}\` | ${count} |`);
70
+ lines.push(`| ${tableCode(file)} | ${count} |`);
70
71
  }
71
72
  lines.push('');
72
73
  }
@@ -77,7 +78,7 @@ function renderMarkdown(report) {
77
78
  lines.push('| File | Class | Suggested class |');
78
79
  lines.push('| --- | --- | --- |');
79
80
  for (const finding of report.findings.tailwind.slice(0, 10)) {
80
- lines.push(`| \`${escapeMarkdown(`${finding.file}:${finding.line}`)}\` | \`${escapeMarkdown(finding.token)}\` | \`${escapeMarkdown(finding.fixedToken || 'n/a')}\` |`);
81
+ lines.push(`| ${tableCode(`${finding.file}:${finding.line}`)} | ${tableCode(finding.token)} | ${tableCode(finding.fixedToken || 'n/a')} |`);
81
82
  }
82
83
  lines.push('');
83
84
  }
@@ -115,7 +116,7 @@ function appendParseErrorsMarkdown(lines, report) {
115
116
  lines.push('| File | Error |');
116
117
  lines.push('| --- | --- |');
117
118
  for (const finding of errors) {
118
- lines.push(`| \`${escapeMarkdown(`${finding.file}:${finding.line}:${finding.column}`)}\` | ${escapeMarkdown(finding.text)} |`);
119
+ lines.push(`| ${tableCode(`${finding.file}:${finding.line}:${finding.column}`)} | ${escapeMarkdown(finding.text)} |`);
119
120
  }
120
121
  lines.push('');
121
122
  }
@@ -138,8 +139,8 @@ function appendTokenChainsMarkdown(lines, chains) {
138
139
  for (const entry of chains.entries.slice(0, 50)) {
139
140
  const detail = entry.reason
140
141
  ? entry.reason
141
- : entry.terminals.map((terminal) => `\`${terminal}\``).join(', ');
142
- lines.push(`| \`${escapeMarkdown(entry.token)}\` | ${entry.outcome} | ${detail}${entry.via.length > 0 ? ` via ${entry.via.map((name) => `\`${name}\``).join(' → ')}` : ''} |`);
142
+ : entry.terminals.map((terminal) => tableCode(terminal)).join(', ');
143
+ lines.push(`| ${tableCode(entry.token)} | ${entry.outcome} | ${detail}${entry.via.length > 0 ? ` via ${entry.via.map((name) => tableCode(name)).join(' → ')}` : ''} |`);
143
144
  }
144
145
  lines.push('');
145
146
  }
@@ -164,16 +165,16 @@ function appendTokenLaddersMarkdown(lines, ladders) {
164
165
  const flagged = new Map();
165
166
  for (const problem of entry.problems) {
166
167
  const where = problem.end === 'both' ? '' : ` at ${problem.end}`;
167
- const note = `${LADDER_PROBLEM_TEXT[problem.type]}${where} with \`${problem.tokens[0]}\``;
168
+ const note = `${LADDER_PROBLEM_TEXT[problem.type]}${where} with ${tableCode(problem.tokens[0])}`;
168
169
  flagged.set(problem.tokens[1], [...(flagged.get(problem.tokens[1]) || []), note]);
169
170
  }
170
- const aliasNote = entry.aliases ? ` (also aliased as ${entry.aliases.map((alias) => `\`${escapeMarkdown(alias)}\``).join(', ')})` : '';
171
- lines.push(`**\`${escapeMarkdown(entry.prefix)}\`**${aliasNote}`);
171
+ const aliasNote = entry.aliases ? ` (also aliased as ${entry.aliases.map((alias) => markdownCode(alias)).join(', ')})` : '';
172
+ lines.push(`**${markdownCode(entry.prefix)}**${aliasNote}`);
172
173
  lines.push('');
173
174
  lines.push('| Token | Min | Max | Problem |');
174
175
  lines.push('| --- | --- | --- | --- |');
175
176
  for (const step of entry.steps) {
176
- lines.push(`| \`${escapeMarkdown(step.token)}\` | ${step.min || 'fluid'} | ${step.max || 'fluid'} | ${(flagged.get(step.token) || []).join('; ')} |`);
177
+ lines.push(`| ${tableCode(step.token)} | ${step.min || 'fluid'} | ${step.max || 'fluid'} | ${(flagged.get(step.token) || []).join('; ')} |`);
177
178
  }
178
179
  lines.push('');
179
180
  }
@@ -208,7 +209,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
208
209
  lines.push('| File | Format | Tokens | Warnings |');
209
210
  lines.push('| --- | --- | ---: | --- |');
210
211
  for (const source of sources.slice(0, 10)) {
211
- lines.push(`| \`${escapeMarkdown(source.file)}\` | \`${source.format}\` | ${source.tokenCount} | \`${escapeMarkdown(source.warnings.join('; ') || 'none')}\` |`);
212
+ lines.push(`| ${tableCode(source.file)} | ${tableCode(source.format)} | ${source.tokenCount} | ${tableCode(source.warnings.join('; ') || 'none')} |`);
212
213
  }
213
214
  lines.push('');
214
215
  }
@@ -219,7 +220,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
219
220
  lines.push('| Token | Files |');
220
221
  lines.push('| --- | --- |');
221
222
  for (const entry of missingTokens.slice(0, 10)) {
222
- lines.push(`| \`${escapeMarkdown(entry.token)}\` | \`${escapeMarkdown(entry.files.join(', '))}\` |`);
223
+ lines.push(`| ${tableCode(entry.token)} | ${tableCode(entry.files.join(', '))} |`);
223
224
  }
224
225
  lines.push('');
225
226
  }
@@ -230,7 +231,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
230
231
  lines.push('| Token | Value |');
231
232
  lines.push('| --- | --- |');
232
233
  for (const entry of unusedTokens.slice(0, 10)) {
233
- lines.push(`| \`${escapeMarkdown(entry.token)}\` | \`${escapeMarkdown((entry.values || []).join(', ') || 'n/a')}\` |`);
234
+ lines.push(`| ${tableCode(entry.token)} | ${tableCode((entry.values || []).join(', ') || 'n/a')} |`);
234
235
  }
235
236
  lines.push('');
236
237
  }
@@ -241,7 +242,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
241
242
  lines.push('| Value | Count | Files |');
242
243
  lines.push('| --- | ---: | --- |');
243
244
  for (const entry of rawValueCandidates.slice(0, 10)) {
244
- lines.push(`| \`${escapeMarkdown(entry.value)}\` | ${entry.count} | \`${escapeMarkdown(entry.files.join(', '))}\` |`);
245
+ lines.push(`| ${tableCode(entry.value)} | ${entry.count} | ${tableCode(entry.files.join(', '))} |`);
245
246
  }
246
247
  lines.push('');
247
248
  }
@@ -252,7 +253,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
252
253
  lines.push('| Value | Count | Tokens |');
253
254
  lines.push('| --- | ---: | --- |');
254
255
  for (const entry of rawValueMatches.slice(0, 10)) {
255
- lines.push(`| \`${escapeMarkdown(entry.value)}\` | ${entry.count} | \`${escapeMarkdown(entry.tokens.join(', '))}\` |`);
256
+ lines.push(`| ${tableCode(entry.value)} | ${entry.count} | ${tableCode(entry.tokens.join(', '))} |`);
256
257
  }
257
258
  lines.push('');
258
259
  }
@@ -263,7 +264,7 @@ function appendTokenContractMarkdown(lines, tokenContract) {
263
264
  lines.push('| Value | Tokens |');
264
265
  lines.push('| --- | --- |');
265
266
  for (const entry of conflictingTokens.slice(0, 10)) {
266
- lines.push(`| \`${escapeMarkdown(entry.value)}\` | \`${escapeMarkdown(entry.tokens.join(', '))}\` |`);
267
+ lines.push(`| ${tableCode(entry.value)} | ${tableCode(entry.tokens.join(', '))} |`);
267
268
  }
268
269
  lines.push('');
269
270
  }
@@ -290,13 +291,13 @@ function appendBaselineMarkdown(lines, report) {
290
291
  lines.push('| New finding | Location |');
291
292
  lines.push('| --- | --- |');
292
293
  for (const finding of report.baseline.newFindings.slice(0, 10)) {
293
- lines.push(`| \`${escapeMarkdown(finding.text)}\` | \`${escapeMarkdown(`${finding.file}:${finding.line}`)}\` |`);
294
+ lines.push(`| ${tableCode(finding.text)} | ${tableCode(`${finding.file}:${finding.line}`)} |`);
294
295
  }
295
296
  lines.push('');
296
297
  }
297
298
 
298
299
  if (report.baselineWritten) {
299
- lines.push(`Baseline written: \`${escapeMarkdown(report.baselineWritten.file)}\``);
300
+ lines.push(`Baseline written: ${markdownCode(report.baselineWritten.file)}`);
300
301
  lines.push('');
301
302
  }
302
303
  }
@@ -313,7 +314,7 @@ function appendMarkdownCounts(lines, title, counts, label = 'Value') {
313
314
  lines.push(`| ${label} | Count |`);
314
315
  lines.push('| --- | ---: |');
315
316
  for (const [value, count] of entries) {
316
- lines.push(`| \`${escapeMarkdown(value)}\` | ${count} |`);
317
+ lines.push(`| ${tableCode(value)} | ${count} |`);
317
318
  }
318
319
  lines.push('');
319
320
  }
@@ -22,6 +22,7 @@ function renderText(report) {
22
22
  ...(report.scanned && report.scanned.scssFiles > 0 ? [` SCSS files scanned ${String(report.scanned.scssFiles - report.scanned.scssSkipped).padStart(4)}`] : []),
23
23
  ...(report.scanned && report.scanned.scssSkipped > 0 ? [` SCSS files skipped ${String(report.scanned.scssSkipped).padStart(4)} (install postcss-scss to audit them)`] : []),
24
24
  ...(report.scanned && report.scanned.stylelintIgnored > 0 ? [` Ignored by .stylelintignore ${String(report.scanned.stylelintIgnored).padStart(4)} (not audited)`] : []),
25
+ ...(report.scanned && report.scanned.linksOutsideRoot > 0 ? [` Links not followed ${String(report.scanned.linksOutsideRoot).padStart(4)} (they point outside the scanned directory)`] : []),
25
26
  ...(parseErrors(report).length > 0 ? [` Parse errors ${String(parseErrors(report).length).padStart(4)} (not audited)`] : []),
26
27
  ` Files with issues ${String(report.filesWithIssues).padStart(4)}`,
27
28
  ` Scale cleanliness ${scoreBar(report.scaleCleanliness)} ${report.scaleCleanliness}%`,
@@ -128,6 +129,9 @@ function appendTokenContractText(lines, tokenContract) {
128
129
  for (const source of sources.slice(0, 5)) {
129
130
  const warningSuffix = source.warnings.length > 0 ? ' (warning)' : '';
130
131
  lines.push(` ${truncate(source.file, 42)} ${source.tokenCount}${warningSuffix}`);
132
+ for (const warning of source.warnings) {
133
+ lines.push(` ! ${warning}`);
134
+ }
131
135
  }
132
136
  }
133
137
 
@@ -20,8 +20,33 @@ function truncate(value, maxLength) {
20
20
  return `…${value.slice(value.length - maxLength + 1)}`;
21
21
  }
22
22
 
23
+ /** Plain Markdown text, safe in a table cell: pipes and backticks escaped, one line. */
23
24
  function escapeMarkdown(value) {
24
- return String(value).replace(/\|/g, '\\|').replace(/`/g, '\\`');
25
+ return String(value).replace(/\r?\n/g, ' ').replace(/\|/g, '\\|').replace(/`/g, '\\`');
26
+ }
27
+
28
+ /**
29
+ * A Markdown code span holding `value` verbatim. A backslash does not escape
30
+ * anything inside a code span, so a backtick in the value is kept by a fence
31
+ * one backtick longer than the longest run in it, padded with a space when the
32
+ * value starts or ends with a backtick (CommonMark strips one space from each
33
+ * side). In a table cell a pipe is still escaped, as GFM reads `\|` before it
34
+ * finds code spans (#285).
35
+ */
36
+ function markdownCode(value, { table = false } = {}) {
37
+ let text = String(value).replace(/\r?\n/g, ' ');
38
+ if (table) {
39
+ text = text.replace(/\|/g, '\\|');
40
+ }
41
+ const longestRun = Math.max(0, ...(text.match(/`+/g) || []).map((run) => run.length));
42
+ const fence = '`'.repeat(longestRun + 1);
43
+ const pad = /^`|`$/.test(text) || (/^ /.test(text) && / $/.test(text) && text.trim() !== '') ? ' ' : '';
44
+ return `${fence}${pad}${text}${pad}${fence}`;
45
+ }
46
+
47
+ /** markdownCode for a table cell. */
48
+ function tableCode(value) {
49
+ return markdownCode(value, { table: true });
25
50
  }
26
51
 
27
52
  function escapeHtml(value) {
@@ -36,6 +61,8 @@ module.exports = {
36
61
  escapeHtml,
37
62
  escapeMarkdown,
38
63
  histBar,
64
+ markdownCode,
65
+ tableCode,
39
66
  scoreBar,
40
67
  truncate,
41
68
  };
@@ -24,6 +24,7 @@ const {
24
24
  inferScaleFromDefinitions,
25
25
  scaleFromDefinitions,
26
26
  } = require('../core/scale-inference');
27
+ const { buildGroupScales } = require('../core/options');
27
28
  const { applyDecisions, buildDecisionPlan } = require('./decisions');
28
29
  const { collectDeclarations, resolveTokenChains, toChainsContract } = require('./token-chains');
29
30
  const { resolveTokenLadders, toLaddersContract } = require('./token-ladders');
@@ -42,10 +43,12 @@ async function createAuditReport(options) {
42
43
  // A --staged run reads each changed file as the index holds it.
43
44
  const readSource = scanFiles.readSource || readSourceFromDisk;
44
45
 
46
+ // A configured source that gives nothing is a warning, not a silent fallback (issue #163).
45
47
  const tokenSourceResult = parseTokenSources({
46
48
  baseFontSize: parsed.baseFontSize,
47
49
  sources: parsed.tokenSources,
48
50
  tokenKind: parsed.tokenKind,
51
+ warnWhenEmpty: true,
49
52
  });
50
53
 
51
54
  // The spacing scale always reads spacing tokens; --token-kind shapes the token contract only (issue #260).
@@ -53,11 +56,15 @@ async function createAuditReport(options) {
53
56
  ? tokenSourceResult
54
57
  : parseTokenSources({ baseFontSize: parsed.baseFontSize, sources: parsed.tokenSources, tokenKind: 'spacing' });
55
58
 
59
+ // A spacing scale in audit.scales is the one use-scale checks spacing
60
+ // against, so it is the scale the report names and prefer-token reads (#283).
61
+ const groupScales = buildGroupScales(parsed.scales);
62
+ const spacingOverride = groupScales.spacing && Array.isArray(groupScales.spacing.scale) ? groupScales.spacing.scale : null;
56
63
  const scale = resolveAuditScale({
57
64
  baseFontSize: parsed.baseFontSize,
58
65
  cssFiles,
59
66
  readSource,
60
- requested: parsed.scale,
67
+ requested: spacingOverride || parsed.scale,
61
68
  tokenSourceResult: spacingSourceResult,
62
69
  });
63
70
 
@@ -96,6 +103,7 @@ async function createAuditReport(options) {
96
103
  dir: parsed.dir,
97
104
  externalTokenDefinitions: tokenSourceResult.definitions,
98
105
  includeMotion: parsed.includeMotion,
106
+ linksOutsideRoot: scanFiles.linksOutsideRoot || [],
99
107
  motionFindings,
100
108
  parseErrorFindings,
101
109
  readSource,
@@ -133,6 +141,7 @@ async function createAuditReport(options) {
133
141
  report.decisionPlan = buildDecisionPlan({
134
142
  baseFontSize: parsed.baseFontSize,
135
143
  decisions: parsed.decisions || [],
144
+ groupScales,
136
145
  offScaleFindings: [
137
146
  ...stylelintFindings.filter((finding) => finding.type === 'off-scale'),
138
147
  ...collectTailwindFindings(templateFiles, lintOptions),
@@ -269,7 +278,12 @@ function resolveAuditScale({ baseFontSize, cssFiles, readSource = readSourceFrom
269
278
  return { files: [], ...(rejected ? { rejected } : {}), source: 'fallback', tokenCount: 0, values: DEFAULT_SCALE };
270
279
  }
271
280
 
272
- function normalizeCreateAuditOptions(options = {}) {
281
+ function normalizeCreateAuditOptions(rawOptions) {
282
+ // A key set to undefined is an omitted key: it neither replaces a default nor
283
+ // counts as given, so the config file still applies to it (#284).
284
+ const options = Object.fromEntries(
285
+ Object.entries(rawOptions || {}).filter(([, value]) => value !== undefined),
286
+ );
273
287
  const parsed = {
274
288
  ...createDefaultAuditOptions(),
275
289
  ...options,
@@ -30,37 +30,101 @@ function assertDirectory(dir) {
30
30
  return resolvedDir;
31
31
  }
32
32
 
33
+ /**
34
+ * Every stylesheet and template under `rootDir`. Symbolic links are followed
35
+ * when they resolve inside `rootDir`: a linked directory is walked unless it
36
+ * is one of the directories being walked already (a cycle), and a file
37
+ * reached by more than one path is scanned once, under its own path when the
38
+ * walk reaches it directly, else under the first linked path in sorted order
39
+ * (#289). A link that resolves outside `rootDir` is never followed, so the
40
+ * audit cannot read, and `rhythmguard fix` cannot rewrite, files outside the
41
+ * directory it was given; such links are returned in `linksOutsideRoot`
42
+ * (root-relative). A broken link is skipped.
43
+ */
33
44
  function walkFiles(rootDir, ignorePatterns = []) {
34
- const cssFiles = [];
35
- const templateFiles = [];
36
45
  const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
46
+ const realRoot = realPathOf(rootDir) || rootDir;
47
+ const found = [];
48
+ const linksOutsideRoot = [];
37
49
 
38
- function walk(currentDir) {
50
+ // `realDir` is where `currentDir` really is. Below a plain directory that is
51
+ // its real path plus the entry name, so only a link costs a realpath call.
52
+ function walk(currentDir, realDir, ancestors, viaLink) {
39
53
  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
40
54
  const fullPath = path.join(currentDir, entry.name);
41
55
  const relativePath = toPosixRelativePath(rootDir, fullPath);
56
+ const link = entry.isSymbolicLink();
57
+ let kind = entry;
58
+ if (link) {
59
+ try {
60
+ kind = fs.statSync(fullPath);
61
+ } catch {
62
+ continue;
63
+ }
64
+ }
42
65
 
43
- if (shouldIgnorePath(relativePath, entry, ignoreMatchers)) {
66
+ if (shouldIgnorePath(relativePath, { isDirectory: () => kind.isDirectory(), name: entry.name }, ignoreMatchers)) {
44
67
  continue;
45
68
  }
46
69
 
47
- if (entry.isDirectory()) {
48
- walk(fullPath);
70
+ const realPath = link ? realPathOf(fullPath) : path.join(realDir, entry.name);
71
+ if (!realPath) {
72
+ continue;
73
+ }
74
+ if (link && !isPathInside(realRoot, realPath)) {
75
+ if (kind.isDirectory() || isCssFile(fullPath) || isTemplateFile(fullPath)) {
76
+ linksOutsideRoot.push(relativePath);
77
+ }
49
78
  continue;
50
79
  }
51
80
 
52
- if (entry.isFile()) {
53
- if (isCssFile(fullPath)) {
54
- cssFiles.push(fullPath);
55
- } else if (isTemplateFile(fullPath)) {
56
- templateFiles.push(fullPath);
81
+ if (kind.isDirectory()) {
82
+ if (!ancestors.has(realPath)) {
83
+ walk(fullPath, realPath, new Set([...ancestors, realPath]), viaLink || link);
57
84
  }
85
+ continue;
86
+ }
87
+
88
+ if (kind.isFile() && (isCssFile(fullPath) || isTemplateFile(fullPath))) {
89
+ found.push({ fullPath, realPath, viaLink: viaLink || link });
58
90
  }
59
91
  }
60
92
  }
61
93
 
62
- walk(rootDir);
63
- return { cssFiles, templateFiles };
94
+ walk(rootDir, realRoot, new Set([realRoot]), false);
95
+
96
+ const chosen = new Map();
97
+ for (const file of found) {
98
+ const current = chosen.get(file.realPath);
99
+ if (!current || preferPath(file, current)) {
100
+ chosen.set(file.realPath, file);
101
+ }
102
+ }
103
+ const cssFiles = [];
104
+ const templateFiles = [];
105
+ for (const file of found) {
106
+ if (chosen.get(file.realPath) !== file) {
107
+ continue;
108
+ }
109
+ (isCssFile(file.fullPath) ? cssFiles : templateFiles).push(file.fullPath);
110
+ }
111
+ return { cssFiles, linksOutsideRoot: linksOutsideRoot.sort(), templateFiles };
112
+ }
113
+
114
+ // A direct path beats a linked one; between two of a kind, the first in sorted order.
115
+ function preferPath(candidate, current) {
116
+ if (candidate.viaLink !== current.viaLink) {
117
+ return !candidate.viaLink;
118
+ }
119
+ return candidate.fullPath < current.fullPath;
120
+ }
121
+
122
+ function realPathOf(filePath) {
123
+ try {
124
+ return fs.realpathSync(filePath);
125
+ } catch {
126
+ return null;
127
+ }
64
128
  }
65
129
 
66
130
  function getScanFiles(rootDir, ignorePatterns, parsed) {
@@ -87,11 +151,10 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
87
151
  // git reports the top level with symlinks resolved (/private/var on macOS);
88
152
  // compare in that form, then name files under the directory as it was given.
89
153
  const realRootDir = fs.realpathSync(rootDir);
90
- const cssFiles = [];
91
- const templateFiles = [];
92
154
  const ignoreMatchers = createIgnoreMatchers(ignorePatterns);
93
155
  const seen = new Set();
94
- const stagedBlobs = new Map();
156
+ const found = [];
157
+ const linksOutsideRoot = [];
95
158
 
96
159
  for (const entry of changed) {
97
160
  const realPath = path.resolve(topLevel, entry.path);
@@ -103,13 +166,18 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
103
166
  continue;
104
167
  }
105
168
 
106
- if (parsed.staged) {
107
- // The index entry is what gets committed: a regular file blob, whatever
108
- // the working tree holds now, or whether the file is still there at all.
109
- if (!REGULAR_FILE_MODES.has(entry.mode)) {
110
- continue;
111
- }
112
- } else if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) {
169
+ // A staged regular file is read from its index blob: that is what gets
170
+ // committed, whatever the working tree holds now, or whether the file is
171
+ // still there at all. A staged symbolic link is followed on disk, as a
172
+ // changed one is in a --since run (#289).
173
+ const link = entry.mode === SYMLINK_MODE;
174
+ if (parsed.staged && !REGULAR_FILE_MODES.has(entry.mode) && !link) {
175
+ continue;
176
+ }
177
+ if ((!parsed.staged || link) && !isFileOnDisk(fullPath)) {
178
+ continue;
179
+ }
180
+ if (!isCssFile(fullPath) && !isTemplateFile(fullPath)) {
113
181
  continue;
114
182
  }
115
183
 
@@ -119,20 +187,44 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
119
187
  }
120
188
 
121
189
  seen.add(fullPath);
122
- if (isCssFile(fullPath)) {
123
- cssFiles.push(fullPath);
124
- } else if (isTemplateFile(fullPath)) {
125
- templateFiles.push(fullPath);
126
- } else {
190
+ const fileRealPath = realPathOf(fullPath) || fullPath;
191
+ // A link that resolves outside the scanned directory is not followed (#289).
192
+ if (!isPathInside(realRootDir, fileRealPath)) {
193
+ linksOutsideRoot.push(relativePath);
127
194
  continue;
128
195
  }
129
- if (parsed.staged) {
130
- stagedBlobs.set(fullPath, entry.blob);
196
+ found.push({
197
+ blob: parsed.staged && !link ? entry.blob : null,
198
+ fullPath,
199
+ realPath: fileRealPath,
200
+ viaLink: link || isSymbolicLink(fullPath),
201
+ });
202
+ }
203
+
204
+ // A file changed under two paths (itself and a link to it) is scanned once.
205
+ const chosen = new Map();
206
+ for (const file of found) {
207
+ const current = chosen.get(file.realPath);
208
+ if (!current || preferPath(file, current)) {
209
+ chosen.set(file.realPath, file);
210
+ }
211
+ }
212
+ const cssFiles = [];
213
+ const templateFiles = [];
214
+ const stagedBlobs = new Map();
215
+ for (const file of found) {
216
+ if (chosen.get(file.realPath) !== file) {
217
+ continue;
218
+ }
219
+ (isCssFile(file.fullPath) ? cssFiles : templateFiles).push(file.fullPath);
220
+ if (file.blob) {
221
+ stagedBlobs.set(file.fullPath, file.blob);
131
222
  }
132
223
  }
133
224
 
134
225
  const result = {
135
226
  cssFiles,
227
+ linksOutsideRoot: linksOutsideRoot.sort(),
136
228
  scanScope: {
137
229
  changedFiles: changed.length,
138
230
  mode: parsed.staged ? 'staged' : 'since',
@@ -149,6 +241,23 @@ function getGitChangedScanFiles(rootDir, ignorePatterns, parsed) {
149
241
  }
150
242
 
151
243
  const REGULAR_FILE_MODES = new Set(['100644', '100755']);
244
+ const SYMLINK_MODE = '120000';
245
+
246
+ function isFileOnDisk(filePath) {
247
+ try {
248
+ return fs.statSync(filePath).isFile();
249
+ } catch {
250
+ return false;
251
+ }
252
+ }
253
+
254
+ function isSymbolicLink(filePath) {
255
+ try {
256
+ return fs.lstatSync(filePath).isSymbolicLink();
257
+ } catch {
258
+ return false;
259
+ }
260
+ }
152
261
 
153
262
  // -z prints names raw and NUL-separated: no quoting of spaces or non-ASCII
154
263
  // bytes. diff.relative is pinned off so every name is relative to the
@@ -28,8 +28,11 @@ const SPACING_TOKEN_NAME = /^--size(?:-|$)|(?:^--|-)(?<!letter-)(?<!word-)(?:spa
28
28
  const VAR_REFERENCE = /^var\(\s*(--[\w-]+)\s*(?:,\s*([\s\S]+))?\)$/;
29
29
  const OUTCOMES = ['on-scale', 'off-scale', 'unresolved', 'ambiguous', 'computed', 'non-length'];
30
30
 
31
+ // Shadows are never spacing, even when `inset` is in the name (Tailwind v4 `--inset-shadow-sm`, issue #295).
32
+ const SHADOW_TOKEN_NAME = /shadow/i;
33
+
31
34
  function isSpacingTokenName(token) {
32
- return token.startsWith('--') && SPACING_TOKEN_NAME.test(token);
35
+ return token.startsWith('--') && SPACING_TOKEN_NAME.test(token) && !SHADOW_TOKEN_NAME.test(token);
33
36
  }
34
37
 
35
38
  /** Every custom property declaration the audit can see: scanned stylesheets plus external token definitions. */
@@ -129,6 +129,26 @@ function sameEnd(a, b) {
129
129
  return (a === null && b === null) || (a !== null && b !== null && numbersEqual(a, b));
130
130
  }
131
131
 
132
+ /**
133
+ * The ranges adjacent steps are compared on. A ladder whose every step is
134
+ * negative (`--space-negative-1: -4px` to `-3: -16px`) grows in magnitude, so
135
+ * it is compared by magnitude, its `min` end being the smaller magnitude
136
+ * (issue #294). A ladder that crosses zero keeps its signed order.
137
+ */
138
+ function comparableSteps(steps) {
139
+ const negative = steps.every((step) => {
140
+ const ends = [step.min, step.max].filter((end) => end !== null);
141
+ return ends.length > 0 && ends.every((end) => end < 0);
142
+ });
143
+ if (!negative) {
144
+ return steps;
145
+ }
146
+ return steps.map((step) => ({
147
+ max: step.min === null ? null : -step.min,
148
+ min: step.max === null ? null : -step.max,
149
+ }));
150
+ }
151
+
132
152
  function compareEnds(lower, upper, end, minStepPx) {
133
153
  const a = lower[end];
134
154
  const b = upper[end];
@@ -191,11 +211,12 @@ function resolveTokenLadders({ baseFontSize = 16, declarations, minStepPx = DEFA
191
211
  for (const ladder of eligible) {
192
212
  if (aliases.has(ladder)) continue;
193
213
  const steps = ladder.steps.sort((a, b) => a.rank - b.rank);
214
+ const compared = comparableSteps(steps);
194
215
  const problems = [];
195
216
  for (let index = 0; index < steps.length - 1; index += 1) {
196
217
  const tokens = [steps[index].token, steps[index + 1].token];
197
- const atMin = compareEnds(steps[index], steps[index + 1], 'min', minStepPx);
198
- const atMax = compareEnds(steps[index], steps[index + 1], 'max', minStepPx);
218
+ const atMin = compareEnds(compared[index], compared[index + 1], 'min', minStepPx);
219
+ const atMax = compareEnds(compared[index], compared[index + 1], 'max', minStepPx);
199
220
  // The same problem at both ends (always, for static steps) is one problem.
200
221
  if (atMin && atMax && atMin.type === atMax.type && atMin.difference === atMax.difference) {
201
222
  problems.push({ end: 'both', tokens, ...atMin });