tailwind-canonical 0.3.0 → 0.4.1

package/dist/cli/cli.js

@@ -1,20 +1,55 @@
-import { watch as fsWatch } from 'node:fs';
+import { watch as fsWatch, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { analyzeFile } from '../core/analyzer.js';
+import { toClassStringOpts } from '../core/class-strings.js';
 import { loadConfig } from '../core/config.js';
-import { analyzeConsistencyFiles } from '../core/consistency.js';
+import { analyzeConsistencyFiles, toConsistencyOptions, } from '../core/consistency.js';
 import { dedupeFile } from '../core/deduplicator.js';
 import { fixFile } from '../core/fixer.js';
 import { mergeFile } from '../core/merger.js';
 import { resolveTargets } from '../core/scanner.js';
 import { sortFile } from '../core/sorter.js';
+import { analyzeTyposFile } from '../core/typos.js';
 const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json';
-const USAGE = 'Usage: tailwind-canonical [--fix] [--merge] [--dedup] [--sort] [--analyze] [--watch] [--reporter json|sarif] <dir|file> [dir|file...]';
-export const defaultSink = {
+const USAGE = 'Usage: tailwind-canonical [--fix] [--merge] [--dedup] [--sort] [--analyze] [--typos] [--watch] [--reporter json|sarif] <dir|file> [dir|file...]';
+const defaultSink = {
     log: (s) => console.log(s),
     error: (s) => console.error(s),
     write: (s) => process.stdout.write(s),
 };
+const KNOWN_CLASS_FUNCTIONS = ['cn', 'clsx', 'cva'];
+const DEFAULT_ANALYZE_TEXT_OPTIONS = {
+    maxScaleGroups: 8,
+    maxScaleValues: 5,
+    maxRareValues: 12,
+    maxPatterns: 10,
+};
+function sarifDocument(rules, results) {
+    return {
+        $schema: SARIF_SCHEMA,
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'tailwind-canonical',
+                        informationUri: 'https://github.com/peak-lab/tailwind-canonical',
+                        rules,
+                    },
+                },
+                results,
+            },
+        ],
+    };
+}
+function fileLocations(files) {
+    return files.map((uri) => ({
+        physicalLocation: {
+            artifactLocation: { uri },
+            region: { startLine: 1, startColumn: 1 },
+        },
+    }));
+}
 function errMsg(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -26,17 +61,55 @@ function timestamp() {
     const pad = (n) => n.toString().padStart(2, '0');
     return `[${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}]`;
 }
+const REPORTERS = ['text', 'json', 'sarif'];
+const KNOWN_FLAGS = new Set([
+    '--fix',
+    '--merge',
+    '--dedup',
+    '--sort',
+    '--watch',
+    '--analyze',
+    '--typos',
+    '--reporter',
+]);
+function isReporter(value) {
+    return REPORTERS.includes(value);
+}
 export function parseArgs(argv) {
-    const reporterIdx = argv.indexOf('--reporter');
-    const reporterValue = argv[reporterIdx + 1];
-    const reporter = reporterIdx !== -1 &&
-        (reporterValue === 'json' || reporterValue === 'sarif')
-        ? reporterValue
-        : 'text';
-    const targets = argv.filter((a, i) => !a.startsWith('--') &&
-        argv[i - 1] !== '--reporter' &&
-        a !== 'json' &&
-        a !== 'sarif');
+    let reporter = 'text';
+    let reporterRaw;
+    const consumed = new Set();
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--reporter') {
+            consumed.add(i);
+            reporterRaw = argv[i + 1];
+            if (i + 1 < argv.length)
+                consumed.add(i + 1);
+        }
+        else if (arg.startsWith('--reporter=')) {
+            consumed.add(i);
+            reporterRaw = arg.slice('--reporter='.length);
+        }
+    }
+    let error;
+    if (reporterRaw !== undefined) {
+        if (isReporter(reporterRaw)) {
+            reporter = reporterRaw;
+        }
+        else {
+            error = `Unknown reporter: ${reporterRaw} (expected ${REPORTERS.join('|')})`;
+        }
+    }
+    if (!error) {
+        const unknown = argv.find((a, i) => a.startsWith('--') &&
+            !consumed.has(i) &&
+            !KNOWN_FLAGS.has(a) &&
+            !a.startsWith('--reporter='));
+        if (unknown)
+            error = `Unknown flag: ${unknown}`;
+    }
+    const targets = argv.filter((a, i) => !(a.startsWith('--') || consumed.has(i)));
     return {
         fix: argv.includes('--fix'),
         merge: argv.includes('--merge'),
@@ -44,15 +117,102 @@ export function parseArgs(argv) {
         sort: argv.includes('--sort'),
         watch: argv.includes('--watch'),
         analyze: argv.includes('--analyze'),
+        typos: argv.includes('--typos'),
         reporter,
         targets,
+        error,
     };
 }
