tailwind-canonical 0.7.0 → 0.7.1

package/dist/cli/format.d.ts

@@ -0,0 +1,3 @@
+export declare function errMsg(error: unknown): string;
+export declare function pluralize(count: number, word: string): string;
+export declare function timestamp(): string;

package/dist/cli/format.js

@@ -0,0 +1,11 @@
+export function errMsg(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function pluralize(count, word) {
+    return `${count} ${word}${count !== 1 ? 's' : ''}`;
+}
+export function timestamp() {
+    const date = new Date();
+    const pad = (value) => value.toString().padStart(2, '0');
+    return `[${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}]`;
+}

package/dist/cli/reporters.d.ts

@@ -0,0 +1,69 @@
+import type { Finding } from '../core/analyzer.js';
+import type { ConsistencyReport } from '../core/consistency.js';
+import type { Config } from '../core/rules.js';
+import type { TypoFinding } from '../core/typos.js';
+import type { FileCounts, Sink } from './types.js';
+type SarifLevel = 'error' | 'warning' | 'note';
+type SarifLocation = {
+    physicalLocation: {
+        artifactLocation: {
+            uri: string;
+            uriBaseId?: string;
+        };
+        region: {
+            startLine: number;
+            startColumn: number;
+            endLine?: number;
+            endColumn?: number;
+        };
+    };
+};
+type SarifReport = {
+    $schema: string;
+    version: string;
+    runs: Array<{
+        tool: {
+            driver: {
+                name: string;
+                version?: string;
+                informationUri: string;
+                rules: Array<{
+                    id: string;
+                    name: string;
+                    shortDescription: {
+                        text: string;
+                    };
+                    defaultConfiguration: {
+                        level: SarifLevel;
+                    };
+                }>;
+            };
+        };
+        results: Array<{
+            ruleId: string;
+            level?: SarifLevel;
+            message: {
+                text: string;
+            };
+            locations: SarifLocation[];
+            partialFingerprints?: Record<string, string>;
+        }>;
+    }>;
+};
+type SarifRule = SarifReport['runs'][0]['tool']['driver']['rules'][0];
+type SarifResult = SarifReport['runs'][0]['results'][0];
+export type SarifContext = {
+    root: string;
+    version?: string;
+};
+export declare function sarifDocument(rules: SarifRule[], results: SarifResult[], ctx: SarifContext): SarifReport;
+export declare function typoSarifDocument(findings: TypoFinding[], ctx: SarifContext): SarifReport;
+export declare function findingsSarifDocument(findings: Finding[], ctx: SarifContext): SarifReport;
+export declare function analyzeSarifDocument(report: ConsistencyReport, ctx: SarifContext): SarifReport;
+export declare function logTransformCounts(counts: FileCounts, file: string, check: boolean, sink: Sink): void;
+export declare function logFindings(findings: Finding[], sink: Sink): void;
+export declare function logWatchFindings(file: string, findings: Finding[], timestamp: string, sink: Sink): void;
+export declare function logTyposText(findings: TypoFinding[], sink: Sink): void;
+export declare function writeJson(sink: Sink, value: unknown): void;
+export declare function logAnalyzeText(report: ConsistencyReport, issueCount: number, config: Config, sink: Sink): void;
+export {};

package/dist/cli/reporters.js

@@ -0,0 +1,333 @@
+import { createHash } from 'node:crypto';
+import { isAbsolute, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { pluralize } from './format.js';
+const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json';
+const DEFAULT_ANALYZE_TEXT_OPTIONS = {
+    maxScaleGroups: 8,
+    maxScaleValues: 5,
+    maxRareValues: 12,
+    maxPatterns: 10,
+};
+const SRCROOT = '%SRCROOT%';
+const FINGERPRINT_KEY = 'tailwindCanonical/v1';
+function artifactLocation(file, root) {
+    const rel = relative(root, file);
+    if (rel === '' || /^\.\.(?:[\\/]|$)/.test(rel) || isAbsolute(rel)) {
+        return { uri: pathToFileURL(file).href };
+    }
+    const uri = rel.split(/[\\/]/).map(encodeURIComponent).join('/');
+    return { uri, uriBaseId: SRCROOT };
+}
+function fingerprint(parts) {
+    return createHash('sha256').update(parts.join('\0')).digest('hex');
+}
+function finalizeResults(rules, results, root) {
+    const levels = new Map(rules.map((rule) => [rule.id, rule.defaultConfiguration.level]));
+    const occurrences = new Map();
+    return results.map((result) => {
+        const locations = result.locations.map((location) => ({
+            physicalLocation: {
+                ...location.physicalLocation,
+                artifactLocation: artifactLocation(location.physicalLocation.artifactLocation.uri, root),
+            },
+        }));
+        const key = fingerprint([
+            result.ruleId,
+            result.message.text,
+            ...locations.map((location) => location.physicalLocation.artifactLocation.uri),
+        ]);
+        const index = occurrences.get(key) ?? 0;
+        occurrences.set(key, index + 1);
+        return {
+            ruleId: result.ruleId,
+            level: result.level ?? levels.get(result.ruleId) ?? 'warning',
+            message: result.message,
+            locations,
+            partialFingerprints: {
+                [FINGERPRINT_KEY]: fingerprint([key, String(index)]),
+            },
+        };
+    });
+}
+export function sarifDocument(rules, results, ctx) {
+    return {
+        $schema: SARIF_SCHEMA,
+        version: '2.1.0',
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: 'tailwind-canonical',
+                        ...(ctx.version ? { version: ctx.version } : {}),
+                        informationUri: 'https://github.com/peak-lab/tailwind-canonical',
+                        rules,
+                    },
+                },
+                results: finalizeResults(rules, results, ctx.root),
+            },
+        ],
+    };
+}
+function pointLocation(uri, line, col, length) {
+    const region = length === undefined
+        ? { startLine: line, startColumn: col }
+        : {
+            startLine: line,
+            startColumn: col,
+            endLine: line,
+            endColumn: col + length,
+        };
+    return { physicalLocation: { artifactLocation: { uri }, region } };
+}
+function fileLocations(files) {
+    return files.map((uri) => pointLocation(uri, 1, 1));
+}
+function uniqueFiles(entries) {
+    return [...new Set(entries.flatMap((entry) => entry.files))];
+}
+export function typoSarifDocument(findings, ctx) {
+    return sarifDocument([
+        {
+            id: 'color-typo',
+            name: 'ColorTypo',
+            shortDescription: {
+                text: 'Class color name is a likely typo of a Tailwind color',
+            },
+            defaultConfiguration: { level: 'warning' },
+        },
+    ], findings.map((f) => ({
+        ruleId: 'color-typo',
+        message: { text: `${f.original} → ${f.suggestion}` },
+        locations: [pointLocation(f.file, f.line, f.col, f.original.length)],
+    })), ctx);
+}
+export function findingsSarifDocument(findings, ctx) {
+    return sarifDocument([
+        {
+            id: 'no-arbitrary-canonical',
+            name: 'NoArbitraryCanonical',
+            shortDescription: {
+                text: 'Arbitrary value has a canonical Tailwind equivalent',
+            },
+            defaultConfiguration: { level: 'warning' },
+        },
+    ], findings.map((f) => ({
+        ruleId: 'no-arbitrary-canonical',
+        message: {
+            text: `${f.suggestion.original} → ${f.suggestion.canonical}`,
+        },
+        locations: [
+            pointLocation(f.file, f.line, f.col, f.suggestion.original.length),
+        ],
+    })), ctx);
+}
+const ANALYZE_SARIF_RULES = [
+    {
+        id: 'color-variant-inconsistency',
+        name: 'ColorVariantInconsistency',
+        shortDescription: {
+            text: 'Multiple color variants of the same family used for one property',
+        },
+        defaultConfiguration: { level: 'note' },
+    },
+    {
+        id: 'scale-inconsistency',
+        name: 'ScaleInconsistency',
+        shortDescription: {
+            text: 'Inconsistent scale values used for the same property',
+        },
+        defaultConfiguration: { level: 'note' },
+    },
+    {
+        id: 'rare-scale-value',
+        name: 'RareScaleValue',
+        shortDescription: {
+            text: 'A scale value appears rarely within an otherwise common property',
+        },
+        defaultConfiguration: { level: 'note' },
+    },
+    {
+        id: 'repeated-combination',
+        name: 'RepeatedCombination',
+        shortDescription: {
+            text: 'Identical class combination repeated across files',
+        },
+        defaultConfiguration: { level: 'note' },
+    },
+];
+export function analyzeSarifDocument(report, ctx) {
+    const colorResults = report.colorVariants.map((group) => ({
+        ruleId: 'color-variant-inconsistency',
+        message: {
+            text: `${group.variants.length} ${group.family} color variants for ${group.property}: ${group.variants.map((v) => v.token).join(', ')}`,
+        },
+        locations: fileLocations(uniqueFiles(group.variants)),
+    }));
+    const scaleResults = report.scaleInconsistencies.map((scale) => ({
+        ruleId: 'scale-inconsistency',
+        message: {
+            text: `${scale.property} inconsistency: ${scale.values.map((v) => scaleClass(scale.property, v.value)).join(' vs ')}`,
+        },
+        locations: fileLocations(uniqueFiles(scale.values)),
+    }));
+    const rareResults = report.rareScaleValues.map((rare) => ({
+        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),
+    }));
+    const comboResults = report.combinations.map((combo) => ({
+        ruleId: 'repeated-combination',
+        message: {
+            text: `Repeated class combination: ${combo.classes.join(' ')}`,
+        },
+        locations: fileLocations(combo.files),
+    }));
+    return sarifDocument(ANALYZE_SARIF_RULES, [...colorResults, ...scaleResults, ...rareResults, ...comboResults], ctx);
+}
+const TRANSFORM_LABELS = [
+    {
+        key: 'fixed',
+        applied: 'fixed ',
+        pending: 'would fix',
+        unit: 'replacement',
+    },
+    {
+        key: 'deduped',
+        applied: 'deduped',
+        pending: 'would dedup',
+        unit: 'class string',
+    },
+    {
+        key: 'merged',
+        applied: 'merged ',
+        pending: 'would merge',
+        unit: 'conflict',
+    },
+    {
+        key: 'sorted',
+        applied: 'sorted ',
+        pending: 'would sort',
+        unit: 'class string',
+    },
+];
+export function logTransformCounts(counts, file, check, sink) {
+    for (const { key, applied, pending, unit } of TRANSFORM_LABELS) {
+        const count = counts[key];
+        if (count > 0) {
+            sink.log(`  ${check ? pending : applied} ${file} (${pluralize(count, unit)})`);
+        }
+    }
+}
+export function logFindings(findings, sink) {
+    for (const finding of findings) {
+        const tag = finding.suggestion.isCustomToken ? ' [custom token]' : '';
+        sink.log(`  ${finding.file}:${finding.line}:${finding.col}  ${finding.suggestion.original} → ${finding.suggestion.canonical}${tag}`);
+    }
+}
+export function logWatchFindings(file, findings, timestamp, sink) {
+    if (findings.length === 0)
+        return;
+    sink.log(`${timestamp} ${file} — ${pluralize(findings.length, 'finding')}`);
+    for (const finding of findings) {
+        const tag = finding.suggestion.isCustomToken ? ' [custom token]' : '';
+        sink.log(`  ${finding.line}:${finding.col}  ${finding.suggestion.original} → ${finding.suggestion.canonical}${tag}`);
+    }
+}
+export function logTyposText(findings, sink) {
+    for (const finding of findings) {
+        sink.log(`  ${finding.file}:${finding.line}:${finding.col}  ${finding.original} → ${finding.suggestion} [typo]`);
+    }
+    sink.log(findings.length === 0
+        ? '✓ No likely typos found'
+        : `\n✖ Found ${pluralize(findings.length, 'likely typo')}`);
+}
+export function writeJson(sink, value) {
+    sink.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function scaleClass(property, value) {
+    return value.startsWith('-')
+        ? `-${property}-${value.slice(1)}`
+        : `${property}-${value}`;
+}
+function compactPath(file) {
+    const normalized = file.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    return parts.length <= 4 ? normalized : `.../${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 scaleTotalUses(scale) {
+    return scale.values.reduce((sum, value) => sum + value.count, 0);
+}
+export function logAnalyzeText(report, issueCount, config, sink) {
+    const options = {
+        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((value) => `${group.property}-${value.token} x${value.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, options.maxScaleGroups)) {
+            const files = new Set(scale.values.flatMap((value) => value.files));
+            sink.log(`  - ${scale.property}: ${scale.values.length} values, ${scaleTotalUses(scale)} uses, ${pluralize(files.size, 'file')}`);
+            sink.log(`    Top: ${withMore(scale.values, options.maxScaleValues, (value) => `${scaleClass(scale.property, value.value)} (${pluralize(value.count, 'use')}, ${pluralize(value.files.length, 'file')})`)}`);
+        }
+        const remaining = scales.length - options.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, options.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 - options.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, options.maxPatterns)) {
+            sink.log(`  - Pattern: "${combo.classes.join(' ')}" repeated in ${pluralize(combo.files.length, 'file')}`);
+        }
+        const remaining = report.combinations.length - options.maxPatterns;
+        if (remaining > 0)
+            sink.log(`  - +${remaining} more repeated patterns`);
+    }
+    sink.log(`\nFound ${pluralize(issueCount, 'consistency issue')} across ${pluralize(report.filesAnalyzed, 'file')}`);
+}

