@servicetitan/stylelint-config 40.1.0 → 40.2.0

package/src/use-tokens/use-tokens.ts

@@ -0,0 +1,214 @@
+import Color from 'color';
+import path from 'path';
+import type { Declaration } from 'postcss';
+import stylelint, { Rule } from 'stylelint';
+import { DESIGN_SYSTEM_SOURCE, Token, TokenSource } from './load-tokens';
+import {
+    borderRadiuses,
+    colors,
+    fontFamilies,
+    fontWeights,
+    lineHeights,
+    opacities,
+    spacings,
+    TokenCollection,
+    typescales,
+    zIndexes,
+} from './values';
+
+const { createPlugin, utils } = stylelint;
+
+/*
+ * Matches spaces outside color functions, so splitting a value on it keeps a color such as
+ * rgb(2, 101, 220) whole while still separating the colors inside a gradient.
+ */
+const spaceOutsideColorFunction = / (?<!\b(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch|color)\([^()]*)/;
+
+const ruleName = '@servicetitan/use-tokens';
+const messages = utils.ruleMessages(ruleName, {
+    variableExpected: (expected: string, found: string) =>
+        `You should use ${expected} instead of "${found}".`,
+});
+
+interface Linter {
+    collection: TokenCollection;
+    /* Limits the check to matching properties. Without it, every property is checked. */
+    condition?: (property: string) => boolean;
+    /* Normalizes a value before it's looked up in the collection. */
+    transformer?: (value: string) => string;
+    /* Looks up each space-separated part of the value. Without it, the whole value is looked up. */
+    multipleValues?: boolean;
+}
+
+const linters: Linter[] = [
+    {
+        collection: colors,
+        transformer: value => {
+            try {
+                /* Includes alpha, so a translucent color doesn't match an opaque token. */
+                return new Color(value).hexa();
+            } catch {
+                return '';
+            }
+        },
+        multipleValues: true,
+    },
+    {
+        collection: typescales,
+        condition: property => property === 'font-size',
+    },
+    {
+        collection: borderRadiuses,
+        condition: property => property.startsWith('border-') && property.endsWith('-radius'),
+        transformer: value => (value === '0px' ? '0' : value),
+        multipleValues: true,
+    },
+    {
+        collection: spacings,
+        condition: property => property.startsWith('margin') || property.startsWith('padding'),
+        transformer: value => {
+            if (value === '0px') {
+                return '0';
+            }
+            return value.startsWith('-') ? value.slice(1) : value;
+        },
+        multipleValues: true,
+    },
+    {
+        collection: fontWeights,
+        condition: property => property === 'font-weight',
+    },
+    {
+        collection: opacities,
+        condition: property => property === 'opacity',
+        transformer: value => (value.startsWith('0.') ? value.slice(1) : value),
+    },
+    {
+        collection: zIndexes,
+        condition: property => property === 'z-index',
+    },
+    {
+        collection: lineHeights,
+        condition: property => property === 'line-height',
+    },
+    {
+        collection: fontFamilies,
+        condition: property => property === 'font-family',
+    },
+];
+
+const plugin: Rule = (_0, _1, context) => {
+    return (root, result) => {
+        const extension = path
+            .extname(result.opts.from ?? '')
+            .slice(1)
+            .toLowerCase();
+
+        /* Returns whether any part of the declaration's value matched a token. */
+        function lint(
+            decl: Declaration,
+            { collection, condition, transformer, multipleValues }: Linter
+        ) {
+            if (condition && !condition(decl.prop)) {
+                return false;
+            }
+
+            const values = multipleValues
+                ? decl.value.split(spaceOutsideColorFunction)
+                : [decl.value];
+
+            let matched = false;
+            for (const rawValue of values) {
+                const value = transformer?.(rawValue) ?? rawValue;
+                const tokens = collection.get(value);
+                if (!tokens) {
+                    continue;
+                }
+
+                matched = true;
+                const replacements = getReplacements(tokens, rawValue, extension);
+
+                if (context.fix && replacements.length === 1) {
+                    values[values.indexOf(rawValue)] = replacements[0].variable;
+                } else {
+                    /* When several tokens match, the developer picks one. */
+                    const message = formatMessage(replacements, rawValue);
+                    utils.report({ node: decl, message, word: rawValue, ruleName, result });
+                }
+            }
+
+            if (context.fix) {
+                decl.value = values.join(' ');
+            }
+
+            return matched;
+        }
+
+        root.walkDecls(decl => {
+            linters.some(linter => lint(decl, linter));
+        });
+    };
+};
+
+plugin.ruleName = ruleName;
+plugin.messages = messages;
+
+export = Object.assign(createPlugin(ruleName, plugin), { ruleName, messages });
+
+interface Replacement {
+    variable: string;
+    source: TokenSource;
+}
+
+/*
+ * Returns the variables that can replace a literal, negated when the literal is negative, for
+ * example "-16px" becomes "-$spacing-2" in Sass.
+ */
+function getReplacements(tokens: Token[], rawValue: string, extension: string) {
+    const negative = rawValue.startsWith('-');
+
+    return tokens.reduce<Replacement[]>((replacements, token) => {
+        const plain = convertToVariable(token, extension);
+        const variable = negative ? negate(plain, token.source) : plain;
+        /*
+         * When tokens from different sources match a literal with the same
+         * replacement, issue just one replacement that --fix can apply.
+         */
+        return replacements.some(replacement => replacement.variable === variable)
+            ? replacements
+            : [...replacements, { variable, source: token.source }];
+    }, []);
+}
+
+function convertToVariable({ name, customProperty, source }: Token, extension: string) {
+    switch (extension) {
+        case 'less':
+            /* Anvil2 publishes no Less variables. */
+            return source === DESIGN_SYSTEM_SOURCE ? `@${name}` : `var(${customProperty})`;
+
+        case 'sass':
+        case 'scss':
+            return `$${name}`;
+
+        default:
+            return `var(${customProperty})`;
+    }
+}
+
+/*
+ * A minus sign negates only a variable that holds a plain number, such as a design-system Sass or
+ * Less variable. CSS has no unary minus for var(), and Anvil2's Sass variables can hold var(), so
+ * those are negated with calc().
+ */
+function negate(variable: string, source: TokenSource) {
+    return source === DESIGN_SYSTEM_SOURCE && !variable.startsWith('var(')
+        ? `-${variable}`
+        : `calc(-1 * ${variable})`;
+}
+
+function formatMessage(replacements: Replacement[], found: string) {
+    const choices = replacements
+        .map(({ variable, source }) => `"${variable}" from \`${source}\``)
+        .join(' or ');
+    return messages.variableExpected(choices, found);
+}

package/src/use-tokens/values.ts

@@ -1,46 +1,64 @@
-import { tokens } from '@servicetitan/tokens/core';
 import Color from 'color';
-import fs from 'fs';
+import { ANVIL2_SOURCE, DESIGN_SYSTEM_SOURCE, Token, TokenSource, loadTokens } from './load-tokens';
 
-const toCamelCase = (str: string) => str.replace(/(-[a-z])/g, ([, letter]) => letter.toUpperCase());
-const toSnakeCase = (str: string) =>
-    str.replace(/([A-Z]|[a-z][0-9])/g, ([letter, digit]) =>
-        digit === undefined ? `-${letter.toLowerCase()}` : `${letter}-${digit}`
-    );
+/* Maps a literal value to the tokens that hold it, at most one per source. */
+export type TokenCollection = Map<string, Token[]>;
 
-const aliases = fs
-    .readFileSync(require.resolve('@servicetitan/tokens/core/tokens.less'), 'utf8')
-    .split('\n')
-    .filter(row => row.startsWith('@') && row.endsWith('(alias)'))
-    .map(row => toCamelCase(row.split(':')[0].slice(1)));
-
-function getValues(
-    condition: (variable: string) => boolean,
-    transformer?: (value: string) => string
-) {
-    return Object.entries(tokens)
-        .filter(([variable]) => !aliases.includes(variable) && condition(variable))
-        .reduce<Record<string, string>>(
-            (result, [variable, value]) => ({
-                ...result,
-                [transformer?.(value) ?? value]: toSnakeCase(variable),
-            }),
-            {}
-        );
-}
+const tokens = loadTokens();
 
 export const colors = getValues(
-    variable => variable.startsWith('color'),
-    value => new Color(value).hex()
+    { [DESIGN_SYSTEM_SOURCE]: /^color/, [ANVIL2_SOURCE]: /^color-/ },
+    value => new Color(value).hexa()
 );
-export const typescales = getValues(variable => variable.startsWith('typescale'));
-export const borderRadiuses = getValues(variable => variable.startsWith('borderRadius'));
-export const spacings = getValues(variable => variable.startsWith('spacing'));
-export const fontWeights = getValues(variable => variable.startsWith('fontWeight'));
-export const opacities = getValues(variable => variable.startsWith('opacity'));
-export const zIndexes = getValues(variable => variable.startsWith('zIndex'));
-export const lineHeights = getValues(variable => variable.endsWith('LineHeight'));
+export const typescales = getValues({
+    [DESIGN_SYSTEM_SOURCE]: /^typescale/,
+    [ANVIL2_SOURCE]: /^font-size-/,
+});
+export const borderRadiuses = getValues({
+    [DESIGN_SYSTEM_SOURCE]: /^border-radius/,
+    [ANVIL2_SOURCE]: /^radius-/,
+});
+export const spacings = getValues({
+    [DESIGN_SYSTEM_SOURCE]: /^spacing/,
+    [ANVIL2_SOURCE]: /^size-/,
+});
+export const fontWeights = getValues({
+    [DESIGN_SYSTEM_SOURCE]: /^font-weight/,
+    [ANVIL2_SOURCE]: /^font-weight-/,
+});
+export const opacities = getValues({ [DESIGN_SYSTEM_SOURCE]: /^opacity/ });
+export const zIndexes = getValues({ [DESIGN_SYSTEM_SOURCE]: /^z-index/ });
+export const lineHeights = getValues({
+    [DESIGN_SYSTEM_SOURCE]: /-line-height$/,
+    [ANVIL2_SOURCE]: /^font-line-height-/,
+});
 export const fontFamilies = getValues(
-    variable => variable.endsWith('FontFamily'),
+    { [DESIGN_SYSTEM_SOURCE]: /-font-family$/, [ANVIL2_SOURCE]: /^font-family-/ },
     value => value.replace(/&#x27;/g, "'")
 );
+
+function getValues(
+    patterns: Partial<Record<TokenSource, RegExp>>,
+    transformer?: (value: string) => string
+) {
+    return tokens.reduce<TokenCollection>((result, token) => {
+        if (!patterns[token.source]?.test(token.name)) {
+            return result;
+        }
+
+        /*
+         * A token the transformer can't normalize, such as an oklch() color, can never match a
+         * literal, so it's skipped rather than failing every lint run.
+         */
+        let value: string;
+        try {
+            value = transformer?.(token.value) ?? token.value;
+        } catch {
+            return result;
+        }
+
+        /* Within a source, the last token with a given value wins. */
+        const matches = (result.get(value) ?? []).filter(({ source }) => source !== token.source);
+        return result.set(value, [...matches, token]);
+    }, new Map());
+}