-function toClassStringOpts(config) {
-    return {
-        functionNames: config.functionNames,
-        attributeNames: config.attributeNames,
-    };
+const TRANSFORM_FLAGS = [
+    { key: 'fix', flag: '--fix' },
+    { key: 'dedup', flag: '--dedup' },
+    { key: 'merge', flag: '--merge' },
+    { key: 'sort', flag: '--sort' },
+];
+/**
+ * Modes are mutually exclusive with a fixed precedence: analyze > typos >
+ * transform/check. `--watch` is only honored in transform/check mode. This
+ * computes warnings for every flag that the active mode will ignore. Pure and
+ * order-stable so it can be unit-tested via the injectable sink.
+ */
+export function flagWarnings(flags) {
+    const warnings = [];
+    if (flags.analyze) {
+        for (const { key, flag } of TRANSFORM_FLAGS) {
+            if (flags[key])
+                warnings.push(`${flag} ignored: --analyze takes priority`);
+        }
+        if (flags.typos)
+            warnings.push('--typos ignored: --analyze takes priority');
+        if (flags.watch)
+            warnings.push('--watch ignored: not supported with --analyze');
+        return warnings;
+    }
+    if (flags.typos) {
+        for (const { key, flag } of TRANSFORM_FLAGS) {
+            if (flags[key])
+                warnings.push(`${flag} ignored: --typos takes priority`);
+        }
+        if (flags.watch)
+            warnings.push('--watch ignored: not supported with --typos');
+        return warnings;
+    }
+    return warnings;
+}
+function runTypos(files, config, reporter, sink) {
+    let hadError = false;
+    const findings = [];
+    for (const file of files) {
+        try {
+            findings.push(...analyzeTyposFile(file, config));
+        }
+        catch (err) {
+            hadError = true;
+            sink.error(`${file}: ${errMsg(err)}`);
+        }
+    }
+    if (reporter === 'json') {
+        const report = {
+            total: findings.length,
+            typos: findings,
+        };
+        sink.write(`${JSON.stringify(report, null, 2)}\n`);
+        return { exitCode: findings.length > 0 || hadError ? 1 : 0 };
+    }
+    if (reporter === 'sarif') {
+        const sarifOutput = sarifDocument([
+            {
+                id: 'color-typo',
+                name: 'ColorTypo',
+                shortDescription: {
+                    text: 'Class color name is a likely typo of a Tailwind color',
+                },
+            },
+        ], findings.map((f) => ({
+            ruleId: 'color-typo',
+            message: { text: `${f.original} → ${f.suggestion}` },
+            locations: [
+                {
+                    physicalLocation: {
+                        artifactLocation: { uri: f.file },
+                        region: { startLine: f.line, startColumn: f.col },
+                    },
+                },
+            ],
+        })));
+        sink.write(`${JSON.stringify(sarifOutput, null, 2)}\n`);
+        return { exitCode: findings.length > 0 || hadError ? 1 : 0 };
+    }
+    for (const f of findings) {
+        sink.log(`  ${f.file}:${f.line}:${f.col}  ${f.original} → ${f.suggestion} [typo]`);
+    }
+    if (findings.length === 0) {
+        sink.log('✓ No likely typos found');
+    }
+    else {
+        sink.log(`\n✖ Found ${pluralize(findings.length, 'likely typo')}`);
+    }
+    return { exitCode: findings.length > 0 || hadError ? 1 : 0 };
 }
 async function processFile(file, flags, config) {
     const opts = toClassStringOpts(config);
@@ -70,40 +230,215 @@ async function processFile(file, flags, config) {
 function totalOf(c) {
     return c.fixed + c.deduped + c.merged + c.sorted;
 }
+function scaleClass(property, value) {
+    return value.startsWith('-')
+        ? `-${property}-${value.slice(1)}`
+        : `${property}-${value}`;
+}
+function findUnconfiguredClassFunctions(files, config) {
+    const configured = new Set(config.functionNames ?? []);
+    const missing = KNOWN_CLASS_FUNCTIONS.filter((name) => !configured.has(name));
+    if (missing.length === 0)
+        return [];
+    const found = new Set();
+    const re = new RegExp(`\\b(${missing.join('|')})\\s*\\(`);
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const match = content.match(re);
+        if (match?.[1])
+            found.add(match[1]);
+    }
+    return [...found].sort();
+}
+function compactPath(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    if (parts.length <= 4)
+        return normalized;
+    return `.../${parts.slice(-4).join('/')}`;
+}
+function withMore(values, limit, format) {
+    const shown = values.slice(0, limit).map(format);
+    const remaining = values.length - shown.length;
+    if (remaining > 0)
+        shown.push(`+${remaining} more`);
+    return shown.join(', ');
+}
+function scaleValueSummary(property, value) {
+    return `${scaleClass(property, value.value)} (${pluralize(value.count, 'use')}, ${pluralize(value.files.length, 'file')})`;
+}
+function scaleTotalUses(scale) {
+    return scale.values.reduce((sum, value) => sum + value.count, 0);
+}
+function logAnalyzeText(report, issueCount, config, sink) {
+    const textOptions = {
+        maxScaleGroups: config.analyze?.maxScaleGroups ??
+            DEFAULT_ANALYZE_TEXT_OPTIONS.maxScaleGroups,
+        maxScaleValues: config.analyze?.maxScaleValues ??
+            DEFAULT_ANALYZE_TEXT_OPTIONS.maxScaleValues,
+        maxRareValues: config.analyze?.maxRareValues ??
+            DEFAULT_ANALYZE_TEXT_OPTIONS.maxRareValues,
+        maxPatterns: config.analyze?.maxPatterns ?? DEFAULT_ANALYZE_TEXT_OPTIONS.maxPatterns,
+    };
+    sink.log('tailwind-canonical analyze');
+    sink.log(`Files analyzed: ${report.filesAnalyzed}`);
+    sink.log(`Issue groups: ${issueCount} (${pluralize(report.colorVariants.length, 'color')}, ${pluralize(report.scaleInconsistencies.length, 'scale')}, ${pluralize(report.combinations.length, 'pattern')})`);
+    if (report.rareScaleValues.length > 0) {
+        sink.log(`Rare values: ${report.rareScaleValues.length}`);
+    }
+    if (issueCount === 0) {
+        sink.log('\nNo cross-file inconsistencies found');
+        return;
+    }
+    if (report.colorVariants.length > 0) {
+        sink.log('\nColor variants');
+        for (const group of report.colorVariants) {
+            const tokens = group.variants
+                .map((v) => `${group.property}-${v.token} x${v.count}`)
+                .join(', ');
+            sink.log(`  - ${group.property}/${group.family}: ${tokens}`);
+        }
+    }
+    if (report.scaleInconsistencies.length > 0) {
+        sink.log('\nScale inconsistency groups');
+        const scales = [...report.scaleInconsistencies].sort((a, b) => scaleTotalUses(b) - scaleTotalUses(a) ||
+            a.property.localeCompare(b.property));
+        for (const scale of scales.slice(0, textOptions.maxScaleGroups)) {
+            const totalUses = scaleTotalUses(scale);
+            const files = new Set(scale.values.flatMap((value) => value.files));
+            sink.log(`  - ${scale.property}: ${scale.values.length} values, ${totalUses} uses, ${pluralize(files.size, 'file')}`);
+            sink.log(`    Top: ${withMore(scale.values, textOptions.maxScaleValues, (value) => scaleValueSummary(scale.property, value))}`);
+        }
+        const remaining = scales.length - textOptions.maxScaleGroups;
+        if (remaining > 0)
+            sink.log(`  - +${remaining} more scale groups`);
+    }
+    if (report.rareScaleValues.length > 0) {
+        sink.log('\nRare scale values');
+        for (const rare of report.rareScaleValues.slice(0, textOptions.maxRareValues)) {
+            const example = rare.files[0]
+                ? `; e.g. ${compactPath(rare.files[0])}`
+                : '';
+            sink.log(`  - ${rare.className}: ${pluralize(rare.count, 'use')} in ${pluralize(rare.files.length, 'file')} (${rare.propertyCount} ${rare.property} uses total)${example}`);
+        }
+        const remaining = report.rareScaleValues.length - textOptions.maxRareValues;
+        if (remaining > 0)
+            sink.log(`  - +${remaining} more rare values`);
+    }
+    if (report.combinations.length > 0) {
+        sink.log('\nRepeated patterns');
+        for (const combo of report.combinations.slice(0, textOptions.maxPatterns)) {
+            sink.log(`  - Pattern: "${combo.classes.join(' ')}" repeated in ${pluralize(combo.files.length, 'file')}`);
+        }
+        const remaining = report.combinations.length - textOptions.maxPatterns;
+        if (remaining > 0)
+            sink.log(`  - +${remaining} more repeated patterns`);
+    }
+    sink.log(`\nFound ${pluralize(issueCount, 'consistency issue')} across ${pluralize(report.filesAnalyzed, 'file')}`);
+}
 function runAnalyze(files, config, reporter, sink) {
     let hadError = false;
-    const report = analyzeConsistencyFiles(files, config, {}, (file, err) => {
+    const options = toConsistencyOptions(config);
+    const report = analyzeConsistencyFiles(files, config, options, (file, err) => {
         hadError = true;
         sink.error(`${file}: ${errMsg(err)}`);
     });
     const issueCount = report.colorVariants.length +
         report.scaleInconsistencies.length +
         report.combinations.length;
+    const unconfiguredFunctions = findUnconfiguredClassFunctions(files, config);
+    if (unconfiguredFunctions.length > 0) {
+        const calls = unconfiguredFunctions
+            .map((name) => `${name}(...)`)
+            .join(', ');
+        sink.error(`Warning: detected ${calls} calls but functionNames does not include them; --analyze may miss class strings.`);
+    }
     if (reporter === 'json') {
         sink.write(`${JSON.stringify(report, null, 2)}\n`);
         return { exitCode: issueCount > 0 || hadError ? 1 : 0 };
     }
-    for (const group of report.colorVariants) {
-        const tokens = group.variants
-            .map((v) => `${group.property}-${v.token} (${v.count})`)
-            .join(', ');
-        sink.log(`  Warning: ${group.variants.length} ${group.family} color variants used for ${group.property}: ${tokens}`);
-    }
-    for (const scale of report.scaleInconsistencies) {
-        const values = scale.values
-            .map((v) => `${scale.property}-${v.value} (${pluralize(v.files.length, 'file')})`)
-            .join(' vs ');
-        sink.log(`  Warning: ${scale.property} inconsistency: ${values}`);
-    }
-    for (const combo of report.combinations) {
-        sink.log(`  Pattern: "${combo.classes.join(' ')}" repeated in ${pluralize(combo.files.length, 'file')}`);
-    }
-    if (issueCount === 0) {
-        sink.log('✓ No cross-file inconsistencies found');
-    }
-    else {
-        sink.log(`\n✖ Found ${pluralize(issueCount, 'consistency issue')} across ${pluralize(report.filesAnalyzed, 'file')}`);
+    if (reporter === 'sarif') {
+        const results = [];
+        for (const group of report.colorVariants) {
+            const tokens = group.variants.map((v) => v.token).join(', ');
+            const files = [...new Set(group.variants.flatMap((v) => v.files))];
+            results.push({
+                ruleId: 'color-variant-inconsistency',
+                message: {
+                    text: `${group.variants.length} ${group.family} color variants for ${group.property}: ${tokens}`,
+                },
+                locations: fileLocations(files),
+            });
+        }
+        for (const scale of report.scaleInconsistencies) {
+            const values = scale.values
+                .map((v) => scaleClass(scale.property, v.value))
+                .join(' vs ');
+            const files = [...new Set(scale.values.flatMap((v) => v.files))];
+            results.push({
+                ruleId: 'scale-inconsistency',
+                message: { text: `${scale.property} inconsistency: ${values}` },
+                locations: fileLocations(files),
+            });
+        }
+        for (const rare of report.rareScaleValues) {
+            results.push({
+                ruleId: 'rare-scale-value',
+                message: {
+                    text: `${rare.className} is rare for ${rare.property}: ${rare.count} occurrence(s) in ${rare.files.length} file(s), within ${rare.propertyCount} ${rare.property} uses`,
+                },
+                locations: fileLocations(rare.files),
+            });
+        }
+        for (const combo of report.combinations) {
+            results.push({
+                ruleId: 'repeated-combination',
+                message: {
+                    text: `Repeated class combination: ${combo.classes.join(' ')}`,
+                },
+                locations: fileLocations(combo.files),
+            });
+        }
+        const sarifOutput = sarifDocument([
+            {
+                id: 'color-variant-inconsistency',
+                name: 'ColorVariantInconsistency',
+                shortDescription: {
+                    text: 'Multiple color variants of the same family used for one property',
+                },
+            },
+            {
+                id: 'scale-inconsistency',
+                name: 'ScaleInconsistency',
+                shortDescription: {
+                    text: 'Inconsistent scale values used for the same property',
+                },
+            },
+            {
+                id: 'rare-scale-value',
+                name: 'RareScaleValue',
+                shortDescription: {
+                    text: 'A scale value appears rarely within an otherwise common property',
+                },
+            },
+            {
+                id: 'repeated-combination',
+                name: 'RepeatedCombination',
+                shortDescription: {
+                    text: 'Identical class combination repeated across files',
+                },
+            },
+        ], results);
+        sink.write(`${JSON.stringify(sarifOutput, null, 2)}\n`);
+        return { exitCode: issueCount > 0 || hadError ? 1 : 0 };
     }
+    logAnalyzeText(report, issueCount, config, sink);
     return { exitCode: issueCount > 0 || hadError ? 1 : 0 };
 }
 function startWatch(files, flags, config, sink) {
@@ -149,7 +484,7 @@ function startWatch(files, flags, config, sink) {
             }, 50));
         });
     }
-    process.on('SIGINT', () => {
+    process.once('SIGINT', () => {
         sink.log('\nWatcher stopped.');
         process.exit(0);
     });
@@ -157,6 +492,10 @@ function startWatch(files, flags, config, sink) {
 }
 export async function run(argv, cwd, sink = defaultSink) {
     const flags = parseArgs(argv);
+    if (flags.error) {
+        sink.error(flags.error);
+        return { exitCode: 1 };
+    }
     if (flags.targets.length === 0) {
         sink.error(USAGE);
         return { exitCode: 1 };
@@ -178,9 +517,14 @@ export async function run(argv, cwd, sink = defaultSink) {
         sink.error(`tailwind-canonical: ${err instanceof Error ? err.message : String(err)}`);
         return { exitCode: 1 };
     }
+    for (const warning of flagWarnings(flags)) {
+        sink.error(`Warning: ${warning}`);
+    }
     const files = await resolveTargets(flags.targets);
     if (flags.analyze)
         return runAnalyze(files, config, flags.reporter, sink);
+    if (flags.typos)
+        return runTypos(files, config, flags.reporter, sink);
     const transforming = flags.fix || flags.dedup || flags.merge || flags.sort;
     const totals = { fixed: 0, deduped: 0, merged: 0, sorted: 0 };
     const allFindings = [];
@@ -229,14 +573,15 @@ export async function run(argv, cwd, sink = defaultSink) {
         return startWatch(files, flags, config, sink);
     if (transforming) {
         if (flags.reporter === 'json') {
-            sink.write(`${JSON.stringify({
+            const report = {
                 files: files.length,
                 changedFiles,
                 fixed: totals.fixed,
                 deduped: totals.deduped,
                 merged: totals.merged,
                 sorted: totals.sorted,
-            }, null, 2)}\n`);
+            };
+            sink.write(`${JSON.stringify(report, null, 2)}\n`);
             return { exitCode: hadError ? 1 : 0 };
         }
         const parts = [];
@@ -253,7 +598,7 @@ export async function run(argv, cwd, sink = defaultSink) {
     }
     const totalFindings = allFindings.length;
     if (flags.reporter === 'json') {
-        sink.write(`${JSON.stringify({
+        const report = {
             files: files.length,
             total: totalFindings,
             findings: allFindings.map((f) => ({
@@ -264,47 +609,33 @@ export async function run(argv, cwd, sink = defaultSink) {
                 canonical: f.suggestion.canonical,
                 isCustomToken: f.suggestion.isCustomToken,
             })),
-        }, null, 2)}\n`);
+        };
+        sink.write(`${JSON.stringify(report, null, 2)}\n`);
         return { exitCode: totalFindings > 0 || hadError ? 1 : 0 };
     }
     if (flags.reporter === 'sarif') {
-        const sarifOutput = {
-            $schema: SARIF_SCHEMA,
-            version: '2.1.0',
-            runs: [
+        const sarifOutput = sarifDocument([
+            {
+                id: 'no-arbitrary-canonical',
+                name: 'NoArbitraryCanonical',
+                shortDescription: {
+                    text: 'Arbitrary value has a canonical Tailwind equivalent',
+                },
+            },
+        ], allFindings.map((f) => ({
+            ruleId: 'no-arbitrary-canonical',
+            message: {
+                text: `${f.suggestion.original} → ${f.suggestion.canonical}`,
+            },
+            locations: [
                 {
-                    tool: {
-                        driver: {
-                            name: 'tailwind-canonical',
-                            informationUri: 'https://github.com/peak-lab/tailwind-canonical',
-                            rules: [
-                                {
-                                    id: 'no-arbitrary-canonical',
-                                    name: 'NoArbitraryCanonical',
-                                    shortDescription: {
-                                        text: 'Arbitrary value has a canonical Tailwind equivalent',
-                                    },
-                                },
-                            ],
-                        },
+                    physicalLocation: {
+                        artifactLocation: { uri: f.file },
+                        region: { startLine: f.line, startColumn: f.col },
                     },
-                    results: allFindings.map((f) => ({
-                        ruleId: 'no-arbitrary-canonical',
-                        message: {
-                            text: `${f.suggestion.original} → ${f.suggestion.canonical}`,
-                        },
-                        locations: [
-                            {
-                                physicalLocation: {
-                                    artifactLocation: { uri: f.file },
-                                    region: { startLine: f.line, startColumn: f.col },
-                                },
-                            },
-                        ],
-                    })),
                 },
             ],
-        };
+        })));
         sink.write(`${JSON.stringify(sarifOutput, null, 2)}\n`);
         return { exitCode: totalFindings > 0 || hadError ? 1 : 0 };
     }