package/dist/cli/types.d.ts

@@ -0,0 +1,16 @@
+export type Sink = {
+    log: (message: string) => void;
+    error: (message: string) => void;
+    write: (message: string) => void;
+};
+export type RunResult = {
+    exitCode: number;
+    watching?: boolean;
+};
+export type Reporter = 'text' | 'json' | 'sarif';
+export type FileCounts = {
+    fixed: number;
+    deduped: number;
+    merged: number;
+    sorted: number;
+};

package/dist/cli/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/watch.d.ts

@@ -0,0 +1,11 @@
+import type { Sink } from './types.js';
+type WatchOptions = {
+    files: string[];
+    sink: Sink;
+    processFile: (file: string) => void;
+};
+export declare function startWatch({ files, sink, processFile }: WatchOptions): {
+    exitCode: number;
+    watching: true;
+};
+export {};

package/dist/cli/watch.js

@@ -0,0 +1,33 @@
+import { watch as fsWatch } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { errMsg, pluralize, timestamp } from './format.js';
+export function startWatch({ files, sink, processFile }) {
+    const fileSet = new Set(files);
+    const timers = new Map();
+    const dirs = new Set(files.map((file) => dirname(file)));
+    sink.log(`Watching ${pluralize(files.length, 'file')}... (Ctrl+C to stop)`);
+    for (const dir of dirs) {
+        fsWatch(dir, { recursive: true }, (_, filename) => {
+            if (!filename)
+                return;
+            const full = resolve(dir, filename);
+            if (!fileSet.has(full))
+                return;
+            clearTimeout(timers.get(full));
+            timers.set(full, setTimeout(() => {
+                timers.delete(full);
+                try {
+                    processFile(full);
+                }
+                catch (error) {
+                    sink.error(`${timestamp()} ${full} — error: ${errMsg(error)}`);
+                }
+            }, 50));
+        });
+    }
+    process.once('SIGINT', () => {
+        sink.log('\nWatcher stopped.');
+        process.exit(0);
+    });
+    return { exitCode: 0, watching: true };
+}

package/dist/core/analyzer.js

@@ -1,9 +1,10 @@
 import { extractClassStrings, SINGLE_CLASS_REGEX, toClassStringOpts, } from './class-strings.js';
 import { suggestCanonical } from './rules.js';
-import { getSuppressedLines, indexToLineCol } from './suppressions.js';
+import { createPositionLookup, getSuppressedLines } from './suppressions.js';
 export function analyzeContent(filePath, content, config = {}) {
     const findings = [];
     const suppressed = getSuppressedLines(content);
+    const positionAt = createPositionLookup(content);
     const opts = toClassStringOpts(config);
     for (const { value, start } of extractClassStrings(content, opts)) {
         for (const clsMatch of value.matchAll(SINGLE_CLASS_REGEX)) {
@@ -11,7 +12,7 @@ export function analyzeContent(filePath, content, config = {}) {
             if (!suggestion)
                 continue;
             const index = start + (clsMatch.index ?? 0);
-            const { line, col } = indexToLineCol(content, index);
+            const { line, col } = positionAt(index);
             if (suppressed.has(line))
                 continue;
             findings.push({ file: filePath, line, col, suggestion });

package/dist/core/class-strings.js

@@ -1,4 +1,4 @@
-import { lineAt } from './suppressions.js';
+import { createPositionLookup } from './suppressions.js';
 /** Builds the shared {functionNames, attributeNames} extraction options from a config. */
 export function toClassStringOpts(config) {
     return {
@@ -65,7 +65,7 @@ function scanCallStrings(content, start) {
     }
     return { strings, consumed: i - start, complete: depth === 0 };
 }
-function transformCallContent(content, start, transform, isSuppressed) {
+function transformCallContent(content, start, transform, isSuppressedAt) {
     const scanned = scanCallStrings(content, start);
     const original = content.slice(start, start + scanned.consumed);
     if (!scanned.complete) {
@@ -76,7 +76,7 @@ function transformCallContent(content, start, transform, isSuppressed) {
     let count = 0;
     for (const string of scanned.strings) {
         parts.push(content.slice(pos, string.start));
-        const out = isSuppressed?.(lineAt(content, string.start - 1))
+        const out = isSuppressedAt?.(string.start - 1)
             ? string.value
             : transform(string.value);
         if (out !== string.value)
@@ -87,6 +87,12 @@ function transformCallContent(content, start, transform, isSuppressed) {
     parts.push(content.slice(pos, start + scanned.consumed));
     return { processed: parts.join(''), consumed: scanned.consumed, count };
 }
+function offsetSuppressor(content, isSuppressed) {
+    if (!isSuppressed)
+        return undefined;
+    const positionAt = createPositionLookup(content);
+    return (offset) => isSuppressed(positionAt(offset).line);
+}
 export function replaceClassStrings(content, transform, opts = {}) {
     const attrNames = opts.attributeNames?.length
         ? opts.attributeNames
@@ -94,6 +100,7 @@ export function replaceClassStrings(content, transform, opts = {}) {
     let result = content;
     let count = 0;
     const isSuppressed = opts.isSuppressed;
+    const isAttributeSuppressed = offsetSuppressor(content, isSuppressed);
     result = result.replace(buildAttrRegex(attrNames), (_full, before, attr, open, bracedDq, bracedSq, bracedBt, close, dq, sq, bt, offset) => {
         const raw = bracedDq ?? bracedSq ?? bracedBt ?? dq ?? sq ?? bt ?? '';
         const q = bracedDq !== undefined || dq !== undefined
@@ -102,9 +109,7 @@ export function replaceClassStrings(content, transform, opts = {}) {
                 ? "'"
                 : '`';
         const attrOffset = offset + before.length;
-        const out = isSuppressed?.(lineAt(content, attrOffset))
-            ? raw
-            : transform(raw);
+        const out = isAttributeSuppressed?.(attrOffset) ? raw : transform(raw);
         if (out !== raw)
             count++;
         return `${before}${attr}=${open ?? ''}${q}${out}${q}${close ?? ''}`;
@@ -115,12 +120,13 @@ export function replaceClassStrings(content, transform, opts = {}) {
     const funcRe = new RegExp(`\\b(?:${funcNames.map(escapeRegex).join('|')})\\s*\\(`, 'g');
     const buf = [];
     let pos = 0;
+    const isCallSuppressed = offsetSuppressor(result, isSuppressed);
     for (const m of result.matchAll(funcRe)) {
         const callStart = (m.index ?? 0) + m[0].length;
         if (callStart < pos)
             continue;
         buf.push(result.slice(pos, callStart));
-        const { processed, consumed, count: c, } = transformCallContent(result, callStart, transform, isSuppressed);
+        const { processed, consumed, count: c, } = transformCallContent(result, callStart, transform, isCallSuppressed);
         buf.push(processed);
         pos = callStart + consumed;
         count += c;

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
 import type { Config } from './rules.js';
-export declare const CONFIG_FILENAMES: readonly ["tailwind-canonical.config.ts", "tailwind-canonical.config.mts", "tailwind-canonical.config.js", "tailwind-canonical.config.mjs"];
+export declare const CONFIG_FILENAMES: readonly ["tailwind-canonical.config.ts", 'tailwind-canonical.config.mts', 'tailwind-canonical.config.js', 'tailwind-canonical.config.mjs'];
 export declare function validateConfig(input: unknown, filename?: string): Config;
 export { loadConfig, resolveInitFilename } from '../io/config.js';